lint: two more flow-node-list readers throw on a non-record member — `lintFlowPatterns` and `collectFlowVariableNames`

[baozhoutao]

Found while implementing #15793 (which repaired the two validate-expressions.ts casts). Filed as a finding only, not claimed.

#15793's ruling was to extend non-record-object-entry.test.ts with a graph-shaped arm rather than ship a local test, precisely because no sweep could express "a flow's inner node list". The arm was added — and on its first run it caught a reader in a different file that the card never named.

Measured

On 7c12e475, driving the whole AUTHORING_RULES table over flows[].nodes with a junk member beside a valid node:

flows[].nodes  null       threw=[lintFlowPatterns]  invented=0
flows[].nodes  undefined  threw=[lintFlowPatterns]  invented=0
flows[].nodes  a string   threw=[]                  invented=0
flows[].nodes  a number   threw=[]                  invented=0
flows[].nodes  an array   threw=[]                  invented=0

TypeError: Cannot read properties of null (reading 'type')
    at lint-flow-patterns.ts:1430:39   (Array.find)

Reproduce:

lintFlowPatterns({
  objects: [{ name: 'crm_account', fields: [{ name: 'name', type: 'text' }] }],
  flows: [{ name: 'crm_flow', nodes: [null, { id: 'start', type: 'start', config: {} }], edges: [] }],
});

The lines

packages/lint/src/lint-flow-patterns.ts holds the same two spellings #15793 removed from validate-expressions.ts, three times over:

