feat(spec,runtime): single-source API-method derivation table (#3391 PR-1)

Introduce the spec's one source of truth for turning an object's
`enable.apiMethods` whitelist into its effective operation set, and make the
runtime dispatcher gate consume it.

- spec: new `@objectstack/spec/data` `api-derivation` module —
  `resolveEffectiveApiMethods` / `isApiOperationAllowed` /
  `effectiveOperationsArray` / `API_METHOD_DERIVATION` /
  `DATA_ACTION_TO_API_OPERATION`. Three-state semantics (undefined =
  unrestricted, [] = deny-all, subset = derived closure); the legacy 8 verbs
  derive from the six primitives (get/list/create/update/delete/bulk).
  restore/purge never derive (enable.trash retired, #2377). liveness note
  updated.
- runtime: rewrite `api-exposure.ts` to consume the shared table. Fixes the
  silent dead dispatcher/MCP gate — `getObject()` returns the flags nested
  under `.enable`, which the flat-only reader ignored (nested-first, flat-
  compatible). Flips `[]` from fail-open to deny-all.
- objectql: registration-time deprecation warning for standalone legacy
  apiMethods values (`warnDeprecatedExplicitApiMethods`); cross-reference
  comments distinguishing the verb→affordance (UI-intent) axis from the
  verb→primitive (API-tightening) axis.
- plugin-security: cross-reference comment on the parallel WRITE_OP_AFFORDANCE.

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

Author: claude

packages/objectql/src/registry.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { SchemaRegistry, applySystemFields, reconcileManagedApiMethods, computeFQN, parseFQN } from './registry';
+import { SchemaRegistry, applySystemFields, reconcileManagedApiMethods, warnDeprecatedExplicitApiMethods, computeFQN, parseFQN } from './registry';
 
 describe('SchemaRegistry', () => {
     let registry: SchemaRegistry;
@@ -846,3 +846,47 @@ describe('reconcileManagedApiMethods', () => {
         expect(stored.enable.apiMethods).toEqual(['get', 'list']);
     });
 });
+
+// ==========================================
+// warnDeprecatedExplicitApiMethods — #3391
+// One-shot deprecation warning for standalone LEGACY apiMethods values (the
+// derived 8). Pure observation — never mutates the schema.
+// ==========================================
+describe('warnDeprecatedExplicitApiMethods (#3391)', () => {
+    it('warns when a whitelist declares a derived legacy value (import/export)', () => {
+        const warn = vi.fn();
+        warnDeprecatedExplicitApiMethods(
+            { name: 'crm_deal_a', enable: { apiMethods: ['get', 'list', 'create', 'update', 'delete', 'import', 'export'] } } as any,
+            { warn },
+        );
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(warn.mock.calls[0][0]).toContain('crm_deal_a');
+        expect(warn.mock.calls[0][0]).toContain('import');
+        expect(warn.mock.calls[0][0]).toContain('export');
+        expect(warn.mock.calls[0][0]).toContain('#3391');
+    });
+
+    it('stays silent for a pure-primitive whitelist', () => {
+        const warn = vi.fn();
+        warnDeprecatedExplicitApiMethods(
+            { name: 'crm_deal_b', enable: { apiMethods: ['get', 'list', 'create', 'update', 'delete', 'bulk'] } } as any,
+            { warn },
+        );
+        expect(warn).not.toHaveBeenCalled();
+    });
+
+    it('stays silent for an undefined / empty whitelist', () => {
+        const warn = vi.fn();
+        warnDeprecatedExplicitApiMethods({ name: 'crm_deal_c', enable: {} } as any, { warn });
+        warnDeprecatedExplicitApiMethods({ name: 'crm_deal_d', enable: { apiMethods: [] } } as any, { warn });
+        expect(warn).not.toHaveBeenCalled();
+    });
+
+    it('warns only once per object name (hot path stays free)', () => {
+        const warn = vi.fn();
+        const schema: any = { name: 'crm_deal_once', enable: { apiMethods: ['list', 'aggregate'] } };
+        warnDeprecatedExplicitApiMethods(schema, { warn });
+        warnDeprecatedExplicitApiMethods(schema, { warn });
+        expect(warn).toHaveBeenCalledTimes(1);
+    });
+});

packages/objectql/src/registry.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { ServiceObject, ObjectSchema, ObjectOwnership, provisionPrimary, resolveCrudAffordances, isTenancyDisabled } from '@objectstack/spec/data';
+import { ServiceObject, ObjectSchema, ObjectOwnership, provisionPrimary, resolveCrudAffordances, isTenancyDisabled, LEGACY_API_METHODS } from '@objectstack/spec/data';
 import { resolveMultiOrgEnabled, resolveSearchPinyinEnabled } from '@objectstack/types';
 import { provisionSearchCompanion } from './search-companion.js';
 import { ObjectStackManifest, ManifestSchema, InstalledPackage, InstalledPackageSchema } from '@objectstack/spec/kernel';
@@ -389,6 +389,16 @@ export function applySystemFields(
  * Generic-write `apiMethods` verbs mapped to the {@link resolveCrudAffordances}
  * flag each one needs. Read verbs (`get`/`list`/`search`/`history`/…) are
  * always permitted, so they are absent here and never stripped.
+ *
+ * ⚠️ Two orthogonal axes — do NOT merge this with the API-tightening table.
+ * This table (verb → *affordance*) is the UI-intent axis: it strips write verbs
+ * a managed bucket does not *offer* from the whitelist. The verb → *primitive*
+ * derivation that decides what the automatic API *admits* lives in
+ * `@objectstack/spec/data` `API_METHOD_DERIVATION` / `resolveEffectiveApiMethods`
+ * (#3391). The identical-shaped `WRITE_OP_AFFORDANCE` in plugin-security
+ * `system-write-guard.ts` is the runtime enforcement of this same UI-intent
+ * axis. Unifying the three is deferred to the enum-shrink (P2 of #3391); until
+ * then keep the axes separate — see ADR-0103.
  */
 const MANAGED_WRITE_VERB_AFFORDANCE: Record<string, 'create' | 'edit' | 'delete'> = {
   create: 'create',
@@ -463,6 +473,43 @@ export function reconcileManagedApiMethods(
   };
 }
 
+/** Objects already warned about explicit legacy `apiMethods` (once per object). */
+const warnedDeprecatedApiMethods = new Set<string>();
+
+/**
+ * Registration-time deprecation warning for standalone LEGACY `apiMethods`
+ * values (#3391). The 8 legacy verbs (`upsert`/`aggregate`/`history`/`search`/
+ * `restore`/`purge`/`import`/`export`) are DERIVED from the six primitives; an
+ * object that declares one explicitly is honored verbatim for one release
+ * ("explicit wins"), then the value is removed in the enum-shrink (P2 of #3391).
+ *
+ * Emitted once per object (not per request — the hot path stays free), mirroring
+ * the {@link reconcileManagedApiMethods} warning format and pointing at P2. Pure
+ * observation: it never mutates the schema.
+ */
+export function warnDeprecatedExplicitApiMethods(
+  schema: ServiceObject,
+  opts?: { warn?: (msg: string) => void },
+): void {
+  const methods = (schema as any).enable?.apiMethods;
+  if (!Array.isArray(methods) || methods.length === 0) return;
+  const legacy = methods.filter((m: string) => (LEGACY_API_METHODS as readonly string[]).includes(m));
+  if (legacy.length === 0) return;
+  const name = String((schema as any).name ?? '');
+  if (warnedDeprecatedApiMethods.has(name)) return;
+  warnedDeprecatedApiMethods.add(name);
+  const warn = opts?.warn ?? ((msg: string) => console.warn(msg));
+  warn(
+    `[Registry] Object "${name}" declares derived legacy apiMethods value(s) ` +
+      `[${legacy.join(', ')}] in enable.apiMethods — these derive from the six ` +
+      `primitives (get/list/create/update/delete/bulk) and are honored verbatim ` +
+      `for now, but standalone declaration is deprecated and will be removed in ` +
+      `the enum-shrink (P2 of #3391). Declare the underlying primitives instead ` +
+      `(e.g. ['create','update'] grants upsert/import; ['list'] grants ` +
+      `aggregate/export/search).`,
+  );
+}
+
 /**
  * Platform namespaces that multiple packages may legitimately share, so the
  * install-time namespace-uniqueness gate (ADR-0048 Phase 1) must never fire on
@@ -714,6 +761,11 @@ export class SchemaRegistry {
     // every non-`better-auth` object.
     schema = reconcileManagedApiMethods(schema);
 
+    // [#3391] One-shot deprecation warning for standalone LEGACY apiMethods
+    // values (the derived 8) — honored this release, removed in the enum-shrink.
+    // Runs after reconcile so we warn about what actually ships.
+    warnDeprecatedExplicitApiMethods(schema);
+
     // [ADR-0079] Object-materialization seam — DESIGNATE-ONLY primary-title
     // provisioning. Runs AFTER `applySystemFields` (so any designated field
     // co-exists with the injected system columns) and ONLY for owned objects

packages/plugins/plugin-security/src/system-write-guard.ts

@@ -52,6 +52,12 @@ export const ENGINE_OWNED_BUCKETS: ReadonlySet<string> = new Set(['system', 'eng
  * Read ops (`find`/`findOne`/`count`/`aggregate`/…) are absent and always pass.
  * Aligned with the `DelegatedAdminGate` governed-operation set and the registry's
  * `MANAGED_WRITE_VERB_AFFORDANCE`.
+ *
+ * ⚠️ This is the UI-intent axis (verb → *affordance*), NOT the API-tightening
+ * axis. What the automatic API *admits* is decided by the verb → *primitive*
+ * derivation in `@objectstack/spec/data` (`resolveEffectiveApiMethods`, #3391) —
+ * a separate table on a separate axis (ADR-0103). Merging the two is deferred to
+ * the enum-shrink (P2 of #3391); keep them distinct until then.
  */
 const WRITE_OP_AFFORDANCE: Record<string, 'create' | 'edit' | 'delete'> = {
   insert: 'create',

packages/runtime/src/api-exposure.test.ts

@@ -50,12 +50,69 @@ describe('checkApiExposure (#1889)', () => {
       expect(d.status).toBe(405);
     });
 
-    it('an empty whitelist is treated as no restriction', () => {
-      expect(checkApiExposure({ apiMethods: [] }, 'create').allowed).toBe(true);
+    it('an empty whitelist is deny-all (405) — flipped by #3391', () => {
+      // Previously treated as "no restriction" (fail-open); the documented
+      // three-state contract makes `[]` mean "expose nothing".
+      const d = checkApiExposure({ apiMethods: [] }, 'create');
+      expect(d.allowed).toBe(false);
+      expect(d.status).toBe(405);
+      // every operation is closed
+      expect(checkApiExposure({ apiMethods: [] }, 'query').allowed).toBe(false);
+      expect(checkApiExposure({ apiMethods: [] }, 'get').allowed).toBe(false);
     });
 
     it('does not gate actions with no ApiMethod mapping', () => {
       expect(checkApiExposure({ apiMethods: ['list'] }, 'somethingCustom').allowed).toBe(true);
     });
+
+    it('surfaces the effective operation set on a 405 denial', () => {
+      const d = checkApiExposure({ apiMethods: ['get', 'list'] }, 'create');
+      expect(d.allowed).toBe(false);
+      expect(d.allowedOperations).toContain('get');
+      expect(d.allowedOperations).toContain('list');
+      // list-class derived reads are exposed too
+      expect(d.allowedOperations).toContain('aggregate');
+      expect(d.allowedOperations).toContain('export');
+      expect(d.allowedOperations).not.toContain('create');
+    });
+  });
+
+  describe('nested enable shape (getObject) — regression for #3391', () => {
+    // meta.getObject() returns the whole schema with the exposure flags under
+    // `.enable`. The previous flat-only reader ignored them → a dead gate.
+    it('reads apiEnabled from the nested enable block (404)', () => {
+      const d = checkApiExposure({ name: 'x', enable: { apiEnabled: false } } as any, 'get');
+      expect(d.allowed).toBe(false);
+      expect(d.status).toBe(404);
+    });
+
+    it('reads apiMethods from the nested enable block (405)', () => {
+      const def = { name: 'x', enable: { apiMethods: ['list', 'get'] } } as any;
+      expect(checkApiExposure(def, 'query').allowed).toBe(true);
+      const d = checkApiExposure(def, 'create');
+      expect(d.allowed).toBe(false);
+      expect(d.status).toBe(405);
+    });
+
+    it('nested empty whitelist is deny-all', () => {
+      const def = { name: 'x', enable: { apiMethods: [], apiEnabled: true } } as any;
+      expect(checkApiExposure(def, 'get').allowed).toBe(false);
+      expect(checkApiExposure(def, 'query').allowed).toBe(false);
+    });
+  });
+
+  describe('derivation-backed operations (#3391)', () => {
+    it('import derives from create/update (writeMode-precise)', () => {
+      const createOnly = { apiMethods: ['create'] };
+      expect(checkApiExposure(createOnly, 'import', { writeMode: 'insert' }).allowed).toBe(true);
+      expect(checkApiExposure(createOnly, 'import', { writeMode: 'update' }).allowed).toBe(false);
+    });
+
+    it('bulk requires the bulk primitive AND the child op', () => {
+      const bulkCreate = { apiMethods: ['create', 'bulk'] };
+      expect(checkApiExposure(bulkCreate, 'batch', { bulkChild: 'create' }).allowed).toBe(true);
+      const createOnly = { apiMethods: ['create'] };
+      expect(checkApiExposure(createOnly, 'batch', { bulkChild: 'create' }).allowed).toBe(false);
+    });
   });
 });

packages/runtime/src/api-exposure.ts

@@ -1,75 +1,108 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * Object-level API exposure gate (ADR-0049, #1889).
+ * Object-level API exposure gate (ADR-0049, #1889, #3391).
  *
  * Objects declare `apiEnabled` (default true) and an optional `apiMethods`
- * whitelist, but the HTTP/MCP data dispatch previously ignored both — an object
- * could not actually be hidden from the API, nor could its allowed operations
- * be restricted. This module decides, for a given data action, whether the
- * object's declared exposure permits it.
+ * whitelist. The HTTP/MCP data dispatch decides, for a given data action,
+ * whether the object's declared exposure permits it. Both fields live in the
+ * object's `enable` capability block.
  *
- * Both fields are *additive restrictions* over a default-allow surface
- * (`apiEnabled` defaults true; absent `apiMethods` means "all operations").
- * Therefore an unresolvable object definition fails OPEN here — that matches
- * the schema defaults and avoids breaking traffic when metadata is briefly
- * unavailable. The gate is a no-op for system/internal contexts (callers pass
- * `isSystem` and skip this check entirely).
+ * ## What #3391 changed here
+ *
+ * 1. **Nested-first shape.** `meta.getObject()` returns the full object schema
+ *    with `apiEnabled`/`apiMethods` under `.enable`. The previous version read
+ *    them off the *flat* top level, so the dispatcher/MCP whitelist never fired
+ *    (a silent dead gate). We now read `def.enable` first, falling back to the
+ *    flat shape for legacy/test doubles.
+ * 2. **Shared derivation.** The action→operation mapping and the three-state
+ *    whitelist semantics are no longer duplicated here — they come from the
+ *    spec's single source of truth (`@objectstack/spec/data`
+ *    `resolveEffectiveApiMethods` / `isApiOperationAllowed`).
+ * 3. **`[]` = deny-all.** An empty whitelist now means "expose nothing" (405),
+ *    matching the documented three-state contract, instead of the prior
+ *    fail-open "no restriction".
+ *
+ * An unresolvable object definition still fails OPEN — that matches the schema
+ * defaults (`apiEnabled` true, no `apiMethods`) and avoids breaking traffic when
+ * metadata is briefly unavailable. The gate is a no-op for system/internal
+ * contexts (callers pass `isSystem` and skip this check entirely).
  */
 
-/** The exposure-relevant slice of an object definition. */
+import {
+  resolveEffectiveApiMethods,
+  isApiOperationAllowed,
+  effectiveOperationsArray,
+  DATA_ACTION_TO_API_OPERATION,
+  type EnableLike,
+} from '@objectstack/spec/data';
+
+/** The exposure-relevant slice of an object definition (flat or nested). */
 export interface ObjectApiDef {
   apiEnabled?: boolean;
   apiMethods?: string[] | null;
+  /** Real `getObject()` shape — the exposure flags live under `enable`. */
+  enable?: EnableLike | null;
+  [key: string]: unknown;
 }
 
 export interface ApiExposureDecision {
   allowed: boolean;
   /** HTTP status to return when denied (404 hides, 405 = method not allowed). */
   status?: number;
   reason?: string;
+  /** The effective operation set (enum-ordered) — surfaced on a 405 denial. */
+  allowedOperations?: string[];
 }
 
 /**
- * Map an internal `callData` action onto the spec `ApiMethod` vocabulary
- * (`object.zod.ts` → `ApiMethod`). Actions with no mapping are not gated by
- * `apiMethods` (they still respect `apiEnabled`).
+ * Resolve the `enable` capability block from either the nested `getObject()`
+ * shape (`{ enable: {...} }`) or a flat legacy/test shape (`{ apiEnabled, ... }`).
+ * Nested wins when present.
  */
-const ACTION_TO_API_METHOD: Record<string, string> = {
-  create: 'create',
-  get: 'get',
-  update: 'update',
-  delete: 'delete',
-  query: 'list',
-  find: 'list',
-  // Aggregation is a list-class read: an object whose whitelist excludes
-  // `list` must not leak row statistics through GROUP BY either.
-  aggregate: 'list',
-  batch: 'bulk',
-};
+function resolveEnableBlock(def: ObjectApiDef): EnableLike {
+  if (def.enable && typeof def.enable === 'object') return def.enable;
+  return def as EnableLike;
+}
 
-export function checkApiExposure(def: ObjectApiDef | null | undefined, action: string): ApiExposureDecision {
+/**
+ * Decide whether a data `action` is permitted for `def`'s declared exposure.
+ *
+ * @param def    Object definition (nested `getObject` shape or flat).
+ * @param action Runtime data action (`create`/`get`/`query`/`find`/`aggregate`/
+ *               `batch`/…); normalized to a canonical operation internally.
+ * @param opts   Optional `writeMode` (import precision) / `bulkChild` (bulk∧child).
+ */
+export function checkApiExposure(
+  def: ObjectApiDef | null | undefined,
+  action: string,
+  opts?: { writeMode?: string; bulkChild?: string },
+): ApiExposureDecision {
   // Unresolvable definition → fall open to the schema defaults.
   if (!def) return { allowed: true };
 
+  const enable = resolveEnableBlock(def);
+
   // `apiEnabled: false` hides the object from the API entirely → 404.
-  if (def.apiEnabled === false) {
+  if (enable.apiEnabled === false) {
     return { allowed: false, status: 404, reason: 'object is not exposed via the API' };
   }
 
-  // `apiMethods` whitelist (when present and non-empty) restricts operations.
-  const whitelist = def.apiMethods;
-  if (Array.isArray(whitelist) && whitelist.length > 0) {
-    const method = ACTION_TO_API_METHOD[action];
-    // Only gate actions that map to a known ApiMethod; unmapped actions pass.
-    if (method && !whitelist.includes(method)) {
-      return {
-        allowed: false,
-        status: 405,
-        reason: `API operation '${method}' is not allowed for this object`,
-      };
-    }
-  }
+  const eff = resolveEffectiveApiMethods(enable);
+  // Unrestricted (no whitelist) → allow everything, exactly as before.
+  if (eff.mode === 'unrestricted') return { allowed: true };
+
+  // Normalize the runtime action onto a canonical ApiMethod operation. An
+  // action with no mapping is not gated by `apiMethods` (respects `apiEnabled`
+  // only), preserving the prior behavior for custom actions.
+  const operation = DATA_ACTION_TO_API_OPERATION[action] ?? action;
+
+  if (isApiOperationAllowed(eff, operation, opts)) return { allowed: true };
 
-  return { allowed: true };
+  return {
+    allowed: false,
+    status: 405,
+    reason: `API operation '${operation}' is not allowed for this object`,
+    allowedOperations: effectiveOperationsArray(eff),
+  };
 }

packages/spec/liveness/object.json

@@ -153,8 +153,8 @@
         },
         "apiMethods": {
           "status": "live",
-          "evidence": "packages/rest/src/rest-server.ts",
-          "note": "enforced by enforceApiAccess — operations outside the whitelist → 405."
+          "evidence": "packages/spec/src/data/api-derivation.ts, packages/rest/src/rest-server.ts, packages/runtime/src/api-exposure.ts",
+          "note": "three-state whitelist over the six primitives (get/list/create/update/delete/bulk): undefined = unrestricted, [] = deny-all (fully closed), subset = the derived closure. resolveEffectiveApiMethods (the single derivation table) is consumed by the REST gate (405 outside the effective set) and the runtime dispatcher gate; the legacy 8 values (upsert/aggregate/history/search/restore/purge/import/export) are DERIVED, not declared standalone (#3391)."
         },
         "trackHistory": {
           "status": "live",