@everystack/model 0.4.23 → 0.4.25

package/src/dependents.ts

@@ -14,9 +14,10 @@
  *
  * Ratified rules (F7):
  *  - 'restrict' → 'restrict', 'nullify' → 'set null', 'cascade' → 'cascade'.
- *  - Lifecycle (P1.2): a lifecycle parent's 'cascade' needs a lifecycle child and compiles to
- *    'restrict' (the soft-delete cascade runs in triggers). Any other cascade into a lifecycle
- *    table is refused, and so is a lifecycle parent's 'cascade' or 'restrict' onto a plain child.
+ *  - Lifecycle (P1.2, ratified 2026-10-29): only a lifecycle table may hold a foreign key into a
+ *    lifecycle table, and the parent declares every such key with a dependent. Soft deletion runs in
+ *    triggers; physical removal follows the declared foreign-key action. A cascade into a lifecycle
+ *    table from a plain parent is refused.
  *  - Neither side wins. Both may declare; agreeing is fine, disagreeing is an error naming both.
  *  - Matched on (target, column): a child's other FKs to the same parent are untouched.
  *  - 'nullify' on a NOT NULL child column is an error (the delete would fail).
@@ -46,11 +47,22 @@ export function lifecycleCascadeHarm(where: string): string {
   return (
     `ON DELETE CASCADE into a lifecycle table is refused. The cascaded delete is turned into a soft delete, `
     + `so the parent row is removed and ${where} still points at it. `
-    + `Use 'restrict' or 'nullify' (onDelete 'restrict' or 'set null') instead; `
+    + `Use 'restrict' or 'nullify' instead (from a plain parent, onDelete 'restrict' or 'set null'; from a lifecycle parent, its hasMany dependent); `
     + `to soft-delete the children with their parent, make the parent lifecycle: true and declare hasMany { dependent: 'cascade' } on it`
   );
 }
 
