@object-ui/core 17.2.0 → 17.3.0

package/dist/evaluator/predicateInput.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 normalized shape {@link ExpressionEvaluator.evaluateCondition} consumes:
+ * a boolean (short-circuits), a `${…}` template string (legacy JS path), a
+ * `{ dialect: 'cel', source }` envelope (canonical `@objectstack/formula`
+ * path), or `undefined` for "no predicate declared".
+ *
+ * ## Why not `PredicateInput` (objectstack#4115 / objectui#3074)
+ *
+ * `@objectstack/spec` owns `PredicateInput` — and it is a genuinely DIFFERENT
+ * concept, so wearing that name would be the exact drift this repo's
+ * `check:spec-symbols` gate exists to stop. The spec's is
+ * `z.input<typeof PredicateInputSchema>`: what an author WRITES, before
+ * normalization — a bare string, or an envelope over the full dialect set
+ * (`cel` | `cron` | `template`) with optional `source` / `ast` / `meta`.
+ *
+ * This one is the OUTPUT of normalization: what the evaluator ACCEPTS. It
+ * admits `boolean` and the `${…}` template spelling (neither of which the spec
+ * models as a predicate), narrows `dialect` to `cel` alone (every other dialect
+ * has already been flattened onto the legacy path by `toPredicateInput`),
+ * requires a non-empty `source`, and carries no `ast` / `meta`. The two unions
+ * are not mutually assignable in either direction.
+ *
+ * The rename is pinned from both sides by the tripwire in
+ * `packages/core/src/utils/__tests__/spec-symbol-batch4.test.ts`: the spec must
+ * still own `PredicateInput` (else this rename has lost its reason), and must
+ * still NOT own `EvaluatorPredicateInput` (the objectui#3074 mistake of
+ * renaming onto another name the spec already holds).
+ */
+export type EvaluatorPredicateInput = string | boolean | {
+    dialect: 'cel';
+    source: string;
+} | undefined;
+/**
+ * Normalize a schema-supplied predicate (`visible` / `enabled` / `disabled` /
+ * `hidden`) into the form {@link ExpressionEvaluator.evaluateCondition}
+ * expects.
+ *
+ * Accepts:
+ *   - `boolean` → returned as-is (predicate evaluation short-circuits).
+ *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
+ *   - `Expression` envelope `{ dialect, source }` (the normalized form
+ *     `@objectstack/spec`'s `ExpressionInputSchema` produces for every
+ *     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).
+ *
+ * ## Why the `cel` envelope must survive normalization (#2661 / #3314)
+ *
+ * `evaluateCondition` routes to the canonical `@objectstack/formula` engine —
+ * the one the SERVER enforces with — only while the argument is still a
+ * `{ dialect: 'cel' }` object. Collapse it to `${source}` first and the
+ * predicate silently falls to the legacy JS evaluator, whose semantics
+ * differ: CEL has no `<` overload for `null`, so `null < null` faults and
+ * fail-closed hides, while JS quietly yields `false`; CEL-only builtins
+ * (`today()`, objectstack#3205) do not exist on the JS path at all. Two
+ * normalizers that disagree on this one branch therefore make the SAME
+ * `visible:` predicate reach different verdicts depending on whether the
+ * action was surfaced by `ActionEngine.getActionsForLocation` or rendered
+ * standalone (#3314).
+ *
+ * This is THE implementation, not one of two — `@object-ui/core` is the common
+ * dependency of every consumer, so engine-side code and renderer-side code
+ * share one normalization instead of hand-rolling envelope unwrapping per call
+ * site. `@object-ui/react`'s `toPredicateInput` is a re-export of this function
+ * (since #3367; it used to be an independent twin held in step by a 14-shape
+ * normalization parity table, which is exactly the arrangement the paragraph
+ * above describes the failure mode of). What pins that now is the identity
+ * assertion in
+ * `packages/react/src/hooks/__tests__/actionPredicate.parity.test.tsx` — the
+ * react export must BE this function object — alongside the engine-path vs
+ * renderer-path verdict parity suite in the same file, which is a separate
+ * claim and still earns its keep: sharing a normalizer does not by itself
+ * prove the two call paths reach the same verdict.
+ */
+export declare function toPredicateInput(value: unknown): EvaluatorPredicateInput;

