@empire-builder-kit/nx 1.0.0-beta.9 → 1.0.0-rc.2

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

@@ -0,0 +1,1901 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDatabaseLifecycleFiles = renderDatabaseLifecycleFiles;
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+const frozen_container_js_1 = require("../workload/frozen-container.js");
+function renderDatabaseLifecycleLoggingHelper() {
+    return `export const DATABASE_LIFECYCLE_EVENT_CONTRACT = Object.freeze({
+  database_bootstrap_client_error: Object.freeze({
+    level: 'ERROR',
+    message: 'Database bootstrap client error',
+  }),
+  database_bootstrap_connection_retry: Object.freeze({
+    level: 'WARN',
+    message: 'Retrying database bootstrap connection',
+  }),
+  database_bootstrap_succeeded: Object.freeze({
+    level: 'INFO',
+    message: 'Database bootstrap succeeded',
+    outcome: 'success',
+  }),
+  database_bootstrap_failed: Object.freeze({
+    level: 'ERROR',
+    message: 'Database bootstrap failed',
+    outcome: 'failure',
+  }),
+  database_retirement_client_error: Object.freeze({
+    level: 'ERROR',
+    message: 'Database retirement client error',
+  }),
+  database_retirement_succeeded: Object.freeze({
+    level: 'INFO',
+    message: 'Database retirement succeeded',
+    outcome: 'success',
+  }),
+  database_retirement_failed: Object.freeze({
+    level: 'ERROR',
+    message: 'Database retirement failed',
+    outcome: 'failure',
+  }),
+  database_connection_retry: Object.freeze({
+    level: 'WARN',
+    message: 'Retrying database migration connection',
+  }),
+  database_client_error: Object.freeze({
+    level: 'ERROR',
+    message: 'Database migration client error',
+  }),
+  migration_skipped: Object.freeze({
+    level: 'INFO',
+    message: 'Database migration skipped',
+  }),
+  migration_applied: Object.freeze({
+    level: 'INFO',
+    message: 'Database migration applied',
+  }),
+  migration_rollback_failed: Object.freeze({
+    level: 'ERROR',
+    message: 'Database migration rollback failed',
+    outcome: 'failure',
+  }),
+  migration_completed: Object.freeze({
+    level: 'INFO',
+    message: 'Database migration completed',
+    outcome: 'success',
+  }),
+  migration_failed: Object.freeze({
+    level: 'ERROR',
+    message: 'Database migration failed',
+    outcome: 'failure',
+  }),
+});
+
+const LOG_RECORD_LIMIT_BYTES = 16 * 1024;
+const ATTRIBUTE_STRING_LIMIT = 256;
+const SAFE_ATTRIBUTE_KEYS = new Set([
+  'attempt',
+  'checksum',
+  'count',
+  'database',
+  'delayMs',
+  'elapsedMs',
+  'errorCode',
+  'errorName',
+  'name',
+  'phase',
+  'roleKind',
+]);
+const OPAQUE_ID_PATTERN = /^[A-Za-z0-9._:/-]{1,128}$/;
+
+const requiredIdentity = (value, field) => {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  if (
+    normalized.length === 0 ||
+    normalized.length > 128 ||
+    [...normalized].some((character) => {
+      const code = character.charCodeAt(0);
+      return code <= 31 || code === 127;
+    })
+  ) {
+    throw new Error('Database lifecycle logger ' + field + ' is invalid.');
+  }
+  return normalized;
+};
+const requiredOpaqueId = (value, field) => {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  if (!OPAQUE_ID_PATTERN.test(normalized)) {
+    throw new Error('Database lifecycle logger ' + field + ' is invalid.');
+  }
+  return normalized;
+};
+const boundedString = (value, truncation) => {
+  if (value.length <= ATTRIBUTE_STRING_LIMIT) return value;
+  truncation.truncatedStrings += 1;
+  const suffix = '…[truncated:' + (value.length - ATTRIBUTE_STRING_LIMIT) + ']';
+  return value.slice(0, ATTRIBUTE_STRING_LIMIT - suffix.length) + suffix;
+};
+const safeAttributes = (fields) => {
+  const attributes = {};
+  const truncation = { droppedKeys: 0, truncatedStrings: 0 };
+  let keys;
+  try {
+    keys = Object.keys(fields).sort();
+  } catch {
+    keys = [];
+    truncation.droppedKeys += 1;
+  }
+  for (const key of keys) {
+    if (!SAFE_ATTRIBUTE_KEYS.has(key)) {
+      truncation.droppedKeys += 1;
+      continue;
+    }
+    let value;
+    try {
+      value = fields[key];
+    } catch {
+      truncation.droppedKeys += 1;
+      continue;
+    }
+    if (typeof value === 'string') {
+      attributes[key] = boundedString(value, truncation);
+    } else if (typeof value === 'number' && Number.isFinite(value)) {
+      attributes[key] = value;
+    } else {
+      truncation.droppedKeys += 1;
+    }
+  }
+  if (truncation.droppedKeys || truncation.truncatedStrings) {
+    attributes.ebkTruncation = {
+      ...(truncation.droppedKeys
+        ? { droppedKeys: truncation.droppedKeys }
+        : {}),
+      ...(truncation.truncatedStrings
+        ? { truncatedStrings: truncation.truncatedStrings }
+        : {}),
+    };
+  }
+  return attributes;
+};
+const timestamp = (now) => {
+  try {
+    const value = now();
+    if (!Number.isNaN(value.getTime())) return value.toISOString();
+  } catch {
+    // Logging never replaces the database lifecycle result.
+  }
+  return new Date().toISOString();
+};
+const encodedBytes = (record) =>
+  Buffer.byteLength(JSON.stringify(record), 'utf8');
+const fitRecord = (record) => {
+  const attributes = { ...record.attributes };
+  let result = { ...record, attributes };
+  while (encodedBytes(result) > LOG_RECORD_LIMIT_BYTES) {
+    const removable = Object.keys(attributes)
+      .filter(
+        (key) =>
+          key !== 'databaseLifecycleId' &&
+          key !== 'ebkTruncation' &&
+          key !== 'lifecycleEvent',
+      )
+      .sort()
+      .at(-1);
+    if (!removable) break;
+    delete attributes[removable];
+    const truncation = attributes.ebkTruncation ?? {};
+    attributes.ebkTruncation = {
+      ...truncation,
+      recordKeysDropped: (truncation.recordKeysDropped ?? 0) + 1,
+    };
+    result = { ...record, attributes };
+  }
+  return result;
+};
+
+export const createDatabaseLifecycleLogger = ({
+  component,
+  correlationId,
+  databaseLifecycleId,
+  now = () => new Date(),
+  operation,
+  slice,
+  stage,
+  streams = { stderr: process.stderr, stdout: process.stdout },
+  workspace,
+}) => {
+  const identity = {
+    component: requiredIdentity(component, 'component'),
+    correlationId: requiredOpaqueId(correlationId, 'correlationId'),
+    databaseLifecycleId: requiredOpaqueId(
+      databaseLifecycleId,
+      'databaseLifecycleId',
+    ),
+    operation: requiredIdentity(operation, 'operation'),
+    slice: requiredIdentity(slice, 'slice'),
+    stage: requiredIdentity(stage, 'stage'),
+    workspace: requiredIdentity(workspace, 'workspace'),
+  };
+
+  return {
+    emit(lifecycleEvent, fields = {}) {
+      if (
+        !Object.prototype.hasOwnProperty.call(
+          DATABASE_LIFECYCLE_EVENT_CONTRACT,
+          lifecycleEvent,
+        )
+      ) {
+        throw new Error(
+          'Unsupported database lifecycle event: ' + String(lifecycleEvent),
+        );
+      }
+      const definition = DATABASE_LIFECYCLE_EVENT_CONTRACT[lifecycleEvent];
+      const record = fitRecord({
+        schemaVersion: 1,
+        timestamp: timestamp(now),
+        level: definition.level,
+        message: definition.message,
+        workspace: identity.workspace,
+        stage: identity.stage,
+        slice: identity.slice,
+        feature: 'database-lifecycle',
+        component: identity.component,
+        operation: identity.operation,
+        ...(definition.outcome ? { outcome: definition.outcome } : {}),
+        correlationId: identity.correlationId,
+        attributes: {
+          databaseLifecycleId: identity.databaseLifecycleId,
+          lifecycleEvent,
+          ...safeAttributes(fields),
+        },
+      });
+      const stream =
+        definition.level === 'WARN' ||
+        definition.level === 'ERROR' ||
+        definition.level === 'FATAL'
+          ? streams.stderr
+          : streams.stdout;
+      try {
+        stream.write(JSON.stringify(record) + '\\n');
+      } catch {
+        // Logging never replaces the database lifecycle result.
+      }
+      return record;
+    },
+  };
+};
+`;
+}
+/** @internal */
+function renderDatabaseLifecycleFiles(name) {
+    return {
+        '.dockerignore': `.sst
+.env
+.env.*
+!.env.example
+dist
+node_modules
+web/.next
+web/.open-next
+`,
+        'database/bindings.json': (0, built_in_plan_shared_js_1.json)({
+            primary: {
+                active: 'primary',
+                provisioned: ['primary'],
+            },
+        }),
+        'migration/Dockerfile': `FROM ${frozen_container_js_1.WORKLOAD_CONTAINER_NODE_IMAGE} AS build
+ARG NPM_CONFIG_REGISTRY=https://registry.npmjs.org
+ENV COREPACK_NPM_REGISTRY=$NPM_CONFIG_REGISTRY
+ENV NPM_CONFIG_REGISTRY=$NPM_CONFIG_REGISTRY
+ENV PNPM_HOME=/pnpm
+ENV PATH=/pnpm:$PATH
+WORKDIR /workspace
+RUN corepack enable && corepack prepare ${frozen_container_js_1.WORKLOAD_CONTAINER_PNPM_DESCRIPTOR} --activate
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN pnpm fetch --frozen-lockfile
+COPY packages/${name}/migration/package.json packages/${name}/migration/package.json
+RUN pnpm --filter @ebk-migration/${name} install --offline --frozen-lockfile
+RUN --network=none pnpm --config.inject-workspace-packages=true --config.store-dir=/workspace/.ebk/cache/pnpm-store --filter @ebk-migration/${name} deploy --prod --offline --frozen-lockfile /opt/migration
+
+FROM ${frozen_container_js_1.WORKLOAD_CONTAINER_NODE_IMAGE}
+WORKDIR /app
+ADD --checksum=sha256:e5bb2084ccf45087bda1c9bffdea0eb15ee67f0b91646106e466714f9de3c7e3 https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem ./rds-global-bundle.pem
+COPY --from=build --chown=node:node /opt/migration ./
+COPY --chown=node:node packages/${name}/jobs/database-lifecycle-logging.mjs ./jobs/database-lifecycle-logging.mjs
+COPY --chown=node:node packages/${name}/jobs/bootstrap-database.mjs ./jobs/bootstrap-database.mjs
+COPY --chown=node:node packages/${name}/jobs/migrate-database.mjs ./jobs/migrate-database.mjs
+COPY --chown=node:node packages/${name}/jobs/retire-database.mjs ./jobs/retire-database.mjs
+COPY --chown=node:node packages/${name}/database/migrations ./database/migrations
+USER node
+CMD ["node", "jobs/migrate-database.mjs"]
+`,
+        'migration/package.json': (0, built_in_plan_shared_js_1.json)({
+            name: `@ebk-migration/${name}`,
+            version: '0.0.0',
+            private: true,
+            type: 'module',
+            dependencies: {
+                '@aws-sdk/client-secrets-manager': '3.1090.0',
+                '@aws-sdk/client-sfn': '3.1090.0',
+                '@aws-sdk/rds-signer': '3.1090.0',
+                pg: '8.22.0',
+            },
+        }),
+        'jobs/database-lifecycle-logging.mjs': renderDatabaseLifecycleLoggingHelper(),
+        'jobs/bootstrap-database.mjs': `import { randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import {
+  GetSecretValueCommand,
+  PutSecretValueCommand,
+  SecretsManagerClient,
+} from '@aws-sdk/client-secrets-manager';
+import { Signer } from '@aws-sdk/rds-signer';
+import pg from 'pg';
+import { createDatabaseLifecycleLogger } from './database-lifecycle-logging.mjs';
+
+const { Client } = pg;
+const required = (name) => {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(name + ' is required.');
+  return value;
+};
+const requiredIdentifier = (name) => {
+  const value = required(name);
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(value)) {
+    throw new Error(name + ' must be a normalized PostgreSQL identifier.');
+  }
+  return value;
+};
+const requiredPort = () => {
+  const value = required('EBK_DATABASE_PORT');
+  if (!/^\\d+$/.test(value)) {
+    throw new Error('EBK_DATABASE_PORT must be an integer.');
+  }
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    throw new Error('EBK_DATABASE_PORT must be from 1 through 65535.');
+  }
+  return port;
+};
+let bootstrapId = 'unresolved';
+let bootstrapPhase = 'configuration';
+let bootstrapLockClient;
+let bootstrapLockKey;
+let lifecycleLogger;
+
+const log = (event, fields = {}) => lifecycleLogger?.emit(event, fields);
+const safeErrorFields = (error) => {
+  const name = error instanceof Error ? error.name : 'UnknownError';
+  const code =
+    error &&
+    typeof error === 'object' &&
+    typeof error.code === 'string' &&
+    /^[A-Z0-9_]{2,32}$/.test(error.code)
+      ? error.code
+      : undefined;
+  return {
+    errorName: name.replace(/[^A-Za-z0-9_.-]/g, '').slice(0, 80) || 'Error',
+    ...(code ? { errorCode: code } : {}),
+  };
+};
+const retryableConnection = (error) => {
+  const code = error && typeof error === 'object' ? error.code : undefined;
+  const message = error instanceof Error ? error.message : String(error);
+  return new Set([
+    '08000',
+    '08001',
+    '08003',
+    '08006',
+    '57P03',
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+  ]).has(code) ||
+    /resum|starting up|temporarily unavailable|timeout|connection terminated unexpectedly|server closed the connection unexpectedly|terminating connection/i.test(message);
+};
+const sleep = (milliseconds) =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));
+const quoteIdentifier = (value) => {
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(value)) {
+    throw new Error('Unsafe PostgreSQL identifier.');
+  }
+  return '"' + value + '"';
+};
+const quoteLiteral = (value) => "'" + value.replaceAll("'", "''") + "'";
+const generatePassword = () =>
+  randomBytes(24)
+    .toString('base64')
+    .replace(/[^A-Za-z0-9]/g, '')
+    .slice(0, 32)
+    .padEnd(32, 'a');
+
+const secrets = new SecretsManagerClient({});
+const readJsonSecret = async (secretArn, missingAllowed = false) => {
+  try {
+    const result = await secrets.send(
+      new GetSecretValueCommand({ SecretId: secretArn }),
+    );
+    if (!result.SecretString) {
+      throw new Error('Secret must contain a JSON SecretString.');
+    }
+    const value = JSON.parse(result.SecretString);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error('Secret JSON must be an object.');
+    }
+    return value;
+  } catch (error) {
+    if (
+      missingAllowed &&
+      error &&
+      typeof error === 'object' &&
+      error.name === 'ResourceNotFoundException'
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+};
+const runtimeCredential = async ({
+  database,
+  host,
+  port,
+  rotationToken,
+  secretArn,
+  username,
+}) => {
+  const current = await readJsonSecret(secretArn, true);
+  const identityMatches =
+    current &&
+    current.database === database &&
+    current.username === username &&
+    typeof current.password === 'string' &&
+    /^[A-Za-z0-9]{32}$/.test(current.password);
+  if (current && !identityMatches) {
+    throw new Error('Existing generated database credential has incompatible metadata.');
+  }
+  const rotate =
+    rotationToken !== '' && current?.rotationToken !== rotationToken;
+  const connectionMetadataChanged =
+    current && (current.host !== host || current.port !== port);
+  return {
+    needsWrite: !current || rotate || connectionMetadataChanged,
+    password: !current || rotate ? generatePassword() : current.password,
+  };
+};
+const writeRuntimeCredential = async ({
+  database,
+  host,
+  password,
+  port,
+  rotationToken,
+  secretArn,
+  username,
+}) => {
+  await secrets.send(
+    new PutSecretValueCommand({
+      SecretId: secretArn,
+      SecretString: JSON.stringify({
+        database,
+        host,
+        password,
+        port,
+        ...(rotationToken ? { rotationToken } : {}),
+        username,
+      }),
+    }),
+  );
+};
+const publishRuntimeCredentials = async ({
+  database,
+  host,
+  port,
+  readonly,
+  readonlySecretArn,
+  readonlyRole,
+  readwrite,
+  readwriteSecretArn,
+  readwriteRole,
+  rotationToken,
+}) => {
+  if (readwrite.needsWrite) {
+    await writeRuntimeCredential({
+      database,
+      host,
+      password: readwrite.password,
+      port,
+      rotationToken,
+      secretArn: readwriteSecretArn,
+      username: readwriteRole,
+    });
+  }
+  if (readonly.needsWrite) {
+    await writeRuntimeCredential({
+      database,
+      host,
+      password: readonly.password,
+      port,
+      rotationToken,
+      secretArn: readonlySecretArn,
+      username: readonlyRole,
+    });
+  }
+};
+const connectWithRetry = async ({
+  database,
+  host,
+  password,
+  port,
+  roleKind,
+  username,
+  ssl,
+}) => {
+  const startedAt = Date.now();
+  let lastError;
+  for (let attempt = 1; attempt <= 10; attempt += 1) {
+    let candidate;
+    try {
+      candidate = new Client({
+        connectionTimeoutMillis: 10_000,
+        database,
+        host,
+        password:
+          typeof password === 'function' ? await password() : password,
+        port,
+        ssl: { ca: ssl, rejectUnauthorized: true },
+        statement_timeout: 10 * 60 * 1000,
+        user: username,
+      });
+      candidate.on('error', (error) => {
+        log('database_bootstrap_client_error', {
+          roleKind,
+          ...safeErrorFields(error),
+        });
+      });
+      await candidate.connect();
+      return candidate;
+    } catch (error) {
+      lastError = error;
+      await candidate?.end().catch(() => undefined);
+      if (!retryableConnection(error) || attempt === 10) throw error;
+      log('database_bootstrap_connection_retry', {
+        attempt,
+        elapsedMs: Date.now() - startedAt,
+        roleKind,
+        ...safeErrorFields(error),
+      });
+      await sleep(Math.min(attempt * 5_000, 30_000));
+    }
+  }
+  throw lastError;
+};
+const roleExists = async (client, role) => {
+  const result = await client.query(
+    'SELECT 1 FROM pg_roles WHERE rolname = ' + quoteLiteral(role),
+  );
+  return result.rowCount > 0;
+};
+const executeStatements = async (client, statements) => {
+  for (const statement of statements) await client.query(statement);
+};
+const releaseBootstrapLock = async () => {
+  const client = bootstrapLockClient;
+  const key = bootstrapLockKey;
+  bootstrapLockClient = undefined;
+  bootstrapLockKey = undefined;
+  if (!client) return;
+  if (key) {
+    await client
+      .query('SELECT pg_advisory_unlock(hashtextextended($1, 0))', [key])
+      .catch(() => undefined);
+  }
+  await client.end().catch(() => undefined);
+};
+
+async function main() {
+  bootstrapId = required('EBK_BOOTSTRAP_ID');
+  lifecycleLogger = createDatabaseLifecycleLogger({
+    component: 'database-bootstrap',
+    correlationId: required('EBK_DATABASE_LIFECYCLE_CORRELATION_ID'),
+    databaseLifecycleId: bootstrapId,
+    operation: 'database.bootstrap',
+    slice: '${name}',
+    stage: required('EBK_STAGE'),
+    workspace: required('EBK_WORKSPACE'),
+  });
+  const database = requiredIdentifier('EBK_DATABASE_NAME');
+  const host = required('EBK_DATABASE_HOST');
+  const masterSecretArn = required('EBK_MASTER_SECRET_ARN');
+  const migratorRole = requiredIdentifier('EBK_DATABASE_MIGRATOR_ROLE');
+  const port = requiredPort();
+  const readonlyRole = requiredIdentifier('EBK_DATABASE_READONLY_ROLE');
+  const readonlySecretArn = required('EBK_READONLY_SECRET_ARN');
+  const readwriteRole = requiredIdentifier('EBK_DATABASE_READWRITE_ROLE');
+  const readwriteSecretArn = required('EBK_READWRITE_SECRET_ARN');
+  const region = required('AWS_REGION');
+  const rotationToken = process.env.EBK_DATABASE_ROTATION_TOKEN?.trim() ?? '';
+  const runtimeHost = required('EBK_RUNTIME_DATABASE_HOST');
+  const ca = await readFile(required('EBK_RDS_CA_BUNDLE'), 'utf8');
+
+  bootstrapPhase = 'credential-resolution';
+  const master = await readJsonSecret(masterSecretArn);
+  if (
+    typeof master.username !== 'string' ||
+    typeof master.password !== 'string' ||
+    master.password.length === 0
+  ) {
+    throw new Error('Foundation master secret lacks username or password.');
+  }
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(master.username)) {
+    throw new Error('Foundation master secret username is invalid.');
+  }
+  const masterUsername = master.username;
+
+  bootstrapPhase = 'database-convergence';
+  const postgres = await connectWithRetry({
+    database: 'postgres',
+    host,
+    password: master.password,
+    port,
+    roleKind: 'master',
+    ssl: ca,
+    username: masterUsername,
+  });
+  bootstrapLockClient = postgres;
+  bootstrapLockKey = 'ebk-bootstrap:' + database;
+  await postgres.query(
+    'SELECT pg_advisory_lock(hashtextextended($1, 0))',
+    [bootstrapLockKey],
+  );
+  bootstrapPhase = 'credential-resolution';
+  const readwrite = await runtimeCredential({
+    database,
+    host: runtimeHost,
+    port,
+    rotationToken,
+    secretArn: readwriteSecretArn,
+    username: readwriteRole,
+  });
+  const readonly = await runtimeCredential({
+    database,
+    host: runtimeHost,
+    port,
+    rotationToken,
+    secretArn: readonlySecretArn,
+    username: readonlyRole,
+  });
+
+  bootstrapPhase = 'database-convergence';
+  const existing = await postgres.query(
+    'SELECT 1 FROM pg_database WHERE datname = ' + quoteLiteral(database),
+  );
+  if (existing.rowCount === 0) {
+    await postgres.query('CREATE DATABASE ' + quoteIdentifier(database));
+  }
+
+  const masterDatabase = await connectWithRetry({
+    database,
+    host,
+    password: master.password,
+    port,
+    roleKind: 'master',
+    ssl: ca,
+    username: masterUsername,
+  });
+  try {
+    for (const [role, password] of [
+      [readwriteRole, readwrite.password],
+      [readonlyRole, readonly.password],
+    ]) {
+      if (await roleExists(masterDatabase, role)) {
+        await masterDatabase.query(
+          'ALTER ROLE ' + quoteIdentifier(role) + ' WITH LOGIN PASSWORD ' + quoteLiteral(password),
+        );
+      } else {
+        await masterDatabase.query(
+          'CREATE ROLE ' + quoteIdentifier(role) + ' WITH LOGIN PASSWORD ' + quoteLiteral(password),
+        );
+      }
+    }
+    if (await roleExists(masterDatabase, migratorRole)) {
+      await masterDatabase.query(
+        'ALTER ROLE ' + quoteIdentifier(migratorRole) + ' WITH LOGIN PASSWORD NULL',
+      );
+    } else {
+      await masterDatabase.query(
+        'CREATE ROLE ' + quoteIdentifier(migratorRole) + ' WITH LOGIN',
+      );
+    }
+
+    // PostgreSQL 16+ can record creator ADMIN memberships when a CREATEROLE
+    // principal creates a role. Keep that non-inheriting administration path
+    // available for the membership grants below, but explicitly remove SET
+    // and INHERIT options before the migrator receives rds_iam. Default
+    // privileges are then converged through direct role-owned sessions.
+    await executeStatements(masterDatabase, [
+      'REVOKE INHERIT OPTION FOR ' + quoteIdentifier(migratorRole) +
+        ' FROM CURRENT_USER',
+      'REVOKE SET OPTION FOR ' + quoteIdentifier(migratorRole) +
+        ' FROM CURRENT_USER',
+      'REVOKE INHERIT OPTION FOR ' + quoteIdentifier(readwriteRole) +
+        ' FROM CURRENT_USER',
+      'REVOKE SET OPTION FOR ' + quoteIdentifier(readwriteRole) +
+        ' FROM CURRENT_USER',
+      'REVOKE ALL ON DATABASE ' + quoteIdentifier(database) + ' FROM PUBLIC',
+      'REVOKE CREATE ON DATABASE ' + quoteIdentifier(database) + ' FROM ' +
+        quoteIdentifier(migratorRole) + ', ' + quoteIdentifier(readwriteRole),
+      'GRANT CONNECT ON DATABASE ' + quoteIdentifier(database) + ' TO ' +
+        quoteIdentifier(migratorRole) + ', ' + quoteIdentifier(readwriteRole) +
+        ', ' + quoteIdentifier(readonlyRole),
+      'GRANT ALL ON SCHEMA public TO ' + quoteIdentifier(migratorRole) +
+        ', ' + quoteIdentifier(readwriteRole),
+      'GRANT USAGE ON SCHEMA public TO ' + quoteIdentifier(readonlyRole),
+      'GRANT rds_iam TO ' + quoteIdentifier(migratorRole),
+      'GRANT ' + quoteIdentifier(readwriteRole) + ' TO ' +
+        quoteIdentifier(migratorRole),
+    ]);
+  } finally {
+    await masterDatabase.end().catch(() => undefined);
+  }
+
+  // Publish immediately after ALTER ROLE convergence. A database password and
+  // Secrets Manager AWSCURRENT cannot change atomically, so keep this
+  // serialized stale window ahead of slower default-privilege work. Runtime
+  // authentication failure invalidates the bounded cache and retries once.
+  bootstrapPhase = 'runtime-secret-publication';
+  await publishRuntimeCredentials({
+    database,
+    host: runtimeHost,
+    port,
+    readonly,
+    readonlySecretArn,
+    readonlyRole,
+    readwrite,
+    readwriteSecretArn,
+    readwriteRole,
+    rotationToken,
+  });
+
+  bootstrapPhase = 'default-privilege-convergence';
+  const readwriteDatabase = await connectWithRetry({
+    database,
+    host,
+    password: readwrite.password,
+    port,
+    roleKind: 'readwrite',
+    ssl: ca,
+    username: readwriteRole,
+  });
+  try {
+    await executeStatements(readwriteDatabase, [
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO ' +
+        quoteIdentifier(readwriteRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ' +
+        quoteIdentifier(readonlyRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ' +
+        quoteIdentifier(readonlyRole),
+    ]);
+  } finally {
+    await readwriteDatabase.end().catch(() => undefined);
+  }
+
+  const signer = new Signer({
+    hostname: host,
+    port,
+    region,
+    username: migratorRole,
+  });
+  const migratorDatabase = await connectWithRetry({
+    database,
+    host,
+    password: () => signer.getAuthToken(),
+    port,
+    roleKind: 'migrator',
+    ssl: ca,
+    username: migratorRole,
+  });
+  try {
+    await executeStatements(migratorDatabase, [
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO ' +
+        quoteIdentifier(readwriteRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ' +
+        quoteIdentifier(readonlyRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO ' +
+        quoteIdentifier(readwriteRole),
+      'ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ' +
+        quoteIdentifier(readonlyRole),
+    ]);
+  } finally {
+    await migratorDatabase.end().catch(() => undefined);
+  }
+
+  await releaseBootstrapLock();
+  log('database_bootstrap_succeeded', { database });
+}
+
+main().catch(async (error) => {
+  await releaseBootstrapLock();
+  log('database_bootstrap_failed', {
+    phase: bootstrapPhase,
+    ...safeErrorFields(error),
+  });
+  process.exitCode = 1;
+});
+`,
+        'jobs/retire-database.mjs': `import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import {
+  DeleteSecretCommand,
+  DescribeSecretCommand,
+  GetSecretValueCommand,
+  SecretsManagerClient,
+} from '@aws-sdk/client-secrets-manager';
+import {
+  SendTaskFailureCommand,
+  SendTaskSuccessCommand,
+  SFNClient,
+} from '@aws-sdk/client-sfn';
+import pg from 'pg';
+import { createDatabaseLifecycleLogger } from './database-lifecycle-logging.mjs';
+
+const { Client } = pg;
+const FIXED_DATABASE_IDENTIFIER = 'retirement_rehearsal';
+const FIXED_STAGE = 'development';
+const MAX_CALLBACK_BYTES = 64 * 1024;
+const MAX_RETAINED_SIBLINGS = 32;
+const SECRET_ABSENCE_POLL_INTERVAL_MS = 2_000;
+const SECRET_ABSENCE_TIMEOUT_MS = 10 * 60 * 1_000;
+const IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+const DATABASE_IDENTIFIER_PATTERN =
+  /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
+const CANDIDATE_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+const COMMIT_PATTERN = /^[a-f0-9]{40}$/;
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+const SECRET_ARN_PATTERN =
+  /^arn:(aws|aws-us-gov|aws-cn):secretsmanager:[a-z0-9-]+:\\d{12}:secret:[A-Za-z0-9/_+=.@-]+$/;
+const SAFE_FAILURE_CODE_PATTERN = /^[A-Z0-9_]{2,32}$/;
+const SAFE_ERROR_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,80}$/;
+
+const required = (environment, name) => {
+  const value = environment[name]?.trim();
+  if (!value) throw new Error(name + ' is required.');
+  return value;
+};
+const requiredExact = (environment, name, expected) => {
+  const value = required(environment, name);
+  if (value !== expected) {
+    throw new Error(name + ' must equal the fixed generated value.');
+  }
+  return value;
+};
+const requiredIdentifier = (environment, name) => {
+  const value = required(environment, name);
+  if (!IDENTIFIER_PATTERN.test(value)) {
+    throw new Error(name + ' must be a normalized PostgreSQL identifier.');
+  }
+  return value;
+};
+const requiredPort = (environment) => {
+  const value = required(environment, 'EBK_DATABASE_PORT');
+  if (!/^\\d+$/.test(value)) {
+    throw new Error('EBK_DATABASE_PORT must be an integer.');
+  }
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    throw new Error('EBK_DATABASE_PORT must be from 1 through 65535.');
+  }
+  return port;
+};
+const safeErrorFields = (error) => {
+  const name = error instanceof Error ? error.name : 'UnknownError';
+  const code =
+    error &&
+    typeof error === 'object' &&
+    typeof error.code === 'string' &&
+    /^[A-Z0-9_]{2,32}$/.test(error.code)
+      ? error.code
+      : undefined;
+  return {
+    errorName: name.replace(/[^A-Za-z0-9_.-]/g, '').slice(0, 80) || 'Error',
+    ...(code ? { errorCode: code } : {}),
+  };
+};
+const callbackFailure = (phase, error) => {
+  const fields = safeErrorFields(error);
+  return {
+    cause: JSON.stringify({
+      errorCode:
+        typeof fields.errorCode === 'string' &&
+        SAFE_FAILURE_CODE_PATTERN.test(fields.errorCode)
+          ? fields.errorCode
+          : undefined,
+      errorName: fields.errorName,
+      phase,
+    }).slice(0, 32 * 1024),
+    error: SAFE_ERROR_NAME_PATTERN.test(fields.errorName)
+      ? fields.errorName
+      : 'DatabaseRetirementError',
+  };
+};
+const quoteIdentifier = (value) => {
+  if (!IDENTIFIER_PATTERN.test(value)) {
+    throw new Error('Unsafe PostgreSQL identifier.');
+  }
+  return '"' + value + '"';
+};
+const requiredPattern = (environment, name, pattern) => {
+  const value = required(environment, name);
+  if (!pattern.test(value)) {
+    throw new Error(name + ' is invalid.');
+  }
+  return value;
+};
+const requiredSecretArn = (environment, name) =>
+  requiredPattern(environment, name, SECRET_ARN_PATTERN);
+const requiredTaskToken = (environment) => {
+  const value = required(environment, 'EBK_STEP_FUNCTIONS_TASK_TOKEN');
+  if (Buffer.byteLength(value, 'utf8') > 1024) {
+    throw new Error(
+      'EBK_STEP_FUNCTIONS_TASK_TOKEN exceeds the Step Functions limit.',
+    );
+  }
+  return value;
+};
+const expectedDatabaseName = (slice, databaseIdentifier) =>
+  [FIXED_STAGE, slice, databaseIdentifier]
+    .join('_')
+    .replaceAll('-', '_');
+const expectedSecretPath = (slice, databaseIdentifier, kind) =>
+  ':secret:ebk/' +
+  FIXED_STAGE +
+  '/' +
+  slice +
+  '/database/' +
+  databaseIdentifier +
+  '/' +
+  kind +
+  '-';
+const requireExactDatabaseResources = ({
+  databaseIdentifier,
+  databaseName,
+  migratorRole,
+  readonlyRole,
+  readonlySecretArn,
+  readwriteRole,
+  readwriteSecretArn,
+  slice,
+}) => {
+  const expectedDatabase = expectedDatabaseName(slice, databaseIdentifier);
+  if (
+    databaseName !== expectedDatabase ||
+    migratorRole !== expectedDatabase + '_migrator' ||
+    readonlyRole !== expectedDatabase + '_readonly' ||
+    readwriteRole !== expectedDatabase + '_readwrite' ||
+    !readonlySecretArn.includes(
+      expectedSecretPath(slice, databaseIdentifier, 'readonly'),
+    ) ||
+    !readwriteSecretArn.includes(
+      expectedSecretPath(slice, databaseIdentifier, 'readwrite'),
+    )
+  ) {
+    throw new Error(
+      'Database retirement resources differ from the exact generated identity.',
+    );
+  }
+};
+const readJsonSecret = async (secrets, secretArn) => {
+  const result = await secrets.send(
+    new GetSecretValueCommand({ SecretId: secretArn }),
+  );
+  if (!result.SecretString) {
+    throw new Error('Secret must contain a JSON SecretString.');
+  }
+  const value = JSON.parse(result.SecretString);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Secret JSON must be an object.');
+  }
+  return value;
+};
+const secretDoesNotExist = (error) =>
+  error &&
+  typeof error === 'object' &&
+  error.name === 'ResourceNotFoundException';
+const normalizedDate = (value) =>
+  value instanceof Date
+    ? value.toISOString()
+    : typeof value === 'string'
+      ? value
+      : undefined;
+const describeSecretMetadata = async (secrets, secretArn) => {
+  try {
+    const result = await secrets.send(
+      new DescribeSecretCommand({ SecretId: secretArn }),
+    );
+    return {
+      arn: result.ARN ?? secretArn,
+      createdDate: normalizedDate(result.CreatedDate),
+      deletedDate: normalizedDate(result.DeletedDate),
+      exists: true,
+      lastChangedDate: normalizedDate(result.LastChangedDate),
+      name: result.Name ?? '',
+      rotationEnabled: result.RotationEnabled === true,
+      versions: Object.entries(result.VersionIdsToStages ?? {})
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([version, stages]) => [
+          version,
+          [...(stages ?? [])].sort(),
+        ]),
+    };
+  } catch (error) {
+    if (secretDoesNotExist(error)) {
+      return { arn: secretArn, exists: false };
+    }
+    throw error;
+  }
+};
+const stableJson = (value) => JSON.stringify(value);
+const fingerprint = (value) =>
+  createHash('sha256').update(stableJson(value), 'utf8').digest('hex');
+const queryDatabaseMetadata = async (postgres, databaseName) => {
+  const result = await postgres.query(
+    'SELECT oid::text, datname, encoding, datcollate, datctype, datistemplate, ' +
+      'datallowconn, datconnlimit FROM pg_database WHERE datname = $1',
+    [databaseName],
+  );
+  return result.rows[0] ?? null;
+};
+const queryRoleMetadata = async (postgres, roles) => {
+  const result = await postgres.query(
+    'SELECT oid::text, rolname, rolcanlogin, rolinherit, rolcreatedb, ' +
+      'rolcreaterole, rolreplication, rolbypassrls, rolconnlimit, ' +
+      'rolvaliduntil::text FROM pg_roles WHERE rolname = ANY($1::text[]) ' +
+      'ORDER BY rolname',
+    [roles],
+  );
+  return result.rows;
+};
+const siblingFingerprint = async (postgres, secrets, sibling) =>
+  fingerprint({
+    database: await queryDatabaseMetadata(postgres, sibling.databaseName),
+    databaseIdentifier: sibling.databaseIdentifier,
+    roles: await queryRoleMetadata(postgres, [
+      sibling.migratorRole,
+      sibling.readonlyRole,
+      sibling.readwriteRole,
+    ]),
+    secrets: {
+      readonly: await describeSecretMetadata(
+        secrets,
+        sibling.readonlySecretArn,
+      ),
+      readwrite: await describeSecretMetadata(
+        secrets,
+        sibling.readwriteSecretArn,
+      ),
+    },
+  });
+const fingerprintSiblings = async (postgres, secrets, siblings) =>
+  Object.fromEntries(
+    await Promise.all(
+      siblings.map(async (sibling) => [
+        sibling.databaseIdentifier,
+        await siblingFingerprint(postgres, secrets, sibling),
+      ]),
+    ),
+  );
+const requireRetainedSiblings = (environment, slice) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(required(environment, 'EBK_RETAINED_SIBLINGS'));
+  } catch {
+    throw new Error('EBK_RETAINED_SIBLINGS must be valid JSON.');
+  }
+  if (
+    !Array.isArray(parsed) ||
+    parsed.length < 1 ||
+    parsed.length > MAX_RETAINED_SIBLINGS
+  ) {
+    throw new Error(
+      'EBK_RETAINED_SIBLINGS must contain from 1 through ' +
+        MAX_RETAINED_SIBLINGS +
+        ' exact siblings.',
+    );
+  }
+  const expectedKeys = [
+    'databaseIdentifier',
+    'databaseName',
+    'migratorRole',
+    'readonlyRole',
+    'readonlySecretArn',
+    'readwriteRole',
+    'readwriteSecretArn',
+  ];
+  const siblings = parsed.map((value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error('Every retained sibling must be an object.');
+    }
+    const keys = Object.keys(value).sort();
+    if (
+      keys.length !== expectedKeys.length ||
+      keys.some((key, index) => key !== [...expectedKeys].sort()[index])
+    ) {
+      throw new Error(
+        'Every retained sibling must contain only exact generated resources.',
+      );
+    }
+    const databaseIdentifier =
+      typeof value.databaseIdentifier === 'string'
+        ? value.databaseIdentifier
+        : '';
+    if (
+      !DATABASE_IDENTIFIER_PATTERN.test(databaseIdentifier) ||
+      databaseIdentifier === FIXED_DATABASE_IDENTIFIER
+    ) {
+      throw new Error('Retained sibling database identifier is invalid.');
+    }
+    const sibling = {
+      databaseIdentifier,
+      databaseName:
+        typeof value.databaseName === 'string' ? value.databaseName : '',
+      migratorRole:
+        typeof value.migratorRole === 'string' ? value.migratorRole : '',
+      readonlyRole:
+        typeof value.readonlyRole === 'string' ? value.readonlyRole : '',
+      readonlySecretArn:
+        typeof value.readonlySecretArn === 'string'
+          ? value.readonlySecretArn
+          : '',
+      readwriteRole:
+        typeof value.readwriteRole === 'string' ? value.readwriteRole : '',
+      readwriteSecretArn:
+        typeof value.readwriteSecretArn === 'string'
+          ? value.readwriteSecretArn
+          : '',
+    };
+    for (const field of [
+      'databaseName',
+      'migratorRole',
+      'readonlyRole',
+      'readwriteRole',
+    ]) {
+      if (!IDENTIFIER_PATTERN.test(sibling[field])) {
+        throw new Error('Retained sibling ' + field + ' is invalid.');
+      }
+    }
+    for (const field of ['readonlySecretArn', 'readwriteSecretArn']) {
+      if (!SECRET_ARN_PATTERN.test(sibling[field])) {
+        throw new Error('Retained sibling ' + field + ' is invalid.');
+      }
+    }
+    requireExactDatabaseResources({ ...sibling, slice });
+    return sibling;
+  });
+  const identifiers = siblings.map(({ databaseIdentifier }) =>
+    databaseIdentifier,
+  );
+  if (new Set(identifiers).size !== identifiers.length) {
+    throw new Error('Retained sibling identities must be unique.');
+  }
+  return siblings.sort((left, right) =>
+    left.databaseIdentifier < right.databaseIdentifier
+      ? -1
+      : left.databaseIdentifier > right.databaseIdentifier
+        ? 1
+        : 0,
+  );
+};
+const resourceExistence = async ({
+  databaseName,
+  migratorRole,
+  postgres,
+  readonlyRole,
+  readonlySecretArn,
+  readwriteRole,
+  readwriteSecretArn,
+  secrets,
+}) => {
+  const database = await queryDatabaseMetadata(postgres, databaseName);
+  const roles = new Set(
+    (
+      await queryRoleMetadata(postgres, [
+        migratorRole,
+        readonlyRole,
+        readwriteRole,
+      ])
+    ).map(({ rolname }) => rolname),
+  );
+  return {
+    databaseExists: database !== null,
+    migratorRoleExists: roles.has(migratorRole),
+    readonlyRoleExists: roles.has(readonlyRole),
+    readonlySecretExists: (
+      await describeSecretMetadata(secrets, readonlySecretArn)
+    ).exists,
+    readwriteRoleExists: roles.has(readwriteRole),
+    readwriteSecretExists: (
+      await describeSecretMetadata(secrets, readwriteSecretArn)
+    ).exists,
+  };
+};
+const deleteExactSecret = async (secrets, secretArn) => {
+  try {
+    await secrets.send(
+      new DeleteSecretCommand({
+        ForceDeleteWithoutRecovery: true,
+        SecretId: secretArn,
+      }),
+    );
+  } catch (error) {
+    if (!secretDoesNotExist(error)) throw error;
+  }
+};
+const waitForSecretAbsence = async ({
+  now,
+  secretArns,
+  secrets,
+  sleep,
+}) => {
+  const deadline = now() + SECRET_ABSENCE_TIMEOUT_MS;
+  while (true) {
+    const descriptions = await Promise.all(
+      secretArns.map((secretArn) =>
+        describeSecretMetadata(secrets, secretArn),
+      ),
+    );
+    if (descriptions.every(({ exists }) => !exists)) return;
+    if (now() >= deadline) {
+      throw new Error(
+        'Timed out proving exact generated credential-container absence.',
+      );
+    }
+    await sleep(SECRET_ABSENCE_POLL_INTERVAL_MS);
+  }
+};
+const requiredConfiguration = (environment) => {
+  const slice = requiredExact(environment, 'EBK_SLICE', '${name}');
+  const databaseIdentifier = requiredExact(
+    environment,
+    'EBK_DATABASE_IDENTIFIER',
+    FIXED_DATABASE_IDENTIFIER,
+  );
+  requiredExact(
+    environment,
+    'EBK_EXECUTION_DATABASE_IDENTIFIER',
+    databaseIdentifier,
+  );
+  requiredExact(environment, 'EBK_EXECUTION_SLICE', slice);
+  requiredExact(environment, 'EBK_EXECUTION_STAGE', FIXED_STAGE);
+  const databaseName = requiredIdentifier(
+    environment,
+    'EBK_DATABASE_NAME',
+  );
+  const migratorRole = requiredIdentifier(
+    environment,
+    'EBK_DATABASE_MIGRATOR_ROLE',
+  );
+  const readonlyRole = requiredIdentifier(
+    environment,
+    'EBK_DATABASE_READONLY_ROLE',
+  );
+  const readwriteRole = requiredIdentifier(
+    environment,
+    'EBK_DATABASE_READWRITE_ROLE',
+  );
+  const readonlySecretArn = requiredSecretArn(
+    environment,
+    'EBK_READONLY_SECRET_ARN',
+  );
+  const readwriteSecretArn = requiredSecretArn(
+    environment,
+    'EBK_READWRITE_SECRET_ARN',
+  );
+  requireExactDatabaseResources({
+    databaseIdentifier,
+    databaseName,
+    migratorRole,
+    readonlyRole,
+    readonlySecretArn,
+    readwriteRole,
+    readwriteSecretArn,
+    slice,
+  });
+  return {
+    candidateIdentity: requiredPattern(
+      environment,
+      'EBK_CANDIDATE_IDENTITY',
+      CANDIDATE_PATTERN,
+    ),
+    correlationId: requiredPattern(
+      environment,
+      'EBK_DATABASE_LIFECYCLE_CORRELATION_ID',
+      /^[A-Za-z0-9._:/-]{1,128}$/,
+    ),
+    databaseIdentifier,
+    databaseName,
+    host: required(environment, 'EBK_DATABASE_HOST'),
+    masterSecretArn: requiredSecretArn(
+      environment,
+      'EBK_MASTER_SECRET_ARN',
+    ),
+    migratorRole,
+    port: requiredPort(environment),
+    readonlyRole,
+    readonlySecretArn,
+    registrationDigest: requiredPattern(
+      environment,
+      'EBK_REGISTRATION_DIGEST',
+      DIGEST_PATTERN,
+    ),
+    retirementId: requiredPattern(
+      environment,
+      'EBK_RETIREMENT_ID',
+      /^[A-Za-z0-9._:/-]{1,128}$/,
+    ),
+    retainedSiblings: requireRetainedSiblings(environment, slice),
+    readwriteRole,
+    readwriteSecretArn,
+    rdsCaBundle: required(environment, 'EBK_RDS_CA_BUNDLE'),
+    slice,
+    sourceCommit: requiredPattern(
+      environment,
+      'EBK_SOURCE_COMMIT',
+      COMMIT_PATTERN,
+    ),
+    stage: requiredExact(environment, 'EBK_STAGE', FIXED_STAGE),
+    taskToken: requiredTaskToken(environment),
+    workspace: required(environment, 'EBK_WORKSPACE'),
+  };
+};
+
+export async function runDatabaseRetirementRehearsal({
+  environment = process.env,
+  now = () => Date.now(),
+  postgresClient = (configuration) => new Client(configuration),
+  readCaBundle = readFile,
+  secrets = new SecretsManagerClient({}),
+  sfn = new SFNClient({}),
+  sleep = (duration) =>
+    new Promise((resolve) => setTimeout(resolve, duration)),
+} = {}) {
+  let configuration;
+  let lifecycleLogger;
+  let postgres;
+  let lockKey;
+  let retirementPhase = 'configuration';
+  let taskToken =
+    typeof environment.EBK_STEP_FUNCTIONS_TASK_TOKEN === 'string'
+      ? environment.EBK_STEP_FUNCTIONS_TASK_TOKEN.trim()
+      : '';
+  const log = (event, fields = {}) => lifecycleLogger?.emit(event, fields);
+  try {
+    configuration = requiredConfiguration(environment);
+    taskToken = configuration.taskToken;
+    lifecycleLogger = createDatabaseLifecycleLogger({
+      component: 'database-retirement',
+      correlationId: configuration.correlationId,
+      databaseLifecycleId: configuration.retirementId,
+      operation: 'database.retire',
+      slice: '${name}',
+      stage: FIXED_STAGE,
+      workspace: configuration.workspace,
+    });
+
+    retirementPhase = 'credential-resolution';
+    const [ca, master] = await Promise.all([
+      readCaBundle(configuration.rdsCaBundle, 'utf8'),
+      readJsonSecret(secrets, configuration.masterSecretArn),
+    ]);
+    if (
+      typeof master.username !== 'string' ||
+      typeof master.password !== 'string' ||
+      master.password.length === 0 ||
+      !IDENTIFIER_PATTERN.test(master.username)
+    ) {
+      throw new Error('Foundation master secret is invalid.');
+    }
+    postgres = postgresClient({
+      connectionTimeoutMillis: 10_000,
+      database: 'postgres',
+      host: configuration.host,
+      password: master.password,
+      port: configuration.port,
+      ssl: { ca, rejectUnauthorized: true },
+      statement_timeout: 10 * 60 * 1000,
+      user: master.username,
+    });
+    postgres.on('error', (error) => {
+      log('database_retirement_client_error', safeErrorFields(error));
+    });
+    await postgres.connect();
+    lockKey = 'ebk-bootstrap:' + configuration.databaseName;
+    retirementPhase = 'serialized-retirement';
+    await postgres.query(
+      'SELECT pg_advisory_lock(hashtextextended($1, 0))',
+      [lockKey],
+    );
+    const beforeSiblingFingerprints = await fingerprintSiblings(
+      postgres,
+      secrets,
+      configuration.retainedSiblings,
+    );
+
+    const existing = await queryDatabaseMetadata(
+      postgres,
+      configuration.databaseName,
+    );
+    const roles = new Set(
+      (
+        await queryRoleMetadata(postgres, [
+          configuration.migratorRole,
+          configuration.readwriteRole,
+          configuration.readonlyRole,
+        ])
+      ).map(({ rolname }) => rolname),
+    );
+    if (existing !== null) {
+      const grantees = [
+        configuration.migratorRole,
+        configuration.readwriteRole,
+        configuration.readonlyRole,
+      ]
+        .filter((role) => roles.has(role))
+        .map(quoteIdentifier)
+        .join(', ');
+      if (grantees) {
+        await postgres.query(
+          'REVOKE ALL ON DATABASE ' +
+            quoteIdentifier(configuration.databaseName) +
+            ' FROM ' +
+            grantees,
+        );
+      }
+      await postgres.query(
+        'DROP DATABASE ' +
+          quoteIdentifier(configuration.databaseName) +
+          ' WITH (FORCE)',
+      );
+    }
+    if (
+      roles.has(configuration.readwriteRole) &&
+      roles.has(configuration.migratorRole)
+    ) {
+      await postgres.query(
+        'REVOKE ' +
+          quoteIdentifier(configuration.readwriteRole) +
+          ' FROM ' +
+          quoteIdentifier(configuration.migratorRole),
+      );
+    }
+    for (const role of [
+      configuration.migratorRole,
+      configuration.readwriteRole,
+      configuration.readonlyRole,
+    ]) {
+      await postgres.query('DROP ROLE IF EXISTS ' + quoteIdentifier(role));
+    }
+    retirementPhase = 'credential-container-retirement';
+    await Promise.all([
+      deleteExactSecret(secrets, configuration.readonlySecretArn),
+      deleteExactSecret(secrets, configuration.readwriteSecretArn),
+    ]);
+    await waitForSecretAbsence({
+      now,
+      secretArns: [
+        configuration.readonlySecretArn,
+        configuration.readwriteSecretArn,
+      ],
+      secrets,
+      sleep,
+    });
+
+    retirementPhase = 'absence-proof';
+    const after = {
+      ...(await resourceExistence({
+        ...configuration,
+        postgres,
+        secrets,
+      })),
+      siblingFingerprints: await fingerprintSiblings(
+        postgres,
+        secrets,
+        configuration.retainedSiblings,
+      ),
+    };
+    if (
+      Object.entries(after)
+        .filter(([key]) => key !== 'siblingFingerprints')
+        .some(([, exists]) => exists !== false)
+    ) {
+      throw new Error(
+        'Exact database retirement left one or more target resources present.',
+      );
+    }
+    for (const [sibling, before] of Object.entries(
+      beforeSiblingFingerprints,
+    )) {
+      if (after.siblingFingerprints[sibling] !== before) {
+        throw new Error(
+          'Retained sibling changed during exact database retirement.',
+        );
+      }
+    }
+
+    const evidence = {
+      after,
+      beforeSiblingFingerprints,
+      candidateIdentity: configuration.candidateIdentity,
+      database: FIXED_DATABASE_IDENTIFIER,
+      databaseLifecycleCorrelationId: configuration.correlationId,
+      evidenceVersion: 1,
+      registrationDigest: configuration.registrationDigest,
+      sourceCommit: configuration.sourceCommit,
+      stage: FIXED_STAGE,
+      slice: configuration.slice,
+    };
+    const output = JSON.stringify(evidence);
+    if (Buffer.byteLength(output, 'utf8') > MAX_CALLBACK_BYTES) {
+      throw new Error(
+        'Database retirement evidence exceeds the bounded callback size.',
+      );
+    }
+
+    retirementPhase = 'callback';
+    await sfn.send(
+      new SendTaskSuccessCommand({
+        output,
+        taskToken: configuration.taskToken,
+      }),
+    );
+    log('database_retirement_succeeded', {
+      database: configuration.databaseName,
+    });
+    return evidence;
+  } catch (error) {
+    log('database_retirement_failed', {
+      phase: retirementPhase,
+      ...safeErrorFields(error),
+    });
+    if (taskToken) {
+      const failure = callbackFailure(retirementPhase, error);
+      await sfn
+        .send(
+          new SendTaskFailureCommand({
+            cause: failure.cause,
+            error: failure.error,
+            taskToken,
+          }),
+        )
+        .catch(() => undefined);
+    }
+    throw error;
+  } finally {
+    if (postgres && lockKey) {
+      await postgres
+        .query('SELECT pg_advisory_unlock(hashtextextended($1, 0))', [
+          lockKey,
+        ])
+        .catch(() => undefined);
+    }
+    await postgres?.end().catch(() => undefined);
+  }
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  runDatabaseRetirementRehearsal().catch(() => {
+    process.exitCode = 1;
+  });
+}
+`,
+        'jobs/migrate-database.mjs': `import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { Signer } from '@aws-sdk/rds-signer';
+import pg from 'pg';
+import { createDatabaseLifecycleLogger } from './database-lifecycle-logging.mjs';
+
+const { Client } = pg;
+const required = (name) => {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(name + ' is required.');
+  return value;
+};
+const requiredIdentifier = (name) => {
+  const value = required(name);
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(value)) {
+    throw new Error(name + ' is not a valid database identifier.');
+  }
+  return value;
+};
+const quoteIdentifier = (value) => '"' + value.replaceAll('"', '""') + '"';
+let migrationId = 'unresolved';
+let migrationPhase = 'configuration';
+let lifecycleLogger;
+
+const log = (event, fields = {}) => lifecycleLogger?.emit(event, fields);
+const safeErrorFields = (error) => {
+  const name = error instanceof Error ? error.name : 'UnknownError';
+  const code =
+    error &&
+    typeof error === 'object' &&
+    typeof error.code === 'string' &&
+    /^[A-Z0-9_]{2,32}$/.test(error.code)
+      ? error.code
+      : undefined;
+  return {
+    errorName: name.replace(/[^A-Za-z0-9_.-]/g, '').slice(0, 80) || 'Error',
+    ...(code ? { errorCode: code } : {}),
+  };
+};
+const retryableConnection = (error) => {
+  const code = error && typeof error === 'object' ? error.code : undefined;
+  const message = error instanceof Error ? error.message : String(error);
+  return new Set([
+    '08000',
+    '08001',
+    '08003',
+    '08006',
+    '57P03',
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+  ]).has(code) ||
+    /resum|starting up|temporarily unavailable|timeout|connection terminated unexpectedly|server closed the connection unexpectedly|terminating connection/i.test(message);
+};
+const sleep = (milliseconds) =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+const sqlCodeOnly = (sql) => {
+  let index = 0;
+  let result = '';
+  const masked = (value) => value.replace(/[^\\r\\n]/g, ' ');
+  while (index < sql.length) {
+    if (sql.startsWith('--', index)) {
+      const end = sql.indexOf('\\n', index);
+      const next = end === -1 ? sql.length : end;
+      result += masked(sql.slice(index, next));
+      index = next;
+      continue;
+    }
+    if (sql.startsWith('/*', index)) {
+      const start = index;
+      let depth = 1;
+      index += 2;
+      while (index < sql.length && depth > 0) {
+        if (sql.startsWith('/*', index)) {
+          depth += 1;
+          index += 2;
+        } else if (sql.startsWith('*/', index)) {
+          depth -= 1;
+          index += 2;
+        } else {
+          index += 1;
+        }
+      }
+      result += masked(sql.slice(start, index));
+      continue;
+    }
+    const quote = sql[index];
+    if (quote === "'" || quote === '"') {
+      const start = index;
+      index += 1;
+      while (index < sql.length) {
+        if (sql[index] === quote) {
+          if (sql[index + 1] === quote) {
+            index += 2;
+            continue;
+          }
+          index += 1;
+          break;
+        }
+        if (quote === "'" && sql[index] === '\\\\' && index + 1 < sql.length) {
+          index += 2;
+        } else {
+          index += 1;
+        }
+      }
+      result += masked(sql.slice(start, index));
+      continue;
+    }
+    if (sql[index] === '$') {
+      const tag = sql
+        .slice(index)
+        .match(/^\\$(?:[A-Za-z_][A-Za-z0-9_]*)?\\$/)?.[0];
+      if (tag) {
+        const start = index;
+        const close = sql.indexOf(tag, index + tag.length);
+        index = close === -1 ? sql.length : close + tag.length;
+        result += masked(sql.slice(start, index));
+        continue;
+      }
+    }
+    result += sql[index];
+    index += 1;
+  }
+  return result;
+};
+const hasExecutableSql = (sql) => sqlCodeOnly(sql).trim().length > 0;
+const unsupportedNonTransactionalSql =
+  /\\b(?:CREATE|DROP)\\s+INDEX\\s+CONCURRENTLY\\b|\\bVACUUM\\b/i;
+
+async function main() {
+  migrationId = required('EBK_MIGRATION_ID');
+  lifecycleLogger = createDatabaseLifecycleLogger({
+    component: 'database-migration',
+    correlationId: required('EBK_DATABASE_LIFECYCLE_CORRELATION_ID'),
+    databaseLifecycleId: migrationId,
+    operation: 'database.migrate',
+    slice: '${name}',
+    stage: required('EBK_STAGE'),
+    workspace: required('EBK_WORKSPACE'),
+  });
+  const host = required('EBK_DATABASE_HOST');
+  const database = required('EBK_DATABASE_NAME');
+  const username = required('EBK_DATABASE_USERNAME');
+  const readwriteRole = requiredIdentifier('EBK_DATABASE_READWRITE_ROLE');
+  const region = required('AWS_REGION');
+  const caBundlePath = required('EBK_RDS_CA_BUNDLE');
+  const port = Number(required('EBK_DATABASE_PORT'));
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    throw new Error('EBK_DATABASE_PORT must be a valid TCP port.');
+  }
+  migrationPhase = 'load_ca_bundle';
+  const ca = await readFile(caBundlePath, 'utf8');
+  const connectDeadline = Date.now() + 8 * 60 * 1000;
+  let attempt = 0;
+  let client;
+  while (!client) {
+    attempt += 1;
+    let candidate;
+    try {
+      migrationPhase = 'connect';
+      const password = await new Signer({
+        hostname: host,
+        port,
+        region,
+        username,
+      }).getAuthToken();
+      candidate = new Client({
+        application_name: migrationId,
+        connectionTimeoutMillis: 15_000,
+        database,
+        host,
+        password,
+        port,
+        ssl: { ca, rejectUnauthorized: true },
+        user: username,
+      });
+      await candidate.connect();
+      client = candidate;
+    } catch (error) {
+      await candidate?.end().catch(() => undefined);
+      if (!retryableConnection(error) || Date.now() >= connectDeadline) {
+        throw error;
+      }
+      const delayMs = Math.min(attempt * 5_000, 30_000);
+      log('database_connection_retry', {
+        attempt,
+        delayMs,
+        ...safeErrorFields(error),
+      });
+      await sleep(delayMs);
+    }
+  }
+
+  let clientFailure;
+  client.on('error', (error) => {
+    clientFailure ??= error;
+    log('database_client_error', {
+      phase: migrationPhase,
+      ...safeErrorFields(error),
+    });
+  });
+
+  let locked = false;
+  try {
+    migrationPhase = 'lock';
+    await client.query("SET lock_timeout = '5min'");
+    await client.query(
+      'SELECT pg_advisory_lock(hashtextextended($1, 0))',
+      [migrationId],
+    );
+    locked = true;
+    migrationPhase = 'ledger';
+    await client.query(
+      'CREATE TABLE IF NOT EXISTS _ebk_migrations (' +
+        'name text PRIMARY KEY, ' +
+        'checksum text NOT NULL, ' +
+        'applied_at timestamptz NOT NULL DEFAULT now())',
+    );
+    const directory = new URL('../database/migrations/', import.meta.url);
+    const files = (await readdir(directory))
+      .filter((file) => file.endsWith('.sql'))
+      .sort();
+    for (const name of files) {
+      migrationPhase = 'migration:' + name;
+      const sql = await readFile(new URL(name, directory), 'utf8');
+      if (!hasExecutableSql(sql)) {
+        throw new Error('Migration contains no executable SQL.');
+      }
+      if (unsupportedNonTransactionalSql.test(sqlCodeOnly(sql))) {
+        throw new Error(
+          'Migration requires an unsupported non-transactional operation.',
+        );
+      }
+      const checksum = createHash('sha256').update(sql).digest('hex');
+      const existing = await client.query(
+        'SELECT checksum FROM _ebk_migrations WHERE name = $1',
+        [name],
+      );
+      const appliedChecksum = existing.rows[0]?.checksum;
+      if (appliedChecksum === checksum) {
+        log('migration_skipped', { checksum, name });
+        continue;
+      }
+      if (appliedChecksum) {
+        throw new Error('An applied migration checksum changed.');
+      }
+
+      await client.query('BEGIN');
+      try {
+        const statements = sql
+          .split(/^--> statement-breakpoint\\s*$/m)
+          .map((value) => value.trim())
+          .filter(Boolean);
+        for (const statement of statements) {
+          await client.query(statement);
+        }
+        await client.query(
+          'INSERT INTO _ebk_migrations (name, checksum) VALUES ($1, $2)',
+          [name, checksum],
+        );
+        await client.query('COMMIT');
+        log('migration_applied', { checksum, name });
+      } catch (error) {
+        await client.query('ROLLBACK').catch((rollbackError) => {
+          log('migration_rollback_failed', {
+            phase: migrationPhase,
+            ...safeErrorFields(rollbackError),
+          });
+        });
+        throw error;
+      }
+    }
+    migrationPhase = 'audit-capability';
+    await client.query(
+      'REVOKE UPDATE, DELETE, TRUNCATE ON TABLE ' +
+        'authorization_audit, data_lifecycle_audit FROM ' +
+        quoteIdentifier(readwriteRole),
+    );
+    await client.query(
+      'GRANT EXECUTE ON FUNCTION ' +
+        'ebk_prune_authorization_audit(timestamptz, integer), ' +
+        'ebk_prune_data_lifecycle_audit(timestamptz, integer) TO ' +
+        quoteIdentifier(readwriteRole),
+    );
+    if (clientFailure) throw clientFailure;
+    log('migration_completed', { count: files.length });
+  } finally {
+    migrationPhase = 'cleanup';
+    if (locked) {
+      await client.query(
+        'SELECT pg_advisory_unlock(hashtextextended($1, 0))',
+        [migrationId],
+      ).catch(() => undefined);
+    }
+    await client.end().catch(() => undefined);
+  }
+}
+
+await main().catch((error) => {
+  log('migration_failed', {
+    phase: migrationPhase,
+    ...safeErrorFields(error),
+  });
+  process.exitCode = 1;
+});
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-database-lifecycle-files.js.map