@mettlecast/domain-cdk-packer 0.2.87 → 0.2.88

package/dist/DomainStack.js

@@ -19,6 +19,7 @@ import { AlarmConstruct } from './constructs/alarm-construct.js';
 import { CanaryConstruct } from './constructs/canary-construct.js';
 import { domainResourceName } from './naming.js';
 import { SecurityAssertionAspect } from './aspects/security-assertion-aspect.js';
+import { validateRegistry } from './validate-registry.js';
 /** L1 helper: adds a CfnRoute + CfnIntegration to an existing HTTP API. */
 function addRouteToApi(scope, fn, path, methods, apiId, auth) {
     const id = path.replace(/[^a-zA-Z0-9]/g, '_').replace(/^_/, 'api') + '_' + methods[0].toLowerCase();
@@ -64,6 +65,16 @@ export class DomainStack extends cdk.Stack {
      */
     constructor(scope, id, props) {
         super(scope, id, props);
+        // Validate registry against strict contract before creating any constructs (#5090).
+        const validationErrors = validateRegistry(props.registry);
+        if (validationErrors.length > 0) {
+            const lines = validationErrors.map(e => {
+                const code = e.code ? ` [${e.code}]` : '';
+                return `  [${e.field}]${code} ${e.message}`;
+            });
+            throw new Error(`Registry validation failed for domain '${props.registry.domain?.id ?? '<unknown>'}':\n${lines.join('\n')}\n\n` +
+                `Fix registry data before deploying.`);
+        }
         const { registry, eventBusArn, eventBusName, databaseUrl, dbSecretArn, appSecretArn, userPoolArn, userPoolId, userPoolClientId, internalSubnetSelection, internetSubnetSelection, enableCmk, enableWaf, enableAlarms, alarmSnsTopicArn, enableCanaryDeploy, reservedConcurrency, logRetentionDays, corsAllowedOrigins, allowCredentials, disableCloudWatchDashboards } = props;
         const vpc = props.vpc ?? (props.vpcId
             ? ec2.Vpc.fromVpcAttributes(this, 'SharedVpc', {

package/dist/__tests__/domain-stack.test.js

@@ -43,6 +43,8 @@ const minimalRegistry = {
                 tenancy: 'required',
             },
             idempotent: false,
+            inputSchema: { type: 'object', properties: {} },
+            outputSchema: { type: 'object', properties: {} },
         },
     ],
     integrations: [],
@@ -228,36 +230,48 @@ describe('DomainStack', () => {
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
                 {
                     id: 'create-user', kind: 'action', handlerFile: 'src/handlers/create-user.ts',
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'POST', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
                 {
                     id: 'replace-user', kind: 'action', handlerFile: 'src/handlers/replace-user.ts',
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users/{id}', method: 'PUT', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
                 {
                     id: 'patch-user', kind: 'action', handlerFile: 'src/handlers/patch-user.ts',
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users/{id}', method: 'PATCH', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
                 {
                     id: 'delete-user', kind: 'action', handlerFile: 'src/handlers/delete-user.ts',
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users/{id}', method: 'DELETE', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
                 {
                     id: 'list-things', kind: 'action', handlerFile: 'src/handlers/list-things.ts',
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/things', method: 'GET', auth: 'none', tenancy: 'required', securityException: { reason: 'public read-only listing' } },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
             ],
         };

package/dist/__tests__/pack-domain.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/pack-domain.test.js

@@ -0,0 +1,325 @@
+import { describe, it, expect } from 'vitest';
+import { validateRegistry } from '../validate-registry.js';
+describe('validateRegistry (#5090 strict contract)', () => {
+    const validRegistry = {
+        schemaVersion: '1',
+        domainRoot: '/tmp/test',
+        domain: { id: 'test-domain', kind: 'domain', name: 'Test Domain', tenancy: 'required' },
+        webhooks: [],
+        subscribers: [],
+        schedules: [],
+        jobs: [],
+        actions: [],
+        integrations: [],
+        events: [],
+    };
+    it('accepts an empty registry (no actions)', () => {
+        const errors = validateRegistry(validRegistry);
+        expect(errors).toHaveLength(0);
+    });
+    it('accepts a valid internal action', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'do-thing',
+                    kind: 'action',
+                    handlerFile: 'src/actions/do-thing.ts',
+                    backendAccess: 'private',
+                    exposure: { type: 'internal' },
+                    idempotent: false,
+                },
+            ],
+        };
+        expect(validateRegistry(registry)).toHaveLength(0);
+    });
+    it('accepts a valid API-exposed action', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'list-users',
+                    kind: 'action',
+                    handlerFile: 'src/actions/list-users.ts',
+                    backendAccess: 'domain',
+                    exposure: {
+                        type: 'api',
+                        path: '/v1/tenants/{tenantId}/users',
+                        method: 'GET',
+                        auth: 'required',
+                        tenancy: 'required',
+                    },
+                    idempotent: false,
+                    inputSchema: { type: 'object', properties: { limit: { type: 'number' } } },
+                    outputSchema: { type: 'object', properties: { items: { type: 'array' } } },
+                },
+            ],
+        };
+        expect(validateRegistry(registry)).toHaveLength(0);
+    });
+    it('rejects missing exposure', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'no-exposure',
+                    kind: 'action',
+                    handlerFile: 'src/actions/no-exposure.ts',
+                    backendAccess: 'private',
+                    exposure: undefined,
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'exposure')).toBe(true);
+    });
+    it('rejects null exposure', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'null-exposure',
+                    kind: 'action',
+                    handlerFile: 'src/actions/null-exposure.ts',
+                    backendAccess: 'private',
+                    exposure: null,
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'exposure')).toBe(true);
+    });
+    it('rejects malformed exposure type', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'bad-type',
+                    kind: 'action',
+                    handlerFile: 'src/actions/bad-type.ts',
+                    backendAccess: 'private',
+                    exposure: { type: 'public' },
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'exposure.type')).toBe(true);
+    });
+    it('rejects internal exposure with extra keys', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'internal-extra',
+                    kind: 'action',
+                    handlerFile: 'src/actions/internal-extra.ts',
+                    backendAccess: 'private',
+                    exposure: { type: 'internal', path: '/v1/secret' },
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        // Should complain about unexpected keys on internal
+        expect(errors.some(e => e.message.includes('unexpected keys'))).toBe(true);
+    });
+    it('rejects API exposure missing path', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'no-path',
+                    kind: 'action',
+                    handlerFile: 'src/actions/no-path.ts',
+                    backendAccess: 'domain',
+                    exposure: { type: 'api', method: 'GET', auth: 'required', tenancy: 'required' },
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'exposure.path')).toBe(true);
+    });
+    it('rejects API exposure missing method', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'no-method',
+                    kind: 'action',
+                    handlerFile: 'src/actions/no-method.ts',
+                    backendAccess: 'domain',
+                    exposure: { type: 'api', path: '/v1/test', auth: 'required', tenancy: 'required' },
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'exposure.method')).toBe(true);
+    });
+    it('rejects API exposure with invalid auth', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'bad-auth',
+                    kind: 'action',
+                    handlerFile: 'src/actions/bad-auth.ts',
+                    backendAccess: 'domain',
+                    exposure: { type: 'api', path: '/v1/test', method: 'GET', auth: 'invalid', tenancy: 'required' },
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'exposure.auth')).toBe(true);
+    });
+    it('rejects missing backendAccess', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'no-backend',
+                    kind: 'action',
+                    handlerFile: 'src/actions/no-backend.ts',
+                    backendAccess: undefined,
+                    exposure: { type: 'internal' },
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'backendAccess')).toBe(true);
+    });
+    it('rejects invalid backendAccess', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'bad-backend',
+                    kind: 'action',
+                    handlerFile: 'src/actions/bad-backend.ts',
+                    backendAccess: 'public',
+                    exposure: { type: 'internal' },
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'backendAccess')).toBe(true);
+    });
+    it('rejects non-boolean idempotent', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'bad-idempotent',
+                    kind: 'action',
+                    handlerFile: 'src/actions/bad-idempotent.ts',
+                    backendAccess: 'private',
+                    exposure: { type: 'internal' },
+                    idempotent: 'yes',
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'idempotent')).toBe(true);
+    });
+    it('rejects null action entries', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                null,
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'actions')).toBe(true);
+    });
+    it('rejects missing handlerFile', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'no-handler',
+                    kind: 'action',
+                    handlerFile: '',
+                    backendAccess: 'private',
+                    exposure: { type: 'internal' },
+                    idempotent: false,
+                },
+            ],
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'handlerFile')).toBe(true);
+    });
+    it('rejects wrong schemaVersion', () => {
+        const registry = {
+            ...validRegistry,
+            schemaVersion: '2',
+        };
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThan(0);
+        expect(errors.some(e => e.field === 'schemaVersion')).toBe(true);
+    });
+    it('reports multiple errors for a completely malformed action', () => {
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: '',
+                    kind: 'not-action',
+                    handlerFile: '',
+                    backendAccess: 'bad',
+                    exposure: undefined,
+                    idempotent: 'nope',
+                },
+            ],
+        };
+        // Should have multiple errors about different fields
+        const errors = validateRegistry(registry);
+        expect(errors.length).toBeGreaterThanOrEqual(3);
+    });
+    it('does NOT reject actions with valid authDeclared/tenancyDeclared flags', () => {
+        // The authDeclared/tenancyDeclared flags are part of the registry data
+        // and must not be treated as unexpected keys on internal exposure
+        const registry = {
+            ...validRegistry,
+            actions: [
+                {
+                    id: 'with-declared',
+                    kind: 'action',
+                    handlerFile: 'src/actions/with-declared.ts',
+                    backendAccess: 'domain',
+                    exposure: {
+                        type: 'api',
+                        path: '/v1/tenants/{tenantId}/users',
+                        method: 'GET',
+                        auth: 'required',
+                        tenancy: 'required',
+                        authDeclared: true,
+                        tenancyDeclared: true,
+                    },
+                    idempotent: false,
+                    inputSchema: { type: 'object', properties: { limit: { type: 'number' } } },
+                    outputSchema: { type: 'object', properties: { items: { type: 'array' } } },
+                },
+            ],
+        };
+        expect(validateRegistry(registry)).toHaveLength(0);
+    });
+});

