@empire-builder-kit/nx 1.0.0-rc.37 → 1.0.0-rc.39

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

@@ -0,0 +1,595 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueExportFiles = renderKeyValueExportFiles;
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+/** Native export authority, publication and cleanup; no SQL compatibility adapter. */
+function renderKeyValueExportFiles(name, pascalName) {
+    const prefix = (0, built_in_plan_shared_js_1.lowerCamelIdentifier)(pascalName);
+    return {
+        'data/record-export.ts': `import {
+  assertAuthorizationAllowed, beginApprovalExecution, completeApprovalExecution,
+  createApprovalRequest, decideApprovalRequest, digestApprovalRequest, expireApprovalRequest,
+  type ApprovalRequest, type AuthorizationPrincipal,
+} from '@empire-builder-kit/runtime/authorization';
+import { createDataLifecycleExportRequest, transitionDataLifecycleExport,
+  type DataLifecycleExportRequestV1 } from '@empire-builder-kit/runtime/data-lifecycle';
+import type { KeyValueChange } from '@empire-builder-kit/runtime/key-value';
+import { compareUtf16 } from '@empire-builder-kit/runtime/deterministic-order';
+import { ${prefix}AuthorizationPolicy } from '../authorization/policy.js';
+import { approvalReference, productRecordReference } from './pseudonymous-reference.js';
+import { canonicalDataRightsNow, DATA_RIGHTS_POLICY_VERSION, dataRightsArtifactReference,
+  dataRightsAuditChange, dataRightsSubjectReference, plusDataRightsHours,
+  requireDirectAdmin, requireDirectHuman, requireExportCleanupAuthority } from './data-rights-shared.js';
+import { loadActiveRecordHolds } from './record-holds.js';
+import { readProductRecord } from './records.js';
+import { dataStore } from './key-value.js';
+import { readExportObject, exportPayloadDigest, putEncryptedExport,
+  runExportObjectCleanupAttempt, type ExportObjectVersion } from './record-export-objects.js';
+export { putEncryptedExport, runExportObjectCleanupAttempt, type ExportObjectCleanupResult,
+  type ExportObjectVersion, type RecordExportObjectStore } from './record-export-objects.js';
+
+const ACTION = '${name}:record-export';
+const COPY = 'primary-database'; // Logical policy location; its physical store is DynamoDB.
+const POLICY = ${prefix}AuthorizationPolicy.version;
+const MAXIMUM_OUTSTANDING = 20;
+const MAXIMUM_REQUESTS_PER_DAY = 5;
+const MAXIMUM_PENDING_REPORTS = 1_000;
+const TENANT = 'application';
+const COLLECTION = 'record-exports';
+interface Command { correlationId: string; now?: string; principal: AuthorizationPrincipal; recordId: string }
+interface Execution extends Command { approvalRequestId: string }
+interface Workflow {
+  kind: 'record-export'; schemaVersion: 1;
+  approval: ApprovalRequest<typeof ACTION>; lifecycle: DataLifecycleExportRequestV1;
+  recordRef: string; subjectRef: string; objectKey: string;
+  cleanupState: 'requested' | 'gathering' | 'ready' | 'deletion-in-progress' | 'failed' | 'completed';
+  uploadStartedAt: string | null; expiresAt: string | null; cleanupDeadlineAt: string | null;
+  recordVersion: number | null; payloadDigest: string | null;
+  artifactRef: string | null; currentVersionId: string | null;
+  versions: ExportObjectVersion[];
+}
+type Loaded = { workflow: Workflow; version: number };
+const exportCommand = (recordId: string) => ({ format: 'application/json', recordRef: productRecordReference(recordId) });
+export function recordExportObjectKey(id: string): string {
+  if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(id))
+    throw new Error('Export object key requires an approval UUID.');
+  return 'confidential-exports/' + id + '/record.json';
+}
+export const recordExportExpiresAt = (now: string) => plusDataRightsHours(canonicalDataRightsNow(now), 21);
+export const recordExportCleanupDeadlineAt = (now: string) => plusDataRightsHours(canonicalDataRightsNow(now), 24);
+export function recordExportSchedule(now: string, persisted: {
+  uploadStartedAt?: string | null; expiresAt?: string | null; cleanupDeadlineAt?: string | null;
+} = {}) {
+  const supplied = [persisted.uploadStartedAt, persisted.expiresAt, persisted.cleanupDeadlineAt].some(value => value != null);
+  if (supplied && [persisted.uploadStartedAt, persisted.expiresAt, persisted.cleanupDeadlineAt].some(value => typeof value !== 'string'))
+    throw new Error('Persisted confidential-export cleanup schedule is incomplete.');
+  const uploadStartedAt = canonicalDataRightsNow(persisted.uploadStartedAt ?? now);
+  const expiresAt = recordExportExpiresAt(uploadStartedAt);
+  const cleanupDeadlineAt = recordExportCleanupDeadlineAt(uploadStartedAt);
+  if (supplied && (persisted.expiresAt !== expiresAt || persisted.cleanupDeadlineAt !== cleanupDeadlineAt))
+    throw new Error('Persisted confidential-export cleanup schedule is inconsistent.');
+  return { uploadStartedAt, expiresAt, cleanupDeadlineAt };
+}
+function workflowChange(workflow: Workflow, version: number): KeyValueChange {
+  // Runtime retry explicitly clears these optional fields with undefined. Project only
+  // those documented omissions; all other non-JSON values still fail native validation.
+  const lifecycle = { ...workflow.lifecycle };
+  if (lifecycle.failurePhase === undefined) delete lifecycle.failurePhase;
+  if (lifecycle.outcomeCode === undefined) delete lifecycle.outcomeCode;
+  return { action: 'put', collection: COLLECTION, id: workflow.approval.id, expectedVersion: version, value: { ...workflow, lifecycle } };
+}
+function audit(input: Omit<Execution, 'recordId'> & { recordId?: string; recordReference?: string }, now: string,
+  purposeCode: string, outcome: 'succeeded' | 'held' | 'rejected' | 'retry-required' = 'succeeded') {
+  return dataRightsAuditChange({ action: 'export', approvalRequestId: input.approvalRequestId,
+    correlationId: input.correlationId, now, outcome, principal: input.principal, purposeCode,
+    ...(input.recordId ? { recordId: input.recordId } : { resourceReference: input.recordReference }),
+    summary: 'A bounded confidential-export workflow transition was committed.' });
+}
+async function commit(changes: KeyValueChange[]) { await dataStore().commit({ tenantId: TENANT, changes }); }
+async function capacity() {
+  const row = await dataStore().get(TENANT, 'export-capacity', 'outstanding');
+  const ids = row ? (row.value as { ids?: unknown } | null)?.ids : [];
+  if (!Array.isArray(ids) || ids.length > MAXIMUM_OUTSTANDING || new Set(ids).size !== ids.length)
+    throw new Error('The bounded confidential-export inventory is invalid.');
+  for (const id of ids) recordExportObjectKey(id);
+  return { ids: ids as string[], version: row?.version ?? 0 };
+}
+function capacityChange(value: Awaited<ReturnType<typeof capacity>>, ids: string[]): KeyValueChange {
+  return { action: 'put', collection: 'export-capacity', id: 'outstanding', expectedVersion: value.version, value: { ids: [...ids].sort() } };
+}
+async function load(id: string): Promise<Loaded> {
+  const objectKey = recordExportObjectKey(id);
+  const row = await dataStore().get(TENANT, COLLECTION, id);
+  const workflow = row?.value as Workflow | undefined;
+  if (!row || !workflow || workflow.kind !== 'record-export' || workflow.schemaVersion !== 1 ||
+      workflow.approval?.id !== id || workflow.approval.action !== ACTION || workflow.approval.slice !== '${name}' ||
+      workflow.approval.schemaVersion !== 1 || workflow.approval.policyVersion !== POLICY ||
+      workflow.approval.resource?.type !== 'record' || workflow.approval.resource.id !== workflow.recordRef ||
+      workflow.objectKey !== objectKey || workflow.subjectRef !== dataRightsSubjectReference(workflow.approval.author.actorId) ||
+      workflow.lifecycle?.kind !== 'data-export' || workflow.lifecycle.version !== 1 ||
+      workflow.lifecycle.requestRef !== approvalReference(id) || workflow.lifecycle.scopeRef !== workflow.recordRef ||
+      workflow.lifecycle.categoryId !== 'product-record' || workflow.lifecycle.policyVersion !== DATA_RIGHTS_POLICY_VERSION ||
+      workflow.lifecycle.approvalRequirement !== 'required' || workflow.lifecycle.sourceCopies?.length !== 1 ||
+      workflow.lifecycle.sourceCopies[0]?.copyId !== COPY || !Array.isArray(workflow.versions) || workflow.versions.length > 100)
+    throw new Error('The exact export workflow was not found or is invalid.');
+  if (!['requested', 'gathering', 'ready', 'deletion-in-progress', 'failed', 'completed'].includes(workflow.cleanupState))
+    throw new Error('The export cleanup state is invalid.');
+  if (workflow.cleanupState !== 'requested' && workflow.cleanupState !== 'completed' &&
+      (typeof workflow.uploadStartedAt !== 'string' || typeof workflow.expiresAt !== 'string' || typeof workflow.cleanupDeadlineAt !== 'string' ||
+       !Number.isSafeInteger(workflow.recordVersion) || workflow.recordVersion! < 1 || !/^[a-f0-9]{64}$/.test(workflow.payloadDigest ?? '')))
+    throw new Error('The prepared export schedule or source binding is invalid.');
+  if (workflow.uploadStartedAt !== null) recordExportSchedule(workflow.uploadStartedAt, workflow);
+  if (workflow.versions.some(value => value.key !== objectKey || typeof value.versionId !== 'string' || !value.versionId || value.versionId.length > 1_024))
+    throw new Error('The export version inventory is invalid.');
+  return { workflow, version: row.version };
+}
+function assertTarget(workflow: Workflow, input: Execution, author = true) {
+  if (workflow.recordRef !== productRecordReference(input.recordId) ||
+      workflow.approval.requestDigest !== digestApprovalRequest({ action: ACTION, command: exportCommand(input.recordId),
+        resource: { id: workflow.recordRef, type: 'record' } }) ||
+      (author && workflow.approval.author.actorId !== input.principal.actor.id))
+    throw new Error('The export workflow was not found.');
+}
+async function ownedRecord(input: Command) {
+  const row = await dataStore().get(TENANT, 'records', input.recordId);
+  if (!row) throw new Error('The export target was not found.');
+  const record = readProductRecord(row.value, input.recordId);
+  if (record.ownerId !== input.principal.actor.id) throw new Error('The export target was not found.');
+  return { record, check: { action: 'check', collection: 'records', id: input.recordId, expectedVersion: row.version } as KeyValueChange };
+}
+const bodyFor = (record: ReturnType<typeof readProductRecord>) => JSON.stringify({ id: record.id, name: record.name, runScope: record.runScope });
+
+export async function requestAuthorizedRecordExport(input: Command) {
+  requireDirectHuman(input.principal);
+  const now = canonicalDataRightsNow(input.now);
+  const record = await ownedRecord(input);
+  const inventory = await capacity();
+  if (inventory.ids.length >= MAXIMUM_OUTSTANDING) throw new Error('Confidential-export capacity is full; complete due cleanup before retrying.');
+  const subjectRef = dataRightsSubjectReference(input.principal.actor.id);
+  const rate = await dataStore().get(TENANT, 'export-rate', subjectRef);
+  const prior = rate ? (rate.value as { requestedAt?: unknown } | null)?.requestedAt : [];
+  if (!Array.isArray(prior) || prior.length > MAXIMUM_REQUESTS_PER_DAY) throw new Error('The export rate inventory is invalid.');
+  const requestedAt = prior.map(value => canonicalDataRightsNow(value)).filter(value => Date.parse(value) > Date.parse(now) - 86_400_000);
+  if (requestedAt.some(value => value > now) || requestedAt.length >= MAXIMUM_REQUESTS_PER_DAY)
+    throw new Error('The subject export request rate limit was reached.');
+  const recordRef = productRecordReference(input.recordId);
+  const approval = createApprovalRequest({ action: ACTION, author: input.principal, command: exportCommand(input.recordId),
+    expiresAt: plusDataRightsHours(now, 1), now, policyVersion: POLICY, resource: { id: recordRef, type: 'record' }, slice: '${name}' });
+  const lifecycle = createDataLifecycleExportRequest({ approvalRequirement: 'required', categoryId: 'product-record', createdAt: now,
+    policyVersion: DATA_RIGHTS_POLICY_VERSION, requestRef: approvalReference(approval.id), scopeRef: recordRef, sourceCopyIds: [COPY] });
+  const workflow: Workflow = { kind: 'record-export', schemaVersion: 1, approval, lifecycle, recordRef, subjectRef,
+    objectKey: recordExportObjectKey(approval.id), cleanupState: 'requested', uploadStartedAt: null, expiresAt: null,
+    cleanupDeadlineAt: null, recordVersion: null, payloadDigest: null, artifactRef: null, currentVersionId: null, versions: [] };
+  await commit([record.check, workflowChange(workflow, 0), capacityChange(inventory, [...inventory.ids, approval.id]),
+    { action: 'put', collection: 'export-rate', id: subjectRef, expectedVersion: rate?.version ?? 0, value: { requestedAt: [...requestedAt, now] } },
+    audit({ ...input, approvalRequestId: approval.id }, now, 'export-request')]);
+  return { approvalRequestId: approval.id, expiresAt: approval.expiresAt, requestDigest: approval.requestDigest, status: 'pending' as const };
+}
+export async function decideRecordExport(input: Execution & {
+  expectedRequestDigest: string; outcome: 'approved' | 'rejected'; reasonReference: string;
+}) {
+  requireDirectAdmin(input.principal);
+  const now = canonicalDataRightsNow(input.now);
+  const { workflow, version } = await load(input.approvalRequestId);
+  assertTarget(workflow, input, false);
+  const result = decideApprovalRequest(workflow.approval, { approver: input.principal, expectedRequestDigest: input.expectedRequestDigest,
+    now, outcome: input.outcome, reasonReference: input.reasonReference, requiredPolicyVersion: POLICY });
+  assertAuthorizationAllowed(result.decision);
+  workflow.approval = result.request;
+  const changes: KeyValueChange[] = [];
+  if (input.outcome === 'rejected') {
+    if (workflow.cleanupState !== 'requested' || workflow.uploadStartedAt !== null) throw new Error('The requested export changed.');
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: now, reasonCode: 'approval-rejected', type: 'reject' });
+    workflow.cleanupState = 'completed';
+    const inventory = await capacity();
+    if (!inventory.ids.includes(input.approvalRequestId)) throw new Error('Export capacity binding is missing.');
+    changes.push(capacityChange(inventory, inventory.ids.filter(id => id !== input.approvalRequestId)));
+  }
+  await commit([...changes, workflowChange(workflow, version), audit(input, now, 'export-decision', input.outcome === 'approved' ? 'succeeded' : 'rejected')]);
+  return { status: result.request.status };
+}
+
+export async function executeApprovedRecordExport(input: Execution): Promise<{ status: 'held' } | { artifactRef: string; expiresAt: string; status: 'ready' }> {
+  requireDirectHuman(input.principal);
+  const now = canonicalDataRightsNow(input.now);
+  let { workflow, version } = await load(input.approvalRequestId);
+  assertTarget(workflow, input);
+  if (workflow.cleanupState === 'ready') {
+    const schedule = recordExportSchedule(now, workflow);
+    if (workflow.approval.status !== 'executed' || workflow.lifecycle.status !== 'ready' ||
+        workflow.lifecycle.artifact?.artifactRef !== workflow.artifactRef || workflow.lifecycle.artifact?.expiresAt !== schedule.expiresAt ||
+        !workflow.artifactRef || !workflow.currentVersionId || Date.parse(schedule.expiresAt) <= Date.parse(now))
+      throw new Error('The export artifact is not ready or has expired.');
+    return { artifactRef: workflow.artifactRef, expiresAt: schedule.expiresAt, status: 'ready' };
+  }
+  const record = await ownedRecord(input);
+  const holds = await loadActiveRecordHolds(input.recordId, now, 'export');
+  const body = bodyFor(record.record);
+  if (workflow.cleanupState === 'requested') {
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { approvalRef: approvalReference(input.approvalRequestId),
+      at: now, authorityRef: dataRightsSubjectReference(input.principal.actor.id), holds: holds.holds, type: 'verify' });
+    if (workflow.lifecycle.status === 'held') {
+      await commit([record.check, holds.check, workflowChange(workflow, version), audit(input, now, 'export-execution', 'held')]);
+      return { status: 'held' };
+    }
+    const begun = beginApprovalExecution(workflow.approval, { action: ACTION, command: exportCommand(input.recordId),
+      executionId: 'export:' + input.approvalRequestId, now, requiredPolicyVersion: POLICY,
+      resource: { id: workflow.recordRef, type: 'record' } });
+    assertAuthorizationAllowed(begun.decision);
+    workflow.approval = begun.request;
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: now, type: 'start-gathering' });
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: now, copyId: COPY, type: 'start-copy' });
+    Object.assign(workflow, recordExportSchedule(now), { cleanupState: 'gathering', recordVersion: record.check.expectedVersion, payloadDigest: exportPayloadDigest(body) });
+    // Durable authority and deadline precede all S3 activity. No plaintext copy is persisted here.
+    await commit([record.check, holds.check, workflowChange(workflow, version)]);
+    ({ workflow, version } = await load(input.approvalRequestId));
+  }
+  if (workflow.cleanupState !== 'gathering' || workflow.lifecycle.status !== 'gathering' || workflow.approval.status !== 'executing' ||
+      workflow.approval.execution?.executionId !== 'export:' + input.approvalRequestId || holds.evaluation.blocked ||
+      workflow.recordVersion !== record.check.expectedVersion || workflow.payloadDigest !== exportPayloadDigest(body))
+    throw new Error('The executing export authority, record or hold changed.');
+  const schedule = recordExportSchedule(now, workflow);
+  if (Date.parse(schedule.expiresAt) <= Date.parse(now)) throw new Error('The confidential export expired before publication.');
+  const versionId = await putEncryptedExport(workflow.objectKey, body);
+  const finishedAt = canonicalDataRightsNow(input.now);
+  if (Date.parse(schedule.expiresAt) <= Date.parse(finishedAt)) throw new Error('The confidential export expired before publication.');
+  const artifactRef = dataRightsArtifactReference(input.approvalRequestId + ':' + versionId);
+  workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: finishedAt, copyId: COPY, outcomeCode: 'gathered', type: 'complete-copy' });
+  workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { artifactRef, at: finishedAt,
+    encryption: 'approved-profile', expiresAt: schedule.expiresAt, type: 'publish' });
+  const completed = completeApprovalExecution(workflow.approval, { executionId: 'export:' + input.approvalRequestId, now: finishedAt, requiredPolicyVersion: POLICY });
+  assertAuthorizationAllowed(completed.decision);
+  Object.assign(workflow, { approval: completed.request, artifactRef, currentVersionId: versionId, cleanupState: 'ready',
+    versions: [{ key: workflow.objectKey, versionId, isDeleteMarker: false }] });
+  // A concurrent hold, owner edit, cleanup or publication wins by CAS. An unaccepted encrypted
+  // object remains covered by the durable gathering row and exact-key cleanup inventory.
+  await commit([record.check, holds.check, workflowChange(workflow, version), audit(input, finishedAt, 'export-execution')]);
+  return { artifactRef, expiresAt: schedule.expiresAt, status: 'ready' };
+}
+
+export async function deliverReadyRecordExport(input: Execution) {
+  requireDirectHuman(input.principal);
+  const now = canonicalDataRightsNow(input.now);
+  const { workflow, version } = await load(input.approvalRequestId);
+  assertTarget(workflow, input);
+  const schedule = recordExportSchedule(now, workflow);
+  if (workflow.cleanupState !== 'ready' || workflow.approval.status !== 'executed' || workflow.lifecycle.status !== 'ready' ||
+      workflow.lifecycle.artifact?.status !== 'available' || workflow.lifecycle.artifact?.artifactRef !== workflow.artifactRef ||
+      workflow.lifecycle.artifact.expiresAt !== schedule.expiresAt || !workflow.currentVersionId || !workflow.artifactRef || !workflow.payloadDigest ||
+      Date.parse(schedule.expiresAt) <= Date.parse(now)) throw new Error('The export artifact is not ready or has expired.');
+  const record = await ownedRecord(input);
+  const holds = await loadActiveRecordHolds(input.recordId, now, 'export');
+  if (holds.evaluation.blocked) throw new Error('An active record hold blocks export delivery.');
+  const delivered = await readExportObject(workflow.objectKey, workflow.currentVersionId, workflow.payloadDigest, input.recordId);
+  const deliveredAt = canonicalDataRightsNow(input.now);
+  if (Date.parse(schedule.expiresAt) <= Date.parse(deliveredAt)) throw new Error('The export artifact has expired.');
+  await commit([record.check, holds.check, { action: 'check', collection: COLLECTION, id: input.approvalRequestId, expectedVersion: version },
+    audit(input, deliveredAt, 'export-download')]);
+  return { artifactRef: workflow.artifactRef, deliveredAt, expiresAt: schedule.expiresAt, record: delivered };
+}
+
+interface DeadlineReport { id: string; deadlineAt: string }
+async function reports() {
+  const row = await dataStore().get(TENANT, 'export-cleanup-reports', 'pending');
+  const pending = row ? (row.value as { pending?: DeadlineReport[] } | null)?.pending : [];
+  if (!Array.isArray(pending) || pending.length > MAXIMUM_PENDING_REPORTS || new Set(pending.map(value => value.id)).size !== pending.length)
+    throw new Error('The export cleanup report inventory is invalid.');
+  for (const report of pending) { recordExportObjectKey(report.id); canonicalDataRightsNow(report.deadlineAt); }
+  return { pending, version: row?.version ?? 0 };
+}
+function reportsChange(current: Awaited<ReturnType<typeof reports>>, pending: DeadlineReport[]): KeyValueChange {
+  return { action: 'put', collection: 'export-cleanup-reports', id: 'pending', expectedVersion: current.version, value: { pending } };
+}
+async function deadlineChange(workflow: Workflow, observedAt: string): Promise<KeyValueChange[]> {
+  if (workflow.uploadStartedAt === null || workflow.lifecycle.status === 'completed') return [];
+  const schedule = recordExportSchedule(observedAt, workflow);
+  if (schedule.cleanupDeadlineAt > observedAt) return [];
+  const current = await reports();
+  const prior = current.pending.find(value => value.id === workflow.approval.id);
+  if (prior && prior.deadlineAt !== schedule.cleanupDeadlineAt) throw new Error('The cleanup deadline report changed.');
+  // Saturated observability must not prevent deletion. The bounded active inventory is
+  // rescanned next time; cleanup itself still reports the observed deadline breach.
+  if (prior || current.pending.length >= MAXIMUM_PENDING_REPORTS) return [];
+  return [reportsChange(current, [...current.pending, { id: workflow.approval.id, deadlineAt: schedule.cleanupDeadlineAt }])];
+}
+export async function reportExportCleanupDeadlineBreaches(input: { correlationId: string; pageSize?: number; report(value: number): boolean }) {
+  const pageSize = input.pageSize ?? 100;
+  if (!Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) throw new Error('Export cleanup report page size must be from 1 through 100.');
+  const current = await reports();
+  const selected = current.pending.slice(0, pageSize);
+  if (!input.report(selected.length)) throw new Error('Confidential export cleanup deadline metric delivery failed.');
+  // Metric failure keeps every report; transaction failure permits at-least-once reporting.
+  if (selected.length) await commit([reportsChange(current, current.pending.slice(selected.length))]);
+  return { continuationRequired: current.pending.length > pageSize, reported: selected.length };
+}
+type CleanupInput = Omit<Execution, 'recordId'> & { recordId?: string; recordReference?: string };
+export async function cleanupExpiredRecordExport(input: CleanupInput): Promise<{ deletedVersions: number; status: 'completed' | 'retry-required' }> {
+  requireExportCleanupAuthority(input.principal);
+  if ((input.recordId === undefined) === (input.recordReference === undefined)) throw new Error('Export cleanup requires exactly one record identifier or reference.');
+  const expected = input.recordReference ?? productRecordReference(input.recordId!);
+  const now = canonicalDataRightsNow(input.now);
+  let { workflow, version } = await load(input.approvalRequestId);
+  if (workflow.recordRef !== expected) throw new Error('The export artifact was not found.');
+  if (workflow.cleanupState === 'completed') return { deletedVersions: 0, status: 'completed' };
+  if (workflow.cleanupState === 'requested') {
+    const expired = expireApprovalRequest(workflow.approval, now);
+    if (expired.status !== 'expired') throw new Error('The export request is not due for cleanup.');
+    workflow.approval = expired;
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: now, reasonCode: 'approval-expired', type: 'reject' });
+    workflow.cleanupState = 'completed';
+    const inventory = await capacity();
+    if (!inventory.ids.includes(input.approvalRequestId)) throw new Error('Export capacity binding is missing.');
+    await commit([workflowChange(workflow, version), capacityChange(inventory, inventory.ids.filter(id => id !== input.approvalRequestId)), audit(input, now, 'export-expiry')]);
+    return { deletedVersions: 0, status: 'completed' };
+  }
+  const schedule = recordExportSchedule(now, workflow);
+  if (schedule.expiresAt > now) throw new Error('The export artifact is not due for cleanup.');
+  const deadline = await deadlineChange(workflow, now);
+  if (workflow.lifecycle.status === 'ready') {
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: now, type: 'expire' });
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: now, type: 'start-artifact-deletion' });
+  } else if (workflow.lifecycle.status === 'gathering') {
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: now, type: 'start-unpublished-artifact-deletion' });
+  } else if (workflow.lifecycle.status === 'failed') {
+    workflow.lifecycle = transitionDataLifecycleExport(workflow.lifecycle, { at: now, type: 'retry' });
+  }
+  if (!['artifact-deletion-in-progress', 'unpublished-artifact-deletion-in-progress'].includes(workflow.lifecycle.status))
+    throw new Error('The export cleanup attempt changed.');
+  workflow.cleanupState = 'deletion-in-progress';
+  await commit([workflowChange(workflow, version), ...deadline]);
+  ({ workflow, version } = await load(input.approvalRequestId));
+  return runExportObjectCleanupAttempt({ objectKey: workflow.objectKey, trackedVersions: workflow.versions,
+    async recordDiscovered(discovered) {
+      const next = await load(input.approvalRequestId);
+      if (next.workflow.cleanupState !== 'deletion-in-progress') throw new Error('The export cleanup attempt changed.');
+      const merged = new Map([...next.workflow.versions, ...discovered].map(value => [value.versionId, value]));
+      if (merged.size > 100) throw new Error('The exact export version inventory exceeded its bound.');
+      next.workflow.versions = [...merged.values()];
+      await commit([workflowChange(next.workflow, next.version)]);
+    },
+    async finalize({ attemptedVersions, failedVersionIds }) {
+      const next = await load(input.approvalRequestId);
+      if (next.workflow.cleanupState === 'completed') return { deletedVersions: 0, status: 'completed' as const };
+      if (next.workflow.cleanupState !== 'deletion-in-progress') throw new Error('The export cleanup attempt changed.');
+      // The scan's input.now is a selection snapshot, not the completion clock.
+      const finishedAt = canonicalDataRightsNow();
+      const pending = await deadlineChange(next.workflow, finishedAt);
+      const failed = new Set(failedVersionIds);
+      const unpublished = next.workflow.lifecycle.artifact === undefined;
+      next.workflow.lifecycle = transitionDataLifecycleExport(next.workflow.lifecycle, failed.size
+        ? { at: finishedAt, errorCode: 'object-version-delete-failed', type: 'fail-artifact-deletion' }
+        : { at: finishedAt, outcomeCode: attemptedVersions.length ? 'deleted' : 'not-found', type: 'complete-artifact-deletion' });
+      if (!failed.size && unpublished) {
+        const completed = completeApprovalExecution(next.workflow.approval, { executionId: 'export:' + input.approvalRequestId, now: finishedAt, requiredPolicyVersion: POLICY });
+        assertAuthorizationAllowed(completed.decision); next.workflow.approval = completed.request;
+      }
+      next.workflow.cleanupState = failed.size ? 'failed' : 'completed';
+      next.workflow.versions = attemptedVersions.filter(value => failed.has(value.versionId));
+      const changes: KeyValueChange[] = [...pending];
+      if (!failed.size) {
+        const inventory = await capacity();
+        if (!inventory.ids.includes(input.approvalRequestId)) throw new Error('Export capacity binding is missing.');
+        changes.push(capacityChange(inventory, inventory.ids.filter(id => id !== input.approvalRequestId)));
+      }
+      await commit([...changes, workflowChange(next.workflow, next.version), audit(input, finishedAt, 'export-expiry', failed.size ? 'retry-required' : 'succeeded')]);
+      return { deletedVersions: attemptedVersions.length - failed.size, status: failed.size ? 'retry-required' as const : 'completed' as const };
+    },
+  });
+}
+
+export async function cleanupDueRecordExports(input: { correlationId: string; limit?: number; maximumBatches?: number;
+  now?: string; principal: AuthorizationPrincipal; shouldContinue?: () => boolean;
+}, dependencies: { cleanupExpiredRecordExport?: typeof cleanupExpiredRecordExport } = {}) {
+  requireExportCleanupAuthority(input.principal);
+  const now = canonicalDataRightsNow(input.now);
+  const limit = input.limit ?? 25;
+  const maximumBatches = input.maximumBatches ?? 100;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(maximumBatches) || maximumBatches < 1 || maximumBatches > 100)
+    throw new Error('Export cleanup batch size and count must be from 1 through 100.');
+  const inventory = await capacity();
+  const active = await Promise.all(inventory.ids.map(load));
+  const due = (workflow: Workflow) => workflow.cleanupState === 'requested' ? workflow.approval.expiresAt <= now : workflow.expiresAt !== null && workflow.expiresAt <= now;
+  let deadlineBreached = false;
+  for (const { workflow } of active) {
+    if (workflow.cleanupState === 'completed') throw new Error('Completed export remains in the active inventory.');
+    const changes = await deadlineChange(workflow, now);
+    if (changes.length) await commit(changes);
+    if (workflow.cleanupDeadlineAt !== null && workflow.cleanupDeadlineAt <= now) deadlineBreached = true;
+  }
+  const candidates = active.filter(({ workflow }) => due(workflow)).sort((a, b) =>
+    compareUtf16(a.workflow.expiresAt ?? a.workflow.approval.expiresAt, b.workflow.expiresAt ?? b.workflow.approval.expiresAt) || compareUtf16(a.workflow.approval.id, b.workflow.approval.id));
+  let processed = 0; let completed = 0; let retryRequired = 0; let batches = 0;
+  for (let offset = 0; offset < candidates.length && batches < maximumBatches && (input.shouldContinue?.() ?? true); offset += limit) {
+    batches += 1;
+    for (const { workflow } of candidates.slice(offset, offset + limit)) {
+      processed += 1;
+      try {
+        const result = await (dependencies.cleanupExpiredRecordExport ?? cleanupExpiredRecordExport)({
+          approvalRequestId: workflow.approval.id, correlationId: input.correlationId, now, principal: input.principal, recordReference: workflow.recordRef });
+        if (result.status === 'completed') completed += 1; else retryRequired += 1;
+      } catch { retryRequired += 1; }
+    }
+  }
+  const remaining = await Promise.all((await capacity()).ids.map(load));
+  const remainingDue = remaining.filter(({ workflow }) => due(workflow)).length;
+  const remainingDeadlineBreaches = remaining.filter(({ workflow }) => workflow.cleanupDeadlineAt !== null && workflow.cleanupDeadlineAt <= now).length;
+  const pendingReports = await reports();
+  return { batches, completed, continuationRequired: retryRequired > 0 || remainingDue > 0,
+    deadlineBreached: deadlineBreached || remainingDeadlineBreaches > 0 || pendingReports.pending.length > 0, processed, remainingDeadlineBreaches, remainingDue, retryRequired };
+}
+`,
+        'data/record-export-objects.ts': renderObjects(),
+        'testing/data-rights-workflows.spec.ts': `import { describe, expect, it } from 'vitest';
+import { createApprovalRequest, decideApprovalRequest, type AuthorizationPrincipal } from '@empire-builder-kit/runtime/authorization';
+import { recordExportSchedule, recordExportObjectKey, runExportObjectCleanupAttempt, type RecordExportObjectStore } from '../data/record-export.js';
+import { createRecordHold } from '../data/record-holds.js';
+const owner: AuthorizationPrincipal = { kind: 'customer', actor: { type: 'user', id: 'owner-one' },
+  subject: { type: 'user', id: 'owner-one' }, authority: { mode: 'direct' }, roles: [], scopes: [] };
+const now = '2026-09-12T12:00:00.000Z';
+describe('native data rights', () => {
+  it('retains an exact upload-relative expiry and deadline on retry', () => {
+    const first = recordExportSchedule(now);
+    expect(first).toEqual({ uploadStartedAt: now, expiresAt: '2026-09-13T09:00:00.000Z', cleanupDeadlineAt: '2026-09-13T12:00:00.000Z' });
+    expect(recordExportSchedule('2026-09-12T13:00:00.000Z', first)).toEqual(first);
+    expect(() => recordExportSchedule(now, { uploadStartedAt: now })).toThrow('incomplete');
+    expect(() => recordExportSchedule(now, { ...first, expiresAt: now })).toThrow('inconsistent');
+  });
+  it('requires independent direct-human review', () => {
+    const request = createApprovalRequest({ action: '${name}:record-export', author: owner, command: { recordRef: 'record-ref' },
+      resource: { id: 'record-ref', type: 'record' }, policyVersion: '1.0.0', slice: '${name}', now, expiresAt: '2026-09-12T13:00:00.000Z' });
+    expect(decideApprovalRequest(request, { approver: { ...owner, kind: 'admin' }, expectedRequestDigest: request.requestDigest,
+      now, outcome: 'approved', reasonReference: 'review-1', requiredPolicyVersion: '1.0.0' }).decision.decision).toBe('deny');
+    expect(() => createRecordHold({ effects: ['block-export'], expiresAt: '2026-09-14T12:00:00.000Z', principal: owner,
+      purpose: 'legal', recordId: 'record-1', reviewAt: '2026-09-13T12:00:00.000Z' }, now)).toThrow('direct admin');
+  });
+  it('rejects review under a newer policy before granting export authority', () => {
+    const request = createApprovalRequest({ action: '${name}:record-export', author: owner, command: { recordRef: 'record-ref' },
+      resource: { id: 'record-ref', type: 'record' }, policyVersion: '1.0.0', slice: '${name}', now, expiresAt: '2026-09-12T13:00:00.000Z' });
+    const approver: AuthorizationPrincipal = { ...owner, kind: 'admin',
+      actor: { type: 'user', id: 'reviewer-two' }, subject: { type: 'user', id: 'reviewer-two' } };
+    expect(decideApprovalRequest(request, { approver, expectedRequestDigest: request.requestDigest,
+      now, outcome: 'approved', reasonReference: 'review-2', requiredPolicyVersion: '2.0.0' }).decision)
+      .toMatchObject({ decision: 'deny', category: 'policy-stale' });
+  });
+  it('persists exact version inventory before deletion and refuses to erase ambiguous errors', async () => {
+    const objectKey = recordExportObjectKey('00000000-0000-4000-8000-000000000001');
+    const seen: string[] = [];
+    let listing = 0;
+    const objectStore: RecordExportObjectStore = { async send(command) {
+      const value = command as { constructor: { name: string }; input: { Delete?: { Objects: unknown[] } } };
+      seen.push(value.constructor.name);
+      if (value.constructor.name === 'ListObjectVersionsCommand') return ++listing === 1
+        ? { Versions: [{ Key: objectKey, VersionId: 'version-1' }] } : {};
+      expect(value.constructor.name).toBe('DeleteObjectsCommand');
+      expect(seen).toContain('inventory-persisted');
+      expect(value.input.Delete?.Objects).toEqual([{ Key: objectKey, VersionId: 'version-1' }]);
+      return { Errors: [{ Key: objectKey }] };
+    } };
+    const priorBucket = process.env.DATA_EXPORT_BUCKET_NAME;
+    const priorKey = process.env.DATA_EXPORT_KMS_KEY_ARN;
+    process.env.DATA_EXPORT_BUCKET_NAME = 'test-exports';
+    process.env.DATA_EXPORT_KMS_KEY_ARN = 'arn:aws:kms:us-east-1:111111111111:key/test';
+    try {
+      const result = await runExportObjectCleanupAttempt({ objectKey, objectStore, trackedVersions: [],
+        recordDiscovered: async () => { seen.push('inventory-persisted'); }, finalize: async value => value });
+      expect(result.failedVersionIds).toEqual(['version-1']);
+      expect(result.remainingVersions).toEqual([]);
+    } finally {
+      if (priorBucket === undefined) delete process.env.DATA_EXPORT_BUCKET_NAME; else process.env.DATA_EXPORT_BUCKET_NAME = priorBucket;
+      if (priorKey === undefined) delete process.env.DATA_EXPORT_KMS_KEY_ARN; else process.env.DATA_EXPORT_KMS_KEY_ARN = priorKey;
+    }
+  });
+});
+`,
+    };
+}
+function renderObjects() {
+    return `import { createHash } from 'node:crypto';
+import { S3Client, PutObjectCommand, HeadObjectCommand, GetObjectCommand, ListObjectVersionsCommand, DeleteObjectsCommand } from '@aws-sdk/client-s3';
+const s3 = new S3Client({ maxAttempts: 3, requestHandler: { connectionTimeout: 5_000, requestTimeout: 30_000 } });
+export interface RecordExportObjectStore { send(command: unknown): Promise<unknown> }
+const defaultStore: RecordExportObjectStore = { send: command => s3.send(command as never) };
+export const exportPayloadDigest = (body: string) => createHash('sha256').update(body).digest('hex');
+function resources() {
+  const bucketName = process.env.DATA_EXPORT_BUCKET_NAME;
+  const kmsKeyArn = process.env.DATA_EXPORT_KMS_KEY_ARN;
+  if (!bucketName || !kmsKeyArn?.startsWith('arn:aws:kms:')) throw new Error('Confidential-export encryption resources are unavailable.');
+  return { bucketName, kmsKeyArn };
+}
+function exactKey(key: string) {
+  if (!/^confidential-exports[/][a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}[/]record[.]json$/i.test(key))
+    throw new Error('An exact confidential-export object key is required.');
+}
+export async function putEncryptedExport(objectKey: string, body: string, objectStore: RecordExportObjectStore = defaultStore): Promise<string> {
+  exactKey(objectKey);
+  if (Buffer.byteLength(body) > 64 * 1_024) throw new Error('The confidential export exceeds its size bound.');
+  const { bucketName, kmsKeyArn } = resources();
+  const digest = exportPayloadDigest(body);
+  try {
+    const result = await objectStore.send(new PutObjectCommand({ Bucket: bucketName, Key: objectKey, Body: body,
+      BucketKeyEnabled: true, ContentType: 'application/json', IfNoneMatch: '*', ServerSideEncryption: 'aws:kms',
+      SSEKMSKeyId: kmsKeyArn, Metadata: { 'ebk-content-sha256': digest } })) as { VersionId?: string };
+    if (!result.VersionId) throw new Error('Versioned export put returned no version identifier.');
+    return result.VersionId;
+  } catch (error) {
+    if ((error as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode !== 412) throw error;
+    const existing = await objectStore.send(new HeadObjectCommand({ Bucket: bucketName, Key: objectKey })) as {
+      VersionId?: string; ServerSideEncryption?: string; SSEKMSKeyId?: string; Metadata?: Record<string, string> };
+    if (!existing.VersionId || existing.ServerSideEncryption !== 'aws:kms' || existing.SSEKMSKeyId !== kmsKeyArn || existing.Metadata?.['ebk-content-sha256'] !== digest)
+      throw new Error('Existing export object failed encryption or content validation.');
+    return existing.VersionId;
+  }
+}
+export async function readExportObject(objectKey: string, versionId: string, expectedDigest: string, recordId: string) {
+  exactKey(objectKey);
+  const { bucketName, kmsKeyArn } = resources();
+  const object = await s3.send(new GetObjectCommand({ Bucket: bucketName, Key: objectKey, VersionId: versionId }));
+  if (object.ContentLength === undefined || object.ContentLength > 64 * 1_024 || object.ContentType !== 'application/json' ||
+      !object.Body || object.VersionId !== versionId || object.ServerSideEncryption !== 'aws:kms' || object.SSEKMSKeyId !== kmsKeyArn)
+    throw new Error('The confidential export artifact is invalid.');
+  const body = await object.Body.transformToString();
+  if (Buffer.byteLength(body) > 64 * 1_024 || exportPayloadDigest(body) !== expectedDigest) throw new Error('The confidential export content changed.');
+  const value = JSON.parse(body) as { id?: unknown; name?: unknown; runScope?: unknown };
+  if (value.id !== recordId || typeof value.name !== 'string' || value.name.length < 1 || value.name.length > 256 ||
+      typeof value.runScope !== 'string' || value.runScope.length < 1 || value.runScope.length > 128)
+    throw new Error('The confidential export artifact is invalid.');
+  return { id: recordId, name: value.name, runScope: value.runScope };
+}
+export interface ExportObjectVersion { isDeleteMarker: boolean; key: string; versionId: string }
+async function list(key: string, store: RecordExportObjectStore) {
+  exactKey(key);
+  const versions = new Map<string, ExportObjectVersion>();
+  const seen = new Set<string>();
+  let keyMarker: string | undefined; let versionMarker: string | undefined;
+  for (let pageNumber = 0; pageNumber < 100; pageNumber += 1) {
+    const page = await store.send(new ListObjectVersionsCommand({ Bucket: resources().bucketName, Prefix: key,
+      KeyMarker: keyMarker, VersionIdMarker: versionMarker, MaxKeys: 100 })) as {
+        Versions?: Array<{ Key?: string; VersionId?: string }>; DeleteMarkers?: Array<{ Key?: string; VersionId?: string }>;
+        IsTruncated?: boolean; NextKeyMarker?: string; NextVersionIdMarker?: string };
+    for (const [isDeleteMarker, values] of [[false, page.Versions ?? []], [true, page.DeleteMarkers ?? []]] as const) {
+      for (const value of values) {
+        if (value.Key !== key) continue;
+        if (!value.VersionId || value.VersionId.length > 1_024) throw new Error('The exact export version is invalid.');
+        versions.set(value.VersionId, { key, versionId: value.VersionId, isDeleteMarker });
+      }
+    }
+    if (versions.size > 100) throw new Error('The exact export version inventory exceeded its bound.');
+    if (!page.IsTruncated) return [...versions.values()];
+    keyMarker = page.NextKeyMarker; versionMarker = page.NextVersionIdMarker;
+    const cursor = JSON.stringify([keyMarker, versionMarker]);
+    if (!keyMarker || !versionMarker || seen.has(cursor)) throw new Error('The exact export version listing did not advance.');
+    seen.add(cursor);
+  }
+  throw new Error('The exact export version listing exceeded its page bound.');
+}
+export interface ExportObjectCleanupResult { attemptedVersions: ExportObjectVersion[]; failedVersionIds: string[]; remainingVersions: ExportObjectVersion[] }
+export async function runExportObjectCleanupAttempt<Result>(input: {
+  objectKey: string; trackedVersions: readonly ExportObjectVersion[]; objectStore?: RecordExportObjectStore;
+  recordDiscovered(versions: readonly ExportObjectVersion[]): Promise<void>; finalize(result: ExportObjectCleanupResult): Promise<Result>;
+}): Promise<Result> {
+  exactKey(input.objectKey);
+  if (input.trackedVersions.length > 100 || input.trackedVersions.some(value => value.key !== input.objectKey || !value.versionId || value.versionId.length > 1_024))
+    throw new Error('The tracked export version inventory is invalid.');
+  const store = input.objectStore ?? defaultStore;
+  const discovered = await list(input.objectKey, store);
+  await input.recordDiscovered(discovered);
+  const attempted = new Map([...input.trackedVersions, ...discovered].map(value => [value.versionId, value]));
+  if (attempted.size > 100) throw new Error('The exact export version inventory exceeded its bound.');
+  const failed = new Set<string>();
+  if (attempted.size) {
+    const result = await store.send(new DeleteObjectsCommand({ Bucket: resources().bucketName,
+      Delete: { Objects: [...attempted.values()].map(value => ({ Key: value.key, VersionId: value.versionId })), Quiet: true } })) as {
+        Errors?: Array<{ Key?: string; VersionId?: string }> };
+    for (const error of result.Errors ?? []) {
+      if (error.VersionId && attempted.has(error.VersionId) && (error.Key === undefined || error.Key === input.objectKey)) failed.add(error.VersionId);
+      else for (const id of attempted.keys()) failed.add(id);
+    }
+  }
+  const remaining = await list(input.objectKey, store);
+  await input.recordDiscovered(remaining);
+  for (const value of remaining) { failed.add(value.versionId); attempted.set(value.versionId, value); }
+  return input.finalize({ attemptedVersions: [...attempted.values()], failedVersionIds: [...failed].sort(), remainingVersions: remaining });
+}
+`;
+}
+//# sourceMappingURL=built-in-plan-key-value-export.js.map

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

