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

package/src/generators/slice/built-in-plan-key-value-provider.js

@@ -0,0 +1,366 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueProviderFiles = renderKeyValueProviderFiles;
+exports.renderKeyValueProviderTestCases = renderKeyValueProviderTestCases;
+/** Native provider inbox. External effects remain at-least-once or require reconciliation. */
+function renderKeyValueProviderFiles(name) {
+    return {
+        'async/provider-inbox.ts': `import { randomUUID } from 'node:crypto';
+import { asyncWorkDigest, createProviderDelivery, type ProviderDeliveryV1 } from '@empire-builder-kit/runtime/async-work';
+import type { KeyValueChange } from '@empire-builder-kit/runtime/key-value';
+import { dataStore } from '../data/key-value.js';
+
+type Store = ReturnType<typeof dataStore>;
+const COLLECTION = 'provider-inbox';
+const LEASE_MS = 120_000;
+const RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
+interface Claim {
+  schemaVersion: 1; deliveryId: string; operationDigest: string;
+  createdAt: string; expiresAt: string; lastAttemptAt: string;
+  attemptToken: string; attempts: number;
+  state: 'prepared' | 'effect-started' | 'failed' | 'succeeded';
+  resultReference: string | null;
+}
+export type ProviderClaimResult =
+  | { outcome: 'claimed'; attemptToken: string }
+  | { outcome: 'conflict' | 'duplicate' | 'retry' | 'expired' | 'terminal-permanent' | 'terminal-reconciliation' };
+
+function timestamp(value: string): number {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value)
+    throw new Error('provider-timestamp-invalid');
+  return time;
+}
+export function parseProviderDelivery(body: string): ProviderDeliveryV1<unknown> {
+  if (typeof body !== 'string' || Buffer.byteLength(body) > 128 * 1024)
+    throw new Error('provider-delivery-invalid');
+  const delivery = JSON.parse(body) as ProviderDeliveryV1<unknown>;
+  const expected = createProviderDelivery({ contract: delivery.contract,
+    createdAt: delivery.createdAt, operationId: delivery.idempotencyKey, request: delivery.request });
+  if (asyncWorkDigest(delivery) !== asyncWorkDigest(expected))
+    throw new Error('provider-delivery-invalid');
+  const retry = expected.contract.retry;
+  // The generated provider Lambda has a one-minute execution budget. Leave
+  // room to persist the outcome, and never start an unbounded provider call.
+  if (!retry || ![retry.maximumAttempts, retry.attemptTimeoutMs, retry.baseDelayMs,
+      retry.maximumDelayMs, retry.totalTimeoutMs].every((value) => Number.isSafeInteger(value) && value > 0) ||
+      retry.maximumAttempts > 100 || retry.baseDelayMs > retry.maximumDelayMs ||
+      retry.attemptTimeoutMs >= retry.totalTimeoutMs || retry.totalTimeoutMs > 50_000)
+    throw new Error('provider-retry-budget-invalid');
+  return expected;
+}
+function operationDigest(delivery: ProviderDeliveryV1<unknown>) {
+  return asyncWorkDigest({ contract: delivery.contract, createdAt: delivery.createdAt,
+    deliveryId: delivery.deliveryId, idempotencyKey: delivery.idempotencyKey, requestDigest: delivery.requestDigest });
+}
+function readClaim(value: unknown, id: string): Claim {
+  const claim = value as Claim;
+  if (!claim || claim.schemaVersion !== 1 || claim.deliveryId !== id ||
+      !/^sha256:[a-f0-9]{64}$/.test(claim.operationDigest) ||
+      !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(claim.attemptToken) ||
+      !Number.isSafeInteger(claim.attempts) || claim.attempts < 1 ||
+      !['prepared', 'effect-started', 'failed', 'succeeded'].includes(claim.state) ||
+      (claim.resultReference !== null && (typeof claim.resultReference !== 'string' || claim.resultReference.length > 256)))
+    throw new Error('provider-inbox-invalid');
+  if (timestamp(claim.expiresAt) !== timestamp(claim.createdAt) + RETENTION_MS ||
+      timestamp(claim.lastAttemptAt) < timestamp(claim.createdAt))
+    throw new Error('provider-inbox-invalid');
+  if (claim.state === 'succeeded' && !claim.resultReference)
+    throw new Error('provider-inbox-confirmation-missing');
+  return claim;
+}
+function conditionalConflict(error: unknown): boolean {
+  return error instanceof Error && error.name === 'TransactionCanceledException' &&
+    (error as Error & { CancellationReasons?: { Code?: string }[] }).CancellationReasons?.some(
+      ({ Code }) => Code === 'ConditionalCheckFailed') === true;
+}
+async function put(store: Store, value: Claim, version: number): Promise<boolean> {
+  try {
+    await store.commit({ tenantId: 'system', changes: [{ action: 'put', collection: COLLECTION,
+      id: value.deliveryId, expectedVersion: version, value }] });
+    return true;
+  } catch (error) {
+    if (conditionalConflict(error)) return false;
+    throw error;
+  }
+}
+export async function claimProviderDelivery(store: Store, raw: ProviderDeliveryV1<unknown>,
+  now: string, createAttemptToken: () => string = randomUUID): Promise<ProviderClaimResult> {
+  const delivery = parseProviderDelivery(JSON.stringify(raw));
+  const time = timestamp(now);
+  const created = timestamp(delivery.createdAt);
+  // This check works even after physical deletion; TTL timing is not replay authority.
+  if (created > time || time >= created + RETENTION_MS) return { outcome: 'expired' };
+  const row = await store.get('system', COLLECTION, delivery.deliveryId);
+  const previous = row ? readClaim(row.value, delivery.deliveryId) : null;
+  const digest = operationDigest(delivery);
+  if (previous) {
+    if (previous.operationDigest !== digest) return { outcome: 'conflict' };
+    if (previous.state === 'succeeded') return { outcome: 'duplicate' };
+    if (previous.state === 'failed' && previous.resultReference?.startsWith('terminal-permanent-'))
+      return { outcome: 'terminal-permanent' };
+    if (previous.state === 'failed' && previous.resultReference?.startsWith('terminal-reconciliation-'))
+      return { outcome: 'terminal-reconciliation' };
+    if (time < timestamp(previous.lastAttemptAt)) throw new Error('provider-clock-regressed');
+    if ((previous.state === 'prepared' || previous.state === 'effect-started') &&
+        time - timestamp(previous.lastAttemptAt) < LEASE_MS) return { outcome: 'retry' };
+    if (previous.state === 'effect-started' && delivery.contract.idempotencyRepeatSafety === 'unproven') {
+      const saved = await put(store, { ...previous, state: 'failed', lastAttemptAt: now,
+        resultReference: 'terminal-reconciliation-' + asyncWorkDigest({ deliveryId: delivery.deliveryId, result: 'provider-effect-outcome-unknown' }) }, row!.version);
+      return { outcome: saved ? 'terminal-reconciliation' : 'retry' };
+    }
+  }
+  const attemptToken = createAttemptToken();
+  const next: Claim = { schemaVersion: 1, deliveryId: delivery.deliveryId, operationDigest: digest,
+    createdAt: delivery.createdAt, expiresAt: new Date(created + RETENTION_MS).toISOString(),
+    lastAttemptAt: now, attemptToken, attempts: (previous?.attempts ?? 0) + 1, state: 'prepared', resultReference: null };
+  readClaim(next, delivery.deliveryId);
+  return await put(store, next, row?.version ?? 0) ? { outcome: 'claimed', attemptToken } : { outcome: 'retry' };
+}
+async function ownedClaim(store: Store, id: string, token: string, state: Claim['state'], now: string) {
+  const row = await store.get('system', COLLECTION, id);
+  if (!row) return null;
+  const value = readClaim(row.value, id);
+  const time = timestamp(now);
+  if (value.attemptToken !== token || value.state !== state || time >= timestamp(value.expiresAt) ||
+      time < timestamp(value.lastAttemptAt) || time - timestamp(value.lastAttemptAt) >= LEASE_MS) return null;
+  return { value, version: row.version };
+}
+export async function markProviderEffectStarted(store: Store, id: string, token: string, now: string): Promise<boolean> {
+  const row = await ownedClaim(store, id, token, 'prepared', now);
+  return row ? put(store, { ...row.value, state: 'effect-started', lastAttemptAt: now }, row.version) : false;
+}
+export async function finishProviderDelivery(store: Store, id: string, token: string, now: string,
+  input: { expectedState?: 'prepared' | 'effect-started'; resultReference: string; status: 'failed' | 'succeeded' }): Promise<boolean> {
+  if (!input.resultReference || input.resultReference.length > 256 ||
+      !['failed', 'succeeded'].includes(input.status) ||
+      (input.status === 'succeeded' && input.expectedState === 'prepared'))
+    throw new Error('provider-finish-invalid');
+  const row = await ownedClaim(store, id, token, input.expectedState ?? 'effect-started', now);
+  return row ? put(store, { ...row.value, state: input.status, resultReference: input.resultReference,
+    lastAttemptAt: now }, row.version) : false;
+}
+
+// Logical expiry above rejects replay even after a terminal row is physically
+// removed. Never erase an uncertain external effect merely because it is old.
+export async function cleanupProviderInbox(store: Store, now: string,
+  clock: () => number = Date.now, deadline?: number) {
+  const time = timestamp(now);
+  const started = clock(), end = Math.min(deadline ?? Infinity, started + 4 * 60_000);
+  if (!Number.isFinite(started) || !Number.isFinite(end)) throw new Error('provider-cleanup-clock-invalid');
+  const cursor = await store.get('system', 'provider-maintenance', 'cleanup');
+  const saved = cursor?.value as { afterId: string | null } | undefined;
+  if (cursor && (!saved || (saved.afterId !== null &&
+      !/^sha256:[a-f0-9]{64}$/.test(saved.afterId)))) throw new Error('provider-cleanup-cursor-invalid');
+  let afterId = saved?.afterId ?? undefined, sawBeginning = afterId === undefined;
+  let inspected = 0, removed = 0, version = cursor?.version ?? 0;
+  const uncertain = new Set<string>();
+  const result = (completeScan: boolean) => ({ removed, inspected, retainedUncertain: uncertain.size,
+    continuationRequired: !completeScan, completeScan });
+  while (inspected < 10_000) {
+  const current = clock();
+  if (!Number.isFinite(current) || current < started) throw new Error('provider-cleanup-clock-invalid');
+  if (current >= end) return result(false);
+  const page = await store.list('system', COLLECTION, { limit: Math.min(20, 10_000 - inspected), afterId });
+  inspected += page.records.length;
+  const changes: KeyValueChange[] = [];
+  for (const row of page.records) {
+    const claim = readClaim(row.value, row.id);
+    if (timestamp(claim.expiresAt) > time) continue;
+    const terminal = claim.state === 'succeeded' || (claim.state === 'failed' &&
+      (claim.resultReference?.startsWith('terminal-permanent-') ||
+       claim.resultReference?.startsWith('terminal-reconciliation-') ||
+       claim.resultReference === 'configuration-disabled' || claim.resultReference === 'configuration-invalid'));
+    if (!terminal) { uncertain.add(row.id); continue; }
+    changes.push({ action: 'delete', collection: COLLECTION, id: row.id, expectedVersion: row.version });
+  }
+  const count = changes.length;
+  changes.push({ action: 'put', collection: 'provider-maintenance', id: 'cleanup',
+    expectedVersion: version, value: { afterId: page.nextId ?? null } });
+  // The cursor advances in the exact deletion transaction, including empty pages.
+  await store.commit({ tenantId: 'system', changes });
+  removed += count; version++; afterId = page.nextId;
+  if (afterId === undefined) {
+    if (sawBeginning) return result(true);
+    sawBeginning = true;
+  }
+  }
+  return result(false);
+}
+`,
+        'async/provider-worker.ts': `import { randomUUID } from 'node:crypto';
+import { asyncWorkDigest, processSqsBatch, runProviderDelivery, type ProviderDeliveryAdapter } from '@empire-builder-kit/runtime/async-work';
+import { deriveOperationalRolloutStableKey } from '@empire-builder-kit/runtime/configuration';
+import { createLogger, type Logger } from '@empire-builder-kit/runtime/logging';
+import { createSliceAwsConfigurationProvider, createSliceLocalConfigurationProvider } from '../configuration/provider.js';
+import { evaluateLambdaProviderDelivery } from '../configuration/rollout.js';
+import { dataStore } from '../data/key-value.js';
+import { asyncAdapterDeclaration, createAsyncRecoveryAdapters } from './recovery-adapters.js';
+import { claimProviderDelivery, finishProviderDelivery, markProviderEffectStarted, parseProviderDelivery } from './provider-inbox.js';
+export { claimProviderDelivery, finishProviderDelivery, markProviderEffectStarted } from './provider-inbox.js';
+
+const protectedStage = process.env.EBK_STAGE === 'staging' || process.env.EBK_STAGE === 'production';
+function required(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(name + ' is required.');
+  return value;
+}
+const configurationProvider = protectedStage ? createSliceAwsConfigurationProvider({
+  applicationIdentifier: required('EBK_APPCONFIG_APPLICATION_ID'),
+  environmentIdentifier: required('EBK_APPCONFIG_ENVIRONMENT_ID'),
+  profileIdentifier: required('EBK_APPCONFIG_PROFILE_ID'),
+}) : createSliceLocalConfigurationProvider();
+const stableKey = deriveOperationalRolloutStableKey({ kind: 'lambda', slice: '${name}', workload: 'provider-worker' });
+interface QueueRecord { body: string; messageId: string }
+interface Dependencies {
+  store: typeof dataStore; now(): string; createAttemptToken(): string;
+  configured(): boolean; adapter(): ProviderDeliveryAdapter<unknown>;
+  evaluateRollout: typeof evaluateLambdaProviderDelivery;
+  logger: Logger;
+}
+export function createProviderWorkerHandler(dependencies: Dependencies) {
+  return async (event: { Records: QueueRecord[] }) => {
+    if (!dependencies.configured()) throw new Error('async-provider-adapter-disabled');
+    const result = await processSqsBatch({ records: event.Records, handler: async (record) => {
+      try {
+        const delivery = parseProviderDelivery(record.body);
+        const store = dependencies.store();
+        const claim = await claimProviderDelivery(store, delivery, dependencies.now(), dependencies.createAttemptToken);
+        if (claim.outcome === 'duplicate') return { outcome: 'succeeded' as const };
+        if (claim.outcome !== 'claimed') return {
+          outcome: claim.outcome === 'retry' ? 'retry' as const : 'terminal' as const,
+          errorCode: 'provider-' + claim.outcome,
+        };
+        const token = claim.attemptToken;
+        let assigned: boolean;
+        try {
+          assigned = (await dependencies.evaluateRollout(configurationProvider, stableKey)).assigned;
+        } catch {
+          const persisted = await finishProviderDelivery(store, delivery.deliveryId, token, dependencies.now(), {
+            expectedState: 'prepared', resultReference: 'configuration-invalid', status: 'failed' });
+          if (!persisted) throw new Error('provider-configuration-result-state-lost');
+          return { errorCode: 'provider-delivery-configuration-invalid', outcome: 'retry' as const };
+        }
+        if (!assigned) {
+          const persisted = await finishProviderDelivery(store, delivery.deliveryId, token, dependencies.now(), {
+            expectedState: 'prepared', resultReference: 'configuration-disabled', status: 'failed' });
+          if (!persisted) throw new Error('provider-configuration-result-state-lost');
+          return { errorCode: 'provider-delivery-disabled', outcome: 'retry' as const };
+        }
+        if (!await markProviderEffectStarted(store, delivery.deliveryId, token, dependencies.now()))
+          return { errorCode: 'idempotency-claim-lost', outcome: 'retry' as const };
+        const result = await runProviderDelivery({ adapter: dependencies.adapter(), delivery });
+        const confirmed = result.outcome === 'confirmed';
+        const reference = result.outcome === 'confirmed' ? result.providerReference :
+          (result.outcome === 'permanent-failure' ? 'terminal-permanent-' : 'terminal-reconciliation-') + result.reconciliationId;
+        if (!await finishProviderDelivery(store, delivery.deliveryId, token, dependencies.now(), {
+          status: confirmed ? 'succeeded' : 'failed', resultReference: reference }))
+          throw new Error('provider-delivery-result-state-lost');
+        dependencies.logger.info('Provider delivery outcome retained', {
+          attributes: { deliveryIdDigest: asyncWorkDigest(delivery.deliveryId), attempts: result.attempts },
+          outcome: confirmed ? 'success' : 'failure',
+        });
+        return result.outcome === 'confirmed' ? { outcome: 'succeeded' as const } :
+          { outcome: 'terminal' as const, errorCode: result.errorCode };
+      } catch {
+        // The queue retains failure; never log the provider request or accept
+        // an unpersisted effect. A stale uncertain claim needs reconciliation.
+        dependencies.logger.error('Provider delivery handler failed', {
+          attributes: { messageIdDigest: asyncWorkDigest(record.messageId) }, outcome: 'failure' });
+        return { errorCode: 'provider-delivery-failed', outcome: 'retry' as const };
+      }
+    } });
+    return result.response;
+  };
+}
+export const handler = createProviderWorkerHandler({
+  store: dataStore, now: () => new Date().toISOString(), createAttemptToken: randomUUID,
+  configured: () => asyncAdapterDeclaration.configured,
+  adapter: () => createAsyncRecoveryAdapters().providerDelivery,
+  evaluateRollout: evaluateLambdaProviderDelivery,
+  logger: createLogger({ component: 'provider-worker', feature: 'async-work', operation: 'provider-delivery',
+    slice: '${name}', stage: process.env.EBK_STAGE ?? 'local', workspace: process.env.EBK_WORKSPACE ?? '${name}' }),
+});
+`,
+    };
+}
+/** Replace only the SQL-specific provider cases; other async acceptance stays mandatory. */
+function renderKeyValueProviderTestCases(name) {
+    return `  function providerFixture() {
+    type Item = Record<string, AttributeValue>;
+    const rows = new Map<string, Item>();
+    let rejectTerminal = false;
+    const key = (item: Item) => item.pk.S + '/' + item.sk.S;
+    const client = { async send(command: unknown) {
+      if (command instanceof GetItemCommand) return { Item: structuredClone(rows.get(key(command.input.Key!))) };
+      if (!(command instanceof TransactWriteItemsCommand)) throw new Error('Unexpected test transport');
+      const writes = command.input.TransactItems!;
+      for (const item of writes) {
+        const op = item.Put!;
+        const previous = rows.get(key(op.Item!));
+        const allowed = op.ConditionExpression === 'attribute_not_exists(pk)' ? !previous : previous &&
+          previous.version.N === op.ExpressionAttributeValues![':version'].N && previous.scope.S === op.ExpressionAttributeValues![':scope'].S;
+        if (!allowed || (rejectTerminal && JSON.parse(op.Item!.value.S!).state === 'failed'))
+          throw Object.assign(new Error('conditional'), { name: 'TransactionCanceledException', CancellationReasons: [{ Code: 'ConditionalCheckFailed' }] });
+      }
+      for (const item of writes) rows.set(key(item.Put!.Item!), structuredClone(item.Put!.Item!));
+      return {};
+    } } as DynamoDBClient;
+    const store = createDynamoPersistence({ client, tableName: '${name}-development-task-test',
+      stage: 'development-task-test', slice: '${name}', eventBusName: 'test-event-bus' });
+    return { store, rows, rejectTerminal: () => { rejectTerminal = true; } };
+  }
+
+  it('routes a stale unproven provider effect to reconciliation without delivery', async () => {
+    const fixture = providerFixture();
+    const delivery = createQueuedProviderDelivery({ createdAt: '2026-01-01T00:00:00.000Z',
+      operationId: 'operation-one', request: { value: true } });
+    const claimed = await claimProviderDelivery(fixture.store, delivery, delivery.createdAt, () => 'first');
+    expect(claimed.outcome).toBe('claimed');
+    await markProviderEffectStarted(fixture.store, delivery.deliveryId, 'first', delivery.createdAt);
+    const deliver = vi.fn();
+    const handler = createProviderWorkerHandler({
+      store: () => fixture.store, createAttemptToken: () => 'next', configured: () => true,
+      adapter: () => ({ deliver }), evaluateRollout: vi.fn() as never,
+      logger: logger as never, now: () => '2026-01-01T00:03:00.000Z',
+    });
+    await expect(handler({ Records: [{ body: JSON.stringify(delivery), messageId: 'message-one' }] }))
+      .resolves.toEqual({ batchItemFailures: [{ itemIdentifier: 'message-one' }] });
+    expect(deliver).not.toHaveBeenCalled();
+    const row = await fixture.store.get('system', 'provider-inbox', delivery.deliveryId);
+    expect(row?.value).toMatchObject({ state: 'failed', resultReference: expect.stringContaining('terminal-reconciliation-') });
+  });
+
+  it('retains the uncertain claim when the terminal reconciliation transition loses its condition', async () => {
+    const fixture = providerFixture();
+    const delivery = createQueuedProviderDelivery({ createdAt: '2026-01-01T00:00:00.000Z',
+      operationId: 'operation-lost', request: { value: true } });
+    await claimProviderDelivery(fixture.store, delivery, delivery.createdAt, () => 'first');
+    await markProviderEffectStarted(fixture.store, delivery.deliveryId, 'first', delivery.createdAt);
+    fixture.rejectTerminal();
+    await expect(claimProviderDelivery(fixture.store, delivery, '2026-01-01T00:03:00.000Z'))
+      .resolves.toEqual({ outcome: 'retry' });
+    expect((await fixture.store.get('system', 'provider-inbox', delivery.deliveryId))?.value)
+      .toMatchObject({ state: 'effect-started', attemptToken: 'first' });
+  });
+
+  it('retries a stale effect only when provider repeat safety is guaranteed', async () => {
+    const fixture = providerFixture();
+    const delivery = createQueuedProviderDelivery({ createdAt: '2026-01-01T00:00:00.000Z',
+      operationId: 'operation-guaranteed', request: { value: true } });
+    delivery.contract.idempotencyRepeatSafety = 'provider-guaranteed';
+    await claimProviderDelivery(fixture.store, delivery, delivery.createdAt, () => 'first');
+    await markProviderEffectStarted(fixture.store, delivery.deliveryId, 'first', delivery.createdAt);
+    const deliver = vi.fn().mockResolvedValue({ outcome: 'confirmed', providerReference: 'provider-reference', statusCode: 202 });
+    const handler = createProviderWorkerHandler({
+      store: () => fixture.store, createAttemptToken: () => 'next', configured: () => true,
+      adapter: () => ({ deliver }), evaluateRollout: vi.fn().mockResolvedValue({ assigned: true }) as never,
+      logger: logger as never, now: () => '2026-01-01T00:03:00.000Z',
+    });
+    await expect(handler({ Records: [{ body: JSON.stringify(delivery), messageId: 'message-one' }] }))
+      .resolves.toEqual({ batchItemFailures: [] });
+    expect(deliver).toHaveBeenCalledTimes(1);
+  });
+`;
+}
+//# sourceMappingURL=built-in-plan-key-value-provider.js.map

