流程链按拓扑序读 —— 图纸坐标不配决定推进次序

任务详情里的「流程链」在 MVP 包上读作 **A1 → A7 → A2 → A6 → A3 → A5 → A4**。
不是随机:`toChain` 按 `layout.col` 排,而 MVP 图是**回形走线**(第 0 行左→右、
第 1 行右→左、第 2 行折回最左),A7 的列位(1)正好跟 A1 并列、A6(3)跟 A2 并列。
原注释还写着「列位是流程的推进次序(拓扑的可视化)」—— 那句话只对 v1 那种一行
从左画到右的包成立,换一张图就是错的。图纸声明为「不影响语义」,那它也不配决定次序。

改为按**边**做拓扑序,新增 `advanceOrder`(process 的 domain,纯函数零 IO):

  · 回边(reopen)排除在外 —— 它是重新入场不是往前推进;留着 G4 → A4 就成环,
    A4 会等自己的下游,拓扑序无从下手
  · 真并行支(G2 分出的 A2 / A3)图上本无先后,按**节点编号**定 ——
    同一个包在谁手上都读作同一条链
  · 进不了拓扑序的节点(不可达、或排除回边后仍有环)按编号缀在末尾:少排序,不丢节点

实测链已读作 A1 → A2 → A3 → A4 → A5 → A6 → A7(A1 current)。
六条 domain 测试盯住它,第一条就是那张回形图。

顺带修了两处会互相传染的闸:
  · `api-report.mjs` 在 tsc 失败那条路径不清 `.api-tmp`,半成品留在盘上,
    eslint 扫到生成的 .d.ts 报 1004 条假错 —— 于是 tsc 一红 lint 跟着红。实测踩到。
  · eslint 只忽略了 `api-report/**`,把同为产物的 `.api-tmp/**` 一并忽略

契约变更(加法,非破坏):①depcruise 反查六处下游无违规 ②CONTRACT.md 已注明
③快照 api-report/…/process/index.d.ts 仅多一个导出名。

typecheck ✓ lint ✓ depcruise 374 模块 ✓ 487 测试 ✓(以退出码验,不以 echo 验)

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

apps/api/src/app/routes/desk.ts

@@ -21,6 +21,7 @@ import {
   workOrderReplySchema,
 } from '@contracts';
 import { ReplyRejectedError } from '@modules/human-tool';
+import { advanceOrder } from '@modules/process';
 import type { Container } from '../container.ts';
 import type { AppEnv } from '../http-env.ts';
 
@@ -76,23 +77,11 @@ export function registerDeskRoutes(app: Hono<AppEnv>, container: Container): voi
     const pkg = await container.process.getPackage(workflow.packageId, workflow.packageVersion);
 
     /*
-     * 链的呈现顺序:**按流程列位排,同列按节点编号排** —— 不吃 `nodes` 数组的书写顺序。
-     *
-     * 并行分支(如 G2 分出的 A2 / A3)在图上本无先后,链却必须挑一个顺序。
-     * 挑「作者数组里怎么写」是最不稳的:换个人写包,链的读法就变了。
-     * 列位 `layout.col` 是流程的推进次序(拓扑的可视化),同列的并行支再按编号定 ——
-     * 于是链永远读作 A1 → A2 → A3 → A4,与人对活动编号的预期一致。
-     * `layout` 声明为「不影响语义」,这里也只拿它排**呈现**,不参与任何流转判断。
+     * 链的呈现顺序:**按边的拓扑序**(`advanceOrder`),不吃 `nodes` 数组的书写顺序,
+     * 也不看图纸坐标 —— 图纸一回形走线,列位就跟推进次序对不上了。
      */
