/**
 * `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;
  /**
   * 一个回合的推进 —— **可选**。
   *
   * 2026-07-29 范式退役后,活动一律案例模型:推进由 Loop 驱动(定位 → 择向 → 决断 →
   * 行动),行动落在基座上,不经活动代码。所以绝大多数活动**不需要 run** ——
   * 它的行为写在清单里(案例模型 + 说明书 + DMN + 技能 + 台账声明),
   * 「系统不执行代码即知包为何物」。
   *
   * 留着它是为确定性子序列(结晶片段)将来有个落点;不写就是不写,不是缺件。
   * 活动不自转、不自设 maxSteps;预算与熔断由基座在环外强制。
   */
  run?(base: ActivityBase): Promise<ActivityOutcome>;
};

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