@object-ui/core 17.5.0 → 17.6.0

package/README.md

@@ -4,7 +4,8 @@ Core logic, types, and validation for Object UI. Zero React dependencies.
 
 ## Features
 
-- 🎯 **Type Definitions** - Complete TypeScript schemas for all components
+- 🎯 **Type Definitions** - Re-exported runtime types; the component schema
+  vocabulary itself is `@object-ui/types`
 - 🔍 **Component Registry** - Framework-agnostic component registration system
 - 📊 **Data Scope** - Data scope management and expression evaluation
 - ✅ **Validation** - Zod-based schema validation
@@ -20,15 +21,20 @@ npm install @object-ui/core
 
 ### Type Definitions
 
+The component schema vocabulary lives in `@object-ui/types`. Core depends on
+that package and does not re-export it, so import the types from there. The
+page node type is `PageNodeSchema` — the SDUI node, as distinct from the
+authored page document.
+
 ```typescript
-import type { 
-  PageSchema, 
-  FormSchema, 
+import type {
+  PageNodeSchema,
+  FormSchema,
   InputSchema,
-  BaseSchema 
-} from '@object-ui/core'
+  BaseSchema
+} from '@object-ui/types'
 
-const mySchema: PageSchema = {
+const mySchema: PageNodeSchema = {
   type: 'page',
   title: 'My Page',
   body: []
@@ -40,22 +46,30 @@ const mySchema: PageSchema = {
 ```typescript
 import { ComponentRegistry } from '@object-ui/core'
 
-const registry = new ComponentRegistry()
-registry.register('button', buttonMetadata)
-const metadata = registry.get('button')
+ComponentRegistry.register('button', buttonMetadata)
+const metadata = ComponentRegistry.get('button')
 ```
 
+`ComponentRegistry` is a process-level singleton exported by `@object-ui/core`;
+`SchemaRenderer` resolves every `type` against it, so a component registered
+here is renderable from schema anywhere in the app.
+
 ### Data Scope
 
+`DataScopeManager` owns the named scopes a component tree reads from, and
+`evaluateExpression` evaluates a `${...}` expression against a context. They
+are separate exports: a scope holds data, it does not evaluate.
+
 ```typescript
-import { DataScope } from '@object-ui/core'
+import { DataScopeManager, evaluateExpression } from '@object-ui/core'
 
-const scope = new DataScope({ 
-  user: { name: 'John', role: 'admin' } 
-})
+const manager = new DataScopeManager()
+manager.registerScope('user', { data: { name: 'John', role: 'admin' } })
 
-const userName = scope.get('user.name') // 'John'
-const isAdmin = scope.evaluate('${user.role === "admin"}') // true
+const userName = manager.getScope('user')?.data.name // 'John'
+const isAdmin = evaluateExpression('${user.role === "admin"}', {
+  user: { name: 'John', role: 'admin' },
+}) // true
 ```
 
 ### Server Action Dispatch (`createServerActionHandler`)
@@ -87,16 +101,16 @@ action identity (ADR-0110), the record-id resolution dance (`_rowRecord`,
 guard, and the `/actions` response-envelope rule (`interpretActionResponse` /
 `readActionPayload`, also exported).
 
-### System Views (`defineView`)
+### System Views (`defineSystemView`)
 
 Schemas authored in source code are part of the product contract and must
-not be mutated at runtime. Wrap them with `defineView()` to deep-freeze the
-graph and tag it as a *System View*.
+not be mutated at runtime. Wrap them with `defineSystemView()` to deep-freeze
+the graph and tag it as a *System View*.
 
 ```typescript
-import { defineView, cloneAsOverride, isSystemView } from '@object-ui/core'
+import { defineSystemView, cloneAsOverride, isSystemView } from '@object-ui/core'
 
