@object-ui/core 17.5.0 → 17.7.0

package/dist/evaluator/predicateInput.js

@@ -5,6 +5,28 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { isUnevaluablePredicate } from './unevaluablePredicate.js';
+/**
+ * The normalized answer for a gate that is DECLARED but has nothing the client
+ * can evaluate (objectui#11358) — the fourth member of
+ * {@link EvaluatorPredicateInput}, a `cel` envelope with no `source`.
+ *
+ * It exists so the normalizer can tell three states apart instead of two.
+ * `undefined` is "absent" and evaluates to `true` (visible / enabled) by the
+ * evaluator's one documented default; this value is "declared and faulting"
+ * and `ExpressionEvaluator.evaluateCondition` treats it as a FAULT — reported,
+ * thrown to a `throwOnError` caller, and answered with the fail-soft `true`
+ * otherwise — so every reader gets the fail direction its key already has for
+ * a predicate that cannot be evaluated. Folding it into `undefined`, as this
+ * function did, made an `ast`-only envelope, `0`, `{}` or an array read as
+ * "no gate" everywhere, in silence (ADR-0137 D4).
+ *
+ * Shape, not a marker: it says what the evaluator receives — a CEL predicate
+ * (a bare predicate is CEL by the spec's contract) whose `source` is absent —
+ * and carries nothing of the original value, so no reader can guess what an
+ * `ast` meant. Frozen and shared, so a reader's memo sees one value per state.
+ */
+const DECLARED_UNEVALUABLE = Object.freeze({ dialect: 'cel' });
 /**
  * Wrap a BARE expression as a `${…}` template, and leave a string that already
  * carries template syntax alone (objectui#3871 — rationale in
@@ -29,8 +51,13 @@ function wrapIfBare(expression) {
  *     authored predicate, including bare strings) → a `cel` dialect keeps
  *     its envelope; every other dialect is unwrapped and wrapped as
  *     `${source}`.
- *   - `null` / `undefined` / empty / anything else → `undefined`
- *     (default visible/enabled).
+ *   - `null` / `undefined` / `''` / an envelope whose `source` is `''` →
+ *     `undefined` (absent: default visible/enabled).
+ *   - anything else that is present — an envelope with no string `source`
+ *     (`{ dialect: 'cel', ast }`), a number, `{}`, an array → the frozen
+ *     `{ dialect: 'cel' }` with no `source`: declared, and a FAULT to the
+ *     evaluator (objectui#11358 — see `DECLARED_UNEVALUABLE` above). This used
+ *     to fold into `undefined` with the absent shapes.
  *
  * ## Why the `cel` envelope must survive normalization (#2661 / #3314)
  *
@@ -113,6 +140,10 @@ export function toPredicateInput(value) {
         return value;
     if (typeof value === 'string')
         return wrapIfBare(value);
+    // Declared, but nothing here can be evaluated (objectui#11358): kept as its
+    // own state rather than folded into "absent". See `DECLARED_UNEVALUABLE`.
+    if (isUnevaluablePredicate(value))
+        return DECLARED_UNEVALUABLE;
     if (typeof value === 'object' && typeof value.source === 'string') {
         const src = value.source;
         if (!src)
@@ -125,5 +156,7 @@ export function toPredicateInput(value) {
         // Every other dialect (template / unset) keeps the legacy `${…}` behavior.
         return wrapIfBare(src);
     }
+    // Unreachable: every present value is a boolean, a string, an envelope with a
+    // string `source`, or unevaluable — all answered above. Kept for the compiler.
     return undefined;
 }

package/dist/evaluator/rowPredicateCanon.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/** The one canonical row-predicate root. */
+export declare const ROW_PREDICATE_CANONICAL_ROOT = "record";
+/** A non-canonical row-predicate spelling, and the edit that fixes it. */
+export type NonCanonicalRowSpelling = {
+    /** Bare shorthand: `status == 'active'` — a field of THIS row, unrooted. */
+    kind: 'bare-shorthand';
+    /** The offending identifier (`status`). */
+    identifier: string;
+    /** What the author should write instead (`record.status`). */
+    canonical: string;
+} | {
+    /** Wrong-layer root: `data.status == 'active'` on a runtime record surface. */
+    kind: 'metadata-layer-root';
+    identifier: string;
+    canonical: string;
+};
+/**
+ * Detect a non-canonical spelling in ONE row predicate, or `null` when the
+ * predicate is already canonical (or is not this module's verdict to give).
+ *
+ * Deliberately conservative in both arms — every condition below can only
+ * REMOVE a finding, never invent one, because a false finding sends an author
+ * to rewrite a predicate that was correct:
+ *
+ * - **Unparseable source** → `null`. Syntax is another gate's verdict.
+ * - **Bare shorthand** is reported only when the undeclared identifier is an own
+ *   key of THIS row. That is what makes it unambiguously the #4075 shorthand
+ *   rather than a host-scope global this module cannot see (a deployment key
+ *   that is simply not in `SCOPE_ROOTS` would otherwise read as a bare field).
+ * - **`data.*`** is reported only when the caller confirms `data` names the row
+ *   (`dataNamesRow`). A surface whose `data` is the host scope's own — a
+ *   `rowless` dialog, a metadata-editing form — is a legitimate `data.*` site
+ *   and is left alone.
+ *
+ * Only the FIRST finding is returned, and the bare-shorthand arm is checked
+ * first: it is the arm the server refuses outright (`visibility-bare-identifier`
+ * is an `error` there, while a mis-layered root is a `warning`), so when a
+ * predicate manages both it is the one the author must fix to have anything
+ * evaluate at all.
+ *
+ * @param source       The predicate's CEL text. A legacy `${…}`-dialect string
+ *                     is not CEL and returns `null` here (unparseable); classify
+ *                     it by its own dialect's rules — on a runtime record surface
+ *                     it retired with the CEL spellings (`83fe6e741`), while on
+ *                     the schema/widget tier `data` is a different scope entirely.
+ * @param row          The row the predicate is bound against.
+ * @param dataNamesRow Whether `data` is bound to that same row on this surface.
+ */
+export declare function detectNonCanonicalRowSpelling(source: string, row: Record<string, unknown> | null | undefined, dataNamesRow: boolean): NonCanonicalRowSpelling | null;

