@object-ui/core 16.1.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,1882 @@
 # @object-ui/core
 
+## 17.2.0
+
+### Minor Changes
+
+- bca45cc: Declare the 18 spec-owned action keys `ActionDef` had been absorbing silently.
+
+  `ActionDef` ends with `[key: string]: any`, so it accepted any key of any type —
+  a typo (`targt`) and a retired spec key (`execute`) both type-checked, then the
+  runner silently bound no handler (the #2169 "Mark Done does nothing" shape).
+  Step 1 (objectstack#4075) made that audible with a dev-mode warning. This is
+  step 2: the keys the warning identified as legitimate are now real fields.
+
+  - **18 keys promoted to explicit optional fields** — `ai`, `aria`, `bodyExtra`,
+    `bodyShape`, `bulkEnabled`, `component`, `icon`, `locations`, `mode`,
+    `objectName`, `order`, `recordIdField`, `recordIdParam`, `requiredPermissions`,
+    `requiresFeature`, `shortcut`, `variant`, `visible`. Every type is **derived**
+    from `@objectstack/spec`'s `ActionInput` (`SpecActionInput['locations']`, …),
+    never hand-copied: a hand-written duplicate of a spec shape is a second
+    contract that drifts, which is the failure this issue is about. Wrong-typed
+    values are now compile errors — `order: 'first'`, `variant: 'chartreuse'`,
+    `locations: ['nope']` — where before they were absorbed silently.
+  - **Derived from `z.input`, not `z.infer`.** `ActionSchema` is a `ZodPipe` whose
+    transform narrows `visible` from `string | { dialect, source }` to the
+    envelope alone. This runner consumes authored/stored rows, which are
+    rehydrated unparsed, so it sees the input shape; deriving from the inferred
+    `Action` would have rejected the raw-string predicate `ActionEngine`
+    explicitly supports.
+  - **Three `as any` casts deleted** in `ActionEngine` — `visible` and
+    `requiredPermissions` at the location filter, `locations` at registration.
+    They existed only because the fields were undeclared.
+  - **Four objectui-dialect keys marked `@deprecated`** with the spec spelling to
+    use instead — `actionType` (→ `type`), `api` and `endpoint` (→ `target`;
+    `executeAPI` already resolves `api || endpoint || target`), and `navigate`
+    (→ flat `target` / `openIn`). Only these four: the remaining dialect keys are
+    runner mechanics (chaining, toasts, post-execution reload/close) with no spec
+    counterpart, and pointing them at a spelling that does not exist would be
+    worse than leaving them declared.
+
+  **Breaking edge, deliberate.** `shortcut` and `bulkEnabled` were retired by
+  `@objectstack/spec` 17 as `retiredKey()` tombstones (`z.never()`), so authoring
+  either is already a hard parse rejection. Deriving their types rather than
+  hand-writing them turns that runtime rejection into a **compile error**: code
+  that assigned `shortcut: 'ctrl+k'` to an `ActionDef` compiled before and does
+  not now. Such metadata was already refused by the platform — this only moves the
+  failure to where it can be fixed. A host may still pass either explicitly via
+  `ActionEngine.registerAction(action, { shortcut, bulkEnabled })`; only authored
+  metadata stopped carrying them. `bulkEnabled`'s replacement is the list view's
+  `bulkActions` / `bulkActionDefs`; `shortcut` has none.
+
+  The index signature **stays** — removing it is step 3, and the inverted pin
+  asserting it is still present remains the issue's own completion check.
+
+- 4bf612c: Aggregate single-call mode for bulk actions: `execution: 'aggregate'` (objectui#3139).
+
+  A `bulkActionDefs` entry with `operation: 'custom'` used to have exactly one
+  dispatch shape: one action-runner call per selected record (`_rowRecord`
+  attached). "Select N rows → ONE call that receives every selected id" — the
+  zip-of-QR-codes / merged-PDF / batch-print shape — could not be expressed, so
+  downstream projects fell back to per-row `window.open` storms or gave up.
+
+  `BulkActionDef` now carries `execution?: 'perRecord' | 'aggregate'` (default
+  `'perRecord'`, existing views untouched). An aggregate def dispatches its
+  action exactly once for the whole selection with `params._selectedIds:
+string[]` injected and the full records published as
+  `context.selectedRecords`. The authored form usually just names a declared
+  object action — `{ name, operation: 'custom', execution: 'aggregate' }` —
+  and `resolveBulkActions` attaches the declaration. Results are
+  all-or-nothing: a failure is attributed to every id with the real error and
+  per-row Retry is hidden (re-running the action is the retry; a total failure
+  keeps the selection). `batchSize` does not apply; `maxRecords` still gates.
+
+  The executor rides the existing `executeBulkBatch` bulk-first decision tree —
+  the aggregate call is its `bulkCall`, and the per-row "fallback" only
+  re-throws the captured error for attribution, never fans out N dispatches
+  against an endpoint written for one `_selectedIds` call.
+
+  Also: url/api target interpolation now exposes `${ctx.selection.ids}` (comma
+  -joined) and `${ctx.selection.count}` from the grid's checkbox selection, so
+  a plain `list_toolbar` action can carry the selection without bulk plumbing;
+  the console's server-action handler recognizes `_selectedIds` and skips the
+  single-record multi-select guard for aggregate dispatches.
+
+- 335041c: Stop declaring 13 `@object-ui/core` symbols under names `@objectstack/spec` owns
+  (objectui#3158, objectstack#4115 batch 4).
+
+  **Breaking for importers of `@object-ui/core`** — seven exported names changed,
+  because the spec exports the same name for a _different_ thing:
+
+  | was                      | now                               | what the spec's same-named export actually is                                |
+  | :----------------------- | :-------------------------------- | :--------------------------------------------------------------------------- |
+  | `ChartSeries`            | `ChartSeriesBinding`              | the authored dataset-binding descriptor (a measure `name`, no `data`)        |
+  | `ActionHandler`          | `ActionRunnerHandler`             | the SERVER-side objectql handler, `(ctx) => unknown`                         |
+  | `PluginDefinition`       | `RegistryPluginDefinition`        | the platform PACKAGE manifest (`id`/`slug`/`staticPath`/install hooks)       |
+  | `ValidationError`        | `SchemaNodeValidationError`       | plugin-manifest validation, keyed by `field`, no severity                    |
+  | `ValidationResult`       | `SchemaNodeValidationResult`      | ditto, with both arrays optional                                             |
+  | `defineView`             | `defineSystemView`                | the VIEW-DOCUMENT factory: parses a `ViewSchema`, returns a validated `View` |
+  | `resolveCrudAffordances` | `resolveEffectiveCrudAffordances` | the object-level affordance matrix, with no notion of server API operations  |
+
+  The other six keep their names and are now **imported from the spec** instead of
+  re-declared: `StyleMap`, `ResponsiveStyles` (ADR-0065), `RowHeight`,
+  `CONTEXT_TOKENS`, `CrudAffordances`, `RowCrudPredicates`.
+
+  **The copies were live misdescriptions, not just duplicates.** Three said so in
+  their own comments:
+
+  - `CONTEXT_TOKENS` carried a note that the duplication was "temporary until the
+    next coordinated release… because the installed `@objectstack/spec` predates
+    that export". The installed spec (17.0.0-rc.0) exports it, and the copy was
+    byte-identical — so it passed every value comparison and every behavioural
+    test for the whole interval in which its stated reason was false.
+  - `RowHeight` advertised itself as "the spec's `RowHeightSchema` vocabulary"
+    while being a hand-written union. It happened to be correct; nothing would
+    have caught the day it stopped being.
+  - `managedBy.ts` described itself as a "UI-side mirror of the framework's
+    `resolveCrudAffordances()`" and carried its own `DEFAULTS` table — a
+    line-for-line copy of the spec's `CRUD_AFFORDANCE_DEFAULTS`, plus a copy of
+    its override parser.
+
+  `resolveEffectiveCrudAffordances` now **delegates** the bucket/`userActions` half
+  to the spec's `resolveCrudAffordances()`, so the bucket table has exactly one
+  definition on the platform. What stays objectui's is the part the spec has no
+  notion of: intersecting that matrix with the server-resolved effective API
+  operation set (#3391), so the UI never offers a button the server would 405 —
+  and the name now says that instead of claiming to be the spec's function.
+
+  Deriving `RowCrudPredicates` also **tightens** it: the local copy typed
+  `visibleWhen`/`disabledWhen` as `unknown`, where the spec types them as
+  `Expression | ExpressionInput`. That was imprecision, not a deliberate dialect.
+
+- b414983: fix(dashboard): a date globalFilter's preset-name default becomes a range, not an equality
+
+  Setup → System Overview rendered EVERY KPI tile as 0 while its period selector
+  read "All time" (objectstack#4475). Every request was `200 OK`, the widgets
+  rendered normally, and nothing in the UI signalled a failure — zeros read as
+  "nothing has happened yet" rather than as an error, which is why this survived
+  to an RC.
+
+  Both symptoms are one missing normalization. `resolveDashboardFilterDefs` lifts
+  the built-in `dateRange` declaration's preset NAME to `{ preset }`, but passed a
+  `globalFilters` entry's `defaultValue` through raw. `@objectstack/spec`'s
+  `GlobalFilterSchema.defaultValue` is `string | number | boolean`, so a bare
+  preset name is the ONLY spelling an author can write — and nothing ever mapped
+  it. System Overview declares
+  `{ field: 'created_at', type: 'date', defaultValue: 'last_7_days' }`, so:
+
+  - `buildFilterCondition` fell through to its "a bare string date means equality
+    on that day" branch and the widget sent
+    `runtimeFilter: { created_at: 'last_7_days' }`. The backend compiled
+    `SELECT COUNT(*) AS "user_count" FROM "sys_user" WHERE created_at = $1`
+    — verified against a live server, byte-for-byte the SQL in the issue. The
+    actual `sys_user` count is 4; that equality matches no row.
+  - `DateRangeFilter` derives its selected item from `value.preset` / `.from` /
+    `.to`, all `undefined` on a bare string, so the control fell through to its
+    ALL sentinel and displayed "All time" while sending that equality. The tiles
+    therefore looked deliberately unfiltered and merely empty.
+
+  `normalizeDateDefault` now applies the same lift the sibling `dateRange`
+  declaration already receives, for `date`/`dateRange` filters whose default names
+  a preset this module actually knows. This is not consumer-side leniency: it is
+  one normalization function completing the same conversion for the sibling
+  declaration, and the spec admits no other spelling for an author to fix at the
+  producer. A genuine ISO date string still means equality on that day (the
+  documented behaviour), and numbers, booleans and unrecognised strings are left
+  exactly as declared.
+
+  No backend change is needed: given a real range the dataset path already lowers
+  it correctly (`WHERE (created_at >= $1 AND created_at < $2)` → 4). The
+  framework's dashboard metadata needs none either — it is spec-compliant as
+  written, and editing it would only hide the defect.
+
+  Levelled `minor` rather than `patch` because the change is visible in rendered
+  dashboards rather than internal: any dashboard declaring a date-typed
+  `globalFilters` default now emits a different query shape, its numbers change
+  (from 0 to real values), and its filter control's displayed label changes with
+  them. Anything asserting on the previously-emitted condition will see it move.
+
+  Known residual, filed separately rather than widened into here: a `date` filter
+  whose value is neither a known preset nor a parseable ISO date still degrades
+  silently to an equality that matches nothing, producing the same
+  healthy-looking zero. Preset names are covered by this change; a misspelled
+  custom value is not.
+
+- 256f8cc: fix(dashboard): an unrecognised date filter value is skipped and named, not compared
+
+  The residual the preset-name fix (objectui#3150 / objectstack#4475) left behind,
+  and the more deceptive half of it: a `date`/`dateRange` filter value that is
+  neither a known preset name nor a parseable date used to fall through to the
+  "a bare string date means equality on that day" branch. A misspelled default —
+  `defaultValue: 'last_7_dayz'` — therefore reached the widget query as
+  `runtimeFilter: { created_at: 'last_7_dayz' }`, which the backend faithfully
+  compiled to `WHERE created_at = $1`. `200 OK`, widget renders, count is 0 —
+  indistinguishable from "this range genuinely has no data". No 4xx, no console
+  warning, no UI signal. objectstack#4475 took a full RC cycle to catch for
+  exactly this reason: **0 looks like a legitimate answer**.
+
+  `buildFilterCondition` now holds a date value to three spellings, and only
+  three:
+
+  1. a known preset name → range bounds (unchanged, objectui#3150);
+  2. an ISO date (`2026-01-15`, `2026-01-15T08:30:00Z`) or a date-macro token
+     (`{today}`, `{7_days_ago}`) → equality on that day (the documented
+     behaviour, unchanged);
+  3. **anything else → the filter is skipped and `console.warn` names the filter,
+     the offending value, and the accepted spellings.**
+
+  The `{ preset: '<unknown>' }` object form gets the same voice. It already
+  dropped the filter — silently — because the preset lookup missed and no
+  `from`/`to` remained; that drop is now announced. When explicit bounds ride
+  along with an unknown preset the bounds are still honoured, and the warning says
+  which of the two won.
+
+  Rule 3 is deliberately the same strictness `buildWidgetScopedFilter` already
+  applies to a _default binding on a field the object does not have_ — skip and
+  warn, with the same rationale spelled out there: never emit a query the backend
+  can only empty-match. Field _names_ had that guard; field _values_ did not.
+
+  The macro-token check asks `resolveDateMacros` itself whether it recognises the
+  string, rather than restating its token grammar in a second place. One
+  vocabulary, no dialect to drift — and a token that resolver does not know
+  (`{last_7_dayz}`) is precisely the typo this guard exists to catch.
+
+  Levelled `minor`, matching objectui#3150, because the emitted query shape
+  changes: a dashboard carrying a misspelled date value stops sending a
+  never-matching equality and instead sends no constraint for that filter (its
+  numbers go from 0 to unfiltered) while the console says why. Anything asserting
+  on the previously-emitted equality will see it disappear.
+
+  Note the direction of the relaxation is chosen, not incidental: skipping widens
+  the result set, so the number visibly changes and the warning explains it —
+  whereas the old behaviour narrowed it to zero, which is the one outcome an
+  author cannot tell from a correct answer. Author-time rejection (validating
+  `GlobalFilterSchema.defaultValue` at publish, in `@objectstack/spec`) is the
+  stricter complement and belongs on the platform side; it is filed separately.
+
+- d3584c6: Bring the whole `@objectstack` family to `17.0.0-rc.1`, so the dependency graph resolves a
+  single copy of `@objectstack/spec`.
+
+  #3178 bumped **only** `@objectstack/spec` to `17.0.0-rc.1`. The rest of the family —
+  `client`, `core`, `formula`, `lint` (and `sdui-parser`, reached through `lint`) — stayed on
+  `17.0.0-rc.0`, and each of them depends on spec at an **exact** version rather than a
+  caret:
+
+  ```
+  @objectstack/client@17.0.0-rc.0  -> spec "17.0.0-rc.0"
+  @objectstack/core@17.0.0-rc.0    -> spec "17.0.0-rc.0"
+  @objectstack/formula@17.0.0-rc.0 -> spec "17.0.0-rc.0"
+  @objectstack/lint@17.0.0-rc.0    -> spec "17.0.0-rc.0"
+  ```
+
+  So `main` carried **two** spec copies: objectui's own code read `17.0.0-rc.1` while every
+  `@objectstack/*` package read `17.0.0-rc.0` from its own nested `node_modules`. That breaks
+  the single-contract invariant this repo's guards are built on, and it breaks them
+  _silently_ — the affected checks depend on identity, not on version strings:
+
+  - `spec-subschema-parity.test.ts` distinguishes a genuine re-export from a fork by
+    **reference identity** of the zod schema object. Two spec copies make every schema a
+    distinct object, so a real re-export starts reading as a fork (or a fork slips through,
+    depending on which copy each side resolved).
+  - `scripts/check-spec-symbol-derivation.mjs` and `spec-symbol-parity.test.ts` use
+    `createRequire` to resolve spec's `.d.ts` and run it through the TS checker. With two
+    copies installed, _which_ declaration file the checker sees is a function of resolution
+    order rather than of intent.
+
+  The declared ranges were already `^17.0.0-rc.0`, which technically admits rc.1 — the pin
+  lived in the lockfile. Raising the remaining ranges to `^17.0.0-rc.1` makes the floor
+  explicit and forbids a future install from silently sliding back onto a family member that
+  drags rc.0 along with it. The rc.1 family members pin spec at `17.0.0-rc.1` exactly, so the
+  graph now converges on one copy by construction, not by luck.
+
+  No product behaviour changes here. `check:spec-symbols` reconciliation was already
+  completed by #3178 and stays green under the unified graph; this changeset is `minor`
+  per the repo's fixed-group version policy.
+
+- 444457c: feat!: follow the framework's `managedBy: 'system'` → `'system-data'` retirement (objectstack#3355)
+
+  **FROM → TO: `managedBy: 'system'` → `managedBy: 'system-data'`.** The framework
+  retired the residual `system` bucket in protocol 17; this is the UI half of that
+  change, landing with it so the closed `ManagedByBucket` union stays a mirror
+  rather than a fork.
+
+  ADR-0103 split the overloaded `system` bucket additively in v16 — the
+  engine-owned objects moved to the explicit `engine-owned`, the admin/user-writable
+  ones stayed on `system` — which left that value named after the half that had
+  already moved out. `system-data` names what it actually holds: the SCHEMA is the
+  platform's, the DATA is the admin's or the user's.
+
+  **The derivation this deletes is the point.** Because v16's `system` doubled as
+  both the engine-owned default and the writable set, three UI surfaces had to
+  RECOVER the distinction from `userActions` at render time:
+
+  - `isSystemWritable()` probed `userActions` for any opted-in write. It is now
+    `managedBy === 'system-data'` — the bucket answers directly.
+  - `ManagedByBadge` derived a synthetic `'system-writable'` variant key. The
+    variant map is now 1:1 with the bucket union, so a new bucket is a compile
+    error to miss instead of a silent fallthrough. The `systemWritable` /
+    `system` i18n keys are **unchanged**, so no locale bundle moves.
+  - `resolveManagedByEmptyState()` asked the resolved `create` affordance whether a
+    `system` list should read "entries appear automatically" or show the New
+    button. `system-data` now falls through to the generic empty state by
+    definition; `engine-owned` keeps the automatic-entries copy.
+
+  **Breaking (UI API):** `ManagedByBadge`'s `userActions` prop and the exported
+  `ManagedByUserActions` interface are **removed**. The bucket alone selects the
+  variant now, so the prop had become metadata nothing read — the exact defect the
+  framework change exists to remove; shipping it as an accepted-but-ignored prop
+  would have reproduced it one layer up. Drop the prop from call sites; no other
+  change is needed.
+
+  `MANAGED_BY_BUCKETS` and `ManagedByBucket` no longer contain `'system'`.
+
+- 850033c: Stop offering the retired `action.shortcut` / `action.bulkEnabled` keys.
+
+  `@objectstack/spec` 17 retired both as `retiredKey()` tombstones: authoring
+  either one is a hard PARSE REJECTION, so a draft carrying it cannot be saved
+  at all. The designer still offered controls for both — a "Bulk — apply to
+  multiple selected rows" checkbox and a "Shortcut" text field — which meant the
+  Studio action inspector let an author build a draft the platform would then
+  refuse, with the rejection arriving later and nowhere near the checkbox.
+
+  - **Action inspector**: both controls removed. The keys stay hidden from the
+    fallback form (the server's live schema still advertises them, so dropping
+    them from the hidden list would put the inputs straight back) — now under a
+    `RETIRED_FIELDS` list that says why, so nobody "restores the missing
+    control". `bulkEnabled`'s replacement is the list view's `bulkActions` /
+    `bulkActionDefs`; `shortcut` has none.
+  - **Action preview**: the `shortcut` and `bulk` pills are gone — they could
+    only ever render for metadata the platform now refuses.
+  - **`ActionEngine.registerActions`**: no longer harvests the two retired keys
+    from authored metadata, which made two dead registration options look
+    load-bearing. Both are still accepted on the single-action
+    `registerAction(action, options)` overload, where a HOST passes them
+    explicitly.
+
+- 009e25d: Report / chart / query symbols stop wearing `@objectstack/spec`'s names
+  (objectui#3155, objectstack#4115).
+
+  **Breaking for TypeScript imports** — six exported names change. Each was a
+  different concept than the spec export it collided with, so an author reading
+  the objectui declaration as "the spec's" was reading a false claim:
+
+  | was                 | now                      | why they were never the same thing                                                                                                                               |
+  | :------------------ | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `ChartSeries`       | `ChartDataSeries`        | ours is a display name plus literal `data: number[]`; the spec's is a dataset-bound series descriptor (`type`/`stack`/`yAxis`/`variant`) with no data at all     |
+  | `ChartSeriesSchema` | `ChartDataSeriesSchema`  | zod twin of the above                                                                                                                                            |
+  | `QueryAST`          | `SqlQueryAST`            | ours is a compiled SQL syntax tree (`select`/`from`/`join`/`group_by`); the spec's is the ObjectQL request descriptor (`object`/`fields`/`where`/`expand`)       |
+  | `QuerySchema`       | `DriverQueryConfig`      | ours is the high-level config `QueryASTBuilder` compiles; the spec exports that name as a zod schema value                                                       |
+  | `DriverInterface`   | `SqlDriverInterface`     | ours is objectui's SQL-oriented client abstraction (`query(sql, params)`); the spec's is the platform runtime driver contract                                    |
+  | `DatasourceSchema`  | `DatasourceRegistration` | ours is the in-memory record `DatasourceManager` holds — its `driver` is a live instance; the spec's is the authored metadata document, where `driver` is a name |
+
+  Three more are now DERIVED from the spec instead of hand-restated, which fixes
+  live silent-stripping defects, since a `z.object()` drops unknown keys:
+
+  - **`DashboardWidgetSchema`** declared 10 of the spec's 22 keys, so
+    `objectui validate` deleted the other 12 without a word — `chartConfig`,
+    `colorVariant`, `filter`, `responsive`, `aria`,
+    `actionUrl`/`actionType`/`actionIcon`, `compareTo`, `suppressWarnings` and the
+    `requiresObject` / `requiresService` capability gates the dashboard renderer
+    honours at runtime. The TS interface had declared most of them all along, so a
+    widget could type-check and still lose half its configuration on validation.
+    Pinned divergences kept: `id` stays optional, `type` stays widened for the
+    objectui-only `list` / `custom` families, and the legacy `component` envelope
+    stays.
+  - **`GlobalFilterSchema`** took `scope` as a free-form string (any typo
+    validated); it now uses the spec's `widget | dashboard` vocabulary. The three
+    objectui widenings that back a real runtime normalizer are kept and pinned:
+    the bare-string `options` shorthand, the normalized `{ preset }` date default,
+    and an optional `optionsFrom.labelField`.
+  - **`AppContextSelectorSchema`** was a full restatement; spec keys and their
+    defaults now flow in by reference, with `label` widened for objectui's i18n
+    label envelope — which `AppContextSelectors` already renders.
+
+  `ListViewSchema`'s zod node now names the spec in its own initializer rather
+  than one hop away through a local const, so its long-standing derivation is
+  visible where it is declared.
+
+  Drift guard: `packages/types/src/__tests__/report-chart-query-spec-parity.test.ts`.
+
+- 726b89c: `@object-ui/types` stops declaring sixteen symbols under names `@objectstack/spec` owns (objectui#3156, objectstack#4115).
+
+  Seven are now **derived** from the spec, nine are **renamed** to the local
+  dialect they always were. Both halves remove the same hazard: a local
+  declaration under a spec export's name reads as the spec's own definition to
+  the next reader, so a copy that is merely _correct today_ is a planted premise
+  tomorrow.
+
+  **Derived** — the spec now supplies the keys, by reference:
+
+  | symbol                   | derivation                                                                        |
+  | :----------------------- | :-------------------------------------------------------------------------------- |
+  | `ActionParam`            | `z.input<typeof ActionParamSchema>`, `type` widened to the local legacy spellings |
+  | `CreateExportJobRequest` | `Omit<CreateExportJobInput, 'object'>` (`object` is the method argument)          |
+  | `CreateExportJobResult`  | re-export from `@objectstack/spec/contracts`                                      |
+  | `ImportRowResult`        | re-export from `@objectstack/spec/api`                                            |
+  | `NavigationArea`         | spec keys, with `navigation` / `visible` pinned locally                           |
+  | `NavigationAreaSchema`   | `specFieldsExcept(NavigationAreaSchema.shape, …)`                                 |
+  | `Theme`                  | re-export of the spec's `ThemeInput` (the authoring shape)                        |
+  | `ExportJobFormat`        | re-export of the spec's `ExportFormat`                                            |
+
+  Four of these close real gaps rather than tidy names. `ActionParam` never
+  declared `reference` — the key `resolveActionParams()` actually reads for an
+  inline lookup target — nor `defaultFromRow`, which the metadata designer's own
+  inspector writes; it also narrowed `visible` to a bare string although the
+  resolver has always accepted the `{ dialect, source }` envelope too.
+  `CreateExportJobResult.createdAt` and `ImportRowResult.action` were optional
+  here and required by the server, leaving every consumer a branch that could
+  never run. And `NavigationArea`'s `id` now carries the spec's own length rule
+  instead of accepting any string.
+
+  **Renamed** — same word, different concept:
+
+  | was                | now                      | why                                                                                                                            |
+  | :----------------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
+  | `FileMetadata`     | `UploadedFileMetadata`   | field-VALUE payload (`url`, `original_name`), not the storage file record                                                      |
+  | `GestureType`      | `TouchGestureType`       | direction-fused (`swipe-left`), not the spec's type+direction pair                                                             |
+  | `GestureConfig`    | `TouchGestureConfig`     | gesture→`action` binding, not per-gesture tuning                                                                               |
+  | `OfflineConfig`    | `PWAOfflineConfig`       | service-worker route caching, not the offline data/sync model                                                                  |
+  | `PageRegion`       | `PageNodeRegion`         | region of the renderer page NODE, holding `SchemaNode`s                                                                        |
+  | `PageRegionSchema` | `PageNodeRegionSchema`   | zod twin of the above                                                                                                          |
+  | `ResponsiveConfig` | `MobileResponsiveConfig` | mobile box config, not the spec's SDUI grid contract                                                                           |
+  | `WidgetManifest`   | `RuntimeWidgetManifest`  | SDUI component manifest, not the field-widget plugin manifest                                                                  |
+  | `WidgetSource`     | `RuntimeWidgetSource`    | `module`/`inline`/`registry` loader union — and its `inline` carries a resolved component where the spec's carries source code |
+
+  **Migration**: the old names are gone, not deprecated — an alias would preserve
+  exactly the ambiguity being removed. Import the new name; nothing about the
+  shapes changed. `@object-ui/types` already re-exports the spec's own
+  `SpecResponsiveConfig`, and `@object-ui/react`'s `useOffline` config remains the
+  spec-shaped `OfflineConfig`, so both concepts stay reachable under
+  distinguishable names.
+
+  Each rename carries a bidirectional tripwire
+  (`packages/types/src/__tests__/page-nav-misc-spec-parity.test.ts`): it fails if
+  the spec ever claims the new name, and also if the spec retires the old one —
+  at which point the natural name can be taken back rather than the workaround
+  outliving its reason.
+
+### Patch Changes
+
+- d9668a7: Honor the server's declared percent scale, so a ratio of exactly 1 renders as 100.0% (#3136)
+
+  A dataset measure declared `format: '0.0%'` rendered every ratio below 1
+  correctly and got the single most consequential one wrong: a rate of exactly
+  `1` printed as **`1.0%`**. On an SLA / pass-rate dashboard that turns
+  "everything met the SLA" into "1% met the SLA", on both surfaces the issue
+  names — the KPI card and the dataset-bound table (they share `formatMeasure`).
+
+  The cause was never a bad multiplier; it was a missing fact. `formatMeasure`
+  scaled by magnitude — `percentDisplayValue` multiplies by 100 only strictly
+  inside `(-1, 1)` — because the column arrived with a `%` format string and
+  nothing saying what scale its numbers were on. That guess is undecidable at
+  exactly 1, which is both a full-compliance ratio ("100%") and one percentage
+  point ("1%"), and it resolved to the reading almost nobody means.
+
+  The server now answers the question instead (framework: `percentScaleOf` +
+  `AnalyticsResult.fields[].percentScale`, the sibling of the ADR-0053 currency
+  chain): a `derived: { op: 'ratio' }` measure is a `fraction` by definition, and
+  a measure over a `percent` field inherits that field's scale. `formatMeasure`
+  takes the declared scale as a fourth argument and, when present, scales by it —
+  `fraction` ×100, `whole` verbatim — instead of inspecting the value. Every
+  dataset-bound call site passes the column's `percentScale`: the dashboard
+  metric/table/pivot cells, the report renderer's cells, totals and KPI, and the
+  dataset preview.
+
+  `percentDisplayValue` is untouched and still the fallback for a column that
+  arrives without the annotation (an older server, or a non-dataset percent cell
+  in a list view), so nothing that renders correctly today changes.
+
+- a8ad6c0: A required boolean must be savable in its UNCHECKED state — `false` and `0` are values.
+
+  Reported against an AI-built task tracker whose 任务 object has a required
+  `是否完成` boolean: the create form showed the switch OFF, answered "是否完成不能
+  为空", and saved instantly once the switch was turned ON. The app could only ever
+  create ALREADY-DONE tasks — the one state the control shows by default was the
+  one value it refused to save (cloud#972).
+
+  Two defects stacked, and either alone is enough to break it:
+
+  **The `required` verdict read truthiness, not presence.** `@objectstack/spec`
+  FieldSchema.required (ADR-0113) is "an insert must provide a NON-NULL value",
+  and objectql's record validator implements exactly that. react-hook-form's
+  built-in rule instead fails whenever `isBoolean(value) && !value` — its
+  accept-the-terms checkbox heritage — silently redefining every required boolean
+  as "must be TRUE", including a select whose chosen option value is `false`. It
+  also disagreed the other way, letting a whitespace-only string through for the
+  server to reject with a 400. The form renderer no longer hands RHF its own
+  `required`: the check is now a `validate` entry keyed `required` (so the error
+  still surfaces as `type: 'required'`, which the conditional-required cleanup
+  keys on) backed by a new shared `isMissingForRequired` in `@object-ui/core`, a
+  deliberate mirror of objectql `record-validator.isMissing` — `undefined`,
+  `null`, blank-after-trim string, empty array. Deleting the inherited rule also
+  stops a `required` that rode in on `validation` from outliving a `requiredWhen`
+  that resolved to FALSE.
+
+  **A boolean field held `undefined` while displaying "off".** A two-state control
+  has no third state, but a field with no entry in `defaultValues` rendered an OFF
+  switch backed by nothing: the create payload omitted the column (it lands null,
+  which reads as unchecked but isn't) and the presence check above would still
+  refuse it. The form renderer now folds `false` into `defaultValues` for every
+  boolean-widget field the caller left unset — in `defaultValues` itself, not
+  per-Controller, because that object is also the dirty-check baseline and what
+  the defaults-reset window replays. Every surface gets it, including the
+  modal/drawer create dialogs that start from a bare `{}`. An authored default
+  (or a loaded record, `null` included) still wins.
+
+  `WizardForm`'s cross-step gate had its own copy of the empty-value predicate; it
+  now imports the shared one so it cannot drift from the per-field verdict. And
+  the field-demo renderer read `schema.defaultValue || schema.value`, throwing
+  away an authored default of `false` / `0` / `''` — same falsy-as-empty class,
+  now `??`.
+
+  Verified end to end on a local stack against the exact metadata shape
+  `apply_blueprint` materializes (`{ type: 'boolean', required: true }`, no
+  default): a 是否完成 = 否 task with 工时 = 0 now creates and persists as
+  `{ hours: 0, is_done: false }`, turning the switch on still stores `true`, and a
+  blank required text is still refused.
+
+- Updated dependencies [4ae0ac4]
+- Updated dependencies [696e3c1]
+- Updated dependencies [4bf612c]
+- Updated dependencies [cb82705]
+- Updated dependencies [f572849]
+- Updated dependencies [444457c]
+- Updated dependencies [022e4c3]
+- Updated dependencies [009e25d]
+- Updated dependencies [726b89c]
+  - @object-ui/types@17.2.0
+
+## 17.1.0
+
+### Minor Changes
+
+- 62311b6: feat(core): inventory `ActionDef`'s keys and warn on the ones nothing reads — objectstack#4075 step 1
+
+  `ActionDef` ends with `[key: string]: any`, so it accepts any key of any type.
+  Deleting `ActionDef.execute` produced **zero** compile errors even though the
+  field had just been removed (objectui#2990), and stale metadata still authoring
+  `execute: 'markDone'` type-checks today. The same deletion against
+  `@object-ui/types`' `ActionSchema` — which has no index signature — correctly
+  produced `TS2353` at the authoring site. One of the two readers can catch a
+  retired key; the other is structurally incapable, which is how a typo (`targt`)
+  and a tombstoned key both reach a runner that then silently does nothing.
+
+  This is the non-breaking first step of the staged narrowing: it makes the key set
+  **visible** and warns on anything outside it, without changing a single type.
+
+  New exports from `@object-ui/core`:
+
+  - `ACTION_DEF_KEYS`, `SPEC_ACTION_KEYS`, `NAVIGATION_ALIAS_KEYS`,
+    `RETIRED_ACTION_KEYS`, `KNOWN_ACTION_KEYS` — the inventory.
+  - `classifyActionKeys(action)` — splits an action's own keys into `unknown` and
+    `retired`.
+  - `warnOnUnknownActionKeys(action)` — dev-mode only, warn-once. Called by
+    `ActionRunner.execute`, so no consumer wiring is needed.
+
+  A retired key gets a louder, more specific warning than an unknown one: an
+  unknown key is probably a typo, a retired key is metadata that used to work.
+  `execute` is not simply gone from the spec — it is a live **tombstone**, still
+  present in `ActionSchema` so the parser can reject it by name with the rename
+  prescription.
+
+  Nothing is rejected and no types changed, so existing metadata behaves exactly as
+  before. Promoting the legitimate keys to explicit optional fields, then removing
+  the index signature so `tsc` catches both typos and retired keys, are steps 2 and
+  3 of objectstack#4075.
+
+- 9e7349e: **`target` is the only action handler slot — the `execute` alias is gone from the renderer (framework#3856).**
+
+  `ActionRunner.executeScript` read `action.target || action.execute`. That fallback
+  is unreachable against `@objectstack/spec` 17: `execute` is now a tombstoned key
+  (framework#3855) that the parser **rejects** with the rename prescription, so no
+  parsed action can carry it and the `||` could only ever yield `target`. Verified
+  against 17.0.0-rc.0 — an action declaring `execute` fails `ActionSchema.safeParse`,
+  and a `target` action's parsed output has no `execute` key at all.
+
+  Deleted rather than left as harmless residue: two handler slots is what let one
+  action run one script server-side and a different one client-side (framework#3713,
+  where this renderer preferred the alias while the spec transform preferred
+  `target`). A dead slot still reads as a live contract to the next maintainer.
+
+  `execute` is also **removed from the types**, which is the part that had never
+  landed. framework#3856 predicted a compile error here; there wasn't one, because
+  neither reader was typed against the spec's `z.infer`:
+
+  - `@object-ui/types` `ActionSchema` hand-declared `execute?: string`. Removed, so
+    `execute: '…'` now fails `tsc` at the authoring site (TS2353).
+  - `@object-ui/core` `ActionDef` hand-declared it too. Removed — but `ActionDef`
+    carries a `[key: string]: any` index signature, so stale hand-authored metadata
+    that never passed through the parser still compiles. For that path
+    `executeScript` now returns the rename prescription instead of a bare
+    "No script provided", matching the spec tombstone's rule that removing an
+    authorable key must be audible: silently binding no handler is the
+    "Mark Done does nothing" shape (framework#2169).
+
+  The four action renderers (`action:button`, `action:icon`, `action:menu`,
+  `action:group`) no longer forward `execute` into the runner, and Studio's
+  `ActionPreview` no longer falls back to it — previewing an alias-only draft as
+  "bound" contradicted the parse that rejects it on save.
+
+  Requires `@objectstack/spec` 17. Metadata still on the alias is rewritten by
+  `os migrate meta --from 16`.
+
+- 6ae818e: feat(core): one column identity per column — `field` stamped at ingestion (#3104)
+
+  A column's field identity was resolved twice, with two different precedences
+  over the same `schema.columns` array, and the two halves disagreed:
+
+  - **request path** — `ListView`'s `$expand` and `$select` builders, and
+    `ObjectGrid.getSelectFields`, read `f?.field` and only `f?.field`.
+  - **render path** — the FLS gate, the hidden-field filter, `fieldOrder`, both
+    export branches and the hide-fields popover read
+    `f.name || f.fieldName || f.field` — name FIRST.
+
+  So `{ field: 'account', name: 'account_name' }` fetched `account` while the
+  renderer keyed off `account_name`, and `{ name: 'account' }` rendered a column
+  the request dropped entirely — neither `$select` nor `$expand` carried it. That
+  is the mechanism behind the "relation column shows a bare id / column is empty
+  / sort does nothing / export is missing a column" defect class.
+
+  Per AGENTS.md #0.1 the fix is not another `?? name` at the read sites. Legacy
+  acceptance moves to the one boundary that already folds this view's vocabulary,
+  `normalizeListViewSchema`, which now also canonicalizes each column's identity.
+
+  New in `@object-ui/core`:
+
+  - `columnIdentity(entry)` — the single reader. Resolves `field` → `name` →
+    `fieldName`, canonical-first, so it agrees with `buildExpandFields` instead
+    of racing it. Handles bare-string columns.
+  - `normalizeColumnIdentity(entry)` / `normalizeColumnIdentities(columns)` — the
+    fold. Stamps `field`; a legacy key that is **already present** is mirrored
+    onto the same identity so name-first readers resolve what the request asked
+    for; a legacy key that is **absent is never invented**, and an
+    already-canonical column is returned by reference.
+  - `hasConflictingColumnIdentity(entry)` — true when a column's keys disagree.
+  - `CANONICAL_COLUMN_IDENTITY_KEY`, `LEGACY_COLUMN_IDENTITY_KEYS`,
+    `TABLE_ADAPTER_COLUMN_KEY`.
+
+  The fold **mirrors** rather than deleting the legacy key, unlike the other
+  folds in `normalizeListViewSchema`. Deleting would work inside this repo (every
+  name-first read falls through to `field`), but `columns` entries cross the
+  package boundary into host renderers and dropping `name` from under them is a
+  breaking change with no inventory. Deletion is a later call, once the in-repo
+  consumers read `columnIdentity()`.
+
+  Behaviour is unchanged for any column carrying a single identity key — every
+  read site resolves the same string it did before. The entries whose resolution
+  moves are exactly the ones where two sites already disagreed.
+
+  `accessorKey` is deliberately untouched: it is TanStack Table's own column key
+  (`TableColumn.accessorKey`), not ObjectStack metadata identity, and folding
+  across that boundary would fossilize the merge.
+
+- 746dd00: feat(sdui): curate the page:\*, element:\* and action:\* families into the public contract
+
+  The AI-authoring vocabulary and the Studio page designer disagreed by thirteen
+  blocks: `PUBLIC_BLOCKS` carried one `page:` tag and one `element:` tag while
+  the designer palette — and @objectstack/spec's page schema — offered the whole
+  families. A block a human can drag in Studio was invisible to a model writing
+  the same page, which is the objectui#3006 state at 10× the scale.
+
+  Fifteen tags join the contract (36 → 42 → **57**), every one shipping a
+  renderer with declared inputs (objectui#3065):
+
+  - `page:` — tabs, card, accordion, section, footer, sidebar
+  - `element:` — text, number, button, definition-list, repeater
+  - `action:` — button, group, menu, icon
+
+  Five stay out, each with its reason recorded and guarded: `action:bar`
+  (`record:quick_actions` covers the record action strip; the spec blesses the
+  other four), `element:image` (duplicates the curated `image` — one spelling
+  per concept), and `element:record_picker` / `element:text_input` /
+  `element:metadata_viewer` (mirroring the Studio palette's own exclusions, so
+  the two vocabularies stay out for the same reasons rather than by
+  coincidence).
+
+  The console's reverse-coverage guard now sweeps all four semantic namespaces
+  instead of `record:` alone — checking only the namespace you just fixed is
+  exactly how the last 22 doubled keys went unnoticed (objectui#3037). A new
+  prop-less allowlist (`element:divider`, `page:section`, `page:footer`,
+  `page:sidebar`) keeps "declares no inputs" a pinned decision in both
+  directions: those four must stay at zero, everything else curated must declare
+  a surface.
+
+- 38ca8be: refactor(fields): `requiredWhen` is the only required-predicate slot — drop the retired `conditionalRequired` alias
+
+  `@objectstack/spec` 17 (objectstack#3855) **retired** `Field.conditionalRequired`,
+  the long-deprecated alias of `requiredWhen`. ObjectUI carried a back-compat read
+  for it in seven places; all of them are removed.
+
+  The removal is safe because the spec did not merely _stop emitting_ the key — it
+  made authoring it **fail loudly**. `retiredKey()` declares the key as
+  `z.never()`, so:
+
+  - `z.input` types it as `never` — writing it is a `tsc` error at the authoring site;
+  - the parse **rejects** it (verified against `17.0.0-rc.0`), at both `FieldSchema`
+    and `ObjectSchema`, with the prescription as the message:
+
+    > `conditionalRequired` was removed in @objectstack/spec 17 (#3855) — use
+    > `requiredWhen`. Rename the key; the value (a CEL predicate) is unchanged.
+    > Run `os migrate meta --from 16` to rewrite it automatically.
+
+  So spec-parsed metadata cannot carry the key — an object declaring it fails to
+  load rather than loading with the rule silently dropped. Keeping a renderer-side
+  `requiredWhen ?? conditionalRequired` would have re-created exactly the second
+  de-facto contract the tombstone exists to prevent: the key would have kept
+  working in the UI while being rejected everywhere else, hiding the producer's bug
+  (AGENTS.md #0.1). "Backend-agnostic" (#1) does not argue for keeping it either —
+  `conditionalRequired` is an ObjectStack-spec-ism, so the only producers that ever
+  emit it are ObjectStack producers on ≤16, and the spec ships them a converter.
+
+  Removed from:
+
+  | package                  | site                                                                                                      |
+  | :----------------------- | :-------------------------------------------------------------------------------------------------------- |
+  | `@object-ui/types`       | the `conditionalRequired?:` member on `FormField`                                                         |
+  | `@object-ui/core`        | the `??` fallback + rules-param member in `resolveFieldRuleState`                                         |
+  | `@object-ui/components`  | three pass-throughs in the form renderer                                                                  |
+  | `@object-ui/plugin-form` | `ObjectForm`, `ModalForm`, `sectionFields`, `deriveMasterDetail` (×2)                                     |
+  | `@object-ui/app-shell`   | the field inspector's legacy read/auto-migrate, and the key's entry in `clientValidation`'s CEL lint list |
+
+  **Studio authors lose nothing.** The object designer's draft validation parses
+  against the spec's own `ObjectSchema`, so a draft carrying the key now surfaces
+  the tombstone's rename prescription under the same `fields.<name>.conditionalRequired`
+  path the CEL lint used to report — a better message than the inspector's silent
+  auto-migration, and one the server agrees with. That behavior is pinned by a test.
+
+  **Migrating:** rename the key to `requiredWhen` (the CEL value is unchanged), or
+  run `os migrate meta --from 16`.
+
+- 02aef0c: fix(sdui): a `kind:'html'` page can use lazily-registered blocks, and recovers when one registers late
+
+  objectui#2953 had a twin one tier over, unreported. The whitelist a
+  `kind:'html'` page's source compiles against was built from `getAllTypes()` +
+  `getConfig()` — both loaded-only — so any block registered via `registerLazy()`
+  was rejected as _"not an allowed component"_.
+
+  The blast radius is worse than the react tier's. There, a missing block cost one
+  identifier; here a compile diagnostic fails the **whole page**, so a single
+  `<object-kanban>` replaced the entire page with `HTML page failed to compile (2)`.
+  And it never recovered: `layoutElement` was memoised on `[schema, pageType]` with
+  no registry signal, so the cached error panel outlived the plugin actually
+  landing — permanently broken for the session.
+
+  `ComponentRegistry` gains three lazy-aware reads:
+
+  - `getKnownTypes()` — loaded registrations **plus** pending lazy stubs, deduped.
+    The set a whitelist or manifest should be built from. `getAllTypes()` keeps its
+    loaded-only meaning ("what can render right now") and now says so.
+  - `getMeta(type, namespace?)` — metadata from the loaded registration, else from
+    a pending stub. `getConfig()` stays loaded-only, since callers read
+    `.component` off it.
+  - `getVersion()` — monotonic counter of changes to the known set, bumped on
+    register / unregister / registerLazy. A cache key that a type _count_ cannot
+    substitute for: one registration plus one unregistration leaves the count
+    untouched while the set changed.
+
+  `getJsxManifest()` builds from those, and `PageRenderer` subscribes to the
+  registry so a page that could not compile retries when the registry grows.
+
+  A stub carries no `inputs` yet, so its props surface as `unknown-prop` warnings
+  rather than errors — the page compiles and renders, and the inner
+  `SchemaRenderer` triggers the loader and swaps in the real block. Authoring-time
+  prop validation is unaffected: `sdui.manifest.json` is generated with every
+  plugin eagerly loaded, and asserts as much.
+
+- c4db402: refactor(views): ListView's `aria` and `sharing` are the spec sub-shapes (#2890 scope A step 5)
+
+  Last rename batch in the ListView vocabulary migration.
+
+  **`aria`** is now the spec's `AriaPropsSchema`: `label` → `ariaLabel`,
+  `describedBy` → `ariaDescribedBy`, folded at the ListView boundary like every
+  other legacy key. Two things fall out of adopting the spec shape:
+
+  - `role` becomes authorable. The list region hardcoded `role="region"`; it now
+    reads `aria.role` and falls back to `region`.
+  - `aria.live` stays as a documented local extension — it has no spec
+    counterpart, and dropping it would silently disable a shipped capability.
+    Promote it rather than growing that extension.
+
+  **`sharing`** is now the spec's `ViewSharingSchema` (`{ type, lockedBy }`),
+  imported by reference — the local four-key object is gone. The legacy pair folds
+  in: `visibility` collapses onto the two ownership kinds the spec models (only
+  `private` is `personal`; `team` / `organization` / `public` are all
+  `collaborative`), and a bare `enabled: true` maps to `personal`, which is the
+  badge the user already saw (the old title fell back to `'private'`).
+
+  _Visible change_: the share badge's tooltip shows the spec ownership type, so a
+  view authored with `visibility: 'team'` reads "Sharing: collaborative" instead
+  of "Sharing: team". The four-value audience has no spec home and nothing but
+  that tooltip consumed it; keeping a second audience enum alive would re-open the
+  fork this issue closes.
+
+  Also fixes the **spec bridge**, which was doing the opposite of its job: given a
+  spec-shaped `sharing`, `transformListView` _downgraded_ it — inventing a legacy
+  `visibility` audience and an `enabled` flag that the renderer then had to fold
+  back. Both sides speak `ViewSharing` now, so it passes through.
+
+  `conditionalFormatting` and `exportOptions` are deliberately **not** folded.
+  Both objectui shapes are supersets carrying capability the spec cannot express —
+  the `{ field, operator, value }` rule form, and `maxRecords` / `includeHeaders`
+  / `fileNamePrefix`. Folding them onto the narrower spec shapes would delete
+  working features; they want promotion upstream, not a rename.
+
+- 5319bf1: feat(views): the list toolbar speaks one vocabulary — `userActions` (#2890 scope A step 3)
+
+  The seven bare `show*` toolbar flags fold into the spec's `userActions`, and the
+  renderer reads nothing else. `showDescription` folds into
+  `appearance.showDescription` at the same boundary.
+
+  | legacy                                                    | canonical                                                 |
+  | :-------------------------------------------------------- | :-------------------------------------------------------- |
+  | `showSearch` / `showSort` / `showFilters` / `showDensity` | `userActions.search` / `.sort` / `.filter` / `.rowHeight` |
+  | `showGroup` / `showHideFields` / `showColor`              | `userActions.group` / `.hideFields` / `.rowColor`         |
+  | `showDescription`                                         | `appearance.showDescription`                              |
+
+  **The last three are new keys, and they close a capability hole rather than just
+  renaming one.** `@objectstack/spec`'s `UserActionsConfigSchema` documents itself
+  as "which interactive actions are available to users in the view toolbar — each
+  boolean toggles the corresponding toolbar element on/off", and already carries
+  `rowHeight` (objectui's `showDensity` under its spec name). Grouping, column
+  visibility and row coloring are the same kind of toggle: the spec models all
+  three as _configuration_ (`grouping`, `hiddenFields`, `rowColor`) but has no
+  "may the user change it" switch for any of them.
+
+  The consequence was visible in the product. With no `userActions` key to read,
+  the two list surfaces **hardcoded opposite policies**: `InterfaceListPage` (the
+  author-curated interface page) pinned all three OFF, `ObjectDataPage` pinned two
+  ON — and an interface-page author could not turn grouping back on for end users
+  at all. Both surfaces now express their policy as `userActions` defaults, which
+  an author can override.
+
+  Until the keys land in `@objectstack/spec`, `@object-ui/types` carries them as a
+  documented `.extend()` on `UserActionsConfigSchema` (the same shape
+  `ListColumnSchema` uses while waiting on objectstack#3761); it collapses into a
+  plain re-export once they do. Note the spec schema is not `.strict()`, so before
+  this an author writing `userActions: { group: false }` had it **silently
+  stripped** — valid on parse, no effect at render.
+
+  Defaults are unchanged and deliberately asymmetric, matching what these flags
+  have always done: `search` / `sort` / `filter` / `rowHeight` / `group` are on
+  unless turned off; `hideFields` / `rowColor` are off unless turned on. Making
+  them uniform would grow two buttons on every existing view, so it is left as its
+  own product decision rather than smuggled into a vocabulary migration.
+
+  Also drops a dead relay in app-shell's `ObjectView`, which forwarded
+  `showDescription` onto the node although `ListView` has only ever read
+  `appearance.showDescription`.
+
+- f59f2c1: refactor(actions): `navigation` becomes a named alias of the spec's `url`, sharing one navigator (#2944)
+
+  The last open item of #2944: `ActionRunner` dispatched a seventh action type,
+  `navigation`, that `@objectstack/spec`'s `ActionType` does not contain. The issue
+  asked for a decision — promote it upstream or delete the case. Neither, as stated.
+
+  - **Promoting it is wrong.** The spec already has `url` for "go to a location",
+    with `openIn` for the new-tab/same-tab choice. A seventh type would put a
+    second spec name on one operation, which is the exact failure the #2901 audit
+    is named after: _a second definition of the vocabulary exists, and the renderer
+    is faithful to the wrong one_.
+  - **Deleting it is worse, because it is silent.** `{ type: 'navigation', to: … }`
+    is authored today (`element:button` CTAs). Without the case the action falls
+    through to `executeActionSchema`, which returns `{ success: true }` — a green
+    toast that navigates nowhere. That is #2960's trap.
+
+  So it stays, but stops being dialect. `ObjectUiLocalActionType` /
+  `OBJECTUI_LOCAL_ACTION_TYPES` in `@object-ui/types` declare it as objectui's own
+  alias of `url` — the same treatment #2985 gave `PageVisualizationAlias` — and the
+  runner routes both names through one navigator.
+
+  **The alias had already drifted, which is the point.** `executeNavigation` was
+  quietly the weaker of the two implementations: no `${param.X}` / `${ctx.X}`
+  interpolation, `openIn` ignored, and no `/api/…` full-page short-circuit (the
+  redirect-dance case `url` exists to handle). An author who wrote
+  `{ type: 'navigation', to: '/x?p=${param.p}' }` shipped the literal `${param.p}`,
+  while the identical `url` action resolved it. Both names now behave identically;
+  `url` in turn gains `replace` pass-through, the one modifier only the alias had.
+
+  Additive only. `replace` is omitted from the `NavigationHandler` options object
+  when unset, so hosts see the option shape they already saw.
+
+  The new guard is structural rather than another assertion. The runner's built-in
+  dispatch is a table typed `Record<RunnableActionType, …>` instead of a `switch`,
+  so an `ActionType` the spec **adds** stops compiling until an executor exists for
+  it — the Tier-2 "validates at save, renders nothing at run time" failure (#2942)
+  becomes a build error for actions. `spec-derived-unions.test.ts` additionally
+  asserts `navigation` is _absent_ from the spec enum, so the day it is adopted
+  upstream, the test fails and names the alias to retire.
+
+- ce08d55: chore(deps): upgrade `@objectstack/*` to 17.0.0-rc.0, and let the spec take back what it now owns
+
+  `spec` / `client` / `formula` / `lint` move from `^16.x` to `^17.0.0-rc.0`. Two
+  groups of v17 changes reach this repo, and they pull in opposite directions —
+  the spec pruned surface objectui re-exported, and adopted surface objectui had
+  been carrying locally.
+
+  **The spec pruned dead Theme config (objectstack#3494), so the re-exports went
+  with it.** `ThemeSchema` dropped `spacing`, `breakpoints`, `logo`, `density`,
+  `wcagContrast`, `rtl`, `touchTarget` and `keyboardNavigation` — authorable but
+  never enforced, so authoring them was already a silent no-op. `@object-ui/types`
+  re-exported those sub-schemas _by reference_ (issue #2231), so they could not
+  survive the prune without becoming hand-written mirrors — exactly the second
+  de-facto contract AGENTS.md #0.1 forbids. Removed from the public surface:
+
+  - Types: `Spacing`, `Breakpoints`, `DensityMode`, `WcagContrastLevel`,
+    `ThemeLogo`, and the deprecated `SpacingScale` alias
+  - Schemas: `SpacingSchema`, `SpacingScaleSchema`, `BreakpointsSchema`,
+    `ThemeLogoSchema`, and the `SpacingSchemaType` / `BreakpointsSchemaType` helpers
+  - `Theme.spacing`, `Theme.breakpoints` and `Theme.logo`
+
+  `mergeThemes` no longer merges the three dropped keys. `generateThemeVars` is
+  unaffected — it never emitted them, which is why the liveness audit called them
+  dead. The one real consumer was `ThemeProvider`, which set the favicon from
+  `theme.logo.favicon`; that path is gone, because v17 strips the key at parse and
+  it could never arrive again. The live favicon is unaffected: it comes from
+  operator branding (`getFaviconUrl()`), applied in the console's `index.html`,
+  `main.tsx`, and on route change.
+
+  Nothing else read the pruned types. In particular the list-density feature is
+  untouched — `useDensityMode` and `rowHeightToDensityMode` use `@object-ui/core`'s
+  own local `DensityMode`, which never came from the spec.
+
+  **The spec adopted objectui's ListColumn extensions (objectui#2231), so the
+  extension collapsed.** `ListColumnSchema` used to `.extend()` the spec with two
+  fields, each carrying a note to promote it upstream rather than grow the
+  extension; v17 did exactly that. `summary` is now the spec's
+  `union([ColumnSummarySchema, ColumnSummaryConfigSchema])` — the same enum ∪
+  `{ type, field }` form `useColumnSummary` reads — and `prefix` is the spec's
+  `ColumnPrefixSchema`. `ListColumnSchema` is now a plain by-reference re-export.
+  One behavior change rides along: `prefix.type` defaults to `'text'` on parse
+  instead of staying `undefined`, so the cell renderer always gets a value.
+
+  **Node 22 is now the floor.** Every `@objectstack` package declares
+  `engines.node: ">=22.0.0"` (objectstack#3825; Node 20 reached EOL 2026-04-30).
+  This repo claimed `>=20` and ran CI on Node 20.x, so it promised — and validated
+  — a runtime its own core dependency does not support. `engines.node` is now
+  `>=22`, CI runs Node 22.x, and the CI/deployment docs say so.
+
+  The major stays 17: per AGENTS.md the major tracks `@objectstack`'s major, which
+  is also 17, and that convention deliberately outranks semver purity — so the
+  removals above ship as a minor rather than desyncing the two.
+
+- 390c071: feat(record): declare inputs for the seven configurable record:\* blocks, and curate six
+
+  Seven `record:*` blocks shipped with renderers that read props but declared no
+  `inputs`. That combination is the worst of both: the renderer honours
+  `limit`, `severity`, `location` …, while every authoring surface — the designer
+  panel, the AI vocabulary, the generated manifest — reports the block takes no
+  configuration. objectui#3013 recorded them as deliberately uncurated for
+  exactly that reason.
+
+  The declarations mirror what each renderer actually reads:
+
+  | block                                  | inputs                                                                       |
+  | -------------------------------------- | ---------------------------------------------------------------------------- |
+  | `record:activity`                      | 11 — from `RecordActivityComponentProps`                                     |
+  | `record:chatter` / `record:discussion` | 5 — from `RecordChatterComponentProps`                                       |
+  | `record:alert`                         | 8 — severity, title, body, visible, icon, action, dismissible, dismissKey    |
+  | `record:quick_actions`                 | 7 — actionNames, requiredPermissions, location, align, inline, variant, size |
+  | `record:history`                       | 3 — limit, emptyText, unknownUserText                                        |
+  | `record:reference_rail`                | 1 — hideEmpty                                                                |
+
+  `inputs` describe what an AUTHOR writes, which is a subset of what the renderer
+  reads. `entries`, `loading` and resolved `actions` are injected by the host
+  shell off RecordContext; declaring them would invite a model to hand-write the
+  data the page is supposed to fetch. `aria` is omitted for the reason it is
+  omitted on `record:details` — an accessibility escape hatch, not a layout
+  choice. `location` takes its enum from the spec's `ACTION_LOCATIONS` rather
+  than restating it, per objectui#3019.
+
+  Six of the seven are now in `PUBLIC_BLOCKS`: configurable and absent from the
+  contract is the state objectui#3006 was about. The contract goes 36 → 42 tags,
+  all resolving.
+
+  `record:chatter` stays out — it is the same renderer as `record:discussion`
+  under a Salesforce-familiar name, kept for schemas already in the wild. Two
+  spellings of one block is ambiguity an authoring model cannot resolve, so the
+  vocabulary carries the spec's name. A test compares the two input lists, so the
+  day they diverge the exclusion stops being justified and fails.
+
+  A companion assertion requires every curated `record:*` tag to declare inputs.
+  A curated tag with none reads as "takes no configuration" when the renderer in
+  fact reads props — the same gap objectui#3006 opened, pointed the other way.
+
+- 912496d: feat(types,core): the `*Validation` rule types derive from spec 17, and the engine agrees with the server — objectstack#4115
+
+  The five spec-named rule variants in `data-protocol.ts` were hand-written
+  interfaces, each labelled `(ObjectStack Spec v2.0.1)` while the installed spec
+  was `17.0.0-rc.0`. Nothing bound them to the spec, so fifteen majors of drift
+  accumulated with `tsc` silent throughout and the comment still vouching for it.
+  They are now `z.input` derivations of `ScriptValidationSchema` /
+  `StateMachineValidationSchema` / `CrossFieldValidationSchema` /
+  `ConditionalValidationSchema` / `FormatValidationSchema`, and canonicity is
+  carried by that binding plus a parity gate rather than by a comment (#3017).
+
+  `z.input`, not `z.infer`, because objectui consumes **authored** metadata as it
+  arrives over `/meta` — before the spec applies its defaults and canonicalizes
+  expressions. That is the shape actually in the JSON.
+
+  **Breaking, in the shape of the rule types** (minor per this repo's version
+  policy — see AGENTS.md §9):
+
+  |                                   | was                                         | is                                                      |
+  | --------------------------------- | ------------------------------------------- | ------------------------------------------------------- |
+  | `ConditionalValidation`           | `condition` + `rules[]`                     | `when` + `then` / `otherwise`                           |
+  | `FormatValidation`                | `pattern` + `flags`, 8 named formats        | `regex`, the 4 formats the server implements            |
+  | `Script`/`CrossField` `condition` | `string`                                    | `string \| { dialect, source }`                         |
+  | `StateMachineValidation`          | —                                           | gains `initialStates` (objectstack#3165)                |
+  | `BaseValidation`                  | no `priority`, `events` included `'delete'` | gains `priority`; `'delete'` retired (objectstack#3184) |
+
+  `UniquenessValidation` / `AsyncValidation` / `RangeValidation` are now
+  `@deprecated`. They have no spec counterpart — the spec removed the first two
+  deliberately (uniqueness → a unique index, since SELECT-then-INSERT is racy;
+  async → the form layer) — and the spec's `ValidationRuleSchema` rejects all
+  three, so no rule in those shapes can ride in `ObjectSchema.validations`.
+
+  **`ObjectValidationEngine` now agrees with `objectql`'s rule-validator.** It is a
+  client PRE-CHECK of rules the server enforces, so every disagreement cost the
+  user something real. Fixed:
+
+  - **Polarity was inverted.** The server violates a rule when the predicate is
+    TRUE; the engine violated it when the predicate was FALSE. Every
+    spec-authored `script` / `cross_field` rule produced the opposite verdict.
+  - **Envelope conditions were a silent no-op.** `{ dialect, source }` reached
+    `expression.trim()`, threw, was caught, and read as "passes".
+  - **`conditional` was a silent no-op**, reading `rule.condition` / `rule.rules`
+    where the spec says `when` / `then`; `otherwise` was never evaluated at all.
+  - **`format` produced FALSE REJECTIONS** — it read `rule.pattern`, and
+    `undefined.test(...)` threw into a catch that reported a violation, blocking
+    writes the server accepts.
+  - **An absent `active` disabled the rule** and an absent `events` threw; both
+    arrive absent from `/meta` because the spec defaults them at parse time.
+  - `priority` now orders execution; `initialStates` is enforced on insert;
+    `format`/`state_machine` only fire when the write touches the field; a broken
+    predicate or an uncompilable `regex` fails OPEN with a warning; and a rule type
+    the engine cannot evaluate (the spec's `json_schema`) warns instead of
+    reporting the record as valid.
+
+  The default `SimpleExpressionEvaluator` is not CEL and never was; it now binds
+  both the spec's `record.x` scope and objectui's historical bare `x`, and
+  documents that richer predicates need a CEL-backed evaluator. `validateRecord`'s
+  `event` parameter no longer accepts `'delete'`.
+
+  Gates: `packages/types/src/__tests__/validation-rule-spec-parity.test.ts` (key
+  sets, wire shapes, the pinned `then`/`otherwise` divergence with an inverted pin
+  that fails when objectstack#4171 is fixed upstream) and the rewritten engine
+  suite. objectstack#4115's ledger drops 120 → 115.
+
+### Patch Changes
+
+- b41f401: **Authoring types are input types (framework#4074 steps 2–3): `ActionParam` takes the spec's declaration forms, `ListViewSchema` stops promising parse-output defaults, and `FormField.dependsOn` matches its runtime reader.**
+
+  Three public types said something different from what the platform accepts. All
+  three divergences were found by making `packages/types`' tests compile (#3009)
+  and then resolving the declared `p1-spec-alignment.test.ts` debt site-by-site
+  instead of papering over it.
+
+  **`ActionParam` is now the authoring shape, aligned with the spec's input.**
+  `name` / `label` / `type` become optional and `field` / `objectOverride` appear:
+  the spec's primary way to declare a param — a bare field reference that inherits
+  label/type/validation/options from an object field — was unrepresentable while
+  all three were required. The _resolved_ shape the dialog consumes (after
+  app-shell's `resolveActionParams()` inlines the reference) remains
+  `@object-ui/core`'s `ActionParamDef`, with all three required. Authoring and
+  resolved are different types on purpose. `label` and option labels take the
+  spec's `I18nLabel` by import — which the new compile-time guard promptly
+  revealed to be aliased to plain `string` in the current spec (the per-locale
+  record is the separate `I18nObject`), so this is not a behavioural widening
+  today; importing the alias means objectui tracks any future widening
+  automatically.
+
+  **Breaking:** code destructuring `param.name` / `param.label` / `param.type` as
+  guaranteed must now handle the field-backed form (or consume the resolved
+  `ActionParamDef` instead, which is what dialog-side code should be doing).
+
+  **`ListViewInferred` is `z.input`, not `z.infer`.** The spec sub-schemas that
+  flow into the list-view surface (`userActions`, `tabs` → `ViewTab`, `sharing`)
+  carry `.default()`s, so the inferred output type made fields like
+  `userActions.refresh` or a tab's `pinned`/`visible` _required_ — but nothing on
+  the render path ever runs `.parse()`: `normalizeListViewSchema` deliberately
+  applies no defaults ("an absent flag stays absent", its own suite). The output
+  type therefore rejected valid authored metadata (`userActions: { sort: true }`)
+  while promising renderers defaults that never arrive. Typing the surface as
+  input matches both the author and the runtime object. Code that _trusted_ those
+  phantom defaults now gets an optionality error — which is a latent bug surfacing,
+  not a regression: the value really could be absent.
+
+  **`FormField.dependsOn` is `DependsOnInput`.** The runtime reader
+  (`resolveCascadingOptions`) has always accepted a bare name, a list of names, or
+  lookup-parameter entries `{ field, param }` — its parameter type says so. The
+  public property said `string`, so array-authored metadata type-errored while
+  working, and the form renderer read the key through `(f as any).dependsOn` to
+  get past its own type. The shape now lives in `@object-ui/types` (single source
+  of truth next to `FormField`), `@object-ui/core` imports and re-exports it, and
+  the two `as any` reads in the components form renderer are typed.
+
+  **The `p1-spec-alignment.test.ts` exclusion is gone.** Its 14 errors resolved:
+  the two "sharing in ObjectUI format" tests and the legacy-ARIA-spelling fixture
+  are deleted/rewritten — those dialects are _normalizer input_, folded by
+  `normalizeListViewSchema` and asserted branch-by-branch in core's
+  `normalize-list-view.test.ts`, the seam where the fold actually runs; asserting
+  them on the canonical type only ever "passed" because nothing compiled the file.
+  One fixture claimed a shape no surface ever admitted (an ObjectQL triplet as a
+  spec `ViewTab.filter`) and was corrected to the rule-object form. Every test
+  file in `@object-ui/types` is now compiled, with no exclusions.
+
+  Discrimination-checked: reverting `ListViewInferred` to `z.infer`, `dependsOn`
+  to `string`, or `ActionParam.name` to required each produces the expected
+  compile error in the now-compiled test files (`TS2739` / `TS2322` / `TS2741`);
+  restored, all projects are clean.
+
+- 95b7214: fix(list,grid,detail,tree,core): every column resolver reads one key (#3104 PR2)
+
+  PR1 (#3119) put a canonicalizing fold at ListView's ingestion boundary. This
+  converges the 22 read sites themselves onto `columnIdentity()` from
+  `@object-ui/core`, so a surface that is NOT downstream of that fold resolves
+  the same identity anyway.
+
+  That distinction is the user-visible part. A standalone `object-grid` node —
+  authored directly on a page, with no `list-view` above it — never passed
+  through `normalizeListViewSchema`. Its `getSelectFields` read `c.field` alone
+  while the `ensureId` probe one line above read `f?.name || f?.field`, so a
+  legacy `{ name: 'account' }` column reached `$select` as a literal `undefined`
+  hole: the server never returned the field and every cell in that column came
+  back empty. Same for `ObjectTree`, `RelatedList` and the `record:details` /
+  `record:related_list` renderers.
+
+  Converged:
+
+  | Surface                                  | Was                                            | Now                                 |
+  | ---------------------------------------- | ---------------------------------------------- | ----------------------------------- |
+  | `ListView` ×9 + its 2 request builders   | `name \|\| fieldName \|\| field` vs `f?.field` | `columnIdentity()`                  |
+  | `RelatedList` ×8                         | `accessorKey \|\| field \|\| name`             | `accessorKey \|\| columnIdentity()` |
+  | `ObjectGrid`                             | name-first probe vs `c.field` projection       | `columnIdentity()`                  |
+  | `ObjectTree`                             | `name \|\| fieldName \|\| field \|\| key`      | `columnIdentity() \|\| key`         |
+  | `buildExpandFields`                      | `field ?? name ?? fieldName`                   | `columnIdentity()`                  |
+  | `record-details` / `record-related-list` | `field \|\| name (\|\| key)`                   | `columnIdentity() (\|\| key)`       |
+
+  `accessorKey` keeps its precedence in `RelatedList` — it is TanStack Table's
+  column key, not ObjectStack metadata identity, and only the `field || name`
+  tail was converged. `key` stays a tail fallback in `ObjectTree` and
+  `record-related-list` for the same reason: it is a generic entry key.
+
+  Two incidental fixes that TypeScript surfaced once the resolver stopped
+  returning `any`: ListView's filter-field options and its hide-fields popover
+  both built entries keyed `undefined` for a column with no resolvable identity.
+  Those entries could never match a column; they are now dropped.
+
+  **Inventory re-triage.** PR1 recorded 24 family members. Two were mis-classified
+  and are reclassified here rather than converged — reading what they actually
+  feed shows they are not column reads at all:
+
+  - `ViewPreview.tsx` adapts a ViewItem **form** section to what `object-form`
+    selects by (`field` → `name`) — the #3090 two-layer join.
+  - `SchemaForm.tsx` renders an arbitrary metadata **array** into a popover
+    summary and guesses at a display key; the entries are validations, actions,
+    or whatever the JSON schema declares.
+
+  So the family was 22, and it is now **0**. The ratchet asserts that, asserts
+  each converged surface actually routes through the shared reader (a surface
+  that dropped identity resolution instead of converging it goes red), and pins
+  `accessorKey`'s precedence in `RelatedList`.
+
+- 7d9734d: feat(core): say which column identity key won, out loud (#3104 PR3)
+
+  Closes the battle opened in #3104. PR1 (#3119) put the canonicalizing fold at
+  ingestion; PR2 (#3122) converged all 22 read sites onto `columnIdentity()`.
+  This is the audible half.
+
+  A column carrying two identity keys that **disagree** — `{ field: 'account',
+name: 'account_name' }` — now logs a one-time dev-mode warning naming which key
+  won and what to change:
+
+  ```
+  [ObjectUI] Column carries two identities: `field: 'account'` and
+  `name: 'account_name'`. `field` wins — it is the only key `ListColumnSchema`
+  declares — and `name` has been rewritten to match, so the rendered column and
+  the requested field agree. Fix the producer: drop `name` and author `field`
+  only. (objectui#3104)
+  ```
+
+  The fold making the two halves agree is what stops the bug, but silently
+  rewriting `name` to match `field` also hides that the producer is emitting a
+  contradiction. The renderer recovering is not the same as the metadata being
+  right, so the recovery says so.
+
+  Deliberately narrow:
+
+  - **Only contradictions.** A legacy-only column (`{ name: 'stage' }`) is legacy,
+    not conflicting — it is stamped without noise.
+  - **Warn once per (identity, conflicting spelling).** Columns are re-normalized
+    on every render; a warning that floods the console is a warning that gets
+    muted. Keyed by the pair rather than the identity alone, so a column carrying
+    two different stale spellings reports both — the author needs to fix every
+    producer, not just the first one seen.
+  - **Silent under `NODE_ENV=production`**, and the fold still runs there.
+
+  `resetColumnIdentityWarnings()` is exported for tests.
+
+  **No lint rule, and that is a measured decision.** #3104 asked for
+  `no-restricted-syntax` on `.field ?? .name` to be evaluated on its
+  false-positive rate first. With the family at zero, all 12 remaining scanner
+  hits are legitimate — a syntactic rule cannot tell a two-layer join from a dual
+  read, because the distinction is what the keys mean in that layer, not how the
+  expression is spelled. Adopting it would mean 12 inline disables on correct
+  code, which trains the next author to reach for the disable. The ratchet carries
+  a `verdict` and a `why` per site instead, so a new hit gets triaged rather than
+  silenced. The evaluation is written into the ratchet's header.
+
+  **Ledger item resolved with no change needed.** #3104 flagged `ListColumn` for
+  disposition under objectstack#4115 (spec-named symbols must be imports, not
+  declarations). `ListColumnSchema` is already a by-reference re-export of
+  `@objectstack/spec/ui`, and `spec-subschema-parity.test.ts` already pins it by
+  reference identity — the only check that distinguishes a re-export from a
+  faithful fork. Already compliant; nothing to do.
+
+- aebfa4f: chore(core): deprecate `ObjectValidationEngine` — rule enforcement stays single-implementation on the server (#3110)
+
+  `ObjectValidationEngine` / `defaultObjectValidationEngine` / `validateRecord` are
+  now `@deprecated`. **Nothing is removed and no behaviour changes** — existing
+  callers keep working exactly as they did after #3103.
+
+  **Why.** Object-level validation rules are _enforcement_, and enforcement is
+  single-implementation on the server (`objectql`'s rule-validator). objectui
+  already draws that line for the predicates it _does_ evaluate client-side:
+  `evaluator/fieldRules.ts` handles the presentation predicates (`visibleWhen` /
+  `readonlyWhen` / `requiredWhen`) by delegating to the canonical
+  `ExpressionEngine`, "rather than re-implementing a parallel evaluator"
+  (ADR-0036). This engine was that parallel evaluator, on the enforcement side.
+
+  #3103 converged its semantics onto the server rule-for-rule, with eight
+  mutation-tested gates — and still left a known divergence: the server carries
+  ADR-0113's legacy-violation exemption (reject only when the merged state violates
+  _and_ this write makes it worse), which this engine does not implement. Editing
+  an unrelated field on a legacy row would be blocked here and accepted there. One
+  careful pass still left a gap, which is the argument: mirroring cross-repo
+  behaviour is structurally unreliable, not unreliable-this-time.
+
+  **What to use instead.** Let the write fail and render the server's rejection —
+  it is already structured (`field` / `code` / `message`, plus a label since
+  objectstack#3957). For pre-submit feedback, the answer is a validate-only
+  (dry-run) write on the server: identical UX, zero parity risk, and it covers the
+  two rule kinds a client can never check — `unique` (needs the database) and
+  `json_schema` (ajv lives server-side).
+
+  **The decision is a mechanism, not a comment.** What #3103 removed was a doc
+  comment claiming spec canonicity that had been false for fifteen majors;
+  shipping its successor as another comment would repeat the mistake one level up.
+  `validation-engine-stays-unwired.test.ts` scans `packages/*/src` and fails if a
+  production module starts referencing the engine, naming the file and the issue to
+  reverse first. Barrels still re-export it — publishing a deprecated API is not
+  wiring — and host applications are free to keep importing it.
+
+  The five spec-derived rule TYPES in `@object-ui/types` are unaffected: they are
+  the anchor for objectstack#4115's ledger and are independent of whether objectui
+  ships an engine.
+
+- c4d7b20: fix(view,list,core): a view's filter no longer disappears, or arrives as a predicate on columns that don't exist
+
+  Sweeping the other `$filter` producers after #3078 turned up two live defects in
+  `ObjectView`, which fetches its own data for calendar / kanban / gallery /
+  timeline (grid delegates to `ObjectGrid`).
+
+  **1. An object filter was dropped, and only for non-grid views.**
+  `table.defaultFilters` is declared `Record<string, any>`, and the merge tested
+  `baseFilter.length > 0` — `undefined > 0` for an object. So the filter vanished
+  and the view returned **every record**. `ObjectGrid` assigns the same value
+  straight to `params.$filter`, so one view definition filtered correctly as a
+  grid and returned everything as a calendar.
+
+  **2. Rule objects were spread into the `and`, not wrapped.**
+  `['and', ...baseFilter, ...userFilter]` is only correct when the source is an
+  array of AST nodes. `activeView.filter` is a spec `ViewFilterRule[]`, so
+  spreading put bare rule objects where the AST expects nodes:
+
+  ```js
+  isFilterAST([
+    "and",
+    { field: "stage", operator: "eq", value: "won" },
+    ["owner", "=", "me"],
+  ]);
+  // false → 400 since objectstack#4121
+  parseFilterAST(same);
+  // {$and:[{field:'stage',operator:'eq',value:'won'}, {owner:'me'}]}
+  ```
+
+  That second line is a predicate over three columns named `field`, `operator`
+  and `value` — which don't exist.
+
+  > **Correction.** The first version of this note said the spread was "reachable
+  > whenever a view with a filter meets a user filter value". That was wrong for
+  > `ObjectView`: the branch required a non-empty user filter, and nothing ever
+  > wrote the state it was built from, so it could never run. The shape is
+  > genuinely broken — a live server answers it with a 400 — and the adapter-level
+  > defence added alongside is still warranted for any producer that emits it, but
+  > **this particular site was dead code, not a live defect.** Defect 1 above was
+  > live: it sat on the always-taken path. The dead machinery behind the wrong
+  > claim is removed in a follow-up.
+
+  New in `@object-ui/core`: `toFilterNode` normalizes one source (rule array / AST
+  / MongoDB object) and `mergeFilterNodes` combines sources as siblings under one
+  `and`. `ObjectView` and `ListView.buildEffectiveFilter` both use them, so the
+  three filter shapes are reconciled in one place instead of by hand at each
+  renderer.
+
+  `ObjectStackAdapter` also now translates a bare rule object sitting directly
+  under a logical node — the chokepoint defence for any producer still emitting
+  the spread shape. Only rule-_shaped_ objects are touched; a child with no
+  `field` is a genuine MongoDB condition and passes through untouched.
+
+  **Correcting a comment shipped in #3078.** `buildEffectiveFilter` documented the
+  dropped-object case as unreachable, "nothing in this repo produces one for a
+  list view". That was wrong: `ObjectView` passes `mergedFilters` straight into
+  that schema's `filter`, and its last fallback is `table.defaultFilters`. The
+  case is now handled rather than explained away.
+
+  Verified with 19 tests across the four packages; reverting each source file
+  fails the ones that cover it. Emitted filters are asserted against the spec's
+  own `isFilterAST` / `parseFilterAST`, including an executable pin on what the
+  old spread shape produced.
+
+- 6f29aa5: fix(grid): a legacy string row action runs instead of green-toasting a no-op — objectui#2960
+
+  A list view declaring `rowActions: ['convert_lead']` rendered a menu item that
+  performed **zero network requests** and reported success. Where the object also
+  declared the same action with `locations: ['list_item']`, the row menu showed a
+  working entry and a dead duplicate of it side by side.
+
+  **The name never became an action.** `ObjectGrid` dispatched the legacy form as
+  `{ type: <action name>, params: { record } }` — the action _name_ landing in the
+  runner's `type` slot, never resolved against the object's action defs. It
+  matches no built-in type and (absent a handler registered under that exact name)
+  no handler either, so it fell through to `ActionRunner.executeActionSchema`,
+  which returned `{success: true, reload: true, close: true}` for a schema with
+  nothing in it. `handlePostExecution` then fired the green "Action completed
+  successfully" toast.
+
+  Two changes, either of which would have surfaced the bug:
+
+  **① `ObjectGrid` resolves legacy names against `objectDef.actions`.** A name
+  that matches a declared action is promoted to that def and dispatched through
+  the same path as a `list_item` action — so it actually runs, and it picks up the
+  def's label, `visible`/`disabled` predicates, param dialog and capability gate,
+  none of which the string form could carry. A name that matches an action already
+  rendered as a def is dropped, which is what removes the dead twin. Names that
+  resolve to nothing are still dispatched by name, since a consumer may have
+  registered a runner handler under exactly that name.
+
+  **② `ActionRunner`'s empty-schema fallthrough fails loudly.** It no longer
+  reports success for an action it never ran: a dispatch with no registered
+  handler and no `api`/`endpoint`/`navigate`/`redirect`/`onClick` returns a
+  failure naming the action. Schema-only shapes that _do_ declare something — a
+  bare `redirect`, an explicit `reload`/`close` — run exactly as before.
+
+- ad0183a: fix(data-objectstack,core): an object filter no longer depends on whether the query expands a lookup
+
+  #3072 single-sourced the ARRAY branch of the adapter's two `find()` routes. The
+  object branch was left as it was: `convertQueryParams` converted a MongoDB-style
+  filter to AST while `translateFilterToAST` returned it verbatim — so the same
+  `$filter` went out in two formats, decided by whether the query happened to
+  expand a lookup.
+
+  Measured across 21 operator shapes, **four diverged**. Most of the gap turned
+  out to be harmless — `{$and: […]}` survives the plain route as a
+  `['$and','=',[…]]` comparison that `parseFilterAST` reads back as a real `$and`,
+  and `$exists` vs `$null` is a difference the server treats identically. Two were
+  not harmless:
+
+  - **The unknown-operator guard only ran on one route.** `convertFiltersToAST`
+    throws on an unrecognised operator, with a comment saying it does so "to avoid
+    silent failure" — but the expanded route never called it, so a typo'd operator
+    threw on a plain read and shipped silently whenever a lookup was expanded.
+  - **`$regex` was silently rewritten to `contains`.** `$regex: 'a.c'` matches
+    "abc"; `contains 'a.c'` matches only those three literal characters. That is a
+    _different question_, not a weaker version of the same one, and neither result
+    looks wrong on screen. The rewrite sat behind a `console.warn`, which is not
+    an error channel in a deployed app — and the function's own unknown-operator
+    message never listed `$regex` among the supported set. The spec has no
+    `$regex` (`FILTER_OPERATORS`, `data/filter.zod.ts`), so there is nothing to
+    translate it into: it is now refused, the same treatment the neighbouring
+    unknown operator already got. Nothing in the repo depended on the conversion.
+
+  Both refusals now throw `FilterOperatorError`, carrying `code: 'INVALID_FILTER'`
+  / `httpStatus: 400`. The pre-existing unknown-operator throw was a bare `Error`,
+  which `classifyLoadError` classifies as a network fault — so a malformed filter
+  told the user to check their connection (#3066), the one thing it definitely
+  was not.
+
+- aa1240a: fix(sdui): lazily-registered public blocks reach a `kind:'react'` page's scope, and ReactRunner keeps the errors it catches
+
+  Two defects in the trusted `kind:'react'` page tier.
+
+  **objectui#2953 — the contract skipped lazy blocks.** `getPublicConfigs()`
+  resolved every curated `PUBLIC_BLOCKS` tag through `getConfig()`, which reads
+  loaded registrations only, so a block registered with `registerLazy()` was
+  absent from the contract until its plugin chunk happened to be imported. In
+  `apps/console` that silently dropped `object-kanban`, `object-calendar`,
+  `object-gantt`, `object-timeline`, `object-map` and `markdown` from every react
+  page's scope — writing `<ObjectKanban/>` threw `ReferenceError` even though the
+  tag is a first-class contract member, and whether it threw depended on load
+  order. `getPublicConfigs()` now resolves pending lazy stubs too, returning them
+  with `lazy: true` and no `component` (new `PublicComponentConfig` type); the
+  injected wrapper renders through `SchemaRenderer`, which triggers the loader and
+  shows its placeholder. `getConfig()` stays loaded-only by design.
+
+  **objectui#2954 — ReactRunner discarded its own error state.**
+  `getDerivedStateFromProps` re-transpiled and re-evaluated the page source on
+  every render and unconditionally set `error: null`. React runs it before the
+  re-render that follows `getDerivedStateFromError`, so the boundary threw away
+  the error it had just caught, rebuilt an identical throwing element, and the
+  throw escaped past its own `fallback` to the renderer's generic panel; `onError`
+  was gated on state that had already been cleared and never fired for a
+  compile-time error at all; and each compile minted a fresh page function — a new
+  element type — that remounted the subtree and wiped the page's `useState`. The
+  transpile+eval is now memoised on `(code, scope)`, errors persist until the
+  inputs actually change, and `onError` reports each error exactly once.
+
+- d10f526: fix(sdui): the curated contract lists `record:line_items`, the tag that actually resolves
+
+  `PUBLIC_BLOCKS` carried `line_items` — the bare tag. `@object-ui/plugin-form`
+  registers the block as `record:line_items` with `skipFallback: true`, which
+  exists precisely so the bare name is _not_ claimed, so that key never existed
+  and the curated entry could never resolve. Its four siblings in the list are all
+  `record:`-prefixed, and plugin-form's own comment says "Register
+  record:line_items"; the bare spelling was a slip.
+
+  The effect was a block that has shipped all along — a full renderer, a label,
+  five declared `inputs` — being absent from the public contract, from the JSX
+  type surface, from the generated manifest, and from every `kind:'react'` page's
+  scope. It read as an unimplemented aspirational entry, which is how it was
+  recorded when objectui#2979 added the contract-coverage guard.
+
+  With the tag corrected the contract has no gaps left: all 36 curated tags
+  resolve in the console, `record:line_items` among them with its full `inputs`.
+  The guard's known-unimplemented list is now empty and stays asserted, so the
+  next entry that cannot resolve surfaces instead of being explained away.
+
+- 2d5d594: fix(list,detail): sorting a lookup column no longer orders by an invisible key — #3096
+
+  A relational column (`lookup` / `master_detail` / `user` / `tree`) never holds
+  the string its cell shows: it holds the `$expand`-ed record, or a raw foreign-key
+  id whose label was resolved separately. Every sort path took that raw value as
+  its key, so the column of names came back in an order with no relation to the
+  names — sorting looked broken, with nothing saying the key was something else.
+
+  The two halves are fixed differently, because they can order by different things:
+
+  - **Client-side sorts** (grid column headers, any `data-table`, a non-windowed
+    related list) now key off the label the cell renders, via the new
+    `getSortValue` / `compareSortValues` in `@object-ui/core` — which resolves an
+    expanded record through `getRecordDisplayName` (ADR-0079), so the sort key and
+    the lookup cell agree on which field names a record. This replaces two broken
+    comparators: `a[col] < b[col]` is always false between two objects (the
+    comparator collapsed to a constant and permuted the rows), and
+    `String(a[col])` is `"[object Object]"` (every row compared equal, so the sort
+    silently did nothing).
+  - **Server `$orderby` sorts** cannot be fixed here — the key is the stored id by
+    construction, and `objectstack#4256` settled that no relation join is coming.
+    So those entry points stop offering the illusion: the ListView toolbar sort
+    picker withholds relational fields and explains why (pointing at a formula
+    field as the supported way to sort by a related name), and a windowed related
+    list renders no sort button for them.
+
+  A relational field the view's CURRENT sort already uses stays listed, labelled
+  `(by ID)`, so view metadata authored or saved with such a sort round-trips
+  instead of rendering a blank row and losing the sort on the next edit.
+
+- 7f23cd0: fix(form): a numeric/boolean select option survives selection with its type intact — #3090
+
+  `SelectOptionSchema.value` has accepted `string | number | boolean` for as
+  long as it has existed, but the Radix controls underneath speak strings:
+  picking `{ value: 2 }` silently submitted `"2"` — a wrong-typed write into a
+  number field that nothing on the client ever reported. (Display half-worked:
+  a numeric default matched its numeric item; only SELECTION morphed the type.)
+
+  The renderers now stringify on the way into the control and map the selection
+  back to the AUTHORED option value on the way out (`matchOptionValue`), across
+  the in-form select, the standalone `type: 'select'` component, and the
+  standalone `type: 'radio-group'` component. The TS types stop lying to match:
+  `SelectOption.value` / `RadioOption.value` and the corresponding
+  `value`/`defaultValue`/`onChange` channels widen to what the zod schemas
+  always accepted — a call site treating `option.value` as `string` is now a
+  compile error pointing at a real latent crash, not a false comfort.
+
+  The ripple the widening named, handled at each boundary: `@object-ui/core`'s
+  `OptionLike.value` widens (the option engines compare by identity, so values
+  flow opaquely; the option-lint's CEL-literal domain stringifies at its
+  boundary), and the multi-value field widgets (checkboxes / multiselect /
+  radio) stringify at theirs — multi-value fields store string arrays.
+
+  Round-trip pinned by real Radix interactions in jsdom: the in-form select
+  submits `2` (number), the standalone select hands its handler `false`
+  (boolean).
+
+- Updated dependencies [9e7349e]
+- Updated dependencies [8864971]
+- Updated dependencies [b41f401]
+- Updated dependencies [19e9fa0]
+- Updated dependencies [38ca8be]
+- Updated dependencies [4952edf]
+- Updated dependencies [7f0252e]
+- Updated dependencies [7639a61]
+- Updated dependencies [94e63ef]
+- Updated dependencies [c4db402]
+- Updated dependencies [5319bf1]
+- Updated dependencies [49e5671]
+- Updated dependencies [b5b97e2]
+- Updated dependencies [f59f2c1]
+- Updated dependencies [4874117]
+- Updated dependencies [ce08d55]
+- Updated dependencies [2374a49]
+- Updated dependencies [ea7f477]
+- Updated dependencies [7f23cd0]
+- Updated dependencies [24e0e0a]
+- Updated dependencies [3a6cf24]
+- Updated dependencies [aa35561]
+- Updated dependencies [03bd53b]
+- Updated dependencies [3c1f321]
+- Updated dependencies [a045a32]
+- Updated dependencies [912496d]
+- Updated dependencies [9867281]
+  - @object-ui/types@17.1.0
+
+## 17.0.0
+
+### Minor Changes
+
+- f9bbddb: feat: gate detail/form edit & delete on the server's effective operation set (#3546)
+
+  PR-4 (#3391) wired the **list/toolbar** surface (ObjectView Import, ListView /
+  ObjectGrid Export) to the server-resolved effective API operation set
+  (`/me/permissions` `apiOperations`, intersected via
+  `resolveCrudAffordances(obj, effectiveApiOperations?)`). The **detail / form**
+  surfaces still gated edit/delete on the bucket + `userActions` alone. This
+  extends the same intersection to them, so the record page and its forms never
+  offer an operation the server would 405.
+
+  - **core** `isObjectInlineEditable(obj, effectiveApiOperations?)` gains the same
+    optional second argument as `resolveCrudAffordances` — inline-edit is now
+    additionally ANDed with the server allowing `update`.
+  - **app-shell** `RecordDetailView` threads the object's effective operations into
+    the synthesized Edit/Delete header actions and the record-body inline-edit
+    gate (`canEdit`); `RelatedRecordActionsBridge` intersects each **child**
+    object's Create/Edit/Delete handlers with that child's own effective set.
+  - **plugin-detail** `record:details` ANDs its inline-edit affordance with the
+    object's effective `update`.
+  - **plugin-form** `ObjectForm`'s blanket managed-object field lock also engages
+    when the server denies `update` (edit mode) / `create` (create mode).
+
+  Backward-compatible: a missing effective set (unrestricted object, older
+  backend, or no `PermissionProvider`) leaves the resolved affordance untouched —
+  the bucket/`userActions` decision wins, exactly as today. Layers on top of the
+  existing per-object `check('edit')` / `check('delete')` permission gates
+  (intersection, never union).
+
+- 2735de6: feat: render the server's effective API operation set (#3391 PR-4)
+
+  The frontend now consumes the per-object **effective API operation set** the
+  server resolves (from `/me/permissions` `apiOperations`, framework #3391) —
+  never the raw `apiMethods` — so Import/Export/New/Edit/Delete buttons match what
+  the server will actually admit, and a 405 import refusal shows a dedicated
+  message instead of silently falling back.
+
+  - **core** `resolveCrudAffordances(obj, effectiveApiOperations?)` — new optional
+    second argument intersects each affordance bit with its API operation
+    (create/import→create/import, edit→update, delete→delete, exportCsv→export).
+    Omitting it (old backend / no effective set) leaves affordances unchanged.
+  - **permissions** — `/me/permissions` response carries per-object
+    `apiOperations`; `PermissionContextValue.getObjectApiOperations(object)`
+    exposes it (undefined when absent → callers keep current behavior); `check()`
+    maps `import→allowCreate`, `export→allowRead`.
+  - **app-shell** `ObjectView` intersects its toolbar affordances with the object's
+    effective operations (Import); the platform-admin identity-import bypass is
+    unaffected.
+  - **plugin-list** `ListView` / **plugin-grid** `ObjectGrid` gate the Export
+    button (and export handler) on effective `export`; `plugin-grid` gains the
+    `@object-ui/permissions` workspace dependency.
+  - **plugin-grid** `ImportWizard` — a 405 / `OBJECT_API_METHOD_NOT_ALLOWED`
+    import refusal is detected by a new `isImportNotAllowed` predicate at every
+    catch site (async, sync, dry-run) and STOPS with a dedicated
+    `grid.import.notAllowed` message (10 locales + fallback dict) — it never falls
+    back to the sync/legacy path (which 405s too), distinct from the 404
+    route-absent fallback.
+
+  Backward-compatible: a missing effective set (unrestricted object, older
+  backend, or no permission provider) preserves the current default-allow
+  behavior everywhere.
+
+- cd09a7b: refactor(views): ListView reads the spec-canonical `columns`, with legacy `fields` folded in one normalizer (#2890 scope A step 1)
+
+  `ListViewSchema` has been derived from `@objectstack/spec/ui` since #2231, but
+  the renderer still spoke objectui's own vocabulary for the same concepts. First
+  rename closed: **`fields` → `columns`**.
+
+  Legacy acceptance does not disappear — stored view metadata in user databases
+  carries `fields` — but it now lives in exactly one place instead of being
+  re-implemented per read-site:
+
+  - **New `normalizeListViewSchema` (`@object-ui/core`)** folds `fields` into
+    `columns` (canonical wins when both are present) and drops the legacy key, so
+    a read-site that was missed fails loudly instead of quietly taking the legacy
+    path. It also absorbs the `viewType` renderability default ListView applied
+    inline. Non-mutating, idempotent, and returns its input by reference when
+    there is nothing to fold, so ListView's downstream memos keep a stable
+    dependency identity.
+  - **`ListView` normalizes once at the component boundary**, before anything
+    reads the schema. This is what guarantees the fold runs: nothing on the render
+    path parses view metadata through zod (the zod schemas serve the CLI
+    validator, the VS Code extension and tests), so a `z.preprocess` on
+    `ListViewSchema` — spec-side or local — would never execute.
+  - **Producers emit `columns`**: `ObjectView`'s `renderListView` payload,
+    `ObjectDataPage`, `InterfaceListPage` and the `list-view` registry defaults
+    had been _downgrading_ already-canonical `columns` config back to `fields`.
+
+  Two latent inconsistencies go away with it: the filter builder's
+  objectDef-not-loaded fallback now resolves `ListColumn.field` (it read only
+  `name`/`fieldName`, so object-form columns produced unnamed filter entries), and
+  the column list no longer depends on which of the two keys a host happened to
+  emit.
+
+  `fields` stays declared on `ListViewSchema` and in the drift guard's sanctioned
+  set — it is still valid input, and `@objectstack/spec`'s `react-blocks.ts`
+  sanctions it as the React-tier `<ListView fields>` prop — but it is input-only.
+
+- f1abf0e: fix(views): ListView reads the spec-canonical `filter`, so a view's base filter reaches every visualization (#2890 scope A step 4)
+
+  Third rename in the ListView vocabulary migration: **`filters` → `filter`**. Unlike
+  the first two this closes a live bug, because the fork was asymmetric.
+
+  `ListView` was the **only** surface in the repo reading `filters`. Every child
+  view — `ObjectGrid`, `ObjectGallery`, `ObjectKanban`, `ObjectCalendar`,
+  `ObjectGantt`, `ObjectMap`, `ObjectTree`, `ObjectChart` — reads `filter`, and
+  `ListView` handed them `filters`. Wherever a child fetches its own rows instead
+  of receiving `ListView`'s, the view's base filter was silently dropped:
+
+  - **a `chart` list view aggregated the whole object.** The chart branch built an
+    `object-chart` node with `filters:`; `ObjectChart` reads `schema.filter` and
+    never read `filters`, so a chart view with a base filter charted unfiltered
+    totals.
+  - the same applied to any of the other view components rendered standalone from
+    a list-view-shaped config.
+
+  Conversely, a **spec-authored** list view — one carrying `filter`, which is what
+  the spec says and what `runtime-metadata-persistence` and "Save as view" already
+  persist — rendered **unfiltered** in `ListView`, because nothing read that key.
+
+  The fold is a key rename only. Both keys carry an ObjectQL FilterNode array
+  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 left alone here: converting formats inside a
+  vocabulary fold would change what reaches the data source.)
+
+  Also collapses a duplicated computation in `app-shell`'s `ObjectView`, which
+  computed the same effective filter **twice** — once as `filter` for the child
+  views, once as `filters` for `ListView` — with the two copies subtly different
+  (only one fell back to `listSchema.filter`; only the other ran token
+  substitution over the URL filters). There is now one computation, keeping both
+  behaviors.
+
+  `filters` stays declared on `ListViewSchema` and in the drift guard's sanctioned
+  set — stored views carry it and it is still valid input — but it is input-only.
+
+- f05b84e: refactor(views): ListView resolves density from the spec-canonical `rowHeight` (#2890 scope A step 2)
+
+  Second rename in the ListView vocabulary migration: **`densityMode` → `rowHeight`**,
+  folded in the same `normalizeListViewSchema` that step 1 introduced.
+
+  Unlike `fields`/`columns` this is not a pure alias — the two vocabularies are
+  different sizes. The spec has five row heights (`compact`/`short`/`medium`/
+  `tall`/`extra_tall`); ListView's toolbar offers three densities
+  (`compact`/`comfortable`/`spacious`). Both directions now live in one place as
+  `DENSITY_MODE_TO_ROW_HEIGHT` / `ROW_HEIGHT_TO_DENSITY_MODE`, chosen so a fold
+  followed by a read is a round trip (`spacious` → `tall` → `spacious`), with the
+  narrowing collapse (`short` → `compact`, `extra_tall` → `spacious`) stated once
+  instead of being re-derived per call site.
+
+  Two behavior fixes fall out of it:
+
+  - **Precedence is no longer inverted.** `ListView` read `densityMode` _first_, so
+    a view carrying both keys rendered the legacy value — backwards from every
+    other legacy/canonical pair in the schema. The canonical key now wins.
+  - **The toolbar stops re-seeding the legacy key.** `ObjectView`'s
+    `onDensityChange` persisted `densityMode` into stored view metadata on every
+    density toggle, so the legacy vocabulary kept regrowing underneath the
+    migration. It persists `rowHeight` now.
+
+  `densityMode` stays declared on `ListViewSchema` and in the drift guard's
+  sanctioned set — stored views carry it and it is still valid input — but it is
+  input-only.
+
+### Patch Changes
+
+- 7b35e4b: fix(dashboard,charts): resolve `{current_user_id}` in widget filters (framework #3574)
+
+  A dashboard widget filtered on `{current_user_id}` rendered `0`. The token
+  reached SQL as a literal, matched no row, and nothing was logged on the client
+  or the server — a silent zero that reads as "you have no work" rather than
+  "this filter did not resolve". The same token in a list-view filter resolved
+  correctly, so a user-scoped list and a user-scoped widget over the same data
+  disagreed.
+
+  There was no shared resolver. Three ad-hoc implementations had grown up
+  independently — `ObjectView` for list views, `ObjectDataPage` for URL filter
+  triples, `NavigationRenderer` for hrefs — and each understood only the filter
+  shape its own surface used. `ObjectView`'s opened with
+  `if (!Array.isArray(filter)) return filter`, so it could not have been reused
+  by dashboard widgets even in principle: widget filters are MongoDB-style
+  objects. Widgets therefore got no resolution at all — `DatasetWidget` called
+  `resolveDateMacros` and nothing else, which is why `{today}` worked in a widget
+  and `{current_user_id}` silently did not.
+
+  - **`@object-ui/core`** — new `utils/filter-tokens.ts` with
+    `resolveContextTokens` and `resolveFilterPlaceholders`. The latter expands
+    _every_ placeholder vocabulary in one call and is what surfaces should use;
+    resolving only some of them is the whole defect. The walk handles arrays and
+    plain objects uniformly, so one resolver covers both platform filter shapes.
+  - **`@object-ui/react`** — new `FilterScopeProvider` / `useFilterScope`. The
+    renderer packages deliberately do not depend on `@object-ui/auth`, so the
+    shell supplies the session values. This is a separate context from
+    `PredicateScopeContext`, which is the expression evaluation scope and carries
+    no organization.
+  - **`@object-ui/plugin-dashboard` / `@object-ui/plugin-charts`** — all six
+    widgets that previously resolved date macros only now resolve both
+    vocabularies: `DatasetWidget`, `ObjectMetricWidget`, `ObjectDataTable`,
+    `ObjectPivotTable`, and `ObjectChart` (dataset-bound and inline paths). The
+    chart's `compareTo` comparison filter gets the session pass too — otherwise
+    the overlay series silently ignored the owner clause the primary series
+    honoured.
+  - **`@object-ui/app-shell`** — `ObjectView`'s local `substituteFilterTokens`
+    and `ObjectDataPage`'s inline `=== '{current_user_id}'` ternary now delegate
+    to the shared resolver, so both also gain `{current_org_id}` and date macros.
+    Two of the three ad-hoc implementations are gone rather than joined by a
+    fourth.
+
+  An unresolvable token is left intact rather than dropped: leaving it yields an
+  empty result, whereas dropping the clause would _widen_ the result set and show
+  a signed-out viewer everyone's data. It is no longer silent — the resolver
+  warns, naming the token, and suggests the intended spelling for known
+  near-misses (`{current_user}`, `{user_id}`, `{organization_id}`). Authoring-time
+  enforcement lands separately as `filter-token-unknown` in `@objectstack/lint`.
+
+- e16ed2d: fix(dashboard,charts): send widget `dateGranularity`/`sortBy`/`limit` to the query, and give funnels a real stage order (framework#3588)
+
+  `DatasetWidget` never read `widget.options`. Four keys an author writes there
+  change the query the server compiles, so a widget declaring
+  `options: { dateGranularity: 'month' }` grouped by the raw timestamp and drew
+  one bar per record, and `sortBy`/`sortOrder` produced no ordering at all.
+
+  - `DatasetWidget` lowers `options.dateGranularity`, `options.sortBy` +
+    `options.sortOrder`, and `options.limit` into the `DatasetSelection` it posts.
+    A `sortBy` naming something the widget does not project is dropped rather than
+    sent, so a stale sort key left by an edit degrades to "unordered" instead of
+    failing the widget against the server's stricter validation. These keys also
+    join the refetch signature, so editing one in the designer refetches instead
+    of re-rendering the previous grid.
+  - Funnel stages follow a **declared order**. `AdvancedChartImpl` sorted funnel
+    segments by value descending, unconditionally — which overrode any server
+    ordering and rendered a sales pipeline as a tidy narrowing shape whatever the
+    stages' real sequence, hiding the very anomaly (a bulge at Proposal) the chart
+    exists to show. It now honours a `categoryOrder`, which `DatasetWidget`
+    derives from the dimension field's picklist option order — the pipeline order
+    an author already declared on the object — or from an explicit
+    `options.stageOrder`. With no declared order the value-descending default is
+    unchanged, and a category missing from the order is kept (after the declared
+    ones), never dropped.
+  - New `@object-ui/core` helpers `buildCategoryOrder` / `buildCategoryRank`,
+    keyed by both the stored value and the display label like the existing
+    `buildOptionColorMap`, so ordering works whether or not the server resolved
+    the dimension's labels.
+
+  Requires the framework-side fix in objectstack#3588 for the selection keys to
+  take effect server-side.
+
+- 53642d4: fix(core,fields): a string `$orderby` is a clause, not a character array — and localize the sharing-rule widgets (objectstack#3821)
+
+  **The recipient picker listed nothing, ever.** `QueryParams['$orderby']` was
+  typed as `Record | string[] | SortObject[]`, so `queryParamsToRecord` sent any
+  non-array value through `Object.entries`. Handed the clause string `'name asc'`
+  — which callers do build by hand — it walked the string index by index and
+  emitted `$orderby=0 n,1 a,2 m,3 e,4 ,5 a,6 s,7 c`. The server sorted by columns
+  that don't exist and every row was filtered out, so
+  `sys_sharing_rule.recipient_id` rendered "No matches" for every recipient type
+  and no sharing rule could be created from the Console. `ObjectGrid` builds the
+  same shape from a schema-level `sort` in three places, so grids with a string
+  sort silently showed an empty table.
+
+  A string `$orderby` is now passed through verbatim (the server's OData
+  normalizer has always parsed `'name asc'`), and the type admits `string`.
+  `RecipientPickerField` additionally switched to the structured
+  `{ name: 'asc' }` form so it can't regress this way against any data source.
+
+  **The three sharing-rule authoring widgets never had translations.**
+  `ObjectRefField`, `RecipientPickerField` and `FilterConditionField` hardcoded
+  their English copy — a Chinese Console showed "Select an object", "Select a
+  user", "Search…", "No matches", "Edit as JSON". They now go through
+  `useFieldTranslation` like every other widget, with keys added under `fields.*`
+  in all ten locales.
+
+  The recipient placeholder was the interesting one: it read
+  `` `Select a ${recipientType.replace(/_/g,' ')}` ``, interpolating the enum
+  value into an English sentence — a shape no locale can translate. It is now a
+  per-type key (`fields.recipient.selectUser`, `…selectBusinessUnit`, …), so
+  "选择业务单元" and "Select a business unit" no longer have to share a structure.
+
+  **Editing a rule silently dropped its recipient.** The picker resets the stored
+  id when `recipient_type` changes, because an id valid for a user is meaningless
+  for a team. It treated the edit form's `'' → 'user'` hydration as such a change:
+  opening any saved rule blanked the recipient, and saving persisted the blank.
+  Only a non-empty predecessor now counts as a type switch.
+
+  **Building a filter submitted the surrounding form.** None of `FilterBuilder`'s
+  controls declared `type="button"`, and a bare `<button>` inside a `<form>`
+  defaults to `type="submit"`. Adding, removing or clearing a condition therefore
+  submitted the sharing-rule dialog — firing validation mid-edit, and on an
+  already-valid form saving the record before the admin was done.
+
+  **A rejected write showed the user raw server diagnostics.** The form rendered
+  `error.message` verbatim, so a sharing / RLS denial reached the dialog and the
+  toast as `FORBIDDEN: insufficient privileges to update showcase_private_note
+pi-TgoJ4_DM55Fqz` — untranslated, and leaking the object's machine name and the
+  record id to whoever hit it. Permission failures now render localized copy
+  (`form.noPermissionToSave`, added in all ten locales), with the server text kept
+  on the console for debugging; other failures still show the server's message,
+  which is the useful part, and fall back to `form.submitFailed` when there is
+  none — replacing the previously hardcoded English "An error occurred during
+  submission".
+
+  **The detail header offered "Edit" on records the user may only read.** Object
+  permissions can't express "this one record is read-only" — a read-only sharing
+  grant sits inside an object the user may otherwise edit — so the header showed
+  the primary Edit CTA, opened the form, and let the user retype a field before
+  the server rejected the save. `DetailView` now gates Edit / Delete on the
+  object-level check AND on the explain engine's record-grained verdict
+  (`POST /api/v1/security/explain` with a `recordId`, ADR-0090 D6 / ADR-0095 C2 —
+  the same pipeline the enforcement middleware runs, so button and server cannot
+  disagree). Explaining oneself needs no special permission. The probe is one
+  cached request per record, skipped entirely when the object-level check already
+  says no, and **fails open** on every uncertainty — an unanswered hint must never
+  be the reason a permitted user cannot act; the server stays the authority
+  (ADR-0057 D10).
+
+  **A long option rendered straight past the combobox border.** `Combobox`'s
+  trigger pinned itself to the component's `w-[200px]` default while the fields
+  around it ran the full form column, and the selected label was a bare text child
+  of a flex button — flex items need `truncate` AND `min-w-0` to clip, and it had
+  neither. So "成员 (showcase_project_membership)" in the object picker overflowed
+  the control and collided with the field beside it. The label now truncates, the
+  trigger can shrink, the dropdown matches the trigger's width instead of a
+  hardcoded 200px (a widened combobox used to clip its own options), and the two
+  sharing-rule pickers ask for `w-full` so they line up with every other input.
+
+  Hardens `evaluatePermission` while there: a role config carrying only
+  `fieldPermissions` (no `actions`) made `check()` throw a TypeError that
+  propagated out of the render. A permission check must not be able to crash a
+  view.
+
+  Browser-verified against the framework showcase Console in Chinese: object /
+  criteria / recipient copy is fully localized, the recipient dropdown lists real
+  users, business units and positions, a saved rule reopens with its recipient and
+  criteria intact, editing the filter no longer submits, and a rule created
+  end-to-end stores a real record id rather than free text. The criteria authored
+  in the builder is honored by the evaluator: `{"pinned":true}` on an owner-private
+  object granted the recipient exactly the matching records and nothing else.
+
+- Updated dependencies [1767124]
+- Updated dependencies [8ecf5a6]
+- Updated dependencies [dfd3705]
+- Updated dependencies [6dee2cb]
+- Updated dependencies [c7cff19]
+- Updated dependencies [cd09a7b]
+- Updated dependencies [f1abf0e]
+- Updated dependencies [f05b84e]
+- Updated dependencies [662bdf9]
+- Updated dependencies [059a052]
+- Updated dependencies [53642d4]
+- Updated dependencies [8aae006]
+- Updated dependencies [d147a13]
+  - @object-ui/types@17.0.0
+
 ## 16.1.0
 
 ### Minor Changes
@@ -59,7 +1936,7 @@
 
   Together with the `^15.1.1` alignment (#2662), a renderer CEL predicate now
   reaches the identical verdict as the server — including the framework's
-  `dateField == today()` equality fix (objectstack-ai/framework#3205) once it
+  `dateField == today()` equality fix (objectstack-ai/objectstack#3205) once it
   lands in a published 15.x. The broader home-grown-vs-canonical divergence
   motivation is #2661.
 
@@ -148,7 +2025,7 @@
     and removes both bounds together. A new `drillUrlFilters` module owns the
     write/read serialization so both sides can't drift (round-trip tested).
 
-  Companion to the framework analytics change (objectstack-ai/framework#3256).
+  Companion to the framework analytics change (objectstack-ai/objectstack#3256).
 
 ### Patch Changes
 
@@ -163,7 +2040,7 @@
   (`visibleWhen`/`readonlyWhen`/`requiredWhen` via `fieldRules.ts`, which delegates
   to `@objectstack/formula`'s `ExpressionEngine`) now tracks the 15.x engine — and
   will pick up the framework's `dateField == today()` equality fix
-  (objectstack-ai/framework#3205) automatically at the next 15.x release via the
+  (objectstack-ai/objectstack#3205) automatically at the next 15.x release via the
   caret range. Renderer/action `visible`/`disabled` predicates are unaffected (they
   use the home-grown JS evaluator — tracked separately in #2661).
 
@@ -736,7 +2613,7 @@
   (plugin-charts) and `DatasetWidget` (plugin-dashboard) both use it, so
   multi-dimension charts render consistently as grouped/coloured bars.
 
-  Refs objectstack-ai/objectui#1759, objectstack-ai/framework#1890
+  Refs objectstack-ai/objectui#1759, objectstack-ai/objectstack#1890
 
 - 7c239fd: Add `ComponentRegistry.unregister(type, namespace?)` — the inverse of
   `register()`. Clears the namespaced key and the bare-name fallback (when it