@object-ui/core 17.3.0 → 17.5.0

package/README.md

@@ -141,21 +141,11 @@ This allows the core types and logic to be used in:
 
 ## API Reference
 
-See [full documentation](https://objectui.org/api/core) for detailed API reference.
-
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
+See [full documentation](https://objectui.org/docs/api) for detailed API reference.
 
 ## Links
 
-- 📚 [Documentation](https://www.objectui.org/docs/core)
+- 📚 [Documentation](https://www.objectui.org/docs/guide/architecture)
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/core)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

package/dist/actions/ActionEngine.d.ts

@@ -8,9 +8,8 @@
 /**
  * @object-ui/core - Action Engine
  *
- * Declarative action dispatch engine. Manages action registration,
- * event-to-action mapping, location-based filtering, keyboard shortcuts,
- * and bulk operation support.
+ * Declarative action engine. Manages action registration, location-based
+ * filtering, keyboard shortcuts, and bulk operation support.
  *
  * Replaces callback-based patterns with a schema-driven pipeline:
  *   ActionSchema[] → ActionEngine → ActionRunner → ActionResult
@@ -37,15 +36,6 @@ export interface RegisteredAction {
     /** Priority for ordering (lower = first) */
     priority?: number;
 }
-/** Event-to-action mapping */
-export interface ActionMapping {
-    /** Event name (e.g., 'row:click', 'toolbar:save', 'keyboard:ctrl+s') */
-    event: string;
-    /** Action name to execute */
-    actionName: string;
-    /** Optional condition expression */
-    condition?: string;
-}
 /** Keyboard shortcut handler */
 export interface ShortcutBinding {
     /** Key combination (e.g., 'ctrl+s', 'meta+k', 'shift+n') */
@@ -53,9 +43,35 @@ export interface ShortcutBinding {
     /** Action name to trigger */
     actionName: string;
 }
+/**
+ * Registration + filtering + execution for declared actions.
+ *
+ * Entry points are by NAME (`executeAction`), by LOCATION
+ * (`getActionsForLocation`), by SHORTCUT (`handleShortcut`) and in BULK
+ * (`executeBulk`). There is deliberately no entry point by arbitrary EVENT
+ * name: this class used to carry a second, parallel one — `addMapping()`
+ * registered `{ event, actionName, condition }` triples into a private
+ * `mappings` array and `dispatch(event)` ran every triple matching an event
+ * string. It was retired under enforce-or-remove (objectui#3368) because it
+ * was a public export of `@object-ui/core` with zero production callers: in
+ * its whole lifetime nothing ever registered a mapping, so `dispatch()` had
+ * no reachable caller either, and its four call sites were all in this
+ * class's own test file.
+ *
+ * Its condition gate had drifted three ways from the `visible` contract
+ * `getActionsForLocation` below implements — it entered on a raw truthy check
+ * (so `condition: false` dispatched anyway), typed `condition` as `string`
+ * only (so a `{ dialect: 'cel', source }` envelope could not reach the
+ * canonical engine), and evaluated without `throwOnError` (so a throwing
+ * predicate failed OPEN, the opposite of `visible`'s fail-closed posture).
+ * All three were retired WITH the path rather than fixed on it: aligning the
+ * contract of an API nobody calls only widens behaviour nobody uses. If an
+ * event-keyed entry point is ever genuinely needed, it must be built on the
+ * shared predicate definitions (`hasDeclaredPredicate` + `toPredicateInput`)
+ * that the surviving gate below already uses, not on a fourth spelling.
+ */
 export declare class ActionEngine {
     private actions;
-    private mappings;
     private shortcuts;
     private normalizedShortcutMap;
     private runner;
@@ -92,21 +108,24 @@ export declare class ActionEngine {
     registerActions(actions: ActionDef[]): void;
     /** Unregister an action by name */
     unregisterAction(name: string): void;
-    /** Add an event-to-action mapping */
-    addMapping(mapping: ActionMapping): void;
     /**
      * Get actions available at a specific location, sorted by priority.
      *
      * Filtering applied (in order):
      *   1. `locations.includes(location)` — location/region match
      *   2. `action.visible` — evaluated against the runner's current context
-     *      ({ record, recordId, objectName, user, … }). Missing or `true`
-     *      passes; any other value is coerced to boolean. Evaluator errors
-     *      hide the action (fail-closed) rather than throwing — this matches
-     *      the contract used by every individual action renderer
-     *      (`action-button`, `action-menu`, `action-bar`, …) so the same
-     *      action behaves identically whether surfaced via the engine or
-     *      consumed standalone.
+     *      ({ record, recordId, objectName, user, … }) whenever a gate is
+     *      DECLARED, which is asked through core's one definition
+     *      `hasDeclaredPredicate` (objectui#3850's ruling, adopted here by
+     *      objectui#3957). No gate — absent, `''`, blank predicate text in either
+     *      spelling, an envelope with no evaluable `source`, or a value that is
+     *      not a predicate at all — means visible. Evaluator errors hide the
+     *      action (fail-closed) rather than throwing — this matches the contract
+     *      used by every individual action renderer (`action-button`,
+     *      `action-menu`, `action-bar`, …) so the same action behaves identically
+     *      whether surfaced via the engine or consumed standalone, which is now
+     *      true of the gate in front of the verdict as well as the verdict
+     *      (objectui#3314: one value, one answer, whichever entry reads it).
      *
      *   Predicate normalization goes through the shared `toPredicateInput`
      *   (`@object-ui/core`'s canonical helper — semantically identical to
@@ -130,8 +149,6 @@ export declare class ActionEngine {
     getAction(name: string): ActionDef | undefined;
     /** Execute an action by name */
     executeAction(name: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult>;
-    /** Dispatch an event — finds mapped actions and executes them */
-    dispatch(event: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult[]>;
     /** Handle a keyboard shortcut event — returns true if handled */
     handleShortcut(keys: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult | null>;
     /** Execute a bulk operation on multiple records */
@@ -146,6 +163,6 @@ export declare class ActionEngine {
     }>;
     /** Update the action context */
     updateContext(context: Partial<ActionContext>): void;
-    /** Clear all registered actions and mappings */
+    /** Clear all registered actions and shortcuts */
     clear(): void;
 }

package/dist/actions/ActionEngine.js

@@ -8,15 +8,15 @@
 /**
  * @object-ui/core - Action Engine
  *
- * Declarative action dispatch engine. Manages action registration,
- * event-to-action mapping, location-based filtering, keyboard shortcuts,
- * and bulk operation support.
+ * Declarative action engine. Manages action registration, location-based
+ * filtering, keyboard shortcuts, and bulk operation support.
  *
  * Replaces callback-based patterns with a schema-driven pipeline:
  *   ActionSchema[] → ActionEngine → ActionRunner → ActionResult
  */
 import { ActionRunner } from './ActionRunner';
 import { toPredicateInput } from '../evaluator/predicateInput.js';
+import { hasDeclaredPredicate } from '../evaluator/declaredPredicate.js';
 export { ACTION_LOCATIONS } from '@object-ui/types';
 /** Normalize a shortcut string for comparison (lowercase, trimmed, sorted parts) */
 function normalizeShortcut(keys) {
@@ -43,6 +43,33 @@ function warnHiddenPredicate(name, raw, err) {
         `Predicate: ${src}. Action predicates evaluate against { record, recordId, objectName, user, os.user, … }; ` +
         `use \`record.<field>\` (not a bare field).`);
 }
+/**
+ * Registration + filtering + execution for declared actions.
+ *
+ * Entry points are by NAME (`executeAction`), by LOCATION
+ * (`getActionsForLocation`), by SHORTCUT (`handleShortcut`) and in BULK
+ * (`executeBulk`). There is deliberately no entry point by arbitrary EVENT
+ * name: this class used to carry a second, parallel one — `addMapping()`
+ * registered `{ event, actionName, condition }` triples into a private
+ * `mappings` array and `dispatch(event)` ran every triple matching an event
+ * string. It was retired under enforce-or-remove (objectui#3368) because it
+ * was a public export of `@object-ui/core` with zero production callers: in
+ * its whole lifetime nothing ever registered a mapping, so `dispatch()` had
+ * no reachable caller either, and its four call sites were all in this
+ * class's own test file.
+ *
+ * Its condition gate had drifted three ways from the `visible` contract
+ * `getActionsForLocation` below implements — it entered on a raw truthy check
+ * (so `condition: false` dispatched anyway), typed `condition` as `string`
+ * only (so a `{ dialect: 'cel', source }` envelope could not reach the
+ * canonical engine), and evaluated without `throwOnError` (so a throwing
+ * predicate failed OPEN, the opposite of `visible`'s fail-closed posture).
+ * All three were retired WITH the path rather than fixed on it: aligning the
+ * contract of an API nobody calls only widens behaviour nobody uses. If an
+ * event-keyed entry point is ever genuinely needed, it must be built on the
+ * shared predicate definitions (`hasDeclaredPredicate` + `toPredicateInput`)
+ * that the surviving gate below already uses, not on a fourth spelling.
+ */
 export class ActionEngine {
     /**
      * @param contextOrRunner Either an initial `ActionContext` (constructs a
@@ -60,12 +87,6 @@ export class ActionEngine {
             writable: true,
             value: new Map()
         });
-        Object.defineProperty(this, "mappings", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
         Object.defineProperty(this, "shortcuts", {
             enumerable: true,
             configurable: true,
@@ -140,11 +161,6 @@ export class ActionEngine {
         }
         this.actions.delete(name);
         this.shortcuts = this.shortcuts.filter(s => s.actionName !== name);
-        this.mappings = this.mappings.filter(m => m.actionName !== name);
-    }
-    /** Add an event-to-action mapping */
-    addMapping(mapping) {
-        this.mappings.push(mapping);
     }
     /**
      * Get actions available at a specific location, sorted by priority.
@@ -152,13 +168,18 @@ export class ActionEngine {
      * Filtering applied (in order):
      *   1. `locations.includes(location)` — location/region match
      *   2. `action.visible` — evaluated against the runner's current context
-     *      ({ record, recordId, objectName, user, … }). Missing or `true`
-     *      passes; any other value is coerced to boolean. Evaluator errors
-     *      hide the action (fail-closed) rather than throwing — this matches
-     *      the contract used by every individual action renderer
-     *      (`action-button`, `action-menu`, `action-bar`, …) so the same
-     *      action behaves identically whether surfaced via the engine or
-     *      consumed standalone.
+     *      ({ record, recordId, objectName, user, … }) whenever a gate is
+     *      DECLARED, which is asked through core's one definition
+     *      `hasDeclaredPredicate` (objectui#3850's ruling, adopted here by
+     *      objectui#3957). No gate — absent, `''`, blank predicate text in either
+     *      spelling, an envelope with no evaluable `source`, or a value that is
+     *      not a predicate at all — means visible. Evaluator errors hide the
+     *      action (fail-closed) rather than throwing — this matches the contract
+     *      used by every individual action renderer (`action-button`,
+     *      `action-menu`, `action-bar`, …) so the same action behaves identically
+     *      whether surfaced via the engine or consumed standalone, which is now
+     *      true of the gate in front of the verdict as well as the verdict
+     *      (objectui#3314: one value, one answer, whichever entry reads it).
      *
      *   Predicate normalization goes through the shared `toPredicateInput`
      *   (`@object-ui/core`'s canonical helper — semantically identical to
@@ -194,22 +215,36 @@ export class ActionEngine {
         })
             .filter(ra => {
             const raw = ra.action.visible;
-            if (raw == null || raw === '' || raw === true)
+            // Ask "is a `visible` gate DECLARED?" through the repo's ONE definition
+            // (`evaluator/declaredPredicate.ts`, objectui#3850's ruling), which is
+            // what the renderers, `SchemaRenderer` and `ActionRunner`'s execution
+            // gates ask. This filter used to answer it with a range of its own —
+            // three empty spellings folded by hand (`null` / `''` / an envelope with
+            // an empty `source`) and everything else coerced with `Boolean(raw)` —
+            // and it was the LAST consumer to do so, so the same value got two
+            // answers depending on which entry read it: `visible: 0` / `NaN` hid the
+            // action here and showed it on the renderer face, and `visible: '   '`
+            // hid it here because the normalizer wraps a blank string into `'${   }'`
+            // whose verdict is falsy. That is the shape objectui#3314's invariant
+            // forbids, and it is fixed by deleting a range, not by adding one
+            // (objectui#3957). A value that is not a predicate, or a predicate that
+            // says nothing, must not be the reason an action is hidden from
+            // everyone — the same fail-open posture `ActionRunner` already committed
+            // to for `disabled` (`catch { isDisabled = false }`).
+            //
+            // Booleans need no branch of their own: they are DECLARED (`visible:
+            // false` is a verdict, objectui#3812) and `evaluateCondition`
+            // short-circuits them.
+            if (!hasDeclaredPredicate(raw))
                 return true;
-            if (raw === false)
-                return false;
             // #3314 — one shared normalization, not two. Hand-rolling the envelope
             // unwrap here is what dropped `dialect: 'cel'` and demoted the
             // predicate to the legacy JS engine; `toPredicateInput` keeps the
             // envelope so `evaluateCondition` can route it to `@objectstack/formula`
             // (the engine the server enforces with), exactly as the renderers do.
+            // Declared ⇒ the normalizer left something to evaluate, so there is no
+            // `undefined` case left to handle here.
             const expr = toPredicateInput(raw);
-            if (expr === undefined) {
-                // Not an evaluable predicate: an envelope with an empty `source`
-                // (→ nothing declared → visible), or a stray non-predicate value,
-                // which keeps the historical `Boolean(raw)` coercion.
-                return typeof raw === 'object' ? true : Boolean(raw);
-            }
             try {
                 // `throwOnError: true` is required for fail-closed semantics: the
                 // evaluator's default behavior swallows expression errors and
@@ -262,26 +297,6 @@ export class ActionEngine {
         }
         return this.runner.execute(registered.action);
     }
-    /** Dispatch an event — finds mapped actions and executes them */
-    async dispatch(event, contextOverride) {
-        const matchingMappings = this.mappings.filter(m => m.event === event);
-        if (matchingMappings.length === 0) {
-            return [];
-        }
-        const results = [];
-        for (const mapping of matchingMappings) {
-            // Check condition if present
-            if (mapping.condition) {
-                const evaluator = this.runner.getEvaluator();
-                const shouldRun = evaluator.evaluateCondition(mapping.condition);
-                if (!shouldRun)
-                    continue;
-            }
-            const result = await this.executeAction(mapping.actionName, contextOverride);
-            results.push(result);
-        }
-        return results;
-    }
     /** Handle a keyboard shortcut event — returns true if handled */
     async handleShortcut(keys, contextOverride) {
         const actionName = this.normalizedShortcutMap.get(normalizeShortcut(keys));
@@ -341,10 +356,9 @@ export class ActionEngine {
     updateContext(context) {
         this.runner.updateContext(context);
     }
-    /** Clear all registered actions and mappings */
+    /** Clear all registered actions and shortcuts */
     clear() {
         this.actions.clear();
-        this.mappings = [];
         this.shortcuts = [];
         this.normalizedShortcutMap.clear();
     }

package/dist/actions/ActionRunner.d.ts

@@ -5,7 +5,22 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { ActionInput as SpecActionInput } from '@objectstack/spec/ui';
+/**
+ * @object-ui/core - Action Runner
+ *
+ * Executes actions defined in ActionSchema and EventHandler.
+ *
+ * Dispatches every `@objectstack/spec` `ActionType` — `script`, `url`, `modal`,
+ * `flow`, `api`, `form` — plus the one declared renderer-local alias,
+ * `navigation` (see `ObjectUiLocalActionType`). The table that does it is typed
+ * against that vocabulary, so this list cannot go stale the way the old comment
+ * had (it still claimed five types after `form` shipped).
+ *
+ * Features: conditional execution, confirmation, toast notifications,
+ * redirect handling, action chaining, custom handler registration.
+ */
+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';
 export interface ActionResult {
@@ -61,6 +76,30 @@ export interface ApiConfig {
 /**
  * Action definition accepted by the runner.
  * Compatible with both UIActionSchema (spec v2.0.1) and legacy crud.ts ActionSchema.
+ *
+ * ── CLOSED since objectstack#4075 step 3 ──────────────────────────────────────
+ *
+ * This interface used to end with `[key: string]: any`, so it accepted any key
+ * of any type: deleting `execute` from it produced ZERO compile errors, a typo
+ * (`targt`, `exectue`) type-checked, and a tombstoned key sailed through to a
+ * runner that then silently did nothing — the objectstack#2169 "Mark Done does
+ * nothing" shape. The index signature is gone. Every key this type accepts is
+ * now written down below, and `tsc` rejects the rest at any site that AUTHORS an
+ * action literal in code.
+ *
+ * What it does NOT reach, and what still covers that: stored `sys_metadata` rows
+ * are rehydrated UNPARSED (objectstack#3903), so authored metadata arrives at
+ * `runner.execute()` as a plain object the compiler never saw. The dev-mode
+ * `warnOnUnknownActionKeys` shim from step 1 therefore STAYS — it is not
+ * redundant with the closed type, it is the other half of the same surface, and
+ * the two halves catch disjoint populations (code-authored literals vs. stored
+ * rows).
+ *
+ * {@link ActionContext} keeps ITS index signature, deliberately. It is a runtime
+ * data bag whose keys are genuinely open (`data`, `record`, `pageVariables`,
+ * `user`, plus whatever a host passes); this is a declared metadata contract
+ * mirroring `@objectstack/spec`'s `ActionSchema`. Open key set on a data bag is
+ * correct; open key set on a contract is the bug above.
  */
 export interface ActionDef {
     /** Action type identifier — a `RunnableActionType` (the spec's six plus the
@@ -77,6 +116,24 @@ export interface ActionDef {
     name?: string;
     /** Display label */
     label?: string;
+    /**
+     * Human description of the action, shown as the param-collection dialog's
+     * subtitle (`useConsoleActionRuntime` reads it beside `label`).
+     *
+     * objectui vocabulary, not spec: `@objectstack/spec`'s `ActionSchema` has no
+     * `description`, so this derives from `@object-ui/types`' renderer view of an
+     * action (`UIActionSchema`, `ui-action.ts`) — the same "authorable for a
+     * declared surface" source `check:action-forward-parity` derives its owed set
+     * from, which is why that gate already requires all four action renderers to
+     * forward this key (objectui#4192: `action:menu`'s dialog titled itself
+     * "Action parameters" instead of naming the action).
+     *
+     * Promoted by step 3 (objectstack#4075): the key was authorable, forwarded
+     * and read, but `ActionDef` never declared it, so it reached its reader only
+     * through `[key: string]: any`. Deleting the index signature is what surfaced
+     * it — the two TS2353s the deletion produced repo-wide were both this key.
+     */
+    description?: UIActionSchema['description'];
     /** Confirmation text — shows a confirm dialog before executing */
     confirmText?: string;
     /** Structured confirmation (from crud.ts) */
@@ -86,10 +143,31 @@ export interface ActionDef {
         confirmText?: string;
         cancelText?: string;
     };
-    /** Condition expression — if falsy, skip action */
-    condition?: string;
-    /** Disabled expression — if truthy, skip action */
-    disabled?: string | boolean;
+    /**
+     * Condition predicate — the action executes only while it holds.
+     *
+     * A boolean, a bare CEL string, a `${…}` template, or the normalized
+     * `{ dialect, source }` envelope `objectstack build` emits. Declared and
+     * FALSE skips the action; not declared at all (absent / empty predicate)
+     * executes. `boolean` is spelled out here because the execution gate now
+     * honours `condition: false` as the verdict it plainly is (objectui#3872) —
+     * the same widening `disabled` already carries below.
+     */
+    condition?: string | boolean;
+    /**
+     * Disabled predicate — the control renders inert while it holds.
+     *
+     * Same three arms as {@link ActionDef.visible}, derived from the same spec
+     * field, because the 2026-08-06 maintainer ruling on objectstack#4075 gave
+     * both keys ONE shape: `boolean | string(CEL) | { dialect, source }` —
+     * "boolean = 条件的退化形字面量,string = CEL 简写,信封 = 完整形". The
+     * envelope arm arrived in `@objectstack/spec` 17.0.0-rc.6 (objectstack#5970,
+     * PR objectstack#6450); until then this was a hand-written `string | boolean`
+     * that could not describe the envelope, which is why `DeclaredActionsBar`
+     * read it through an `(action as any).disabled` cast. Derived, not restated,
+     * so the two keys cannot drift apart again.
+     */
+    disabled?: SpecActionInput['disabled'];
     /**
      * API endpoint (string URL or complex config).
      *
@@ -121,6 +199,19 @@ export interface ActionDef {
      * today (objectstack#4075 step 2).
      */
     navigate?: any;
+    /** `navigation` alias: the target URL. `executeNavigation` resolves
+     *  `to || target || redirect`, so a flat spec-style `target` also works. */
+    to?: string;
+    /** `navigation` alias: force the external-URL treatment that the scheme
+     *  heuristic would otherwise decide. */
+    external?: boolean;
+    /** `navigation` alias: open in a new tab. The first-class spec switch is
+     *  `openIn: 'new-tab'`, which WINS over this one — prefer it in new metadata.
+     *  Unrelated to the retired `params.newTab` read (objectui#4097). */
+    newTab?: boolean;
+    /** `navigation` alias: replace the current history entry instead of pushing
+     *  a new one. No `ActionSchema` counterpart in any spelling. */
+    replace?: boolean;
     /** onClick callback (legacy) */
     onClick?: () => void | Promise<void>;
     /** Whether to reload data after success */
@@ -213,16 +304,23 @@ export interface ActionDef {
     /**
      * Visibility predicate, evaluated against the runner's context.
      *
-     * The `boolean` arm is objectui's own, deliberately wider than the spec:
-     * `ActionSchema.visible` admits only a CEL string or a `{ dialect, source }`
-     * envelope, while `ActionEngine.getActionsForLocation` also honours a literal
-     * `visible: true` / `false` (pinned by `ActionEngine.visibility.test.ts`).
-     * Declared rather than left to the index signature so the tolerance is
-     * auditable instead of invisible — but it IS a dialect, and objectstack#4075
-     * step 3 has to decide whether the spec adopts the boolean or objectui drops
-     * it. Do not widen this further.
-     */
-    visible?: SpecActionInput['visible'] | boolean;
+     * Three arms — `boolean | string(CEL) | { dialect, source }` — and all three
+     * now come from the spec. Step 2 had to write `SpecActionInput['visible'] |
+     * boolean` because the literal `visible: true` / `false` that
+     * `ActionEngine.getActionsForLocation` honours (pinned by
+     * `ActionEngine.visibility.test.ts`) was objectui tolerance the spec did not
+     * share, and it left the open question step 3 was blocked on: does the spec
+     * adopt the boolean, or does objectui drop it?
+     *
+     * The maintainer ruled ADOPT on 2026-08-06 (objectstack#4075): "统一形状,
+     * spec 采纳 —— `visible` / `disabled` 两键在 spec 侧统一收敛为
+     * `boolean | string(CEL) | {dialect, source}`(boolean = 条件的退化形字面量,
+     * string = CEL 简写,信封 = 完整形)". `@objectstack/spec` 17.0.0-rc.6 carries
+     * it (objectstack#5970, PR objectstack#6450), so the local `| boolean` is no
+     * longer a tolerance to declare — it is part of the derived type, and adding
+     * it back would restate a spec arm rather than widen anything.
+     */
+    visible?: SpecActionInput['visible'];
     /** System permissions the caller must ALL hold for the action to be offered
      *  (ADR-0066 D4 UI half — the server enforces the source of truth). */
     requiredPermissions?: SpecActionInput['requiredPermissions'];
@@ -268,8 +366,6 @@ export interface ActionDef {
      * remains available to a HOST passing it explicitly.
      */
     bulkEnabled?: SpecActionInput['bulkEnabled'];
-    /** Any additional properties */
-    [key: string]: any;
 }
 /**
  * A handler registered with {@link ActionRunner} — the client-side action
@@ -351,6 +447,31 @@ export interface ResultDialogSpec {
  * cleanup purposes (the action already succeeded).
  */
 export type ResultDialogHandler = (spec: ResultDialogSpec, data: unknown, action?: ActionDef) => Promise<void>;
+/**
+ * One entry of a param's option list, as the RESOLVED param carries it.
+ *
+ * `label` / `value` are the two keys this layer itself reads and rewrites (i18n
+ * translation of the label, value matching). Everything else an option declares
+ * rides along in the catch-all and reaches the widgets untouched: per-option
+ * `visibleWhen` (the CEL predicate `resolveVisibleOptions()` filters on —
+ * ADR-0058 / #2284), `color`, `icon`, `disabled`.
+ *
+ * The catch-all is deliberate rather than a closed key list (objectui#3559).
+ * A field's option vocabulary is owned by the field metadata (`@objectstack/spec`'s
+ * `SelectOptionSchema`) and read by the option widgets; a param's option list is
+ * only a CONDUIT between the two. When this type restated that vocabulary as
+ * `{ label, value }`, the resolver dutifully rebuilt every inherited option to
+ * match and a field's `visibleWhen` stopped narrowing the dialog's list — the
+ * same field metadata behaving two ways on two surfaces. Naming the two keys
+ * this layer uses and passing the rest through is what keeps that from
+ * recurring; it is NOT an invitation to author new resolved-only option keys
+ * (the spec's schema is the authoring gate, and it is `.strict()`).
+ */
+export type ActionParamOption = {
+    label: string;
+    value: string;
+    [key: string]: unknown;
+};
 /**
  * ActionParam definition accepted by the runner.
  * Compatible with @objectstack/spec ActionParam.
@@ -373,10 +494,7 @@ export interface ActionParamDef {
     label: string;
     type: string;
     required?: boolean;
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
+    options?: ActionParamOption[];
     defaultValue?: unknown;
     helpText?: string;
     placeholder?: string;
@@ -543,6 +661,37 @@ export declare class ActionRunner {
      * through to `executeActionSchema` and silently no-opped (the "Log Time does
      * nothing" report). The current record id is forwarded as `?recordId=` for
      * hosts that support it; the form route ignores unknown query params.
+     *
+     * ## An id never travels without its object (objectui#4292)
+     *
+     * `?recordId=` names an id and nothing else, so the consumer has to pick an
+     * object to resolve it against, and the only one it can pick is the FormView's
+     * own target object (`/forms/:name` does exactly that since objectui#4278).
+     * That is right whenever the action fired from a record OF that object, and
+     * nothing here used to check that it did: `target: 'showcase_task.edit'` on an
+     * Account record header is publishable metadata, and with per-table integer
+     * keys `GET /data/showcase_task/42` cheerfully answers for Account 42. Before
+     * #4278 the damage stopped at a duplicate insert; now that the route honours
+     * the param, the same mis-scoped action PATCHes a different object's record
+     * with no error anywhere. So the id is forwarded only when the two objects
+     * MATCH, and the object identity rides along as the consumer's second half of
+     * the check ({@link FORM_RECORD_OBJECT_PARAM}).
+     *
+     * The three outcomes, and why the third preserves rather than refuses:
+     *
+     *  - **match** — forward `?recordId=&recordObject=`. The #4278 edit path,
+     *    plus the identity the consumer re-checks against its own view metadata;
+     *  - **mismatch** — forward NEITHER, i.e. the bare `/forms/:name`. A "log
+     *    time" action fired from a Task at another object's create view is not a
+     *    broken edit, it is a CREATE that happens to be launched from a record —
+     *    which is exactly what this route did before #4278 taught it to read the
+     *    param. Refusing here would break a shape that works;
+     *  - **not comparable** — either end unknown ⇒ forward as before. A host that
+     *    publishes no `objectName`, or an unqualified target name, gives this
+     *    runner nothing to compare; tightening on absent information would turn
+     *    working edit flows into creates on every such host. The guard only ever
+     *    fires on information it actually has, and the consumer half applies the
+     *    same rule to a missing `recordObject`.
      */
     private executeForm;
     /**
@@ -556,6 +705,35 @@ export declare class ActionRunner {
      * drift apart again. Prefer `type: 'url'` + `openIn` in new metadata.
      */
     private executeNavigation;
+    /**
+     * Assemble the request body for the runner's OWN `executeAPI` — the path taken
+     * when no host registered an `api` handler.
+     *
+     * `bodyExtra` is merged LAST, which is the spec's documented semantics for the
+     * key ("Static request-body fields for a `type:'api'` action, merged last
+     * (overrides user params)") and what the console's `apiHandler` already does on
+     * both of its branches. Before objectstack#6837 this path read `action.params`
+     * alone and never looked at `bodyExtra` at all, so an action whose payload lives
+     * entirely in `bodyExtra` — the shape the ADR-0087 conversion produces from an
+     * old object-form `params` page — POSTed an empty body here.
+     *
+     * `params` contributes only in its DEPRECATED non-array form (the compat window
+     * #5777 opened; see `warnOnDeprecatedObjectParams`). An ARRAY `params` is a
+     * parameter DEFINITION list, not a payload: it reaches this method unconsumed
+     * only when no `paramCollectionHandler` is mounted, and POSTing the definitions
+     * as the request body was never a payload any endpoint wanted. It now falls
+     * through to the context record like an absent `params` does.
+     *
+     * `bodyShape` then decides how that payload is WRAPPED, and the wrap covers the
+     * collected payload ONLY — `bodyExtra` stays at the top level. That is the
+     * spec's own wording for the key ("`{ wrap: 'data' }` nests the user-collected
+     * params under that key, while `recordIdParam` and other top-level keys stay
+     * flat") and what both console read-sites already do, so the key means one
+     * thing on every path that honours it. Until objectstack#6938 this path did not
+     * read it at all: the console `apiHandler` wrapped and the runner's own fallback
+     * did not, so the same action changed body shape with the host it ran under.
+     */
+    private buildApiRequestBody;
     /**
      * Execute API action — supports both simple string endpoint and complex ApiConfig.
      */