@everystack/cli 0.4.102 → 0.4.104

package/src/cli/lifecycle-derived.ts

@@ -1,49 +1,58 @@
 /**
  * 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
+ * Per lifecycle table `<t>`, generated functions and triggers use 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
+ *    owned by the lifecycle role sets 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 deleted 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 delete (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
+ *    the whole cascade subtree that delete marked, 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, never ids.
+ *    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:
+ * row, so the FK never fires. Physical removal follows the declared FK action. Soft deletion uses
+ * the cascade trigger and transition 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
+ *    lifecycle values 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.
+ *    It UPDATEs, never DELETEs: a DELETE would give each child its own batch. Depth
+ *    comes from each child's own cascade trigger; a child reached twice
+ *    (a diamond) is already deleted 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).
+ *    after its delete (so after the whole cascade), refuses (23503) while a LIVE child references a
+ *    row the delete marked deleted. One check, after everything is marked deleted: a child the same delete
+ *    marked deleted 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
+ *    A trigger fired by a soft delete or by destroy 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.
+ *    During destroy, a DELETE (a consumer trigger's included) removes a row only if it is already
+ *    soft-deleted and either before the call's cutoff or a cascade child whose declared cascade
+ *    parent is gone; any other row raises 23503. Otherwise deletes are soft.
  *
  * 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.
@@ -51,11 +60,12 @@
  *    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
+ *    concurrent delete 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
+ * The guard and the parent check skip the lifecycle role, the one role that marks rows deleted. The
+ * transition does not: it tests only the destroy marker, so outside a destroy call that role's
+ * DELETE is soft too. 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.
@@ -64,13 +74,20 @@
  * 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.
  *
+ * `<t>_lifecycle_destroy` removes eligible rows under a private, transaction-scoped authority: a
+ * destroy_log marker, holding the call's cutoff, that exists only while the call runs.
+ * `<t>_lifecycle_destroy_before` exposes only that cutoff (NULL without a marker) to the transition,
+ * which really removes a row only when it was soft-deleted before it (see eligibleOnly). No role but
+ * the log's owner can write or read it: the lifecycle role goes through everystack.destroy_log_mark,
+ * destroy_log_unmark and destroy_cutoff (packages/model/src/destroy-log.ts).
+ *
  * 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 { can, defineFunction, trigger, sql, parseQualified, lifecycleDestroyOrder, relationDeleteActions, 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 { pgType, toSnakeCase, modelForeignKeys } from './schema-compile';
+import { allRowsManageRoles, deleteRulePredicates } from './authz-compile';
 import { canonHash, canonOfFunction } from './lifecycle-canon';
 
 /** Exact inputs read by the lifecycle builders, serializable without model references. */
