fix(lint)!: refuse an app nav visible that does not parse, and page variables that are duplicated, unnamed or wrong-typed - #28723

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 32 documentable anchor(s). ⚠️ 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.

13 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/deployment/validating-metadata.mdx (via AUTHORING_RULES (symbol, a top-level const object), runtimeTypes (symbol, a field of const object AUTHORING_RULES))
• content/docs/frontend/plugins/plugin-detail.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/kernel/contracts/storage-service.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/kernel/runtime-services/audit-service.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/permissions/permission-metadata.mdx (via org_admin (literal, a string literal in example), org_owner (literal, a string literal in a comment in AUTHORING_RULES))
• content/docs/permissions/positions.mdx (via org_admin (literal, a string literal in example), org_owner (literal, a string literal in a comment in AUTHORING_RULES))
• content/docs/permissions/record-view-auditing.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/permissions/sharing-rules.mdx (via org_admin (literal, a string literal in example), org_owner (literal, a string literal in a comment in AUTHORING_RULES))
• content/docs/protocol/kernel/http-protocol.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/protocol/kernel/realtime-protocol.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/ui/audience-based-interfaces.mdx (via org_admin (literal, a string literal in example))
• content/docs/ui/pages.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))

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

• content/docs/releases/v16.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/releases/v17/17-4.mdx (via org_admin (literal, a string literal in example))
• content/docs/releases/v17/17-5.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), org_admin (literal, a string literal in example), org_owner (literal, a string literal in a comment in AUTHORING_RULES), record_id (literal, a string literal in defaultMatches))
• content/docs/releases/v17/17-6.mdx (via record_id (symbol, a field of const object EMPTY_VALUE; a field of const object TYPE_NOUN), record_id (literal, a string literal in defaultMatches))
• content/docs/releases/v18/18-0.mdx (via org_owner (literal, a string literal in a comment in AUTHORING_RULES))

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.

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

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

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 d62d973734d1e0af3f183340a5674f320b7c0858 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

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

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: bb33ace7a2c8a9d1443d088873c8d9b9bbb60889
Local-runs: none
Scope: packages/lint/src/validate-visibility-predicates.ts, packages/lint/src/validate-page-variables.ts, packages/lint/src/authoring-rules.ts, packages/lint/src/index.ts, packages/lint/src/rule-explanations.ts, packages/lint/src/runtime-gate.app-nav-visible-predicate-writes.test.ts, packages/lint/src/runtime-gate.page-variable-writes.test.ts, packages/lint/src/runtime-gate.page-visibility-predicate-writes.test.ts, packages/lint/src/validate-predicate-path-refs.test.ts, packages/lint/src/validate-security-posture.runtime-surface.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/app.zod.ts, packages/spec/src/ui/page.zod.ts, packages/spec/src/shared/expression.zod.ts, packages/spec/src/shared/metadata-collection.zod.ts, packages/spec/src/ui/component.zod.ts, packages/lint/src/runtime-gate.ts, packages/lint/src/collection-entries.ts, packages/lint/src/authoring-rule-wiring.test.ts, packages/lint/src/rule-explanations.test.ts, packages/metadata-protocol/src/protocol-authoring-gate.ts, packages/metadata-protocol/src/runtime-authoring-gate.ts, packages/cli/src/commands/validate.ts, ui/packages/core/src/evaluator/ExpressionEvaluator.ts, ui/packages/app-shell/src/providers/ExpressionProvider.tsx, ui/packages/app-shell/src/hooks/useNavMemberGates.ts, ui/packages/react/src/hooks/usePageVariables.tsx, ui/packages/types/src/zod/app.zod.ts, examples/app-crm/src/apps/crm.app.ts, examples/app-showcase/src/ui/pages/page-variables.page.ts, examples/app-showcase/src/ui/pages/contact-form.page.ts. Not reviewed (prose faces): the changeset and the four content/docs transcripts, read for ② only.

