@voltro/cli 0.33.0 → 0.35.0

package/templates/agent-docs/database/migrations.md

@@ -17,7 +17,7 @@ Voltro's migrator does not generate or apply migration files. Instead, on every
 2. **Diffs** that against your declared schema (every `*.entity.ts` / `*.schema.ts` file in the project plus the framework's bookkeeping tables).
 3. **Classifies** each pending DDL op into one of seven `OperationClass`es — `safe`, `needs-default`, `needs-backfill`, `needs-rename-annotation`, `lossy`, `online-required`, `multi-step`.
 4. **Refuses** to apply anything that can't be made safe automatically. The diff output tells you exactly which DSL annotation to add (`.backfill()`, `.renamedFrom()`, `dropped()`, …).
-5. **Applies** the rest under an advisory lock + records the result in `_voltro_migration_plans` with a fingerprint of the post-apply schema.
+5. **Applies** the rest under an advisory lock + records the result in `_voltro_migration_plans` with a fingerprint of the post-apply schema. On a dialect that cannot apply the whole plan in one transaction (MySQL / MariaDB / SQLite / Turso), each operation is also recorded in a **resume ledger** (`_voltro_migration_ops`) as it lands, so a crashed apply is continued rather than re-planned blind — see [multi-dialect](./multi-dialect.md).
 
 There are no generated SQL files to commit, no `migrations/` directory to rebase, no checksum manifest to repair. The source of truth is your schema TypeScript; the DB is the slave.
 
@@ -862,28 +862,36 @@ completed rows.
 <!-- source: en/database/migrations/multi-dialect.md -->
 ## Multi-dialect strategy
 
-_How the planner + applier behave across Postgres, MySQL, MariaDB, MSSQL, SQLite — the atomicity matrix, MySQL's implicit-commit landmine + re-diff-to-recover, SQLite's table-rewrite mechanic, plus the per-dialect DDL idioms the framework hides._
+_How the planner + applier behave across Postgres, MySQL, MariaDB, MSSQL, SQLite, Turso — the atomicity matrix, the resume ledger that carries a crashed apply on the non-transactional dialects, SQLite's table-rewrite mechanic, plus the per-dialect DDL idioms the framework hides._
 
 The planner produces ONE `MigrationPlan` regardless of dialect. The applier executes it per-dialect, dispatching through `sql.onDialectOrElse` for every emit + falling back to runtime probes when behaviour diverges. The same `voltro db apply` invocation against the same schema produces structurally identical results on every backend.
 
 What ISN'T uniform: **transactional DDL semantics**.
 
-| Dialect | Transactional DDL | Advisory-lock mechanism | Backfill in tx with DDL |
+| Dialect | Plan applied atomically | Advisory-lock mechanism | Recovery after a mid-plan crash |
 |---|---|---|---|
-| Postgres | ✓ all DDL atomic | `pg_advisory_lock(KEY)` | ✓ |
-| MSSQL | ✓ all DDL atomic | `sp_getapplock` | ✓ |
-| SQLite | ✓ all DDL atomic | process-local mutex | ✓ |
-| **MySQL / MariaDB** | **✗ implicit commit per DDL** | `GET_LOCK('voltro_migration', N)` | ✓ but SEPARATE from DDL |
+| Postgres | ✓ one transaction | `pg_advisory_lock(KEY)` | nothing to recover — rolled back |
+| MSSQL | ✓ one transaction | `sp_getapplock` | nothing to recover — rolled back |
+| **MySQL / MariaDB** | **✗ implicit commit per DDL** | `GET_LOCK('voltro_migration', N)` | resume ledger |
+| **SQLite / Turso** | **✗ per statement** | process-local mutex | resume ledger |
 
 This is the operationally heaviest cross-dialect difference. The rest of the page covers what changes.
 
-## Postgres / MSSQL / SQLite — transactional happy path
+**SQLite is on the non-atomic side, and the reason is Turso.** SQLite the engine *can* do transactional DDL. The applier does not use it, because SQLite and Turso share one dialect token and Turso rejects DDL inside its default transaction — the applier cannot wrap one without wrapping the other. Both therefore take the per-statement path and the resume ledger below.
+
+**On Postgres one class of operation is still not covered by the transaction:** `online-required` ops (`CREATE INDEX CONCURRENTLY`, the shadow-column type swap) are *rejected* inside a transaction, so they run after the commit. They are ledgered like a MySQL plan.
+
+## Postgres / MSSQL — transactional happy path
 
 A multi-step plan runs inside one `BEGIN ... COMMIT`. Mid-flight failure rolls EVERYTHING back; the next plan diff is identical to the pre-apply one. There's nothing to resume — re-running the apply re-runs the plan from scratch.
 
 The advisory-lock variants serialise concurrent applies — two operators running `voltro db apply` against the same DB at the same time go through serially.
 
-## MySQL / MariaDB — re-diff-to-recover territory
+**The lock is scoped to your configured schema.** With `DB_SCHEMA` set, the lock key (Postgres) / lock name (MySQL, MSSQL) is derived from the schema, so two apps sharing one database in different schemas do not serialise — or defer — each other's migrations and trigger repairs. Without `DB_SCHEMA` (or with `DB_SCHEMA=public`) every instance takes one stable framework-wide key, which is what makes a rolling deploy safe: old and new replicas contend on the same lock. On MySQL/MariaDB `GET_LOCK` is server-wide; setting `DB_SCHEMA` to your database name un-shares the lock between two apps on one server.
+
+**Transient DDL failures are retried, per the dialect's own predicate.** A `CREATE TABLE IF NOT EXISTS` that meets SQLite/Turso's schema lock (`database is locked` / `SQLITE_BUSY`), a MySQL lock-wait timeout, or a Postgres/MSSQL deadlock victim during the boot auto-migrate is retried with bounded attempts and exponential backoff instead of failing the boot on the first attempt — only statements that are safe to re-run, and on Postgres/MSSQL as a fresh transaction (their deadlock classes roll the whole transaction back). `VOLTRO_MIGRATION_DDL_RETRIES` moves the retry count (default 4; `0` disables).
+
+## MySQL / MariaDB / SQLite / Turso — the resume ledger
 
 Every DDL statement implicitly commits. A 5-op plan on MySQL is effectively 5 separate "atomic statements" with the prior ones already committed when a later one fails. If op 5 of 5 fails, ops 1–4 stay applied:
 
@@ -896,13 +904,36 @@ plan applying (mysql, env=prod):
   5. add-index audit_logs(actorId)          ✗  ER_DUP_KEYNAME
 ```
 
-There is NO `--resume` / `--abort` flag and NO per-op partial-status row — the applier records a `_voltro_migration_plans` row only on a fully successful apply. Recovery is to re-run the apply once the cause is fixed:
+The `_voltro_migration_plans` row is still written only on a fully successful apply — that row means "this schema is live", and a half-applied plan is not. What the applier DOES write as it goes is a per-operation **resume ledger**, `_voltro_migration_ops`:
+
+- every operation that will run outside a transaction is inserted `pending` **before any DDL runs**, so a crash on operation 1 still leaves the whole intended sequence on disk;
+- each row flips to `started` immediately before its statement and `applied` immediately after;
+- the rows are **deleted** once the apply converges and the plan row lands. The ledger is a work queue, not a history — the history is `_voltro_migration_plans.operations`.
+
+There is still no `--resume` / `--abort` flag, because there is nothing to choose. Recovery is to re-run the apply once the cause is fixed:
 
 ```sh
 voltro db apply
 ```
 
-`voltro db apply` re-introspects the live DB and diffs the declared schema against the (half-applied) live shape, so it emits ONLY the ops still missing — ops 1–4 are already in the DB and don't reappear in the diff. If someone finished op 5 out of band (psql, a corrective hot-fix), the re-diff sees it as present and skips it too. If the failed op is no longer the right answer because the schema was edited in response, the next `voltro db plan` already reflects the new declared shape — nothing to abort.
+The next apply finds the ledger, says so in the log, and continues the interrupted run:
+
+```
+[voltro:migrate] migration resume: found an interrupted run (plan_msocz71h_x0qq5d) — 4 of 5 operation(s) completed, in flight: add-index index:audit_logs.audit_logs_actorId_idx
+[voltro:migrate] migration resume: continuing run plan_msocz71h_x0qq5d — replaying 1 operation(s), 4 already applied
+```
+
+Three things are worth knowing about how it decides.
+
+**The ledger cannot be atomic with the DDL it records** — on MySQL the statement commits itself, so there is always a window where the DDL landed and the `applied` flip did not. That window is not eliminated, it is BOUNDED: the ledger is written strictly sequentially, so **at most one operation can be `started`**, and it is the only one whose outcome is unknown. That one is resolved by asking the planner — the fresh diff was computed against the live database moments ago, so an operation it no longer mentions has already taken effect. Completed operations are never re-attempted.
+
+**If you edited the schema in response to the failure, the recorded plan is dropped** and the freshly-diffed one is applied instead — the old plan aims at a target nobody wants any more. The interruption is still logged, and the artefacts below are still reconciled first.
+
+**Two operations are repaired rather than re-diffed.** The Postgres online type change (shadow-column swap) and the SQLite table rebuild both build a temporary object and swap it into place, and interrupted mid-swap they leave a live schema that means something ELSE to a differ — a half-finished shadow swap looks like a *missing column*, and the plan a blind re-diff produces for that is `add-column`, which succeeds and loses the data sitting in `<col>__old`. The applier reconciles `<col>__shadow` / `<col>__old` and `<table>__voltro_rebuild` from their observable state before anything else reads the schema. If a shadow-swap state cannot be classified, the apply **refuses**, changes nothing, and names the three columns to inspect.
+
+**What has not changed: convergence still gates the fingerprint.** After the DDL — resumed or not — the applier re-plans against the live schema and refuses to record a fingerprint while anything remains. A resumed run is held to exactly the same standard as a fresh one, and an apply that does not converge KEEPS its ledger, because an unfinished run's record is the only thing that tells the next boot it is looking at a half-migrated schema.
+
+If someone finished the failed op out of band (a `mysql` shell, a corrective hot-fix), the fresh diff sees it as present and it is skipped.
 
 ## SQLite — table rewrite mechanic
 
@@ -954,7 +985,7 @@ The DDL emitter under `@voltro/database/src/migrate.ts` is one of the densest cr
 [voltro:dev] auto-migrate: applied 3 op(s) in 412ms [safe=3 needs-default=0 needs-backfill=0 rename=0 lossy=0] fingerprint=8f507ba1e1aadad5
 ```
 
-For MySQL the line notes the non-atomic-DDL constraint (a failed op leaves earlier ops committed; re-run apply to finish):
+For MySQL the line notes the non-atomic-DDL constraint (a failed op leaves earlier ops committed; re-run apply and the resume ledger continues from there):
 
 ```
 [voltro:dev] auto-migrate: planning schema dialect=mysql env=dev tables=22 (implicit-commit DDL — re-run apply after a mid-plan failure)
@@ -1302,6 +1333,36 @@ If `down` throws, the rollback is treated as failed — the schema stays
 in the half-rolled-back state + the operator handles it manually. The
 framework can't auto-recover from a broken inverse.
 
+## `voltro serve` refuses to boot while any are pending
+
+Serve's schema guard is a DECLARATIVE fingerprint diff — the declared schema
+against the last applied plan. A file-based migration exists for the changes a
+state diff cannot infer: a data move, a backfill, a cross-table rewrite. Those
+move **no fingerprint at all**, so the guard passed and production ran
+un-migrated with nothing said.
+
+On a real deploy environment (`NODE_ENV=production` / `staging`), against a SQL
+store, `voltro serve` now refuses to boot while any migration file has never run
+against that database, and names the pending ids:
+
+```text
+serve: refusing to boot — 2 pending file-based migration(s) have never run
+against this database. They perform the changes a schema diff cannot infer
+(data moves, backfills, table splits), so the declarative fingerprint check
+below cannot see them.
+
+  Run them from your pre-deploy job — `voltro db migrate .` (schema + files)
+  or `voltro db files .` (files alone).
+```
+
+It does **not** apply them, and that is deliberate: a rolling deploy starts N
+replicas, each would try, and the migration lock turns that into N-1 processes
+blocked on boot. `VOLTRO_AUTO_MIGRATE=0` bypasses this exactly as it already
+bypassed the fingerprint check — one switch for "no boot-time schema checks".
+
+A local `voltro serve` is untouched: `voltro dev` applies migrations there, so a
+preview serve has nothing to report.
+
 ## Remote databases: boot will not apply them unattended
 
 `voltro dev` applies pending migration files at boot. Against a local
@@ -1521,9 +1582,25 @@ The applier:
 1. Introspects the live DB and plans the diff fresh (it does NOT ingest
    a plan file — the diff is computed against live at apply time)
 2. Refuses (exit 2) if any op is blocked, or refuses (exit 3) if
-   `NODE_ENV=production` — so the apply runs in a one-shot job with
-   `NODE_ENV` unset / `staging`, holding migration credentials, NOT in
-   the serving process
+   `NODE_ENV=production` — so a bare apply runs in a one-shot job with
+   `NODE_ENV=staging`, holding migration credentials, NOT in the serving
+   process
+
+> **`NODE_ENV` unset is no longer "not production".** Every `voltro db …`
+> and `voltro migrate` invocation resolves an unset `NODE_ENV` to
+> `production`, exactly as `voltro serve` and `voltro start` do — so a bare
+> `voltro db apply` in a pipeline that forgot the variable now refuses (exit
+> 3) instead of silently applying an un-reviewed diff to production. Set
+> `NODE_ENV=development` for a local database; use the `--plan` path below
+> for a real one.
+>
+> This is not only about the refusal. `_voltro_traces` and `_voltro_undo_log`
+> are created only when tracing / undo capture are on, and both are *on
+> unless production* — so an apply with `NODE_ENV` unset used to DECLARE two
+> tables the serving container did not. The declared set is what the schema
+> fingerprint hashes, so the apply recorded a fingerprint the container could
+> not reproduce and `voltro serve` refused to boot with `prod-mismatch`,
+> telling you to run the apply you had just run.
 3. Acquires the advisory lock + executes the plan
 4. Records the result in `_voltro_migration_plans` with
    `source: 'auto-diff'` + `notes: 'PR #1234 — add user emails'`
@@ -1554,6 +1631,31 @@ up-to-date DB is a clean no-op (`schema is up to date — nothing to
 apply`). That's what makes the apply safe to run in every pod of a
 stateless deploy.
 
+Both spellings of the flag work: `--plan plan.json` and `--plan=plan.json`.
+
+### The FIRST deploy, against an empty database
+
+Nothing special is required, and the plan you review is the whole story: on a
+database with no tables, `voltro db plan --json` includes the framework's own
+`_voltro_*` tables (the migration ledger, api keys, kv, outbox, traces …) plus
+`actors`, alongside your own. They are part of the declared schema, so they are
+planned, classified and applied by exactly the same code as your tables — expect
+a first-deploy plan to be ~20 operations larger than the diff you wrote.
+
+Two consequences worth knowing:
+
+- The reviewed plan is complete. `db apply --plan` creates nothing beside it, so
+  the fingerprint the plan was generated against is still the live schema when
+  the guard checks it. (It did not used to be: the ledger tables were created
+  before the fingerprint was taken, so the first deploy of every new database
+  refused with `the live schema has drifted` one second after the plan was
+  generated. Fixed.)
+- One table is deliberately absent from the plan: `_voltro_migration_ops`, the
+  crash-resume ledger. It has to exist before the very first plan runs — the plan
+  that creates everything else — so `voltro db apply` creates it itself, under the
+  migration lock. A live `_voltro_*` table your schema does not declare is never
+  planned for a drop, so it does not show up in the next diff either.
+
 ## Apply timing relative to deploy
 
 Two orderings, both common:
@@ -3036,12 +3138,68 @@ voltro db apply --note 'PR #1234'
 
 4. Re-deploy. The new boot's fingerprint check passes.
 
-Note: the boot-mismatch message itself prints
-`voltro db apply --plan plan.json`, but `--plan` is not a real flag —
-the prod apply is a plain `voltro db apply` that recomputes the diff.
+`--plan` IS a real flag, and it is the better answer here. This note used to
+say it was not, and told you to run a plain `voltro db apply` instead — which
+recomputes the diff and therefore applies something nobody reviewed. The claim
+came from a defect, not from the design: the app root was resolved as "the
+first argument that does not start with `-`", so `--plan plan.json` handed the
+plan FILE to schema discovery (`no schema files found, root: …/plan.json`)
+while `--plan=plan.json` worked. Both spellings work now.
+
+Prefer the reviewed form in a pipeline:
+
+```sh
+voltro db plan --json > plan.json          # review this in the PR
+voltro db apply --plan plan.json           # apply exactly it, fingerprint-guarded
+```
+
+A plain `voltro db apply` stays correct for a developer machine, where the diff
+you would review is the one you just wrote.
 
 If the cause is drift (someone DDL'd prod manually), see [drift.md](./drift.md) for reconciliation paths.
 
+### If the two processes are the same image: compare their `env:` blocks
+
+A fingerprint mismatch does not always mean the schema changed. The declared
+table set is what gets hashed, and until 0.35.0 three RUNTIME flags could move
+it — so a pre-deploy migrate Job and the pods it feeds could disagree while
+running identical code against one database.
+
+That was reported as a green migrate job followed by every pod in
+CrashLoopBackOff. The chart gave the Job its own `env:` list (`NODE_ENV`,
+`DB_*`) while `CDC: "0"` lived in the pods' block, because change data capture
+reads as a runtime concern. Measured on mariadb at `NODE_ENV=production`, each
+flag flipped alone:
+
+| flag | effect on the DECLARED set |
+| --- | --- |
+| `CDC=0` | removes `_voltro_cdc_offsets` |
+| `VOLTRO_UNDO=on` | adds `_voltro_undo_log` |
+| `VOLTRO_TRACING_PERSIST=all` | adds `_voltro_traces` |
+
+**From 0.35.0 none of them does.** `_voltro_cdc_offsets` follows the DIALECT, so
+a mariadb/mssql app declares it either way; the other two are declared in
+`app.config.ts` and the env vars only choose what a process captures:
+
+```ts
+export default {
+  // Both default to on outside production. Declare them when you want the
+  // table in a production schema — `VOLTRO_UNDO` / `VOLTRO_TRACING_PERSIST`
+  // alone is no longer enough, because your migrate job does not carry them.
+  schema: { undo: true, traces: true },
+}
+```
+
+Setting a capture flag ON without the declaration now refuses the boot and names
+the field, rather than writing to a table nobody created.
+
+The refusal also prints which of the three tables this process decided and from
+which input, so the comparison is a glance rather than a hash diff. Do compare
+the two `env:` blocks anyway if you use plugins: a plugin's `extendSchema.tables`
+is your code and may read anything, which is the one part the framework cannot
+guarantee for you.
+
+
 ## "duplicate column name in plan" (logically invalid plan)
 
 ```
@@ -3170,13 +3328,19 @@ so a failure THERE can leave the index half-built; re-apply finishes it.)
 
 **MySQL and MariaDB** (and sqlite / turso) implicit-commit every DDL
 statement, so THERE a plan that fails on op N leaves ops 1..N-1 committed.
