@everystack/server 0.4.39 → 0.4.41

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to `@everystack/server` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.41] - 2026-10-31
+
+### Fixed
+
+- destroyExpired links a module's raw models itself
+
+## [0.4.40] - 2026-10-30
+
+### BREAKING CHANGES
+
+- destroy is one generated SQL function per lifecycle table; purgeExpired is removed
+- only a lifecycle table may hold a foreign key into a lifecycle table
+
+### Added
+
+- the apply preflight refuses a live catalog that breaks the soft delete
+- destroyExpired counts skipped roots by reason and blocker
+- describeSkipped renders a destroy result's skipped roots
+- db:reconcile runs the live catalog check on every write path
+- destroy runs under an app role; a stock destroy job
+
+### Fixed
+
+- destroyExpired pages candidates on every path, so a call's retry work stays bounded
+- review nits for lifecycle/testing
+- consumer-named blockers cannot corrupt counts or log lines
+- describeSkipped strips bidi overrides and line separators
+- destroy eligibility follows the root
+- the destroy job logs no error text and fails a failed run
+
+### Changed
+
+- one delete hook pair; beforeStamp and afterStamp are folded into beforeDelete and afterDelete
+- a destroy skip is an alarm, not an operator workflow
+
 ## [0.4.39] - 2026-10-23
 
 ### BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.39",
+  "version": "0.4.41",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -126,10 +126,20 @@
       "types": "./src/restore-witness.ts",
       "default": "./src/restore-witness.ts"
     },