+/**
+ * A lifecycle parent's hasMany with both a `dependent` and `where`: `where` is display only and never
+ * narrows what a delete does, so the pair reads as a filtered cascade or restrict that does not
+ * exist. Refused on a lifecycle parent; a plain parent keeps accepting it (declarations predate this).
+ */
+export function dependentWhereRefusal(parent: string, relation: string, rel: { dependent?: unknown; where?: unknown }): string | undefined {
+  if (rel.dependent === undefined || rel.where === undefined) return undefined;
+  return `model '${parent}': relation '${relation}' declares dependent '${String(rel.dependent)}' with where: where is display only and never narrows a dependent. `
+    + 'Use an unfiltered dependent and a separate display relation, or drop where.';
+}
+
 /**
  * Validate every dependent in the set and return the actions it implies. Pure: nothing is written.
  * `targetOf` resolves a thunk; linkModels passes one that knows the names it has resolved but not
@@ -72,6 +84,8 @@ export function relationDeleteActions(
         // defineModel refuses these shapes; a hand-edited descriptor still never compiles.
         throw new Error(`${at}, which is not a hasMany 'restrict', 'nullify' or 'cascade'`);
       }
+      const filtered = parent.lifecycle ? dependentWhereRefusal(nameOf(parent), name, rel) : undefined;
+      if (filtered) throw new Error(filtered);
       const child = targetOf(rel.target);
       const where = `${nameOf(child)}.${rel.column}`;
       const f = child.fields[rel.column];
@@ -122,28 +136,10 @@ export function relationDeleteActions(
       if (dependent === 'cascade' && child.lifecycle && !parent.lifecycle) {
         throw new Error(`${at}, but ${where} is in a lifecycle table: ${lifecycleCascadeHarm(where)}`);
       }
-      if (dependent === 'cascade' && parent.lifecycle && !child.lifecycle) {
-        throw new Error(
-          `${at}, but ${where} is not in a lifecycle table. Deleting a lifecycle row is a soft delete, so the parent `
-          + `row stays and its foreign key never fires: ${where} would stay live under a deleted parent. `
-          + `Make '${nameOf(child)}' lifecycle: true (its rows are then soft-deleted with the parent), `
-          + `or use dependent 'restrict' or 'nullify'`,
-        );
-      }
+      if (parent.lifecycle && !child.lifecycle) throw new Error(plainKeyRefusal(`${at}, but ${where}`, nameOf(child), nameOf(parent), '.references()'));
 
-      if (dependent === 'restrict' && parent.lifecycle && !child.lifecycle) {
-        throw new Error(
-          `${at}, but ${where} is not in a lifecycle table. Deleting a lifecycle row is a soft delete, so the foreign key `
-          + `never fires; the restrict check runs in a trigger as the lifecycle role, which holds no rights on a plain table. `
-          + `Make '${nameOf(child)}' lifecycle: true, or use dependent 'nullify'`,
-        );
-      }
-
-      // A lifecycle parent soft-deletes its lifecycle 'cascade' children through triggers
-      // (lifecycle-derived.ts), never through the foreign key: its DELETE never removes the row,
-      // and an RI cascade into a lifecycle table would leave the child pointing at a removed
-      // parent once one is purged. So that foreign key is RESTRICT; the relation keeps 'cascade'.
-      const onDelete: ReferentialAction = dependent === 'cascade' && parent.lifecycle ? 'restrict' : ACTION[dependent];
+      // Soft deletion uses triggers; destroy follows the declared foreign-key action.
+      const onDelete: ReferentialAction = ACTION[dependent];
       const forChild = planned.get(child) ?? new Map();
       const earlier = forChild.get(rel.column);
       if (earlier && earlier.onDelete !== onDelete) {
@@ -162,7 +158,158 @@ export function relationDeleteActions(
       planned.set(child, forChild);
     }
   }
+  assertLifecycleKeysDeclared(models, targetOf);
+  lifecycleDestroyOrder(models, targetOf);
   const out = new Map<ModelDescriptor, ReadonlyMap<string, ReferentialAction>>();
   for (const [child, fields] of planned) out.set(child, new Map([...fields].map(([k, v]) => [k, v.onDelete])));
   return out;
 }
+
+/**
+ * Only a lifecycle table may hold a foreign key into a lifecycle table (ratified 2026-10-29). Soft
+ * delete never removes the parent row, so a plain child's key never fires, and the triggers that
+ * soft-delete, restrict or restore run as the lifecycle role, which holds no rights on a plain
+ * table. A plain table refers to a lifecycle row by value.
+ */
+function plainKeyRefusal(site: string, child: string, parent: string, key: string): string {
+  return `${site} references lifecycle table '${parent}', but '${child}' is not a lifecycle table: only a lifecycle table may hold `
+    + `a foreign key into a lifecycle table. Make '${child}' lifecycle: true (and declare the dependent on '${parent}'), `
+    + `or refer to it by value (drop ${key})`;
+}
+
+const UNDECLARED = 'Soft delete never consults an undeclared key, so destroy would later defer or skip the parent row.';
+
+/**
+ * Every foreign key into a lifecycle table comes from a lifecycle table, and the parent's hasMany
+ * declares it with a dependent (cascade, restrict or nullify): the one way to declare it. Soft
+ * delete decides every consequence; a key nobody declared is a consequence nobody decided.
+ */
+function assertLifecycleKeysDeclared(models: readonly ModelDescriptor[], targetOf: (thunk: () => unknown) => ModelDescriptor): void {
+  // A set with no lifecycle model evaluates no reference thunk (linkModels never needs to).
+  if (!models.some((m) => m.lifecycle === true)) return;
+  for (const child of new Set(models)) {
+    for (const [key, f] of Object.entries(child.fields)) {
+      if (!f.spec.references) continue;
+      const parent = targetOf(f.spec.references);
+      if (parent.lifecycle !== true) continue;
+      const site = `model '${nameOf(child)}': field '${key}'`;
+      if (child.lifecycle !== true) throw new Error(plainKeyRefusal(site, nameOf(child), nameOf(parent), '.references()'));
+      const declared = (Object.values(parent.relations) as Relation[]).some((rel) => rel.kind === 'hasMany'
+        && rel.dependent !== undefined && rel.column === key && targetOf(rel.target) === child);
+      if (declared) continue;
+      throw new Error(
+        `${site} references lifecycle table '${nameOf(parent)}', and '${nameOf(parent)}' declares no dependent `
+        + `for ${nameOf(child)}.${key}. ${UNDECLARED} Declare what deleting a '${nameOf(parent)}' row does to it in '${nameOf(parent)}'s relations: `
+        + `hasMany('${nameOf(child)}', '${key}', { dependent: 'cascade' | 'restrict' | 'nullify' })`,
+      );
+    }
+    for (const c of child.constraints) {
+      if (c.kind !== 'foreignKey' || !c.references) continue;
+      const parent = targetOf(c.references as () => unknown);
+      if (parent.lifecycle !== true) continue;
+      const site = `model '${nameOf(child)}': foreignKey(${c.columns.join(', ')})`;
+      if (child.lifecycle !== true) throw new Error(plainKeyRefusal(site, nameOf(child), nameOf(parent), 'the foreignKey'));
+      throw new Error(
+        `${site} references lifecycle table '${nameOf(parent)}', and a table-level foreignKey cannot carry a dependent. `
+        + `${UNDECLARED} Reference '${nameOf(parent)}'s primary key with a field .references() and declare a hasMany dependent on '${nameOf(parent)}'`,
+      );
+    }
+  }
+}
+
+/**
+ * The child FK columns a lifecycle parent's dependents need indexed, per child model. A property
+ * of the MODEL SET like {@link relationDeleteActions}: pure, nothing written, every reader that
+ * compiles indexes from the set consults it.
+ *
+ * Why: the cascade trigger on a middle table runs one UPDATE on the child per stamped row, the
+ * restrict check counts the child by the FK, and destroy's ON DELETE SET NULL ('nullify') runs
+ * PostgreSQL's referential action by the FK, once per removed parent. Without an index each is a
+ * full scan of the child (measured: a 100k-child delete 15.5 s without, 1.4 s with; a 1,000-parent
+ * destroy over 600k SET NULL children 21.4 s without, 0.6 s with).
+ *
+ * Rules: only a LIFECYCLE parent's hasMany with a dependent; field keys, one column (a dependent
+ * rides a field `.references()`, never a composite foreignKey); skipped when the child already has
+ * a btree index, unique or primary key whose LEADING column is that one (a partial, hash or
+ * expression index does not serve every row); one entry per column however many edges share it;
+ * column lists sorted for a stable result.
+ */
+export type DependentIndexes = ReadonlyMap<ModelDescriptor, ReadonlyArray<readonly string[]>>;
+
+const leads = (columns: readonly string[], fk: readonly string[]): boolean =>
+  fk.length > 0 && fk.every((c, i) => columns[i] === c);
+
+function servedBy(child: ModelDescriptor, fk: readonly string[]): boolean {
+  if (leads(child.primaryKey, fk)) return true;
+  if (fk.length === 1 && child.fields[fk[0]]?.spec.isUnique) return true;
+  return child.constraints.some((c) => {
+    if (c.kind === 'unique') return leads(c.columns, fk);
+    if (c.kind !== 'index') return false;
+    if (c.predicate !== undefined || (c.method !== undefined && c.method !== 'btree')) return false;
+    if (fk.some((_, i) => c.rawPositions?.[i])) return false;
+    return leads(c.columns, fk);
+  });
+}
+
+export function lifecycleDependentIndexes(
+  models: readonly ModelDescriptor[],
+  targetOf: (thunk: () => unknown) => ModelDescriptor = (thunk) => thunk() as ModelDescriptor,
+): DependentIndexes {
+  const out = new Map<ModelDescriptor, string[][]>();
+  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 === undefined) continue;
+      const child = targetOf(rel.target);
+      const fk = [rel.column];
+      if (servedBy(child, fk)) continue;
+      const list = out.get(child) ?? [];
+      if (!list.some((l) => l.join('\u0000') === fk.join('\u0000'))) list.push(fk);
+      out.set(child, list);
+    }
+  }
+  for (const list of out.values()) list.sort((a, b) => a.join('\u0000').localeCompare(b.join('\u0000')));
+  return out;
+}
+
+/**
+ * Lifecycle table names in children-first destroy order over restrict/cascade edges. Ties keep
+ * model-set order; public names are bare and other schemas are qualified. A self-reference is
+ * allowed: a restrict tree converges one level per run. Multi-table cycles cannot be ordered.
+ * `targetOf` lets linkModels check the graph before binding any name references.
+ */
+export function lifecycleDestroyOrder(
+  models: readonly ModelDescriptor[],
+  targetOf: (thunk: () => unknown) => ModelDescriptor = (thunk) => thunk() as ModelDescriptor,
+): string[] {
+  const tables = [...new Set(models)].filter(m => m.lifecycle === true);
+  const children = new Map(tables.map(m => [m, new Set<ModelDescriptor>()]));
+  for (const parent of tables) {
+    for (const rel of Object.values(parent.relations) as Relation[]) {
+      if (rel.kind !== 'hasMany' || (rel.dependent !== 'restrict' && rel.dependent !== 'cascade')) continue;
+      const child = targetOf(rel.target);
+      if (child !== parent && children.has(child)) children.get(parent)!.add(child);
+    }
+  }
+  const visited = new Set<ModelDescriptor>();
+  const path: ModelDescriptor[] = [];
+  const visit = (table: ModelDescriptor): void => {
+    const at = path.indexOf(table);
+    if (at !== -1) throw new Error(`unsupported destroy order: ${[...path.slice(at), table].map(nameOf).join(' -> ')}`);
+    if (visited.has(table)) return;
+    path.push(table);
+    for (const child of children.get(table)!) visit(child);
+    path.pop();
+    visited.add(table);
+  };
+  for (const table of tables) visit(table);
+  const remaining = new Set(tables);
+  const ordered: string[] = [];
+  while (remaining.size) {
+    // Pick the earliest ready table again after each removal, so ties keep their input order.
+    const next = tables.find(m => remaining.has(m) && [...children.get(m)!].every(child => !remaining.has(child)))!;
+    ordered.push(nameOf(next));
+    remaining.delete(next);
+  }
+  return ordered;
+}