-There is no `--resume` / `--abort` flag and no per-op partial-status
-tracking — the apply records a row only on full success.
-
-Recovery is just to re-run the apply: `voltro db apply` re-diffs the
-declared schema against the current (half-applied) live shape and emits
-only the ops that are still missing. Fix the cause of the failed op
-first (e.g. the `ER_DUP_KEYNAME` that stopped op N), then:
+The `_voltro_migration_plans` row is still written only on full success —
+that row means "this schema is live". What the apply DOES write as it goes
+is a per-operation **resume ledger** (`_voltro_migration_ops`): every op is
+recorded before any DDL runs, flipped to `started` before its statement and
+`applied` after, and the rows are deleted once the apply converges. There is
+still no `--resume` / `--abort` flag because there is nothing to choose.
+
+Recovery is just to re-run the apply. It finds the ledger, logs
+`migration resume: found an interrupted run …`, reconciles any half-finished
+shadow-column swap or table rebuild, skips the ops that already took effect,
+and replays the rest — including a `.backfill()` that was only partly done,
+which a plain re-diff cannot express. Fix the cause of the failed op first
+(e.g. the `ER_DUP_KEYNAME` that stopped op N), then:
 
 ```sh
 voltro db apply --note 'completing partial apply after fixing op N'
@@ -3361,6 +3525,40 @@ db apply: change triggers converged (1501 statement(s))
 
 The mirror case is reported the same way: a `.nonReactive()` table that still carries a trigger keeps paying `REPLICA IDENTITY FULL` and a `NOTIFY` on every write for a subscription nobody receives. `db apply` removes both.
 
+**Boot converges them too, on both boot paths.** `voltro dev` and `voltro serve`
+run the same check-and-repair at startup, so a schema-only restore or a
+`CDC=0` → `CDC=1` flip no longer waits for someone to notice:
+
+```text
+reactive triggers: converged at boot — installed 500, removed 0 (1501 statement(s))
+```
+
+Three things about it are worth knowing before you deploy a fleet:
+
+- **It does not queue.** The repair takes the migration advisory lock with
+  `pg_try_advisory_lock` and SKIPS if anything holds it, so N replicas booting
+  together produce one repairing and N-1 logging `another instance … is
+  converging it`. A concurrent `voltro db apply` holds the same lock, so the two
+  can never run each other's DDL. The lock is scoped to your configured
+  `DB_SCHEMA`, so `another instance` really means an instance of YOUR
+  deployment — a second app sharing the database in a different schema takes a
+  different key and neither defers the other.
+- **It never fails a boot.** A check that cannot run warns and the process
+  continues; reactivity may be degraded, and that is still better than a
+  diagnostic taking the app down.
+- **It is a tunable**, `reactiveTriggers` in `app.config.ts`, default `'repair'`:
+
+  ```ts
+  export default defineApiApp({
+    store: 'postgres',
+    reactiveTriggers: 'report',   // 'repair' (default) · 'report' · 'off'
+  })
+  ```
+
+  `VOLTRO_REACTIVE_TRIGGERS` overrides the field. `VOLTRO_AUTO_MIGRATE=0`
+  downgrades `'repair'` to `'report'` — that variable means "this boot issues no
+  DDL", and it is deliberately not read as "and say nothing".
+
 ## When the fix hint doesn't match reality
 
 The fix hints come from the planner's classification logic — they should always be actionable. If you see one that doesn't make sense given your code:

package/templates/agent-docs/database/misc.md

@@ -1,6 +1,6 @@
 # Database
 
-> Spin up an isolated branch of a tenant's data — a namespace snapshot/restore by default (dialect-agnostic, no vendor lock) or a Neon copy-on-write fast-path on Postgres — then bind to it and tear it down. The basis for per-PR preview environments.
+> Branch the live schema and REHEARSE your migration on it — apply the plan to a throwaway copy, flag every lossy operation, prove it converges, drop the branch. Plus the branch primitive itself (namespace snapshot on Postgres, Neon copy-on-write fast-path).
 
 
 
@@ -9,73 +9,178 @@
 <!-- source: en/database/branching.md -->
 ## Data branching
 
-_Spin up an isolated branch of a tenant's data — a namespace snapshot/restore by default (dialect-agnostic, no vendor lock) or a Neon copy-on-write fast-path on Postgres — then bind to it and tear it down. The basis for per-PR preview environments._
+_Branch the live schema and REHEARSE your migration on it — apply the plan to a throwaway copy, flag every lossy operation, prove it converges, drop the branch. Plus the branch primitive itself (namespace snapshot on Postgres, Neon copy-on-write fast-path)._
 
-Data branching creates an **isolated copy of a tenant's data** you can read and
-write without touching the source — the basis for per-PR preview environments and
-safe "try a migration against real-shaped data" workflows. The default mechanism
-is a **namespace snapshot/restore** (works on every dialect, no vendor lock); on
-Postgres backed by Neon, a **copy-on-write branch** fast-path is used instead.
+Data branching creates an **isolated copy of a schema** you can read, write and
+migrate without touching the source. The headline use is not the branch — every
+serverless-Postgres vendor sells one of those — it is what Voltro can do WITH a
+branch that a vendor cannot: **rehearse your pending migration on it and tell you
+what it would do.**
+
+## `voltro db branch` — the migration rehearsal
+
+```bash
+voltro db branch --pr 128                 # branch the live schema, rehearse, report, drop it
+voltro db branch --pr 128 --seed copy     # …with the parent's rows copied in
+voltro db branch --pr 128 --keep          # leave the branch standing to poke at
+voltro db branch --pr 128 --json          # machine-readable, for a PR comment
+```
+
+What it does, in order:
+
+1. **Branches the LIVE schema** into a throwaway namespace (`br_pr128_<app>`).
+2. **Checks fidelity** — plans the declared schema against the branch AND against
+   the parent, and aborts if the two disagree. A branch that is not a faithful
+   copy rehearses a different migration from the one you are about to run, and
+   saying nothing about that would be worse than not rehearsing at all.
+3. **Plans your migration** against the branch and classifies every operation.
+4. **Executes it there**, including the destructive operations.
+5. **Re-plans.** An empty re-plan is the verdict; a migration that applies and
+   then re-proposes itself forever is not a migration.
+6. **Drops the branch** (unless `--keep`), even when the apply failed.
+
+```
+branch rehearsal · br_pr128_shop · mechanism namespace
+  branched 18 table(s), replayed 3 foreign key(s)
+  plan: 2 operation(s), 1 lossy, 0 refused
+    • add-column members [safe]
+    ✗ drop-column members [lossy]
+
+  ⚠ 1 operation(s) DESTROY DATA. They were executed on the branch (it is
+    disposable) so they are rehearsed, but production refuses them until you set
+    VOLTRO_DESTRUCTIVE_OK — naming the tables, not `1`.
+
+  ✓ applied on the branch, and the re-plan is EMPTY (the migration converges).
+  branch br_pr128_shop torn down.
+```
+
+### Lossy operations are executed, not skipped
+
+Production refuses a `drop-column` until a human acknowledges it. A branch that
+is about to be dropped has no such reason — and refusing there would mean the one
+operation most likely to fail is the one operation never rehearsed. So the
+rehearsal unblocks lossy operations on the branch, runs them, and leads the report
+with every one of them. That report is the thing you paste into the PR.
+
+Operations the planner refuses **anywhere** (`needs-rename-annotation`,
+`multi-step`) are NOT executed — the plan is reported as `blocked` instead.
+
+### Exit codes
+
+| code | meaning |
+|---|---|
+| `0` | applied on the branch and converged, nothing lossy |
+| `2` | a REVIEW signal: the plan destroys data, or the planner refuses part of it |
+| `1` | the rehearsal could not answer — it failed, the branch was not faithful, or the migration did not converge |
+
+`lossy` is deliberately not an error. A `drop-column` in a PR is a normal,
+intentional thing; making it exit `1` trains people to pass `--force`, and the
+next real failure goes with it.
+
+### What `--seed` does and does not rehearse
+
+`--seed empty` (the default) branches the SCHEMA only. That is enough for every
+structural question and costs nothing. It does **not** rehearse anything
+data-dependent: a `NOT NULL` meeting existing NULLs, a backfill meeting real
+values, a unique constraint meeting duplicates, or the row-count threshold that
+promotes an operation to `online-required`. Use `--seed copy` for those — it
+copies every row, which is fast on a small database and slow on a large one.
+
+## Mechanisms — what actually works
+
+Be precise here, because the vendor landscape invites over-claiming. The branch
+**plan** is dialect-agnostic. The shipped **executor** is not.
+
+| mechanism | when | status |
+|---|---|---|
+| `namespace` | Postgres — a schema per branch | shipped, and what `voltro db branch` uses |
+| `neon-cow` | Postgres on Neon, `seed: 'copy'` | plan shipped; **executed by the cloud control plane**, not the CLI |
+
+- **MySQL, MariaDB, SQLite and SQL Server are not supported by
+  `voltro db branch`.** `makeNamespaceBranchExecutor` emits `CREATE SCHEMA`,
+  `CREATE TABLE … (LIKE … INCLUDING ALL)` and `"`-quoted identifiers, none of
+  which those engines accept. The command refuses with that reason rather than
+  sending Postgres syntax at them. Writing your own `BranchExecutor` for another
+  dialect is the supported path — the plan is already portable.
+- **Neon copy-on-write is a call to Neon's branch API** and needs a Neon token,
+  which the CLI does not hold. `voltro db branch` names the mechanism and refuses,
+  pointing at `--prefer namespace`. The cloud control plane executes it.
+- **There is no Supabase mechanism and no template-database mechanism.** Neither
+  exists in the codebase.
 
 ## The plan/execute split
 
 Branching is a **plan** (what to do) + an **executor** (do it), mirroring the