package/dist/__tests__/security-assertion-aspect.test.js

@@ -29,6 +29,8 @@ function buildStackAndGetErrors(registry) {
     const stack = new DomainStack(app, 'SecAspectStack', {
         registry,
         eventBusArn: 'arn:aws:events:eu-north-1:123456789012:event-bus/tib-event-bus',
+        projectId: 'mtc',
+        envCode: 'dev',
     });
     // Force synthesis so the aspect's visit() fires.
     try {
@@ -59,13 +61,7 @@ beforeAll(() => {
     // entry id (`list-users` -> `listUsers`). We provide every named export
     // the security-aspect test uses so each test can pick the same handler
     // file regardless of which entry id it instantiates.
-    //
-    // Issue #4689: defineApi was removed; HTTP endpoints are now declared
-    // as actions with `exposure.type === 'api'`. Each named export below
-    // matches one of the action ids used in the test fixtures.
     fs.writeFileSync(path.join(handlerDir, 'noop.ts'), [
-        // Match the grouped-lambda-factory's export-name conversion so the
-        // bundler can resolve the import for every test fixture.
         'export const listUsers = { id: "list-users", backendAccess: "domain", exposure: { type: "api", path: "/v1/tenants/{tenantId}/users", method: "GET", auth: "required", tenancy: "required" }, input: { parse: (x) => x }, output: { parse: (x) => x }, idempotent: false, handler: async () => ({ ok: true }) };',
         'export const listAll = { id: "list-all", backendAccess: "domain", exposure: { type: "api", path: "/v1/tenants/{tenantId}/all", method: "GET", auth: "required", tenancy: "required" }, input: { parse: (x) => x }, output: { parse: (x) => x }, idempotent: false, handler: async () => ({ ok: true }) };',
         'export const noopAction = { id: "noop-action", backendAccess: "private", exposure: { type: "internal" }, input: { parse: (x) => x }, output: { parse: (x) => x }, idempotent: false, handler: async () => ({ ok: true }) };',
@@ -79,8 +75,13 @@ afterAll(() => {
  * last line of defence: it walks the synthesised tree and verifies the
  * invariants the CLI validator already enforces. These tests pin each
  * invariant independently so a regression in any single check is caught.
+ *
+ * Issue #5090 — the strict registry contract now validates all action
+ * entries before any constructs are created. Null/missing exposure
+ * entries are rejected at validation time, so the aspect no longer
+ * needs to handle them.
  */
-describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
+describe('SecurityAssertionAspect (#4662 Task D, #4689, #5090)', () => {
     it('does not emit errors for an empty registry', () => {
         const { errorMessages } = buildStackAndGetErrors(baseRegistry);
         // The base stack emits zero routes / zero Function URLs, so the aspect
@@ -89,9 +90,6 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
         expect(errorMessages.filter(m => aspectCodes.some(c => m.includes(c)))).toHaveLength(0);
     });
     it('emits SECURITY_MISSING_TENANT_PATH when an action API path lacks the tenant placeholder', () => {
-        // Issue #4689: the canonical HTTP endpoint surface is the action
-        // array with `exposure.type === 'api'`. The aspect now reads from
-        // `actions[]` rather than `apis[]`.
         const registry = {
             ...baseRegistry,
             actions: [
@@ -100,6 +98,8 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/users', method: 'GET', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
             ],
         };
@@ -115,6 +115,8 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
             ],
         };
@@ -132,6 +134,8 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
             ],
         };
@@ -139,9 +143,6 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
         expect(errorMessages.some(m => m.includes('SECURITY_MISSING_JWT_AUTHORIZER') || m.includes('JWT-protected routes'))).toBe(true);
     });
     it('does NOT emit SECURITY_MISSING_SECURITY_EXCEPTION when authType is none but the route is the health probe', () => {
-        // The DomainStack installs the health/ready probes as `authType: 'none'` routes.
-        // Because they are special-cased in the aspect (and CLI validator
-        // ignores them), the aspect must NOT fire for them.
         const registry = {
             ...baseRegistry,
         };
@@ -149,13 +150,9 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
         expect(errorMessages.some(m => m.includes('SECURITY_MISSING_SECURITY_EXCEPTION'))).toBe(false);
     });
     it('does NOT emit Function URL error for the existing health/ready probes', () => {
-        // HealthConstruct attaches `Lambda::Url` to its functions. The aspect
-        // exempts them via fn-name regex; we must not regress that exemption.
         const registry = { ...baseRegistry };
         const { errorMessages } = buildStackAndGetErrors(registry);
         // HealthConstruct uses NodejsFunction which DOES NOT create Lambda::Url
-        // (URLs are only created when fn.addFunctionUrl is called). So there
-        // should be no Function URL errors at all on the base stack.
         expect(errorMessages.some(m => m.includes('SECURITY_ACTION_FUNCTION_URL'))).toBe(false);
     });
     it('emits SECURITY_MISSING_TENANT_PATH for an action exposure with tenancy=required but bad path', () => {
@@ -169,6 +166,8 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/admin/users', method: 'GET', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
             ],
         };
@@ -186,6 +185,8 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
                     backendAccess: 'domain',
                     exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET', auth: 'required', tenancy: 'required' },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
             ],
         };
@@ -210,13 +211,80 @@ describe('SecurityAssertionAspect (#4662 Task D, #4689)', () => {
                         securityException: { reason: 'public liveness probe; ticket OPS-123' },
                     },
                     idempotent: false,
+                    inputSchema: { type: 'object', properties: {} },
+                    outputSchema: { type: 'object', properties: {} },
                 },
             ],
         };
         const { errorMessages } = buildStackAndGetErrors(registry);
-        // Note: the CLI validator's AUTH_NONE_REQUIRES_EXCEPTION rule mirrors
-        // this; we only check that the *aspect* does not block a well-formed
-        // action.
         expect(errorMessages.some(m => m.includes('SECURITY_MISSING_SECURITY_EXCEPTION'))).toBe(false);
     });