-    "./purge": {
-      "source": "./src/purge.ts",
-      "types": "./src/purge.ts",
-      "default": "./src/purge.ts"
+    "./destroy": {
+      "source": "./src/destroy.ts",
+      "types": "./src/destroy.ts",
+      "default": "./src/destroy.ts"
+    },
+    "./destroy-job": {
+      "source": "./src/destroy-job.ts",
+      "types": "./src/destroy-job.ts",
+      "default": "./src/destroy-job.ts"
+    },
+    "./destroy-log": {
+      "source": "./src/destroy-log.ts",
+      "types": "./src/destroy-log.ts",
+      "default": "./src/destroy-log.ts"
     }
   },
   "peerDependencies": {
@@ -197,11 +207,11 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.103",
-    "@everystack/auth": "0.4.9"
+    "@everystack/auth": "0.4.10",
+    "@everystack/cli": "0.4.105"
   },
   "dependencies": {
-    "@everystack/model": "0.4.24"
+    "@everystack/model": "0.4.25"
   },
   "scripts": {
     "test": "jest",

package/src/destroy-job.ts

@@ -0,0 +1,74 @@
+/**
+ * The stock lifecycle destroy job: a scheduled handler around destroyExpired.
+ *
+ * Inert until the app sets a retention window (`after`). It runs on the app's least-privilege
+ * login (NOINHERIT, granted the app roles) and switches with SET LOCAL ROLE in each transaction,
+ * as the API does. Never the database master, never everystack_lifecycle. Logs are counts and
+ * table names only, never a row key.
+ */
+import type { ModelDescriptor } from '@everystack/model';
+import type { SessionCapableDb } from './db-session';
+import { assertDestroyRole, describeSkipped, destroyExpired, overdueLifecycleRowsReadOnly, type DestroyFault, type DestroyResult } from './destroy';
+
+export interface DestroyJobOptions {
+  models: ModelDescriptor[];
+  /** Retention in milliseconds after soft delete. Undefined leaves the job inert. */
+  after?: number;
+  /** Roots removed per table per run (destroyExpired's batch). */
+  batch?: number;
+  /** The application role each transaction switches to. Must manage the lifecycle tables. */
+  role?: string;
+  /** A handle on the least-privilege login, or a function that opens one on first use. */
+  db: SessionCapableDb | (() => SessionCapableDb);
+  /** Hook and destroy faults. Default: one log line with the table and phase, not the message. */
+  onError?: (fault: DestroyFault) => void | Promise<void>;
+}
+
+export interface DestroyJobEvent {
+  /** Count the overdue rows under the role; change nothing. */
+  dryRun?: boolean;
+}
+
+export type DestroyJobResult =
+  | { status: 'not_configured' }
+  | { status: 'dry_run'; overdue: Record<string, number> }
+  | { status: 'done'; perTable: DestroyResult['perTable']; skipped: string[] };
+
+const log = (level: 'info' | 'warn', message: string, fields: Record<string, unknown> = {}): void => {
+  console.log(JSON.stringify({ timestamp: new Date().toISOString(), level, message, ...fields }));
+};
+
+/**
+ * Per-table counts for the log line. `failed` and `skippedBy` carry text a consumer's RAISE can
+ * choose (a trigger can raise a row key), so the line keeps only that a table failed.
+ */
+const loggable = (perTable: DestroyResult['perTable']): Record<string, { removed: number; held: number; skipped: number; failed?: true }> =>
+  Object.fromEntries(Object.entries(perTable).map(([table, { removed, held, skipped, failed }]) =>
+    [table, failed === undefined ? { removed, held, skipped } : { removed, held, skipped, failed: true as const }]));
+
+export function createDestroyJob(options: DestroyJobOptions): (event?: DestroyJobEvent) => Promise<DestroyJobResult> {
+  const role = options.role ?? 'admin';
+  assertDestroyRole(role);
+  const { models, after, batch } = options;
+  if (after !== undefined && (!Number.isFinite(after) || after <= 0)) throw new Error('retention must be positive milliseconds');
+  const connect = (): SessionCapableDb => typeof options.db === 'function' ? options.db() : options.db;
+  const onError = options.onError ?? ((fault: DestroyFault): void => log('warn', 'Lifecycle destroy fault', { table: fault.table, phase: fault.phase }));
+  return async (event) => {
+    if (after === undefined) {
+      log('info', 'Lifecycle destroy not configured: set a retention window (after) to enable it');
+      return { status: 'not_configured' };
+    }
+    if (event?.dryRun) {
+      const overdue = await overdueLifecycleRowsReadOnly(connect(), models, { after, role });
+      log('info', 'Lifecycle destroy dry run', { role, overdue });
+      return { status: 'dry_run', overdue };
+    }
+    const result = await destroyExpired(connect(), models, { after, batch, role, onError });
+    const skipped = describeSkipped(result);
+    const failed = Object.keys(result.perTable).filter(table => result.perTable[table].failed !== undefined);
+    log(failed.length > 0 || skipped.length > 0 ? 'warn' : 'info', 'Lifecycle destroy complete', { role, perTable: loggable(result.perTable), skipped });
+    // Fail the invocation so error alarms fire; name the tables only, the cause can carry a key.
+    if (failed.length > 0) throw new Error(`lifecycle destroy failed on ${failed.join(', ')}; the cause reaches onError`);
+    return { status: 'done', perTable: result.perTable, skipped };
+  };
+}

package/src/destroy-log.ts

@@ -0,0 +1,2 @@
+/** The log is shared with the CLI's database builder without a server dependency. */
+export { ENSURE_DESTROY_LOG_SQL } from '@everystack/model';

package/src/destroy.ts

@@ -0,0 +1,226 @@
+/** Generated SQL owns removal; this module brackets it with root hooks. */
+import { sql, type SQL } from 'drizzle-orm';
+import { isVeto, lifecycleDestroyOrder, linkModels, pgType, type DestroyContext, type ModelDescriptor } from '@everystack/model';
+import type { SessionCapableDb, SessionTx } from './db-session';
+
+type Row = Record<string, unknown>;
+const label = (m: ModelDescriptor): string => `${m.schema}.${m.table}`;
+const table = (m: ModelDescriptor): SQL => sql`${sql.identifier(m.schema)}.${sql.identifier(m.table)}`;
+const rowsOf = (result: unknown): Row[] => Array.isArray(result) ? result : (result as { rows: Row[] }).rows;
+
+// The identifier rule withRole uses (db.ts): the only value ever interpolated into SET ROLE.
+const ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * Refuse a role the destroy path must not switch to. everystack_lifecycle is the private authority
+ * the generated function holds for one statement; a caller that can assume it can also
+ * unmark rows by hand, so a routine job never runs as it.
+ */
+export function assertDestroyRole(role: string): void {
+  if (!ROLE_NAME.test(role)) throw new Error(`Invalid role name: ${JSON.stringify(role)}`);
+  if (role === 'everystack_lifecycle') throw new Error('destroy must not run as everystack_lifecycle: pass an application role that manages the tables (e.g. admin)');
+}
+
+/** SET LOCAL ROLE as a transaction's first statement, as withRole does. */
+async function switchRole(tx: Pick<SessionTx, 'execute'>, role: string | undefined): Promise<void> {
+  if (role !== undefined) await tx.execute(sql.raw(`SET LOCAL ROLE ${role}`));
+}
+
+/**
+ * Count expired lifecycle rows without invoking hooks or changing data. With `role`, exec must be
+ * a transaction: SET LOCAL outside one is a no-op, so the switch is checked before counting.
+ */
+export async function overdueLifecycleRows(
+  exec: Pick<SessionTx, 'execute'>,
+  models: ModelDescriptor[],
+  options: { after: number; role?: string },
+): Promise<Record<string, number>> {
+  if (!Number.isFinite(options.after) || options.after <= 0) throw new Error('retention must be positive milliseconds');
+  const cutoff = new Date(Date.now() - options.after);
+  if (!Number.isFinite(cutoff.getTime())) throw new Error('retention exceeds clock range');
+  if (options.role !== undefined) {
+    assertDestroyRole(options.role);
+    await switchRole(exec, options.role);
+    const [row] = rowsOf(await exec.execute(sql`SELECT current_user AS role`));
+    if (row?.role !== options.role) throw new Error(`role ${options.role} was not set: overdueLifecycleRows with a role is not inside a transaction`);
+  }
+  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;
+}
+
+/** overdueLifecycleRows in one read-only transaction of its own, under `role` when given. */
+export async function overdueLifecycleRowsReadOnly(
+  db: SessionCapableDb,
+  models: ModelDescriptor[],
+  options: { after: number; role?: string },
+): Promise<Record<string, number>> {
+  if (options.role !== undefined) assertDestroyRole(options.role);
+  return db.transaction(tx => overdueLifecycleRows(tx, models, options), { accessMode: 'read only' });
+}
+
+/**
+ * Why a root was skipped: 'referenced', a foreign key outside the declarations still references it;
+ * 'ineligible_live', a delete during destroy reached a live row (the tamper alarm). Every key into a
+ * lifecycle table is declared, so neither is reachable by normal writes.
+ */
+export type DestroySkipReason = 'referenced' | 'ineligible_live';
+
+export interface DestroyResult {
+  /**
+   * skipped: the roots the generated function returned as 'skipped' (db:doctor counts them overdue).
+   * skippedBy: the same roots counted by reason, then by blocker (schema.table.constraint for
+   * 'referenced', the child's schema.table otherwise). Counts only, never keys.
+   */
+  perTable: Record<string, { removed: number; held: number; skipped: number; skippedBy: Partial<Record<DestroySkipReason, Record<string, number>>>; failed?: string }>;
+  order: string[];
+}
+
+export interface DestroyFault {
+  table: string;
+  phase: 'beforeDestroy' | 'afterDestroy' | 'destroy';
+  error: unknown;
+}
+
+/** A blocker is name text a consumer's RAISE can set: no control, line-separator or bidi-override character reaches a log line. */
+const printable = (text: string): string => text.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, '');
+
+/**
+ * One plain-text line per table and blocker of a destroyExpired result's skipped roots, with its
+ * count. Built from names and counts only; the result never carries a key. Under the declared design
+ * soft delete decides every consequence, so a skip means an out-of-band key or trigger. The blocker
+ * comes from the error PostgreSQL reported, so a consumer trigger that raises 23503 itself can
+ * choose it: a lead to check, not proof.
+ */
+export function describeSkipped(result: DestroyResult): string[] {
+  const lines: string[] = [];
+  for (const [table, entry] of Object.entries(result.perTable)) {
+    for (const blockers of Object.values(entry.skippedBy)) {
+      for (const blocker of Object.keys(blockers!).sort()) {
+        lines.push(`${table}: destroy was blocked by ${printable(blocker)} (${blockers![blocker]} root(s)); `
+          + 'this should not happen under the declared design, check for an out-of-band key or trigger');
+      }
+    }
+  }
+  return lines;
+}
+
+const columnName = (key: string): string => key.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
+const context = (row: Row): DestroyContext => Object.freeze({
+  phase: 'destroy', batch: row.deleted_batch as string | null ?? null, user: null, client: null,
+});
+
+/**
+ * Remove expired roots through their generated SQL functions, children first.
+ * Pass a database handle, never a transaction: every destroy needs its own top-level
+ * transaction. Hooks run for roots only; FK cascades remove children without hooks.
+ * A remaining restrict child defers its root (visible through overdueLifecycleRows). A root another
+ * foreign key still references is skipped and counted, and the rest of the batch is removed.
+ * Candidates are read a page of `batch` at a time and each call names its keys, so one call's
+ * retry work is bounded by batch however many roots stay pinned. `batch` caps the roots removed
+ * per table per run. Locked rows are skipped, so fewer than batch roots may return. Hooks may repeat if
+ * commit fails. afterDestroy runs after commit, best-effort: a crash can lose it.
+ * `role`: every transaction opens with SET LOCAL ROLE, so a least-privilege login (NOINHERIT,
+ * granted the app roles) runs it as a role that manages the tables. Never everystack_lifecycle.
+ * `models` may be a module's raw array: it is linked here (linkModels) before the destroy order is read.
+ */
+export async function destroyExpired(
+  db: SessionCapableDb,
+  models: ModelDescriptor[],
+  options: {
+    after: number;
+    batch?: number;
+    now?: Date;
+    statementTimeoutMs?: number;
+    role?: string;
+    onError?: (fault: DestroyFault) => void | Promise<void>;
+  },
+): Promise<DestroyResult> {
+  if (options.role !== undefined) assertDestroyRole(options.role);
+  if (!Number.isFinite(options.after) || options.after <= 0) throw new Error('retention must be positive milliseconds');
+  const before = new Date((options.now?.getTime() ?? Date.now()) - options.after);
+  if (!Number.isFinite(before.getTime())) throw new Error('retention exceeds clock range');
+  const batch = options.batch ?? 1000;
+  const timeout = options.statementTimeoutMs ?? 60000;
+  for (const [name, value] of [['batch', batch], ['statementTimeoutMs', timeout]] as const) {
+    if (!Number.isInteger(value) || value <= 0 || value > 2147483647) throw new Error(`${name} must be a positive PostgreSQL integer`);
+  }
+  // A module's raw models still hold name references; linking an already linked set is a no-op.
+  const order = lifecycleDestroyOrder(linkModels(models));
+  const byName = new Map(models.map(m => [m.schema === 'public' ? m.table : label(m), m]));
+  const result: DestroyResult = { perTable: {}, order };
+  const report = async (fault: DestroyFault): Promise<void> => {
+    try { await options.onError?.(fault); } catch { /* Reporting must not stop removal of other roots. */ }
+  };
+  for (const name of order) {
+    const model = byName.get(name)!;
+    const entry: DestroyResult['perTable'][string] = { removed: 0, held: 0, skipped: 0, skippedBy: {} };
+    result.perTable[label(model)] = entry;
+    try {
+      const pk = columnName(model.primaryKey[0]);
+      const keyType = sql.raw(pgType(model.fields[model.primaryKey[0]].spec));
+      const hooks = model.hooks;
+      /** One generated destroy call in its own transaction; afterDestroy for the roots it removed. */
+      const destroy = async (allowed: Row[], limit: number): Promise<void> => {
+        const keys = sql`ARRAY[${sql.join(allowed.map(row => sql`${row[pk]}`), sql`, `)}]::${keyType}[]`;
+        const outcomes = await db.transaction(async tx => {
+          await switchRole(tx, options.role);
+          await tx.execute(sql.raw(`SET LOCAL statement_timeout = ${timeout}`));
+          return rowsOf(await tx.execute(sql`SELECT key, outcome, reason, blocker FROM ${sql.identifier(model.schema)}.${sql.identifier(`${model.table}_lifecycle_destroy`)}(${keys}, ${before.toISOString()}, ${limit})`));
+        });
+        const removed = outcomes.filter(row => row.outcome === 'removed');
+        entry.removed += removed.length;
+        entry.skipped += outcomes.length - removed.length;
+        for (const row of outcomes) {
+          if (row.outcome === 'removed') continue;
+          // Null prototype: a blocker is text a consumer's RAISE can choose ('__proto__', 'constructor').
+          const byBlocker = entry.skippedBy[row.reason as DestroySkipReason] ??= Object.create(null) as Record<string, number>;
+          const blocker = typeof row.blocker === 'string' ? row.blocker : '(unnamed)';
+          byBlocker[blocker] = (byBlocker[blocker] ?? 0) + 1;
+        }
+        if (!hooks?.afterDestroy) return;
+        const returned = new Set(removed.map(row => String(row.key)));
+        for (const row of allowed) {
+          if (!returned.has(String(row[pk]))) continue;
+          try { await hooks.afterDestroy(row, context(row)); }
+          catch (error) { await report({ table: label(model), phase: 'afterDestroy', error }); }
+        }
+      };
+      // Page past held and skipped roots, so the oldest stuck rows cannot starve the table. The
+      // cursor keeps deleted_at as text: a JavaScript Date drops its microseconds. Without hooks
+      // only the key is read.
+      const columns = hooks?.beforeDestroy || hooks?.afterDestroy ? sql`*` : sql.identifier(pk);
+      let cursor: { at: unknown; key: unknown } | undefined;
+      while (entry.removed < batch) {
+        const after = cursor ? sql`AND (deleted_at, ${sql.identifier(pk)}) > (${cursor.at}::timestamptz, ${cursor.key}::${keyType})` : sql``;
+        const page = await db.transaction(async tx => {
+          await switchRole(tx, options.role);
+          return rowsOf(await tx.execute(sql`SELECT ${columns}, deleted_at::text AS lc_cursor_at FROM ${table(model)} WHERE deleted_at IS NOT NULL AND deleted_at < ${before.toISOString()} ${after} ORDER BY deleted_at, ${sql.identifier(pk)} LIMIT ${batch}`));
+        }, { accessMode: 'read only' });
+        if (page.length === 0) break;
+        cursor = { at: page[page.length - 1].lc_cursor_at, key: page[page.length - 1][pk] };
+        const allowed: Row[] = [];
+        for (const { lc_cursor_at: _at, ...row } of page) {
+          try {
+            if (isVeto(await hooks?.beforeDestroy?.(row, context(row)))) { entry.held++; continue; }
+            allowed.push(row);
+          } catch (error) {
+            entry.held++;
+            await report({ table: label(model), phase: 'beforeDestroy', error });
+          }
+        }
+        if (allowed.length > 0) await destroy(allowed, batch - entry.removed);
+        if (page.length < batch) break;
+      }
+    } catch (error) {
+      entry.failed = error instanceof Error ? error.message : String(error);
+      await report({ table: label(model), phase: 'destroy', error });
+    }
+  }
+  return result;
+}

