docs(lint,objectql): correct the null-guard seam ledger after #6454 — readonlyWhen is TOTAL, excluded by ruling, not by binding

[os-project-manager]

Fixes #6458

Problem

The surface ledger in packages/lint/src/validate-null-guards.ts — the module-header table the next author reads to decide whether a seam joins the null-guard gate (#4811: "a surface excluded without a reason is indistinguishable from one nobody looked at") — still carried this row:

| field `readonlyWhen` | sparse | `stripReadonlyWhenFields` merges {...previous, ...data} and never materializes | excluded |

That row became false the moment PR #6454 merged (2026-08-07 22:14 UTC). #6454's own body says it deliberately did not touch packages/lint (quoted verbatim, per its Chinese original): 「#4811 的 null-guard 闸门扩面按裁决第 3 条要等两处服务端接缝都齐,故本 PR 不触 packages/lint」— so the ledger was knowingly left behind, and this PR is the catch-up. Re-verified on origin/main (64d764e76) before editing: readonlyWhenBindings (rule-validator.ts:474) runs both the record and previous roots through materializeDeclaredFields; the code the evidence column pointed at no longer exists.

What the corrected row says — deliberately not "now materialized"

A one-word swap from sparse to TOTAL would replace one false statement with another, because #6454's measured grid was not uniform — one cell flipped the opposite way:

predicate	before (sparse prior)	after (sparse prior)
record.b == null	fault, change passes	true, change stripped
has(record.b)	false, change passes	true, change stripped
!has(record.b)	true, change stripped	false, change passes

A lock spelled !has(record.b) stopped locking when #6454 landed. The rewritten row therefore records three facts, each traced to code:

1. Binding: TOTAL — readonlyWhenBindings materialises both roots (#4649 的「记录对已声明字段全量」只落在两个接缝上 —— 另外三处求值仍是稀疏绑定 #4953 clause 1, landed in fix(objectql): 字段 readonlyWhen 求值补 materializeDeclaredFields —— 服务端第三个接缝 (#4953) #6454). The totality criterion is now satisfied on this face.
2. Verdict: still excluded — but the reason changed. Not "the binding is sparse, the rule would prescribe the wrong fix" anymore; now it is clause 3 of the maintainer's 2026-08-06 ruling on #4649 的「记录对已声明字段全量」只落在两个接缝上 —— 另外三处求值仍是稀疏绑定 #4953: the gate widens only once BOTH server-side seams are total, and the flow trigger-record half (services lane) is not wired yet. The header now states explicitly that totality is necessary but not sufficient — binding and verdict are two different questions and have come apart on this row.
3. Two facts the future widening must carry into the evidence column (the issue's half 2, recorded now so they are not re-derived): the face is fail-OPEN (isReadonlyWhenLocked logs failed to evaluate — change allowed through; exception: the Parent-scoped readonlyWhen is unenforced server-side — the field lock fails open, so a paid invoice's frozen lines can be rewritten over the API #4889 unbound-root branch resolves LOCKED), so it wants nullGuardMessage's 'fail-open' outcome like requiredWhen; and the !has(record.b) reversal above, pinned by fix(objectql): 字段 readonlyWhen 求值补 materializeDeclaredFields —— 服务端第三个接缝 (#4953) #6454 in rule-validator.test.ts in both spellings.

Neighbouring rows — checked in the same pass, verdicts stated explicitly

• flow / edge condition (stale, fixed): the binding is still sparse (verified: record-change-trigger.ts:309 seeds { ...(inputData ?? {}), ...after }, no materialization), but the row's standing changed with the same ruling: this is #4649 的「记录对已声明字段全量」只落在两个接缝上 —— 另外三处求值仍是稀疏绑定 #4953 clause 1's other half, so the exclusion is now a NOT-YET (services lane outstanding) rather than an open question. When it lands, this row and the readonlyWhen row flip together — exactly clause 3's condition. Also renamed the evidence's inputDoc spelling to inputData (trigger-record-change 的 input.doc 防御性 alias 读的是一个没有生产者的键(引擎只建 input.data) #5671 dropped that alias read; the old name no longer appears in the trigger), here and in the two validate-expressions.ts / .test.ts comments that quoted it.
• action visible / disabled (reason upgraded): still sparse (no materialization exists in objectui on that path — unchanged), but the "requires first deciding whether the binding should be made total" sentence was stale: #4649 的「记录对已声明字段全量」只落在两个接缝上 —— 另外三处求值仍是稀疏绑定 #4953 clause 2 DECIDED it. The face stays sparse by ruling (totalising would mean every REST read padding out all declared columns); authors there guard with has(). The row now cites the decision instead of asking for one.
• object validation rules / lifecycle hook condition / field requiredWhen: checked, still true — rule-validator.ts:1370 (materializeDeclaredFields(merged, fields)), hook-wrappers.ts:886/889/946, and the requiredWhen row's fail-open note all still describe the code on main. Unchanged.
• sharing-rule condition / field expression: checked, still true — SQL compilation and the validate-expressions.ts 的 field-formula 校验读 f.formula —— spec 声明的是 expression,这段从未对任何 spec 合法 stack 跑过 #5026 product-judgement exclusion are untouched by fix(objectql): 字段 readonlyWhen 求值补 materializeDeclaredFields —— 服务端第三个接缝 (#4953) #6454. Unchanged.

The rider the issue named

packages/objectql/src/cel-fault.ts's header said materializeDeclaredFields sits "in front of both evaluators" — three server-side seams since #4953. Corrected in place, with the note that the third seam (fail-open) reads only unknownVariableOf and never this module's rejection sentences (which is why cel-fault itself needed no code change in #6454). Two lines of the same drift, same cause, folded in per the triage comment; it stayed a comment-only edit, so no lane boundary issue arose.

Also updated: the checkNullGuards doc block in validate-expressions.ts, which repeated the sparse-binding claim for readonlyWhen ("its binding is sparse and != null would be the wrong prescription") — now states the real blocker (clause 3) and the 'fail-open' outcome the future wiring needs.

Scope guard

• ⛔ The gate itself is NOT widened: checkNullGuards call sites are unchanged; validate-expressions.ts / .test.ts edits are comment text only. Widening is null-guard 闸门(#4763)只覆盖了校验规则与 hook 条件 —— action / flow 条件两面待定,formula 面待判 #4811 / ruling clause 3 and waits for the services half.
• ⛔ validate-translation-references.ts untouched (claimed in parallel under lint: collectViewRecord 的 listViews/formViews 分支收「map key + 内层 name」两种拼写,而组装器只认 map key —— 冲突改名时两者恰好相反 #6422).
• No behaviour moves anywhere: the diff is doc comments in 3 source files + 1 test-file comment.

Verification honesty

This ledger is a decision input, not a machine-read artifact: no test or gate asserts its text, so no assertion could go red on the stale row — that is exactly why the issue was filed rather than caught by CI. The gates below prove the change breaks nothing; they cannot prove the prose true. The truth claim rests on the file:line evidence cited above, all re-checked on origin/main at 64d764e76.

Note on the Docs Drift Check advisory on this PR: it fired on package paths (any diff under @objectstack/lint / @objectstack/objectql triggers it), not on semantics. This diff carries no behaviour change, so none of the listed hand-written docs can have drifted from it — not actionable here, and it is advisory-only, not a required check.

$ pnpm --filter @objectstack/lint test -- --maxWorkers=2
 Test Files  65 passed (65)
      Tests  1652 passed (1652)

$ pnpm --filter @objectstack/objectql test -- --maxWorkers=2
 Test Files  149 passed (149)
      Tests  2549 passed (2549)

$ pnpm --filter @objectstack/lint typecheck && pnpm --filter @objectstack/objectql typecheck
(tsc --noEmit, both clean, exit 0)

$ node scripts/check-nul-bytes.mjs
check-nul-bytes: OK (scanned 6269 tracked text file(s); no raw ASCII control bytes).
$ grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' (the 4 changed files)
clean — no raw control bytes

$ pnpm --filter @objectstack/lint run check:doc-formula-expressions
✓ 22 record-scoped formula example(s) across 378 files / 1397 TS blocks judged clean

$ pnpm exec eslint (the 4 changed files)
exit 0

Comment-only, releases nothing → no changeset; skip-changeset label applied (read back after the labeler settled: size/m, tests, skip-changeset).

🤖 Generated with Claude Code

https://claude.ai/code/session_01F8q5J1MQyocgtNspb15fSn

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 5:55pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/lint, @objectstack/objectql.

17 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx (via @objectstack/lint)
• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx (via @objectstack/objectql)
• content/docs/deployment/vercel.mdx (via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx (via packages/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/permissions/authorization.mdx (via @objectstack/lint)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql)
• content/docs/protocol/kernel/index.mdx (via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx (via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
• content/docs/releases/implementation-status.mdx (via @objectstack/objectql)
• content/docs/releases/v17.mdx (via @objectstack/lint)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.