fix(example-showcase): guard the authored action predicates against the sparse face (#8990) (#9280)

* fix(example-showcase): guard the authored action predicates against the sparse face (#8990)

Every record-scoped `visible` / `disabled` predicate in app-showcase now carries
the `has()` guard the sparse action face requires. A row action's predicate binds
a LIST ROW carrying only the view's `$select` projection, and CEL aborts with
`No such key` on a column that row never projected -- fail-closed, so the button
silently is not offered, which is indistinguishable from the gate saying no.

Measured against the running app's own payloads (showcase booted, real seeded
records, real view projections): 40 of the 53 predicates in
predicate-matrix.action.ts aborted on a default-list row before this change and 0
do after, while every verdict on a record-detail binding is unchanged -- so the
Full-vs-Minimal contrast the fixture exists to demonstrate is preserved exactly.

The guard is minimal per predicate rather than blanket: has() alone where the read
is only compared by == / != , the full has(x) && x != null conjunction only where
an operand can fault (traversal, method call, ordering, arithmetic, `in`, bare !).

Census correction: the remainder was 57, not the 12 carried forward from PR #9166.
`zooTypeGate(name, label, visible)` passes its predicate POSITIONALLY, so the
`visible:`-key grep behind both the original 34 and the 12 saw 8 of these and
missed 45. The new test reads predicates off the exported actions instead.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTKPDRoynY8i3HmdSFUxFj

* docs(objectql): carry #8990's three sparse-face measurements to the canonical rule

The showcase migration (PR #9280) measured three shapes the two-level nested
table at :79 reads as already covered and does not reach. Recorded additively at
the definition site, because a rule stated only in a reader is how #8975 came to
exist:

1. A three-level path needs has() at EVERY segment. Guarding the leaf subsumes
   the parent's `!= null` but NOT the parent's has(): `has(record.r) &&
   has(record.r.p.s)` still faults `No such key: p` on `{r: null}` / `{r: {}}`.
2. A nested leaf used for ORDERING still needs its own `!= null` -- the leaf
   has() proves presence, not value, and the equality exception does not extend
   to `< <= > >=`.
3. Indexing faults on an EMPTY list, not only a null one: `record.b[0]` on
   `{b: []}` gives `No such key: index out of bounds`, so `!= null` is not the
   guard for a subscript; a `.size()` test is.

Every cell of all three tables was evaluated against the canonical
@objectstack/formula engine before being written.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTKPDRoynY8i3HmdSFUxFj

* chore(gates): narrow the showcase source-resolution registries after the formula alias

Both shrink-only registries recorded @objectstack/example-showcase as still
reaching @objectstack/formula through dist/. It no longer does -- this PR added
the vitest alias and the tsconfig `paths` rule so the new sparse-face test
evaluates and typechecks against engine SOURCE. Dropping the entry is a SHRINK,
the permitted direction; the gates printed the exact replacement lists and both
were applied verbatim.

Deliberately NOT fixed by removing the alias to make the registries true again:
that would trade a green gate for the hazard the gates exist to name -- a test
that runs green against a stale engine build, and a typecheck that PASSES over a
contract that has since moved.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTKPDRoynY8i3HmdSFUxFj

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/showcase-predicate-sparse-face-remainder.md

@@ -0,0 +1,25 @@
+---
+"@objectstack/example-showcase": patch
+---
+
+Guard the showcase's authored action predicates against the sparse action face (#8990)
+
+Every record-scoped `visible` / `disabled` predicate in `app-showcase` now carries the
+`has()` guard the sparse action face requires, closing the remainder of #8990 in this
+repo. A row action's predicate binds a LIST ROW carrying only the view's `$select`
+projection, and CEL aborts with `No such key` on a column that row never projected —
+fail-closed, so the button silently is not offered.
+
+Measured against the running app's own payloads: 40 of the 53 predicates in
+`predicate-matrix.action.ts` aborted on a default-list row before this change and 0 do
+after, while every verdict on a record-detail binding is unchanged — the Full-vs-Minimal
+contrast the fixture exists to demonstrate is preserved exactly.
+
+The guard is minimal per predicate rather than blanket: `has()` alone where the read is
+only compared by `==` / `!=` (CEL compares heterogeneously and answers `false` rather
+than faulting), the full `has(x) && x != null` conjunction only where an operand can
+fault — traversal, method call, ordering, arithmetic, `in`, or a bare `!`.
+
+The teaching surfaces move with the code, since they quote it: `content/docs/ui/actions.mdx`
+(whose `visible: '!record.done'` was the exact negation shape that faults on a NULL
+column), `quick-start.mdx` and `build-with-claude-code.mdx`.

content/docs/getting-started/build-with-claude-code.mdx

@@ -159,7 +159,9 @@ export const ResolveTicketAction = defineAction({
   locations: ['record_header', 'list_item'],
   // Only offer "Resolve" on tickets that aren't already resolved or closed.
   // Predicates are CEL, record-scoped — `record.status`, never bare `status`.
-  visible: 'record.status != "resolved" && record.status != "closed"',
+  // `has()` guards the sparse list row: a list projects only the columns it
+  // shows, and CEL faults on an absent key (which hides the button silently).
+  visible: 'has(record.status) && record.status != "resolved" && record.status != "closed"',
   successMessage: 'Ticket resolved.',
   refreshAfter: true,
   ai: {

content/docs/getting-started/quick-start.mdx

@@ -109,6 +109,11 @@ reviewing an agent's work, these are the two things most worth a close read:
   `status`. A bare reference silently hides the action on every record — the single
   most common AI mistake, which is exactly why `os validate` rejects it. See it in
   action in [Build with Claude Code → the gate](/docs/getting-started/build-with-claude-code#4-the-gate-os-validate-catches-ai-mistakes).
+  On a row action, also **guard the field with `has()`** —
+  `has(record.status) && record.status != 'sent'` — because a list row carries
+  only the columns that view projects, and reading an absent one faults and
+  hides the button. See [Actions](/docs/ui/actions) for when the guard needs
+  `&& record.x != null` on top.
 - **Views & Apps** (`defineView`, `App.create`) — the list/form lenses and the
   navigation. Reading these tells you what the user will actually see and click.
 

content/docs/ui/actions.mdx

@@ -91,7 +91,7 @@ export const MarkDoneAction = defineAction({
     capabilities: ['api.write'],
   },
   successMessage: 'Task marked done.',
-  visible: '!record.done',
+  visible: 'has(record.done) && record.done != true',
   locations: ['list_item', 'record_header', 'record_section'],
   refreshAfter: true,
 });
@@ -276,10 +276,24 @@ is a spec proposal for a properly named key, not a values map under this one.
   Unset means no gate beyond object CRUD permissions. Referenced capabilities
   must exist — `os lint` checks that.
 - **`visible`** is a CEL predicate evaluated **fail-closed**: an expression
-  that throws hides the action silently. The rule that saves real debugging
-  time: always prefix record fields (`record.status != "closed"`, never a bare
-  `status`, which faults as an undeclared identifier). Compound `&&` / `||`
-  predicates are fully supported — see the
+  that throws hides the action silently. Two rules save real debugging time:
+
+  1. **Always prefix record fields** — `record.status != "closed"`, never a bare
+     `status`, which faults as an undeclared identifier.
+  2. **Guard with `has()`** — a record-scoped predicate on `list_item` binds a
+     LIST ROW, which carries only the columns that view projects. Reading a
+     field the list does not show aborts the expression with `No such key`, and
+     fail-closed means the button simply is not offered — indistinguishable from
+     the gate having said no. `has(record.x) && …` answers `false` instead.
+
+  Add `&& record.x != null` **only** when the value is then traversed
+  (`record.x.k`), called (`record.x.size()`), ordered (`<` `<=` `>` `>=`),
+  negated (`!record.x`) or used with `in` — those fault on a projected NULL. A
+  plain `==` / `!=` against a literal never does, so `has()` alone is the whole
+  guard there. Prefer the minimal form: an over-guarded predicate is the pattern
+  the next author copies.
+
+  Compound `&&` / `||` predicates are fully supported — see the
   [formulas guide](/docs/data-modeling/formulas) for CEL syntax.
 - **`requiresFeature`** ties visibility to a feature flag (compiled into a
   `visible` predicate).

examples/app-showcase/src/ui/actions/index.ts

@@ -59,8 +59,18 @@ export const MarkDoneAction = defineAction({
   // `record.`-prefix: the ActionEngine evaluates a record-header action's
   // `visible` against `{ record, recordId, … }` with fail-closed semantics, so
   // a bare `done`/`status` throws (field not at top level) and silently hides
-  // the action. Single operand, too — the template path throws on `&&`/`||`.
-  visible: '!record.done',
+  // the action.
+  //
+  // #8990 — `has()` guards the SPARSE action face: this action reaches
+  // `list_item`, so its predicate binds a list row carrying only the view's
+  // `$select` projection, and CEL aborts with `No such key: done` on any task
+  // list that does not project the column (fail-closed, the button silently
+  // is not offered). The comparison is `!= true` rather than the older
+  // `!record.done` because a bare `!` on a projected-but-NULL column faults
+  // `no such overload: !null`, while `!=` against a literal never faults and
+  // still reads an unset `done` as "not done". `has()` alone is therefore the
+  // whole guard here. Rule: `packages/objectql/src/declared-fields.ts`.
+  visible: 'has(record.done) && record.done != true',
   // `record_section` so the Task Detail page's `record:quick_actions` bar
   // (which names this action) resolves it — the engine location-filters even
   // explicitly-named actions, mirroring the platform's own sys-user pages.
@@ -259,9 +269,12 @@ export const SubmitForSignoffAction = defineAction({
     capabilities: ['api.write'],
   },
   successMessage: 'Invoice submitted for finance + legal sign-off.',
-  // Only on invoices not yet sent. `record.`-prefixed single comparison, per the
+  // Only on invoices not yet sent. `record.`-prefixed comparison, per the
   // ActionEngine's fail-closed CEL evaluation (see MarkDoneAction's note).
-  visible: "record.status != 'sent'",
+  // #8990 — `has()` guards the sparse face this reaches via `list_item`; the
+  // `!=` against a literal never faults on a projected NULL, so `has()` alone
+  // is the whole guard.
+  visible: "has(record.status) && record.status != 'sent'",
   locations: ['list_item', 'record_header'],
   refreshAfter: true,
 });
@@ -362,8 +375,9 @@ export const ArchiveTaskAction = defineAction({
     capabilities: [],
   },
   successMessage: 'Task archived (demo — no data changed).',
-  // Disabled while the task is not done — visible either way.
-  disabled: 'record.done != true',
+  // Disabled while the task is not done — visible either way. #8990: `has()`
+  // for the sparse face; `!=` against a literal cannot fault, so no `!= null`.
+  disabled: 'has(record.done) && record.done != true',
   locations: ['record_header', 'record_section'],
   refreshAfter: false,
 });