@object-ui/core 17.6.0 → 17.7.0

package/dist/utils/emptiness.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ObjectUI — the shared emptiness floor
+ * 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 floor under "is this value empty" (objectui#8496 — director seat,
+ * decision batch #86, 2026-09-08, option B).
+ *
+ * Exactly four members, and it never grows past them:
+ *
+ *   `null` · `undefined` · the empty string · the empty array
+ *
+ * ## What a floor IS, and what it is not
+ *
+ * It is the WEAKEST claim the surfaces below it can all make — not the answer
+ * any one of them gives. A caller does one of two things with it, and both are
+ * legitimate:
+ *
+ *  - **extends** it — `isEmptyValue(v) || <its own clause>` — when its surface
+ *    calls MORE things empty (a grid trims whitespace; a boolean column calls
+ *    every non-boolean empty);
+ *  - **declines a member** in the open — `isEmptyValue(v) && !Array.isArray(v)`
+ *    — when its surface has MEASURED that member to be a value there (a `json`
+ *    cell draws the two-character literal `[]` on purpose, objectui#8474).
+ *
+ * What is NOT legitimate is a sixth private re-spelling of these four members.
+ * That is the defect this function exists to close: `plugin-detail`'s
+ * `hasCellValue`, `RelatedList`'s `isValueEmpty`, `ObjectGallery`'s and
+ * `ObjectKanban`'s inline guards and the guard idioms across
+ * `@object-ui/fields`' cell renderers each grew their own copy, and
+ * objectui#8481 was the THIRD rediscovery of the same hole — objectui#8474 and
+ * objectui#8459 had each closed it at their own door first. A copy that agrees
+ * today stops agreeing; one definition cannot.
+ *
+ * ## ⛔ The floor never grows past those four members
+ *
+ * The ruling fixed the member list, and every candidate fifth member is a
+ * measured disagreement rather than an oversight:
+ *
+ *  - **whitespace-only strings.** `'   '` is EMPTY on `record:details` and in
+ *    `RelatedList` (objectui#8350 measured the damage a blank cell does there)
+ *    and a VALUE on the gallery, the kanban and the shared renderers. Both are
+ *    right for their surface, so the trim is an EXTENSION, not a member.
+ *  - **`{}`.** Measured as a VALUE and pinned (objectui#8474): a populated or
+ *    empty object literal is handed to a type-aware renderer that draws it, and
+ *    the shape that would sweep it in — `Object.keys(v).length === 0` — is also
+ *    true of `new Date(0)`, of a populated `Map`, of a populated `Set` and of
+ *    any class instance whose state sits behind getters.
+ *  - **`0` / `false`.** Values everywhere. `BooleanCellRenderer` keeping
+ *    `false` a value is the pinned case (objectui#8582).
+ *
+ * ## Why `@object-ui/core` and not `@object-ui/types`
+ *
+ * It is a runtime predicate, not a protocol type, so it belongs in the engine.
+ * The ruling made that conditional on a measurement — `@object-ui/fields` is
+ * the lowest consumer, and if it did not already depend on `core` the floor
+ * would have had to fall back to `types`. Measured on the implementing branch:
+ * `@object-ui/fields`' `package.json` lists `@object-ui/core` in
+ * `dependencies`, and its barrel already imports from it. No new dependency
+ * edge is created by this file, in either direction — `core` reaches no
+ * consumer, which is why exporting the helper from `@object-ui/fields` instead
+ * (option C) was refused: the gallery and the kanban would then import a
+ * `fields` helper to decide whether to call a `fields` renderer.
+ *
+ * ## "Empty" is two questions; this floor answers the half both share
+ *
+ * objectui#8496's later evidence (comment 5603203484) measured that the word
+ * has split in two on this codebase: SCALAR-MISSING (`EmptyValue`, the em-dash
+ * affordance whose accessible name is fixed) and COLLECTION-EMPTY
+ * (`EmptyDescription`, an author's own sentence). The floor serves both and
+ * does not have to choose: its four members ARE two scalar-missing members,
+ * one blank scalar and one empty collection, and no call site asks a boolean to
+ * tell those apart — each one knows statically which affordance it is drawing.
+ * ⛔ So this function is deliberately NOT the place to grow a second axis. Which
+ * COMPONENT states the emptiness is a different question, carried by
+ * objectui#8570 / objectui#8526 / objectui#8507.
+ *
+ * ## Readers
+ *
+ * `isOptionGroupGated` / `isValueStillOffered` here in `core` (this function's
+ * origin: it was written privately in `evaluator/optionRules.ts`, byte-for-byte
+ * these four members, before the ruling promoted it); `hasCellValue` and
+ * `RelatedList.isValueEmpty` in `@object-ui/plugin-detail`; `ObjectGallery`'s
+ * card-field row filter; `ObjectKanban`'s card-field loop; and the cell-renderer
+ * guards in `@object-ui/fields`.
+ *
+ * The extensions and the declensions are pinned — the assertion that each
+ * surface still answers DIFFERENTLY from the floor, not merely that the floor
+ * works — in `__tests__/emptiness-floor-8496.test.ts` here and in
+ * `emptinessFloorExtensions-8496.test.tsx` in `@object-ui/fields` and
+ * `@object-ui/plugin-detail`.
+ */
+export declare function isEmptyValue(value: unknown): boolean;

package/dist/utils/emptiness.js

@@ -0,0 +1,101 @@
+/**
+ * ObjectUI — the shared emptiness floor
+ * 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 floor under "is this value empty" (objectui#8496 — director seat,
+ * decision batch #86, 2026-09-08, option B).
+ *
+ * Exactly four members, and it never grows past them:
+ *
+ *   `null` · `undefined` · the empty string · the empty array
+ *
+ * ## What a floor IS, and what it is not
+ *
+ * It is the WEAKEST claim the surfaces below it can all make — not the answer
+ * any one of them gives. A caller does one of two things with it, and both are
+ * legitimate:
+ *
+ *  - **extends** it — `isEmptyValue(v) || <its own clause>` — when its surface
+ *    calls MORE things empty (a grid trims whitespace; a boolean column calls
+ *    every non-boolean empty);
+ *  - **declines a member** in the open — `isEmptyValue(v) && !Array.isArray(v)`
+ *    — when its surface has MEASURED that member to be a value there (a `json`
+ *    cell draws the two-character literal `[]` on purpose, objectui#8474).
+ *
+ * What is NOT legitimate is a sixth private re-spelling of these four members.
+ * That is the defect this function exists to close: `plugin-detail`'s
+ * `hasCellValue`, `RelatedList`'s `isValueEmpty`, `ObjectGallery`'s and
+ * `ObjectKanban`'s inline guards and the guard idioms across
+ * `@object-ui/fields`' cell renderers each grew their own copy, and
+ * objectui#8481 was the THIRD rediscovery of the same hole — objectui#8474 and
+ * objectui#8459 had each closed it at their own door first. A copy that agrees
+ * today stops agreeing; one definition cannot.
+ *
+ * ## ⛔ The floor never grows past those four members
+ *
+ * The ruling fixed the member list, and every candidate fifth member is a
+ * measured disagreement rather than an oversight:
+ *
+ *  - **whitespace-only strings.** `'   '` is EMPTY on `record:details` and in
+ *    `RelatedList` (objectui#8350 measured the damage a blank cell does there)
+ *    and a VALUE on the gallery, the kanban and the shared renderers. Both are
+ *    right for their surface, so the trim is an EXTENSION, not a member.
+ *  - **`{}`.** Measured as a VALUE and pinned (objectui#8474): a populated or
+ *    empty object literal is handed to a type-aware renderer that draws it, and
+ *    the shape that would sweep it in — `Object.keys(v).length === 0` — is also
+ *    true of `new Date(0)`, of a populated `Map`, of a populated `Set` and of
+ *    any class instance whose state sits behind getters.
+ *  - **`0` / `false`.** Values everywhere. `BooleanCellRenderer` keeping
+ *    `false` a value is the pinned case (objectui#8582).
+ *
+ * ## Why `@object-ui/core` and not `@object-ui/types`
+ *
+ * It is a runtime predicate, not a protocol type, so it belongs in the engine.
+ * The ruling made that conditional on a measurement — `@object-ui/fields` is
+ * the lowest consumer, and if it did not already depend on `core` the floor
+ * would have had to fall back to `types`. Measured on the implementing branch:
+ * `@object-ui/fields`' `package.json` lists `@object-ui/core` in
+ * `dependencies`, and its barrel already imports from it. No new dependency
+ * edge is created by this file, in either direction — `core` reaches no
+ * consumer, which is why exporting the helper from `@object-ui/fields` instead
+ * (option C) was refused: the gallery and the kanban would then import a
+ * `fields` helper to decide whether to call a `fields` renderer.
+ *
+ * ## "Empty" is two questions; this floor answers the half both share
+ *
+ * objectui#8496's later evidence (comment 5603203484) measured that the word
+ * has split in two on this codebase: SCALAR-MISSING (`EmptyValue`, the em-dash
+ * affordance whose accessible name is fixed) and COLLECTION-EMPTY
+ * (`EmptyDescription`, an author's own sentence). The floor serves both and
+ * does not have to choose: its four members ARE two scalar-missing members,
+ * one blank scalar and one empty collection, and no call site asks a boolean to
+ * tell those apart — each one knows statically which affordance it is drawing.
+ * ⛔ So this function is deliberately NOT the place to grow a second axis. Which
+ * COMPONENT states the emptiness is a different question, carried by
+ * objectui#8570 / objectui#8526 / objectui#8507.
+ *
+ * ## Readers
+ *
+ * `isOptionGroupGated` / `isValueStillOffered` here in `core` (this function's
+ * origin: it was written privately in `evaluator/optionRules.ts`, byte-for-byte
+ * these four members, before the ruling promoted it); `hasCellValue` and
+ * `RelatedList.isValueEmpty` in `@object-ui/plugin-detail`; `ObjectGallery`'s
+ * card-field row filter; `ObjectKanban`'s card-field loop; and the cell-renderer
+ * guards in `@object-ui/fields`.
+ *
+ * The extensions and the declensions are pinned — the assertion that each
+ * surface still answers DIFFERENTLY from the floor, not merely that the floor
+ * works — in `__tests__/emptiness-floor-8496.test.ts` here and in
+ * `emptinessFloorExtensions-8496.test.tsx` in `@object-ui/fields` and
+ * `@object-ui/plugin-detail`.
+ */
+export function isEmptyValue(value) {
+    return (value === undefined ||
+        value === null ||
+        value === '' ||
+        (Array.isArray(value) && value.length === 0));
+}

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

@@ -7,14 +7,52 @@
  */
 /**
  * Relational ("reference-bearing") field types whose stored value is a foreign
- * key into another object — and which therefore benefit from `$expand` so a
- * list / grid / detail cell can render the related record's display name
- * instead of a bare id placeholder ("—").
+ * key into another object — and which therefore benefit from `$expand`, so a
+ * response carries the related record instead of only its foreign key.
  *
  * `user` is a lookup specialised to `sys_user`: it carries the same `reference`
  * + id storage and the server resolves it through the same expand path as
  * `lookup` / `master_detail`, so a `user` column that is NOT requested for
- * expansion comes back as a raw user id and renders as "—" (objectui#2032).
+ * expansion comes back as a raw user id (objectui#2032). What a CELL then
+ * prints for that id is deliberately not stated here — see the next section.
+ *
+ * ## No rendering claim is made here, on purpose — objectui#8693
+ *
+ * Both paragraphs above used to make one: the `user` sentence ended "…and
+ * renders as '—'", and the opening one called the unexpanded cell "a bare id
+ * placeholder ('—')". Measured on `da5e4f69e` by resolving each family through
+ * `getCellRenderer` and rendering three unexpanded primitives:
+ *
+ * | unexpanded value     | `lookup` / `master_detail` / `tree` | `user`             |
+ * |----------------------|-------------------------------------|--------------------|
+ * | `'u_1'`              | `u_1`, plain truncated span         | `u_1`, same span   |
+ * | `'01HQZX9K2M4N6P8R'` | muted `—`                           | the raw ULID       |
+ * | `'Ada Lovelace'`     | `Ada Lovelace`, plain span          | the raw string     |
+ *
+ * Wrong twice over. `user` never drew the em-dash at all — `UserCellRenderer`
+ * has no resolver, no `useLookupName`, no `isLikelyOpaqueId`. And the three
+ * families that do draw it draw it ONLY for values `isLikelyOpaqueId` accepts;
+ * that qualifier is the entire content of the behaviour and the sentence never
+ * carried it, so a reader was told a human-readable id would degrade visibly
+ * when it printed as if it were a name — the defect objectui#8434 was for.
+ *
+ * It is not replaced by a corrected sentence, because a corrected sentence
+ * could not be kept true HERE. `@object-ui/core` does not depend on
+ * `@object-ui/fields` in `dependencies`, `peerDependencies` or
+ * `devDependencies` — the arrow runs the other way — so no test that can reach
+ * this file can render the cell it would describe, and nothing in this repo
+ * compares a docblock to rendered output. A replacement would be checked by
+ * whatever checked the last one: nobody. Its shelf life was measured too —
+ * while objectui#8693 was open, PR #8698 (objectui#8434) sat in the merge
+ * queue rewriting the `user` column of that very table: on its head
+ * `3692f7218` all three primitives render an unresolved-reference affordance
+ * that KEEPS the raw value. A corrected sentence would have been stale before
+ * it landed. The other three families are byte-identical on both trees.
+ *
+ * The storage claim is the half this set actually depends on, and that half IS
+ * checkable here (`__tests__/expand-fields.test.ts`, plus the identity pins
+ * below). How an unexpanded reference prints belongs next to the renderers in
+ * `@object-ui/fields`, where a test can fail.
  *
  * Note on `tree`: a self-referencing hierarchy field is a reference too, so it
  * belongs in this set; whether the backend materialises the expanded object
@@ -31,6 +69,12 @@
  * the falsification note at the end. Read the list below as the lineage of the
  * conversions, not as a census; the mechanical fact is the identity pins.
  *
+ * Re-measured for objectui#8693 on `da5e4f69e`: stale again, by FOUR. The
+ * commit that corrected the "fourth and last" claim (objectui#5874 / #6064)
+ * converged four more private copies of its own and never added them here —
+ * the last four bullets below. Re-derive before trusting it; the recipe is at
+ * the end of the list.
+ *
  * This is the reference-bearing FAMILY, not the `$expand` builder's private
  * list, and these concerns read it under several different words:
  *
@@ -43,7 +87,7 @@
  *  - the grid's bulk-action dialog — `widgetNeedsDataSource` in
  *    `packages/plugin-grid/src/components/bulkParamToField.ts`, which decides
  *    which param widget is handed the grid's `DataSource` and which param field
- *    shape carries `reference_to` / `display_field`;
+ *    shape carries `reference` / `displayField`;
  *  - the action-param dialog — `paramToField` in
  *    `packages/app-shell/src/utils/paramToField.ts`, which decides which param
  *    carries a reference target (objectui#5312);
@@ -52,7 +96,33 @@
  *  - the dashboard table's `$expand` whitelist — `computeLookupExpand` in
  *    `packages/plugin-dashboard/src/ObjectDataTable.tsx` (objectui#5692);
  *  - the dashboard's relation/link test — `isLookupType` in
- *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692).
+ *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692);
+ *  - the action-param RESOLVER (one step before `paramToField`) —
+ *    `packages/app-shell/src/utils/resolveActionParams.ts` (objectui#5874);
+ *  - the detail header's relation test — `HeaderHighlight.tsx` in
+ *    `packages/plugin-detail` (objectui#5874);
+ *  - the detail drawer's relation test — `RecordDetailDrawer.tsx` in
+ *    `packages/plugin-detail`, reading through `isExpandableFieldType`
+ *    (objectui#5874);
+ *  - the kanban board's `$expand` — `ObjectKanban.tsx` in
+ *    `packages/plugin-kanban`, reading through `buildExpandFields`
+ *    (objectui#5874).
+ *
+ * ⚠️ Re-derive rather than trust. One command, from the repo root, over the
+ * whole tree with NO pathspec. (Narrowing it to `packages/` + a `*` segment +
+ * `/src` matches ZERO files, and would drop `apps/` besides. The two-character
+ * sequence is spelled out in words here because writing it literally would end
+ * this comment.)
+ *
+ *     git grep -lE 'EXPANDABLE_FIELD_TYPES|isExpandableFieldType|buildExpandFields'
+ *
+ * 96 files on `da5e4f69e`. Drop tests, changesets and changelogs and the
+ * production readers fall into three radii, only the first of which the list
+ * above is about: this file plus 8 more naming the set directly, plus 4 more
+ * calling `isExpandableFieldType`, plus 13 more calling `buildExpandFields`.
+ * The sweep was controlled by planting a reader under `apps/console/src/` and
+ * confirming the same command found it — `apps/` holds no reader today, and a
+ * zero-hit region is otherwise indistinguishable from a blind spot.
  *
  * The third one used to be a second hand-maintained copy, and this comment used
  * to claim the set "mirrors the form layer's `DATA_SOURCE_FIELD_TYPES`

package/dist/utils/expand-fields.js

@@ -8,14 +8,52 @@
 import { columnIdentity } from './column-identity.js';
 /**
  * Relational ("reference-bearing") field types whose stored value is a foreign
- * key into another object — and which therefore benefit from `$expand` so a
- * list / grid / detail cell can render the related record's display name
- * instead of a bare id placeholder ("—").
+ * key into another object — and which therefore benefit from `$expand`, so a
+ * response carries the related record instead of only its foreign key.
  *
  * `user` is a lookup specialised to `sys_user`: it carries the same `reference`
  * + id storage and the server resolves it through the same expand path as
  * `lookup` / `master_detail`, so a `user` column that is NOT requested for
- * expansion comes back as a raw user id and renders as "—" (objectui#2032).
+ * expansion comes back as a raw user id (objectui#2032). What a CELL then
+ * prints for that id is deliberately not stated here — see the next section.
+ *
+ * ## No rendering claim is made here, on purpose — objectui#8693
+ *
+ * Both paragraphs above used to make one: the `user` sentence ended "…and
+ * renders as '—'", and the opening one called the unexpanded cell "a bare id
+ * placeholder ('—')". Measured on `da5e4f69e` by resolving each family through
+ * `getCellRenderer` and rendering three unexpanded primitives:
+ *
+ * | unexpanded value     | `lookup` / `master_detail` / `tree` | `user`             |
+ * |----------------------|-------------------------------------|--------------------|
+ * | `'u_1'`              | `u_1`, plain truncated span         | `u_1`, same span   |
+ * | `'01HQZX9K2M4N6P8R'` | muted `—`                           | the raw ULID       |
+ * | `'Ada Lovelace'`     | `Ada Lovelace`, plain span          | the raw string     |
+ *
+ * Wrong twice over. `user` never drew the em-dash at all — `UserCellRenderer`
+ * has no resolver, no `useLookupName`, no `isLikelyOpaqueId`. And the three
+ * families that do draw it draw it ONLY for values `isLikelyOpaqueId` accepts;
+ * that qualifier is the entire content of the behaviour and the sentence never
+ * carried it, so a reader was told a human-readable id would degrade visibly
+ * when it printed as if it were a name — the defect objectui#8434 was for.
+ *
+ * It is not replaced by a corrected sentence, because a corrected sentence
+ * could not be kept true HERE. `@object-ui/core` does not depend on
+ * `@object-ui/fields` in `dependencies`, `peerDependencies` or
+ * `devDependencies` — the arrow runs the other way — so no test that can reach
+ * this file can render the cell it would describe, and nothing in this repo
+ * compares a docblock to rendered output. A replacement would be checked by
+ * whatever checked the last one: nobody. Its shelf life was measured too —
+ * while objectui#8693 was open, PR #8698 (objectui#8434) sat in the merge
+ * queue rewriting the `user` column of that very table: on its head
+ * `3692f7218` all three primitives render an unresolved-reference affordance
+ * that KEEPS the raw value. A corrected sentence would have been stale before
+ * it landed. The other three families are byte-identical on both trees.
+ *
+ * The storage claim is the half this set actually depends on, and that half IS
+ * checkable here (`__tests__/expand-fields.test.ts`, plus the identity pins
+ * below). How an unexpanded reference prints belongs next to the renderers in
+ * `@object-ui/fields`, where a test can fail.
  *
  * Note on `tree`: a self-referencing hierarchy field is a reference too, so it
  * belongs in this set; whether the backend materialises the expanded object
@@ -32,6 +70,12 @@ import { columnIdentity } from './column-identity.js';
  * the falsification note at the end. Read the list below as the lineage of the
  * conversions, not as a census; the mechanical fact is the identity pins.
  *
+ * Re-measured for objectui#8693 on `da5e4f69e`: stale again, by FOUR. The
+ * commit that corrected the "fourth and last" claim (objectui#5874 / #6064)
+ * converged four more private copies of its own and never added them here —
+ * the last four bullets below. Re-derive before trusting it; the recipe is at
+ * the end of the list.
+ *
  * This is the reference-bearing FAMILY, not the `$expand` builder's private
  * list, and these concerns read it under several different words:
  *
@@ -44,7 +88,7 @@ import { columnIdentity } from './column-identity.js';
  *  - the grid's bulk-action dialog — `widgetNeedsDataSource` in
  *    `packages/plugin-grid/src/components/bulkParamToField.ts`, which decides
  *    which param widget is handed the grid's `DataSource` and which param field
- *    shape carries `reference_to` / `display_field`;
+ *    shape carries `reference` / `displayField`;
  *  - the action-param dialog — `paramToField` in
  *    `packages/app-shell/src/utils/paramToField.ts`, which decides which param
  *    carries a reference target (objectui#5312);
@@ -53,7 +97,33 @@ import { columnIdentity } from './column-identity.js';
  *  - the dashboard table's `$expand` whitelist — `computeLookupExpand` in
  *    `packages/plugin-dashboard/src/ObjectDataTable.tsx` (objectui#5692);
  *  - the dashboard's relation/link test — `isLookupType` in
- *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692).
+ *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692);
+ *  - the action-param RESOLVER (one step before `paramToField`) —
+ *    `packages/app-shell/src/utils/resolveActionParams.ts` (objectui#5874);
+ *  - the detail header's relation test — `HeaderHighlight.tsx` in
+ *    `packages/plugin-detail` (objectui#5874);
+ *  - the detail drawer's relation test — `RecordDetailDrawer.tsx` in
+ *    `packages/plugin-detail`, reading through `isExpandableFieldType`
+ *    (objectui#5874);
+ *  - the kanban board's `$expand` — `ObjectKanban.tsx` in
+ *    `packages/plugin-kanban`, reading through `buildExpandFields`
+ *    (objectui#5874).
+ *
+ * ⚠️ Re-derive rather than trust. One command, from the repo root, over the
+ * whole tree with NO pathspec. (Narrowing it to `packages/` + a `*` segment +
+ * `/src` matches ZERO files, and would drop `apps/` besides. The two-character
+ * sequence is spelled out in words here because writing it literally would end
+ * this comment.)
+ *
+ *     git grep -lE 'EXPANDABLE_FIELD_TYPES|isExpandableFieldType|buildExpandFields'
+ *
+ * 96 files on `da5e4f69e`. Drop tests, changesets and changelogs and the
+ * production readers fall into three radii, only the first of which the list
+ * above is about: this file plus 8 more naming the set directly, plus 4 more
+ * calling `isExpandableFieldType`, plus 13 more calling `buildExpandFields`.
+ * The sweep was controlled by planting a reader under `apps/console/src/` and
+ * confirming the same command found it — `apps/` holds no reader today, and a
+ * zero-hit region is otherwise indistinguishable from a blind spot.
  *
  * The third one used to be a second hand-maintained copy, and this comment used
  * to claim the set "mirrors the form layer's `DATA_SOURCE_FIELD_TYPES`

package/dist/utils/extract-records.d.ts

@@ -6,11 +6,71 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Extract an array of records from various API response formats.
- * Supports: raw array, { records: [] }, { data: [] }, { value: [] }.
+ * Extract the rows array out of a `DataSource.find()` answer.
  *
- * This utility normalises the different shapes returned by ObjectStack,
- * OData, and MSW mock endpoints so that every data-fetching component
- * can rely on a single extraction path.
+ * Accepted shapes, in the order they are tried:
+ *
+ *   1. a bare array — the live non-envelope shape fakes and `ValueDataSource`
+ *      answer with;
+ *   2. `{ data: [] }` — the ONE rows member `QueryResult` (`@object-ui/types`)
+ *      declares;
+ *   3. `{ value: [] }` — the OData spelling, still LIVE at this seam (see
+ *      below).
+ *
+ * ## `records` is NOT read here (objectui#6839, following #5945 / #6726)
+ *
+ * A `records` arm used to sit AHEAD of `data` — the precedence inversion
+ * objectui#5945 was filed about and objectui#6726 repaired by hand in seven
+ * modules. `records` is the below-the-adapter spelling: both
+ * `ObjectStackAdapter.normalizeQueryResult` (`@object-ui/data-objectstack`)
+ * and `ApiDataSource.normalizeQueryResult` (its `['data','items','results',
+ * 'records','value']` envelope loop) CONSUME the server/SDK `records` envelope
+ * and return `data` before the answer ever reaches this helper. Every consumer
+ * below calls it strictly ABOVE that fold, so the arm was unreachable — and an
+ * unreachable tolerant arm is exactly where a non-conforming producer keeps
+ * working unrejected (AGENTS.md #0.1). Worse, being FIRST, it outranked the
+ * contract's own member: a producer emitting both would have had `data`
+ * ignored.
+ *
+ * Measured on this tree, per consumer rather than once for all of them, since
+ * this helper is reached from ten call sites in nine packages:
+ *
+ *   packages/plugin-charts/src/ObjectChart.tsx        (x2: rows, ref labels)
+ *   packages/plugin-dashboard/src/ObjectDataTable.tsx
+ *   packages/plugin-dashboard/src/ObjectPivotTable.tsx
+ *   packages/plugin-gantt/src/ObjectGantt.tsx         (ref option labels)
+ *   packages/plugin-kanban/src/ObjectKanban.tsx
+ *   packages/plugin-timeline/src/ObjectTimeline.tsx
+ *   packages/core/src/utils/non-grid-row-ceiling.ts   (applyNonGridRowCeiling,
+ *     itself the seam for ObjectCalendar, ObjectGantt, ObjectMap, ObjectTree;
+ *     measured when it lived in `@object-ui/react`, moved here unchanged by
+ *     objectui#7508)
+ *
+ * ZERO of them can be reached by a `records` envelope: no `find()` in any of
+ * those packages, nor in the apps and examples that mount them, emits one.
+ * CONTROL, so the zero is a reading rather than a miss — the same sweep DOES
+ * find `records` envelopes elsewhere: `ViewDataProvider`'s own `ResolvedData`
+ * (a different contract, served by that module's own private reader), the raw
+ * Cloud HTTP payloads, the client-SDK doubles below `normalizeQueryResult`,
+ * the record-visibility batch route stubs, and one live `find()` double at
+ * `plugin-list`'s ObjectGallery — a consumer with its OWN unwrap ladder, which
+ * does not come through here.
+ *
+ * ⛔ Do not restore the arm, and ⛔ do not widen `QueryResult` to bless
+ * `records` instead — that is a published-type change and the maintainer's
+ * call, the same floor objectui#6726 and #6840 respected. A producer that
+ * really does speak `records` belongs behind an adapter that folds it into
+ * `data`, which is what both adapters above already do.
+ *
+ * ## `value` STAYS — it is live here, and that is seam-local
+ *
+ * objectui#6840 / PR #6916 deleted the `value` arm from `ObjectView`'s ladder
+ * on a measured zero at THAT seam, and said in as many words that its zero
+ * must not be carried here. It does not: five `find()` doubles emit
+ * `{ value: [...] }` into this helper today (three in `plugin-kanban`, two in
+ * `plugin-calendar`). Deleting it here would break them. Whether `value`
+ * should survive at this seam is its own card with its own measurement.
+ *
+ * Pinned per module by the `*.contractEnvelope-6839.*` suites.
  */
 export declare function extractRecords(results: unknown): any[];

package/dist/utils/extract-records.js

@@ -6,21 +6,78 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Extract an array of records from various API response formats.
- * Supports: raw array, { records: [] }, { data: [] }, { value: [] }.
+ * Extract the rows array out of a `DataSource.find()` answer.
  *
- * This utility normalises the different shapes returned by ObjectStack,
- * OData, and MSW mock endpoints so that every data-fetching component
- * can rely on a single extraction path.
+ * Accepted shapes, in the order they are tried:
+ *
+ *   1. a bare array — the live non-envelope shape fakes and `ValueDataSource`
+ *      answer with;
+ *   2. `{ data: [] }` — the ONE rows member `QueryResult` (`@object-ui/types`)
+ *      declares;
+ *   3. `{ value: [] }` — the OData spelling, still LIVE at this seam (see
+ *      below).
+ *
+ * ## `records` is NOT read here (objectui#6839, following #5945 / #6726)
+ *
+ * A `records` arm used to sit AHEAD of `data` — the precedence inversion
+ * objectui#5945 was filed about and objectui#6726 repaired by hand in seven
+ * modules. `records` is the below-the-adapter spelling: both
+ * `ObjectStackAdapter.normalizeQueryResult` (`@object-ui/data-objectstack`)
+ * and `ApiDataSource.normalizeQueryResult` (its `['data','items','results',
+ * 'records','value']` envelope loop) CONSUME the server/SDK `records` envelope
+ * and return `data` before the answer ever reaches this helper. Every consumer
+ * below calls it strictly ABOVE that fold, so the arm was unreachable — and an
+ * unreachable tolerant arm is exactly where a non-conforming producer keeps
+ * working unrejected (AGENTS.md #0.1). Worse, being FIRST, it outranked the
+ * contract's own member: a producer emitting both would have had `data`
+ * ignored.
+ *
+ * Measured on this tree, per consumer rather than once for all of them, since
+ * this helper is reached from ten call sites in nine packages:
+ *
+ *   packages/plugin-charts/src/ObjectChart.tsx        (x2: rows, ref labels)
+ *   packages/plugin-dashboard/src/ObjectDataTable.tsx
+ *   packages/plugin-dashboard/src/ObjectPivotTable.tsx
+ *   packages/plugin-gantt/src/ObjectGantt.tsx         (ref option labels)
+ *   packages/plugin-kanban/src/ObjectKanban.tsx
+ *   packages/plugin-timeline/src/ObjectTimeline.tsx
+ *   packages/core/src/utils/non-grid-row-ceiling.ts   (applyNonGridRowCeiling,
+ *     itself the seam for ObjectCalendar, ObjectGantt, ObjectMap, ObjectTree;
+ *     measured when it lived in `@object-ui/react`, moved here unchanged by
+ *     objectui#7508)
+ *
+ * ZERO of them can be reached by a `records` envelope: no `find()` in any of
+ * those packages, nor in the apps and examples that mount them, emits one.
+ * CONTROL, so the zero is a reading rather than a miss — the same sweep DOES
+ * find `records` envelopes elsewhere: `ViewDataProvider`'s own `ResolvedData`
+ * (a different contract, served by that module's own private reader), the raw
+ * Cloud HTTP payloads, the client-SDK doubles below `normalizeQueryResult`,
+ * the record-visibility batch route stubs, and one live `find()` double at
+ * `plugin-list`'s ObjectGallery — a consumer with its OWN unwrap ladder, which
+ * does not come through here.
+ *
+ * ⛔ Do not restore the arm, and ⛔ do not widen `QueryResult` to bless
+ * `records` instead — that is a published-type change and the maintainer's
+ * call, the same floor objectui#6726 and #6840 respected. A producer that
+ * really does speak `records` belongs behind an adapter that folds it into
+ * `data`, which is what both adapters above already do.
+ *
+ * ## `value` STAYS — it is live here, and that is seam-local
+ *
+ * objectui#6840 / PR #6916 deleted the `value` arm from `ObjectView`'s ladder
+ * on a measured zero at THAT seam, and said in as many words that its zero
+ * must not be carried here. It does not: five `find()` doubles emit
+ * `{ value: [...] }` into this helper today (three in `plugin-kanban`, two in
+ * `plugin-calendar`). Deleting it here would break them. Whether `value`
+ * should survive at this seam is its own card with its own measurement.
+ *
+ * Pinned per module by the `*.contractEnvelope-6839.*` suites.
  */
 export function extractRecords(results) {
     if (Array.isArray(results)) {
         return results;
     }
     if (results && typeof results === 'object') {
-        if (Array.isArray(results.records)) {
-            return results.records;
-        }
         if (Array.isArray(results.data)) {
             return results.data;
         }