package/dist/evaluator/predicateInput.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+/**
+ * Normalize a schema-supplied predicate (`visible` / `enabled` / `disabled` /
+ * `hidden`) into the form {@link ExpressionEvaluator.evaluateCondition}
+ * expects.
+ *
+ * Accepts:
+ *   - `boolean` → returned as-is (predicate evaluation short-circuits).
+ *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
+ *   - `Expression` envelope `{ dialect, source }` (the normalized form
+ *     `@objectstack/spec`'s `ExpressionInputSchema` produces for every
+ *     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).
+ *
+ * ## Why the `cel` envelope must survive normalization (#2661 / #3314)
+ *
+ * `evaluateCondition` routes to the canonical `@objectstack/formula` engine —
+ * the one the SERVER enforces with — only while the argument is still a
+ * `{ dialect: 'cel' }` object. Collapse it to `${source}` first and the
+ * predicate silently falls to the legacy JS evaluator, whose semantics
+ * differ: CEL has no `<` overload for `null`, so `null < null` faults and
+ * fail-closed hides, while JS quietly yields `false`; CEL-only builtins
+ * (`today()`, objectstack#3205) do not exist on the JS path at all. Two
+ * normalizers that disagree on this one branch therefore make the SAME
+ * `visible:` predicate reach different verdicts depending on whether the
+ * action was surfaced by `ActionEngine.getActionsForLocation` or rendered
+ * standalone (#3314).
+ *
+ * This is THE implementation, not one of two — `@object-ui/core` is the common
+ * dependency of every consumer, so engine-side code and renderer-side code
+ * share one normalization instead of hand-rolling envelope unwrapping per call
+ * site. `@object-ui/react`'s `toPredicateInput` is a re-export of this function
+ * (since #3367; it used to be an independent twin held in step by a 14-shape
+ * normalization parity table, which is exactly the arrangement the paragraph
+ * above describes the failure mode of). What pins that now is the identity
+ * assertion in
+ * `packages/react/src/hooks/__tests__/actionPredicate.parity.test.tsx` — the
+ * react export must BE this function object — alongside the engine-path vs
+ * renderer-path verdict parity suite in the same file, which is a separate
+ * claim and still earns its keep: sharing a normalizer does not by itself
+ * prove the two call paths reach the same verdict.
+ */
+export function toPredicateInput(value) {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string')
+        return `\${${value}}`;
+    if (typeof value === 'object' && typeof value.source === 'string') {
+        const src = value.source;
+        if (!src)
+            return undefined;
+        // Preserve a CEL-dialect envelope so `evaluateCondition` routes it to the
+        // canonical `@objectstack/formula` engine (identical verdict to the
+        // server) instead of collapsing it onto the legacy JS path.
+        if (value.dialect === 'cel')
+            return { dialect: 'cel', source: src };
+        // Every other dialect (template / unset) keeps the legacy `${…}` behavior.
+        return `\${${src}}`;
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -48,7 +48,10 @@ export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
 export * from './utils/dataset-format.js';
+export * from './utils/dataset-pivot.js';
 export * from './utils/record-title.js';
 export * from './utils/export-filename.js';
 export * from './utils/reference-keys.js';
+export * from './utils/predicate-record.js';
+export * from './utils/predicate-fields.js';
 export * from './utils/normalize-list-view.js';

package/dist/index.js

@@ -50,7 +50,19 @@ export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
 export * from './utils/dataset-format.js';
+// Pivot lookup-key encoders, shared by every cross-tab renderer so the
+// dashboard widget and the report renderer key their buckets identically
+// (objectstack#5473 / objectstack#5665).
+export * from './utils/dataset-pivot.js';
 export * from './utils/record-title.js';
 export * from './utils/export-filename.js';
 export * from './utils/reference-keys.js';
+// Binds a fetched record into an expression scope the way the SERVER binds it
+// (a relation is its foreign key, never the expanded record) — see
+// `toPredicateRecord` for why an unnormalized one gives the same predicate
+// different verdicts on different surfaces.
+export * from './utils/predicate-record.js';
+// The other half of a view's field appetite: the fields its PREDICATES read,
+// which the column-derived `$select` never asked the server for.
+export * from './utils/predicate-fields.js';
 export * from './utils/normalize-list-view.js';

package/dist/protocols/index.d.ts

@@ -7,6 +7,5 @@
  */
 export * from './DndProtocol.js';
 export * from './KeyboardProtocol.js';
-export * from './NotificationProtocol.js';
 export * from './ResponsiveProtocol.js';
 export * from './SharingProtocol.js';

package/dist/protocols/index.js

@@ -7,6 +7,13 @@
  */
 export * from './DndProtocol.js';
 export * from './KeyboardProtocol.js';
-export * from './NotificationProtocol.js';
+// `NotificationProtocol` removed in the 17.0.0-rc.2 uptake: it bridged
+// `@objectstack/spec/ui`'s `Notification` / `NotificationConfig`, which
+// objectstack#4610 deleted with no successor. The bridge had zero consumers in
+// this repo — the live notification config resolution is
+// `resolveNotificationConfig` in `@object-ui/react`'s `NotificationContext`,
+// which declares its own `NotificationSystemConfig` and is what every surface
+// reads. Re-typing the bridge would have meant re-declaring a vocabulary the
+// spec had just retired (AGENTS.md #0.1).
 export * from './ResponsiveProtocol.js';
 export * from './SharingProtocol.js';

package/dist/utils/dataset-format.d.ts

@@ -15,6 +15,7 @@
  * Pure (no React / i18n) so it can live in `@object-ui/core` and be imported
  * by both `@object-ui/plugin-dashboard` and `@object-ui/plugin-report`.
  */
+import type { PercentScale } from '@objectstack/spec/data';
 /**
  * Column metadata the analytics server returns alongside the rows: a display
  * `label` for both dimensions and measures, plus a measure's numeral `format`
@@ -38,8 +39,12 @@ export interface DatasetResultField {
  * field's scale) and carried on the result column, so display never has to
  * infer it from the value's magnitude — the inference that printed a ratio of
  * exactly 1 as "1.0%" (#3136).
+ *
+ * Spec-owned since 17.0.0-rc.2 (`@objectstack/spec/data` exports the identical
+ * union); re-exported here so existing `@object-ui/core` consumers keep their
+ * import path.
  */
-export type PercentScale = 'fraction' | 'whole';
+export type { PercentScale } from '@objectstack/spec/data';
 /**
  * Scale a stored `percent`-field value to its DISPLAY magnitude.
  *

package/dist/utils/dataset-pivot.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.
+ */
+/**
+ * dataset-pivot — the lookup-key encoders every cross-tab over a semantic-layer
+ * `queryDataset` result shares (ADR-0021).
+ *
+ * A pivot keys three lookups off dimension-value tuples: the DOWN bucket, the
+ * ACROSS bucket, and the cell where the two meet. Every one of them used to be
+ * spelled by concatenating values with a character the data was ASSUMED never
+ * to contain — an empty string, a plain space, U+0001 — and each assumption
+ * failed on ordinary data: `"x"` + `"yz"` and `"xy"` + `"z"` are one id under an
+ * empty join, and `"New"` × `"York Q1"` and `"New York"` × `"Q1"` are one cell
+ * key under a space join. The later row silently overwrote the earlier one, so
+ * the cell showed a different row's measure, the overwritten row's value was
+ * unreachable, and drill-through followed the same wrong index into the wrong
+ * records — all without an error (objectstack#5473, objectstack#5665).
+ *
+ * `JSON.stringify` carries the boundary in its own quoting rather than in a
+ * character the values must avoid, so these are unambiguous for ANY value a
+ * dimension can hold. The ids are opaque lookup keys, never displayed — visible
+ * text comes from the separately-formatted labels.
+ *
+ * Both encoders live here, in `@object-ui/core`, because the same pivot is
+ * rendered by two packages (`plugin-dashboard`'s `DatasetWidget` and
+ * `plugin-report`'s `DatasetReportRenderer`). Each having written its own is
+ * exactly why both carried the defect and why fixing one left the other broken.
+ * The same rule applies WITHIN a renderer: the cell index and the subtotal
+ * lookups key the same buckets, so they must all call these — a second
+ * hand-rolled encoding of the same id agrees with the first only for the
+ * dimension counts someone happened to test, which is what kept the original
+ * bug invisible.
+ *
+ * Pure (no React / i18n), like its `dataset-format` neighbour.
+ *
+ * Known residual, tracked separately in objectstack#5666: callers encode a
+ * null/undefined dimension value as a placeholder string, so it still collides
+ * with a value that literally equals that placeholder. That is a property of
+ * the placeholder, not of the encoding below.
+ */
+/**
+ * Encode a pivot BUCKET id from its dimension values.
+ *
+ * Axis-neutral on purpose: a DOWN bucket and an ACROSS bucket are the same kind
+ * of thing (a dimension-value tuple), and a cross-tab with multiple across
+ * dimensions collides on that axis just as readily as on the down axis.
+ */
+export declare const pivotBucketId: (dimensionValues: string[]) => string;
+/**
+ * Encode the cell key for a (down bucket, across bucket) pair — the key of the
+ * map a renderer reads to place a measure and to resolve a drill-through.
+ */
+export declare const pivotCellKey: (rowId: string, colId: string) => string;

package/dist/utils/dataset-pivot.js

@@ -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.
+ */
+/**
+ * dataset-pivot — the lookup-key encoders every cross-tab over a semantic-layer
+ * `queryDataset` result shares (ADR-0021).
+ *
+ * A pivot keys three lookups off dimension-value tuples: the DOWN bucket, the
+ * ACROSS bucket, and the cell where the two meet. Every one of them used to be
+ * spelled by concatenating values with a character the data was ASSUMED never
+ * to contain — an empty string, a plain space, U+0001 — and each assumption
+ * failed on ordinary data: `"x"` + `"yz"` and `"xy"` + `"z"` are one id under an
+ * empty join, and `"New"` × `"York Q1"` and `"New York"` × `"Q1"` are one cell
+ * key under a space join. The later row silently overwrote the earlier one, so
+ * the cell showed a different row's measure, the overwritten row's value was
+ * unreachable, and drill-through followed the same wrong index into the wrong
+ * records — all without an error (objectstack#5473, objectstack#5665).
+ *
+ * `JSON.stringify` carries the boundary in its own quoting rather than in a
+ * character the values must avoid, so these are unambiguous for ANY value a
+ * dimension can hold. The ids are opaque lookup keys, never displayed — visible
+ * text comes from the separately-formatted labels.
+ *
+ * Both encoders live here, in `@object-ui/core`, because the same pivot is
+ * rendered by two packages (`plugin-dashboard`'s `DatasetWidget` and
+ * `plugin-report`'s `DatasetReportRenderer`). Each having written its own is
+ * exactly why both carried the defect and why fixing one left the other broken.
+ * The same rule applies WITHIN a renderer: the cell index and the subtotal
+ * lookups key the same buckets, so they must all call these — a second
+ * hand-rolled encoding of the same id agrees with the first only for the
+ * dimension counts someone happened to test, which is what kept the original
+ * bug invisible.
+ *
+ * Pure (no React / i18n), like its `dataset-format` neighbour.
+ *
+ * Known residual, tracked separately in objectstack#5666: callers encode a
+ * null/undefined dimension value as a placeholder string, so it still collides
+ * with a value that literally equals that placeholder. That is a property of
+ * the placeholder, not of the encoding below.
+ */
+/**
+ * Encode a pivot BUCKET id from its dimension values.
+ *
+ * Axis-neutral on purpose: a DOWN bucket and an ACROSS bucket are the same kind
+ * of thing (a dimension-value tuple), and a cross-tab with multiple across
+ * dimensions collides on that axis just as readily as on the down axis.
+ */
+export const pivotBucketId = (dimensionValues) => JSON.stringify(dimensionValues);
+/**
+ * Encode the cell key for a (down bucket, across bucket) pair — the key of the
+ * map a renderer reads to place a measure and to resolve a drill-through.
+ */
+export const pivotCellKey = (rowId, colId) => JSON.stringify([rowId, colId]);

package/dist/utils/filter-converter.d.ts

@@ -5,12 +5,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * Filter Converter Utilities
- *
- * Shared utilities for converting MongoDB-like filter operators
- * to ObjectStack FilterNode AST format.
- */
 /**
  * FilterNode AST type definition
  * Represents a filter condition or a logical combination of conditions
@@ -83,6 +77,36 @@ export declare function convertFiltersToAST(filter: Record<string, any>): Filter
  * `table.defaultFilters` (declared `Record<string, any>`) was DROPPED and the
  * view returned every record. Silently: no error, just a wider answer.
  *
+ * The FIRST never worked at all (objectui#3431). The array branch returned
+ * every array VERBATIM, so a saved view's `ViewFilterRule[]` travelled to
+ * `$filter` as bare rule objects — which the server refuses: `isFilterAST` is
+ * false for an array of objects, and the wire face answers `400
+ * INVALID_FILTER`. Verified against a real backend on the showcase's SHIPPED
+ * `showcase_task.in_progress` view (`filter: [{field:'status',
+ * operator:'equals', value:'in_progress'}]`): 400 as sent, 200 with its 2 rows
+ * once lowered to `[['status','equals','in_progress']]`. Every saved view
+ * carrying a filter was a failed list. `mergeFilterNodes` below has warned
+ * about exactly this hazard since it was written — the warning was accurate,
+ * and the sink it warns for never implemented the lowering it describes.
+ *
+ * **Why the fold lives HERE and not at the producer.** `ListViewSchema.filter`
+ * / `ViewTab.filter` are spec-declared `z.array(ViewFilterRuleSchema)`, and a
+ * view hands a renderer a `ListViewSchema` — so folding one hop earlier (in
+ * `app-shell`'s ObjectView, say) would write ObjectQL AST triples INTO a
+ * spec-declared rule-array slot: an off-spec value in a spec field, AGENTS.md
+ * #0.1 inverted. This function is the last hop before the wire, where the value
+ * legitimately leaves the spec's view vocabulary and becomes an ObjectQL AST.
+ * It is also the single sink both producers already share — `plugin-list`'s
+ * `buildEffectiveFilter` (which feeds the grid AND the export) and
+ * `plugin-view`'s ObjectView (calendar / kanban / gallery / timeline). One
+ * lowering, one place; the same reason the MongoDB-style shape is lowered here
+ * rather than at each of its callers.
+ *
+ * Mixed arrays fold ELEMENT-WISE, because that is what reaches this function in
+ * practice: `ObjectView` concatenates a saved view's rules with the
+ * `?filter[<field>]=<value>` URL triples into one array. Triples pass through
+ * untouched.
+ *
  * Returns `undefined` for an absent or empty source, so callers can skip
  * `$filter` rather than sending an empty array.
  */
@@ -92,11 +116,15 @@ export declare function toFilterNode(source: unknown): FilterNode | Record<strin
  *
  * Wrapping rather than spreading, on purpose. `['and', ...rules]` looks
  * equivalent and is not: spreading a `ViewFilterRule[]` puts bare rule OBJECTS
- * where the AST expects nodes, and the server neither understands nor rejects
- * that cleanly — `isFilterAST` says no (a 400 since objectstack#4121), while
- * `parseFilterAST` reads the rule as a Mongo condition and filters on columns
- * literally named `field` / `operator` / `value`. Spreading is only correct
- * when the source happens to be an array of nodes, which is why it survived.
+ * where the AST expects nodes, and the server does not accept that —
+ * `isFilterAST` says no and the wire face answers `400 INVALID_FILTER`
+ * (objectstack#4121). Spreading is only correct when the source happens to be
+ * an array of nodes, which is why it survived.
+ *
+ * Since objectui#3431 the rule objects never reach that position anyway:
+ * `toFilterNode` lowers a `ViewFilterRule[]` to AST nodes on the way in. The
+ * paragraph above is kept because it is why each source stays its own child —
+ * and because it correctly diagnosed the bug the sink itself was carrying.
  *
  * Sources that normalize to nothing are skipped; one surviving source is
  * returned as-is rather than wrapped in a pointless `and`.

package/dist/utils/filter-converter.js

@@ -5,6 +5,13 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * Filter Converter Utilities
+ *
+ * Shared utilities for converting MongoDB-like filter operators
+ * to ObjectStack FilterNode AST format.
+ */
+import { normalizeFilterOperator } from '@objectstack/spec/ui';
 /**
  * Map MongoDB-like operators to ObjectStack filter operators.
  *
@@ -152,6 +159,37 @@ export function convertFiltersToAST(filter) {
     // Multiple conditions: combine with 'and'
     return ['and', ...conditions];
 }
+function isViewFilterRule(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const field = value.field;
+    return typeof field === 'string' && field !== '';
+}
+/**
+ * Lower ONE spec `ViewFilterRule` to an ObjectQL AST comparison node.
+ *
+ * The operator goes through the spec's OWN {@link normalizeFilterOperator} —
+ * the exact exit the WRITE side uses (`app-shell/views/viewFilterFold.ts`), so
+ * the two directions cannot drift into two dialects. No second canonical map is
+ * introduced, and none is needed: all 19 `VIEW_FILTER_OPERATORS` are already
+ * members of the wire's `VALID_AST_OPERATORS`, so the lowering is purely
+ * structural. An operator the spec does not know is passed through VERBATIM, so
+ * `isFilterAST` still refuses it and the server still answers `400
+ * INVALID_FILTER` — a misspelling must not be coerced into a valid one.
+ *
+ * `value` is emitted only when the rule carries one. A rule that omits it
+ * (`is_empty` / `is_null`, whose direction comes from the operator NAME) would
+ * otherwise gain an invented `null` the author never wrote — `JSON.stringify`
+ * turns a hole in an array into `null`, and `['x', 'equals', null]` is a real
+ * `{x: null}` predicate, i.e. a silently-wrong filter. Same rule the write side
+ * applies (`if (c.value !== undefined)`).
+ */
+function viewFilterRuleToNode(rule) {
+    const operator = normalizeFilterOperator(rule.operator);
+    return (rule.value === undefined
+        ? [rule.field, operator]
+        : [rule.field, operator, rule.value]);
+}
 /**
  * Normalize ONE filter source into a single filter node.
  *
@@ -167,14 +205,52 @@ export function convertFiltersToAST(filter) {
  * `table.defaultFilters` (declared `Record<string, any>`) was DROPPED and the
  * view returned every record. Silently: no error, just a wider answer.
  *
+ * The FIRST never worked at all (objectui#3431). The array branch returned
+ * every array VERBATIM, so a saved view's `ViewFilterRule[]` travelled to
+ * `$filter` as bare rule objects — which the server refuses: `isFilterAST` is
+ * false for an array of objects, and the wire face answers `400
+ * INVALID_FILTER`. Verified against a real backend on the showcase's SHIPPED
+ * `showcase_task.in_progress` view (`filter: [{field:'status',
+ * operator:'equals', value:'in_progress'}]`): 400 as sent, 200 with its 2 rows
+ * once lowered to `[['status','equals','in_progress']]`. Every saved view
+ * carrying a filter was a failed list. `mergeFilterNodes` below has warned
+ * about exactly this hazard since it was written — the warning was accurate,
+ * and the sink it warns for never implemented the lowering it describes.
+ *
+ * **Why the fold lives HERE and not at the producer.** `ListViewSchema.filter`
+ * / `ViewTab.filter` are spec-declared `z.array(ViewFilterRuleSchema)`, and a
+ * view hands a renderer a `ListViewSchema` — so folding one hop earlier (in
+ * `app-shell`'s ObjectView, say) would write ObjectQL AST triples INTO a
+ * spec-declared rule-array slot: an off-spec value in a spec field, AGENTS.md
+ * #0.1 inverted. This function is the last hop before the wire, where the value
+ * legitimately leaves the spec's view vocabulary and becomes an ObjectQL AST.
+ * It is also the single sink both producers already share — `plugin-list`'s
+ * `buildEffectiveFilter` (which feeds the grid AND the export) and
+ * `plugin-view`'s ObjectView (calendar / kanban / gallery / timeline). One
+ * lowering, one place; the same reason the MongoDB-style shape is lowered here
+ * rather than at each of its callers.
+ *
+ * Mixed arrays fold ELEMENT-WISE, because that is what reaches this function in
+ * practice: `ObjectView` concatenates a saved view's rules with the
+ * `?filter[<field>]=<value>` URL triples into one array. Triples pass through
+ * untouched.
+ *
  * Returns `undefined` for an absent or empty source, so callers can skip
  * `$filter` rather than sending an empty array.
  */
 export function toFilterNode(source) {
     if (source === null || source === undefined)
         return undefined;
-    if (Array.isArray(source))
-        return source.length > 0 ? source : undefined;
+    if (Array.isArray(source)) {
+        if (source.length === 0)
+            return undefined;
+        // Spec `ViewFilterRule[]` (possibly mixed with AST nodes) → AST nodes. Left
+        // untouched when the array holds no rule objects, which is the common case:
+        // user-filter conditions and URL triples are already nodes.
+        return (source.some(isViewFilterRule)
+            ? source.map((el) => (isViewFilterRule(el) ? viewFilterRuleToNode(el) : el))
+            : source);
+    }
     if (typeof source !== 'object')
         return undefined;
     const obj = source;
@@ -188,11 +264,15 @@ export function toFilterNode(source) {
  *
  * Wrapping rather than spreading, on purpose. `['and', ...rules]` looks
  * equivalent and is not: spreading a `ViewFilterRule[]` puts bare rule OBJECTS
- * where the AST expects nodes, and the server neither understands nor rejects
- * that cleanly — `isFilterAST` says no (a 400 since objectstack#4121), while
- * `parseFilterAST` reads the rule as a Mongo condition and filters on columns
- * literally named `field` / `operator` / `value`. Spreading is only correct
- * when the source happens to be an array of nodes, which is why it survived.
+ * where the AST expects nodes, and the server does not accept that —
+ * `isFilterAST` says no and the wire face answers `400 INVALID_FILTER`
+ * (objectstack#4121). Spreading is only correct when the source happens to be
+ * an array of nodes, which is why it survived.
+ *
+ * Since objectui#3431 the rule objects never reach that position anyway:
+ * `toFilterNode` lowers a `ViewFilterRule[]` to AST nodes on the way in. The
+ * paragraph above is kept because it is why each source stays its own child —
+ * and because it correctly diagnosed the bug the sink itself was carrying.
  *
  * Sources that normalize to nothing are skipped; one surviving source is
  * returned as-is rather than wrapped in a pointless `and`.

package/dist/utils/predicate-fields.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ObjectUI — predicate field harvesting
+ * 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.
+ */
+/**
+ * Which record fields a view's PREDICATES read — the half of a view's field
+ * appetite that is not its columns.
+ *
+ * A list view projects what it DISPLAYS: `$select` is built from the column
+ * list (plus `id` and the expanded relation roots). That is correct for
+ * rendering and wrong for gating, because a `visible` / `disabled` /
+ * conditional-formatting predicate reads fields nobody put on screen — gating a
+ * row action on `record.owner` while showing Title / Status is the ordinary
+ * case, not an exotic one.
+ *
+ * The field then simply is not in the payload, and CEL does not treat an absent
+ * key as null: `record.owner == os.user.id` FAULTS with `No such key: owner`.
+ * Fault handling differs per surface and both answers are wrong — fail-CLOSED
+ * on the row kebab and the selection bar (the button silently disappears for
+ * everyone), fail-OPEN on the lenient paths (it appears for everyone). Nothing
+ * in either outcome points at a projection.
+ *
+ * Harvesting the names a predicate mentions and adding them to `$select` is
+ * what closes that. Note what it deliberately does NOT add: `$expand`. A
+ * predicate wants the stored foreign key, which is exactly what an unexpanded
+ * relation column already is — so a predicate-only relation field costs one
+ * more column and no extra round trip. (A relation that IS displayed still gets
+ * expanded for its label, and `toPredicateRecord` collapses it back for the
+ * predicate.)
+ */
+/**
+ * The columns the framework provisions on EVERY business object
+ * (`applySystemFields`) but does not publish in the object's `fields` metadata.
+ *
+ * They matter here because the most ordinary ownership predicate there is —
+ * `record.owner_id == os.user.id` — names one of them. Checking a harvested
+ * name against the declared fields alone would drop it, leaving the predicate
+ * with the same missing key the harvest exists to prevent.
+ *
+ * Deliberately the columns OBSERVED on a live payload rather than
+ * `SYSTEM_MANAGED_FIELD_NAMES` (`@object-ui/types`), which is the broader
+ * DISPLAY-oriented set and carries legacy aliases (`_id`, `createdAt`,
+ * `modified`, `space`) that are not columns anywhere. An alias in `$select` is
+ * exactly the unknown key the guard exists to keep out.
+ */
+export declare const PLATFORM_RECORD_COLUMNS: ReadonlySet<string>;
+/**
+ * Whether a harvested name is safe to put in a `$select` projection: either the
+ * object declares it, or it is one of the platform columns every object has.
+ *
+ * The check is not pedantry — an unknown key is not ignored by every backend
+ * (the cloud multi-tenant runtime answers with an EMPTY result set), so without
+ * it one typo'd predicate could blank a whole list.
+ */
+export declare function isProjectableField(name: string, declaredFields: Record<string, unknown> | null | undefined): boolean;
+/**
+ * Collect the record field names referenced by a set of predicates.
+ *
+ * Accepts predicates in every authored shape (bare CEL string, the
+ * `{ dialect, source }` envelope, `null`/`undefined`/boolean — the last three
+ * contribute nothing). Returns names in first-seen order, deduplicated.
+ *
+ * The result is a set of CANDIDATES, not verified fields: a typo'd predicate
+ * yields a name this object does not have. Callers must intersect it with the
+ * object's declared fields before putting it in a query — an unknown key in
+ * `$select` is not ignored by every backend (the cloud runtime answers with an
+ * empty result set), which would turn a typo into a blank list.
+ */
+export declare function collectPredicateFieldRefs(predicates: readonly unknown[]): string[];
+/**
+ * Every predicate a list-ish view carries, flattened for
+ * {@link collectPredicateFieldRefs}.
+ *
+ * One reader so the projection cannot fall behind the surfaces: each entry here
+ * is a place a predicate is actually evaluated against a row — conditional
+ * formatting, the row kebab (custom defs AND the built-in Edit/Delete
+ * overrides), the selection bar, and the object's declared actions.
+ *
+ * `objectActions` is deliberately the object's WHOLE action set rather than
+ * only the ones this view promotes. Narrowing it would mean re-running the
+ * name resolution `resolveLegacyRowActions` / `resolveBulkActions` already do,
+ * at a point in the fetch where the view's `rowActions` / `bulkActions` lists
+ * have not been folded yet — and the two directions of error are not
+ * symmetric: an extra column costs bytes, a missing one silently breaks the
+ * predicate that needed it.
+ */
+export declare function listViewPredicates(view: {
+    conditionalFormatting?: readonly unknown[] | null;
+    rowActionDefs?: readonly unknown[] | null;
+    bulkActionDefs?: readonly unknown[] | null;
+    objectActions?: readonly unknown[] | null;
+    userActions?: Record<string, unknown> | null;
+}): unknown[];