-migration engine. The plan is pure + inspectable; the executor performs the I/O.
+migration engine. The plan is pure and inspectable; the executor performs the I/O.
 
 ```ts
 import { planBranch, resolveBranchMechanism } from '@voltro/database'
 
-// Pick the mechanism: 'neon-cow' when seeding a copy on a Neon URL,
-// 'namespace' (schema-per-branch) otherwise.
 const mechanism = resolveBranchMechanism({ seed: 'copy', dbUrl: connectionString })
 const steps = planBranch({
   mechanism,
-  branchId: 'branch_acme_pr128',
+  branchId: 'br_pr128_shop',
   tableNames,
   seed: 'copy',
-  parentNamespace: 'public',   // namespace mechanism: the schema to snapshot from
+  parentNamespace: 'public',
 })
-// steps: e.g. [{ kind: 'neon-branch-create', … }] or per-table namespace snapshot steps
 ```
 
 ## Provision + tear down
 
 `provisionBranch` / `teardownBranch` run a plan through an injected
-`BranchExecutor` (the dialect/Neon adapter). Injected so the lifecycle is
-unit-testable with a recording executor — no live DB:
+`BranchExecutor`. Injected so the lifecycle is unit-testable with a recording
+executor — no live database:
 
 ```ts
-import { provisionBranch, teardownBranch } from '@voltro/database'
+import { provisionBranch, teardownBranch, makeNamespaceBranchExecutor } from '@voltro/database'
 
 const result = await provisionBranch(
-  { appSlug: 'acme', prNumber: 128, seed: 'copy', tableNames, dbUrl: connectionString },
-  executor,
+  {
+    appSlug: 'shop', prNumber: 128, seed: 'copy', tableNames,
+    parentNamespace: 'public',
+    foreignKeys,       // see below — LIKE does not copy these
+    indexNames,        // see below — LIKE renames these
+    dbUrl: connectionString,
+  },
+  makeNamespaceBranchExecutor({ run: (sql) => client.query(sql) }),
 )
-// result: { branchId, mechanism, steps, … } — for 'neon-cow' also the
-// branch's own connection string to bind the preview store to.
 
-// …run the preview against result, then:
 await teardownBranch(result.branchId, result.mechanism, executor)
 ```
 
