@mettlecast/domain-cli 0.2.59 → 0.2.61

package/src/__tests__/smoke/scaffold.test.ts

@@ -448,11 +448,10 @@ describe('scaffold smoke test (issue #3831)', () => {
     expect(tsconfig.compilerOptions.strict).toBe(true);
   });
 
-  it('seeds api handlers from auth that import defineApi from @mettlecast/domain-runtime', async () => {
+  it('seeds api handlers from auth that import defineAction + exposure from @mettlecast/domain-runtime', async () => {
     // The auth module ships a hand-written seed api/me.ts. We
     // confirm it parses (no obvious syntax errors) and uses the runtime
-    // primitive. This is a structural check; the wave-2 "import ky + call
-    // initOtel()" expectation is documented below as a separate soft gate.
+    // primitive. This is a structural check.
     const apiFile = join(projectDir, 'domains', 'auth', 'api', 'me.ts');
     const s = await stat(apiFile).catch(() => null);
     if (!s) {
@@ -462,7 +461,8 @@ describe('scaffold smoke test (issue #3831)', () => {
     }
     const content = await readFile(apiFile, 'utf-8');
     expect(content).toMatch(/from\s+['"]@mettlecast\/domain-runtime['"]/);
-    expect(content).toMatch(/defineApi\s*\(/);
+    expect(content).toMatch(/defineAction\s*\(/);
+    expect(content).toMatch(/type:\s*['"]api['"]/);
   });
 
   it('seeds initOtel() references in api handlers (wave-2 acceptance gate)', async () => {
@@ -499,20 +499,18 @@ describe('scaffold smoke test (issue #3831)', () => {
     }
   });
 
-  it('api-skeleton template (add-api) emits createKyClient + initOtel references', async () => {
-    // The add-api template now imports `createKyClient` and `initOtel`
-    // from @mettlecast/domain-runtime (the ky-backed runtime client),
-    // not a direct `ky` npm import.  Seed handlers may also import `ky`
-    // directly if they need a browser-friendly HTTP client.
+  it('api-skeleton template (add-api) emits defineAction + exposure.type=api references', async () => {
+    // The add-api template now emits defineAction + exposure.type='api' as
+    // the canonical action-first HTTP endpoint primitive (#4689).
     const out = apiSkeletonTemplateForTest('payments', 'charge-card', 'required');
-    const hasKy = /createKyClient/.test(out) || /from\s+['"]ky['"]/.test(out);
-    const hasInitOtel = /\binitOtel\s*\(/.test(out);
-    if (!hasKy || !hasInitOtel) {
+    const hasDefineAction = /defineAction\s*\(/.test(out);
+    const hasApiExposure = /type:\s*['"]api['"]/.test(out);
+    if (!hasDefineAction || !hasApiExposure) {
       throw new Error(
         'api-skeleton template (packages/domain-cli/src/templates/api-skeleton.ts) ' +
-          'does not emit createKyClient or initOtel()\n' +
-          `  hasKy=${hasKy} hasInitOtel=${hasInitOtel}\n` +
-          '  expected: import { createKyClient, initOtel } from "@mettlecast/domain-runtime" AND initOtel()',
+          'does not emit defineAction + exposure.type=api\n' +
+          `  hasDefineAction=${hasDefineAction} hasApiExposure=${hasApiExposure}\n` +
+          '  expected: import { defineAction } from "@mettlecast/domain-runtime" AND exposure: { type: "api", ... }',
       );
     }
   });

package/src/__tests__/utils/install-file.test.ts

@@ -157,8 +157,8 @@ describe('installScaffoldFile', () => {
 
       const result = await installScaffoldFile(filePath, newContent, 'editable', currentEntry);
       expect(result.status).toBe('update-available');
-      // Verify NO .tib-upgrade file written
-      await expect(access(filePath + '.tib-upgrade')).rejects.toThrow();
+      // Verify NO .mc-upgrade file written
+      await expect(access(filePath + '.mc-upgrade')).rejects.toThrow();
       // Verify original file NOT overwritten
       const diskContent = await readFile(filePath, 'utf-8');
       expect(diskContent).toBe(existingContent);

package/src/__tests__/utils/manifest.test.ts

@@ -57,8 +57,8 @@ describe('manifest utilities', () => {
       expect(inferPolicyFromPath('infra/main.tf')).toBe('managed');
     });
 
-    it('returns editable for .mc/infra/ paths', () => {
-      expect(inferPolicyFromPath('.mc/infra/stack.ts')).toBe('editable');
+    it('returns editable for unrecognised .mc paths', () => {
+      expect(inferPolicyFromPath('.mc/custom/stack.ts')).toBe('editable');
     });
 
     it('returns managed for mc-deploy.yml', () => {

package/src/__tests__/validate.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 
 vi.mock('../utils/logger.js', () => ({
   cliLogger: {
@@ -9,10 +9,579 @@ vi.mock('../utils/logger.js', () => ({
   },
 }));
 
+vi.mock('../builder/load-module.js', () => ({
+  loadModuleExports: vi.fn(),
+}));
+vi.mock('../utils/file-helpers.js', () => ({
+  walkDomainDir: vi.fn(),
+}));
+
 import { runValidate } from '../commands/validate.js';
+import { buildRegistry } from '../builder/build-registry.js';
+import { loadModuleExports } from '../builder/load-module.js';
+import { walkDomainDir } from '../utils/file-helpers.js';
+
+const mockLoadModuleExports = vi.mocked(loadModuleExports);
+const mockWalkDomainDir = vi.mocked(walkDomainDir);
 
 describe('runValidate error shape', () => {
   it('throws when domain root has no domain.config.ts', async () => {
     await expect(runValidate('/nonexistent-path', false)).rejects.toThrow();
   });
 });
+
+/**
+ * Action-first migration (#4619, Wave 1 Task 1.2):
+ *
+ * `runValidate` ultimately delegates to `buildRegistry` for the
+ * registry assembly. These tests exercise the action mapping directly
+ * through `buildRegistry` (mocked file walker + module loader) so we
+ * catch regressions in how legacy `visibility` maps to `backendAccess`
+ * and how `exposure` is serialized.
+ */
+describe('buildRegistry action mapping (action-first migration)', () => {
+  const DOMAIN_ROOT = '/fake/domains/billing';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('reads backendAccess directly when raw action exposes it', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/charge-card.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        {
+          _kind: 'action',
+          _exportName: 'chargeCard',
+          id: 'charge-card',
+          backendAccess: 'domain',
+          exposure: {
+            type: 'api',
+            path: '/v1/tenants/{tenantId}/billing/charges',
+            method: 'POST',
+            auth: 'required',
+            tenancy: 'required',
+          },
+          idempotent: true,
+        },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+
+    expect(registry.actions).toHaveLength(1);
+    const action = registry.actions[0]!;
+    expect(action.id).toBe('charge-card');
+    expect(action.backendAccess).toBe('domain');
+    expect(action.exposure.type).toBe('api');
+    if (action.exposure.type === 'api') {
+      expect(action.exposure.path).toBe('/v1/tenants/{tenantId}/billing/charges');
+      expect(action.exposure.method).toBe('POST');
+      expect(action.exposure.auth).toBe('required');
+      expect(action.exposure.tenancy).toBe('required');
+    }
+  });
+
+  it('falls back from legacy visibility to backendAccess and collapses workspace -> domain', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: [
+        '/fake/domains/billing/actions/verify-token.ts',
+        '/fake/domains/billing/actions/provision-tenant.ts',
+      ],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      // First call resolves the actions array (Promise.all maps in order).
+      .mockResolvedValueOnce([
+        { _kind: 'action', _exportName: 'verifyToken', id: 'verify-token', visibility: 'workspace', idempotent: false },
+        { _kind: 'action', _exportName: 'provisionTenant', id: 'provision-tenant', visibility: 'domain', idempotent: true },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+
+    expect(registry.actions).toHaveLength(2);
+    const verify = registry.actions.find(a => a.id === 'verify-token');
+    const provision = registry.actions.find(a => a.id === 'provision-tenant');
+    expect(verify?.backendAccess).toBe('domain');
+    expect(verify?.exposure).toEqual({ type: 'internal' });
+    expect(provision?.backendAccess).toBe('domain');
+    expect(provision?.exposure).toEqual({ type: 'internal' });
+  });
+
+  it('defaults missing exposure to { type: internal } for legacy actions', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/legacy.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        { _kind: 'action', _exportName: 'legacy', id: 'legacy', visibility: 'private', idempotent: false },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+
+    expect(registry.actions[0]?.exposure).toEqual({ type: 'internal' });
+    expect(registry.actions[0]?.backendAccess).toBe('private');
+  });
+
+  it('preserves inputSchema and outputSchema extraction', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/charge-card.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        {
+          _kind: 'action',
+          _exportName: 'chargeCard',
+          id: 'charge-card',
+          backendAccess: 'domain',
+          exposure: { type: 'internal' },
+          idempotent: true,
+          input: { type: 'object', properties: { amount: { type: 'number' } } },
+          output: { type: 'object', properties: { id: { type: 'string' } } },
+        },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+
+    expect(registry.actions[0]?.inputSchema).toEqual({ type: 'object', properties: { amount: { type: 'number' } } });
+    expect(registry.actions[0]?.outputSchema).toEqual({ type: 'object', properties: { id: { type: 'string' } } });
+  });
+});
+
+/**
+ * Action-first security validation rules (#4619, Wave 6 Task 6.1).
+ *
+ * These tests exercise the new validation gates added to `runValidate`.
+ * Each test mocks `buildRegistry` consumers so the assertions target the
+ * rule codes (`ACTION_EXPOSURE_REQUIRED`, `TENANT_API_PATH_REQUIRED`,
+ * `AUTH_NONE_REQUIRES_EXCEPTION`, etc.) without needing a real
+ * domain on disk.
+ */
+describe('runValidate action-first security rules (#4619 / Wave 6)', () => {
+  const DOMAIN_ROOT = '/fake/domains/billing';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  /**
+   * Helper that wires the two file-walker / module-loader mocks so
+   * `buildRegistry` returns the supplied actions plus the canonical
+   * domain row. Returns the ValidationResult
+   * produced by `runValidate`.
+   */
+  async function runValidateWith({
+    actions = [],
+  }: {
+    actions?: Record<string, unknown>[];
+  }): Promise<{ errors: { code: string; message: string }[]; warnings: string[]; valid: boolean; }> {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: actions.map(() => '/fake/domains/billing/actions/x.ts'),
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    // Mock consumption order inside buildRegistry:
+    //   1. domain (paths.domain)        -> mock #1
+    //   2. webhooks/subscribers/schedules/jobs/integrations -> empty arrays, no calls
+    //   3. actions files (paths.actions)-> mock #N (if any)
+    //   4. publishes (paths.publishes)  -> undefined, no call
+    // Each non-empty slot consumes exactly one mock per file (we
+    // generate one synthetic file path per item so the slot has length
+    // equal to the supplied arrays).
+    mockLoadModuleExports.mockResolvedValueOnce([
+      { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+    ]);
+    if (actions.length > 0) {
+      mockLoadModuleExports.mockResolvedValueOnce(actions as never);
+    }
+
+    const result = await runValidate(DOMAIN_ROOT, false);
+    return { errors: result.errors, warnings: result.warnings, valid: result.valid };
+  }
+
+  it('ACTION_EXPOSURE_REQUIRED — fires when a non-private action omits exposure', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        // `backendAccess: 'platform'` is the strongest "new-style" signal;
+        // omitting `exposure` should now fail the build.
+        {
+          _kind: 'action', _exportName: 'sysReset',
+          id: 'sys-reset', backendAccess: 'platform', idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'ACTION_EXPOSURE_REQUIRED');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'sys-reset'");
+  });
+
+  it('ACTION_EXPOSURE_REQUIRED — does NOT fire for explicit internal exposure', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'sysReset',
+          id: 'sys-reset', backendAccess: 'platform',
+          exposure: { type: 'internal' },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'ACTION_EXPOSURE_REQUIRED')).toBeUndefined();
+  });
+
+  it('ACTION_EXPOSURE_REQUIRED — silent on legacy private action (migration compatibility)', async () => {
+    // Legacy `visibility: 'private'` actions map to `backendAccess: 'private'`
+    // and default `exposure` to `{ type: 'internal' }`. The rule must not
+    // flag these so the migration window stays unblocked.
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'legacyPrivate',
+          id: 'legacy-private', visibility: 'private', idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'ACTION_EXPOSURE_REQUIRED')).toBeUndefined();
+  });
+
+  it('TENANT_API_PATH_REQUIRED — fires when tenancy is required but path lacks tenant placeholder', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listAll',
+          id: 'list-all', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/admin/users', method: 'GET',
+            auth: 'required', tenancy: 'required',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'TENANT_API_PATH_REQUIRED');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'list-all'");
+    expect(rule?.message).toContain('/v1/tenants/{tenantId}/');
+  });
+
+  it('TENANT_API_PATH_REQUIRED — passes when tenancy is required AND path includes placeholder', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listUsers',
+          id: 'list-users', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET',
+            auth: 'required', tenancy: 'required',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'TENANT_API_PATH_REQUIRED')).toBeUndefined();
+  });
+
+  it('API_EXPOSURE_AUTH_REQUIRED — fires when auth was defaulted (not declared in source)', async () => {
+    // Source did NOT include `auth` — the builder will default to
+    // 'required' and the validator must surface the omission.
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listUsers',
+          id: 'list-users', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET',
+            tenancy: 'required',
+            // auth omitted on purpose
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'API_EXPOSURE_AUTH_REQUIRED');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'list-users'");
+  });
+
+  it('API_EXPOSURE_AUTH_REQUIRED — silent when auth is explicitly declared', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listUsers',
+          id: 'list-users', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET',
+            auth: 'required', tenancy: 'required',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'API_EXPOSURE_AUTH_REQUIRED')).toBeUndefined();
+  });
+
+  it('AUTH_NONE_REQUIRES_EXCEPTION — fires when auth is none without securityException', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'health',
+          id: 'health', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/health', method: 'GET',
+            auth: 'none', tenancy: 'none',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'health'");
+  });
+
+  it('AUTH_NONE_REQUIRES_EXCEPTION — passes when auth is none WITH securityException.reason', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'health',
+          id: 'health', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/health', method: 'GET',
+            auth: 'none', tenancy: 'none',
+            securityException: { reason: 'public liveness probe; no PII; ticket OPS-123' },
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION')).toBeUndefined();
+  });
+
+  it('AUTH_NONE_REQUIRES_EXCEPTION — fires when securityException.reason is whitespace-only', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'health',
+          id: 'health', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/health', method: 'GET',
+            auth: 'none', tenancy: 'none',
+            securityException: { reason: '   ' },
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION')).toBeDefined();
+  });
+
+  it('TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC — fires when tenancy is none without securityException', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'publicLookup',
+          id: 'public-lookup', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/public/lookup', method: 'GET',
+            auth: 'required', tenancy: 'none',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'public-lookup'");
+  });
+
+  it('SYSTEM_API_REQUIRES_ROLE — fires when system tenancy + required auth without roles', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'adminPing',
+          id: 'admin-ping', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/admin/ping', method: 'GET',
+            auth: 'required', tenancy: 'system',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'SYSTEM_API_REQUIRES_ROLE');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'admin-ping'");
+  });
+
+  it('SYSTEM_API_REQUIRES_ROLE — passes when system tenancy has non-empty roles', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'adminPing',
+          id: 'admin-ping', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/admin/ping', method: 'GET',
+            auth: 'required', tenancy: 'system',
+            roles: ['sys-admin'],
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'SYSTEM_API_REQUIRES_ROLE')).toBeUndefined();
+  });
+
+  it('SYSTEM_API_REQUIRES_ROLE — silent when auth is service (service-only route, no role narrowing required)', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'replicationHook',
+          id: 'replication-hook', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/admin/replicate', method: 'POST',
+            auth: 'service', tenancy: 'system',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'SYSTEM_API_REQUIRES_ROLE')).toBeUndefined();
+  });
+
+  it('combined: well-formed api action passes every rule', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'chargeCard',
+          id: 'charge-card', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/billing/charges', method: 'POST',
+            auth: 'required', tenancy: 'required',
+            roles: ['billing-admin'],
+          },
+          idempotent: true,
+        },
+      ],
+    });
+    const securityCodes = [
+      'ACTION_EXPOSURE_REQUIRED', 'API_EXPOSURE_AUTH_REQUIRED',
+      'TENANT_API_PATH_REQUIRED', 'AUTH_NONE_REQUIRES_EXCEPTION',
+      'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC', 'SYSTEM_API_REQUIRES_ROLE',
+    ];
+    const firedSecurityRules = errors.filter(e => securityCodes.includes(e.code));
+    expect(firedSecurityRules).toHaveLength(0);
+    // Non-security rules (e.g. MISSING_HANDLER_FILE on the synthetic
+    // mock file path) may legitimately fire; we only assert that the
+    // Wave 6 security gates are clean.
+  });
+});
+
+/**
+ * Deployment-time security rules (#4662 Task D, #4689).
+ *
+ * These mirror the CDK aspect's synth-time checks so CI can gate the
+ * build BEFORE synth is attempted. Each rule emits a structured
+ * `ValidationError` whose `code` matches the aspect annotation code,
+ * making the two layers correlatable.
+ *
+ * Issue #4689: defineApi and registry.apis were removed. The action-first
+ * `TENANT_API_PATH_REQUIRED` rule in the `#4619 / Wave 6` suite now owns
+ * the placeholder invariant. The deployment-time rules below assert that
+ * no duplicate `SECURITY_MISSING_TENANT_PATH` codes are emitted for the
+ * action surface.
+ */
+describe('runValidate deployment-time security rules (#4662 Task D)', () => {
+  const DOMAIN_ROOT = '/fake/domains/billing';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  async function runValidateWith({
+    actions = [],
+  }: {
+    actions?: Record<string, unknown>[];
+  }): Promise<{ errors: { code: string; message: string }[]; warnings: string[]; valid: boolean; }> {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: actions.map(() => '/fake/domains/billing/actions/x.ts'),
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports.mockResolvedValueOnce([
+      { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+    ]);
+    if (actions.length > 0) {
+      mockLoadModuleExports.mockResolvedValueOnce(actions as never);
+    }
+
+    const result = await runValidate(DOMAIN_ROOT, false);
+    return { errors: result.errors, warnings: result.warnings, valid: result.valid };
+  }
+
+  it('does NOT emit SECURITY_MISSING_TENANT_PATH for an action that already includes the tenant placeholder', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listUsers',
+          id: 'list-users', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET',
+            auth: 'required', tenancy: 'required',
+          },
+          idempotent: true,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'SECURITY_MISSING_TENANT_PATH')).toBeUndefined();
+  });
+});