feat(core): inventory ActionDef's keys and warn on the ones nothing reads (objectstack#4075 step 1)

`ActionDef` ends with `[key: string]: any`, so it accepts any key of any type.
Deleting `ActionDef.execute` produced ZERO compile errors even though the field
had just been removed (objectui#2990), and stale metadata still authoring
`execute: 'markDone'` type-checks today. The same deletion against
`@object-ui/types`' `ActionSchema` — no index signature — correctly produced
TS2353 at the authoring site. One reader can catch a retired key; the other is
structurally incapable.

Step 1 is the non-breaking half: make the key set visible, warn on anything
outside it, change no types.

What the inventory found, which is step 2's worklist:

- 18 keys the SPEC owns that `ActionDef` never declared — `visible`, `locations`,
  `icon`, `variant`, `order`, `component`, `bulkEnabled`, `requiredPermissions`
  and 10 more. `ActionEngine` reads two of them through `as any` casts
  (`(ra.action as any).visible`, `(action as any).locations`); those casts exist
  only because the field is undeclared.
- 17 keys `ActionDef` declares that the spec does not own — `actionType`, `api`,
  `chain`, `onClick`, `toast` and others, several already marked legacy. This is
  objectui's own dialect and needs the #4115 treatment: documented as deliberate,
  or retired.
- `execute` is not simply gone from the spec — it is a live TOMBSTONE, still in
  `ActionSchema` so the parser can reject it BY NAME with the rename
  prescription. So it is warned about separately and more loudly than an unknown
  key: an unknown key is probably a typo, a retired key is metadata that used to
  work.
- `to` / `external` / `newTab` / `replace` are a real objectui dialect — the
  `navigation` alias's own spelling, read off the action when no nested
  `navigate` object is present. Declared here rather than left to trip the
  warning, with a tripwire test that fails if the spec ever adopts one.

The lists are data because TypeScript types do not survive to runtime, and
`keyof ActionDef` cannot substitute — the index signature widens it to
`string | number`, which is the problem itself. `actionKeys.pin.test.ts`
re-derives each list from its real source (the interface via the AST, the spec
via its schema) so a hand-maintained list cannot drift from what it mirrors.

The spec key list is pinned rather than resolved at runtime: `ActionSchema` is a
lazy proxy that does not forward `.shape`, so reading it means walking zod
internals — fine in a test, wrong in shipped code. `@object-ui/types` made the
same call for `ActionComponent`.

Discrimination proof: dropping any entry from `ACTION_DEF_KEYS` fails with
"ActionDef declares keys the inventory is missing: <name>"; the warning tests
assert it stays silent on a well-formed action, names `targt`, gives `execute`
its rename prescription, warns once rather than per click, and says nothing in
production. Core type-checks clean and all 207 existing action tests still pass.

One pin is deliberately inverted: the suite asserts the index signature is STILL
THERE. The day that fails, step 3 has landed, `tsc` catches unknown keys itself,
and this warning plus `executeScript`'s rename branch can retire together.

Refs objectstack#4075, objectstack#3903, objectui#2990, #3856, #3855, #2169, AGENTS.md PD #12

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

Author: claude

packages/core/src/actions/ActionRunner.ts

@@ -24,6 +24,7 @@
 import type { RunnableActionType } from '@object-ui/types';
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
 import { globalUndoManager, type UndoableOperation } from './UndoManager';
+import { warnOnUnknownActionKeys } from './actionKeys';
 
 export interface ActionResult {
   success: boolean;
@@ -475,6 +476,12 @@ export class ActionRunner {
 
   async execute(action: ActionDef): Promise<ActionResult> {
     try {
+      // `ActionDef` accepts any key of any type, so a typo (`targt`) and a
+      // retired key (`execute`) both reach here having type-checked. Neither
+      // binds a handler, and binding no handler silently is the #2169 "Mark Done
+      // does nothing" shape. Dev-only, warn-once, changes nothing (#4075 step 1).
+      warnOnUnknownActionKeys(action);
+
       // Resolve the action type
       const actionType = action.type || action.actionType || action.name || '';
 

packages/core/src/actions/__tests__/actionKeys.pin.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Pins the key inventory in `actionKeys.ts` to the two things it mirrors —
+ * `ActionDef`'s own declarations and `@objectstack/spec`'s `ActionSchema`
+ * (objectstack#4075 step 1).
+ *
+ * Why a test rather than a comment: a hand-maintained list that silently drifts
+ * from the interface it claims to mirror is the exact "declared ≠ enforced"
+ * failure this work is about. `ActionDef` cannot be enumerated at runtime — its
+ * `[key: string]: any` widens `keyof` to `string | number` — so the list is data,
+ * and this file is what makes the data true. Adding a field to `ActionDef`
+ * without adding it here fails, by name.
+ *
+ * Discrimination proof for the guard below: with `ACTION_DEF_KEYS` complete these
+ * pass; dropping any single entry (e.g. `target`) fails with
+ * "ActionDef declares keys the inventory is missing: target".
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import ts from 'typescript';
+import * as SpecUI from '@objectstack/spec/ui';
+import {
+  ACTION_DEF_KEYS,
+  SPEC_ACTION_KEYS,
+  NAVIGATION_ALIAS_KEYS,
+  RETIRED_ACTION_KEYS,
+  KNOWN_ACTION_KEYS,
+  classifyActionKeys,
+  warnOnUnknownActionKeys,
+  resetActionKeyWarnings,
+} from '../actionKeys';
+
+const RUNNER = join(dirname(fileURLToPath(import.meta.url)), '..', 'ActionRunner.ts');
+
+/** `ActionDef`'s declared property names, read off the interface itself. */
+function declaredActionDefKeys(): string[] {
+  const sf = ts.createSourceFile(RUNNER, readFileSync(RUNNER, 'utf8'), ts.ScriptTarget.Latest, true);
+  for (const stmt of sf.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'ActionDef') continue;
+    return stmt.members
+      .filter(ts.isPropertySignature)
+      .map((m) => (m.name && (ts.isIdentifier(m.name) || ts.isStringLiteral(m.name)) ? m.name.text : null))
+      .filter((n): n is string => n !== null);
+  }
+  throw new Error('ActionDef interface not found in ActionRunner.ts');
+}
+
+/**
+ * The spec's `ActionSchema` keys. `ActionSchema` is a lazy proxy that does not
+ * forward `.shape`, so this walks zod internals to reach the object shape —
+ * acceptable HERE (a test pins a fact) and deliberately not done in shipped code.
+ */
+function specActionKeys(): string[] {
+  const seen = new Set<unknown>();
+  const walk = (schema: unknown, depth = 0): string[] | null => {
+    if (!schema || depth > 8 || seen.has(schema)) return null;
+    seen.add(schema);
+    const s = schema as Record<string, any>;
+    if (s.shape) return Object.keys(s.shape);
+    const def = s._def ?? s.def;
+    if (!def) return null;
+    if (def.shape) return Object.keys(def.shape);
+    for (const key of ['in', 'out', 'innerType', 'schema', 'left', 'right']) {
+      const found = def[key] ? walk(def[key], depth + 1) : null;
+      if (found) return found;
+    }
+    return null;
+  };
+  const keys = walk(SpecUI.ActionSchema);
+  if (!keys) throw new Error('could not resolve @objectstack/spec/ui ActionSchema shape');
+  return keys;
+}
+
+describe('action key inventory (objectstack#4075 step 1)', () => {
+  it('ActionDef still has the index signature this inventory compensates for', () => {
+    // The day this fails, step 3 has landed: `tsc` catches unknown keys itself
+    // and the dev-mode warning (plus `executeScript`'s rename branch) can retire.
+    expect(readFileSync(RUNNER, 'utf8')).toContain('[key: string]: any');
+  });
+
+  it('lists every key ActionDef declares', () => {
+    const declared = declaredActionDefKeys();
+    const missing = declared.filter((k) => !(ACTION_DEF_KEYS as readonly string[]).includes(k));
+    const stale = (ACTION_DEF_KEYS as readonly string[]).filter((k) => !declared.includes(k));
+    expect({ missing, stale }).toEqual({ missing: [], stale: [] });
+  });
+
+  it('lists every key the spec ActionSchema declares', () => {
+    const spec = specActionKeys();
+    const missing = spec.filter((k) => !(SPEC_ACTION_KEYS as readonly string[]).includes(k));
+    const stale = (SPEC_ACTION_KEYS as readonly string[]).filter((k) => !spec.includes(k));
+    // `missing` means the spec grew a key objectui does not know about; `stale`
+    // means it dropped one. Either way the inventory has to be re-derived, and
+    // the diff names exactly which key moved.
+    expect({ missing, stale }).toEqual({ missing: [], stale: [] });
+  });
+
+  it('`execute` is still a live spec tombstone, so it must not count as known', () => {
+    const parsed = SpecUI.ActionSchema.safeParse({
+      name: 'mark_done',
+      label: 'Mark Done',
+      type: 'script',
+      execute: 'markDone',
+    });
+    expect(parsed.success).toBe(false);
+    expect(RETIRED_ACTION_KEYS).toHaveProperty('execute');
+    expect(KNOWN_ACTION_KEYS.has('execute')).toBe(false);
+  });
+
+  it('keeps the navigation alias out of the spec vocabulary it is not part of', () => {
+    // If the spec ever adopts one of these, it stops being objectui dialect and
+    // this fails — naming the alias to retire, the same tripwire shape as
+    // `ObjectUiLocalActionType`.
+    const spec = specActionKeys();
+    expect(NAVIGATION_ALIAS_KEYS.filter((k) => spec.includes(k))).toEqual([]);
+  });
+});
+
+describe('unknown-key warning', () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    resetActionKeyWarnings();
+    warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+  afterEach(() => warn.mockRestore());
+
+  it('says nothing about an action built only from recognized keys', () => {
+    warnOnUnknownActionKeys({ name: 'save', type: 'api', target: '/api/v1/save', locations: ['record_header'] });
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('names a typo that the compiler cannot see', () => {
+    // `targt` type-checks today: ActionDef's index signature accepts it. Nothing
+    // reads it, so the action runs and does nothing — #2169's shape.
+    warnOnUnknownActionKeys({ name: 'save', type: 'script', targt: 'saveRecord' });
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain('`targt`');
+  });
+
+  it('gives a retired key its rename prescription, not a bare "unknown"', () => {
+    warnOnUnknownActionKeys({ name: 'mark_done', type: 'script', execute: 'markDone' });
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain('rename the key to `target`');
+  });
+
+  it('warns once per key, not once per click', () => {
+    for (let i = 0; i < 5; i++) warnOnUnknownActionKeys({ name: 'save', type: 'script', targt: 'x' });
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('is silent in production', () => {
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+    try {
+      warnOnUnknownActionKeys({ name: 'save', type: 'script', targt: 'x' });
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      process.env.NODE_ENV = prev;
+    }
+  });
+
+  it('classifies unknown and retired keys separately', () => {
+    expect(classifyActionKeys({ type: 'script', execute: 'a', targt: 'b' })).toEqual({
+      unknown: ['targt'],
+      retired: ['execute'],
+    });
+  });
+});