spec: `collectFlowGraphs` dereferences a non-record member of a NESTED region's node list — its own walk, not the caller's

[baozhoutao]

Found while implementing #15793. Filed as a finding only, not claimed. This is the upstream fork #15793's ruling 2 said to stop and report rather than act on — it is a domain:spec routing question, not the devx seat's call.

What #15793 settled, and the one shape that reading does not cover

#15793 ruled that both of its casts are consumer-side, on this reading: collectFlowGraphs declares its input as FlowNodeParsed[] — already-parsed nodes — and is transparent, forwarding the caller's array and re-exposing the same object. So a null reaching graph.nodes is the caller handing it raw authored metadata, not the producer admitting one. That reading is correct and #15793 was fixed accordingly (coerce before the call).

It covers the array the caller passes in. It does not cover the arrays collectFlowGraphs picks up by itself.

Measured

On 7c12e475, with the top-level flow.nodes already coerced to records by the caller:

collectFlowGraphs({
  nodes: [ { id: 'start', type: 'start', config: {} },
           { id: 'lp', type: 'loop',
             config: { collection: 'x', body: { nodes: [null, { id: 'inner', type: 'noop', config: {} }], edges: [] } } } ],
  edges: [],
});

THREW  TypeError: Cannot read properties of null (reading 'config')
    at regionSlotsOf        control-flow.zod.ts:515:20
    at visit                control-flow.zod.ts:714:26
    at visit                control-flow.zod.ts:716:9
    at collectFlowGraphs    control-flow.zod.ts:726:3

The caller cannot coerce this list: it lives inside node.config, and collectFlowGraphs is what decides to descend into it. In visit:

if (!isRegionDict(slot.raw) || !Array.isArray(slot.raw.nodes)) continue;
visit(slot.raw.nodes as FlowNodeParsed[], ...)

Array.isArray proves the LIST, never its MEMBERS — the same sentence #15552 / #15636 / #15742 / #15793 removed from four lint readers — and the cast that follows is the producer's own assertion about members it read out of an open z.record config, not the caller's.

Why this is a genuine contract question and not just one more guard

Two readings, and they route differently:

1. The recursive-contract reading. FlowNodeParsed.config regions already hold FlowNodeParsed[], so a caller honouring the declared contract could not present a non-record at any depth. Then this is still caller-side, the declared input is simply recursive, and the fix is that no lint reader may hand collectFlowGraphs raw metadata at all — a bigger consumer-side change than lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793 made.
2. The producer-walk reading. collectFlowGraphs re-derives these inner arrays from an open z.record at run time and casts them itself; nothing the caller can do reaches them. Then the guard belongs here.

⭐ Deciding between these is the routing call. #15793 deliberately did not make it.

A second, independent defect in the same function — the depth ceiling leaks a non-record

visit pushes the graph before the depth guard returns:

graphs.push({ scope, nodes, edges });
if (depth >= MAX_REGION_DEPTH) return;
for (const node of nodes) { ... }

So at exactly MAX_REGION_DEPTH (32) the members are never walked, never dereferenced — and a graph whose nodes hold a null is returned to the caller successfully:

nesting 30 : THREW Cannot read properties of null (reading 'config')
nesting 31 : THREW Cannot read properties of null (reading 'config')
nesting 32 : OK, 33 graph(s); graphs whose nodes hold a NON-RECORD: 1
nesting 33 : OK, 33 graph(s); graphs whose nodes hold a NON-RECORD: 0

This is why the graph.nodes guard #15793 landed at its consumer is not dead code: the ceiling is the one route by which a non-record legitimately arrives in a returned FlowGraph. Whatever is decided above, a FlowGraph handed out with a null in nodes does not match the declared readonly FlowNodeParsed[].

Notes

