Mastra 化阶段1:抽 FlowRuntime 端口 —— 编排层执行面成为可替换切面,解耦完全成形

目标(用户定):完全实现编排层与活动解耦。解耦线(TaskGateway 起活动 / 终态回报)
本就存在;缺的是 CONTRACT M5-1 那句「Mastra 编译器作可替换 adapter、usecase 不动」
的端口 —— 勘察坐实它此前不存在,状态机直接写在 usecase 里揉着五端口副作用编排。

- port.ts 立 FlowRuntime 端口:begin / onTaskTerminal / applyFailure /
  onApprovalVerdict / refreshState / terminate —— 执行面的全部
- 状态机整体迁入 internal/runtime/self-hosted-runtime.ts(逐字搬迁,行为零变化):
  enter(调度+组轮值分派+实例落 assignee)、advanceFrom(条件出边选路+死路诊断+
  分支不连坐)、失败走向四选一、审批裁决(边优先、声明兜底)、三态聚合投影、终止级联
- process-service 573→248 行薄壳:定义生命周期(保存/激活/校验)+ 起单前置
  (取生效版/入参校验/工作组快照/建单留痕)+ 五方法委托;
  ProcessServiceDeps.runtime 可注入 —— Mastra 编译产物从这里换入,路由/接线零动
- index 出口 FlowRuntime 型;CONTRACT.md 记切面与已核实的语义冲突清单
  (reopen 无原语待 spike / parallel 失败连坐须 step 内自吞 / abnormal 三态 /
  node_instance 投影必留);debt M5-1 → 切面已立

等价性护栏:process 49 单测 + 八例端到端真库,提取前后原样全绿 —— 行为零变化实证。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m

api-report/apps/api/src/modules/process/index.d.ts

@@ -3,7 +3,7 @@
  */
 export type { ActivityContractFace, AssembleScope, Candidate, ClosureInput, ClosureReport, ClosureViolation, NodeInstance, OwnerSpec, ProcessPackage, ProcessService, ResolveContext, Resolution, StartWorkflowInput, WorkflowRecord, WorkflowState, } from './contract.ts';
 export { CallInterfaceViolationError, NotClosedError, PinnedVersionError, PositionVacantError, StaleVersionError } from './contract.ts';
-export type { ActivityDirectory, ApprovalGateway, Clock, FlowEventPublisher, IdGenerator, OrgDirectory, ProcessStore, ReceiptNotifier, Sfeel, TaskGateway, } from './port.ts';
+export type { FlowRuntime, ActivityDirectory, ApprovalGateway, Clock, FlowEventPublisher, IdGenerator, OrgDirectory, ProcessStore, ReceiptNotifier, Sfeel, TaskGateway, } from './port.ts';
 export type { ProcessServiceDeps } from './internal/usecase/process-service.ts';
 export { createProcessService } from './internal/usecase/process-service.ts';
 export { advanceOrder, assemble, dispatchOf, rejectRouteOf, selectEdges, startNodeOf, } from './internal/domain/routing.ts';

api-report/apps/api/src/modules/process/port.d.ts

@@ -1,7 +1,7 @@
 /**
  * module: process —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
  */
-import type { ProcessPackage, StaffId, TerminalState, WorkflowState } from '@contracts';
+import type { ProcessNode, ProcessPackage, StaffId, TerminalState, WorkflowState } from '@contracts';
 import type { NodeInstance } from './internal/domain/owner-resolution.ts';
 import type { ActivityContractFace } from './internal/domain/closure.ts';
 export type Clock = {
@@ -35,6 +35,24 @@ export type WorkflowRecord = {
     readonly startedAt: string;
     readonly finishedAt?: string;
 };
+/**
+ * 流程运行时 —— **执行面的可替换切面**(M5-1):按结构调度节点、条件出边选路、
+ * 失败走向、审批裁决、状态聚合。自持状态机(internal/runtime/self-hosted-runtime)
+ * 是默认实现;Mastra 编译产物(workflow-compiler)将是第二实现 ——
+ * 八例端到端是两个实现的等价性护栏。
+ * 定义生命周期(保存/激活/校验)不在此内:那决定「编译哪一份定义」,与引擎选型无关。
+ */
+export type FlowRuntime = {
+    /** 起单后进入起点(起单前置 —— 校验/建单/留痕 —— 归 usecase,不在此内) */
+    begin(record: WorkflowRecord, pkg: ProcessPackage): Promise<void>;
+    onTaskTerminal(taskId: string, terminal: TerminalState, ports: Record<string, Record<string, unknown>>): Promise<WorkflowState | undefined>;
+    applyFailure(workflowId: string, nodeId: string, instance: number, node: Extract<ProcessNode, {
+        kind: 'activity';
+    }>, terminal: TerminalState): Promise<WorkflowState>;
+    onApprovalVerdict(workflowId: string, nodeId: string, verdict: 'pass' | 'reject', payload: Record<string, unknown>): Promise<WorkflowState>;
+    refreshState(workflowId: string): Promise<WorkflowState>;
+    terminate(workflowId: string, reason: string): Promise<WorkflowState>;
+};
 export type ProcessStore = {
     savePackage(pkg: ProcessPackage): Promise<void>;
     /** 就地写回一版的定义(编辑即其身)—— 撞不存在的版本报错,不静默插入 */