fix(lint)!: refuse a page variable source naming no component on the page, and a page.NAME read the page does not declare - #28769

📓 Docs Drift Check

18 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️ 1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 96c93b7787545281da05a2579faaf2f6ec1c2d57 && git checkout 96c93b7787545281da05a2579faaf2f6ec1c2d57
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d08b859a7177cf16d6190163f2e42efa2d980d3a f0519ad0f54cbb47b050e43c26f1860b8d00d6b3 && git checkout -B drift-repro d08b859a7177cf16d6190163f2e42efa2d980d3a && git merge --no-ff f0519ad0f54cbb47b050e43c26f1860b8d00d6b3

node scripts/docs-audit/affected-docs.mjs --json d08b859a7177cf16d6190163f2e42efa2d980d3a

domain:server#5 · os-project-manager · session_01FEkQ5oc56xChD6Wrc4cGSt

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f0519ad0f54cbb47b050e43c26f1860b8d00d6b3
Local-runs: none
Scope: packages/lint/src/validate-page-variables.ts, packages/lint/src/validate-visibility-predicates.ts, packages/lint/src/index.ts, packages/lint/src/rule-explanations.ts, packages/lint/src/runtime-gate.page-variable-references.test.ts, packages/lint/src/runtime-gate.page-visibility-predicate-writes.test.ts, packages/lint/src/validate-visibility-predicates.test.ts, packages/metadata-protocol/src/protocol.draft-publish-verdict.test.ts, packages/metadata-protocol/src/protocol.runtime-authoring-gate.test.ts + packages/spec/src/ui/page.zod.ts, packages/spec/src/ui/component.zod.ts, packages/spec/src/ui/action.zod.ts, packages/lint/src/page-walk.ts, packages/lint/src/predicate-rhs-position.ts, packages/lint/src/rule-explanations.test.ts, packages/lint/src/runtime-gate.ts, packages/metadata-protocol/src/protocol-authoring-gate.ts, ui/packages/react/src/hooks/usePageVariables.tsx, ui/packages/react/src/hooks/usePageVariableActionBridge.tsx, ui/packages/react/src/SchemaRenderer.tsx, ui/packages/components/src/renderers/layout/page.tsx, ui/packages/components/src/renderers/basic/record-picker.tsx, ui/packages/components/src/renderers/basic/text-input.tsx, ui/packages/plugin-dashboard/src/DashboardRenderer.tsx, examples/app-showcase/src/ui/pages/page-variables.page.ts, examples/app-showcase/src/ui/pages/contact-form.page.ts. Not reviewed (prose face): .changeset/28725-page-variable-source-and-read.md, read for ② only.

Check-runs on the head: 67 runs, 56 success, 11 skipped, 0 failed, 0 cancelled, 0 pending (read with --paginate; a Check Changeset re-run that was in progress at the first read finished green). Green include Check Changeset, PR-body guards, Governed Surface Queue Guard, Dogfood Regression Gate, Lint · PM dispatch-gates, Lint · ESLint and the other Lint jobs, Type Check (workspace, source, consumer, debt ledger, UI), Test Core 1-8, Test UI 1-16, Build Core, Build and E2E UI, Live E2E UI.

① Derived judgments

