@object-ui/core 16.1.0 → 17.2.0

package/dist/utils/managedBy.d.ts

@@ -1,51 +1,54 @@
 /**
- * managedBy — the single source of truth for interpreting an object's
- * lifecycle bucket (`ObjectSchema.managedBy`) into CRUD affordances.
+ * managedBy — the UI end of the platform's `managedBy` → CRUD affordance
+ * contract (ADR-0103).
  *
- * UI-side mirror of the framework's `resolveCrudAffordances()`
- * (`@objectstack/spec/data/object.zod.ts`, ADR-0103). Lives in `@object-ui/core`
- * — React-free and reachable by every UI package (app-shell, plugin-detail,
- * plugin-form, plugin-grid) — so the bucket logic is defined ONCE instead of
- * hand-mirrored in each. Components ask "should I show New / Import / Edit /
- * Delete / Export?" and get an answer that tracks the object's lifecycle without
- * special-casing `sys_*` names.
+ * ## What is spec-owned here, and what is not (objectstack#4115)
  *
- * The bucket UNION type lives in `@object-ui/types` (`ManagedByBucket`) so the
- * schema field can reference it; this module re-exports it for convenience.
- * Only the affordance BOOLEANS live here — all translated copy (badge variants,
- * empty-state messages) stays in `@object-ui/app-shell`.
+ * The bucket logic is **the spec's**, and this module now says so in code
+ * rather than in a comment. `CrudAffordances` / `RowCrudPredicates` are
+ * re-exported from `@objectstack/spec/data`, and the bucket resolution itself
+ * delegates to the spec's `resolveCrudAffordances()`.
+ *
+ * This module used to describe itself as a "UI-side mirror" of that function
+ * and carry its own `DEFAULTS` table — a line-for-line copy of the spec's
+ * `CRUD_AFFORDANCE_DEFAULTS`, plus a copy of its override parser. A faithful
+ * copy passes every value comparison and every behavioural test, so nothing
+ * would have caught the release in which the spec re-buckets an object class;
+ * reference identity is the only check that distinguishes a re-export from a
+ * fork (objectui#3003).
+ *
+ * What is genuinely objectui's and keeps a local name:
+ * {@link resolveEffectiveCrudAffordances} — the spec's object-level matrix
+ * INTERSECTED with the server-resolved effective API operation set (#3391), so
+ * the UI never offers a button the server would 405. The spec's function has
+ * no such notion; naming ours after it was the misdescription this burn-down
+ * removes.
+ *
+ * Lives in `@object-ui/core` — React-free and reachable by every UI package
+ * (app-shell, plugin-detail, plugin-form, plugin-grid) — so the intersection is
+ * defined ONCE instead of hand-mirrored in each. The bucket UNION type lives in
+ * `@object-ui/types` (`ManagedByBucket`) and is re-exported here for
+ * convenience. All translated copy (badge variants, empty-state messages) stays
+ * in `@object-ui/app-shell`.
  */
+import { type CrudAffordances, type RowCrudPredicates } from '@objectstack/spec/data';
 export type { ManagedByBucket } from '@object-ui/types';
