@palbase/backend 38.0.16 → 39.0.0

package/docs/README.md

@@ -82,7 +82,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 38.
+> and will not compile against `@palbase/backend` 39.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 

package/docs/database.md

@@ -455,6 +455,85 @@ const rows = await Database.$query(
 A JavaScript array parameter is encoded as a Postgres array literal, so
 `= ANY($1::uuid[])` works.
 
+**Do not reach for `$query` to take a lock.** That is the single most common
+reason this escape hatch gets used, and there are typed primitives for it —
+see the next section.
+
+### Locks — `$lockRows`, `$lockRowsWhere`, `$advisoryXactLock`, `lock: "update"`
+
+Four surfaces, for four different things.
+
+**`Database.$lockRows(table, ids)` — lock these rows, and let the layer order
+them.** You declare the set you are about to touch; the ordering is not yours to
+choose. Trusting the caller's order means two callers entering the same two rows
+in opposite orders, and the bill for a deadlock is not cheap: `deadlock_timeout`
+defaults to **1 second**, so the loser waits a full second before it errors.
+
+```ts
+await Database.$lockRows("accounts", [input.from, input.to]);
+```
+
+It de-duplicates and sorts the ids, then emits
+`SELECT pk … WHERE pk IN (…) ORDER BY pk FOR NO KEY UPDATE` — the same lock mode
+`updateMany`'s CTE takes, because two write paths must share one order and one
+mode or each will wait on the other. It requires a single-column primary key and
+throws if the table has none. An empty list locks nothing and returns.
+
+**`Database.$lockRowsWhere(table, where, { mode })` — lock what a FILTER
+matches.** `$lockRows` asks you to enumerate the set. "Lock every pending entry
+on this account" cannot: the id list only comes out of a query, and the gap
+between that query and the lock is exactly the race the lock exists to close.
+This form selects and locks the set in ONE statement.
+
+```ts
+await Database.$lockRowsWhere("entries", { account_id: id, status: "pending" });
+const rows = await Database.$findMany("entries", { account_id: id, status: "pending" });
+```
+
+The filter is the ordinary one — same compiler as `findMany` and `updateMany`,
+so there is no second filter dialect and no `$query`. It emits
+`SELECT pk … WHERE … ORDER BY pk <lock clause>`, and that `ORDER BY pk` is the
+**same order `updateMany`'s CTE takes**: two transactions entering the same rows
+by different routes cannot take them in opposite orders. Measured against live
+Postgres in both directions.
+
+The lock MODE is yours, and it is deliberately not equalised with `updateMany`'s:
+
+| `mode` | Postgres clause | when |
+|---|---|---|
+| `"update"` (default) | `FOR UPDATE` | you are about to change these rows |
+| `"share"` | `FOR SHARE` | "nobody may change these while I read them" |
+| `"noKeyUpdate"` | `FOR NO KEY UPDATE` | `updateMany`'s own mode — non-key columns |
+
+Forcing everyone onto one mode would make a reader take a stronger lock than it
+needs. What prevents the deadlock is the ORDER, not the mode. An unrecognised
+mode is refused rather than quietly downgraded — a silently weaker lock is
+fail-open.
+
+Two refusals worth knowing before you reach for it: an **empty filter** is
+rejected (locking the whole table is not somewhere you should arrive by
+accident — every writer waits until your transaction ends), and a table with no
+single-column primary key is rejected, because the lock ORDER needs a key.
+
+**`Database.$advisoryXactLock(key)` — lock a NAME, not a row.** For work that
+has no row to lock: "only one statement close runs at a time", or serializing
+retries of the same idempotency key before reading its result.
+
+```ts
+await tx.$advisoryXactLock(`billing.close:${householdId}:${period}`);
+```
+
+The key is text; Postgres wants a 64-bit integer, so it is hashed with
+`hashtextextended` and **the text never enters the SQL**. Only the
+transaction-scoped family is offered (`pg_advisory_xact_lock`): Postgres releases
+it on commit or rollback, so it cannot be forgotten. The session-scoped version
+is deliberately absent — the connection returns to the pool with the lock still
+held, and the next request waits forever.
+
+**`select(where, { lock: "update" })` — a real `FOR UPDATE`**, inside a
+`$transaction` plan. Use it when the rows you want to lock are the rows you were
+about to select anyway.
+
 ### Bulk writes with a conflict rule
 
 Inside a transaction, `insertMany` takes an optional conflict rule — which is how

package/docs/llms-full.txt

@@ -90,7 +90,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 38.
+> and will not compile against `@palbase/backend` 39.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -1589,6 +1589,85 @@ const rows = await Database.$query(
 A JavaScript array parameter is encoded as a Postgres array literal, so
 `= ANY($1::uuid[])` works.
 
+**Do not reach for `$query` to take a lock.** That is the single most common
+reason this escape hatch gets used, and there are typed primitives for it —
+see the next section.
+
+### Locks — `$lockRows`, `$lockRowsWhere`, `$advisoryXactLock`, `lock: "update"`
+
+Four surfaces, for four different things.
+
+**`Database.$lockRows(table, ids)` — lock these rows, and let the layer order
+them.** You declare the set you are about to touch; the ordering is not yours to
+choose. Trusting the caller's order means two callers entering the same two rows
+in opposite orders, and the bill for a deadlock is not cheap: `deadlock_timeout`
+defaults to **1 second**, so the loser waits a full second before it errors.
+
+```ts
+await Database.$lockRows("accounts", [input.from, input.to]);
+```
+
+It de-duplicates and sorts the ids, then emits
+`SELECT pk … WHERE pk IN (…) ORDER BY pk FOR NO KEY UPDATE` — the same lock mode
+`updateMany`'s CTE takes, because two write paths must share one order and one
+mode or each will wait on the other. It requires a single-column primary key and
+throws if the table has none. An empty list locks nothing and returns.
+
+**`Database.$lockRowsWhere(table, where, { mode })` — lock what a FILTER
+matches.** `$lockRows` asks you to enumerate the set. "Lock every pending entry
+on this account" cannot: the id list only comes out of a query, and the gap
+between that query and the lock is exactly the race the lock exists to close.
+This form selects and locks the set in ONE statement.
+
+```ts
+await Database.$lockRowsWhere("entries", { account_id: id, status: "pending" });
+const rows = await Database.$findMany("entries", { account_id: id, status: "pending" });
+```
+
+The filter is the ordinary one — same compiler as `findMany` and `updateMany`,
+so there is no second filter dialect and no `$query`. It emits
+`SELECT pk … WHERE … ORDER BY pk <lock clause>`, and that `ORDER BY pk` is the
+**same order `updateMany`'s CTE takes**: two transactions entering the same rows
+by different routes cannot take them in opposite orders. Measured against live
+Postgres in both directions.
+
+The lock MODE is yours, and it is deliberately not equalised with `updateMany`'s:
+
+| `mode` | Postgres clause | when |
+|---|---|---|
+| `"update"` (default) | `FOR UPDATE` | you are about to change these rows |
+| `"share"` | `FOR SHARE` | "nobody may change these while I read them" |
+| `"noKeyUpdate"` | `FOR NO KEY UPDATE` | `updateMany`'s own mode — non-key columns |
+
+Forcing everyone onto one mode would make a reader take a stronger lock than it
+needs. What prevents the deadlock is the ORDER, not the mode. An unrecognised
+mode is refused rather than quietly downgraded — a silently weaker lock is
+fail-open.
+
+Two refusals worth knowing before you reach for it: an **empty filter** is
+rejected (locking the whole table is not somewhere you should arrive by
+accident — every writer waits until your transaction ends), and a table with no
+single-column primary key is rejected, because the lock ORDER needs a key.
+
+**`Database.$advisoryXactLock(key)` — lock a NAME, not a row.** For work that
+has no row to lock: "only one statement close runs at a time", or serializing
+retries of the same idempotency key before reading its result.
+
+```ts
+await tx.$advisoryXactLock(`billing.close:${householdId}:${period}`);
+```
+
+The key is text; Postgres wants a 64-bit integer, so it is hashed with
+`hashtextextended` and **the text never enters the SQL**. Only the
+transaction-scoped family is offered (`pg_advisory_xact_lock`): Postgres releases
+it on commit or rollback, so it cannot be forgotten. The session-scoped version
+is deliberately absent — the connection returns to the pool with the lock still
+held, and the next request waits forever.
+
+**`select(where, { lock: "update" })` — a real `FOR UPDATE`**, inside a
+`$transaction` plan. Use it when the rows you want to lock are the rows you were
+about to select anyway.
+
 ### Bulk writes with a conflict rule
 
 Inside a transaction, `insertMany` takes an optional conflict rule — which is how
@@ -2374,6 +2453,52 @@ export const orgs = defineTable("orgs", {
 });
 ```
 
+### Composite foreign keys — `foreignKeys`
+
+`.references()` on a column is single-column and single-target. Multi-tenant
+integrity usually wants more than that: the parent must not merely EXIST, it must
+belong to the same tenant. That is one constraint over two columns, and a
+per-column model cannot say it.
+
+```ts
+import { defineTable, foreignKey, uuid, bigint } from "@palbase/backend";
+
+export const settlements = defineTable("settlements", {
+  columns: {
+    id:           uuid().primaryKey().defaultRandom(),
+    household_id: uuid().notNull(),
+    entry_id:     uuid().notNull(),
+    amount:       bigint().notNull(),
+  },
+  foreignKeys: (c) => [
+    foreignKey("settlement_entry_household")
+      .on(c.col("household_id"), c.col("entry_id"))
+      .references(entries, "household_id", "id")
+      .onDelete("cascade"),
+  ],
+});
+```
+
+That emits `FOREIGN KEY (household_id, entry_id) REFERENCES entries (household_id, id)`:
+a settlement cannot point at another household's entry, and the database is what
+enforces it — under every escape hatch, for every writer.
+
+- **`.on(...)`** takes column references from the callback's context, so a typo is
+  a compile error. Order is preserved and matches `.references()` position by
+  position; a length mismatch is refused where you write it, not mid-deploy.
+- **`.references(table, ...cols)`** takes the table VALUE, not a thunk and not a
+  string — the target's column names are checked against its declaration.
+- **`.onUpdate(a)` / `.onDelete(a)`** — `"cascade"`, `"restrict"`, `"set null"`,
+  `"set default"`, `"no action"`.
+- **`.match("full")`** — with `MATCH SIMPLE` (the default) a single NULL among the
+  referencing columns skips the constraint entirely. `MATCH FULL` evaluates it
+  unless ALL of them are NULL. [`freeze`](#conditional-foreign-keys--freeze)
+  uses the SIMPLE escape on purpose; an ordinary FK usually does not want it.
+
+**The two forms do not displace each other.** This declaration is tracked under
+its own name; column-level ones are tracked as `<table>_<column>_fkey`. One table
+can carry both.
+
 ### Relation names
 
 Every foreign key produces **two** named relations, and the two names are derived
@@ -2543,7 +2668,8 @@ used to reject passed after the rename.
 
 ## Indexes
 
-`indexes` declares plain (non-unique) btree indexes over an ordered column list:
+`indexes` is a callback that receives the table's column context and returns
+`index(name)` builders — one non-unique btree index each:
 
 ```ts
 export const sessions = defineTable("sessions", {
@@ -2552,12 +2678,17 @@ export const sessions = defineTable("sessions", {
     room_id:    uuid().references(() => rooms.id),
     started_at: timestamp().defaultNow(),
   },
-  indexes: [
-    { name: "sessions_room_started_idx", columns: ["room_id", "started_at"] },
+  indexes: (c) => [
+    index("sessions_room_started_idx").on(c.col("room_id"), c.col("started_at")),
   ],
 });
 ```
 
+The older plain-object form — `indexes: [{ name, columns }]` — still typechecks
+and still means the same thing. The builder is what the rest of this section
+documents, because everything past a plain column list is only reachable
+through it.
+
 On deploy each entry becomes a statement of its own — `CREATE INDEX IF NOT
 EXISTS <name> ON <table> (<columns>)` — not a clause of the `CREATE TABLE`. The
 name and every column are identifier-validated before any SQL is built.
@@ -2570,50 +2701,348 @@ knowing before you name an index:
   names.
 - Removing an entry from `indexes` therefore does **not** drop the index. Drop it
   in an explicit [migration](./migrations.md).
-- Changing `columns` under a name that is already live does **nothing** — the
-  deploy matches the name, sees it, and skips. Give the new column list a NEW
-  name (and drop the old index in a migration if you want it gone).
+- Changing an index that is already live does **nothing** — the deploy matches
+  the name, sees it, and skips. This is the whole definition, not just the
+  columns: edit `.where(…)`, `.onExpression(…)`, `.include(…)` or the sort under
+  a live name and the database keeps the old index, silently. Give the new
+  definition a NEW name (and drop the old index in a migration if you want it
+  gone).
 
-### Scope: plain btree over columns, nothing else
+### Scope
 
-`indexes` models exactly one kind of index. It cannot express:
+The builder covers btree indexes, including the shapes that need a predicate or
+an expression:
 
 | what you want | declare it with |
 |---------------|-----------------|
-| a UNIQUE index | `unique: [{ name, columns }]` on the table |
-| a partial index (`WHERE …`) | `raw()` |
-| an expression index (`lower(email)`, …) | `raw()` |
-| any other method (`gin`, `gist`, `hnsw`, …) | `raw()` |
-
-The limit is deliberate, not an oversight. Comparing a partial predicate or an
-expression against the live database needs the same round-trip through Postgres'
-own deparse that `checks` uses; without it an edited predicate would silently do
-nothing. Rather than ship a half-working partial-index path, the typed field
-stays columns-only and `raw()` carries the rest:
+| a multi-column index | `index("i").on(c.col("a"), c.col("b"))` |
+| a partial index (`WHERE …`) | `index("i").on(c.col("a")).where(c.col("status").eq("pending"))` |
+| an expression index (`lower(email)`, …) | `index("i").onExpression("lower(email)")` |
+| a covering index (`INCLUDE …`) | `index("i").on(c.col("a")).include(["b", "c"])` |
+| a sort that matches an `ORDER BY` | `index("i").on(c.col("a")).desc().nulls("last")` |
+| a UNIQUE **constraint** | `unique: [{ name, columns }]` on the table |
+| a UNIQUE **index** | `index("i").unique().on(c.col("a"))` |
+| a **partial UNIQUE** index | `index("i").unique().on(c.col("a")).where(…)` |
+| another method (`gin`, `gist`, `brin`, `hash`), an opclass, `CONCURRENTLY` | `raw()` |
+
+`.where()` takes the same typed predicate language as `policy().using()`, so
+column names are checked at compile time. `.onExpression()` takes SQL text and
+emits it verbatim — the same trust posture as `policy().using("…")`.
+
+**Both are checked against the live database before the push, not during it.**
+Every declared predicate and expression is probed twice: once as a prepared
+statement, and once as a real `CREATE INDEX` on an empty `LIKE` clone of the
+table. The second probe is the one that matters — an index predicate has rules a
+`SELECT` does not, so `where(p.existsIn(…))` (writable at the type level) and a
+non-`IMMUTABLE` function are both refused at push time instead of failing
+halfway through an apply.
+
+**`.unique()` composes with everything else on the builder**, which is what makes
+the partial-unique shape declarative. `unique: [{ name, columns }]` produces a
+UNIQUE *constraint*, and a constraint cannot carry a `WHERE`; `index()` could
+carry the `WHERE` but could not be unique. Those were two halves that never met.
 
 ```ts
-import { defineTable, raw, uuid, text, timestamp } from "@palbase/backend";
+import { defineTable, index, uuid, text, timestamp } from "@palbase/backend";
 
 export const orders = defineTable("orders", {
   columns: {
-    id:         uuid().primaryKey().defaultRandom(),
-    status:     text().notNull(),
-    created_at: timestamp().defaultNow(),
+    id:          uuid().primaryKey().defaultRandom(),
+    status:      text().notNull(),
+    external_id: text().nullable(),
+    created_at:  timestamp().defaultNow(),
+  },
+  indexes: (c) => [
+    // Partial index.
+    index("orders_pending_idx").on(c.col("created_at")).where(c.col("status").eq("pending")),
+    // Partial UNIQUE: NULLs stay free, non-NULLs are unique. No `raw()`.
+    index("orders_external_id_idx")
+      .unique()
+      .on(c.col("external_id"))
+      .where(c.col("external_id").isNull(true)),   // isNull(true) is IS NOT NULL
+  ],
+});
+```
+
+Reach for `unique:` when you want a named CONSTRAINT (something a foreign key can
+reference); reach for `index().unique()` when you want a unique INDEX, which is
+the only one of the two that can be partial.
+
+### `raw()` — the last resort, and it takes TWO arguments
+
+```ts
+raw("<name>", "<sql>")
+```
+
+Most of what this list used to carry is declarative now, and the typed field is
+the one to reach for — it is diffed, checked against the live database before the
+push, and its errors arrive in your editor instead of halfway through an apply:
+
+| you used to write `raw()` for | write instead |
+|---|---|
+| a CHECK constraint | [`checks`](#checks) — string or typed `check()` |
+| a partial / expression / covering index | [`index()`](#indexes) |
+| a partial UNIQUE index | `index("i").unique().where(…)` |
+| a composite FOREIGN KEY | [`foreignKeys`](#composite-foreign-keys--foreignkeys) |
+| a conditional FK ("frozen while …") | [`freeze`](#conditional-foreign-keys--freeze) |
+| a trigger that refuses a write | [`guards`](#guards--refusing-a-write-in-your-own-words) |
+| a one-off data fix | [`backfills`](#backfills--a-data-fix-that-runs-once) |
+| dropping a constraint | [`dropConstraints`](#dropping-a-constraint--dropconstraints) |
+
+What is left for `raw()`: an index method other than btree (`gin`, `gist`,
+`brin`, `hash`), an opclass, `CONCURRENTLY`, `EXCLUDE` constraints, views, and
+PL/pgSQL functions.
+
+**There is no `down`, and no teardown option of any kind.** One used to be
+accepted; it was carried into a generated `Down` that NOTHING ever ran, so an
+author who wrote one believed they had a rollback they did not have. Drop what a
+`raw()` created by declaring the drop as its own `raw()`.
+
+`up` is emitted verbatim, and the body is **read before the push, not trusted
+blindly**: a body that reaches past what a schema declaration is allowed to do is
+refused up front rather than part-way through an apply. How a CHANGED body is
+treated depends on what the name addresses:
+
+- **The name addresses a constraint or an index.** Tracked by
+  NAME only — the deploy sees the catalog object and skips, so an edited body
+  does nothing. Give it a new name, or drop and re-add it explicitly.
+- **The name addresses nothing in the catalog** (functions, triggers, grants,
+  compound statements). The last applied body is recorded in
+  `public.palbase_raw_objects` inside the same DDL transaction, and an edited
+  body **is** re-applied. You do not need a new name to change a trigger.
+
+## Checks
+
+`checks` declares named CHECK constraints — the invariants the database itself
+enforces, under every escape hatch, for every writer:
+
+```ts
+export const transfers = defineTable("transfers", {
+  columns: {
+    id:               uuid().primaryKey().defaultRandom(),
+    from_account_id:  uuid().notNull(),
+    to_account_id:    uuid().notNull(),
+    debited_value:    bigint().notNull(),
+    credited_value:   bigint().notNull(),
   },
-  raw: [
-    raw(
-      "orders_pending_idx",
-      "CREATE INDEX IF NOT EXISTS orders_pending_idx ON orders (created_at) WHERE status = 'pending'",
-      { down: "DROP INDEX IF EXISTS orders_pending_idx" },
-    ),
+  checks: [
+    { name: "transfer_positive", expr: "debited_value > 0 AND credited_value > 0" },
+    { name: "transfer_distinct_accounts", expr: "from_account_id <> to_account_id" },
   ],
 });
 ```
 
-`raw()`'s `up` is emitted verbatim on the privileged DDL connection and, like
-`indexes`, is tracked by NAME only — a changed body needs a new name. Pass
-`down` yourself for an index: the default drop statement drops a *constraint*,
-and an index is not one.
+`expr` is trusted SQL emitted verbatim (the same posture as `policy().using()`);
+`name` is identifier-validated.
+
+**Or write the expression typed**, with `checks` as a callback and `check()`:
+
+```ts
+import { defineTable, check, bigint, text, uuid } from "@palbase/backend";
+
+export const transfers = defineTable("transfers", {
+  columns: {
+    id:             uuid().primaryKey().defaultRandom(),
+    debited_value:  bigint().notNull(),
+    currency:       text().nullable(),
+  },
+  checks: (c) => [
+    check("transfer_positive", c.col("debited_value").gt(0)),
+    check("transfer_currency_set", c.col("currency").isNull(true)),
+  ],
+});
+```
+
+Both forms are accepted and both land on the wire as the same string — the
+callback compiles the expression to SQL where you declare it. The difference is
+WHEN a mistyped column name answers you. In the string form `debited_vlaue > 0`
+comes back from Postgres during `ALTER TABLE … ADD CONSTRAINT`, in the MIDDLE of
+a deploy; in the typed form it is a compile error. The callback shape is what
+makes that possible: a plain array cannot be contextualised with the table's own
+column names.
+
+The typed expression is held to the CHECK context, which is NARROWER than a
+policy's. Postgres forbids subqueries in a CHECK, so `existsIn(…)` and
+`auth.uid()` are refused by `check()` where you write them — with a sentence
+saying what to use instead — rather than failing the apply. What is left is the
+part a CHECK can actually evaluate: columns, literals, comparisons, `and`/`or`,
+`not`, `isNull`.
+
+**Unlike indexes, checks are diffed by BODY, not just by name.** Editing an
+`expr` under a live name recreates the constraint (`DROP` + `ADD`) — which is
+what you want, and it is why you should reach for `checks` before `raw()` for
+anything a CHECK can express.
+
+That body compare works because the declared expression is round-tripped through
+Postgres' own parser and deparser before the diff: a scratch `NOT VALID`
+constraint carrying your text is added to the live table, `pg_get_constraintdef`
+is read back, and the scratch is dropped. Without it, `price > 0` would come
+back as `(price > 0)` and every deploy would re-drop and re-add every unchanged
+check forever.
+
+**What a CHECK cannot do:** reference another table. Postgres forbids subqueries
+in a CHECK, so a cross-table invariant is not a check. Three declarative places
+take that work instead, in order of how much they cost you:
+[`foreignKeys`](#composite-foreign-keys--foreignkeys) when the rule is "the
+parent exists and matches", [`freeze`](#conditional-foreign-keys--freeze) when it
+holds only while some condition does, and
+[`guards`](#guards--refusing-a-write-in-your-own-words) when the rule is a
+predicate no constraint can carry.
+
+## Conditional foreign keys — `freeze`
+
+"While a payment is `settled`, the invoice's amount and currency may not change."
+That is a foreign key that only applies part of the time, and it is declarative:
+
+```ts
+import { defineTable, freeze, bigint, text, uuid } from "@palbase/backend";
+
+export const payments = defineTable("payments", {
+  columns: {
+    id:       uuid().primaryKey().defaultRandom(),
+    status:   text().notNull(),
+    inv_id:   uuid().notNull(),
+    amount:   bigint().notNull(),
+    currency: text().notNull(),
+  },
+  freeze: (c) => [
+    freeze("pay_settled_inv")
+      .when(c.col("status").eq("settled"))
+      .columns("inv_id", "amount", "currency")
+      .references(invoices, "id", "amount", "currency"),
+  ],
+});
+```
+
+**It is not a trigger.** What gets created is a constraint: a UNIQUE on the
+parent's tuple, `STORED` generated columns on the child that are NULL while the
+condition is false, and an `ON UPDATE RESTRICT ON DELETE RESTRICT` foreign key
+over those. `MATCH SIMPLE`'s NULL escape — "a row with a NULL among the
+referencing columns need not satisfy the constraint" — is what gives you a
+conditional FK without a `WHERE`.
+
+Measured against live Postgres, that buys four behaviours a trigger would not:
+
+- while the condition does NOT hold, nothing is frozen — the row is ordinary;
+- a row whose columns do not match its parent **cannot be made `settled`**. The
+  reverse direction is closed too; a trigger guarding the parent would have left
+  it open;
+- a frozen row's columns cannot be changed, and its parent cannot be deleted;
+- when the condition lifts, the freeze **dissolves by itself**. Nothing has to
+  remember to release it.
+
+The chain ends at `.references()` on purpose: that is where the declaration is
+completed and checked, so a `freeze` missing its target cannot reach a table at
+all. `.columns()` and the target list must be the same length, and the frozen
+columns must be `NOT NULL` — a nullable one opens the same `MATCH SIMPLE` escape
+INDEPENDENTLY of your condition, which would mean the freeze silently never
+formed. The push refuses that declaration rather than shipping it.
+
+## Guards — refusing a write in your own words
+
+Some rules no constraint can carry: write-once fields, state-machine
+transitions, a cross-row check whose predicate is not immutable, a
+transaction-level total. RLS cannot express them either — `OLD` and `NEW` are not
+names a policy expression has, and `USING`/`WITH CHECK` are evaluated against two
+separate rows with no scope that puts them side by side.
+
+A guard is the narrow way to say it. **You write three things: which event, which
+condition, and what to say when refusing.**
+
+```ts
+import { defineTable, guard, text, uuid } from "@palbase/backend";
+
+export const documents = defineTable("documents", {
+  columns: {
+    id:     uuid().primaryKey().defaultRandom(),
+    status: text().notNull(),
+    body:   text().notNull(),
+  },
+  guards: (g) => [
+    guard("documents_frozen_body")
+      .on("update")
+      .when(g.col("status").eq("archived"))
+      .refuse("An archived document's body cannot be changed", { column: "body" }),
+  ],
+});
+```
+
+Everything else is a safe default and deliberately not on this surface: `BEFORE`,
+`FOR EACH ROW` (Postgres defaults to `STATEMENT`, which is wrong for a guard),
+`SECURITY INVOKER` — never `DEFINER` — a pinned `search_path`, an `UPDATE OF (…)`
+list derived from the columns your condition names, `IS DISTINCT FROM` for the
+change test (`<>` answers wrong on NULL), and the right `RETURN`. Exposing a knob
+turns it into a policy; these are not policies. There is also **no global escape
+hatch** — no session setting that lets a connection skip a guard.
+
+**The refusal is machine-readable.** It arrives with SQLSTATE `PB001` — not
+`23514`, which is a real CHECK violation and would be indistinguishable — the
+guard's NAME in the `CONSTRAINT` field and, if you gave one, the field name in
+`COLUMN`. A client branches on those without parsing your sentence. Measured on
+a live refusal: `constraint=documents_frozen_body · column=body`. `detail` and
+`hint` land in Postgres' fields of the same name.
+
+The name is required, and not for tidiness: Postgres runs triggers bound to one
+event **in alphabetical order by name**, and there is no other handle on ordering.
+
+For a cross-row rule, `.exists(table, row => …)` puts the predicate in an
+`EXISTS` block instead of the trigger's `WHEN` clause — Postgres does not allow a
+subquery in `WHEN`. Inside the callback, `row.col(…)` is the OTHER table's
+column; an unqualified column is the row being written.
+
+One shape is refused at push: an **`insert` guard cannot read a generated
+column**. They are empty in `NEW`, so the condition would silently never fire —
+fail-open on a refusal path.
+
+## Backfills — a data fix that runs once
+
+Adding a column is declarative. FILLING it is not. That work used to live inside
+a `raw()` block, which re-runs on every deploy, so it was either written
+defensively idempotent or run by hand with no record that it happened.
+
+```ts
+import { backfill, defineTable, text, uuid } from "@palbase/backend";
+
+export const ledger = defineTable("ledger", {
+  columns: {
+    id:       uuid().primaryKey().defaultRandom(),
+    currency: text().nullable(),
+  },
+  backfills: [
+    backfill("ledger_currency_try", "UPDATE ledger SET currency = 'TRY' WHERE currency IS NULL"),
+  ],
+});
+```
+
+It runs **after** the DDL, in its own phase and its own transaction, and **once
+per name**. The record lives in `public.palbase_backfills`, so "did this run?" is
+answered by the database rather than by memory.
+
+**The NAME is the record.** Keeping the name and editing the SQL does NOT produce
+a second run — to correct a backfill, give it a new name. That is also why an
+empty body is refused: it would register the name and burn it permanently, and
+the real SQL written later would never run and never complain. The registry is
+global, so two tables cannot declare the same backfill name.
+
+A plain array, not a callback: a backfill has no predicate to contextualise —
+its body is verbatim SQL.
+
+## Dropping a constraint — `dropConstraints`
+
+The diff is **additive**: a constraint that exists in the database but not in your
+declaration is never dropped. Your schema file adds objects; it does not own the
+database's. So a deliberate removal has to be SAID:
+
+```ts
+export const orders = defineTable("orders", {
+  columns: { /* … */ },
+  dropConstraints: ["orders_legacy_status_check"],
+});
+```
+
+This is the one exception to the additive rule, and requiring it in writing is
+the point — the alternative is a deploy that drops a constraint because someone
+deleted a line.
 
 ## Typed DB access — by default