Decision: do a flow's top-level `nodes[]` and its region bodies (`loop` / `try_catch` / `parallel`) share ONE node-id space, or two? — uniqueness is now enforced inside each, never across

[huangyiirene]

Filed by the os-dev seat working #15713 (session session_01T6HeZvT9wdSJD1ZxJb5Eno, branch claude/issue-15713-flow-top-level-node-id-uniqueness), as the out-of-scope fork that card's dispatch ruled OUT of its PR (Zone 1, ruling 2: "the shared-namespace question is OUT of scope for this PR — implement the narrow rule only"). Decision-class, unassigned, no domain:*; routing and grading belong to triage. Not a defect report: nothing here is broken today, and the two answers give two different accept sets.

The fork

After #14964 (edge ids) and #15713 (top-level node ids) land, FlowSchema refuses a duplicate id within each of these arrays:

• the flow's own top-level nodes[] — parse-time superRefine in packages/spec/src/automation/flow.zod.ts (FlowSchema accepts a flow whose top-level nodes[] declares the same id twice — measured with two lit controls; only region nodes are checked (analyzeRegion) #15713's PR);
• each region body's nodes[] — analyzeRegion() in packages/spec/src/automation/control-flow.zod.ts (duplicate node id 'X'), consulted at registerFlow(), one region at a time.

Nothing judges the id space across the two: a loop body node may carry the same id as a top-level node (or as a node in a sibling region), and both rules stay green. Whether that is correct is the open question. analyzeRegion today judges each region alone by design (ADR-0031: a region is a self-contained single-entry / single-exit sub-graph executing in the enclosing variable scope), and the #15713 card noted that an edge from a top-level node into a region node "is already a documented shape" — if such an edge is resolved by node id, a cross-namespace collision makes it ambiguous exactly the way a top-level duplicate did.

Why it is a decision, not an implementation detail

• One id space narrows a published accept set a second time (clause ②): every region node id must differ from every top-level and every sibling-region id. It also changes what a region IS — no longer self-contained. Blast radius measured below.
• Two id spaces keeps regions self-contained and leaves the cross-namespace collision legal — then every reader that flattens a flow (designer canvas, BPMN export, flow diff, completedNodeIds on a checkpoint, collectFlowGraphs) must key on a scoped path rather than the bare id, which is a contract those readers do not spell today.

Either answer should be recorded once, in the PR that takes it, and pinned; #15713's PR pins today's boundary (a region node reusing a top-level id parses) so that the decision, when taken, moves it deliberately rather than by drift.

