@everystack/model 0.4.23 → 0.4.24

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [Unreleased]
+
+### Documentation
+
+- verify a built database with compileDeclaredState, not a per-model compileTableSchema loop
+
+## [0.4.24] - 2026-10-23
+
+### BREAKING CHANGES
+
+- lifecycle: { deleteWhen } refuses deleting a row its predicate does not allow
+- refuse dependent + where on a lifecycle parent's hasMany
+- can('read', { role, deleted: 'include' | 'only' }) on a lifecycle model
+- one lifecycle hook API: (rows, ctx), veto(reason), beforeStamp
+- refuse can('read', { deleted }) for anon, authenticated and public
+
+### Added
+
+- index the FK column of every lifecycle dependent
+
+### Documentation
+
+- what a lifecycle delete returns, plain children, vetoing a delete, the purge executor, the caching note
+- lifecycle dependents' FK columns are indexed by the generator; what a pull without dependents plans
+- measure what the lifecycle read guard costs a non-leakproof index search
+- can('read', { role, deleted }) as the read hatch for a lifecycle index search
+- Extending lifecycle, the phase table, the veto and failure rules
+- the keyed lifecycle DELETE, before-hook pool hazard, batch as a hint, deleted-reader grants, FK index drops
+
 ## [0.4.23] - 2026-10-23
 
 ### Added

package/README.md

@@ -219,6 +219,9 @@ A string third argument is `references`, the key on the other side when it is no
 | `'nullify'`  | `ON DELETE SET NULL`              |
 | `'cascade'`  | `ON DELETE CASCADE`               |
 
