@everystack/cli 0.4.103 → 0.4.105

package/src/cli/lifecycle-preflight.ts

@@ -0,0 +1,617 @@
+/** Read-only prerequisite for the state and derived halves of a lifecycle apply. */
+import { createHash } from 'node:crypto';
+import { DESTROY_LOG_MARKER_BODIES, DESTROY_LOG_MARKER_LANGUAGES, DESTROY_LOG_MARKER_SEARCH_PATH, LIFECYCLE_OWNER_ROLE, type ModelDescriptor } from '@everystack/model';
+import type { QueryRunner } from './authz-contract';
+import { compileTableContract } from './authz-compile';
+import { reconcileOwner, triggerFunctionOf } from './derived-apply';
+import { isSessionError, type SessionRunner } from './session';
+import { parseQualified, type SourceObject } from './derived-source';
+import { lifecycleDerived, lifecycleManifestOf, lifecycleRole } from './lifecycle-derived';
+
+export const LIFECYCLE_LOG_REFUSAL = 'everystack.destroy_log is missing; run db:provision before db:apply';
+export const LIFECYCLE_LOG_OUTDATED_REFUSAL = 'everystack.destroy_log is out of date (it has no before column or no marker functions); run db:provision before db:apply';
+/**
+ * Present, and current: it has the `before` column and the three marker functions the generated
+ * destroy calls (destroy_log_mark, destroy_log_unmark, destroy_cutoff). The reconcile creates
+ * functions with check_function_bodies off, so on an earlier log it would install them and every
+ * lifecycle DELETE would then fail with an unknown-column or unknown-function error.
+ */
+export const LIFECYCLE_LOG_SQL = `SELECT pg_catalog.to_regclass('everystack.destroy_log') IS NOT NULL AS present,
+  EXISTS (SELECT 1 FROM pg_catalog.pg_attribute WHERE attrelid = pg_catalog.to_regclass('everystack.destroy_log')
+    AND attname = 'before' AND NOT attisdropped)
+  AND pg_catalog.to_regprocedure('everystack.destroy_log_mark(timestamptz)') IS NOT NULL
+  AND pg_catalog.to_regprocedure('everystack.destroy_log_unmark()') IS NOT NULL
+  AND pg_catalog.to_regprocedure('everystack.destroy_cutoff()') IS NOT NULL AS current`;
+
+/** The refusal for one LIFECYCLE_LOG_SQL row, or null when the log is present and current. */
+export function lifecycleLogRowRefusal(log: { present?: unknown; current?: unknown } | undefined): string | null {
+  if (log?.present !== true) return LIFECYCLE_LOG_REFUSAL;
+  return log.current === true ? null : LIFECYCLE_LOG_OUTDATED_REFUSAL;
+}
+
+/**
+ * The log's shape first (its refusals are unchanged), then the live catalog facts the soft delete
+ * rests on (lifecycleCatalogRefusal). Pure SELECTs: the --stage lane runs them over db:query.
+ */
+export async function lifecycleApplyRefusal(runner: QueryRunner, models: readonly ModelDescriptor[]): Promise<string | null> {
+  if (!models.some(model => model.lifecycle === true)) return null;
+  const [log] = await runner(LIFECYCLE_LOG_SQL);
+  // Before the plan: a modeled table's keys are the plan's to converge (the models declare each
+  // one, or refuse to compile), so rule 6 reports only keys from tables the models do not have.
+  const modeledTables = [...new Set(models.map(model => `${model.schema}.${model.table}`))];
+  return lifecycleLogRowRefusal(log) ?? lifecycleCatalogRefusal(runner, { ...catalogInputsFromModels(models), modeledTables });
+}
+
+const literal = (s: string): string => `'${s.replace(/'/g, "''")}'`;
+const ident = (s: string): string => (/^[a-z_][a-z0-9_]*$/.test(s) ? s : `"${s.replace(/"/g, '""')}"`);
+/** A `schema.table` label, quoted for a fix statement. */
+const quoteLabel = (label: string): string => {
+  const dot = label.indexOf('.');
+  return `${ident(label.slice(0, dot))}.${ident(label.slice(dot + 1))}`;
+};
+const textArray = (values: readonly string[]): string => `ARRAY[${values.map(literal).join(', ')}]::text[]`;
+/** An aclexplode grantee by name, PUBLIC for 0. */
+const granteeName = (column: string): string =>
+  `CASE WHEN ${column} = 0 THEN 'PUBLIC' ELSE pg_catalog.pg_get_userbyid(${column})::text END`;
+const md5 = (text: string): string => createHash('md5').update(text, 'utf8').digest('hex');
+const truthy = (v: unknown): boolean => v === true || v === 't' || v === 'true';
+const textList = (v: unknown): string[] => (Array.isArray(v) ? v.map(String) : typeof v === 'string' && v.startsWith('{')
+  ? v.slice(1, -1).split(',').filter(Boolean).map(s => s.replace(/^"|"$/g, '')) : []);
+const MARKERS = Object.keys(DESTROY_LOG_MARKER_BODIES) as Array<keyof typeof DESTROY_LOG_MARKER_BODIES>;
+const MARKER_CONFIG = `search_path=${DESTROY_LOG_MARKER_SEARCH_PATH}`;
+
+/**
+ * What the catalog check reads from the declared side. The check needs nothing else from the
+ * models, so db:reconcile's ops action can run it from its wire payload, which carries no models.
+ *
+ *   lifecycleTables   `schema.table` of every lifecycle table
+ *   applicationRoles  every role the models' compiled contracts grant to or name in a policy. A
+ *                     request runs as one of them. SQL cannot tell which role is the application's
+ *                     login; a login with no grant or policy of its own is application-side only
+ *                     when it can assume one of these. PUBLIC and the lifecycle role never count.
+ */
+export interface LifecycleCatalogInputs {
+  lifecycleTables: readonly string[];
+  applicationRoles: readonly string[];
+  /** Every declared dependent key (dependentKeysFromDeclared). */
+  dependentKeys: readonly LifecycleDependentKey[];
+  /**
+   * `schema.table` of each lifecycle table whose manifest has no nullify record (an older CLI sent
+   * it): a key it declares 'nullify' cannot be seen, so its finding says to upgrade the CLI.
+   */
+  nullifyUnrecorded?: readonly string[];
+  /**
+   * Before the plan only (lifecycleApplyRefusal): `schema.table` of every modeled table, whose keys
+   * rule 6 leaves to the plan. Absent after the state apply: every key is checked.
+   */
+  modeledTables?: readonly string[];
+}
+
+/** A declared dependent: the child's `schema.table`, its foreign-key column (SQL name), the lifecycle parent's `schema.table`. */
+export interface LifecycleDependentKey {
+  child: string;
+  column: string;
+  parent: string;
+}
+
+/**
+ * The declared dependents ('cascade', 'restrict' and 'nullify'), read from the generated lifecycle
+ * functions' manifests: the declared layer itself, so the models path and a db:reconcile payload
+ * (which carries no models) read one source.
+ */
+export function dependentKeysFromDeclared(declared: readonly Parameters<typeof lifecycleManifestOf>[0][]): LifecycleDependentKey[] {
+  const label = (name: string): string => {
+    if (!name.startsWith('"')) return name;
+    const { schema, name: table } = parseQualified(name);
+    return `${schema}.${table}`;
+  };
+  const keys = new Map<string, LifecycleDependentKey>();
+  for (const object of declared) {
+    const manifest = lifecycleManifestOf(object);
+    if (!manifest) continue;
+    const edges = [...manifest.decl.edges, ...(manifest.decl.nullify ?? []).map(n => ({ ...n, parent: manifest.model }))];
+    for (const edge of edges) {
+      const key = { child: label(edge.child), column: edge.column, parent: edge.parent };
+      keys.set(JSON.stringify(key), key);
+    }
+  }
+  return [...keys.values()].sort((a, b) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1));
+}
+
+/** The lifecycle tables whose transition manifest has no `decl.nullify` (a CLI that predates it sent the layer). */
+export function nullifyUnrecordedFromDeclared(declared: readonly Parameters<typeof lifecycleManifestOf>[0][]): string[] {
+  return [...new Set(declared.map(object => lifecycleManifestOf(object))
+    .filter(manifest => manifest?.role === 'transition' && manifest.decl.nullify === undefined)
+    .map(manifest => manifest!.model))].sort();
+}
+
+const notApplicationRole = (lc: string) => (role: string): boolean => role !== 'PUBLIC' && role !== 'public' && role !== lc;
+
+/** The catalog check's inputs, read from the models. */
+export function catalogInputsFromModels(models: readonly ModelDescriptor[]): { lifecycleTables: string[]; applicationRoles: string[]; dependentKeys: LifecycleDependentKey[] } {
+  const roles = new Set<string>();
+  for (const model of models) {
+    const contract = compileTableContract(model);
+    for (const role of Object.keys(contract.grants)) roles.add(role);
+    for (const role of Object.keys(contract.columnGrants ?? {})) roles.add(role);
+    for (const policy of contract.policies) for (const role of policy.roles) roles.add(role);
+  }
+  return {
+    lifecycleTables: [...new Set(models.filter(model => model.lifecycle === true).map(model => `${model.schema}.${model.table}`))].sort(),
+    applicationRoles: [...roles].filter(notApplicationRole(LIFECYCLE_OWNER_ROLE)).sort(),
+    dependentKeys: models.some(model => model.lifecycle === true) ? dependentKeysFromDeclared(lifecycleDerived(models)) : [],
+  };
+}
+
+/**
+ * `x` can act as `y`: SET ROLE to it, or inherit its privileges. On PostgreSQL 16 and later
+ * pg_has_role's MEMBER also counts an ADMIN-only grant (no SET, no INHERIT), which a non-superuser
+ * CREATEROLE role gets on every role it creates; SET and USAGE do not. Before 16 every membership
+ * could SET ROLE, MEMBER means exactly that, and 'SET' is not a keyword, so the branch is on
+ * server_version_num.
+ */
+const assumes = (x: string, y: string): string => `(pg_catalog.pg_has_role(${x}, ${y}, 'USAGE') OR CASE
+    WHEN pg_catalog.current_setting('server_version_num')::int >= 160000 THEN pg_catalog.pg_has_role(${x}, ${y}, 'SET')
+    ELSE pg_catalog.pg_has_role(${x}, ${y}, 'MEMBER') END)`;
+/** `x` can act as `y`, or hold ADMIN on it: an ADMIN holder can grant `y` to itself WITH SET. */
+const reaches = (x: string, y: string): string =>
+  `(${assumes(x, y)} OR pg_catalog.pg_has_role(${x}, ${y}, 'MEMBER WITH ADMIN OPTION'))`;
+
+/**
+ * The application-side roles, as a CTE `side(oid, rolname)`: non-superusers that are, or can act
+ * as, an application role. A superuser passes every pg_has_role and is left out; so is the RDS
+ * master, whose ADMIN-only membership in the roles it created lets it act as none of them.
+ */
+const sideCte = (apps: string[]): string => `side AS (SELECT r.oid, r.rolname::text AS rolname FROM pg_catalog.pg_roles r
+    WHERE NOT r.rolsuper AND EXISTS (SELECT 1 FROM pg_catalog.pg_roles a
+      WHERE a.rolname = ANY(${textArray(apps)}) AND (a.oid = r.oid OR ${assumes('r.oid', 'a.oid')})))`;
+
+/** Rule 1, attributes. */
+const roleSql = (lc: string): string => `SELECT lc.oid IS NOT NULL AS present,
+    COALESCE(lc.rolcanlogin, false) AS login, COALESCE(lc.rolsuper, false) AS super,
+    COALESCE(lc.rolcreaterole, false) AS createrole, COALESCE(lc.rolbypassrls, false) AS bypassrls
+  FROM (SELECT 1) AS one LEFT JOIN pg_catalog.pg_roles lc ON lc.rolname = ${literal(lc)}`;
+
+/**
+ * Rule 1, members: each application-side role that reaches the lifecycle role, with the
+ * application roles it acts as. The operator's membership (WITH INHERIT FALSE, SET TRUE, which a
+ * non-superuser builder needs to create the lifecycle functions) passes: it acts as no application role.
+ */
+const memberSql = (apps: string[], lc: string): string => `WITH ${sideCte(apps)}
+  SELECT s.rolname AS role, ARRAY(SELECT a.rolname::text FROM pg_catalog.pg_roles a
+      WHERE a.rolname = ANY(${textArray(apps)}) AND (a.oid = s.oid OR ${assumes('s.oid', 'a.oid')}) ORDER BY 1) AS apps
+  FROM side s JOIN pg_catalog.pg_roles lc ON lc.rolname = ${literal(lc)}
+  WHERE s.oid <> lc.oid AND ${reaches('s.oid', 'lc.oid')}
+  ORDER BY 1`;
+
+/**
+ * Rule 2. The owner of a lifecycle table can disable its triggers; the owner of destroy_log can
+ * write the marker; the owner of a marker function can replace it. Each such object is a finding
+ * when its owner is the lifecycle role, or when an application-side role is that owner, can act
+ * as it, or holds ADMIN on it. The operator owning all of them is the documented setup and passes.
+ */
+const ownerSql = (tables: string[], apps: string[], lc: string): string => `WITH ${sideCte(apps)},
+  owned AS (
+    SELECT 'table' AS kind, n.nspname::text || '.' || c.relname::text AS name, c.relowner AS owner
+    FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relkind IN ('r', 'p') AND (n.nspname::text || '.' || c.relname::text) = ANY(${textArray(tables)})
+    UNION ALL
+    SELECT 'table', 'everystack.destroy_log', c.relowner FROM pg_catalog.pg_class c
+    WHERE c.oid = pg_catalog.to_regclass('everystack.destroy_log')
+    UNION ALL
+    SELECT 'function', m.sig, p.proowner FROM pg_catalog.unnest(${textArray(MARKERS)}) AS m(sig)
+    JOIN pg_catalog.pg_proc p ON p.oid = pg_catalog.to_regprocedure(m.sig))
+  SELECT o.kind, o.name, pg_catalog.pg_get_userbyid(o.owner)::text AS owner, o.owner = lc.oid AS lifecycle_owned,
+    ARRAY(SELECT s.rolname FROM side s WHERE s.oid = o.owner OR ${reaches('s.oid', 'o.owner')} ORDER BY 1) AS via
+  FROM owned o LEFT JOIN pg_catalog.pg_roles lc ON lc.rolname = ${literal(lc)}
+  WHERE o.owner = lc.oid OR EXISTS (SELECT 1 FROM side s WHERE s.oid = o.owner OR ${reaches('s.oid', 'o.owner')})
+  ORDER BY 2, 1`;
+
+/**
+ * Rule 3. TRIGGER, REFERENCES or TRUNCATE on a lifecycle table, or REFERENCES on one of its
+ * columns, held by anyone but its owner. On everystack.destroy_log, any privilege but SELECT
+ * (table or column) held by anyone but its owner: a writer could forge or remove a marker.
+ */
+const aclSql = (tables: string[]): string => `SELECT n.nspname::text || '.' || c.relname::text AS "table", ${granteeName('a.grantee')} AS grantee,
+    a.privilege_type AS privilege, NULL::text AS "column"
+  FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+  CROSS JOIN LATERAL pg_catalog.aclexplode(c.relacl) a
+  WHERE c.relkind IN ('r', 'p') AND a.grantee <> c.relowner AND (
+    ((n.nspname::text || '.' || c.relname::text) = ANY(${textArray(tables)}) AND a.privilege_type IN ('TRIGGER', 'REFERENCES', 'TRUNCATE'))
+    OR (c.oid = pg_catalog.to_regclass('everystack.destroy_log') AND a.privilege_type <> 'SELECT'))
+  UNION ALL
+  SELECT n.nspname::text || '.' || c.relname::text, ${granteeName('a.grantee')}, a.privilege_type, t.attname::text
+  FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+  JOIN pg_catalog.pg_attribute t ON t.attrelid = c.oid AND t.attnum > 0 AND NOT t.attisdropped
+  CROSS JOIN LATERAL pg_catalog.aclexplode(t.attacl) a
+  WHERE c.relkind IN ('r', 'p') AND a.grantee <> c.relowner AND (
+    ((n.nspname::text || '.' || c.relname::text) = ANY(${textArray(tables)}) AND a.privilege_type = 'REFERENCES')
+    OR (c.oid = pg_catalog.to_regclass('everystack.destroy_log') AND a.privilege_type <> 'SELECT'))
+  ORDER BY 1, 4 NULLS FIRST, 3, 2`;
+
+/**
+ * Rule 4. Each marker function: SECURITY DEFINER, owned by destroy_log's owner, EXECUTE for the
+ * lifecycle role and nobody else but the owner (PUBLIC included; a NULL ACL is PUBLIC's default),
+ * and the language, settings and body (md5 of prosrc) provisioning installs.
+ */
+const markerSql = (lc: string): string => `SELECT s.sig, p.oid IS NOT NULL AS present, COALESCE(p.prosecdef, false) AS secdef,
+    pg_catalog.pg_get_userbyid(p.proowner)::text AS owner, pg_catalog.pg_get_userbyid(d.relowner)::text AS log_owner,
+    pg_catalog.md5(p.prosrc) AS body_md5, l.lanname::text AS language,
+    pg_catalog.array_to_string(p.proconfig, '; ') AS config,
+    ARRAY(SELECT DISTINCT ${granteeName('a.grantee')} FROM pg_catalog.aclexplode(COALESCE(p.proacl, pg_catalog.acldefault('f', p.proowner))) a
+      WHERE a.privilege_type = 'EXECUTE' AND a.grantee <> p.proowner AND a.grantee IS DISTINCT FROM lc.oid ORDER BY 1) AS others,
+    EXISTS (SELECT 1 FROM pg_catalog.aclexplode(COALESCE(p.proacl, pg_catalog.acldefault('f', p.proowner))) a
+      WHERE a.privilege_type = 'EXECUTE' AND a.grantee = lc.oid) AS lifecycle_execute
+  FROM (VALUES ${MARKERS.map((sig, i) => `(${i}, ${literal(sig)})`).join(', ')}) AS s(i, sig)
+  LEFT JOIN pg_catalog.pg_proc p ON p.oid = pg_catalog.to_regprocedure(s.sig)
+  LEFT JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+  LEFT JOIN pg_catalog.pg_class d ON d.oid = pg_catalog.to_regclass('everystack.destroy_log')
+  LEFT JOIN pg_catalog.pg_roles lc ON lc.rolname = ${literal(lc)}
+  ORDER BY s.i`;
+
+/**
+ * Rule 5. A trigger on a lifecycle table whose function's owner is an application-side role, or
+ * one an application-side role reaches. The soft delete's stamp and destroy's DELETE run as the
+ * lifecycle role, so an INVOKER trigger function runs as it and a DEFINER one as its owner; either
+ * way whoever can replace the body acts inside every soft delete and destroy. So the security
+ * mode does not matter, and neither the table's owner nor the lifecycle role is exempt.
+ */
+const triggerOwnerSql = (tables: string[], apps: string[]): string => `WITH ${sideCte(apps)}
+  SELECT n.nspname::text || '.' || c.relname::text AS "table", g.tgname::text AS trigger,
+    pg_catalog.quote_ident(fn.nspname) || '.' || pg_catalog.quote_ident(p.proname) || '(' || pg_catalog.pg_get_function_identity_arguments(p.oid) || ')' AS function,
+    pg_catalog.pg_get_userbyid(p.proowner)::text AS owner,
+    ARRAY(SELECT s.rolname FROM side s WHERE s.oid = p.proowner OR ${reaches('s.oid', 'p.proowner')} ORDER BY 1) AS via
+  FROM pg_catalog.pg_trigger g JOIN pg_catalog.pg_class c ON c.oid = g.tgrelid
+  JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace JOIN pg_catalog.pg_proc p ON p.oid = g.tgfoid
+  JOIN pg_catalog.pg_namespace fn ON fn.oid = p.pronamespace
+  WHERE NOT g.tgisinternal AND (n.nspname::text || '.' || c.relname::text) = ANY(${textArray(tables)})
+    AND EXISTS (SELECT 1 FROM side s WHERE s.oid = p.proowner OR ${reaches('s.oid', 'p.proowner')})
+  ORDER BY 1, 2`;
+
+/**
+ * One rule-5 finding. `via` holds the application-side roles that are, or reach, `owner`. When the
+ * owner is one of them the fix is a new owner; otherwise it is to revoke the path to the owner.
+ * `would`: the pre-exposure gate, which judges a declared trigger before the reconcile creates it.
+ */
+export function triggerOwnerFinding(row: { trigger: string; table: string; function: string; owner: string; via: readonly string[] }, would = false): string {
+  const { owner, via } = row;
+  const sideOwned = via.includes(owner);
+  const who = sideOwned ? `${owner}, an application-side role`
+    : `${owner}, which the application-side role${via.length === 1 ? '' : 's'} ${via.join(', ')} can assume`;
+  const fix = sideOwned
+    ? `declare ${row.function}'s owner in db/models as a role no application role can act as, and apply `
+      + `(the apply re-creates a declared function with its declared owner, so a live ALTER alone is undone); `
+      + `for a function not declared in db/models: ALTER FUNCTION ${row.function} OWNER TO <that role>;`
+    : `${via.map(r => `REVOKE ${ident(owner)} FROM ${ident(r)};`).join(' ')} (or from the role each reaches ${owner} through)`;
+  return `trigger ${row.trigger} on ${row.table} ${would ? 'would run' : 'runs'} ${row.function}, owned by ${who}; `
+    + `${via.join(', ')} can replace its body, and it runs inside every soft delete and destroy. Fix: ${fix}`;
+}
+
+/**
+ * Rule 6. Every foreign key into a lifecycle table (a partition's clone excluded), with its columns
+ * in key order and its ON DELETE action. Which ones a model declares is decided by the caller.
+ */
+const inboundKeySql = (tables: string[]): string => `SELECT n.nspname::text || '.' || c.relname::text AS child, k.conname::text AS "constraint",
+    ARRAY(SELECT a.attname::text FROM pg_catalog.unnest(k.conkey) WITH ORDINALITY AS u(attnum, i)
+      JOIN pg_catalog.pg_attribute a ON a.attrelid = k.conrelid AND a.attnum = u.attnum ORDER BY u.i) AS columns,
+    pn.nspname::text || '.' || p.relname::text AS parent, k.confdeltype::text AS action
+  FROM pg_catalog.pg_constraint k JOIN pg_catalog.pg_class c ON c.oid = k.conrelid
+  JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+  JOIN pg_catalog.pg_class p ON p.oid = k.confrelid JOIN pg_catalog.pg_namespace pn ON pn.oid = p.relnamespace
+  WHERE k.contype = 'f' AND k.conparentid = 0 AND (pn.nspname::text || '.' || p.relname::text) = ANY(${textArray(tables)})
+  ORDER BY 1, 2`;
+
+const ON_DELETE: Record<string, string> = { a: 'NO ACTION', r: 'RESTRICT', c: 'CASCADE', n: 'SET NULL', d: 'SET DEFAULT' };
+
+const OWNER_HAZARD = {
+  table: 'an owner can disable its triggers',
+  log: 'an owner can write the marker',
+  function: 'an owner can replace the function',
+};
+
+/**
+ * The live catalog facts a lifecycle soft delete rests on, which the generator cannot guarantee.
+ * Every finding is named on its own line with its fix, or null when there is none.
+ * `lifecycleRole` is a test seam (the role is cluster-level); callers leave it unset.
+ *
+ * THREAT MODEL. This defends an HONEST operator from installing or re-arming the lifecycle
+ * SECURITY DEFINER objects onto a database whose grants or ownership have drifted: an application
+ * role that owns a lifecycle table, holds TRIGGER on one, can write everystack.destroy_log, a
+ * replaced marker function, and the rest below. It does not defend against a hostile IAM deployer,
+ * who can already reach the ops Lambda's other actions; so the roles may come from the caller
+ * (db:reconcile's wire payload carries them).
+ *
+ * The one implementation: db:apply, db:sync and db:plan reach it through lifecycleApplyRefusal
+ * (inputs from the models); db:reconcile, local and in the ops Lambda, through
+ * lifecycleReconcileRefusal (tables from the declared transition triggers); db:apply and db:build
+ * again after the derived layer lands, through lifecyclePostApplyRefusal.
+ */
+export async function lifecycleCatalogRefusal(
+  runner: QueryRunner,
+  inputs: LifecycleCatalogInputs,
+  options: { lifecycleRole?: string } = {},
+): Promise<string | null> {
+  const findings = await lifecycleCatalogFindings(runner, inputs, options);
+  if (findings.length === 0) return null;
+  return `the live catalog breaks the lifecycle soft delete (${findings.length} finding${findings.length === 1 ? '' : 's'}); `
+    + `fix each, then re-run:\n${findingLines(findings)}`;
+}
+
+const findingLines = (findings: readonly string[]): string => findings.map(finding => `  - ${finding}`).join('\n');
+const countFindings = (n: number): string => `${n} lifecycle finding${n === 1 ? '' : 's'}`;
+
+/** lifecycleCatalogRefusal's findings, one string each, without the heading. */
+async function lifecycleCatalogFindings(
+  runner: QueryRunner,
+  inputs: LifecycleCatalogInputs,
+  options: { lifecycleRole?: string } = {},
+): Promise<string[]> {
+  const lc = options.lifecycleRole ?? LIFECYCLE_OWNER_ROLE;
+  const tables = [...new Set(inputs.lifecycleTables)].sort();
+  if (tables.length === 0) return [];
+  const apps = [...new Set(inputs.applicationRoles)].filter(notApplicationRole(lc)).sort();
+  const findings: string[] = [];
+
+  const [role] = await runner(roleSql(lc));
+  if (!truthy(role?.present)) {
+    findings.push(`role ${lc} is missing. Fix: run db:provision.`);
+  } else {
+    const attributes = (['login', 'super', 'createrole', 'bypassrls'] as const).filter(key => truthy(role[key]));
+    const word = { login: 'LOGIN', super: 'SUPERUSER', createrole: 'CREATEROLE', bypassrls: 'BYPASSRLS' };
+    if (attributes.length > 0) {
+      findings.push(`role ${lc} has ${attributes.map(key => word[key]).join(', ')}. `
+        + `Fix: ALTER ROLE ${ident(lc)} ${attributes.map(key => `NO${word[key]}`).join(' ')};`);
+    }
+    for (const member of await runner(memberSql(apps, lc))) {
+      findings.push(`role ${member.role} can assume ${lc} and is, or can assume, an application role (${textList(member.apps).join(', ')}). `
+        + `Fix: REVOKE ${ident(lc)} FROM ${ident(String(member.role))}; (or from the role it reaches ${lc} through).`);
+    }
+  }
+
+  for (const row of await runner(ownerSql(tables, apps, lc))) {
+    const kind = row.kind === 'function' ? 'function' : 'table';
+    const hazard = row.name === 'everystack.destroy_log' ? OWNER_HAZARD.log : OWNER_HAZARD[kind];
+    const via = textList(row.via);
+    const who = truthy(row.lifecycle_owned) ? `${row.owner}, the lifecycle role`
+      : via.includes(String(row.owner)) ? `${row.owner}, an application-side role`
+        : `${row.owner}, which the application-side role${via.length === 1 ? '' : 's'} ${via.join(', ')} can assume`;
+    const name = kind === 'function' ? String(row.name) : quoteLabel(String(row.name));
+    const fix = truthy(row.lifecycle_owned) || via.includes(String(row.owner))
+      ? `ALTER ${kind.toUpperCase()} ${name} OWNER TO <your operator role>;`
+      : `${via.map(r => `REVOKE ${ident(String(row.owner))} FROM ${ident(r)};`).join(' ')} (or from the role each reaches it through)`;
+    findings.push(`${kind} ${row.name} is owned by ${who}; ${hazard}. Fix: ${fix}`);
+  }
+
+  for (const row of await runner(aclSql(tables))) {
+    const on = row.column == null ? '' : ` (${ident(String(row.column))})`;
+    const who = row.grantee === 'PUBLIC' ? 'PUBLIC' : ident(String(row.grantee));
+    findings.push(`${row.grantee} holds ${row.privilege}${on} on ${row.table}. `
+      + `Fix: REVOKE ${row.privilege}${on} ON TABLE ${quoteLabel(String(row.table))} FROM ${who};`);
+  }
+
+  for (const row of await runner(markerSql(lc))) {
+    const sig = String(row.sig) as keyof typeof DESTROY_LOG_MARKER_BODIES;
+    const fn = `marker function ${sig}`;
+    if (!truthy(row.present)) { findings.push(`${fn} is missing. Fix: run db:provision.`); continue; }
+    if (!truthy(row.secdef)) findings.push(`${fn} is not SECURITY DEFINER. Fix: run db:provision.`);
+    if (row.owner !== row.log_owner) {
+      findings.push(`${fn} is owned by ${row.owner}, not ${row.log_owner} (the owner of everystack.destroy_log). `
+        + `Fix: ALTER FUNCTION ${sig} OWNER TO ${ident(String(row.log_owner))}; then run db:provision.`);
+    }
+    const others = textList(row.others);
+    if (others.length > 0) findings.push(`${fn} grants EXECUTE to ${others.join(', ')}. Fix: run db:provision.`);
+    if (!truthy(row.lifecycle_execute)) findings.push(`${fn} does not grant EXECUTE to ${lc}. Fix: run db:provision.`);
+    if (row.language !== DESTROY_LOG_MARKER_LANGUAGES[sig]) {
+      findings.push(`${fn} is in language ${row.language}, not ${DESTROY_LOG_MARKER_LANGUAGES[sig]}. Fix: run db:provision.`);
+    }
+    if ((row.config ?? '') !== MARKER_CONFIG) {
+      findings.push(`${fn} has settings ${row.config || '(none)'}, not ${MARKER_CONFIG}. Fix: run db:provision.`);
+    }
+    if (row.body_md5 !== md5(DESTROY_LOG_MARKER_BODIES[sig])) {
+      findings.push(`${fn} has a body other than the one db:provision installs. Fix: run db:provision.`);
+    }
+  }
+
+  for (const row of await runner(triggerOwnerSql(tables, apps))) {
+    findings.push(triggerOwnerFinding({ trigger: String(row.trigger), table: String(row.table), function: String(row.function),
+      owner: String(row.owner), via: textList(row.via) }));
+  }
+
+  const declared = new Set(inputs.dependentKeys.map(key => JSON.stringify([key.child, key.column, key.parent])));
+  const modeled = new Set(inputs.modeledTables ?? []);
+  // After the state apply a key the models no longer hold, or now declare, may not be converged yet.
+  const applyFirst = inputs.modeledTables ? '' : 'If the models already refer to it by value or declare it, mint a plan that drops or rewrites the key '
+    + '(db:plan, with --allow-drops when it is a drop) and db:apply it. Otherwise ';
+  const unrecorded = new Set(inputs.nullifyUnrecorded ?? []);
+  for (const row of await runner(inboundKeySql(tables))) {
+    // Before the plan, a modeled table's keys are the plan's to converge: the models hold only
+    // declared keys from lifecycle tables (or refuse to compile), and the plan drops the rest.
+    if (modeled.has(String(row.child))) continue;
+    const columns = textList(row.columns);
+    const key = `foreign key ${row.constraint} on ${row.child} (${columns.join(', ')}) references lifecycle table ${row.parent} `
+      + `with ON DELETE ${ON_DELETE[String(row.action)] ?? row.action}`;
+    const drop = `ALTER TABLE ${quoteLabel(String(row.child))} DROP CONSTRAINT ${ident(String(row.constraint))};`;
+    if (!tables.includes(String(row.child))) {
+      findings.push(`${key}, but ${row.child} is not a lifecycle table: only a lifecycle table may hold a foreign key into a lifecycle table. `
+        + `Fix: ${applyFirst}${applyFirst ? 'make' : 'Make'} ${row.child} a lifecycle model and declare the dependent on ${row.parent}, or refer to it by value and drop the key: ${drop}`);
+      continue;
+    }
+    if (columns.length === 1 && declared.has(JSON.stringify([row.child, columns[0], row.parent]))) continue;
+    findings.push(`${key}, and no model declares what deleting a ${row.parent} row does to it: soft delete never consults it, `
+      + `so destroy would defer or skip the row. Fix: ${applyFirst}${applyFirst ? 'declare' : 'Declare'} it as a hasMany dependent on ${row.parent}, or drop the key: ${drop}`
+      + (unrecorded.has(String(row.parent)) ? ` The declared layer for ${row.parent} carries no nullify record, so the sending CLI may predate it: `
+        + 'if the models declare this key nullify, upgrade the CLI (@everystack/cli) and re-run.' : ''));
+  }
+
+  return findings;
+}
+
+/**
+ * A lifecycle finding raised around the derived layer: by the pre-exposure gate (nothing derived
+ * was written) or by the post-check (the objects are live). Its message is the whole report, one
+ * line of head and one line per finding, so a caller prints it as is.
+ */
+export class LifecycleFindingsError extends Error {}
+
+/**
+ * The pre-exposure gate: rule 5 over the DECLARED owners, before the reconcile creates anything.
+ * Each declared trigger on a lifecycle table whose function is declared is judged by the owner the
+ * reconcile will give that function (reconcileOwner: the declared owner, else the role the
+ * reconcile runs as). A declared owner that does not exist live is a finding. A trigger whose
+ * function is not declared is left to the post-check, which reads the live owner.
+ *
+ * `session` reads the builder: it runs on the connection the reconcile writes on. On a stage that
+ * is db:session, the operator connection; db:query (`runner`) may run on a reader
+ * (QUERY_DATABASE_URL), whose CURRENT_USER is not the role that will own the function. `runner`
+ * reads only pg_roles, which is the same on any connection.
+ *
+ * `stateApplied`: the table and column changes have committed, so the refusal says so.
+ */
+export async function lifecycleDeclaredOwnerRefusal(
+  runner: QueryRunner,
+  session: SessionRunner,
+  declared: readonly SourceObject[],
+  models: readonly ModelDescriptor[],
+  options: { stateApplied: boolean },
+): Promise<string | null> {
+  const { lifecycleTables, applicationRoles } = catalogInputsFromModels(models);
+  const tables = new Set(lifecycleTables);
+  const triggers = declared.flatMap((object) => {
+    if (object.kind !== 'trigger' || !object.table) return [];
+    const { schema, name } = parseQualified(object.table);
+    const fn = tables.has(`${schema}.${name}`) ? triggerFunctionOf(object, declared) : undefined;
+    return fn ? [{ trigger: object.name, table: `${schema}.${name}`, fn }] : [];
+  });
+  if (triggers.length === 0) return null;
+  const [slot] = await session(['SELECT CURRENT_USER::text AS builder']);
+  if (isSessionError(slot) || slot?.[0]?.builder == null) throw new Error('could not read the role the reconcile runs as (CURRENT_USER)');
+  const builder = String(slot[0].builder);
+  const judged = triggers.map(t => ({ ...t, owner: reconcileOwner(t.fn, builder) }));
+  const owners = [...new Set(judged.map(t => t.owner))].sort();
+  const rows = await runner(`WITH ${sideCte(applicationRoles)}
+    SELECT d.name AS owner, o.oid IS NOT NULL AS present,
+      ARRAY(SELECT s.rolname FROM side s WHERE s.oid = o.oid OR ${reaches('s.oid', 'o.oid')} ORDER BY 1) AS via
+    FROM pg_catalog.unnest(${textArray(owners)}) AS d(name) LEFT JOIN pg_catalog.pg_roles o ON o.rolname = d.name`);
+  const byOwner = new Map(rows.map(row => [String(row.owner), { present: truthy(row.present), via: textList(row.via) }]));
+  const findings = judged.flatMap((t) => {
+    const owner = byOwner.get(t.owner);
+    if (!owner?.present) {
+      return [`trigger ${t.trigger} on ${t.table} would run ${t.fn.identity}, owned by ${t.owner}, which does not exist. `
+        + `Fix: create ${t.owner} as a role no application role can act as, or declare an existing such role as ${t.fn.identity}'s owner in db/models.`];
+    }
+    if (owner.via.length === 0) return [];
+    return [triggerOwnerFinding({ trigger: t.trigger, table: t.table, function: t.fn.identity, owner: t.owner, via: owner.via }, true)];
+  });
+  if (findings.length === 0) return null;
+  return `${options.stateApplied ? 'tables and columns applied; ' : ''}derived layer NOT applied: ${countFindings(findings.length)}; `
+    + `fix each, then re-run:\n${findingLines(findings)}`;
+}
+
+/**
+ * The post-check: the live catalog check again, after the derived layer landed. The reconcile
+ * commits what it created, so the report never says refused or rolled back: the objects are live,
+ * and the next apply's preflight refuses until each finding is fixed.
+ *
+ * It reads on `session`, the reconcile's own connection: on a stage, db:session (the operator
+ * connection). db:query may read a replica the reconcile's commit has not reached yet, and pass.
+ */
+export async function lifecyclePostApplyRefusal(session: SessionRunner, models: readonly ModelDescriptor[]): Promise<string | null> {
+  if (!models.some(model => model.lifecycle === true)) return null;
+  const read: QueryRunner = async (q) => {
+    const [slot] = await session([q]);
+    if (isSessionError(slot)) throw new Error(slot.message);
+    return slot ?? [];
+  };
+  const findings = await lifecycleCatalogFindings(read, catalogInputsFromModels(models));
+  if (findings.length === 0) return null;
+  return `${countFindings(findings.length)} after reconcile; the objects are live; the next apply refuses until fixed:\n${findingLines(findings)}`;
+}
+
+/** An older CLI sends no applicationRoles, so the catalog check cannot run: fail closed. */
+export const LIFECYCLE_ROLES_ABSENT_REFUSAL = 'this db:reconcile payload carries lifecycle-owned objects but no application roles, '
+  + 'so the lifecycle catalog check cannot run. The sending CLI predates the check: upgrade the CLI (@everystack/cli) and re-run.';
+
+/** The declared dependents are read from the transition functions' manifests: one without fails closed. */
+export const LIFECYCLE_MANIFEST_ABSENT_REFUSAL = (functions: readonly string[]): string => `this db:reconcile payload's lifecycle transition `
+  + `function${functions.length === 1 ? '' : 's'} ${functions.join(', ')} carr${functions.length === 1 ? 'ies' : 'y'} no manifest, so the declared dependents `
+  + 'cannot be read and the lifecycle catalog check cannot run. Compile the declared layer from the models with this CLI and re-run.';
+
+/** Generated by an older CLI (0.4.101's per-row restrict pair); a payload may still carry one it is replacing. */
+const RETIRED_LIFECYCLE_ROLES = ['restrict'] as const;
+
+/**
+ * The lifecycle tables, read from the declared derived layer: each `<t>_lifecycle_transition`
+ * trigger names its table. Every lifecycle-owned object must belong to one of those tables by its
+ * exact generated name in the table's schema (lifecycleRole, or a retired role). Never by prefix:
+ * every name of a table `t_lifecycle_x` starts with `t_lifecycle_`, so a prefix would hand them to
+ * `t`. One that belongs to none is a contradiction, refused: the check would otherwise run on fewer
+ * tables than the objects it arms. Never read from the live catalog, which would be a second
+ * derivation that drifts.
+ */
+export function lifecycleTablesFromDeclared(declared: readonly SourceObject[]): { tables: string[] } | { refusal: string } {
+  const tables = [...new Set(declared.flatMap(object => {
+    if (object.kind !== 'trigger' || !object.table) return [];
+    const { schema, name } = parseQualified(object.table);
+    return object.name === `${name}_lifecycle_transition` ? [`${schema}.${name}`] : [];
+  }))].sort();
+  const orphans = declared.filter(object => object.owner === LIFECYCLE_OWNER_ROLE
+    && !tables.some(table => table.startsWith(`${object.schema}.`) && (lifecycleRole(`${object.schema}.${object.name}`, table) !== undefined
+      || RETIRED_LIFECYCLE_ROLES.some(role => `${object.schema}.${object.name}` === `${table}_lifecycle_${role}`))))
+    .map(object => object.identity).sort();
+  if (orphans.length === 0) return { tables };
+  return {
+    refusal: `the declared derived layer contradicts itself: ${orphans.join(', ')} ${orphans.length === 1 ? 'is' : 'are'} owned by `
+      + `${LIFECYCLE_OWNER_ROLE}, but no declared <table>_lifecycle_transition trigger names ${orphans.length === 1 ? 'its table' : 'their tables'}. `
+      + 'The lifecycle tables are read from those triggers, so the catalog check cannot cover these objects. '
+      + 'Compile the declared layer from the models with this CLI and re-run.',
+  };
+}
+
+/**
+ * db:reconcile's lifecycle gate, local and in the ops Lambda alike: the destroy_log shape, the
+ * declared layer's own consistency, the application roles' presence (fail closed), then the
+ * catalog check. Null when nothing declared is lifecycle-owned. `applicationRoles` is `unknown`
+ * because the ops Lambda reads it off the wire.
+ */
+export async function lifecycleReconcileRefusal(
+  runner: QueryRunner,
+  declared: readonly SourceObject[],
+  options: { applicationRoles?: unknown; lifecycleRole?: string } = {},
+): Promise<string | null> {
+  if (!declared.some(object => object.owner === LIFECYCLE_OWNER_ROLE)) return null;
+  const [log] = await runner(LIFECYCLE_LOG_SQL);
+  const shape = lifecycleLogRowRefusal(log);
+  if (shape) return shape;
+  const derived = lifecycleTablesFromDeclared(declared);
+  if ('refusal' in derived) return derived.refusal;
+  const roles = options.applicationRoles;
+  if (!Array.isArray(roles) || roles.some(role => typeof role !== 'string')) return LIFECYCLE_ROLES_ABSENT_REFUSAL;
+  const unreadable = declared.filter(object => object.owner === LIFECYCLE_OWNER_ROLE && object.name.endsWith('_lifecycle_transition')
+    && !lifecycleManifestOf(object)).map(object => object.identity).sort();
+  if (unreadable.length > 0) return LIFECYCLE_MANIFEST_ABSENT_REFUSAL(unreadable);
+  return lifecycleCatalogRefusal(runner, { lifecycleTables: derived.tables, applicationRoles: roles, dependentKeys: dependentKeysFromDeclared(declared),
+    nullifyUnrecorded: nullifyUnrecordedFromDeclared(declared) },
+    { lifecycleRole: options.lifecycleRole });
+}
+
+// Live = fires in an ordinary session ('O' origin/local, 'A' always; not 'R' replica-only or 'D')
+// and runs the table's own generated transition function, not merely a trigger with its name.
+const LIVE_TRANSITIONS_SQL = `SELECT n.nspname || '.' || c.relname AS "table" FROM pg_catalog.pg_trigger g
+  JOIN pg_catalog.pg_class c ON c.oid = g.tgrelid JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+  JOIN pg_catalog.pg_proc p ON p.oid = g.tgfoid
+  WHERE NOT g.tgisinternal AND g.tgenabled IN ('O', 'A') AND g.tgname = c.relname || '_lifecycle_transition'
+    AND p.pronamespace = c.relnamespace AND p.proname = c.relname || '_lifecycle_transition'`;
+
+/**
+ * --state-only skips the derived layer, so a lifecycle table whose transition trigger is not live
+ * would keep its DELETE policies with nothing turning a DELETE into a soft delete.
+ */
+export async function lifecycleStateOnlyRefusal(runner: QueryRunner, models: readonly ModelDescriptor[]): Promise<string | null> {
+  const lifecycle = models.filter(model => model.lifecycle === true);
+  if (lifecycle.length === 0) return null;
+  const live = new Set((await runner(LIVE_TRANSITIONS_SQL)).map(row => row.table));
+  const missing = lifecycle.map(model => `${model.schema}.${model.table}`).filter(table => !live.has(table)).sort();
+  if (missing.length === 0) return null;
+  return `--state-only skips the lifecycle triggers, and ${missing.join(', ')} ${missing.length === 1 ? 'has' : 'have'} no live transition trigger, `
+    + 'so a DELETE there would remove rows for real. Run db:apply without --state-only.';
+}