Check-runs on the head at review time: 62 runs, 0 failed, 0 cancelled, 27 still in progress (Test Core 1-8, Test UI 1-16, Build Core, Build Docs, Live E2E UI, the five Type Check jobs, the six Lint jobs still running). Completed green: Check Changeset, PR-body guards, Governed Surface Queue Guard, Spec property liveness, Lint · PM dispatch-gates, Lint · scoped · tooling self-tests, Dogfood Regression Gate, Check PR Size, Check Documentation Links, Flag docs affected by code changes, Build UI Deps, Plan Test Core shards. The pending families are the queue guard's to wait on; nothing in this record re-runs or pre-judges them.

① Derived judgments

1. App writes: a navigation[].visible, areas[].navigation[].visible or any children[].visible that is a bare string or a { dialect: 'cel', source } envelope and does not parse on formula's parseCelToAstWithReason is now refused with visibility-predicate-syntax at the key path. RIGHT. The spec declares the slot as EvaluatedExpressionInputSchema (app.zod.ts line 371), whose string arm is by definition { dialect: 'cel', source } (expression.zod.ts lines 269-274), and the console reads both shapes on the CEL engine (ExpressionEvaluator.ts evaluateCondition, the console: a bare-string CEL predicate (nav visible, page visibleWhen) runs on the legacy evaluator and fails, though the spec defines a bare string as CEL shorthand #27457 branch) and WITHHOLDS the entry on a fault (ExpressionProvider.tsx evaluateNavigationVisibility, throwOnError then withhold). The narrowing makes the spec's own refusal real at the author; nothing the console could ever render is taken away.
2. App writes: a ${...} template bare string on a nav visible is now refused too, since it is not CEL. RIGHT, named as the one console-tolerated shape the door now closes: the console still routes a ${ string to its legacy path, but the spec never declared that reading (bare string = CEL), the page visibleWhen door has refused the same spelling since view/page 可见性谓词的 CEL **语法**在构建期无人校验 —— country === "USA" 这类写法零诊断、运行时静默 fail-open #6253 with the same celRefusal, and the corpus (examples, platform packages, docs, skills) carries no ${ nav visible. Parity, not a new refusal class.
3. App writes: a boolean visible, an envelope of dialect template or cron, and an envelope without a string source are not judged. RIGHT. The spec admits every dialect envelope on this slot; the console evaluates a non-cel envelope on its legacy path; an envelope without source is already the spec parse's refusal (EVALUATED_EXPRESSION_SOURCE_REQUIRED). The rule narrows nothing the spec leaves open.
4. App writes: only the syntax verdict runs on a nav entry; the family's root-binding verdicts (visibility-bare-identifier, visibility-root-mislayered, visibility-predicate-unknown-function, has() shape) do not. RIGHT by measurement: the shell binds current_user, user, ctx.user, os.user, features and data beside a dataSource (ExpressionProvider.tsx line 213; useNavMemberGates.ts navEntryVisible), not record or page, so the page-rooted checks would refuse features.cloudManaged != true and current_user.can('crm_opportunity', 'read'), both of which the console evaluates. The PR's control list pins exactly these.
5. validatePredicatePathRefs declares app beside its sibling and judges nothing on an app write. RIGHT: authoring-rule-wiring.test.ts pins the family on one runtimeTypes set (lines 469-497), and the rule walks stack.views only; the pin in validate-predicate-path-refs.test.ts is updated with the reason.
6. The app door's rulesRun disclosure grows from [validateSecurityRoleWord] to [validateVisibilityPredicates, validatePredicatePathRefs, validateSecurityRoleWord]; the two pins in validate-security-posture.runtime-surface.test.ts are updated. RIGHT, additive on a 422 or 2xx wire detail; no other test at head enumerates the app door's list (grepped).
7. Page writes: page-variable-name-duplicate (located at the later entry, naming the first index), page-variable-name-empty (empty or blank), page-variable-default-type (a present, non-null defaultValue whose JS kind is not the declared type's: string for string and record_id, finite number, boolean, plain object, array; an absent type is judged as string). RIGHT against the spec and the consumer: PageVariableSchema (page.zod.ts lines 895-915) declares type with .default('string') and defaultValue: z.unknown(), so the untyped-number refusal follows the declared default, not the rule's invention; the console's initializeVariables (usePageVariables.tsx lines 40-69) seeds defaultValue as written when present (null included, so admitting null matches what the consumer does), falls to '' for string, record_id and anything else, and keeps the LAST of two same-named declarations. record_id as a string is consistent with the spec's own typing of record ids on UI surfaces (recordId: z.string(), component.zod.ts line 2524). Types outside the enum are the parse's refusal and are left alone. The two showcase pages (5 variables) are admitted by the control set.
8. Public surface of @objectstack/lint: validatePageVariables, the three id constants and PageVariableFinding are exported from index.ts; three os explain entries and a nav paragraph on visibility-predicate-syntax are added. RIGHT; the explanation entries meet the registry's own pins (covers under 60 chars without a period, paragraphs naming no issue number).
9. os validate / os build / os lint rule count 57 to 58 in the four CLI transcripts. RIGHT (the registry derives it; check:docs-transcript-drift is the gate).
10. One implementation at every surface, verified in the live tree: the metadata save door (judgeRuntimeAuthoringRules to evaluateRuntimeAuthoringGate to runRuntimeAuthoringRules, which filters AUTHORING_RULES by runtimeTypes and builds the snapshot with TYPE_TO_STACK_KEY.app = 'apps', page = 'pages'), the draft _diagnostics (draftPublishVerdict calls the same judge with state: 'active'), the publish (assertRuntimeAuthoringRules is the same judge plus the throw) and the CLI (runAuthoringRules('validate') over normalizeStackInput, which coerces map collections to arrays and leaves nav visible and page variables as authored). No gate source in metadata-protocol moves; the protocol tests pin the draft read, the publish 422 and the active save. Nothing stored keeps its stored shape changed: a stored app or page keeps loading; only its next save is judged.

② Semver level

.changeset/28663-nav-visible-syntax-page-variables.md: @objectstack/lint minor, BREAKING banner, Clause-②: no (narrowing), Metadata-protocol: narrowed, Skills-docs: none with its reason, and one ADR-0087 marker not-required (no-migration-prescription) with the no-conversion argument. Matches what the diff publishes: a value the author could write is now refused at every door (narrowed), on the one package the diff moves (metadata-protocol changes are tests only, which publish nothing). The (narrowing) arm is the BREAKING one by AGENTS.md's declaration rule, and the kind takes at least minor. The PR body carries the same two lines. Check Changeset and the PR-body guards are green on the head. Clause-②: no (narrowing) is right, and the claim comment's bare no is the seat's own line to amend (③ 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; check-changeset-no-major.mjs refuses narrowed beside a line without the arm. The seat amends its claim comment; no PR change.
2. File surface widened to four content/docs/** CLI transcripts and four existing lint test pins. Answered: the transcripts are the mechanical rule-count line check:docs-transcript-drift enforces, not teaching prose; the four pins are the app and page doors' rule lists, which any registry change must re-pin. Both inside the ruling's intent; nothing under packages/spec/**, packages/formula/** or ui/** is touched.

Out-of-scope findings the dev reported, each escalated rather than fixed here:
3. A page variable source naming a component the page does not hold is still admitted. The card's item 2 lists it, its Expected line does not, and the ruling names uniqueness, name and default-versus-type only. Escalated: the seat files it (class a, dedupe words given in the report).
4. A visibleWhen reading an undeclared page.X is still admitted. Same disposition; the seat files it.
5. A nav visible that is flawless CEL over the parse budget is still admitted. See ④ S1; the seat files it.
6. The operator-table hint on a nav entry carries a record-rooted example. See ④ S2.

④ Design judgment

The narrowing, read against the published spec on main and the consumer that evaluates it: the spec already says a nav visible is CEL and an evaluated slot must be something the engine runs; the console's navigation gate falls closed on a fault. A predicate that cannot parse therefore never worked for any viewer, and refusing it at the author is the spec's own refusal made real, not a capability withdrawn. The page-variable rule judges a list the spec types entry-by-entry and never judged as a list; each verdict mirrors what usePageVariables does with the declaration (last wins, unreachable name, wrong-kind seed), so no declared variable shape that the console honours is refused. Attempts to break it: every shape the console evaluates on a nav entry (current_user.can(...), features.*, user.isPlatformAdmin == true, the in membership test, the cel envelope, a boolean, a template envelope) is admitted at both doors by the PR's controls and by reading celRefusal (blank source answers null, bounds answers a kind the nav walker drops, only syntax fires); the single nav visible in the shipped corpus (examples/app-crm) and the five showcase variables pass; map-shaped apps collections resolve through collectionEntries with honest paths; a non-record nav entry or a non-array navigation/variables is skipped, never thrown on. The differential at the door is clean because apps and pages are not context collections, so the written item's own findings are the only ones that can appear.

Findings:

• S1 (should-fix, follow-up card): a nav visible that is valid CEL but over DEFAULT_LIMITS is admitted at every door, while the console's engine refuses it at parse under the same limits and the nav gate withholds the entry, which is the card's silent-disappearance shape by another route. celRefusal already returns kind: 'bounds'; walkNavPredicates drops it, so the fix is a second arm with the existing visibility-predicate-over-budget id and the nav consequence clause. Not a must-fix here: the ruling names the syntax judgment alone and the dev reported the gap for filing.
• S2 (should-fix, cosmetic): when a nav entry uses an other-language operator (===), the hint's example comes from the shared operator table and is record-rooted; the SyntaxSurface.example is read only on the no-token branch. The operator correction itself is right; a per-surface example on the token branch would finish the job.
• S3 (should-fix, by filing): the two page-variable faults the card observed and the ruling left out (unknown source component, undeclared page.X read) stay admitted; the seat files them as reported.
• Must-fix: none.

Implemented-by: claude/project-thread-oqpu4s
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-01T15:51Z · head bb33ace7 · #28663

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

席位意见:与 diff 相符。导航 visible 写成解析不了的 CEL 时,保存、草稿诊断、发布和 os validate 都会拒绝并指出位置(以前保存成功,导航项对所有人静默消失);页面变量重名、空名、默认值与类型不符同样在这四处被拒。现有示例全部通过。

1. Shape: draft against main, Fixes #28663, @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 28723: NOT governed, +978 / -28. git merge-tree against main: clean. Landing tier S.
2. Against the order: one syntax verdict on nav visible (bare string and cel envelope) through the existing visibility-predicate-syntax rule; the page-rooted root checks deliberately not run on nav, since the shell binds current_user / features / data there; a new validate-page-variables.ts with three ids. One implementation at save, draft _diagnostics, publish and os validate; no gate source in metadata-protocol moves.
3. Accepted deviations: four content/docs/** CLI transcripts (rule count 57 → 58, the line check:docs-transcript-drift enforces) and four existing lint test pins (the app and page doors' rule lists). 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 6560166888, no must-fix. Check-runs on this head: 57 success, 8 skipped, 0 failed (Test Core 1-8, Test UI 1-16, Type Check, Lint and Check Changeset green).
5. Out of scope: filed authoring gate: a page variable whose source names a component the page does not hold, and a visibleWhen reading an undeclared page variable, both pass save and draft diagnostics #28725 (page-variable source naming no component, visibleWhen reading an undeclared page.X; review S3) and 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 visible over the CEL parse budget; review S1), both pm:blocked on authoring gate: an app navigation visible with a CEL syntax error passes save, draft diagnostics and publish (a page visibleWhen with the same fault is refused), and page variables publish with duplicate, empty or wrong-typed declarations #28663 until this lands. Review S2 (the operator-table hint's record-rooted example on a nav entry) is cosmetic and not filed: the operator correction itself is right ⇒ Acceptance notes.
6. Landing: pr_ready + automerge_enable through the relay.