JX-BPOS/apps/api/src/modules/loop-engine/contract.ts

/**
 * module: loop-engine —— 对外类型(编码规范 §10.1;语义出处 AM 03 / 04)。
 *
 * loop 的运行 = **CMMN 语义引擎(下层,零 LLM)× Agent 回路(上层,临场裁量)**。
 * 两层的耦合点是任务数据(驱动耦合)与任务记忆(记录同轴)。
 */
import type { LoopModel, TaskId } from '@contracts';
import type { CaseModel, PlanItem, PlanItemType } from './internal/domain/cmmn-parse.ts';
import type {
  CaseRuntime,
  CaseState,
  EnabledEntry,
  EnabledSet,
  ItemRuntime,
  ItemState,
  Navigation,
  TerminalAuthority,
} from './internal/domain/lifecycle.ts';
import type { DecisionResult, DecisionTrace, Gap } from './internal/domain/dmn.ts';

export type {
  CaseModel,
  CaseRuntime,
  CaseState,
  DecisionResult,
  DecisionTrace,
  EnabledEntry,
  EnabledSet,
  Gap,
  ItemRuntime,
  ItemState,
  LoopModel,
  Navigation,
  PlanItem,
  PlanItemType,
  TerminalAuthority,
};

export { CmmnParseError } from './internal/domain/cmmn-parse.ts';
export { IllegalTransitionError } from './internal/domain/lifecycle.ts';

export class ForbiddenTerminalError extends Error {
  constructor(readonly by: TerminalAuthority) {
    super(`终局迁移不得由 ${by} 产生:Completed 必经放行,Terminated 只出自 Harness 与负责人(AM 4.1)`);
    this.name = 'ForbiddenTerminalError';
  }
}

export class AutomaticOnWorldTouchingError extends Error {
  constructor(readonly itemId: string) {
    super(`计划项 ${itemId} 触达世界却未声明 manualActivationRule —— Enabled ≠ Active(AM 12.2)`);
    this.name = 'AutomaticOnWorldTouchingError';
  }
}

/** Agent 的三型行动 —— 每一步行动属于且仅属于其一(AM 4.2) */
export type AgentAction =
  /** 调工具:系统调用与 LLM 工具 */
  | { readonly kind: 'tool'; readonly itemId: string; readonly tool: string; readonly input: Record<string, unknown> }
  /** 调人:四卡之一 —— 调人 = 立监听听人 */
  | { readonly kind: 'human'; readonly itemId: string; readonly card: Record<string, unknown>; readonly workOrder: 'execution' | 'acceptance' }
  /** 立监听:AI 不能调用世界,对世界只有两种合法姿势 —— 触达它(动作)与等它(监听) */
  | { readonly kind: 'listen'; readonly itemId: string; readonly eventType: 'data' | 'time'; readonly keyFilter: Record<string, string>; readonly deadline: string }
  /** 启动一个 Enabled 项(manualStart,留痕) */
  | { readonly kind: 'start'; readonly itemId: string }
  /** 规划裁量项入场 */
  | { readonly kind: 'plan'; readonly itemId: string }
  /** 弃用某项(此单不走这条) */
  | { readonly kind: 'disable'; readonly itemId: string; readonly reason: string }
  /** 评估语义性前提(评估留痕,可回放可归因) */
  | { readonly kind: 'judge'; readonly criterion: string; readonly satisfied: boolean; readonly rationale: string }
  /** 判定成果已齐,提交放行 */
  | { readonly kind: 'submit'; readonly rationale: string }
  /**
   * 本回合**已在工具循环里调过人**:卡已发、监听已立(工具总线执行的)。
   * 引擎只收尾把这一拍置 awaiting —— 不能再发一张,否则负责人工位上堆两张同样的卡。
   * 开环模式(Mastra Agent 自主连环调工具)专用;单拍模式给不出这一型。
   */
  | { readonly kind: 'asked'; readonly cardId: string; readonly rationale: string };

export type TurnOutcome = {
  readonly runtime: CaseRuntime;
  readonly enabled: EnabledSet;
  readonly navigation: Navigation;
  readonly action?: AgentAction;
  readonly status: 'running' | 'awaiting' | 'submitted' | 'finished' | 'blocked';
  readonly blockedReason?: string;
  /** 终局唯放行:finished 时带裁决 —— released=true 才算走完,选口随放行确认 */
  readonly released?: boolean;
  readonly selectedPorts?: Record<string, string>;
};

export type LoopEngineService = {
  /** 装载:XML 进语义引擎,说明书进 Agent 上下文;版本全部入信封 */
  load(taskId: TaskId, model: LoopModel): Promise<CaseRuntime>;
  runtime(taskId: TaskId): Promise<CaseRuntime | undefined>;
  /** 发布 Enabled 集与红绿灯 —— 引擎推进的终点 */
  publish(taskId: TaskId): Promise<EnabledSet>;
  /** 跑一个回合:定位 → 择向 → 决断 → 行动 → 写数据 */
  runTurn(taskId: TaskId): Promise<TurnOutcome>;
  /** 事件驱动续跑:数据 / 时间 / 人 / 控制 */
  /**
   * 事件到达:**只记不跑**(登记 occur / 收验收裁决,存快照即返)。
   * 从前这里自跑一整拍、deliver 随后的 tick 又跑一拍 —— 每次人卡回传
   * 多耗一次不计 steps/activeMs 预算的模型决策。推进统一归 tick。
   */
  onEvent(taskId: TaskId, event: { kind: 'data' | 'time' | 'human' | 'control'; ref: string; payload: Record<string, unknown> }): Promise<void>;
  /** DMN 确定性求值 —— 能算的不问 LLM */
  decide(taskId: TaskId, decision: string): Promise<DecisionResult>;
  /** 驳回:相关计划项以新实例重新入场(迁移不是状态) */
  reenter(taskId: TaskId, itemId: string): Promise<CaseRuntime>;
};