@everystack/model 0.4.24 → 0.4.25

package/CHANGELOG.md

@@ -4,11 +4,47 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [Unreleased]
+## [0.4.25] - 2026-10-30
+
+### BREAKING CHANGES
+
+- destroy is one generated SQL function per lifecycle table; purgeExpired is removed
+- only a lifecycle table may hold a foreign key into a lifecycle table
+
+### Added
+
+- a destroy call removes only rows soft-deleted before its cutoff
+- close destroy_log to the lifecycle role; the marker functions refuse inside a trigger
+- a lifecycle model refuses TRIGGER and REFERENCES in privileges
+- the apply preflight refuses a live catalog that breaks the soft delete
+- db:reconcile runs the live catalog check on every write path
+
+### Fixed
+
+- destroy hooks are refused on a table that is not a lifecycle table
+- provisioning clears committed destroy_log rows and validates the transaction check
+- a DELETE as the lifecycle role is soft outside a destroy call
+- a destroy call whose marker was removed mid-call fails whole (55000)
+- catalog checks pass the RDS shape and see owner, log and settings holes
+- the destroy job logs no error text and fails a failed run
+- LifecycleDestroy runs on CronV2, which the deploy identity may create
+
+### Changed
+
+- one delete hook pair; beforeStamp and afterStamp are folded into beforeDelete and afterDelete
 
 ### Documentation
 
 - verify a built database with compileDeclaredState, not a per-model compileTableSchema loop
+- one delete hook pair
+- destroy, the everystack schema, and the upgrade from purgeExpired
+- who runs destroyExpired, what batch caps, and the single destroy_log marker
+- a destroy call removes only rows soft-deleted before its cutoff
+- the out-of-date destroy_log refusal, a leftover destroying() function, and a root skipped for one run
+- destroy_log is closed to the lifecycle role, and destroy cannot run inside a trigger
+- the destroy result's reason, blocker and skippedBy
+- only a lifecycle table holds a key into one; soft delete decides, destroy executes
+- the destroy role option, the stock job and a first run by hand
 
 ## [0.4.24] - 2026-10-23
 

package/README.md

@@ -163,10 +163,10 @@ such a model and it throws at import, naming which branch it tripped. Where noth
 publicly and nothing deletes, the flag provably changes neither the SQL nor the handler, so
 nothing is required.
 
-Pick `true` if the row is meant to survive its own deletion — anything with a cleanup or purge
+Pick `true` if the row is meant to survive its own deletion — anything with a cleanup or destroy
 job, an audit trail, or rows other tables reference. Pick `false` if `deleted_at` here is
 audit-only and a `DELETE` really should remove the row. It is not cosmetic: a table whose S3
-cleanup job finds work by `deleted_at IS NOT NULL` orphans every file it should have purged if
+cleanup job finds work by `deleted_at IS NOT NULL` orphans every file it should have removed if
 the row is hard-deleted instead.
 
 A column named `deleted_at` is not a statement of intent — it is carried for audit, for