package/dist/evaluator/rowPredicateCanon.js

@@ -0,0 +1,158 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The row-predicate spelling CANON: on a runtime record surface the row is bound
+ * as `record.*` and nothing else (objectui#5330, maintainer ruling 2026-08-20,
+ * option B; Phase 2 executed by `83fe6e741`).
+ *
+ * ## The canon
+ *
+ * A row predicate — `visible` / `disabled` / `enabled` on an action renderer, a
+ * row scope, a `record:alert`, a conditional-formatting `condition` — used to
+ * bind the row THREE ways: canonical `record.status`, bare shorthand `status`,
+ * and legacy `data.status` (objectui#4075 / PR #4079 bound all four action
+ * renderers all three ways to restore consistency, deliberately without
+ * deciding which of them was CONTRACT). The ruling decided it, in two phases:
+ *
+ * > **The canon is `record.*`.** Phase 1 (`d1ab06f0f`) declared it and warned
+ * > once, in dev, on the two other spellings. Phase 2 (`83fe6e741`, ruled
+ * > 2026-09-02 and amended 2026-09-05) retired them: the bare shorthand and
+ * > `data.*` are no longer bound on runtime record surfaces, and the Phase-1
+ * > warning went with them. No stored-metadata survey was run (「不考虑存量」);
+ * > the Phase-1 warning period was the notice.
+ *
+ * ## What a retired spelling does now: it FAULTS, as it always did on the server
+ *
+ * The canon states the SERVER's accept set. Measured against
+ * `@objectstack/formula@17.1.0` — the engine the server evaluates with, and the
+ * one `fieldRules.ts` delegates to:
+ *
+ * | spelling | server runtime (`buildScope` + `celEngine`) | server authoring oracle |
+ * |---|---|---|
+ * | `record.status` | ✅ `{ ok: true, value: true }` | ✅ accepted |
+ * | bare `status`   | ❌ `Unknown variable: status` | ❌ refused (`'status'`) |
+ * | `data.status`   | ❌ `Unknown variable: data`   | ⚠️ silently accepted |
+ *
+ * `buildScope({ record })` mounts exactly `['record']`. Since Phase 2 the client
+ * binds the same set (`listConditional.ts`' scope bag and `@object-ui/react`'s
+ * `usePredicateRecordContext`), so both retired spellings fault on the client
+ * with the server's verdict, and each surface applies its EXISTING fault policy:
+ * fail-closed `visible` on the throwing `useCondition` legs, the caller's
+ * `fallback` on `evalRowPredicate` / `partitionRowsByPredicate`, fail-soft on
+ * the non-throwing `useCondition` legs. There is no runtime detector, no
+ * "treat as absent" special case and no uniform override — a retired spelling
+ * is not a recognised-and-rejected thing, it is an unknown variable like any
+ * other, and the existing fault warnings are what name it.
+ *
+ * One consequence, stated so it is not read back as a bug: a host scope may
+ * legitimately carry its OWN `data` (a rowless dialog's, or app-shell's ambient
+ * `data: {}`), and it is left standing. `data.*` on a record surface then reads
+ * the host's object rather than the row — which is exactly what "no longer bound
+ * to the row" means, and, against an ambient `data: {}`, the constant-false
+ * signature the Phase-1 warning text already described for the server.
+ *
+ * ## `data.*` is retired HERE, not everywhere — the canon is layer-scoped
+ *
+ * `data` is the CANONICAL root one layer over, in a metadata-editing form (the
+ * row under edit): objectstack's `CANONICAL_ROOT_BY_LAYER` reads
+ * `{ runtime: 'record', metadata: 'data' }` (ADR-0089 D3), and objectui's own
+ * `app-shell` metadata-admin `SchemaForm` binds `{ data: row }` on purpose,
+ * through its own evaluator (`views/metadata-admin/predicate.ts`) — never
+ * through `evalRowPredicate` or `usePredicateRecordContext`. So `data.*` is not
+ * retired platform-wide: it is a WRONG-LAYER spelling on a runtime record
+ * surface, and that is the only thing the detector below reports.
+ *
+ * ## What is left in this module, and why
+ *
+ * {@link detectNonCanonicalRowSpelling} is the OFFLINE instrument: it classifies
+ * an authored predicate's spelling against a row without evaluating it, so a
+ * sweep over stored or in-repo metadata (the `702c48a62` corpus sweep's
+ * recipe) can find the documents that still need rewriting. It is
+ * exported for that purpose and nothing on the hot path calls it — the runtime
+ * warning half Phase 1 built on it (`warnNonCanonicalRowSpelling`,
+ * `resetRowPredicateCanonWarnings`) was removed with the bindings.
+ *
+ * ## Why the detection reuses the server's oracle instead of a regex
+ *
+ * `collectCelRootIdentifiers` and `firstUndeclaredReference` are
+ * `@objectstack/formula` exports — the same two oracles objectstack's
+ * `visibility-bare-identifier` gate uses. Reading roots off the canonical AST
+ * rather than pattern-matching the source is what keeps this from inventing a
+ * second dialect judgement client-side: a string this module cannot parse is
+ * NOT this module's verdict to give (syntax belongs to the gates that own it),
+ * and it stands down rather than guessing.
+ */
+import { collectCelRootIdentifiers, firstUndeclaredReference } from '@objectstack/formula';
+/** The one canonical row-predicate root. */
+export const ROW_PREDICATE_CANONICAL_ROOT = 'record';
+/**
+ * The metadata-editing-form root (ADR-0089 D3). Canonical on THAT layer, and a
+ * wrong-layer paste on a runtime record surface — see the module note.
+ */
+const METADATA_LAYER_ROOT = 'data';
+/**
+ * Detect a non-canonical spelling in ONE row predicate, or `null` when the
+ * predicate is already canonical (or is not this module's verdict to give).
+ *
+ * Deliberately conservative in both arms — every condition below can only
+ * REMOVE a finding, never invent one, because a false finding sends an author
+ * to rewrite a predicate that was correct:
+ *
+ * - **Unparseable source** → `null`. Syntax is another gate's verdict.
+ * - **Bare shorthand** is reported only when the undeclared identifier is an own
+ *   key of THIS row. That is what makes it unambiguously the #4075 shorthand
+ *   rather than a host-scope global this module cannot see (a deployment key
+ *   that is simply not in `SCOPE_ROOTS` would otherwise read as a bare field).
+ * - **`data.*`** is reported only when the caller confirms `data` names the row
+ *   (`dataNamesRow`). A surface whose `data` is the host scope's own — a
+ *   `rowless` dialog, a metadata-editing form — is a legitimate `data.*` site
+ *   and is left alone.
+ *
+ * Only the FIRST finding is returned, and the bare-shorthand arm is checked
+ * first: it is the arm the server refuses outright (`visibility-bare-identifier`
+ * is an `error` there, while a mis-layered root is a `warning`), so when a
+ * predicate manages both it is the one the author must fix to have anything
+ * evaluate at all.
+ *
+ * @param source       The predicate's CEL text. A legacy `${…}`-dialect string
+ *                     is not CEL and returns `null` here (unparseable); classify
+ *                     it by its own dialect's rules — on a runtime record surface
+ *                     it retired with the CEL spellings (`83fe6e741`), while on
+ *                     the schema/widget tier `data` is a different scope entirely.
+ * @param row          The row the predicate is bound against.
+ * @param dataNamesRow Whether `data` is bound to that same row on this surface.
+ */
+export function detectNonCanonicalRowSpelling(source, row, dataNamesRow) {
+    if (typeof source !== 'string' || !source.trim())
+        return null;
+    const roots = collectCelRootIdentifiers(source);
+    // Not parseable through the canonical front end — not our verdict.
+    if (!roots || roots.ok !== true)
+        return null;
+    // (1) Bare shorthand — the arm the server refuses outright.
+    const bare = firstUndeclaredReference(source);
+    if (typeof bare === 'string' &&
+        row != null &&
+        typeof row === 'object' &&
+        Object.prototype.hasOwnProperty.call(row, bare)) {
+        return {
+            kind: 'bare-shorthand',
+            identifier: bare,
+            canonical: `${ROW_PREDICATE_CANONICAL_ROOT}.${bare}`,
+        };
+    }
+    // (2) Wrong-layer `data.*` root — silent at runtime on the server.
+    if (dataNamesRow && Array.isArray(roots.roots) && roots.roots.includes(METADATA_LAYER_ROOT)) {
+        return {
+            kind: 'metadata-layer-root',
+            identifier: METADATA_LAYER_ROOT,
+            canonical: ROW_PREDICATE_CANONICAL_ROOT,
+        };
+    }
+    return null;
+}