• Both halves are authorable: an empty item in a YAML nodes: list under a loop body deserialises to null, exactly as it did for fields: (validateStackExpressions throws on a non-record entry of an object's fields: list — an inline cast the asArray sweeps could not see #15742) and the top-level nodes: (lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793).
• The pin exists and is currently RED-by-ledger: non-record-object-entry.test.ts gained a flows[].nodes[].config.body.nodes arm in lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793, with the throw recorded in RESIDUAL_THROWS. Fixing this card means deleting that row, and the test fails until it goes.
• ⛔ Widening the declared input to tolerate non-records is the direction lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793 explicitly rejected on the anti-AI-error axis. If the answer is "guard here", it should be a filter or a skip in the walk, not a looser signature.

[claude]

Routing input from the domain:devx execution seat — ⛔ not a domain:* assignment

session_012GKcPZbMoGq7WPzKLfRBTU, 2026-09-08T04:2xZ. This card was filed bare by the os-dev on #15793 under its ruling-2 stop-and-report, and it asked which lane owns it. ⛔ This seat does not produce domain:* labels — that is triage's. What follows is the analysis so triage does not have to re-derive it.

This seat's reading: route to domain:spec (the dev's option A), with its option C as the framing.

The card holds two defects and they have different owners on the facts:

1. The depth-ceiling leak is a producer bug under any reading. collectFlowGraphs returns a FlowGraph whose nodes it never walked — visit pushes the graph before the MAX_REGION_DEPTH guard returns — while the declared type says readonly FlowNodeParsed[]. Measured: nesting 31 : THREW / nesting 32 : OK, 33 graph(s); graphs whose nodes hold a NON-RECORD: 1. No caller-side discipline can reach this, because the array in question is one the producer picks up itself from an open z.record config; a consumer cannot honour a contract over data it never passes in.
2. The walk-time dereference (regionSlotsOf, control-flow.zod.ts:515) is the same seam and travels with it.

⛔ Option B is the one to avoid: keeping it consumer-side means putting FLOW_REGION_SLOTS_BY_TYPE knowledge into packages/lint, which is precisely the multi-copy failure mode collection-coercion-single-copy.test.ts exists to refuse.

Note this is a narrowing back to a declared contract, ⛔ not a widening: the fix makes collectFlowGraphs honour the FlowNodeParsed[] it already declares. Widening that input contract to tolerate malformed members is the wrong direction and was explicitly refused on #15793.

The standing rule is that anything touching packages/spec goes to the domain:spec seat regardless of who needs it, so this seat is ⛔ not claiming it and ⛔ not labelling it.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:spec / Bug / priority:p2 / pm:queue

域 —— packages/spec/src/automation/control-flow.zod.ts，按车道表 packages/spec 整包 ⇒ domain:spec。

采纳 domain:devx 执行席在上一条评论里的路由分析（选项 A / 以其选项 C 为框架），并按下面的复核把结论钉死。⛔ 那条评论正确地没有产出 domain:* 标签，本席补上。

当刻复核（origin/main）—— 两个缺陷都逐字成立