+    /**
+     * Issue #5090 — strict registry contract: null/missing exposure entries
+     * are rejected at validation time. The tests below verify that
+     * DomainStack throws when given an invalid registry, rather than
+     * silently skipping bad entries.
+     */
+    describe('strict validation rejects malformed entries (#5090)', () => {
+        it('throws on null exposure', () => {
+            const registry = {
+                ...baseRegistry,
+                actions: [
+                    {
+                        id: 'null-exposure',
+                        kind: 'action',
+                        handlerFile: 'src/handlers/noop.ts',
+                        backendAccess: 'domain',
+                        exposure: null,
+                        idempotent: false,
+                    },
+                ],
+            };
+            expect(() => {
+                const app = new cdk.App();
+                new DomainStack(app, 'NullExposureStack', { registry, eventBusArn: 'arn:aws:events:eu-north-1:123456789012:event-bus/tib-event-bus' });
+            }).toThrow('Registry validation failed');
+        });
+        it('throws on undefined exposure', () => {
+            const registry = {
+                ...baseRegistry,
+                actions: [
+                    {
+                        id: 'missing-exposure',
+                        kind: 'action',
+                        handlerFile: 'src/handlers/noop.ts',
+                        backendAccess: 'domain',
+                        exposure: undefined,
+                        idempotent: false,
+                    },
+                ],
+            };
+            expect(() => {
+                const app = new cdk.App();
+                new DomainStack(app, 'MissingExposureStack', { registry, eventBusArn: 'arn:aws:events:eu-north-1:123456789012:event-bus/tib-event-bus' });
+            }).toThrow('Registry validation failed');
+        });
+        it('throws on null entry in actions array', () => {
+            const registry = {
+                ...baseRegistry,
+                actions: [
+                    null,
+                    {
+                        id: 'list-users',
+                        kind: 'action',
+                        handlerFile: 'src/handlers/noop.ts',
+                        backendAccess: 'domain',
+                        exposure: { type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET', auth: 'required', tenancy: 'required' },
+                        idempotent: false,
+                        inputSchema: { type: 'object', properties: {} },
+                        outputSchema: { type: 'object', properties: {} },
+                    },
+                ],
+            };
+            expect(() => {
+                const app = new cdk.App();
+                new DomainStack(app, 'NullEntryStack', { registry, eventBusArn: 'arn:aws:events:eu-north-1:123456789012:event-bus/tib-event-bus' });
+            }).toThrow('Registry validation failed');
+        });
+    });
 });