package/src/plugin.ts

@@ -1479,6 +1479,9 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
           rebuild: p.rebuild,
           overwriteDrift: p.overwriteDrift,
           only: p.only,
+          // The lifecycle catalog check's roles, as sent. executeReconcile refuses lifecycle-owned
+          // objects when they are absent or malformed (an older CLI): fail closed, never skipped.
+          applicationRoles: p.applicationRoles,
           actor: p.actor ?? null,
           gitRef: p.gitRef ?? null,
         });

package/src/provision.ts

@@ -20,6 +20,7 @@
  * without a database; plugin.ts wires the real deps.
  */
 
+import { ENSURE_DESTROY_LOG_SQL } from './destroy-log';
 import { generateRoleChainSQL, generateAdminRoleSQL, generateSearchPathSQL, generateRotationPairSQL, generateReaderRoleSQL, generateLifecycleRoleSQL, LIFECYCLE_ROLE } from './role-chain';
 import {
   pgVersionRefusal,
@@ -333,6 +334,9 @@ export async function runProvision(
   // ahead of every password and well clear of the password-to-secret window.
   if (lifecycleSql) {
     await deps.execute(lifecycleSql);
+    for (const statement of ENSURE_DESTROY_LOG_SQL) {
+      await deps.execute(statement.replace(/\beverystack_lifecycle\b/g, lifecycleRole));
+    }
     result.lifecycleRole = {
       role: lifecycleRole,
       created: lifecycleLive ? !lifecycleLive.existed : null,

package/src/purge-graph.ts

@@ -1,91 +0,0 @@
-/** 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

@@ -1,63 +0,0 @@
-/**
- * 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

@@ -1,375 +0,0 @@
-/** 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 { isVeto, type ModelDescriptor, type DestroyContext } from '@everystack/model';
-import type { SessionTx } from './db-session';
-import { unsupportedPurgeGraphs } from './purge-graph';
-export { ENSURE_PURGE_LOG_SQL } from './purge-log';
-export { veto, isVeto } from '@everystack/model';
-export type { HookVeto, LifecycleContext, DestroyContext, DestroyHook } from '@everystack/model';
-
-/** A destroy hook failed after physical removal committed. */
-/** A row lifecycle: { deleteWhen } no longer allows: kept, recorded, never cooled down. */
-const PROTECTED_BY_DELETE_WHEN = 'protected by deleteWhen';
-/** beforeDestroy returned veto(reason): the row is kept with a `skipped` receipt `held: <reason>`, never cooled down. */
-const HELD = 'held: ';
-/** Thrown inside the removal savepoint to roll it back when beforeDestroy vetoes. */
-class HeldByHook extends Error {}
-
-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 contextFor = (row: Row): DestroyContext => Object.freeze({
-  phase: 'destroy', source: 'purge', batch: typeof row.deleted_batch === 'string' ? row.deleted_batch : null, 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, with `{ phase: 'destroy', source: 'purge',
- * batch: <the row's deleted_batch> }`. A hook throw rolls back the removal (failed receipt, retry
- * cooldown). A returned `veto(reason)` rolls it back too, as a decision: a `skipped` receipt with
- * detail `held: <reason>`, no cooldown, so the next run asks again. 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()}
-          AND receipt.detail IS DISTINCT FROM ${PROTECTED_BY_DELETE_WHEN}
-          AND NOT (receipt.outcome = 'skipped' AND coalesce(receipt.detail, '') LIKE ${HELD + '%'})
-      )` : 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;
-        let held: 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()}
-                  AND receipt.detail IS DISTINCT FROM ${PROTECTED_BY_DELETE_WHEN}
-                  AND NOT (receipt.outcome = 'skipped' AND coalesce(receipt.detail, '') LIKE ${HELD + '%'})
-              )`));
-            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`);
-              // lifecycle: { deleteWhen } — a drift guard, not the main gate: the stamp already passed the
-              // guard trigger, but the predicate's columns may have changed since. A row it no longer
-              // allows stays, with a `skipped` receipt that sets no retry cooldown (the next run looks again).
-              // On lines of its own: a trailing `--` comment in the predicate must not hide RETURNING.
-              const guard = model.deleteWhen !== undefined ? sql` AND (\n${sql.raw(model.deleteWhen)}\n)` : sql``;
-              const deleted = rowsOf(await work.execute(sql`DELETE FROM ${table(model)} WHERE ${keyWhere(model, row)}${guard} RETURNING ${sql.join(model.primaryKey.map(column), sql`, `)}`));
-              if (model.deleteWhen !== undefined && deleted.length === 0) {
-                skippedReason = PROTECTED_BY_DELETE_WHEN;
-                await appendReceipt(work, result.runId, now, { model, row, outcome: 'skipped', hook: 'none', detail: skippedReason });
-                return false;
-              }
-              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 {
-                  const verdict = await model.hooks.beforeDestroy(hookRow(model, row), contextFor(row));
-                  beforeRan = true;
-                  if (isVeto(verdict)) held = HELD + verdict.reason;
-                } catch (error) { beforeFailed = true; throw error; }
-                // A veto rolls back the removal like a throw, but it is a decision, not a failure.
-                if (held !== undefined) throw new HeldByHook(held);
-              }
-              await appendReceipt(work, result.runId, now, { model, row, outcome: 'purged', hook: beforeRan ? 'ran' : 'none' });
-              return true;
-            });
-          } catch (error) {
-            if (error instanceof HeldByHook) {
-              skippedReason = held;
-              await appendReceipt(tx, result.runId, now, { model, row, outcome: 'skipped', hook: 'ran', detail: held });
-              return false;
-            }
-            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!), contextFor(selected!)); }
-          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;
-}