@@ -80,6 +97,8 @@ export interface LifecycleTable {
   pk: { column: string; type: string };
   unique: boolean;
   auth: Record<string, string>;
+  /** The trusted audience for physical removal, independent of delete predicates. */
+  manageRoles?: string[];
 }
 export interface LifecycleEdge {
   parent: string;
@@ -87,12 +106,26 @@ export interface LifecycleEdge {
   column: string;
   dependent: 'cascade' | 'restrict';
 }
+export interface LifecycleDestroyReference {
+  child: { schema: string; table: string };
+  columns: string[];
+  refColumns: string[];
+}
 export interface LifecycleDeclaration {
   tables: Record<string, LifecycleTable>;
   edges: LifecycleEdge[];
+  /** All declared inbound restrict/no-action FKs of this root; absent on older recorded inputs. */
+  destroyReferences?: LifecycleDestroyReference[];
+  /**
+   * The keys this root declares 'nullify' (`schema.table` of the child, its column). No builder reads
+   * them: a soft delete leaves the parent row, so a nullify needs nothing until destroy's SET NULL.
+   * They record the declaration for the live catalog check. Always present (empty when the root
+   * declares none): its absence marks a manifest from a CLI that predates the record.
+   */
+  nullify?: Array<{ child: string; column: string }>;
 }
 export const MANIFEST_VERSION = 1;
-export const LIFECYCLE_ROLES = ['transition', 'guard', 'restore', 'cascade', 'parent'] as const;
+export const LIFECYCLE_ROLES = ['transition', 'guard', 'restore', 'cascade', 'parent', 'delete_when', 'destroy_before', 'destroy'] as const;
 export type LifecycleRole = typeof LIFECYCLE_ROLES[number];
 export interface LifecycleManifest {
   everystack: 'lifecycle';
@@ -100,6 +133,9 @@ export interface LifecycleManifest {
   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'>;
@@ -131,13 +167,43 @@ 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 HINT of the transition's refusal of a live row (the tamper alarm); destroy matches it, never message text. */
+const INELIGIBLE_LIVE = 'everystack:ineligible_live';
+
 /**
- * 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.
+ * The transition's first decision, before any soft-delete work. During a destroy call (the
+ * destroy_log marker of this transaction holds the call's cutoff), a lifecycle DELETE really removes
+ * a row only if it is already soft-deleted AND either before that cutoff (the test the call applies
+ * to its roots) or a cascade child whose declared cascade parent is gone: soft delete decided its
+ * fate with the root's, so eligibility follows the root, whatever the child's own stamp. The parent
+ * check is exact: a BEFORE DELETE fired by the parent's ON DELETE CASCADE runs after the parent row is
+ * removed, and a non-NULL key with no parent row can only mean a removal in this transaction. Any
+ * other row raises 23503 (foreign_key_violation): a live row (HINT `everystack:ineligible_live`, the
+ * tamper alarm) or a soft-deleted one that is neither expired nor cascading (a consumer trigger may
+ * not erase it early). The destroy function retries each root alone and reports one that still
+ * raises as 'skipped', so nothing is removed for it and no child is left under a removed parent. The
+ * message names this table, never a row. Without a marker the cutoff is NULL and the row takes the
+ * soft-delete path, whoever issues the DELETE, the lifecycle role included. Application roles must
+ * not own these tables, be superusers, or inherit or assume the lifecycle or manage roles: owners
+ * can disable triggers.
  */
-const TRANSITION_WHEN = sql`CURRENT_USER <> ${literal(LIFECYCLE_OWNER_ROLE)} OR pg_catalog.pg_trigger_depth() > 0`;
+function eligibleOnly(model: LifecycleTable, cascadeParents: readonly LifecycleDependent[]): string {
+  const parentGone = cascadeParents.map((d) => `
+       OR (OLD.${ident(d.column)} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${qualified(d.parent)} p WHERE p.${pkOf(d.parent)} = OLD.${ident(d.column)}))`).join('');
+  return `lc.cutoff := ${ident(model.schema)}.${ident(model.table + '_lifecycle_destroy_before')}();
+  IF lc.cutoff IS NOT NULL THEN
+    IF OLD.${AT} IS NOT NULL AND (OLD.${AT} < lc.cutoff${parentGone}) THEN
+      RETURN OLD;
+    END IF;
+    IF OLD.${AT} IS NULL THEN
+      RAISE EXCEPTION USING ERRCODE = '23503', MESSAGE = ${literal(`destroy refused: a ${labelOf(model)} row is not eligible for destroy (it is live; only deleted rows are removed)`)},
+        SCHEMA = ${literal(model.schema)}, TABLE = ${literal(model.table)}, HINT = ${literal(INELIGIBLE_LIVE)};
+    END IF;
+    RAISE EXCEPTION USING ERRCODE = '23503', MESSAGE = ${literal(
+      `destroy refused: a ${labelOf(model)} row is not eligible for destroy (it is neither deleted before the call's cutoff nor removed with its cascade parent)`,
+    )}, SCHEMA = ${literal(model.schema)}, TABLE = ${literal(model.table)};
+  END IF;`;
+}
 
 /** The first statement of every generated trigger function: run only as a trigger on `model`. */
 function ownTableOnly(model: LifecycleTable, fnName: string): string {
@@ -159,7 +225,7 @@ interface ModelDependent {
 
 /**
  * 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:
+ * child and column so the generated bodies are byte-stable. 'nullify' needs nothing until destroy:
  * 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.
@@ -179,7 +245,7 @@ function lifecycleDependents(models: readonly ModelDescriptor[]): ModelDependent
   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): LifecycleObject[] {
+function lifecycleObjects(model: LifecycleTable, dependents: readonly LifecycleDependent[], decl: LifecycleDeclaration, deleteWhen?: string): LifecycleObject[] {
   const table = qualified(model);
   const label = labelOf(model);
   const pk = pkOf(model);
@@ -200,21 +266,31 @@ function lifecycleObjects(model: LifecycleTable, dependents: readonly LifecycleD
 DECLARE
   claims text := pg_catalog.current_setting('request.jwt.claims', true);
   actor text;
+  batch uuid := pg_catalog.gen_random_uuid();
+  cutoff timestamptz;
 ${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;
+  ${eligibleOnly(model, lifecycleParents(model, dependents).filter((d) => d.dependent === 'cascade'))}
 ${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} = ${check ? 'lc.batch' : 'pg_catalog.gen_random_uuid()'},
+         ${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`,
   });
@@ -246,17 +322,146 @@ END`,
     transition,
     guard,
     restoreFunction(model, dependents, decl),
+    ...destroyFunctions(model, dependents, decl),
     lifecycleTrigger(`${model.table}_lifecycle_transition`, {
-      on: model, timing: 'before', events: ['delete'], forEach: 'row', condition: TRANSITION_WHEN, execute: transition,
+      on: model, timing: 'before', events: ['delete'], forEach: 'row', 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),
   ];
 }
 
+/**
+ * Physical removal runs inside one call that writes its destroy_log marker (with p_before, the cutoff
+ * every transition checks) first and removes it before it returns, so the log is empty at rest. The
+ * marker functions refuse to run inside a trigger (55000), so the call must be a top-level statement:
+ * a nested call, and a consumer trigger's attempt to remove or rewrite the marker, are refused. If the
+ * marker is gone at the end anyway (code the log's owner wrote removed it), a cascaded child may have
+ * been soft-deleted under a removed root, so the call raises 55000 and rolls back whole. Any remaining
+ * declared restrict/no-action foreign key defers its root, dead children included; a live blocker leaves it overdue for
+ * db:doctor to report. lifecycleDestroyOrder orders declared dependents; callers order ordinary
+ * FK children first themselves. Self-restrict
+ * trees converge one level per call. Fewer than p_max_rows may return: concurrent locks are skipped.
+ * The caller sets statement_timeout BEFORE invoking and passes the SAME p_before used to select
+ * candidates: a row restored and re-deleted after that cutoff is skipped, so stale hook approval
+ * cannot destroy it. A key the deferral cannot see (a NO ACTION key into a cascaded child, or one
+ * from a table outside the model set) raises foreign_key_violation. The set DELETE then rolls back
+ * and each candidate is retried alone; a root that still raises is returned as 'skipped' and the
+ * rest are removed. A skipped row carries reason and blocker (NULL on 'removed'), built from the
+ * error's name fields only: 'referenced' (a foreign key; blocker = the referencing
+ * schema.table.constraint, as PostgreSQL names it), or the transition's HINT 'ineligible_live'
+ * (a live row; blocker = that table's schema.table). The retry walks past skipped roots until p_max_rows are removed, so the oldest
+ * pinned roots cannot starve the table. Only that error is caught: a lock timeout or any other
+ * error rolls the call back. The retry costs one subtransaction per candidate it tries, so it runs
+ * only after the set DELETE failed.
+ * Application roles must not own lifecycle tables, be superusers, or inherit
+ * or assume everystack_lifecycle or a manage role; a table owner can disable triggers.
+ */
+function destroyFunctions(model: LifecycleTable, dependents: readonly LifecycleDependent[], decl: LifecycleDeclaration): FunctionDescriptor[] {
+  const name = `${model.schema}.${model.table}_lifecycle_destroy`;
+  const table = qualified(model);
+  const pk = pkOf(model);
+  const candidateKey = `lc_candidate.${pk}`;
+  // Older manifests recorded only hasMany dependents. Preserve their exact regeneration.
+  const references = decl.destroyReferences ?? dependents.filter(d => d.parent === model && d.dependent === 'restrict')
+    .map(d => ({ child: d.child, columns: [d.column], refColumns: [model.pk.column] }));
+  const restrict = references.map(reference => {
+    const child = qualified(reference.child);
+    const match = reference.columns.map((column, i) => `${child}.${ident(column)} = lc_candidate.${ident(reference.refColumns[i])}`).join(' AND ');
+    return `        AND NOT EXISTS (SELECT 1 FROM ${child} WHERE ${match})`;
+  }).join('\n');
+  const parameter = (key: string): string => `${ident(model.table + '_lifecycle_destroy')}.${key}`;
+  const destroyBefore = defineFunction(`${model.schema}.${model.table}_lifecycle_destroy_before`, {
+    returns: 'timestamptz', language: 'sql', volatility: 'stable', security: 'definer',
+    // No grant: the only caller is the transition, a definer function the same role owns.
+    // `internal` tells db:check that is reviewed and permanent, not an undeclared audience.
+    internal: true,
+    owner: LIFECYCLE_OWNER_ROLE, searchPath: SEARCH_PATH,
+    body: sql`SELECT everystack.destroy_cutoff()`,
+  });
+  const destroy = defineFunction(name, {
+    args: [
+      { name: 'p_keys', type: `${pkType(model)}[]`, default: 'NULL' },
+      { name: 'p_before', type: 'timestamptz', default: 'pg_catalog.now()' },
+      { name: 'p_max_rows', type: 'integer', default: '1000' },
+    ],
+    returns: `TABLE(key ${pkType(model)}, outcome text, reason text, blocker text)`, language: 'plpgsql', security: 'definer',
+    lockTimeout: '5s',
+    owner: LIFECYCLE_OWNER_ROLE, searchPath: SEARCH_PATH,
+    abilities: (model.manageRoles ?? []).map(role => can('execute', { role })),
+    body: sql`
+#variable_conflict use_column
+<<lc>>
+DECLARE
+  candidate ${pkType(model)};
+  removed_keys ${pkType(model)}[] := '{}';
+  skipped_keys ${pkType(model)}[] := '{}';
+  skipped_reasons text[] := '{}';
+  skipped_blockers text[] := '{}';
+  err_schema text;
+  err_table text;
+  err_constraint text;
+  err_hint text;
+BEGIN
+  IF p_max_rows IS NULL OR p_max_rows < 1 THEN
+    RAISE EXCEPTION USING ERRCODE = '22023', MESSAGE = 'p_max_rows must be a positive integer';
+  END IF;
+  PERFORM everystack.destroy_log_mark(${parameter('p_before')});
+  BEGIN
+    WITH lc_gone AS (
+      DELETE FROM ${table}
+      WHERE ${pk} IN (
+      SELECT ${candidateKey} FROM ${table} AS lc_candidate
+      WHERE lc_candidate.${AT} IS NOT NULL AND lc_candidate.${AT} < ${parameter('p_before')}
+        AND (${parameter('p_keys')} IS NULL OR ${candidateKey} = ANY(${parameter('p_keys')}))
+${restrict ? `${restrict}\n` : ''}      ORDER BY lc_candidate.${AT}, ${candidateKey}
+      LIMIT ${parameter('p_max_rows')} FOR UPDATE SKIP LOCKED
+      ) RETURNING ${pk}
+    ) SELECT COALESCE(pg_catalog.array_agg(lc_gone.${pk}), '{}') INTO lc.removed_keys FROM lc_gone;
+  EXCEPTION WHEN foreign_key_violation THEN
+    FOR lc.candidate IN
+      SELECT ${candidateKey} FROM ${table} AS lc_candidate
+      WHERE lc_candidate.${AT} IS NOT NULL AND lc_candidate.${AT} < ${parameter('p_before')}
+        AND (${parameter('p_keys')} IS NULL OR ${candidateKey} = ANY(${parameter('p_keys')}))
+${restrict ? `${restrict}\n` : ''}      ORDER BY lc_candidate.${AT}, ${candidateKey}
+      FOR UPDATE SKIP LOCKED
+    LOOP
+      EXIT WHEN pg_catalog.cardinality(lc.removed_keys) >= ${parameter('p_max_rows')};
+      BEGIN
+        DELETE FROM ${table} WHERE ${pk} = lc.candidate;
+        IF FOUND THEN lc.removed_keys := lc.removed_keys || lc.candidate; END IF;
+      EXCEPTION WHEN foreign_key_violation THEN
+        -- Names only: MESSAGE_TEXT and the DETAIL of a foreign key error carry a key value.
+        GET STACKED DIAGNOSTICS lc.err_schema = SCHEMA_NAME, lc.err_table = TABLE_NAME,
+          lc.err_constraint = CONSTRAINT_NAME, lc.err_hint = PG_EXCEPTION_HINT;
+        lc.skipped_keys := lc.skipped_keys || lc.candidate;
+        lc.skipped_reasons := pg_catalog.array_append(lc.skipped_reasons, CASE lc.err_hint
+          WHEN ${literal(INELIGIBLE_LIVE)} THEN 'ineligible_live'
+          ELSE 'referenced' END);
+        -- A consumer's RAISE can set any text: each part is capped at an identifier's length.
+        lc.skipped_blockers := pg_catalog.array_append(lc.skipped_blockers, NULLIF(pg_catalog.concat_ws('.',
+          NULLIF(pg_catalog.left(lc.err_schema, 63), ''), NULLIF(pg_catalog.left(lc.err_table, 63), ''),
+          NULLIF(pg_catalog.left(lc.err_constraint, 63), '')), ''));
+      END;
+    END LOOP;
+  END;
+  IF NOT everystack.destroy_log_unmark() THEN
+    RAISE EXCEPTION USING ERRCODE = '55000', MESSAGE = ${literal(
+      `destroy of ${labelOf(model)} failed: the destroy_log marker was removed during the call, so a cascaded child may have been soft-deleted instead of removed; nothing was destroyed`,
+    )};
+  END IF;
+  RETURN QUERY SELECT lc_key, 'removed'::text, NULL::text, NULL::text FROM pg_catalog.unnest(lc.removed_keys) AS lc_key
+    UNION ALL SELECT lc_skip.k, 'skipped'::text, lc_skip.r, lc_skip.b
+      FROM ROWS FROM (pg_catalog.unnest(lc.skipped_keys), pg_catalog.unnest(lc.skipped_reasons), pg_catalog.unnest(lc.skipped_blockers)) AS lc_skip(k, r, b);
+END`,
+  });
+  return [destroyBefore, destroy];
+}
+
 /** 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'
@@ -283,7 +488,7 @@ function lifecycleParents(model: LifecycleTable, dependents: readonly LifecycleD
 
 /**
  * `<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
+ * marked deleted (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
@@ -439,7 +644,7 @@ ${parentsLive(m, `lc.r${i}`, 'lc.live := false;').replace(/^/gm, '      ')}
     lc.skipped := lc.skipped + lc.n;`).join('\n');
 
   const walk = edges.length === 0
-    ? `  RETURN pg_catalog.jsonb_build_object('restored', 1, 'skipped', 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}];
@@ -458,7 +663,7 @@ ${pass}
     END LOOP;
 ${left}
   END IF;
-  RETURN pg_catalog.jsonb_build_object('restored', lc.restored, 'skipped', lc.skipped);`;
+  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) }],
@@ -506,7 +711,7 @@ function lifecycleTriggerFunction(name: string, body: string) {
   });
 }
 
-/** `<t>_lifecycle_cascade`: stamp each live 'cascade' child with the parent's four values. */
+/** `<t>_lifecycle_cascade`: mark 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`;
@@ -537,10 +742,10 @@ END`);
 
 /**
  * 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
+ * below it has marked rows deleted (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 marked deleted: 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 cascade ran in, because a C row the same delete marked deleted 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
@@ -582,7 +787,6 @@ function restrictCheck(model: LifecycleTable, dependents: readonly LifecycleDepe
       || ${literal(` live row(s) of ${labelOf(d.child)} still reference it (dependent 'restrict' on ${d.column})`)};
   END IF;`).join('\n');
   const declare = [
-    'batch uuid := pg_catalog.gen_random_uuid();',
     'n bigint;',
     ...(walk ? ['grew boolean;', ...tables.flatMap((m, i) => [
       `s${i} ${pkType(m)}[] := '{}';`, `f${i} ${pkType(m)}[] := '{}';`, `nf${i} ${pkType(m)}[];`,
@@ -616,9 +820,57 @@ ${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 delete (the transition's UPDATE) and for
+ * a parent's cascade 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 deleted 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 marks rows deleted (the guard), and restore and destroy 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.
+ * The 23503 names the child table and `<t>_lifecycle_parent` as its constraint (names only), so a
+ * destroy root it skips reports a named blocker.
  */
 function parentLiveObjects(model: LifecycleTable, parents: readonly LifecycleDependent[]): LifecycleObject[] {
   const unique = lifecycleParents(model, parents);
@@ -633,7 +885,7 @@ function parentLiveObjects(model: LifecycleTable, parents: readonly LifecycleDep
       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})`,
-        )};
+        )}, SCHEMA = ${literal(model.schema)}, TABLE = ${literal(model.table)}, CONSTRAINT = ${literal(`${model.table}_lifecycle_parent`)};
       END IF;
       lc.parent_deleted := NULL;
     END IF;`;
@@ -677,6 +929,8 @@ export function declOf(model: ModelDescriptor, dependents: readonly ModelDepende
         || 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),
+      // Destroy ignores row ownership, so only a manage that already covers every row may run it.
+      manageRoles: allRowsManageRoles(m),
     };
   }
   return { tables, edges: relevant.map(d => ({ parent: labelOf(d.parent),
@@ -686,7 +940,7 @@ export function declOf(model: ModelDescriptor, dependents: readonly ModelDepende
 }
 
 /** One generator for model emission and verification of recorded JSON inputs. */
-export function regenerateLifecycle(model: string, decl: LifecycleDeclaration): LifecycleObject[] {
+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 => {
@@ -696,23 +950,58 @@ export function regenerateLifecycle(model: string, decl: LifecycleDeclaration):
     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);
+  return lifecycleObjects(root, dependents, decl, deleteWhen);
+}
+
+/**
+ * The manifest a generated lifecycle function carries, from its descriptor's `comment` (the models
+ * path) or its compiled COMMENT attachment (a db:reconcile payload). Undefined for any other object.
+ */
+export function lifecycleManifestOf(object: { kind: string; owner?: string; comment?: string; attachments?: readonly { kind: string; sql: string }[] }): LifecycleManifest | undefined {
+  if (object.kind !== 'function' || object.owner !== LIFECYCLE_OWNER_ROLE) return undefined;
+  let text = object.comment;
+  if (text === undefined) {
+    const attached = object.attachments?.find(a => a.kind === 'comment')?.sql.match(/ IS '((?:[^']|'')*)'$/s);
+    text = attached?.[1].replace(/''/g, "'");
+  }
+  if (text === undefined) return undefined;
+  try {
+    const manifest = JSON.parse(text) as LifecycleManifest;
+    return manifest?.everystack === 'lifecycle' ? manifest : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
 /** The generated lifecycle objects, with comments stamped by the ordinary reconciler. */
 export function lifecycleDerived(models: readonly ModelDescriptor[]): DerivedDescriptor[] {
+  lifecycleDestroyOrder(models);
   const dependents = lifecycleDependents(models);
   const byName = new Map(models.map(model => [labelOf(model), model]));
+  const actions = relationDeleteActions(models);
+  const foreignKeys = [...new Set(models)].flatMap(child => modelForeignKeys(child, actions).map(fk => ({ child, fk })));
   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);
+      const refName = model.schema === 'public' ? model.table : labelOf(model);
+      const references = foreignKeys.filter(({ fk }) => (fk.refTable === refName || fk.refTable === labelOf(model))
+        && (fk.onDelete === undefined || fk.onDelete === 'restrict' || fk.onDelete === 'no action'))
+        .map(({ child, fk }) => ({ child: { schema: child.schema, table: child.table }, columns: fk.columns, refColumns: fk.refColumns }));
+      const key = (reference: LifecycleDestroyReference): string => JSON.stringify([reference.child.schema, reference.child.table, reference.columns, reference.refColumns]);
+      decl.destroyReferences = [...new Map(references.map(reference => [key(reference), reference])).values()]
+        .sort((a, b) => key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0);
+      const nullify = (Object.values(model.relations) as Relation[]).filter(rel => rel.kind === 'hasMany' && rel.dependent === 'nullify')
+        .map(rel => ({ child: labelOf(rel.target()), column: toSnakeCase(rel.column) }))
+        .sort((a, b) => (`${a.child}\u0000${a.column}` < `${b.child}\u0000${b.column}` ? -1 : 1));
+      decl.nullify = nullify;
+      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, defHash: canonHash(canonOfFunction(object)) };
+        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.