package/dist/__tests__/validate-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/validate-registry.test.js

@@ -0,0 +1,352 @@
+import { describe, it, expect } from 'vitest';
+import { validateRegistry } from '../validate-registry.js';
+/**
+ * Helper: build a minimal valid registry, then override specific fields
+ * for each test case.
+ */
+function minimalValidRegistry(overrides) {
+    return {
+        schemaVersion: '1',
+        domainRoot: '/workspace/my-domain',
+        domain: { id: 'my-domain', kind: 'domain', name: 'My Domain', tenancy: 'required' },
+        webhooks: [],
+        subscribers: [],
+        schedules: [],
+        jobs: [],
+        actions: [],
+        integrations: [],
+        events: [],
+        ...overrides,
+    };
+}
+/**
+ * Helper: build a valid API action entry that passes all checks.
+ */
+function validApiAction(overrides) {
+    return {
+        id: 'test-action',
+        kind: 'action',
+        handlerFile: 'src/actions/test.ts',
+        backendAccess: 'domain',
+        idempotent: true,
+        exposure: {
+            type: 'api',
+            path: '/v1/tenants/{tenantId}/test',
+            method: 'GET',
+            auth: 'required',
+            tenancy: 'required',
+        },
+        inputSchema: { type: 'object', properties: { foo: { type: 'string' } } },
+        outputSchema: { type: 'object', properties: { bar: { type: 'number' } } },
+        ...overrides,
+    };
+}
+describe('validateRegistry', () => {
+    describe('structural checks', () => {
+        it('passes for a valid minimal registry with no actions', () => {
+            const errors = validateRegistry(minimalValidRegistry());
+            expect(errors).toHaveLength(0);
+        });
+        it('passes for a valid registry with a well-formed API action', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction()],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors).toHaveLength(0);
+        });
+        it('passes for a valid internal action', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'internal-action',
+                        kind: 'action',
+                        handlerFile: 'src/actions/internal.ts',
+                        backendAccess: 'private',
+                        idempotent: false,
+                        exposure: { type: 'internal' },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors).toHaveLength(0);
+        });
+        it('rejects null/undefined action at index', () => {
+            const registry = minimalValidRegistry();
+            registry.actions = [null];
+            const errors = validateRegistry(registry);
+            expect(errors.length).toBeGreaterThan(0);
+            expect(errors[0]?.code).toBe('ACTION_NULL');
+        });
+        it('rejects missing domain entry', () => {
+            const registry = minimalValidRegistry({ domain: undefined });
+            const errors = validateRegistry(registry);
+            expect(errors.length).toBeGreaterThan(0);
+            expect(errors[0]?.code).toBe('DOMAIN_MISSING');
+        });
+        it('rejects invalid schemaVersion', () => {
+            const registry = minimalValidRegistry({ schemaVersion: '2' });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'SCHEMA_VERSION')).toBe(true);
+        });
+        it('rejects missing kind', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'bad-kind',
+                        kind: 'webhook',
+                        handlerFile: 'src/actions/bad.ts',
+                        backendAccess: 'private',
+                        idempotent: false,
+                        exposure: { type: 'internal' },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'ACTION_KIND_INVALID')).toBe(true);
+        });
+        it('rejects missing handlerFile', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'no-handler',
+                        kind: 'action',
+                        backendAccess: 'private',
+                        idempotent: false,
+                        exposure: { type: 'internal' },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'ACTION_HANDLER_MISSING')).toBe(true);
+        });
+        it('rejects invalid backendAccess', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'bad-backend',
+                        kind: 'action',
+                        handlerFile: 'src/actions/bad.ts',
+                        backendAccess: 'public',
+                        idempotent: false,
+                        exposure: { type: 'internal' },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'ACTION_BACKEND_ACCESS_INVALID')).toBe(true);
+        });
+        it('rejects non-boolean idempotent', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'bad-idempotent',
+                        kind: 'action',
+                        handlerFile: 'src/actions/bad.ts',
+                        backendAccess: 'private',
+                        idempotent: 'yes',
+                        exposure: { type: 'internal' },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'ACTION_IDEMPOTENT_INVALID')).toBe(true);
+        });
+        it('rejects missing exposure', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'no-exposure',
+                        kind: 'action',
+                        handlerFile: 'src/actions/no-exp.ts',
+                        backendAccess: 'private',
+                        idempotent: false,
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'ACTION_EXPOSURE_MISSING')).toBe(true);
+        });
+        it('rejects invalid exposure type', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'bad-exp-type',
+                        kind: 'action',
+                        handlerFile: 'src/actions/bad-exp.ts',
+                        backendAccess: 'private',
+                        idempotent: false,
+                        exposure: { type: 'hybrid' },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'ACTION_EXPOSURE_TYPE_INVALID')).toBe(true);
+        });
+        it('rejects internal exposure with extra keys', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'internal-extra',
+                        kind: 'action',
+                        handlerFile: 'src/actions/extra.ts',
+                        backendAccess: 'private',
+                        idempotent: false,
+                        exposure: { type: 'internal', path: '/v1/secret' },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'INTERNAL_EXPOSURE_EXTRA_KEYS')).toBe(true);
+        });
+    });
+    describe('API exposure validation', () => {
+        it('rejects API action missing path', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', method: 'GET', auth: 'required', tenancy: 'required' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_PATH_INVALID')).toBe(true);
+        });
+        it('rejects API action with path not starting with /', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: 'v1/test', method: 'GET', auth: 'required', tenancy: 'required' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_PATH_INVALID')).toBe(true);
+        });
+        it('rejects API action missing method', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/test', auth: 'required', tenancy: 'required' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_METHOD_INVALID')).toBe(true);
+        });
+        it('rejects invalid HTTP method', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/test', method: 'INVALID', auth: 'required', tenancy: 'required' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'INVALID_HTTP_METHOD')).toBe(true);
+        });
+        it('rejects API action missing auth', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/test', method: 'GET', tenancy: 'required' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_AUTH_INVALID')).toBe(true);
+        });
+        it('rejects API action missing tenancy', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/test', method: 'GET', auth: 'required' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_TENANCY_INVALID')).toBe(true);
+        });
+    });
+    describe('input/output schema validation for API actions', () => {
+        it('rejects API action lacking inputSchema', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'no-input',
+                        kind: 'action',
+                        handlerFile: 'src/actions/no-input.ts',
+                        backendAccess: 'domain',
+                        idempotent: false,
+                        exposure: { type: 'api', path: '/v1/tenants/{tenantId}/test', method: 'GET', auth: 'required', tenancy: 'required' },
+                        outputSchema: { type: 'object', properties: { id: { type: 'string' } } },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_INPUT_SCHEMA_REQUIRED')).toBe(true);
+        });
+        it('rejects API action lacking outputSchema', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'no-output',
+                        kind: 'action',
+                        handlerFile: 'src/actions/no-output.ts',
+                        backendAccess: 'domain',
+                        idempotent: false,
+                        exposure: { type: 'api', path: '/v1/tenants/{tenantId}/test', method: 'GET', auth: 'required', tenancy: 'required' },
+                        inputSchema: { type: 'object', properties: { foo: { type: 'string' } } },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_OUTPUT_SCHEMA_REQUIRED')).toBe(true);
+        });
+        it('accepts API action with empty inputSchema object (empty schema is valid)', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'empty-input',
+                        kind: 'action',
+                        handlerFile: 'src/actions/empty-input.ts',
+                        backendAccess: 'domain',
+                        idempotent: false,
+                        exposure: { type: 'api', path: '/v1/tenants/{tenantId}/test', method: 'GET', auth: 'required', tenancy: 'required' },
+                        inputSchema: {},
+                        outputSchema: { type: 'object', properties: { id: { type: 'string' } } },
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_INPUT_SCHEMA_REQUIRED')).toBe(false);
+        });
+        it('accepts API action with empty outputSchema object (empty schema is valid)', () => {
+            const registry = minimalValidRegistry({
+                actions: [{
+                        id: 'empty-output',
+                        kind: 'action',
+                        handlerFile: 'src/actions/empty-output.ts',
+                        backendAccess: 'domain',
+                        idempotent: false,
+                        exposure: { type: 'api', path: '/v1/tenants/{tenantId}/test', method: 'GET', auth: 'required', tenancy: 'required' },
+                        inputSchema: { type: 'object', properties: { foo: { type: 'string' } } },
+                        outputSchema: {},
+                    }],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'API_OUTPUT_SCHEMA_REQUIRED')).toBe(false);
+        });
+    });
+    describe('security exception validation', () => {
+        it('rejects auth: none without securityException.reason', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/health', method: 'GET', auth: 'none', tenancy: 'none' }, inputSchema: { type: 'object', properties: {} }, outputSchema: { type: 'object', properties: {} } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION')).toBe(true);
+        });
+        it('accepts auth: none with valid securityException.reason', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/health', method: 'GET', auth: 'none', tenancy: 'none', securityException: { reason: 'public health check; ticket OPS-123' } } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION')).toBe(false);
+        });
+        it('rejects auth: none with whitespace-only securityException.reason', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/health', method: 'GET', auth: 'none', tenancy: 'none', securityException: { reason: '   ' } } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION')).toBe(true);
+        });
+        it('rejects tenancy: none without securityException.reason', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/public/lookup', method: 'GET', auth: 'required', tenancy: 'none' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC')).toBe(true);
+        });
+        it('accepts tenancy: none with valid securityException.reason', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/public/lookup', method: 'GET', auth: 'required', tenancy: 'none', securityException: { reason: 'no-tenant lookup; ticket OPS-456' } } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC')).toBe(false);
+        });
+        it('rejects system tenancy + required auth without roles', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/admin/ping', method: 'GET', auth: 'required', tenancy: 'system' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'SYSTEM_API_REQUIRES_ROLE')).toBe(true);
+        });
+        it('accepts system tenancy + required auth with roles', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/admin/ping', method: 'GET', auth: 'required', tenancy: 'system', roles: ['sys-admin'] } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'SYSTEM_API_REQUIRES_ROLE')).toBe(false);
+        });
+        it('accepts system tenancy + service auth without roles (service-only route)', () => {
+            const registry = minimalValidRegistry({
+                actions: [validApiAction({ exposure: { type: 'api', path: '/v1/admin/replicate', method: 'POST', auth: 'service', tenancy: 'system' } })],
+            });
+            const errors = validateRegistry(registry);
+            expect(errors.some(e => e.code === 'SYSTEM_API_REQUIRES_ROLE')).toBe(false);
+        });
+    });
+});