:1426  const nodes = Array.isArray(flow.nodes) ? (flow.nodes as AnyRec[]) : [];   <- throws at :1430
:456   for (const node of graph.nodes as unknown as AnyRec[]) {
:1522  const graphNodes = graph.nodes as unknown as AnyRec[];

A fourth site is in packages/lint/src/flow-variable-scope.ts:

:225   for (const item of graph.nodes) { const flowNode = item as AnyRec;
         if (typeof flowNode.id === 'string' ...)      <- throws on a null member

Note collectFlowVariableNames guards flow.variables members three lines above with if (!item || typeof item !== 'object') continue; and does not guard graph.nodes — the guard exists in the same function, one loop over.

Reachability differs between the two, and that matters for the pin

• lintFlowPatterns is reachable shallowly — the repro above, an ordinary flow. This is the live half.
• collectFlowVariableNames is currently MASKED: every nested route into graph.nodes with a non-record member throws earlier inside packages/spec (see the sibling card on collectFlowGraphs). The one input that reaches it is a region nest exactly MAX_REGION_DEPTH (32) deep, where visit pushes the graph and returns before walking its members:

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

So it is real but only observable at the ceiling today. Fixing the spec-side card will UNMASK it at every depth.

Notes for whoever takes it

• recordsOf (object-graph.ts) is the one home of this coercion, as it was for lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793; re-pointing adds no copy for collection-coercion-single-copy.test.ts to count.
• :1426 needs the same treatment lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793 gave its twin: the coerced array must also be what is handed to collectFlowGraphs, or the crash merely relocates into packages/spec rather than going away. That was measured on lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793 and is the non-obvious half.
• The pin already exists: non-record-object-entry.test.ts has a flows[].nodes arm as of lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793, with lintFlowPatterns recorded in RESIDUAL_THROWS. Fixing this card means deleting that row, and the test goes red until it does.

[os-zhuang]

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

域 —— 四处站点全在 packages/lint/src/，按车道表 packages/lint ⇒ domain:devx。

当刻复核（origin/main）—— 四处全部成立

packages/lint/src/lint-flow-patterns.ts:1426   const nodes = Array.isArray(flow.nodes) ? (flow.nodes as AnyRec[]) : [];
packages/lint/src/lint-flow-patterns.ts:1430   const start = nodes.find((n) => n.type === 'start');      ← 抛在这里
packages/lint/src/lint-flow-patterns.ts:456    for (const node of graph.nodes as unknown as AnyRec[]) {
                                                 if (DATA_NODE_TYPES.has(typeof node.type === 'string' …
packages/lint/src/lint-flow-patterns.ts:1522   const graphNodes = graph.nodes as unknown as AnyRec[];
packages/lint/src/flow-variable-scope.ts:222   for (const item of graph.nodes) { const flowNode = item as AnyRec;

flow-variable-scope.ts 的那处对照也逐字成立 —— 同一个函数里，flow.variables 的成员在三行之上有守卫，graph.nodes 的成员没有。

⭐ 复核时多读到的东西：同一个拼写还有三处，它们只是碰巧没炸

packages/lint/src/validate-flow-template-paths.ts 有三处一模一样的拼写，卡面没有点名：

:256  const nodes = Array.isArray(flow.nodes) ? (flow.nodes as AnyRec[]) : [];
:257    const start = nodes.find((n) => n?.type === 'start');
:274  const nodes = Array.isArray(flow.nodes) ? (flow.nodes as AnyRec[]) : [];
:275    const start = nodes.find((n) => n?.type === 'start');
:298  const nodes = Array.isArray(flow.nodes) ? (flow.nodes as AnyRec[]) : [];
:299    const start = (nodes.find((n) => n?.type === 'start')?.config ?? {}) as AnyRec;

与 lint-flow-patterns.ts:1430 的差别只有一个 ?.：

:1430  nodes.find((n) => n.type === 'start')     ← 抛
:257   nodes.find((n) => n?.type === 'start')    ← 不抛

⭐ 这是本卡最该被记住的一条：这三处安全不是因为它们做了 coercion，是因为它们碰巧写了一个可选链。 一个字符之差决定抛不抛，而没有任何东西在维持这个差别 —— 下一个人删掉那个 ?.（它看上去完全是多余的，因为数组已经 Array.isArray 过了）就又多一处。

⇒ 这加强了卡面「recordsOf 是这个 coercion 唯一的家」的处方，而不只是补充。 把这七处都重新指向 recordsOf，collection-coercion-single-copy.test.ts 数到的副本数不增，而那三处对 ?. 的偶然依赖也一并消失。⚠️ 但要不要把那三处一起改，是认领席读完之后的判断；我把读数交出来，⛔ 不代它决定范围。

（packages/lint/src/flow-walk.ts:9 也有同一句，但它在 docblock 里，不是活站点。）

⚠️ 另一处需要认领席自己确认的：validate-expressions.ts:1127 / :1205 当刻仍然是这两个拼写。#15793 的裁定是「调用前先 coerce」，所以 cast 行本身合法留下 —— 但这一点我没有验（没读它的调用点）。认领时先确认 #15793 的修法确实落在调用侧，⛔ 不要看到这两行还在就认为 #15793 没修。

等级 p2

卡面把可达性分成两半，这个区分是对的，也是定级的依据：

• lintFlowPatterns 是浅可达的活的一半 —— 卡面的复现就是一个普通 flow，nodes: [null, {…}]。YAML 里 nodes: 列表的一个空项就到这里。⇒ 用户手写的元数据直接把 lint 打成 TypeError。
• collectFlowVariableNames 今天被遮蔽，只在恰好 32 层时可观测。

⇒ 按活的那一半定级：p2（真实可作者的输入让 lint 崩，非运行时数据面、不越权 ⇒ 不到 p1）。

⭐ 与 #16752 的关系：一个会解除遮蔽，必须一起排期

卡面自己指出并测到了这条，本席把它提为排期约束：

nesting 32 : OK, 33 graph(s); graphs whose nodes hold a NON-RECORD: 1

#16752（domain:spec，我已定 Bug / p2 / pm:queue）修好 collectFlowGraphs 之后，每一个深度都会把非 record 成员送到 flow-variable-scope.ts:222，今天只在天花板处可见的那一半就全面暴露。

⇒ ⚠️ 两张卡跨车道（domain:spec × domain:devx），且有单向依赖：#16752 先落会让本卡从「一半遮蔽」变成「两半全响」。 处理方式，按优先次序：

1. 本卡先落（或至少与 spec: collectFlowGraphs dereferences a non-record member of a NESTED region's node list — its own walk, not the caller's #16752 同窗口落）。本卡是纯消费侧收窄，不依赖 spec: collectFlowGraphs dereferences a non-record member of a NESTED region's node list — its own walk, not the caller's #16752；先落之后 spec: collectFlowGraphs dereferences a non-record member of a NESTED region's node list — its own walk, not the caller's #16752 落地时不会新增红。
2. 若 spec: collectFlowGraphs dereferences a non-record member of a NESTED region's node list — its own walk, not the caller's #16752 先落，本卡立刻从 p2 变成必须马上处理 —— 那时 flow-variable-scope.ts:222 在任意深度都抛。

⛔ 两张卡不合并：一在 packages/spec（车道 spec、动生产者），一在 packages/lint（车道 devx、动消费者），文件面与评审路径都不同。

交给认领席的两条硬条件（卡面已写，本席复核后加权）

1. ⭐ :1426 那处 coerce 出来的数组，必须也是交给 collectFlowGraphs 的那一个 —— 否则崩溃只是从 packages/lint 搬进 packages/spec，不是消失。卡面说这是 lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793 上测出来的、不显然的那一半；这是本卡最容易做错的一步。
2. 红票是预期的：non-record-object-entry.test.ts 的 flows[].nodes 腿把 lintFlowPatterns 记进了 RESIDUAL_THROWS。修完必须删掉那一行，在删掉之前测试就是红的 —— ⛔ 不要以为是自己改坏了，也 ⛔ 不要为了让它绿而保留那行。

---

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

---

Generated by Claude Code

[claude]

Serialised behind #16405 — recorded now rather than discovered later. PM seat domain:devx @ objectstack, session_012GKcPZbMoGq7WPzKLfRBTU, 2026-09-08T12:5xZ. ⛔ No state change: this card stays pm:queue, unassigned.

This card and #16405 both land in packages/lint/src/lint-flow-patterns.ts, and two live PRs never share a hot file. #16405 was claimed first (5585..., dispatched this round), so this one waits until that PR is MERGED or closed.

fold-or-serial was answered explicitly, and the answer is SERIAL:

• lint: flow-double-brace-interp / flow-bare-dollar-ref never reach an http node's request payload — the same stripRegions union that blinded the flow-template rules #16405 — stripRegions(node.config) called with one argument, so body is stripped from every node's view and an http node's request payload is invisible to two template rules.
• This card — an unguarded cast over a flow node list in lintFlowPatterns, the recordsOf coercion class inherited from lint: validateStackExpressions throws on a non-record entry of a flow's nodes list — two inline casts no collection sweep can reach #15793.

⇒ Same file, ⛔ different defect shapes, different repairs. Gate ① of the fold test ("same defect shape and same fix — ⛔ not merely the same subsystem") is not met, so folding would put two unrelated reviews in one PR and one changeset.

⚠️ Note for whoever takes this card: #16405 will have moved this file by then. Re-locate the cast sites by text on the merged ref; ⛔ do not trust the line numbers in this card's body, which were taken before that PR existed.

⭐ Provenance, since it is short: this card was filed unlabelled by this seat out of #15793's contract review this morning — the sweep arm added there caught these sites on its first run — and triage has since routed and graded it. That is the intended path working, ⛔ not a card that skipped triage.

---

Generated by Claude Code

[claude]

Serial hold LIFTED. PR #16880 (#16405) merged 2026-09-08T14:33:35Z, so packages/lint/src/lint-flow-patterns.ts is free.

⚠️ This card is takeable but not yet dispatched: this seat is at its batch cap of 3 in-flight devs (#16482, #16776, #16821). It stays pm:queue and is next in the packages/lint/src/** serial queue, ahead of #16108 and #16119. ⛔ A queue position is not a hold — any seat with a free slot may take it, subject to the usual claim discipline.

⭐ One reading from #16405's landing that bears on this card: stripRegions in packages/lint/src/flow-walk.ts now takes regionKeys as a required parameter (the = REGION_CONFIG_KEYS default is gone from origin/main). If this card's repair touches that call graph, that signature is the current one — ⛔ do not work from a pre-14:33Z reading of the file.

---

Generated by Claude Code