@mettlecast/domain-cli 0.2.59 → 0.2.61

package/src/commands/doctor.ts

@@ -18,15 +18,13 @@ export const DOCTOR_FIX_FLAG = '--fix';
 export interface DoctorOptions {
   /** Root directory of the project (defaults to cwd). */
   projectRoot?: string;
-  /** Flag to run relocation of old-layout scaffold files to new layout. */
+  /** Deprecated legacy flag retained as a no-op for older automation. */
   relocate?: boolean;
   /**
-   * Auto-remediate before reporting. --fix is a superset of --relocate: it
-   * first runs the relocation routine (auto-moves owned scaffold files outside
-   * .mc/ into .mc/ and updates .mc/manifest.json), then continues with the
-   * full doctor report. On a project that is already clean, --fix is a no-op
-   * (0 files moved, exit 0). Does NOT auto-generate missing fixtures
-   * (deferred).
+   * Auto-remediate before reporting. The legacy relocation routine is now a
+   * no-op because current scaffold manifests intentionally track managed files
+   * in their installed project locations (infra/modules, domains, .github, etc.).
+   * Does NOT auto-generate missing fixtures (deferred).
    */
   fix?: boolean;
   /**
@@ -123,8 +121,10 @@ async function checkHandlersUseResult(projectRoot: string): Promise<DoctorCheck>
     const missing: string[] = [];
     for (const file of apiFiles) {
       const content = await readFile(file, 'utf8');
-      // A file contains a handler export — check the return type
-      if (/defineApi\s*\(/.test(content)) {
+      // A file contains a handler export — check the return type.
+      // Issue #4689: defineApi was removed. The action-first
+      // contract uses defineAction with exposure.type='api'.
+      if (/defineAction\s*\(/.test(content)) {
         // Look for Result<T> in the handler's return type annotation
         if (!/: .*Result</.test(content)) {
           missing.push(relative(projectRoot, file));
@@ -224,16 +224,15 @@ async function checkGeneratedClientsFresh(projectRoot: string): Promise<DoctorCh
 export async function runDoctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
   const projectRoot = opts.projectRoot ?? process.cwd();
 
-  // --relocate runs ONLY the relocation routine (existing behaviour).
-  // --fix is a superset: it runs relocation first, then the full report.
+  // --relocate is retained as a safe no-op for older automation.
+  // --fix runs that no-op preflight first, then the full report.
   // When both are set, --fix takes precedence so the report still runs.
   if (opts.relocate && !opts.fix) {
     return runRelocate(projectRoot);
   }
 
-  // --fix preflight: run the relocation routine and merge its checks into
-  // the doctor report. On a clean project (no files outside .mc/ to move)
-  // runRelocate returns a no-op summary check (0 moved, 0 warned, 8 skipped).
+  // --fix preflight: run the legacy relocation no-op and merge its check into
+  // the doctor report.
   let preflightChecks: DoctorCheck[] = [];
   if (opts.fix) {
     const relocationReport = await runRelocate(projectRoot);
@@ -451,49 +450,64 @@ async function checkNoCrossDomainImports(projectRoot: string): Promise<DoctorChe
 async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck> {
   try {
     const domainsDir = join(projectRoot, 'domains');
-    const allApiFiles: string[] = [];
+    const allActionFiles: string[] = [];
 
-    // Find all API files in all domains
+    // Find API-exposed action files in both actions/ and api/ directories.
+    // Issue #4689: defineApi was removed. API-exposed actions live in
+    // domains/*/actions/ but legacy api/ directories may still exist.
     const entries = await readdir(domainsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const apiFiles = findFiles(apiDir, /\.ts$/);
-      allApiFiles.push(...apiFiles);
+      for (const dir of ['actions', 'api']) {
+        const actionDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(actionDir, /\.ts$/);
+        allActionFiles.push(...files);
+      }
     }
-    const apiFiles = allApiFiles;
 
-    if (apiFiles.length === 0) {
+    // Only consider files that define an API-exposed action (defineAction
+    // with exposure.type === 'api' or exposure: { type: 'api' }).
+    const apiExposedFiles: string[] = [];
+    for (const file of allActionFiles) {
+      const content = await readFile(file, 'utf8');
+      if (/defineAction\s*\(/.test(content) && /exposure\s*:\s*\{\s*type\s*:\s*['"]api['"]/.test(content)) {
+        apiExposedFiles.push(file);
+      }
+    }
+
+    if (apiExposedFiles.length === 0) {
       return {
         name: 'APIs declare versions',
         status: 'PASS',
-        message: 'No APIs found (optional)',
+        message: 'No API-exposed actions found (optional)',
         kNodeRef: 'K:runbook:add-domain',
       };
     }
 
-    // Simple heuristic: grep for 'versions:' in each API file
-    let missingVersions = 0;
-    for (const file of apiFiles) {
+    // Issue #4689: action-first contract requires input/output Zod schemas
+    // with `.default({...})` example data. Check that each API-exposed
+    // action file contains `.default(` (indicating example data).
+    let missingDefaults = 0;
+    for (const file of apiExposedFiles) {
       const content = await readFile(file, 'utf8');
-      if (!content.includes('versions:')) {
-        missingVersions++;
+      if (!content.includes('.default(')) {
+        missingDefaults++;
       }
     }
 
-    if (missingVersions === 0) {
+    if (missingDefaults === 0) {
       return {
         name: 'APIs declare versions',
         status: 'PASS',
-        message: `All ${apiFiles.length} API files declare versions`,
+        message: `All ${apiExposedFiles.length} API-exposed action(s) have .default() example data`,
         kNodeRef: 'K:runbook:add-domain',
       };
     } else {
       return {
         name: 'APIs declare versions',
         status: 'FAIL',
-        message: `${missingVersions}/${apiFiles.length} API files missing versions: field`,
-        fixHint: 'Add versions: { v1: { ... } } to defineApi calls',
+        message: `${missingDefaults}/${apiExposedFiles.length} API-exposed action(s) missing .default() example data. Add \`.default({...})\` to the top-level input and output Zod schemas in each defineAction({ exposure: { type: 'api', ... } }) call.`,
+        fixHint: "Add `input` and `output` Zod schemas with `.default({...})` to defineAction({ exposure: { type: 'api', ... } }) calls",
         kNodeRef: 'K:runbook:add-domain',
       };
     }
@@ -501,7 +515,7 @@ async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck>
     return {
       name: 'APIs declare versions',
       status: 'WARN',
-      message: `Could not check API versions: ${String(err)}`,
+      message: `Could not check API schemas: ${String(err)}`,
       kNodeRef: 'K:runbook:add-domain',
     };
   }
@@ -510,30 +524,42 @@ async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck>
 async function checkApisHaveTenancy(projectRoot: string): Promise<DoctorCheck> {
   try {
     const domainsDir = join(projectRoot, 'domains');
-    const allApiFiles: string[] = [];
+    const allActionFiles: string[] = [];
 
-    // Find all API files in all domains
+    // Find API-exposed action files in both actions/ and api/ directories.
+    // Issue #4689: defineApi was removed. Tenancy is now declared on the
+    // action's exposure block via `exposure.tenancy`.
     const entries = await readdir(domainsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const apiFiles = findFiles(apiDir, /\.ts$/);
-      allApiFiles.push(...apiFiles);
+      for (const dir of ['actions', 'api']) {
+        const actionDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(actionDir, /\.ts$/);
+        allActionFiles.push(...files);
+      }
     }
-    const apiFiles = allApiFiles;
 
-    if (apiFiles.length === 0) {
+    // Only consider files that define an API-exposed action.
+    const apiExposedFiles: string[] = [];
+    for (const file of allActionFiles) {
+      const content = await readFile(file, 'utf8');
+      if (/defineAction\s*\(/.test(content) && /exposure\s*:\s*\{\s*type\s*:\s*['"]api['"]/.test(content)) {
+        apiExposedFiles.push(file);
+      }
+    }
+
+    if (apiExposedFiles.length === 0) {
       return {
         name: 'APIs declare tenancy',
         status: 'PASS',
-        message: 'No APIs found (optional)',
+        message: 'No API-exposed actions found (optional)',
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     }
 
-    // Simple heuristic: grep for 'tenancy:' in each API file
+    // Check for `tenancy:` anywhere in each API-exposed action file.
     let missingTenancy = 0;
-    for (const file of apiFiles) {
+    for (const file of apiExposedFiles) {
       const content = await readFile(file, 'utf8');
       if (!content.includes('tenancy:')) {
         missingTenancy++;
@@ -544,15 +570,15 @@ async function checkApisHaveTenancy(projectRoot: string): Promise<DoctorCheck> {
       return {
         name: 'APIs declare tenancy',
         status: 'PASS',
-        message: `All ${apiFiles.length} API files declare tenancy`,
+        message: `All ${apiExposedFiles.length} API-exposed action(s) declare tenancy`,
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     } else {
       return {
         name: 'APIs declare tenancy',
         status: 'FAIL',
-        message: `${missingTenancy}/${apiFiles.length} API files missing tenancy: field`,
-        fixHint: "Add tenancy: 'required' | 'none' | 'system' to defineApi calls",
+        message: `${missingTenancy}/${apiExposedFiles.length} API-exposed action(s) missing tenancy. Tenancy must be declared on the action's exposure block: \`exposure.tenancy: 'required' | 'none' | 'system'\`.`,
+        fixHint: "Add `exposure.tenancy: 'required' | 'none' | 'system'` to defineAction({ exposure: { type: 'api', ... } }) calls",
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     }
@@ -568,14 +594,22 @@ async function checkApisHaveTenancy(projectRoot: string): Promise<DoctorCheck> {
 
 async function checkScaffoldConfigMatchesDisk(projectRoot: string): Promise<DoctorCheck> {
   try {
-    const configPath = join(projectRoot, '.tib', 'scaffold-config.json');
+    const configPath = join(projectRoot, '.mc', 'scaffold-config.json');
     const domainsDir = join(projectRoot, 'domains');
 
     let configDomains: string[] = [];
     try {
       const configContent = await readFile(configPath, 'utf8');
       const config = JSON.parse(configContent) as { domainIds?: string[] };
-      configDomains = config.domainIds ?? [];
+      if (!Array.isArray(config.domainIds)) {
+        return {
+          name: 'scaffold-config.json matches on-disk',
+          status: 'PASS',
+          message: '.mc/scaffold-config.json has no domainIds array — domain list sync check skipped',
+          kNodeRef: 'K:runbook:add-domain',
+        };
+      }
+      configDomains = config.domainIds;
     } catch {
       return {
         name: 'scaffold-config.json matches on-disk',
@@ -868,7 +902,7 @@ async function checkAllRoutesUseTanStackRouter(projectRoot: string): Promise<Doc
 
 /**
  * Check W5-4: Lambda handler files contain initOtel() call.
- * Scans `domains/*\/api/*.ts` and FAILs if any handler is missing initOtel().
+  * Scans `domains/*\/actions/*.ts` and `domains/*\/api/*.ts` and FAILs if any handler is missing initOtel().
  */
 async function checkOtelInitInLambdas(projectRoot: string): Promise<DoctorCheck> {
   try {
@@ -885,9 +919,11 @@ async function checkOtelInitInLambdas(projectRoot: string): Promise<DoctorCheck>
     const handlerFiles: string[] = [];
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const files = findFiles(apiDir, /\.ts$/);
-      handlerFiles.push(...files);
+      for (const dir of ['actions', 'api']) {
+        const handlerDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(handlerDir, /\.ts$/);
+        handlerFiles.push(...files);
+      }
     }
 
     if (handlerFiles.length === 0) {
@@ -1205,7 +1241,7 @@ async function checkDomainBrainReachable(projectRoot: string): Promise<DoctorChe
  */
 async function checkActionsHaveTypes(projectRoot: string): Promise<DoctorCheck> {
   try {
-    const typesPath = join(projectRoot, '.tib', 'actions-types.d.ts');
+    const typesPath = join(projectRoot, '.mc', 'actions-types.d.ts');
     const domainsDir = join(projectRoot, 'domains');
     const discoveredActions: string[] = [];
 
@@ -1435,7 +1471,7 @@ async function checkSeedPagesHaveNoHeaders(projectRoot: string): Promise<DoctorC
 
 /**
  * Check Part C: Layout validation checks
- * 1. owned files in unexpected locations
+ * 1. managed files are not registered in obsolete legacy locations
  * 2. tracked/seed files inside .mc/
  * 3. manifest entries pointing at missing files
  * 4. scaffold-tracked files (with @mc-scaffold: header) that lack manifest entries
@@ -1452,26 +1488,29 @@ async function checkLayoutPolicy(projectRoot: string): Promise<DoctorCheck[]> {
     return [];
   }
 
-  // Check 1: owned files in unexpected locations
-  // Policy: owned files should be in .mc/ OR .github/workflows/tib-*
-  const ownedOutsideTib = manifest.files.filter(f =>
-    f.policy === 'managed' &&
-    !f.path.startsWith('.mc/') &&
-    !/^\.github\/workflows\/tib-/.test(f.path)
+  // Check 1: managed files should not be registered in obsolete legacy
+  // locations. Current scaffold manifests intentionally track managed files at
+  // their installed paths (infra/modules, domains, .github, CLAUDE.md, etc.).
+  const legacyManagedLocations = manifest.files.filter(f =>
+    f.policy === 'managed' && (
+      f.path.startsWith('.tib/') ||
+      f.path.startsWith('.mc/infra/') ||
+      f.path === 'mc-deploy.yml'
+    )
   );
-  if (ownedOutsideTib.length === 0) {
+  if (legacyManagedLocations.length === 0) {
     results.push({
-      name: 'Layout: owned files in .mc/',
+      name: 'Layout: no managed files in legacy locations',
       status: 'PASS',
-      message: 'All owned scaffold files are under .mc/ or .github/workflows/tib-*',
+      message: 'Managed scaffold files use current manifest paths',
     });
   } else {
-    for (const f of ownedOutsideTib) {
+    for (const f of legacyManagedLocations) {
       results.push({
-        name: 'Layout: owned files in .mc/',
+        name: 'Layout: no managed files in legacy locations',
         status: 'FAIL',
-        message: `Owned scaffold file outside .mc/: ${f.path}`,
-        fixHint: `Run 'tib doctor --relocate' to migrate ${f.path} to .mc/`,
+        message: `Managed scaffold file registered in legacy location: ${f.path}`,
+        fixHint: 'Run `npx mc-domain-module upgrade` to refresh scaffold metadata',
         file: f.path,
       });
     }
@@ -1521,7 +1560,7 @@ async function checkLayoutPolicy(projectRoot: string): Promise<DoctorCheck[]> {
       name: 'Layout: manifest entries exist on disk',
       status: 'FAIL',
       message: `${missingFiles.length} manifest entry/entries point to missing files:\n  ${missingFiles.join('\n  ')}`,
-      fixHint: 'Run tib doctor --relocate or tib upgrade to fix missing files',
+      fixHint: 'Run `npx mc-domain-module upgrade` to refresh scaffold metadata, or restore the missing files',
     });
   }
 
@@ -1566,7 +1605,7 @@ async function checkLayoutPolicy(projectRoot: string): Promise<DoctorCheck[]> {
       name: 'Layout: scaffold-tracked files have manifest entries',
       status: 'WARN',
       message: `${untracked.length} file(s) with @mc-scaffold: header not in manifest:\n  ${untracked.join('\n  ')}`,
-      fixHint: 'Run tib upgrade or tib doctor --relocate to register these files',
+      fixHint: 'Run `npx mc-domain-module upgrade` to refresh scaffold metadata',
     });
   }
 
@@ -1574,156 +1613,19 @@ async function checkLayoutPolicy(projectRoot: string): Promise<DoctorCheck[]> {
 }
 
 /**
- * Old path → new path mapping for known scaffold files
- */
-const RELOCATION_MAP: Array<{ oldPath: string; newPath: string; policy: 'managed' | 'editable' | 'seed' }> = [
-  { oldPath: 'infra/modules/app.ts', newPath: '.mc/infra/modules/app.ts', policy: 'managed' },
-  { oldPath: 'infra/modules/shared/SharedStack.ts', newPath: '.mc/infra/modules/shared/SharedStack.ts', policy: 'managed' },
-  { oldPath: 'infra/modules/domains/dispatch-middleware.ts', newPath: '.mc/infra/modules/domains/dispatch-middleware.ts', policy: 'managed' },
-  { oldPath: 'infra/modules/PowerTuningStack.ts', newPath: '.mc/infra/modules/PowerTuningStack.ts', policy: 'managed' },
-  { oldPath: 'infra/cdk.json', newPath: '.mc/infra/cdk.json', policy: 'managed' },
-  { oldPath: 'infra/tsconfig.json', newPath: '.mc/infra/tsconfig.json', policy: 'managed' },
-  { oldPath: 'infra/package.json', newPath: '.mc/infra/package.json', policy: 'managed' },
-  { oldPath: 'mc-deploy.yml', newPath: '.github/workflows/mc-deploy.yml', policy: 'managed' },
-];
-
-/**
- * Run relocation of old-layout scaffold files to new layout
+ * Legacy relocation entrypoint retained for older automation.
+ *
+ * Earlier scaffold versions tried to move generated infra into .mc/infra. The
+ * current scaffold contract keeps generated infra under infra/modules and uses
+ * .mc/manifest.json plus .mc/modules-hashes.json for ownership/drift tracking.
+ * Moving files here would corrupt modern projects, so relocation is now a no-op.
  */
 async function runRelocate(projectRoot: string): Promise<DoctorReport> {
-  const checks: DoctorCheck[] = [];
-
-  const { readManifest, writeManifest, upsertManifestFile } = await import('../utils/manifest.js');
-  const { readFile, writeFile, mkdir, unlink } = await import('node:fs/promises');
-  const { computeChecksumFile, computeChecksumString } = await import('../utils/checksum.js');
-  const { join, dirname } = await import('node:path');
-
-  const manifest = await readManifest(projectRoot);
-  if (!manifest) {
-    checks.push({
-      name: 'Relocate: manifest present',
-      status: 'FAIL',
-      message: '.mc/manifest.json not found — cannot relocate without a manifest',
-      fixHint: 'This project may not be a TIB scaffold project',
-    });
-    return { checks, exitCode: 1, pass: false };
-  }
-
-  let moved = 0;
-  let warned = 0;
-  let skipped = 0;
-
-  for (const { oldPath, newPath, policy } of RELOCATION_MAP) {
-    const oldAbsPath = join(projectRoot, oldPath);
-    const newAbsPath = join(projectRoot, newPath);
-
-    // Check if old file exists
-    const { access: fsAccess } = await import('node:fs/promises');
-    try { await fsAccess(oldAbsPath); } catch { skipped++; continue; }
-
-    // Check if it has the scaffold header (confirm it's scaffold-owned)
-    let content: string;
-    try {
-      content = await readFile(oldAbsPath, 'utf-8');
-    } catch {
-      skipped++;
-      continue;
-    }
-
-    if (!content.includes('@mc-scaffold:')) {
-      // File exists but no header — user-owned, leave it
-      checks.push({
-        name: 'Relocate: checking ' + oldPath,
-        status: 'WARN',
-        message: `${oldPath} has no @mc-scaffold: header — left in place (user-owned)`,
-        file: oldPath,
-      });
-      warned++;
-      continue;
-    }
-
-    // Check for user drift
-    const manifestEntry = manifest.files.find(f => f.path === oldPath);
-    if (manifestEntry) {
-      const diskSha = await computeChecksumFile(oldAbsPath);
-      if (diskSha && diskSha !== manifestEntry.sha256) {
-        // File has been modified — leave with warning
-        checks.push({
-          name: 'Relocate: checking ' + oldPath,
-          status: 'WARN',
-          message: `${oldPath} has local modifications — left in place. Migrate manually: move to ${newPath}`,
-          file: oldPath,
-        });
-        warned++;
-        continue;
-      }
-    }
-
-    // Check if destination already exists
-    try {
-      await fsAccess(newAbsPath);
-      checks.push({
-        name: 'Relocate: ' + oldPath,
-        status: 'WARN',
-        message: `${newPath} already exists — skipping move of ${oldPath}`,
-        file: newPath,
-      });
-      warned++;
-      continue;
-    } catch { /* destination doesn't exist, good */ }
-
-    // Move the file
-    try {
-      await mkdir(dirname(newAbsPath), { recursive: true });
-      // Copy + delete (rename may fail across filesystems)
-      await writeFile(newAbsPath, content, 'utf-8');
-
-      // Update manifest: remove old entry, add new with new path + policy
-      manifest.files = manifest.files.filter(f => f.path !== oldPath);
-      const sha256 = manifestEntry?.sha256 ?? computeChecksumString(content);
-      upsertManifestFile(manifest, {
-        path: newPath,
-        module: manifestEntry?.module ?? 'domain',
-        moduleVersion: manifestEntry?.moduleVersion ?? '1.0.0',
-        sha256,
-        wasTemplate: manifestEntry?.wasTemplate ?? false,
-        installedAt: manifestEntry?.installedAt ?? new Date().toISOString(),
-        policy,
-      });
-
-      // Delete old file
-      await unlink(oldAbsPath);
-
-      checks.push({
-        name: 'Relocate: ' + oldPath,
-        status: 'PASS',
-        message: `Moved ${oldPath} → ${newPath} (policy: ${policy})`,
-        file: newPath,
-      });
-      moved++;
-    } catch (err) {
-      checks.push({
-        name: 'Relocate: ' + oldPath,
-        status: 'FAIL',
-        message: `Failed to move ${oldPath} → ${newPath}: ${String(err)}`,
-        file: oldPath,
-      });
-    }
-  }
-
-  // Write updated manifest
-  if (moved > 0) {
-    await writeManifest(projectRoot, manifest);
-  }
-
-  // Summary check
-  checks.push({
-    name: 'Relocate: summary',
-    status: warned > 0 ? 'WARN' : 'PASS',
-    message: `Relocation complete: ${moved} file(s) moved, ${warned} warning(s), ${skipped} skipped (not present)`,
-  });
-
-  const hasFail = checks.some(c => c.status === 'FAIL');
-  const exitCode = hasFail ? 1 : 0;
-  return { checks, exitCode, pass: exitCode === 0 };
+  void projectRoot;
+  const checks: DoctorCheck[] = [{
+    name: 'Relocate: deprecated no-op',
+    status: 'PASS',
+    message: 'No files moved. Current scaffold layout keeps generated files at their installed paths and tracks ownership via .mc/manifest.json.',
+  }];
+  return { checks, exitCode: 0, pass: true };
 }

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',