package/dist/index.d.ts

@@ -29,6 +29,8 @@ export { DomainStack } from './DomainStack.js';
 export type { DomainStackProps } from './DomainStack.js';
 export { packDomain } from './pack-domain.js';
 export type { PackDomainOptions } from './pack-domain.js';
+export { validateRegistry } from './validate-registry.js';
+export type { RegistryValidationError } from './validate-registry.js';
 export { StepFunctionsCodegen } from './step-functions-codegen.js';
 export type { DomainActionFlowNode, StepFunctionsTaskState } from './step-functions-codegen.js';
 export type { FlowRegistry, FlowRegistryEntry, SerialFlowStep, SerialDomainActionStep, SerialDomainApiStep, SerialDomainEventStep, SerialDomainQueryStep, SerialAwsServiceStep, SerialFlowControlStep } from './flow-registry.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export { AlarmConstruct } from './constructs/alarm-construct.js';
 export { CanaryConstruct } from './constructs/canary-construct.js';
 export { DomainStack } from './DomainStack.js';
 export { packDomain } from './pack-domain.js';
+export { validateRegistry } from './validate-registry.js';
 export { StepFunctionsCodegen } from './step-functions-codegen.js';
 export { FlowsStack, packFlows } from './pack-flows.js';
 export { domainResourceName } from './naming.js';