package/src/derive.ts

@@ -14,6 +14,7 @@
 
 import type { ModelDescriptor } from './model';
 import type { ModelHooks } from './model';
+import { assertDeleteHookNames, assertDestroyHooks } from './lifecycle-hooks';
 import type { AbilityCondition } from './can';
 import { linkModels } from './link';
 
@@ -68,6 +69,8 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
   const hooks: Record<string, ModelHooks> = {};
 
   for (const model of models) {
+    assertDeleteHookNames(model.table, model.hooks);
+    assertDestroyHooks(model.table, model.hooks, model.lifecycle === true);
     // A private model is generated (schema + authz) but is not a generic-API
     // resource — it contributes nothing to the handler config (no exposedTables
     // entry, no hidden/protected/ownership/relation/hook derivation).

package/src/derived.ts

@@ -391,6 +391,8 @@ export interface FunctionDefinition {
    * exactly as it always has. Strictness by explicitness, never by provenance.
    */
   searchPath?: string[] | 'unpinned';
+  /** Function-scoped PostgreSQL lock_timeout; restored on return. The caller sets statement_timeout. */
+  lockTimeout?: string;
   /** Default `'volatile'` (PostgreSQL's own). `immutable` enables expression indexes. */
   volatility?: 'immutable' | 'stable' | 'volatile';
   dependsOn?: DependsOnRef[];
@@ -440,6 +442,8 @@ export interface FunctionDescriptor {
   owner?: string;
   /** See {@link FunctionDefinition.searchPath}. `'unpinned'` = no `SET search_path`, declared. */
   searchPath?: string[] | 'unpinned';
+  /** Function-scoped PostgreSQL lock_timeout; restored on return. The caller sets statement_timeout. */
+  lockTimeout?: string;
   volatility: 'immutable' | 'stable' | 'volatile';
   dependsOn: DependsOnRef[];
   abilities: Ability[];
@@ -538,6 +542,7 @@ export function defineFunction(name: string, def: FunctionDefinition): FunctionD
     security,
     ...(def.owner ? { owner: def.owner } : {}),
     ...(def.searchPath ? { searchPath: def.searchPath } : {}),
+    ...(def.lockTimeout !== undefined ? { lockTimeout: def.lockTimeout } : {}),
     volatility: def.volatility ?? 'volatile',
     dependsOn: def.dependsOn ?? [],
     abilities: def.abilities ?? [],

package/src/destroy-log.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared provisioning SQL for everystack.destroy_log.
+ *
+ * The table holds one marker row per destroy call in progress, keyed by the transaction id, with the
+ * call's cutoff (p_before). The generated <t>_lifecycle_destroy writes it before it deletes and
+ * removes it before it returns, so the table is empty at rest. While the marker exists,
+ * <t>_lifecycle_destroy_before() returns the cutoff, and a lifecycle DELETE in that transaction
+ * really removes a row only if it is already soft-deleted before the cutoff; any other row raises.
+ * Without it every DELETE is soft, the lifecycle role's included: the marker is the only way to a
+ * real delete.
+ *
+ * No role but the table owner holds a privilege on the table, the lifecycle role included. Consumer
+ * triggers run as the lifecycle role inside a destroy call; a role that could write the table could
+ * delete the call's marker and insert another (the CHECK allows the current transaction), or widen
+ * its cutoff. The lifecycle role reaches the marker only through three SECURITY DEFINER functions the
+ * table owner owns: destroy_log_mark and destroy_log_unmark refuse to run inside a trigger
+ * (pg_trigger_depth() > 0), so only a top-level destroy call can write it; destroy_cutoff only reads.
+ * So <t>_lifecycle_destroy cannot run inside a trigger. Only the lifecycle role may EXECUTE them.
+ */
+/** The marker functions' refusal inside a trigger, as a SQL literal: a destroy call is a top-level statement. */
+const IN_TRIGGER = "'destroy cannot run inside a trigger: call <table>_lifecycle_destroy as a top-level statement, as destroyExpired does'";
+
+/**
+ * The marker functions' bodies, keyed by signature: exactly the text between the $fn$ quotes, so
+ * equal to pg_proc.prosrc of the function provisioning installs. The apply preflight compares them.
+ */
+type MarkerSignature = 'everystack.destroy_log_mark(timestamptz)' | 'everystack.destroy_log_unmark()' | 'everystack.destroy_cutoff()';
+/** The marker functions' language (pg_language.lanname), keyed by signature. */
+export const DESTROY_LOG_MARKER_LANGUAGES: Readonly<Record<MarkerSignature, 'plpgsql' | 'sql'>> = {
+  'everystack.destroy_log_mark(timestamptz)': 'plpgsql',
+  'everystack.destroy_log_unmark()': 'plpgsql',
+  'everystack.destroy_cutoff()': 'sql',
+};
+/** The marker functions' pinned search_path, as written in SET and as pg_proc.proconfig holds it after `search_path=`. */
+export const DESTROY_LOG_MARKER_SEARCH_PATH = 'pg_catalog, pg_temp';
+export const DESTROY_LOG_MARKER_BODIES: Readonly<Record<MarkerSignature, string>> = {
+  'everystack.destroy_log_mark(timestamptz)': `
+    BEGIN
+      IF pg_catalog.pg_trigger_depth() > 0 THEN
+        RAISE EXCEPTION USING ERRCODE = '55000', MESSAGE = ${IN_TRIGGER};
+      END IF;
+      INSERT INTO everystack.destroy_log (xid, before) VALUES (pg_catalog.pg_current_xact_id(), p_before);
+    END
+    `,
+  'everystack.destroy_log_unmark()': `
+    BEGIN
+      IF pg_catalog.pg_trigger_depth() > 0 THEN
+        RAISE EXCEPTION USING ERRCODE = '55000', MESSAGE = ${IN_TRIGGER};
+      END IF;
+      DELETE FROM everystack.destroy_log WHERE xid = pg_catalog.pg_current_xact_id();
+      RETURN FOUND;
+    END
+    `,
+  'everystack.destroy_cutoff()': `
+    SELECT before FROM everystack.destroy_log WHERE xid = pg_catalog.pg_current_xact_id()
+    `,
+};
+
+export const ENSURE_DESTROY_LOG_SQL: string[] = [
+  'CREATE SCHEMA IF NOT EXISTS everystack',
+  // Two older shapes are replaced. An unreleased build kept an append-only audit here (an `event`
+  // column, started/finished rows); an earlier build keyed the marker on xid alone (no `before`).
+  // The table is empty at rest, so a committed row in either is stale: dropping it loses nothing.
+  `DO $old$
+    BEGIN
+      IF EXISTS (SELECT 1 FROM pg_catalog.pg_attribute
+        WHERE attrelid = pg_catalog.to_regclass('everystack.destroy_log') AND attname = 'event' AND NOT attisdropped) THEN
+        DROP TABLE everystack.destroy_log;
+        DROP FUNCTION IF EXISTS everystack.destroy_log_refuse_mutation();
+      ELSIF pg_catalog.to_regclass('everystack.destroy_log') IS NOT NULL AND NOT EXISTS (SELECT 1 FROM pg_catalog.pg_attribute
+        WHERE attrelid = pg_catalog.to_regclass('everystack.destroy_log') AND attname = 'before' AND NOT attisdropped) THEN
+        DROP TABLE everystack.destroy_log;
+      END IF;
+    END
+    $old$`,
+  // A marker can only name the transaction that writes it, so nothing running as the lifecycle role
+  // (a consumer trigger inside a destroy) can leave one that turns a later transaction's deletes hard.
+  // `before` is the call's cutoff: only a row soft-deleted before it may be removed for real.
+  `CREATE TABLE IF NOT EXISTS everystack.destroy_log (
+    xid xid8 PRIMARY KEY,
+    before timestamptz NOT NULL,
+    CONSTRAINT destroy_log_current_xact CHECK (xid = pg_catalog.pg_current_xact_id())
+  )`,
+  `DO $check$
+    BEGIN
+      IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_constraint
+        WHERE conrelid = 'everystack.destroy_log'::regclass AND conname = 'destroy_log_current_xact') THEN
+        ALTER TABLE everystack.destroy_log
+          ADD CONSTRAINT destroy_log_current_xact CHECK (xid = pg_catalog.pg_current_xact_id()) NOT VALID;
+      END IF;
+    END
+    $check$`,
+  // Empty at rest: a committed row is stale or forged. A call in flight holds an uncommitted row this
+  // DELETE cannot see, so it is left alone. Then the check holds for every row and can be validated.
+  'DELETE FROM everystack.destroy_log',
+  'ALTER TABLE everystack.destroy_log VALIDATE CONSTRAINT destroy_log_current_xact',
+  'REVOKE ALL PRIVILEGES ON TABLE everystack.destroy_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.destroy_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.destroy_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.destroy_log'::regclass
+        )
+      LOOP
+        EXECUTE pg_catalog.format('REVOKE ALL PRIVILEGES ON TABLE everystack.destroy_log FROM %I', r.rolname);
+        EXECUTE pg_catalog.format('REVOKE ALL PRIVILEGES (xid, before) ON TABLE everystack.destroy_log FROM %I', r.rolname);
+      END LOOP;
+    END
+    $acl$`,
+  'REVOKE ALL PRIVILEGES (xid, before) ON TABLE everystack.destroy_log FROM PUBLIC',
+  'GRANT USAGE ON SCHEMA everystack TO everystack_lifecycle',
+  // The only writers. pg_trigger_depth() counts every trigger level, the ON DELETE CASCADE key's
+  // included, so a consumer trigger anywhere inside a destroy call is refused.
+  `CREATE OR REPLACE FUNCTION everystack.destroy_log_mark(p_before timestamptz) RETURNS void
+    LANGUAGE ${DESTROY_LOG_MARKER_LANGUAGES['everystack.destroy_log_mark(timestamptz)']} SECURITY DEFINER SET search_path = ${DESTROY_LOG_MARKER_SEARCH_PATH} AS $fn$${DESTROY_LOG_MARKER_BODIES['everystack.destroy_log_mark(timestamptz)']}$fn$`,
+  `CREATE OR REPLACE FUNCTION everystack.destroy_log_unmark() RETURNS boolean
+    LANGUAGE ${DESTROY_LOG_MARKER_LANGUAGES['everystack.destroy_log_unmark()']} SECURITY DEFINER SET search_path = ${DESTROY_LOG_MARKER_SEARCH_PATH} AS $fn$${DESTROY_LOG_MARKER_BODIES['everystack.destroy_log_unmark()']}$fn$`,
+  // The cutoff of this transaction's destroy call, NULL without one. Read at any trigger depth.
+  `CREATE OR REPLACE FUNCTION everystack.destroy_cutoff() RETURNS timestamptz
+    LANGUAGE ${DESTROY_LOG_MARKER_LANGUAGES['everystack.destroy_cutoff()']} STABLE SECURITY DEFINER SET search_path = ${DESTROY_LOG_MARKER_SEARCH_PATH} AS $fn$${DESTROY_LOG_MARKER_BODIES['everystack.destroy_cutoff()']}$fn$`,
+  // EXECUTE for the lifecycle role alone, without grant option: every other grant is revoked.
+  `DO $exec$
+    DECLARE f regprocedure; r record;
+    BEGIN
+      FOREACH f IN ARRAY ARRAY['everystack.destroy_log_mark(timestamptz)', 'everystack.destroy_log_unmark()', 'everystack.destroy_cutoff()']::regprocedure[] LOOP
+        EXECUTE pg_catalog.format('REVOKE ALL PRIVILEGES ON FUNCTION %s FROM PUBLIC', f);
+        FOR r IN
+          SELECT DISTINCT roles.rolname
+          FROM pg_catalog.pg_proc p CROSS JOIN LATERAL pg_catalog.aclexplode(p.proacl) acl
+          JOIN pg_catalog.pg_roles roles ON roles.oid = acl.grantee
+          WHERE p.oid = f AND acl.grantee <> p.proowner
+        LOOP
+          EXECUTE pg_catalog.format('REVOKE ALL PRIVILEGES ON FUNCTION %s FROM %I', f, r.rolname);
+        END LOOP;
+      END LOOP;
+    END
+    $exec$`,
+  'GRANT EXECUTE ON FUNCTION everystack.destroy_log_mark(timestamptz), everystack.destroy_log_unmark(), everystack.destroy_cutoff() TO everystack_lifecycle',
+];

package/src/index.ts

@@ -10,7 +10,7 @@
 export { field, FieldBuilder } from './field';
 export type { FieldSpec, FieldType, DefaultKind, ReferentialAction } from './field';
 
-export { canonicalColumnType, fieldFactoryCall, pgTypeRefusal } from './pg-type';
+export { canonicalColumnType, fieldFactoryCall, pgTypeRefusal, pgType } from './pg-type';
 
 export { parseQualified } from './qualified';
 export { linkModels, ModelLinkError } from './link';
@@ -29,11 +29,12 @@ export type { Ability, AbilityCondition, Action } from './can';
 
 export { belongsTo, hasMany, hasOne } from './relations';
 export type { Relation, BelongsToOptions, HasManyOptions, HasOneOptions, HasManyDependent, RelationOrder, RelationWhere } from './relations';
-export { relationDeleteActions } from './dependents';
-export type { DependentActions } from './dependents';
+export { relationDeleteActions, lifecycleDependentIndexes, lifecycleDestroyOrder } from './dependents';
+export type { DependentActions, DependentIndexes } from './dependents';
 
+export { veto, isVeto } from './lifecycle-hooks';
 export { defineModel, defineMaterializedTable, LIFECYCLE_COLUMNS, LIFECYCLE_OWNER_ROLE, EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './model';
-export type { ModelDescriptor, ModelDefinition, ModelHooks, DestroyContext, DestroyHook, WrittenBy, ExtraPrivilege, TablePrivilege, DmlPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, LifecycleOptions, DestroyContext, DestroyHook, LifecycleContext, HookVeto, BeforeLifecycleHook, AfterLifecycleHook, WrittenBy, ExtraPrivilege, TablePrivilege, DmlPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
 export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
 export type { Module, ModuleDefinition } from './module';
@@ -53,3 +54,5 @@ export type {
 
 export { deriveHandlerConfig, deriveForceRlsCarveouts, deriveFunctionSchemas } from './derive';
 export type { DerivedHandlerConfig, RelationConfig } from './derive';
+
+export { ENSURE_DESTROY_LOG_SQL, DESTROY_LOG_MARKER_BODIES, DESTROY_LOG_MARKER_LANGUAGES, DESTROY_LOG_MARKER_SEARCH_PATH } from './destroy-log';

package/src/lifecycle-hooks.ts

@@ -0,0 +1,70 @@
+/**
+ * The lifecycle hook contract, shared by the model, the API handler and destroy workers.
+ * `@everystack/api` carries a structurally identical copy (it has no runtime dependencies);
+ * a veto made by either package is recognized by both.
+ */
+
+const VETO_KIND = 'everystack.hookVeto';
+
+/** What a before hook returns to refuse its operation. Make it with {@link veto}. */
+export interface HookVeto {
+  readonly kind: typeof VETO_KIND;
+  readonly reason: string;
+}
+
+/** Refuse the operation a before hook guards. A throw is a failure; a veto is a decision. */
+export function veto(reason: string): HookVeto {
+  if (typeof reason !== 'string' || reason.trim() === '') throw new TypeError('veto(reason) needs a non-empty reason string');
+  return Object.freeze({ kind: VETO_KIND, reason });
+}
+
+/** True only for a value {@link veto} made (or its twin in `@everystack/api`). */
+export function isVeto(value: unknown): value is HookVeto {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && (value as { kind?: unknown }).kind === VETO_KIND && typeof (value as { reason?: unknown }).reason === 'string';
+}
+
+/** The one context every lifecycle hook receives. */
+export interface LifecycleContext {
+  /** `delete`: a request-level delete. `restore`: a batch came back. `destroy`: physical removal. */
+  phase: 'delete' | 'restore' | 'destroy';
+  /** Request-level deletes use null. Restore and destroy can carry the row's existing batch. */
+  batch: string | null;
+  user: Record<string, unknown> | null;
+  client: Record<string, unknown> | null;
+  /** Restore only: what the restore function reported. */
+  counts?: { restored: number; skipped: number };
+}
+
+/** Context for a real removal. Hooks must be idempotent: retries can repeat external effects. */
+export interface DestroyContext extends LifecycleContext {
+  phase: 'destroy';
+}
+
+/** beforeDestroy may return {@link veto}; afterDestroy's return value is ignored. */
+export type DestroyHook = (row: Record<string, unknown>, ctx: DestroyContext) => void | HookVeto | Promise<void | HookVeto>;
+
+/** Before commit, once per matched root row; returns nothing or a veto. Cascaded children run no hook: guard them with deleteWhen. */
+export type BeforeLifecycleHook = (row: Record<string, unknown>, ctx: LifecycleContext) => void | HookVeto | Promise<void | HookVeto>;
+
+/** After commit, once per request with the root rows. Best-effort; cascaded children run no hook. */
+export type AfterLifecycleHook = (rows: Record<string, unknown>[], ctx: LifecycleContext) => void | Promise<void>;
+
+/** Refuse removed hook names before a declaration can silently lose its guard. */
+export function assertDeleteHookNames(table: string, hooks: object | undefined): void {
+  for (const [oldName, replacement] of [['beforeStamp', 'beforeDelete'], ['afterStamp', 'afterDelete']]) {
+    if ((hooks as Record<string, unknown> | undefined)?.[oldName] !== undefined) {
+      throw new Error(`[everystack/model] hooks.${table}.${oldName} was renamed to ${replacement}; update the hook name`);
+    }
+  }
+}
+
+/** Refuse destroy hooks that would never run on a table without lifecycle. */
+export function assertDestroyHooks(table: string, hooks: object | undefined, lifecycle: boolean): void {
+  if (lifecycle) return;
+  for (const name of ['beforeDestroy', 'afterDestroy']) {
+    if ((hooks as Record<string, unknown> | undefined)?.[name] !== undefined) {
+      throw new Error(`[everystack/model] hooks.${table}.${name} runs only when a lifecycle table is destroyed, and ${table} is not a lifecycle table. Use beforeDelete or afterDelete, which run at the DELETE`);
+    }
+  }
+}