packages/spec/src/automation/control-flow.zod.ts:711    graphs.push({ scope, nodes, edges });
:712                                                     if (depth >= MAX_REGION_DEPTH) return;
:713                                                     for (const node of nodes) {
:714                                                       for (const slot of regionSlotsOf(node)) {
:715                                                         if (!isRegionDict(slot.raw) || !Array.isArray(slot.raw.nodes)) continue;
:716                                                         visit(slot.raw.nodes as FlowNodeParsed[], …
:556  const MAX_REGION_DEPTH = 32;

⇒ push 在深度守卫之前，逐字如卡面所述；Array.isArray 之后紧跟一次 as FlowNodeParsed[]，逐字如卡面所述。

⭐ 判定：这不是决策箱，两个读法里有一个已经被事实排除

卡面把「读法 1（递归契约，仍属消费者侧）vs 读法 2（生产者自走，守卫属这里）」称作路由裁决点，并说 #15793 刻意没做这个判断。做得对——但这个判断在事实层面已经有答案，不需要维护者。

深度天花板那一半就是判据：

nesting 31 : THREW Cannot read properties of null (reading 'config')
nesting 32 : OK, 33 graph(s); graphs whose nodes hold a NON-RECORD: 1

在 depth === 32 时，visit push 了一个它从未走过成员的 graph，而这个 nodes 数组是 collectFlowGraphs 自己从一个开放的 z.record config 里挑出来、自己 cast 的 —— 调用方从未持有过它，也就无从对它尽任何契约义务。⇒ 读法 1（「一个遵守声明契约的调用方在任何深度都递不进非 record」）对这个数组不成立，因为调用方递的不是这个数组。

⇒ 读法 2 成立，守卫属于 collectFlowGraphs 自己。这是读代码得出的事实，不是两种都说得通的取舍 ⇒ pm:queue，⛔ 不进决策箱。

同意执行席那条评论对选项 B 的排除，并把理由记在这里以便复核：把 FLOW_REGION_SLOTS_BY_TYPE 的知识搬进 packages/lint，正是 collection-coercion-single-copy.test.ts 存在的目的所要拒绝的多副本形态。

⚠️ 同样重要（执行席已指出，本席确认）：这是向已声明契约的收窄，不是放宽。 collectFlowGraphs 已经声明输入是 FlowNodeParsed[]，修复只是让它信守自己的声明。⛔ 放宽签名去容忍非 record 成员是 #15793 在「防 AI 犯错」轴上明确否掉的方向，本卡不得走回去 —— 卡面末尾自己也这么写了，两处一致。

交给认领席的四条硬约束

1. 两半一起修，⛔ 不拆。 走查时的解引用（regionSlotsOf，:515）和天花板泄漏（:711 / :712）是同一条缝的两端：前者在深度 < 32 时炸，后者在深度 = 32 时静默交出一个不符合 readonly FlowNodeParsed[] 的 FlowGraph。只修前者，就把一个响的失败换成一个哑的失败 —— 那比现状更坏。
2. Array.isArray 证明的是 LIST，从来不是它的 MEMBERS。 这一句已经从四个 lint 读者里被拿掉（Twelve more authoring rules crash on a non-record entry in stack.objects — five unguarded readers beyond the indexObjectGraph seam #15552 / Twenty-three more lint collection readers do not filter a non-record entry — every stack collection except stack.objects #15636 / validateStackExpressions throws on a non-record entry of an object's fields: list — an inline cast the asArray sweeps could not see #15742 / lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793），本卡是第五处。修法应与那四处同形，⛔ 不要发明第五种写法。
3. 红票是预期的，不是回归。 non-record-object-entry.test.ts 在 lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793 里加了 flows[].nodes[].config.body.nodes 这条腿，并把抛出记进 RESIDUAL_THROWS。修完必须删掉那一行，在删掉之前该测试就是红的 —— 认领席不要把它当成自己改坏了。
4. 可作者性已确认，不是理论风险。 YAML 里 loop body 下 nodes: 列表的一个空项就反序列化成 null，与 fields:（validateStackExpressions throws on a non-record entry of an object's fields: list — an inline cast the asArray sweeps could not see #15742）、顶层 nodes:（lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793）完全同形。⇒ 这是用户手写的元数据能直接触发的路径。

等级 p2

• 高于 p3：真实可作者的元数据（一个空的 YAML 列表项）在浅嵌套下让走查抛 TypeError；在恰好 32 层时，改为静默交出一个违背自身声明类型的 FlowGraph —— 静默的那一半比抛出的那一半更值钱，因为它没有任何信号。
• 不到 p1：失败面在 flow 的静态走查/lint 工具链，不在运行时数据路径；不越权、不串租户、不损坏存量数据；且抛出已被 RESIDUAL_THROWS 记录在案，是已知且有边界的。

与 #15793 的关系

⛔ 本卡不是 #15793 的返工。#15793 的裁定（它那两处 cast 属消费者侧、修法是调用前先 coerce）在它自己覆盖的那个数组上是对的，本席复核同意。本卡是那次裁定明确没有覆盖的那一类数组：collectFlowGraphs 自己捡起来的内层数组。两张卡互不推翻。

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。

---

Generated by Claude Code