@@ -248,13 +248,13 @@ 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. 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.
+`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 parent rendered `lifecycle: true` is the exception: `db:pull` renders the `dependent` of each key from a lifecycle child on the parent, from the key's `ON DELETE`, and leaves a plain child's key as it is, with a comment: only a lifecycle table may hold a key into a lifecycle table, so that model refuses to compile until you make it `lifecycle: true` or drop the `.references()`.
 
 ### Lifecycle
 
-`lifecycle: true` declares deletion in two steps: hide the row now, remove it later with an explicit purge.
+`lifecycle: true` declares deletion in two steps: hide the row now, remove it later with explicit destruction.
 For example, deleting a post hides its lifecycle comments in the same batch. Restoring the post restores that
-batch subtree. Purging first removes the expired comments, then the post.
+batch subtree. Destroy first removes the expired comments, then the post.
 
 ```typescript
 const Post = defineModel('posts', {
@@ -276,21 +276,21 @@ fingerprint and generated schema. Do not declare these fields yourself, includin
 Lifecycle needs a single-column primary key and RLS. Omit `lifecycle` to disable it; `false` is refused.
 Do not combine it with `softDelete`. The boolean remains supported separately; its removal has not shipped.
 
-A DELETE stamps these columns and reports zero removed rows. Read roles see only live rows;
+A DELETE sets these columns and reports zero removed rows. Read roles see only live rows;
 a plain manage role can see deleted rows. The API hides `deletedBy`, `deletedBatch` and `deletedXid` from other roles.
 `deletedAt` stays visible. The generated guard refuses direct writes to the four columns by ordinary callers.
 Only `everystack_lifecycle`, a reserved NOLOGIN role, performs physical deletion. It receives SELECT,
 UPDATE of those four columns, and DELETE on lifecycle tables, but no INSERT there.
-Authors cannot name this role in abilities or privileges. TRUNCATE privileges on lifecycle models are refused.
+Authors cannot name this role in abilities or privileges. TRUNCATE, TRIGGER and REFERENCES privileges on lifecycle models are refused.
 
 | `dependent` | Lifecycle parent's soft deletion | Physical removal |
 | --- | --- | --- |
-| `restrict` | Refuses while live lifecycle children remain | FK remains RESTRICT; purge waits for all remaining lifecycle children |
-| `cascade` | Stamps lifecycle children in the parent's batch | FK is RESTRICT; purge removes children first |
-| `nullify` | Leaves the child and its link unchanged | SET NULL clears the link at purge |
+| `restrict` | Refuses while live lifecycle children remain | FK is RESTRICT; any remaining child defers the root |
+| `cascade` | Soft-deletes lifecycle children in the parent's batch | FK is CASCADE; physical removal follows it |
+| `nullify` | Leaves the child and its link unchanged | SET NULL clears the link at destroy |
 
 Cascade and restrict from a lifecycle parent require lifecycle children. Nullify requires a nullable FK.
-An actual `ON DELETE CASCADE` into a lifecycle table is refused. Plain-table cascades still remove rows without
+An explicit field `onDelete: 'cascade'` into a lifecycle table is refused; use the lifecycle parent's declared dependent instead. 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.
 
@@ -309,17 +309,15 @@ const List = defineModel('lists', {
 
 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
+The guard checks every soft delete, direct or cascaded, so one guarded child refuses its parent's whole delete and nothing is
+soft-deleted, as `restrict` does. A DELETE of several rows is refused as a whole when any one is guarded. `lifecycle: {}`
+is `lifecycle: true`. Destroy does not re-evaluate the predicate after soft deletion. 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
+For logic a predicate cannot express, a `beforeDelete` hook can `veto(reason)` a root row's soft delete 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.
+There is no option to require an actor on a soft delete: use a veto trigger, or require authentication on DELETE.
+`db:pull` renders live objects without a separate lifecycle verifier; review differences with `db:plan`.
 
 Call `<table>_restore(id)` to restore a batch subtree, or use the API's `POST /<table>/restore { id }`.
 Restore checks the caller's delete rule, not its read policy, because read policies hide deleted rows.
@@ -379,54 +377,154 @@ Where the searching role is shared with other reads, use a `SECURITY DEFINER` lo
 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`
-(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.
-A cyclic lifecycle relation aborts the whole purge run before any row is removed.
-Each selected row gets its own READ COMMITTED transaction and lock. The DELETE runs as the reserved role.
-A remaining cascade/restrict lifecycle child blocks its parent; a nullify child clears its FK on the real delete.
-Unsupported live graph paths are reported without invoking hooks or deleting rows.
-Rows removed by `ON DELETE CASCADE` get no individual destroy hook or receipt.
-
-`budgetMs` defaults to 30000 and is checked between rows; a current transaction finishes.
-`retryAfterMs` defaults to one hour for skipped/failed keys; zero disables it.
-Skipped and failed rows do not consume `batch`. The result has per-table counts, skip reasons,
-`noHook` for removed tables without destroy hooks, and `incomplete` when the time budget ends the run.
-`afterDestroyErrors` counts after-hook failures; `afterDestroyFailures` records the first message per table/key.
-The optional `onError` sink receives each after-hook fault; a throwing sink does not stop the purge.
-
-`everystack.purge_log` stores the run id, table/key, batch, deletion and attempt times, actor, outcome,
-before-hook status and optional detail. A purged receipt commits with its DELETE.
-A failed attempt records failure after rolling back its savepoint, while retaining the row lock.
-The ledger grants INSERT only to the reserved role; guards refuse UPDATE, DELETE and TRUNCATE.
-It contains no row payload. Its owner can disable guards, so it is not evidence against that trusted owner.
-`db:doctor --purge-after <days>` counts overdue rows without hooks or writes; without that flag it skips the count.
-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 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 `{ 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.
-Existing `beforeDelete` and `afterDelete` remain API request hooks, including on lifecycle soft deletion.
+### Destroy expired rows
+
+The operational tables destroy relies on are listed in [the everystack schema](../../docs/everystack-schema.md).
+
+Provision with `db:provision`, or build a fresh database with `db:build`. Both create
+`everystack.destroy_log` before the generated lifecycle functions are installed.
+For each lifecycle table, `<schema>.<table>_lifecycle_destroy(p_keys DEFAULT NULL,
+p_before DEFAULT now(), p_max_rows DEFAULT 1000)` returns one row per root it acted on:
+`key`, and `outcome` (`'removed'` or `'skipped'`).
+Only a role whose `manage` covers every row receives EXECUTE. An owner-scoped `manage`, or a
+role-less one on an owner-scoped model, covers only the caller's rows, so it receives none.
+A role-less `can('manage')` on a model with no owner scope covers every row for `authenticated`,
+and `can('manage', { role: 'anon' })` does the same for `anon`. Those roles then receive EXECUTE
+too, so any caller with that role can destroy soft-deleted rows before your retention window ends.
+To keep destroy with your operators, declare `manage` for a named role such as `admin`. This key-list contract currently requires scalar
+primary keys; declaration refuses array-valued keys. 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.
+
+The function selects already deleted rows strictly older than `p_before`, ordered by deletion
+time and key, with `FOR UPDATE SKIP LOCKED`. NULL keys select by date alone. Foreign keys
+apply the declared CASCADE, SET NULL, or RESTRICT action. A root with any remaining restrict
+child, live or deleted, is deferred until that child is gone. Run tables in
+`lifecycleDestroyOrder(models)` (children first over restrict and cascade edges), with each call in
+its own transaction. Self-restrict trees converge one level per call; multi-table cycles are
+refused at link and compile time. A live blocker leaves the parent overdue for `db:doctor`.
+Only a lifecycle table may hold a foreign key into a lifecycle table, and the parent declares each one
+with a hasMany `dependent`; a plain table refers to a lifecycle row by value. Any other key into a
+lifecycle table is refused at `linkModels` and by `db:apply`. A key outside the declarations
+(an out-of-band key, which no normal write makes) makes the set delete raise. The function then retries each root alone, returns each one
+that still raises as `'skipped'`, and removes the rest. Only `foreign_key_violation` is skipped;
+a lock timeout or any other error rolls the call back. The retry uses one subtransaction per root.
+Fewer than `p_max_rows` rows may be returned (rows locked by a concurrent transaction are skipped).
+`p_max_rows` must be a non-NULL positive integer; there is no upper cap.
+The function uses a function-level `lock_timeout = '5s'`, restored on return. The caller must set
+`statement_timeout` before invoking: setting it inside cannot bound an already running statement.
+The wrapper must pass the SAME `p_before` cutoff it used to select candidates. A row restored and
+re-deleted after that cutoff has a newer `deleted_at` and is skipped, which neutralises stale hook
+approval without a token. Eligibility is checked inside the function; `deleteWhen`
+is not checked again during destroy.
+
+During the call, a lifecycle `DELETE` removes a row only if it is already soft-deleted and either
+older than the call's cutoff or a cascade child whose declared cascade parent the call removed:
+eligibility follows the root, so a child soft-deleted on its own a moment after its root goes with
+it. Anything else (a live row, or a deleted row that is neither expired nor cascading, such as one a
+consumer trigger tries to erase early) raises `23503`, and the root is reported as `'skipped'` with
+nothing removed. Every delete after
+the call returns is soft again, the lifecycle role's included.
+
+`everystack.destroy_log` holds one row per destroy call in progress: the transaction ID and the
+call's cutoff (`before`, the `p_before` it was given). The call writes it before it deletes and removes it before it returns, so the table is empty at rest
+and never grows. No role but its owner holds a privilege on it. The call writes and removes its row
+through `everystack.destroy_log_mark` and `everystack.destroy_log_unmark`, which only the lifecycle
+role may run, and which refuse to run inside a trigger (`55000`). So a consumer trigger cannot
+remove the call's row or write a new one with another cutoff, and **destroy cannot run inside a
+trigger**: a `<table>_lifecycle_destroy` call from a trigger (a nested call during a destroy
+included) fails with `55000`. Call it as a top-level statement, as `destroyExpired` does. A later
+call in the same transaction runs on its own row. If the call's row is gone before the call ends,
+the call fails whole with `55000` and removes nothing. A consumer trigger on a cascaded child runs
+as that child table's owner (PostgreSQL runs `ON DELETE CASCADE` as the referencing table's owner),
+not as the lifecycle role: treat it as owner code. The table keeps
+no audit: `destroyExpired` returns what it removed per table, for the caller to record if it wants.
+
+Use `destroyExpired` on a top-level database handle to run optional JavaScript hooks around
+the generated SQL calls. It uses `lifecycleDestroyOrder(models)`; it computes no graph. The role it
+runs as needs EXECUTE on the destroy functions and must read every expired row: a role whose `manage`
+covers every row, such as `admin`. Pass `role: 'admin'` on the app's least-privilege login
+(`authenticator`, NOINHERIT): every transaction then starts with `SET LOCAL ROLE admin`, as the API
+does. Never run it as the database master or as `everystack_lifecycle`, which it refuses. It reads candidates a page of `batch` at a time
+and names each page's keys in its call, so a call's work stays bounded however many roots are pinned.
+
+```typescript
+import { destroyExpired } from '@everystack/server/destroy';
+
+const result = await destroyExpired(db, models, {
+  after: 30 * 86400000, // Positive retention window in milliseconds, supplied by the caller.
+  batch: 1000,         // Roots removed per table per run, at most; also the page size.
+  statementTimeoutMs: 60000,
+  role: 'admin',       // SET LOCAL ROLE in every transaction; omit to run as the handle's own role.
+  onError: ({ table, phase, error }) => report({ table, phase, error }),
+});
+```
+
+There is no retention window on the Model. `after` is required; `batch` defaults to 1000 and
+`statementTimeoutMs` to 60000. Optional `now: Date` fixes the run's clock. The wrapper chooses
+one cutoff for the whole run, sets `SET LOCAL statement_timeout` before every destroy call,
+and opens a separate top-level transaction for each call. A table with nothing expired gets no call. Do not pass a transaction handle.
+It does not retry or schedule work.
+
+| Hook on the Model | When | Effect |
+| --- | --- | --- |
+| `beforeDestroy(row, ctx)` | Before the SQL attempt, per candidate root | `veto(reason)` or a throw holds that root |
+| `afterDestroy(row, ctx)` | After commit, only for root keys returned by SQL | Best-effort; errors do not change the result |
+
+Hooks receive database rows with SQL column names. `ctx` is frozen:
+`{ phase: 'destroy', batch: row.deleted_batch ?? null, user: null, client: null }`.
+A failed commit can cause hooks to repeat on a later run; hooks must tolerate repetition.
+Before-hook errors increment `held` and reach `onError`. An SQL or transaction failure sets
+`failed` for that table and the run continues. After-hook errors reach `onError` without
+changing the committed result. A throwing `onError` does not stop the run.
+
+The result is `{ perTable, order }`: each `perTable['<schema>.<table>']` has
+`{ removed, held, skipped, failed? }`. `held` counts vetoed or hook-skipped roots. `skipped` counts
+roots a foreign key still references; `db:doctor` keeps counting them overdue. Neither counts
+roots deferred by restrict children or skipped because they are locked. `order` is the list
+from `lifecycleDestroyOrder` (public table names are bare; other schemas are qualified).
+
+beforeDestroy(row, ctx) runs before an attempt; return veto(reason) to withhold the row. The row may still survive the attempt, so do nothing irreversible here. afterDestroy fires at most once per removed root, after commit; a crash between commit and the hook loses the call, so durable work belongs in a consumer AFTER DELETE trigger writing to an outbox. Hooks run for roots only: a child removed by its parent's cascade fires no afterDestroy; a sweep or a child trigger covers it. While a destroy call executes, a delete of a lifecycle row in that call, including one a consumer trigger issues, removes the row only if it is already soft-deleted and older than the call's cutoff; anything else raises, and the root is reported as skipped with nothing removed. Outside a destroy, every delete is soft. A root with a remaining restrict child is deferred until the child is gone. destroyExpired's perTable[t].skippedBy counts skipped roots by reason ('referenced', 'ineligible_live') and blocker (a table or constraint name, never a key); normal writes never cause a skip, so one means an out-of-band key or trigger. Fewer than batch rows may be returned. 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). The caller sets statement_timeout; the function sets only lock_timeout. Pass the same cutoff you selected with.
+
+`db:doctor --destroy-after <days>` counts overdue rows without hooks or writes.
+`overdueLifecycleRowsReadOnly(db, models, { after, role })` gives the same counts in one read-only
+transaction under `role`.
+
+#### The scheduled destroy job
+
+`createDestroyJob` from `@everystack/server/destroy-job` is the stock scheduled handler. It does
+nothing until you set `after`: with no retention window it logs one line and never connects. Give
+it a handle on the least-privilege login; it switches to `role` (default `admin`) in each
+transaction. It logs one JSON line with per-table counts and the `describeSkipped` lines, never a
+row key or an error message. A run where any table failed then throws, naming only the failed
+tables, so the invocation fails and error alarms fire; the cause reaches `onError`.
+
+```typescript
+import { createDb } from '@everystack/server/db';
+import { createDestroyJob } from '@everystack/server/destroy-job';
+
+export const handler = createDestroyJob({
+  models,
+  after: 30 * 86400000,
+  db: () => createDb(schema).db,
+});
+```
+
+`createDb` connects as the authenticator only when the function links the `DATABASE_URL` secret and not the `Database` component; with no `DATABASE_URL` linked it falls back to the master.
+
+The event `{ "dryRun": true }` counts the overdue rows under the role and changes nothing. The
+example app runs the job as the `LifecycleDestroy` CronV2, linked to `DATABASE_URL` only. For a first
+run, invoke it by hand with your AWS profile; you hold no database credential and no lifecycle role.
+With several stages in one account the lookup lists each; set `fn` to the one for your stage.
+
+```bash
+fn=$(aws lambda list-functions --query "Functions[?contains(FunctionName, 'LifecycleDestroy')].FunctionName" --output text)
+aws lambda invoke --function-name "$fn" --cli-binary-format raw-in-base64-out --payload '{"dryRun":true}' dry.json && cat dry.json
+aws lambda invoke --function-name "$fn" run.json && cat run.json
+```
+
+Read the dry run's counts before the real run. The real run removes at most `batch` roots per table.
+The example's account-erasure cron remains paused; it needs a separate adoption change.
 
 ### Display options: `orderBy`, `limit`, `where`, and `hasOne`
 
@@ -476,7 +574,7 @@ const handler = createHandler(db, schema, deriveHandlerConfig(models));
 
 Do not hand-write the per-table keys beside it. Each one is a view of the models, and a
 hand-kept copy drifts silently: `softDelete.tables` losing two entries is what let a table start
-hard-deleting rows whose S3 objects a purge job keyed on `deleted_at IS NOT NULL`. Handler-level
+hard-deleting rows whose S3 objects a destroy job keyed on `deleted_at IS NOT NULL`. Handler-level
 options that are not per-table — `auth`, `pgSettings`, `rpc`, limits — stay explicit.
 
 ## Programmatic API (`@everystack/cli/model`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "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/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,7 +47,7 @@ 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`
   );
 }
@@ -135,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 (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'`,
-        );
-      }
+      if (parent.lifecycle && !child.lifecycle) throw new Error(plainKeyRefusal(`${at}, but ${where}`, nameOf(child), nameOf(parent), '.references()'));
 
-      // 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) {
@@ -175,21 +158,75 @@ 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 purge's ON DELETE SET NULL ('nullify') runs
+ * 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
- * purge over 600k SET NULL children 21.4 s without, 0.6 s with).
+ * 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
@@ -234,3 +271,45 @@ export function lifecycleDependentIndexes(
   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,7 +29,7 @@ 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, lifecycleDependentIndexes } from './dependents';
