@everystack/server 0.4.37 → 0.4.38

package/src/provision.ts

@@ -20,7 +20,7 @@
  * without a database; plugin.ts wires the real deps.
  */
 
-import { generateRoleChainSQL, generateAdminRoleSQL, generateSearchPathSQL, generateRotationPairSQL, generateReaderRoleSQL } from './role-chain';
+import { generateRoleChainSQL, generateAdminRoleSQL, generateSearchPathSQL, generateRotationPairSQL, generateReaderRoleSQL, generateLifecycleRoleSQL, LIFECYCLE_ROLE } from './role-chain';
 import {
   pgVersionRefusal,
   ownerFactsSql,
@@ -107,6 +107,12 @@ export interface ProvisionPayload {
   searchPath?: string[];
   /** Create A/B rotation pairs for credential rotation without downtime. */
   rotationPairs?: boolean;
+  /**
+   * The Models declare a `lifecycle: true` model, so provision the reserved role it compiles to
+   * (everystack_lifecycle): NOLOGIN NOINHERIT NOBYPASSRLS, no grants, no members. Derived from the
+   * Models barrel by the CLI. Absent or false (an older CLI) = no role is created, as before.
+   */
+  lifecycleRole?: boolean;
 }
 
 /**
@@ -148,6 +154,20 @@ export interface ProvisionDeps {
    * not-existing (the role is being created now, so its password IS set).
    */
   roleHasLogin?: (role: string) => Promise<boolean>;
+  /**
+   * The lifecycle role's name. A TEST seam only: the role is cluster-level and a dev cluster may
+   * already hold the real one. No caller sets it; absent = everystack_lifecycle.
+   */
+  lifecycleRoleName?: string;
+}
+
+/** One direct member of the lifecycle role, with the options its membership carries. */
+export interface LifecycleRoleMember {
+  role: string;
+  admin: boolean;
+  inherit: boolean;
+  /** Can SET ROLE to it (always true before PostgreSQL 16, which has no per-grant SET option). */
+  set: boolean;
 }
 
 export interface ProvisionResult {
@@ -202,6 +222,23 @@ export interface ProvisionResult {
    * says nothing about it. Same non-fatal contract as ENACT: never throws, never aborts.
    */
   publicSchemaPosture?: PublicSchemaPosture;
+  /**
+   * The reserved lifecycle role. Absent when the payload did not ask for it. `created` = false means
+   * it existed and its attributes were re-asserted. `members` are its direct members, reported and
+   * never revoked: a member can SET ROLE to it, and that passes the lifecycle guard. Null when this
+   * caller cannot read (no `query` dep).
+   */
+  lifecycleRole?: {
+    role: string;
+    created: boolean | null;
+    members: LifecycleRoleMember[] | null;
+    /**
+     * Elevated attributes an existing role carries that provision does not strip (CREATEROLE,
+     * CREATEDB, REPLICATION), for the CLI to name. SUPERUSER is never here: it is refused.
+     * Null when this caller cannot read.
+     */
+    attributes: string[] | null;
+  };
   error?: string;
 }
 
@@ -238,8 +275,11 @@ export async function runProvision(
   let roleSql: string;
   let adminSql: string | null = null;
   let readerSql: string | null = null;
+  let lifecycleSql: string | null = null;
+  const lifecycleRole = deps.lifecycleRoleName ?? LIFECYCLE_ROLE;
   try {
     roleSql = generateRoleChainSQL({ loginRole, appRoles });
+    if (payload.lifecycleRole === true) lifecycleSql = generateLifecycleRoleSQL(lifecycleRole);
     if (adminPassword) adminSql = generateAdminRoleSQL({ adminRole });
     if (readerPassword) readerSql = generateReaderRoleSQL({ readerRole });
   } catch (err: any) {
@@ -256,6 +296,30 @@ export async function runProvision(
   const adminExisted = !!adminPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(admin));
   const readerExisted = !!readerPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(reader));
 
+  // The lifecycle role's live state, read BEFORE any DDL so a refusal leaves nothing half-done.
+  let lifecycleLive: { existed: boolean; attributes: string[] } | null = null;
+  if (lifecycleSql && deps.query) {
+    const [row] = await deps.query(
+      `SELECT rolsuper, rolcreaterole, rolcreatedb, rolreplication FROM pg_roles WHERE rolname = '${lifecycleRole}'`,
+    );
+    const on = (v: unknown): boolean => v === true || v === 't' || v === 'true';
+    if (row && on(row.rolsuper)) {
+      // Not fixed by the ALTER: PostgreSQL 16 refuses NOSUPERUSER from a non-superuser, and a
+      // superuser owning SECURITY DEFINER functions makes every one of them run as a superuser.
+      throw new Error(
+        `the lifecycle role '${lifecycleRole}' exists with SUPERUSER — refused before any change. ` +
+        `As a superuser run: ALTER ROLE ${lifecycleRole} NOSUPERUSER; (or drop the role and re-run db:provision).`,
+      );
+    }
+    lifecycleLive = {
+      existed: !!row,
+      attributes: row
+        ? ([['CREATEROLE', row.rolcreaterole], ['CREATEDB', row.rolcreatedb], ['REPLICATION', row.rolreplication]] as const)
+          .filter(([, v]) => on(v)).map(([name]) => name)
+        : [],
+    };
+  }
+
   await deps.execute(roleSql);
 
   const result: ProvisionResult = {
@@ -265,6 +329,18 @@ export async function runProvision(
     passwordSet: false,
   };
 
+  // The reserved lifecycle role — a NOLOGIN role with no password, so it sits with the role chain,
+  // ahead of every password and well clear of the password-to-secret window.
+  if (lifecycleSql) {
+    await deps.execute(lifecycleSql);
+    result.lifecycleRole = {
+      role: lifecycleRole,
+      created: lifecycleLive ? !lifecycleLive.existed : null,
+      members: deps.query ? await lifecycleRoleMembers(lifecycleRole, deps.query) : null,
+      attributes: lifecycleLive ? lifecycleLive.attributes : null,
+    };
+  }
+
   // The role-default search_path (search-path-ownership): set it on the login role now that it
   // exists. The right layer — a clean connection secret, bare refs resolved for every direct
   // connection, and it persists through the API's SET ROLE. No-op for an all-public app.
@@ -387,6 +463,26 @@ export async function runProvision(
   return result;
 }
 
+/**
+ * The direct members of the lifecycle role, from pg_auth_members. `to_jsonb(m)` reads the
+ * PostgreSQL 16 per-grant options without naming columns an older server lacks; before 16 every
+ * membership could SET ROLE and INHERIT followed the member, so a missing option reads that way.
+ */
+async function lifecycleRoleMembers(role: string, query: (sql: string) => Promise<any[]>): Promise<LifecycleRoleMember[]> {
+  const rows = await query(
+    `SELECT r.rolname AS member, m.admin_option AS admin,
+            COALESCE((to_jsonb(m) ->> 'inherit_option')::boolean, r.rolinherit) AS inherit,
+            COALESCE((to_jsonb(m) ->> 'set_option')::boolean, true) AS set
+       FROM pg_auth_members m
+       JOIN pg_roles g ON g.oid = m.roleid
+       JOIN pg_roles r ON r.oid = m.member
+      WHERE g.rolname = '${role}'
+      ORDER BY r.rolname`,
+  );
+  const truthy = (v: unknown): boolean => v === true || v === 't' || v === 'true';
+  return rows.map((r) => ({ role: String(r.member), admin: truthy(r.admin), inherit: truthy(r.inherit), set: truthy(r.set) }));
+}
+
 /**
  * Converge declared ownership — ENACT (Gap 1) then ADOPT (Gap 2) — as a step SEPARATE from and
  * AFTER credential provisioning + the secret-store write (see runProvision's closing note). By the

package/src/purge-graph.ts

@@ -0,0 +1,91 @@
+/** Refuse physical removal when live foreign keys exceed the declared lifecycle graph. */
+import { sql } from 'drizzle-orm';
+import type { ModelDescriptor, Relation } from '@everystack/model';
+import type { SessionTx } from './db-session';
+
+interface ForeignKey {
+  parent_schema: string;
+  parent_table: string;
+  child_schema: string;
+  child_table: string;
+  parent_columns: string[];
+  child_columns: string[];
+  action: string;
+  child_lifecycle: boolean;
+}
+const label = (m: ModelDescriptor): string => `${m.schema}.${m.table}`;
+const parentOf = (f: ForeignKey): string => `${f.parent_schema}.${f.parent_table}`;
+const childOf = (f: ForeignKey): string => `${f.child_schema}.${f.child_table}`;
+const snake = (name: string): string => name.replace(/[A-Z]/g, c => '_' + c.toLowerCase());
+const expectedAction = (rel: Relation, liveLifecycle: boolean): string => rel.dependent === 'nullify' ? 'n'
+  : rel.dependent === 'cascade' && !liveLifecycle && !rel.target().lifecycle ? 'c' : 'r';
+
+function matches(fk: ForeignKey, parent: ModelDescriptor, rel: Relation): boolean {
+  return rel.kind === 'hasMany' && Boolean(rel.dependent)
+    && parentOf(fk) === label(parent) && childOf(fk) === label(rel.target())
+    && fk.child_columns.length === 1 && fk.child_columns[0] === snake(rel.column)
+    && fk.parent_columns.length === 1 && fk.parent_columns[0] === snake(rel.references ?? parent.primaryKey[0]);
+}
+
+/** Catalog read only. A refusal has no hook, DELETE or receipt, even for eligible rows. */
+export async function unsupportedPurgeGraphs(exec: SessionTx, models: ModelDescriptor[]): Promise<Map<string, string>> {
+  const raw: unknown = await exec.execute(sql`
+    SELECT pn.nspname AS parent_schema, p.relname AS parent_table,
+      cn.nspname AS child_schema, c.relname AS child_table, f.confdeltype AS action,
+      ARRAY(SELECT a.attname FROM unnest(f.confkey) WITH ORDINALITY k(num,pos)
+        JOIN pg_catalog.pg_attribute a ON a.attrelid=p.oid AND a.attnum=k.num ORDER BY k.pos) AS parent_columns,
+      ARRAY(SELECT a.attname FROM unnest(f.conkey) WITH ORDINALITY k(num,pos)
+        JOIN pg_catalog.pg_attribute a ON a.attrelid=c.oid AND a.attnum=k.num ORDER BY k.pos) AS child_columns,
+      EXISTS (SELECT 1 FROM pg_catalog.pg_trigger t
+        JOIN pg_catalog.pg_proc fn ON fn.oid=t.tgfoid
+        JOIN pg_catalog.pg_roles r ON r.oid=fn.proowner
+        WHERE t.tgrelid=c.oid AND NOT t.tgisinternal
+          AND (t.tgtype & 2)=2 AND (t.tgtype & 8)=8
+          AND r.rolname='everystack_lifecycle') AS child_lifecycle
+    FROM pg_catalog.pg_constraint f
+      JOIN pg_catalog.pg_class p ON p.oid=f.confrelid
+      JOIN pg_catalog.pg_namespace pn ON pn.oid=p.relnamespace
+      JOIN pg_catalog.pg_class c ON c.oid=f.conrelid
+      JOIN pg_catalog.pg_namespace cn ON cn.oid=c.relnamespace
+    WHERE f.contype='f'`);
+  const fks = (Array.isArray(raw) ? raw : (raw as { rows: ForeignKey[] }).rows) as ForeignKey[];
+  const byParent = new Map<string, ForeignKey[]>();
+  for (const fk of fks) byParent.set(parentOf(fk), [...(byParent.get(parentOf(fk)) ?? []), fk]);
+  const declared = new Map(models.map(m => [label(m), m]));
+  const badActions = new Map<string, string>();
+  for (const model of models) {
+    const root = label(model);
+    for (const rel of Object.values(model.relations)) {
+      if (rel.kind !== 'hasMany' || !rel.dependent) continue;
+      const edges = (byParent.get(root) ?? []).filter(fk => matches(fk, model, rel));
+      if (!edges.length || edges.some(fk => fk.action !== expectedAction(rel, fk.child_lifecycle))) {
+        badActions.set(root, `unsupported graph: ${label(rel.target())} foreign key disagrees with declared ${rel.dependent}`);
+      }
+    }
+  }
+  const refused = new Map<string, string>();
+  for (const model of models.filter(m => m.lifecycle)) {
+    const root = label(model);
+    const visited = new Set<string>();
+    const walk = (parent: string): string | undefined => {
+      const mismatch = badActions.get(parent);
+      if (mismatch) return mismatch;
+      if (visited.has(parent)) return;
+      visited.add(parent);
+      for (const fk of byParent.get(parent) ?? []) {
+        const child = childOf(fk);
+        const descriptor = declared.get(parent);
+        const rel = descriptor && Object.values(descriptor.relations).find(r => matches(fk, descriptor, r));
+        if (fk.child_lifecycle && (!rel || fk.action !== expectedAction(rel, fk.child_lifecycle))) {
+          return `unsupported graph: path ${root} reaches undeclared lifecycle edge ${parent} -> ${child}`;
+        }
+        if (!['c', 'n', 'd'].includes(fk.action)) continue;
+        const deeper = walk(child);
+        if (deeper) return deeper;
+      }
+    };
+    const reason = walk(root);
+    if (reason) refused.set(root, reason);
+  }
+  return refused;
+}

package/src/purge-log.ts

@@ -0,0 +1,63 @@
+/**
+ * The purge ledger contains keys and outcomes, never row payloads. Run this ensure
+ * as the table owner before purging. Only the lifecycle role may append receipts.
+ * Mutation guards also refuse a writer with direct privileges. The trusted owner
+ * can still disable these triggers; this is not a boundary against that owner.
+ */
+export const ENSURE_PURGE_LOG_SQL: string[] = [
+  'CREATE SCHEMA IF NOT EXISTS everystack',
+  `CREATE TABLE IF NOT EXISTS everystack.purge_log (
+    run_id uuid NOT NULL,
+    "table" text NOT NULL,
+    "key" text NOT NULL,
+    deleted_batch uuid,
+    deleted_at timestamptz NOT NULL,
+    purged_at timestamptz NOT NULL,
+    actor text,
+    outcome text NOT NULL CHECK (outcome IN ('purged', 'skipped', 'failed')),
+    hook text NOT NULL CHECK (hook IN ('ran', 'none', 'failed')),
+    detail text
+  )`,
+  'CREATE INDEX IF NOT EXISTS purge_log_key_time ON everystack.purge_log ("table", "key", purged_at)',
+  // Typed key comparisons still need an index that bounds the recent receipt window.
+  'CREATE INDEX IF NOT EXISTS purge_log_table_time ON everystack.purge_log ("table", purged_at)',
+  `CREATE OR REPLACE FUNCTION everystack.purge_log_refuse_mutation() RETURNS trigger
+    LANGUAGE plpgsql SET search_path = pg_catalog AS $guard$
+    BEGIN
+      RAISE EXCEPTION 'everystack.purge_log is append-only' USING ERRCODE = '42501';
+    END
+    $guard$`,
+  `CREATE OR REPLACE TRIGGER purge_log_no_mutation BEFORE UPDATE OR DELETE ON everystack.purge_log
+    FOR EACH ROW EXECUTE FUNCTION everystack.purge_log_refuse_mutation()`,
+  `CREATE OR REPLACE TRIGGER purge_log_no_truncate BEFORE TRUNCATE ON everystack.purge_log
+    FOR EACH STATEMENT EXECUTE FUNCTION everystack.purge_log_refuse_mutation()`,
+  // PUBLIC function defaults would become reachable after the new schema USAGE grant.
+  'REVOKE EXECUTE ON ALL FUNCTIONS IN SCHEMA everystack FROM PUBLIC',
+  'REVOKE ALL PRIVILEGES ON TABLE everystack.purge_log FROM PUBLIC',
+  `DO $acl$
+    DECLARE r record;
+    BEGIN
+      FOR r IN
+        SELECT DISTINCT roles.rolname
+        FROM (
+          SELECT acl.grantee
+          FROM pg_catalog.pg_class c CROSS JOIN LATERAL pg_catalog.aclexplode(c.relacl) acl
+          WHERE c.oid = 'everystack.purge_log'::regclass
+          UNION
+          SELECT acl.grantee
+          FROM pg_catalog.pg_attribute a CROSS JOIN LATERAL pg_catalog.aclexplode(a.attacl) acl
+          WHERE a.attrelid = 'everystack.purge_log'::regclass AND a.attnum > 0 AND NOT a.attisdropped
+        ) grants JOIN pg_catalog.pg_roles roles ON roles.oid = grants.grantee
+        WHERE grants.grantee <> 0 AND roles.oid <> (
+          SELECT c.relowner FROM pg_catalog.pg_class c WHERE c.oid = 'everystack.purge_log'::regclass
+        )
+      LOOP
+        EXECUTE pg_catalog.format('REVOKE ALL PRIVILEGES ON TABLE everystack.purge_log FROM %I', r.rolname);
+        EXECUTE pg_catalog.format('REVOKE ALL PRIVILEGES (run_id, "table", "key", deleted_batch, deleted_at, purged_at, actor, outcome, hook, detail) ON TABLE everystack.purge_log FROM %I', r.rolname);
+      END LOOP;
+    END
+    $acl$`,
+  'REVOKE ALL PRIVILEGES (run_id, "table", "key", deleted_batch, deleted_at, purged_at, actor, outcome, hook, detail) ON TABLE everystack.purge_log FROM PUBLIC',
+  'GRANT USAGE ON SCHEMA everystack TO everystack_lifecycle',
+  'GRANT INSERT ON TABLE everystack.purge_log TO everystack_lifecycle',
+];

package/src/purge.ts

@@ -0,0 +1,337 @@
+/** Real lifecycle removal. Provision ENSURE_PURGE_LOG_SQL on the owner connection first. */
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { sql, type SQL } from 'drizzle-orm';
+import type { ModelDescriptor, DestroyContext } from '@everystack/model';
+import type { SessionTx } from './db-session';
+import { unsupportedPurgeGraphs } from './purge-graph';
+export { ENSURE_PURGE_LOG_SQL } from './purge-log';
+
+/** A destroy hook failed after physical removal committed. */
+export interface PurgeHookFault {
+  kind: 'hook';
+  name: string;
+  method: 'DELETE';
+  status: 500;
+  table: string;
+  key: string;
+  message: string;
+  stack?: string;
+}
+export interface PurgeOptions {
+  /** Retention in milliseconds, strictly positive. */
+  after: number;
+  /** Maximum rows physically purged across all tables. */
+  batch: number;
+  /** One clock for both selection and receipts. Defaults to the run's start. */
+  now?: Date;
+  /** Elapsed-time budget, checked between rows; a current transaction finishes. Default 30000. */
+  budgetMs?: number;
+  /** Cooldown for skipped or failed keys, in milliseconds. Default one hour. Zero disables it. */
+  retryAfterMs?: number;
+  /** After-commit hook faults; a sink failure cannot undo removal or stop the run. */
+  onError?: (fault: PurgeHookFault) => void | Promise<void>;
+}
+export interface PurgeCounts { purged: number; skipped: number; failed: number; }
+export interface PurgeResult {
+  runId: string;
+  perTable: Record<string, PurgeCounts>;
+  noHook: string[];
+  skipped: { table: string; key: string; reason: string }[];
+  afterDestroyErrors: number;
+  afterDestroyFailures: { table: string; key: string; message: string }[];
+  incomplete?: true;
+  /** Why no rows were purged, when the run removed none. */
+  reason?: string;
+}
+
+type Row = Record<string, unknown>;
+type Receipt = { model: ModelDescriptor; row: Row; outcome: 'purged' | 'skipped' | 'failed'; hook: 'ran' | 'none' | 'failed'; detail?: string };
+const context: DestroyContext = Object.freeze({ source: 'purge', user: null, client: null });
+const param = (value: unknown): unknown => value instanceof Date ? value.toISOString() : typeof value === 'bigint' ? value.toString() : value;
+const snake = (name: string): string => name.replace(/[A-Z]/g, c => '_' + c.toLowerCase());
+const label = (m: ModelDescriptor): string => `${m.schema}.${m.table}`;
+const table = (m: ModelDescriptor): SQL => sql`${sql.identifier(m.schema)}.${sql.identifier(m.table)}`;
+const column = (key: string): SQL => sql`${sql.identifier(snake(key))}`;
+const rowsOf = (result: unknown): Row[] => Array.isArray(result) ? result : (result as { rows: Row[] }).rows;
+function fieldParam(model: ModelDescriptor, key: string, value: unknown): unknown {
+  const spec = model.fields[key].spec;
+  if (spec.isArray) return sql`(jsonb_populate_record(NULL::${table(model)}, jsonb_build_object(${snake(key)}::text, ${JSON.stringify(value)}::jsonb))).${column(key)}`;
+  const type = spec.type;
+  return type === 'json' || type === 'jsonb' ? JSON.stringify(value) : param(value);
+}
+
+/** Keep timestamp key identity independent of the session timezone without losing microseconds. */
+function keyValue(model: ModelDescriptor, key: string, row: Row): unknown {
+  const value = row[snake(key)];
+  if (value instanceof Uint8Array) return '\\x' + Buffer.from(value).toString('hex');
+  const spec = model.fields[key].spec;
+  if (spec.isArray || spec.type === 'json' || spec.type === 'jsonb') return JSON.stringify(value);
+  const type = spec.type === 'pgType' ? spec.pgTypeName : spec.type;
+  if (!/^(timestamptz|timestamp(?:\(\d+\))? with time zone)$/i.test(type ?? '')) return param(value);
+  if (value === 'infinity' || value === '-infinity') return value;
+  const date = value instanceof Date ? value : new Date(String(value));
+  if (!Number.isFinite(date.getTime())) throw new Error(`purge cannot normalize timestamp key on ${label(model)}`);
+  const iso = date.toISOString();
+  const fraction = typeof value === 'string' ? value.match(/\.(\d+)/)?.[1] : undefined;
+  const precise = (fraction ?? iso.match(/\.(\d+)Z$/)![1]).replace(/0+$/, '').padEnd(3, '0');
+  return iso.replace(/\.\d{3}Z$/, `.${precise}Z`);
+}
+const keyValues = (m: ModelDescriptor, row: Row): unknown[] => m.primaryKey.map(k => keyValue(m, k, row));
+function keyOf(model: ModelDescriptor, row: Row): string {
+  const values = keyValues(model, row);
+  if (values.length !== 1) return JSON.stringify(values);
+  return typeof values[0] === 'object' ? JSON.stringify(values[0]) : String(values[0]);
+}
+const keyWhere = (m: ModelDescriptor, row: Row): SQL => sql.join(m.primaryKey.map(k => sql`${column(k)} = ${fieldParam(m, k, row[snake(k)])}`), sql` AND `);
+const hookRow = (m: ModelDescriptor, row: Row): Row => Object.fromEntries(Object.keys(m.fields).map(k => [k, row[snake(k)]]));
+
+/** Compare keys as their native type while guarding casts from other tables' receipts. */
+function cooldownKeyMatches(model: ModelDescriptor): SQL {
+  const key = model.primaryKey[0];
+  const spec = model.fields[key].spec;
+  const type = spec.type === 'pgType' ? spec.pgTypeName ?? '' : spec.type;
+  const candidate = sql`${table(model)}.${column(key)}`;
+  const ownKey = sql`CASE WHEN receipt."table" = ${label(model)} THEN receipt."key" END`;
+  if (spec.isArray) {
+    return sql`(jsonb_populate_record(NULL::${table(model)}, jsonb_build_object(${snake(key)}::text, ${ownKey}::jsonb))).${column(key)} = ${candidate}`;
+  }
+  if (type === 'json' || type === 'jsonb') return sql`${ownKey}::jsonb = ${candidate}`;
+  if (/^(timestamptz|timestamp(?:\(\d+\))? with time zone)$/i.test(type)) return sql`${ownKey}::timestamptz = ${candidate}`;
+  if (/^timestamp(?:\(\d+\))?(?: without time zone)?$/i.test(type)) return sql`${ownKey}::timestamp = ${candidate}`;
+  if (type === 'real') return sql`${ownKey}::real = ${candidate}`;
+  if (type === 'doublePrecision' || type === 'double precision') return sql`${ownKey}::double precision = ${candidate}`;
+  if (type === 'bytea') return sql`${ownKey}::bytea = ${candidate}`;
+  if (type === 'date') return sql`${ownKey}::date = ${candidate}`;
+  return sql`receipt."key" = ${candidate}::text`;
+}
+
+/** Every declared lifecycle edge orders the child before the parent, nullify included. */
+function orderedModels(models: ModelDescriptor[]): ModelDescriptor[] {
+  const lifecycle = models.filter(m => m.lifecycle);
+  const set = new Set(lifecycle);
+  const visiting = new Set<ModelDescriptor>();
+  const visited = new Set<ModelDescriptor>();
+  const ordered: ModelDescriptor[] = [];
+  const visit = (m: ModelDescriptor): void => {
+    if (visiting.has(m)) throw new Error(`purge relation cycle at ${label(m)}`);
+    if (visited.has(m)) return;
+    visiting.add(m);
+    for (const rel of Object.values(m.relations)) {
+      if (rel.kind === 'hasMany' && rel.dependent) {
+        const child = rel.target();
+        if (child.lifecycle && !set.has(child)) throw new Error(`purge needs declared child ${label(child)}`);
+        if (set.has(child)) visit(child);
+      }
+    }
+    visiting.delete(m); visited.add(m); ordered.push(m);
+  };
+  for (const m of lifecycle) {
+    if (m.primaryKey.length !== 1) throw new Error(`purge needs a single-column primary key on ${label(m)}`);
+    visit(m);
+  }
+  return ordered;
+}
+
+async function appendReceipt(tx: SessionTx, runId: string, now: Date, receipt: Receipt): Promise<void> {
+  const { model, row, outcome, hook, detail } = receipt;
+  await tx.execute(sql`SET LOCAL ROLE everystack_lifecycle`);
+  await tx.execute(sql`INSERT INTO everystack.purge_log
+    (run_id, "table", "key", deleted_batch, deleted_at, purged_at, actor, outcome, hook, detail)
+    VALUES (${runId}, ${label(model)}, ${keyOf(model, row)}, ${row.deleted_batch}, ${param(row.deleted_at)}, ${now.toISOString()}, 'purge', ${outcome}, ${hook}, ${detail ?? null})`);
+}
+
+/**
+ * Purge expired lifecycle rows, children first, in one transaction per selected row.
+ * The executor is the existing ops Drizzle database (execute/transaction); its caller
+ * must read the selected tables and purge_log, and SET ROLE to everystack_lifecycle. Hooks run outside
+ * that role after DELETE and immediate constraint checks; a hook throw rolls back the
+ * removal. A successful hook can repeat if commit fails, so it must be idempotent. A skipped row appends another
+ * skipped receipt on each retry. Plain children with ON DELETE CASCADE are removed by
+ * referential integrity; they receive neither a destroy hook nor a purge receipt.
+ * The receipt's hook status describes beforeDestroy. afterDestroy is best-effort after
+ * commit and cannot change that append-only receipt or undo the physical removal.
+ */
+export async function purgeExpired(exec: SessionTx, models: ModelDescriptor[], options: PurgeOptions): Promise<PurgeResult> {
+  const started = performance.now();
+  const after = options.after;
+  const batch = options.batch;
+  const budgetMs = options.budgetMs ?? 30_000;
+  const retryAfterMs = options.retryAfterMs ?? 3_600_000;
+  if (!Number.isFinite(budgetMs) || budgetMs < 0) throw new Error('purge budgetMs must be nonnegative milliseconds');
+  if (!Number.isFinite(retryAfterMs) || retryAfterMs < 0) throw new Error('purge retryAfterMs must be nonnegative milliseconds');
+  const outOfBudget = (): boolean => performance.now() - started >= budgetMs;
+  if (!Number.isFinite(after) || after <= 0) throw new Error('purge after must be positive milliseconds');
+  if (!Number.isSafeInteger(batch) || batch <= 0) throw new Error('purge batch must be a positive integer');
+  const now = new Date(options.now?.getTime() ?? Date.now());
+  const cutoff = new Date(now.getTime() - after);
+  if (!Number.isFinite(now.getTime()) || !Number.isFinite(cutoff.getTime())) throw new Error('purge needs a valid clock');
+  const retryCutoff = new Date(now.getTime() - retryAfterMs);
+  if (!Number.isFinite(retryCutoff.getTime())) throw new Error('purge retryAfterMs exceeds clock range');
+  const ordered = orderedModels(models);
+  const result: PurgeResult = { runId: randomUUID(), perTable: {}, noHook: [], skipped: [], afterDestroyErrors: 0, afterDestroyFailures: [] };
+  let purged = 0;
+  const finish = (incomplete = false): PurgeResult => {
+    if (incomplete) result.incomplete = true;
+    if (purged === 0) result.reason = incomplete ? 'time budget exhausted'
+      : result.skipped[0]?.reason ?? 'no expired lifecycle rows';
+    return result;
+  };
+  if (outOfBudget()) return finish(true);
+  const unsupported = await unsupportedPurgeGraphs(exec, models);
+  for (const model of ordered) {
+    const name = label(model);
+    const counts = result.perTable[name] = { purged: 0, skipped: 0, failed: 0 };
+    const unsupportedReason = unsupported.get(name);
+    if (unsupportedReason) {
+      // '*' is a table-level refusal, not an attempted row or an audit receipt.
+      result.skipped.push({ table: name, key: '*', reason: unsupportedReason });
+      continue;
+    }
+    const attempted = new Set<string>();
+    let cursor: Row | undefined;
+    while (purged < batch) {
+      if (outOfBudget()) return finish(true);
+      const tuple = sql.join([sql`deleted_at`, ...model.primaryKey.map(column)], sql`, `);
+      const cursorValues = cursor ? sql.join([sql`${param(cursor.deleted_at)}`, ...model.primaryKey.map(k => sql`${fieldParam(model, k, cursor![snake(k)])}`)], sql`, `) : undefined;
+      const cooldown = retryAfterMs > 0 ? sql`AND NOT EXISTS (
+        SELECT 1 FROM everystack.purge_log AS receipt
+        WHERE receipt."table" = ${name} AND ${cooldownKeyMatches(model)}
+          AND receipt.outcome IN ('skipped', 'failed') AND receipt.purged_at > ${retryCutoff.toISOString()}
+      )` : sql``;
+      const page = rowsOf(await exec.execute(sql`SELECT * FROM ${table(model)}
+        WHERE deleted_at <= ${cutoff.toISOString()} ${cooldown} ${cursorValues ? sql`AND (${tuple}) > (${cursorValues})` : sql``}
+        ORDER BY ${tuple} LIMIT ${Math.min(100, batch - purged)}`));
+      if (!page.length) {
+        if (retryAfterMs > 0 && purged === 0 && result.skipped.length === 0) {
+          const expired = rowsOf(await exec.execute(sql`SELECT 1 FROM ${table(model)} WHERE deleted_at <= ${cutoff.toISOString()} LIMIT 1`));
+          if (expired.length) result.skipped.push({ table: name, key: '*', reason: 'retry cooldown' });
+        }
+        break;
+      }
+      for (const candidate of page) {
+        cursor = candidate;
+        if (outOfBudget()) return finish(true);
+        const candidateKey = keyOf(model, candidate);
+        if (attempted.has(candidateKey)) continue;
+        attempted.add(candidateKey);
+        let selected: Row | undefined;
+        let beforeFailed = false;
+        let beforeRan = false;
+        let skippedReason: string | undefined;
+        let failureReason: string | undefined;
+        const removed = await exec.transaction(async tx => {
+          const [isolation] = rowsOf(await tx.execute(sql`SHOW transaction_isolation`));
+          if (isolation?.transaction_isolation !== 'read committed') throw new Error('purge requires READ COMMITTED');
+          const locked = rowsOf(await tx.execute(sql`SELECT * FROM ${table(model)}
+            WHERE ${keyWhere(model, candidate)} AND deleted_at <= ${cutoff.toISOString()} FOR UPDATE SKIP LOCKED`));
+          selected = locked[0];
+          if (!selected) return false;
+          const row = selected;
+          // Selection precedes the row lock. Another run may have committed a failure since then.
+          if (retryAfterMs > 0) {
+            const cooling = rowsOf(await tx.execute(sql`SELECT 1 FROM ${table(model)}
+              WHERE ${keyWhere(model, row)} AND EXISTS (
+                SELECT 1 FROM everystack.purge_log AS receipt
+                WHERE receipt."table" = ${name} AND ${cooldownKeyMatches(model)}
+                  AND receipt.outcome IN ('skipped', 'failed') AND receipt.purged_at > ${retryCutoff.toISOString()}
+              )`));
+            if (cooling.length) { skippedReason = 'retry cooldown'; return false; }
+          }
+          try {
+            // Keep the row lock outside the savepoint, including while recording a failed attempt.
+            return await tx.transaction(async work => {
+              for (const rel of Object.values(model.relations)) {
+                const child = rel.kind === 'hasMany' && (rel.dependent === 'cascade' || rel.dependent === 'restrict') ? rel.target() : undefined;
+                if (!child?.lifecycle) continue;
+                const reference = rel.references ?? model.primaryKey[0];
+                const remains = rowsOf(await work.execute(sql`SELECT 1 FROM ${table(child)} WHERE ${column(rel.column)} = ${fieldParam(model, reference, row[snake(reference)])} LIMIT 1`));
+                if (remains.length) {
+                  skippedReason = `remaining lifecycle child ${label(child)}`;
+                  await appendReceipt(work, result.runId, now, { model, row, outcome: 'skipped', hook: 'none', detail: skippedReason });
+                  return false;
+                }
+              }
+              const caller = model.hooks?.beforeDestroy
+                ? rowsOf(await work.execute(sql`SELECT current_user AS role`))[0] : undefined;
+              await work.execute(sql`SET LOCAL ROLE everystack_lifecycle`);
+              const deleted = rowsOf(await work.execute(sql`DELETE FROM ${table(model)} WHERE ${keyWhere(model, row)} RETURNING ${sql.join(model.primaryKey.map(column), sql`, `)}`));
+              if (deleted.length !== 1 || keyOf(model, deleted[0]) !== keyOf(model, row)) throw new Error('purge DELETE did not return the locked key');
+              // Refuse deferred constraints before invoking a hook with external effects.
+              await work.execute(sql`SET CONSTRAINTS ALL IMMEDIATE`);
+              if (caller) await work.execute(sql`SET LOCAL ROLE ${sql.identifier(String(caller.role))}`);
+              if (model.hooks?.beforeDestroy) {
+                try { await model.hooks.beforeDestroy(hookRow(model, row), context); beforeRan = true; }
+                catch (error) { beforeFailed = true; throw error; }
+              }
+              await appendReceipt(work, result.runId, now, { model, row, outcome: 'purged', hook: beforeRan ? 'ran' : 'none' });
+              return true;
+            });
+          } catch (error) {
+            failureReason = error instanceof Error ? error.message : String(error);
+            await appendReceipt(tx, result.runId, now, { model, row, outcome: 'failed', hook: beforeFailed ? 'failed' : beforeRan ? 'ran' : 'none', detail: failureReason });
+            return false;
+          }
+        });
+        if (failureReason !== undefined) {
+          counts.failed++;
+          result.skipped.push({ table: name, key: keyOf(model, selected!), reason: failureReason });
+          continue;
+        }
+        if (skippedReason) {
+          counts.skipped++;
+          result.skipped.push({ table: name, key: keyOf(model, candidate), reason: skippedReason });
+        }
+        if (!removed) {
+          if (!selected) {
+            counts.skipped++;
+            result.skipped.push({ table: name, key: candidateKey, reason: 'row locked or no longer expired' });
+          }
+          continue;
+        }
+        purged++; counts.purged++;
+        if (!model.hooks?.beforeDestroy && !model.hooks?.afterDestroy && !result.noHook.includes(name)) result.noHook.push(name);
+        if (model.hooks?.afterDestroy) {
+          try { await model.hooks.afterDestroy(hookRow(model, selected!), context); }
+          catch (error) {
+            // Formatting an arbitrary rejection must not lose a committed outcome.
+            let message = 'unreadable error';
+            let stack: string | undefined;
+            try { message = String(error instanceof Error ? error.message : error); } catch { /* Keep the fallback. */ }
+            try { stack = error instanceof Error ? error.stack : undefined; } catch { /* Stack is optional. */ }
+            const key = keyOf(model, selected!);
+            result.afterDestroyErrors++;
+            result.afterDestroyFailures.push({ table: name, key, message });
+            try {
+              await options.onError?.({ kind: 'hook', name: `${name}.afterDestroy`, method: 'DELETE', status: 500,
+                table: name, key, message: `after-hook failed after the write: ${message}`,
+                stack });
+            } catch { /* The observability sink cannot replace a committed outcome. */ }
+          }
+        }
+        if (purged >= batch) break;
+      }
+    }
+    if (purged >= batch) break;
+  }
+  return finish();
+}
+
+/** Count expired lifecycle rows without invoking hooks or changing data. */
+export async function overdueLifecycleRows(
+  exec: Pick<SessionTx, 'execute'>,
+  models: ModelDescriptor[],
+  options: { after: number },
+): Promise<Record<string, number>> {
+  if (!Number.isFinite(options.after) || options.after <= 0) throw new Error('purge after must be positive milliseconds');
+  const cutoff = new Date(Date.now() - options.after);
+  if (!Number.isFinite(cutoff.getTime())) throw new Error('purge after exceeds clock range');
+  const counts: Record<string, number> = {};
+  for (const model of models.filter(m => m.lifecycle)) {
+    const [row] = rowsOf(await exec.execute(sql`SELECT count(*) AS count FROM ${table(model)} WHERE deleted_at <= ${cutoff.toISOString()}`));
+    const count = Number(row.count);
+    if (!Number.isSafeInteger(count) || count < 0) throw new Error(`invalid overdue count on ${label(model)}`);
+    counts[label(model)] = count;
+  }
+  return counts;
+}