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

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

@@ -0,0 +1,477 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueRetentionWorkerFiles = renderKeyValueRetentionWorkerFiles;
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+/** Native bounded retention execution; no database credential, SQL adapter, or container prerequisite. */
+function renderKeyValueRetentionWorkerFiles(name, pascalName) {
+    const prefix = (0, built_in_plan_shared_js_1.lowerCamelIdentifier)(pascalName);
+    return {
+        'jobs/data-retention/src/adapter.ts': `import type { DataLifecycleRetentionCandidateV1 } from '@empire-builder-kit/runtime/data-lifecycle';
+import type { KeyValueRecord } from '@empire-builder-kit/runtime/key-value';
+import { productRecordReference } from '../../../data/pseudonymous-reference.js';
+import { readProductRecord } from '../../../data/records.js';
+import { RETENTION_DAYS } from '../../../data/retention-state.js';
+
+export interface RetentionCandidate extends DataLifecycleRetentionCandidateV1 { recordId: string; recordVersion: number }
+/** Adopter-owned selection of due Standard records; test-run cleanup is separate. */
+export function selectRetentionCandidate(row: KeyValueRecord & { id: string }, asOf: string): RetentionCandidate | null {
+  const record = readProductRecord(row.value, row.id);
+  const dueAt = new Date(Date.parse(record.lastActivityAt) + RETENTION_DAYS * 86_400_000).toISOString();
+  if (record.testExpiresAt !== null || Date.parse(dueAt) > Date.parse(asOf)) return null;
+  return { categoryId: 'product-record', locationId: 'primary-database', dueAt,
+    recordRef: productRecordReference(row.id), recordId: row.id, recordVersion: row.version };
+}
+`,
+        'data/retention-worker.ts': `import { createHash } from 'node:crypto';
+import {
+  assertAuthorizationAllowed, beginApprovalExecution, completeApprovalExecution,
+  createAuthorizationEvaluator, defineCoarseAdmission, digestApprovalRequest,
+  type AuthorizationPrincipal,
+} from '@empire-builder-kit/runtime/authorization';
+import { buildEventEntry } from '@empire-builder-kit/runtime/events';
+import {
+  createDataLifecycleEvidence, createDataLifecycleLedgerEntry, createDataLifecycleRetentionCheckpoint,
+  runDataLifecycleRetention, type DataLifecycleRetentionCheckpointV1,
+} from '@empire-builder-kit/runtime/data-lifecycle';
+import { ${prefix}AuthorizationActions, ${prefix}AuthorizationPolicy } from '../authorization/policy.js';
+import { ${pascalName}DataLifecycleChanged } from '../contracts/events.js';
+import { dispatchEventIntent } from '../async/key-value-delivery.js';
+import { selectRetentionCandidate, type RetentionCandidate } from '../jobs/data-retention/src/adapter.js';
+import { dataStore } from './key-value.js';
+import { dataRightsAuditChange, canonicalDataRightsNow, plusDataRightsDays } from './data-rights-shared.js';
+import { approvalReference, productRecordReference } from './pseudonymous-reference.js';
+import { loadActiveRecordHolds } from './record-holds.js';
+import { create${pascalName}DataLifecycleChanged } from './lifecycle-event.js';
+import { createReportedRetentionRun, loadRetentionRun, retentionApprovalInput, retentionRunChange,
+  retentionRunReference, retentionStage, RETENTION_RUNS, RETENTION_POLICY, RETENTION_DAYS,
+  RETENTION_AUTHORIZATION_POLICY, type RetentionRun, type ${pascalName}RetentionPlanV1 } from './retention-state.js';
+
+const TENANT = 'application';
+const SNAPSHOTS = 'data-retention-snapshots';
+const CANDIDATES = 'data-retention-candidates';
+const EXECUTIONS = 'data-retention-executions';
+const RECEIPTS = 'data-retention-receipts';
+const CHUNK_SIZE = 50;
+const MAX_ITEMS = 10000;
+const REPORT_PAGES_PER_INVOCATION = 20;
+const WORKLOAD = '${name}:data-retention-job';
+const sha = (value: unknown) => 'sha256:' + createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const planDigest = (run: RetentionRun) => digestApprovalRequest(retentionApprovalInput(run.plan));
+const chunkId = (runId: string, index: number) => runId + ':' + String(index).padStart(4, '0');
+const now = () => new Date().toISOString();
+class DeliveryPending extends Error {}
+interface Snapshot {
+  kind: 'retention-snapshot'; runId: string; slice: '${name}'; stage: string;
+  status: 'building' | 'completed'; createdAt: string; expiresAt: string;
+  pages: string[]; due: number; scanned: number; queryPages: number; planDigest: string | null;
+  binding: string; afterId: string | null; tail: RetentionCandidate[]; scanComplete: boolean;
+  command: RetentionInput;
+}
+interface Execution {
+  kind: 'retention-execution'; runId: string; planDigest: string; approvalId: string;
+  checkpoint: DataLifecycleRetentionCheckpointV1;
+  pageAttempts: number; replays: number; completedAt: string | null;
+}
+interface Receipt {
+  kind: 'retention-receipt'; runId: string; planDigest: string; candidateDigest: string;
+  eventId: string; appliedAt: string; publishedAt: string | null; expiresAt: string;
+}
+export interface RetentionInput {
+  mode: 'report' | 'apply'; runId: string; approvalRequestId: string;
+  asOf: string; correlationId: string; slice: string; stage: string; sourceCommit: string;
+  resume?: true;
+}
+function reportBinding(command: RetentionInput) {
+  // Stored JSON is canonicalized; never bind to incidental object-key order.
+  return sha({ mode: command.mode, runId: command.runId, approvalRequestId: command.approvalRequestId,
+    asOf: command.asOf, correlationId: command.correlationId, slice: command.slice, stage: command.stage,
+    sourceCommit: command.sourceCommit, policy: RETENTION_POLICY, retentionDays: RETENTION_DAYS });
+}
+function input(value: RetentionInput) {
+  if (!value || (value.mode !== 'report' && value.mode !== 'apply') || value.slice !== '${name}' ||
+      value.stage !== retentionStage() || typeof value.asOf !== 'string' ||
+      !/^[a-f0-9]{40,64}$/.test(value.sourceCommit ?? '') ||
+      !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.correlationId ?? ''))
+    throw new Error('Retention invocation identity or mode is invalid.');
+  retentionRunReference(value.runId); canonicalDataRightsNow(value.asOf);
+  if (value.resume !== undefined && (value.resume !== true || value.mode !== 'report'))
+    throw new Error('Only a report may resume its original selection.');
+  if (value.mode === 'apply') retentionRunReference(value.approvalRequestId);
+  else if (value.approvalRequestId !== '') throw new Error('A report cannot select mutation approval.');
+}
+export async function authorizeRetentionOperation(mode: 'report' | 'apply', at: string, runId: string): Promise<AuthorizationPrincipal> {
+  if (process.env.EBK_WORKLOAD_IDENTITY !== WORKLOAD) throw new Error('Retention Job workload identity is invalid.');
+  const principal: AuthorizationPrincipal = { actor: { id: WORKLOAD, type: 'service' }, audience: WORKLOAD,
+    authority: { machineIdentityId: WORKLOAD, mode: 'machine' }, kind: 'agent', roles: [], scopes: [], subject: { id: WORKLOAD, type: 'service' } };
+  await createAuthorizationEvaluator({ admission: defineCoarseAdmission({ anyOf: [{ kinds: ['agent'], subjectTypes: ['service'] }] }),
+    policy: ${prefix}AuthorizationPolicy, requiredPolicyVersion: RETENTION_AUTHORIZATION_POLICY }).authorize({
+      action: mode === 'report' ? ${prefix}AuthorizationActions.retentionReport : ${prefix}AuthorizationActions.retentionApply,
+      context: { facts: { operationId: runId }, now: at, stage: retentionStage() }, principal,
+      resource: { attributes: { collection: true }, type: 'slice' },
+    });
+  return principal;
+}
+function audit(command: RetentionInput, principal: AuthorizationPrincipal, purposeCode: string, at: string) {
+  return dataRightsAuditChange({ action: command.mode === 'report' ? 'retention-report' : 'retention-apply',
+    ...(command.approvalRequestId ? { approvalRequestId: command.approvalRequestId } : {}),
+    correlationId: command.correlationId, now: at, principal, resourceReference: retentionRunReference(command.runId),
+    purposeCode, outcome: 'succeeded', summary: 'A bounded native retention transition was committed.' });
+}
+function validateCandidate(value: RetentionCandidate, asOf: string): RetentionCandidate {
+  if (!value || typeof value.recordId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.recordId) ||
+      !Number.isSafeInteger(value.recordVersion) || value.recordVersion < 1 || value.categoryId !== 'product-record' ||
+      value.locationId !== 'primary-database' || value.recordRef !== productRecordReference(value.recordId) || typeof value.dueAt !== 'string' ||
+      Object.keys(value).sort().join(',') !== 'categoryId,dueAt,locationId,recordId,recordRef,recordVersion')
+    throw new Error('Retention candidate does not belong to the exact record contract.');
+  canonicalDataRightsNow(value.dueAt);
+  if (Date.parse(value.dueAt) > Date.parse(asOf)) throw new Error('Retention candidate is not due.');
+  // Construct a deterministic projection independent of object property order.
+  return { categoryId: value.categoryId, locationId: value.locationId, dueAt: value.dueAt,
+    recordRef: value.recordRef, recordId: value.recordId, recordVersion: value.recordVersion };
+}
+function inventoryDigest(pages: readonly string[], due: number) { return sha({ pages, due, chunkSize: CHUNK_SIZE }); }
+function bounded(deadline: number) {
+  if (Date.now() >= deadline) throw new Error('Retention invocation time budget exhausted; retained state requires retry, not success.');
+}
+async function report(command: RetentionInput, principal: AuthorizationPrincipal, startedAt: string, deadline: number) {
+  if (Date.parse(command.asOf) > Date.parse(startedAt)) throw new Error('Retention report cannot select future records.');
+  const store = dataStore();
+  const binding = reportBinding(command);
+  const retained = await store.get(TENANT, SNAPSHOTS, command.runId);
+  let version = retained?.version ?? 0;
+  let building: Snapshot = retained ? retained.value as Snapshot : {
+    kind: 'retention-snapshot', runId: command.runId, slice: '${name}', stage: retentionStage(),
+    status: 'building', createdAt: startedAt, expiresAt: plusDataRightsDays(startedAt, 400),
+    pages: [], due: 0, scanned: 0, queryPages: 0, planDigest: null,
+    binding, command: { ...command }, afterId: null, tail: [], scanComplete: false };
+  if (!building || building.kind !== 'retention-snapshot' || building.runId !== command.runId ||
+      building.slice !== '${name}' || building.stage !== retentionStage() || building.binding !== binding ||
+      !building.command || reportBinding(building.command) !== binding ||
+      !['building', 'completed'].includes(building.status) || !Array.isArray(building.pages) ||
+      building.pages.some(page => !/^sha256:[a-f0-9]{64}$/.test(page)) || !Array.isArray(building.tail) ||
+      building.tail.length >= CHUNK_SIZE || typeof building.scanComplete !== 'boolean' ||
+      !Number.isSafeInteger(building.due) || building.due < 0 || building.due > MAX_ITEMS ||
+      !Number.isSafeInteger(building.scanned) || building.scanned < building.due ||
+      !Number.isSafeInteger(building.queryPages) || building.queryPages < 0 ||
+      typeof building.createdAt !== 'string' || typeof building.expiresAt !== 'string' ||
+      (building.afterId !== null && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(building.afterId)) ||
+      building.expiresAt !== plusDataRightsDays(canonicalDataRightsNow(building.createdAt), 400) ||
+      Date.parse(startedAt) >= Date.parse(building.expiresAt))
+    throw new Error('Retention report checkpoint differs from this invocation or has expired.');
+  building.tail = building.tail.map(candidate => validateCandidate(candidate, command.asOf));
+  if (building.scanComplete ? building.tail.length !== 0 || building.pages.length !== Math.ceil(building.due / CHUNK_SIZE)
+    : building.pages.length * CHUNK_SIZE + building.tail.length !== building.due)
+    throw new Error('Retention report checkpoint has inconsistent candidate counts.');
+  if (building.status === 'completed') {
+    const { run } = await loadRetentionRun(command.runId, startedAt);
+    if (run.status !== 'reported')
+      throw new Error('Retention report cannot be resumed after approval or execution; retained apply evidence is unchanged.');
+    await snapshotFor(run);
+    return finishEvidence(command, run, { applied: 0, alreadyApplied: 0, applyPages: 0,
+      due: building.due, reportPages: building.queryPages }, building.createdAt, run.createdAt);
+  }
+  if (!retained) {
+    await store.commit({ tenantId: TENANT, changes: [
+      { action: 'check', collection: RETENTION_RUNS, id: command.runId, expectedVersion: 0 },
+      { action: 'put', collection: SNAPSHOTS, id: command.runId, expectedVersion: 0, value: building },
+    ] });
+    version++;
+  }
+  // Each invocation scans at most 1,000 rows. The 10,000 bound applies to the
+  // reviewed deletion batch, not to unrelated healthy records in the table.
+  for (let queries = 0; !building.scanComplete && queries < REPORT_PAGES_PER_INVOCATION; queries++) {
+    if (Date.now() >= deadline) return { complete: false as const, runRef: command.runId, checkpointComplete: false };
+    const page = await store.list(TENANT, 'records', { limit: CHUNK_SIZE,
+      ...(building.afterId ? { afterId: building.afterId } : {}) });
+    let afterId = building.afterId, scanned = building.scanned, due = building.due;
+    const candidates = [...building.tail];
+    for (const row of page.records) {
+      if (afterId && row.id <= afterId) throw new Error('Retention inventory did not advance.');
+      scanned++; afterId = row.id;
+      const selected = selectRetentionCandidate(row, command.asOf);
+      if (selected) {
+        const candidate = validateCandidate(selected, command.asOf);
+        if (candidate.recordId !== row.id || candidate.recordVersion !== row.version) throw new Error('Retention adapter substituted the record identity.');
+        candidates.push(candidate); due++;
+      }
+      if (due === MAX_ITEMS) break;
+    }
+    if (page.nextId && due < MAX_ITEMS && (page.records.length === 0 || page.nextId !== afterId))
+      throw new Error('Retention inventory is incomplete or its cursor is invalid.');
+    const scanComplete = !page.nextId || due === MAX_ITEMS;
+    const pages = [...building.pages], chunks = [];
+    while (candidates.length >= CHUNK_SIZE || (scanComplete && candidates.length)) {
+      const records = candidates.splice(0, CHUNK_SIZE), index = pages.length;
+      pages.push(sha(records));
+      chunks.push({ action: 'put' as const, collection: CANDIDATES, id: chunkId(command.runId, index), expectedVersion: 0,
+        value: { runId: command.runId, stage: retentionStage(), slice: '${name}', index, records, expiresAt: building.expiresAt } });
+    }
+    const next = { ...building, pages, due, scanned, queryPages: building.queryPages + 1,
+      afterId, tail: candidates, scanComplete };
+    bounded(deadline);
+    await store.commit({ tenantId: TENANT, changes: [
+      { action: 'check', collection: RETENTION_RUNS, id: command.runId, expectedVersion: 0 },
+      { action: 'put', collection: SNAPSHOTS, id: command.runId, expectedVersion: version, value: next }, ...chunks,
+    ] });
+    building = next; version++;
+  }
+  if (!building.scanComplete) return { complete: false as const, runRef: command.runId, checkpointComplete: false };
+  bounded(deadline);
+  const completedAt = now();
+  const plan: ${pascalName}RetentionPlanV1 = { asOf: command.asOf, candidateDigest: inventoryDigest(building.pages, building.due),
+    categoryId: 'product-record', due: building.due, locationId: 'primary-database', maxItems: 10000,
+    pageSize: 100, policyVersion: RETENTION_POLICY, retentionDays: RETENTION_DAYS, runId: command.runId };
+  const run = createReportedRetentionRun(plan, completedAt);
+  const snapshot: Snapshot = { ...building, status: 'completed', planDigest: planDigest(run) };
+  await store.commit({ tenantId: TENANT, changes: [retentionRunChange(run, 0),
+    { action: 'put', collection: SNAPSHOTS, id: command.runId, expectedVersion: version, value: snapshot },
+    audit(command, principal, 'report-completed', completedAt),
+  ] });
+  return finishEvidence(command, run, { applied: 0, alreadyApplied: 0, applyPages: 0, due: building.due, reportPages: building.queryPages }, building.createdAt, completedAt);
+}
+async function snapshotFor(run: RetentionRun) {
+  const row = await dataStore().get(TENANT, SNAPSHOTS, run.plan.runId);
+  const value = row?.value as Snapshot | undefined;
+  if (!value || value.kind !== 'retention-snapshot' || value.status !== 'completed' || value.runId !== run.plan.runId ||
+      value.stage !== run.stage || value.slice !== '${name}' || value.planDigest !== planDigest(run) || value.due !== run.plan.due ||
+      !Array.isArray(value.pages) || value.pages.length !== Math.ceil(value.due / CHUNK_SIZE) ||
+      value.pages.some(digest => typeof digest !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(digest)) ||
+      inventoryDigest(value.pages, value.due) !== run.plan.candidateDigest ||
+      !Number.isSafeInteger(value.scanned) || value.scanned < value.due ||
+      !Number.isSafeInteger(value.queryPages) || value.queryPages < 1 ||
+      value.scanComplete !== true || value.tail?.length !== 0 ||
+      typeof value.createdAt !== 'string' || typeof value.expiresAt !== 'string')
+    throw new Error('The approved retention snapshot is missing or inconsistent.');
+  canonicalDataRightsNow(value.createdAt); canonicalDataRightsNow(value.expiresAt);
+  if (value.expiresAt !== plusDataRightsDays(value.createdAt, 400) || Date.parse(now()) >= Date.parse(value.expiresAt))
+    throw new Error('The approved retention snapshot is expired.');
+  return { snapshot: value, version: row!.version };
+}
+async function candidatePage(run: RetentionRun, snapshot: Snapshot, offset: number, limit: number) {
+  const result: RetentionCandidate[] = [];
+  for (let index = Math.floor(offset / CHUNK_SIZE); index < Math.ceil(Math.min(offset + limit, snapshot.due) / CHUNK_SIZE); index++) {
+    const row = await dataStore().get(TENANT, CANDIDATES, chunkId(run.plan.runId, index));
+    const value = row?.value as { runId: string; stage: string; slice: string; index: number; records: RetentionCandidate[]; expiresAt: string } | undefined;
+    if (!value || value.runId !== run.plan.runId || value.stage !== run.stage || value.slice !== '${name}' || value.index !== index ||
+        !Array.isArray(value.records) || value.records.length !== Math.min(CHUNK_SIZE, snapshot.due - index * CHUNK_SIZE) ||
+        value.expiresAt !== snapshot.expiresAt)
+      throw new Error('Retention candidate page is missing or outside its approved snapshot.');
+    const records = value.records.map(record => validateCandidate(record, run.plan.asOf));
+    if (sha(records) !== snapshot.pages[index]) throw new Error('Retention candidate page changed after approval.');
+    result.push(...records);
+  }
+  const selected = result.slice(offset % CHUNK_SIZE, offset % CHUNK_SIZE + limit);
+  if (new Set(selected.map(record => record.recordId)).size !== selected.length) throw new Error('Retention candidate page has duplicate records.');
+  return selected;
+}
+function offsetFor(checkpoint: DataLifecycleRetentionCheckpointV1, due: number) {
+  if (!checkpoint || checkpoint.version !== 1 || checkpoint.policyVersion !== RETENTION_POLICY || typeof checkpoint.complete !== 'boolean')
+    throw new Error('Retention execution checkpoint is malformed.');
+  if (checkpoint.complete) {
+    if (checkpoint.cursor !== undefined) throw new Error('Completed retention cannot retain a cursor.');
+    return due;
+  }
+  if (checkpoint.cursor === undefined) return 0;
+  if (!/^offset_[1-9][0-9]*$/.test(checkpoint.cursor)) throw new Error('Retention execution cursor is invalid.');
+  const offset = Number(checkpoint.cursor.slice(7));
+  if (!Number.isSafeInteger(offset) || offset % 100 || offset >= due) throw new Error('Retention execution cursor is outside its approved plan.');
+  return offset;
+}
+async function executionFor(run: RetentionRun) {
+  const row = await dataStore().get(TENANT, EXECUTIONS, run.plan.runId);
+  const value = row?.value as Execution | undefined;
+  if (!row || !value || value.kind !== 'retention-execution' || value.runId !== run.plan.runId || value.planDigest !== planDigest(run) ||
+      value.approvalId !== run.approval?.id || !Number.isSafeInteger(value.pageAttempts) || value.pageAttempts < 0 ||
+      !Number.isSafeInteger(value.replays) || value.replays < 0)
+    throw new Error('Retention execution is missing or no longer matches its approval.');
+  offsetFor(value.checkpoint, run.plan.due);
+  if (value.completedAt !== null) {
+    if (typeof value.completedAt !== 'string') throw new Error('Retention completion time is invalid.');
+    canonicalDataRightsNow(value.completedAt);
+    if (!value.checkpoint.complete || run.status !== 'completed' || value.completedAt !== run.approval?.execution?.completedAt)
+      throw new Error('Retention lacks matching completed execution evidence.');
+  } else if (run.status === 'completed') throw new Error('Retention completion evidence is missing.');
+  return { execution: value, version: row.version };
+}
+async function applyCandidate(command: RetentionInput, principal: AuthorizationPrincipal, run: RetentionRun, runVersion: number,
+  candidate: RetentionCandidate, idempotencyKey: string) {
+  const store = dataStore();
+  const eventId = 'retention-' + createHash('sha256').update(command.runId + '\\0' + idempotencyKey).digest('hex');
+  const receiptId = command.runId + ':' + eventId;
+  let row = await store.get(TENANT, RECEIPTS, receiptId);
+  let receipt = row?.value as Receipt | undefined;
+  const prior = !!row;
+  if (!row) {
+    const record = await store.get(TENANT, 'records', candidate.recordId);
+    if (!record || record.version !== candidate.recordVersion) throw new Error('A reviewed record changed; create and approve a new retention report.');
+    const current = selectRetentionCandidate({ ...record, id: candidate.recordId }, run.plan.asOf);
+    if (!current || sha(validateCandidate(current, run.plan.asOf)) !== sha(candidate)) throw new Error('The reviewed record is no longer due.');
+    const at = now();
+    const holds = await loadActiveRecordHolds(candidate.recordId, at, 'deletion');
+    if (holds.evaluation.blocked) throw new Error('Retention deletion is blocked by an active hold.');
+    receipt = { kind: 'retention-receipt', runId: command.runId, planDigest: planDigest(run), candidateDigest: sha(candidate),
+      eventId, appliedAt: at, publishedAt: null, expiresAt: plusDataRightsDays(at, 400) };
+    const ledger = createDataLifecycleLedgerEntry({ action: 'deletion', categoryId: 'product-record', effectiveAt: at,
+      expiresAt: receipt.expiresAt, policyVersion: RETENTION_POLICY, pseudonymousKey: candidate.recordRef });
+    const entry = buildEventEntry(${pascalName}DataLifecycleChanged,
+      create${pascalName}DataLifecycleChanged({ action: 'deletion', occurredAt: at, policyVersion: RETENTION_POLICY,
+        recordId: candidate.recordId, requestRef: approvalReference(command.approvalRequestId) }),
+      { busName: process.env.EVENT_BUS_NAME ?? '', stage: retentionStage(), eventId, occurredAt: at,
+        context: { correlationId: command.correlationId, tenantId: TENANT } }).entry;
+    await store.commit({ tenantId: TENANT, changes: [
+      { action: 'check', collection: RETENTION_RUNS, id: command.runId, expectedVersion: runVersion },
+      { action: 'delete', collection: 'records', id: candidate.recordId, expectedVersion: candidate.recordVersion },
+      holds.check,
+      { action: 'put', collection: RECEIPTS, id: receiptId, expectedVersion: 0, value: receipt },
+      { action: 'put', collection: 'data-lifecycle-ledger', id: eventId, expectedVersion: 0, value: ledger },
+      audit(command, principal, 'primary-deleted', at),
+    ], events: [entry], retainEventsUntilAcknowledged: true });
+    row = await store.get(TENANT, RECEIPTS, receiptId); receipt = row?.value as Receipt | undefined;
+  }
+  if (!row || !receipt || receipt.kind !== 'retention-receipt' || receipt.runId !== command.runId ||
+      receipt.planDigest !== planDigest(run) || receipt.candidateDigest !== sha(candidate) || receipt.eventId !== eventId ||
+      typeof receipt.appliedAt !== 'string' || receipt.expiresAt !== plusDataRightsDays(receipt.appliedAt, 400))
+    throw new Error('Retention receipt is missing or differs from the approved effect.');
+  canonicalDataRightsNow(receipt.appliedAt);
+  if (Date.parse(receipt.appliedAt) > Date.parse(now()) || Date.parse(now()) >= Date.parse(receipt.expiresAt)) throw new Error('Retention receipt is expired or future-dated.');
+  if (receipt.publishedAt !== null) {
+    if (typeof receipt.publishedAt !== 'string') throw new Error('Retention delivery evidence is invalid.');
+    canonicalDataRightsNow(receipt.publishedAt);
+    if (Date.parse(receipt.publishedAt) < Date.parse(receipt.appliedAt) || Date.parse(receipt.publishedAt) > Date.parse(now())) throw new Error('Retention delivery time is invalid.');
+    return 'already-applied' as const;
+  }
+  const delivery = await dispatchEventIntent(eventId);
+  if (delivery === 'delivery-pending') throw new DeliveryPending('Another worker holds the durable delivery lease.');
+  if (delivery !== 'published') throw new Error('Retention event remains unacknowledged; retry the exact approved run.');
+  await store.commit({ tenantId: TENANT, changes: [
+    { action: 'check', collection: RETENTION_RUNS, id: command.runId, expectedVersion: runVersion },
+    { action: 'put', collection: RECEIPTS, id: receiptId, expectedVersion: row.version, value: { ...receipt, publishedAt: now() } },
+  ], acknowledgeEvents: [eventId] });
+  return prior ? 'already-applied' as const : 'applied' as const;
+}
+function finishEvidence(command: RetentionInput, run: RetentionRun, counts: {
+  applied: number; alreadyApplied: number; applyPages: number; due: number; reportPages: number;
+}, startedAt: string, completedAt: string) {
+  return { complete: true as const, runRef: command.runId, counts, planDigest: 'sha256:' + planDigest(run),
+    ...(command.mode === 'apply' ? { approvalRequestId: command.approvalRequestId, checkpointComplete: true } : {}),
+    evidence: createDataLifecycleEvidence({ categoryId: 'product-record', completedAt, counts,
+      operation: command.mode === 'apply' ? 'retention-apply' : 'retention-report', outcome: 'succeeded',
+      policyVersion: RETENTION_POLICY, ...(command.approvalRequestId ? { requestRef: approvalReference(command.approvalRequestId) } : {}),
+      startedAt, summary: command.mode === 'report' ? 'Bounded native retention report completed without product-data mutation.'
+        : 'Bounded native retention apply and durable event delivery completed under non-author approval.',
+      systemIds: ['primary-database', 'lifecycle-control'] }),
+  };
+}
+export async function runNativeRetention(command: RetentionInput, budgetMs = 240_000) {
+  input(command);
+  if (!Number.isSafeInteger(budgetMs) || budgetMs < 1 || budgetMs > 240_000) throw new Error('Retention requires a bounded invocation budget.');
+  const startedAt = now(), deadline = Date.now() + budgetMs;
+  const principal = await authorizeRetentionOperation(command.mode, startedAt, command.runId);
+  bounded(deadline);
+  if (command.resume) {
+    const row = await dataStore().get(TENANT, SNAPSHOTS, command.runId);
+    const original = (row?.value as Snapshot | undefined)?.command;
+    if (!original) throw new Error('Retention report resume requires its existing checkpoint.');
+    input(original);
+    if (original.mode !== 'report' || original.resume !== undefined || original.runId !== command.runId ||
+        original.slice !== command.slice || original.stage !== command.stage || original.sourceCommit !== command.sourceCommit)
+      throw new Error('Retention report resume differs from the original source or scope. Resume with the original checkout/artifacts and EBK_SOURCE_COMMIT=' + original.sourceCommit + '.');
+    // The new execution's clock/correlation cannot select additional records.
+    // report() revalidates the retained policy binding, expiry and checkpoint.
+    command = original;
+  }
+  if (command.mode === 'report') return report(command, principal, startedAt, deadline);
+  const store = dataStore();
+  let { run, version: runVersion } = await loadRetentionRun(command.runId, startedAt);
+  if (!run.approval || run.approval.id !== command.approvalRequestId) throw new Error('Retention apply requires its exact report approval.');
+  const { snapshot } = await snapshotFor(run);
+  if (run.status === 'completed') {
+    const { execution } = await executionFor(run);
+    if (!execution.completedAt) throw new Error('Retention completion is missing.');
+    return finishEvidence(command, run, { applied: run.plan.due, alreadyApplied: execution.replays,
+      applyPages: execution.pageAttempts, due: run.plan.due, reportPages: snapshot.queryPages }, run.approval.execution!.startedAt, execution.completedAt);
+  }
+  if (!['approval-approved', 'applying', 'retry-required'].includes(run.status)) throw new Error('Retention run is not approved for apply.');
+  const begun = beginApprovalExecution(run.approval, { ...retentionApprovalInput(run.plan), executionId: command.runId,
+    now: startedAt, requiredPolicyVersion: RETENTION_AUTHORIZATION_POLICY });
+  assertAuthorizationAllowed(begun.decision);
+  if (run.status === 'approval-approved') {
+    // Only the retained, approved candidates are mutation targets. Each target
+    // is revalidated with its exact version and hold set at the deletion below;
+    // later unrelated inserts cannot expand or invalidate this bounded approval.
+    const execution: Execution = { kind: 'retention-execution', runId: command.runId, planDigest: planDigest(run),
+      approvalId: command.approvalRequestId, checkpoint: createDataLifecycleRetentionCheckpoint(RETENTION_POLICY), pageAttempts: 0, replays: 0, completedAt: null };
+    bounded(deadline);
+    await store.commit({ tenantId: TENANT, changes: [
+      retentionRunChange({ ...run, approval: begun.request, status: 'applying', updatedAt: now() }, runVersion),
+      { action: 'put', collection: EXECUTIONS, id: command.runId, expectedVersion: 0, value: execution },
+      audit(command, principal, 'execution-started', now()),
+    ] });
+    ({ run, version: runVersion } = await loadRetentionRun(command.runId, now()));
+  }
+  let { execution, version: executionVersion } = await executionFor(run);
+  if (!execution.checkpoint.complete) {
+    const offset = offsetFor(execution.checkpoint, run.plan.due);
+    const candidates = await candidatePage(run, snapshot, offset, 100);
+    const lookup = new Map(candidates.map(candidate => [candidate.recordRef, candidate]));
+    let deliveryPending = false;
+    const result = await runDataLifecycleRetention({ asOf: run.plan.asOf, checkpoint: execution.checkpoint,
+      limit: 100, mode: 'apply', policyVersion: RETENTION_POLICY, adapter: {
+        scan: async () => ({ items: candidates, ...(offset + candidates.length < run.plan.due ? { nextCursor: 'offset_' + (offset + candidates.length) } : {}) }),
+        apply: async ({ candidate, idempotencyKey }) => {
+          bounded(deadline);
+          const retained = lookup.get(candidate.recordRef);
+          if (!retained) throw new Error('Retention candidate was not part of this reviewed page.');
+          try { return await applyCandidate(command, principal, run, runVersion, retained, idempotencyKey); }
+          catch (error) { deliveryPending = error instanceof DeliveryPending; throw error; }
+        },
+      } });
+    execution = { ...execution, checkpoint: result.checkpoint, pageAttempts: execution.pageAttempts + 1, replays: execution.replays + result.alreadyApplied };
+    await store.commit({ tenantId: TENANT, changes: [
+      { action: 'check', collection: RETENTION_RUNS, id: command.runId, expectedVersion: runVersion },
+      { action: 'put', collection: EXECUTIONS, id: command.runId, expectedVersion: executionVersion, value: execution },
+    ] });
+    executionVersion++;
+    if (result.status === 'retry-required') {
+      if (deliveryPending) return { complete: false as const, runRef: command.runId, checkpointComplete: false, deliveryPending: true };
+      throw new Error('Retention apply needs an exact-run retry; no success evidence was issued.');
+    }
+    if (!execution.checkpoint.complete) return { complete: false as const, runRef: command.runId, checkpointComplete: false };
+  }
+  bounded(deadline);
+  const completedAt = now();
+  const completed = completeApprovalExecution(run.approval!, { executionId: command.runId, now: completedAt, requiredPolicyVersion: RETENTION_AUTHORIZATION_POLICY });
+  assertAuthorizationAllowed(completed.decision);
+  run = { ...run, approval: completed.request, status: 'completed', updatedAt: completedAt };
+  await store.commit({ tenantId: TENANT, changes: [retentionRunChange(run, runVersion),
+    { action: 'put', collection: EXECUTIONS, id: command.runId, expectedVersion: executionVersion, value: { ...execution, completedAt } },
+    audit(command, principal, 'execution-completed', completedAt),
+  ] });
+  return finishEvidence(command, run, { applied: run.plan.due, alreadyApplied: execution.replays,
+    applyPages: execution.pageAttempts, due: run.plan.due, reportPages: snapshot.queryPages }, run.approval!.execution!.startedAt, completedAt);
+}
+`,
+        'jobs/data-retention/src/run.ts': `import { createLogger } from '@empire-builder-kit/runtime/logging';
+import { runNativeRetention, type RetentionInput } from '../../../data/retention-worker.js';
+export { authorizeRetentionOperation } from '../../../data/retention-worker.js';
+
+/** Step Functions invokes one bounded native page; only complete=true carries success evidence. */
+export async function handler(event: RetentionInput, context?: { getRemainingTimeInMillis(): number }) {
+  const logger = createLogger({ component: 'job-data-retention', feature: 'data-lifecycle', operation: 'retention',
+    slice: '${name}', stage: process.env.EBK_STAGE ?? 'unknown', workspace: process.env.EBK_WORKSPACE ?? '${name}' });
+  try {
+    const remaining = context?.getRemainingTimeInMillis() ?? 250_000;
+    const result = await runNativeRetention(event, Math.min(240_000, remaining - 10_000));
+    logger.info('Native retention invocation completed', { attributes: { complete: result.complete },
+      outcome: result.complete ? 'success' : 'unknown' });
+    return result;
+  } catch (error) {
+    // No record values, secret material, snapshot identifiers or provider body is logged.
+    logger.error('Native retention invocation failed', { outcome: 'failure', attributes: { retryRequired: true } });
+    throw error;
+  }
+}
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-key-value-retention-worker.js.map

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

@@ -0,0 +1,2 @@
+/** Framework retention control records remain in DynamoDB, including for SQL-enabled Slices. */
+export declare function renderKeyValueRetentionFiles(name: string, pascalName: string): Readonly<Record<string, string>>;