M5/M6 修复串:判据 ③ 全链路跑通 —— 六处「声明与引擎对不上」

判据 ③ 现在从入站到 released 一路走通:步序推进 → LLM 步(密钥是占位符,
按声明降级为人兜底)→ 台账草稿层 → D1 条件跳步 → S4 工具 → S5 DMN 三分类
(LM358DR → Type A · 直接快答)→ 验收放行 → 草稿合并正式版 2 行 → 输出口
intake 发射 → 终态 released。

沿路修掉的六处,每一处都是「声明是这么写的,引擎不这么读」:

1. 人兜底卡只问一个笼统「结果」框 → 改问**这一步声明的出参字段**。
   出参契约属于步、不属于执行者:同一步谁做完,落进作用域的形状都得一样。
2. 人事件的载荷是回传协议壳 `{mode,workOrderId,values}`,
   引擎把整个壳当出参写 → 取 `values`。
3. 引擎作用域是 `{'域.对象': 行数组}`,而所有活动的步声明写的都是裸字段名 →
   任务视图三层铺开:起单入参在底、各对象最新行的字段铺顶层、地址式整表保留。
4. 起单入参从不落库、也进不了作用域 → task 存 `input_data`,断点续跑后仍在。
5. 步出参无法声明**写哪一行** → 出参加 `key`(主键列 → 作用域路径);
   六个活动包的每处出参补上键。台账几乎都有主键,不声明键就只能写无主键行。
6. `tick` 不处理 `finished`:谱走完仍按 running 一拍拍推,把预算烧到 exhausted,
   把「没人裁」误报成「跑爆了」→ 放行通过则落地收敛后 released;未放行则挂起等人。
   `flow.advance` 据末步验收裁决报 released —— **完成只出自放行通过**。

另两处装配缺口:
  · `release.land()` 实现完整却无人调用 —— 放行后从不落地。经 LandingGateway 接上。
  · `process.onTaskTerminal()` 实现完整却无人调用 —— 任务终态报不到流程层,
    流就停在那个节点上,既不流转也不走失败走向。task 在 L6 不得反向依赖 L7,
    这一跳由 app 缝合(延后绑定,同 container 里 TriggerMatcher 的手法)。

还有一处版本化缺陷:资产播种恒用 v1,`shouldSeedAsset` 一比就跳过 ——
只有**第一个**包版本的资产此生有效,之后装什么都跑旧的。改为播下一版;
进化管线放行出的更高版仍不被盖过;同版重复安装不再播种。

gates: tsc / eslint / depcruise(317 模块)/ api-report / 393 测试 全绿

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m

apps/api/src/modules/flow-engine/__tests__/step-sequence.test.ts

