@everystack/model 0.4.22 → 0.4.23

package/CHANGELOG.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.22",
+  "version": "0.4.23",
   "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/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 } : {}),

package/src/dependents.ts

@@ -0,0 +1,168 @@
+/**
+ * hasMany `dependent` → the ON DELETE of the CHILD's foreign key.
+ *
+ * `hasMany(() => Comment, 'postId', { dependent: 'nullify' })` on posts says: deleting a post sets
+ * comments.post_id to NULL. The foreign key that does it belongs to comments, so the compiler
+ * gives the child's FK on `postId` the action `set null`, and a plan shows it as an ordinary FK
+ * change.
+ *
+ * The result is a property of the MODEL SET, never of a field spec. `relationDeleteActions(models)`
+ * is a pure function: it returns a map keyed by (child model, field key) and writes nothing. Every
+ * FK reader that holds the set consults it. A field builder shared by two children, or a child
+ * reused in two sets with different parents, therefore compiles per (set, child), and compiling
+ * one set never changes what another compiles to.
+ *
+ * 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.
+ *  - 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).
+ *  - The child must declare `.references()` to this model. A dependent never creates a foreign
+ *    key: the child file must show its own constraint.
+ *
+ * linkModels runs the same checks at load. With no dependent in the set the map is empty and no
+ * thunk is called.
+ */
+
+import type { ReferentialAction } from './field';
+import type { ModelDescriptor } from './model';
+import type { HasManyDependent, Relation } from './relations';
+
+const ACTION: Record<HasManyDependent, ReferentialAction> = { restrict: 'restrict', nullify: 'set null', cascade: 'cascade' };
+
+/** The derived ON DELETE per child model, per field key. Empty when the set declares no dependent. */
+export type DependentActions = ReadonlyMap<ModelDescriptor, ReadonlyMap<string, ReferentialAction>>;
+
+const nameOf = (m: ModelDescriptor): string => (!m.schema || m.schema === 'public' ? m.table : `${m.schema}.${m.table}`);
+
+/**
+ * Why an ON DELETE CASCADE into a lifecycle table is refused, and the fix. One text for every
+ * declaration site (a parent's hasMany, the child's own onDelete), so the reason cannot drift.
+ */
+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; `
+    + `to soft-delete the children with their parent, make the parent lifecycle: true and declare hasMany { dependent: 'cascade' } on it`
+  );
+}
+
+/**
+ * Validate every dependent in the set and return the actions it implies. Pure: nothing is written.
+ * `targetOf` resolves a thunk; linkModels passes one that knows the names it has resolved but not
+ * yet bound, so an error leaves nothing half-linked.
+ */
+export function relationDeleteActions(
+  models: readonly ModelDescriptor[],
+  targetOf: (thunk: () => unknown) => ModelDescriptor = (thunk) => thunk() as ModelDescriptor,
+): DependentActions {
+  // Keyed by (child, field key); `site`/`dependent` name the relation for a later disagreement.
+  const planned = new Map<ModelDescriptor, Map<string, { onDelete: ReferentialAction; site: string; dependent: string }>>();
+  for (const parent of new Set(models)) {
+    for (const [name, rel] of Object.entries(parent.relations) as Array<[string, Relation]>) {
+      if (rel.dependent === undefined) continue;
+      const dependent = rel.dependent;
+      const site = `model '${nameOf(parent)}': relation '${name}'`;
+      const at = `${site} declares dependent '${dependent}'`;
+      if (rel.kind !== 'hasMany' || !Object.hasOwn(ACTION, dependent)) {
+        // defineModel refuses these shapes; a hand-edited descriptor still never compiles.
+        throw new Error(`${at}, which is not a hasMany 'restrict', 'nullify' or 'cascade'`);
+      }
+      const child = targetOf(rel.target);
+      const where = `${nameOf(child)}.${rel.column}`;
+      const f = child.fields[rel.column];
+      if (!f) throw new Error(`${at}, but model '${nameOf(child)}' has no field '${rel.column}'`);
+      const spec = f.spec;
+
+      if (!spec.references) {
+        if (spec.referencesExternal) {
+          const ext = spec.referencesExternal;
+          throw new Error(
+            `${at}, but ${where} references '${ext.schema}.${ext.table}', not '${nameOf(parent)}': `
+            + `declare .references() on ${where} to this model (dependent never creates a foreign key)`,
+          );
+        }
+        const covering = child.constraints.find((c) => c.kind === 'foreignKey' && c.columns.includes(rel.column));
+        if (covering && covering.kind === 'foreignKey') {
+          throw new Error(
+            `${at}, but ${where} is covered by a table-level foreignKey(${covering.columns.join(', ')}): `
+            + 'dependent applies only to a field .references(); declare onDelete on that foreignKey(...) instead',
+          );
+        }
+        throw new Error(
+          `${at}, but ${where} has no foreign key to '${nameOf(parent)}': `
+          + `declare .references() on ${where} (dependent never creates a foreign key)`,
+        );
+      }
+      const referenced = targetOf(spec.references);
+      if (referenced !== parent) {
+        throw new Error(
+          `${at}, but ${where} references '${nameOf(referenced)}', not '${nameOf(parent)}': `
+          + `declare .references() on ${where} to this model (dependent never creates a foreign key)`,
+        );
+      }
+      const pk = parent.primaryKey[0] ?? 'id';
+      if (rel.references !== undefined && rel.references !== pk) {
+        throw new Error(
+          `${at} with references '${rel.references}', but ${where}'s foreign key points at the primary key '${pk}': `
+          + 'dependent needs the relation to join on that key',
+        );
+      }
+      if (dependent === 'nullify' && spec.isNotNull) {
+        throw new Error(
+          `${at}, but ${where} is NOT NULL: ON DELETE SET NULL would fail on every delete; `
+          + "make the field nullable or use dependent 'restrict'",
+        );
+      }
+
+      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'`,
+        );
+      }
+
+      // 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];
+      const forChild = planned.get(child) ?? new Map();
+      const earlier = forChild.get(rel.column);
+      if (earlier && earlier.onDelete !== onDelete) {
+        throw new Error(
+          `${at} (ON DELETE ${onDelete.toUpperCase()}), but ${earlier.site} declares dependent '${earlier.dependent}' `
+          + `for the same foreign key ${where}: they disagree`,
+        );
+      }
+      if (spec.onDelete !== undefined && spec.onDelete !== onDelete) {
+        throw new Error(
+          `${at} (ON DELETE ${onDelete.toUpperCase()}), but model '${nameOf(child)}': field '${rel.column}' `
+          + `declares onDelete '${spec.onDelete}': they disagree; declare one, or make them agree`,
+        );
+      }
+      if (!earlier) forChild.set(rel.column, { onDelete, site, dependent });
+      planned.set(child, forChild);
+    }
+  }
+  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;
+}

