feat(core): declare the 18 spec-owned action keys ActionDef absorbed silently

`ActionDef` ends with `[key: string]: any`, so it accepted any key of any
type — a typo (`targt`) and a retired spec key (`execute`) both type-checked,
then the runner silently bound no handler (the #2169 shape). Step 1 made that
audible with a dev-mode warning; this is step 2, promoting the keys that
warning identified as legitimate into real fields.

- Promote 18 spec-owned keys to explicit optional fields, every type DERIVED
  from `@objectstack/spec`'s `ActionInput` rather than hand-copied. A
  hand-written duplicate of a spec shape is a second contract that drifts,
  which is the failure this issue is about.
- Derive from `z.input`, not `z.infer`: `ActionSchema` is a `ZodPipe` whose
  transform narrows `visible` to the `{ dialect, source }` envelope alone.
  This runner reads authored rows unparsed, so it sees the input shape;
  `Action` would have rejected the raw-string predicate ActionEngine supports.
- Delete three `as any` casts in `ActionEngine` (`visible`,
  `requiredPermissions`, `locations`) that existed only because the fields
  were undeclared. Package `as any` count drops 9 -> 3.
- Mark `@deprecated` only the four dialect keys the runner itself proves are
  aliases: `actionType` -> `type`, `api`/`endpoint` -> `target`, `navigate` ->
  flat `target`/`openIn`. The rest are runner mechanics with no spec spelling.

`shortcut` and `bulkEnabled` derive to `undefined` because spec 17 retired
both as `retiredKey()` tombstones — so authoring either, already a hard parse
rejection, is now a compile error too. Hand-copying would have quietly
re-legitimized two dead keys.

The index signature stays; removing it is step 3, and the inverted pin
asserting it is still present remains the issue's completion check.

Refs objectstack-ai/objectstack#4075

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5

Author: claude

.changeset/actiondef-spec-owned-keys-explicit.md

@@ -0,0 +1,51 @@
+---
+"@object-ui/core": minor
+---
+
+Declare the 18 spec-owned action keys `ActionDef` had been absorbing silently.
+
+`ActionDef` ends with `[key: string]: any`, so it accepted any key of any type —
+a typo (`targt`) and a retired spec key (`execute`) both type-checked, then the
+runner silently bound no handler (the #2169 "Mark Done does nothing" shape).
+Step 1 (objectstack#4075) made that audible with a dev-mode warning. This is
+step 2: the keys the warning identified as legitimate are now real fields.
+
+- **18 keys promoted to explicit optional fields** — `ai`, `aria`, `bodyExtra`,
+  `bodyShape`, `bulkEnabled`, `component`, `icon`, `locations`, `mode`,
+  `objectName`, `order`, `recordIdField`, `recordIdParam`, `requiredPermissions`,
+  `requiresFeature`, `shortcut`, `variant`, `visible`. Every type is **derived**
+  from `@objectstack/spec`'s `ActionInput` (`SpecActionInput['locations']`, …),
+  never hand-copied: a hand-written duplicate of a spec shape is a second
+  contract that drifts, which is the failure this issue is about. Wrong-typed
+  values are now compile errors — `order: 'first'`, `variant: 'chartreuse'`,
+  `locations: ['nope']` — where before they were absorbed silently.
+- **Derived from `z.input`, not `z.infer`.** `ActionSchema` is a `ZodPipe` whose
+  transform narrows `visible` from `string | { dialect, source }` to the
+  envelope alone. This runner consumes authored/stored rows, which are
+  rehydrated unparsed, so it sees the input shape; deriving from the inferred
+  `Action` would have rejected the raw-string predicate `ActionEngine`
+  explicitly supports.
+- **Three `as any` casts deleted** in `ActionEngine` — `visible` and
+  `requiredPermissions` at the location filter, `locations` at registration.
+  They existed only because the fields were undeclared.
+- **Four objectui-dialect keys marked `@deprecated`** with the spec spelling to
+  use instead — `actionType` (→ `type`), `api` and `endpoint` (→ `target`;
+  `executeAPI` already resolves `api || endpoint || target`), and `navigate`
+  (→ flat `target` / `openIn`). Only these four: the remaining dialect keys are
+  runner mechanics (chaining, toasts, post-execution reload/close) with no spec
+  counterpart, and pointing them at a spelling that does not exist would be
+  worse than leaving them declared.
+
+**Breaking edge, deliberate.** `shortcut` and `bulkEnabled` were retired by
+`@objectstack/spec` 17 as `retiredKey()` tombstones (`z.never()`), so authoring
+either is already a hard parse rejection. Deriving their types rather than
+hand-writing them turns that runtime rejection into a **compile error**: code
+that assigned `shortcut: 'ctrl+k'` to an `ActionDef` compiled before and does
+not now. Such metadata was already refused by the platform — this only moves the
+failure to where it can be fixed. A host may still pass either explicitly via
+`ActionEngine.registerAction(action, { shortcut, bulkEnabled })`; only authored
+metadata stopped carrying them. `bulkEnabled`'s replacement is the list view's
+`bulkActions` / `bulkActionDefs`; `shortcut` has none.
+
+The index signature **stays** — removing it is step 3, and the inverted pin
+asserting it is still present remains the issue's own completion check.

packages/core/src/actions/ActionEngine.ts

@@ -156,7 +156,10 @@ export class ActionEngine {
   registerActions(actions: ActionDef[]): void {
     for (const action of actions) {
       this.registerAction(action, {
-        locations: (action as any).locations,
+        // No cast: `locations` is a declared `ActionDef` field as of
+        // objectstack#4075 step 2. The `as any` it replaces existed only
+        // because the key reached this reader through the index signature.
+        locations: action.locations,
       });
     }
   }
@@ -210,21 +213,21 @@ export class ActionEngine {
         // systemPermissions is unknown (undefined): the server still 403s, and
         // hiding on missing data is a worse regression than showing a button
         // that errors clearly. Mirrors the App/nav requiredPermissions gate.
-        const required = (ra.action as any).requiredPermissions as string[] | undefined;
+        const required = ra.action.requiredPermissions;
         if (!Array.isArray(required) || required.length === 0) return true;
         const held = (this.runner.getContext() as any)?.user?.systemPermissions as string[] | undefined;
         if (!Array.isArray(held)) return true;
         return required.every((p) => held.includes(p));
       })
       .filter(ra => {
-        const raw = (ra.action as any).visible;
+        const raw = ra.action.visible;
         if (raw == null || raw === '' || raw === true) return true;
         if (raw === false) return false;
         let expr: string | boolean;
         if (typeof raw === 'string') {
           expr = `\${${raw}}`;
-        } else if (typeof raw === 'object' && typeof (raw as any).source === 'string') {
-          const src = (raw as any).source as string;
+        } else if (typeof raw === 'object' && typeof raw.source === 'string') {
+          const src = raw.source;
           if (!src) return true;
           expr = `\${${src}}`;
         } else {
@@ -246,7 +249,7 @@ export class ActionEngine {
           // user }` eval scope. Silently hiding it makes that bug invisible
           // (the #2183 hunt). Warn once per predicate so it is diagnosable
           // without spamming re-renders.
-          warnHiddenPredicate((ra.action as any).name, raw, err);
+          warnHiddenPredicate(ra.action.name, raw, err);
           return false;
         }
       })

packages/core/src/actions/ActionRunner.ts

@@ -22,6 +22,7 @@
  */
 
 import type { RunnableActionType } from '@object-ui/types';
+import type { ActionInput as SpecActionInput } from '@objectstack/spec/ui';
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
 import { globalUndoManager, type UndoableOperation } from './UndoManager';
 import { warnOnUnknownActionKeys } from './actionKeys';
@@ -87,7 +88,12 @@ export interface ActionDef {
   /** Action type identifier — a `RunnableActionType` (the spec's six plus the
    *  `navigation` alias of `url`) or a custom type with a registered handler. */
   type?: string;
-  /** Legacy action type field */
+  /**
+   * Legacy action type field.
+   *
+   * @deprecated objectui dialect — use the spec spelling `type`. Both are read,
+   * `type` first (objectstack#4075 step 2).
+   */
   actionType?: string;
   /** Action name (from UIActionSchema) */
   name?: string;
@@ -101,13 +107,36 @@ export interface ActionDef {
   condition?: string;
   /** Disabled expression — if truthy, skip action */
   disabled?: string | boolean;
-  /** API endpoint (string URL or complex config) */
+  /**
+   * API endpoint (string URL or complex config).
+   *
+   * @deprecated objectui dialect — the spec spells an `api` action's endpoint
+   * `target` (with the verb in `method`). `executeAPI` resolves
+   * `api || endpoint || target`, so `target` alone is sufficient. The
+   * `ApiConfig` object form has no spec counterpart and is objectui-only
+   * (objectstack#4075 step 2).
+   */
   api?: string | ApiConfig;
-  /** API endpoint URL (spec v2.0.1 alias) */
+  /**
+   * API endpoint URL.
+   *
+   * @deprecated objectui dialect — this was the "spec v2.0.1 alias", but spec 17
+   * spells it `target`. `executeAPI` resolves `api || endpoint || target`
+   * (objectstack#4075 step 2).
+   */
   endpoint?: string;
   /** HTTP method */
   method?: string;
-  /** Navigation target */
+  /**
+   * Navigation target — a nested envelope carrying the `navigation` alias's own
+   * spelling (`to` / `external` / `newTab` / `replace`).
+   *
+   * @deprecated objectui dialect — the spec has no nested navigation envelope;
+   * it spells a navigation action `{ type: 'url', target, openIn }`.
+   * `executeNavigation` reads `navigate.to || navigate.target || navigate.redirect`,
+   * falling back to the same keys on the action itself, so a flat `target` works
+   * today (objectstack#4075 step 2).
+   */
   navigate?: any;
   /** onClick callback (legacy) */
   onClick?: () => void | Promise<void>;
@@ -190,6 +219,97 @@ export interface ActionDef {
    *  must perform all auth/authz itself (e.g. the cloud `/sso-open` endpoint,
    *  which re-runs every check the POST half would have done). */
   newTabUrl?: string;
+
+  // ── Spec-owned keys, promoted from the index signature ─────────────────────
+  //
+  // objectstack#4075 step 2. Step 1's inventory found 18 keys that
+  // `@objectstack/spec`'s `ActionSchema` owns and that authored metadata
+  // carries today, but that `ActionDef` never declared — so they reached
+  // readers only through `[key: string]: any`, and the two `ActionEngine`
+  // actually reads (`visible`, `locations`) had to be read through an `as any`
+  // cast. Declaring them is what removes those casts.
+  //
+  // Every type below is DERIVED from the spec via `SpecActionInput[...]`, never
+  // hand-copied: a hand-written duplicate of a spec shape is a second contract
+  // that drifts silently, which is the failure this whole issue is about.
+  //
+  // Derived from `z.input` (`ActionInput`), not `z.infer` (`Action`), and the
+  // difference is load-bearing rather than stylistic. `ActionSchema` is a
+  // `ZodPipe` whose transforms narrow the authored shape — `visible` is authored
+  // as `string | { dialect, source }` but INFERS to the object form alone. This
+  // runner consumes authored/stored rows, which #3903 established are rehydrated
+  // UNPARSED, so it sees the input shape. Deriving from `Action` would have
+  // type-errored the raw-string predicate that `ActionEngine` explicitly
+  // supports and that `ActionEngine.visibility.test.ts` pins.
+  //
+  // `shortcut` and `bulkEnabled` land here as `undefined`, not as a usable type
+  // — that is correct and deliberate. Spec 17 retired both as `retiredKey()`
+  // tombstones (`z.never()`), so authoring either is a hard parse rejection.
+  // Deriving rather than hand-writing turns that rejection into a COMPILE error
+  // for free; hand-copying would have re-legitimized two dead keys.
+
+  /** Where this action renders (`record_header`, `list_toolbar`, …). Read by
+   *  `ActionEngine.registerActions` to seed the location filter. */
+  locations?: SpecActionInput['locations'];
+  /**
+   * 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;
+  /** 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'];
+  /** Icon name for the rendered control. */
+  icon?: SpecActionInput['icon'];
+  /** Visual emphasis of the rendered control (`primary`, `danger`, …). */
+  variant?: SpecActionInput['variant'];
+  /** Sort weight among sibling actions. */
+  order?: SpecActionInput['order'];
+  /** Which renderer surfaces the action (`action:button`, `action:menu`, …). */
+  component?: SpecActionInput['component'];
+  /** Object this action is declared against. */
+  objectName?: SpecActionInput['objectName'];
+  /** AI affordance metadata (tool exposure, prompts). */
+  ai?: SpecActionInput['ai'];
+  /** Accessibility overrides for the rendered control. */
+  aria?: SpecActionInput['aria'];
+  /** Extra properties merged into the request body alongside the collected params. */
+  bodyExtra?: SpecActionInput['bodyExtra'];
+  /** How collected params are shaped into the request body (`flat` or nested). */
+  bodyShape?: SpecActionInput['bodyShape'];
+  /** Execution mode of the action. */
+  mode?: SpecActionInput['mode'];
+  /** Field on the record supplying the record id sent to the endpoint. */
+  recordIdField?: SpecActionInput['recordIdField'];
+  /** Request-parameter name carrying the record id. */
+  recordIdParam?: SpecActionInput['recordIdParam'];
+  /** Auth/tenancy feature the action requires before it is offered. */
+  requiresFeature?: SpecActionInput['requiresFeature'];
+  /**
+   * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
+   * authoring it is a hard parse rejection, so this resolves to `undefined` and
+   * assigning a value is a compile error. A HOST may still pass a shortcut
+   * explicitly via `ActionEngine.registerAction(action, { shortcut })`; it is
+   * only no longer sourced from authored metadata. No replacement key.
+   */
+  shortcut?: SpecActionInput['shortcut'];
+  /**
+   * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
+   * authoring it is a hard parse rejection, so this resolves to `undefined` and
+   * assigning a value is a compile error. Use the list view's `bulkActions` /
+   * `bulkActionDefs` instead; `ActionEngine.registerAction(action, { bulkEnabled })`
+   * remains available to a HOST passing it explicitly.
+   */
+  bulkEnabled?: SpecActionInput['bulkEnabled'];
+
   /** Any additional properties */
   [key: string]: any;
 }