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

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

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueRetentionInfrastructureFiles = renderKeyValueRetentionInfrastructureFiles;
+/** Framework retention uses native DynamoDB regardless of optional feature SQL. */
+function renderKeyValueRetentionInfrastructureFiles(name, pascalName) {
+    return {
+        'infra/key-value-retention.ts': `export function createKeyValueRetentionInfrastructure(input: {
+  keyValue: { environment: Record<string, any>; dataPermissions: any[] };
+  workspace: string;
+  eventBusArn: any;
+  alertTopicArn: any;
+  schedule: { scheduleExpression: string; state: 'ENABLED' | 'DISABLED' };
+  scheduleName: string;
+  managedLogGroup(logicalName: string, component: string, alertTopicArn: any): any;
+  lambdaLogging(logGroupName: any): any;
+  register(stateMachineArn: any): any;
+}) {
+  // Personal hot fleets do not create protected retention orchestration.
+  // They still exercise the native data/approval APIs.
+  if ($dev) return {};
+  const environment = { ...input.keyValue.environment, EBK_WORKSPACE: input.workspace,
+    EBK_WORKLOAD_IDENTITY: '${name}:data-retention-job' };
+  const workerLogs = input.managedLogGroup('${pascalName}DataRetentionWorkerLogs', 'job-data-retention', input.alertTopicArn);
+  const maintenanceLogs = input.managedLogGroup('${pascalName}DataRetentionMaintenanceLogs', 'job-data-retention-maintenance', input.alertTopicArn);
+  const workflowLogs = input.managedLogGroup('${pascalName}DataRetentionWorkflowLogs', 'job-data-retention-orchestration', input.alertTopicArn);
+  const worker = new sst.aws.Function('${pascalName}DataRetentionWorker', {
+    handler: 'jobs/data-retention/src/run.handler', dev: false, timeout: '5 minutes',
+    environment, permissions: [...input.keyValue.dataPermissions,
+      { actions: ['events:PutEvents'], resources: [input.eventBusArn] }],
+    ...input.lambdaLogging(workerLogs.logGroup.name),
+  });
+  const maintenance = new sst.aws.Function('${pascalName}DataRetentionMaintenance', {
+    handler: 'jobs/data-retention/src/maintenance.handler', dev: false, timeout: '5 minutes',
+    environment, permissions: input.keyValue.dataPermissions,
+    // Conditional record/run/checkpoint transactions coordinate overlap. Do
+    // not require spare account-level reserved concurrency on a fresh account.
+    ...input.lambdaLogging(maintenanceLogs.logGroup.name),
+  });
+  const partition = aws.getPartitionOutput({}).partition;
+  const account = aws.getCallerIdentityOutput({}).accountId;
+  const region = aws.getRegionOutput({}).name;
+  const workflowName = '${name}-' + $app.stage + '-data-retention';
+  const workflowArn = $interpolate\`arn:\${partition}:states:\${region}:\${account}:stateMachine:\${workflowName}\`;
+  // The normal Slice-level IAM transform supplies the mandatory stage path and
+  // boundary. This runtime role invokes only this handler, not arbitrary Lambdas.
+  const role = new aws.iam.Role('${pascalName}DataRetentionRole', {
+    assumeRolePolicy: $jsonStringify({ Version: '2012-10-17', Statement: [{ Effect: 'Allow',
+      Principal: { Service: 'states.amazonaws.com' }, Action: 'sts:AssumeRole',
+      Condition: { StringEquals: { 'aws:SourceAccount': account }, ArnEquals: { 'aws:SourceArn': workflowArn } } }] }),
+    inlinePolicies: [{ name: 'runtime', policy: $jsonStringify({ Version: '2012-10-17', Statement: [
+      { Effect: 'Allow', Action: ['lambda:InvokeFunction'], Resource: [worker.arn] },
+      // CloudWatch's log-delivery control APIs do not support resource scoping.
+      { Effect: 'Allow', Action: ['logs:CreateLogDelivery', 'logs:GetLogDelivery', 'logs:UpdateLogDelivery',
+        'logs:DeleteLogDelivery', 'logs:ListLogDeliveries', 'logs:PutResourcePolicy', 'logs:DescribeResourcePolicies', 'logs:DescribeLogGroups'], Resource: '*' },
+    ] }) }],
+  });
+  const stateMachine = new aws.sfn.StateMachine('${pascalName}DataRetention', {
+    name: workflowName, type: 'STANDARD', roleArn: role.arn,
+    loggingConfiguration: { includeExecutionData: false, level: 'ERROR', logDestination: $interpolate\`\${workflowLogs.logGroup.arn}:*\` },
+    definition: $jsonStringify({ StartAt: 'Initialize', TimeoutSeconds: 2700, States: {
+      Initialize: { Type: 'Pass', Parameters: { 'command.$': '$', attempt: 1 }, Next: 'RunDataRetention' },
+      RunDataRetention: { Type: 'Task', Resource: worker.arn, InputPath: '$.command', ResultPath: '$.page', TimeoutSeconds: 250,
+        Retry: [{ ErrorEquals: ['Lambda.ServiceException', 'Lambda.AWSLambdaException', 'Lambda.SdkClientException', 'Lambda.TooManyRequestsException'],
+          IntervalSeconds: 2, BackoffRate: 2, MaxAttempts: 2 }], Next: 'CheckCompletion' },
+      CheckCompletion: { Type: 'Choice', Choices: [
+        { And: [{ Variable: '$.page.complete', BooleanEquals: true },
+          { Variable: '$.page.evidence.kind', StringEquals: 'data-lifecycle-evidence' },
+          { Variable: '$.page.evidence.outcome', StringEquals: 'succeeded' }], Next: 'DataRetentionSucceeded' },
+        { And: [{ Variable: '$.page.complete', BooleanEquals: false },
+          { Variable: '$.page.checkpointComplete', BooleanEquals: false },
+          { Variable: '$.attempt', NumericLessThan: 100 }], Next: 'NextPage' },
+      ], Default: 'DataRetentionFailed' },
+      NextPage: { Type: 'Pass', Parameters: { 'command.$': '$.command', 'attempt.$': 'States.MathAdd($.attempt, 1)' }, Next: 'RunDataRetention' },
+      DataRetentionSucceeded: { Type: 'Succeed', OutputPath: '$.page' },
+      DataRetentionFailed: { Type: 'Fail', Error: 'IncompleteRetention', Cause: 'Native retention did not return bounded completed evidence; inspect the retained run.' },
+    } }),
+  });
+  const registration = input.register(stateMachine.arn);
+  const failureAlarm = new aws.cloudwatch.MetricAlarm('${pascalName}DataRetentionFailure', {
+    name: '${name}-' + $app.stage + '-retention-job-failure', alarmActions: [input.alertTopicArn],
+    alarmDescription: JSON.stringify({ schemaVersion: 1, slice: '${name}', owner: '${name}-product', route: '${name}-on-call',
+      businessSymptom: 'The native retention Job terminated unsuccessfully.', id: 'retention-job-failure', runbook: 'jobs/data-retention/README.md' }),
+    comparisonOperator: 'GreaterThanOrEqualToThreshold', evaluationPeriods: 1, threshold: 1, treatMissingData: 'notBreaching',
+    metricQueries: [...['ExecutionsFailed', 'ExecutionsTimedOut', 'ExecutionsAborted'].map((metricName, index) => ({
+      id: 'm' + index, metric: { dimensions: { StateMachineArn: stateMachine.arn }, metricName, namespace: 'AWS/States', period: 60, stat: 'Sum' }, returnData: false })),
+      { expression: 'm0+m1+m2', id: 'failures', label: 'Retention terminal execution failures', returnData: true }],
+  });
+  const rule = new aws.cloudwatch.EventRule('${pascalName}DataRetentionMaintenanceSchedule', {
+    name: input.scheduleName, ...input.schedule,
+  });
+  const permission = new aws.lambda.Permission('${pascalName}DataRetentionMaintenanceSchedulePermission', {
+    action: 'lambda:InvokeFunction', function: maintenance.arn, principal: 'events.amazonaws.com', sourceArn: rule.arn,
+  });
+  const target = new aws.cloudwatch.EventTarget('${pascalName}DataRetentionMaintenanceTarget', {
+    arn: maintenance.arn, rule: rule.name, targetId: 'DataRetentionMaintenance',
+  }, { dependsOn: [permission] });
+  return { dataRetention: { worker, workerLogs, workflowLogs, role, stateMachine, registration, failureAlarm },
+    dataRetentionMaintenance: { maintenance, maintenanceLogs, rule, permission, target } };
+}
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-key-value-retention-infrastructure.js.map

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

@@ -0,0 +1,2 @@
+/** Native DynamoDB retention packaging, independent of feature-owned optional SQL. */
+export declare function renderKeyValueRetentionJobFiles(name: string, runtimeVersion: string): Readonly<Record<string, string>>;

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

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueRetentionJobFiles = renderKeyValueRetentionJobFiles;
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+/** Native DynamoDB retention packaging, independent of feature-owned optional SQL. */
+function renderKeyValueRetentionJobFiles(name, runtimeVersion) {
+    return {
+        'jobs/data-retention/package.json': (0, built_in_plan_shared_js_1.json)({
+            name: `@${name}/job-data-retention`,
+            private: true,
+            type: 'module',
+            version: '0.0.0',
+            scripts: {
+                build: 'tsc -p tsconfig.build.json',
+                lint: 'eslint .',
+                test: 'vitest run',
+                typecheck: 'tsc --noEmit -p tsconfig.json',
+                verify: 'pnpm run lint && pnpm run typecheck && pnpm test && pnpm run build',
+            },
+            dependencies: {
+                '@aws-sdk/client-dynamodb': built_in_plan_shared_js_1.PRODUCT_VERSIONS.awsDynamoDb,
+                '@aws-sdk/client-eventbridge': built_in_plan_shared_js_1.PRODUCT_VERSIONS.awsEventBridge,
+                '@empire-builder-kit/runtime': runtimeVersion,
+            },
+            devDependencies: {
+                '@types/node': built_in_plan_shared_js_1.PRODUCT_VERSIONS.typesNode,
+                typescript: '~5.9.2',
+                vitest: built_in_plan_shared_js_1.PRODUCT_VERSIONS.vitest,
+            },
+        }),
+        'jobs/data-retention/README.md': `# Data retention Job
+
+The Slice's data-retention target starts its registered Step Functions workflow.
+SST packages the native Lambda handlers from this source; no SQL connection,
+container image, Fargate task or VPC is required for DynamoDB-default retention.
+Adding relational storage does not move these existing records into SQL.
+
+Run \`pnpm nx run ${name}:data-retention -- --report --stage=development\`
+from the workspace. The launcher records the caller checkout's HEAD by default;
+an explicitly supplied EBK_SOURCE_COMMIT must be a full commit SHA. This is
+caller provenance, not proof of deployed code or permission to apply retention.
+The deployed worker still requires its exact workload identity and approved run.
+
+Report reads at most 1,000 records per invocation in consistent pages of 50.
+It checkpoints progress across larger tables, freezes at most 10,000 selected
+deletion candidates per report and returns a bounded run reference. Healthy
+records do not consume that candidate limit. Each workflow execution remains
+bounded to 100 worker attempts and 45 minutes. To continue an interrupted or
+budget-exhausted report, use
+\`pnpm nx run ${name}:data-retention -- --report --stage=development --run-ref=<run-uuid>\`
+from the same source commit. The worker reloads the original selection time,
+correlation and policy binding; the new invocation cannot expand the selection.
+Failures print the original \`EBK_SOURCE_COMMIT=<commit>\` command binding.
+Keep that checkout and its artifacts; setting this variable is not permission
+to substitute different deployed code. Report replay is refused after review
+or execution begins, so a report cannot overwrite retained apply evidence.
+Missing, expired or changed checkpoints are refused, not restarted. Only a
+completed report can be reviewed. A later report
+handles any remaining due records after the approved batch is applied.
+Reporting never deletes domain data.
+The authenticated API requests review; apply requires a different direct human's
+approval of that exact report. Each apply invocation handles at most 100 records.
+The workflow continues from the persisted checkpoint until complete=true; only
+that final result is accepted evidence. Failure preserves the same run for
+governed retry. Changed candidates require a new report and approval.
+
+The seeded adapter owns record selection. Keep it aligned with data/policy.json.
+Never log raw identifiers, record content or credentials. Native deletion checks
+holds and atomically commits the record change, audit, ledger and event intent.
+Delivery is at least once; downstream inboxes deduplicate events.
+An active delivery lease returns a pending checkpoint without completed apply
+evidence. The same approved run continues after acknowledgement or lease expiry.
+Workflow event intents retain their publication acknowledgement without TTL
+until the matching completion receipt commits. That transaction starts the
+ordinary seven-day delivered-intent TTL; an interrupted completion or a long
+maintenance pause cannot discard its delivery proof. A deletion ledger alone
+does not prove publication.
+
+Control maintenance is independent of domain retention: its scheduled Lambda
+checks the exact ${name}:retention-maintenance authority, active control holds,
+400-day control retention and bounded resumable work.
+Control-hold inspection checkpoints up to 1,000 entries per invocation; pruning
+does not begin until that inspection completes. Each pruning pass handles at
+most another 1,000 control records within the same time budget. Old export-rate
+metadata is removed only after every request is outside the 400-day control
+retention window, using an exact version check so concurrent requests survive.
+Pending deletion completion has its own transactional work records, not a scan
+of historical approvals. Its stored authorization can finish an already-committed
+deletion after a policy update; starting a deletion still requires current policy.
+Completion failures retain content-free failure markers and fail the worker;
+inspect those pending records and retry reconciliation, never erase them as
+ordinary historical metadata.
+Explicit pauses/cadence in operations/background-work.json survive generation. Database capacity does not
+silently enable or disable this work. Incomplete maintenance is not success and
+continues from its checkpoint on the next enabled scheduled invocation.
+
+Run this project's test/typecheck/build for an affected worker edit. These checks
+do not replace the generated adopter's fleet, AWS or release acceptance.
+`,
+        'jobs/data-retention/src/retention-contract.spec.ts': `import { afterEach, describe, expect, it, vi } from 'vitest';
+import { selectRetentionCandidate } from './adapter.js';
+import { authorizeRetentionMaintenance } from './maintenance.js';
+import { authorizeRetentionOperation } from './run.js';
+import { runNativeRetention } from '../../../data/retention-worker.js';
+import { RETENTION_DAYS } from '../../../data/retention-state.js';
+import { productRecordReference } from '../../../data/pseudonymous-reference.js';
+
+// Refusal tests must finish before any provider request, even with valid table configuration.
+const io = vi.hoisted(() => ({ dataStore: vi.fn(() => { throw new Error('Unexpected provider access'); }) }));
+vi.mock('../../../data/key-value.js', () => io);
+const recordId = '11111111-1111-4111-8111-111111111111';
+const runId = '22222222-2222-4222-8222-222222222222';
+const at = '2026-09-12T12:00:00.000Z';
+const dueAt = new Date(Date.parse(at) + RETENTION_DAYS * 86_400_000).toISOString();
+const row = { id: recordId, version: 1, value: { id: recordId, name: 'fixture', ownerId: 'owner',
+  runScope: 'retention-test', createdAt: at, lastActivityAt: at, testExpiresAt: null } };
+function identity() {
+  vi.stubEnv('EBK_STAGE', 'development-task-fixture');
+  vi.stubEnv('EBK_WORKLOAD_IDENTITY', '${name}:data-retention-job');
+}
+afterEach(() => { vi.unstubAllEnvs(); vi.clearAllMocks(); });
+describe('native retention contract', () => {
+  it('selects due records by last activity, with exact identity and version', () => {
+    expect(selectRetentionCandidate(row, at)).toBeNull();
+    expect(selectRetentionCandidate(row, dueAt)).toEqual({ categoryId: 'product-record', locationId: 'primary-database',
+      recordId, recordVersion: 1, recordRef: productRecordReference(recordId), dueAt });
+  });
+  it('keeps test-run records in the separate protected cleanup path', () => {
+    expect(selectRetentionCandidate({ ...row, value: { ...row.value, testExpiresAt: dueAt } }, dueAt)).toBeNull();
+  });
+  it('refuses malformed or substituted record identity', () => {
+    expect(() => selectRetentionCandidate({ ...row, id: 'different' }, dueAt)).toThrow();
+  });
+  it('authorizes report, apply and maintenance as the exact generated machine workload', async () => {
+    identity();
+    for (const mode of ['report', 'apply'] as const) {
+      const principal = await authorizeRetentionOperation(mode, at, runId);
+      expect(principal.actor.id).toBe('${name}:data-retention-job');
+    }
+    expect((await authorizeRetentionMaintenance(at)).actor.id).toBe('${name}:data-retention-job');
+    expect(io.dataStore).not.toHaveBeenCalled();
+  });
+  it('rejects a substituted workload before provider access', async () => {
+    identity(); vi.stubEnv('EBK_WORKLOAD_IDENTITY', 'other:data-retention-job');
+    await expect(authorizeRetentionOperation('report', at, runId)).rejects.toThrow();
+    await expect(authorizeRetentionMaintenance(at)).rejects.toThrow();
+    expect(io.dataStore).not.toHaveBeenCalled();
+  });
+  it.each(['stage', 'sourceCommit', 'slice', 'approvalRequestId'] as const)('rejects a mismatched %s before provider access', async (field) => {
+    identity();
+    const command = { mode: 'report' as const, runId, approvalRequestId: '', asOf: at, correlationId: runId,
+      slice: '${name}', stage: 'development-task-fixture', sourceCommit: 'a'.repeat(40), [field]: 'invalid' };
+    await expect(runNativeRetention(command)).rejects.toThrow();
+    expect(io.dataStore).not.toHaveBeenCalled();
+  });
+});
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-key-value-retention-job-files.js.map

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

@@ -0,0 +1,2 @@
+/** Control retention is independent of domain retention, database choice and schedule cadence. */
+export declare function renderKeyValueRetentionMaintenanceFiles(name: string, pascalName: string): Readonly<Record<string, string>>;

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

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueRetentionMaintenanceFiles = renderKeyValueRetentionMaintenanceFiles;
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+/** Control retention is independent of domain retention, database choice and schedule cadence. */
+function renderKeyValueRetentionMaintenanceFiles(name, pascalName) {
+    const prefix = (0, built_in_plan_shared_js_1.lowerCamelIdentifier)(pascalName);
+    return {
+        'jobs/data-retention/src/maintenance.ts': `import { randomUUID } from 'node:crypto';
+import {
+  createAuthorizationEvaluator, defineCoarseAdmission, digestApprovalRequest, expireApprovalRequest,
+  toAuthorizationAuditRecord, type ApprovalRequest, type AuthorizationPrincipal,
+} from '@empire-builder-kit/runtime/authorization';
+import {
+  evaluateDataLifecycleHolds, normalizeDataLifecycleRuntimeHold, parseDataLifecycleChangeEvent, DATA_LIFECYCLE_SAFE_REFERENCE_PATTERN,
+  transitionDataLifecycleDeletion, type DataLifecycleDeletionRequestV1, type DataLifecycleRuntimeHoldV1,
+} from '@empire-builder-kit/runtime/data-lifecycle';
+import type { KeyValueChange, KeyValueRecord } from '@empire-builder-kit/runtime/key-value';
+import { createLogger } from '@empire-builder-kit/runtime/logging';
+import { ${prefix}AuthorizationActions, ${prefix}AuthorizationPolicy } from '../../../authorization/policy.js';
+import { dataStore } from '../../../data/key-value.js';
+import { canonicalDataRightsNow, dataRightsSubjectReference, plusDataRightsDays } from '../../../data/data-rights-shared.js';
+import { ${pascalName}ControlMetadataRuntimePolicy } from '../../../data/runtime-policy.cjs';
+import { requireRetainedRetentionPlan, retentionApprovalInput, retentionStage, RETENTION_RUNS, type RetentionRun } from '../../../data/retention-state.js';
+
+const TENANT = 'application';
+const WORKLOAD = '${name}:data-retention-job';
+const CHECKPOINTS = 'data-maintenance-checkpoints';
+const CHECKPOINT = 'lifecycle-control';
+const COLLECTIONS = [
+  'authorization-audit', 'data-lifecycle-audit', 'data-lifecycle-ledger',
+  'record-deletions', 'record-exports', 'delegation-grants', 'approval-requests',
+  'data-lifecycle-holds', 'record-mutations', 'data-retention-receipts',
+  'data-retention-candidates', 'data-retention-executions', 'data-retention-snapshots', RETENTION_RUNS,
+  'data-lifecycle-downstream-copies', 'data-lifecycle-receipts', 'export-rate',
+] as const;
+type Collection = typeof COLLECTIONS[number];
+type Row = KeyValueRecord & { id: string };
+type Value = Record<string, unknown>;
+interface Checkpoint { schemaVersion: 1; collection: number; afterId: string | null }
+function object(value: unknown): Value {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Control metadata is malformed.');
+  return value as Value;
+}
+function timestamp(value: unknown): string {
+  if (typeof value !== 'string') throw new Error('Control metadata timestamp is missing.');
+  return canonicalDataRightsNow(value);
+}
+function past(value: unknown, at: string, days = 0): boolean {
+  return plusDataRightsDays(timestamp(value), days) <= at;
+}
+function approval(value: unknown, id: string): ApprovalRequest {
+  const result = object(value) as unknown as ApprovalRequest;
+  if (result.schemaVersion !== 1 || result.id !== id || result.slice !== '${name}' ||
+      !Number.isSafeInteger(result.revision) || result.revision < 0 ||
+      !['pending', 'approved', 'executing', 'executed', 'expired', 'rejected'].includes(result.status))
+    throw new Error('Control approval does not match its stored identity.');
+  timestamp(result.requestedAt); timestamp(result.expiresAt);
+  return result;
+}
+const remove = (collection: Collection, row: Row): KeyValueChange => ({ action: 'delete', collection, id: row.id, expectedVersion: row.version });
+const check = (collection: string, id: string, version: number): KeyValueChange => ({ action: 'check', collection, id, expectedVersion: version });
+const put = (collection: string, row: Row, value: unknown): KeyValueChange => ({ action: 'put', collection, id: row.id, expectedVersion: row.version, value });
+
+export async function authorizeRetentionMaintenance(at: string): Promise<AuthorizationPrincipal> {
+  timestamp(at); retentionStage();
+  if (process.env.EBK_WORKLOAD_IDENTITY !== WORKLOAD) throw new Error('Retention maintenance 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: ${prefix}AuthorizationPolicy.version }).authorize({
+      action: ${prefix}AuthorizationActions.retentionMaintenance,
+      context: { facts: { operationId: CHECKPOINT }, now: at, stage: retentionStage() }, principal,
+      resource: { attributes: { collection: true }, type: 'slice' },
+    });
+  return principal;
+}
+function declaredHolds(holds: readonly DataLifecycleRuntimeHoldV1[], at: string) {
+  // Native record-hold commands own product-record holds. Control-metadata
+  // holds are explicit policy declarations, not inferred from domain ownership.
+  for (const hold of holds) {
+    if (hold.categoryId !== 'lifecycle-control-metadata') continue;
+    if (evaluateDataLifecycleHolds({ categoryId: hold.categoryId, holds: [hold], now: at,
+      operation: 'deletion', scopeRef: hold.scopeRef }).blocked)
+      throw new Error('Retention maintenance is blocked by an active control-metadata hold.');
+  }
+}
+async function terminalRun(runId: string, at: string) {
+  const row = await dataStore().get(TENANT, RETENTION_RUNS, runId);
+  if (!row) return null;
+  const value = object(row.value) as unknown as RetentionRun;
+  if (value.kind !== 'data-retention-run' || value.schemaVersion !== 1 || value.slice !== '${name}' || value.stage !== retentionStage())
+    throw new Error('Retention metadata belongs to a different Slice or stage.');
+  requireRetainedRetentionPlan(value.plan, runId);
+  if (!['reported', 'completed', 'approval-pending', 'approval-approved', 'approval-rejected', 'expired', 'applying', 'retry-required'].includes(value.status))
+    throw new Error('Retention metadata status is invalid.');
+  const expected = { reported: null, completed: 'executed', 'approval-pending': 'pending', 'approval-approved': 'approved',
+    'approval-rejected': 'rejected', expired: 'expired', applying: 'executing', 'retry-required': 'executing' };
+  if ((value.approval?.status ?? null) !== expected[value.status] || value.approval &&
+      (value.approval.requestDigest !== digestApprovalRequest(retentionApprovalInput(value.plan)) || value.approval.resource.id !== runId))
+    throw new Error('Retention metadata approval binding is invalid.');
+  if (value.expiresAt !== plusDataRightsDays(timestamp(value.createdAt), 400)) throw new Error('Retention metadata expiry is invalid.');
+  const eligible = past(value.expiresAt, at) && ['reported', 'completed', 'approval-rejected', 'expired'].includes(value.status);
+  if (value.status === 'completed' && (value.approval?.status !== 'executed' || !value.approval.execution?.completedAt))
+    throw new Error('Retention completion metadata is inconsistent.');
+  return { row: { ...row, id: runId }, value, eligible };
+}
+async function hasRunChild(collection: 'data-retention-candidates' | 'data-retention-receipts', runId: string) {
+  const page = await dataStore().list(TENANT, collection, { limit: 1, afterId: runId });
+  return page.records[0]?.id.startsWith(runId + ':') ?? false;
+}
+/** Returns only conditional control-record changes; never domain or external-object effects. */
+async function changesFor(collection: Collection, row: Row, at: string): Promise<KeyValueChange[]> {
+  const value = object(row.value), store = dataStore();
+  switch (collection) {
+    case 'export-rate': {
+      if (!Array.isArray(value.requestedAt) || value.requestedAt.length > 100 ||
+          value.requestedAt.some(at => typeof at !== 'string')) throw new Error('Export rate metadata is malformed.');
+      // Version-bound deletion cannot erase a concurrently renewed limiter.
+      return value.requestedAt.every(requestedAt => past(requestedAt, at, 400)) ? [remove(collection, row)] : [];
+    }
+    case 'data-lifecycle-receipts': {
+      const { expiresAt, ...event } = value;
+      const retained = parseDataLifecycleChangeEvent(event);
+      if (retained.categoryId !== 'product-record' || expiresAt !== plusDataRightsDays(retained.occurredAt, 400))
+        throw new Error('Lifecycle receipt scope or expiry differs.');
+      return past(expiresAt, at) ? [remove(collection, row)] : [];
+    }
+    case 'data-lifecycle-downstream-copies': {
+      if (value.copyId !== '${name}-lifecycle-consumer' || value.recipient !== '${name}' ||
+          value.purpose !== 'lifecycle-reconciliation' || typeof value.sourceSlice !== 'string' ||
+          !/^[a-z][a-z0-9-]{0,62}$/.test(value.sourceSlice) || typeof value.pseudonymousKey !== 'string' ||
+          !DATA_LIFECYCLE_SAFE_REFERENCE_PATTERN.test(value.pseudonymousKey) || !['correction', 'deletion'].includes(String(value.action)) ||
+          value.status !== (value.action === 'deletion' ? 'deleted' : 'reconciled') ||
+          !Array.isArray(value.holdRefs) || value.holdRefs.some(ref => typeof ref !== 'string' || !ref) ||
+          value.expiresAt !== plusDataRightsDays(timestamp(value.updatedAt), 400))
+        throw new Error('Lifecycle downstream copy scope or expiry differs.');
+      return value.holdRefs.length === 0 && past(value.expiresAt, at) ? [remove(collection, row)] : [];
+    }
+    case 'authorization-audit':
+      if (value.slice !== '${name}' || value.stage !== retentionStage()) throw new Error('Authorization audit scope differs.');
+      return past(value.timestamp, at, 400) ? [remove(collection, row)] : [];
+    case 'data-lifecycle-audit':
+      if (value.slice !== '${name}' || value.stage !== retentionStage() || value.expiresAt !== plusDataRightsDays(timestamp(object(value.audit).timestamp), 400))
+        throw new Error('Lifecycle audit scope or expiry differs.');
+      return past(value.expiresAt, at) ? [remove(collection, row)] : [];
+    case 'data-lifecycle-ledger':
+      if (value.expiresAt !== plusDataRightsDays(timestamp(value.effectiveAt), 400)) throw new Error('Lifecycle ledger expiry differs.');
+      return past(value.expiresAt, at) ? [remove(collection, row)] : [];
+    case 'record-mutations':
+      // Pending outbox records have no TTL and are owned by the dispatcher.
+      // This is only bounded, content-free API retry metadata.
+      if (value.expiresAt !== plusDataRightsDays(timestamp(value.occurredAt), 400)) throw new Error('Record retry expiry differs.');
+      return past(value.expiresAt, at) ? [remove(collection, row)] : [];
+    case 'delegation-grants': {
+      if (value.id !== row.id || value.slice !== '${name}' || row.version !== Number(value.revision) + 1) throw new Error('Delegation metadata identity differs.');
+      return past(value.expiresAt, at) && past(value.issuedAt, at, 400) ? [remove(collection, row)] : [];
+    }
+    case 'approval-requests': {
+      const current = approval(value, row.id);
+      if (row.version !== current.revision + 1) throw new Error('Approval metadata revision differs.');
+      const expired = expireApprovalRequest(current, at);
+      if (expired !== current) return [put(collection, row, expired)];
+      return current.status !== 'executing' && past(current.expiresAt, at, 400) ? [remove(collection, row)] : [];
+    }
+    case 'data-lifecycle-holds': {
+      const hold = normalizeDataLifecycleRuntimeHold(value as unknown as DataLifecycleRuntimeHoldV1, 0);
+      if (hold.holdId !== row.id) throw new Error('Hold metadata identity differs.');
+      if (hold.categoryId !== 'product-record') throw new Error('Stored control holds are unsupported; declare control-metadata holds in data/policy.json.');
+      return hold.status === 'released' && past(hold.expiresAt, at, 400) ? [remove(collection, row)] : [];
+    }
+    case 'record-deletions': {
+      const current = approval(value.approval, row.id);
+      const lifecycle = object(value.lifecycle) as unknown as DataLifecycleDeletionRequestV1;
+      if (value.kind !== 'record-deletion' || value.schemaVersion !== 1 || current.action !== '${name}:record-delete' || lifecycle.kind !== 'data-deletion')
+        throw new Error('Deletion control identity differs.');
+      const expired = expireApprovalRequest(current, at);
+      if (expired !== current) {
+        if (!['requested', 'verified', 'held'].includes(lifecycle.status)) throw new Error('Unstarted deletion approval has active effects.');
+        return [put(collection, row, { ...value, approval: expired,
+          lifecycle: transitionDataLifecycleDeletion(lifecycle, { type: 'reject', at, reasonCode: 'approval-expired' }) })];
+      }
+      const terminal = ['expired', 'rejected'].includes(current.status) && lifecycle.status === 'rejected' ||
+        current.status === 'executed' && lifecycle.status === 'completed' && lifecycle.primaryStatus === 'completed' && lifecycle.downstreamCopies.every(copy => copy.status === 'completed');
+      return terminal && past(lifecycle.updatedAt, at, 400) ? [remove(collection, row)] : [];
+    }
+    case 'record-exports': {
+      // The dedicated export cleanup owns object/version deletion, approval
+      // expiry and the outstanding-capacity binding. Never bypass that worker.
+      const current = approval(value.approval, row.id), lifecycle = object(value.lifecycle);
+      if (value.kind !== 'record-export' || value.schemaVersion !== 1 || current.action !== '${name}:record-export' || lifecycle.kind !== 'data-export')
+        throw new Error('Export control identity differs.');
+      if (value.cleanupState !== 'completed' || !['completed', 'rejected'].includes(String(lifecycle.status)) || !past(lifecycle.updatedAt, at, 400)) return [];
+      if (!Array.isArray(value.versions) || value.versions.length !== 0 || !['executed', 'expired', 'rejected'].includes(current.status))
+        throw new Error('Export control lacks completed cleanup evidence.');
+      const capacity = await store.get(TENANT, 'export-capacity', 'outstanding');
+      const ids = capacity ? object(capacity.value).ids : [];
+      if (!Array.isArray(ids)) throw new Error('Export capacity metadata is invalid.');
+      if (ids.includes(row.id)) return [];
+      return [check('export-capacity', 'outstanding', capacity?.version ?? 0), remove(collection, row)];
+    }
+    case 'data-retention-receipts': {
+      if (value.kind !== 'retention-receipt' || typeof value.eventId !== 'string' || row.id !== value.runId + ':' + value.eventId || typeof value.runId !== 'string' ||
+          value.expiresAt !== plusDataRightsDays(timestamp(value.appliedAt), 400)) throw new Error('Retention receipt binding differs.');
+      if (!past(value.expiresAt, at)) return [];
+      const retained = await terminalRun(value.runId, at);
+      if (!retained?.eligible || retained.value.status !== 'completed') return [];
+      if (value.publishedAt === null) throw new Error('Completed retention run retains unpublished delivery.');
+      if (!past(value.publishedAt, at)) throw new Error('Retention publication time is invalid.');
+      if (value.planDigest !== digestApprovalRequest(retentionApprovalInput(retained.value.plan))) throw new Error('Retention receipt plan binding differs.');
+      return [check(RETENTION_RUNS, value.runId, retained.row.version), remove(collection, row)];
+    }
+    case 'data-retention-candidates': {
+      if (typeof value.runId !== 'string' || value.slice !== '${name}' || value.stage !== retentionStage() || !row.id.startsWith(value.runId + ':'))
+        throw new Error('Retention candidate metadata scope differs.');
+      if (!past(value.expiresAt, at)) return [];
+      const retained = await terminalRun(value.runId, at);
+      if (retained) return retained.eligible && !await hasRunChild('data-retention-receipts', value.runId)
+        ? [check(RETENTION_RUNS, value.runId, retained.row.version), remove(collection, row)] : [];
+      const snapshot = await store.get(TENANT, 'data-retention-snapshots', value.runId);
+      const building = snapshot ? object(snapshot.value) : null;
+      if (!snapshot || building?.status !== 'building') return [];
+      if (building.kind !== 'retention-snapshot' || building.runId !== value.runId || building.slice !== '${name}' || building.stage !== retentionStage() ||
+          building.expiresAt !== plusDataRightsDays(timestamp(building.createdAt), 400) || value.expiresAt !== building.expiresAt)
+        throw new Error('Unfinished retention snapshot binding differs.');
+      if (!past(building.expiresAt, at)) return [];
+      return [check(RETENTION_RUNS, value.runId, 0), check('data-retention-snapshots', value.runId, snapshot.version), remove(collection, row)];
+    }
+    case 'data-retention-executions': {
+      if (value.kind !== 'retention-execution' || value.runId !== row.id) throw new Error('Retention execution identity differs.');
+      const retained = await terminalRun(row.id, at);
+      if (!retained?.eligible || retained.value.status !== 'completed' || await hasRunChild('data-retention-receipts', row.id)) return [];
+      if (value.completedAt !== retained.value.approval?.execution?.completedAt || object(value.checkpoint).complete !== true ||
+          value.planDigest !== digestApprovalRequest(retentionApprovalInput(retained.value.plan)) || value.approvalId !== retained.value.approval?.id)
+        throw new Error('Retention execution lacks final completion evidence.');
+      return [check(RETENTION_RUNS, row.id, retained.row.version), remove(collection, row)];
+    }
+    case 'data-retention-snapshots': {
+      if (value.kind !== 'retention-snapshot' || value.runId !== row.id || value.stage !== retentionStage() || value.slice !== '${name}' ||
+          value.expiresAt !== plusDataRightsDays(timestamp(value.createdAt), 400)) throw new Error('Retention snapshot scope or expiry differs.');
+      if (!past(value.expiresAt, at) || await hasRunChild('data-retention-candidates', row.id) || await hasRunChild('data-retention-receipts', row.id)) return [];
+      const retained = await terminalRun(row.id, at);
+      if (retained ? !retained.eligible : value.status !== 'building') return [];
+      return [check(RETENTION_RUNS, row.id, retained?.row.version ?? 0), remove(collection, row)];
+    }
+    case RETENTION_RUNS: {
+      const retained = await terminalRun(row.id, at);
+      if (!retained || retained.row.version !== row.version) throw new Error('Retention run changed during maintenance.');
+      const current = retained.value.approval;
+      if (current && ['approval-pending', 'approval-approved'].includes(retained.value.status)) {
+        const expired = expireApprovalRequest(approval(current, current.id), at);
+        if (expired !== current) return [put(collection, row, { ...retained.value, approval: expired, status: 'expired', updatedAt: at })];
+      }
+      if (!retained.eligible || await hasRunChild('data-retention-candidates', row.id) || await hasRunChild('data-retention-receipts', row.id)) return [];
+      const execution = await store.get(TENANT, 'data-retention-executions', row.id);
+      const snapshot = await store.get(TENANT, 'data-retention-snapshots', row.id);
+      if (execution || snapshot) return [];
+      return [check('data-retention-executions', row.id, 0), check('data-retention-snapshots', row.id, 0), remove(collection, row)];
+    }
+  }
+}
+
+export async function runRetentionMaintenance(options: { budgetMs?: number; maxItems?: number } = {}) {
+  const at = new Date().toISOString();
+  const principal = await authorizeRetentionMaintenance(at);
+  const budget = options.budgetMs ?? 240_000, maximum = options.maxItems ?? 1000;
+  if (!Number.isSafeInteger(budget) || budget < 1 || budget > 240_000 || !Number.isSafeInteger(maximum) || maximum < 1 || maximum > 1000)
+    throw new Error('Retention maintenance requires bounded work.');
+  const deadline = Date.now() + budget, store = dataStore();
+  declaredHolds(${pascalName}ControlMetadataRuntimePolicy.declaredHolds, at);
+  const loaded = await store.get(TENANT, CHECKPOINTS, CHECKPOINT);
+  let version = loaded?.version ?? 0;
+  let cursor: Checkpoint = loaded ? object(loaded.value) as unknown as Checkpoint : { schemaVersion: 1, collection: 0, afterId: null };
+  if (cursor.schemaVersion !== 1 || !Number.isInteger(cursor.collection) || cursor.collection < 0 || cursor.collection >= COLLECTIONS.length ||
+      (cursor.afterId !== null && (typeof cursor.afterId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(cursor.afterId))))
+    throw new Error('Retention maintenance checkpoint is invalid.');
+  const invocation = randomUUID();
+  const audit = toAuthorizationAuditRecord({ action: ${prefix}AuthorizationActions.retentionMaintenance,
+    context: { facts: { operationId: CHECKPOINT }, now: at, stage: retentionStage() }, principal, resource: { attributes: { collection: true }, type: 'slice' } },
+    { decision: 'allow', obligations: [], policyVersion: ${prefix}AuthorizationPolicy.version },
+    { correlationId: invocation, pseudonymousSubjectId: dataRightsSubjectReference(WORKLOAD), slice: '${name}', stage: retentionStage(), timestamp: at });
+  await store.commit({ tenantId: TENANT, changes: [
+    { action: 'put', collection: CHECKPOINTS, id: CHECKPOINT, expectedVersion: version, value: cursor },
+    { action: 'put', collection: 'authorization-audit', id: invocation, expectedVersion: 0, value: audit },
+  ] }); version++;
+  // The committed policy above is the complete control-hold authority for this
+  // deployment, on every invocation and regardless of cursor. Record-hold APIs
+  // cannot create control holds. Their history is pruned below, not scanned as
+  // a mutable global authority snapshot before unrelated control work.
+  let scanned = 0, deleted = 0, reconciled = 0, complete = false;
+  while (scanned < maximum && Date.now() < deadline) {
+    const collection = COLLECTIONS[cursor.collection];
+    const page = await store.list(TENANT, collection, { limit: Math.min(50, maximum - scanned), ...(cursor.afterId ? { afterId: cursor.afterId } : {}) });
+    let afterId = cursor.afterId;
+    for (const row of page.records) {
+      if (Date.now() >= deadline) break;
+      if (afterId && row.id <= afterId) throw new Error('Control inventory did not advance.');
+      const changes = await changesFor(collection, row, at);
+      if (changes.length) {
+        await store.commit({ tenantId: TENANT, changes: [check(CHECKPOINTS, CHECKPOINT, version), ...changes] });
+        deleted += changes.filter(change => change.action === 'delete').length;
+        reconciled += changes.filter(change => change.action === 'put').length;
+      }
+      afterId = row.id; scanned++;
+    }
+    const consumed = page.records.length === 0 || afterId === page.records.at(-1)?.id;
+    if (page.nextId && (page.records.length === 0 || page.nextId !== page.records.at(-1)?.id)) throw new Error('Control inventory cursor is invalid.');
+    if (consumed && !page.nextId) {
+      if (cursor.collection + 1 === COLLECTIONS.length) { cursor = { schemaVersion: 1, collection: 0, afterId: null }; complete = true; }
+      else cursor = { schemaVersion: 1, collection: cursor.collection + 1, afterId: null };
+    } else cursor = { ...cursor, afterId };
+    await store.commit({ tenantId: TENANT, changes: [{ action: 'put', collection: CHECKPOINTS, id: CHECKPOINT, expectedVersion: version, value: cursor }] }); version++;
+    if (complete || !consumed) break;
+  }
+  return { complete, scanned, deleted, reconciled };
+}
+export async function handler(_event: unknown, context?: { getRemainingTimeInMillis(): number }) {
+  const logger = createLogger({ component: 'job-data-retention-maintenance', feature: 'data-lifecycle', operation: 'retention-maintenance',
+    slice: '${name}', stage: process.env.EBK_STAGE ?? 'unknown', workspace: process.env.EBK_WORKSPACE ?? '${name}' });
+  try {
+    const result = await runRetentionMaintenance({ budgetMs: Math.min(240_000, (context?.getRemainingTimeInMillis() ?? 250_000) - 10_000) });
+    logger.info('Native control maintenance completed', { attributes: result, outcome: result.complete ? 'success' : 'unknown' });
+    return result;
+  } catch (error) { logger.error('Native control maintenance failed', { outcome: 'failure' }); throw error; }
+}
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-key-value-retention-maintenance.js.map

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

@@ -0,0 +1,2 @@
+/** Native bounded retention execution; no database credential, SQL adapter, or container prerequisite. */
+export declare function renderKeyValueRetentionWorkerFiles(name: string, pascalName: string): Readonly<Record<string, string>>;