/**
 * `defineActivity()` —— 活动包的 ABI 入口(ADR-004)。
 *
 * 「单文件 ESM,**默认导出** `defineActivity()` 的返回值;能力全部注入(基座六件句柄),
 *  **零环境能力**;静态审扫描产物 import 与全局引用。」
 */
import type { ActivityBase } from './base.ts';

/** 活动的运行结论 —— 提交放行是唯一的成功出路 */
export type ActivityOutcome =
  /** 判定成果已齐,提交放行(必交付物齐备、判据全绿只是可提交) */
  | { readonly kind: 'submit'; readonly deliverable: string; readonly rationale: string }
  /** 等外界:已立监听,回合到此为止 */
  | { readonly kind: 'await'; readonly reason: string }
  /** 无法推进,申报受阻待人 */
  | { readonly kind: 'blocked'; readonly reason: string };

export type ActivityDefinition = {
  readonly name: string;
  /** 范式只存在于引擎层;此处声明是给装载器看的 */
  readonly paradigm: 'loop' | 'flow';
  /**
   * 一个回合的推进。由**引擎**驱动调用 —— 活动不自转、不自设 maxSteps;
   * 预算与熔断由基座在环外强制。
   */
  run(base: ActivityBase): Promise<ActivityOutcome>;
};

export function defineActivity(definition: ActivityDefinition): ActivityDefinition {
  if (definition.name.trim() === '') throw new Error('活动必须有名字');
  return Object.freeze(definition);
}