fix(lint): extend the flattened-scope shadowing warning to the descriptor-declared predicate slots

[claude]

Fixes#14288

This card was measure-first: the ruling made "narrower per-node scope ⇒ close as not-a-gap, no PR" a complete deliverable, so the scope question was answered on the engine before any lint file was touched. The measurement says shared map, for both predicate slot kinds — so the fix applies, and it is one call site.

1. The measurement (engine, read-only)

All citations against packages/services/service-automation/src/engine.ts at base fed4fa409.

The shadowing mechanism is unchanged

seedRunVariables (engine.ts:7673-7692) seeds the flow's declared variables first and flattens the record's fields only where nothing is bound yet:

• :7679 — const variables = this.seedDeclaredVariables(flow, context);
• :7684 — for (const [k, v] of Object.entries(context.record)) { if (!variables.has(k)) variables.set(k, v); }

So a name bound as BOTH a declared variable and a field on the bound object resolves to the variable, silently. That is the #14089 diagnostic's whole subject.

The single map threads to every node executor — no clone, no narrowing

• :3835 — const variables = this.seedRunVariables(flow, flowName, context, runId);
• :3937 — await this.executeNode(startNode, flow, variables, runContext, steps);
• :6578-6583 — executeNode(node, flow, variables: Map, context, steps)
• :6647 / :6652 — executor.execute(node, variables, context)

The two positions PR #14263 already covers ride that same map: node conditions at :3874 and edge conditions at :6955. A grep for new Map(variables / new Map(...variables / scopeFor / narrowScope over engine.ts returns zero hits — the only const scope = new Map in the file is :5097, and it is a superset (below).

Slot kind 1 — decision.conditions[].expression ⇒ SHARED MAP

packages/services/service-automation/src/builtin/logic-nodes.ts:73