1. Page writes: a variables[i].source naming no component id the page holds is refused with page-variable-source-unknown at variables[i].source. RIGHT. The spec declares source as "Component id that writes this variable" (page.zod.ts line 913) and retired the reverse targetVariable keys on the two writers because the binding "is resolved from the page variable whose source names this component's id" (component.zod.ts lines 3271-3337); the console resolves it exactly so, definitions.find on d.source === componentId called with schema.id by record-picker.tsx and text-input.tsx, the only two callers. A source no component carries binds nothing, so the variable keeps its default for the page's life: a declared binding that never resolves, refused where it was written. Component ids come from walkPageComponents, the one shared walk whose slot positions derive from the spec's own list (regions, slots, every properties sub-tree including page:tabs / page:accordion panels), read once per page and only when some entry has a source; a kind: 'react' or 'html' page yields nothing from that walk and is not judged, which is the right stand-down (its components live in the source). Case is compared exactly, as the console compares it.
2. Page writes: a page component visibleWhen reading page.NAME or page.?NAME for a NAME the page's variables does not declare is refused with visibility-page-variable-undeclared at the component, naming the first such read. RIGHT. The spec binds page.VAR to "page state" declared in variables (page.zod.ts lines 770, 884, 1964); the console's buildNodeEvaluationScope writes page: pageVariables after the ambient spread (SchemaRenderer.tsx lines 699-712), so nothing else can supply page; the store is seeded from the declarations alone, mounted only when the page declares variables (page.tsx line 973), and its writers are the two bound elements (declared names only) and a dashboard's filter bar, which mounts its own nested provider for its own declared filters (DashboardRenderer.tsx line 1583) and whose writes reach the page scope only for a name the page defines. No other setVariable caller exists in ui/. So an undeclared member of page is never present; the read faults and the element renders, the fail-open the family's other gating ids refuse. Judged from the AST the has() check already holds (no second parser), on page components only; a comprehension that binds page as its loop variable stands the predicate down, and an index read is not judged, both missed catches rather than false errors. A has(page.nosuch) or page.?nosuch.orValue(...) guard on an undeclared name is refused too, rightly: the name can never exist on that page, so the guard is dead code the author did not mean.
3. Public surface of @objectstack/lint: PAGE_VARIABLE_SOURCE_UNKNOWN and VISIBILITY_PAGE_VARIABLE_UNDECLARED exported; two os explain entries (covers under 60 characters without a period, no issue number in a paragraph). No registry change: both ids live in rules already wired on page writes (validatePageVariables, validateVisibilityPredicates), so rulesRun, the CLI rule count and the content/docs transcripts do not move, and the nav walker is untouched by the two new verdicts. RIGHT.
4. One implementation at every surface: save door, draft _diagnostics and publish through judgeRuntimeAuthoringRules over the same registry, the CLI through runAuthoringRules('validate'); the protocol tests pin the draft read (variables.0.source, regions.0.components.0), the 422 and the active save with the build's message; the lint tests pin door and os validate parity. RIGHT.
5. The fold: checkElement's bounds arm and navOverBudgetFinding are replaced by one overBudgetFinding(refusal, where, path, surface, root) with SyntaxSurface.overBudgetHint(root); navOverBudgetFinding is removed. Wording byte-identical on the tree, judged by reading both sides against origin/main: the message is the same template (overruns ${boundName(...)}, the summary echoed only when the bound is unnamed, then the surface's consequence, which is NEVER_EVALUATES for ELEMENT_SURFACE and the nav clause for NAV_SURFACE); the element hint string with ${root}.f in ['a', 'b', …] and the formula/rollup clause is character-for-character the old arm's with the same CANONICAL_ROOT_BY_LAYER[layer] root; the nav hint is the 130-character fix(lint)!: refuse an app nav visible over the CEL parse budget #28756 line unchanged. The existing pins (the page/view over-budget cases in validate-visibility-predicates.test.ts, the authoring gate: an app navigation visible over the CEL size budget passes save and draft diagnostics, where a page visibleWhen of the same size is refused #28726 nav block with its 200-character line pin) are untouched and green. RIGHT; the nav call passes an unused 'record' root, commented as such.
6. Fixture triage: two clean controls that read page.selectedId / page.selectedProjectId on pages declaring no variables now declare them, and the page door family set gains the new id so the controls also assert its silence. RIGHT: a declaration added, not a predicate respelled.
7. Corpus: the shipped pages carry 3 source bindings and 5 page.NAME predicate reads, all on the two showcase pages and all resolving (read in page-variables.page.ts and contact-form.page.ts); the source: keys on the other showcase pages are page data bindings, not variables. 0 refused. RIGHT.

② Semver level

.changeset/28725-page-variable-source-and-read.md: @objectstack/lint minor, BREAKING banner, Clause-②: no (narrowing), Metadata-protocol: narrowed, Skills-docs: none with its reason (the skills name page.VAR in root tables and teach no source binding), one ADR-0087 marker not-required (no-migration-prescription) with the no-conversion argument and the corpus count. Matches what the diff publishes: two references an author could write are now refused at every door (narrowed), on the one package the diff moves; metadata-protocol changes are tests only. The (narrowing) arm is the BREAKING one by AGENTS.md and the kind takes at least minor; the fold publishes nothing new. The PR body carries the same lines; Check Changeset and the PR-body guards are green. Clause-②: no (narrowing) is right; the claim comment's bare no is the seat's own line (③ item 1).

③ Boundary flags

open_questions: none declared.

Deviations, each answered:

1. Claim line Clause-②: no versus PR body and changeset Clause-②: no (narrowing). Answered: the PR body and changeset are the records the gates read and they are right; the seat amends its claim comment; no PR change.
2. Two metadata-protocol test files added (test only) beyond the claim's packages/lint/src surface. Answered: fix(lint)!: refuse an app nav visible that does not parse, and page variables that are duplicated, unnamed or wrong-typed #28723's and fix(lint)!: refuse an app nav visible over the CEL parse budget #28756's precedent and the only proof of the three doors; no source edit there.
3. The seat-ordered fold reported as not done in the os-dev-report, then done in the PR body's patch round. Answered on the tree: head f0519ad0 carries the fold (① item 5); the report predates the commit.
4. check:type-check-debt first read a lock queue-timeout; re-run exit 0. Answered: Type Check · debt ledger is green on the head.
5. Dogfood battery not re-measured at f0519ad0 (lint-only byte-identical refactor plus a merge). Answered: Dogfood Regression Gate is green on the head.

