@mettlecast/domain-cli 0.2.60 → 0.2.62

package/src/commands/explain.ts

@@ -58,25 +58,25 @@ const RULE_EXPLANATIONS: Record<string, RuleExplanation> = {
     ruleId: 'no-raw-http-server',
     title: 'No raw HTTP server in domain code',
     description:
-      'Domain code must not create raw HTTP servers (express, fastify, etc.). All HTTP handling goes through defineApi which is wired to API Gateway by the scaffold.',
+      'Domain code must not create raw HTTP servers (express, fastify, etc.). All HTTP handling goes through defineAction with exposure.type=\'api\' which is wired to API Gateway by the scaffold.',
     severity: 'error',
     category: 'structure',
     kNodeRef: 'K:convention:tier-1-foundations',
-    fixHint: 'Wrap your HTTP handler with defineApi({ ... }). The scaffold handles API Gateway wiring.',
+    fixHint: 'Wrap your HTTP handler with defineAction({ exposure: { type: \'api\', ... } }). The scaffold handles API Gateway wiring.',
     exampleBad: "import express from 'express';\nconst app = express();",
-    exampleGood: "export const myApi = defineApi({ id: 'my-api', path: '/v1/my-api', ... });",
+    exampleGood: "export const myAction = defineAction({ id: 'my-action', exposure: { type: 'api', path: '/v1/my-action', method: 'GET', auth: 'required', tenancy: 'required' }, ... });",
   },
   'require-define-primitive': {
     ruleId: 'require-define-primitive',
     title: 'Require define primitive factories',
     description:
-      'All domain handlers must use the appropriate factory function: defineApi for HTTP APIs, defineSubscriber for event subscribers, defineAction for cross-domain actions, defineJob for background jobs.',
+      'All domain handlers must use the appropriate factory function: defineAction (HTTP APIs via exposure.type=\'api\', or internal-only actions), defineSubscriber for event subscribers, defineJob for background jobs, defineWebhook for webhooks, defineEvent for event types.',
     severity: 'error',
     category: 'structure',
     kNodeRef: 'K:runbook:add-domain',
     fixHint: "Wrap your handler with the appropriate define* factory from @mettlecast/domain-runtime.",
     exampleBad: "export const handler = async (event) => ({ statusCode: 200 });",
-    exampleGood: "export const myApi = defineApi({ id: 'my-api', ... });",
+    exampleGood: "export const myAction = defineAction({ id: 'my-action', exposure: { type: 'api', ... }, ... });",
   },
   'flow-domain-ownership': {
     ruleId: 'flow-domain-ownership',
@@ -106,25 +106,25 @@ const RULE_EXPLANATIONS: Record<string, RuleExplanation> = {
     ruleId: 'apis-have-versions',
     title: 'APIs declare versions',
     description:
-      'Every defineApi must have a versions field with at least one version entry. Versioning is mandatory for API evolution.',
+      'Every API-exposed action (defineAction with exposure.type=\'api\') must declare input and output Zod schemas with .default() so the runtime has a concrete example payload. The action-first contract replaced legacy defineApi\'s versions map (#4689).',
     severity: 'error',
     category: 'correctness',
     kNodeRef: 'K:runbook:add-domain',
-    fixHint: 'Add versions: { v1: { status, input, output, handler } } to your defineApi call.',
-    exampleBad: "defineApi({ id: 'my-api', path: '/v1/my-api' }) // missing versions",
-    exampleGood: "defineApi({ id: 'my-api', path: '/v1/my-api', versions: { v1: { ... } } });",
+    fixHint: 'Add Zod input/output schemas to your defineAction call (e.g. z.object({...}).default({...})).',
+    exampleBad: "defineAction({ id: 'my-action', exposure: { type: 'api', path: '/v1/my-action', ... }, handler: ... }) // missing input/output schemas",
+    exampleGood: "defineAction({ id: 'my-action', exposure: { type: 'api', ... }, input: z.object({...}).default({...}), output: z.object({...}).default({...}), handler: ... });",
   },
   'apis-have-tenancy': {
     ruleId: 'apis-have-tenancy',
     title: 'APIs declare tenancy',
     description:
-      'Every defineApi must declare its tenancy mode: required (tenant-scoped), none (tenant-agnostic like registration), or system (system-internal admin).',
+      'Every defineAction with exposure.type=\'api\' must declare exposure.tenancy: required (tenant-scoped), none (tenant-agnostic like registration), or system (system-internal admin). The action-first contract enforces this at registration time (#4689).',
     severity: 'error',
     category: 'correctness',
     kNodeRef: 'K:convention:tier-1-foundations',
-    fixHint: "Add tenancy: 'required' | 'none' | 'system' to your defineApi call.",
-    exampleBad: "defineApi({ id: 'my-api', path: '/v1/my-api' }) // missing tenancy",
-    exampleGood: "defineApi({ id: 'my-api', path: '/v1/my-api', tenancy: 'required' });",
+    fixHint: "Add `exposure.tenancy: 'required' | 'none' | 'system'` to your defineAction call.",
+    exampleBad: "defineAction({ id: 'my-action', exposure: { type: 'api', path: '/v1/my-action' }, ... }) // missing exposure.tenancy",
+    exampleGood: "defineAction({ id: 'my-action', exposure: { type: 'api', path: '/v1/my-action', method: 'GET', auth: 'required', tenancy: 'required' }, ... });",
   },
   'no-cross-domain-imports': {
     ruleId: 'no-cross-domain-imports',

package/src/commands/generate-openapi.ts

@@ -1,7 +1,12 @@
 /**
  * generate-openapi — read a domain's registry and produce an OpenAPI 3.1
  * specification as JSON. The registry is consumed at build time; each
- * `defineApi` entry contributes one path under the domain's route prefix.
+ * `defineAction({ exposure: { type: 'api', ... } })` entry contributes
+ * one path under the domain's route prefix.
+ *
+ * Issue #4689: the legacy `defineApi` factory was removed and the
+ * `registry.apis` slot is now always empty in new registries. This
+ * command therefore reads exclusively from `actions[]`.
  *
  * Usage: npx mc-domain-module generate-openapi <domain>
  */
@@ -17,51 +22,24 @@ export interface GenerateOpenapiOptions {
   output?: string;
 }
 
-interface ApiRegistryEntry {
-  id: string;
-  path: string;
-  method: string;
-  tenancy: string;
-  versions: Record<string, {
-    status: string;
-    inputSchema?: unknown;
-    outputSchema?: unknown;
-    input?: unknown;
-    output?: unknown;
-  }>;
-  examples?: { request?: unknown; response?: unknown };
-}
-
 interface DomainRegistry {
   domain: { id: string };
-  apis: ApiRegistryEntry[];
+  actions: Array<{
+    id: string;
+    exposure?: {
+      type: 'api' | 'internal';
+      path?: string;
+      method?: string;
+    };
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+  }>;
 }
 
 /**
- * Extract a Zod schema shape from a registry entry version.
- * The registry may store schemas as `input`/`output` (raw Zod
- * objects) or `inputSchema`/`outputSchema` (JSON Schema shapes).
- * Returns a best-effort JSON Schema object for the OpenAPI spec.
+ * Run the generate-openapi command: read the domain's registry and emit
+ * an OpenAPI 3.1 spec covering every API-exposed action.
  */
-function extractSchema(version: ApiRegistryEntry['versions'][string], field: 'input' | 'output'): unknown {
-  // Prefer JSON Schema if present
-  const schemaField = field === 'input' ? version.inputSchema : version.outputSchema;
-  if (schemaField && typeof schemaField === 'object' && schemaField !== null) {
-    return schemaField;
-  }
-  // Fall back to the raw Zod shape — try to produce a minimal JSON
-  // Schema from the Zod _def. For full support, add zod-to-json-schema
-  // to the CLI dependencies and call `zodToJsonSchema(zodSchema)`.
-  const raw = field === 'input' ? version.input : version.output;
-  if (raw && typeof raw === 'object' && raw !== null) {
-    // Attempt minimal mapping: if the Zod shape has a `type` field
-    // from its _def, describe it as JSON Schema.
-    const def = raw as { type?: string; items?: unknown; properties?: unknown; required?: string[] };
-    return { type: def.type ?? 'object', properties: def.properties, required: def.required };
-  }
-  return { type: 'object' };
-}
-
 export async function runGenerateOpenapi(options: GenerateOpenapiOptions): Promise<string> {
   const projectRoot = options.projectRoot ?? process.cwd();
   const domain = options.domain;
@@ -74,22 +52,22 @@ export async function runGenerateOpenapi(options: GenerateOpenapiOptions): Promi
 
   const paths: Record<string, unknown> = {};
 
-  for (const api of registry.apis) {
-    const method = (api.method ?? 'get').toLowerCase();
-    const fullPath = `/v1/${domain}${api.path}`;
-    const v1 = api.versions['v1'] ?? api.versions[Object.keys(api.versions)[0]];
-    if (!v1) continue;
+  for (const action of registry.actions ?? []) {
+    if (action.exposure?.type !== 'api') continue;
+    const method = (action.exposure.method ?? 'get').toLowerCase();
+    const fullPath = `/v1/${domain}${action.exposure.path}`;
+    const inputSchema = action.inputSchema ?? { type: 'object' };
+    const outputSchema = action.outputSchema ?? { type: 'object' };
 
     if (!paths[fullPath]) paths[fullPath] = {};
-
     (paths[fullPath] as Record<string, unknown>)[method] = {
-      operationId: `${domain}.${api.id}`,
-      summary: `${domain}.${api.id}`,
-      description: `Version: ${v1.status}`,
+      operationId: `${domain}.${action.id}`,
+      summary: `${domain}.${action.id}`,
+      description: 'Action-first contract (defineAction + exposure.type=api).',
       requestBody: {
         content: {
           'application/json': {
-            schema: extractSchema(v1, 'input'),
+            schema: inputSchema,
           },
         },
       },
@@ -98,7 +76,7 @@ export async function runGenerateOpenapi(options: GenerateOpenapiOptions): Promi
           description: 'OK',
           content: {
             'application/json': {
-              schema: extractSchema(v1, 'output'),
+              schema: outputSchema,
             },
           },
         },
@@ -151,4 +129,4 @@ export async function runGenerateOpenapiCli(domain: string, opts: { projectRoot?
   const outputPath = await runGenerateOpenapi({ domain, ...opts });
   // eslint-disable-next-line no-console
   console.log(`OpenAPI spec written to: ${outputPath}`);
-}
+}

package/src/commands/regenerate-modules-hashes.ts

@@ -0,0 +1,89 @@
+import { readFile, readdir, writeFile, mkdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the regenerate-modules-hashes command.
+ */
+export interface RegenerateModulesHashesOptions {
+  /** Root directory of the project (defaults to cwd). */
+  projectRoot?: string;
+}
+
+/**
+ * Manifest of infra/modules/ files with their SHA256 hashes.
+ */
+export interface ModulesHashesManifest {
+  /** Schema version. */
+  version: '1';
+  /** ISO timestamp when the manifest was generated. */
+  generatedAt: string;
+  /** Map of relative file path to SHA256 hex digest. */
+  files: Record<string, string>;
+}
+
+/**
+ * Walk infra/modules/, compute a SHA256 for every file, and write the result
+ * to .mc/modules-hashes.json. Used to refresh the scaffold drift baseline.
+ * @param opts Options including project root directory.
+ * @returns Absolute path to the written manifest file.
+ */
+export async function runRegenerateModulesHashes(
+  opts: RegenerateModulesHashesOptions = {},
+): Promise<string> {
+  const root = opts.projectRoot ?? process.cwd();
+  const mcDir = join(root, '.mc');
+  const manifestPath = join(mcDir, 'modules-hashes.json');
+  const modulesDir = join(root, 'infra', 'modules');
+
+  // Files/directories to skip when walking infra/modules/
+  const SKIP_NAMES = new Set(['node_modules', 'dist', 'cdk.out', 'package-lock.json', '.npmrc']);
+
+  /** Normalize CRLF → LF so hashes match across platforms (Windows vs Linux). */
+  function normalizeLineEndings(buf: Buffer): Buffer {
+    const str = buf.toString('utf8');
+    if (!str.includes('\r\n')) return buf;
+    return Buffer.from(str.replace(/\r\n/g, '\n'), 'utf8');
+  }
+
+  // Walk infra/modules/ and collect every file path
+  async function walk(dir: string): Promise<string[]> {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const files: string[] = [];
+    for (const entry of entries) {
+      if (SKIP_NAMES.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) files.push(...await walk(full));
+      else if (entry.isFile()) files.push(full);
+    }
+    return files;
+  }
+
+  const onDiskFiles = await walk(modulesDir);
+
+  // Compute SHA256 for each file (line-ending-normalised)
+  const files: Record<string, string> = {};
+  for (const absPath of onDiskFiles) {
+    const relPath = relative(root, absPath).replace(/\\/g, '/');
+    const content = await readFile(absPath);
+    const normalized = normalizeLineEndings(content);
+    files[relPath] = createHash('sha256').update(normalized).digest('hex');
+  }
+
+  const manifest: ModulesHashesManifest = {
+    version: '1',
+    generatedAt: new Date().toISOString(),
+    files,
+  };
+
+  await mkdir(mcDir, { recursive: true });
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+
+  cliLogger.info(
+    { path: manifestPath, fileCount: Object.keys(files).length },
+    'modules-hashes manifest regenerated',
+  );
+
+  return manifestPath;
+}

package/src/commands/show.ts

@@ -21,10 +21,10 @@ export interface ShowDomainOptions {
 const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
 
 /**
- * Represents a primitive entry (API, subscriber, action, or job).
+ * Represents a primitive entry (action, subscriber, or job).
  */
 interface PrimitiveEntry {
-  type: 'api' | 'subscriber' | 'action' | 'job';
+  type: 'subscriber' | 'action' | 'job';
   id: string;
   file: string;
 }
@@ -35,7 +35,6 @@ interface PrimitiveEntry {
 interface DomainSummary {
   domain: string;
   primitives: {
-    apis: PrimitiveEntry[];
     subscribers: PrimitiveEntry[];
     actions: PrimitiveEntry[];
     jobs: PrimitiveEntry[];
@@ -114,7 +113,6 @@ export async function runShowDomain(opts: ShowDomainOptions): Promise<DomainSumm
   }
 
   // Scan primitives
-  const apis = await scanPrimitives(join(domainDir, 'api'), 'api');
   const subscribers = await scanPrimitives(join(domainDir, 'subscribers'), 'subscriber');
   const actions = await scanPrimitives(join(domainDir, 'actions'), 'action');
   const jobs = await scanPrimitives(join(domainDir, 'jobs'), 'job');
@@ -155,7 +153,6 @@ export async function runShowDomain(opts: ShowDomainOptions): Promise<DomainSumm
   const summary: DomainSummary = {
     domain: opts.domain,
     primitives: {
-      apis,
       subscribers,
       actions,
       jobs,

package/src/commands/test.ts

@@ -38,7 +38,6 @@ export async function runTest(options: TestOptions): Promise<void> {
   const { registry } = await buildRegistry(domainRoot);
 
   const allEntries: RegistryEntry[] = [
-    ...registry.apis,
     ...registry.webhooks,
     ...registry.subscribers,
     ...registry.schedules,

package/src/commands/update-all.ts

@@ -0,0 +1,79 @@
+import { join } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+import { readScaffoldConfig } from '../utils/scaffold-config.js';
+import { runBuild } from './build.js';
+import { runBuildCatalog } from './build-catalog.js';
+import { runBuildFlows } from './build-flows.js';
+import { runBuildUi } from './build-ui.js';
+import { runRegenerateModulesHashes } from './regenerate-modules-hashes.js';
+import { runDoctor } from './doctor.js';
+
+/**
+ * Run the full scaffold update pipeline:
+ *   1. Build each domain registry from `.mc/scaffold-config.json`
+ *   2. Build the combined domain catalog
+ *   3. Build flows registry
+ *   4. Build UI manifests
+ *   5. Regenerate module hashes
+ *   6. Run doctor
+ *
+ * Per-domain build failures are logged and skipped so that one bad domain does
+ * not abort the whole pipeline. The remaining steps still run.
+ *
+ * @param opts - Optional projectRoot override. Defaults to cwd.
+ * @returns success derived from doctor pass/fail and a human-readable summary.
+ */
+export async function runUpdateAll(opts?: { projectRoot?: string }): Promise<{ success: boolean; summary: string }> {
+  const projectRoot = opts?.projectRoot ?? process.cwd();
+
+  cliLogger.info({ projectRoot }, 'update-all: starting');
+
+  // 1. Read scaffold-config to discover domains
+  const scaffoldConfig = await readScaffoldConfig(projectRoot);
+  const domainIds = scaffoldConfig.domainIds ?? [];
+
+  cliLogger.info({ domainCount: domainIds.length }, 'update-all: building domain registries');
+
+  // 2. Build each domain. Per-domain failures are logged and skipped.
+  for (const domainId of domainIds) {
+    const domainRoot = join(projectRoot, 'domains', domainId);
+    try {
+      cliLogger.info({ domainId, domainRoot }, 'update-all: building domain');
+      await runBuild({ domainRoot });
+    } catch (err) {
+      cliLogger.error(
+        { domainId, err: err instanceof Error ? err.message : String(err) },
+        'update-all: domain build failed — continuing',
+      );
+    }
+  }
+
+  // 3. Build catalog from .mc
+  const mcDir = join(projectRoot, '.mc');
+  cliLogger.info({ mcDir }, 'update-all: building domain catalog');
+  await runBuildCatalog(mcDir);
+
+  // 4. Build flows
+  cliLogger.info({ projectRoot }, 'update-all: building flows registry');
+  await runBuildFlows({ projectRoot });
+
+  // 5. Build UI manifests
+  cliLogger.info({ projectRoot }, 'update-all: building UI manifests');
+  await runBuildUi({ projectRoot });
+
+  // 6. Regenerate module hashes
+  cliLogger.info({ projectRoot }, 'update-all: regenerating module hashes');
+  await runRegenerateModulesHashes({ projectRoot });
+
+  // 7. Run doctor — final gate
+  cliLogger.info({ projectRoot }, 'update-all: running doctor');
+  const report = await runDoctor({ projectRoot });
+
+  cliLogger.info(
+    { pass: report.pass, exitCode: report.exitCode, checkCount: report.checks.length },
+    'update-all: doctor complete',
+  );
+
+  const summary = `Updated ${domainIds.length} domains; doctor ${report.pass ? 'PASS' : 'FAIL'}`;
+  return { success: report.pass, summary };
+}

package/src/commands/upgrade-backend.ts

@@ -22,10 +22,10 @@ const MIGRATIONS: Migration[] = [
   {
     fromMajor: 1,
     toMajor: 2,
-    description: 'Migrate defineApi from v1 to v2: rename `versions.v1.handler` shape',
+    description: 'Audit v1 domain backends for action-first API exposure requirements',
     transform(repoRoot: string, dryRun: boolean): void {
-      // Placeholder: real migration uses ts-morph to rewrite handler signatures
-      console.log(`[G20] Would apply: defineApi v1→v2 migration in ${repoRoot}/domains/**`);
+      // Placeholder: real migration uses ts-morph to rewrite handler signatures.
+      console.log(`[G20] Would audit action-first API exposure in ${repoRoot}/domains/**`);
       if (!dryRun) {
         console.log('[G20] ts-morph transform: (not yet implemented — add jscodeshift transforms here)');
       }

package/src/commands/validate.ts

@@ -149,44 +149,17 @@ async function checkRawPathViolations(
  * Each rule maps 1:1 to an aspect annotation code so downstream tooling
  * can correlate build-time and synth-time failures.
  *
- * NOTE on `SECURITY_MISSING_SECURITY_EXCEPTION` for legacy `defineApi`
- * entries: the registry builder does not propagate `securityException`
- * from legacy source — that field only exists on action-style API
- * exposures, which are covered by the existing `AUTH_NONE_REQUIRES_EXCEPTION`
- * rule in `checkActionFirstSecurity`. The aspect's corresponding check
- * (`assertAnonymousRoutesHaveException`) catches the legacy case at
- * synth time so a developer migrating to action-style APIs gets the
- * right guidance at the right layer.
+ * Issue #4689: the legacy `defineApi` factory and `registry.apis` field
+ * were removed. Deployment-time API invariants are enforced against the
+ * `actions[]` API-exposure surface — see `checkActionFirstSecurity`.
  */
-function checkDeploymentSecurity(
-  apis: import('@mettlecast/domain-cdk-packer').ApiRegistryEntry[],
-  actions: ActionRegistryEntry[],
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-
-  for (const api of apis) {
-    // Non-anonymous APIs whose path lacks the tenant placeholder cannot
-    // bind `ctx.tenant.id` from the URL. The aspect surfaces this as
-    // `SECURITY_MISSING_TENANT_PATH`; the CLI version is a faster gate so
-    // CI doesn't pay the synth cost.
-    if (api.authType !== 'none' && !api.path.includes('/v1/tenants/{tenantId}/')) {
-      errors.push({
-        code: 'SECURITY_MISSING_TENANT_PATH',
-        message: `API '${api.id}' (${api.method} ${api.path}) is JWT-protected but its path does not include the canonical '/v1/tenants/{tenantId}/' placeholder. The runtime cannot bind ctx.tenant.id from a path that lacks the placeholder.`,
-      });
-    }
-  }
-
+function checkDeploymentSecurity(_actions: ActionRegistryEntry[]): ValidationError[] {
   // Action API exposures are already covered by `checkActionFirstSecurity`
   // for `tenancy: 'required'` paths and `auth: 'none'` exceptions. The
   // codes there (TENANT_API_PATH_REQUIRED, AUTH_NONE_REQUIRES_EXCEPTION)
   // are kept stable for back-compat — they map to the same aspect codes.
-
-  // Suppress the unused-actions lint while keeping the parameter shape
-  // for the future where actions gain new deployment-time invariants.
-  void actions;
-
-  return errors;
+  //
+  return [];
 }
 
 /**
@@ -308,28 +281,6 @@ function checkApiExposureSecurity(actionId: string, exposure: ActionApiExposureW
   return errors;
 }
 
-/**
- * DEFINE_API_LEGACY_USAGE — the action-first migration replaces
- * standalone `defineApi` calls with `defineAction` + `exposure.type:
- * 'api'`. Every `defineApi` call still in the source produces a row in
- * `registry.apis`; the validator emits one error per legacy API to
- * enforce the alpha breaking migration. The validate command's fixture
- * suite intentionally does not use `defineApi`, so this rule does not
- * break existing unit tests.
- */
-function checkDefineApiLegacyUsage(apiCount: number, apis: RegistryEntry[]): ValidationError[] {
-  if (apiCount === 0) return [];
-  const errors: ValidationError[] = [];
-  for (const api of apis) {
-    if (api.kind !== 'api') continue;
-    errors.push({
-      code: 'DEFINE_API_LEGACY_USAGE',
-      message: `API '${api.id}' uses legacy \`defineApi\`. Migrate to \`defineAction\` with \`exposure: { type: 'api', path, method, auth, tenancy }\` (#4619).`,
-    });
-  }
-  return errors;
-}
-
 /**
  * Run the validate command: build the registry and perform structural validation.
  * Exits the process with code 1 if validation fails (CI gate usage).
@@ -352,7 +303,6 @@ export async function runValidate(
   }
 
   errors.push(
-    ...checkDuplicateIds(registry.apis, 'api'),
     ...checkDuplicateIds(registry.webhooks, 'webhook'),
     ...checkDuplicateIds(registry.subscribers, 'subscriber'),
     ...checkDuplicateIds(registry.schedules, 'schedule'),
@@ -363,7 +313,6 @@ export async function runValidate(
   );
 
   const entriesWithFiles = [
-    ...registry.apis,
     ...registry.webhooks,
     ...registry.subscribers,
     ...registry.schedules,
@@ -387,42 +336,9 @@ export async function runValidate(
 
   errors.push(...checkSubscriberSemverRanges(registry.subscribers));
 
-  const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
-  for (const api of registry.apis) {
-    const entry = api as unknown as { deprecatedAt?: string; sunsetAt?: string };
-    errors.push(...checkLifecycleConsistency(entry, `api '${api.id}'`));
-    if (!api.requestSchema) {
-      errors.push({
-        code: 'MISSING_API_REQUEST_SCHEMA',
-        message: `API '${api.id}' (${api.method} ${api.path}) has no request schema. Define input/output in defineApi versions.`,
-      });
-    }
-    if (!api.responseSchema) {
-      errors.push({
-        code: 'MISSING_API_RESPONSE_SCHEMA',
-        message: `API '${api.id}' (${api.method} ${api.path}) has no response schema. Define input/output in defineApi versions.`,
-      });
-    }
-    if (!VALID_METHODS.has(api.method)) {
-      errors.push({
-        code: 'INVALID_API_METHOD',
-        message: `API '${api.id}' (${api.method} ${api.path}) has invalid method "${api.method}". Use one of: ${[...VALID_METHODS].join(', ')}.`,
-      });
-    }
-    const isVoidInput = api.requestSchema?.type === 'null';
-    if (!isVoidInput && !api.examples?.request) {
-      errors.push({
-        code: 'MISSING_API_REQUEST_EXAMPLE',
-        message: `API '${api.id}' (${api.method} ${api.path}) has no request example. Add examples: { request: {...}, response: {...} } to the defineApi config.`,
-      });
-    }
-    if (!api.examples?.response) {
-      errors.push({
-        code: 'MISSING_API_RESPONSE_EXAMPLE',
-        message: `API '${api.id}' (${api.method} ${api.path}) has no response example. Add examples: { request: {...}, response: {...} } to the defineApi config.`,
-      });
-    }
-  }
+  // Issue #4689: defineApi and registry.apis were removed. The action-first
+  // validation rules in `checkActionFirstSecurity` cover the action surface
+  // that now owns all HTTP endpoints.
 
   const rawPathErrors = await checkRawPathViolations(registry.domainRoot, config);
   errors.push(...rawPathErrors);
@@ -431,14 +347,13 @@ export async function runValidate(
   // Runs against the registry built above so the rules see the same
   // shape the CDK packer will eventually consume.
   errors.push(...checkActionFirstSecurity(registry.actions));
-  errors.push(...checkDefineApiLegacyUsage(registry.apis.length, registry.apis));
 
   // Issue #4662 Task D — deployment-time security gates. These mirror
   // the CDK synth-time `SecurityAssertionAspect` so violations are
   // caught before any AWS deployment is attempted.
-  errors.push(...checkDeploymentSecurity(registry.apis, registry.actions));
+  errors.push(...checkDeploymentSecurity(registry.actions));
 
-  const totalPrimitives = registry.apis.length + registry.webhooks.length +
+  const totalPrimitives = registry.webhooks.length +
     registry.subscribers.length + registry.schedules.length +
     registry.jobs.length + registry.actions.length;
   if (totalPrimitives === 0) {

package/src/server/api-server.ts

@@ -1,5 +1,5 @@
 import Fastify, { type FastifyInstance } from 'fastify';
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 import { mountRoutes } from './mount-routes.js';
 
 /**

package/src/server/mount-routes.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import type { FastifyInstance } from 'fastify';
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 import { hydrateLocalCtx } from '../runtime-stubs/hydrate-local-ctx.js';
 
 /**
@@ -21,30 +21,41 @@ function toFastifyPath(path: string): string {
 
 /**
  * Mount all API routes from the DomainRegistry onto the Fastify server.
- * Each route dynamically imports its handler file and hydrates a local dev ctx per request.
+ *
+ * Issue #4689: the only HTTP endpoint surface in the new registry is
+ * `actions[]` whose `exposure.type === 'api'`. `defineApi` was removed
+ * and `registry.apis` is always empty in fresh registries, so the
+ * dev server iterates the action array and mounts each API exposure
+ * directly. Internal-only actions are intentionally skipped — they
+ * are reachable only through `ctx.actions`.
+ *
+ * Each route dynamically imports its handler file and hydrates a local
+ * dev ctx per request.
  * @param options - MountRoutesOptions.
  */
 export async function mountRoutes(options: MountRoutesOptions): Promise<void> {
   const { server, registry, domainRoot } = options;
 
-  for (const api of registry.apis) {
-    const handlerAbsPath = join(domainRoot, api.handlerFile);
-    const fastifyPath = toFastifyPath(api.path);
+  for (const action of registry.actions) {
+    if (action.exposure?.type !== 'api') continue;
+    const exposure = action.exposure;
+    const handlerAbsPath = join(domainRoot, action.handlerFile);
+    const fastifyPath = toFastifyPath(exposure.path);
 
     const mod = await import(handlerAbsPath) as Record<string, unknown>;
     const def = Object.values(mod).find(
-      v => v && typeof v === 'object' && (v as Record<string, unknown>)['id'] === api.id
+      v => v && typeof v === 'object' && (v as Record<string, unknown>)['id'] === action.id
     ) as Record<string, unknown> | undefined;
 
     if (!def || typeof def['handler'] !== 'function') {
-      server.log.warn({ apiId: api.id, handlerAbsPath }, 'No handler function found, skipping route');
+      server.log.warn({ actionId: action.id, handlerAbsPath }, 'No handler function found, skipping route');
       continue;
     }
 
     const handler = def['handler'] as (event: unknown, ctx: unknown) => Promise<unknown>;
 
     server.route({
-      method: api.method === 'ANY' ? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] : [api.method as never],
+      method: [exposure.method as never],
       url: fastifyPath,
       handler: async (request, reply) => {
         const { ctx } = await hydrateLocalCtx({ domainRoot });
@@ -63,6 +74,6 @@ export async function mountRoutes(options: MountRoutesOptions): Promise<void> {
       },
     });
 
-    server.log.info({ method: api.method, path: fastifyPath, apiId: api.id }, 'Route mounted');
+    server.log.info({ method: exposure.method, path: fastifyPath, actionId: action.id }, 'Route mounted');
   }
-}
+}