package/dist/pack-domain.js

@@ -1,4 +1,5 @@
 import { DomainStack } from './DomainStack.js';
+import { validateRegistry } from './validate-registry.js';
 /**
  * Convenience entry-point: constructs a DomainStack from a compiled registry.
  * Intended to be called from a CDK app entrypoint (e.g. bin/app.ts in the project's infra).
@@ -11,6 +12,16 @@ import { DomainStack } from './DomainStack.js';
  * @returns The constructed DomainStack.
  */
 export function packDomain(registry, app, stackId, eventBusArn, options) {
+    // Validate registry before any CDK constructs are created (#5090)
+    const validationErrors = validateRegistry(registry);
+    if (validationErrors.length > 0) {
+        const lines = validationErrors.map(e => {
+            const code = e.code ? ` [${e.code}]` : '';
+            return `  [${e.field}]${code} ${e.message}`;
+        });
+        throw new Error(`Registry validation failed for domain '${registry.domain?.id ?? '<unknown>'}':\n${lines.join('\n')}\n\n` +
+            `Fix these issues in your domain source before deploying.`);
+    }
     // Support both old (env as 5th arg) and new (options object) calling conventions
     // Check if options looks like a CDK Environment (has 'account' and/or 'region' props, not the full options interface)
     const opts = options &&

package/dist/validate-registry.d.ts

@@ -0,0 +1,38 @@
+import type { DomainRegistry } from './registry.js';
+/**
+ * Validation error detail.
+ */
+export interface RegistryValidationError {
+    /** Domain ID from the registry. */
+    domainId: string;
+    /** Entry ID (action id, etc). */
+    entryId: string;
+    /** Field path that failed validation. */
+    field: string;
+    /** Stable error code for CI/tooling correlation. */
+    code?: string;
+    /** Human-readable error message. */
+    message: string;
+}
+/**
+ * Validate a DomainRegistry against the strict contract (#5090) before
+ * any CDK constructs are created.
+ *
+ * Checks:
+ * - Every action has `kind: 'action'`, `id`, `handlerFile`, `backendAccess`,
+ *   `idempotent`, and explicit `exposure`.
+ * - API exposure requires non-empty `path`, valid HTTP `method`, valid
+ *   `auth`, valid `tenancy`.
+ * - API-exposed actions must have non-empty `inputSchema` and `outputSchema`.
+ * - `auth: 'none'` requires a `securityException.reason`.
+ * - `tenancy: 'none'` requires a `securityException.reason`.
+ * - `tenancy: 'system'` + `auth: 'required'` requires non-empty `roles`.
+ * - Internal exposure must be exactly `{type:'internal'}`.
+ * - Path must start with `/`.
+ * - No null/undefined entries in arrays.
+ * - Schema version contract is honoured.
+ *
+ * @param registry The compiled domain registry.
+ * @returns Array of validation errors. Empty array means valid.
+ */
+export declare function validateRegistry(registry: DomainRegistry): RegistryValidationError[];

package/dist/validate-registry.js

@@ -0,0 +1,205 @@
+/**
+ * Allowed HTTP methods for API-exposed actions.
+ */
+const ALLOWED_HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+/**
+ * Validate a DomainRegistry against the strict contract (#5090) before
+ * any CDK constructs are created.
+ *
+ * Checks:
+ * - Every action has `kind: 'action'`, `id`, `handlerFile`, `backendAccess`,
+ *   `idempotent`, and explicit `exposure`.
+ * - API exposure requires non-empty `path`, valid HTTP `method`, valid
+ *   `auth`, valid `tenancy`.
+ * - API-exposed actions must have non-empty `inputSchema` and `outputSchema`.
+ * - `auth: 'none'` requires a `securityException.reason`.
+ * - `tenancy: 'none'` requires a `securityException.reason`.
+ * - `tenancy: 'system'` + `auth: 'required'` requires non-empty `roles`.
+ * - Internal exposure must be exactly `{type:'internal'}`.
+ * - Path must start with `/`.
+ * - No null/undefined entries in arrays.
+ * - Schema version contract is honoured.
+ *
+ * @param registry The compiled domain registry.
+ * @returns Array of validation errors. Empty array means valid.
+ */
+export function validateRegistry(registry) {
+    const errors = [];
+    const domainId = registry.domain?.id ?? '<unknown>';
+    if (!registry.domain) {
+        errors.push({ domainId, entryId: '', field: 'domain', code: 'DOMAIN_MISSING', message: 'Registry has no domain entry.' });
+        return errors;
+    }
+    // Schema version contract
+    if (registry.schemaVersion !== '1') {
+        errors.push({
+            domainId, entryId: '', field: 'schemaVersion', code: 'SCHEMA_VERSION',
+            message: `Registry schemaVersion must be '1'. Got: ${JSON.stringify(registry.schemaVersion)}`,
+        });
+    }
+    // Validate every action entry
+    for (let i = 0; i < (registry.actions ?? []).length; i++) {
+        const action = registry.actions[i];
+        const entryId = action?.id ?? `[index ${i}]`;
+        if (action == null) {
+            errors.push({
+                domainId, entryId, field: 'actions', code: 'ACTION_NULL',
+                message: `Action at index ${i} is null or undefined. All action entries must be valid objects.`,
+            });
+            continue;
+        }
+        // kind must be 'action'
+        if (action.kind !== 'action') {
+            errors.push({
+                domainId, entryId, field: 'kind', code: 'ACTION_KIND_INVALID',
+                message: `Action '${entryId}' has kind '${action.kind}', expected 'action'.`,
+            });
+        }
+        // id must be non-empty
+        if (!action.id || typeof action.id !== 'string') {
+            errors.push({
+                domainId, entryId, field: 'id', code: 'ACTION_ID_MISSING',
+                message: `Action at index ${i} has missing or invalid id.`,
+            });
+        }
+        // handlerFile must be non-empty
+        if (!action.handlerFile || typeof action.handlerFile !== 'string') {
+            errors.push({
+                domainId, entryId, field: 'handlerFile', code: 'ACTION_HANDLER_MISSING',
+                message: `Action '${entryId}' is missing handlerFile (required).`,
+            });
+        }
+        // backendAccess must be valid
+        const validBackendAccess = ['private', 'domain', 'platform'];
+        if (!action.backendAccess || !validBackendAccess.includes(action.backendAccess)) {
+            errors.push({
+                domainId, entryId, field: 'backendAccess', code: 'ACTION_BACKEND_ACCESS_INVALID',
+                message: `Action '${entryId}' has invalid backendAccess '${action.backendAccess}'. Must be one of: ${validBackendAccess.join(', ')}.`,
+            });
+        }
+        // idempotent must be boolean
+        if (typeof action.idempotent !== 'boolean') {
+            errors.push({
+                domainId, entryId, field: 'idempotent', code: 'ACTION_IDEMPOTENT_INVALID',
+                message: `Action '${entryId}' has invalid idempotent '${action.idempotent}'. Must be a boolean.`,
+            });
+        }
+        // exposure is required
+        if (!action.exposure || typeof action.exposure !== 'object') {
+            errors.push({
+                domainId, entryId, field: 'exposure', code: 'ACTION_EXPOSURE_MISSING',
+                message: `Action '${entryId}' is missing exposure. Every action must declare exposure explicitly.`,
+            });
+            continue;
+        }
+        const exposure = action.exposure;
+        // Must be 'api' or 'internal'
+        if (exposure.type !== 'api' && exposure.type !== 'internal') {
+            errors.push({
+                domainId, entryId, field: 'exposure.type', code: 'ACTION_EXPOSURE_TYPE_INVALID',
+                message: `Action '${entryId}' has exposure.type '${String(exposure.type)}'. Must be 'api' or 'internal'.`,
+            });
+            continue;
+        }
+        if (exposure.type === 'internal') {
+            // Internal must have no extra keys
+            const extraKeys = Object.keys(exposure).filter(k => k !== 'type');
+            if (extraKeys.length > 0) {
+                errors.push({
+                    domainId, entryId, field: 'exposure', code: 'INTERNAL_EXPOSURE_EXTRA_KEYS',
+                    message: `Action '${entryId}' has internal exposure with unexpected keys: ${extraKeys.join(', ')}. Internal exposure must be exactly { type: 'internal' }.`,
+                });
+            }
+        }
+        else if (exposure.type === 'api') {
+            // API requires path, method, auth, tenancy
+            // Path must be a non-empty string starting with '/'
+            if (typeof exposure.path !== 'string' || !exposure.path) {
+                errors.push({
+                    domainId, entryId, field: 'exposure.path', code: 'API_PATH_INVALID',
+                    message: `Action '${entryId}' has api exposure but path is missing or invalid.`,
+                });
+            }
+            else if (!exposure.path.startsWith('/')) {
+                errors.push({
+                    domainId, entryId, field: 'exposure.path', code: 'API_PATH_INVALID',
+                    message: `Action '${entryId}' has api exposure but path '${exposure.path}' does not start with '/'.`,
+                });
+            }
+            // Method must be a non-empty string and one of the allowed HTTP methods
+            if (typeof exposure.method !== 'string' || !exposure.method) {
+                errors.push({
+                    domainId, entryId, field: 'exposure.method', code: 'API_METHOD_INVALID',
+                    message: `Action '${entryId}' has api exposure but method is missing or invalid.`,
+                });
+            }
+            else if (!ALLOWED_HTTP_METHODS.includes(exposure.method)) {
+                errors.push({
+                    domainId, entryId, field: 'exposure.method', code: 'INVALID_HTTP_METHOD',
+                    message: `Action '${entryId}' has invalid HTTP method '${exposure.method}'. Must be one of: ${ALLOWED_HTTP_METHODS.join(', ')}.`,
+                });
+            }
+            // Auth must be valid
+            if (!['required', 'none', 'service'].includes(exposure.auth)) {
+                errors.push({
+                    domainId, entryId, field: 'exposure.auth', code: 'API_AUTH_INVALID',
+                    message: `Action '${entryId}' has api exposure but auth is missing or invalid. Must be 'required', 'none', or 'service'.`,
+                });
+            }
+            // Tenancy must be valid
+            if (!['required', 'none', 'system'].includes(exposure.tenancy)) {
+                errors.push({
+                    domainId, entryId, field: 'exposure.tenancy', code: 'API_TENANCY_INVALID',
+                    message: `Action '${entryId}' has api exposure but tenancy is missing or invalid. Must be 'required', 'none', or 'system'.`,
+                });
+            }
+            // API-exposed actions must have inputSchema
+            if (!action.inputSchema || typeof action.inputSchema !== 'object') {
+                errors.push({
+                    domainId, entryId, field: 'inputSchema', code: 'API_INPUT_SCHEMA_REQUIRED',
+                    message: `Action '${entryId}' is API-exposed but has no \`inputSchema\`. API-exposed actions must declare input/output Zod schemas.`,
+                });
+            }
+            // API-exposed actions must have outputSchema
+            if (!action.outputSchema || typeof action.outputSchema !== 'object') {
+                errors.push({
+                    domainId, entryId, field: 'outputSchema', code: 'API_OUTPUT_SCHEMA_REQUIRED',
+                    message: `Action '${entryId}' is API-exposed but has no \`outputSchema\`. API-exposed actions must declare input/output Zod schemas.`,
+                });
+            }
+            // AUTH_NONE_REQUIRES_EXCEPTION — auth: 'none' must carry a securityException with non-empty reason
+            if (exposure.auth === 'none') {
+                const apiExposure = exposure;
+                const reason = apiExposure.securityException?.reason;
+                if (!reason || reason.trim().length === 0) {
+                    errors.push({
+                        domainId, entryId, field: 'exposure.securityException', code: 'AUTH_NONE_REQUIRES_EXCEPTION',
+                        message: `Action '${entryId}' has \`exposure.auth: 'none'\` but no \`exposure.securityException.reason\`. Public/anonymous routes must document the security exception with a non-empty reason.`,
+                    });
+                }
+            }
+            // TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC — tenancy: 'none' must carry a securityException with non-empty reason
+            if (exposure.tenancy === 'none') {
+                const apiExposure = exposure;
+                const reason = apiExposure.securityException?.reason;
+                if (!reason || reason.trim().length === 0) {
+                    errors.push({
+                        domainId, entryId, field: 'exposure.securityException', code: 'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC',
+                        message: `Action '${entryId}' 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' + auth: 'required' requires non-empty roles
+            if (exposure.tenancy === 'system' && exposure.auth === 'required') {
+                const apiExposure = exposure;
+                if (!Array.isArray(apiExposure.roles) || apiExposure.roles.length === 0) {
+                    errors.push({
+                        domainId, entryId, field: 'exposure.roles', code: 'SYSTEM_API_REQUIRES_ROLE',
+                        message: `Action '${entryId}' 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-cdk-packer",
-  "version": "0.2.87",
+  "version": "0.2.88",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",