@everystack/model 0.4.23 → 0.4.25

package/CHANGELOG.md

@@ -4,6 +4,71 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [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
+
+### 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

@@ -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
@@ -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,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.
+`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', {
@@ -273,25 +276,48 @@ 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.
-`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.
+
+#### 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 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 `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 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.
@@ -305,51 +331,204 @@ 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.
 
-### 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`.
-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. 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.
-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.
+### 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.
+
+### 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`
 
-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', {
@@ -395,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`)
@@ -405,12 +584,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.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/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.
    *