@@ -0,0 +1,105 @@
+/** flow 步序:声明校验 / 失败走向 / 兜底出参 —— domain 测试零 mock(AM 12.3) */
+import { describe, expect, it } from 'vitest';
+import { flowStepSchema } from '@contracts';
+import type { FlowStep } from '@contracts';
+import {
+  checkDeclaration,
+  fallbackFields,
+  failureAction,
+  initialPosition,
+  lastStepIsAcceptance,
+  markStep,
+  parallelGroupComplete,
+} from '../internal/domain/step-sequence.ts';
+
+const llmStep = (over: Record<string, unknown> = {}): FlowStep =>
+  flowStepSchema.parse({
+    kind: 'llm',
+    name: 'S3',
+    label: 'S3 逐条解析归一',
+    input: { rfqRef: 'rfqRef' },
+    output: { domain: 'quote_intake', object: 'record', fields: { pn: 'pn', brand: 'brand', eau: 'eau' } },
+    model: 'quote-extractor',
+    template: '解析 {{rfqRef}}',
+    outputSchema: { type: 'object' },
+    failure: { retry: { times: 2, backoff: 'PT30S' }, fallback: { kind: 'human', workOrder: 'execution' } },
+    ...over,
+  });
+
+describe('人兜底:出参契约属于步,不属于执行者', () => {
+  it('兜底卡问的字段 = 这一步声明的出参 —— 人填完能落进作用域', () => {
+    // 若只给一个笼统的「结果」框,下游按 output.fields 取值会取空,在下一步崩
+    expect(fallbackFields(llmStep())).toEqual(['pn', 'brand', 'eau']);
+  });
+
+  it('无出参声明的步不凭空造字段', () => {
+    const step = flowStepSchema.parse({
+      kind: 'llm',
+      name: 'S9',
+      label: '只说不写的一步',
+      input: {},
+      model: 'm',
+      template: 't',
+      outputSchema: { type: 'object' },
+      failure: { retry: { times: 0, backoff: 'PT1S' }, fallback: { kind: 'blocked' } },
+    });
+    expect(fallbackFields(step)).toEqual([]);
+  });
+});
+
+describe('失败走向声明给定,不临场发明', () => {
+  it('重试次数未用尽 → retry', () => {
+    expect(failureAction(llmStep(), 1).kind).toBe('retry');
+  });
+
+  it('重试用尽 → 按声明的 fallback 转人', () => {
+    const action = failureAction(llmStep(), 2);
+    expect(action.kind).toBe('human');
+  });
+
+  it('声明 blocked 的步不转人 —— 走向是声明的,不是猜的', () => {
+    const step = llmStep({ failure: { retry: { times: 0, backoff: 'PT1S' }, fallback: { kind: 'blocked' } } });
+    expect(failureAction(step, 0).kind).toBe('blocked');
+  });
+});
+
+describe('步序位置', () => {
+  it('初始位置每步待跑', () => {
+    const position = initialPosition([llmStep(), llmStep({ name: 'S4' })]);
+    expect(position.index).toBe(0);
+    expect(position.steps.map((s) => s.state)).toEqual(['pending', 'pending']);
+  });
+
+  it('markStep 只改那一步,其余原样', () => {
+    const position = initialPosition([llmStep(), llmStep({ name: 'S4' })]);
+    const next = markStep(position, 1, { state: 'done' });
+    expect(next.steps.map((s) => s.state)).toEqual(['pending', 'done']);
+  });
+
+  it('并行组要全完成才算完成', () => {
+    const position = markStep(initialPosition([llmStep(), llmStep({ name: 'S4' })]), 0, { state: 'done' });
+    expect(parallelGroupComplete(position, ['S3', 'S4'])).toBe(false);
+    expect(parallelGroupComplete(markStep(position, 1, { state: 'done' }), ['S3', 'S4'])).toBe(true);
+  });
+});
+
+describe('声明校验', () => {
+  it('步名重复即拒', () => {
+    expect(checkDeclaration([llmStep(), llmStep()]).length).toBeGreaterThan(0);
+  });
+
+  it('末步是验收工单可辨', () => {
+    const acceptance: FlowStep = flowStepSchema.parse({
+      kind: 'human',
+      name: 'S6',
+      label: '验收',
+      input: {},
+      workOrder: 'acceptance',
+      card: {},
+      deadline: 'P1D',
+      failure: { retry: { times: 0, backoff: 'PT1S' }, fallback: { kind: 'blocked' } },
+    });
+    expect(lastStepIsAcceptance([llmStep(), acceptance])).toBe(true);
+    expect(lastStepIsAcceptance([llmStep()])).toBe(false);
+  });
+});

apps/api/src/modules/flow-engine/internal/domain/step-sequence.ts

@@ -17,6 +17,8 @@ export type StepRuntime = {
   readonly attempt: number;
   readonly output?: Record<string, unknown>;
   readonly error?: string;
+  /** 验收工单的放行裁决:pass / 驳回类别 —— 末步据此定终局 */
+  readonly verdict?: string;
 };
 
 export type FlowPosition = {
@@ -121,3 +123,25 @@ export function parallelGroupComplete(position: FlowPosition, members: readonly
     return runtime?.state === 'done' || runtime?.state === 'skipped';
   });
 }
+
+/**
+ * 人兜底时要回填的字段 —— 取自这一步**声明的出参**。
+ *
+ * 出参契约属于**步**,不属于执行者:同一步无论由 LLM、工具还是人做完,
+ * 落进作用域的形状必须一致。若兜底卡只给一个笼统的「结果」文本框,
+ * 人填了也落不进去 —— 下游按 `output.fields` 取值,取不到就在下一步崩。
+ *
+ * 返回键名数组,与 human 步的 `card.fields` 同形:卡的渲染只有一套。
+ */
+export function fallbackFields(step: FlowStep): readonly string[] {
+  return step.output === undefined ? [] : Object.values(step.output.fields);
+}
+
+/**
+ * 末步的放行裁决是否「通过」—— **完成只出自放行通过**(OS 05)。
+ * 驳回(重做 / 迭代)不是完成:谱虽走完,任务不得进 released。
+ */
+export function lastVerdictPassed(position: FlowPosition): boolean {
+  const last = position.steps[position.steps.length - 1];
+  return last?.verdict === 'pass';
+}