-    const declared = (pkg?.nodes ?? []).filter((n) => n.kind === 'activity' || n.kind === 'approval');
-    const nodes = declared
-      .map((n, index) => ({ n, index }))
-      .sort(
-        (a, b) =>
-          (a.n.layout?.col ?? a.index) - (b.n.layout?.col ?? b.index) ||
-          (a.n.id < b.n.id ? -1 : a.n.id > b.n.id ? 1 : 0),
-      )
-      .map((x) => x.n);
+    const nodes =
+      pkg === undefined ? [] : advanceOrder(pkg).filter((n) => n.kind === 'activity' || n.kind === 'approval');
 
     /*
      * 状态取**真实的节点实例**,不按下标推。

apps/api/src/modules/process/CONTRACT.md

@@ -15,7 +15,9 @@
   - 纯函数:`checkClosure` `publishable` `resolveOwner` `aggregateWorkflowState`
           (`resolveOwner` 的 `bound` 入参 = 已校验的工作组绑定,ADR-011)
           `isDigested` `nextInstanceNumber` `selectEdges` `assemble` `joinReady`
-          `rejectRouteOf` `dispatchOf` `startNodeOf`
+          `rejectRouteOf` `dispatchOf` `startNodeOf` `advanceOrder`
+          (`advanceOrder` = 推进次序,按边拓扑排、排除回边、并行支按编号定序;
+           呈现用,不参与流转判断 —— 图纸坐标不配决定次序)
   - adapter:`createProcessStore`;Drizzle 表:`processPackageTable` `workflowTable` `nodeInstanceTable`
 
 层级:      L7(编码规范 §4)

apps/api/src/modules/process/__tests__/advance-order.test.ts

@@ -0,0 +1,170 @@
+/**
+ * 推进次序 —— 拓扑序,不看图纸(domain 测试零 mock)。
+ *
+ * 这条曾经拿 `layout.col` 排,在**回形走线**的图上读错过:MVP 图第 0 行左→右、
+ * 第 1 行右→左、第 2 行折回最左,A7 的列位跟 A1 并列,链就读成 A1 → A7 → A2 → A6 → A3。
+ * 所以这里的第一个用例就是那张回形图 —— 保证它只能读作 A1 → … → A7。
+ */
+import { describe, expect, it } from 'vitest';
+import type { Edge, ProcessNode, ProcessPackage } from '@contracts';
+import { advanceOrder } from '../internal/domain/routing.ts';
+
+/** 活动节点:`col`/`row` 故意按回形图给,证明次序不吃图纸 */
+const act = (id: string, col: number, row: number): ProcessNode =>
+  ({
+    id,
+    kind: 'activity',
+    label: id,
+    activityId: id.toLowerCase(),
+    owner: { position: 'BD', strategy: 'sole' },
+    failure: { kind: 'terminate' },
+    layout: { row, col },
+  }) as never;
+
+const gw = (id: string, mode: 'fork' | 'join', col: number, row: number): ProcessNode =>
+  ({
+    id,
+    kind: 'gateway',
+    label: id,
+    gateway: 'exclusive',
+    mode,
+    layout: { row, col },
+  }) as never;
+
+const edge = (from: string, to: string, reopen = false): Edge =>
+  ({ id: `e-${from}-${to}`, from, to, mapping: [], reopen }) as never;
+
+const pkg = (nodes: ProcessNode[], edges: Edge[]): ProcessPackage =>
+  ({
+    id: 'unified-quote' as never,
+    name: '统一报价',
+    version: 1,
+    state: 'published',
+    callInterface: { input: {}, output: {} },
+    nodes,
+    edges,
+    variables: [],
+  }) as never;
+
+/** 断言里要按裸字符串找位置,所以出口就摘掉品牌 —— 测试比对的是「读出来的次序」 */
+const ids = (p: ProcessPackage): string[] => advanceOrder(p).map((n) => n.id);
+const acts = (p: ProcessPackage): string[] =>
+  advanceOrder(p)
+    .filter((n) => n.kind === 'activity')
+    .map((n) => n.id);
+
+describe('advanceOrder', () => {
+  /** MVP 图原样:col 是蛇形列位 —— A7(col 1)与 A1(col 1)并列,A6(col 3)与 A2(col 3)并列 */
+  const serpentine = pkg(
+    [
+      { id: 'start', kind: 'start', label: '询价', layout: { row: 0, col: 0 } } as never,
+      act('A1', 1, 0),
+      gw('G1', 'fork', 2, 0),
+      act('A2', 3, 0),
+      gw('G2', 'fork', 4, 0),
+      act('A3', 5, 0),
+      gw('G2J', 'join', 6, 0),
+      act('A4', 7, 0),
+      act('A5', 6, 1),
+      act('A6', 3, 1),
+      gw('G4', 'fork', 2, 1),
+      act('A7', 1, 2),
+      { id: 'end_won', kind: 'end', label: '成交', layout: { row: 1, col: 0 } } as never,
+      { id: 'end_arch', kind: 'end', label: '归档', layout: { row: 2, col: 0 } } as never,
+    ],
+    [
+      edge('start', 'A1'),
+      edge('A1', 'G1'),
+      edge('G1', 'A2'),
+      edge('G1', 'G2'),
+      edge('A2', 'G2'),
+      edge('G2', 'A3'),
+      edge('G2', 'G2J'),
+      edge('A3', 'G2J'),
+      edge('G2J', 'A4'),
+      edge('A4', 'A5'),
+      edge('A5', 'A6'),
+      edge('A6', 'G4'),
+      edge('G4', 'end_won'),
+      edge('G4', 'A4', true), // 回边:有异议退回重新定价
+      edge('G4', 'A7'),
+      edge('A7', 'end_arch'),
+    ],
+  );
+
+  it('回形图也读作编号序 —— 列位并列不影响推进次序', () => {
+    expect(acts(serpentine)).toEqual(['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7']);
+  });
+
+  it('起点在最前、网关按边落位、两个终点都在 A7 之后', () => {
+    const order = ids(serpentine);
+    expect(order[0]).toBe('start');
+    expect(order.indexOf('G1')).toBeGreaterThan(order.indexOf('A1'));
+    expect(order.indexOf('G2J')).toBeGreaterThan(order.indexOf('A3'));
+    // 两个终点谁在最后没有意义(都是终态),但都必须在最后一个活动之后
+    expect(order.indexOf('end_won')).toBeGreaterThan(order.indexOf('A6'));
+    expect(order.indexOf('end_arch')).toBeGreaterThan(order.indexOf('A7'));
+  });
+
+  /**
+   * 回边不参与排序。要看出差别,编号序得跟拓扑序**相反** ——
+   * AZ 在流程上先于 AB,但字母序 AB 在前。回边一旦当成正向边,两头互等成环、
+   * 一起落榜,就只能按编号读作 AB → AZ,把流程读反了。
+   */
+  it('回边排除在外 —— 否则两头互等成环,链会读反', () => {
+    const nodes = [
+      { id: 'start', kind: 'start', label: '起', layout: { row: 0, col: 0 } } as never,
+      act('AZ', 1, 0),
+      act('AB', 2, 0),
+      { id: 'end', kind: 'end', label: '终', layout: { row: 0, col: 3 } } as never,
+    ];
+    const forward = [edge('start', 'AZ'), edge('AZ', 'AB'), edge('AB', 'end')];
+
+    expect(acts(pkg(nodes, [...forward, edge('AB', 'AZ', true)]))).toEqual(['AZ', 'AB']);
+    // 同一张图,只把回边的声明摘掉 —— 立刻读反
+    expect(acts(pkg(nodes, [...forward, edge('AB', 'AZ')]))).toEqual(['AB', 'AZ']);
+  });
+
+  it('真并行支按编号定序 —— 同一个包在谁手上都读作同一条链', () => {
+    const parallel = pkg(
+      [
+        { id: 'start', kind: 'start', label: '起', layout: { row: 0, col: 0 } } as never,
+        gw('F', 'fork', 1, 0),
+        act('AZ', 2, 0),
+        act('AB', 2, 1),
+        gw('J', 'join', 3, 0),
+        { id: 'end', kind: 'end', label: '终', layout: { row: 0, col: 4 } } as never,
+      ],
+      [
+        edge('start', 'F'),
+        edge('F', 'AZ'),
+        edge('F', 'AB'),
+        edge('AZ', 'J'),
+        edge('AB', 'J'),
+        edge('J', 'end'),
+      ],
+    );
+    // 书写顺序是 AZ 在前,但编号 AB < AZ —— 链按编号读
+    expect(acts(parallel)).toEqual(['AB', 'AZ']);
+  });
+
+  it('不可达节点不丢 —— 按编号缀在末尾', () => {
+    const orphan = pkg(
+      [
+        { id: 'start', kind: 'start', label: '起', layout: { row: 0, col: 0 } } as never,
+        act('A1', 1, 0),
+        act('A9', 9, 9), // 没有任何边连它
+        { id: 'end', kind: 'end', label: '终', layout: { row: 0, col: 2 } } as never,
+      ],
+      [edge('start', 'A1'), edge('A1', 'end')],
+    );
+    // 无入边的节点本身就在第一轮 ready 里,按编号与 start 一同排;关键是它在
+    const order = ids(orphan);
+    expect(order).toContain('A9');
+    expect(order).toHaveLength(4);
+  });
+
+  it('空包不炸', () => {
+    expect(advanceOrder(pkg([], []))).toEqual([]);
+  });
+});

