@object-ui/core 17.3.0 → 17.6.0

package/dist/actions/actionKeys.d.ts

@@ -6,26 +6,46 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * What an action is allowed to carry — objectstack#4075 step 1.
+ * What an action is allowed to carry — objectstack#4075, all three steps.
  *
- * `ActionDef` ends with `[key: string]: any`, so it accepts any key of any type.
- * Concretely (objectui#2990): deleting `ActionDef.execute` produced ZERO compile
- * errors even though the field had just been removed, 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.
+ * `ActionDef` used to end with `[key: string]: any`, so it accepted any key of
+ * any type. Concretely (objectui#2990): deleting `ActionDef.execute` produced
+ * ZERO compile errors even though the field had just been removed, and stale
+ * metadata authoring `execute: 'markDone'` type-checked. 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
+ * could catch a retired key; the other was structurally incapable.
  *
- * That asymmetry is the issue. An open key set on a DECLARED METADATA CONTRACT
+ * That asymmetry was the issue. An open key set on a DECLARED METADATA CONTRACT
  * is what lets a typo (`targt`, `exectue`) and a tombstoned key (`execute`) both
  * sail through to a runner that then silently does nothing — the #2169 "Mark
  * Done does nothing" shape.
  *
- * This module is step 1 of the staged narrowing: it makes the key set VISIBLE
- * and warns on anything outside it, without changing a single type. Nothing
- * breaks, and an invisible failure becomes an audible one. Steps 2 and 3 —
- * promoting the legitimate keys to explicit optional fields, then removing the
- * index signature — are what finally let `tsc` catch typos and retired keys.
+ * This module was step 1 of the staged narrowing: make the key set VISIBLE and
+ * warn on anything outside it, without changing a single type. Step 2 promoted
+ * the legitimate keys to explicit optional fields; **step 3 removed the index
+ * signature**, so `tsc` now rejects a typo or a retired key outright.
+ *
+ * ── Why this module SURVIVES step 3 ──────────────────────────────────────────
+ * Step 1 wrote that the dev-mode warning "can retire" once the index signature
+ * came down. Step 3 measured that and kept it, because the two mechanisms cover
+ * DISJOINT populations rather than the same one twice:
+ *
+ *   - `tsc` sees action literals AUTHORED IN CODE. It rejects an unknown key at
+ *     the construction site, which is the strongest possible signal — but only
+ *     for actions that exist as TypeScript.
+ *   - the warning below sees actions that arrive as DATA. objectstack#3903
+ *     established that stored `sys_metadata` rows are rehydrated UNPARSED, so
+ *     authored metadata reaches `runner.execute()` as a plain object no
+ *     compiler ever looked at. That is the population `execute: 'markDone'`
+ *     actually lives in, and no type can reach it.
+ *
+ * Retiring the warning would therefore have re-opened the runtime half of the
+ * gap while closing the compile-time half — which is why `executeScript`'s
+ * rename-prescription branch also survives, for the same rows and the same
+ * reason. What DID retire with the index signature is the inverted pin in
+ * `actionKeys.pin.test.ts` that asserted the signature was still there; it now
+ * asserts the opposite, which was always its stated completion condition.
  *
  * The lists are pinned by `__tests__/actionKeys.pin.test.ts`, which re-derives
  * each one from its actual source. A hand-maintained list that drifts from the
@@ -66,17 +86,32 @@
  * deprecating them toward a spelling that does not exist would be worse than
  * leaving them declared.
  *
- * Step 3 remains: remove the index signature, at which point `tsc` catches both
- * typos and retired keys and the dev-mode warning below can retire with it.
+ * ── What step 3 found the first two steps had missed ─────────────────────────
+ * Deleting the index signature is the only thing that can name the keys still
+ * hiding behind it, and it named five, in two groups:
+ *
+ * `to` / `external` / `newTab` / `replace` — the `navigation` alias's own
+ * spelling. Step 1 had already ruled these legitimate and listed them below in
+ * {@link NAVIGATION_ALIAS_KEYS}, but step 2's scope was the SPEC-owned keys, so
+ * they were declared as data and never as fields; `executeNavigation` read them
+ * through the index signature. Promoted, and deliberately not `@deprecated` —
+ * step 2's acceptance ruled on exactly that point.
+ *
+ * `description` — objectui vocabulary from `@object-ui/types`' renderer view of
+ * an action, forwarded by all four action renderers (`check:action-forward-parity`
+ * requires it) and read by the param-collection dialog for its subtitle
+ * (objectui#4192). Authorable, forwarded, read — and undeclared. These were the
+ * only two `TS2353`s the deletion produced across the whole workspace.
  */
 /**
  * Every property `ActionDef` declares, in declaration order.
  *
- * Kept as data because TypeScript types do not survive to runtime — and
- * `keyof ActionDef` cannot substitute for this list: the index signature widens
- * it to `string | number`, which is precisely the problem being worked around.
+ * Kept as data because TypeScript types do not survive to runtime — `keyof
+ * ActionDef` is erased along with the interface, so it cannot hand a runtime
+ * classifier a list of anything. `actionKeys.pin.test.ts` re-derives this one
+ * from the interface's AST, which is what keeps the data true.
  */
-export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl", "locations", "visible", "requiredPermissions", "icon", "variant", "order", "component", "objectName", "ai", "aria", "bodyExtra", "bodyShape", "mode", "recordIdField", "recordIdParam", "requiresFeature", "shortcut", "bulkEnabled"];
+export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "description", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "to", "external", "newTab", "replace", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl", "locations", "visible", "requiredPermissions", "icon", "variant", "order", "component", "objectName", "ai", "aria", "bodyExtra", "bodyShape", "mode", "recordIdField", "recordIdParam", "requiresFeature", "shortcut", "bulkEnabled"];
 /**
  * Every property `@objectstack/spec`'s `ActionSchema` declares.
  *
@@ -91,7 +126,7 @@ export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "l
  * test and wrong in shipped code — `@object-ui/types` made the same call for
  * `ActionComponent`. The pin test does the walk and fails the day this drifts.
  */
-export declare const SPEC_ACTION_KEYS: readonly ["_lock", "_lockDocsUrl", "_lockReason", "_lockSource", "_packageId", "_packageVersion", "_provenance", "ai", "aria", "body", "bodyExtra", "bodyShape", "bulkEnabled", "component", "confirmText", "disabled", "errorMessage", "execute", "icon", "label", "locations", "method", "mode", "name", "newTabUrl", "objectName", "openIn", "opensInNewTab", "order", "params", "recordIdField", "recordIdParam", "refreshAfter", "requiredPermissions", "requiresFeature", "resultDialog", "shortcut", "successMessage", "target", "type", "undoable", "variant", "visible"];
+export declare const SPEC_ACTION_KEYS: readonly ["_lock", "_lockDocsUrl", "_lockReason", "_lockSource", "_packageId", "_packageVersion", "_provenance", "ai", "aria", "body", "bodyExtra", "bodyShape", "bulkEnabled", "component", "confirmText", "description", "disabled", "errorMessage", "execute", "icon", "label", "locations", "method", "mode", "name", "newTabUrl", "objectName", "onSuccess", "openIn", "opensInNewTab", "order", "params", "recordIdField", "recordIdParam", "refreshAfter", "requiredPermissions", "requiresFeature", "resultDialog", "shortcut", "successMessage", "target", "type", "undoable", "variant", "visible"];
 /**
  * The `navigation` alias's own spelling of a target, read off the action itself
  * when no nested `navigate` object is present (`ActionRunner.executeNavigation`).
@@ -103,6 +138,54 @@ export declare const SPEC_ACTION_KEYS: readonly ["_lock", "_lockDocsUrl", "_lock
  * runner itself supports.
  */
 export declare const NAVIGATION_ALIAS_KEYS: readonly ["to", "external", "newTab", "replace"];
+/**
+ * Keys a HOST composes on the DISPATCH OBJECT at dispatch time — chrome the
+ * runtime reads once on its way to the dialog, that no author ever writes and
+ * no store ever holds.
+ *
+ * Distinct from every other list in this module, and the distinction is the
+ * whole point: each of the three lists above restates one AUTHORED surface —
+ * what `ActionDef` itself declares, what the spec's `ActionSchema` declares,
+ * and the `navigation` alias's objectui dialect — so a key joining one of them
+ * is a key an author may legally write. This list claims no such derivation and
+ * must not acquire one: a key here is the opposite, and writing it in metadata
+ * is still a compile error that must stay one. Maintainer ruling
+ * 2026-08-22 fixes both halves of that: ⛔ the key is NOT declared on
+ * `ActionDef` and ⛔ NOT added to {@link ACTION_DEF_KEYS}; it is declared at the
+ * seam, on `packages/app-shell/src/consoleActionDispatch.ts`'s
+ * `ConsoleActionDispatch`, and appears HERE only so the dev-mode warning below
+ * stops calling it unknown.
+ *
+ * Why the warning has to know: `classifyActionKeys` sees the object the runner
+ * was handed, which is the DISPATCH, not the stored metadata row. With the key
+ * absent from the inventory, `warnOnUnknownActionKeys` told the author that a
+ * key TWO files read is one "no reader recognizes", and prescribed promoting it
+ * to `ActionDef` — the one shape the ruling forbids for it. A diagnostic that
+ * fires on the product's own privileged path is how a console gets muted.
+ *
+ * {@link HOST_STASHED_PARAM_KEYS} below is the same category one level down —
+ * host-composed keys inside `params` rather than on the action itself — and
+ * cites `DeclaredActionsBar` by name for the same reason this does. Two lists
+ * because the two warnings ask different questions of different objects, not
+ * because the categories differ.
+ *
+ * `overrideNotice` — the privileged-override safety copy (objectui#5178),
+ * naming the approvers about to be bypassed.
+ * - producer: `packages/app-shell/src/views/DeclaredActionsBar.tsx`, on the
+ *   `can_act:false && can_override:true` branch.
+ * - readers: `packages/app-shell/src/hooks/useConsoleActionRuntime.tsx` and
+ *   `packages/app-shell/src/views/RecordDetailView.tsx`, the console's two
+ *   param-collection handlers, which render it ahead of the declared
+ *   description in the dialog's subtitle.
+ *
+ * Anything added here must satisfy all three of: composed by a host in code,
+ * never read back out of stored metadata, and read by the runtime. A key an
+ * AUTHOR is meant to write belongs on `ActionDef` — or, when the spec owns it,
+ * in `@objectstack/spec` first — and not in this list. `actionKeys.pin.test.ts`
+ * pins the contents exactly, so growing the set is a deliberate, reviewed edit
+ * rather than a quiet one.
+ */
+export declare const HOST_DISPATCH_ACTION_KEYS: readonly ["overrideNotice"];
 /**
  * Keys the spec has TOMBSTONED: still present in `ActionSchema` so the parser can
  * reject them BY NAME with a rename prescription, rather than fail with a bare
@@ -111,11 +194,27 @@ export declare const NAVIGATION_ALIAS_KEYS: readonly ["to", "external", "newTab"
  * Warned about separately from unknown keys, and more loudly: an unknown key is
  * probably a typo, while a retired key is metadata that used to work. That
  * distinction is why `executeScript` carries a runtime branch returning the
- * rename prescription — a branch that exists solely to compensate for the index
- * signature, and that can retire with it in step 3.
+ * rename prescription.
+ *
+ * Step 1 expected that branch to retire with the index signature. It does not,
+ * and the reason is the one in this module's header: `tsc` closed the
+ * code-authored half of the gap, while `execute: 'markDone'` lives in stored
+ * rows that reach the runner UNPARSED (objectstack#3903). The branch reads the
+ * key off an untyped view of the action precisely so that `ActionDef` can go on
+ * NOT declaring it — declaring it to make the read compile would re-legitimize
+ * a tombstone the spec keeps only in order to reject it by name.
  */
 export declare const RETIRED_ACTION_KEYS: Readonly<Record<string, string>>;
-/** Every key an action may legitimately carry today. */
+/**
+ * Every key an action may legitimately carry today — authored or host-composed.
+ *
+ * Four inputs, three of them mirrors of an authored surface and the fourth
+ * ({@link HOST_DISPATCH_ACTION_KEYS}) the host-composed dispatch chrome. The
+ * union is what `classifyActionKeys` consults, and it is deliberately wider
+ * than the authored surface: the runner classifies the object it was HANDED,
+ * and a host hands it a dispatch. Membership here grants nothing to an author —
+ * `ActionDef` is what decides that, and it is closed.
+ */
 export declare const KNOWN_ACTION_KEYS: ReadonlySet<string>;
 /** Split an action's own keys into the two things worth saying out loud. */
 export declare function classifyActionKeys(action: object | null | undefined): {
@@ -128,8 +227,45 @@ export declare function resetActionKeyWarnings(): void;
  * Dev-mode only: name the keys an action carries that no reader will ever look
  * at. Non-breaking by construction — it changes no types and rejects nothing.
  *
- * Silently binding no handler is the #2169 "Mark Done does nothing" shape, and
- * the compiler cannot help while the index signature stands. Until it comes
- * down, this is the audible half.
+ * Silently binding no handler is the #2169 "Mark Done does nothing" shape. The
+ * compiler now catches it in action literals AUTHORED IN CODE — objectstack#4075
+ * step 3 closed `ActionDef` — but not in the actions that arrive as DATA, which
+ * reach the runner unparsed and which no compiler ever looked at. This is the
+ * audible half for that population; see this module's header.
  */
 export declare function warnOnUnknownActionKeys(action: object | null | undefined, where?: string): void;
+/**
+ * Does this action carry the DEPRECATED object-form `params` — a static request
+ * payload written under the key that means "parameter definitions"?
+ *
+ * The discriminator is `Array.isArray` and the type guard is `api`, mirroring
+ * `@objectstack/spec`'s `inline-action-api-params-to-body-extra` conversion
+ * (ADR-0087 D2) key for key. Contract parity with the producer is the point: the
+ * conversion rewrites exactly this shape to `bodyExtra` at load, so the runner
+ * must recognize exactly the same shape as "the thing that got rewritten".
+ *
+ * The `api` guard is also what keeps the deprecation out of objectstack#6828's
+ * territory — object-form `params` on a `type: 'url'` action is a THIRD meaning
+ * (`interpolateTarget`'s `${param.X}` scope, `executeUrl`'s `params.newTab`) and
+ * `bodyExtra` is NOT its replacement. Do not widen this guard without that
+ * ruling.
+ */
+export declare function hasDeprecatedObjectParams(action: object | null | undefined): boolean;
+/**
+ * Dev-mode only: name the object-form `params` that `@objectstack/spec` 17 already
+ * refuses at the authoring door, and prescribe `bodyExtra`.
+ *
+ * This is the audible half of the compat window the maintainer's 2026-08-06
+ * ruling on objectstack#5777 ordered (direction A — a separate key, no same-name
+ * union): the runner keeps READING a non-array `params` as the static payload for
+ * one version window, says so, and the arm is deleted at 18. The loud half lives
+ * at the producer, where it belongs — spec's `params` field refuses the object
+ * form outright with a message naming `bodyExtra`, and the ADR-0087 conversion
+ * rewrites sources that still carry it. So a warning is the correct severity
+ * HERE: by the time metadata reaches this runner the producer has already had its
+ * say, and what is left to catch is a host composing an ActionDef in code.
+ *
+ * Dev-only and warn-once, matching {@link warnOnUnknownActionKeys} — a warning
+ * that floods a production console is a warning that gets muted.
+ */
+export declare function warnOnDeprecatedObjectParams(action: object | null | undefined, where?: string): void;

package/dist/actions/actionKeys.js

@@ -6,26 +6,46 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * What an action is allowed to carry — objectstack#4075 step 1.
+ * What an action is allowed to carry — objectstack#4075, all three steps.
  *
- * `ActionDef` ends with `[key: string]: any`, so it accepts any key of any type.
- * Concretely (objectui#2990): deleting `ActionDef.execute` produced ZERO compile
- * errors even though the field had just been removed, 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.
+ * `ActionDef` used to end with `[key: string]: any`, so it accepted any key of
+ * any type. Concretely (objectui#2990): deleting `ActionDef.execute` produced
+ * ZERO compile errors even though the field had just been removed, and stale
+ * metadata authoring `execute: 'markDone'` type-checked. 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
+ * could catch a retired key; the other was structurally incapable.
  *
- * That asymmetry is the issue. An open key set on a DECLARED METADATA CONTRACT
+ * That asymmetry was the issue. An open key set on a DECLARED METADATA CONTRACT
  * is what lets a typo (`targt`, `exectue`) and a tombstoned key (`execute`) both
  * sail through to a runner that then silently does nothing — the #2169 "Mark
  * Done does nothing" shape.
  *
- * This module is step 1 of the staged narrowing: it makes the key set VISIBLE
- * and warns on anything outside it, without changing a single type. Nothing
- * breaks, and an invisible failure becomes an audible one. Steps 2 and 3 —
- * promoting the legitimate keys to explicit optional fields, then removing the
- * index signature — are what finally let `tsc` catch typos and retired keys.
+ * This module was step 1 of the staged narrowing: make the key set VISIBLE and
+ * warn on anything outside it, without changing a single type. Step 2 promoted
+ * the legitimate keys to explicit optional fields; **step 3 removed the index
+ * signature**, so `tsc` now rejects a typo or a retired key outright.
+ *
+ * ── Why this module SURVIVES step 3 ──────────────────────────────────────────
+ * Step 1 wrote that the dev-mode warning "can retire" once the index signature
+ * came down. Step 3 measured that and kept it, because the two mechanisms cover
+ * DISJOINT populations rather than the same one twice:
+ *
+ *   - `tsc` sees action literals AUTHORED IN CODE. It rejects an unknown key at
+ *     the construction site, which is the strongest possible signal — but only
+ *     for actions that exist as TypeScript.
+ *   - the warning below sees actions that arrive as DATA. objectstack#3903
+ *     established that stored `sys_metadata` rows are rehydrated UNPARSED, so
+ *     authored metadata reaches `runner.execute()` as a plain object no
+ *     compiler ever looked at. That is the population `execute: 'markDone'`
+ *     actually lives in, and no type can reach it.
+ *
+ * Retiring the warning would therefore have re-opened the runtime half of the
+ * gap while closing the compile-time half — which is why `executeScript`'s
+ * rename-prescription branch also survives, for the same rows and the same
+ * reason. What DID retire with the index signature is the inverted pin in
+ * `actionKeys.pin.test.ts` that asserted the signature was still there; it now
+ * asserts the opposite, which was always its stated completion condition.
  *
  * The lists are pinned by `__tests__/actionKeys.pin.test.ts`, which re-derives
  * each one from its actual source. A hand-maintained list that drifts from the
@@ -66,21 +86,40 @@
  * deprecating them toward a spelling that does not exist would be worse than
  * leaving them declared.
  *
- * Step 3 remains: remove the index signature, at which point `tsc` catches both
- * typos and retired keys and the dev-mode warning below can retire with it.
+ * ── What step 3 found the first two steps had missed ─────────────────────────
+ * Deleting the index signature is the only thing that can name the keys still
+ * hiding behind it, and it named five, in two groups:
+ *
+ * `to` / `external` / `newTab` / `replace` — the `navigation` alias's own
+ * spelling. Step 1 had already ruled these legitimate and listed them below in
+ * {@link NAVIGATION_ALIAS_KEYS}, but step 2's scope was the SPEC-owned keys, so
+ * they were declared as data and never as fields; `executeNavigation` read them
+ * through the index signature. Promoted, and deliberately not `@deprecated` —
+ * step 2's acceptance ruled on exactly that point.
+ *
+ * `description` — objectui vocabulary from `@object-ui/types`' renderer view of
+ * an action, forwarded by all four action renderers (`check:action-forward-parity`
+ * requires it) and read by the param-collection dialog for its subtitle
+ * (objectui#4192). Authorable, forwarded, read — and undeclared. These were the
+ * only two `TS2353`s the deletion produced across the whole workspace.
  */
 /**
  * Every property `ActionDef` declares, in declaration order.
  *
- * Kept as data because TypeScript types do not survive to runtime — and
- * `keyof ActionDef` cannot substitute for this list: the index signature widens
- * it to `string | number`, which is precisely the problem being worked around.
+ * Kept as data because TypeScript types do not survive to runtime — `keyof
+ * ActionDef` is erased along with the interface, so it cannot hand a runtime
+ * classifier a list of anything. `actionKeys.pin.test.ts` re-derives this one
+ * from the interface's AST, which is what keeps the data true.
  */
 export const ACTION_DEF_KEYS = [
     'type',
     'actionType',
     'name',
     'label',
+    // Promoted by step 3 — objectui vocabulary (`@object-ui/types`' renderer view
+    // of an action), forwarded by all four action renderers and read by the
+    // param-collection dialog, but never declared on `ActionDef`.
+    'description',
     'confirmText',
     'confirm',
     'condition',
@@ -89,6 +128,14 @@ export const ACTION_DEF_KEYS = [
     'endpoint',
     'method',
     'navigate',
+    // The `navigation` alias's own spelling, promoted to real fields by step 3.
+    // Listed a second time in `NAVIGATION_ALIAS_KEYS` below, which keeps the
+    // separate fact that these four are objectui dialect with a spec-adoption
+    // tripwire; this list is only "what the interface declares".
+    'to',
+    'external',
+    'newTab',
+    'replace',
     'onClick',
     'reload',
     'close',
@@ -169,6 +216,15 @@ export const SPEC_ACTION_KEYS = [
     'bulkEnabled',
     'component',
     'confirmText',
+    // Added to `ActionSchema` in @objectstack/spec 17.0.0-rc.6. Listed here purely
+    // because this array's contract is "every property the spec's `ActionSchema`
+    // declares" — restating the spec, not adopting a feature. `ActionDef` does NOT
+    // declare `description` and is not changed: whether the runner or any renderer
+    // should READ it is a separate question, and `actionKeys.pin.test.ts`'s
+    // `ActionDef` half stays green without it. What this entry buys is that an
+    // action carrying a `description` is no longer reported as having an unknown
+    // key, which is the only thing the inventory is consulted for.
+    'description',
     'disabled',
     'errorMessage',
     'execute',
@@ -180,6 +236,14 @@ export const SPEC_ACTION_KEYS = [
     'name',
     'newTabUrl',
     'objectName',
+    // Declared by `ActionSchema` as of @objectstack/spec 17.1.0 (objectui#5328).
+    // Listing it here is a DIAGNOSTIC statement only — `KNOWN_ACTION_KEYS` feeds
+    // `warnOnUnknownActionKeys`, so without this row an author writing the key the
+    // spec now accepts would be warned it is unknown. It says nothing about the
+    // key being forwarded: the four declared action surfaces still drop it before
+    // the runner, tracked as KNOWN_GAPS in check-action-forward-parity.mjs and
+    // filed as objectui#5493.
+    'onSuccess',
     'openIn',
     'opensInNewTab',
     'order',
@@ -209,6 +273,54 @@ export const SPEC_ACTION_KEYS = [
  * runner itself supports.
  */
 export const NAVIGATION_ALIAS_KEYS = ['to', 'external', 'newTab', 'replace'];
+/**
+ * Keys a HOST composes on the DISPATCH OBJECT at dispatch time — chrome the
+ * runtime reads once on its way to the dialog, that no author ever writes and
+ * no store ever holds.
+ *
+ * Distinct from every other list in this module, and the distinction is the
+ * whole point: each of the three lists above restates one AUTHORED surface —
+ * what `ActionDef` itself declares, what the spec's `ActionSchema` declares,
+ * and the `navigation` alias's objectui dialect — so a key joining one of them
+ * is a key an author may legally write. This list claims no such derivation and
+ * must not acquire one: a key here is the opposite, and writing it in metadata
+ * is still a compile error that must stay one. Maintainer ruling
+ * 2026-08-22 fixes both halves of that: ⛔ the key is NOT declared on
+ * `ActionDef` and ⛔ NOT added to {@link ACTION_DEF_KEYS}; it is declared at the
+ * seam, on `packages/app-shell/src/consoleActionDispatch.ts`'s
+ * `ConsoleActionDispatch`, and appears HERE only so the dev-mode warning below
+ * stops calling it unknown.
+ *
+ * Why the warning has to know: `classifyActionKeys` sees the object the runner
+ * was handed, which is the DISPATCH, not the stored metadata row. With the key
+ * absent from the inventory, `warnOnUnknownActionKeys` told the author that a
+ * key TWO files read is one "no reader recognizes", and prescribed promoting it
+ * to `ActionDef` — the one shape the ruling forbids for it. A diagnostic that
+ * fires on the product's own privileged path is how a console gets muted.
+ *
+ * {@link HOST_STASHED_PARAM_KEYS} below is the same category one level down —
+ * host-composed keys inside `params` rather than on the action itself — and
+ * cites `DeclaredActionsBar` by name for the same reason this does. Two lists
+ * because the two warnings ask different questions of different objects, not
+ * because the categories differ.
+ *
+ * `overrideNotice` — the privileged-override safety copy (objectui#5178),
+ * naming the approvers about to be bypassed.
+ * - producer: `packages/app-shell/src/views/DeclaredActionsBar.tsx`, on the
+ *   `can_act:false && can_override:true` branch.
+ * - readers: `packages/app-shell/src/hooks/useConsoleActionRuntime.tsx` and
+ *   `packages/app-shell/src/views/RecordDetailView.tsx`, the console's two
+ *   param-collection handlers, which render it ahead of the declared
+ *   description in the dialog's subtitle.
+ *
+ * Anything added here must satisfy all three of: composed by a host in code,
+ * never read back out of stored metadata, and read by the runtime. A key an
+ * AUTHOR is meant to write belongs on `ActionDef` — or, when the spec owns it,
+ * in `@objectstack/spec` first — and not in this list. `actionKeys.pin.test.ts`
+ * pins the contents exactly, so growing the set is a deliberate, reviewed edit
+ * rather than a quiet one.
+ */
+export const HOST_DISPATCH_ACTION_KEYS = ['overrideNotice'];
 /**
  * Keys the spec has TOMBSTONED: still present in `ActionSchema` so the parser can
  * reject them BY NAME with a rename prescription, rather than fail with a bare
@@ -217,19 +329,36 @@ export const NAVIGATION_ALIAS_KEYS = ['to', 'external', 'newTab', 'replace'];
  * Warned about separately from unknown keys, and more loudly: an unknown key is
  * probably a typo, while a retired key is metadata that used to work. That
  * distinction is why `executeScript` carries a runtime branch returning the
- * rename prescription — a branch that exists solely to compensate for the index
- * signature, and that can retire with it in step 3.
+ * rename prescription.
+ *
+ * Step 1 expected that branch to retire with the index signature. It does not,
+ * and the reason is the one in this module's header: `tsc` closed the
+ * code-authored half of the gap, while `execute: 'markDone'` lives in stored
+ * rows that reach the runner UNPARSED (objectstack#3903). The branch reads the
+ * key off an untyped view of the action precisely so that `ActionDef` can go on
+ * NOT declaring it — declaring it to make the read compile would re-legitimize
+ * a tombstone the spec keeps only in order to reject it by name.
  */
 export const RETIRED_ACTION_KEYS = {
     execute: '`execute` was removed in @objectstack/spec 17 (#3855) — rename the key to `target`. ' +
         'The value (a script name or expression) is unchanged. ' +
         'Run `os migrate meta --from 16` to rewrite it automatically.',
 };
-/** Every key an action may legitimately carry today. */
+/**
+ * Every key an action may legitimately carry today — authored or host-composed.
+ *
+ * Four inputs, three of them mirrors of an authored surface and the fourth
+ * ({@link HOST_DISPATCH_ACTION_KEYS}) the host-composed dispatch chrome. The
+ * union is what `classifyActionKeys` consults, and it is deliberately wider
+ * than the authored surface: the runner classifies the object it was HANDED,
+ * and a host hands it a dispatch. Membership here grants nothing to an author —
+ * `ActionDef` is what decides that, and it is closed.
+ */
 export const KNOWN_ACTION_KEYS = new Set([
     ...ACTION_DEF_KEYS,
     ...SPEC_ACTION_KEYS,
     ...NAVIGATION_ALIAS_KEYS,
+    ...HOST_DISPATCH_ACTION_KEYS,
 ].filter((key) => !(key in RETIRED_ACTION_KEYS)));
 /** Split an action's own keys into the two things worth saying out loud. */
 export function classifyActionKeys(action) {
@@ -264,9 +393,11 @@ const isDev = () => globalThis.process?.env?.NODE_ENV !==
  * Dev-mode only: name the keys an action carries that no reader will ever look
  * at. Non-breaking by construction — it changes no types and rejects nothing.
  *
- * Silently binding no handler is the #2169 "Mark Done does nothing" shape, and
- * the compiler cannot help while the index signature stands. Until it comes
- * down, this is the audible half.
+ * Silently binding no handler is the #2169 "Mark Done does nothing" shape. The
+ * compiler now catches it in action literals AUTHORED IN CODE — objectstack#4075
+ * step 3 closed `ActionDef` — but not in the actions that arrive as DATA, which
+ * reach the runner unparsed and which no compiler ever looked at. This is the
+ * audible half for that population; see this module's header.
  */
 export function warnOnUnknownActionKeys(action, where = 'ActionRunner') {
     if (!isDev())
@@ -289,6 +420,86 @@ export function warnOnUnknownActionKeys(action, where = 'ActionRunner') {
     console.warn(`[${where}] action "${String(name)}" carries ${unknown.length === 1 ? 'a key' : 'keys'} no reader ` +
         `recognizes: \`${unknown.join('`, `')}\`. Nothing will read ${unknown.length === 1 ? 'it' : 'them'} — ` +
         'check for a typo, or promote the key to an explicit field on `ActionDef` ' +
-        '(packages/core/src/actions/actionKeys.ts). Warned rather than rejected because `ActionDef` ' +
-        'still carries `[key: string]: any`, so the compiler cannot see this (objectstack#4075).');
+        '(packages/core/src/actions/ActionRunner.ts), adding it to `ACTION_DEF_KEYS` ' +
+        '(packages/core/src/actions/actionKeys.ts) in the SAME commit — the pin test derives one ' +
+        'from the other, so either edit alone goes red. Warned rather than rejected because `tsc` ' +
+        'only sees actions authored in code: this one may have arrived as DATA, and stored ' +
+        '`sys_metadata` rows reach the runner unparsed (objectstack#3903).');
+}
+/**
+ * Keys a HOST stashes into an action's `params` for the runner's own plumbing,
+ * rather than an author writing them there as a request payload.
+ *
+ * {@link warnOnDeprecatedObjectParams} has to tell "the author put the payload in
+ * `params`" (the shape objectstack#5777 retires) apart from "a host stashed row
+ * context there" (a shape the runner itself asks for, and that is not going
+ * away). `DeclaredActionsBar` dispatches `params: { _rowRecord: record }`,
+ * `RelatedRecordActionsBridge` does the same, and `ObjectGrid` adds
+ * `_selectedIds`; the api handler lifts `recordId` out of the field values
+ * before it updates. Warning on those would fire on nearly every declared-action
+ * click and prescribe `bodyExtra`, which is the wrong home for all of them.
+ *
+ * The `_` prefix is the existing convention for the stash — `recordId` is its one
+ * unprefixed member, so it is listed rather than inferred.
+ */
+const HOST_STASHED_PARAM_KEYS = new Set(['recordId']);
+const isAuthoredParamKey = (key) => !key.startsWith('_') && !HOST_STASHED_PARAM_KEYS.has(key);
+/**
+ * Does this action carry the DEPRECATED object-form `params` — a static request
+ * payload written under the key that means "parameter definitions"?
+ *
+ * The discriminator is `Array.isArray` and the type guard is `api`, mirroring
+ * `@objectstack/spec`'s `inline-action-api-params-to-body-extra` conversion
+ * (ADR-0087 D2) key for key. Contract parity with the producer is the point: the
+ * conversion rewrites exactly this shape to `bodyExtra` at load, so the runner
+ * must recognize exactly the same shape as "the thing that got rewritten".
+ *
+ * The `api` guard is also what keeps the deprecation out of objectstack#6828's
+ * territory — object-form `params` on a `type: 'url'` action is a THIRD meaning
+ * (`interpolateTarget`'s `${param.X}` scope, `executeUrl`'s `params.newTab`) and
+ * `bodyExtra` is NOT its replacement. Do not widen this guard without that
+ * ruling.
+ */
+export function hasDeprecatedObjectParams(action) {
+    if (!action || typeof action !== 'object')
+        return false;
+    const { type, actionType, params } = action;
+    if ((type ?? actionType) !== 'api')
+        return false;
+    if (!params || typeof params !== 'object' || Array.isArray(params))
+        return false;
+    return Object.keys(params).some(isAuthoredParamKey);
+}
+/**
+ * Dev-mode only: name the object-form `params` that `@objectstack/spec` 17 already
+ * refuses at the authoring door, and prescribe `bodyExtra`.
+ *
+ * This is the audible half of the compat window the maintainer's 2026-08-06
+ * ruling on objectstack#5777 ordered (direction A — a separate key, no same-name
+ * union): the runner keeps READING a non-array `params` as the static payload for
+ * one version window, says so, and the arm is deleted at 18. The loud half lives
+ * at the producer, where it belongs — spec's `params` field refuses the object
+ * form outright with a message naming `bodyExtra`, and the ADR-0087 conversion
+ * rewrites sources that still carry it. So a warning is the correct severity
+ * HERE: by the time metadata reaches this runner the producer has already had its
+ * say, and what is left to catch is a host composing an ActionDef in code.
+ *
+ * Dev-only and warn-once, matching {@link warnOnUnknownActionKeys} — a warning
+ * that floods a production console is a warning that gets muted.
+ */
+export function warnOnDeprecatedObjectParams(action, where = 'ActionRunner') {
+    if (!isDev())
+        return;
+    if (!hasDeprecatedObjectParams(action))
+        return;
+    const name = action?.name ?? '(unnamed)';
+    const memo = `deprecated-object-params:${String(name)}`;
+    if (warned.has(memo))
+        return;
+    warned.add(memo);
+    console.warn(`[${where}] action "${String(name)}" carries a static request payload in \`params\`. ` +
+        '`params` is the parameter DEFINITION array (fields collected from the user before the ' +
+        'action runs), never a payload map — put the payload in `bodyExtra` instead ' +
+        '(objectstack#5777). Still read as the payload for one version window; the arm is ' +
+        'removed at 18. `bodyExtra` is merged LAST, so it overrides anything left here.');
 }

package/dist/actions/actionResponse.js

@@ -47,7 +47,7 @@
  * - **transport-level `success: false`** — the outer envelope reporting a
  *   failure directly.
  */
-import { actionErrorDetail } from './actionErrorDetail';
+import { actionErrorDetail } from './actionErrorDetail.js';
 /**
  * The handler's own return value — one level deeper than the action envelope.
  *

package/dist/actions/index.d.ts

@@ -14,3 +14,4 @@ export * from './bulkFastPath.js';
 export * from './actionErrorDetail.js';
 export * from './actionResponse.js';
 export * from './serverActionHandler.js';
+export * from './recordIdParam.js';

package/dist/actions/index.js

@@ -14,3 +14,4 @@ export * from './bulkFastPath.js';
 export * from './actionErrorDetail.js';
 export * from './actionResponse.js';
 export * from './serverActionHandler.js';
+export * from './recordIdParam.js';