apps/api/src/modules/flow-engine/internal/usecase/flow-runner.ts

@@ -19,6 +19,9 @@ import type {
 import type { FlowPosition } from '../domain/step-sequence.ts';
 import {
   checkDeclaration,
+  fallbackFields,
+  lastStepIsAcceptance,
+  lastVerdictPassed,
   failureAction,
   initialPosition,
   markStep,
@@ -52,15 +55,29 @@ export function createFlowRunner(deps: FlowRunnerDeps): FlowEngineService {
     for (const [field, path] of Object.entries(step.output.fields)) {
       patch[field] = output[path] ?? output[field];
     }
+    // 写哪一行:主键取自出参,取不到再回作用域(起单入参往往就带着主键)
+    const scope = await deps.data.view(taskId);
+    const key: Record<string, string | number> = {};
+    for (const [column, path] of Object.entries(step.output.key)) {
+      const value = output[path] ?? scope[path];
+      // 主键值只能是标量;取不到就不填,让台账的非空约束在合并时如实报出来
+      if (typeof value === 'string' || typeof value === 'number') key[column] = value;
+    }
     await deps.data.draftWrite({
       taskId,
       domain: step.output.domain,
       object: step.output.object,
-      key: {},
+      key,
       patch,
     });
   }
 
+  /** 回传协议 → 出参:取 `values`;非回传形状的人事件按原样当出参 */
+  function replyValuesOf(payload: Record<string, unknown>): Record<string, unknown> {
+    const values = payload['values'];
+    return typeof values === 'object' && values !== null ? (values as Record<string, unknown>) : payload;
+  }
+
   function inputOf(step: FlowStep, scope: Record<string, unknown>): Record<string, unknown> {
     const out: Record<string, unknown> = {};
     for (const [key, path] of Object.entries(step.input)) {
@@ -188,7 +205,13 @@ export function createFlowRunner(deps: FlowRunnerDeps): FlowEngineService {
         ownerId: context.ownerId,
         humanCallCap: context.humanCallCap,
         workOrder: action.workOrder,
-        card: { title: `步「${step.label}」重试仍败,转人兜底`, reason: error },
+        card: {
+          title: `步「${step.label}」重试仍败,转人兜底`,
+          reason: error,
+          // 兜底的人要交的东西,和这一步**本来该产出的东西**同形:
+          // 出参契约是步的契约,不因换谁来做而变(统一执行契约)。
+          fields: fallbackFields(step),
+        },
       });
       await deps.listeners.register({
         taskId,
@@ -231,8 +254,10 @@ export function createFlowRunner(deps: FlowRunnerDeps): FlowEngineService {
 
       switch (action.kind) {
         case 'finished': {
-          // 末步是验收工单时,终态由其裁决给出;此处只报「谱走完」
-          return { position, status: 'finished', released: false };
+          // 末步是验收工单时,终态由其**裁决**给出 —— 完成只出自放行通过。
+          // 裁决记在末步的 runtime 上(resume 时落笔),谱走完在这里读出来。
+          const released = lastStepIsAcceptance(model.steps) && lastVerdictPassed(position);
+          return { position, status: 'finished', released };
         }
         case 'skip': {
           await deps.memory.append({
@@ -268,10 +293,14 @@ export function createFlowRunner(deps: FlowRunnerDeps): FlowEngineService {
         title: `事件到达,步 ${index + 1} 完成条件满足(${event.kind})`,
         detail: { ref: event.ref },
       });
+      // 放行裁决落笔在这一步的运行时上:谱走完时据此定终局
+      const verdict = event.kind === 'human' ? String(event.payload['verdict'] ?? '') : '';
       if (step !== undefined && event.kind === 'human') {
-        await writeOutput(taskId, step, event.payload);
+        // 人事件的载荷是**回传协议**的形状(`{mode, workOrderId, values}`),
+        // 出参在 `values` 里;直接把整个载荷当出参写,落进去的会是协议壳而不是答案。
+        await writeOutput(taskId, step, replyValuesOf(event.payload));
       }
-      const next = markStep(position, index, { state: 'done' });
+      const next = markStep(position, index, verdict === '' ? { state: 'done' } : { state: 'done', verdict });
       await deps.state.save(taskId, model, next);
       return { position: next, status: 'running' };
     },