package/src/derive.ts

@@ -23,15 +23,24 @@ export interface RelationConfig {
   from: string;
   to: string;
   many?: boolean;
+  /** To-one from the parent side: the first target row in `orderBy` order, or null. */
+  hasOne?: true;
+  orderBy?: Array<{ column: string; order: 'asc' | 'desc' }>;
+  limit?: number;
+  where?: Record<string, string | number | boolean | null>;
 }
 
 export interface DerivedHandlerConfig {
   exposedTables: string[];
   hiddenColumns: Record<string, string[]>;
+  /** Plain manage roles that may read lifecycle metadata; private fields stay hidden. */
+  hiddenColumnsExceptRoles?: Record<string, string[]>;
   protectedFields: Record<string, string[]>;
   /** `exceptRoles` is present only when a `can('manage', { role })` exists for the table. */
   rowOwnership: Record<string, { column: string; userField: string; exceptRoles?: string[] }>;
-  softDelete: { tables: string[] };
+  /** `lifecycle` (present only when a lifecycle model exists) lists the `lifecycle: true` tables;
+   *  each is also in `tables`, so the read filter applies to it. */
+  softDelete: { tables: string[]; lifecycle?: string[] };
   relations: Record<string, Record<string, RelationConfig>>;
   hooks: Record<string, ModelHooks>;
 }
@@ -50,9 +59,11 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
   linkModels(models);
   const exposedTables: string[] = [];
   const hiddenColumns: Record<string, string[]> = {};
+  const hiddenColumnsExceptRoles: Record<string, string[]> = {};
   const protectedFields: Record<string, string[]> = {};
   const rowOwnership: DerivedHandlerConfig['rowOwnership'] = {};
   const softDeleteTables: string[] = [];
+  const lifecycleTables: string[] = [];
   const relations: Record<string, Record<string, RelationConfig>> = {};
   const hooks: Record<string, ModelHooks> = {};
 
@@ -79,6 +90,13 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
     // The first owner-shaped ability → the handler's rowOwnership IDOR backstop.
     // (RLS, compiled from the same ability in Phase 1, is the primary enforcement;
     // this is the HTTP-path guard. A model's owner abilities share one column.)
+    const exceptRoles = [
+      ...new Set(
+        model.abilities
+          .filter((a) => a.action === 'manage' && isPlainRole(a.condition))
+          .map((a) => a.condition.role as string),
+      ),
+    ];
     const ownerAbility = model.abilities.find((a) => a.condition.owner);
     if (ownerAbility) {
       rowOwnership[table] = {
@@ -90,19 +108,20 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       // counts: a role-scoped update or delete alone does not lift it, and neither does a
       // manage ability with any other condition, which narrows what RLS lets it write
       // (fail closed: a whitelist of `role`, not a blacklist of the rest).
-      const exceptRoles = [
-        ...new Set(
-          model.abilities
-            .filter((a) => a.action === 'manage' && isPlainRole(a.condition))
-            .map((a) => a.condition.role as string),
-        ),
-      ];
       if (exceptRoles.length) rowOwnership[table].exceptRoles = exceptRoles;
     }
 
     // Declared, not inferred — one `softDelete` decision drives both the API filter and the
     // RLS guard, so the two can never disagree about what a soft-deleted row is.
     if (model.softDelete) softDeleteTables.push(table);
+    // A lifecycle table soft-deletes in the database (its delete trigger); the handler reads it as
+    // a soft-delete table and drives that machinery instead of writing deleted_at itself.
+    if (model.lifecycle) {
+      softDeleteTables.push(table);
+      lifecycleTables.push(table);
+      hiddenColumns[table] = [...new Set([...(hiddenColumns[table] ?? []), 'deletedBy', 'deletedBatch', 'deletedXid'])];
+      hiddenColumnsExceptRoles[table] = exceptRoles;
+    }
 
     if (model.hooks) hooks[table] = model.hooks;
 
@@ -112,7 +131,18 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       for (const name of relationNames) {
         const rel = model.relations[name];
         const target = rel.target();
-        if (rel.kind === 'belongsTo') {
+        if (rel.kind === 'hasOne') {
+          // this.<pk> → target.<column>, one row. linkModels normalized the orderBy: it always
+          // ends with the target's key, so the handler chooses the same row every time.
+          resolved[name] = {
+            table: target.table,
+            from: rel.references ?? primaryKeyOf(model),
+            to: rel.column,
+            hasOne: true,
+            orderBy: (rel.orderBy ?? []).map((t) => ({ column: t.field, order: t.order })),
+          };
+          if (rel.where) resolved[name].where = { ...rel.where };
+        } else if (rel.kind === 'belongsTo') {
           // this.<column> → target.<pk>
           resolved[name] = {
             table: target.table,
@@ -127,18 +157,23 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
             to: rel.column,
             many: true,
           };
+          // Model field names are the schema property names the handler resolves.
+          if (rel.orderBy) resolved[name].orderBy = rel.orderBy.map((t) => ({ column: t.field, order: t.order }));
+          if (rel.limit !== undefined) resolved[name].limit = rel.limit;
+          if (rel.where) resolved[name].where = { ...rel.where };
         }
       }
-      relations[table] = resolved;
+      if (Object.keys(resolved).length) relations[table] = resolved;
     }
   }
 
   return {
     exposedTables,
     hiddenColumns,
+    ...(lifecycleTables.length ? { hiddenColumnsExceptRoles } : {}),
     protectedFields,
     rowOwnership,
-    softDelete: { tables: softDeleteTables },
+    softDelete: { tables: softDeleteTables, ...(lifecycleTables.length ? { lifecycle: lifecycleTables } : {}) },
     relations,
     hooks,
   };