-export const userListView = defineView({
+export const userListView = defineSystemView({
   type: 'list',
   data: { object: 'User' },
   columns: [{ name: 'email' }],
@@ -115,7 +129,7 @@ isSystemView(draft)                          // false — clone is no longer Sys
 
 | Tier        | Source                | Mutable? | API                         |
 | ----------- | --------------------- | -------- | --------------------------- |
-| System View | code (`import` / `as const`) | ❌ frozen | `defineView()`              |
+| System View | code (`import` / `as const`) | ❌ frozen | `defineSystemView()`        |
 | Tenant View | backend / DB          | ⚠️ admin only | `cloneAsOverride()` + persist |
 | User View   | localStorage / API    | ✅ user-editable | `cloneAsOverride()` + persist |
 

package/dist/actions/ActionEngine.d.ts

@@ -14,7 +14,7 @@
  * Replaces callback-based patterns with a schema-driven pipeline:
  *   ActionSchema[] → ActionEngine → ActionRunner → ActionResult
  */
-import { ActionRunner, type ActionDef, type ActionContext, type ActionResult } from './ActionRunner';
+import { ActionRunner, type ActionDef, type ActionContext, type ActionResult } from './ActionRunner.js';
 /**
  * Action location types — re-exported from `@objectstack/spec/ui` so the
  * platform has one source of truth (`ACTION_LOCATIONS`). Do NOT redeclare

package/dist/actions/ActionEngine.js

@@ -14,7 +14,7 @@
  * Replaces callback-based patterns with a schema-driven pipeline:
  *   ActionSchema[] → ActionEngine → ActionRunner → ActionResult
  */
-import { ActionRunner } from './ActionRunner';
+import { ActionRunner } from './ActionRunner.js';
 import { toPredicateInput } from '../evaluator/predicateInput.js';
 import { hasDeclaredPredicate } from '../evaluator/declaredPredicate.js';
 export { ACTION_LOCATIONS } from '@object-ui/types';
@@ -38,7 +38,6 @@ function warnHiddenPredicate(name, raw, err) {
         return;
     _warnedPredicates.add(key);
     const msg = err instanceof Error ? err.message : String(err);
-    // eslint-disable-next-line no-console
     console.warn(`[ActionEngine] action "${String(name)}" hidden: its \`visible\` predicate threw — ${msg}. ` +
         `Predicate: ${src}. Action predicates evaluate against { record, recordId, objectName, user, os.user, … }; ` +
         `use \`record.<field>\` (not a bare field).`);

package/dist/actions/ActionRunner.d.ts

@@ -21,8 +21,8 @@
  */
 import type { UIActionSchema } from '@object-ui/types';
 import type { Action as SpecActionInput } from '@objectstack/spec/ui';
-import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
-import { type UndoableOperation } from './UndoManager';
+import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator.js';
+import { type UndoableOperation } from './UndoManager.js';
 export interface ActionResult {
     success: boolean;
     data?: any;
@@ -134,15 +134,22 @@ export interface ActionDef {
      * it — the two TS2353s the deletion produced repo-wide were both this key.
      */
     description?: UIActionSchema['description'];
-    /** Confirmation text — shows a confirm dialog before executing */
+    /**
+     * Confirmation text — shows a confirm dialog before executing. The ONE
+     * confirm spelling: `@objectstack/spec`'s action surface and the
+     * TranslationBundle key (`{ns}.objects.{obj}._actions.{name}.confirmText`)
+     * both stand on it.
+     */
     confirmText?: string;
-    /** Structured confirmation (from crud.ts) */
-    confirm?: {
-        title?: string;
-        message?: string;
-        confirmText?: string;
-        cancelText?: string;
-    };
+    /**
+     * RETIRED (objectui#4314): the structured confirm object used to sit here
+     * and its `message` OUTRANKED `confirmText` — untranslated, since no bundle
+     * key exists for it. `?: never` so constructing an action with it is a tsc
+     * error rather than a silently-ignored key; the authorable twin
+     * (`@object-ui/types` `crud.ts`) carries the same tombstone.
+     * @deprecated Retired — author `confirmText` instead.
+     */
+    confirm?: never;
     /**
      * Condition predicate — the action executes only while it holds.
      *
@@ -382,6 +389,29 @@ export type ActionRunnerHandler = (action: ActionDef, context: ActionContext) =>
 /**
  * Confirmation handler — replaces window.confirm.
  * Consumers can provide an async implementation (e.g., Shadcn AlertDialog).
+ *
+ * `options` is LIVE, and its producer is not in this file — searching the
+ * runner alone will tell you otherwise. The only call site here passes one
+ * argument (the structured `confirm` arm that used to forward a bag was
+ * retired, objectui#4314), so a runner-scoped sweep reads this parameter as
+ * declared-but-never-produced and files it for removal. That has already
+ * happened once: objectui#5205, ruled KEEP on 2026-08-22.
+ *
+ * The producer bypasses the runner entirely. `handleDeleteView` in
+ * `packages/app-shell/src/views/ObjectView.tsx` — the admin "delete saved
+ * view" confirmation — invokes a `ConfirmationHandler` with all three fields
+ * populated and localized (`console.objectView.deleteViewTitle` / `.delete` /
+ * `.cancel`), and `app-shell`'s `ActionConfirmDialog.tsx` renders them in
+ * place of its generic `actionConfirm.*` fallbacks. Line numbers are left out
+ * on purpose: #5205's pointer had already drifted by the time it was executed.
+ *
+ * So re-measure across the repo, not this package: grep for two-argument
+ * calls of `ConfirmationHandler`-typed values (`confirmHandler(`, `onConfirm(`)
+ * in `app-shell` as well as here. Dropping `options` costs that dialog its
+ * title and both button labels, and narrows a published `.d.ts` against the
+ * natural `(message, options) => …` spelling — which TypeScript rejects
+ * against a one-parameter target unless the second parameter is written
+ * optional.
  */
 export type ConfirmationHandler = (message: string, options?: {
     title?: string;
@@ -604,6 +634,30 @@ export declare class ActionRunner {
      * Post-execution: emit toast notifications, handle chaining, callbacks.
      */
     private handlePostExecution;
+    /**
+     * Perform the `ActionSchema.onSuccess` hop for an action that just succeeded.
+     *
+     * **The router is the app's own.** `navigationHandler` is the seam every
+     * navigator in this file already goes through, and the console wires it to
+     * react-router's `navigate` — so `openIn: 'self'` is a real SPA route hop,
+     * in place, immune to popup blocking. No `window.location` / `window.open`
+     * mechanism is introduced here; the no-handler fallback is the same
+     * `result.redirect` hand-off `navigateTo` already uses.
+     *
+     * **No default is written here.** `openIn` is a materialised
+     * `.default('self')` in the spec, so parse output always carries a resolved
+     * member; this reads the ONE member that changes the branch and leaves the
+     * other implicit. A `?? 'self'` would be a second source of truth for a
+     * default the producer already resolved.
+     *
+     * **The two `openIn` spellings never cross.** This reads
+     * `onSuccess.openIn` (`'self' | 'newTab'`) and nothing else — never the
+     * top-level `type: 'url'` switch, which spells its new-tab member
+     * `'new-tab'`. Spec refuses each crossover spelling with a keyed error; a
+     * renderer that accepted either would be a second, looser contract than the
+     * one authors are validated against.
+     */
+    private navigateOnSuccess;
     /**
      * Execute script action — evaluates client-side expression via ExpressionEvaluator.
      * Supports ${} template expressions referencing data, record, user context.
@@ -787,3 +841,21 @@ export declare class ActionRunner {
  * Convenience function to execute a single action with a one-off runner.
  */
 export declare function executeAction(action: ActionDef, context?: ActionContext): Promise<ActionResult>;
+/** The `ActionSchema.onSuccess` block, as the pinned spec declares it. */
+export interface OnSuccessNavigation {
+    navigate: string;
+    /** `'self' | 'newTab'` — read as data, so an off-contract value cannot widen the branch. */
+    openIn?: unknown;
+}
+/**
+ * Is this `onSuccess` the SPEC's navigation block, or this runner's older
+ * chained-callback channel (`ActionDef | ActionDef[]`)?
+ *
+ * The test IS the spec's declaration: a non-array object carrying a STRING
+ * `navigate`. Nothing else can produce that shape — the spec object is strict
+ * with `navigate: z.string()` required, and on a callback `ActionDef`,
+ * `navigate` is the deprecated nested navigation ENVELOPE that
+ * `executeNavigation` reads `to`/`target`/`redirect` off, so a bare string
+ * there has never been runnable.
+ */
+export declare function readOnSuccessNavigation(value: unknown): OnSuccessNavigation | null;

package/dist/actions/ActionRunner.js

@@ -5,10 +5,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
-import { hasDeclaredPredicate } from '../evaluator/declaredPredicate';
-import { globalUndoManager } from './UndoManager';
-import { warnOnDeprecatedObjectParams, warnOnUnknownActionKeys } from './actionKeys';
+import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator.js';
+import { hasDeclaredPredicate } from '../evaluator/declaredPredicate.js';
+import { globalUndoManager } from './UndoManager.js';
+import { warnOnDeprecatedObjectParams, warnOnUnknownActionKeys } from './actionKeys.js';
+import { readActionPayload } from './actionResponse.js';
 /**
  * Bind the server-CEL-parity `os.user` identity alias into an action context
  * (#2358 trap 1). `@objectstack/spec` documents the canonical CEL identity
@@ -389,14 +390,13 @@ export class ActionRunner {
                     return { success: false, error: 'Action is disabled' };
                 }
             }
-            // Confirmation (structured or simple)
-            const confirmMessage = action.confirm?.message || action.confirmText;
-            if (confirmMessage) {
-                const confirmed = await this.confirmHandler(this.evaluator.evaluate(confirmMessage), action.confirm ? {
-                    title: action.confirm.title,
-                    confirmText: action.confirm.confirmText,
-                    cancelText: action.confirm.cancelText,
-                } : undefined);
+            // Confirmation. One spelling: `confirmText` — the only one the
+            // translation bundle can address (`…._actions.{name}.confirmText`). The
+            // structured `confirm.message` read that used to OUTRANK it is retired
+            // (objectui#4314): it had zero producers and no bundle key, so a dialog
+            // authored that way silently lost localization.
+            if (action.confirmText) {
+                const confirmed = await this.confirmHandler(this.evaluator.evaluate(action.confirmText));
                 if (!confirmed) {
                     return { success: false, error: 'Action cancelled by user' };
                 }
@@ -558,12 +558,10 @@ export class ActionRunner {
                 catch (err) {
                     // Acknowledgement failure is non-fatal; the underlying action already
                     // succeeded. Log so consumers can wire it through their error reporter.
-                    // eslint-disable-next-line no-console
                     console.warn('[ActionRunner] resultDialog handler rejected; treating as acknowledged', err);
                 }
             }
             else {
-                // eslint-disable-next-line no-console
                 console.warn('[ActionRunner] action.resultDialog set but no resultDialogHandler registered — the response value will not be shown to the user.', { action: action.name, data: result.data });
             }
         }
@@ -586,16 +584,94 @@ export class ActionRunner {
             if (chainResult.reload)
                 result.reload = true;
         }
-        // Execute onSuccess/onFailure callbacks
+        // ── ActionSchema.onSuccess — post-success navigation ────────────────────
+        //
+        // objectui#5221, the console half of objectstack#9566/#9474. The spec
+        // declares `onSuccess` as a CLOSED STRICT object
+        // `{ navigate: string, openIn: 'self' | 'newTab' }`, refine-scoped to
+        // `type: 'api'` and `type: 'script'` — the two types whose success event
+        // carries a server response for `${result.*}` to read.
+        //
+        // This runner's OWN `ActionDef.onSuccess` predates that key and means
+        // something else entirely: `ActionDef | ActionDef[]`, chained callbacks.
+        // The two are told apart by the spec's own declaration — a non-array object
+        // whose `navigate` is a STRING is the spec block and nothing else can be:
+        // `navigate` on a callback ActionDef is the deprecated nested navigation
+        // ENVELOPE (`executeNavigation` reads `navigate.to`), so a string there has
+        // never been runnable. This is a NARROWING to the declared contract, not a
+        // lenient fallback: a shape the spec refuses gets no new reading here.
+        //
+        // Before this branch existed, the ruled shape fell into the callback path,
+        // dispatched `{ navigate: '<string>' }` as an action, and failed inside
+        // `executeNavigation` with "No URL provided for navigation action" — the
+        // author got a red toast and no hop.
         if (result.success && action.onSuccess) {
-            const callbacks = Array.isArray(action.onSuccess) ? action.onSuccess : [action.onSuccess];
-            await this.executeChain(callbacks, 'sequential');
+            const navigation = readOnSuccessNavigation(action.onSuccess);
+            if (navigation) {
+                this.navigateOnSuccess(navigation, action, result);
+            }
+            else {
+                const callbacks = Array.isArray(action.onSuccess) ? action.onSuccess : [action.onSuccess];
+                await this.executeChain(callbacks, 'sequential');
+            }
         }
         if (!result.success && action.onFailure) {
             const callbacks = Array.isArray(action.onFailure) ? action.onFailure : [action.onFailure];
             await this.executeChain(callbacks, 'sequential');
         }
     }
+    /**
+     * Perform the `ActionSchema.onSuccess` hop for an action that just succeeded.
+     *
+     * **The router is the app's own.** `navigationHandler` is the seam every
+     * navigator in this file already goes through, and the console wires it to
+     * react-router's `navigate` — so `openIn: 'self'` is a real SPA route hop,
+     * in place, immune to popup blocking. No `window.location` / `window.open`
+     * mechanism is introduced here; the no-handler fallback is the same
+     * `result.redirect` hand-off `navigateTo` already uses.
+     *
+     * **No default is written here.** `openIn` is a materialised
+     * `.default('self')` in the spec, so parse output always carries a resolved
+     * member; this reads the ONE member that changes the branch and leaves the
+     * other implicit. A `?? 'self'` would be a second source of truth for a
+     * default the producer already resolved.
+     *
+     * **The two `openIn` spellings never cross.** This reads
+     * `onSuccess.openIn` (`'self' | 'newTab'`) and nothing else — never the
+     * top-level `type: 'url'` switch, which spells its new-tab member
+     * `'new-tab'`. Spec refuses each crossover spelling with a keyed error; a
+     * renderer that accepted either would be a second, looser contract than the
+     * one authors are validated against.
+     */
+    navigateOnSuccess(block, action, result) {
+        // `${result.*}` reads the HANDLER's return value, one level below the
+        // action envelope — the same level `readActionPayload` hands the
+        // `redirectUrl` convention. Reading `result.data` raw would see the
+        // `{ success, data }` envelope on pre-objectstack#3962 servers, which is
+        // the "one level too shallow" bug (#2904) in a new place.
+        const url = this.interpolateTarget(block.navigate, action, readActionPayload(result.data));
+        // `navigate` is author-supplied metadata and lands in a URL position, so
+        // it goes through the same scheme guard as every other navigator here.
+        if (!this.isValidUrl(url)) {
+            console.warn('[ActionRunner] onSuccess.navigate resolved to a URL this runner refuses to open '
+                + '(only http://, https:// and relative URLs are allowed) — no navigation performed.', { action: action.name, navigate: block.navigate, resolved: url });
+            return;
+        }
+        const newTab = block.openIn === 'newTab';
+        // Same external-URL convention `navigateTo` hands the handler; `newTab`
+        // stays the declared choice alone, never `?? isExternal`.
+        const external = url.startsWith('http://') || url.startsWith('https://');
+        if (this.navigationHandler) {
+            this.navigationHandler(url, { external, newTab });
+            return;
+        }
+        if (newTab) {
+            window.open(url, '_blank', 'noopener,noreferrer');
+        }
+        else {
+            result.redirect = url;
+        }
+    }
     /**
      * Execute script action — evaluates client-side expression via ExpressionEvaluator.
      * Supports ${} template expressions referencing data, record, user context.
@@ -1098,7 +1174,7 @@ export class ActionRunner {
      * param. Consumers can extend by stuffing extra keys under
      * `context.ctx = {...}` before calling `runner.execute()`.
      */
-    interpolateTarget(target, action) {
+    interpolateTarget(target, action, resultScope) {
         if (typeof target !== 'string' || target.indexOf('${') === -1)
             return target;
         // ── The `${param.X}` scope is an INTERNAL runtime value bag, not an
@@ -1135,10 +1211,21 @@ export class ActionRunner {
         const params = (action.params && typeof action.params === 'object' && !Array.isArray(action.params))
             ? action.params
             : {};
-        const ctx = this.buildInterpolationContext();
-        return target.replace(/\$\{(param|ctx)\.([\w.]+)\}/g, (_match, scope, path) => {
-            const root = scope === 'param' ? params : ctx;
-            const value = readPath(root, path);
+        // The scope MAP defines the vocabulary — the pattern is built from its
+        // keys, so a scope that is not in play is not a scope this call recognizes.
+        //
+        // `result` (the handler's own return value) is passed by exactly one caller:
+        // the `ActionSchema.onSuccess` post-success hop, where a response exists.
+        // Every other caller — `executeUrl`, `executeAPI` — interpolates a target
+        // BEFORE the request, so there is no result to read; admitting `${result.*}`
+        // there would widen the authorable surface with nothing behind it and
+        // silently blank the token instead of leaving the author's mistake visible.
+        const scopes = { param: params, ctx: this.buildInterpolationContext() };
+        if (resultScope !== undefined)
+            scopes.result = resultScope;
+        const pattern = new RegExp(`\\$\\{(${Object.keys(scopes).join('|')})\\.([\\w.]+)\\}`, 'g');
+        return target.replace(pattern, (_match, scope, path) => {
+            const value = readPath(scopes[scope], path);
             if (value == null)
                 return '';
             return encodeURIComponent(String(value));
@@ -1207,6 +1294,25 @@ export async function executeAction(action, context = {}) {
     const runner = new ActionRunner(context);
     return await runner.execute(action);
 }
+/**
+ * Is this `onSuccess` the SPEC's navigation block, or this runner's older
+ * chained-callback channel (`ActionDef | ActionDef[]`)?
+ *
+ * The test IS the spec's declaration: a non-array object carrying a STRING
+ * `navigate`. Nothing else can produce that shape — the spec object is strict
+ * with `navigate: z.string()` required, and on a callback `ActionDef`,
+ * `navigate` is the deprecated nested navigation ENVELOPE that
+ * `executeNavigation` reads `to`/`target`/`redirect` off, so a bare string
+ * there has never been runnable.
+ */
+export function readOnSuccessNavigation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const navigate = value.navigate;
+    if (typeof navigate !== 'string' || navigate === '')
+        return null;
+    return value;
+}
 /**
  * Dot-path read used by target interpolation. Plain reduce — kept inline
  * to avoid pulling lodash for a 3-line helper.

package/dist/actions/actionKeys.d.ts

@@ -106,9 +106,10 @@
 /**
  * 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", "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"];
 /**
@@ -125,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", "description", "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`).
@@ -137,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
@@ -156,7 +205,16 @@ export declare const NAVIGATION_ALIAS_KEYS: readonly ["to", "external", "newTab"
  * 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): {
@@ -169,9 +227,11 @@ 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;
 /**