@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/predicate-fields.js

@@ -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
@@ -74,6 +83,81 @@ export function isProjectableField(name, declaredFields) {
  * record-header path), so this covers the documented spelling.
  */
 const RECORD_REF = /\b(?:record|data)\.([A-Za-z_][A-Za-z0-9_]*)/g;
+/**
+ * A whole bare identifier — what a field name is, and the only shape that can be
+ * spelled as `record.<name>` without the harvester's regex reading a PREFIX of it
+ * as the name (`record.not a field` would otherwise yield `not`). Used to gate
+ * the non-predicate names folded into {@link listViewPredicates}, so a malformed
+ * declaration contributes nothing instead of contributing a plausible wrong name.
+ */
+const BARE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * A `{field}` token in an action's `target` — the grammar the console's `api`
+ * handler (`useConsoleActionRuntime` in `@object-ui/app-shell`) substitutes from
+ * the row record, spelled exactly as that handler spells it, so the harvest
+ * reads the same tokens it fills. The capture is a bare identifier by
+ * construction: a dotted path (`{owner.name}`), an expression (`{a + b}`) and
+ * the runner's own `${param.X}` / `${ctx.X}` scopes all fall outside it and
+ * match nothing here — this grammar does not read them off the row, so they owe
+ * the projection nothing.
+ */
+const TARGET_ROW_TOKEN = /\{([a-z_][a-z0-9_]*)\}/gi;
+/**
+ * The row key a `defaultFromRow` param seeds its value from — `field` wins,
+ * because row data is keyed by object field; `name` is the fallback. The same
+ * precedence `resolveActionParam` (`@object-ui/app-shell`) reads, which is the
+ * point: the projection must carry the key the runtime looks up, not the
+ * param's payload name. `remove_team_member` seeds `teamId` from `team_id`.
+ */
+function defaultFromRowKey(param) {
+    if (!param || typeof param !== 'object')
+        return undefined;
+    const p = param;
+    if (!p.defaultFromRow)
+        return undefined;
+    return p.field ?? p.name;
+}
+/**
+ * The keys an `undoable` action WRITES, which are the keys its Undo capture
+ * reads off the row (objectui#10404). Returned unfiltered; the caller applies
+ * the identifier gate.
+ *
+ * Each source is the one a writer actually merges into the written set:
+ *
+ *  - `patch`: the static field values of `operation: 'update'`, merged under the
+ *    collected params (`ActionRunner`'s `executeUpdateOperation`);
+ *  - each param's COLLECTED key, `name ?? field`: the key the param dialog
+ *    stores its answer under (`paramName` in `app-shell`'s
+ *    `resolveActionParams`). This is the opposite precedence to
+ *    {@link defaultFromRowKey} on purpose: that one asks which row key a value
+ *    is READ from, this one asks which key a value is WRITTEN under, and the
+ *    capture looks the written key up on the row;
+ *  - `bodyExtra`: the static body the console's generic `api` handler merges
+ *    over the params before it writes (`useConsoleActionRuntime`).
+ *
+ * `recordId` is left out: both writers read it as the record's address and
+ * strip it from the written set, so no capture ever looks it up.
+ *
+ * A key the harvest cannot make the row carry (undeclared, or a field the
+ * principal may not read) is not rescued here. The capture refuses to invent a
+ * prior value for it instead, and offers no Undo.
+ */
+function undoableWrittenKeys(def) {
+    const keys = [];
+    for (const bag of [def.patch, def.bodyExtra]) {
+        if (bag && typeof bag === 'object' && !Array.isArray(bag))
+            keys.push(...Object.keys(bag));
+    }
+    if (Array.isArray(def.params)) {
+        for (const param of def.params) {
+            if (!param || typeof param !== 'object')
+                continue;
+            const p = param;
+            keys.push(p.name ?? p.field);
+        }
+    }
+    return keys.filter((key) => key !== 'recordId');
+}
 /** Pull the CEL source out of any of the shapes a predicate is authored in. */
 function predicateSource(pred) {
     if (typeof pred === 'string')
@@ -117,13 +201,62 @@ export function collectPredicateFieldRefs(predicates) {
     return out;
 }
 /**
- * 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
@@ -151,6 +284,38 @@ export function listViewPredicates(view) {
                 continue;
             const d = def;
             preds.push(d.visible, d.disabled);
+            // The row key this action identifies its record by — a field the runtime
+            // READS off the row, so the projection owes it exactly as it owes a
+            // predicate's operands. Spelled as a `record.` reference so the one
+            // harvester handles it (see the doc above).
+            if (typeof d.recordIdField === 'string' && BARE_IDENTIFIER.test(d.recordIdField)) {
+                preds.push(`record.${d.recordIdField}`);
+            }
+            // A `defaultFromRow` param's seed field and the `{field}` tokens of the
+            // action's `target` (objectui#10277) — two more row keys the runtime
+            // READS, by the same rule and the same identifier gate.
+            if (Array.isArray(d.params)) {
+                for (const param of d.params) {
+                    const key = defaultFromRowKey(param);
+                    if (typeof key === 'string' && BARE_IDENTIFIER.test(key))
+                        preds.push(`record.${key}`);
+                }
+            }
+            if (typeof d.target === 'string') {
+                TARGET_ROW_TOKEN.lastIndex = 0;
+                for (let m = TARGET_ROW_TOKEN.exec(d.target); m; m = TARGET_ROW_TOKEN.exec(d.target)) {
+                    preds.push(`record.${m[1]}`);
+                }
+            }
+            // The fields an `undoable` action writes (objectui#10404): its Undo
+            // capture reads each one's prior value off the row. Same rule, same
+            // identifier gate.
+            if (d.undoable) {
+                for (const key of undoableWrittenKeys(d)) {
+                    if (typeof key === 'string' && BARE_IDENTIFIER.test(key))
+                        preds.push(`record.${key}`);
+                }
+            }
         }
     }
     for (const override of Object.values(view.userActions ?? {})) {

package/dist/utils/record-color.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+/**
+ * Resolve the colour a record's value stands for, off the field's own metadata.
+ *
+ * ## Why this is shared (objectui#7243)
+ *
+ * `colorField` is one authored key — `gantt.colorField`, `calendar.colorField`,
+ * `timeline.colorField` — and it used to mean three different things:
+ *
+ *   - `plugin-timeline` resolved the field's option `color` (correct);
+ *   - `plugin-calendar` passed the raw value on to a deterministic hash, so the
+ *     colour the author declared on the option was never consulted;
+ *   - `plugin-gantt` passed the raw value straight into `backgroundColor`, so
+ *     `colorField: 'status'` emitted `backgroundColor: "open"` — not a colour.
+ *     The browser dropped the declaration and every bar rendered identically,
+ *     which made DECLARING the documented key strictly worse than omitting it.
+ *
+ * The timeline's resolver is lifted here verbatim so all three answer the same
+ * question the same way. What lives here is the part that is genuinely common —
+ * the two rungs that depend only on the field metadata and the stored value:
+ *
+ *   1. the field's own option `color` for that value;
+ *   2. the value itself when it already IS a CSS colour literal.
+ *
+ * The LAST rung deliberately stays with each caller, because each one has a
+ * different right answer for "a value that is neither": the gantt derives a
+ * semantic token hex (a bar must be painted), the calendar hashes onto its
+ * theme-aware 8-stop class palette (a soft tint, not a solid fill), and the
+ * timeline draws its default marker variant. Pulling those together would be a
+ * repaint of existing views, not a bug fix.
+ *
+ * ## Keyed by option `value` only
+ *
+ * Deliberately NOT `buildOptionColorMap` (`./chart-series.ts`), which keys by
+ * value AND display label: that one reads dataset ROWS, where the server may
+ * have resolved a select dimension to its label. These callers read RECORDS,
+ * where `record[colorField]` is the stored value. Keying by label as well would
+ * colour a record whose stored value happens to collide with another option's
+ * label — a tolerance nothing here needs, and one the timeline never had.
+ */
+/** One entry of a select-like field's `options`, as far as colour is concerned. */
+export interface FieldColorOption {
+    value?: unknown;
+    color?: unknown;
+}
+/** The slice of a field definition this resolver reads. */
+export interface FieldColorDefinition {
+    options?: unknown;
+}
+/** Does this string already name a colour the DOM can paint? */
+export declare function isColorLiteral(value: string): boolean;
+/**
+ * Build a `value -> option colour` lookup from a field definition's `options`.
+ * Returns an empty map for a field with no options, so callers need no guard.
+ */
+export declare function buildFieldColorMap(fieldDef: FieldColorDefinition | undefined | null): Record<string, string>;
+/**
+ * Build the per-field colour resolver: rung 1 (option colour) then rung 2 (the
+ * value is already a colour literal), else `undefined` so the caller runs its
+ * own last rung.
+ *
+ * A factory rather than a plain function because callers resolve one field
+ * across every row of a view — the option map is built once, not per record.
+ *
+ * @param fieldDef `objectSchema.fields[colorField]`, or `undefined` when the
+ *   view has no schema in hand (an inline-data or `api`-provider view). With no
+ *   options, rung 1 is a no-op and rung 2 still answers for literal colours.
+ */
+export declare function createFieldColorResolver(fieldDef: FieldColorDefinition | undefined | null): (value: unknown) => string | undefined;

package/dist/utils/record-color.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+/**
+ * Colour literals the renderers accept as-is.
+ *
+ * Hex accepts 3, 6 and 8 digits. The timeline's private regex accepted 3 and 6;
+ * `plugin-calendar`'s accepted 3, 6 and 8 — two in-repo spellings of the same
+ * question, and the narrow one is the only one under which a VALID CSS colour
+ * (`#rrggbbaa`) could fall past this rung and be replaced by a derived colour.
+ * Widening can only turn "not recognised" into "the author's colour"; it can
+ * never turn a colour into something else. So the wider spelling wins.
+ */
+const HEX_COLOR_RE = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/** Does this string already name a colour the DOM can paint? */
+export function isColorLiteral(value) {
+    return HEX_COLOR_RE.test(value) || value.startsWith('rgb') || value.startsWith('hsl');
+}
+/**
+ * Build a `value -> option colour` lookup from a field definition's `options`.
+ * Returns an empty map for a field with no options, so callers need no guard.
+ */
+export function buildFieldColorMap(fieldDef) {
+    const options = fieldDef?.options;
+    if (!Array.isArray(options))
+        return {};
+    const map = {};
+    for (const opt of options) {
+        if (!opt || typeof opt !== 'object')
+            continue;
+        if (opt.value == null)
+            continue;
+        if (typeof opt.color === 'string' && opt.color)
+            map[String(opt.value)] = opt.color;
+    }
+    return map;
+}
+/**
+ * Build the per-field colour resolver: rung 1 (option colour) then rung 2 (the
+ * value is already a colour literal), else `undefined` so the caller runs its
+ * own last rung.
+ *
+ * A factory rather than a plain function because callers resolve one field
+ * across every row of a view — the option map is built once, not per record.
+ *
+ * @param fieldDef `objectSchema.fields[colorField]`, or `undefined` when the
+ *   view has no schema in hand (an inline-data or `api`-provider view). With no
+ *   options, rung 1 is a no-op and rung 2 still answers for literal colours.
+ */
+export function createFieldColorResolver(fieldDef) {
+    const colorByValue = buildFieldColorMap(fieldDef);
+    return (value) => {
+        if (value == null || value === '')
+            return undefined;
+        const key = String(value);
+        const optionColor = colorByValue[key];
+        if (optionColor)
+            return optionColor;
+        return isColorLiteral(key) ? key : undefined;
+    };
+}

package/dist/utils/record-source.d.ts

@@ -0,0 +1,298 @@
+/**
+ * ObjectUI — the shared record-source readers: the ruled three-rung ladder
+ * (`resolveRecordSourceConfig`) and the object-name it resolves to
+ * (`resolveRecordSourceObjectName`)
+ * 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 type { ViewData } from '@object-ui/types';
+/**
+ * The object a view block is bound to, resolved ONCE for the whole renderer
+ * (`b041b9c0c`).
+ *
+ * ## The question this answers, and the one it does not
+ *
+ * There are TWO separately-ruled precedence questions about `objectName`, and
+ * they only look like one question when a single reader is asked to answer
+ * both:
+ *
+ *  1. **Which object does this block RESOLVE, at render time, when it carries
+ *     more than one binding?** — the published three-rung record-source ladder
+ *     (`data`, then `staticData`, then `objectName`), declared on both faces of
+ *     the contract (`ObjectMapSchema.objectName` / `ObjectGanttSchema.objectName`
+ *     in `@object-ui/types`, and the `.describe` on their zod twins — the map
+ *     twin's reads *"objectName — the THIRD record source `getDataConfig`
+ *     resolves, after `data` and `staticData`"*, naming `ObjectMap.tsx`'s local
+ *     wrapper; the gantt twin names `resolveRecordSourceConfig` itself), ruled
+ *     2026-09-02 (landed as `77cb489b4`) and pinned by
+ *     `objectql-record-source-refinement-6939.test.ts`. **That is this
+ *     function.**
+ *  2. **How does `objectName` get POPULATED when it is absent?** — the
+ *     authoring-time gap-fill in `normalizeListViewSchema` (objectui#7477,
+ *     ruling B, landed as `00d2fa682`), where an `objectName` already on the schema WINS
+ *     and the `data` block only fills a gap: *"it can never re-point a binding
+ *     that already resolves."*
+ *
+ * The two are NOT merged and neither is re-pointed at the other. Merging them
+ * would override a standing maintainer ruling in whichever direction the merged
+ * reader happened to pick: at the sites below the binding that already resolves
+ * IS `data.object`, so ruling B's own words argue for keeping rung 1 as it is.
+ *
+ * ## Why `staticData` does not appear here
+ *
+ * The ladder's second rung wraps inline rows as `{ provider: 'value', items }`,
+ * which names no object at all. So for the object-NAME question the three-rung
+ * ladder reduces to two rungs — the resolved config's object when it names one,
+ * else the schema's own `objectName`, which is what a `value`/`api`-backed block
+ * still needs for metadata reads, i18n field labels and permission verdicts.
+ * Callers pass the ALREADY-RESOLVED config (their
+ * {@link resolveRecordSourceConfig} output, direct or through a local wrapper),
+ * so rung ordering is settled before this function is reached.
+ *
+ * ## No lenient rung was added (AGENTS.md #0.1)
+ *
+ * `ViewDataSchema`'s `object` provider is a `strictObject` carrying exactly
+ * `{ provider, object }` with `object` REQUIRED, so `{ provider: 'object' }`
+ * without an `object` is off-contract. This reader does not coerce that shape
+ * back to `objectName`; the two call sites that used to (`ObjectGrid`'s
+ * `'object' in dataConfig` test and `ObjectTree`'s header `?? schema.objectName`
+ * tail) keep their own tail at the site, so the collapse changes nothing they
+ * resolve today while the shared rung stays contract-strict.
+ *
+ * @param schema - The block's schema; only `objectName` is read.
+ * @param dataConfig - The RESOLVED data config — the caller's own
+ *   {@link resolveRecordSourceConfig} output, `null` when nothing is bound.
+ * @returns The bound object's name, or `undefined` when neither the resolved
+ *   config nor the schema names one.
+ *
+ * @example
+ * ```ts
+ * const dataConfig = useMemo(() => resolveRecordSourceConfig(schema, 'view-data'), [schema]);
+ * const objectName = resolveRecordSourceObjectName(schema, dataConfig);
+ * ```
+ */
+export declare function resolveRecordSourceObjectName(schema: {
+    objectName?: string;
+} | null | undefined, dataConfig: {
+    provider?: string;
+    object?: string;
+} | null | undefined): string | undefined;
+/**
+ * Which arm of `data` a block's PUBLISHED row declares — the only shape rung 1
+ * of the ladder honours for that block (objectui#8348).
+ *
+ * Maintainer ruling, decision batch #83 (2026-09-08), verbatim: 「8348 以协议为准」
+ * — the contract decides. A renderer honours the `data` spelling its block's
+ * published row declares and no other: what `os validate` and the save gate
+ * refuse, the renderer refuses too.
+ *
+ *  - `'view-data'` — the row is the spec's `ViewData` discriminated union, four
+ *    strict OBJECT arms on `provider`. A bare array under `data` is NOT a record
+ *    source for such a block.
+ *  - `'array'` — the row is `z.array(...)`: an array of PRE-FETCHED RECORDS. The
+ *    `{ provider, items }` config object is NOT a record source for such a
+ *    block.
+ *  - `'undeclared'` — no published face declares a `data` row for the block at
+ *    all, so neither arm of the ruling reaches it and rung 1 keeps its pre-8348
+ *    verbatim behaviour. ⛔ NOT a tolerance to copy: it is the honest answer for
+ *    a block the ruling does not decide, and it is reported rather than guessed.
+ *    No ladder block passes it any more: `object-tree`, the last one that did,
+ *    gained a published row and moved to `'view-data'` (objectui#8348, ruling
+ *    batch #136 item 3, Q1-C). It stays the answer
+ *    {@link recordSourceDataArmForType} gives a type it does not list.
+ *
+ * The arm is passed BY THE CALL SITE rather than looked up from `schema.type`
+ * on purpose. Most of these renderers are registered twice — `object-grid`
+ * and the `view:grid` alias `grid`, `object-calendar` and `calendar`, and so on
+ * (the bare `gantt` and `map` keys are retired, objectui#8008 / objectui#10393)
+ * — so a node reaches the same component under either spelling, and a table
+ * keyed by `type` would answer for one tag and silently miss the other. A
+ * REQUIRED parameter makes the arm a compile-time obligation at each of the
+ * five sites instead.
+ */
+export type RecordSourceDataArm = 'view-data' | 'array' | 'undeclared';
+/**
+ * The authored `data` shape a block ON THAT ARM may declare — the DECLARATION
+ * half of the same per-block ruling {@link authoredDataIsOnTheDeclaredArm}
+ * decides at RUNTIME (`ab856ed30`).
+ *
+ * ## The contradiction this closes
+ *
+ * {@link resolveRecordSourceConfig} used to declare its `data` parameter as a
+ * flat `ViewData`, while its own docblock, its REQUIRED `dataArm` parameter and
+ * its rung-1 predicate all say the honoured shape DIFFERS PER BLOCK — and
+ * `ViewData` is a discriminated union over four strict OBJECT arms with no
+ * array member. So the signature refused the one block whose published row IS
+ * the array arm, and the arm parameter that exists to make the row a
+ * compile-time obligation was the one thing the compiler ignored. The
+ * contradiction was held shut at `ObjectCalendar.tsx`'s call site by an
+ * `as ViewData | undefined` cast whose own comment reported it as an upstream
+ * defect rather than a licence.
+ *
+ * ⛔ The repair is NOT a union of the arms. `ViewData | unknown[]` would let a
+ * `'view-data'` site declare a bare array and a `'array'` site declare a
+ * provider block — each of them the shape that block's row REFUSES, each of
+ * them compiling — which is the repo-wide default {@link RecordSourceDataArm}'s
+ * docblock refuses by name: *"a default is how the second de-facto contract got
+ * in"* (AGENTS.md #0.1).
+ *
+ *  - `'view-data'` — the spec's `ViewData`. UNCHANGED, and that matters: this
+ *    is exactly what the flat declaration said, and it was right for the three
+ *    blocks on this arm, so nothing moves for `object-grid`, `object-map` or
+ *    `object-gantt`.
+ *  - `'array'` — `unknown[]`, the shape `object-calendar`'s published row
+ *    declares (`ComponentPropsMap['object-calendar'].data` is
+ *    `z.array(z.unknown()).optional()`, *"Pre-fetched records"*).
+ *  - `'undeclared'` — `unknown`. No published face declares a `data` row for
+ *    such a block, so rung 1 keeps its pre-8348 verbatim behaviour and honours
+ *    ANY truthy value. Anything narrower here would be a rule nobody has ruled.
+ *
+ * ⚠️ RUNTIME IS UNMOVED. This type is erased; {@link authoredDataIsOnTheDeclaredArm}
+ * still takes `unknown` and still decides rung 1 on the value's KIND, so every
+ * runtime verdict — including the off-arm ones — is byte-for-byte what it was.
+ * `record-source-config.behaviourNeutrality-7632.test.ts` passes its fixtures
+ * through `as any` precisely so it keeps measuring that, whatever the
+ * declaration says.
+ *
+ * ⚠️ DISTRIBUTIVE on purpose, and that is why this is a conditional type rather
+ * than a set of overloads. A caller holding a `RecordSourceDataArm`-typed
+ * VARIABLE instead of a literal gets `ViewData | unknown[] | unknown`, i.e.
+ * `unknown` — the honest answer when the arm is not decided at compile time.
+ * The same caller would match NONE of three literal-armed overloads, which
+ * would turn a working call into an error for no contract reason.
+ */
+export type AuthoredRecordSourceData<Arm extends RecordSourceDataArm> = Arm extends 'view-data' ? ViewData : Arm extends 'array' ? unknown[] : unknown;
+/**
+ * The block's record source, resolved from the ruled three-rung ladder
+ * (`ce2aaefe1`), with rung 1 judged against the block's own published `data`
+ * row (objectui#8348).
+ *
+ * ## The ruled contract this is the ONE implementation of
+ *
+ * `data`, then `staticData`, then `objectName` — declared on both faces of the
+ * published contract and pinned by
+ * `objectql-record-source-refinement-6939.test.ts`. Quoted here from the
+ * `ObjectMapSchema` faces, whose `getDataConfig` is `ObjectMap.tsx`'s local
+ * wrapper around this function; the gantt and calendar faces name
+ * `resolveRecordSourceConfig` instead (objectui#9618):
+ *
+ *  1. **`data`** — *"Data source configuration. Read FIRST by `getDataConfig`"*,
+ *     honoured ONLY on the arm `dataArm` names. Returned verbatim, so a config
+ *     on the declared arm reaches the caller exactly as the author wrote it.
+ *  2. **`staticData`** — *"Inline records — read SECOND by `getDataConfig`,
+ *     wrapped into a `{ provider: value }` config"*.
+ *  3. **`objectName`** — *"the THIRD record source `getDataConfig` resolves,
+ *     after `data` and `staticData`"*, folded to `{ provider: 'object' }`.
+ *
+ * `null` when none of the three is present — the same "nothing is drawn" signal
+ * the zod `requireRecordSource` refinement is written against.
+ *
+ * This is the PRODUCER whose output {@link resolveRecordSourceObjectName} (the
+ * reader `b041b9c0c` published) consumes; that function's docblock describes the same
+ * ladder from the consuming end. Five plugins — calendar, gantt, grid, map and
+ * tree — each carried a hand-copy of this ladder with no gate holding them
+ * together, which is the AGENTS.md #0.1 drift class: a change to the ruled
+ * order had five edit sites and nothing noticed a missed one.
+ *
+ * ## Rung 1 is judged against the block's own row (objectui#8348)
+ *
+ * ⛔ This docblock used to state, as a fact about the whole ladder, that *"an
+ * array under `data` cannot be published"*. That is true of the blocks whose row
+ * is `ViewData` and FALSE of `object-calendar`, whose published row
+ * (`ComponentPropsMap['object-calendar'].data` on `@objectstack/spec` 17.4.0) is
+ * `z.array(z.unknown()).optional()` — *"Pre-fetched records — skips the internal
+ * fetch"*. Both directions of that disagreement were live at once: the renderers
+ * honoured the `{ provider, items }` object on a block whose row refuses it by
+ * kind, and `ObjectGrid` / `ObjectMap` lifted a bare array on blocks whose row
+ * refuses THAT by kind. Decision batch #83 settled it — the row decides — and
+ * `dataArm` is where each block says which row it has.
+ *
+ * JUDGED, per block, against that block's `ComponentPropsMap` row in the
+ * INSTALLED `@objectstack/spec` — and ⛔ the verdicts are not written down here
+ * as facts, because a spec release can move a row (AGENTS.md #9). Each pin
+ * below derives the arm from the row at test time and compares it with what the
+ * block passes, so a moved row turns it red:
+ *
+ *  - `object-grid` — `'view-data'`; `gridBareArrayDataRefused-8348.test.tsx`,
+ *    its "the spec row is what all of the above is judged against" test. The
+ *    row's own description names the refusal: *"the bare-array shortcut is
+ *    refused — see migration `object-grid-data-view-data-converged`"*.
+ *  - `object-calendar` — `'array'`; the test of the same name in
+ *    `ObjectCalendar.dataObjectArmRefused-8348.test.tsx`. The registration
+ *    publishes the same arm (`{ name: 'data', type: 'array' }`).
+ *  - `object-map`, `object-gantt`, `object-tree` — `'view-data'`; one
+ *    `dataArmSpecRow-8348` pin per block, in each plugin's own tests. These
+ *    three rows are what ruling batch #136 item 3 (Q1-C) had the protocol
+ *    gain; until they were installable, map and gantt were judged through this
+ *    repo's own `ObjectMapSchema.data` / `ObjectGanttSchema.data` and tree
+ *    passed `'undeclared'`. The tree's row declares `data`, so the ruling's
+ *    「协议没有的能力删」 clause did not fire for it: it keeps the object arm and
+ *    loses only the bare-array spelling. Its `staticData` rung is declared by
+ *    the same row and is unchanged.
+ *
+ * ## The DECLARATION follows the arm too (`ab856ed30`)
+ *
+ * The `data` member below is {@link AuthoredRecordSourceData}`<Arm>`, not a flat
+ * `ViewData`: the arm decides what a site may DECLARE exactly as it decides
+ * what rung 1 HONOURS. Read that type's docblock for why it is arm-indexed
+ * rather than a union of the arms, and for the reading that says nothing at
+ * runtime moved.
+ *
+ * ## No lenient rung was added (AGENTS.md #0.1)
+ *
+ * **Null tolerance** stays out: all five copies dereference `schema` unguarded
+ * and would throw on `null`; no site passes one, so no `?.` was added.
+ *
+ * `ObjectCalendar`'s copy guarded with `'data' in schema && schema.data`. That
+ * `in` test was a TYPESCRIPT narrowing device, not a behavioural one: when the
+ * property is absent the read yields `undefined`, which is falsy either way, so
+ * the guard could never change which rung is taken. The optional-property
+ * parameter below admits a schema that declares neither key directly, which is
+ * why the guard is gone rather than flattened away. The equivalence itself is
+ * pinned, not argued, by `CALENDAR_IN_GUARD` in
+ * `record-source-config.behaviourNeutrality-7632.test.ts`.
+ *
+ * ⛔ This passage used to explain that guard by the PROPS UNION the calendar
+ * plugin once carried — `ObjectGridSchema | CalendarSchema`, whose second
+ * member declared neither `data` nor `staticData`. objectui#8651 RETIRED that
+ * union (`ObjectCalendarComponentProps.schema` is the published
+ * `ObjectCalendarSchema` today), so the sentence explained the guard by a type
+ * no reader could look up. Rewritten rather than deleted: the guard's history
+ * is still why this parameter's members are optional.
+ *
+ * @param schema - The block's schema; only `data`, `staticData` and
+ *   `objectName` are read. Its `data` member is typed by the arm — see
+ *   {@link AuthoredRecordSourceData}.
+ * @param dataArm - The arm the CALLING BLOCK's published `data` row declares.
+ *   Required: there is no repo-wide default, because the answer differs per
+ *   block and a default is how the second de-facto contract got in.
+ * @returns The resolved data config, or `null` when nothing is bound.
+ *
+ * @example
+ * ```ts
+ * const dataConfig = useMemo(() => resolveRecordSourceConfig(schema, 'view-data'), [schema]);
+ * const objectName = resolveRecordSourceObjectName(schema, dataConfig);
+ * ```
+ */
+export declare function resolveRecordSourceConfig<Arm extends RecordSourceDataArm>(schema: {
+    objectName?: string;
+    data?: AuthoredRecordSourceData<Arm>;
+    staticData?: any[];
+}, dataArm: Arm): ViewData | null;
+/**
+ * Which `data` arm the block registered under `type` declares.
+ *
+ * `'undeclared'` for every type not listed above — the same verdict the ladder
+ * gives a block no published face declares a `data` row for, and the same
+ * behaviour those types have today. That default is deliberately the
+ * NO-CHANGE direction: a caller acting on this reading (today:
+ * `SchemaRenderer`'s props spread) leaves an unlisted type exactly as it was,
+ * so a block that has never been measured is never silently re-decided by this
+ * table's mere existence.
+ *
+ * @param type - The node's registry key, either spelling.
+ * @returns The arm that type's published `data` row declares.
+ */
+export declare function recordSourceDataArmForType(type: string | null | undefined): RecordSourceDataArm;