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

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

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueRetentionFiles = renderKeyValueRetentionFiles;
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+/** Framework retention control records remain in DynamoDB, including for SQL-enabled Slices. */
+function renderKeyValueRetentionFiles(name, pascalName) {
+    const prefix = (0, built_in_plan_shared_js_1.lowerCamelIdentifier)(pascalName);
+    return {
+        'data/retention-state.ts': `import { digestApprovalRequest, type ApprovalRequest } from '@empire-builder-kit/runtime/authorization';
+import type { KeyValueChange } from '@empire-builder-kit/runtime/key-value';
+import { createDataLifecyclePseudonymousReference } from '@empire-builder-kit/runtime/data-lifecycle';
+import { ${prefix}AuthorizationPolicy } from '../authorization/policy.js';
+import { canonicalDataRightsNow, plusDataRightsDays } from './data-rights-shared.js';
+import { ${pascalName}DataLifecycleRuntimePolicy } from './runtime-policy.cjs';
+import { dataStore } from './key-value.js';
+
+export const RETENTION_ACTION = '${name}:retention-apply';
+export const RETENTION_AUTHORIZATION_POLICY = ${prefix}AuthorizationPolicy.version;
+export const RETENTION_POLICY = ${pascalName}DataLifecycleRuntimePolicy.policyVersion;
+export const RETENTION_DAYS = ${pascalName}DataLifecycleRuntimePolicy.retentionDays;
+export const RETENTION_RUNS = 'data-retention-runs';
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+
+export interface ${pascalName}RetentionPlanV1 {
+  asOf: string; candidateDigest: string; categoryId: 'product-record'; due: number;
+  locationId: 'primary-database'; maxItems: 10000; pageSize: 100;
+  policyVersion: string; retentionDays: number; runId: string;
+}
+export interface RetentionRun {
+  kind: 'data-retention-run'; schemaVersion: 1; slice: '${name}'; stage: string;
+  plan: ${pascalName}RetentionPlanV1;
+  approval: ApprovalRequest<typeof RETENTION_ACTION> | null;
+  status: 'reported' | 'approval-pending' | 'approval-approved' | 'approval-rejected' |
+    'applying' | 'retry-required' | 'completed' | 'expired';
+  createdAt: string; updatedAt: string; expiresAt: string;
+}
+export function retentionStage(): string {
+  const stage = process.env.EBK_STAGE;
+  if (!stage || !/^[a-z][a-z0-9-]{0,62}$/.test(stage)) throw new Error('Retention requires the exact Slice/task stage.');
+  return stage;
+}
+export function retentionRunReference(runId: string): string {
+  if (typeof runId !== 'string' || !UUID.test(runId)) throw new Error('Retention run requires an exact UUID.');
+  return createDataLifecyclePseudonymousReference({ categoryId: 'lifecycle-control-metadata', slice: '${name}', value: runId });
+}
+/** Retained control metadata is validated against its own policy, never today's deletion authority. */
+export function requireRetainedRetentionPlan(value: ${pascalName}RetentionPlanV1, runId: string): ${pascalName}RetentionPlanV1 {
+  retentionRunReference(runId);
+  if (!value || value.runId !== runId || typeof value.policyVersion !== 'string' || !value.policyVersion.trim() || value.policyVersion.length > 128 ||
+      value.categoryId !== 'product-record' || value.locationId !== 'primary-database' ||
+      value.maxItems !== 10000 || value.pageSize !== 100 || !Number.isSafeInteger(value.retentionDays) || value.retentionDays < 1 ||
+      !Number.isSafeInteger(value.due) || value.due < 0 || value.due > value.maxItems ||
+      typeof value.asOf !== 'string' || typeof value.candidateDigest !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(value.candidateDigest) ||
+      Object.keys(value).sort().join(',') !== 'asOf,candidateDigest,categoryId,due,locationId,maxItems,pageSize,policyVersion,retentionDays,runId')
+    throw new Error('Retention report plan is invalid.');
+  canonicalDataRightsNow(value.asOf);
+  return value;
+}
+export function requireRetentionPlan(value: ${pascalName}RetentionPlanV1, runId: string): ${pascalName}RetentionPlanV1 {
+  requireRetainedRetentionPlan(value, runId);
+  if (value.policyVersion !== RETENTION_POLICY || value.retentionDays !== RETENTION_DAYS)
+    throw new Error('Retention report policy changed; create and approve a new report.');
+  return value;
+}
+export const retentionApprovalInput = (plan: ${pascalName}RetentionPlanV1) => ({
+  action: RETENTION_ACTION, command: plan, resource: { id: plan.runId, type: 'retention-run' },
+} as const);
+export function createReportedRetentionRun(plan: ${pascalName}RetentionPlanV1, now: string): RetentionRun {
+  if (typeof now !== 'string') throw new Error('Retention report requires an explicit timestamp.');
+  requireRetentionPlan(plan, plan.runId); canonicalDataRightsNow(now);
+  if (Date.parse(plan.asOf) > Date.parse(now)) throw new Error('Retention report cannot select future records.');
+  return { kind: 'data-retention-run', schemaVersion: 1, slice: '${name}', stage: retentionStage(),
+    plan, approval: null, status: 'reported', createdAt: now, updatedAt: now, expiresAt: plusDataRightsDays(now, 400) };
+}
+export function retentionRunChange(run: RetentionRun, expectedVersion: number): KeyValueChange {
+  return { action: 'put', collection: RETENTION_RUNS, id: run.plan.runId, expectedVersion, value: run };
+}
+export async function loadRetentionRun(runId: string, now: string) {
+  if (typeof now !== 'string') throw new Error('Retention operation requires an explicit timestamp.');
+  retentionRunReference(runId); canonicalDataRightsNow(now);
+  const row = await dataStore().get('application', RETENTION_RUNS, runId);
+  const run = row?.value as RetentionRun | undefined;
+  if (!row || !run || run.kind !== 'data-retention-run' || run.schemaVersion !== 1 ||
+      run.slice !== '${name}' || run.stage !== retentionStage() ||
+      !['reported', 'approval-pending', 'approval-approved', 'approval-rejected', 'applying', 'retry-required', 'completed', 'expired'].includes(run.status))
+    throw new Error('The exact retention report was not found or is malformed.');
+  requireRetentionPlan(run.plan, runId);
+  for (const value of [run.createdAt, run.updatedAt, run.expiresAt]) {
+    if (typeof value !== 'string') throw new Error('Retention report time bounds are malformed.');
+    canonicalDataRightsNow(value);
+  }
+  if (Date.parse(run.plan.asOf) > Date.parse(run.createdAt) || Date.parse(run.createdAt) > Date.parse(run.updatedAt) ||
+      Date.parse(run.updatedAt) > Date.parse(now) || run.expiresAt !== plusDataRightsDays(run.createdAt, 400) ||
+      Date.parse(now) >= Date.parse(run.expiresAt))
+    throw new Error('Retention report is expired or its retained time bounds are invalid.');
+  const approval = run.approval;
+  if (approval !== null) {
+    if (!approval || !UUID.test(approval.id) || approval.schemaVersion !== 1 || approval.slice !== '${name}' ||
+        approval.action !== RETENTION_ACTION || approval.policyVersion !== RETENTION_AUTHORIZATION_POLICY ||
+        approval.resource?.id !== runId || approval.resource.type !== 'retention-run' ||
+        !Number.isSafeInteger(approval.revision) || approval.revision < 0 ||
+        digestApprovalRequest(retentionApprovalInput(run.plan)) !== approval.requestDigest ||
+        approval.author?.authorityMode !== 'direct' || approval.author.subjectType !== 'user' ||
+        typeof approval.author.actorId !== 'string' || !approval.author.actorId ||
+        approval.author.effectiveHumanId !== approval.author.actorId)
+      throw new Error('Retention approval is not bound to the exact report and direct author.');
+    if (typeof approval.requestedAt !== 'string' || typeof approval.expiresAt !== 'string')
+      throw new Error('Retention approval time bounds are malformed.');
+    canonicalDataRightsNow(approval.requestedAt); canonicalDataRightsNow(approval.expiresAt);
+    if (Date.parse(approval.requestedAt) < Date.parse(run.createdAt) || Date.parse(approval.requestedAt) > Date.parse(run.updatedAt) ||
+        Date.parse(approval.expiresAt) > Date.parse(run.expiresAt) ||
+        approval.expiresAt !== plusDataRightsDays(approval.requestedAt, 1))
+      throw new Error('Retention approval has invalid time bounds.');
+  }
+  const expected = { reported: null, 'approval-pending': 'pending', 'approval-approved': 'approved',
+    'approval-rejected': 'rejected', applying: 'executing', 'retry-required': 'executing', completed: 'executed', expired: 'expired' };
+  if ((approval?.status ?? null) !== expected[run.status]) throw new Error('Retention report and approval state disagree.');
+  return { run, version: row.version };
+}
+`,
+        'data/retention-control.ts': `import {
+  assertAuthorizationAllowed, createApprovalRequest, decideApprovalRequest,
+  type AuthorizationPrincipal,
+} from '@empire-builder-kit/runtime/authorization';
+import { canonicalDataRightsNow, dataRightsAuditChange, plusDataRightsDays, requireDirectAdmin } from './data-rights-shared.js';
+import { dataStore } from './key-value.js';
+import { loadRetentionRun, retentionApprovalInput, retentionRunChange, retentionRunReference,
+  RETENTION_AUTHORIZATION_POLICY, type RetentionRun } from './retention-state.js';
+export type { ${pascalName}RetentionPlanV1 } from './retention-state.js';
+
+interface Command { correlationId: string; now: string; principal: AuthorizationPrincipal; runId: string }
+function validate(input: Command) {
+  requireDirectAdmin(input.principal);
+  if (typeof input.now !== 'string') throw new Error('Retention operation requires an explicit timestamp.');
+  canonicalDataRightsNow(input.now); retentionRunReference(input.runId);
+  if (typeof input.correlationId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.correlationId))
+    throw new Error('Retention requires a bounded correlation identifier.');
+}
+async function commit(run: RetentionRun, version: number, input: Command, purposeCode: string) {
+  if (!run.approval) throw new Error('Retention approval transition requires an approval.');
+  // Report, approval and audit share one native transaction; no independently
+  // writable approval file/row can authorize another report or a stale version.
+  await dataStore().commit({ tenantId: 'application', changes: [
+    retentionRunChange(run, version),
+    dataRightsAuditChange({ action: 'retention-apply', approvalRequestId: run.approval.id,
+      correlationId: input.correlationId, now: input.now, principal: input.principal,
+      resourceReference: retentionRunReference(input.runId), purposeCode,
+      outcome: run.status === 'approval-rejected' ? 'rejected' : 'succeeded',
+      summary: 'A bounded retention approval transition was committed.' }),
+  ] });
+}
+export async function request${pascalName}RetentionApproval(input: Command) {
+  validate(input);
+  const { run, version } = await loadRetentionRun(input.runId, input.now);
+  if (run.status !== 'reported' || run.approval !== null)
+    throw new Error('Retention report already has an approval request or is no longer reviewable.');
+  const approval = createApprovalRequest({ ...retentionApprovalInput(run.plan), author: input.principal,
+    expiresAt: plusDataRightsDays(input.now, 1), now: input.now,
+    policyVersion: RETENTION_AUTHORIZATION_POLICY, slice: '${name}' });
+  if (Date.parse(approval.expiresAt) > Date.parse(run.expiresAt))
+    throw new Error('Retention report expires before its approval; create a new report.');
+  await commit({ ...run, approval, status: 'approval-pending', updatedAt: input.now }, version, input, 'approval-pending');
+  return { approvalRequestId: approval.id, expiresAt: approval.expiresAt, requestDigest: approval.requestDigest, status: approval.status };
+}
+export async function decide${pascalName}RetentionApproval(input: Command & {
+  approvalRequestId: string; expectedRequestDigest: string; outcome: 'approved' | 'rejected'; reasonReference: string;
+}) {
+  validate(input);
+  if (input.outcome !== 'approved' && input.outcome !== 'rejected') throw new Error('Retention approval outcome is invalid.');
+  const { run, version } = await loadRetentionRun(input.runId, input.now);
+  if (run.status !== 'approval-pending' || !run.approval || run.approval.id !== input.approvalRequestId)
+    throw new Error('Retention approval does not match the pending report.');
+  const decision = decideApprovalRequest(run.approval, { approver: input.principal,
+    expectedRequestDigest: input.expectedRequestDigest, now: input.now, outcome: input.outcome,
+    reasonReference: input.reasonReference, requiredPolicyVersion: RETENTION_AUTHORIZATION_POLICY });
+  assertAuthorizationAllowed(decision.decision);
+  await commit({ ...run, approval: decision.request, status: input.outcome === 'approved' ? 'approval-approved' : 'approval-rejected',
+    updatedAt: input.now }, version, input, 'approval-' + input.outcome);
+  return { approvalRequestId: decision.request.id, status: decision.request.status };
+}
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-key-value-retention.js.map

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

@@ -1,3 +1,3 @@
 import type { GeneratedOwnershipRecord } from '../../ownership/index.js';
 /** @internal */
-export declare function renderSliceMetadataFiles(name: string, scope: string, pascalName: string, ownership: GeneratedOwnershipRecord): Readonly<Record<string, string>>;
+export declare function renderSliceMetadataFiles(name: string, scope: string, pascalName: string, ownership: GeneratedOwnershipRecord, sql?: boolean): Readonly<Record<string, string>>;

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

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderSliceMetadataFiles = renderSliceMetadataFiles;
 const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
 /** @internal */
-function renderSliceMetadataFiles(name, scope, pascalName, ownership) {
+function renderSliceMetadataFiles(name, scope, pascalName, ownership, sql = false) {
     return {
         '.ebk/ownership.json': (0, built_in_plan_shared_js_1.json)(ownership),
         'README.md': `# ${name}
@@ -18,7 +18,8 @@ files from \`packages/foundation/infra\` or from another slice's internals.
 
 - Next.js web application with sign-in, refresh, sign-out, callback, and password-reset paths
 - Lambda HTTP API with health and JWT-protected routes
-- stage- and slice-scoped logical Postgres database plus migration history
+- task/stage- and Slice-scoped DynamoDB persistence with durable event intents and inbox handling
+- optional user-feature PostgreSQL/Drizzle backed by Foundation Aurora when SQL is declared
 - typed EventBridge publisher and SQS/DLQ-backed consumer
 - Product Slice dashboard and API/DLQ alarms routed through Foundation alerts
 - Vitest source test and Playwright deployed-smoke path
@@ -26,11 +27,20 @@ files from \`packages/foundation/infra\` or from another slice's internals.
   rendered accessibility checks, and reviewable visual evidence
 - versioned SLO, alarm, diagnostic, incident-remediation, and reliability-exercise contracts
 - performance, capacity, resource-tag, protected-load, and actual-cost evidence contracts
-- workspace-lockfile-derived migration and retention container recipes with supply-chain checks
+- supply-chain-checked migration containers only for declared SQL workloads
 
 Keep business contracts in \`contracts/\`. Add long-running Services and finite Jobs only when
 the product needs them.
 
+Declare a new same-Slice domain event in the seeded \`contracts/events.ts\`
+\`EventContractSchema\` and implement its effect in the seeded \`api/event-consumer.ts\`.
+The existing queue rule subscribes to those declared event types while retaining
+the exact publishing Slice and current stage filters. Keep the built-in event
+declarations; lifecycle events retain their separate declared-source rule.
+Commit domain changes and event intents together through the DynamoDB store,
+and commit consumer effects with the inbox. Do not edit managed routing or
+assume that declaring an event implements its consumer behavior.
+
 Run \`pnpm nx run ${name}:verify\` for the non-deployed Slice checks. The policy files under
 \`frontend/\`, \`docs/reliability/\`, \`operations/\`, and \`performance/\` are seeded decisions:
 adopt real owners, journeys, thresholds, targets, and evidence sources before enabling
@@ -43,19 +53,61 @@ Add product dependencies with \`pnpm --filter ${scope}/${name} add <package>\`.
 its recorded framework keys in this package manifest, so health checks and upgrades preserve
 dependencies, scripts, and other keys added by the product team.
 
-## Local database
+## Develop the DynamoDB-first application
 
-Run \`ebk dev up ${name}\`. The framework derives the current developer's
-personal stage, starts Docker Postgres, applies local migrations, and starts
-SST live mode through the workspace-pinned Nx task. A caller cannot supply or
-persist a stage override. The fleet supervisor allocates the internal Next.js
-port and reports the HTTPS readiness URL.
+Run \`ebk dev up ${name}\`. The framework reuses this worktree's persisted opaque
+task identity, starts the selected Slice and declared dependencies, and runs
+SST live mode through the workspace-pinned Nx task. Native persistence uses the
+task's real AWS DynamoDB resources; Docker PostgreSQL starts only for declared
+relational workloads. \`verify\` runs \`test-integration\`, which starts DynamoDB
+Local (and PostgreSQL when declared) in disposable Docker containers, so
+verification needs a running Docker engine. A caller cannot supply or persist a
+stage override. The
+fleet supervisor allocates the internal Next.js port and reports the HTTPS
+readiness URL. Development accepts a dirty tree and requires no production
+confirmation or release artifact.
 
 The workspace fleet target discovers this slice through its versioned
 \`metadata.ebk.localDev\` adapter. It supplies the exact HTTPS fleet origin, secure-cookie
 signal, callback/logout URLs, and allocated internal port; do not persist a developer port in
 this project.
 
+Functions added with \`nx g @empire-builder-kit/nx:function\` use
+\`/${name}/api/functions/<name>\` on this same browser origin. During fleet
+development, generated Next routing forwards only that namespace to this task's
+SST API; handlers keep native SST live execution. This is not deployed-stage
+fallback. Keep user-owned Next API routes local and do not add a manual proxy.
+
+Use \`pnpm nx run ${name}:verify-local-browser\` against that owned fleet origin.
+Before its first run, install the pinned browser from this Slice's directory
+with \`pnpm exec playwright install chromium\`. Repeat after a Playwright upgrade
+only when the required browser revision changes. Verification never downloads
+a browser or changes system trust silently. Inspect local failures under
+\`.ebk/evidence/local-browser-artifacts\` in this Slice; keep these diagnostics
+private because they may contain application test data.
+Run affected feature tests, typecheck and lint for ordinary edits; use the
+complete Slice/workspace verification at milestones, not after every hot edit.
+Local fixture tests do not prove cloud routing, Streams, IAM or browser behavior.
+Run \`ebk dev down ${name}\` when finished; cleanup must target only owned task
+resources, and retained local SQL volumes remain available for the next session.
+
+## Add relational storage deliberately
+
+SQL is optional for user features that need relational constraints, joins or
+transactions. DynamoDB remains the framework core, including its inbox and
+outbox, when SQL is enabled. Use the Standard Blueprint's \`inputs.sql.reason\`
+at Slice creation, or run
+\`pnpm nx g @empire-builder-kit/nx:sql ${name} --reason="Explain the relational requirement"\`
+to review the later addition, then repeat with \`--apply\`. The generator updates
+the persisted Foundation/Slice declarations and reports resource implications;
+it does not deploy AWS resources. New SQL defaults to \`cost-optimized\` Aurora
+(0–2 ACUs, five-minute auto-pause); an explicit existing capacity choice is
+preserved. Choose \`balanced\` or \`standard\` only when measured latency and
+capacity needs justify a warm floor. Capacity selection does not pause schedules.
+
+The commands below apply only after SQL has been declared. No Aurora, Drizzle
+migration target or local PostgreSQL prerequisite is part of the SQL-free path.
+
 \`database/bindings.json\` is the adopter-owned database selection contract. Add a candidate
 identifier to \`primary.provisioned\` to provision it without moving workload traffic. Every
 provisioned identifier receives its own AWS-internal bootstrap-and-migration workflow. Run
@@ -67,10 +119,7 @@ databases with Foundation master credentials.
 The readiness route is framework-managed for local orchestration. Put product-specific
 dependency and status checks under \`/${name}/api/status\` rather than editing that route.
 
-Run \`ebk dev down ${name}\` when finished. The named volume preserves local
-data between sessions.
-
-For a deployed canonical stage, \`${name}:db-migrate\` does not connect from the
+For a deployed canonical SQL stage, \`${name}:db-migrate\` does not connect from the
 local or GitHub process. It starts the generated Standard Step Functions
 workflow, waits for its one-off Fargate task, and reports the execution ARN.
 The workflow first runs an AWS-internal bootstrap task that converges the
@@ -79,16 +128,22 @@ IAM-authenticated migration task. Neither password resolves in GitHub, SST, or
 Pulumi state. The authenticated \`GET /database-health\` API route uses the
 server-only resolver, linked secret, and runtime-embedded AWS RDS global CA
 bundle to prove the deployed runtime path with hostname-verified TLS.
-Staging and production use the existing environment-scoped
-\`AWS_DEPLOY_ROLE_ARN\`; no second migration OIDC role or database password is
-configured by the adopter. That role needs only \`ssm:GetParameter\` for the
+Staging and production use the canonical stage deployment role
+(\`ebk-<stage>-deploy\`), which the managed Deploy workflow derives from
+committed account, stage and partition policy and exposes to its jobs as
+\`AWS_DEPLOY_ROLE_ARN\`; no GitHub environment role secret, second migration
+OIDC role or database password is configured by the adopter. That role needs only \`ssm:GetParameter\` for the
 exact generated migration-registration path and \`states:StartExecution\` /
 \`states:DescribeExecution\` for the exact generated state machine and its
 execution namespace; it never receives SQL, database-token, or arbitrary ECS
-authority.
-
-Ordinary Slice removal is non-destructive and retains logical databases and
-credential containers. The only destructive v1 database path is the protected
+authority. When a user feature changes SQL data and publishes an event, keep
+the SQL change and SQL intent in one transaction, then notify after commit.
+Missed SQL notifications recover on the next hourly reconciliation by default;
+explicit cadence and maintenance pauses remain independent settings. No
+transaction spans SQL and DynamoDB.
+
+Ordinary Slice removal retains declared relational databases and their
+credential containers. The generated SQL retirement rehearsal is the protected
 \`db-retirement-rehearsal\` target for the exact operations-declared
 \`development\` database named \`retirement_rehearsal\`. It accepts no stage,
 Slice, database, task, role, image, network, or workflow selection.
@@ -110,12 +165,14 @@ export const ${pascalName}ContractVersion = '1.0.0' as const;
 
 ## Boundary
 
-This slice owns its product behavior, routes, app clients, logical databases, event rules,
-queues, alarms, dashboards, and runbooks. The Foundation owns shared capacity and policy.
+This Slice owns its product behavior, routes, app clients, DynamoDB tables,
+declared relational databases, event rules, queues, alarms, dashboards and
+runbooks. Foundation owns shared capabilities and policy; Aurora is provisioned
+only for declared relational requirements, not for the DynamoDB framework core.
 
 ## Dependencies
 
-- Foundation contract: \`^1\`
+- Foundation discovery follows its versioned capability contract
 - Canonical stages map to the same Foundation stage; framework-derived personal stages map
   only to \`development\`
 - Other slices: contracts-only imports
@@ -146,7 +203,8 @@ before adopting capacity limits, enabling protected load, or collecting actual-c
 
 ## Database migration
 
-Protected migration runs from generated immutable bootstrap and migration
+${sql
+            ? `Protected migration runs from generated immutable bootstrap and migration
 Fargate tasks through one Standard Step Functions workflow per provisioned
 database identifier. The bootstrap task owns exact master-secret read,
 runtime-secret read/write, and migrator-connect permissions; it converges the
@@ -157,10 +215,12 @@ receives only exact migrator-connect permission.
 
 Retain the workflow execution ARN, both task identities, image identity, source
 commit, migration checksums, sanitized CloudWatch logs, backup reference, and
-verification result. The GitHub job reuses
-\`AWS_DEPLOY_ROLE_ARN\` only to start and describe the exact workflow; it must
-not have direct SQL, secret-value, \`rds-db:connect\`, or arbitrary
-\`ecs:RunTask\` authority.
+verification result. The GitHub job uses the stage deployment role
+(\`AWS_DEPLOY_ROLE_ARN\`) only to start and describe the exact workflow. That
+role has no \`rds-db:connect\` or \`ecs:RunTask\` authority and no secret-value
+access to operator or Slice secret containers; its sole secret-value exception
+is the SST-managed Foundation Aurora credential described in the workspace
+\`docs/stage-deployment-authority.md\`.
 
 The default \`db-migrate\` target selects the active \`primary\` database.
 During replacement, first add the candidate to \`primary.provisioned\`, deploy
@@ -188,10 +248,75 @@ reviewed replacement or forward-compatible design instead of bypassing the
 transaction. Apply expand/migrate/contract. Repair failures with a forward
 migration or the documented restore/replacement procedure; do not edit an
 applied SQL file.
+`
+            : `This Slice uses DynamoDB and has no SQL migration or retirement targets.
+For a feature requiring relational integrity or joins, review
+\`pnpm nx g @empire-builder-kit/nx:sql ${name} --reason="Explain the relational requirement"\`,
+then repeat with \`--apply\`. Generation declares the capability; deploy through
+the normal lifecycle. DynamoDB remains the framework core after SQL is added.
+`}
+`,
+        'docs/runbooks/database-recovery.md': `# ${name} persistence recovery
+
+Start with the exact Slice, stage, source and alarm dimensions. Keep unrelated
+stages and production protections unchanged. Record bounded diagnostics; do not
+retain record bodies, credentials or raw provider state.
+
+## DynamoDB
+
+For \`database-errors\`, inspect both table and PendingEvents index read/write
+throttle metrics. Check hot keys, account/service quotas, retries and backlog;
+do not treat a missing RDS signal as proof that the table is healthy. Check the
+outbox schedule and stream mapping against their deliberate maintenance state.
+Never delete pending intents or completion work to silence an alarm. If delivery
+was interrupted, restore the owning worker's authority/connectivity and allow
+bounded reconciliation to resume. Repeated failures require investigation of
+the retained content-free failure marker and exact original workflow.
+Completion failures retain a bounded attempt counter and exponential retry
+delay (one minute up to one hour). A deferred or earlier-page obligation keeps
+reconciliation partial; it is never expired by TTL. Repair the owning failure,
+then allow the next retry, or retry the original approved deletion command.
+Never invent publication acknowledgement or remove its pending-work binding.
+
+Control-metadata holds belong in the seeded \`data/policy.json\` descriptor and
+take effect with its governed deployment. They are checked before every
+maintenance invocation, independent of its retained cursor. Record-hold APIs
+create only product-record holds. Do not insert control holds directly into
+the product hold collection; it is not a global maintenance-authority surface.
+
+For restore, use point-in-time recovery into a new, separately identified table.
+Verify record integrity, encryption, access scope and replay/idempotency behavior
+before proposing a reviewed binding change. Do not automatically cut over,
+overwrite the original table, replay expired inbox messages or disable deletion
+protection. Retain measured recovery point/time and the rollback identity.
+
+${sql
+            ? `## Declared PostgreSQL
+
+The declared Aurora database additionally requires its migration checksums,
+backup identity, retained resource identity and deletion protection to be checked.
+Use the [database migration procedure](../runbooks.md#database-migration).
+Restore into a new resource and verify authorization and migrations before any
+reviewed traffic change; never edit an applied migration or replace production
+as an incidental repair.
+`
+            : `SQL is not declared. No Aurora investigation or SQL migration command is
+required for this Slice's DynamoDB recovery.
+`}
 `,
         'ebk-globals.d.ts': `import 'sst/resource';
 
 declare global {
+  type EbkSstOutput<T> = {
+    apply<U>(operation: (value: T) => U): EbkSstOutput<U>;
+  };
+  type EbkSstUnwrap<T> = T extends EbkSstOutput<infer U>
+    ? EbkSstUnwrap<U>
+    : T extends readonly (infer U)[]
+      ? EbkSstUnwrap<U>[]
+      : T extends Record<string, unknown>
+        ? { [K in keyof T]: EbkSstUnwrap<T[K]> }
+        : T;
   const sst: any;
   const aws: any;
   const $app: { name: string; stage: string };
@@ -202,6 +327,10 @@ declare global {
     ...values: unknown[]
   ) => unknown;
   const $jsonStringify: (value: unknown) => unknown;
+  const $output: (value: unknown) => any;
+  function $resolve<T extends Record<string, any>>(
+    value: T,
+  ): EbkSstOutput<EbkSstUnwrap<T>>;
   const $transform: any;
   const $util: any;
 }

package/src/generators/slice/built-in-plan-native-runtime-authority-files.d.ts

@@ -0,0 +1,2 @@
+/** @internal */
+export declare function renderStandardSliceNativeRuntimeAuthorityFiles(name: string, workspace: string, sql?: boolean): Readonly<Record<string, string>>;