@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/number-display.js

@@ -9,11 +9,23 @@
  * The grouping policy, alone and testable: does this number get thousands
  * separators?
  *
- * @param scale    the field's declared `scale`, or `undefined` when the caller
- *                 has no field declaration behind it
- * @param currency ISO 4217 code when the number is money
+ * This is the ONE place the decision is made. An authored `useGrouping`
+ * answers it outright; only when the field declared nothing does the
+ * `scale`/`currency` heuristic below get a say (objectui#11026).
+ *
+ * @param scale       the field's declared `scale`, or `undefined` when the
+ *                    caller has no field declaration behind it
+ * @param currency    ISO 4217 code when the number is money
+ * @param useGrouping the field's authored `useGrouping`, or `undefined` when
+ *                    the author declared none
  */
-export function shouldGroupDisplayNumber(scale, currency) {
+export function shouldGroupDisplayNumber(scale, currency, useGrouping) {
+    // The author's explicit declaration beats every guess below, money included:
+    // the spec reads `false` as "never grouped, regardless of what the
+    // renderer's heuristic would have guessed", and `true` as the same override
+    // in the other direction.
+    if (typeof useGrouping === 'boolean')
+        return useGrouping;
     // Money always groups — including money whose currency code could not be
     // resolved, which still renders as an amount (just without a symbol).
     if (currency)
@@ -32,7 +44,7 @@ export function shouldGroupDisplayNumber(scale, currency) {
  * malformed tag from a tenant config must never take a grid cell down.
  */
 export function formatDisplayNumber(value, options = {}) {
-    const { locale, currency, scale, style, ...passthrough } = options;
+    const { locale, currency, scale, useGrouping, style, ...passthrough } = options;
     const intlOptions = { ...passthrough };
     if (style === 'percentPoints') {
         // The locale's percent convention WITHOUT `style: 'percent'`'s ×100 — see
@@ -50,15 +62,25 @@ export function formatDisplayNumber(value, options = {}) {
         delete intlOptions.unit;
         delete intlOptions.unitDisplay;
     }
-    // ⚠️ Set `useGrouping` ONLY to suppress. `useGrouping: true` is NOT the same
-    // as omitting the key: `true` means "always", while omitting it means "auto"
-    // (and "min2" under compact notation), which is the locale's own preference.
-    // Measured — for 1234: es-ES "auto" → `1234` but "always" → `1.234`; pl-PL
-    // "auto" → `1234` but "always" → `1 234`. Writing `true` here would silently
-    // override those locales' conventions in the name of preserving en-US output.
-    if (!shouldGroupDisplayNumber(scale, currency)) {
+    // ⚠️ Never write `useGrouping: true` on the renderer's own behalf.
+    // `useGrouping: true` is NOT the same as omitting the key: `true` means
+    // "always", while omitting it means "auto" (and "min2" under compact
+    // notation), which is the locale's own preference. Measured — for 1234:
+    // es-ES "auto" → `1234` but "always" → `1.234`; pl-PL "auto" → `1234` but
+    // "always" → `1 234`. Writing `true` for a field that declared nothing would
+    // silently override those locales' conventions in the name of preserving
+    // en-US output.
+    //
+    // The ONE `true` this function writes is the author's own (objectui#11026):
+    // `FieldSchema.useGrouping` maps 1:1 onto this `Intl` option, and an author
+    // who pinned grouping on asked for "always". The decision itself is made
+    // once, above, by `shouldGroupDisplayNumber`; this only spells it for `Intl`.
+    if (!shouldGroupDisplayNumber(scale, currency, useGrouping)) {
         intlOptions.useGrouping = false;
     }
+    else if (useGrouping === true) {
+        intlOptions.useGrouping = true;
+    }
     try {
         return new Intl.NumberFormat(locale, intlOptions).format(value);
     }

package/dist/utils/object-aggregate-query.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+/**
+ * object-aggregate-query — the ONE answer to "which CALL does an object-bound
+ * `aggregate` make when its authored `groupBy` is the structured node?"
+ * (objectui#8613).
+ *
+ * ## The two wires, and why the choice is not cosmetic
+ *
+ * An authored `aggregate.groupBy` is a union: a bare field name, or the
+ * structured date-bucketing node `{ field, dateGranularity?, alias? }` — the
+ * union `ChartGroupBySchema` declares and `GroupByNodeSchema` (the query AST)
+ * mirrors. The adapter routes on the SHAPE of the params it is handed, not on
+ * the shape of the authored value:
+ *
+ *   - `{ groupBy: GroupByNode[], aggregations, where }` — the spec-shape query,
+ *     which reaches `engine.aggregate` and runs the server-side date-bucket
+ *     engine;
+ *   - `{ field, function, groupBy, filter }` — the legacy cube/analytics query,
+ *     whose `dimensions` the contract declares as an array of dimension NAMES
+ *     and which does NOT honour `dateGranularity` at all.
+ *
+ * So a structured node forwarded on the legacy wire is posted as a dimension
+ * OBJECT where a name is declared: the author asks for monthly buckets and the
+ * platform answers a different question, with no diagnostic on the way. That is
+ * the defect objectui#8613 records on the metric path, and it was reachable
+ * there only because this payload was spelled INSIDE one renderer
+ * (`ObjectChart.runAggregate`) rather than anywhere a second renderer could
+ * reuse it.
+ *
+ * ## Why a shared module rather than a second copy
+ *
+ * The alternative was to transcribe the eight lines into the metric widget.
+ * That is the objectui#5042 / #7544 / #8193 / #8266 / #8269 drift shape — a
+ * second opinion of one question, with nothing keeping the two in agreement —
+ * and it is the same shape those cards' fixes (`chartMeasureKey`,
+ * `chartCategoryKey`) exist to end, one column at a time. This module is that
+ * move applied to the REQUEST rather than to a result column.
+ *
+ * ## What is NOT here
+ *
+ * The legacy bag itself. The two renderers do not agree on it and should not be
+ * made to: a chart passes the authored `groupBy` through untouched, while a
+ * metric floors an absent one at `'_all'` (one bucket) because it paints a
+ * single number. Folding that difference into a shared builder would put a
+ * renderer's own default into a module that has no business holding one, so the
+ * shared part stops exactly where the agreement stops.
+ */
+import type { ChartGroupBy } from '@objectstack/spec/ui';
+import { type ChartAggregateLike } from './chart-measure-key.js';
+/**
+ * The STRUCTURED arm of the contract's `groupBy` union — the date-bucketing
+ * node, as distinct from the bare field name the same union admits.
+ *
+ * Extracted from `ChartGroupBy` rather than restated, so a member added to the
+ * node upstream (as `alias` once was) arrives here without an edit.
+ */
+export type StructuredGroupBy = Extract<ChartGroupBy, {
+    field: string;
+}>;
+/**
+ * The spec-shape aggregate query's `aggregations[]` entry, as
+ * `AggregationNodeSchema` declares it: `alias` is REQUIRED (it names the column
+ * the measure is projected under), `field` is optional because a `count` counts
+ * rows rather than a column.
+ */
+export interface ObjectAggregationNode {
+    function?: string;
+    alias: string;
+    field?: string;
+}
+/** The spec-shape query body — `{ groupBy: GroupByNode[], aggregations, where }`. */
+export interface ObjectAggregateSpecQuery {
+    groupBy: StructuredGroupBy[];
+    aggregations: ObjectAggregationNode[];
+    where: unknown;
+}
+/**
+ * Is this authored `aggregate.groupBy` the structured node rather than a bare
+ * field name?
+ *
+ * ⚠️ An ARRAY answers `false`. It is an object, but it is not this union's
+ * object arm — neither `ChartGroupBySchema` nor `ObjectMetricPropsSchema`'s
+ * `aggregate` admits one at this position, and `data-objectstack`'s adapter
+ * already refuses it at the wire (`503cd8b89`). Letting it through here would
+ * wrap it into `groupBy: [[…]]` and turn a producer-side refusal into a
+ * malformed query.
+ */
+export declare function isStructuredGroupBy(groupBy: unknown): groupBy is StructuredGroupBy;
+/**
+ * The spec-shape aggregate query for an object-bound `aggregate` whose
+ * `groupBy` is the structured node.
+ *
+ * The measure is projected under {@link chartMeasureKey}'s answer — the raw
+ * field name, or the literal `'count'` for a fieldless count — so a caller's
+ * existing result readback finds the value under the key it already looks for,
+ * and a chart's series binding names the column the rows actually carry.
+ *
+ * `field` is omitted for `count` so the engine emits `count(*)`: the dashboard
+ * relays default `field: 'value'` for a widget with no explicit measure column,
+ * and `count(value)` crashes SQL drivers with "no such column: value" on the
+ * count-the-rows case that is the common one.
+ *
+ * @param aggregate the authored inline aggregate
+ * @param groupBy   its `groupBy`, already narrowed by {@link isStructuredGroupBy}
+ * @param where     the resolved filter, in the spec Query DSL's `where` position
+ */
+export declare function objectAggregateSpecQuery(aggregate: ChartAggregateLike, groupBy: StructuredGroupBy, where: unknown): ObjectAggregateSpecQuery;

package/dist/utils/object-aggregate-query.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+import { chartMeasureKey } from './chart-measure-key.js';
+/**
+ * Is this authored `aggregate.groupBy` the structured node rather than a bare
+ * field name?
+ *
+ * ⚠️ An ARRAY answers `false`. It is an object, but it is not this union's
+ * object arm — neither `ChartGroupBySchema` nor `ObjectMetricPropsSchema`'s
+ * `aggregate` admits one at this position, and `data-objectstack`'s adapter
+ * already refuses it at the wire (`503cd8b89`). Letting it through here would
+ * wrap it into `groupBy: [[…]]` and turn a producer-side refusal into a
+ * malformed query.
+ */
+export function isStructuredGroupBy(groupBy) {
+    return !!groupBy && typeof groupBy === 'object' && !Array.isArray(groupBy);
+}
+/**
+ * The spec-shape aggregate query for an object-bound `aggregate` whose
+ * `groupBy` is the structured node.
+ *
+ * The measure is projected under {@link chartMeasureKey}'s answer — the raw
+ * field name, or the literal `'count'` for a fieldless count — so a caller's
+ * existing result readback finds the value under the key it already looks for,
+ * and a chart's series binding names the column the rows actually carry.
+ *
+ * `field` is omitted for `count` so the engine emits `count(*)`: the dashboard
+ * relays default `field: 'value'` for a widget with no explicit measure column,
+ * and `count(value)` crashes SQL drivers with "no such column: value" on the
+ * count-the-rows case that is the common one.
+ *
+ * @param aggregate the authored inline aggregate
+ * @param groupBy   its `groupBy`, already narrowed by {@link isStructuredGroupBy}
+ * @param where     the resolved filter, in the spec Query DSL's `where` position
+ */
+export function objectAggregateSpecQuery(aggregate, groupBy, where) {
+    const aggFn = aggregate.function;
+    const node = {
+        function: aggFn,
+        alias: chartMeasureKey(aggregate, aggFn || 'count'),
+    };
+    if (aggFn !== 'count' && aggregate.field)
+        node.field = aggregate.field;
+    return { groupBy: [groupBy], aggregations: [node], where };
+}

package/dist/utils/parent-scope.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 parent-relationship condition a detail-page related list is scoped by —
+ * compiled ONCE, here, for every surface that asks the question.
+ *
+ * ## Why this is a seam and not a helper
+ *
+ * A related list asks its backend "which children belong to this parent?" from
+ * two places: the ROW query (`RelatedList`) and the tab-badge count probe
+ * (`RelatedCountStore`). Those two used to compile the condition separately,
+ * and objectui#8882 is what that costs: objectui#7299 taught the ROW side to
+ * compile by the relationship field's ARITY, the BADGE side kept sending bare
+ * equality, and on a multi-value relationship the page then rendered rows above
+ * a tab with no count at all — two implementations of one question, drifted.
+ *
+ * Patching the second copy to match the first would leave two copies. So the
+ * condition has one implementation, and both callers import it.
+ *
+ * ## The rule itself is not invented here
+ *
+ * The arity verdict is `@objectstack/spec/data`'s own `isMultiValueField`. That
+ * matters more here than anywhere: this function chooses `$contains` vs `=` and
+ * every surface that asks the question now reads that one choice, so two
+ * readers of one question disagreeing — the entire defect class — cannot
+ * recur INSIDE this repository. The spec's rule is BROADER than an eyeballed
+ * `multiple === true` in both directions — `multiselect` / `checkboxes` /
+ * `tags` persist an array with no flag at all, and `multiple: true` is INERT on
+ * a type outside the spec's multi-capable set (`master_detail`, say) — so a
+ * local approximation is wrong in both directions, not merely incomplete.
+ *
+ * ⛔ Do not add a local arity rule at any call site, however small, and ⛔ do
+ * not widen this function to accept an arity the caller computed: the parameter
+ * it takes is METADATA, and the verdict is drawn from it here.
+ *
+ * ## ⚠️ The STORAGE side does not read this predicate — the two rules DIVERGE
+ *
+ * This header used to say `isMultiValueField` is "the same predicate the driver
+ * that executes the query decides on". It is not, and the difference is
+ * observable (objectui#8937). Measured on objectstack `origin/main`,
+ * `driver-sql` gates the equality family on its own STORAGE question,
+ * `isJsonField`: a column is JSON when the field's type is in that driver's
+ * `JSON_COLUMN_TYPES` — the spec's `STRUCTURED_JSON_TYPES` and
+ * `MULTI_OPTION_TYPES`, plus the driver-internal `object` / `array` aliases —
+ * OR when `multiple` is merely TRUTHY, on ANY type; a single-value media type
+ * answers from the ADR-0104 dual-encoding window instead. The spec's predicate
+ * is `MULTI_OPTION_TYPES.has(type) || (MULTI_CAPABLE_TYPES.has(type) &&
+ * multiple === true)`.
+ *
+ * ⇒ They diverge for a type OUTSIDE `MULTI_CAPABLE_TYPES` carrying
+ * `multiple: true` (`master_detail` / `tree` / `text`): the spec says
+ * single-valued, so this seam compiles `=`, while the driver stores a JSON
+ * column and refuses `=` with the same `400 INVALID_FILTER` objectui#7299 was
+ * filed for. That is a KNOWN divergence and ⛔ not a regression — both
+ * surfaces sent `=` for that shape before objectui#7299 and objectui#8882 too.
+ *
+ * ⛔ Do NOT close it by widening the predicate here: which of the two rules is
+ * right is an upstream question, filed as objectstack#17469 (enforce-or-align),
+ * and this seam is deliberately not blocked on it. Widening on this side would
+ * move the disagreement across the wire rather than end it, and would make the
+ * ONE compiler this module exists to be disagree with the spec it delegates to.
+ * The divergence is re-derived from the installed spec on every run by
+ * `relatedListParentScopeResidue-8937.test.ts`, so this section reddens when the
+ * spec side moves.
+ */
+import { type ValueShapeFieldDef } from '@objectstack/spec/data';
+import type { FieldContainerLike } from './predicate-record.js';
+/**
+ * Look one field def up in either container shape the metadata API serves.
+ *
+ * The pair is the one {@link FieldContainerLike} names: the Record keyed by
+ * field name, and the array of defs carrying their own `name`. A reader that
+ * knows only one of them silently answers "no such field" for the other — and
+ * "no such field" here means "single-valued", which is this card's own bug
+ * spelled as a default.
+ */
+export declare function parentRelationshipFieldDef(fields: FieldContainerLike, fieldName: string | undefined): ValueShapeFieldDef | undefined;
+/**
+ * Does this relationship field store MANY parent ids rather than one?
+ *
+ * The seam's verdict, exposed on its own because a caller sometimes needs the
+ * ANSWER without the condition — the raw-URL related-list path, whose
+ * `filter[<field>]=<value>` grammar has no membership operator, has to know
+ * the arity in order to REFUSE. Deriving it a second time at that call site is
+ * how the two compilers this module exists to merge came about, so it is
+ * derived once here and read from both shapes below.
+ */
+export declare function isMultiValueRelationship(fields: FieldContainerLike, fieldName: string | undefined): boolean;
+/**
+ * The parent-relationship condition, compiled to match the field's ARITY.
+ *
+ *   - single-valued → `{ [relationshipField]: parentId }` — equality, byte for
+ *     byte what both surfaces have always sent;
+ *   - `multiple: true` (per the spec predicate) →
+ *     `{ [relationshipField]: { $contains: parentId } }` — MEMBERSHIP, because
+ *     the stored value is an ARRAY of ids and equality asks whether that whole
+ *     array IS one id. `$contains` is the spelling the drivers execute for it,
+ *     the one `driver-sql` names in the `400 INVALID_FILTER` it answers the
+ *     equality form with.
+ *
+ * The author never writes either: they named a relationship, and its storage
+ * form is the renderer's business.
+ *
+ * The return value is the plain MongoDB-style object both call sites have
+ * always put on the wire, NOT a lowered ObjectQL AST. That is deliberate: with
+ * nothing else declared the query must stay byte-identical to what it was, and
+ * a freshly lowered AST would mean the same thing, be invisible on screen, and
+ * break every caller pinning the wire. Composition with a list's own declared
+ * scope stays the caller's step, through `mergeFilterNodes`.
+ *
+ * @param relationshipField  The child field pointing back at the parent.
+ * @param parentId           The parent record's primary key value.
+ * @param fields             The CHILD object's field defs (`objectSchema.fields`),
+ *                           in either served shape. Without them the condition
+ *                           compiles to equality — the historical wire, and the
+ *                           only answer available to a caller that cannot see
+ *                           the metadata. A caller that CAN see it must pass it.
+ */
+export declare function composeParentScopeFilter(relationshipField: string, parentId: string | number, fields?: FieldContainerLike): Record<string, unknown>;

package/dist/utils/parent-scope.js

@@ -0,0 +1,140 @@
+/**
+ * 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 parent-relationship condition a detail-page related list is scoped by —
+ * compiled ONCE, here, for every surface that asks the question.
+ *
+ * ## Why this is a seam and not a helper
+ *
+ * A related list asks its backend "which children belong to this parent?" from
+ * two places: the ROW query (`RelatedList`) and the tab-badge count probe
+ * (`RelatedCountStore`). Those two used to compile the condition separately,
+ * and objectui#8882 is what that costs: objectui#7299 taught the ROW side to
+ * compile by the relationship field's ARITY, the BADGE side kept sending bare
+ * equality, and on a multi-value relationship the page then rendered rows above
+ * a tab with no count at all — two implementations of one question, drifted.
+ *
+ * Patching the second copy to match the first would leave two copies. So the
+ * condition has one implementation, and both callers import it.
+ *
+ * ## The rule itself is not invented here
+ *
+ * The arity verdict is `@objectstack/spec/data`'s own `isMultiValueField`. That
+ * matters more here than anywhere: this function chooses `$contains` vs `=` and
+ * every surface that asks the question now reads that one choice, so two
+ * readers of one question disagreeing — the entire defect class — cannot
+ * recur INSIDE this repository. The spec's rule is BROADER than an eyeballed
+ * `multiple === true` in both directions — `multiselect` / `checkboxes` /
+ * `tags` persist an array with no flag at all, and `multiple: true` is INERT on
+ * a type outside the spec's multi-capable set (`master_detail`, say) — so a
+ * local approximation is wrong in both directions, not merely incomplete.
+ *
+ * ⛔ Do not add a local arity rule at any call site, however small, and ⛔ do
+ * not widen this function to accept an arity the caller computed: the parameter
+ * it takes is METADATA, and the verdict is drawn from it here.
+ *
+ * ## ⚠️ The STORAGE side does not read this predicate — the two rules DIVERGE
+ *
+ * This header used to say `isMultiValueField` is "the same predicate the driver
+ * that executes the query decides on". It is not, and the difference is
+ * observable (objectui#8937). Measured on objectstack `origin/main`,
+ * `driver-sql` gates the equality family on its own STORAGE question,
+ * `isJsonField`: a column is JSON when the field's type is in that driver's
+ * `JSON_COLUMN_TYPES` — the spec's `STRUCTURED_JSON_TYPES` and
+ * `MULTI_OPTION_TYPES`, plus the driver-internal `object` / `array` aliases —
+ * OR when `multiple` is merely TRUTHY, on ANY type; a single-value media type
+ * answers from the ADR-0104 dual-encoding window instead. The spec's predicate
+ * is `MULTI_OPTION_TYPES.has(type) || (MULTI_CAPABLE_TYPES.has(type) &&
+ * multiple === true)`.
+ *
+ * ⇒ They diverge for a type OUTSIDE `MULTI_CAPABLE_TYPES` carrying
+ * `multiple: true` (`master_detail` / `tree` / `text`): the spec says
+ * single-valued, so this seam compiles `=`, while the driver stores a JSON
+ * column and refuses `=` with the same `400 INVALID_FILTER` objectui#7299 was
+ * filed for. That is a KNOWN divergence and ⛔ not a regression — both
+ * surfaces sent `=` for that shape before objectui#7299 and objectui#8882 too.
+ *
+ * ⛔ Do NOT close it by widening the predicate here: which of the two rules is
+ * right is an upstream question, filed as objectstack#17469 (enforce-or-align),
+ * and this seam is deliberately not blocked on it. Widening on this side would
+ * move the disagreement across the wire rather than end it, and would make the
+ * ONE compiler this module exists to be disagree with the spec it delegates to.
+ * The divergence is re-derived from the installed spec on every run by
+ * `relatedListParentScopeResidue-8937.test.ts`, so this section reddens when the
+ * spec side moves.
+ */
+import { isMultiValueField } from '@objectstack/spec/data';
+/**
+ * Look one field def up in either container shape the metadata API serves.
+ *
+ * The pair is the one {@link FieldContainerLike} names: the Record keyed by
+ * field name, and the array of defs carrying their own `name`. A reader that
+ * knows only one of them silently answers "no such field" for the other — and
+ * "no such field" here means "single-valued", which is this card's own bug
+ * spelled as a default.
+ */
+export function parentRelationshipFieldDef(fields, fieldName) {
+    if (!fieldName || !fields || typeof fields !== 'object')
+        return undefined;
+    const def = Array.isArray(fields)
+        ? fields.find((f) => f?.name === fieldName)
+        : fields[fieldName];
+    if (!def || typeof def !== 'object')
+        return undefined;
+    // `type` is the one member the spec's predicate reads besides `multiple`; a
+    // def without it answers `false` through both of the predicate's set lookups,
+    // which is the right answer for a field whose type nobody declared.
+    return def;
+}
+/**
+ * Does this relationship field store MANY parent ids rather than one?
+ *
+ * The seam's verdict, exposed on its own because a caller sometimes needs the
+ * ANSWER without the condition — the raw-URL related-list path, whose
+ * `filter[<field>]=<value>` grammar has no membership operator, has to know
+ * the arity in order to REFUSE. Deriving it a second time at that call site is
+ * how the two compilers this module exists to merge came about, so it is
+ * derived once here and read from both shapes below.
+ */
+export function isMultiValueRelationship(fields, fieldName) {
+    const def = parentRelationshipFieldDef(fields, fieldName);
+    return def !== undefined && isMultiValueField(def);
+}
+/**
+ * The parent-relationship condition, compiled to match the field's ARITY.
+ *
+ *   - single-valued → `{ [relationshipField]: parentId }` — equality, byte for
+ *     byte what both surfaces have always sent;
+ *   - `multiple: true` (per the spec predicate) →
+ *     `{ [relationshipField]: { $contains: parentId } }` — MEMBERSHIP, because
+ *     the stored value is an ARRAY of ids and equality asks whether that whole
+ *     array IS one id. `$contains` is the spelling the drivers execute for it,
+ *     the one `driver-sql` names in the `400 INVALID_FILTER` it answers the
+ *     equality form with.
+ *
+ * The author never writes either: they named a relationship, and its storage
+ * form is the renderer's business.
+ *
+ * The return value is the plain MongoDB-style object both call sites have
+ * always put on the wire, NOT a lowered ObjectQL AST. That is deliberate: with
+ * nothing else declared the query must stay byte-identical to what it was, and
+ * a freshly lowered AST would mean the same thing, be invisible on screen, and
+ * break every caller pinning the wire. Composition with a list's own declared
+ * scope stays the caller's step, through `mergeFilterNodes`.
+ *
+ * @param relationshipField  The child field pointing back at the parent.
+ * @param parentId           The parent record's primary key value.
+ * @param fields             The CHILD object's field defs (`objectSchema.fields`),
+ *                           in either served shape. Without them the condition
+ *                           compiles to equality — the historical wire, and the
+ *                           only answer available to a caller that cannot see
+ *                           the metadata. A caller that CAN see it must pass it.
+ */
+export function composeParentScopeFilter(relationshipField, parentId, fields) {
+    const multi = isMultiValueRelationship(fields, relationshipField);
+    return { [relationshipField]: multi ? { $contains: parentId } : parentId };
+}

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

@@ -30,6 +30,15 @@
  * 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.)
+ *
+ * Since objectstack#8018 the same reader also carries the non-predicate row keys
+ * a view's actions read: `recordIdField`, since objectui#10277 the field a
+ * `defaultFromRow` param seeds from and the `{field}` tokens of an action's
+ * `target`, and since objectui#10404 the fields an `undoable` action writes,
+ * whose prior values the Undo capture reads off the row. The name kept the
+ * "predicate" spelling because the mechanism is identical (harvest a name, gate
+ * it against the declared fields, add it to `$select`); see
+ * {@link listViewPredicates} for what is in the set and why.
  */
 /**
  * The columns the framework provisions on EVERY business object
@@ -71,13 +80,62 @@ export declare function isProjectableField(name: string, declaredFields: Record<
  */
 export declare function collectPredicateFieldRefs(predicates: readonly unknown[]): string[];
 /**
- * Every predicate a list-ish view carries, flattened for
+ * Every record-field reference 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.
+ * is a place a row field is actually READ — conditional formatting, the row
+ * kebab (custom defs AND the built-in Edit/Delete overrides), the selection bar,
+ * and the object's declared actions.
+ *
+ * Most entries are predicates. Five are not, and all are spelled as a synthetic
+ * `record.<name>` so the one harvester handles them: conditional formatting's
+ * native `{ field, operator, value }` shape, an action's `recordIdField`
+ * (objectstack#8018), the field each `defaultFromRow` param seeds from, each
+ * `{field}` token of the action's `target` (both objectui#10277), and the fields
+ * an `undoable` action writes (objectui#10404). The
+ * `recordIdField` case is the same *class* of bug the predicate harvest exists
+ * to close, one surface over — the action runtime reads
+ * `rowRecord[action.recordIdField]` to seed `recordIdParam`, so a key outside the
+ * listView columns arrived absent and the injection was silently skipped, which
+ * turns a record-scoped mutation into one that names no record while still
+ * reporting success. The default (`id`) is already projected unconditionally, so
+ * only an explicit declaration adds anything here.
+ *
+ * The last two are the same class again, and they were silent in the same way.
+ * `resolveActionParam` seeds a `defaultFromRow` param only when the row HAS the
+ * key (an own-property check), so an absent key opened the param dialog with the
+ * field blank; and the console's `api` handler fills a `{field}` token from the
+ * row, so an absent key put an empty path segment into the URL. The key a param
+ * seeds from is `field ?? name` — the runtime's precedence, not the param's
+ * payload name — and the token grammar is the handler's own. Neither is
+ * narrowed by the action's `type`, for the asymmetry stated below: an extra
+ * column costs bytes.
+ *
+ * The written fields are the same class once more, and the worst of them,
+ * because what went wrong was a write. The Undo capture of an `undoable` update
+ * reads each written field's prior value off the row; on a projected row a
+ * written field no column shows was absent, the capture recorded `null`, and
+ * Undo then wrote `null` over the stored value it existed to restore. The
+ * written keys are `patch`, each param's collected key and `bodyExtra` (see
+ * `undoableWrittenKeys`). This one IS narrowed, to `undoable`, and not for
+ * cost: the capture is the only reader of a written field's prior value, and it
+ * runs only under `undoable`, so without it the row reads none of these keys.
+ *
+ * A `recordIdField`, param key or written key that is not a bare identifier is
+ * dropped here
+ * (a `target` token is one by construction of its grammar), and a name the
+ * object does not declare is dropped by the caller's `isProjectableField`
+ * guard. Both drops are the safe direction: such a name is not a column
+ * anywhere, and an unknown key in `$select` is not ignored by every backend.
+ * The identifier gate is not decoration — without it the harvester's regex would
+ * read a PREFIX of a malformed name (`record.not a field` → `not`) and
+ * contribute a plausible wrong field instead of nothing.
+ *
+ * ⛔ Harvesting is not a read grant. Every name here is a CANDIDATE: each
+ * consumer still passes it through its own field-level read filter before it
+ * reaches `$select`, so a field the principal may not read is not requested
+ * because an action names it.
  *
  * `objectActions` is deliberately the object's WHOLE action set rather than
  * only the ones this view promotes. Narrowing it would mean re-running the