apps/api/src/modules/process/index.ts

@@ -37,6 +37,7 @@ export type { ProcessServiceDeps } from './internal/usecase/process-service.ts';
 export { createProcessService } from './internal/usecase/process-service.ts';
 
 export {
+  advanceOrder,
   assemble,
   dispatchOf,
   joinReady,

apps/api/src/modules/process/internal/domain/routing.ts

@@ -141,3 +141,52 @@ export function rejectRouteOf(
 export function startNodeOf(pkg: ProcessPackage): ProcessNode | undefined {
   return pkg.nodes.find((n) => n.kind === 'start');
 }
+
+/**
+ * 推进次序 —— 按**边**做拓扑序,不看图纸坐标。
+ *
+ * 「链」要回答的是「这一单接下来往哪走」,那是边的事实。曾经拿 `layout.col` 排,
+ * 因为 v1 的包是一行从左画到右,列位恰好等于推进次序 —— 但 MVP 图是**回形走线**
+ * (第 0 行左→右、第 1 行右→左、第 2 行折回最左),A7 的列位跟 A1 并列,链就读成了
+ * A1 → A7 → A2 → A6 → A3(实测)。图纸声明为「不影响语义」,那它也不配决定次序。
+ *
+ * 回边(`reopen`)排除在外:它是**重新入场**,不是往前推进。留着它图上就有环,
+ * 拓扑序无从下手(G4 → A4 会让 A4 等自己的下游)。
+ *
+ * 真并行的分支(G2 分出的 A2 / A3)在图上本无先后,链却必须挑一个顺序:
+ * 按**节点编号**定,于是同样的包在谁手上都读作同一条链。
+ * 进不了拓扑序的节点(不可达、或排除回边后仍有环)一律按编号缀在末尾 —— 少排序,不丢节点。
+ */
+export function advanceOrder(pkg: ProcessPackage): readonly ProcessNode[] {
+  const byId = new Map(pkg.nodes.map((n) => [n.id, n]));
+  const byNodeId = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+
+  const forward = pkg.edges.filter((e) => e.reopen !== true && byId.has(e.from) && byId.has(e.to));
+  const indegree = new Map(pkg.nodes.map((n) => [n.id, 0]));
+  const next = new Map<ProcessNode['id'], ProcessNode['id'][]>();
+  for (const e of forward) {
+    indegree.set(e.to, (indegree.get(e.to) ?? 0) + 1);
+    next.set(e.from, [...(next.get(e.from) ?? []), e.to]);
+  }
+
+  // Kahn:每轮从「无未满足前驱」的节点里取编号最小的,顺序才与书写无关
+  const ready = pkg.nodes.filter((n) => indegree.get(n.id) === 0).map((n) => n.id);
+  const ordered: ProcessNode[] = [];
+  const placed = new Set<string>();
+  while (ready.length > 0) {
+    ready.sort(byNodeId);
+    const id = ready.shift()!;
+    if (placed.has(id)) continue;
+    placed.add(id);
+    const node = byId.get(id);
+    if (node !== undefined) ordered.push(node);
+    for (const to of next.get(id) ?? []) {
+      const left = (indegree.get(to) ?? 0) - 1;
+      indegree.set(to, left);
+      if (left === 0) ready.push(to);
+    }
+  }
+
+  const stranded = pkg.nodes.filter((n) => !placed.has(n.id)).sort((a, b) => byNodeId(a.id, b.id));
+  return [...ordered, ...stranded];
+}