+export { relationDeleteActions, lifecycleDependentIndexes, lifecycleDestroyOrder } from './dependents';
 export type { DependentActions, DependentIndexes } from './dependents';
 
 export { veto, isVeto } from './lifecycle-hooks';
@@ -54,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

@@ -1,5 +1,5 @@
 /**
- * The lifecycle hook contract, shared by the model, the API handler and purge.
+ * 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.
  */
@@ -26,11 +26,9 @@ export function isVeto(value: unknown): value is HookVeto {
 
 /** 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. */
+  /** `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;
@@ -46,8 +44,27 @@ export interface DestroyContext extends LifecycleContext {
 /** 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. */
+/** 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>;
 
-/** An after hook of the lifecycle: called after commit with the root rows of one batch. Best-effort. */
+/** 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`);
+    }
+  }
+}

package/src/model.ts

@@ -23,12 +23,12 @@ 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';
+import { assertDeleteHookNames, assertDestroyHooks, type AfterLifecycleHook, type BeforeLifecycleHook, type 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
+ * absorb (remove a stored object after destroy, set a column on create) — held
  * verbatim and passed through to the handler's `hooks`.
  */
 export interface ModelHooks {
@@ -36,20 +36,17 @@ export interface ModelHooks {
   afterCreate?: (...args: any[]) => any;
   beforeUpdate?: (...args: any[]) => any;
   afterUpdate?: (...args: any[]) => any;
-  beforeDelete?: (...args: any[]) => any;
-  afterDelete?: (...args: any[]) => any;
-  /** Runs after the DELETE statement, before commit. A throw rolls back only the database
-   * delete, never an external effect. No transaction is passed. Must be idempotent.
-   * Treat the row as read-only: it is the same object later serialized into the response. */
+  /** Before commit, once per matched root. Cascaded children run no hook; use deleteWhen. */
+  beforeDelete?: BeforeLifecycleHook;
+  /** After commit, once per request with the root rows. Best-effort. */
+  afterDelete?: AfterLifecycleHook;
+  /** Before an SQL destroy attempt, per candidate root. A veto or throw holds that root.
+   * The row may survive the attempt; do nothing irreversible here. No transaction is passed.
+   * Hooks may repeat after a failed commit. Treat the database row as read-only. */
   beforeDestroy?: DestroyHook;
-  /** 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. */
+  /** After commit, only for removed roots; FK cascade children run no hook. Best-effort:
+   * a crash can lose the call. Cannot undo removal. Treat the database row as read-only. */
   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. */
@@ -123,7 +120,7 @@ export interface ModelDefinition {
    *
    * The guard used to ask only about the public read, which is the visibility axis. That let a
    * model with an owner-scoped read and a `delete` ability default to `false` and begin
-   * destroying rows — with an S3 purge job keyed on `deleted_at IS NOT NULL`, that orphaned
+   * destroying rows — with an S3 cleanup job keyed on `deleted_at IS NOT NULL`, that orphaned
    * every file it should have cleaned up. On those models the flag adds no policy at all, so
    * visibility was never the axis that mattered.
    *
@@ -142,10 +139,10 @@ export interface ModelDefinition {
    * `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.
    *
-   * `{ deleteWhen: sql\`<predicate>\` }` is lifecycle too, with a guard: a row may be stamped
+   * `{ deleteWhen: sql\`<predicate>\` }` is lifecycle too, with a guard: a row may be marked
    * 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`.
+   * Destroy does not re-check this predicate after deletion. `{}` is `true`.
    */
   lifecycle?: true | LifecycleOptions;
   /**
@@ -320,7 +317,7 @@ 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. */
+  /** A row may be marked deleted only when this is TRUE for it; FALSE or NULL refuses. */
   deleteWhen?: RawSql;
 }
 
@@ -377,7 +374,7 @@ function assertLifecycle(table: string, def: ModelDefinition): void {
   }
   // A cascade into this table, declared on this table's own foreign key. A parent's
   // hasMany { dependent: 'cascade' } is checked in relationDeleteActions (allowed from a
-  // lifecycle parent, where it compiles to RESTRICT and the triggers soft-delete the children).
+  // lifecycle parent: the triggers soft-delete the children, and destroy follows the real CASCADE).
   const tableName = def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table;
   for (const [name, f] of Object.entries(def.fields)) {
     if (f.spec.onDelete !== 'cascade') continue;
@@ -395,6 +392,10 @@ function assertLifecycle(table: string, def: ModelDefinition): void {
         `Mark exactly one field .primaryKey().`,
     );
   }
+  const [key, keyField] = Object.entries(def.fields).find(([, f]) => f.spec.isPrimaryKey)!;
+  if (keyField.spec.isArray) {
+    throw new Error(`model '${tableName}': lifecycle needs a primary key PostgreSQL can list in a key array; ${key} is an array type`);
+  }
   // The generated trigger and function names are `<table>_lifecycle_transition` and `_guard`.
   // PostgreSQL silently truncates an identifier past 63 bytes, so the declared name would not be the live one.
   // UTF-8 bytes, as PostgreSQL counts them. TextEncoder rather than Buffer: a model also loads outside Node.
@@ -412,7 +413,9 @@ function assertLifecycle(table: string, def: ModelDefinition): void {
  * Restore runs the table's delete rule inside a SECURITY DEFINER function as the lifecycle role.
  * Refuse a delete rule whose meaning would change there: a subquery (`via`, or SELECT in
  * where/sql) runs with that role's privileges, and current_user/session_user name that role or
- * the login, not the caller. TRUNCATE is refused because it skips the delete triggers.
+ * the login, not the caller. TRUNCATE is refused because it skips the delete triggers; TRIGGER
+ * because its holder can create triggers on the table; REFERENCES because its holder can
+ * add a foreign key that blocks or cascades a destroy.
  */
 function assertLifecycleRestoreSafe(table: string, def: ModelDefinition): void {
   if (!isLifecycle(def)) return;
@@ -464,9 +467,25 @@ function assertLifecycleRestoreSafe(table: string, def: ModelDefinition): void {
         `triggers, so it would erase rows past the soft delete and restore. Remove TRUNCATE from the entry.`,
     );
   }
+  const beyondDelete: Record<string, string> = {
+    TRIGGER: 'TRIGGER lets the holder create triggers on the table, so its own code would run inside every delete and destroy',
+    REFERENCES: 'REFERENCES lets the holder add a foreign key that blocks or cascades a destroy',
+  };
+  for (const [role, privs] of Object.entries(def.privileges ?? {})) {
+    if (!Array.isArray(privs)) continue;
+    for (const priv of ['TRIGGER', 'REFERENCES'] as const) {
+      if (!privs.includes(priv)) continue;
+      throw new Error(
+        `model '${table}': privileges['${role}'] grants ${priv} on a lifecycle: true model — ${beyondDelete[priv]}. ` +
+          `Remove ${priv} from the entry.`,
+      );
+    }
+  }
 }
 
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
+  assertDeleteHookNames(table, def.hooks);
+  assertDestroyHooks(table, def.hooks, isLifecycle(def));
   // Refuse first, then inject: the author-declared collisions are checked against what the author wrote.
   assertRoleNotReserved(table, def);
   assertLifecycle(table, def);

package/src/pg-type.ts

@@ -1,3 +1,5 @@
+import type { FieldSpec } from './field';
+
 /**
  * pg-type — the ONE definition of a column type's spelling.
  *
@@ -95,3 +97,67 @@ export function pgTypeRefusal(typeName: string): string | null {
   }
   return null;
 }
+
+/**
+ * Postgres type for a field, with the precision drizzle-kit would emit — in
+ * `format_type`'s vocabulary, because this feeds the IR that diffs against
+ * introspection. A serial field's *column type* is integer/bigint (`serial` is
+ * DDL shorthand, not a type — `format_type` never reports it); the sequence
+ * default is carried separately (see compileTableSchema), and the DDL renderers
+ * spell the shorthand (see SERIAL_DDL).
+ */
+const PG_TYPE: Record<string, string> = {
+  text: 'text',
+  uuid: 'uuid',
+  integer: 'integer',
+  boolean: 'boolean',
+  json: 'json',
+  jsonb: 'jsonb',
+  bigint: 'bigint',
+  serial: 'integer',
+  bigserial: 'bigint',
+  real: 'real',
+  doublePrecision: 'double precision',
+  timestamptz: 'timestamp with time zone',
+  // `format_type` canonicalizes a bare `timestamp` column to this spelling, and
+  // introspection compares against it — so the compiler must emit the same, or an
+  // unchanged `timestamp` column round-trips to a spurious ALTER COLUMN TYPE.
+  timestamp: 'timestamp without time zone',
+  date: 'date',
+};
+
+export function pgType(spec: FieldSpec): string {
+  // An array is the base type with `[]` appended — `text` → `text[]`, exactly as
+  // `format_type` spells it.
+  return spec.isArray ? `${scalarPgType(spec)}[]` : scalarPgType(spec);
+}
+
+function scalarPgType(spec: FieldSpec): string {
+  // Parameterized types build their own canonical string — exactly as `format_type`
+  // spells it (no space after the comma; `varchar` is `character varying`; a
+  // precision-only numeric carries scale 0), so an unchanged column round-trips clean.
+  if (spec.type === 'numeric') {
+    if (spec.precision != null) return `numeric(${spec.precision},${spec.scale ?? 0})`;
+    return 'numeric';
+  }
+  if (spec.type === 'varchar') {
+    return spec.length != null ? `character varying(${spec.length})` : 'character varying';
+  }
+  if (spec.type === 'enum') {
+    // The column's type is the enum's own type name; `format_type` reports the same bare
+    // name, so it round-trips. The `CREATE TYPE` is emitted separately, before the table.
+    if (!spec.enumName) throw new Error('field bridge: an enum field needs a type name — field.enum(name, values)');
+    return spec.enumName;
+  }
+  if (spec.type === 'pgType') {
+    // A verbatim type: the declared string IS the canonical `format_type` spelling
+    // (the factory refused anything else), so it round-trips byte-for-byte.
+    if (!spec.pgTypeName) throw new Error('field bridge: a pgType field needs its type name — field.pgType(name)');
+    return spec.pgTypeName;
+  }
+  const t = PG_TYPE[spec.type];
+  if (!t) {
+    throw new Error(`field bridge: no DDL mapping for field type '${spec.type}' yet`);
+  }
+  return t;
+}

package/src/wire.ts

@@ -46,8 +46,10 @@
  *
  * v1 — the first version. Shapes as they stood when the guard was introduced.
  * v2 — ProvisionWirePayload gains `lifecycleRole` (provision the reserved lifecycle role).
+ * v3 — ReconcileWirePayload gains `applicationRoles` (the lifecycle catalog check's roles). A v2
+ *      CLI's payload carries none, and a reconcile of lifecycle-owned objects refuses without them.
  */
-export const MODEL_WIRE_CONTRACT = 2;
+export const MODEL_WIRE_CONTRACT = 3;
 
 /**
  * Every Model-derived wire payload carries this. The server refuses a payload whose `modelContract`
@@ -237,6 +239,12 @@ export interface ReconcileWirePayload extends ModelWireEnvelope {
   rebuild?: boolean;
   overwriteDrift?: boolean;
   only?: string[];
+  /**
+   * The application roles the Models' compiled contracts name (catalogInputsFromModels in the
+   * CLI): the lifecycle catalog check's one input the declared layer cannot supply. Absent while a
+   * declared object is lifecycle-owned = the reconcile refuses (fail closed).
+   */
+  applicationRoles?: string[];
   actor?: string | null;
   gitRef?: string | null;
 }