@everystack/cli 0.4.100 → 0.4.103

package/src/cli/lifecycle-derived.ts

@@ -0,0 +1,787 @@
+/**
+ * The lifecycle triggers — derived objects GENERATED from every `lifecycle: true` model in a set.
+ *
+ * Per lifecycle table `<t>`, two functions and two triggers, built with the ordinary descriptors so
+ * compile, introspect, reconcile and fingerprint treat them like any declared object:
+ *
+ *  - `<t>_lifecycle_transition` (BEFORE DELETE): instead of deleting, a SECURITY DEFINER function
+ *    owned by the lifecycle role stamps the four lifecycle columns and skips the delete. A row that
+ *    is already deleted keeps its stamps. It refuses to run as a trigger on any other table: a
+ *    role holding EXECUTE could otherwise attach it to its own table and soft-delete `<t>` rows by id.
+ *    It hands the batch to a caller that cannot read it: for a top-level DELETE (trigger depth 1) it
+ *    appends `<JSON-quoted key> <batch>` as a line to the transaction-local setting
+ *    `everystack.lifecycle_batch`, one line per stamped root. Informational, never a gate: any role
+ *    can set that name, and the stamp columns stay the truth.
+ *  - `<t>_lifecycle_guard` (BEFORE INSERT OR UPDATE): refuses any direct write to those columns.
+ *  - `<t>_lifecycle_delete_when` (BEFORE UPDATE OF deleted_at, live -> deleted), only for
+ *    lifecycle: { deleteWhen }: refuses the stamp (23514) unless the predicate is TRUE for the row,
+ *    for a direct delete and a cascade alike. Its predicate rides on its own manifest only.
+ *  - `<t>_restore(p_id)`: undoes a delete for whoever may delete p_id. A SECURITY DEFINER
+ *    function owned by the lifecycle role, EXECUTE to exactly the roles with a delete rule. The
+ *    caller is the SET ROLE role (session_user when none); a role branch passes when the caller
+ *    holds USAGE on that role (never MEMBER: the authenticator is a NOINHERIT member of every app
+ *    role) AND the role's delete predicate, read from the compiled DELETE policies, holds on the
+ *    row. Every refusal raises the same message, naming only the table and the id. It brings back
+ *    the whole cascade subtree that delete stamped, on p_id's authority alone: the delete took
+ *    those rows whatever the deleter's rights over them, so its undo must too, or a user's
+ *    restore would leave the likes others put on their posts deleted for good. It never makes a
+ *    live row under a deleted parent (see restoreFunction), and it returns counts and the batch it
+ *    restored (`{ restored, skipped, batch }`; batch null for a legacy row), never ids.
+ *
+ * A lifecycle parent's hasMany `dependent` cannot ride the foreign key: its DELETE never removes the
+ * row, so the FK never fires (relationDeleteActions compiles a lifecycle parent's 'cascade' to
+ * RESTRICT). The cascade trigger and the transition carry it instead, generated from the MODEL SET:
+ *
+ *  - `<t>_lifecycle_cascade` (AFTER UPDATE OF deleted_at, live -> deleted): copies the parent's four
+ *    stamps onto its live 'cascade' children, so the whole tree shares one batch, one xid and the
+ *    deleter's sub. It runs as the lifecycle role, so the deleter needs no rights over the children.
+ *    It UPDATEs, never DELETEs: as the lifecycle role a child's transition is skipped, so a DELETE
+ *    would really delete. Depth comes from each child's own cascade trigger; a child reached twice
+ *    (a diamond) is already stamped the second time and the `deleted_at IS NULL` filter skips it.
+ *  - 'restrict': the transition of every table whose cascade subtree holds a 'restrict' parent,
+ *    after its stamp (so after the whole cascade), refuses (23503) while a LIVE child references a
+ *    row the delete stamped. One check, after everything is stamped: a child the same delete
+ *    stamped does not count, whatever order the cascade ran in (see restrictCheck).
+ *    The contract: 'restrict' permits a delete when its live children are deleted by the same cascade.
+ *    A multi-row DELETE runs one transition per row, each its own batch, in scan order: rows that
+ *    share a restrict child through different families can refuse depending on that order, never
+ *    accept a live child under a deleted parent.
+ *    Author triggers must not write the lifecycle columns: the check trusts that only delete and
+ *    restore set deleted_batch.
+ *    A trigger fired by a stamp or by purge runs inside these functions' pinned search_path
+ *    (pg_catalog, pg_temp), so it must schema-qualify every table name.
+ *    A DELETE a consumer trigger issues on a lifecycle table during a stamp or purge is a soft delete
+ *    (TRANSITION_WHEN lets depth > 0 through), not a hard delete.
+ *
+ * Both refuse outside READ COMMITTED: a REPEATABLE READ snapshot cannot see a child committed after
+ * it began, so the cascade would leave that child live, and the restrict count would miss it.
+ *  - `<t>_lifecycle_parent` on a lifecycle child of a 'cascade' or 'restrict' relation (BEFORE
+ *    INSERT OR UPDATE OF the foreign key): a live row may not point at a deleted parent, and a
+ *    missing parent gets the same refusal, so the message never tells a hidden deleted row from no
+ *    row at all. It reads the parent FOR SHARE, which conflicts with the FOR NO KEY UPDATE a
+ *    concurrent stamp takes; the FK's own FOR KEY SHARE does not, so without it an insert racing a
+ *    cascade would land live.
+ *
+ * Every trigger but the cascade skips the lifecycle role, the one role that really deletes and
+ * stamps. The role test lives in the trigger's WHEN clause, which PostgreSQL evaluates as the
+ * INVOKING user before it calls the function. Inside the definer function `current_user` is always
+ * the lifecycle role, so the body never tests it. The transition's own UPDATE runs as that role, so
+ * the guard skips it. The cascade must not skip it: its recursion IS the lifecycle role's UPDATE.
+ * Only the lifecycle role can change deleted_at (the guard), so the cascade fires on nothing else.
+ *
+ * Every function here refuses to run as a trigger on any table but its own (42501), for the
+ * transition's reason: EXECUTE, or a superuser's mistake, must not let it act on `<t>`'s children.
+ *
+ * Computed from the models every time, never stored on a module.
+ */
+
+import { can, defineFunction, trigger, sql, parseQualified, LIFECYCLE_COLUMNS, LIFECYCLE_OWNER_ROLE } from '@everystack/model';
+import type { DerivedDescriptor, ModelDescriptor, Relation, FunctionDescriptor, TriggerDefinition, TriggerSpec } from '@everystack/model';
+import { pgType, toSnakeCase } from './schema-compile';
+import { deleteRulePredicates } from './authz-compile';
+import { canonHash, canonOfFunction } from './lifecycle-canon';
+
+/** Exact inputs read by the lifecycle builders, serializable without model references. */
+export interface LifecycleTable {
+  schema: string;
+  table: string;
+  pk: { column: string; type: string };
+  unique: boolean;
+  auth: Record<string, string>;
+}
+export interface LifecycleEdge {
+  parent: string;
+  child: string;
+  column: string;
+  dependent: 'cascade' | 'restrict';
+}
+export interface LifecycleDeclaration {
+  tables: Record<string, LifecycleTable>;
+  edges: LifecycleEdge[];
+}
+export const MANIFEST_VERSION = 1;
+export const LIFECYCLE_ROLES = ['transition', 'guard', 'restore', 'cascade', 'parent', 'delete_when'] as const;
+export type LifecycleRole = typeof LIFECYCLE_ROLES[number];
+export interface LifecycleManifest {
+  everystack: 'lifecycle';
+  v: number;
+  role: LifecycleRole;
+  model: string;
+  decl: LifecycleDeclaration;
+  /** The `delete_when` function's own input: lifecycle: { deleteWhen }'s predicate text. Carried on
+   *  that function's manifest only, so a guard added later changes no other function's manifest. */
+  deleteWhen?: string;
+  defHash: string;
+}
+type TableName = Pick<LifecycleTable, 'schema' | 'table'>;
+export interface LifecycleTrigger extends TriggerSpec { kind: 'trigger'; on: LifecycleTable; }
+export type LifecycleObject = FunctionDescriptor | LifecycleTrigger;
+interface LifecycleDependent { parent: LifecycleTable; child: TableName; column: string; dependent: 'cascade' | 'restrict'; }
+
+/** Restore has a distinct naming pattern; unknown family names are never guessed. */
+export function lifecycleRole(name: string, model: string): LifecycleRole | undefined {
+  for (const role of LIFECYCLE_ROLES) {
+    if (name === (role === 'restore' ? `${model}_restore` : `${model}_lifecycle_${role}`)) return role;
+  }
+  return undefined;
+}
+function lifecycleTrigger(name: string, def: TriggerDefinition & { on: LifecycleTable }): LifecycleTrigger {
+  return { ...trigger(name, def), kind: 'trigger', on: def.on };
+}
+
+/** Search path for the generated functions: pg_temp explicit and last, so it is never searched first. */
+const SEARCH_PATH = ['pg_catalog', 'pg_temp'];
+
+const ident = (name: string): string => `"${name.replace(/"/g, '""')}"`;
+const literal = (s: string): string => `'${s.replace(/'/g, "''")}'`;
+
+const qualified = (m: TableName): string => `${ident(m.schema)}.${ident(m.table)}`;
+const labelOf = (m: TableName): string => `${m.schema}.${m.table}`;
+const pkOf = (m: LifecycleTable): string => ident(m.pk.column);
+const pkType = (m: LifecycleTable): string => m.pk.type;
+const hasUnique = (m: LifecycleTable): boolean => m.unique;
+const [AT, BY, BATCH, XID] = LIFECYCLE_COLUMNS.map((c) => ident(toSnakeCase(c)));
+const SKIP_LIFECYCLE_ROLE = sql`CURRENT_USER <> ${literal(LIFECYCLE_OWNER_ROLE)}`;
+/**
+ * The transition skips only a TOP-LEVEL DELETE by the lifecycle role: purge's real removal. A DELETE
+ * issued from inside a trigger (a consumer trigger fired by a stamp or by purge runs as the lifecycle
+ * role, because the generated functions are SECURITY DEFINER) is soft-deleted like any other. The
+ * WHEN is evaluated at the depth of the DELETE statement itself, so purge's top-level DELETE sees 0.
+ */
+const TRANSITION_WHEN = sql`CURRENT_USER <> ${literal(LIFECYCLE_OWNER_ROLE)} OR pg_catalog.pg_trigger_depth() > 0`;
+
+/** The first statement of every generated trigger function: run only as a trigger on `model`. */
+function ownTableOnly(model: LifecycleTable, fnName: string): string {
+  return `IF TG_TABLE_SCHEMA <> ${literal(model.schema)} OR TG_TABLE_NAME <> ${literal(model.table)} THEN
+    RAISE EXCEPTION USING ERRCODE = '42501', MESSAGE = ${literal(
+      `${fnName} belongs to ${labelOf(model)} and refuses to run as a trigger on `,
+    )} || TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME;
+  END IF;`;
+}
+
+/** One declared `dependent` of a lifecycle parent, resolved: the child and its foreign-key column. */
+interface ModelDependent {
+  parent: ModelDescriptor;
+  child: ModelDescriptor;
+  /** The child's foreign-key column, SQL name. */
+  column: string;
+  dependent: 'cascade' | 'restrict';
+}
+
+/**
+ * Every 'cascade' and 'restrict' dependent of a lifecycle parent in the set, sorted by parent,
+ * child and column so the generated bodies are byte-stable. 'nullify' needs nothing until purge:
+ * a soft delete leaves the parent row, so the child's reference stays valid. A 'cascade' or
+ * 'restrict' onto a plain child is refused by relationDeleteActions; it is skipped here, never
+ * half-generated.
+ */
+function lifecycleDependents(models: readonly ModelDescriptor[]): ModelDependent[] {
+  const out: ModelDependent[] = [];
+  for (const parent of new Set(models)) {
+    if (parent.lifecycle !== true) continue;
+    for (const rel of Object.values(parent.relations) as Relation[]) {
+      if (rel.kind !== 'hasMany' || (rel.dependent !== 'cascade' && rel.dependent !== 'restrict')) continue;
+      const child = rel.target();
+      if (child.lifecycle !== true) continue;
+      out.push({ parent, child, column: toSnakeCase(rel.column), dependent: rel.dependent });
+    }
+  }
+  const key = (d: ModelDependent): string => `${labelOf(d.parent)}\u0000${labelOf(d.child)}\u0000${d.column}\u0000${d.dependent}`;
+  return out.sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
+
+function lifecycleObjects(model: LifecycleTable, dependents: readonly LifecycleDependent[], decl: LifecycleDeclaration, deleteWhen?: string): LifecycleObject[] {
+  const table = qualified(model);
+  const label = labelOf(model);
+  const pk = pkOf(model);
+  const [at, by, batch, xid] = [AT, BY, BATCH, XID];
+  const fn = (suffix: string): string => `${model.schema}.${model.table}_lifecycle_${suffix}`;
+  const skipLifecycleRole = SKIP_LIFECYCLE_ROLE;
+
+  const check = restrictCheck(model, dependents, decl);
+  const transition = defineFunction(fn('transition'), {
+    returns: 'trigger',
+    language: 'plpgsql',
+    security: 'definer',
+    owner: LIFECYCLE_OWNER_ROLE,
+    searchPath: SEARCH_PATH,
+    body: sql`
+#variable_conflict use_column
+<<lc>>
+DECLARE
+  claims text := pg_catalog.current_setting('request.jwt.claims', true);
+  actor text;
+  batch uuid := pg_catalog.gen_random_uuid();
+${check ? `${check.declare}\n` : ''}BEGIN
+  IF TG_TABLE_SCHEMA <> ${literal(model.schema)} OR TG_TABLE_NAME <> ${literal(model.table)} THEN
+    RAISE EXCEPTION USING ERRCODE = '42501', MESSAGE = ${literal(
+      `${fn('transition')} belongs to ${label} and refuses to run as a trigger on `,
+    )} || TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME;
+  END IF;
+${check ? `  ${readCommittedOnly(model)}\n` : ''}  IF lc.claims IS NOT NULL AND lc.claims <> '' THEN
+    lc.actor := lc.claims::pg_catalog.jsonb ->> 'sub';
+  END IF;
+  UPDATE ${table}
+     SET ${at} = pg_catalog.now(),
+         ${by} = lc.actor,
+         ${batch} = lc.batch,
+         ${xid} = pg_catalog.txid_current()
+   WHERE ${pk} = OLD.${pk} AND ${at} IS NULL;
+  -- The batch, for the caller that cannot read it: one line per root of a top-level DELETE,
+  -- appended to a transaction-local setting. Informational; the stamp columns are the truth.
+  IF FOUND AND pg_catalog.pg_trigger_depth() = 1 THEN
+    PERFORM pg_catalog.set_config('everystack.lifecycle_batch',
+      pg_catalog.concat_ws(E'\\n', NULLIF(pg_catalog.current_setting('everystack.lifecycle_batch', true), ''),
+        pg_catalog.to_jsonb(OLD.${pk}::text)::text || ' ' || lc.batch::text), true);
+  END IF;
+${check ? `${check.body}\n` : ''}  RETURN NULL;
+END`,
+  });
+
+  const changed = (op: 'INSERT' | 'UPDATE'): string =>
+    [at, by, batch, xid].map((c) => (op === 'INSERT' ? `NEW.${c} IS NOT NULL` : `NEW.${c} IS DISTINCT FROM OLD.${c}`)).join(' OR ');
+  const refuse = `RAISE EXCEPTION USING ERRCODE = '42501', MESSAGE = ${literal(
+    `${label}: the lifecycle columns (deleted_at, deleted_by, deleted_batch, deleted_xid) are written only by delete and restore`,
+  )};`;
+  const guard = defineFunction(fn('guard'), {
+    returns: 'trigger',
+    language: 'plpgsql',
+    owner: LIFECYCLE_OWNER_ROLE,
+    searchPath: SEARCH_PATH,
+    body: sql`
+BEGIN
+  IF TG_OP = 'INSERT' THEN
+    IF ${changed('INSERT')} THEN
+      ${refuse}
+    END IF;
+  ELSIF ${changed('UPDATE')} THEN
+    ${refuse}
+  END IF;
+  RETURN NEW;
+END`,
+  });
+
+  return [
+    transition,
+    guard,
+    restoreFunction(model, dependents, decl),
+    lifecycleTrigger(`${model.table}_lifecycle_transition`, {
+      on: model, timing: 'before', events: ['delete'], forEach: 'row', condition: TRANSITION_WHEN, execute: transition,
+    }),
+    lifecycleTrigger(`${model.table}_lifecycle_guard`, {
+      on: model, timing: 'before', events: ['insert', 'update'], forEach: 'row', condition: skipLifecycleRole, execute: guard,
+    }),
+    ...cascadeObjects(model, dependents.filter((d) => d.parent === model && d.dependent === 'cascade')),
+    ...parentLiveObjects(model, dependents.filter((d) => d.child === model)),
+    ...deleteWhenObjects(model, deleteWhen),
+  ];
+}
+
+/** Refuse outside READ COMMITTED (55000): an older snapshot cannot see a related row committed since. */
+function readCommittedOnly(model: LifecycleTable, op: 'delete' | 'restore' = 'delete'): string {
+  const what = op === 'delete'
+    ? 'it checks or soft-deletes its dependent rows, which needs READ COMMITTED (a snapshot taken earlier cannot see a dependent row committed since)'
+    : 'it checks its parent rows and restores its dependent rows, which needs READ COMMITTED (a snapshot taken earlier cannot see a related row committed since)';
+  return `IF pg_catalog.current_setting('transaction_isolation') <> 'read committed' THEN
+    RAISE EXCEPTION USING ERRCODE = '55000', MESSAGE = ${literal(
+      `${op} of ${labelOf(model)} refused: ${what}; this transaction is `,
+    )} || pg_catalog.upper(pg_catalog.current_setting('transaction_isolation'));
+  END IF;`;
+}
+
+/** The declared lifecycle parents of `model` ('cascade' or 'restrict'), one per parent and column. */
+function lifecycleParents(model: LifecycleTable, dependents: readonly LifecycleDependent[]): LifecycleDependent[] {
+  const seen = new Set<string>();
+  return dependents.filter((d) => {
+    if (d.child !== model) return false;
+    const k = `${labelOf(d.parent)}\u0000${d.column}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
+/**
+ * `<t>_restore(p_id)`: restore p_id, then every row of its 'cascade' subtree that the same delete
+ * stamped (same deleted_batch), on the ROOT's authority: whoever may delete p_id may undo what that
+ * delete did, rows the caller could not delete included.
+ *
+ * Invariant kept: no live row has a deleted lifecycle parent. The parent-live trigger skips the
+ * lifecycle role (these UPDATEs), so this function checks it itself, reading each parent FOR SHARE
+ * so a concurrent parent delete either waits for this transaction or is seen by it. A deleted
+ * parent of p_id refuses the whole restore. A member comes back only once ALL its parents are live,
+ * so parents always precede children; a member whose other parent stays deleted (another batch, or
+ * itself left deleted) stays deleted, and so does everything under it. The pass repeats until it
+ * restores nothing: a diamond child reached before its second parent is restored on the next pass.
+ *
+ * A unique collision (a live row now holds the value) refuses on p_id and skips a member. The member
+ * UPDATE covers all eligible members of one table per pass. A table with a declared unique index
+ * uses one exception block, falling back to per-row blocks only on unique_violation. The index
+ * decides, including partial and expression indexes, without a check-before-write race. Tables
+ * with only their primary key need no exception block: restore never changes that key. The
+ * handler therefore covers only DECLARED unique indexes: a 23505 from a consumer trigger or an
+ * undeclared index on such a table aborts the restore (the root surfaces the raw 23505, not the
+ * uniform 42501). A self-referencing table restores one depth level per pass.
+ *
+ * Reading a parent FOR SHARE can deadlock with a concurrent cascade delete of its grandparent (that
+ * delete locks the grandparent, then waits on the parent; this restore holds the parent, then
+ * needs a row the delete already locked, such as the grandparent as another parent of a member). PostgreSQL aborts one side with 40P01; the invariant holds
+ * either way, since each side's writes commit or roll back whole.
+ *
+ * The subtree is computed at compile time as the set of tables reachable through 'cascade' edges and
+ * at run time as id arrays per table, grown from the FRONTIER (the ids the previous round added),
+ * so each child is read once rather than once per round. A cycle ends because each new id must be a
+ * deleted row of the batch not yet in its array (the EXCEPT). A NULL batch (a legacy row) restores alone.
+ * Counts only, never another row's id: restored + skipped = the batch subtree.
+ */
+function restoreFunction(model: LifecycleTable, dependents: readonly LifecycleDependent[], decl: LifecycleDeclaration) {
+  const table = qualified(model);
+  const label = labelOf(model);
+  const pk = pkOf(model);
+  const inputTable = (m: TableName): LifecycleTable => {
+    const input = decl.tables[labelOf(m)];
+    if (!input) throw new Error(`lifecycle declaration misses ${labelOf(m)}`);
+    return input;
+  };
+  const rules = model.auth;
+  const roles = Object.keys(rules);
+  const branches = roles.map((role) => `(pg_catalog.pg_has_role(lc.actor, ${literal(role)}, 'USAGE') AND (${rules[role]}))`);
+  const rule = branches.length ? branches.join('\n       OR ') : 'false';
+  // Every variable is qualified (lc.<name>; the parameter by the label PostgreSQL gives the function's
+  // outer block, its own name), so `#variable_conflict use_column` only decides the unqualified
+  // names, and those are the delete rule's columns.
+  const id = `${ident(`${model.table}_restore`)}.p_id`;
+  const refuse = `RAISE EXCEPTION ${literal(`restore refused: ${label} id=% is not a deleted row you may restore`)}, ${id}
+      USING ERRCODE = '42501';`;
+  const clear = `${AT} = NULL, ${BY} = NULL, ${BATCH} = NULL, ${XID} = NULL`;
+
+
+  // The tables of the cascade subtree, root first, in discovery order; the edges among them.
+  const tables: LifecycleTable[] = [model];
+  const cascades = dependents.filter((d) => d.dependent === 'cascade');
+  for (let i = 0; i < tables.length; i++) {
+    for (const d of cascades) if (d.parent === tables[i] && !tables.some(m => labelOf(m) === labelOf(d.child))) tables.push(inputTable(d.child));
+  }
+  const edges = cascades.filter((d) => tables.includes(d.parent));
+  const ix = (m: TableName): number => tables.findIndex(t => labelOf(t) === labelOf(m));
+  const rootParents = lifecycleParents(model, dependents);
+  const related = edges.length > 0 || rootParents.length > 0;
+
+  /** The parent-live test of one row whose foreign keys are the record's p<j> fields. */
+  const parentsLive = (m: LifecycleTable, rec: string, onDeleted: string): string =>
+    lifecycleParents(m, dependents).map((d, j) => `  IF ${rec}.p${j} IS NOT NULL THEN
+    SELECT p.${AT} INTO lc.parent_deleted FROM ${qualified(d.parent)} p WHERE p.${pkOf(d.parent)} = ${rec}.p${j} FOR SHARE;
+    IF NOT FOUND OR lc.parent_deleted IS NOT NULL THEN
+      ${onDeleted}
+    END IF;
+  END IF;`).join('\n');
+  const fkColumns = (m: LifecycleTable, alias: string): string =>
+    lifecycleParents(m, dependents).map((d, j) => `, ${alias}${ident(d.column)} AS p${j}`).join('');
+
+  const declare = [
+    'parent_deleted timestamptz;',
+    'root record;',
+    ...(edges.length === 0 ? [] : [
+      'batch_id uuid;',
+      'live boolean;',
+      'grew boolean;',
+      'progress boolean;',
+      'n bigint;',
+      'restored bigint := 1;',
+      'skipped bigint := 0;',
+      ...tables.flatMap((m, i) => [
+        `s${i} ${pkType(m)}[] := '{}';`,
+        `add${i} ${pkType(m)}[];`,
+        `f${i} ${pkType(m)}[] := '{}';`,
+        `nf${i} ${pkType(m)}[];`,
+        `stuck${i} ${pkType(m)}[] := '{}';`,
+        `ready${i} ${pkType(m)}[] := '{}';`,
+        `r${i} record;`,
+      ]),
+    ]),
+  ].map((l) => `  ${l}`).join('\n');
+
+  const grow = edges.map((d) => {
+    const [p, c] = [ix(d.parent), ix(d.child)];
+    return `      lc.add${c} := ARRAY(SELECT t.${pkOf(inputTable(d.child))} FROM ${qualified(d.child)} t
+          JOIN pg_catalog.unnest(lc.f${p}) AS f(k) ON t.${ident(d.column)} = f.k
+         WHERE t.${AT} IS NOT NULL AND t.${BATCH} = lc.batch_id
+        EXCEPT SELECT pg_catalog.unnest(lc.s${c}));
+      IF pg_catalog.cardinality(lc.add${c}) > 0 THEN
+        lc.s${c} := lc.s${c} || lc.add${c};
+        lc.nf${c} := lc.nf${c} || lc.add${c};
+        lc.grew := true;
+      END IF;`;
+  }).join('\n');
+  const frontierReset = tables.map((_, i) => `      lc.nf${i} := '{}';`).join('\n');
+  const frontierAdvance = tables.map((_, i) => `      lc.f${i} := lc.nf${i};`).join('\n');
+
+  const pass = tables.map((m, i) => {
+    const mpk = pkOf(m);
+    const count = `GET DIAGNOSTICS lc.n = ROW_COUNT;
+          lc.restored := lc.restored + lc.n;
+          lc.progress := lc.progress OR lc.n > 0;`;
+    const bulk = `UPDATE ${qualified(m)} SET ${clear}
+           WHERE ${mpk} = ANY(lc.ready${i}) AND ${AT} IS NOT NULL AND ${BATCH} = lc.batch_id;
+          ${count}`;
+    const update = hasUnique(m) ? `BEGIN
+          ${bulk}
+        EXCEPTION WHEN unique_violation THEN
+          FOR lc.r${i} IN SELECT k FROM pg_catalog.unnest(lc.ready${i}) AS u(k) ORDER BY k LOOP
+            BEGIN
+              UPDATE ${qualified(m)} SET ${clear}
+               WHERE ${mpk} = lc.r${i}.k AND ${AT} IS NOT NULL AND ${BATCH} = lc.batch_id;
+              ${count}
+            EXCEPTION WHEN unique_violation THEN
+              lc.stuck${i} := lc.stuck${i} || lc.r${i}.k;
+            END;
+          END LOOP;
+        END;` : bulk;
+    // Keep parent locks outside the exception block so a failed bulk update cannot release them.
+    return `      lc.ready${i} := '{}';
+      FOR lc.r${i} IN SELECT t.${mpk} AS k${fkColumns(m, 't.')} FROM ${qualified(m)} t
+          WHERE t.${mpk} = ANY(lc.s${i}) AND t.${AT} IS NOT NULL AND t.${BATCH} = lc.batch_id
+            AND t.${mpk} <> ALL(lc.stuck${i})
+          ORDER BY t.${mpk} LOOP
+        lc.live := true;
+${parentsLive(m, `lc.r${i}`, 'lc.live := false;').replace(/^/gm, '      ')}
+        IF lc.live THEN
+          lc.ready${i} := lc.ready${i} || lc.r${i}.k;
+        END IF;
+      END LOOP;
+      IF pg_catalog.cardinality(lc.ready${i}) > 0 THEN
+        ${update}
+      END IF;`;
+  }).join('\n');
+
+  const left = tables.map((m, i) => `    SELECT pg_catalog.count(*) INTO lc.n FROM ${qualified(m)} t
+     WHERE t.${pkOf(m)} = ANY(lc.s${i}) AND t.${AT} IS NOT NULL AND t.${BATCH} = lc.batch_id;
+    lc.skipped := lc.skipped + lc.n;`).join('\n');
+
+  const walk = edges.length === 0
+    ? `  RETURN pg_catalog.jsonb_build_object('restored', 1, 'skipped', 0, 'batch', lc.root.b);`
+    : `  lc.batch_id := lc.root.b;
+  IF lc.batch_id IS NOT NULL THEN
+    lc.s0 := ARRAY[${id}];
+    lc.f0 := lc.s0;
+    LOOP
+      lc.grew := false;
+${frontierReset}
+${grow}
+${frontierAdvance}
+      EXIT WHEN NOT lc.grew;
+    END LOOP;
+    LOOP
+      lc.progress := false;
+${pass}
+      EXIT WHEN NOT lc.progress;
+    END LOOP;
+${left}
+  END IF;
+  RETURN pg_catalog.jsonb_build_object('restored', lc.restored, 'skipped', lc.skipped, 'batch', lc.batch_id);`;
+
+  return defineFunction(`${model.schema}.${model.table}_restore`, {
+    args: [{ name: 'p_id', type: pkType(model) }],
+    returns: 'jsonb',
+    language: 'plpgsql',
+    security: 'definer',
+    owner: LIFECYCLE_OWNER_ROLE,
+    searchPath: SEARCH_PATH,
+    abilities: roles.map((role) => can('execute', { role })),
+    body: sql`
+#variable_conflict use_column
+<<lc>>
+DECLARE
+  actor text := CASE WHEN pg_catalog.current_setting('role') = 'none' THEN session_user
+                     ELSE pg_catalog.current_setting('role') END;
+${declare}
+BEGIN
+${related ? `  ${readCommittedOnly(model, 'restore')}\n` : ''}  SELECT ${BATCH} AS b${fkColumns(model, '')} INTO lc.root FROM ${table}
+   WHERE ${pk} = ${id} AND ${AT} IS NOT NULL
+     AND (${rule})
+     FOR UPDATE;
+  IF NOT FOUND THEN
+    ${refuse}
+  END IF;
+${parentsLive(model, 'lc.root', refuse)}
+${hasUnique(model) ? `  BEGIN
+    UPDATE ${table} SET ${clear} WHERE ${pk} = ${id};
+  EXCEPTION WHEN unique_violation THEN
+    ${refuse}
+  END;` : `  UPDATE ${table} SET ${clear} WHERE ${pk} = ${id};`}
+${walk}
+END`,
+  });
+}
+
+/** The definer function shape every new trigger function shares. */
+function lifecycleTriggerFunction(name: string, body: string) {
+  return defineFunction(name, {
+    returns: 'trigger',
+    language: 'plpgsql',
+    security: 'definer',
+    owner: LIFECYCLE_OWNER_ROLE,
+    searchPath: SEARCH_PATH,
+    body: sql`${body}`,
+  });
+}
+
+/** `<t>_lifecycle_cascade`: stamp each live 'cascade' child with the parent's four values. */
+function cascadeObjects(model: LifecycleTable, children: readonly LifecycleDependent[]): LifecycleObject[] {
+  if (children.length === 0) return [];
+  const name = `${model.schema}.${model.table}_lifecycle_cascade`;
+  const pk = pkOf(model);
+  const updates = children.map((d) => `  UPDATE ${qualified(d.child)}
+     SET ${AT} = NEW.${AT}, ${BY} = NEW.${BY}, ${BATCH} = NEW.${BATCH}, ${XID} = NEW.${XID}
+   WHERE ${ident(d.column)} = NEW.${pk} AND ${AT} IS NULL;`);
+  const cascade = lifecycleTriggerFunction(name, `
+BEGIN
+  ${ownTableOnly(model, name)}
+  ${readCommittedOnly(model)}
+${updates.join('\n')}
+  RETURN NULL;
+END`);
+  return [
+    cascade,
+    lifecycleTrigger(`${model.table}_lifecycle_cascade`, {
+      on: model,
+      timing: 'after',
+      events: ['update'],
+      of: [toSnakeCase(LIFECYCLE_COLUMNS[0])],
+      forEach: 'row',
+      condition: sql`OLD.${AT} IS NULL AND NEW.${AT} IS NOT NULL`,
+      execute: cascade,
+    }),
+  ];
+}
+
+/**
+ * The 'restrict' check, run by the transition AFTER its own stamp, so after the whole cascade
+ * below it has stamped (AFTER ROW triggers fire at the end of that UPDATE). A 'restrict' edge
+ * P -> C refuses the delete when a LIVE C row references a P row this delete stamped: the same
+ * check whether P is the deleted row or a row its cascade reached, and independent of the order
+ * the cascade stamped in, because a C row the same delete stamped is no longer live.
+ *
+ * The stamped P rows are found the way restore finds a batch: from OLD's key, down the 'cascade'
+ * edges, keeping rows of THIS batch, one set per table, grown from the frontier. Only tables on a
+ * cascade path to a 'restrict' parent are walked. OLD's key is in its table's set even when the
+ * row was already deleted (an older batch), so a live child of it still refuses, as before.
+ * Counts run as the lifecycle role, so rows the deleter cannot see still count; the refusal names
+ * the parent table, the child table and a count, never a row.
+ */
+function restrictCheck(model: LifecycleTable, dependents: readonly LifecycleDependent[], decl: LifecycleDeclaration): { declare: string; body: string } | undefined {
+  const inputTable = (m: TableName): LifecycleTable => {
+    const input = decl.tables[labelOf(m)];
+    if (!input) throw new Error(`lifecycle declaration misses ${labelOf(m)}`);
+    return input;
+  };
+  const cascades = dependents.filter((d) => d.dependent === 'cascade');
+  const subtree: LifecycleTable[] = [model];
+  for (let i = 0; i < subtree.length; i++) {
+    for (const d of cascades) if (labelOf(d.parent) === labelOf(subtree[i]) && !subtree.some((m) => labelOf(m) === labelOf(d.child))) subtree.push(inputTable(d.child));
+  }
+  const inSubtree = (m: TableName): boolean => subtree.some((t) => labelOf(t) === labelOf(m));
+  const restricts = dependents.filter((d) => d.dependent === 'restrict' && inSubtree(d.parent));
+  if (restricts.length === 0) return undefined;
+  // Walk only the tables that lead, through cascade edges, to a restrict parent.
+  const needed = new Set(restricts.map((d) => labelOf(d.parent)));
+  for (let grew = true; grew;) {
+    grew = false;
+    for (const d of cascades) {
+      if (inSubtree(d.parent) && needed.has(labelOf(d.child)) && !needed.has(labelOf(d.parent))) { needed.add(labelOf(d.parent)); grew = true; }
+    }
+  }
+  const tables = subtree.filter((m) => needed.has(labelOf(m)));
+  const edges = cascades.filter((d) => needed.has(labelOf(d.parent)) && needed.has(labelOf(d.child)));
+  const ix = (m: TableName): number => tables.findIndex((t) => labelOf(t) === labelOf(m));
+  const walk = edges.length > 0;
+  const keys = (d: LifecycleDependent): string => (walk ? `= ANY(lc.s${ix(d.parent)})` : `= OLD.${pkOf(model)}`);
+  const checks = restricts.map((d) => `  SELECT pg_catalog.count(*) INTO lc.n FROM ${qualified(d.child)} WHERE ${ident(d.column)} ${keys(d)} AND ${AT} IS NULL;
+  IF lc.n > 0 THEN
+    RAISE EXCEPTION USING ERRCODE = '23503', MESSAGE = ${literal(`delete of ${labelOf(d.parent)} refused: `)} || lc.n
+      || ${literal(` live row(s) of ${labelOf(d.child)} still reference it (dependent 'restrict' on ${d.column})`)};
+  END IF;`).join('\n');
+  const declare = [
+    'n bigint;',
+    ...(walk ? ['grew boolean;', ...tables.flatMap((m, i) => [
+      `s${i} ${pkType(m)}[] := '{}';`, `f${i} ${pkType(m)}[] := '{}';`, `nf${i} ${pkType(m)}[];`,
+      // Only a table some walk edge grows into needs the per-edge buffer.
+      ...(edges.some((d) => ix(d.child) === i) ? [`add${i} ${pkType(m)}[];`] : []),
+    ])] : []),
+  ].map((l) => `  ${l}`).join('\n');
+  if (!walk) return { declare, body: checks };
+  const grow = edges.map((d) => {
+    const [p, c] = [ix(d.parent), ix(d.child)];
+    return `    lc.add${c} := ARRAY(SELECT t.${pkOf(inputTable(d.child))} FROM ${qualified(d.child)} t
+        JOIN pg_catalog.unnest(lc.f${p}) AS f(k) ON t.${ident(d.column)} = f.k
+       WHERE t.${BATCH} = lc.batch
+      EXCEPT SELECT pg_catalog.unnest(lc.s${c}));
+    IF pg_catalog.cardinality(lc.add${c}) > 0 THEN
+      lc.s${c} := lc.s${c} || lc.add${c};
+      lc.nf${c} := lc.nf${c} || lc.add${c};
+      lc.grew := true;
+    END IF;`;
+  }).join('\n');
+  const body = `  lc.s0 := ARRAY[OLD.${pkOf(model)}];
+  lc.f0 := lc.s0;
+  LOOP
+    lc.grew := false;
+${tables.map((_, i) => `    lc.nf${i} := '{}';`).join('\n')}
+${grow}
+${tables.map((_, i) => `    lc.f${i} := lc.nf${i};`).join('\n')}
+    EXIT WHEN NOT lc.grew;
+  END LOOP;
+${checks}`;
+  return { declare, body };
+}
+
+/**
+ * `<t>_lifecycle_delete_when` — lifecycle: { deleteWhen }'s guard. BEFORE UPDATE OF deleted_at on
+ * the live -> deleted stamp, so it fires for the row's own stamp (the transition's UPDATE) and for
+ * a parent's cascade stamp alike (a cascaded child's BEFORE DELETE transition never runs). The
+ * predicate is read with bare column names against the row as it still stands (a BEFORE trigger:
+ * the table holds the old values), one primary-key lookup per stamped row. The predicate sits on
+ * lines of its own, so a trailing `--` comment in it ends only its own line. Anything but TRUE
+ * refuses with 23514 and the constraint name, naming the table and never a row value; the whole
+ * statement rolls back, so one guarded child refuses its parent's delete. No role test: only the
+ * lifecycle role stamps (the guard), and restore and purge never make this transition.
+ */
+function deleteWhenObjects(model: LifecycleTable, deleteWhen: string | undefined): LifecycleObject[] {
+  if (deleteWhen === undefined) return [];
+  const name = `${model.schema}.${model.table}_lifecycle_delete_when`;
+  const pk = pkOf(model);
+  const guard = lifecycleTriggerFunction(name, `
+#variable_conflict use_column
+<<lc>>
+DECLARE
+  allowed boolean;
+BEGIN
+  ${ownTableOnly(model, name)}
+  SELECT (
+${deleteWhen}
+) INTO lc.allowed FROM ${qualified(model)} WHERE ${pk} = OLD.${pk};
+  IF lc.allowed IS NOT TRUE THEN
+    RAISE EXCEPTION USING ERRCODE = '23514', CONSTRAINT = ${literal(`${model.table}_lifecycle_delete_when`)},
+      SCHEMA = ${literal(model.schema)}, TABLE = ${literal(model.table)},
+      MESSAGE = ${literal(`delete of ${labelOf(model)} refused: the model's deleteWhen does not allow deleting this row`)};
+  END IF;
+  RETURN NEW;
+END`);
+  return [
+    guard,
+    lifecycleTrigger(`${model.table}_lifecycle_delete_when`, {
+      on: model,
+      timing: 'before',
+      events: ['update'],
+      of: [toSnakeCase(LIFECYCLE_COLUMNS[0])],
+      forEach: 'row',
+      condition: sql`OLD.${AT} IS NULL AND NEW.${AT} IS NOT NULL`,
+      execute: guard,
+    }),
+  ];
+}
+
+/**
+ * `<t>_lifecycle_parent` on a lifecycle child: a live row may not reference a deleted parent of a
+ * 'cascade' or 'restrict' relation. Only a lifecycle parent can be deleted and still be there.
+ */
+function parentLiveObjects(model: LifecycleTable, parents: readonly LifecycleDependent[]): LifecycleObject[] {
+  const unique = lifecycleParents(model, parents);
+  if (unique.length === 0) return [];
+  const name = `${model.schema}.${model.table}_lifecycle_parent`;
+  const checks = unique.map((d) => {
+    const fk = ident(d.column);
+    return `    IF NEW.${fk} IS NOT NULL AND (TG_OP = 'INSERT' OR NEW.${fk} IS DISTINCT FROM OLD.${fk}) THEN
+      SELECT p.${AT} INTO lc.parent_deleted FROM ${qualified(d.parent)} p WHERE p.${pkOf(d.parent)} = NEW.${fk} FOR SHARE;
+      -- A missing parent gets the same refusal as a deleted one. Left to the foreign key, it would
+      -- fail with a different message, telling any inserter which ids are hidden deleted rows.
+      IF NOT FOUND OR lc.parent_deleted IS NOT NULL THEN
+        RAISE EXCEPTION USING ERRCODE = '23503', MESSAGE = ${literal(
+          `${labelOf(model)}: a live row may not reference a missing or deleted ${labelOf(d.parent)} row (${d.column})`,
+        )};
+      END IF;
+      lc.parent_deleted := NULL;
+    END IF;`;
+  });
+  const parentLive = lifecycleTriggerFunction(name, `
+#variable_conflict use_column
+<<lc>>
+DECLARE
+  parent_deleted timestamptz;
+BEGIN
+  ${ownTableOnly(model, name)}
+  IF NEW.${AT} IS NULL THEN
+${checks.join('\n')}
+  END IF;
+  RETURN NEW;
+END`);
+  const columns = [...new Set(unique.map((d) => d.column))].sort();
+  return [
+    parentLive,
+    lifecycleTrigger(`${model.table}_lifecycle_parent`, {
+      on: model, timing: 'before', events: ['insert', 'update'], of: columns, forEach: 'row', condition: SKIP_LIFECYCLE_ROLE, execute: parentLive,
+    }),
+  ];
+}
+
+/** Serialize the root, its cascade subtree and every lifecycle parent those builders read. */
+export function declOf(model: ModelDescriptor, dependents: readonly ModelDependent[]): LifecycleDeclaration {
+  const subtree = new Set<ModelDescriptor>([model]);
+  for (const parent of subtree) {
+    for (const edge of dependents) if (edge.parent === parent && edge.dependent === 'cascade') subtree.add(edge.child);
+  }
+  // A 'restrict' edge below the subtree is a transition input: the delete checks it after the cascade.
+  const relevant = dependents.filter(d => d.parent === model || subtree.has(d.child) || (d.dependent === 'restrict' && subtree.has(d.parent)));
+  const inputs = new Set([...subtree, ...relevant.map(d => d.parent)]);
+  const tables: Record<string, LifecycleTable> = {};
+  for (const m of [...inputs].sort((a, b) => labelOf(a) < labelOf(b) ? -1 : labelOf(a) > labelOf(b) ? 1 : 0)) {
+    tables[labelOf(m)] = {
+      schema: m.schema, table: m.table,
+      pk: { column: toSnakeCase(m.primaryKey[0]), type: pgType(m.fields[m.primaryKey[0]].spec) },
+      unique: Object.values(m.fields).some(f => f.spec.isUnique && !f.spec.isPrimaryKey)
+        || m.constraints.some(c => c.kind === 'unique' || (c.kind === 'index' && c.isUnique)),
+      // Role insertion order is a builder input: its branches must stay byte-identical.
+      auth: deleteRulePredicates(m),
+    };
+  }
+  return { tables, edges: relevant.map(d => ({ parent: labelOf(d.parent),
+    // A restrict-only child has no table descriptor: quote its dotted schema before splitting.
+    child: !tables[labelOf(d.child)] && /[."]/.test(d.child.schema) ? `${ident(d.child.schema)}.${ident(d.child.table)}` : labelOf(d.child),
+    column: d.column, dependent: d.dependent })) };
+}
+
+/** One generator for model emission and verification of recorded JSON inputs. */
+export function regenerateLifecycle(model: string, decl: LifecycleDeclaration, deleteWhen?: string): LifecycleObject[] {
+  const root = decl.tables[model];
+  if (!root) throw new Error(`lifecycle declaration misses ${model}`);
+  const dependents = decl.edges.map(edge => {
+    const parent = decl.tables[edge.parent];
+    if (!parent) throw new Error(`lifecycle declaration misses ${edge.parent}`);
+    // A restrict-only child contributes its qualified name, not fields or restore inputs.
+    const { schema, name: table } = parseQualified(edge.child);
+    return { parent, child: decl.tables[edge.child] ?? { schema, table }, column: edge.column, dependent: edge.dependent };
+  });
+  return lifecycleObjects(root, dependents, decl, deleteWhen);
+}
+
+/** The generated lifecycle objects, with comments stamped by the ordinary reconciler. */
+export function lifecycleDerived(models: readonly ModelDescriptor[]): DerivedDescriptor[] {
+  const dependents = lifecycleDependents(models);
+  const byName = new Map(models.map(model => [labelOf(model), model]));
+  return [...new Set(models)].filter(m => m.lifecycle === true)
+    .sort((a, b) => labelOf(a) < labelOf(b) ? -1 : labelOf(a) > labelOf(b) ? 1 : 0)
+    .flatMap(model => {
+      const decl = declOf(model, dependents);
+      const generated = regenerateLifecycle(labelOf(model), decl, model.deleteWhen);
+      for (const object of generated) {
+        if (object.kind !== 'function') continue;
+        const role = lifecycleRole(object.name, labelOf(model));
+        if (!role) throw new Error(`unknown lifecycle function ${object.name}`);
+        const manifest: LifecycleManifest = { everystack: 'lifecycle', v: MANIFEST_VERSION, role, model: labelOf(model), decl,
+          ...(role === 'delete_when' && model.deleteWhen !== undefined ? { deleteWhen: model.deleteWhen } : {}), defHash: canonHash(canonOfFunction(object)) };
+        object.comment = JSON.stringify(manifest);
+      }
+      // Only the emitter binds table references back to Models; the builders never see them.
+      return generated.map(object => object.kind === 'trigger' ? { ...object, on: byName.get(labelOf(object.on))! } : object);
+    });
+}