-`admitBranch` gates whether a branch may be served (e.g. it exists + is ready)
-so a request never binds to a half-provisioned branch.
+`admitBranch` enforces the storage-cost caps (a TTL and a maximum number of live
+branches) before a new one is provisioned.
 
-## Mechanisms
+### Two things `LIKE … INCLUDING ALL` does not carry
 
-| mechanism | when | how |
-|---|---|---|
-| `namespace-snapshot` | any dialect (default) | snapshot the tenant's namespace → restore into a new branch namespace |
-| `neon-branch` | Postgres on Neon | a copy-on-write Neon branch (instant, storage-shared) |
+Both were found by pointing the rehearsal at a real Postgres and watching a
+converged schema propose work. They are properties of Postgres, not of Voltro's
+emission, and a branch missing either is not a copy:
+
+- **Foreign keys are not copied.** There is no `INCLUDING` clause that copies
+  them. A branch without them accepts writes production rejects.
+- **Index names are re-derived** from the table and columns. Measured on pg 17:
+  `byApiKeyTenant` came back as `_voltro_api_keys_tenantId_idx`, and
+  `_voltro_idempotency_scope_key_uq` as `…_scope_key_idx`. The migration planner
+  compares indexes by name, so every custom-named index reads as a different
+  index.
 
-The mechanism is resolved from the connection, so the same `planBranch` call
-produces the right steps for the deployment's database — dialect-agnostic by
-default, with the Neon fast-path when it's available. No code path is locked to a
-vendor.
+`provisionBranch` replays both (`foreignKeys` + `indexNames`, sourced from the
+parent's introspected snapshot). `voltro db branch` does it for you, and refuses
+to report anything about your migration if the branch still differs from the
+parent.
+
+## Branch-per-PR in CI
+
+```yaml
+- run: voltro db branch --pr ${{ github.event.number }} --json > rehearsal.json
+  continue-on-error: true      # exit 2 is a review signal, not a build failure
+- run: node scripts/comment-rehearsal.mjs rehearsal.json
+```
 
-> Branching copies **data**, not the schema definition — apply migrations to a
-> branch the same way you would to any store. Teardown is explicit; a branch
-> left bound holds its namespace/Neon branch until torn down.
+The `--json` report carries `operations`, `lossy`, `blocked`, `residual`,
+`converged` and `infidelity` — everything a PR comment needs, already classified.
 
 
 
@@ -281,11 +386,22 @@ recoveryNote: text().encrypted(),                // encrypted at rest, but the o
 apiToken:     text().encrypted().serverOnly(),    // secret at rest AND never to a client
 ```
 
-Enforcement: the [`crud.*` read helpers](/docs/data/crud) strip `.serverOnly()`
-columns from every returned row **automatically** — you declare the exposure
-policy once at the schema and can't forget it on a handler. For a hand-written
-query, omit the column from the `output` schema (and don't put it in the returned
-object).
+Enforcement runs in **both directions**, because "never crosses the wire" is not
+a one-way claim:
+
+- **Outbound** — the [`crud.*` read helpers](/docs/data/crud) strip `.serverOnly()`
+  columns from every returned row **automatically**. You declare the exposure
+  policy once at the schema and can't forget it on a handler. For a hand-written
+  query, omit the column from the `output` schema (and don't put it in the
+  returned object).
+- **Inbound** — `crud.create` / `crud.update` **refuse** an input that sets a
+  `.serverOnly()` column, with `ServerOnlyColumnWrite` naming it, and write
+  nothing. A column the client may not read must not be one the client can set:
+  accepting it is mass assignment. It is refused rather than silently stripped
+  because a stripped field makes an attack indistinguishable from a no-op. When
+  the *server* needs to write one, do it from the handler with
+  `ctx.store.insert` / `ctx.store.update` — the refusal is on the generated
+  path, which is the one fed straight from client input.
 
 A hand-written output is the case `crud.*` cannot cover, so an audit checks it:
 a wire-reachable query whose `source` table carries a `.serverOnly()` column that

package/templates/agent-docs/database/querying.md

@@ -260,9 +260,27 @@ The `sql` tag is imported from the server-only `@voltro/database/sql` subpath
 **Raw queries aren't tracked by the reactive engine** — the planner can't infer which tables an arbitrary SQL string touches. If you want a subscription to invalidate on a raw read's tables, declare them explicitly:
 
 ```ts
-ctx.store.raw!<{ … }>(sql`…`, { dependsOn: ['events'] })
+ctx.store.raw!<{ n: number }>(sql`SELECT count(*) AS n FROM events`, { dependsOn: ['events'] })
 ```
 
+The tables can also live on the fragment itself (`{ ...frag, dependsOn: ['events'] }`), which is handy when the fragment is built somewhere else. They are taken at face value — the framework records what you declare and never checks it against the SQL.
+
+**If you forget, the framework tells you.** A raw read taken while a live query's handler runs, with nothing declared, warns once at subscribe time and names both the query and the SQL:
+
+```
+[voltro] reports.summary: a raw SQL read in this live query declares no
+dependsOn, so no write can invalidate it — every subscriber keeps its first
+result until it reconnects. Declare the tables it reads:
+ctx.store.raw(fragment, { dependsOn: ['orders'] }) — or on the fragment itself.
+The read: SELECT sum(total) FROM orders WHERE tenant = ?
+```
+
+Only the STATIC text is logged; the bound values never are.
+
+The diagnostic keeps a bounded record: one request remembers up to 32 distinct raw reads (deduplicated by SQL text), tunable with `VOLTRO_RAW_READ_TRACKING_LIMIT`. Reads past the bound are dropped rather than remembered — a handler that raw-reads in a loop must not turn a warning into a memory leak. Raise it only if a handler issues many distinct raw reads and you want the warning to name a later one.
+
+**Where `dependsOn` works, and where it can only warn.** It drives recomputation for a query whose handler returns a **computed value** — the shape whose handler is genuinely re-run on a change (see [Subscriptions](/docs/data/subscriptions)). The declared tables join the query's own `source:`; they never replace it. A handler that returns a query **descriptor** is different: a change re-runs the descriptor's query, not your handler, so the raw result is not refreshed. There the warning is the whole answer — return a computed value if the raw read has to stay live.
+
 ## Tenant scoping (implicit)
 
 If the table has the `tenant()` mixin, every `select` auto-merges `WHERE tenantId = ctx.subject.tenantId`. You don't write it; the runtime injects it. To opt out (admin queries crossing tenants), use `.unscoped()`: