@everystack/model 0.4.22 → 0.4.24

package/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [Unreleased]
+
+### Documentation
+
+- verify a built database with compileDeclaredState, not a per-model compileTableSchema loop
+
+## [0.4.24] - 2026-10-23
+
+### BREAKING CHANGES
+
+- lifecycle: { deleteWhen } refuses deleting a row its predicate does not allow
+- refuse dependent + where on a lifecycle parent's hasMany
+- can('read', { role, deleted: 'include' | 'only' }) on a lifecycle model
+- one lifecycle hook API: (rows, ctx), veto(reason), beforeStamp
+- refuse can('read', { deleted }) for anon, authenticated and public
+
+### Added
+
+- index the FK column of every lifecycle dependent
+
+### Documentation
+
+- what a lifecycle delete returns, plain children, vetoing a delete, the purge executor, the caching note
+- lifecycle dependents' FK columns are indexed by the generator; what a pull without dependents plans
+- measure what the lifecycle read guard costs a non-leakproof index search
+- can('read', { role, deleted }) as the read hatch for a lifecycle index search
+- Extending lifecycle, the phase table, the veto and failure rules
+- the keyed lifecycle DELETE, before-hook pool hazard, batch as a hint, deleted-reader grants, FK index drops
+
+## [0.4.23] - 2026-10-23
+
+### Added
+
+- external FK target, .references({ schema, table, column })
+- F7a relation options; hasMany dependent sets the child FK ON DELETE
+- relation display options and hasOne (F7b)
+- per-parent embed order, limit and where on both read paths (F10)
+- hasOne one-row embed on both read paths (P2)
+- hasMany dependent 'cascade' is ON DELETE CASCADE on the child's foreign key (D1)
+- lifecycle: true declares four generated columns (L1.1)
+- lifecycle gets a reserved owner role and hides deleted rows from read roles (L1.2a)
+- lifecycle triggers turn DELETE into a soft delete (L1.2b)
+- lifecycle restore, for whoever may delete the row (L1.3)
+- a lifecycle parent's delete soft-deletes its cascade children in the same batch (L2 + L6, P1.2)
+- the handler deletes, hides and restores lifecycle rows through the database (H1, P1.4)
+- db:provision creates the reserved lifecycle role (P2.7)
+- lifecycle columns are hidden from callers that cannot manage the table
+- beforeDestroy and afterDestroy hooks at a real removal
+
+### Fixed
+
+- F3e review minors: catalog FK target, one target slot, derived refusal
+- F7a review: derive dependent ON DELETE per set, never write a field spec
+- F7b review: mark display relations in drizzle, withhold only where/limit
+- a beforeDestroy HandlerError renders with its own status
+
+### Changed
+
+- break the link.ts <-> relations.ts import cycle (F7b)
+
+### Documentation
+
+- name the one runtime-vs-generated Drizzle difference a parent dependent creates
+- handler relation orderBy/limit/where; the API handler applies the display options (F11)
+- lifecycle, dependents, hooks at the real removal, purge
+- define destroy timing and verification limits
+
 ## [0.4.22] - 2026-10-16
 
 ### Added

package/README.md

@@ -72,7 +72,7 @@ export const models = [Account, Note];
 | `field.jsonb()` | `jsonb` |
 | `field.enum('name', [...])` | a `CREATE TYPE … AS ENUM` (name is explicit, so `db:pull` round-trips it) |
 
-Modifiers: `.primaryKey()`, `.notNull()` / `.nullable()`, `.unique()`, `.default(value)` / `.defaultNow()` / `.defaultRandom()`, `.references(() => Other, { onDelete, onUpdate })`, `.private()` (never serialized), `.readonly()` (never accepted on write), `.validate(zodSchema)`, `.renamedFrom('oldField')` (turns a drop+add into a data-preserving `RENAME COLUMN`), and `.deprecated()` (the contract phase of contraction: the column stays in the database and stays readable — old clients keep working — while new writes are rejected and generated types strike it through; deleting the field later is the actual drop, destructive and gated).
+Modifiers: `.primaryKey()`, `.notNull()` / `.nullable()`, `.unique()`, `.default(value)` / `.defaultNow()` / `.defaultRandom()`, `.references(() => Other, { onDelete, onUpdate })` (or `.references({ schema, table, column })` for a table no model declares, below), `.private()` (never serialized), `.readonly()` (never accepted on write), `.validate(zodSchema)`, `.renamedFrom('oldField')` (turns a drop+add into a data-preserving `RENAME COLUMN`), and `.deprecated()` (the contract phase of contraction: the column stays in the database and stays readable — old clients keep working — while new writes are rejected and generated types strike it through; deleting the field later is the actual drop, destructive and gated).
 
 Renaming a whole table works the same way, at the model level: `defineModel('articles', { renamedFrom: 'posts', ... })` compiles to one `ALTER TABLE … RENAME TO …` (data preserved, policies ride along) instead of CREATE plus a held DROP. Both markers are one-shot — remove them once every environment is past the state; a satisfied rename is an inert notice.
 
@@ -87,6 +87,24 @@ The table-level surface, composed in `constraints: [...]`, for what a column-sco
 - `check(sql\`a >= b\`)` — a multi-column CHECK.
 - `foreignKey(['a', 'b'], () => Other, ['x', 'y'], { onDelete })` — a composite foreign key.
 
+### A foreign key to a table no model declares
+
+Another system can own the table a column points at: an auth provider's `auth.users`, a table another service writes. Name it as an object:
+
+```typescript
+ownerId: field.uuid().references({ schema: 'auth', table: 'users', column: 'id' }, { onDelete: 'cascade' }),
+// composite: the reference columns are the third argument
+constraints: [foreignKey(['orgId', 'teamId'], { schema: 'auth', table: 'teams' }, ['org_id', 'team_id'])],
+```
+
+- `schema`, `table` and `column` are all required. There is no `public` default, and nothing is split on a dot: each is one PostgreSQL name, used as written (no snake_casing). A name holding a quote, a dot or a control character, or longer than 63 bytes, is refused.
+- A string target is always a model name. `.references('users')` with no `users` model is an error, never a table.
+- If a model in the set declares that schema and table, the object form is refused: use the model.
+- It is a foreign key only, never a relation. It adds no `belongsTo`/`hasMany`, no embedding and no handler relation.
+- It plans, applies and fingerprints exactly like a model foreign key. Delete it from the model and the next plan drops it; drop it from the database and the next plan adds it back.
+- The deploying role needs `REFERENCES` on the target table. Without it the apply fails with PostgreSQL's `permission denied for table …`; granting it is the target owner's decision.
+- A plan line names the target as `schema.table`: `+ add constraint things_owner_id_users_id_fk on things referencing auth.users`.
+
 Each can carry the name the database calls it: `index('slug').name('posts_slug_lookup')`, `foreignKey([...], () => Other, [...], { name: 'posts_owner_fk' })`, and `check(sql\`ends_at >= starts_at\`, { name: 'events_window_check' })`. Undeclared, the compiler generates the name. A check is then named by its position among the table's unnamed checks (`events_check_0`, `events_check_1`), so inserting or reordering one renames the others; an explicit name is used verbatim and is stable under reordering. A name must be a bare lowercase identifier of at most 63 bytes, and two checks in one table cannot share a name or take one an unnamed check gets by position. Declaring a name on an existing constraint plans a `RENAME CONSTRAINT` (or `ALTER INDEX … RENAME`), never a drop and re-add. `db:apply` applies a rename like any other change, also when it is the only change in the plan. `db:pull` declares a live name only when it is not the one the compiler would generate.
 
 ## Authorization
@@ -159,17 +177,283 @@ flag explicitly for the same reason.
 ## Relations
 
 ```typescript
-import { belongsTo, hasMany } from '@everystack/model';
+import { belongsTo, hasMany, hasOne } from '@everystack/model';
 
 defineModel('notes', {
   fields: { /* … */ },
   relations: {
     account: belongsTo(() => Account, 'accountId'),
     comments: hasMany(() => Comment, 'noteId'),
+    latestComment: hasOne(() => Comment, 'noteId', { orderBy: [{ field: 'createdAt', order: 'desc' }] }),
+  },
+});
+```
+
+The target is a model thunk or a model name (`hasMany('comments', 'noteId')`), resolved by `linkModels`. The third argument is optional:
+
+```typescript
+belongsTo(target, column, opts?: string | { references?: string })
+hasMany(target, column, opts?: string | {
+  references?: string;
+  dependent?: 'restrict' | 'nullify' | 'cascade';
+  orderBy?: Array<{ field: string; order: 'asc' | 'desc' }>;
+  limit?: number;
+  where?: Record<string, string | number | boolean | null>;
+})
+hasOne(target, column, opts?: {
+  references?: string;
+  orderBy?: Array<{ field: string; order: 'asc' | 'desc' }>;
+  where?: Record<string, string | number | boolean | null>;
+})
+```
+
+A string third argument is `references`, the key on the other side when it is not the primary key. Existing calls mean what they meant. An unknown option is refused by name.
+
+### What a delete does: `dependent`
+
+`dependent` on a `hasMany` says what deleting this row does to the target rows. For plain tables, it compiles to the `ON DELETE` of the target's foreign key on `column`. Lifecycle tables use the rules below:
+
+| `dependent`  | the child's foreign key           |
+| ------------ | --------------------------------- |
+| `'restrict'` | `ON DELETE RESTRICT`              |
+| `'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() },
+  relations: { comments: hasMany('comments', 'postId', { dependent: 'nullify' }) },
+});
+const Comment = defineModel('comments', {
+  fields: { id: field.uuid().primaryKey(), postId: field.uuid().references('posts') },
+});
+// db:plan: comments_post_id_posts_id_fk is re-created ON DELETE SET NULL.
+// Deleting a post sets its comments' post_id to NULL.
+```
+
+The foreign key belongs to the child table, so the action lands there: in the plan, the from-scratch build and the fingerprint, as an ordinary foreign-key change you review. The rules:
+
+- **The child must declare the foreign key.** `.references()` on the target field, pointing at this model. A `dependent` never creates one; without it the compile fails with `declare .references() on comments.postId`.
+- **Neither side wins.** The child may also declare `onDelete`. If both say the same thing (`'restrict'` and `'restrict'`, `'nullify'` and `'set null'`), that is fine and emitted once. If they disagree, the compile fails naming both places. A child's explicit `onDelete: 'no action'` disagrees with `dependent: 'restrict'`: `NO ACTION` can be deferred to the end of the transaction, `RESTRICT` cannot.
+- **`'restrict'` is a real change from the default.** A child FK with no `onDelete` is PostgreSQL's default, `NO ACTION`. Adding `dependent: 'restrict'` over it moves it to `RESTRICT`, and `db:plan` shows that as the FK being re-created.
+- The action is a property of the model set, never written into a field. A field builder shared by two child models gets the action only on the child the relation names. The runtime `toDrizzleTable(model)` is built per model, so it carries only the child's own `onDelete`; the DDL, the plan, the fingerprint and the generated `schema.generated.ts` carry the derived one.
+- **`'nullify'` needs a nullable column.** On a `NOT NULL` field it is a compile error.
+- It applies to the one foreign key on `column`. Another foreign key from the same child to the same parent is untouched.
+- The relation must join on the primary key (the key a field `.references()` points at). A field covered only by a table-level `foreignKey(...)` declares `onDelete` there.
+- **`'cascade'` deletes the children in the database** (Rails `delete_all`). It runs no hook of the child and no code of yours. A child that must run code when it goes is not a cascade; that is `'destroy'`, which is not available yet. `'cascade'` works over a `NOT NULL` column, and it follows the child's own foreign keys in turn: deleting a thread deletes its replies and their reactions.
+- **A cascade is not checked against the child's own abilities.** PostgreSQL runs the referential action as the owner of the child table, so a role that may delete the parent row removes its children even when it holds no `DELETE` grant on the child and the child's row-level policy would refuse it. Grant `delete` on the parent only to roles that may remove everything below it. `'nullify'` has the same property for `UPDATE`.
+- 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.
+
+### Lifecycle
+
+`lifecycle: true` declares deletion in two steps: hide the row now, remove it later with an explicit purge.
+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.
+
+```typescript
+const Post = defineModel('posts', {
+  lifecycle: true,
+  fields: { id: field.uuid().primaryKey() },
+  relations: { comments: hasMany('comments', 'postId', { dependent: 'cascade' }) },
+  abilities: [can('manage', { role: 'admin' })],
+});
+const Comment = defineModel('comments', {
+  lifecycle: true,
+  fields: { id: field.uuid().primaryKey(), postId: field.uuid().references('posts') },
+  abilities: [can('manage', { role: 'admin' })],
+});
+```
+
+The compiler adds nullable `deletedAt` (timestamptz), `deletedBy` (text, no foreign key),
+`deletedBatch` (uuid) and `deletedXid` (bigint). `LIFECYCLE_COLUMNS` names them. They enter the schema plan,
+fingerprint and generated schema. Do not declare these fields yourself, including their snake_case spellings.
+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 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.
+
+| `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 |
+
+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
+running app hooks. `dependent: 'destroy'` has not shipped.
+AFTER DELETE audit triggers are supported; they do not run on a soft deletion.
+
+#### Refusing some deletes: `deleteWhen`
+
+`lifecycle: { deleteWhen: sql\`<predicate>\` }` is lifecycle with a guard: a row may be deleted only when the predicate
+is TRUE for it. FALSE refuses, and so does NULL. The predicate uses bare column names, like a policy predicate:
+
+```typescript
+const List = defineModel('lists', {
+  lifecycle: { deleteWhen: sql`NOT (kind = 'system' AND private)` },
+  fields: { id: field.integer().primaryKey(), kind: field.text().notNull(), private: field.boolean().notNull() },
+  abilities: [can('manage', { role: 'admin' })],
+});
+```
+
+A refused delete raises SQLSTATE `23514` with the constraint `<table>_lifecycle_delete_when` and a message that names
+the table, never a row value; the API answers `422` with `"Deleting this row is not allowed by its model's deleteWhen."`.
+The guard checks every stamp, direct or cascaded, so one guarded child refuses its parent's whole delete and nothing is
+stamped, as `restrict` does. A DELETE of several rows is refused as a whole when any one is guarded. `lifecycle: {}`
+is `lifecycle: true`. Purge removes a row only while the predicate still holds: a row whose columns changed after its
+stamp stays, with a `skipped` receipt (`protected by deleteWhen`) and no retry cooldown. The predicate runs as the
+reserved lifecycle role with a pinned `search_path`, so qualify any function of your own it calls.
+For logic a predicate cannot express, a `beforeStamp` hook can `veto(reason)` a root row's stamp through the API
+([Extending lifecycle](../../docs/handler.md#extending-lifecycle)); the `BEFORE UPDATE` veto trigger in docs/upgrading.md
+remains the last resort, the one that also sees direct SQL and cascades.
+There is no option to require an actor on a stamp: use a veto trigger, or require authentication on DELETE.
+`db:pull` refuses author BEFORE DELETE triggers on lifecycle tables because they can suppress purge DELETE.
+It also refuses TRUNCATE triggers because TRUNCATE bypasses lifecycle row removal.
+
+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.
+Missing, live and unauthorized roots all raise the same `42501` permission error.
+A lifecycle delete/manage rule cannot use `via`, a subquery, `current_user`, `session_user` or role `public`.
+Keep predicates to column comparisons and request claims; a schema-qualified helper inside restore runs as the reserved role.
+Restore uses set-based updates, with per-row collision fallback only when uniqueness is declared.
+See [restore limits](../../docs/handler.md#lifecycle-tables) for undeclared unique errors and concurrent restores.
+
+The API process is fully trusted. SQL on its connection can rewrite the request claims value.
+`deleted_by` is attribution, not proof. Lifecycle graph operations require READ COMMITTED;
+an earlier snapshot can miss a related row committed since it began.
+
+### Lifecycle and indexes
+
+Every SELECT policy on a lifecycle table carries the guard `(deleted_at IS NULL)`, except the lifecycle role's own and a
+`manage` ALL policy. PostgreSQL evaluates a policy qual before any of the query's own conditions whose operator function
+is not `leakproof`, so such a condition cannot be an index condition below it. Measured on PostgreSQL 16, 100k and 500k
+rows, one read per operator (`scripts/bench/lifecycle-read-guard.py`), generic and custom plans alike:
+
+| operator (function) | leakproof | read whose policy was `true` | with the guard |
+| --- | --- | --- | --- |
+| `slug = $1` (`texteq`), `id = ANY($1)` (`int4eq`) | yes | index condition | index condition, unchanged |
+| `tags @> $1` (`arraycontains`) | no | GIN, 1.7 ms at 500k | sequential scan, 41.8 ms |
+| `meta @> $1` (`jsonb_contains`) | no | GIN, 1.0 ms at 500k | sequential scan, 44.6 ms |
+| `title ILIKE $1` (`texticlike`, trigram) | no | GIN, 1.0 ms at 500k | sequential scan, 92.8 ms |
+| `body_tsv @@ $1` (`ts_match_vq`) | no | GIN, 1.0 ms at 500k | sequential scan, 36.4 ms |
+
+At 100k the same four went from 100 to 300 buffers to about 2,700 (0.15 to 0.7 ms to 12 to 48 ms).
+Only a read whose policy was `true` before lifecycle regresses (a public read, or a role read with no condition).
+A read that already had its own condition (an owner or `sql` read) used a sequential scan for these operators
+before lifecycle too, so the guard changes nothing there. A partial index `WHERE deleted_at IS NULL` did not help.
+A role whose policy has no guard keeps the index.
+
+For a hot search over a lifecycle table with one of those operators, give the search a role whose read has no guard
+and filter deleted rows yourself:
+
+```typescript
+abilities: [
+  can('read'),                                           // guarded: live rows only
+  can('read', { role: 'lookup_role', deleted: 'include' }), // no guard: live and deleted rows, index usable
+  can('read', { role: 'trash_role', deleted: 'only' }),     // (deleted_at IS NOT NULL): a trash view
+]
+```
+
+`deleted` works only on `can('read', { role })` of a lifecycle model and changes only that role's read policy; its
+`sql`, `where` and `columns` still apply. `'include'` means the role's queries must add `deleted_at IS NULL`
+themselves when they want live rows (a leakproof `IS NULL` costs nothing). A role cannot have both a guarded read and
+a `deleted` read: they would compile to the same policy, and `defineModel`'s compile refuses that. A column read may
+list `deletedAt` (every reader sees it); `deletedBy`, `deletedBatch` and `deletedXid` stay unlistable.
+`deleted` is for a named internal role: `defineModel` refuses it for `anon`, `authenticated` and `public`.
+A `deleted` read with no `columns` is granted SELECT on every column except `deleted_by`, `deleted_batch` and
+`deleted_xid`, not the whole table, so the role cannot read who deleted a row, even with plain SQL. A role that must see
+who deleted uses `manage`; a `manage` or a `privileges` SELECT for the same role grants the whole table.
+`db:plan` says `⚠ ACCESS — role <r> can read deleted rows of <table>` when it adds or changes such a policy.
+Where the searching role is shared with other reads, use a `SECURITY DEFINER` lookup function owned by such a role,
+whose body adds `deleted_at IS NULL` itself, schema-qualifies every table, pins `search_path`, and is granted EXECUTE
+only to the roles that may search.
+
+### Purge
+
+Import `purgeExpired` and `ENSURE_PURGE_LOG_SQL` from `@everystack/server/purge`.
+On the trusted owner connection, run the ensure statements before the first purge.
+Pass the ops Drizzle database, the full linked model set, and `{ after, batch }`.
+`after` is positive retention in milliseconds; `batch` bounds the rows physically removed across all tables.
+The executor must read those tables and the ledger, and be allowed to SET ROLE to `everystack_lifecycle`
+(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.
+
+### 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. 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', {
+  fields: { id: field.uuid().primaryKey() },
+  relations: {
+    recent: hasMany('comments', 'postId', { orderBy: [{ field: 'createdAt', order: 'desc' }], limit: 5, where: { approved: true } }),
+    pinned: hasOne('comments', 'postId', { where: { pinned: true } }),
   },
 });
+// After linkModels:
+//   recent.orderBy = [{ field: 'createdAt', order: 'desc' }, { field: 'id', order: 'asc' }]
+//   pinned.orderBy = [{ field: 'id', order: 'asc' }]
 ```
 
+- **`orderBy`** names fields of the TARGET model. `linkModels` checks them and normalizes the list once: it appends the target's primary key, ascending, as the tie-breaker (every key column, for a composite key), so two rows never tie. A key column you list keeps its place and direction and is not added again. A `hasMany` with no `orderBy` gets no order, as before.
+- **`limit`** is a positive integer. `hasOne` takes none: it is one row.
+- **`where`** is an equality map over target fields, the same semantics as the admin `ResourceConfig.where`: equality only, and `null` means `IS NULL`. Values are a string, a finite number, a boolean or `null`. It is a display filter, **not access control**: what a role may read is its abilities (RLS).
+- **`hasOne`** is the first target row whose `column` points back at this row, in `orderBy`. With no `orderBy` that is the target's primary key, ascending; an explicit `orderBy` gets the key appended. It takes no `dependent` (declare it on a `hasMany` over the same column) and no `limit`.
+- Errors name the relation. The shape (an empty `orderBy`, a direction other than `'asc'`/`'desc'`, a field listed twice, a `limit` of `0`, a non-scalar `where` value) is refused at `defineModel`. A field the target does not have is refused by `linkModels` (`orderBy field 'craetedAt' is not a field of model 'comments'`), as is an `orderBy` or `hasOne` over a target with no primary key.
+- In the generated `schema.generated.ts` a `hasOne` is `one(target)`: the inverse of the target's `belongsTo`, as `many(target)` is for a `hasMany`. The target declares that `belongsTo`. A `hasOne` between two tables joined by more than one foreign key is refused by `db:generate` for now: drizzle cannot pair a `one()` by name alone.
+- **Drizzle `with` ignores the display options.** Drizzle relations carry no order, limit or filter, so your own `db.query.posts.findMany({ with: { recent: true } })` returns every comment, unordered, and `with: { pinned: true }` returns any one of the post's comments, pinned or not. In your own queries put the filter, order and limit in the query (`with: { comments: { where, orderBy, limit } }`). The API handler does this for you (next bullet). The generated schema marks each such relation with a one-line comment; a relation that declares none gets no comment.
+- **The API handler applies `orderBy`, `limit` and `where` to a `hasMany` embed, per parent.** `GET /posts?select=*,recent(*)` returns each post's own five newest approved comments, on both read paths (see `docs/handler.md`, `relations`). `deriveHandlerConfig` hands them over in schema-property terms. A `hasOne` is handed over as `hasOne: true` with its normalized `orderBy` and its `where`, and embeds as one object or `null` (`GET /posts?select=*,pinned(*)`). The database chooses the row by that order, so it is never an arbitrary one.
+
 ## Compile
 
 `@everystack/model` is the declaration surface; `@everystack/cli` is the compiler. With your `models` array:
@@ -202,12 +486,13 @@ The same compiler the CLI uses is importable for your own CI and tests — point
 ```typescript
 import {
   compileMigration, generateMigrationSql, introspectSchema, diffSchema,   // data layer
+  compileDeclaredState,                                                     // the declared state of the set
   compileTableContract, introspectContract, diffContracts,                 // authz layer
   buildOwnerProbeSql, evaluateOwnerProbe,                                   // owner-isolation red-team
 } from '@everystack/cli/model';
 ```
 
-- **Data** — `introspectSchema(run)` reads the whole DB; `diffSchema(desired, current)` / `generateMigrationSql(models, current)` produce the structural delta. A green `db:generate` is this returning empty.
+- **Data** — `introspectSchema(run)` reads the whole DB; `diffSchema(desired, current)` / `generateMigrationSql(models, current)` produce the structural delta. A green `db:generate` is this returning empty. For `desired`, use `compileDeclaredState(models, { schema }).snapshot`, not a `compileTableSchema` call per Model: the set derives parts no one Model carries (the hasMany `ON DELETE`, the generated lifecycle FK indexes), and a per-Model loop reads those live objects as drops.
 - **Authz** — `compileTableContract(model)` is the declared RLS/grants; `introspectContract(run)` is what's live; `diffContracts(declared, live)` is the drift audit (`db:authz:diff`).
 - **Red-team** — `buildOwnerProbeSql` / `evaluateOwnerProbe` drive two JWT identities per owner-scoped table to catch IDOR (`db:authz:owner`).
 

package/package.json

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

package/src/can.ts

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

package/src/constraints.ts

@@ -12,6 +12,7 @@
 
 import type { RawSql } from './raw-sql';
 import type { ReferentialAction } from './field';
+import { externalTableRef, type ExternalTableRef } from './external';
 
 export type TableConstraint =
   /** `UNIQUE (a, b)` over two or more field keys — the composite the field builder can't carry. */
@@ -28,7 +29,15 @@ export type TableConstraint =
    * `.references()` can't carry. Local field keys, a model thunk for the target, and the target's
    * field keys; optional `onDelete`/`onUpdate` referential actions.
    */
-  | { kind: 'foreignKey'; columns: string[]; references: () => unknown; refColumns: string[]; onDelete?: ReferentialAction; onUpdate?: ReferentialAction; constraintName?: string;
+  | { kind: 'foreignKey'; columns: string[];
+      /** The target model thunk. Absent exactly when {@link external} is set. */
+      references?: () => unknown;
+      /**
+       * The target as a table NO model declares: `foreignKey(cols, { schema, table }, refColumns)`.
+       * Then `refColumns` are PostgreSQL column names, taken verbatim. See external.ts.
+       */
+      external?: ExternalTableRef;
+      refColumns: string[]; onDelete?: ReferentialAction; onUpdate?: ReferentialAction; constraintName?: string;
       /** `validate: false` — see {@link foreignKey}. Stored only when FALSE; the default
        *  (validate against the rows already there) is the absence of the field. */
       validate?: boolean };
@@ -100,6 +109,11 @@ export function assertCheckNames(table: string, constraints: readonly TableConst
  * target columns are explicit (a composite FK references a composite key, not just the PK), and
  * the referential actions ride here the same way they ride on `.references()`.
  *
+ * A table no model declares is named as an object, the composite twin of the external
+ * `.references({ schema, table, column })`: `foreignKey(['orgId', 'teamId'], { schema: 'auth',
+ * table: 'teams' }, ['org_id', 'team_id'])`. The reference columns are then PostgreSQL column
+ * names, verbatim (there is no model whose field keys they could be).
+ *
  * `validate: false` means the same thing it means on `.references()` — "enforce forward,
  * grandfather legacy": the key is installed `NOT VALID` and is never asked to prove itself
  * against the rows that were already there. See {@link FieldBuilder.references} for the whole
@@ -107,14 +121,18 @@ export function assertCheckNames(table: string, constraints: readonly TableConst
  */
 export function foreignKey(
   columns: string[],
-  references: () => unknown,
+  references: (() => unknown) | ExternalTableRef,
   refColumns: string[],
   opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean },
 ): TableConstraint {
+  const call = `foreignKey(${columns.join(', ')})`;
+  if (typeof references !== 'function' && (references === null || typeof references !== 'object')) {
+    throw new Error(`${call}: the target is ${references === null ? 'null' : typeof references}; pass a model thunk or { schema, table }`);
+  }
   return {
     kind: 'foreignKey',
     columns,
-    references,
+    ...(typeof references === 'function' ? { references } : { external: externalTableRef(references, refColumns, call) }),
     refColumns,
     ...(opts?.onDelete ? { onDelete: opts.onDelete } : {}),
     ...(opts?.onUpdate ? { onUpdate: opts.onUpdate } : {}),