package/dist/evaluator/subjectPermissions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The acting subject's effective object permissions, carried to the one place
+ * this repo hands a predicate to the CEL engine (objectui#4421).
+ *
+ * ## What it is for
+ *
+ * `@objectstack/formula` registers `current_user.can(object, verb)` as a
+ * receiver method on the acting subject, and answers it from
+ * `EvalContext.permissions` — the verbatim `objects` map of the
+ * `/auth/me/permissions` response. That map is a separate field of the engine
+ * context, and the engine is explicit that it is ⛔ NOT a CEL variable: an
+ * authored predicate must not be able to read `permissions.crm_lead.allowEdit`
+ * and step around the closed verb table.
+ *
+ * This repo's evaluation seam (`evalFieldPredicate`) is not handed an engine
+ * context by its callers, though. Every action surface — the row menu, the
+ * record header, the `action:*` renderers, `DeclaredActionsBar` — hands it a
+ * variable BAG (the host's predicate scope, spread, merged, pushed through an
+ * `ExpressionContext`), and the bag's string keys all become CEL roots. So the
+ * permissions cannot ride on the bag under a name: any name would be a root.
+ *
+ * They ride on the SUBJECT instead, under a symbol:
+ *
+ *  - The engine models the map as the subject's own answer sheet — it binds
+ *    `permissions` only alongside a user, and `can` refuses any receiver that
+ *    is not that user (`receiver !== subject`). The subject is the one object
+ *    every bag already carries by reference under `current_user` (and the
+ *    `user` / `ctx.user` / `os.user` aliases of it), through every spread and
+ *    every `ExpressionContext` scope, so no surface needs its own copy of the
+ *    hand-off.
+ *  - A symbol is the one kind of key no predicate dialect can name: CEL
+ *    identifiers and member names are strings, and so are the legacy
+ *    evaluator's. `current_user.permissions` still faults as an unknown key.
+ *
+ * ## Absent is not empty
+ *
+ * A subject that carries NO map — the payload has not loaded, no permission
+ * provider is mounted, or the provider has no `/auth/me/permissions` answer at
+ * all — hands the engine no `permissions`, and `can` then refuses loudly
+ * (`ok: false`, `kind: 'runtime'`). That refusal is a FAULT, so each surface
+ * applies its own fault policy to it; it is never turned into a quiet `false`
+ * here, because the engine's contract is that an empty map means "holds
+ * nothing" and a caller that has no data must not claim it has that answer.
+ */
+import type { EvalPermissions } from '@objectstack/formula';
+/**
+ * The key the subject carries its effective object permissions under.
+ *
+ * `Symbol.for` rather than `Symbol()` so two copies of this module in one page
+ * (a host that bundles `@object-ui/core` twice) still agree on the key; the
+ * namespace keeps it from colliding with anyone else's registry entry.
+ */
+export declare const SUBJECT_PERMISSIONS: unique symbol;
+/**
+ * The subject to publish as `current_user`, carrying `permissions` when there
+ * are any.
+ *
+ * Returns a shallow copy so the caller's own user object is never mutated; the
+ * copy is what the whole predicate scope must use for every alias of the
+ * subject, because the engine compares the `can` receiver by IDENTITY. With no
+ * `permissions` the result carries none — a subject built from one that did is
+ * stripped rather than left answering from a stale map.
+ */
+export declare function bindSubjectPermissions<T extends object>(subject: T, permissions: EvalPermissions | undefined): T;
+/**
+ * The effective object permissions a subject carries, or `undefined` when it
+ * carries none (see "Absent is not empty" above).
+ */
+export declare function subjectPermissionsOf(subject: unknown): EvalPermissions | undefined;

package/dist/evaluator/subjectPermissions.js

@@ -0,0 +1,44 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The key the subject carries its effective object permissions under.
+ *
+ * `Symbol.for` rather than `Symbol()` so two copies of this module in one page
+ * (a host that bundles `@object-ui/core` twice) still agree on the key; the
+ * namespace keeps it from colliding with anyone else's registry entry.
+ */
+export const SUBJECT_PERMISSIONS = Symbol.for('@object-ui/core:subject-permissions');
+/**
+ * The subject to publish as `current_user`, carrying `permissions` when there
+ * are any.
+ *
+ * Returns a shallow copy so the caller's own user object is never mutated; the
+ * copy is what the whole predicate scope must use for every alias of the
+ * subject, because the engine compares the `can` receiver by IDENTITY. With no
+ * `permissions` the result carries none — a subject built from one that did is
+ * stripped rather than left answering from a stale map.
+ */
+export function bindSubjectPermissions(subject, permissions) {
+    if (permissions === undefined) {
+        if (!Object.prototype.hasOwnProperty.call(subject, SUBJECT_PERMISSIONS))
+            return subject;
+        const stripped = { ...subject };
+        delete stripped[SUBJECT_PERMISSIONS];
+        return stripped;
+    }
+    return { ...subject, [SUBJECT_PERMISSIONS]: permissions };
+}
+/**
+ * The effective object permissions a subject carries, or `undefined` when it
+ * carries none (see "Absent is not empty" above).
+ */
+export function subjectPermissionsOf(subject) {
+    if (subject === null || typeof subject !== 'object')
+        return undefined;
+    return subject[SUBJECT_PERMISSIONS];
+}

package/dist/evaluator/unevaluablePredicate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Is this value a gate the author DECLARED but the client cannot EVALUATE?
+ * (objectui#11358)
+ *
+ * A predicate gate (`visible` / `hidden` / `enabled` / `disabled` /
+ * `condition`) is in one of three states, and this is the one place the third
+ * is told apart from the other two:
+ *
+ *   - **absent** — `null` / `undefined` / `''` / blank predicate text. Nothing
+ *     was declared; {@link hasDeclaredPredicate} answers "not declared" (and
+ *     reports a blank one, objectui#8069).
+ *   - **evaluable** — a boolean, a predicate string, or an envelope whose
+ *     `source` is a non-blank string.
+ *   - **declared but not evaluable** — anything else that is present: an
+ *     envelope with no string `source` (the `ast`-only `{ dialect: 'cel', ast }`
+ *     an authoring door can admit), a number (`0`, `42`), an object with no
+ *     `source` (`{}`), an array. This function answers `true` for exactly
+ *     these.
+ *
+ * Triage's ruling on objectui#11358 makes the third state "declared and
+ * faulting": it is a gate, so it is never "no gate", and it cannot be
+ * evaluated, so it takes the path every other faulting predicate takes —
+ * reported, and answered with the fail direction its key already has. Before
+ * that ruling the normalizer folded it to `undefined`, the same answer as
+ * "absent", so every reader showed / enabled / ran it in silence: ADR-0137 D4's
+ * "a gate predicate that is blank or faulting is diagnosed, never a silent
+ * `true`", broken by a fold.
+ *
+ * Read by the normalizer ({@link toPredicateInput}, which now keeps the state
+ * instead of folding it), the evaluation step
+ * (`ExpressionEvaluator.evaluateCondition`, which reports it and answers it as a
+ * fault), the canonical predicate helper (`evalFieldPredicate`, which tags its
+ * reason) and the dev-mode schema validator (which still refuses it). ⛔ Not
+ * re-exported from the package entry: it is the internal definition those four
+ * share, not public API.
+ *
+ * ⚠️ No client-side reading of what an `ast` MEANT: the client evaluates
+ * `source` text only, so an `ast` with no `source` is not evaluable here,
+ * whatever it says.
+ */
+export declare function isUnevaluablePredicate(value: unknown): boolean;
+/**
+ * The `reason` reported for a gate that is declared but cannot be evaluated,
+ * tagged like an engine reason (`[parse]`, `[type]`, `[blank]`) because it
+ * travels the same two channels — `evalFieldPredicate`'s one-time warning and
+ * its `onFault` passback — and a caller that routes on the tag must tell it
+ * apart from a predicate that faulted with text in it: the fix is to give the
+ * gate a `source` (or delete it), never to debug CEL syntax.
+ */
+export declare const UNEVALUABLE_PREDICATE_REASON: string;

package/dist/evaluator/unevaluablePredicate.js

@@ -0,0 +1,70 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Is this value a gate the author DECLARED but the client cannot EVALUATE?
+ * (objectui#11358)
+ *
+ * A predicate gate (`visible` / `hidden` / `enabled` / `disabled` /
+ * `condition`) is in one of three states, and this is the one place the third
+ * is told apart from the other two:
+ *
+ *   - **absent** — `null` / `undefined` / `''` / blank predicate text. Nothing
+ *     was declared; {@link hasDeclaredPredicate} answers "not declared" (and
+ *     reports a blank one, objectui#8069).
+ *   - **evaluable** — a boolean, a predicate string, or an envelope whose
+ *     `source` is a non-blank string.
+ *   - **declared but not evaluable** — anything else that is present: an
+ *     envelope with no string `source` (the `ast`-only `{ dialect: 'cel', ast }`
+ *     an authoring door can admit), a number (`0`, `42`), an object with no
+ *     `source` (`{}`), an array. This function answers `true` for exactly
+ *     these.
+ *
+ * Triage's ruling on objectui#11358 makes the third state "declared and
+ * faulting": it is a gate, so it is never "no gate", and it cannot be
+ * evaluated, so it takes the path every other faulting predicate takes —
+ * reported, and answered with the fail direction its key already has. Before
+ * that ruling the normalizer folded it to `undefined`, the same answer as
+ * "absent", so every reader showed / enabled / ran it in silence: ADR-0137 D4's
+ * "a gate predicate that is blank or faulting is diagnosed, never a silent
+ * `true`", broken by a fold.
+ *
+ * Read by the normalizer ({@link toPredicateInput}, which now keeps the state
+ * instead of folding it), the evaluation step
+ * (`ExpressionEvaluator.evaluateCondition`, which reports it and answers it as a
+ * fault), the canonical predicate helper (`evalFieldPredicate`, which tags its
+ * reason) and the dev-mode schema validator (which still refuses it). ⛔ Not
+ * re-exported from the package entry: it is the internal definition those four
+ * share, not public API.
+ *
+ * ⚠️ No client-side reading of what an `ast` MEANT: the client evaluates
+ * `source` text only, so an `ast` with no `source` is not evaluable here,
+ * whatever it says.
+ */
+export function isUnevaluablePredicate(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'boolean' || typeof value === 'string')
+        return false;
+    if (typeof value === 'object') {
+        return typeof value.source !== 'string';
+    }
+    // A number (`0` included — it is present, not absent), a function, a symbol
+    // or a bigint: nothing a predicate is spelled as.
+    return true;
+}
+/**
+ * The `reason` reported for a gate that is declared but cannot be evaluated,
+ * tagged like an engine reason (`[parse]`, `[type]`, `[blank]`) because it
+ * travels the same two channels — `evalFieldPredicate`'s one-time warning and
+ * its `onFault` passback — and a caller that routes on the tag must tell it
+ * apart from a predicate that faulted with text in it: the fix is to give the
+ * gate a `source` (or delete it), never to debug CEL syntax.
+ */
+export const UNEVALUABLE_PREDICATE_REASON = '[unevaluable] the gate is declared but has no `source` to evaluate (an ' +
+    '`ast`-only envelope, a number, an object or an array) — it fails in the ' +
+    'direction its key fails on any fault';

package/dist/index.d.ts

@@ -8,6 +8,7 @@
 export type { SchemaNode, ComponentRendererProps } from './types/index.js';
 export * from './registry/Registry.js';
 export * from './registry/public-blocks.js';
+export * from './registry/html-tier-intrinsics.js';
 export * from './registry/PluginSystem.js';
 export * from './registry/PluginScopeImpl.js';
 export * from './registry/WidgetRegistry.js';
@@ -17,7 +18,12 @@ export * from './utils/dom-props.js';
 export * from './utils/filter-converter.js';
 export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
+export * from './utils/non-grid-row-ceiling.js';
+export * from './utils/emptiness.js';
 export * from './utils/expand-fields.js';
+export * from './utils/retired-field-types.js';
+export * from './utils/unmaterialized-fields.js';
+export * from './utils/column-sortability.js';
 export * from './utils/column-identity.js';
 export * from './utils/sort-values.js';
 export * from './utils/sort-query.js';
@@ -49,12 +55,24 @@ export * from './utils/dashboard-filters.js';
 export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
+export * from './utils/chart-measure-key.js';
+export * from './utils/chart-category-key.js';
+export * from './utils/object-aggregate-query.js';
+export * from './utils/chart-presentation.js';
 export * from './utils/number-display.js';
+export * from './utils/date-display.js';
+export * from './utils/native-date-value.js';
 export * from './utils/dataset-format.js';
 export * from './utils/dataset-pivot.js';
 export * from './utils/record-title.js';
+export * from './utils/record-color.js';
 export * from './utils/export-filename.js';
 export * from './utils/reference-keys.js';
 export * from './utils/predicate-record.js';
+export * from './utils/without-denied-fields.js';
+export * from './utils/parent-scope.js';
 export * from './utils/predicate-fields.js';
+export * from './utils/grouping-fields.js';
 export * from './utils/normalize-list-view.js';
+export * from './utils/record-source.js';
+export * from './utils/humanize-label.js';