if (engine.evaluateCondition({ dialect: 'cel', source: cond.expression }, variables)) {

variables is the executor's own second parameter (async execute(node, variables, _context), logic-nodes.ts:46) — literally the same Map object handed in at engine.ts:6647/:6652, and therefore the same object a node condition is judged against at :3874. Same verdict as condition.

Slot kind 2 — screen.fields[].visibleWhen ⇒ SHARED MAP (superset)

refuseInvalidScreenInput (engine.ts:5084, called :4848):

• :5097 — const scope = new Map(Object.entries(run.variables));
• :5098 — for (const [k, v] of Object.entries(bag)) scope.set(k, v);
• :5102 — return this.evaluateCondition(String(field.visibleWhen), scope);

run.variablesis the persisted seedRunVariables map: the suspend path snapshots it at :4007 (Object.fromEntries(variables)) into persistSuspendedRun:4014; the re-suspend path does the same at :4971/:4976, and executeWithoutRetry at :7866/:7873. Resume rebuilds the traversal map from that identical field at :4855.

The submitted bag is overlaid on top, making the scope a superset — so the shadow still reaches it. The overlay carries the screen's own collected values (user input), never the bound record's field, so it can never hand back a field the variable displaced. A superset makes the warning more correct here, not less.

Verdict

Both predicate rows on the ledger evaluate against the run's one flattened variable map. Outcome A.loop.collection and map.collection are flow-template, not predicate, and the slot loop already skips them before this pass — so they are correctly untouched.

2. The change

packages/lint/src/validate-expressions.ts — the descriptor-slot loop (:1137-1143 on base). The location label is hoisted into one slotWhere const (it was already built inline for checkDeclaredPredicate) and onewarnShadowedFieldReads(slotWhere, found.value) call is added inside the existing role === 'predicate' branch, reusing the declaredVariables set collected once per flow at :1093. The comment records the measurement above so the next reader does not have to re-derive it.

Within option C's letter, as the ruling requires: warning-only, same severity, no new rule id, no accept set moved, and no bare identifier judged for being bare. Nothing that linted clean before can newly fail a build.

3. Tests

packages/lint/src/validate-expressions.test.ts — one positive and one negative per predicate slot kind, plus a severity assertion, nested inside the existing flattened-scope shadowing (#14089) block and reusing its shadowFields / record_change fixtures:

• screen visibleWhen reading a shadowed bare name ⇒ exactly one warning naming screen field visibleWhen at config.fields[0].visibleWhen
• screen visibleWhen whose bare name is a field only ⇒ zero issues (the canon-taught form)
• decision branch expression reading a shadowed bare name ⇒ exactly one warning naming decision branch expression at config.conditions[0].expression
• decision expression whose bare name is a variable only ⇒ zero issues
• both slots together ⇒ 2 issues, none above warning (a toHaveLength(1) would still pass if the issue were an error, so severity is asserted separately)

Reverse verification. Predicted direction: RED. The subject under test is imported relatively (from './validate-expressions.js'), so it resolves to package source, not dist — no rebuild leg applies. From the committed state, the single call-site line was deleted and the mutation confirmed on disk before measuring (marker count 1 before, 0 after; git diff --stat showed 1 deletion). Result: 3 failed, 2 passed — both positives (expected [] to have a length of 1) and the severity test (expected [] to have a length of 2). The two negative controls stayed green, which is correct: they assert zero warnings and so cannot detect the call site — they are controls, not detectors. The restore leg was then proven by byte identity, not by an exit code: worktree blob 47a90b260358d4c0ffdf8d4ca8adfe15e686844b equals the HEAD blob, git diff HEAD empty, marker count back to 1.

4. Verification

Union run on the final merged commit b3fbd92bc (after git merge origin/main).

• pnpm --filter @objectstack/lint test — 93 files, 2822 passed
• pnpm --filter @objectstack/lint typecheck — clean. tsconfig.json excludes *.test.ts, so the check:test-typecheck half is what covers the new tests; tsc -p tsconfig.test.json --listFiles confirms both edited files are in that program (the "green over source nothing read" trap), and the 6 residual errors are the ledgered TS6059 in two other files, none of them mine.
• pnpm lint — whole repo, eslint . --no-inline-config, exit 0. Not narrowed, so no narrowing argument is owed.
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — the script derives its own change set from the merge base): 34 families, identical before and after the merge. Harvested with --commands, not from the prose. Result: 33 exit 0, 1 NOT MEASURED — check-test-completeness.mjs, which grades a CI-produced turbo run test log and prints PREREQUISITE NOT MET with exit 3 locally, its own documented NOT MEASURED branch. node scripts/pm/dispatch-gates.mjs --ran reconciles: 34 derived, 34 run, 0 UNRUN.
• The build-dependent ratchets were re-run on the merged head against a rebuilt workspace (turbo run build, 70/70): check:type-check-debt (--re-measure: OK, none above its recorded number) and check:dual-build-cjs-loads both exit 0, as did the build-free ratchets.

Exit codes were captured by redirecting first and reading $? before any pipe, and each verdict above is the gate's own printed judgement line rather than a bare $?.

5. Changeset

.changeset/lint-shadow-warning-descriptor-predicate-slots.md — @objectstack/lint: patch.

Draft, per the dispatch order: not marked ready, auto-merge not enabled.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 1 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 84c605e5de514dcae6217d69c81ef4f8776e4371 — the merge of head b3fbd92bc3db882601a32037d05bdb3b2695fc6e into base 7286dd58e806ed321cbdfc23a1c455db8f80b1ad, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 84c605e5de514dcae6217d69c81ef4f8776e4371 && git checkout 84c605e5de514dcae6217d69c81ef4f8776e4371
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7286dd58e806ed321cbdfc23a1c455db8f80b1ad b3fbd92bc3db882601a32037d05bdb3b2695fc6e && git checkout -B drift-repro 7286dd58e806ed321cbdfc23a1c455db8f80b1ad && git merge --no-ff b3fbd92bc3db882601a32037d05bdb3b2695fc6e
node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14288

This card was measure-first: the ruling made "narrower per-node scope ⇒ close as not-a-gap, no PR" a complete deliverable, so the scope question was answered on the engine before any lint file was touched. The measurement says shared map, for both predicate slot kinds — so the fix applies, and it is one call site.

1. The measurement (engine, read-only)

All citations against packages/services/service-automation/src/engine.ts at base fed4fa409.

The shadowing mechanism is unchanged

seedRunVariables (engine.ts:7673-7692) seeds the flow's declared variables first and flattens the record's fields only where nothing is bound yet:

• :7679 — const variables = this.seedDeclaredVariables(flow, context);
• :7684 — for (const [k, v] of Object.entries(context.record)) { if (!variables.has(k)) variables.set(k, v); }

So a name bound as BOTH a declared variable and a field on the bound object resolves to the variable, silently. That is the #14089 diagnostic's whole subject.

The single map threads to every node executor — no clone, no narrowing

• :3835 — const variables = this.seedRunVariables(flow, flowName, context, runId);
• :3937 — await this.executeNode(startNode, flow, variables, runContext, steps);
• :6578-6583 — executeNode(node, flow, variables: Map, context, steps)
• :6647 / :6652 — executor.execute(node, variables, context)

The two positions PR #14263 already covers ride that same map: node conditions at :3874 and edge conditions at :6955. A grep for new Map(variables / new Map(...variables / scopeFor / narrowScope over engine.ts returns zero hits — the only const scope = new Map in the file is :5097, and it is a superset (below).

Slot kind 1 — decision.conditions[].expression ⇒ SHARED MAP

packages/services/service-automation/src/builtin/logic-nodes.ts:73

if (engine.evaluateCondition({ dialect: 'cel', source: cond.expression }, variables)) {

variables is the executor's own second parameter (async execute(node, variables, _context), logic-nodes.ts:46) — literally the same Map object handed in at engine.ts:6647/:6652, and therefore the same object a node condition is judged against at :3874. Same verdict as condition.

Slot kind 2 — screen.fields[].visibleWhen ⇒ SHARED MAP (superset)

refuseInvalidScreenInput (engine.ts:5084, called :4848):

• :5097 — const scope = new Map(Object.entries(run.variables));
• :5098 — for (const [k, v] of Object.entries(bag)) scope.set(k, v);
• :5102 — return this.evaluateCondition(String(field.visibleWhen), scope);

run.variablesis the persisted seedRunVariables map: the suspend path snapshots it at :4007 (Object.fromEntries(variables)) into persistSuspendedRun:4014; the re-suspend path does the same at :4971/:4976, and executeWithoutRetry at :7866/:7873. Resume rebuilds the traversal map from that identical field at :4855.

The submitted bag is overlaid on top, making the scope a superset — so the shadow still reaches it. The overlay carries the screen's own collected values (user input), never the bound record's field, so it can never hand back a field the variable displaced. A superset makes the warning more correct here, not less.

Verdict

Both predicate rows on the ledger evaluate against the run's one flattened variable map. Outcome A.loop.collection and map.collection are flow-template, not predicate, and the slot loop already skips them before this pass — so they are correctly untouched.

2. The change

packages/lint/src/validate-expressions.ts — the descriptor-slot loop (:1137-1143 on base). The location label is hoisted into one slotWhere const (it was already built inline for checkDeclaredPredicate) and onewarnShadowedFieldReads(slotWhere, found.value) call is added inside the existing role === 'predicate' branch, reusing the declaredVariables set collected once per flow at :1093. The comment records the measurement above so the next reader does not have to re-derive it.

Within option C's letter, as the ruling requires: warning-only, same severity, no new rule id, no accept set moved, and no bare identifier judged for being bare. Nothing that linted clean before can newly fail a build.

3. Tests

packages/lint/src/validate-expressions.test.ts — one positive and one negative per predicate slot kind, plus a severity assertion, nested inside the existing flattened-scope shadowing (#14089) block and reusing its shadowFields / record_change fixtures:

• screen visibleWhen reading a shadowed bare name ⇒ exactly one warning naming screen field visibleWhen at config.fields[0].visibleWhen
• screen visibleWhen whose bare name is a field only ⇒ zero issues (the canon-taught form)
• decision branch expression reading a shadowed bare name ⇒ exactly one warning naming decision branch expression at config.conditions[0].expression
• decision expression whose bare name is a variable only ⇒ zero issues
• both slots together ⇒ 2 issues, none above warning (a toHaveLength(1) would still pass if the issue were an error, so severity is asserted separately)

Reverse verification. Predicted direction: RED. The subject under test is imported relatively (from './validate-expressions.js'), so it resolves to package source, not dist — no rebuild leg applies. From the committed state, the single call-site line was deleted and the mutation confirmed on disk before measuring (marker count 1 before, 0 after; git diff --stat showed 1 deletion). Result: 3 failed, 2 passed — both positives (expected [] to have a length of 1) and the severity test (expected [] to have a length of 2). The two negative controls stayed green, which is correct: they assert zero warnings and so cannot detect the call site — they are controls, not detectors. The restore leg was then proven by byte identity, not by an exit code: worktree blob 47a90b260358d4c0ffdf8d4ca8adfe15e686844b equals the HEAD blob, git diff HEAD empty, marker count back to 1.

4. Verification

Union run on the final merged commit b3fbd92bc (after git merge origin/main).

• pnpm --filter @objectstack/lint test — 93 files, 2822 passed
• pnpm --filter @objectstack/lint typecheck — clean. tsconfig.json excludes *.test.ts, so the check:test-typecheck half is what covers the new tests; tsc -p tsconfig.test.json --listFiles confirms both edited files are in that program (the "green over source nothing read" trap), and the 6 residual errors are the ledgered TS6059 in two other files, none of them mine.
• pnpm lint — whole repo, eslint . --no-inline-config, exit 0. Not narrowed, so no narrowing argument is owed.
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — the script derives its own change set from the merge base): 34 families, identical before and after the merge. Harvested with --commands, not from the prose. Result: 33 exit 0, 1 NOT MEASURED — check-test-completeness.mjs, which grades a CI-produced turbo run test log and prints PREREQUISITE NOT MET with exit 3 locally, its own documented NOT MEASURED branch. node scripts/pm/dispatch-gates.mjs --ran reconciles: 34 derived, 34 run, 0 UNRUN.
• The build-dependent ratchets were re-run on the merged head against a rebuilt workspace (turbo run build, 70/70): check:type-check-debt (--re-measure: OK, none above its recorded number) and check:dual-build-cjs-loads both exit 0, as did the build-free ratchets.

Exit codes were captured by redirecting first and reading $? before any pipe, and each verdict above is the gate's own printed judgement line rather than a bare $?.

5. Changeset

.changeset/lint-shadow-warning-descriptor-predicate-slots.md — @objectstack/lint: patch.

Draft, per the dispatch order: not marked ready, auto-merge not enabled.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 1 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 84c605e5de514dcae6217d69c81ef4f8776e4371 — the merge of head b3fbd92bc3db882601a32037d05bdb3b2695fc6e into base 7286dd58e806ed321cbdfc23a1c455db8f80b1ad, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 84c605e5de514dcae6217d69c81ef4f8776e4371 && git checkout 84c605e5de514dcae6217d69c81ef4f8776e4371
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7286dd58e806ed321cbdfc23a1c455db8f80b1ad b3fbd92bc3db882601a32037d05bdb3b2695fc6e && git checkout -B drift-repro 7286dd58e806ed321cbdfc23a1c455db8f80b1ad && git merge --no-ff b3fbd92bc3db882601a32037d05bdb3b2695fc6e
node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14288

This card was measure-first: the ruling made "narrower per-node scope ⇒ close as not-a-gap, no PR" a complete deliverable, so the scope question was answered on the engine before any lint file was touched. The measurement says shared map, for both predicate slot kinds — so the fix applies, and it is one call site.

1. The measurement (engine, read-only)

All citations against packages/services/service-automation/src/engine.ts at base fed4fa409.

The shadowing mechanism is unchanged

seedRunVariables (engine.ts:7673-7692) seeds the flow's declared variables first and flattens the record's fields only where nothing is bound yet:

• :7679 — const variables = this.seedDeclaredVariables(flow, context);
• :7684 — for (const [k, v] of Object.entries(context.record)) { if (!variables.has(k)) variables.set(k, v); }

So a name bound as BOTH a declared variable and a field on the bound object resolves to the variable, silently. That is the #14089 diagnostic's whole subject.

The single map threads to every node executor — no clone, no narrowing

• :3835 — const variables = this.seedRunVariables(flow, flowName, context, runId);
• :3937 — await this.executeNode(startNode, flow, variables, runContext, steps);
• :6578-6583 — executeNode(node, flow, variables: Map, context, steps)
• :6647 / :6652 — executor.execute(node, variables, context)

The two positions PR #14263 already covers ride that same map: node conditions at :3874 and edge conditions at :6955. A grep for new Map(variables / new Map(...variables / scopeFor / narrowScope over engine.ts returns zero hits — the only const scope = new Map in the file is :5097, and it is a superset (below).

Slot kind 1 — decision.conditions[].expression ⇒ SHARED MAP

packages/services/service-automation/src/builtin/logic-nodes.ts:73

if (engine.evaluateCondition({ dialect: 'cel', source: cond.expression }, variables)) {

variables is the executor's own second parameter (async execute(node, variables, _context), logic-nodes.ts:46) — literally the same Map object handed in at engine.ts:6647/:6652, and therefore the same object a node condition is judged against at :3874. Same verdict as condition.

Slot kind 2 — screen.fields[].visibleWhen ⇒ SHARED MAP (superset)

refuseInvalidScreenInput (engine.ts:5084, called :4848):

• :5097 — const scope = new Map(Object.entries(run.variables));
• :5098 — for (const [k, v] of Object.entries(bag)) scope.set(k, v);
• :5102 — return this.evaluateCondition(String(field.visibleWhen), scope);

run.variablesis the persisted seedRunVariables map: the suspend path snapshots it at :4007 (Object.fromEntries(variables)) into persistSuspendedRun:4014; the re-suspend path does the same at :4971/:4976, and executeWithoutRetry at :7866/:7873. Resume rebuilds the traversal map from that identical field at :4855.

The submitted bag is overlaid on top, making the scope a superset — so the shadow still reaches it. The overlay carries the screen's own collected values (user input), never the bound record's field, so it can never hand back a field the variable displaced. A superset makes the warning more correct here, not less.

Verdict

Both predicate rows on the ledger evaluate against the run's one flattened variable map. Outcome A.loop.collection and map.collection are flow-template, not predicate, and the slot loop already skips them before this pass — so they are correctly untouched.

2. The change

packages/lint/src/validate-expressions.ts — the descriptor-slot loop (:1137-1143 on base). The location label is hoisted into one slotWhere const (it was already built inline for checkDeclaredPredicate) and onewarnShadowedFieldReads(slotWhere, found.value) call is added inside the existing role === 'predicate' branch, reusing the declaredVariables set collected once per flow at :1093. The comment records the measurement above so the next reader does not have to re-derive it.

Within option C's letter, as the ruling requires: warning-only, same severity, no new rule id, no accept set moved, and no bare identifier judged for being bare. Nothing that linted clean before can newly fail a build.

3. Tests

packages/lint/src/validate-expressions.test.ts — one positive and one negative per predicate slot kind, plus a severity assertion, nested inside the existing flattened-scope shadowing (#14089) block and reusing its shadowFields / record_change fixtures:

• screen visibleWhen reading a shadowed bare name ⇒ exactly one warning naming screen field visibleWhen at config.fields[0].visibleWhen
• screen visibleWhen whose bare name is a field only ⇒ zero issues (the canon-taught form)
• decision branch expression reading a shadowed bare name ⇒ exactly one warning naming decision branch expression at config.conditions[0].expression
• decision expression whose bare name is a variable only ⇒ zero issues
• both slots together ⇒ 2 issues, none above warning (a toHaveLength(1) would still pass if the issue were an error, so severity is asserted separately)

Reverse verification. Predicted direction: RED. The subject under test is imported relatively (from './validate-expressions.js'), so it resolves to package source, not dist — no rebuild leg applies. From the committed state, the single call-site line was deleted and the mutation confirmed on disk before measuring (marker count 1 before, 0 after; git diff --stat showed 1 deletion). Result: 3 failed, 2 passed — both positives (expected [] to have a length of 1) and the severity test (expected [] to have a length of 2). The two negative controls stayed green, which is correct: they assert zero warnings and so cannot detect the call site — they are controls, not detectors. The restore leg was then proven by byte identity, not by an exit code: worktree blob 47a90b260358d4c0ffdf8d4ca8adfe15e686844b equals the HEAD blob, git diff HEAD empty, marker count back to 1.

4. Verification

Union run on the final merged commit b3fbd92bc (after git merge origin/main).

• pnpm --filter @objectstack/lint test — 93 files, 2822 passed
• pnpm --filter @objectstack/lint typecheck — clean. tsconfig.json excludes *.test.ts, so the check:test-typecheck half is what covers the new tests; tsc -p tsconfig.test.json --listFiles confirms both edited files are in that program (the "green over source nothing read" trap), and the 6 residual errors are the ledgered TS6059 in two other files, none of them mine.
• pnpm lint — whole repo, eslint . --no-inline-config, exit 0. Not narrowed, so no narrowing argument is owed.
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — the script derives its own change set from the merge base): 34 families, identical before and after the merge. Harvested with --commands, not from the prose. Result: 33 exit 0, 1 NOT MEASURED — check-test-completeness.mjs, which grades a CI-produced turbo run test log and prints PREREQUISITE NOT MET with exit 3 locally, its own documented NOT MEASURED branch. node scripts/pm/dispatch-gates.mjs --ran reconciles: 34 derived, 34 run, 0 UNRUN.
• The build-dependent ratchets were re-run on the merged head against a rebuilt workspace (turbo run build, 70/70): check:type-check-debt (--re-measure: OK, none above its recorded number) and check:dual-build-cjs-loads both exit 0, as did the build-free ratchets.

Exit codes were captured by redirecting first and reading $? before any pipe, and each verdict above is the gate's own printed judgement line rather than a bare $?.

5. Changeset

.changeset/lint-shadow-warning-descriptor-predicate-slots.md — @objectstack/lint: patch.

Draft, per the dispatch order: not marked ready, auto-merge not enabled.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 1 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 84c605e5de514dcae6217d69c81ef4f8776e4371 — the merge of head b3fbd92bc3db882601a32037d05bdb3b2695fc6e into base 7286dd58e806ed321cbdfc23a1c455db8f80b1ad, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 84c605e5de514dcae6217d69c81ef4f8776e4371 && git checkout 84c605e5de514dcae6217d69c81ef4f8776e4371
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7286dd58e806ed321cbdfc23a1c455db8f80b1ad b3fbd92bc3db882601a32037d05bdb3b2695fc6e && git checkout -B drift-repro 7286dd58e806ed321cbdfc23a1c455db8f80b1ad && git merge --no-ff b3fbd92bc3db882601a32037d05bdb3b2695fc6e
node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14288

This card was measure-first: the ruling made "narrower per-node scope ⇒ close as not-a-gap, no PR" a complete deliverable, so the scope question was answered on the engine before any lint file was touched. The measurement says shared map, for both predicate slot kinds — so the fix applies, and it is one call site.

1. The measurement (engine, read-only)

All citations against packages/services/service-automation/src/engine.ts at base fed4fa409.

The shadowing mechanism is unchanged

seedRunVariables (engine.ts:7673-7692) seeds the flow's declared variables first and flattens the record's fields only where nothing is bound yet:

• :7679 — const variables = this.seedDeclaredVariables(flow, context);
• :7684 — for (const [k, v] of Object.entries(context.record)) { if (!variables.has(k)) variables.set(k, v); }

So a name bound as BOTH a declared variable and a field on the bound object resolves to the variable, silently. That is the #14089 diagnostic's whole subject.

The single map threads to every node executor — no clone, no narrowing

• :3835 — const variables = this.seedRunVariables(flow, flowName, context, runId);
• :3937 — await this.executeNode(startNode, flow, variables, runContext, steps);
• :6578-6583 — executeNode(node, flow, variables: Map, context, steps)
• :6647 / :6652 — executor.execute(node, variables, context)

The two positions PR #14263 already covers ride that same map: node conditions at :3874 and edge conditions at :6955. A grep for new Map(variables / new Map(...variables / scopeFor / narrowScope over engine.ts returns zero hits — the only const scope = new Map in the file is :5097, and it is a superset (below).

Slot kind 1 — decision.conditions[].expression ⇒ SHARED MAP

packages/services/service-automation/src/builtin/logic-nodes.ts:73

if (engine.evaluateCondition({ dialect: 'cel', source: cond.expression }, variables)) {

variables is the executor's own second parameter (async execute(node, variables, _context), logic-nodes.ts:46) — literally the same Map object handed in at engine.ts:6647/:6652, and therefore the same object a node condition is judged against at :3874. Same verdict as condition.

Slot kind 2 — screen.fields[].visibleWhen ⇒ SHARED MAP (superset)

refuseInvalidScreenInput (engine.ts:5084, called :4848):

• :5097 — const scope = new Map(Object.entries(run.variables));
• :5098 — for (const [k, v] of Object.entries(bag)) scope.set(k, v);
• :5102 — return this.evaluateCondition(String(field.visibleWhen), scope);

run.variablesis the persisted seedRunVariables map: the suspend path snapshots it at :4007 (Object.fromEntries(variables)) into persistSuspendedRun:4014; the re-suspend path does the same at :4971/:4976, and executeWithoutRetry at :7866/:7873. Resume rebuilds the traversal map from that identical field at :4855.

The submitted bag is overlaid on top, making the scope a superset — so the shadow still reaches it. The overlay carries the screen's own collected values (user input), never the bound record's field, so it can never hand back a field the variable displaced. A superset makes the warning more correct here, not less.

Verdict

Both predicate rows on the ledger evaluate against the run's one flattened variable map. Outcome A.loop.collection and map.collection are flow-template, not predicate, and the slot loop already skips them before this pass — so they are correctly untouched.

2. The change

packages/lint/src/validate-expressions.ts — the descriptor-slot loop (:1137-1143 on base). The location label is hoisted into one slotWhere const (it was already built inline for checkDeclaredPredicate) and onewarnShadowedFieldReads(slotWhere, found.value) call is added inside the existing role === 'predicate' branch, reusing the declaredVariables set collected once per flow at :1093. The comment records the measurement above so the next reader does not have to re-derive it.

Within option C's letter, as the ruling requires: warning-only, same severity, no new rule id, no accept set moved, and no bare identifier judged for being bare. Nothing that linted clean before can newly fail a build.

3. Tests

packages/lint/src/validate-expressions.test.ts — one positive and one negative per predicate slot kind, plus a severity assertion, nested inside the existing flattened-scope shadowing (#14089) block and reusing its shadowFields / record_change fixtures:

• screen visibleWhen reading a shadowed bare name ⇒ exactly one warning naming screen field visibleWhen at config.fields[0].visibleWhen
• screen visibleWhen whose bare name is a field only ⇒ zero issues (the canon-taught form)
• decision branch expression reading a shadowed bare name ⇒ exactly one warning naming decision branch expression at config.conditions[0].expression
• decision expression whose bare name is a variable only ⇒ zero issues
• both slots together ⇒ 2 issues, none above warning (a toHaveLength(1) would still pass if the issue were an error, so severity is asserted separately)

Reverse verification. Predicted direction: RED. The subject under test is imported relatively (from './validate-expressions.js'), so it resolves to package source, not dist — no rebuild leg applies. From the committed state, the single call-site line was deleted and the mutation confirmed on disk before measuring (marker count 1 before, 0 after; git diff --stat showed 1 deletion). Result: 3 failed, 2 passed — both positives (expected [] to have a length of 1) and the severity test (expected [] to have a length of 2). The two negative controls stayed green, which is correct: they assert zero warnings and so cannot detect the call site — they are controls, not detectors. The restore leg was then proven by byte identity, not by an exit code: worktree blob 47a90b260358d4c0ffdf8d4ca8adfe15e686844b equals the HEAD blob, git diff HEAD empty, marker count back to 1.

4. Verification

Union run on the final merged commit b3fbd92bc (after git merge origin/main).

• pnpm --filter @objectstack/lint test — 93 files, 2822 passed
• pnpm --filter @objectstack/lint typecheck — clean. tsconfig.json excludes *.test.ts, so the check:test-typecheck half is what covers the new tests; tsc -p tsconfig.test.json --listFiles confirms both edited files are in that program (the "green over source nothing read" trap), and the 6 residual errors are the ledgered TS6059 in two other files, none of them mine.
• pnpm lint — whole repo, eslint . --no-inline-config, exit 0. Not narrowed, so no narrowing argument is owed.
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — the script derives its own change set from the merge base): 34 families, identical before and after the merge. Harvested with --commands, not from the prose. Result: 33 exit 0, 1 NOT MEASURED — check-test-completeness.mjs, which grades a CI-produced turbo run test log and prints PREREQUISITE NOT MET with exit 3 locally, its own documented NOT MEASURED branch. node scripts/pm/dispatch-gates.mjs --ran reconciles: 34 derived, 34 run, 0 UNRUN.
• The build-dependent ratchets were re-run on the merged head against a rebuilt workspace (turbo run build, 70/70): check:type-check-debt (--re-measure: OK, none above its recorded number) and check:dual-build-cjs-loads both exit 0, as did the build-free ratchets.

Exit codes were captured by redirecting first and reading $? before any pipe, and each verdict above is the gate's own printed judgement line rather than a bare $?.

5. Changeset

.changeset/lint-shadow-warning-descriptor-predicate-slots.md — @objectstack/lint: patch.

Draft, per the dispatch order: not marked ready, auto-merge not enabled.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 1 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 84c605e5de514dcae6217d69c81ef4f8776e4371 — the merge of head b3fbd92bc3db882601a32037d05bdb3b2695fc6e into base 7286dd58e806ed321cbdfc23a1c455db8f80b1ad, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 84c605e5de514dcae6217d69c81ef4f8776e4371 && git checkout 84c605e5de514dcae6217d69c81ef4f8776e4371
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7286dd58e806ed321cbdfc23a1c455db8f80b1ad b3fbd92bc3db882601a32037d05bdb3b2695fc6e && git checkout -B drift-repro 7286dd58e806ed321cbdfc23a1c455db8f80b1ad && git merge --no-ff b3fbd92bc3db882601a32037d05bdb3b2695fc6e
node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14288

This card was measure-first: the ruling made "narrower per-node scope ⇒ close as not-a-gap, no PR" a complete deliverable, so the scope question was answered on the engine before any lint file was touched. The measurement says shared map, for both predicate slot kinds — so the fix applies, and it is one call site.

1. The measurement (engine, read-only)

All citations against packages/services/service-automation/src/engine.ts at base fed4fa409.

The shadowing mechanism is unchanged

seedRunVariables (engine.ts:7673-7692) seeds the flow's declared variables first and flattens the record's fields only where nothing is bound yet:

• :7679 — const variables = this.seedDeclaredVariables(flow, context);
• :7684 — for (const [k, v] of Object.entries(context.record)) { if (!variables.has(k)) variables.set(k, v); }

So a name bound as BOTH a declared variable and a field on the bound object resolves to the variable, silently. That is the #14089 diagnostic's whole subject.

The single map threads to every node executor — no clone, no narrowing

• :3835 — const variables = this.seedRunVariables(flow, flowName, context, runId);
• :3937 — await this.executeNode(startNode, flow, variables, runContext, steps);
• :6578-6583 — executeNode(node, flow, variables: Map, context, steps)
• :6647 / :6652 — executor.execute(node, variables, context)

The two positions PR #14263 already covers ride that same map: node conditions at :3874 and edge conditions at :6955. A grep for new Map(variables / new Map(...variables / scopeFor / narrowScope over engine.ts returns zero hits — the only const scope = new Map in the file is :5097, and it is a superset (below).

Slot kind 1 — decision.conditions[].expression ⇒ SHARED MAP

packages/services/service-automation/src/builtin/logic-nodes.ts:73

if (engine.evaluateCondition({ dialect: 'cel', source: cond.expression }, variables)) {

variables is the executor's own second parameter (async execute(node, variables, _context), logic-nodes.ts:46) — literally the same Map object handed in at engine.ts:6647/:6652, and therefore the same object a node condition is judged against at :3874. Same verdict as condition.

Slot kind 2 — screen.fields[].visibleWhen ⇒ SHARED MAP (superset)

refuseInvalidScreenInput (engine.ts:5084, called :4848):

• :5097 — const scope = new Map(Object.entries(run.variables));
• :5098 — for (const [k, v] of Object.entries(bag)) scope.set(k, v);
• :5102 — return this.evaluateCondition(String(field.visibleWhen), scope);

run.variablesis the persisted seedRunVariables map: the suspend path snapshots it at :4007 (Object.fromEntries(variables)) into persistSuspendedRun:4014; the re-suspend path does the same at :4971/:4976, and executeWithoutRetry at :7866/:7873. Resume rebuilds the traversal map from that identical field at :4855.

The submitted bag is overlaid on top, making the scope a superset — so the shadow still reaches it. The overlay carries the screen's own collected values (user input), never the bound record's field, so it can never hand back a field the variable displaced. A superset makes the warning more correct here, not less.

Verdict

Both predicate rows on the ledger evaluate against the run's one flattened variable map. Outcome A.loop.collection and map.collection are flow-template, not predicate, and the slot loop already skips them before this pass — so they are correctly untouched.

2. The change

packages/lint/src/validate-expressions.ts — the descriptor-slot loop (:1137-1143 on base). The location label is hoisted into one slotWhere const (it was already built inline for checkDeclaredPredicate) and onewarnShadowedFieldReads(slotWhere, found.value) call is added inside the existing role === 'predicate' branch, reusing the declaredVariables set collected once per flow at :1093. The comment records the measurement above so the next reader does not have to re-derive it.

Within option C's letter, as the ruling requires: warning-only, same severity, no new rule id, no accept set moved, and no bare identifier judged for being bare. Nothing that linted clean before can newly fail a build.

3. Tests

packages/lint/src/validate-expressions.test.ts — one positive and one negative per predicate slot kind, plus a severity assertion, nested inside the existing flattened-scope shadowing (#14089) block and reusing its shadowFields / record_change fixtures:

• screen visibleWhen reading a shadowed bare name ⇒ exactly one warning naming screen field visibleWhen at config.fields[0].visibleWhen
• screen visibleWhen whose bare name is a field only ⇒ zero issues (the canon-taught form)
• decision branch expression reading a shadowed bare name ⇒ exactly one warning naming decision branch expression at config.conditions[0].expression
• decision expression whose bare name is a variable only ⇒ zero issues
• both slots together ⇒ 2 issues, none above warning (a toHaveLength(1) would still pass if the issue were an error, so severity is asserted separately)

Reverse verification. Predicted direction: RED. The subject under test is imported relatively (from './validate-expressions.js'), so it resolves to package source, not dist — no rebuild leg applies. From the committed state, the single call-site line was deleted and the mutation confirmed on disk before measuring (marker count 1 before, 0 after; git diff --stat showed 1 deletion). Result: 3 failed, 2 passed — both positives (expected [] to have a length of 1) and the severity test (expected [] to have a length of 2). The two negative controls stayed green, which is correct: they assert zero warnings and so cannot detect the call site — they are controls, not detectors. The restore leg was then proven by byte identity, not by an exit code: worktree blob 47a90b260358d4c0ffdf8d4ca8adfe15e686844b equals the HEAD blob, git diff HEAD empty, marker count back to 1.

4. Verification

Union run on the final merged commit b3fbd92bc (after git merge origin/main).

• pnpm --filter @objectstack/lint test — 93 files, 2822 passed
• pnpm --filter @objectstack/lint typecheck — clean. tsconfig.json excludes *.test.ts, so the check:test-typecheck half is what covers the new tests; tsc -p tsconfig.test.json --listFiles confirms both edited files are in that program (the "green over source nothing read" trap), and the 6 residual errors are the ledgered TS6059 in two other files, none of them mine.
• pnpm lint — whole repo, eslint . --no-inline-config, exit 0. Not narrowed, so no narrowing argument is owed.
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — the script derives its own change set from the merge base): 34 families, identical before and after the merge. Harvested with --commands, not from the prose. Result: 33 exit 0, 1 NOT MEASURED — check-test-completeness.mjs, which grades a CI-produced turbo run test log and prints PREREQUISITE NOT MET with exit 3 locally, its own documented NOT MEASURED branch. node scripts/pm/dispatch-gates.mjs --ran reconciles: 34 derived, 34 run, 0 UNRUN.
• The build-dependent ratchets were re-run on the merged head against a rebuilt workspace (turbo run build, 70/70): check:type-check-debt (--re-measure: OK, none above its recorded number) and check:dual-build-cjs-loads both exit 0, as did the build-free ratchets.

Exit codes were captured by redirecting first and reading $? before any pipe, and each verdict above is the gate's own printed judgement line rather than a bare $?.

5. Changeset

.changeset/lint-shadow-warning-descriptor-predicate-slots.md — @objectstack/lint: patch.

Draft, per the dispatch order: not marked ready, auto-merge not enabled.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 1 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 84c605e5de514dcae6217d69c81ef4f8776e4371 — the merge of head b3fbd92bc3db882601a32037d05bdb3b2695fc6e into base 7286dd58e806ed321cbdfc23a1c455db8f80b1ad, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 84c605e5de514dcae6217d69c81ef4f8776e4371 && git checkout 84c605e5de514dcae6217d69c81ef4f8776e4371
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7286dd58e806ed321cbdfc23a1c455db8f80b1ad b3fbd92bc3db882601a32037d05bdb3b2695fc6e && git checkout -B drift-repro 7286dd58e806ed321cbdfc23a1c455db8f80b1ad && git merge --no-ff b3fbd92bc3db882601a32037d05bdb3b2695fc6e
node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14288

This card was measure-first: the ruling made "narrower per-node scope ⇒ close as not-a-gap, no PR" a complete deliverable, so the scope question was answered on the engine before any lint file was touched. The measurement says shared map, for both predicate slot kinds — so the fix applies, and it is one call site.

1. The measurement (engine, read-only)

All citations against packages/services/service-automation/src/engine.ts at base fed4fa409.

The shadowing mechanism is unchanged

seedRunVariables (engine.ts:7673-7692) seeds the flow's declared variables first and flattens the record's fields only where nothing is bound yet:

• :7679 — const variables = this.seedDeclaredVariables(flow, context);
• :7684 — for (const [k, v] of Object.entries(context.record)) { if (!variables.has(k)) variables.set(k, v); }

So a name bound as BOTH a declared variable and a field on the bound object resolves to the variable, silently. That is the #14089 diagnostic's whole subject.

The single map threads to every node executor — no clone, no narrowing

• :3835 — const variables = this.seedRunVariables(flow, flowName, context, runId);
• :3937 — await this.executeNode(startNode, flow, variables, runContext, steps);
• :6578-6583 — executeNode(node, flow, variables: Map, context, steps)
• :6647 / :6652 — executor.execute(node, variables, context)

The two positions PR #14263 already covers ride that same map: node conditions at :3874 and edge conditions at :6955. A grep for new Map(variables / new Map(...variables / scopeFor / narrowScope over engine.ts returns zero hits — the only const scope = new Map in the file is :5097, and it is a superset (below).

Slot kind 1 — decision.conditions[].expression ⇒ SHARED MAP

packages/services/service-automation/src/builtin/logic-nodes.ts:73

if (engine.evaluateCondition({ dialect: 'cel', source: cond.expression }, variables)) {

variables is the executor's own second parameter (async execute(node, variables, _context), logic-nodes.ts:46) — literally the same Map object handed in at engine.ts:6647/:6652, and therefore the same object a node condition is judged against at :3874. Same verdict as condition.

Slot kind 2 — screen.fields[].visibleWhen ⇒ SHARED MAP (superset)

refuseInvalidScreenInput (engine.ts:5084, called :4848):

• :5097 — const scope = new Map(Object.entries(run.variables));
• :5098 — for (const [k, v] of Object.entries(bag)) scope.set(k, v);
• :5102 — return this.evaluateCondition(String(field.visibleWhen), scope);

run.variablesis the persisted seedRunVariables map: the suspend path snapshots it at :4007 (Object.fromEntries(variables)) into persistSuspendedRun:4014; the re-suspend path does the same at :4971/:4976, and executeWithoutRetry at :7866/:7873. Resume rebuilds the traversal map from that identical field at :4855.

The submitted bag is overlaid on top, making the scope a superset — so the shadow still reaches it. The overlay carries the screen's own collected values (user input), never the bound record's field, so it can never hand back a field the variable displaced. A superset makes the warning more correct here, not less.

Verdict

Both predicate rows on the ledger evaluate against the run's one flattened variable map. Outcome A.loop.collection and map.collection are flow-template, not predicate, and the slot loop already skips them before this pass — so they are correctly untouched.

2. The change

packages/lint/src/validate-expressions.ts — the descriptor-slot loop (:1137-1143 on base). The location label is hoisted into one slotWhere const (it was already built inline for checkDeclaredPredicate) and onewarnShadowedFieldReads(slotWhere, found.value) call is added inside the existing role === 'predicate' branch, reusing the declaredVariables set collected once per flow at :1093. The comment records the measurement above so the next reader does not have to re-derive it.

Within option C's letter, as the ruling requires: warning-only, same severity, no new rule id, no accept set moved, and no bare identifier judged for being bare. Nothing that linted clean before can newly fail a build.

3. Tests

packages/lint/src/validate-expressions.test.ts — one positive and one negative per predicate slot kind, plus a severity assertion, nested inside the existing flattened-scope shadowing (#14089) block and reusing its shadowFields / record_change fixtures:

• screen visibleWhen reading a shadowed bare name ⇒ exactly one warning naming screen field visibleWhen at config.fields[0].visibleWhen
• screen visibleWhen whose bare name is a field only ⇒ zero issues (the canon-taught form)
• decision branch expression reading a shadowed bare name ⇒ exactly one warning naming decision branch expression at config.conditions[0].expression
• decision expression whose bare name is a variable only ⇒ zero issues
• both slots together ⇒ 2 issues, none above warning (a toHaveLength(1) would still pass if the issue were an error, so severity is asserted separately)

Reverse verification. Predicted direction: RED. The subject under test is imported relatively (from './validate-expressions.js'), so it resolves to package source, not dist — no rebuild leg applies. From the committed state, the single call-site line was deleted and the mutation confirmed on disk before measuring (marker count 1 before, 0 after; git diff --stat showed 1 deletion). Result: 3 failed, 2 passed — both positives (expected [] to have a length of 1) and the severity test (expected [] to have a length of 2). The two negative controls stayed green, which is correct: they assert zero warnings and so cannot detect the call site — they are controls, not detectors. The restore leg was then proven by byte identity, not by an exit code: worktree blob 47a90b260358d4c0ffdf8d4ca8adfe15e686844b equals the HEAD blob, git diff HEAD empty, marker count back to 1.

4. Verification

Union run on the final merged commit b3fbd92bc (after git merge origin/main).

• pnpm --filter @objectstack/lint test — 93 files, 2822 passed
• pnpm --filter @objectstack/lint typecheck — clean. tsconfig.json excludes *.test.ts, so the check:test-typecheck half is what covers the new tests; tsc -p tsconfig.test.json --listFiles confirms both edited files are in that program (the "green over source nothing read" trap), and the 6 residual errors are the ledgered TS6059 in two other files, none of them mine.
• pnpm lint — whole repo, eslint . --no-inline-config, exit 0. Not narrowed, so no narrowing argument is owed.
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — the script derives its own change set from the merge base): 34 families, identical before and after the merge. Harvested with --commands, not from the prose. Result: 33 exit 0, 1 NOT MEASURED — check-test-completeness.mjs, which grades a CI-produced turbo run test log and prints PREREQUISITE NOT MET with exit 3 locally, its own documented NOT MEASURED branch. node scripts/pm/dispatch-gates.mjs --ran reconciles: 34 derived, 34 run, 0 UNRUN.
• The build-dependent ratchets were re-run on the merged head against a rebuilt workspace (turbo run build, 70/70): check:type-check-debt (--re-measure: OK, none above its recorded number) and check:dual-build-cjs-loads both exit 0, as did the build-free ratchets.

Exit codes were captured by redirecting first and reading $? before any pipe, and each verdict above is the gate's own printed judgement line rather than a bare $?.

5. Changeset

.changeset/lint-shadow-warning-descriptor-predicate-slots.md — @objectstack/lint: patch.

Draft, per the dispatch order: not marked ready, auto-merge not enabled.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 1 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 84c605e5de514dcae6217d69c81ef4f8776e4371 — the merge of head b3fbd92bc3db882601a32037d05bdb3b2695fc6e into base 7286dd58e806ed321cbdfc23a1c455db8f80b1ad, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 84c605e5de514dcae6217d69c81ef4f8776e4371 && git checkout 84c605e5de514dcae6217d69c81ef4f8776e4371
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7286dd58e806ed321cbdfc23a1c455db8f80b1ad b3fbd92bc3db882601a32037d05bdb3b2695fc6e && git checkout -B drift-repro 7286dd58e806ed321cbdfc23a1c455db8f80b1ad && git merge --no-ff b3fbd92bc3db882601a32037d05bdb3b2695fc6e
node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14288

This card was measure-first: the ruling made "narrower per-node scope ⇒ close as not-a-gap, no PR" a complete deliverable, so the scope question was answered on the engine before any lint file was touched. The measurement says shared map, for both predicate slot kinds — so the fix applies, and it is one call site.

1. The measurement (engine, read-only)

All citations against packages/services/service-automation/src/engine.ts at base fed4fa409.

The shadowing mechanism is unchanged

seedRunVariables (engine.ts:7673-7692) seeds the flow's declared variables first and flattens the record's fields only where nothing is bound yet:

• :7679 — const variables = this.seedDeclaredVariables(flow, context);
• :7684 — for (const [k, v] of Object.entries(context.record)) { if (!variables.has(k)) variables.set(k, v); }

So a name bound as BOTH a declared variable and a field on the bound object resolves to the variable, silently. That is the #14089 diagnostic's whole subject.

The single map threads to every node executor — no clone, no narrowing

• :3835 — const variables = this.seedRunVariables(flow, flowName, context, runId);
• :3937 — await this.executeNode(startNode, flow, variables, runContext, steps);
• :6578-6583 — executeNode(node, flow, variables: Map, context, steps)
• :6647 / :6652 — executor.execute(node, variables, context)

The two positions PR #14263 already covers ride that same map: node conditions at :3874 and edge conditions at :6955. A grep for new Map(variables / new Map(...variables / scopeFor / narrowScope over engine.ts returns zero hits — the only const scope = new Map in the file is :5097, and it is a superset (below).

Slot kind 1 — decision.conditions[].expression ⇒ SHARED MAP

packages/services/service-automation/src/builtin/logic-nodes.ts:73

if (engine.evaluateCondition({ dialect: 'cel', source: cond.expression }, variables)) {

variables is the executor's own second parameter (async execute(node, variables, _context), logic-nodes.ts:46) — literally the same Map object handed in at engine.ts:6647/:6652, and therefore the same object a node condition is judged against at :3874. Same verdict as condition.

Slot kind 2 — screen.fields[].visibleWhen ⇒ SHARED MAP (superset)

refuseInvalidScreenInput (engine.ts:5084, called :4848):

• :5097 — const scope = new Map(Object.entries(run.variables));
• :5098 — for (const [k, v] of Object.entries(bag)) scope.set(k, v);
• :5102 — return this.evaluateCondition(String(field.visibleWhen), scope);

run.variablesis the persisted seedRunVariables map: the suspend path snapshots it at :4007 (Object.fromEntries(variables)) into persistSuspendedRun:4014; the re-suspend path does the same at :4971/:4976, and executeWithoutRetry at :7866/:7873. Resume rebuilds the traversal map from that identical field at :4855.

The submitted bag is overlaid on top, making the scope a superset — so the shadow still reaches it. The overlay carries the screen's own collected values (user input), never the bound record's field, so it can never hand back a field the variable displaced. A superset makes the warning more correct here, not less.

Verdict

Both predicate rows on the ledger evaluate against the run's one flattened variable map. Outcome A.loop.collection and map.collection are flow-template, not predicate, and the slot loop already skips them before this pass — so they are correctly untouched.

2. The change

packages/lint/src/validate-expressions.ts — the descriptor-slot loop (:1137-1143 on base). The location label is hoisted into one slotWhere const (it was already built inline for checkDeclaredPredicate) and onewarnShadowedFieldReads(slotWhere, found.value) call is added inside the existing role === 'predicate' branch, reusing the declaredVariables set collected once per flow at :1093. The comment records the measurement above so the next reader does not have to re-derive it.

Within option C's letter, as the ruling requires: warning-only, same severity, no new rule id, no accept set moved, and no bare identifier judged for being bare. Nothing that linted clean before can newly fail a build.

3. Tests

packages/lint/src/validate-expressions.test.ts — one positive and one negative per predicate slot kind, plus a severity assertion, nested inside the existing flattened-scope shadowing (#14089) block and reusing its shadowFields / record_change fixtures:

• screen visibleWhen reading a shadowed bare name ⇒ exactly one warning naming screen field visibleWhen at config.fields[0].visibleWhen
• screen visibleWhen whose bare name is a field only ⇒ zero issues (the canon-taught form)
• decision branch expression reading a shadowed bare name ⇒ exactly one warning naming decision branch expression at config.conditions[0].expression
• decision expression whose bare name is a variable only ⇒ zero issues
• both slots together ⇒ 2 issues, none above warning (a toHaveLength(1) would still pass if the issue were an error, so severity is asserted separately)

Reverse verification. Predicted direction: RED. The subject under test is imported relatively (from './validate-expressions.js'), so it resolves to package source, not dist — no rebuild leg applies. From the committed state, the single call-site line was deleted and the mutation confirmed on disk before measuring (marker count 1 before, 0 after; git diff --stat showed 1 deletion). Result: 3 failed, 2 passed — both positives (expected [] to have a length of 1) and the severity test (expected [] to have a length of 2). The two negative controls stayed green, which is correct: they assert zero warnings and so cannot detect the call site — they are controls, not detectors. The restore leg was then proven by byte identity, not by an exit code: worktree blob 47a90b260358d4c0ffdf8d4ca8adfe15e686844b equals the HEAD blob, git diff HEAD empty, marker count back to 1.

4. Verification

Union run on the final merged commit b3fbd92bc (after git merge origin/main).

• pnpm --filter @objectstack/lint test — 93 files, 2822 passed
• pnpm --filter @objectstack/lint typecheck — clean. tsconfig.json excludes *.test.ts, so the check:test-typecheck half is what covers the new tests; tsc -p tsconfig.test.json --listFiles confirms both edited files are in that program (the "green over source nothing read" trap), and the 6 residual errors are the ledgered TS6059 in two other files, none of them mine.
• pnpm lint — whole repo, eslint . --no-inline-config, exit 0. Not narrowed, so no narrowing argument is owed.
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — the script derives its own change set from the merge base): 34 families, identical before and after the merge. Harvested with --commands, not from the prose. Result: 33 exit 0, 1 NOT MEASURED — check-test-completeness.mjs, which grades a CI-produced turbo run test log and prints PREREQUISITE NOT MET with exit 3 locally, its own documented NOT MEASURED branch. node scripts/pm/dispatch-gates.mjs --ran reconciles: 34 derived, 34 run, 0 UNRUN.
• The build-dependent ratchets were re-run on the merged head against a rebuilt workspace (turbo run build, 70/70): check:type-check-debt (--re-measure: OK, none above its recorded number) and check:dual-build-cjs-loads both exit 0, as did the build-free ratchets.

Exit codes were captured by redirecting first and reading $? before any pipe, and each verdict above is the gate's own printed judgement line rather than a bare $?.

5. Changeset

.changeset/lint-shadow-warning-descriptor-predicate-slots.md — @objectstack/lint: patch.

Draft, per the dispatch order: not marked ready, auto-merge not enabled.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 1 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 84c605e5de514dcae6217d69c81ef4f8776e4371 — the merge of head b3fbd92bc3db882601a32037d05bdb3b2695fc6e into base 7286dd58e806ed321cbdfc23a1c455db8f80b1ad, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 84c605e5de514dcae6217d69c81ef4f8776e4371 && git checkout 84c605e5de514dcae6217d69c81ef4f8776e4371
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7286dd58e806ed321cbdfc23a1c455db8f80b1ad b3fbd92bc3db882601a32037d05bdb3b2695fc6e && git checkout -B drift-repro 7286dd58e806ed321cbdfc23a1c455db8f80b1ad && git merge --no-ff b3fbd92bc3db882601a32037d05bdb3b2695fc6e
node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Fixes#14288

This card was measure-first: the ruling made "narrower per-node scope ⇒ close as not-a-gap, no PR" a complete deliverable, so the scope question was answered on the engine before any lint file was touched. The measurement says shared map, for both predicate slot kinds — so the fix applies, and it is one call site.

1. The measurement (engine, read-only)

All citations against packages/services/service-automation/src/engine.ts at base fed4fa409.

The shadowing mechanism is unchanged

seedRunVariables (engine.ts:7673-7692) seeds the flow's declared variables first and flattens the record's fields only where nothing is bound yet:

• :7679 — const variables = this.seedDeclaredVariables(flow, context);
• :7684 — for (const [k, v] of Object.entries(context.record)) { if (!variables.has(k)) variables.set(k, v); }

So a name bound as BOTH a declared variable and a field on the bound object resolves to the variable, silently. That is the #14089 diagnostic's whole subject.

The single map threads to every node executor — no clone, no narrowing

• :3835 — const variables = this.seedRunVariables(flow, flowName, context, runId);
• :3937 — await this.executeNode(startNode, flow, variables, runContext, steps);
• :6578-6583 — executeNode(node, flow, variables: Map, context, steps)
• :6647 / :6652 — executor.execute(node, variables, context)

The two positions PR #14263 already covers ride that same map: node conditions at :3874 and edge conditions at :6955. A grep for new Map(variables / new Map(...variables / scopeFor / narrowScope over engine.ts returns zero hits — the only const scope = new Map in the file is :5097, and it is a superset (below).

Slot kind 1 — decision.conditions[].expression ⇒ SHARED MAP

packages/services/service-automation/src/builtin/logic-nodes.ts:73

if (engine.evaluateCondition({ dialect: 'cel', source: cond.expression }, variables)) {

variables is the executor's own second parameter (async execute(node, variables, _context), logic-nodes.ts:46) — literally the same Map object handed in at engine.ts:6647/:6652, and therefore the same object a node condition is judged against at :3874. Same verdict as condition.

Slot kind 2 — screen.fields[].visibleWhen ⇒ SHARED MAP (superset)

refuseInvalidScreenInput (engine.ts:5084, called :4848):

• :5097 — const scope = new Map(Object.entries(run.variables));
• :5098 — for (const [k, v] of Object.entries(bag)) scope.set(k, v);
• :5102 — return this.evaluateCondition(String(field.visibleWhen), scope);

run.variablesis the persisted seedRunVariables map: the suspend path snapshots it at :4007 (Object.fromEntries(variables)) into persistSuspendedRun:4014; the re-suspend path does the same at :4971/:4976, and executeWithoutRetry at :7866/:7873. Resume rebuilds the traversal map from that identical field at :4855.

The submitted bag is overlaid on top, making the scope a superset — so the shadow still reaches it. The overlay carries the screen's own collected values (user input), never the bound record's field, so it can never hand back a field the variable displaced. A superset makes the warning more correct here, not less.

Verdict

Both predicate rows on the ledger evaluate against the run's one flattened variable map. Outcome A.loop.collection and map.collection are flow-template, not predicate, and the slot loop already skips them before this pass — so they are correctly untouched.

2. The change

packages/lint/src/validate-expressions.ts — the descriptor-slot loop (:1137-1143 on base). The location label is hoisted into one slotWhere const (it was already built inline for checkDeclaredPredicate) and onewarnShadowedFieldReads(slotWhere, found.value) call is added inside the existing role === 'predicate' branch, reusing the declaredVariables set collected once per flow at :1093. The comment records the measurement above so the next reader does not have to re-derive it.

Within option C's letter, as the ruling requires: warning-only, same severity, no new rule id, no accept set moved, and no bare identifier judged for being bare. Nothing that linted clean before can newly fail a build.

3. Tests

packages/lint/src/validate-expressions.test.ts — one positive and one negative per predicate slot kind, plus a severity assertion, nested inside the existing flattened-scope shadowing (#14089) block and reusing its shadowFields / record_change fixtures:

• screen visibleWhen reading a shadowed bare name ⇒ exactly one warning naming screen field visibleWhen at config.fields[0].visibleWhen
• screen visibleWhen whose bare name is a field only ⇒ zero issues (the canon-taught form)
• decision branch expression reading a shadowed bare name ⇒ exactly one warning naming decision branch expression at config.conditions[0].expression
• decision expression whose bare name is a variable only ⇒ zero issues
• both slots together ⇒ 2 issues, none above warning (a toHaveLength(1) would still pass if the issue were an error, so severity is asserted separately)

Reverse verification. Predicted direction: RED. The subject under test is imported relatively (from './validate-expressions.js'), so it resolves to package source, not dist — no rebuild leg applies. From the committed state, the single call-site line was deleted and the mutation confirmed on disk before measuring (marker count 1 before, 0 after; git diff --stat showed 1 deletion). Result: 3 failed, 2 passed — both positives (expected [] to have a length of 1) and the severity test (expected [] to have a length of 2). The two negative controls stayed green, which is correct: they assert zero warnings and so cannot detect the call site — they are controls, not detectors. The restore leg was then proven by byte identity, not by an exit code: worktree blob 47a90b260358d4c0ffdf8d4ca8adfe15e686844b equals the HEAD blob, git diff HEAD empty, marker count back to 1.

4. Verification

Union run on the final merged commit b3fbd92bc (after git merge origin/main).

• pnpm --filter @objectstack/lint test — 93 files, 2822 passed
• pnpm --filter @objectstack/lint typecheck — clean. tsconfig.json excludes *.test.ts, so the check:test-typecheck half is what covers the new tests; tsc -p tsconfig.test.json --listFiles confirms both edited files are in that program (the "green over source nothing read" trap), and the 6 residual errors are the ledgered TS6059 in two other files, none of them mine.
• pnpm lint — whole repo, eslint . --no-inline-config, exit 0. Not narrowed, so no narrowing argument is owed.
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — the script derives its own change set from the merge base): 34 families, identical before and after the merge. Harvested with --commands, not from the prose. Result: 33 exit 0, 1 NOT MEASURED — check-test-completeness.mjs, which grades a CI-produced turbo run test log and prints PREREQUISITE NOT MET with exit 3 locally, its own documented NOT MEASURED branch. node scripts/pm/dispatch-gates.mjs --ran reconciles: 34 derived, 34 run, 0 UNRUN.
• The build-dependent ratchets were re-run on the merged head against a rebuilt workspace (turbo run build, 70/70): check:type-check-debt (--re-measure: OK, none above its recorded number) and check:dual-build-cjs-loads both exit 0, as did the build-free ratchets.

Exit codes were captured by redirecting first and reading $? before any pipe, and each verdict above is the gate's own printed judgement line rather than a bare $?.

5. Changeset

.changeset/lint-shadow-warning-descriptor-predicate-slots.md — @objectstack/lint: patch.

Draft, per the dispatch order: not marked ready, auto-merge not enabled.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 1 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 84c605e5de514dcae6217d69c81ef4f8776e4371 — the merge of head b3fbd92bc3db882601a32037d05bdb3b2695fc6e into base 7286dd58e806ed321cbdfc23a1c455db8f80b1ad, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 84c605e5de514dcae6217d69c81ef4f8776e4371 && git checkout 84c605e5de514dcae6217d69c81ef4f8776e4371
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7286dd58e806ed321cbdfc23a1c455db8f80b1ad b3fbd92bc3db882601a32037d05bdb3b2695fc6e && git checkout -B drift-repro 7286dd58e806ed321cbdfc23a1c455db8f80b1ad && git merge --no-ff b3fbd92bc3db882601a32037d05bdb3b2695fc6e
node scripts/docs-audit/affected-docs.mjs --json 7286dd58e806ed321cbdfc23a1c455db8f80b1ad

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7286dd58e806ed321cbdfc23a1c455db8f80b1ad → pass the list as
args.docs, on the commit named under Which tree this was computed on.