-export interface CrudAffordances {
-    /** Generic "New" button for single-record creation. */
-    create: boolean;
-    /** CSV bulk-import wizard. */
-    import: boolean;
-    /** Inline + form editing of existing rows. */
-    edit: boolean;
-    /** Row-level + bulk delete. */
-    delete: boolean;
-    /** CSV / clipboard export. */
-    exportCsv: boolean;
-    /**
-     * Per-record CEL predicates for the built-in row Edit/Delete actions,
-     * present only when `userActions.edit` / `delete` used the object form
-     * (objectui#2614). Carried through as authored for row renderers to evaluate;
-     * they never affect the object-level booleans above.
-     */
-    editPredicates?: RowCrudPredicates;
-    deletePredicates?: RowCrudPredicates;
-}
-/** Per-record predicates from the #2614 object form of a userActions flag. */
-export interface RowCrudPredicates {
-    visibleWhen?: unknown;
-    disabledWhen?: unknown;
-}
+/**
+ * The resolved CRUD affordance matrix and its per-record predicate envelope
+ * are **spec-owned** (`@objectstack/spec/data`, ADR-0103) and re-exported here,
+ * not re-declared.
+ *
+ * Note this also TIGHTENS the predicate types: the local copies typed
+ * `visibleWhen` / `disabledWhen` as `unknown`, while the spec types them as
+ * `Expression | ExpressionInput` — the authored CEL shorthand or its envelope.
+ * The local `unknown` was imprecision, not a deliberate dialect.
+ */
+export type { CrudAffordances, RowCrudPredicates };
 /** `edit`/`delete` accept a bare boolean or the #2614 object form. */
 export type UserActionOverride = boolean | {
     enabled?: boolean;
-    visibleWhen?: unknown;
-    disabledWhen?: unknown;
+    visibleWhen?: RowCrudPredicates['visibleWhen'];
+    disabledWhen?: RowCrudPredicates['disabledWhen'];
 };
 export interface UserActionsOverride {
     create?: boolean;
@@ -63,11 +66,14 @@ export interface SchemaLike {
  * the given bucket default, surfacing any per-record predicates alongside.
  *
  * THE single parser for the `userActions.{edit,delete}` override shape — every
- * UI package (grid row affordances, related-list row predicates, this module's
- * own `resolveCrudAffordances`) routes through here instead of re-implementing
- * the boolean/object-form parse locally. `base` is the bucket default an
- * omitted `enabled` falls back to (callers that only gate on an explicit
- * opt-out pass `true`; predicate extraction is independent of `base`).
+ * UI package (grid row affordances, related-list row predicates) routes through
+ * here instead of re-implementing the boolean/object-form parse locally. The
+ * spec keeps its equivalent (`normalizeRowCrudOverride`) module-private, so
+ * this stays a local declaration — under a name the spec does not own.
+ *
+ * `base` is the bucket default an omitted `enabled` falls back to (callers that
+ * only gate on an explicit opt-out pass `true`; predicate extraction is
+ * independent of `base`).
  */
 export declare function normalizeUserAction(v: UserActionOverride | undefined | null, base: boolean): {
     enabled: boolean;
@@ -81,14 +87,47 @@ export declare function normalizeUserAction(v: UserActionOverride | undefined |
  * {@link normalizeUserAction} so the parse lives in exactly one place.
  */
 export declare function userActionPredicates(v: UserActionOverride | undefined | null): RowCrudPredicates | undefined;
-/** Resolve the effective CRUD affordances for an object schema. */
-export declare function resolveCrudAffordances(obj: SchemaLike | null | undefined): CrudAffordances;
+/**
+ * Resolve the CRUD affordances a UI surface should expose for an object —
+ * the spec's object-level matrix, INTERSECTED with what the server will
+ * actually accept.
+ *
+ * The bucket/`userActions` half is **not computed here**: it is delegated to
+ * `resolveCrudAffordances()` from `@objectstack/spec/data` (ADR-0103), so the
+ * bucket table has exactly one definition on the platform. Only the
+ * intersection below is objectui's, which is why this function no longer
+ * carries the spec's name (objectstack#4115).
+ *
+ * @param obj The object schema (managedBy bucket + userActions overrides).
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   provided, each affordance bit is ANDed with the corresponding API operation
+ *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
+ *   so the UI never shows a button the server would 405. Passing `undefined`
+ *   (old backend / no effective set) leaves the affordances untouched —
+ *   backward-compatible. An empty array means "expose nothing" → all bits off.
+ */
+export declare function resolveEffectiveCrudAffordances(obj: SchemaLike | null | undefined, effectiveApiOperations?: readonly string[] | null): CrudAffordances;
 /** True only when a `userActions` flag (bare boolean or #2614 object form) opts the write in. */
 export declare function isWriteOptedIn(v: UserActionOverride | undefined | null): boolean;
 /**
- * ADR-0103 — a `system`-bucket object that opened ANY write via `userActions`
- * is admin/user-writable DATA, not an engine-owned monitoring surface. Used to
- * pick the writable-system badge/empty-state copy.
+ * True for a platform-defined schema whose DATA is admin/user-writable — the
+ * `system-data` bucket. Used to pick the writable-system badge/empty-state copy
+ * instead of the engine-owned "read-only monitoring surface" copy.
+ *
+ * **Simplified in protocol 17 (objectstack#3355).** Under ADR-0103's v16 split
+ * this had to RECOVER the distinction from `userActions`: `system` doubled as
+ * both the engine-owned default and the writable set, so "did it open any
+ * write?" was the only way to tell a Notification Preferences grid from an
+ * automation-run log. v17 retired that overload — the writable half is now the
+ * `system-data` bucket (writable by DEFAULT) and the engine-owned half is
+ * `engine-owned` — so the bucket answers the question directly and the
+ * `userActions` probe would only re-derive what the value already states.
+ *
+ * The narrowing case is deliberately still `true`: a `system-data` grid that
+ * narrows to edit-only is still platform-schema/user-data and should read as
+ * such. The spec refuses `system-data` on an object that narrows away every
+ * write, so there is no "writable bucket with no writes" shape to worry about.
  */
 export declare function isSystemWritable(obj: SchemaLike | null | undefined): boolean;
 /**
@@ -97,5 +136,12 @@ export declare function isSystemWritable(obj: SchemaLike | null | undefined): bo
  * `append-only` / `better-auth` objects resolve to `false` unless they opened
  * `userActions.edit`. (Per-record predicates gate row action buttons, not
  * object-level editability, so only the resolved boolean matters here.)
+ *
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (`/me/permissions` `apiOperations`, #3391/#3546). When
+ *   provided, inline-edit is additionally ANDed with the server allowing
+ *   `update`, so a record page never offers double-click/pencil editing the
+ *   server would 405. `undefined` (old backend / unrestricted) leaves the
+ *   bucket affordance untouched.
  */
-export declare function isObjectInlineEditable(obj: SchemaLike | null | undefined): boolean;
+export declare function isObjectInlineEditable(obj: SchemaLike | null | undefined, effectiveApiOperations?: readonly string[] | null): boolean;

package/dist/utils/managedBy.js

@@ -1,38 +1,50 @@
 /**
- * managedBy — the single source of truth for interpreting an object's
- * lifecycle bucket (`ObjectSchema.managedBy`) into CRUD affordances.
+ * managedBy — the UI end of the platform's `managedBy` → CRUD affordance
+ * contract (ADR-0103).
  *
- * UI-side mirror of the framework's `resolveCrudAffordances()`
- * (`@objectstack/spec/data/object.zod.ts`, ADR-0103). Lives in `@object-ui/core`
- * — React-free and reachable by every UI package (app-shell, plugin-detail,
- * plugin-form, plugin-grid) — so the bucket logic is defined ONCE instead of
- * hand-mirrored in each. Components ask "should I show New / Import / Edit /
- * Delete / Export?" and get an answer that tracks the object's lifecycle without
- * special-casing `sys_*` names.
+ * ## What is spec-owned here, and what is not (objectstack#4115)
  *
- * The bucket UNION type lives in `@object-ui/types` (`ManagedByBucket`) so the
- * schema field can reference it; this module re-exports it for convenience.
- * Only the affordance BOOLEANS live here — all translated copy (badge variants,
- * empty-state messages) stays in `@object-ui/app-shell`.
+ * The bucket logic is **the spec's**, and this module now says so in code
+ * rather than in a comment. `CrudAffordances` / `RowCrudPredicates` are
+ * re-exported from `@objectstack/spec/data`, and the bucket resolution itself
+ * delegates to the spec's `resolveCrudAffordances()`.
+ *
+ * This module used to describe itself as a "UI-side mirror" of that function
+ * and carry its own `DEFAULTS` table — a line-for-line copy of the spec's
+ * `CRUD_AFFORDANCE_DEFAULTS`, plus a copy of its override parser. A faithful
+ * copy passes every value comparison and every behavioural test, so nothing
+ * would have caught the release in which the spec re-buckets an object class;
+ * reference identity is the only check that distinguishes a re-export from a
+ * fork (objectui#3003).
+ *
+ * What is genuinely objectui's and keeps a local name:
+ * {@link resolveEffectiveCrudAffordances} — the spec's object-level matrix
+ * INTERSECTED with the server-resolved effective API operation set (#3391), so
+ * the UI never offers a button the server would 405. The spec's function has
+ * no such notion; naming ours after it was the misdescription this burn-down
+ * removes.
+ *
+ * Lives in `@object-ui/core` — React-free and reachable by every UI package
+ * (app-shell, plugin-detail, plugin-form, plugin-grid) — so the intersection is
+ * defined ONCE instead of hand-mirrored in each. The bucket UNION type lives in
+ * `@object-ui/types` (`ManagedByBucket`) and is re-exported here for
+ * convenience. All translated copy (badge variants, empty-state messages) stays
+ * in `@object-ui/app-shell`.
  */
-const DEFAULTS = {
-    platform: { create: true, import: true, edit: true, delete: true, exportCsv: true },
-    config: { create: true, import: false, edit: true, delete: true, exportCsv: true },
-    system: { create: false, import: false, edit: false, delete: false, exportCsv: true },
-    'engine-owned': { create: false, import: false, edit: false, delete: false, exportCsv: true },
-    'append-only': { create: false, import: false, edit: false, delete: false, exportCsv: true },
-    'better-auth': { create: false, import: false, edit: false, delete: false, exportCsv: true },
-};
+import { resolveCrudAffordances as resolveSpecCrudAffordances, } from '@objectstack/spec/data';
 /**
  * Collapse an `edit`/`delete` override (boolean or #2614 object form) onto
  * the given bucket default, surfacing any per-record predicates alongside.
  *
  * THE single parser for the `userActions.{edit,delete}` override shape — every
- * UI package (grid row affordances, related-list row predicates, this module's
- * own `resolveCrudAffordances`) routes through here instead of re-implementing
- * the boolean/object-form parse locally. `base` is the bucket default an
- * omitted `enabled` falls back to (callers that only gate on an explicit
- * opt-out pass `true`; predicate extraction is independent of `base`).
+ * UI package (grid row affordances, related-list row predicates) routes through
+ * here instead of re-implementing the boolean/object-form parse locally. The
+ * spec keeps its equivalent (`normalizeRowCrudOverride`) module-private, so
+ * this stays a local declaration — under a name the spec does not own.
+ *
+ * `base` is the bucket default an omitted `enabled` falls back to (callers that
+ * only gate on an explicit opt-out pass `true`; predicate extraction is
+ * independent of `base`).
  */
 export function normalizeUserAction(v, base) {
     if (v == null)
@@ -59,24 +71,58 @@ export function normalizeUserAction(v, base) {
 export function userActionPredicates(v) {
     return normalizeUserAction(v, false).predicates;
 }
-/** Resolve the effective CRUD affordances for an object schema. */
-export function resolveCrudAffordances(obj) {
-    const bucket = obj?.managedBy ?? 'platform';
-    const base = DEFAULTS[bucket] ?? DEFAULTS.platform;
-    const o = obj?.userActions ?? {};
-    const edit = normalizeUserAction(o.edit, base.edit);
-    const del = normalizeUserAction(o.delete, base.delete);
-    const out = {
-        create: o.create ?? base.create,
-        import: o.import ?? base.import,
-        edit: edit.enabled,
-        delete: del.enabled,
-        exportCsv: o.exportCsv ?? base.exportCsv,
-    };
-    if (edit.predicates)
-        out.editPredicates = edit.predicates;
-    if (del.predicates)
-        out.deletePredicates = del.predicates;
+/**
+ * The affordance-bit → server API-operation mapping used to intersect the
+ * UI-intent affordances with the server's effective API operation set (#3391).
+ * This is the objectui end of the framework's `API_METHOD_DERIVATION` contract:
+ * the button predicate is `affordance(op) ∧ effective.api(op)`.
+ */
+const AFFORDANCE_TO_API_OPERATION = {
+    create: 'create',
+    import: 'import',
+    edit: 'update',
+    delete: 'delete',
+    exportCsv: 'export',
+};
+/**
+ * Resolve the CRUD affordances a UI surface should expose for an object —
+ * the spec's object-level matrix, INTERSECTED with what the server will
+ * actually accept.
+ *
+ * The bucket/`userActions` half is **not computed here**: it is delegated to
+ * `resolveCrudAffordances()` from `@objectstack/spec/data` (ADR-0103), so the
+ * bucket table has exactly one definition on the platform. Only the
+ * intersection below is objectui's, which is why this function no longer
+ * carries the spec's name (objectstack#4115).
+ *
+ * @param obj The object schema (managedBy bucket + userActions overrides).
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   provided, each affordance bit is ANDed with the corresponding API operation
+ *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
+ *   so the UI never shows a button the server would 405. Passing `undefined`
+ *   (old backend / no effective set) leaves the affordances untouched —
+ *   backward-compatible. An empty array means "expose nothing" → all bits off.
+ */
+export function resolveEffectiveCrudAffordances(obj, effectiveApiOperations) {
+    // The spec's resolver is the single definition of the bucket defaults and the
+    // `userActions` override parse (including the #2614 object form). Its input
+    // type does not model the `null`s objectui's loosely-typed schemas carry, so
+    // they are normalised away at this one seam rather than re-deriving anything.
+    const out = resolveSpecCrudAffordances({
+        managedBy: obj?.managedBy ?? undefined,
+        userActions: (obj?.userActions ?? undefined),
+    });
+    // [#3391] Intersect with the server's effective API operations when present.
+    // The frontend consumes the effective set the server hands down; it never
+    // reads the raw `apiMethods` nor re-derives.
+    if (Array.isArray(effectiveApiOperations)) {
+        const eff = new Set(effectiveApiOperations);
+        for (const [bit, op] of Object.entries(AFFORDANCE_TO_API_OPERATION)) {
+            if (out[bit] && !eff.has(op))
+                out[bit] = false;
+        }
+    }
     return out;
 }
 /** True only when a `userActions` flag (bare boolean or #2614 object form) opts the write in. */
@@ -84,15 +130,26 @@ export function isWriteOptedIn(v) {
     return v === true || (typeof v === 'object' && v !== null && v.enabled === true);
 }
 /**
- * ADR-0103 — a `system`-bucket object that opened ANY write via `userActions`
- * is admin/user-writable DATA, not an engine-owned monitoring surface. Used to
- * pick the writable-system badge/empty-state copy.
+ * True for a platform-defined schema whose DATA is admin/user-writable — the
+ * `system-data` bucket. Used to pick the writable-system badge/empty-state copy
+ * instead of the engine-owned "read-only monitoring surface" copy.
+ *
+ * **Simplified in protocol 17 (objectstack#3355).** Under ADR-0103's v16 split
+ * this had to RECOVER the distinction from `userActions`: `system` doubled as
+ * both the engine-owned default and the writable set, so "did it open any
+ * write?" was the only way to tell a Notification Preferences grid from an
+ * automation-run log. v17 retired that overload — the writable half is now the
+ * `system-data` bucket (writable by DEFAULT) and the engine-owned half is
+ * `engine-owned` — so the bucket answers the question directly and the
+ * `userActions` probe would only re-derive what the value already states.
+ *
+ * The narrowing case is deliberately still `true`: a `system-data` grid that
+ * narrows to edit-only is still platform-schema/user-data and should read as
+ * such. The spec refuses `system-data` on an object that narrows away every
+ * write, so there is no "writable bucket with no writes" shape to worry about.
  */
 export function isSystemWritable(obj) {
-    if (obj?.managedBy !== 'system')
-        return false;
-    const o = obj?.userActions ?? {};
-    return o.create === true || isWriteOptedIn(o.edit) || isWriteOptedIn(o.delete);
+    return obj?.managedBy === 'system-data';
 }
 /**
  * Whether an object's rows may be edited in place (detail inline-edit / form
@@ -100,7 +157,14 @@ export function isSystemWritable(obj) {
  * `append-only` / `better-auth` objects resolve to `false` unless they opened
  * `userActions.edit`. (Per-record predicates gate row action buttons, not
  * object-level editability, so only the resolved boolean matters here.)
+ *
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (`/me/permissions` `apiOperations`, #3391/#3546). When
+ *   provided, inline-edit is additionally ANDed with the server allowing
+ *   `update`, so a record page never offers double-click/pencil editing the
+ *   server would 405. `undefined` (old backend / unrestricted) leaves the
+ *   bucket affordance untouched.
  */
-export function isObjectInlineEditable(obj) {
-    return resolveCrudAffordances(obj).edit;
+export function isObjectInlineEditable(obj, effectiveApiOperations) {
+    return resolveEffectiveCrudAffordances(obj, effectiveApiOperations).edit;
 }

package/dist/utils/normalize-list-view.d.ts

@@ -0,0 +1,109 @@
+/**
+ * ObjectUI — list-view vocabulary canonicalization
+ * 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 { RowHeight } from '@objectstack/spec/ui';
+/** ListView's toolbar density vocabulary — three steps, not the spec's five. */
+export type DensityMode = 'compact' | 'comfortable' | 'spacious';
+/**
+ * The spec's `RowHeightSchema` vocabulary — **re-exported, not re-declared**.
+ *
+ * The hand-written union that used to sit here already advertised itself as
+ * "the spec's `RowHeightSchema` vocabulary" in its doc comment, which is the
+ * failure class objectstack#4115 is about: the claim was true when written and
+ * nothing would have caught the day it stopped being true. The maps below are
+ * `Record<RowHeight, …>`, so a spec-side addition now fails the build here
+ * instead of silently leaving a row height with no density mapping.
+ */
+export type { RowHeight };
+/**
+ * `densityMode` → `rowHeight`. The two vocabularies are not the same size: the
+ * spec has five row heights, ListView's toolbar offers three. Widening maps
+ * each density onto the spec value the renderer already resolves it back to
+ * (see {@link ROW_HEIGHT_TO_DENSITY_MODE}), so a fold followed by a read is a
+ * round trip — `spacious` → `tall` → `spacious`.
+ */
+export declare const DENSITY_MODE_TO_ROW_HEIGHT: Record<DensityMode, RowHeight>;
+/**
+ * `rowHeight` → `densityMode`, the read direction. Narrowing five values onto
+ * three is lossy by construction: `short` collapses into `compact` and
+ * `extra_tall` into `spacious`. Exported so the renderer and the persistence
+ * layer agree on the collapse instead of each hard-coding its own table.
+ */
+export declare const ROW_HEIGHT_TO_DENSITY_MODE: Record<RowHeight, DensityMode>;
+/**
+ * Tolerant reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}. View metadata is
+ * user-authored, so `rowHeight` is not guaranteed to be one of the five spec
+ * values — an unknown one lands on `comfortable` rather than rendering an
+ * undefined density. Keeping the fallback here means every surface collapses
+ * the same way.
+ */
+export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode;
+/**
+ * ObjectUI's `list-view` node historically used a different vocabulary from
+ * `@objectstack/spec` for the same concepts (`fields` where the spec says
+ * `columns`, `viewType` where it says `type`, …). Issue #2231 closed the
+ * type-level fork; #2890 closes the vocabulary fork.
+ *
+ * Stored view metadata in user databases still carries the legacy keys, so the
+ * renderer cannot simply stop accepting them. Per AGENTS.md Commandment #0.1 the
+ * answer is NOT a per-read-site `??` fallback — those fossilize a second de-facto
+ * contract and drift apart (they already had: `ObjectGrid` preferred `columns`
+ * in one branch and `fields` in another). Instead legacy acceptance lives HERE,
+ * in one documented normalizer at the component boundary, mirroring
+ * `normalizeSchemaReferenceKeys` (object schemas) and the spec's own
+ * `normalizeVisibleWhen` / `normalizeFilterOperator` migration bridges.
+ *
+ * Note this cannot be a `z.preprocess` on `ListViewSchema`: nothing on the
+ * render path parses view metadata through zod (the zod schemas are used by the
+ * CLI validator, the VS Code extension and tests only), so a schema-level fold
+ * would never run. The guarantee comes from the call site instead — `ListView`
+ * normalizes before it reads anything.
+ *
+ * The fold is deliberately one-directional: the canonical key wins when both are
+ * present, and the legacy key is REMOVED from the result so a read-site that was
+ * missed fails loudly instead of quietly taking the legacy path. Like a spec
+ * migration bridge, this is expected to be dropped in a future major once stored
+ * metadata has been migrated.
+ *
+ * Non-mutating and allocation-frugal: returns the input by reference when there
+ * is nothing to fold, so `ListView`'s downstream `useMemo`s keep a stable
+ * dependency identity on the common (already-canonical) path.
+ *
+ * Currently folded:
+ *  - `fields` → `columns` (#2890 scope A step 1)
+ *  - `densityMode` → `rowHeight` (#2890 scope A step 2)
+ *  - the `show*` toolbar flags → `userActions` (#2890 scope A step 3), and
+ *    `showDescription` → `appearance.showDescription`. The canonical key wins
+ *    per-flag, so a view may carry `userActions` for some toggles and a legacy
+ *    flag for others. NOTE the fold does not apply any default: an absent flag
+ *    stays absent, because the defaults are per-toggle (search/sort/filter/
+ *    rowHeight/group default ON, hideFields/rowColor default OFF) and belong to
+ *    the renderer, not to the vocabulary bridge.
+ *  - `aria: { label, describedBy }` → the spec's `AriaProps`
+ *    (`{ ariaLabel, ariaDescribedBy }`), and `sharing: { visibility, enabled }`
+ *    → the spec's `ViewSharing` (`{ type }`) — #2890 scope A step 5. `aria.live`
+ *    survives untouched: it has no spec counterpart.
+ *  - `filters` → `filter` (#2890 scope A step 4). A key rename only: BOTH keys
+ *    carry an ObjectQL FilterNode array (`[['stage','=','won']]`) everywhere in
+ *    objectui — every consumer passes the value straight to `$filter`. The spec
+ *    types `filter` as `ViewFilterRule[]` (`{field, operator, value}` objects),
+ *    so objectui's field is typed from the spec but used as something else.
+ *    That mismatch is real and out of scope here; converting formats inside a
+ *    vocabulary fold would change what reaches the data source.
+ *  - `viewType`: a missing kind, or the view CATEGORY `'list'` that AI-authored
+ *    metadata stores and hosts forward verbatim, becomes the renderable `'grid'`
+ *    — otherwise it reaches the renderer's typeless default branch and shows as
+ *    a red "Unknown component type" box.
+ *  - each `columns` entry's IDENTITY — `name` / `fieldName` → the spec's `field`
+ *    (#3104). This one MIRRORS instead of deleting, for the reason given on
+ *    {@link normalizeColumnIdentities}: `columns` entries cross the package
+ *    boundary into host renderers, so dropping `name` from under them is a
+ *    breaking change with no inventory. Runs AFTER the `fields` → `columns` fold
+ *    above, so a view that spells its column list the legacy way still gets its
+ *    entries canonicalized.
+ */
+export declare function normalizeListViewSchema<T>(schema: T): T;