@mettlecast/domain-cli 0.2.60 → 0.2.62

package/dist/builder/build-registry.d.ts

@@ -1,4 +1,4 @@
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 /**
  * Result of a registry build operation.
  */

package/dist/builder/build-registry.js

@@ -141,8 +141,7 @@ export async function buildRegistry(domainRoot) {
         tenancy: String(domainRaw['tenancy']),
         defaultDeployment: deployment(domainRaw),
     };
-    const [apiExports, webhookExports, subscriberExports, actionExports, scheduleExports, jobExports, integrationExports, eventExports] = await Promise.all([
-        Promise.all(paths.apis.map(load)),
+    const [webhookExports, subscriberExports, actionExports, scheduleExports, jobExports, integrationExports, eventExports] = await Promise.all([
         Promise.all(paths.webhooks.map(load)),
         Promise.all(paths.subscribers.map(load)),
         Promise.all(paths.actions.map(load)),
@@ -151,39 +150,6 @@ export async function buildRegistry(domainRoot) {
         Promise.all(paths.integrations.map(load)),
         paths.publishes ? load(paths.publishes) : Promise.resolve([]),
     ]);
-    const VALID_API_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
-    const apis = paths.apis.flatMap((filePath, i) => (apiExports[i] ?? [])
-        .filter(e => e['_kind'] === 'api')
-        .map(e => {
-        const rawMethod = typeof e['method'] === 'string' ? e['method'].toUpperCase() : '';
-        if (!rawMethod || !VALID_API_METHODS.has(rawMethod)) {
-            warnings.push(`${relPath(filePath)}: defineApi "${e['id']}" has invalid or missing method "${rawMethod || '(none)'}". Use one of: ${[...VALID_API_METHODS].join(', ')}.`);
-        }
-        const rawVersions = e['versions'];
-        const versionSnapshots = rawVersions
-            ? Object.entries(rawVersions).map(([ver, v]) => ({
-                version: ver,
-                requestSchema: isJsonSchema(v?.input) ? v.input : undefined,
-                responseSchema: isJsonSchema(v?.output) ? v.output : undefined,
-            }))
-            : [];
-        const latestVersion = versionSnapshots[versionSnapshots.length - 1];
-        return {
-            id: String(e['id']),
-            kind: 'api',
-            handlerFile: relPath(filePath),
-            path: String(e['path']),
-            method: VALID_API_METHODS.has(rawMethod) ? rawMethod : 'GET',
-            authType: e['auth']?.type ?? 'jwt',
-            description: typeof e['description'] === 'string' ? e['description'] : undefined,
-            deployment: deployment(e),
-            outboundAccess: outboundAccess(e),
-            requestSchema: latestVersion?.requestSchema,
-            responseSchema: latestVersion?.responseSchema,
-            versions: versionSnapshots.length > 0 ? versionSnapshots : undefined,
-            examples: e['examples'],
-        };
-    }));
     const webhooks = paths.webhooks.flatMap((filePath, i) => (webhookExports[i] ?? [])
         .filter(e => e['_kind'] === 'webhook')
         .map(e => ({
@@ -298,7 +264,6 @@ export async function buildRegistry(domainRoot) {
         schemaVersion: '1',
         domainRoot,
         domain,
-        apis,
         webhooks,
         subscribers,
         schedules,

package/dist/builder/build-types.d.ts

@@ -1,4 +1,4 @@
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 /**
  * Generate a .d.ts file declaring typed `ctx.actions.call(actionId, input)`
  * overrides for the union of actions across all registries. The generated

package/dist/builder/load-module.d.ts

@@ -1,7 +1,7 @@
 /**
  * The set of `_kind` discriminant values that identify a domain primitive export.
  */
-export declare const PRIMITIVE_KINDS: Set<"api" | "domain" | "webhook" | "subscriber" | "schedule" | "job" | "action" | "integration" | "event">;
+export declare const PRIMITIVE_KINDS: Set<"domain" | "api" | "webhook" | "subscriber" | "schedule" | "job" | "action" | "integration" | "event">;
 /**
  * A raw primitive export extracted from a domain source file.
  * Functions (handler) and Zod schemas (input/output/versions) are stripped

package/dist/cli.js

@@ -13,6 +13,8 @@ import { runAddModule } from './commands/add-module.js';
 import { runBuildFlows } from './commands/build-flows.js';
 import { runDoctor } from './commands/doctor.js';
 import { runCheckHashes } from './commands/check-hashes.js';
+import { runUpdateAll } from './commands/update-all.js';
+import { runRegenerateModulesHashes } from './commands/regenerate-modules-hashes.js';
 import { runUpgradeBackend } from './commands/upgrade-backend.js';
 import { runAddPage } from './commands/add-page.js';
 import { runCreateProject } from './commands/create-project.js';
@@ -67,7 +69,7 @@ program
 });
 program
     .command('dev <domain>')
-    .description('Start a local HTTP server simulating API Gateway for all defineApi handlers')
+    .description('Start a local HTTP server simulating API Gateway for all API-exposed defineAction handlers')
     .option('--port <n>', 'Port to listen on', '3000')
     .action(async (domain, opts) => {
     await runDev({ domainRoot: domain, port: opts.port ? parseInt(opts.port, 10) : 3000 });
@@ -173,10 +175,26 @@ program
 program
     .command('check-hashes')
     .description('Verify infra/modules/ has not been hand-edited since last scaffold')
-    .action(async () => {
-    const result = await runCheckHashes({});
+    .option('--write', 'Regenerate modules-hashes.json from current disk state instead of verifying')
+    .action(async (opts) => {
+    const result = await runCheckHashes({ write: opts.write });
     process.exit(result.ok ? 0 : 1);
 });
+program
+    .command('update-all')
+    .description('Full refresh: build all domains, build catalog, build flows, build UI, regenerate hashes, run doctor')
+    .option('--project-root <path>', 'Root of the project (defaults to cwd)')
+    .action(async (opts) => {
+    const result = await runUpdateAll({ projectRoot: opts.projectRoot });
+    process.exit(result.success ? 0 : 1);
+});
+program
+    .command('regenerate-modules-hashes')
+    .description('Walk infra/modules/, compute SHA256 hashes, and write .mc/modules-hashes.json')
+    .option('--project-root <path>', 'Root of the project (defaults to cwd)')
+    .action(async (opts) => {
+    await runRegenerateModulesHashes({ projectRoot: opts.projectRoot });
+});
 program
     .command('upgrade-backend <target-major>')
     .description('Run jscodeshift/ts-morph migrations between major versions of domain-runtime')

package/dist/commands/add-api.js

@@ -48,7 +48,7 @@ export async function runAddApi(opts) {
     catch {
         throw new Error(`Domain "${opts.domain}" not found at ${domainDir}`);
     }
-    const apiFilePath = join(domainDir, 'api', `${opts.id}.ts`);
+    const apiFilePath = join(domainDir, 'actions', `${opts.id}.ts`);
     // Refuse if API already exists
     try {
         await access(apiFilePath);
@@ -74,7 +74,7 @@ export async function runAddApi(opts) {
     // Write API file
     await writeFile(apiFilePath, apiContent);
     // Create fixture with the input schema's default shape as the example payload
-    const apiTestDir = join(domainDir, 'api', '__tests__');
+    const apiTestDir = join(domainDir, 'actions', '__tests__');
     await mkdir(apiTestDir, { recursive: true });
     await writeFile(join(apiTestDir, `${opts.id}.fixture.json`), apiFixtureSkeleton(opts.domain, opts.id, exampleBody));
     cliLogger.info({ domain: opts.domain, api: opts.id, method: opts.method ?? 'GET', pattern: opts.pattern ?? 'skeleton' }, 'API added');

package/dist/commands/add-domain.js

@@ -34,13 +34,13 @@ export async function runAddDomain(opts) {
         }
     }
     // Create directory structure
-    await mkdir(join(domainDir, 'api', '__tests__'), { recursive: true });
+    await mkdir(join(domainDir, 'actions', '__tests__'), { recursive: true });
     await mkdir(join(domainDir, 'subscribers'), { recursive: true });
     await mkdir(join(domainDir, 'publishes'), { recursive: true });
     // Write skeleton files
     await writeFile(join(domainDir, 'domain.config.ts'), domainConfigTemplate(opts.id, opts.tenancy));
-    await writeFile(join(domainDir, 'api', 'example.ts'), apiSkeletonTemplate(opts.id, 'example', opts.tenancy));
-    await writeFile(join(domainDir, 'api', '__tests__', 'example.fixture.json'), apiFixtureSkeleton(opts.id, 'example'));
+    await writeFile(join(domainDir, 'actions', 'example.ts'), apiSkeletonTemplate(opts.id, 'example', opts.tenancy));
+    await writeFile(join(domainDir, 'actions', '__tests__', 'example.fixture.json'), apiFixtureSkeleton(opts.id, 'example'));
     await writeFile(join(domainDir, 'publishes', 'events.ts'), eventsSkeletonTemplate(opts.id));
     await writeFile(join(domainDir, 'CLAUDE.md'), claudeMdTemplate(opts.id));
     await writeFile(join(domainDir, 'README.md'), readmeTemplate(opts.id));
@@ -66,6 +66,6 @@ export async function runAddDomain(opts) {
     await addDomainToScaffoldConfig(opts.id, configRoot);
     cliLogger.info({ id: opts.id, dir: domainDir }, 'Domain scaffolded');
     // eslint-disable-next-line no-console
-    console.log(`\n✓ Domain "${opts.id}" added at ${domainDir}\nNext: edit api/example.ts, ` +
+    console.log(`\n✓ Domain "${opts.id}" added at ${domainDir}\nNext: edit actions/example.ts, ` +
         `then run \`mc-domain-module build ${opts.id}\` to generate the registry.`);
 }

package/dist/commands/add-fixture-factory.js

@@ -37,18 +37,17 @@ export async function runAddFixtureFactory(options) {
     const projectRoot = options.projectRoot ?? process.cwd();
     const domain = options.domain;
     const apiId = options.apiId;
-    const apiFile = join(projectRoot, 'domains', domain, 'api', `${apiId}.ts`);
+    const apiFile = join(projectRoot, 'domains', domain, 'actions', `${apiId}.ts`);
     await access(apiFile).catch(() => {
-        throw new Error(`API file not found: ${apiFile}. Run add-api first.`);
+        throw new Error(`Action file not found: ${apiFile}. Run add-api first.`);
     });
-    // Read the API file to extract the input type name
+    // Read the action file to extract the input type name
     const content = await readFile(apiFile, 'utf8');
-    const outputTypeArg = content.match(/import\s+\{\s*[\w\s,]*\s*\}\s+from\s+['"]@mettlecast/);
-    const factoryFile = join(projectRoot, 'domains', domain, 'api', '__tests__', `${apiId}.factory.ts`);
+    const factoryFile = join(projectRoot, 'domains', domain, 'actions', '__tests__', `${apiId}.factory.ts`);
     const factoryContent = FACTORY_TEMPLATE
         .replace(/\{domain\}/g, domain)
         .replace(/\{apiId\}/g, apiId);
-    await mkdir(join(projectRoot, 'domains', domain, 'api', '__tests__'), { recursive: true });
+    await mkdir(join(projectRoot, 'domains', domain, 'actions', '__tests__'), { recursive: true });
     await writeFile(factoryFile, factoryContent, 'utf8');
     cliLogger.info({ factoryFile }, 'add-fixture-factory: factory written');
     return factoryFile;

package/dist/commands/build-catalog.d.ts

@@ -1,30 +1,15 @@
-/** A single API entry in the catalog. */
-export interface CatalogApi {
-    id: string;
-    domainId: string;
-    path: string;
-    method: string;
-    authType: string;
-    description?: string;
-    requestSchema?: Record<string, unknown>;
-    responseSchema?: Record<string, unknown>;
-    versions?: Array<{
-        version: string;
-        requestSchema?: Record<string, unknown>;
-        responseSchema?: Record<string, unknown>;
-    }>;
-    examples?: {
-        request?: Record<string, unknown>;
-        response?: Record<string, unknown>;
-    };
-}
 /** A single action entry in the catalog. */
 export interface CatalogAction {
     id: string;
     domainId: string;
-    visibility: string;
+    backendAccess: string;
+    exposure: Record<string, unknown>;
+    exposureDeclared?: boolean;
     idempotent: boolean;
     description?: string;
+    handlerFile?: string;
+    deployment?: Record<string, unknown>;
+    outboundAccess?: string;
     inputSchema?: Record<string, unknown>;
     outputSchema?: Record<string, unknown>;
 }
@@ -81,7 +66,6 @@ export interface DomainCatalog {
     version: 2;
     generatedAt: string;
     domains: CatalogDomain[];
-    apis: CatalogApi[];
     actions: CatalogAction[];
     events: CatalogEvent[];
     subscribers: CatalogSubscriber[];

package/dist/commands/build-catalog.js

@@ -25,7 +25,6 @@ export async function runBuildCatalog(registryDir) {
         version: 2,
         generatedAt: new Date().toISOString(),
         domains: [],
-        apis: [],
         actions: [],
         events: [],
         subscribers: [],
@@ -55,29 +54,19 @@ export async function runBuildCatalog(registryDir) {
             tenancy: String(domainEntry['tenancy'] ?? 'none'),
             description: domainEntry['description'],
         });
-        const apis = registry['apis'] ?? [];
-        for (const api of apis) {
-            catalog.apis.push({
-                id: String(api['id']),
-                domainId,
-                path: String(api['path']),
-                method: String(api['method'] ?? 'ANY'),
-                authType: String(api['authType'] ?? 'jwt'),
-                description: api['description'],
-                requestSchema: api['requestSchema'],
-                responseSchema: api['responseSchema'],
-                versions: api['versions'],
-                examples: api['examples'],
-            });
-        }
         const actions = registry['actions'] ?? [];
         for (const action of actions) {
             catalog.actions.push({
                 id: String(action['id']),
                 domainId,
-                visibility: String(action['visibility'] ?? 'private'),
+                backendAccess: String(action['backendAccess'] ?? 'private'),
+                exposure: action['exposure'] ?? { type: 'internal' },
+                exposureDeclared: action['exposureDeclared'],
                 idempotent: Boolean(action['idempotent'] ?? false),
                 description: action['description'],
+                handlerFile: action['handlerFile'],
+                deployment: action['deployment'],
+                outboundAccess: action['outboundAccess'],
                 inputSchema: action['inputSchema'],
                 outputSchema: action['outputSchema'],
             });
@@ -135,6 +124,6 @@ export async function runBuildCatalog(registryDir) {
     await mkdir(mcDir, { recursive: true });
     const outPath = join(mcDir, 'domain-registry.json');
     await writeFile(outPath, JSON.stringify(catalog), 'utf8');
-    cliLogger.info({ outPath, domains: catalog.domains.length, apis: catalog.apis.length, actions: catalog.actions.length, events: catalog.events.length, jobs: catalog.jobs.length, schedules: catalog.schedules.length, integrations: catalog.integrations.length }, 'Domain catalog written');
+    cliLogger.info({ outPath, domains: catalog.domains.length, actions: catalog.actions.length, events: catalog.events.length, jobs: catalog.jobs.length, schedules: catalog.schedules.length, integrations: catalog.integrations.length }, 'Domain catalog written');
     return catalog;
 }

package/dist/commands/build.js

@@ -23,7 +23,8 @@ export async function runBuild(options) {
     }
     await mkdir(join(outFile, '..'), { recursive: true });
     await writeFile(outFile, JSON.stringify(registry), 'utf8');
-    cliLogger.info({ outFile, apis: registry.apis.length, events: registry.events.length }, 'Registry written');
+    const apiExposedActions = registry.actions.filter(action => action.exposure.type === 'api').length;
+    cliLogger.info({ outFile, apiExposedActions, events: registry.events.length }, 'Registry written');
     // Discover all sibling registries and emit aggregated types
     const registryDir = join(outFile, '..');
     const registryFiles = (await readdir(registryDir)).filter(f => f.endsWith('-registry.json'));

package/dist/commands/check-hashes.d.ts

@@ -4,6 +4,8 @@
 export interface CheckHashesOptions {
     /** Root directory of the project (defaults to cwd). */
     projectRoot?: string;
+    /** If true, regenerate .mc/modules-hashes.json from current infra/modules/ before checking. */
+    write?: boolean;
 }
 /**
  * A single hash check result.

package/dist/commands/check-hashes.js

@@ -10,6 +10,14 @@ import { cliLogger } from '../utils/logger.js';
  */
 export async function runCheckHashes(opts = {}) {
     const root = opts.projectRoot ?? process.cwd();
+    // --write bootstraps the manifest from current infra/modules/ before verification.
+    // Must run before the manifest read below so it can create a missing manifest.
+    if (opts.write) {
+        const { runRegenerateModulesHashes } = await import('./regenerate-modules-hashes.js');
+        const outPath = await runRegenerateModulesHashes({ projectRoot: root });
+        cliLogger.info({ outPath }, 'modules-hashes.json regenerated');
+        return { ok: true, drifted: [], missing: [], unexpected: [] };
+    }
     const manifestPath = join(root, '.mc', 'modules-hashes.json');
     const modulesDir = join(root, 'infra', 'modules');
     let manifest;

package/dist/commands/dev.js

@@ -21,7 +21,7 @@ export async function startDev(options) {
     for (const w of warnings) {
         cliLogger.warn(w);
     }
-    cliLogger.info({ domain: registry.domain.id, apis: registry.apis.length, port }, 'Starting local dev server');
+    cliLogger.info({ domain: registry.domain.id, apiActions: registry.actions.filter(a => a.exposure?.type === 'api').length, port }, 'Starting local dev server');
     const server = await createApiServer({ port, registry, domainRoot });
     // Spawn Vite if frontend/ exists; skip with warning otherwise.
     const frontendDir = join(projectRoot, 'frontend');

package/dist/commands/doctor.js

@@ -59,8 +59,10 @@ async function checkHandlersUseResult(projectRoot) {
         const missing = [];
         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));
@@ -361,38 +363,52 @@ async function checkNoCrossDomainImports(projectRoot) {
 async function checkApisHaveVersions(projectRoot) {
     try {
         const domainsDir = join(projectRoot, 'domains');
-        const allApiFiles = [];
-        // Find all API files in all domains
+        const allActionFiles = [];
+        // 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 = [];
+        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',
             };
         }
@@ -400,8 +416,8 @@ async function checkApisHaveVersions(projectRoot) {
             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',
             };
         }
@@ -410,7 +426,7 @@ async function checkApisHaveVersions(projectRoot) {
         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',
         };
     }
@@ -418,28 +434,39 @@ async function checkApisHaveVersions(projectRoot) {
 async function checkApisHaveTenancy(projectRoot) {
     try {
         const domainsDir = join(projectRoot, 'domains');
-        const allApiFiles = [];
-        // Find all API files in all domains
+        const allActionFiles = [];
+        // 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 = [];
+        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++;
@@ -449,7 +476,7 @@ async function checkApisHaveTenancy(projectRoot) {
             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',
             };
         }
@@ -457,8 +484,8 @@ async function checkApisHaveTenancy(projectRoot) {
             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',
             };
         }
@@ -493,9 +520,9 @@ async function checkScaffoldConfigMatchesDisk(projectRoot) {
         catch {
             return {
                 name: 'scaffold-config.json matches on-disk',
-                status: 'FAIL',
-                message: 'Could not read .mc/scaffold-config.json',
-                fixHint: 'Ensure .mc/scaffold-config.json exists and is valid JSON',
+                status: 'WARN',
+                message: '.mc/scaffold-config.json not found or unreadable — skipping domain list sync check (expected on fresh clones before first scaffold)',
+                fixHint: 'Run mc-domain-module update-all to regenerate scaffold metadata',
                 kNodeRef: 'K:runbook:add-domain',
             };
         }
@@ -607,7 +634,7 @@ async function checkRootLevelFlows(projectRoot) {
         }
         return {
             name: 'No root-level flows (deprecated)',
-            status: 'WARN',
+            status: 'FAIL',
             message: `${flowFiles.length} flow(s) still in root-level flows/: ${flowFiles.join(', ')}`,
             fixHint: 'Move these flows to domains/{owningDomain}/flows/ and delete the root-level copies.',
             kNodeRef: 'K:convention:flow-vs-subscriber-rule',
@@ -776,7 +803,7 @@ async function checkAllRoutesUseTanStackRouter(projectRoot) {
 }
 /**
  * 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) {
     try {
@@ -794,9 +821,11 @@ async function checkOtelInitInLambdas(projectRoot) {
         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) {
             return { name: 'OTel init in Lambdas', status: 'PASS',

package/dist/commands/explain.js

@@ -31,24 +31,24 @@ const RULE_EXPLANATIONS = {
     'no-raw-http-server': {
         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.',
+        description: '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.',
+        description: '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',
@@ -75,24 +75,24 @@ const RULE_EXPLANATIONS = {
     'apis-have-versions': {
         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.',
+        description: '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).',
+        description: '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',