Out-of-scope observations the dev reported, each a missed catch and escalated for the seat's filing judgment, not this PR:
6. page.NAME reads outside a component visibleWhen are not resolved: props-bag CEL slots (page:tabs item predicates, which bind a different evaluator anyway) and {{page.NAME}} interpolation tokens in action bodies (bodyExtra, action.zod.ts line 1799). Agreed as outside the card's two observed shapes.
7. A source naming a component that exists but cannot write (only element:record_picker and element:text_input bind) still binds nothing. Agreed: the card and ruling ask for existence; a writer-capability check would be a new rule over the component vocabulary.

④ Design judgment

The narrowing, read against the published spec on main and the consumer: the spec says source names the writer component's id and page.VAR is the page's declared state; the console binds both exactly that way and nowhere else. A source with no matching id and a page.NAME with no declaration are references the spec declares as resolvable only against the page itself and that never resolve there, so refusing them at the author makes the spec's own contract real and takes no working capability away. Attempts to break it: a writer nested in a container, a tabs panel or a slot is found by the shared walk (pinned for properties.children); a source-authored page is not judged on source; the console mounts no provider for a page without variables and no outer provider exists in the shell, so a variable-less page reading page.X really has nothing to read (there is no component that embeds one page inside another's scope; the dashboard's nested scope is the dashboard's own and a page component outside it cannot read its filters without declaring the name, which is exactly what the rule asks); has()-guarded declared reads, deeper reads through a declared object variable, variables with no source, and comprehension-bound page are all admitted; two undeclared reads are one finding; the differential at the door stays clean because pages is not a context collection. Hint lines are 172 and 117 characters. The fold is byte-identical by construction, with one builder per id as syntaxFinding already does.

Findings:

• Must-fix: none.
• Should-fix: none. The two observations in ③ items 6 and 7 are the seat's to file or decline; neither is a defect of this change.

Implemented-by: claude/project-thread-1t94a5
Reviewed-by: session_01FEkQ5oc56xChD6Wrc4cGSt

VERDICT: PASS

domain:server#5 · os-project-manager · session_01FEkQ5oc56xChD6Wrc4cGSt

席位核对

ACCEPT · domain:server seat 5 · os-project-manager · session_01FEkQ5oc56xChD6Wrc4cGSt · 2026-11-01T19:28Z · head f0519ad0 · #28725

The maintainer's standing authorisation for landing reviewed PRs, verbatim: 「按照 pm-dispatch 规则复核过的都授权」.

席位意见:与 diff 相符。页面变量的 source 写了页面上不存在的组件，或组件的显示条件读了页面没声明的变量，以前能保存发布但绑定永远不生效；现在保存、草稿诊断、发布和 os validate 都会拒绝并指出位置。现有示例全部通过。

1. Shape: draft against main, Fixes #28725, @objectstack/lint minor changeset with the BREAKING banner, Clause-②: no (narrowing), Metadata-protocol: narrowed, Skills-docs: none with its reason, ADR-0087 marker. check-governed-merges --pr 28769: NOT governed, +534 / -59. git merge-tree against main: clean. Landing tier S.
2. Against the order: ruling 1 → page-variable-source-unknown in validate-page-variables.ts, ids from the shared walkPageComponents; ruling 2 → visibility-page-variable-undeclared judged from the AST in the visibility rule, no second parser; ruling 3 → migration count 0 (3 source bindings, 5 page.NAME reads, all resolving). One implementation at save, draft _diagnostics, publish and os validate.
3. Accepted deviations: two metadata-protocol test files (tests only, as fix(lint)!: refuse an app nav visible that does not parse, and page variables that are duplicated, unnamed or wrong-typed #28723 and fix(lint)!: refuse an app nav visible over the CEL parse budget #28756 did). The seat-ordered fold of the two visibility-predicate-over-budget builders into one overBudgetFinding (fix(lint)!: refuse an app nav visible over the CEL parse budget #28756 review S2), wording byte-identical, judged on the tree by the review. The PR body's fold paragraph was added by the seat through the relay. The claim's Clause-②: no is the claim template's line; the PR body and changeset carry the (narrowing) arm the gates read.
4. Gates: ## Contract review at CONTRACT_REVIEW_TIER on this head: PASS, comment 6562765111, no must-fix, no should-fix. Check-runs on this head: 56 success, 11 skipped, 0 failed. Dev: 59/59 derived families, --ran derived zero.
5. Out of scope: the dev's two observations are missed catches outside the card, so neither is filed and no measured author was hurt ⇒ Acceptance notes: page.NAME inside props-bag slots and {{page.NAME}} action tokens are not judged; a source naming a component that exists but writes no variable is not judged.
6. Landing: pr_ready + automerge_enable through the relay.