@@ -0,0 +1,2 @@
+/** Native DynamoDB integration; this is not a SQL compatibility adapter. */
+export declare function renderKeyValueRuntimeFiles(name: string): Readonly<Record<string, string>>;

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

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueRuntimeFiles = renderKeyValueRuntimeFiles;
+const built_in_plan_key_value_delivery_js_1 = require("./built-in-plan-key-value-delivery.js");
+/** Native DynamoDB integration; this is not a SQL compatibility adapter. */
+function renderKeyValueRuntimeFiles(name) {
+    return {
+        'async/key-value-delivery.ts': (0, built_in_plan_key_value_delivery_js_1.renderKeyValueDeliverySource)(name),
+        'data/key-value.ts': `import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { createDynamoPersistence } from '@empire-builder-kit/runtime/key-value';
+
+function required(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(name + ' is required for this Slice/task data store.');
+  return value;
+}
+
+let store: ReturnType<typeof createDynamoPersistence> | undefined;
+export function dataStore() {
+  return store ??= createDynamoPersistence({
+    client: new DynamoDBClient({}),
+    tableName: required('EBK_KEY_VALUE_TABLE'),
+    stage: required('EBK_STAGE'),
+    slice: '${name}',
+    eventBusName: required('EVENT_BUS_NAME'),
+  });
+}
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-key-value-files.js.map

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

@@ -0,0 +1,2 @@
+/** Native data-rights holds. The versioned per-record set closes absent-hold races. */
+export declare function renderKeyValueHoldFiles(name: string, pascalName: string): Readonly<Record<string, string>>;