@mettlecast/domain-cli 0.2.59 → 0.2.61

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/power-tune.ts

@@ -5,13 +5,13 @@ import { cliLogger } from '../utils/logger.js';
 
 export async function runPowerTune(domain: string, primitive: string): Promise<void> {
   // Load registry to find Lambda ARN
-  const registryPath = path.join(process.cwd(), '.tib', `${domain}-registry.json`);
+  const registryPath = path.join(process.cwd(), '.mc', `${domain}-registry.json`);
 
   let registry: { domain: { id: string }; functionArns?: Record<string, string> };
   try {
     registry = JSON.parse(readFileSync(registryPath, 'utf8'));
   } catch {
-    cliLogger.error({}, `Registry not found at ${registryPath}. Run: tib build domains/${domain}`);
+    cliLogger.error({}, `Registry not found at ${registryPath}. Run: npx mc-domain-module build domains/${domain}`);
     process.exit(1);
   }
 

package/src/commands/show-dns.ts

@@ -26,7 +26,7 @@ function toZoneLine(r: DnsRecord): string {
 }
 
 /**
- * tib show-dns [--env dev|staging|prod] [--project-dir <path>]
+ * mc-domain-module show-dns [--env dev|staging|prod] [--project-dir <path>]
  *
  * Reads the scaffold-config.json and prints DNS records that must be added for
  * custom domain wiring: certificate validation CNAMEs (step 1) and traffic
@@ -37,27 +37,27 @@ function toZoneLine(r: DnsRecord): string {
  */
 export async function runShowDns(opts: ShowDnsOptions): Promise<void> {
   const projectDir = opts.projectDir ? path.resolve(opts.projectDir) : process.cwd();
-  const configPath = path.join(projectDir, '.tib', 'scaffold-config.json');
+  const configPath = path.join(projectDir, '.mc', 'scaffold-config.json');
 
   let config: { environments?: Record<string, { dashboardUrl?: string }> };
   try {
     const raw = await readFile(configPath, 'utf-8');
     config = JSON.parse(raw) as typeof config;
   } catch {
-    console.error('[tib] Could not read .mc/scaffold-config.json — run from a TIB project root.');
+    console.error('[mc-domain-module] Could not read .mc/scaffold-config.json — run from a Mettlecast project root.');
     process.exit(1);
   }
 
   const environments = config.environments ?? {};
   if (Object.keys(environments).length === 0) {
-    console.log('[tib] No environments configured. Set a custom domain via `tib show-dns` or the Setup tab.');
+    console.log('[mc-domain-module] No environments configured. Set a custom domain via `npx mc-domain-module show-dns` or the Setup tab.');
     return;
   }
 
   // Try to load CDK outputs for routing records
   let cdkOutputs: Record<string, Record<string, string>> = {};
   try {
-    const outputsPath = path.join(projectDir, '.tib', 'cdk-outputs.json');
+    const outputsPath = path.join(projectDir, '.mc', 'cdk-outputs.json');
     const raw = await readFile(outputsPath, 'utf-8');
     cdkOutputs = JSON.parse(raw) as typeof cdkOutputs;
   } catch {

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/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/upgrade.ts

@@ -251,9 +251,9 @@ function buildPrBody(
     lines.push('### Drift warnings — manual review required');
     lines.push(
       'The following files were locally modified after scaffold installation. ' +
-        'New versions have been written to `{path}.tib-upgrade` — merge manually then remove the `.tib-upgrade` file.'
+        'New versions have been written to `{path}.mc-upgrade` — merge manually then remove the `.mc-upgrade` file.'
     );
-    for (const r of conflicts) lines.push(`- \`${r.path}\` → \`${r.path}.tib-upgrade\``);
+    for (const r of conflicts) lines.push(`- \`${r.path}\` → \`${r.path}.mc-upgrade\``);
     lines.push('');
   }
 
@@ -322,9 +322,9 @@ function buildFrontendComponentsPrBody(
     lines.push('### Drift warnings — manual review required');
     lines.push(
       'The following files were locally modified after scaffold installation. ' +
-        'New versions have been written to `{path}.tib-upgrade` — merge manually then remove the `.tib-upgrade` file.'
+        'New versions have been written to `{path}.mc-upgrade` — merge manually then remove the `.mc-upgrade` file.'
     );
-    for (const r of conflicts) lines.push(`- \`${r.path}\` → \`${r.path}.tib-upgrade\``);
+    for (const r of conflicts) lines.push(`- \`${r.path}\` → \`${r.path}.mc-upgrade\``);
     lines.push('');
   }
 
@@ -512,14 +512,20 @@ export async function runUpgrade(
         continue;
       }
 
-      // Add to results
-      allResults.push({ path: installPath, status: installResult.status, module: mod.id });
-
-      // update-available: do NOT update manifest (file was not written to disk)
+      // update-available: write the proposed new content beside the drifted file
+      // for manual merge, but do NOT update the manifest or overwrite the file.
       if (installResult.status === 'update-available') {
+        if (!opts.dryRun) {
+          await mkdir(dirname(diskPath), { recursive: true });
+          await writeFile(`${diskPath}.mc-upgrade`, newContent, 'utf-8');
+        }
+        allResults.push({ path: installPath, status: 'conflict', module: mod.id });
         continue;
       }
 
+      // Add to results
+      allResults.push({ path: installPath, status: installResult.status, module: mod.id });
+
       // Update manifest if file was not skipped
       const newChecksum = computeChecksumString(newContent);
       upsertManifestFile(updatedManifest, {
@@ -566,7 +572,7 @@ export async function runUpgrade(
   if (conflicts.length > 0) {
     console.log('\nDrift warnings:');
     for (const r of conflicts) {
-      console.log(`  ${r.path} — new version written to ${r.path}.tib-upgrade`);
+      console.log(`  ${r.path} — new version written to ${r.path}.mc-upgrade`);
     }
   }
 
@@ -601,7 +607,7 @@ export async function runUpgrade(
   await writeScaffoldConfig(projectDir, updatedConfig);
 
   // 10. Commit on upgrade branch
-  const branchName = `tib-upgrade/${targetVersion}`;
+  const branchName = `mc-upgrade/${targetVersion}`;
   try {
     execSync(`git -C "${projectDir}" checkout -b "${branchName}"`, {
       stdio: ['pipe', 'pipe', 'pipe'],

package/src/commands/validate.ts

@@ -1,11 +1,32 @@
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import type { RegistryEntry } from '@mettlecast/domain-cdk-packer';
+import type {
+  RegistryEntry,
+  ActionRegistryEntry,
+} from '@mettlecast/domain-cdk-packer';
 import { validRange } from 'semver';
 import type { DomainModuleConfig } from '@mettlecast/domain-runtime/types';
 import { buildRegistry } from '../builder/build-registry.js';
 import { cliLogger } from '../utils/logger.js';
 
+type ActionApiExposureWithDeclaration = {
+  type: 'api';
+  path: string;
+  method: string;
+  auth: 'required' | 'none' | 'service';
+  tenancy: 'required' | 'none' | 'system';
+  roles?: string[];
+  securityException?: { reason: string };
+  authDeclared?: boolean;
+  tenancyDeclared?: boolean;
+};
+
+type ActionRegistryEntryWithDeclaration = ActionRegistryEntry & {
+  backendAccess?: 'private' | 'domain' | 'platform';
+  exposureDeclared?: boolean;
+  exposure: { type: 'internal' } | ActionApiExposureWithDeclaration;
+};
+
 /**
  * A single validation failure.
  */
@@ -116,6 +137,150 @@ async function checkRawPathViolations(
   return [];
 }
 
+/**
+ * Deployment-time security checks (#4662 Task D).
+ *
+ * Mirrors the invariants enforced at CDK synth time by
+ * `SecurityAssertionAspect` in `@mettlecast/domain-cdk-packer`. Running
+ * them at the CLI stage means developers get a structured error code in
+ * their terminal and CI fails on `mc-domain-module validate` BEFORE a
+ * (potentially expensive) `cdk synth` is attempted.
+ *
+ * Each rule maps 1:1 to an aspect annotation code so downstream tooling
+ * can correlate build-time and synth-time failures.
+ *
+ * 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(_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.
+  //
+  return [];
+}
+
+/**
+ * Action-first security validation rules (#4619, Wave 6 Task 6.1).
+ *
+ * These checks enforce the action-first security model on the
+ * serialised DomainRegistry produced by `buildRegistry`. The rules
+ * intentionally mirror the Zod cross-field refinements defined in
+ * `@mettlecast/domain-runtime/primitives/action` (`ApiExposureSchema`)
+ * so violations are caught at build time, not at runtime.
+ *
+ * Each rule emits a structured `ValidationError` whose `code` is the
+ * rule ID listed in the spec (e.g. `ACTION_EXPOSURE_REQUIRED`,
+ * `TENANT_API_PATH_REQUIRED`). Messages include the offending action
+ * or API id and the actionable fix.
+ */
+function checkActionFirstSecurity(actions: ActionRegistryEntry[]): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  for (const action of actions as ActionRegistryEntryWithDeclaration[]) {
+    const id = action.id;
+
+    // ACTION_EXPOSURE_REQUIRED — every action registry entry must have
+    // `exposure` declared in source. The builder defaults missing
+    // exposure to `{ type: 'internal' }` for backwards compatibility,
+    // and flags the entry with `exposureDeclared: false` so the validator
+    // can surface it. Legacy actions that use `visibility` only (no
+    // `backendAccess`) are also allowed to default during migration.
+    if (action.exposureDeclared === false && action.backendAccess !== 'private') {
+      // Only fire for non-private actions: a private action with no
+      // exposure is the natural migration state for legacy
+      // visibility:'private' handlers, and forcing exposure would
+      // produce noisy errors during the migration window.
+      // (When Wave 7+ removes the legacy visibility alias this branch
+      // becomes a hard error for every action.)
+      errors.push({
+        code: 'ACTION_EXPOSURE_REQUIRED',
+        message: `Action '${id}' has no explicit \`exposure\`. New-style actions must declare \`exposure\` (e.g. \`{ type: 'api', path: '...', method: 'POST', auth: 'required', tenancy: 'required' }\`) or \`{ type: 'internal' }\` to opt out of API exposure.`,
+      });
+    }
+
+    if (action.exposure.type === 'api') {
+      errors.push(...checkApiExposureSecurity(action.id, action.exposure));
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a single API-exposed action. Pulled out as a separate helper
+ * so each sub-rule is independently testable and the messages stay short.
+ */
+function checkApiExposureSecurity(actionId: string, exposure: ActionApiExposureWithDeclaration): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // API_EXPOSURE_AUTH_REQUIRED — API-exposed actions must declare auth
+  // explicitly. The builder defaults auth to 'required' when the source
+  // omits it; the validator surfaces the omission so developers are not
+  // silently relying on the safe-default.
+  if (exposure.authDeclared === false) {
+    errors.push({
+      code: 'API_EXPOSURE_AUTH_REQUIRED',
+      message: `Action '${actionId}' has \`exposure.type: 'api'\` but \`exposure.auth\` is not declared. Set \`exposure.auth\` to 'required' | 'none' | 'service' explicitly.`,
+    });
+  }
+
+  // TENANT_API_PATH_REQUIRED — API-exposed actions with `tenancy: 'required'`
+  // must use a path that includes the canonical tenant placeholder so the
+  // runtime can bind `ctx.tenant.id` from the URL.
+  if (exposure.tenancy === 'required' && !exposure.path.includes('/v1/tenants/{tenantId}/')) {
+    errors.push({
+      code: 'TENANT_API_PATH_REQUIRED',
+      message: `Action '${actionId}' declares \`exposure.tenancy: 'required'\` but \`exposure.path\` ('${exposure.path}') does not include the canonical tenant placeholder '/v1/tenants/{tenantId}/'.`,
+    });
+  }
+
+  // AUTH_NONE_REQUIRES_EXCEPTION — `auth: 'none'` (anonymous) routes
+  // must carry an explicit `securityException` with a non-empty reason
+  // so security reviewers can audit the relaxation.
+  if (exposure.auth === 'none') {
+    const reason = exposure.securityException?.reason;
+    if (!reason || reason.trim().length === 0) {
+      errors.push({
+        code: 'AUTH_NONE_REQUIRES_EXCEPTION',
+        message: `Action '${actionId}' has \`exposure.auth: 'none'\` but no \`exposure.securityException.reason\`. Public/anonymous routes must document the security exception with a non-empty reason (and ideally a tracking reference).`,
+      });
+    }
+  }
+
+  // TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC — `tenancy: 'none'` on a
+  // public API route must justify the missing tenant context. If the
+  // route is already justified as anonymous via `auth: 'none'` the
+  // same `securityException` may be reused; otherwise an exception is
+  // required for tenancy: 'none' on its own.
+  if (exposure.tenancy === 'none') {
+    const reason = exposure.securityException?.reason;
+    if (!reason || reason.trim().length === 0) {
+      errors.push({
+        code: 'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC',
+        message: `Action '${actionId}' has \`exposure.tenancy: 'none'\` but no \`exposure.securityException.reason\`. Routes without tenant context must document the security exception with a non-empty reason.`,
+      });
+    }
+  }
+
+  // SYSTEM_API_REQUIRES_ROLE — `tenancy: 'system'` combined with
+  // `auth: 'required'` must declare non-empty `roles` so the JWT
+  // authorizer can scope the call. Routes that use `auth: 'service'`
+  // are service-only and do not require role narrowing.
+  if (exposure.tenancy === 'system' && exposure.auth === 'required') {
+    if (!Array.isArray(exposure.roles) || exposure.roles.length === 0) {
+      errors.push({
+        code: 'SYSTEM_API_REQUIRES_ROLE',
+        message: `Action '${actionId}' has \`exposure.tenancy: 'system'\` and \`exposure.auth: 'required'\` but no \`exposure.roles\`. System-tenancy routes using user auth must declare at least one required role.`,
+      });
+    }
+  }
+
+  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).
@@ -138,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'),
@@ -149,7 +313,6 @@ export async function runValidate(
   );
 
   const entriesWithFiles = [
-    ...registry.apis,
     ...registry.webhooks,
     ...registry.subscribers,
     ...registry.schedules,
@@ -173,47 +336,24 @@ 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);
 
-  const totalPrimitives = registry.apis.length + registry.webhooks.length +
+  // Wave 6 Task 6.1: action-first security validation gates (#4619).
+  // Runs against the registry built above so the rules see the same
+  // shape the CDK packer will eventually consume.
+  errors.push(...checkActionFirstSecurity(registry.actions));
+
+  // 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.actions));
+
+  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');
   }
-}
+}