package/src/generators/slice/built-in-plan-key-value-records.d.ts

@@ -0,0 +1,3 @@
+/** Seeded native record behavior. SQL declarations do not switch existing records between stores. */
+export declare function renderKeyValueRecordFiles(name: string, pascalName: string): Readonly<Record<string, string>>;
+export declare function renderKeyValueRecordApi(pascalName: string, workspace: string): string;

package/src/generators/slice/built-in-plan-key-value-records.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueRecordFiles = renderKeyValueRecordFiles;
+exports.renderKeyValueRecordApi = renderKeyValueRecordApi;
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+/** Seeded native record behavior. SQL declarations do not switch existing records between stores. */
+function renderKeyValueRecordFiles(name, pascalName) {
+    return {
+        'data/records.ts': `import { createHash } from 'node:crypto';
+import type { AuthorizationPrincipal } from '@empire-builder-kit/runtime/authorization';
+import { buildEventEntry } from '@empire-builder-kit/runtime/events';
+import { RuntimeError } from '@empire-builder-kit/runtime/response';
+import {
+  createDataLifecycleAuditRecord,
+  createDataLifecycleLedgerEntry,
+  createDataLifecyclePseudonymousReference,
+  lifecycleIdempotencyKey,
+} from '@empire-builder-kit/runtime/data-lifecycle';
+import { ${pascalName}Created, ${pascalName}DataLifecycleChanged } from '../contracts/events.js';
+import { create${pascalName}DataLifecycleChanged } from './lifecycle-event.js';
+import { productRecordReference } from './pseudonymous-reference.js';
+import { ${pascalName}DataLifecycleRuntimePolicy } from './runtime-policy.cjs';
+import { dataStore } from './key-value.js';
+
+export interface ProductRecord {
+  id: string;
+  name: string;
+  ownerId: string;
+  runScope: string;
+  createdAt: string;
+  lastActivityAt: string;
+  testExpiresAt: string | null;
+}
+export interface RecordMutationInput {
+  correlationId: string;
+  name: string;
+  now?: string;
+  principal: AuthorizationPrincipal;
+  recordId: string;
+  runScope: string;
+  testExpiresAt?: string;
+}
+export interface RecordMutationResult {
+  id: string;
+  name: string;
+  runScope: string;
+  propagation: 'pending';
+  requestRef: string;
+  created: boolean;
+}
+
+function failure(code: string, message: string, status: number): never {
+  throw new RuntimeError({ code, message, status, retryable: code === 'record_write_conflict' });
+}
+const hash = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const canonical = (value: unknown): value is string =>
+  typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+
+export function effectiveRecordOwner(principal: AuthorizationPrincipal): string {
+  if (principal.authority.mode === 'machine')
+    throw new Error('Machine authority cannot mutate a subject-owned record.');
+  return principal.authority.mode === 'delegated' ? principal.authority.delegatedBy.id : principal.actor.id;
+}
+
+export function readProductRecord(value: unknown, id: string): ProductRecord {
+  const record = value as ProductRecord;
+  if (!record || record.id !== id || typeof record.ownerId !== 'string' || !record.ownerId ||
+      typeof record.name !== 'string' || !record.name || record.name.length > 256 ||
+      typeof record.runScope !== 'string' || !record.runScope || record.runScope.length > 128 ||
+      !canonical(record.createdAt) || !canonical(record.lastActivityAt) ||
+      (record.testExpiresAt !== null && !canonical(record.testExpiresAt)))
+    throw new Error('Stored product record is malformed or has a different identity.');
+  // Explicit projection prevents unrelated fields from becoming API/export data.
+  return { id, name: record.name, ownerId: record.ownerId, runScope: record.runScope,
+    createdAt: record.createdAt, lastActivityAt: record.lastActivityAt, testExpiresAt: record.testExpiresAt };
+}
+
+export async function getOwnedRecord(id: string, ownerId: string): Promise<ProductRecord | null> {
+  const row = await dataStore().get('application', 'records', id);
+  if (!row) return null;
+  const record = readProductRecord(row.value, id);
+  return record.ownerId === ownerId ? record : null;
+}
+
+function conditionConflict(error: unknown): boolean {
+  return error instanceof Error && error.name === 'TransactionCanceledException' &&
+    (error as Error & { CancellationReasons?: { Code?: string }[] }).CancellationReasons?.some(
+      ({ Code }) => Code === 'ConditionalCheckFailed') === true;
+}
+
+/** Record, audit, lifecycle ledger and event intent either all commit or none do. */
+export async function mutateRecord(input: RecordMutationInput, allowCreate: boolean): Promise<RecordMutationResult> {
+  const ownerId = effectiveRecordOwner(input.principal);
+  const now = input.now ?? new Date().toISOString();
+  if (!canonical(now) || typeof input.name !== 'string' || !input.name || input.name.length > 256 ||
+      typeof input.runScope !== 'string' || !input.runScope || input.runScope.length > 128 ||
+      !input.correlationId || input.correlationId.length > 128)
+    failure('record_input_invalid', 'Record input is invalid.', 400);
+  const requestRef = lifecycleIdempotencyKey('record-put', [input.recordId, ownerId, input.correlationId]);
+  // Time is assigned only on the first successful mutation, not reconstructed on retry.
+  const commandDigest = hash([input.recordId, ownerId, input.principal.actor.id, input.principal.authority.mode,
+    input.name, input.runScope, input.testExpiresAt ?? null]);
+  const store = dataStore();
+  const row = await store.get('application', 'records', input.recordId);
+  const previous = row ? readProductRecord(row.value, input.recordId) : null;
+  if (previous && previous.ownerId !== ownerId)
+    failure('record_conflict', 'The record identifier is owned by another principal.', 409);
+  if (!previous && !allowCreate) failure('record_not_found', 'The correction target was not found.', 404);
+
+  async function retained(): Promise<RecordMutationResult | null> {
+    const receipt = await store.get('application', 'record-mutations', requestRef);
+    if (!receipt) return null;
+    const value = receipt.value as { commandDigest: string; result: { requestRef: string; created: boolean } };
+    if (!value || value.commandDigest !== commandDigest ||
+        value.result?.requestRef !== requestRef || typeof value.result.created !== 'boolean')
+      failure('record_idempotency_conflict', 'The mutation receipt does not match this exact request.', 409);
+    return { id: input.recordId, name: input.name, runScope: input.runScope,
+      propagation: 'pending', requestRef, created: value.result.created };
+  }
+  const repeated = await retained();
+  if (repeated) {
+    if (!previous) failure('record_not_found', 'The record no longer exists.', 404);
+    return repeated;
+  }
+  if (input.testExpiresAt !== undefined && (!canonical(input.testExpiresAt) ||
+      Date.parse(input.testExpiresAt) <= Date.parse(now) ||
+      Date.parse(input.testExpiresAt) - Date.parse(now) > 48 * 60 * 60 * 1_000))
+    failure('test_data_expiry_invalid', 'Test data expiry must be a canonical future timestamp within 48 hours.', 400);
+  const record: ProductRecord = {
+    id: input.recordId, name: input.name, ownerId, runScope: input.runScope,
+    createdAt: previous?.createdAt ?? now, lastActivityAt: now,
+    testExpiresAt: input.testExpiresAt ?? previous?.testExpiresAt ?? null,
+  };
+  const result: RecordMutationResult = { id: record.id, name: record.name, runScope: record.runScope,
+    propagation: 'pending', requestRef, created: !previous };
+  const policyVersion = ${pascalName}DataLifecycleRuntimePolicy.policyVersion;
+  const expiresAt = new Date(Date.parse(now) + 400 * 24 * 60 * 60 * 1_000).toISOString();
+  const recordRef = productRecordReference(record.id);
+  const entry = buildEventEntry(previous ? ${pascalName}DataLifecycleChanged : ${pascalName}Created,
+    previous ? create${pascalName}DataLifecycleChanged({ action: 'correction', occurredAt: now,
+      policyVersion, recordId: record.id, requestRef }) : { id: record.id, occurredBy: ownerId }, {
+      busName: process.env.EVENT_BUS_NAME ?? '', stage: process.env.EBK_STAGE ?? '',
+      context: { correlationId: input.correlationId, tenantId: 'application' }, eventId: requestRef, occurredAt: now,
+    }).entry;
+  const changes: Parameters<typeof store.commit>[0]['changes'][number][] = [
+    { action: 'put', collection: 'records', id: record.id, expectedVersion: row?.version ?? 0, value: record },
+    { action: 'put', collection: 'record-mutations', id: requestRef, expectedVersion: 0,
+      // Retry metadata must not retain a second copy of subject-owned content.
+      value: { commandDigest, result: { requestRef, created: result.created }, occurredAt: now, expiresAt } },
+  ];
+  if (previous) {
+    const pseudonym = (categoryId: string, value: string) => createDataLifecyclePseudonymousReference({
+      categoryId, slice: '${name}', value });
+    const audit = createDataLifecycleAuditRecord({ action: 'correction',
+      actorRef: pseudonym('authorization-subject', input.principal.actor.id), authorityCode: input.principal.authority.mode,
+      correlationRef: pseudonym('correlation', input.correlationId), outcome: 'succeeded', policyVersion,
+      purposeCode: 'record-correction', summary: 'A record correction and its downstream event were committed.',
+      targetCategoryId: 'product-record', timestamp: now });
+    changes.push(
+      { action: 'put', collection: 'data-lifecycle-ledger', id: requestRef, expectedVersion: 0,
+        value: createDataLifecycleLedgerEntry({ action: 'correction', categoryId: 'product-record',
+          effectiveAt: now, expiresAt, policyVersion, pseudonymousKey: recordRef }) },
+      { action: 'put', collection: 'data-lifecycle-audit', id: requestRef, expectedVersion: 0,
+        value: { audit, resourceReference: recordRef, principalKind: input.principal.kind,
+          subjectType: input.principal.actor.type, slice: '${name}', stage: process.env.EBK_STAGE,
+          approvalReference: null, expiresAt } },
+    );
+  }
+  try {
+    await store.commit({ tenantId: 'application', changes, events: [entry] });
+  } catch (error) {
+    if (!conditionConflict(error)) throw error;
+    // A concurrent exact retry may have committed. Anything else is a real
+    // optimistic-write conflict, never an accepted partial correction.
+    const latest = await getOwnedRecord(input.recordId, ownerId);
+    const replay = latest ? await retained() : null;
+    if (replay) return replay;
+    failure('record_write_conflict', 'The record changed concurrently; retry the request.', 409);
+  }
+  return result;
+}
+`,
+        'data/record-correction.ts': `import { mutateRecord, type RecordMutationInput } from './records.js';
+import { dispatchEventIntent } from '../async/key-value-delivery.js';
+
+export type RecordCorrectionInput = RecordMutationInput;
+export const correctRecordWithLifecycle = (input: RecordCorrectionInput) => mutateRecord(input, false);
+export const putRecordWithLifecycle = (input: RecordMutationInput) => mutateRecord(input, true);
+
+export async function publishRecordCorrection(_correlationId: string, requestRef: string) {
+  return dispatchEventIntent(requestRef);
+}
+`,
+    };
+}
+function renderKeyValueRecordApi(pascalName, workspace) {
+    const prefix = (0, built_in_plan_shared_js_1.lowerCamelIdentifier)(pascalName);
+    return `import type { RuntimeHttpEvent } from '@empire-builder-kit/runtime';
+import type { Principal } from '@empire-builder-kit/runtime/auth';
+import type { AuthorizationPrincipal } from '@empire-builder-kit/runtime/authorization';
+import { createContractHttpJsonHandler } from '@empire-builder-kit/runtime/api-server';
+import { RuntimeError } from '@empire-builder-kit/runtime/response';
+import { ${prefix}GetRecord, ${prefix}PutRecord } from '../api/contracts/protected.js';
+import { authorize${pascalName}DataRightsOperation, authorize${pascalName}Operation } from '../authorization/runtime.js';
+import { putRecordWithLifecycle } from '../data/record-correction.js';
+import { getOwnedRecord } from '../data/records.js';
+
+export const putHandler = createContractHttpJsonHandler<typeof ${prefix}PutRecord, RuntimeHttpEvent, AuthorizationPrincipal>({
+  component: 'database-records', operation: ${prefix}PutRecord, workspace: '${workspace}',
+  authorize: authorize${pascalName}DataRightsOperation,
+  async handle({ context, principal, request }) {
+    const result = await putRecordWithLifecycle({ correlationId: context.correlationId, principal,
+      recordId: request.path.recordId, name: request.body.name, runScope: request.body.runScope,
+      testExpiresAt: request.body.testExpiresAt });
+    // The durable intent commits with the record; Streams/reconciliation own
+    // delivery. An EventBridge outage cannot turn a committed write into loss.
+    return { id: result.id, name: result.name, runScope: result.runScope };
+  },
+});
+
+export const getHandler = createContractHttpJsonHandler<typeof ${prefix}GetRecord, RuntimeHttpEvent, Principal>({
+  component: 'database-records', operation: ${prefix}GetRecord, workspace: '${workspace}',
+  authorize: authorize${pascalName}Operation,
+  async handle({ principal, request }) {
+    const record = await getOwnedRecord(request.path.recordId, principal.id);
+    if (!record) throw new RuntimeError({ code: 'record_not_found', message: 'The record was not found.', status: 404, retryable: false });
+    return { id: record.id, name: record.name, runScope: record.runScope };
+  },
+});
+`;
+}
+//# sourceMappingURL=built-in-plan-key-value-records.js.map

package/src/generators/slice/built-in-plan-key-value-retention-infrastructure.d.ts

@@ -0,0 +1,2 @@
+/** Framework retention uses native DynamoDB regardless of optional feature SQL. */
+export declare function renderKeyValueRetentionInfrastructureFiles(name: string, pascalName: string): Readonly<Record<string, string>>;