@empire-builder-kit/nx 1.0.0-rc.40 → 1.0.0-rc.42

package/src/generators/slice/built-in-plan-testing-persistence-event-files.js

@@ -0,0 +1,487 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTestingPersistenceEventFiles = renderTestingPersistenceEventFiles;
+/**
+ * Seeded behavioral integration specs that drive the seeded event consumer
+ * against the disposable worker stores. They never write DynamoDB outbox rows
+ * (integration/record.spec.ts owns the exactly-one-outbox assertion on the
+ * shared worker table), assert by seed-scoped key, and never wait in real time.
+ */
+function renderTestingPersistenceEventFiles(name, pascalName, sql) {
+    const inboxHelpers = `const inboxCount = async (source: string, eventId: string) => {
+  // Key-scoped: the inbox sort key is unique to this seed's event, while its
+  // partition carries the consumer identity. Never count the shared table.
+  const sk = lifecycleIdempotencyKey('event-consumer', [source, eventId]);
+  let count = 0;
+  let ExclusiveStartKey: Record<string, AttributeValue> | undefined;
+  do {
+    const page = await localKeyValueClient.send(new ScanCommand({ TableName: localKeyValueTable, ConsistentRead: true,
+      FilterExpression: '#sk = :sk AND #kind = :kind', ExpressionAttributeNames: { '#sk': 'sk', '#kind': 'kind' },
+      ExpressionAttributeValues: { ':sk': { S: sk }, ':kind': { S: 'inbox' } }, ExclusiveStartKey }));
+    count += page.Items?.length ?? 0;
+    ExclusiveStartKey = page.LastEvaluatedKey;
+  } while (ExclusiveStartKey);
+  return count;
+};`;
+    const seedHelpers = (spec) => `const seed = process.env.EBK_TEST_SEED;
+if (!seed) throw new Error('EBK_TEST_SEED is required for reproducible integration fixtures.');
+const stage = process.env.EBK_STAGE ?? '';
+const busName = process.env.EVENT_BUS_NAME ?? '';
+// The seeded consumer authorizes its own workload identity on every invocation.
+process.env.EBK_WORKLOAD_IDENTITY = '${name}:event-consumer';
+const scoped = (label: string) =>
+  'b4-' + createHash('sha256').update(seed + '/${spec}/' + label).digest('hex').slice(0, 32);`;
+    const files = {
+        'integration/event-consumer-duplicates.spec.ts': `import { createHash } from 'node:crypto';
+import { ScanCommand, type AttributeValue } from '@aws-sdk/client-dynamodb';
+import { createDataLifecycleChangeEvent, lifecycleIdempotencyKey } from '@empire-builder-kit/runtime/data-lifecycle';
+import { buildEventEntry } from '@empire-builder-kit/runtime/events';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { handler } from '../api/event-consumer.js';
+import { ${pascalName}Created, ${pascalName}DataLifecycleChanged } from '../contracts/events.js';
+import { localKeyValueClient, localKeyValueStore, localKeyValueTable } from '../testing/local-key-value.js';
+
+const observed = vi.hoisted(() => ({ consumed: [] as string[], refusals: [] as { code: string; eventId: string }[] }));
+vi.mock('../data/key-value.js', async () => {
+  const { localKeyValueStore } = await import('../testing/local-key-value.js');
+  const store = localKeyValueStore();
+  // Observe the inbox boundary without changing what the seeded consumer does.
+  const consume: typeof store.consume = async (input) => {
+    observed.consumed.push(input.eventId);
+    try {
+      return await store.consume(input);
+    } catch (error) {
+      observed.refusals.push({ code: String((error as { code?: unknown }).code), eventId: input.eventId });
+      throw error;
+    }
+  };
+  return { dataStore: () => ({ ...store, consume }) };
+});
+${seedHelpers('event-consumer-duplicates')}
+let sequence = 0;
+const messageId = (label: string) => scoped(label) + '-m' + String(++sequence);
+afterAll(() => localKeyValueClient.destroy());
+
+function created(eventId: string, occurredAt: string, options: { occurredBy?: string; stage?: string; tenantId?: string } = {}) {
+  const built = buildEventEntry(${pascalName}Created, { id: eventId, occurredBy: options.occurredBy ?? 'integration-owner' }, {
+    busName, stage: options.stage ?? stage, eventId, occurredAt,
+    context: { correlationId: eventId, tenantId: options.tenantId ?? 'application' },
+  });
+  return JSON.stringify({ source: built.entry.source, 'detail-type': built.entry.detailType, detail: JSON.parse(built.entry.detail) });
+}
+function lifecycle(eventId: string, pseudonymousKey: string, occurredAt: string) {
+  const data = createDataLifecycleChangeEvent({ action: 'correction', categoryId: 'product-record', occurredAt,
+    policyVersion: '1.0.0', pseudonymousKey, requestRef: lifecycleIdempotencyKey('request', [eventId]), sourceSlice: '${name}' });
+  const built = buildEventEntry(${pascalName}DataLifecycleChanged, data, {
+    busName, stage, eventId, occurredAt, context: { correlationId: eventId, tenantId: 'application' },
+  });
+  return JSON.stringify({ source: built.entry.source, 'detail-type': built.entry.detailType, detail: JSON.parse(built.entry.detail) });
+}
+${inboxHelpers}
+const inboxKey = (eventId: string) => lifecycleIdempotencyKey('event-consumer', ['${name}', eventId]);
+
+describe('${name} event consumer duplicate consumption', () => {
+  it('consumes a created event delivered repeatedly and twice in one batch exactly once', async () => {
+    const eventId = scoped('created');
+    const body = created(eventId, new Date().toISOString());
+    await expect(handler({ Records: [{ messageId: messageId('created'), body }] })).resolves.toEqual({ batchItemFailures: [] });
+    await expect(handler({ Records: [{ messageId: messageId('created'), body }] })).resolves.toEqual({ batchItemFailures: [] });
+    await expect(handler({ Records: [{ messageId: messageId('created'), body }, { messageId: messageId('created'), body }] }))
+      .resolves.toEqual({ batchItemFailures: [] });
+    expect(observed.consumed.filter((id) => id === inboxKey(eventId))).toHaveLength(4);
+    await expect(inboxCount('${name}', eventId)).resolves.toBe(1);
+  });
+
+  it('records one receipt and keeps the downstream copy unchanged when a lifecycle event is redelivered', async () => {
+    const eventId = scoped('lifecycle');
+    const pseudonymousKey = lifecycleIdempotencyKey('record', [scoped('lifecycle-record')]);
+    const body = lifecycle(eventId, pseudonymousKey, new Date().toISOString());
+    const store = localKeyValueStore();
+    const copyId = lifecycleIdempotencyKey('lifecycle-copy', ['${name}', pseudonymousKey, '${name}-lifecycle-consumer']);
+    await expect(handler({ Records: [{ messageId: messageId('lifecycle'), body }] })).resolves.toEqual({ batchItemFailures: [] });
+    const copy = await store.get('application', 'data-lifecycle-downstream-copies', copyId);
+    expect(copy).toMatchObject({ version: 1, value: { status: 'reconciled', action: 'correction' } });
+    await expect(handler({ Records: [{ messageId: messageId('lifecycle'), body }] })).resolves.toEqual({ batchItemFailures: [] });
+    await expect(store.get('application', 'data-lifecycle-receipts', inboxKey(eventId))).resolves.toMatchObject({ version: 1 });
+    await expect(store.get('application', 'data-lifecycle-downstream-copies', copyId)).resolves.toEqual(copy);
+    await expect(inboxCount('${name}', eventId)).resolves.toBe(1);
+  });
+
+  it('fails only the message that reuses an event id with changed data', async () => {
+    const eventId = scoped('conflict');
+    const independent = scoped('conflict-independent');
+    const occurredAt = new Date().toISOString();
+    await expect(handler({ Records: [{ messageId: messageId('conflict'), body: created(eventId, occurredAt) }] }))
+      .resolves.toEqual({ batchItemFailures: [] });
+    const changed = messageId('conflict-changed');
+    await expect(handler({ Records: [
+      { messageId: changed, body: created(eventId, occurredAt, { occurredBy: 'integration-other-owner' }) },
+      { messageId: messageId('conflict-independent'), body: created(independent, occurredAt) },
+    ] })).resolves.toEqual({ batchItemFailures: [{ itemIdentifier: changed }] });
+    expect(observed.refusals).toContainEqual({ code: 'idempotency-conflict', eventId: inboxKey(eventId) });
+    await expect(inboxCount('${name}', eventId)).resolves.toBe(1);
+    await expect(inboxCount('${name}', independent)).resolves.toBe(1);
+  });
+
+  it('refuses foreign tenant and foreign stage events before any inbox write', async () => {
+    const occurredAt = new Date().toISOString();
+    const tenant = scoped('foreign-tenant');
+    const foreignStage = scoped('foreign-stage');
+    const application = scoped('application-tenant');
+    const tenantMessage = messageId('foreign-tenant');
+    const stageMessage = messageId('foreign-stage');
+    await expect(handler({ Records: [
+      { messageId: tenantMessage, body: created(tenant, occurredAt, { tenantId: 'foreign-tenant' }) },
+      { messageId: stageMessage, body: created(foreignStage, occurredAt, { stage: stage === 'production' ? 'staging' : 'production' }) },
+      { messageId: messageId('application-tenant'), body: created(application, occurredAt) },
+    ] })).resolves.toEqual({ batchItemFailures: [{ itemIdentifier: tenantMessage }, { itemIdentifier: stageMessage }] });
+    expect(observed.consumed).not.toContain(inboxKey(tenant));
+    expect(observed.consumed).not.toContain(inboxKey(foreignStage));
+    await expect(inboxCount('${name}', tenant)).resolves.toBe(0);
+    await expect(inboxCount('${name}', foreignStage)).resolves.toBe(0);
+    await expect(inboxCount('${name}', application)).resolves.toBe(1);
+  });
+});
+`,
+        'integration/event-consumer-redrive.spec.ts': `import { createHash } from 'node:crypto';
+import { ScanCommand, type AttributeValue, type DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { createDataLifecycleChangeEvent, lifecycleIdempotencyKey } from '@empire-builder-kit/runtime/data-lifecycle';
+import { buildEventEntry } from '@empire-builder-kit/runtime/events';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { handler } from '../api/event-consumer.js';
+import workContract from '../async/work-contract.json' with { type: 'json' };
+import { ${pascalName}Created, ${pascalName}DataLifecycleChanged } from '../contracts/events.js';
+import { localKeyValueClient, localKeyValueStore, localKeyValueTable } from '../testing/local-key-value.js';
+
+const control = vi.hoisted(() => ({ outage: false }));
+vi.mock('../data/key-value.js', async () => {
+  const { createDynamoPersistence } = await import('@empire-builder-kit/runtime/key-value');
+  const { localKeyValueClient, localKeyValueTable } = await import('../testing/local-key-value.js');
+  const passthrough = localKeyValueClient.send.bind(localKeyValueClient) as (command: unknown) => Promise<unknown>;
+  // A transient dependency outage: every store call fails while it lasts.
+  const client = { send: (command: unknown) =>
+    control.outage ? Promise.reject(new Error('Integration DynamoDB outage.')) : passthrough(command) };
+  const store = createDynamoPersistence({ client: client as unknown as DynamoDBClient, tableName: localKeyValueTable,
+    stage: process.env.EBK_STAGE ?? '', slice: '${name}', eventBusName: 'local-integration-events' });
+  return { dataStore: () => store };
+});
+${seedHelpers('event-consumer-redrive')}
+afterAll(() => localKeyValueClient.destroy());
+const maxReceiveCount = workContract.queue.maxReceiveCount;
+if (!Number.isSafeInteger(maxReceiveCount) || maxReceiveCount < 1)
+  throw new Error('The async work contract must declare a positive maxReceiveCount.');
+
+interface QueuedMessage { body: string; messageId: string; receiveCount: number }
+/**
+ * In-test SQS source queue and DLQ with the declared redrive policy. Visibility
+ * timeouts elapse instantly; real SQS movement is not proven locally.
+ */
+function createQueue(label: string) {
+  const source: QueuedMessage[] = [];
+  const deadLetter: QueuedMessage[] = [];
+  const reported: string[] = [];
+  let sequence = 0;
+  const send = (body: string) => {
+    const messageId = scoped(label) + '-m' + String(++sequence);
+    source.push({ body, messageId, receiveCount: 0 });
+    return messageId;
+  };
+  async function drain() {
+    while (source.length > 0) {
+      const batch = source.splice(0, 10);
+      for (const message of batch) message.receiveCount += 1;
+      const { batchItemFailures } = await handler({ Records: batch.map(({ body, messageId }) => ({ body, messageId })) });
+      const failed = new Set(batchItemFailures.map(({ itemIdentifier }) => itemIdentifier));
+      reported.push(...failed);
+      for (const message of batch) {
+        if (!failed.has(message.messageId)) continue;
+        (message.receiveCount >= maxReceiveCount ? deadLetter : source).push(message);
+      }
+    }
+  }
+  // An operator redrive returns dead letters as new source messages.
+  const redrive = () => { for (const message of deadLetter.splice(0)) send(message.body); };
+  return { deadLetter, drain, redrive, reported, send };
+}
+function body(detailType: string, built: { entry: { source: string; detail: string } }) {
+  return JSON.stringify({ source: built.entry.source, 'detail-type': detailType, detail: JSON.parse(built.entry.detail) });
+}
+${inboxHelpers}
+
+describe('${name} event consumer poison redrive', () => {
+  it('dead-letters a transiently failing event at the declared receive limit and redrives it exactly once', async () => {
+    const queue = createQueue('transient');
+    const eventId = scoped('transient');
+    const occurredAt = new Date().toISOString();
+    const pseudonymousKey = lifecycleIdempotencyKey('record', [scoped('transient-record')]);
+    const message = body(${pascalName}DataLifecycleChanged.detailType, buildEventEntry(${pascalName}DataLifecycleChanged,
+      createDataLifecycleChangeEvent({ action: 'correction', categoryId: 'product-record', occurredAt, policyVersion: '1.0.0',
+        pseudonymousKey, requestRef: lifecycleIdempotencyKey('request', [eventId]), sourceSlice: '${name}' }),
+      { busName, stage, eventId, occurredAt, context: { correlationId: eventId, tenantId: 'application' } }));
+    const store = localKeyValueStore();
+    const receiptId = lifecycleIdempotencyKey('event-consumer', ['${name}', eventId]);
+    const copyId = lifecycleIdempotencyKey('lifecycle-copy', ['${name}', pseudonymousKey, '${name}-lifecycle-consumer']);
+    control.outage = true;
+    try {
+      queue.send(message);
+      await queue.drain();
+    } finally {
+      control.outage = false;
+    }
+    expect(queue.deadLetter.map(({ receiveCount }) => receiveCount)).toEqual([maxReceiveCount]);
+    await expect(store.get('application', 'data-lifecycle-receipts', receiptId)).resolves.toBeNull();
+    await expect(store.get('application', 'data-lifecycle-downstream-copies', copyId)).resolves.toBeNull();
+    await expect(inboxCount('${name}', eventId)).resolves.toBe(0);
+    queue.redrive();
+    await queue.drain();
+    expect(queue.deadLetter).toEqual([]);
+    await expect(store.get('application', 'data-lifecycle-receipts', receiptId)).resolves.toMatchObject({ version: 1 });
+    const copy = await store.get('application', 'data-lifecycle-downstream-copies', copyId);
+    expect(copy).toMatchObject({ version: 1, value: { status: 'reconciled' } });
+    // A repeated operator redrive or archive replay is a duplicate, not a second effect.
+    queue.send(message);
+    await queue.drain();
+    expect(queue.deadLetter).toEqual([]);
+    await expect(store.get('application', 'data-lifecycle-receipts', receiptId)).resolves.toMatchObject({ version: 1 });
+    await expect(store.get('application', 'data-lifecycle-downstream-copies', copyId)).resolves.toEqual(copy);
+    await expect(inboxCount('${name}', eventId)).resolves.toBe(1);
+  });
+
+  it('keeps a conflicting event poisoned across redrive while independent messages proceed', async () => {
+    const queue = createQueue('permanent');
+    const eventId = scoped('permanent');
+    const independent = scoped('permanent-independent');
+    const occurredAt = new Date().toISOString();
+    const created = (id: string, occurredBy: string) => body(${pascalName}Created.detailType, buildEventEntry(${pascalName}Created,
+      { id, occurredBy }, { busName, stage, eventId: id, occurredAt, context: { correlationId: id, tenantId: 'application' } }));
+    queue.send(created(eventId, 'integration-owner'));
+    await queue.drain();
+    expect(queue.reported).toEqual([]);
+    const poison = queue.send(created(eventId, 'integration-other-owner'));
+    queue.send(created(independent, 'integration-owner'));
+    await queue.drain();
+    expect(queue.reported).toEqual(Array.from({ length: maxReceiveCount }, () => poison));
+    expect(queue.deadLetter).toHaveLength(1);
+    await expect(inboxCount('${name}', independent)).resolves.toBe(1);
+    queue.redrive();
+    await queue.drain();
+    expect(queue.deadLetter.map(({ receiveCount }) => receiveCount)).toEqual([maxReceiveCount]);
+    expect(queue.reported).toHaveLength(2 * maxReceiveCount);
+    await expect(inboxCount('${name}', eventId)).resolves.toBe(1);
+  });
+});
+`,
+    };
+    if (!sql)
+        return files;
+    const sqlHelpers = `vi.mock('../data/key-value.js', async () => {
+  const { localKeyValueStore } = await import('../testing/local-key-value.js');
+  const store = localKeyValueStore();
+  // Observe the inbox boundary without changing what the seeded consumer does.
+  const consume: typeof store.consume = async (input) => {
+    observed.consumed.push(input.eventId);
+    return store.consume(input);
+  };
+  return { dataStore: () => ({ ...store, consume }) };
+});
+// The deployed credential adapter and EventBridge transport never run locally.
+vi.mock('../database/runtime-client', () => ({
+  withPrimaryDatabase: () => { throw new Error('Integration must not resolve deployed database credentials.'); },
+}));
+vi.mock('@aws-sdk/client-eventbridge', () => ({
+  EventBridgeClient: class { send() { throw new Error('Integration must not publish to a real event bus.'); } },
+  PutEventsCommand: class {},
+}));
+`;
+    const sqlOutbox = `const published: PutEventsRequestEntry[] = [];
+const outbox = createSqlEventOutbox({ scope: () => ({ stage, busName, enabled: true }), withDatabase: withLocalDatabase,
+  publish: async (entry) => { published.push(entry); } });
+const eventIdOf = (entry: PutEventsRequestEntry) =>
+  (JSON.parse(entry.Detail ?? '{}') as { meta?: { eventId?: string } }).meta?.eventId;
+const publishedFor = (eventId: string) =>
+  published.filter((entry) => entry.DetailType === ${pascalName}Created.detailType && eventIdOf(entry) === eventId);
+const record = (entry: PutEventsRequestEntry, messageId: string) => ({ messageId,
+  body: JSON.stringify({ source: entry.Source, 'detail-type': entry.DetailType, detail: JSON.parse(entry.Detail ?? 'null') }) });
+const intents = (eventId: string) => withLocalDatabase({ correlationId: eventId }, 'api-database-records', async (client) =>
+  (await client.query<{ attempts: number; last_error_code: string | null; published: boolean }>(
+    "SELECT attempts, last_error_code, published_at IS NOT NULL AS published FROM data_lifecycle_outbox WHERE (event_json->>'Detail')::jsonb->'meta'->>'eventId' = $1",
+    [eventId])).rows);
+const owned = new Set<string>();
+afterAll(async () => {
+  // Test-owned intents leave the shared worker database so later relays see none of them.
+  await withLocalDatabase({ correlationId: 'integration-cleanup' }, 'api-database-records', async (client) => {
+    await client.query("DELETE FROM data_lifecycle_outbox WHERE (event_json->>'Detail')::jsonb->'meta'->>'eventId' = ANY($1)", [[...owned]]);
+  });
+  localKeyValueClient.destroy();
+});`;
+    const sqlImports = `import { createHash } from 'node:crypto';
+import type { PutEventsRequestEntry } from '@aws-sdk/client-eventbridge';
+import { ScanCommand, type AttributeValue } from '@aws-sdk/client-dynamodb';
+import { lifecycleIdempotencyKey } from '@empire-builder-kit/runtime/data-lifecycle';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { handler } from '../api/event-consumer.js';
+import { ${pascalName}Created } from '../contracts/events.js';
+import { createSqlEventOutbox } from '../database/sql-events';`;
+    return {
+        ...files,
+        'testing/local-sql.ts': `import pg, { type Client as PgClient } from 'pg';
+
+const databaseUrl = new URL(process.env.DATABASE_URL ?? 'postgresql://invalid');
+if (!['postgres:', 'postgresql:'].includes(databaseUrl.protocol) || databaseUrl.hostname !== '127.0.0.1' ||
+    !databaseUrl.port || databaseUrl.search || databaseUrl.hash ||
+    !/^\\/ebk_test_[0-9a-f]{24}$/.test(databaseUrl.pathname)) {
+  throw new Error('Integration requires the runner-owned loopback PostgreSQL worker database.');
+}
+const connectionString = databaseUrl.href;
+
+/** Same call shape as withPrimaryDatabase, bound to the disposable worker database. */
+export async function withLocalDatabase<Result>(
+  _context: { correlationId: string },
+  _workload: string,
+  operation: (client: PgClient) => Promise<Result>,
+): Promise<Result> {
+  const client = new pg.Client({ connectionString });
+  await client.connect();
+  try {
+    return await operation(client);
+  } finally {
+    await client.end();
+  }
+}
+`,
+        'integration/dual-store.spec.ts': `${sqlImports}
+import { localKeyValueClient, localKeyValueStore, localKeyValueTable } from '../testing/local-key-value.js';
+import { withLocalDatabase } from '../testing/local-sql.js';
+
+const observed = vi.hoisted(() => ({ consumed: [] as string[] }));
+${sqlHelpers}${seedHelpers('dual-store')}
+${sqlOutbox}
+${inboxHelpers}
+const ledger = (id: string) => withLocalDatabase({ correlationId: id }, 'api-database-records', async (client) => {
+  await client.query('CREATE TABLE IF NOT EXISTS integration_dual_store_ledger (id text PRIMARY KEY, amount integer NOT NULL)');
+  return (await client.query<{ amount: number }>('SELECT amount FROM integration_dual_store_ledger WHERE id = $1', [id])).rows;
+});
+const recordCreated = (eventId: string, fail = false) =>
+  outbox.transaction({ correlationId: eventId }, 'api-database-records', async (client, emit) => {
+    owned.add(eventId);
+    await client.query('CREATE TABLE IF NOT EXISTS integration_dual_store_ledger (id text PRIMARY KEY, amount integer NOT NULL)');
+    await client.query('INSERT INTO integration_dual_store_ledger (id, amount) VALUES ($1, $2)', [eventId, 100]);
+    await emit(${pascalName}Created, { id: eventId, occurredBy: 'integration-owner' }, { eventId, occurredAt: new Date().toISOString() });
+    if (fail) throw new Error('Integration domain refusal.');
+    return eventId;
+  });
+
+describe('${name} dual-store DynamoDB and SQL event delivery', () => {
+  it('commits a relational row with its intent, relays it and consumes it once into the DynamoDB inbox', async () => {
+    const eventId = scoped('committed');
+    await expect(recordCreated(eventId)).resolves.toEqual({ value: eventId, queued: 1, notification: 'notified' });
+    expect(publishedFor(eventId)).toEqual([]);
+    await expect(ledger(eventId)).resolves.toEqual([{ amount: 100 }]);
+    await expect(intents(eventId)).resolves.toEqual([{ attempts: 0, last_error_code: null, published: false }]);
+    await outbox.reconcile({ correlationId: eventId });
+    const [entry] = publishedFor(eventId);
+    expect(publishedFor(eventId)).toHaveLength(1);
+    await expect(intents(eventId)).resolves.toEqual([{ attempts: 1, last_error_code: null, published: true }]);
+    await expect(handler({ Records: [record(entry, scoped('delivery'))] })).resolves.toEqual({ batchItemFailures: [] });
+    // A publish/acknowledgement interruption redelivers the same event: a duplicate.
+    await expect(handler({ Records: [record(entry, scoped('redelivery'))] })).resolves.toEqual({ batchItemFailures: [] });
+    await outbox.reconcile({ correlationId: eventId });
+    expect(publishedFor(eventId)).toHaveLength(1);
+    expect(observed.consumed).toContain(lifecycleIdempotencyKey('event-consumer', ['${name}', eventId]));
+    await expect(inboxCount('${name}', eventId)).resolves.toBe(1);
+  });
+
+  it('rolls back the relational row and its intent together without reaching DynamoDB', async () => {
+    const eventId = scoped('rolled-back');
+    await expect(recordCreated(eventId, true)).rejects.toThrow('Integration domain refusal.');
+    await expect(ledger(eventId)).resolves.toEqual([]);
+    await expect(intents(eventId)).resolves.toEqual([]);
+    await outbox.reconcile({ correlationId: eventId });
+    expect(publishedFor(eventId)).toEqual([]);
+    await expect(inboxCount('${name}', eventId)).resolves.toBe(0);
+  });
+
+  it('commits each store in its own transaction without a cross-store guarantee', async () => {
+    const id = scoped('independent');
+    const store = localKeyValueStore();
+    await store.commit({ tenantId: 'application', changes: [{ action: 'put', collection: 'integration-dual-store', id,
+      expectedVersion: 0, value: { amount: 100 } }] });
+    await expect(recordCreated(id, true)).rejects.toThrow('Integration domain refusal.');
+    // The SQL rollback cannot undo the committed DynamoDB write, and vice versa.
+    await expect(store.get('application', 'integration-dual-store', id)).resolves.toEqual({ value: { amount: 100 }, version: 1 });
+    await expect(ledger(id)).resolves.toEqual([]);
+    await expect(intents(id)).resolves.toEqual([]);
+  });
+});
+`,
+        'integration/sql-tenant-denial.spec.ts': `${sqlImports}
+import { localKeyValueClient, localKeyValueTable } from '../testing/local-key-value.js';
+import { withLocalDatabase } from '../testing/local-sql.js';
+
+const observed = vi.hoisted(() => ({ consumed: [] as string[] }));
+${sqlHelpers}${seedHelpers('sql-tenant-denial')}
+${sqlOutbox}
+${inboxHelpers}
+const emitCreated = (eventId: string, context: { correlationId: string }) =>
+  outbox.transaction(context, 'api-database-records', async (_client, emit) => {
+    owned.add(eventId);
+    await emit(${pascalName}Created, { id: eventId, occurredBy: 'integration-owner' }, { eventId, occurredAt: new Date().toISOString() });
+  });
+const rewrite = (eventId: string, sql: string, values: unknown[]) =>
+  withLocalDatabase({ correlationId: eventId }, 'api-database-records', async (client) => {
+    const result = await client.query(sql + " WHERE (event_json->>'Detail')::jsonb->'meta'->>'eventId' = $1", [eventId, ...values]);
+    if (result.rowCount !== 1) throw new Error('Expected exactly one stored intent to rewrite.');
+  });
+
+describe('${name} SQL-originated tenant and scope denial', () => {
+  it('refuses stored intents rewritten to a foreign stage, bus or Slice at the relay', async () => {
+    const ids = { bus: scoped('foreign-bus'), slice: scoped('foreign-slice'), stage: scoped('foreign-stage') };
+    for (const eventId of Object.values(ids)) await emitCreated(eventId, { correlationId: eventId });
+    // Simulate stored intents that no longer match this relay's exact scope.
+    await rewrite(ids.stage, "UPDATE data_lifecycle_outbox SET event_json = jsonb_set(event_json, '{Detail}', to_jsonb(replace(event_json->>'Detail', $2, $3)))",
+      ['"stage":"' + stage + '"', '"stage":"' + (stage === 'production' ? 'staging' : 'production') + '"']);
+    await rewrite(ids.bus, "UPDATE data_lifecycle_outbox SET event_json = jsonb_set(event_json, '{EventBusName}', to_jsonb($2::text))", ['foreign-bus']);
+    await rewrite(ids.slice, "UPDATE data_lifecycle_outbox SET event_json = jsonb_set(jsonb_set(event_json, '{Source}', to_jsonb($2::text)), '{Detail}', to_jsonb(replace(event_json->>'Detail', $3, $4)))",
+      ['foreign-slice', '"slice":"${name}"', '"slice":"foreign-slice"']);
+    const result = await outbox.reconcile({ correlationId: ids.stage });
+    expect(result.failed).toBeGreaterThanOrEqual(3);
+    for (const eventId of Object.values(ids)) {
+      expect(publishedFor(eventId)).toEqual([]);
+      await expect(intents(eventId)).resolves.toEqual([{ attempts: 1, last_error_code: 'event-publication-failed', published: false }]);
+      await expect(inboxCount('${name}', eventId)).resolves.toBe(0);
+    }
+  });
+
+  it('refuses a foreign-Slice event at emission and rolls back its transaction', async () => {
+    const eventId = scoped('foreign-emission');
+    await expect(outbox.transaction({ correlationId: eventId }, 'api-database-records', async (_client, emit) => {
+      owned.add(eventId);
+      await emit({ ...${pascalName}Created, source: 'foreign-slice' }, { id: eventId, occurredBy: 'integration-owner' },
+        { eventId, occurredAt: new Date().toISOString() });
+    })).rejects.toThrow('SQL event differs from its Slice/bus scope.');
+    await expect(intents(eventId)).resolves.toEqual([]);
+  });
+
+  it('refuses a foreign-tenant SQL event at the seeded consumer before any inbox write', async () => {
+    const foreign = scoped('foreign-tenant');
+    const application = scoped('application-tenant');
+    // The outbox context is typed { correlationId }; a widened runtime context can still carry tenant metadata.
+    const foreignContext = { correlationId: foreign, tenantId: 'foreign-tenant' };
+    await emitCreated(foreign, foreignContext);
+    await emitCreated(application, { correlationId: application });
+    await outbox.reconcile({ correlationId: foreign });
+    const [foreignEntry] = publishedFor(foreign);
+    const [applicationEntry] = publishedFor(application);
+    expect(JSON.parse(foreignEntry.Detail ?? '{}').meta.tenantId).toBe('foreign-tenant');
+    const refused = scoped('foreign-tenant-delivery');
+    await expect(handler({ Records: [record(foreignEntry, refused), record(applicationEntry, scoped('application-delivery'))] }))
+      .resolves.toEqual({ batchItemFailures: [{ itemIdentifier: refused }] });
+    expect(observed.consumed).not.toContain(lifecycleIdempotencyKey('event-consumer', ['${name}', foreign]));
+    await expect(inboxCount('${name}', foreign)).resolves.toBe(0);
+    await expect(inboxCount('${name}', application)).resolves.toBe(1);
+  });
+});
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-testing-persistence-event-files.js.map

package/src/generators/slice/built-in-plan-testing-persistence-files.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderTestingPersistenceFiles = renderTestingPersistenceFiles;
+const built_in_plan_testing_persistence_event_files_js_1 = require("./built-in-plan-testing-persistence-event-files.js");
 /** Disposable integration resources are independent of fleet or deployed data. */
 function renderTestingPersistenceFiles(name, pascalName, sql) {
     const labels = `    labels:
@@ -173,6 +174,7 @@ describe('${name} optional SQL migrations', () => {
 `,
             }
             : {}),
+        ...(0, built_in_plan_testing_persistence_event_files_js_1.renderTestingPersistenceEventFiles)(name, pascalName, sql),
     };
 }
 //# sourceMappingURL=built-in-plan-testing-persistence-files.js.map

package/src/generators/slice/built-in-plan.js

@@ -239,7 +239,8 @@ function classifyPaths(files, sql) {
         'api/generated/contract.json',
         'api/generated/openapi.json',
         'authorization/machine-authorization-proof.ts',
-        'authorization/machine-client-provisioner.py',
+        'authorization/machine-client-provisioner.spec.ts',
+        'authorization/machine-client-provisioner.ts',
         'authorization/runtime.ts',
         'authorization/record-store.ts',
         'authorization/groups.mjs',
@@ -250,6 +251,7 @@ function classifyPaths(files, sql) {
         'testing/quarantine-runtime.mjs',
         'testing/strict-json-reporter.mjs',
         'testing/local-key-value.ts',
+        'testing/local-sql.ts',
         'e2e/frontend-accessibility.spec.ts',
     ]);
     for (const path of built_in_plan_performance_files_js_1.PRODUCT_PERFORMANCE_SEEDED_PATHS)

package/src/generators/workload/frozen-container.d.ts

@@ -1,4 +1,4 @@
-export declare const WORKLOAD_CONTAINER_NODE_IMAGE: "node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2";
+export declare const WORKLOAD_CONTAINER_NODE_IMAGE: "node:22-alpine@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402";
 export declare const WORKLOAD_CONTAINER_PNPM_VERSION: "11.20.0";
 export declare const WORKLOAD_CONTAINER_PNPM_DESCRIPTOR: "pnpm@11.20.0+sha512.9a6f330a95b66446ea088faf1521405a8a01f07fde7124cc9958dfed52d4bb436737e65b08f85f37b46fcba375092558ac51262b816844b22f63406ed166bfee";
 export declare const WORKLOAD_CONTAINER_PNPM_STORE = "/workspace/.ebk/cache/pnpm-store";

package/src/git-policy/github-bootstrap.d.ts

@@ -15,6 +15,13 @@ export declare const EBK_PROTECTED_MAIN_RULESET_NAME: "EBK protected main (trunk
 export declare const EBK_STAGING_PROMOTION_PULL_ROLE_SECRET = "AWS_STAGING_PROMOTION_PULL_ROLE_ARN";
 export declare const EBK_PROTECTED_ENVIRONMENT_SECRETS: readonly ["AWS_ASYNC_RECOVERY_ROLE_ARN", "AWS_ECR_INSPECTOR_EVIDENCE_ROLE_ARN", "AWS_DEPLOY_ROLE_ARN", "AWS_STAGING_PROMOTION_PULL_ROLE_ARN"];
 export declare const EBK_PROTECTED_ENVIRONMENT_VARIABLES: readonly ["AWS_EXPECTED_ACCOUNT_ID", "AWS_REGION", "AWS_STAGING_PROMOTION_EXPECTED_ACCOUNT_ID", "AWS_STAGING_PROMOTION_REGION", "EBK_ALLOW_PRODUCTION_REMOVE", "EBK_FLEET_ORIGIN"];
+/**
+ * Non-secret stage environment variables an operator may set to request a
+ * machine credential generation or its retirement on a workflow deploy. They
+ * are never required, and a repository- or organization-scoped copy would
+ * silently apply to every stage, so only the stage environment may hold them.
+ */
+export declare const EBK_OPTIONAL_STAGE_ENVIRONMENT_VARIABLES: readonly ["EBK_MACHINE_CREDENTIAL_GENERATION", "EBK_MACHINE_RETIRE_PREVIOUS_GENERATION"];
 export declare const EBK_CODE_OWNER_PLACEHOLDER: "@REPLACE_WITH_GITHUB_CODE_OWNER";
 type GitHubEnvironmentStage = 'development' | 'production' | 'staging';
 type GitHubAuxiliaryEnvironment = 'async-recovery' | 'ecr-inspector';
@@ -25,6 +32,8 @@ export interface GitHubEnvironmentTopologyEntry {
     additionalBranches?: readonly ('develop' | 'main')[];
     branch: 'develop' | 'main';
     name: GitHubEnvironmentName;
+    /** Variables the environment may hold but never requires. */
+    optionalVariables?: readonly string[];
     requiredSecrets: readonly string[];
     requiredVariables: readonly string[];
     stage: GitHubEnvironmentStage;

package/src/git-policy/github-bootstrap.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EBK_CODE_OWNER_PLACEHOLDER = exports.EBK_PROTECTED_ENVIRONMENT_VARIABLES = exports.EBK_PROTECTED_ENVIRONMENT_SECRETS = exports.EBK_STAGING_PROMOTION_PULL_ROLE_SECRET = exports.EBK_PROTECTED_MAIN_RULESET_NAME = exports.EBK_RECORD_MAIN_TOKEN_SECRET = exports.EBK_PERFORMANCE_ORIGINS_VARIABLE = exports.EBK_PERFORMANCE_LOAD_ROLE_SECRET = exports.EBK_PERFORMANCE_COST_ROLE_SECRET = exports.EBK_PERFORMANCE_AGGREGATE_ROLE_SECRET = exports.EBK_ASYNC_RECOVERY_ROLE_SECRET = exports.EBK_ECR_INSPECTOR_EVIDENCE_ROLE_SECRET = exports.EBK_RETIRED_DEPLOYMENT_ROLE_SECRET = exports.EBK_REQUIRED_CHECKS = exports.EBK_PROTECTED_BRANCH_RULESET_NAME = void 0;
+exports.EBK_CODE_OWNER_PLACEHOLDER = exports.EBK_OPTIONAL_STAGE_ENVIRONMENT_VARIABLES = exports.EBK_PROTECTED_ENVIRONMENT_VARIABLES = exports.EBK_PROTECTED_ENVIRONMENT_SECRETS = exports.EBK_STAGING_PROMOTION_PULL_ROLE_SECRET = exports.EBK_PROTECTED_MAIN_RULESET_NAME = exports.EBK_RECORD_MAIN_TOKEN_SECRET = exports.EBK_PERFORMANCE_ORIGINS_VARIABLE = exports.EBK_PERFORMANCE_LOAD_ROLE_SECRET = exports.EBK_PERFORMANCE_COST_ROLE_SECRET = exports.EBK_PERFORMANCE_AGGREGATE_ROLE_SECRET = exports.EBK_ASYNC_RECOVERY_ROLE_SECRET = exports.EBK_ECR_INSPECTOR_EVIDENCE_ROLE_SECRET = exports.EBK_RETIRED_DEPLOYMENT_ROLE_SECRET = exports.EBK_REQUIRED_CHECKS = exports.EBK_PROTECTED_BRANCH_RULESET_NAME = void 0;
 exports.githubEnvironmentTopology = githubEnvironmentTopology;
 exports.runGitHubBootstrap = runGitHubBootstrap;
 const index_js_1 = require("../repository-policy/index.js");
@@ -33,6 +33,16 @@ exports.EBK_PROTECTED_ENVIRONMENT_VARIABLES = [
     'EBK_ALLOW_PRODUCTION_REMOVE',
     'EBK_FLEET_ORIGIN',
 ];
+/**
+ * Non-secret stage environment variables an operator may set to request a
+ * machine credential generation or its retirement on a workflow deploy. They
+ * are never required, and a repository- or organization-scoped copy would
+ * silently apply to every stage, so only the stage environment may hold them.
+ */
+exports.EBK_OPTIONAL_STAGE_ENVIRONMENT_VARIABLES = [
+    'EBK_MACHINE_CREDENTIAL_GENERATION',
+    'EBK_MACHINE_RETIRE_PREVIOUS_GENERATION',
+];
 const FORBIDDEN_NPM_TOKEN_NAMES = [
     'NODE_AUTH_TOKEN',
     'NPM_CONFIG_TOKEN',
@@ -62,6 +72,7 @@ function stageEnvironmentTopology(stage, deploymentProfile) {
     return Object.freeze({
         branch: production ? 'main' : 'develop',
         name: stage,
+        optionalVariables: exports.EBK_OPTIONAL_STAGE_ENVIRONMENT_VARIABLES,
         requiredSecrets: Object.freeze(production
             ? deploymentProfile === 'starter'
                 ? []
@@ -808,6 +819,7 @@ function evaluate(repository, state, inspectionBlockers, productionApprovalMode,
     }
     for (const variable of [
         ...exports.EBK_PROTECTED_ENVIRONMENT_VARIABLES,
+        ...exports.EBK_OPTIONAL_STAGE_ENVIRONMENT_VARIABLES,
         ...FORBIDDEN_NPM_TOKEN_NAMES,
     ]) {
         if (state.repositoryVariableNames.includes(variable)) {
@@ -880,8 +892,10 @@ function evaluate(repository, state, inspectionBlockers, productionApprovalMode,
                 blockers.push(`${environment} environment is missing required variable ${variable}; bootstrap never creates variable values.`);
             }
         }
+        const optionalVariables = topology.optionalVariables ?? [];
         for (const variable of current.variableNames) {
-            if (!requiredVariables.includes(variable)) {
+            if (!requiredVariables.includes(variable) &&
+                !optionalVariables.includes(variable)) {
                 blockers.push(`${environment} environment exposes ${variable} outside its exact capability boundary.`);
             }
         }