+On a lifecycle parent the generator also indexes the child's foreign-key column for `'cascade'`, `'restrict'` and `'nullify'`; an index you declare with that column leading is used instead.
+Dropping a generated index is destructive (`--allow-drops` on `db:sync`, `--confirm` on `db:apply`, refused on `db:apply --stage`): it happens when you remove the dependent, make the parent non-lifecycle, or add your own index that leads with the foreign-key column after the generated one was applied.
+
 ```typescript
 const Post = defineModel('posts', {
   fields: { id: field.uuid().primaryKey() },
@@ -245,7 +248,7 @@ The foreign key belongs to the child table, so the action lands there: in the pl
 - Any other value (for example `'softDelete'`) is refused by name.
 - `belongsTo` takes no `dependent`. A `hasMany` with no `dependent` is display only and compiles exactly as before.
 
-`db:pull` renders the action on the child (`.references(() => Post, { onDelete: 'set null' })`) and no `dependent` on the parent; that agrees with a parent that declares one, so pull then plan is empty.
+`db:pull` renders the action on the child (`.references(() => Post, { onDelete: 'set null' })`) and no `dependent` on the parent; that agrees with a parent that declares one, so pull then plan is empty. A lifecycle parent is the exception: without its `dependent` declarations the generated foreign-key indexes are no longer declared, so `db:plan` refuses their drops as destructive until you declare the `dependent` again.
 
 ### Lifecycle
 
@@ -290,6 +293,31 @@ Cascade and restrict from a lifecycle parent require lifecycle children. Nullify
 An actual `ON DELETE CASCADE` into a lifecycle table is refused. Plain-table cascades still remove rows without
 running app hooks. `dependent: 'destroy'` has not shipped.
 AFTER DELETE audit triggers are supported; they do not run on a soft deletion.
+
+#### Refusing some deletes: `deleteWhen`
+
+`lifecycle: { deleteWhen: sql\`<predicate>\` }` is lifecycle with a guard: a row may be deleted only when the predicate
+is TRUE for it. FALSE refuses, and so does NULL. The predicate uses bare column names, like a policy predicate:
+
+```typescript
+const List = defineModel('lists', {
+  lifecycle: { deleteWhen: sql`NOT (kind = 'system' AND private)` },
+  fields: { id: field.integer().primaryKey(), kind: field.text().notNull(), private: field.boolean().notNull() },
+  abilities: [can('manage', { role: 'admin' })],
+});
+```
+
+A refused delete raises SQLSTATE `23514` with the constraint `<table>_lifecycle_delete_when` and a message that names
+the table, never a row value; the API answers `422` with `"Deleting this row is not allowed by its model's deleteWhen."`.
+The guard checks every stamp, direct or cascaded, so one guarded child refuses its parent's whole delete and nothing is
+stamped, as `restrict` does. A DELETE of several rows is refused as a whole when any one is guarded. `lifecycle: {}`
+is `lifecycle: true`. Purge removes a row only while the predicate still holds: a row whose columns changed after its
+stamp stays, with a `skipped` receipt (`protected by deleteWhen`) and no retry cooldown. The predicate runs as the
+reserved lifecycle role with a pinned `search_path`, so qualify any function of your own it calls.
+For logic a predicate cannot express, a `beforeStamp` hook can `veto(reason)` a root row's stamp through the API
+([Extending lifecycle](../../docs/handler.md#extending-lifecycle)); the `BEFORE UPDATE` veto trigger in docs/upgrading.md
+remains the last resort, the one that also sees direct SQL and cascades.
+There is no option to require an actor on a stamp: use a veto trigger, or require authentication on DELETE.
 `db:pull` refuses author BEFORE DELETE triggers on lifecycle tables because they can suppress purge DELETE.
 It also refuses TRUNCATE triggers because TRUNCATE bypasses lifecycle row removal.
 
@@ -305,13 +333,62 @@ The API process is fully trusted. SQL on its connection can rewrite the request
 `deleted_by` is attribution, not proof. Lifecycle graph operations require READ COMMITTED;
 an earlier snapshot can miss a related row committed since it began.
 
+### Lifecycle and indexes
+
+Every SELECT policy on a lifecycle table carries the guard `(deleted_at IS NULL)`, except the lifecycle role's own and a
+`manage` ALL policy. PostgreSQL evaluates a policy qual before any of the query's own conditions whose operator function
+is not `leakproof`, so such a condition cannot be an index condition below it. Measured on PostgreSQL 16, 100k and 500k
+rows, one read per operator (`scripts/bench/lifecycle-read-guard.py`), generic and custom plans alike:
+
+| operator (function) | leakproof | read whose policy was `true` | with the guard |
+| --- | --- | --- | --- |
+| `slug = $1` (`texteq`), `id = ANY($1)` (`int4eq`) | yes | index condition | index condition, unchanged |
+| `tags @> $1` (`arraycontains`) | no | GIN, 1.7 ms at 500k | sequential scan, 41.8 ms |
+| `meta @> $1` (`jsonb_contains`) | no | GIN, 1.0 ms at 500k | sequential scan, 44.6 ms |
+| `title ILIKE $1` (`texticlike`, trigram) | no | GIN, 1.0 ms at 500k | sequential scan, 92.8 ms |
+| `body_tsv @@ $1` (`ts_match_vq`) | no | GIN, 1.0 ms at 500k | sequential scan, 36.4 ms |
+
+At 100k the same four went from 100 to 300 buffers to about 2,700 (0.15 to 0.7 ms to 12 to 48 ms).
+Only a read whose policy was `true` before lifecycle regresses (a public read, or a role read with no condition).
+A read that already had its own condition (an owner or `sql` read) used a sequential scan for these operators
+before lifecycle too, so the guard changes nothing there. A partial index `WHERE deleted_at IS NULL` did not help.
+A role whose policy has no guard keeps the index.
+
+For a hot search over a lifecycle table with one of those operators, give the search a role whose read has no guard
+and filter deleted rows yourself:
+
+```typescript
+abilities: [
+  can('read'),                                           // guarded: live rows only
+  can('read', { role: 'lookup_role', deleted: 'include' }), // no guard: live and deleted rows, index usable
+  can('read', { role: 'trash_role', deleted: 'only' }),     // (deleted_at IS NOT NULL): a trash view
+]
+```
+
+`deleted` works only on `can('read', { role })` of a lifecycle model and changes only that role's read policy; its
+`sql`, `where` and `columns` still apply. `'include'` means the role's queries must add `deleted_at IS NULL`
+themselves when they want live rows (a leakproof `IS NULL` costs nothing). A role cannot have both a guarded read and
+a `deleted` read: they would compile to the same policy, and `defineModel`'s compile refuses that. A column read may
+list `deletedAt` (every reader sees it); `deletedBy`, `deletedBatch` and `deletedXid` stay unlistable.
+`deleted` is for a named internal role: `defineModel` refuses it for `anon`, `authenticated` and `public`.
+A `deleted` read with no `columns` is granted SELECT on every column except `deleted_by`, `deleted_batch` and
+`deleted_xid`, not the whole table, so the role cannot read who deleted a row, even with plain SQL. A role that must see
+who deleted uses `manage`; a `manage` or a `privileges` SELECT for the same role grants the whole table.
+`db:plan` says `⚠ ACCESS — role <r> can read deleted rows of <table>` when it adds or changes such a policy.
+Where the searching role is shared with other reads, use a `SECURITY DEFINER` lookup function owned by such a role,
+whose body adds `deleted_at IS NULL` itself, schema-qualifies every table, pins `search_path`, and is granted EXECUTE
+only to the roles that may search.
+
 ### Purge
 
 Import `purgeExpired` and `ENSURE_PURGE_LOG_SQL` from `@everystack/server/purge`.
 On the trusted owner connection, run the ensure statements before the first purge.
 Pass the ops Drizzle database, the full linked model set, and `{ after, batch }`.
 `after` is positive retention in milliseconds; `batch` bounds the rows physically removed across all tables.
-The executor must read those tables and the ledger, and be allowed to SET ROLE to `everystack_lifecycle`.
+The executor must read those tables and the ledger, and be allowed to SET ROLE to `everystack_lifecycle`
+(membership in that role; no verb grants it yet, so `GRANT everystack_lifecycle TO <ops role>` by hand).
+The DELETE and the ledger INSERT run as `everystack_lifecycle` with that role's own grants. A lockdown that
+revokes DELETE from other roles must leave this role's DELETE on the lifecycle tables alone.
 This is trusted server code, not a client RPC capability.
 
 Purge checks the live FK graph against the declaration, then visits lifecycle children before parents.
@@ -338,10 +415,14 @@ The example's account-erasure cron remains paused.
 
 `hooks.beforeDestroy(row, ctx)` and `hooks.afterDestroy(row, ctx)` describe physical removal.
 `beforeDestroy` runs only for rows whose DELETE succeeded at statement level, inside the transaction with the removed row's data.
-A throw cancels that removal. A successful beforeDestroy can repeat if later work rolls back the removal or commit fails.
+A throw cancels that removal and is a failure (a `failed` receipt, retry cooldown). `return veto(reason)` cancels it as a
+decision: a `skipped` receipt with detail `held: <reason>` and no cooldown, so the next run asks again.
+A successful beforeDestroy can repeat if later work rolls back the removal or commit fails.
 Purge checks its reserved-role DELETE and deferred constraints before the hook, which runs under the original caller's role.
-Purge passes `{ source: 'purge', user: null, client: null }`; hooks that authorize on `ctx.user` must handle that null user.
-The API passes `{ source: 'api', user, client }` after a hard DELETE returns the authorized rows, before commit.
+Purge passes `{ phase: 'destroy', source: 'purge', batch: <deleted_batch>, user: null, client: null }`; hooks that authorize on `ctx.user` must handle that null user.
+The API passes `{ phase: 'destroy', source: 'api', batch: null, user, client }` after a hard DELETE returns the authorized rows, before commit.
+`veto`, `isVeto`, `HookVeto` and `LifecycleContext` are exported here and from `@everystack/server/purge`. All lifecycle
+hooks (`beforeStamp`, `afterStamp`, `afterRestore`, the destroy pair) are in [Extending lifecycle](../../docs/handler.md#extending-lifecycle).
 A driver without transactions refuses API hard DELETE on a table with a destroy hook: `db.transaction is not a function`.
 `afterDestroy` runs once per removed row after commit, best-effort; process death in between can prevent delivery.
 Irreversible external effects belong in `afterDestroy`. Make them idempotent; no transaction is passed to either hook.
@@ -349,7 +430,7 @@ Existing `beforeDelete` and `afterDelete` remain API request hooks, including on
 
 ### Display options: `orderBy`, `limit`, `where`, and `hasOne`
 
-These say which related rows a reader sees, and in what order. They are **display only**: they emit no SQL, do not move the fingerprint, and never narrow a `dependent`. A `hasMany` with `dependent: 'nullify'` and `where: { approved: true }` still sets `post_id` to NULL on every comment, approved or not.
+These say which related rows a reader sees, and in what order. They are **display only**: they emit no SQL, do not move the fingerprint, and never narrow a `dependent`. A `hasMany` with `dependent: 'nullify'` and `where: { approved: true }` still sets `post_id` to NULL on every comment, approved or not. On a lifecycle parent that combination is refused, because it reads as a filtered cascade that does not exist: declare the `dependent` on an unfiltered relation and keep `where` on a separate display relation.
 
 ```typescript
 const Post = defineModel('posts', {
@@ -405,12 +486,13 @@ The same compiler the CLI uses is importable for your own CI and tests — point
 ```typescript
 import {
   compileMigration, generateMigrationSql, introspectSchema, diffSchema,   // data layer
+  compileDeclaredState,                                                     // the declared state of the set
   compileTableContract, introspectContract, diffContracts,                 // authz layer
   buildOwnerProbeSql, evaluateOwnerProbe,                                   // owner-isolation red-team
 } from '@everystack/cli/model';
 ```
 
-- **Data** — `introspectSchema(run)` reads the whole DB; `diffSchema(desired, current)` / `generateMigrationSql(models, current)` produce the structural delta. A green `db:generate` is this returning empty.
+- **Data** — `introspectSchema(run)` reads the whole DB; `diffSchema(desired, current)` / `generateMigrationSql(models, current)` produce the structural delta. A green `db:generate` is this returning empty. For `desired`, use `compileDeclaredState(models, { schema }).snapshot`, not a `compileTableSchema` call per Model: the set derives parts no one Model carries (the hasMany `ON DELETE`, the generated lifecycle FK indexes), and a per-Model loop reads those live objects as drops.
 - **Authz** — `compileTableContract(model)` is the declared RLS/grants; `introspectContract(run)` is what's live; `diffContracts(declared, live)` is the drift audit (`db:authz:diff`).
 - **Red-team** — `buildOwnerProbeSql` / `evaluateOwnerProbe` drive two JWT identities per owner-scoped table to catch IDOR (`db:authz:owner`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.23",
+  "version": "0.4.24",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/can.ts

@@ -81,6 +81,14 @@ export interface AbilityCondition {
   where?: unknown;
   /** Escape hatch: a verbatim RLS predicate, preserved and diffed by normalized text. */
   sql?: unknown;
+  /**
+   * Lifecycle models only, on `can('read', { role })`: which rows this role's SELECT policy covers
+   * by deletion state. `'include'` drops the `(deleted_at IS NULL)` guard (live and deleted rows);
+   * `'only'` replaces it with `(deleted_at IS NOT NULL)` (deleted rows only). Omitted, the guard
+   * stays. Every other restriction of the ability (`sql`, `where`, `owner`, `columns`) still applies.
+   * The same words as the request-time `?deleted=include|only`.
+   */
+  deleted?: 'include' | 'only';
   /**
    * The WRITE predicate, when it differs from the read predicate.
    *

package/src/dependents.ts

@@ -51,6 +51,17 @@ export function lifecycleCascadeHarm(where: string): string {
   );
 }
 
+/**
+ * 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 +83,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];
@@ -166,3 +179,58 @@ export function relationDeleteActions(
   for (const [child, fields] of planned) out.set(child, new Map([...fields].map(([k, v]) => [k, v.onDelete])));
   return out;
 }
+
+/**
+ * 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 purge'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
+ * purge 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;
+}

package/src/index.ts

@@ -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 } 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';

package/src/lifecycle-hooks.ts

@@ -0,0 +1,53 @@
+/**
+ * The lifecycle hook contract, shared by the model, the API handler and purge.
+ * `@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 {
+  /** `stamp`: the row was marked deleted. `restore`: a batch came back. `destroy`: physical removal. */
+  phase: 'stamp' | 'restore' | 'destroy';
+  /** `api`: a request through createHandler. `purge`: purgeExpired. */
+  source: 'api' | 'purge';
+  /** The lifecycle batch, or null when there is none to report (before a stamp, a non-lifecycle table, a pre-batch row). Never invented. */
+  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>;
+
+/** A before hook of the lifecycle: called once per root row; returns nothing or a veto. */
+export type BeforeLifecycleHook = (row: Record<string, unknown>, ctx: LifecycleContext) => void | HookVeto | Promise<void | HookVeto>;
+
+/** An after hook of the lifecycle: called after commit with the root rows of one batch. Best-effort. */
+export type AfterLifecycleHook = (rows: Record<string, unknown>[], ctx: LifecycleContext) => void | Promise<void>;

package/src/model.ts

@@ -1,3 +1,4 @@
+import { dependentWhereRefusal } from './dependents';
 /**
  * `defineModel` — Layer 2. One call colocates everything about a table: its
  * fields, its authorization (`abilities`), its mutation hooks, and its relations.
@@ -22,20 +23,14 @@ import type { RawSql } from './raw-sql';
 import { validateTriggersFor, type TriggerSpec, type DependsOnRef } from './derived';
 import { TABLE_PRIVILEGES, type TablePrivilege } from './privileges';
 
+import type { AfterLifecycleHook, BeforeLifecycleHook, DestroyHook } from './lifecycle-hooks';
+export type { AfterLifecycleHook, BeforeLifecycleHook, DestroyContext, DestroyHook, HookVeto, LifecycleContext } from './lifecycle-hooks';
+
 /**
  * Per-table mutation hooks. Imperative function bodies the framework cannot
  * absorb (purge an S3 object on delete, stamp a column on create) — held
  * verbatim and passed through to the handler's `hooks`.
  */
-/** Context for a real removal. Hooks must be idempotent: retries can repeat external effects. */
-export interface DestroyContext {
-  source: 'purge' | 'api';
-  user: Record<string, unknown> | null;
-  client: Record<string, unknown> | null;
-}
-
-export type DestroyHook = (row: Record<string, unknown>, ctx: DestroyContext) => void | Promise<void>;
-
 export interface ModelHooks {
   beforeCreate?: (...args: any[]) => any;
   afterCreate?: (...args: any[]) => any;
@@ -50,6 +45,15 @@ export interface ModelHooks {
   /** Runs after commit, best-effort. Cannot undo the removal. Must be idempotent.
    * Treat the row as read-only: it is the same object later serialized into the response. */
   afterDestroy?: DestroyHook;
+  /** Lifecycle tables: before the API DELETE stamps, once per matched root row, inside its transaction.
+   * Return `veto(reason)` to refuse the whole request (409). Cascaded children run no hook: guard them with `deleteWhen`. */
+  beforeStamp?: BeforeLifecycleHook;
+  /** Lifecycle tables: after a stamping DELETE commits, once per batch, with that batch's root rows. Best-effort. */
+  afterStamp?: AfterLifecycleHook;
+  /** Lifecycle tables: after `POST {table}/restore` commits, with `[{ <key>: id }]`, the batch and the counts. Best-effort. */
+  afterRestore?: AfterLifecycleHook;
+  /** Reserved for a future release; createHandler refuses it. */
+  beforeRestore?: never;
 }
 
 /**
@@ -137,9 +141,13 @@ export interface ModelDefinition {
    * ({@link LIFECYCLE_COLUMNS}): `deletedAt` timestamptz, `deletedBy` text (no foreign key),
    * `deletedBatch` uuid, `deletedXid` bigint. The author never declares them, never combines
    * lifecycle with `softDelete`, and declares a single-column primary key; each is refused here.
-   * `true` is the only value today.
+   *
+   * `{ deleteWhen: sql\`<predicate>\` }` is lifecycle too, with a guard: a row may be stamped
+   * deleted only when the predicate is TRUE for it (FALSE or NULL refuses, SQLSTATE 23514), whether
+   * the delete is the row's own or a parent's cascade. Bare column names, like a policy predicate.
+   * Purge keeps the row (a `skipped` receipt) when the predicate no longer holds. `{}` is `true`.
    */
-  lifecycle?: true;
+  lifecycle?: true | LifecycleOptions;
   /**
    * The Postgres schema the table lives in. Default `'public'`. Package-owned
    * tables declare their own (`'dist'`, `'ops'`, `'auth'`) so one db:generate run
@@ -220,8 +228,11 @@ export interface ModelDescriptor {
   privileges: Record<string, TablePrivilege[]>;
   /** `true` excludes `deleted_at IS NULL` rows from public reads and the data API. Declared, never inferred. */
   softDelete: boolean;
-  /** Present only when declared: `fields` carries the generated {@link LIFECYCLE_COLUMNS}. */
+  /** Present only when declared: `fields` carries the generated {@link LIFECYCLE_COLUMNS}. Always
+   *  `true` on the descriptor, whichever form the definition used. */
   lifecycle?: true;
+  /** `lifecycle: { deleteWhen }`'s predicate text. Absent when there is no guard. */
+  deleteWhen?: string;
   /** The resolved Postgres schema (default `'public'`). Package tables live in their own. */
   schema: string;
   /** `true` removes the table from the generic data API (not in `exposedTables`). Default `false`. */
@@ -307,14 +318,40 @@ function lifecycleFields(): Record<(typeof LIFECYCLE_COLUMNS)[number], FieldBuil
   };
 }
 
+/** `lifecycle: { … }` options. */
+export interface LifecycleOptions {
+  /** A row may be stamped deleted only when this is TRUE for it; FALSE or NULL refuses. */
+  deleteWhen?: RawSql;
+}
+
+/** True for `lifecycle: true` and for `lifecycle: { … }` (validated by assertLifecycle). */
+function isLifecycle(def: ModelDefinition): boolean {
+  return def.lifecycle === true || (typeof def.lifecycle === 'object' && def.lifecycle !== null);
+}
+
+/** The guard predicate text, or undefined. Call after assertLifecycle. */
+function deleteWhenOf(def: ModelDefinition): string | undefined {
+  const value = def.lifecycle;
+  return typeof value === 'object' && value !== null && value.deleteWhen !== undefined ? value.deleteWhen.sql : undefined;
+}
+
 function assertLifecycle(table: string, def: ModelDefinition): void {
   const value: unknown = def.lifecycle;
   if (value === undefined) return;
   if (value === false) {
     throw new Error(`model '${table}': lifecycle: false is not supported yet. Omit the key for a model without lifecycle.`);
   }
-  if (value !== true) {
-    throw new Error(`model '${table}': lifecycle: ${JSON.stringify(value)} — the only value is lifecycle: true.`);
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const unknown = Object.keys(value).filter((k) => k !== 'deleteWhen');
+    if (unknown.length > 0) {
+      throw new Error(`model '${table}': lifecycle: { ${unknown.join(', ')} } — the only key is deleteWhen (lifecycle: { deleteWhen: sql\`…\` }).`);
+    }
+    const when = (value as { deleteWhen?: unknown }).deleteWhen;
+    if (when !== undefined && !(typeof when === 'object' && when !== null && typeof (when as RawSql).sql === 'string' && (when as RawSql).sql.trim() !== '')) {
+      throw new Error(`model '${table}': lifecycle: { deleteWhen } — deleteWhen must be sql\`…\`, a non-empty predicate over this table's columns.`);
+    }
+  } else if (value !== true) {
+    throw new Error(`model '${table}': lifecycle: ${JSON.stringify(value)} — the only values are lifecycle: true and lifecycle: { deleteWhen: sql\`…\` }.`);
   }
   if (def.softDelete !== undefined) {
     throw new Error(
@@ -378,7 +415,7 @@ function assertLifecycle(table: string, def: ModelDefinition): void {
  * the login, not the caller. TRUNCATE is refused because it skips the delete triggers.
  */
 function assertLifecycleRestoreSafe(table: string, def: ModelDefinition): void {
-  if (def.lifecycle !== true) return;
+  if (!isLifecycle(def)) return;
   const why = 'restore runs the delete rule inside a SECURITY DEFINER function as the lifecycle owner';
   const abilities = def.abilities ?? [];
   // A role-less (or authenticated) delete on a model scoped only through `via` compiles to the
@@ -434,7 +471,8 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
   assertRoleNotReserved(table, def);
   assertLifecycle(table, def);
   assertLifecycleRestoreSafe(table, def);
-  const lifecycle = def.lifecycle === true;
+  const lifecycle = isLifecycle(def);
+  const deleteWhen = deleteWhenOf(def);
   const fields: Record<string, FieldBuilder> = lifecycle ? { ...def.fields, ...lifecycleFields() } : def.fields;
 
   for (const [name, field] of Object.entries(def.fields)) {
@@ -443,6 +481,8 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
   for (const [name, relation] of Object.entries(def.relations ?? {})) {
     assertRelationShape(def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table, name, relation);
     referenceLocation(relation.target, `${table}.${name}`);
+    const filtered = lifecycle ? dependentWhereRefusal(def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table, name, relation) : undefined;
+    if (filtered) throw new Error(filtered);
   }
   const primaryKey = Object.entries(def.fields)
     .filter(([, f]) => f.spec.isPrimaryKey)
@@ -453,6 +493,28 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
       throw new Error(`model '${table}': can('execute') is a function ability — declare it on the defineFunction it gates.`);
     }
 
+    if (a.condition.deleted !== undefined) {
+      if (a.action !== 'read') {
+        throw new Error(`model '${table}': deleted applies only to can('read'), not can('${a.action}').`);
+      }
+      if (a.condition.deleted !== 'include' && a.condition.deleted !== 'only') {
+        throw new Error(`model '${table}': can('read', { deleted: ${JSON.stringify(a.condition.deleted)} }) — deleted must be 'include' or 'only'.`);
+      }
+      if (!lifecycle) {
+        throw new Error(`model '${table}': can('read', { deleted }) — deleted applies only to a lifecycle model; this model has no deleted rows to include.`);
+      }
+      if (!a.condition.role) {
+        throw new Error(`model '${table}': can('read', { deleted }) — deleted needs a role: it changes that role's own read policy. Name the role that may see deleted rows.`);
+      }
+      // A public tier is every caller of the API, and db:pull could not fold the table back.
+      if (['anon', 'authenticated', 'public'].includes(a.condition.role.toLowerCase())) {
+        throw new Error(
+          `model '${table}': can('read', { role: '${a.condition.role}', deleted }) — deleted rows are for a named internal role, ` +
+            `never a public tier (anon, authenticated, public). Name the role that searches or restores, such as 'support_role'.`,
+        );
+      }
+    }
+
     // A column list is authorization, not a selection hint. If it reaches a table-grant path
     // unnoticed, Postgres receives a whole-table privilege. Admit only the shapes the column
     // compiler understands, and reject an empty list because it is indistinguishable from no
@@ -484,7 +546,9 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
         );
       }
       for (const column of a.condition.columns) {
-        if (!(column in def.fields)) {
+        // deletedAt is visible to every reader of a lifecycle model, so a column read may list it.
+        // deletedBy, deletedBatch and deletedXid are hidden by design and stay refused.
+        if (!(column in def.fields) && !(lifecycle && a.action === 'read' && column === 'deletedAt')) {
           throw new Error(
             `model '${table}': columns names '${column}', but no such field exists. Column abilities use model field keys.`,
           );
@@ -686,6 +750,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     // Stays false on a lifecycle model: its reads are filtered by the RLS guard (L1.2a), its deletes arrive with the triggers.
     softDelete: def.softDelete ?? false,
     ...(lifecycle ? { lifecycle: true as const } : {}),
+    ...(deleteWhen !== undefined ? { deleteWhen } : {}),
     schema: def.schema ?? 'public',
     private: def.private ?? false,
     rls: def.rls ?? true,