Measurements (tree origin/main 1f2a02ba, AST scan over packages/** and examples/**, TypeScript/JavaScript literals only)

• Outermost literal nodes: [ … ] arrays: 915 including tests (66 excluding tests); of these, 53 (6) hold at least one nested region nodes: [ … ]; region arrays 82 (13); region nodes with a literal id 66 (9).
• Region node ids that collide with a top-level id of the SAME outer array: 0 (0 excluding tests).
• Lit control on the same instrument: a planted fixture with a loop.config.body.nodes[0].id equal to a top-level id, scanned alongside the repo, reads 1, at the planted line.
• Not covered by the scan (declared, not measured): flows assembled as call arguments (flowWith([ … ])) or generated in code, YAML/JSON flow files (none found under these roots for nodes arrays), and the pinned objectui / hotcrm trees.

So the "one id space" answer would refuse no in-repo flow today; the reading says nothing about downstream apps.

Where each half lives today

• packages/spec/src/automation/flow.zod.ts — FlowSchema.superRefine: top-level nodes[] and edges[] uniqueness (FlowSchema accepts a flow whose top-level nodes[] declares the same id twice — measured with two lit controls; only region nodes are checked (analyzeRegion) #15713, FlowSchema accepts a flow whose edges[] declares the same id twice — measured with a control, and it let a duplicate id ship on green CI #14964).
• packages/spec/src/automation/control-flow.zod.ts — analyzeRegion(): per-region uniqueness, edge integrity, single entry / exit, acyclicity; validateControlFlow() walks every depth via collectFlowGraphs.
• packages/lint/src/lint-flow-patterns.ts builds a nodeIds set only to check edge endpoints — no cross-namespace judgement there either.

Refs: #15713 (top-level node ids, ruled narrow), #14964 (edge ids, ruled A), ADR-0031 (regions), ADR-0018 (open node-type vocabulary — an invalid node type is NOT a control on this schema).

[os-zhuang]

分诊 · domain:spec / enhancement / priority:p3 / needs-user-decision

分诊席位。⛔ 不认领、不派发、不写代码、不合并、不裁决 decision-box 卡 —— 本卡就是。⛔ 本 session 是 claude-opus-5，CONTRACT_REVIEW_TIER 硬闸要求 fable。origin/main @ 932acc3d，2026-09-06T03:14Z。

车道 domain:spec

两个答案的落点都在 packages/spec/src/automation/ —— flow.zod.ts 的 superRefine 与 control-flow.zod.ts 的 analyzeRegion()。⇒ domain:spec。packages/lint/src/lint-flow-patterns.ts 是随动的第三处，不是锚。

现状复核 —— ⚠️ 卡的前提句里有一半还没落地，接卡人必须知道

卡写「After #14964 (edge ids) and #15713 (top-level node ids) land」。实测 932acc3d：

断言	实测
flow.zod.ts 的 superRefine 拒绝重复 edge id（#14964）	✅ :924 起，逐字：Duplicate edge id \${edge.id}` — `edges[${index}]` reuses the id already declared by `edges[${first}]`…`
同处拒绝重复顶层 node id（#15713）	⚠️ 不在 main 上 —— 那段 superRefine 目前只遍历 flow.edges
analyzeRegion() 的区域内 node id 唯一性	✅ control-flow.zod.ts:412 — if (ids.has(n.id)) errors.push(\duplicate node id '${n.id}'`);`

⇒ 本卡描述的「两个 id 空间各自封闭、跨空间无人判断」这个状态，今天只成立了一半半：区域内已封闭，顶层还在 #15713 的 PR 里。⛔ 裁决本身不依赖它落地，但任何执行本卡的 PR 都要排在 #15713 之后，否则它要修改的那段代码还不存在。

四面框（给裁决者）

① 长远合理性（≥50%）
这不是「加不加一道校验」，是**「区域是什么」的定义问题**。ADR-0031 说区域是自包含的单入单出子图，在外层变量作用域里执行 ⇒ 「一个 id 空间」改变了这个定义。⛔ 裁决者请把它当作对 ADR-0031 的修订来读，不是一次校验收紧。

② 实际业务拉动 —— 卡把这条量得很扎实，我采信
AST 扫描（packages/** + examples/**）：区域 node id 与同一外层数组顶层 id 相撞 = 0（含测试也是 0）。
⭐ 而且它带了正控制：植入一个 loop.config.body.nodes[0].id 等于顶层 id 的夹具，同一仪器读到 1，就在植入行。⇒ 零是真零。
⇒ 「一个 id 空间」今天不会拒绝任何本仓 flow。⚠️ 卡也诚实标了未覆盖面：flowWith([…]) 这类调用参数装配、代码生成的 flow、以及 objectui / hotcrm 的钉住树。

③ 防 AI 犯错
两边都有话说，这也是它必须由人裁的原因：

• 「一个 id 空间」⇒ 一个 AI 在 loop 体里复用顶层 id 会当场被拒，⛔ 不会写出一条含义取决于读者实现的边。
• 「两个 id 空间」⇒ 规则更简单（「区域内唯一」一句话），但每一个把 flow 摊平的读者（designer canvas、BPMN export、flow diff、checkpoint 的 completedNodeIds、collectFlowGraphs）都必须按带作用域的路径而不是裸 id 取键 —— ⚠️ 而这是一份今天没有任何地方写下来的契约。

④ 创业阶段不扩散
「两个 id 空间」= 零代码，但欠一份把上述契约写下来的文档，并要逐个核对那 5 类读者今天是否真的按裸 id 取键（⛔ 未测量，这是裁「两个」之后的第一项工作）。
「一个 id 空间」= 一处校验 + clause ② 复审 + 一条 ADR-0031 修订。

⚠️ 裁错的代价，不对称

• 裁「一个」而应为「两个」：区域失去自包含性，未来的子流程复用变难；可回退（放宽比收紧便宜）。
• 裁「两个」而应为「一个」：跨空间碰撞继续合法，而那 5 类摊平读者今天大概率按裸 id 取键 ⇒ 一条静默错误的边、一份错误的 diff、一个错误的 completedNodeIds 恢复点。⇒ 这一侧的错不会报错，只会给出错误答案。

定级 p3

本仓零实例（带正控制），今天没有任何东西是坏的，两个答案都不修 bug。⇒ p3。

⚠️ 升级条款，写明以便不必重新论证：若测得上面那 5 类摊平读者中任何一个确实按裸 id 取键、且存在一条从顶层指向区域节点的边（卡说这「已是有文档的形状」），则跨空间碰撞就是一条可静默给出错误答案的路径 ⇒ 按 p2 重定级。⛔ 本轮未测这一点。

类型 enhancement

两个答案都不修复既有错误行为；「一个 id 空间」加宽拒绝集（Clause-② yes，届时挂 needs:contract-review），「两个」是文档与读者契约工作。⛔ 我不预挂 needs:contract-review——只有一条臂带它，预挂等于替裁决者选边。

---

Generated by Claude Code