Guard the authored action predicates for the sparse record face (#8990)

[os-zhuang]

Part of #8990. Backlink: #8975 (the guard rule this migrates to, merged as ccc917cb5 / PR #8997).

An action visible / disabled predicate binds whatever record the client already fetched — a record-detail read, or a LIST ROW carrying only the view's $select projection. That binding stays sparse by decision (#4953 item 2), and CEL aborts the whole expression at key resolution when a key is absent. The abort is fail-closed, so the button is simply not offered — indistinguishable to the user from the gate having said no, and reported nowhere.

This migrates the authored record-scoped action predicates on the platform objects and the CRM example to that rule.

Census, re-measured on the merged ref

The card's figure was 34 authored record-scoped action predicates across both repos, 0 using has(). Re-measured at origin/main @ 3851f87f0:

where	count
objectstack — authored action predicates reading record.*	34
objectui — same, excluding tests / fixtures / doc comments	0

The delta: the 34 is entirely in this repo, not split across two. objectui's 104 record.* predicate hits are test cases, renderer fixtures and doc comments; its four non-test hits are all prose inside comments (containers.tsx, data-table.tsx, action-group.tsx, predicate-record.ts). There is no authored objectui metadata to migrate — the objectui half of this problem is the RENDERER's (how it evaluates and what it does with a fault), which is a different question from this card. 0 of 34 used has() is confirmed unchanged.

Of the 34, this PR migrates 22 and leaves 12 — all in app-showcase, all deliberately out of the dispatched surface:

• predicate-matrix.action.ts (8) — the live browser specimen, untouched on purpose; changing it changes what the fixture demonstrates and wants a dogfood re-verification, not a rewrite.
• ui/actions/index.ts (3) and ui/views/field-zoo.view.ts (1) — showcase specimens outside the declared file surface.

So #8990 stays open, hence Part of.

The scoping decision is per predicate

Measured against the canonical @objectstack/formula CEL engine, on the three bindings a sparse row can present:

predicate shape	guard	why
bare equality against a literal	has() alone	CEL compares heterogeneously — has(record.a) && record.a == "high" is false, not a fault, on {a: null}
method call · ordering · arithmetic	full has(x) && x != null	has(record.a) && record.a.size() faults no such overload on {a: null}
!x / bare truthy x	rewrite to x != true / x == true, then has() alone	! and the logical operators need a bool and fault on null; the equality form does not, and it keeps the intended reading of a null column
nested traversal	has(x) && has(x.leaf) && x.leaf == true	see below

The full conjunction was NOT applied to all 22. Nineteen of them are equality-only and take has() alone.

Two measured findings the card did not have

1. The canonical two-term conjunction is not sufficient over a nested read. sys_approval_request gates on the service-attached record.viewer block. Measured:

has(record.viewer) && record.viewer != null && record.viewer.can_act
  {}                        => false
  {viewer: null}            => false
  {viewer: {}}              => FAULT No such key: can_act
  {viewer: {can_act: null}} => FAULT Logical operator requires bool operands, got 'null'

Guarding the LEAF is total, and it subsumes the parent != null half — has() on a path whose parent is null answers false rather than faulting:

has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true
  {} / {viewer: null} / {viewer: {}} / {viewer: {can_act: null}}  => false
  {viewer: {can_act: true}}                                       => true

So the minimal safe form here is leaf-first, and == true is load-bearing while the parent != null is not. Both claims are pinned as tests so the next author applying the canonical rule literally cannot "complete" it back into a faulting form. This is a partial falsification of the prescription #8975 landed, so the canonical statement itself is updated — see the docs section.

2. has() alone never flips a hidden button to offered. For an equality-only predicate a fault and a has()-false both mean "not offered", so the migration converts a fault into a deterministic false without changing visibility. The visibility flips come from the null-capable operand classes — which is exactly where the one user-visible change in this PR lives.

The behaviour change, demonstrated

sys_oauth_application. Both toggles reach list_item, and disabled is nullable upstream (better-auth writes the column only when it is set), so a list row carries it PROJECTED AND NULL for every application nobody has ever toggled — the ordinary state.

binding {disabled: null}	before	after
Disable button — !record.disabled ⇢ has(record.disabled) && record.disabled != true	FAULT no such overload: !null ⇒ hidden	true ⇒ offered
Enable button — record.disabled ⇢ has(record.disabled) && record.disabled == true	null (a non-boolean; the renderer decided what that meant)	false

The rest of the truth table is unchanged, and on a row that never projected the column both stay closed.

Reverse verification

Reverted disable_oauth_application to !record.disabled on the committed tree and re-ran the pin. Direction predicted before running: RED. Observed:

× no predicate faults on any binding a sparse row can present
+   "...disable_oauth_application.visible on {} (nothing projected): FAULT No such key: disabled
+   "...disable_oauth_application.visible on disabled projected as null: FAULT no such overload: !null
× the migrated spellings answer a real boolean — Disable offered, Enable not
    expected 'FAULT no such overload: !null' to be true
Test Files  1 failed (1)   Tests  3 failed | 5 passed (8)

Restored with git checkout HEAD -- ... and re-ran the union at the head commit.

Bounding sweep named

sys_oauth_application is not in the dispatched enumeration (sys-user, sys-invitation, sys-member, sys-approval-request) but is a platform object in the same directory, the same defect class, mechanical, and under the same gate families — and the card's own body says "every platform object's actions". It is also the only site where the defect is user-visible today, so leaving it would have shipped the migration without its demonstration. Named here rather than folded in silently.

Tests

Three new files, all driving the real @objectstack/formula engine rather than asserting spellings alone:

• packages/platform-objects/src/identity/action-predicate-sparse-face.test.ts — a SWEEP that discovers every record-scoped action predicate across 16 identity objects and evaluates each on every binding a sparse row can present (so a NEW unguarded action goes red without anyone updating a list), plus per-site verdicts so a guard cannot be an always-false wrapper, plus the oauth flip with the old spelling pinned as faulting.
• packages/plugins/plugin-approvals/src/action-predicate-sparse-face.test.ts — the fail-closed intent as a real false, every lever still opening for approver / override admin / submitter, and the four measurements behind the leaf-first form.
• examples/app-crm/test/action-predicate-sparse-face.test.ts — the example authors copy.

examples/app-crm gained @objectstack/formula as a devDependency, plus the vitest.config.ts alias and tsconfig paths rule that check:test-source-alias and check:type-source-resolution require, so the new pin is a verdict about the source in the checkout and not about build state. Neither gate's shrink-only registry was touched. rootDir / outDir came off that tsconfig as a consequence (it is tsc --noEmit; the app is built by the CLI), the same correction packages/qa/downstream-contract made.

packages/platform-objects/src/platform-objects.test.ts — the #2874 feature-gate lowering matrix pins the composed predicate verbatim, so six rows moved with the residuals. Its header now says what the matrix still pins (the gate term, the composition, the operand order) and that the residuals changed under #8990.

Docs the migration moves

Swept the whole content/docs/** corpus for the probe tokens rather than trusting a page list. Four surfaces moved, and one of them is the rule itself:

• packages/objectql/src/declared-fields.ts — the CANONICAL statement of the guard rule (The sparse action visible/disabled face is given two contradictory guard idioms by two platform documents, and measured, neither one alone is correct #8975). Its two-term conjunction guards ONE read and is measurably insufficient the moment a predicate traverses, so it now carries the nested-read row: guard the leaf, which subsumes the parent != null, with the outer has() and the == true both load-bearing. Doc comment only, no runtime change. Leaving it as it stood would have shipped metadata whose literal reading contradicts the platform's own canonical rule — the two-documents-disagree failure The sparse action visible/disabled face is given two contradictory guard idioms by two platform documents, and measured, neither one alone is correct #8975 existed to end.
• content/docs/automation/flows.mdx — its one-line restatement of the sparse-face rule now says "per READ" and carries the traversal form.
• content/docs/protocol/objectui/actions.mdx — quoted visible: "!record.disabled" verbatim, a predicate this PR changes, so the page both contradicted the shipped metadata and taught the shape that faults on a NULL column. Requoted; and the page that teaches action predicates now states the sparse-face guard rule, which it had never mentioned at all.
• content/docs/automation/approvals.mdx — its callout on browsing the raw sys_approval_request table ("a correct, completely inert list") is still true and is now true BY DESIGN rather than by fault; that distinction is recorded there.

Not changed, reported instead: content/docs/ui/actions.mdx:94 teaches visible: '!record.done' — the faulting negation shape — but it mirrors a showcase predicate this PR deliberately does not migrate, so changing it would desync the doc from the code the follow-up card owns. Same for the unguarded examples in getting-started/quick-start.mdx and getting-started/build-with-claude-code.mdx, and for protocol/objectui/record-alert.mdx, which is the surface of finding #9167.

content/docs/references/** (auto-generated) and content/docs/releases/** (release-owned) untouched.

Verification

Everything below was re-run at f5e13cc1f, the head commit — the numbers are from that run, not carried forward from the first commit.

pnpm --filter @objectstack/platform-objects --filter @objectstack/plugin-approvals --filter @objectstack/example-crm test
  platform-objects   Test Files  25 passed (25)   Tests  419 passed (419)
  plugin-approvals   Test Files  24 passed (24)   Tests  496 passed (496)
  example-crm        Test Files   4 passed  (4)   Tests   42 passed  (42)

... --filter @objectstack/objectql typecheck  -> all four Done

check:nul-bytes · check:docs-audit-scope · check:docs-redirects · check:role-word
check:durability-log-level · check:liveness · check:test-source-alias
check:type-source-resolution · check:engine-double-contract · check:where-matcher
check:query-options-erasure · check:i18n · check:type-check-coverage
check:changeset-gate-self-tests · check:objectui-changeset · check-engine-split-ratio
check-adr-0087-registration · check-changeset-no-major · check-empty-changeset
                                                                        -> all PASS

check:type-check-debt --re-measure     (re-run at this head, not the earlier one)
  OK — 33 ledger entr(ies) re-measured in 308.0s, 1926 raw tsc error(s) total,
  none above its recorded number. surplus: none.

The gate list was re-derived with scripts/pm/dispatch-gates.mjs against the full two-commit changed-path set (git diff --name-only origin/main...HEAD), not against the first commit's. The second commit widened the union by six families the first derivation could not see: check:docs-audit-scope, check:docs-redirects and check:role-word from the three content/docs pages; check:durability-log-level and check-engine-split-ratio from packages/objectql/src; and check:liveness — CI's Spec property liveness job — which the local path derivation does not name for a packages/objectql touch, so it was run directly rather than inferred. All six pass.

Standing refusals honored, not re-opened

• No lint rule. The mirror gate was evaluated and DECLINED (Evaluate the mirror null-guard gate for the sparse action visible/disabled binding — #4953's clause-2 remainder, whose premise moved when objectui#4079 landed #8881 / PR Record the declined verdict for the mirror null-guard gate on the sparse action face #8979) on measured grounds: sparseness is a property of the view's $select projection and of row data, not of the metadata a linter sees, so a sound static rule would flag 34 of 34.
• The showcase specimen is untouched. predicate-matrix.action.ts is a live browser specimen, and the PR for The sparse action visible/disabled face is given two contradictory guard idioms by two platform documents, and measured, neither one alone is correct #8975 left it alone on purpose and says so in the file.
• The binding stays sparse (#4649 的「记录对已声明字段全量」只落在两个接缝上 —— 另外三处求值仍是稀疏绑定 #4953 clause 2). Nothing here makes the action record total.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/objectql, @objectstack/platform-objects, @objectstack/plugin-approvals.

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

• content/docs/automation/approvals.mdx (via @objectstack/plugin-approvals)
• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/kernel/contracts/data-engine.mdx (via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx (via packages/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql, @objectstack/plugin-approvals)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/permissions/system-context.mdx (via packages/objectql)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql, @objectstack/platform-objects, @objectstack/plugin-approvals)
• 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/ui/setup-app.mdx (via @objectstack/platform-objects)

⛔ 2 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/objectql, @objectstack/plugin-approvals)
• content/docs/releases/v9.mdx (via @objectstack/plugin-approvals)

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.

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.