@voltro/runtime 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -39,6 +39,177 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.42.0] — 2026-08-17
+
+### ⚠ BREAKING
+
+- **@voltro/cli, @voltro/data-transfer** — **Two security defects on the data-transfer surface, both found by using the feature rather than by reading it.**
+
+  **A `{ profile }` in an admin-export request could name a PATH.** `loadProfile` resolved the client's string with `resolve(cwd, x)` — which returns an absolute path unchanged and lets `../` traverse — and the resolved file is `await import()`ed, which RUNS it. So a holder of the data-transfer secret could make the api process execute any file on the pod: an escalation from "can export prod data" to "can run code", and chainable on an instance whose object storage is a filesystem the same caller can write to.
+
+  `POST /_voltro/admin/export` now accepts a NAME only — `[A-Za-z0-9_-]{1,64}`, resolved under `data-profiles/` and checked to be contained there. **Migration: if you passed a path over `--target api`, move the file to `data-profiles/<name>.ts` and pass `<name>`.** `voltro data export --profile` on a DIRECT target still accepts a path: it runs on the operator's own machine, where a path is not an escalation. No user-authored code changes, so `codemod: none`.
+
+  **An unrecognised masking action copied the value through.** `applyAction` ended in `return input.value`, so a profile with a typo in the action shape (`{ action: 'fake', kind: 'email' }` instead of `{ fake: 'email' }`) exported every row of a `.sensitive()` column verbatim — with a 200 and an audit line counting the column as masked. Measured against a live instance: a masked export of two users came back carrying both real addresses.
+
+  The applier now throws, and `planMasking` refuses the policy BEFORE a row is read: `MaskingError` gained `invalidActions`, reported separately from `unclassified` because the fixes differ — one needs a classification, the other needs the policy corrected.
+
+### Added
+
+- **@voltro/runtime** — A write the database refuses on an integrity rule now raises a typed `ConstraintViolation` instead of an opaque `SqlError`. It carries `{ kind, table, operation, constraint?, column? }`, where `kind` is one of `foreignKey` · `foreignKeyInUse` · `unique` · `notNull` · `check`. Declare it in a procedure's `error:` to pattern-match it; undeclared it still reaches the client as an `InternalError` carrying its own sentence rather than `Failed to execute statement`.
+
+  It carries NAMES and never the driver's message, which on most engines contains row data — postgres attaches the complete failing row to a not-null and a check violation, mysql and mssql echo the duplicate value. Classification is measured against live postgres 17, MySQL 8.4, MariaDB 11, SQL Server 2022 and sqlite.
+
+  Raised from one guard covering every write op (insert · insertMany · upsert · insertIgnore · update · updateMany · delete · deleteMany · hardDelete · patchJson); the tenant-FK case still resolves to `TenantScopeViolation` first.
+
+### Fixed
+
+- **@voltro/cli, @voltro/data-transfer** — `voltro data import|export` — four defects on the `--target api` path, all found by a consumer seeding a fresh cluster from a bundle.
+
+  **A flag this command does not read is now an ERROR.** `--dry-run` and `--tables` were accepted on the import path and dropped in silence: a preview against a production-shaped cluster ran the import instead (2905 rows, then a 500), and a run narrowed to a one-row table wrote all 10 593. Both are one defect — an argument parser that ignores what it does not understand — so every `voltro data` subcommand now declares the flags it reads per target and refuses the rest, naming the flag and what to use instead.
+
+  **`--dry-run` and `--tables` now work on the import, on BOTH targets.** A dry run reaches every verdict a real run reaches (schema fit, cross-dialect portability, mode legality, the table selection) and stops before the first write; the api path carries them as `x-import-dry-run` / `x-import-tables` and echoes `{ dryRun: true, wrote: false }`. A `--tables` name the bundle does not carry is refused, listing what it does. `--dry-run` on an api EXPORT is refused rather than ignored — previewing a read protects nothing.
+
+  **The schema-drift pre-flight compares the INTERSECTION, not whole schemas.** A bundle's fingerprint covers its source schema regardless of export scope, and two environments never have identical whole schemas, so the check refused every cross-environment seed with a diff whose every line said the difference changes nothing — making `--force` the routine way to import and removing the protection it guards. It now reports only what would break the load: a carried table or column the target lacks, a type mismatch, or a column the target REQUIRES that the bundle carries no value for.
+
+  **A failed row says why.** `reason` was `Failed to execute statement` for every one of 2905 rows. It now names the constraint and the rule (`foreign key tasks_laneId_fkey: the referenced row does not exist [23503]`), or the driver's own message with its code, or — where there is no driver under the failure — the error from the layer that refused.
+
+  Also: `voltro data inspect` accepts a directory bundle instead of dying inside the archive reader with a JSON parse error (`--target api` always unpacks into a directory, even when the path ends in `.vbundle`).
+
+  **Three more, found by running the whole thing against live MariaDB and MySQL** rather than against sqlite:
+
+  - A re-run of a COMPLETED import wrote nothing and reported the bundle's full row count — the resume ledger lives in the bundle directory, so truncating a target and re-importing printed `import complete … 10593 rows` over an empty database. Resume is right; being quiet about it was not. It now warns, names the skipped tables, and says which ledger file to delete. - The deferred-FK recovery pass OVERWROTE the diagnosis. When a held row cannot be written, the resolver retries it with every `reference` column nulled to break a cycle — and that attempt's failure replaced the original reason, so a row whose real problem was one column reported a not-null violation on a column the framework itself had nulled. The recovery attempt no longer records a reason. - MySQL/MariaDB errno **1364** (a statement that OMITS a column which is NOT NULL with no default) is classified as a not-null violation. postgres reports 23502 for that situation and mssql 515, so the mysql family was the only one where "you did not supply a required column" came back unclassified.
+- **@voltro/database** — CHECK constraints were invisible to introspection on **MySQL** — and with them every `.oneOf()` column and every `json_valid` marker.
+
+  `information_schema.check_constraints` differs between the two engines of the family: MariaDB carries `TABLE_NAME`, MySQL does not have that column at all. The introspector selected it, the query errored, and an `Effect.orElseSucceed` turned that into an empty list. A swallowed error and an empty result read identically, which is why this needed a two-engine test to surface. The query JOINs `information_schema.table_constraints` for the name now, which both engines answer.
+
+  `parseEnumCheck` also learned MySQL's rendering. The same clause is stored differently:
+
+  mariadb 11 `status` in ('draft','live','done') mysql 8.4 (`status` in (_latin1'draft',_latin1'live',_latin1'done'))
+
+  MySQL puts a charset introducer before each literal, which the pattern — written against MariaDB's form — did not read. Both are pinned in `enumCheckParity.test.ts`.
+
+  Neither fix completes the round trip on MySQL: `.oneOf()` still comes back unclassified there. That is asserted as a known gap in `oneOfCheck.mariadb.integration.test.ts` (which fails the moment it starts working) and written up in `plans/open/framework/mysql-oneof-roundtrip.md`.
+- **@voltro/database** — `voltro db apply` works on MySQL. It could not create a table with an index, and could not drop a column, on that engine at all.
+
+  `IF [NOT] EXISTS` outside `CREATE`/`DROP TABLE` is a MariaDB extension — MySQL rejects it with ER_PARSE_ERROR (measured on 8.4 for `CREATE INDEX IF NOT EXISTS`, `ALTER TABLE … DROP COLUMN IF EXISTS`, and `ADD COLUMN IF NOT EXISTS`). The applier emitted the first two, because `@effect/sql-mysql2` reports the dialect `mysql` for both engines and the shared branch had only ever run against MariaDB. A `reference()` column gets an index by default, so in practice most tables were affected.
+
+  The applier now asks the SERVER which engine it is (`SELECT VERSION()`; MariaDB stamps itself into the string) and emits the plain form on MySQL. The idempotency `IF [NOT] EXISTS` provided moves into the statement runner, which tolerates exactly the errnos meaning "already in the requested state" — 1061 for a duplicate index name, 1091 for dropping something absent. The engine is read from the connection rather than from `DB_DIALECT` or `variant`, because the DDL has to be legal for the server that receives it and those are what an operator typed.
+
+  Verified against live MySQL 8.4 and MariaDB 11: a schema evolution — create, add column, add index, drop column — applied through `applyPlan` on both, converging at every step, plus a replayed plan (what a resume does) that must not error on the statements it repeats.
+
+  **sqlite had the same defect, found by the new cross-dialect scenario on its first run.** `ALTER TABLE … DROP COLUMN IF EXISTS` is accepted by postgres, mssql and MariaDB and rejected by sqlite — and the generic emitter, shaped for postgres, is what sqlite used. So `voltro db apply` could not drop a column on sqlite either. The conditional form is now emitted only where it is legal, and the "already dropped" case is tolerated per dialect (`idempotentDdl.ts`).
+
+  `runDialectParity` gained a schema-evolution scenario — create, add column, add index, drop column, applied for real with a convergence check after each step — so the migration APPLIER is now covered on all five dialects. It previously had one scenario covering one op kind, while twenty-two covered the store; that split is why four emitter defects survived.
+
+  **And a fifth, found by making one MariaDB-only suite two-sided.** `text().unique()` on an unbounded text column created a table on MariaDB and failed the CREATE outright on MySQL: `BLOB/TEXT column 'x' used in key specification without a key length`. The bring-up emitter (`migrate.ts`) wrote an inline `UNIQUE`; the declarative applier had always written a separate PREFIXED unique index. The two emitters disagreeing on one statement is the failure shape this package's own notes describe, and only one engine said so.
+
+  `migrate.ts` emits the prefixed index now, through the same `indexStmt` that already owns the per-dialect `IF NOT EXISTS` rule, and names it `<table>_<column>_key` to match the applier's — so the two paths produce the same object.
+
+  **Note the behaviour change on MariaDB.** It accepted the inline form by backing it with a HASH long-unique index, whose hidden `DB_ROW_HASH_n` column breaks the binlog CDC reader (documented in `packages/database/CLAUDE.md`). Uniqueness on such a column is now enforced on the first 191 characters rather than the whole value — which is what `voltro db apply` already did, and what MySQL can express at all. Bound the column with `text().maxLength(n)` if you need full-value uniqueness.
+- **@voltro/sql-mysql** — `insertIgnore` on MySQL was a different feature from `insertIgnore` on MariaDB — and the difference could turn a conflict into an error.
+
+  The whole diagnostic apparatus — the refusal to report a REJECTED write as a conflict, and the message naming the constraint that actually fired — sat behind a `variant === 'mariadb'` branch. MySQL took an `else` that used no `INSERT IGNORE` at all: look for a row matching the conflict columns, insert if there is none. That cannot hold the one property the method exists for. A caller that looks before anyone else writes sees nothing, so the write it then makes is the one that raises the duplicate-key error `insertIgnore` promises never to raise — reproduced deterministically against both engines with an uncommitted holder (the lookup cannot see the holder's row; the insert cannot proceed until it commits).
+
+  Underneath sat the reason a straight port would still have produced nothing: **MySQL answers a PREPARED `SHOW WARNINGS` with 1295 ER_UNSUPPORTED_PS**, and the warning read is deliberately failure-tolerant (a diagnostic must never replace the caller's real problem), so it returned an empty list — indistinguishable from a statement that raised nothing. MariaDB accepts both protocols. The read goes through the text protocol now, the same spelling the binlog path already used for `SHOW MASTER STATUS`.
+
+  Both engines now run one `INSERT IGNORE` and reach one decision function. What differs is only the probe for "did it land": MariaDB has `INSERT IGNORE … RETURNING *`; MySQL has no RETURNING, so the row's own key answers instead. `SELECT ROW_COUNT()` — the obvious alternative — cannot be used: measured on both engines, it reports 1/0 correctly but CLEARS the warning list on MySQL, and run the other way round returns `-1` because `SHOW WARNINGS` is then the last statement. The count and the diagnosis cannot both be had; the diagnosis is the one worth having.
+
+  Found by converting the suite that covers this to run on both engines, which is also where every MySQL assertion in it had been reporting the driver's generic `Failed to execute statement`.
+- **@voltro/database** — A `reference()` column now creates a real foreign key on **MySQL**. It did not before: MySQL/InnoDB parses a column-inline `REFERENCES` clause and discards it — no constraint, no warning, the `CREATE TABLE` succeeds — while MariaDB honours the identical clause. Both engines reach the same emitter (the driver reports the dialect `mysql` for either), and every mysql-family integration suite in the repo runs against MariaDB, so referential integrity that postgres, MariaDB, mssql and sqlite all enforced was silently absent on MySQL.
+
+  Both emitters now write a table-level `CONSTRAINT <table>_<column>_fkey FOREIGN KEY …` inside the `CREATE TABLE`, which both engines honour and which `CREATE TABLE IF NOT EXISTS` keeps idempotent. Existing MariaDB schemas are unaffected — the introspected snapshot carries no constraint name, so nothing re-plans.
+
+  Verified against live MySQL 8.4: the constraint is in the catalog, the server refuses an orphan row, introspection reads it back, and the re-plan is empty.
+- **@voltro/sql-turso, @voltro/testing** — A migration on turso applied correctly and then reported itself as failed: `voltro db apply` ran an `add-column`, re-planned to prove convergence, saw the column still missing, proposed the same operation again, and the second execution died with `duplicate column name`. No fingerprint was recorded, so every subsequent boot re-proposed the same work — and the error named the migration applier, which had done nothing wrong.
+
+  The client caches one prepared statement per connection per SQL text, and a prepared statement carries the schema it was prepared against. So a cached `PRAGMA table_info(t)` keeps answering with the old columns after a DDL — it is never re-prepared, so sqlite's schema-cookie re-preparation never runs. The invalidation for this existed, on the unprepared path (`sql.unsafe`) only, and the migration path sends its DDL through the PREPARED one. The statement that changed the schema and the cache that had to be dropped were on the same connection, one function apart, with nothing connecting them.
+
+  Any schema-changing statement now drops that connection's cached statements, whichever path it arrived on.
+
+  Three hypotheses were measured and disproven before this one — an applier retry (each operation is issued once), an MVCC snapshot (two raw libsql clients both see the DDL), and a pool-wide cache problem (four connections held open together, the PRAGMA prepared on each, a DDL on one: the other three answer correctly, because SQLite bumps the schema cookie and the driver re-prepares on the connections that did not make the change).
+
+  The two `runDialectParity` scenarios that drive the migration applier were skipped for turso on the strength of that misreading. They run now, and the per-fixture opt-out that carried the skip is deleted: it was holding a defect open while reading like a documented limitation.
+
+  **`apiSurface: compatible`, and the reason is a date rather than an argument.** Removing `DialectFixture.skipApplierScenarios` moves a line in `@voltro/testing`'s golden, so the changelog's narrowing detector flags it — and it is right to, because that detector's baseline is `origin/main`. But the field never reached a RELEASE: it was added after `v0.41.0` and deleted before this one, both inside the same unreleased range. `git show v0.41.0:packages/testing/etc/testing-dialect.api.md` does not contain it. No published version ever offered it, so no consumer can have set it, and there is nothing to migrate.
+
+  Worth writing down because the first reading of this was wrong in the safe direction: it was filed `BREAKING` with a codemod on the strength of "an optional field disappeared from a published package's surface", which is the right instinct and the wrong conclusion here. **"Removed relative to main" is not "removed relative to what users have"** — a symbol that lives and dies between two tags trips the detector while breaking nobody, and the difference is only visible by asking the last TAG rather than the last commit.
+
+---
+
+## [0.41.0] — 2026-08-17
+
+### ⚠ BREAKING
+
+- **@voltro/web, @voltro/cli** — `middleware.ts` exports `defineMiddleware(...)` (from `@voltro/web/middleware`) instead of a bare function, and each export carries its own `match`. Several middlewares per file are allowed; **at most one may match a given route**.
+
+  Migration: the codemod wraps the existing default export. That is behaviour-preserving — no `match` means every server-rendered route, which is what an unwrapped middleware did — and its note explains how to replace a hand-written path gate with a `match`.
+
+  **Why it was worth a break.** A hand-written `if (!req.pathname.startsWith('/app')) return` is invisible: nothing can tell you a middleware runs nowhere, or that two of them claim one route. `match` puts it where both the boot and `voltro doctor` can read it.
+
+  **The matcher speaks ROUTES, not URL patterns** — `under` / `routes` / `except`, validated against the app's own route patterns. A path matching no route refuses the boot instead of silently never firing. This is the deliberate difference from the `'/((?!api|_next/static|…).*)'` shape: our hook runs after route matching, so an app has never needed to know its own asset layout, and non-page requests are reachable only by asking (`assets: true`) — where, note, there is no render, so only `setCookies` takes effect.
+
+  An overlap refuses the boot and names both middlewares plus the route. Declaration order is not a semantic, "most specific wins" silently drops the broader hook, and merging needs a per-field rule nobody remembers — so two hooks writing one `authorization` header is a refusal, not a resolution.
+
+  **The web bundle budget moved UP, and the split is worth stating** because only one half is a cost the framework imposes:
+
+  | measured | before | after | | --- | --- | --- | | first load | 184 955 B | 185 309 B (**+354**) | | lazy route chunks | 3 502 B | 4 415 B (+913) |
+
+  The **+354 B of first load is the real price** — one `serverContext` chunk, 0.2 KB gz, which every app now carries whether or not it declares a middleware. That is the number to argue with, and it leaves 6.7 KB of headroom under the ceiling.
+
+  The +913 B is NOT a per-route regression: the fixture gained four routes (`exact`, `exact/[id]`, `mw`, `mw/skip`) to exercise the feature end to end, at 0.1–0.2 KB gz each, which accounts for the growth without remainder. Re-pinned with `--update` rather than by hand, so the `slackFloor` keeps ratcheting — a ceiling nobody lowers again silently permits re-inflating to the old number.
+
+### Fixed
+
+- **@voltro/data-transfer, @voltro/cli** — `voltro data export` could not export a table whose primary key is not named `id`, and one of its two failure modes reported success.
+
+  The keyset column was `columns.find(c => c.type === 'id')?.name ?? 'id'`, and `type: 'id'` is tagged only on a column that is BOTH the single-column primary key AND literally named `id` — identically in all four dialect introspectors. So any introspected table with another PK name was ordered by a column that does not exist. It now comes from the real primary key (the synthesised `<table>_pkey` index), with the declared `id()` column still winning where there is one.
+
+  **A composite or absent primary key is now REFUSED**, not silently ordered by the first column: keyset pagination on a non-unique order splits equal values across page boundaries, so rows are dropped or duplicated into a bundle that reports success. Bounded exports are recoverable; a quietly short backup is discovered at the restore.
+
+  **A requested table missing from the schema is refused too.** `scope: { kind: 'tables' }` used to drop unknown names, so a run that explicitly named a table wrote `"tables": []` and printed `export complete` with exit 0. `kind: 'all'` over an empty database is still a legal empty export — the asymmetry is deliberate: a named table is an expectation.
+
+  **Failure reasons survive.** `String(e?.message ?? e)` produced `"write table failed: "` with nothing after the colon — `??` falls back on null/undefined, and an Effect `TaggedError` carries an empty-string `message`. Every catch site in the exporter now reports tag, message or cause.
+
+  **New: `voltro data export --exclude a,b`** — everything except these, resolved against the live table list. It is the escape hatch the refusals above require; without it a single unkeyable table would block a whole-database export. An unknown name is refused for the same reason. Direct target only (the expansion needs the live table list), and it expands to an explicit `tables` scope, so the manifest records what was actually exported.
+
+  Reported with a reduced repro, a four-way variation over PK TYPES that ruled type out, and two disproved hypotheses. The affected tables include `@effect/cluster`'s own (`cluster_locks`, `cluster_migrations`), so no app running workflows could take a whole-database export.
+- **@voltro/database, @voltro/runtime, @voltro/cli** — `.encrypted()` had three writers and two encodings. The store wrote `encrypt(JSON.stringify(v))`; `encryptField` — the documented raw-SQL escape hatch — and `voltro db encrypt-column` wrote `encrypt(v)`. All three produce the same `enc:v1:` envelope and nothing distinguished them, so a value written by one and read by another either threw with the wrong diagnosis or came back subtly wrong (`decryptField` handed back the JSON encoding verbatim, quotes and all, raising nothing).
+
+  There is one encoding for every WRITE now, and every READ resolves BOTH forms — so **no data has to be rewritten and nothing is blocked**. That second half is the point: the old form is already on staging and production disks, and a fix that needs the rows rewritten before the app works is an outage with a migration attached.
+
+  Reading two forms is deterministic, not a heuristic. After decrypting, a parse failure is the raw form; a parse to a STRING is the JSON form; a parse to a non-string depends on the column's declared type (a text column cannot hold a number, so `12345` is a raw string that parsed by accident). The one case nothing can separate — a raw secret whose literal text is `"abc"`, quotes included — is stated in the code rather than hidden.
+
+  **`voltro db encrypt-column` verified itself against the wrong decoder.** It wrote the raw form and checked it with `cipher.decrypt` — a decoder nothing reads these columns with — so it reported success over columns the app could not read. It round-trips through `decodeFieldValue` now, the same function the store calls. A self-check against a decoder the runtime does not use is not a weaker check; it is a second opinion from the same mistake.
+
+  The command also NORMALISES rows in the old encoding as it goes (reported separately from the ones it encrypts), so an operator does not write a script per column. It skips anything ambiguous and anything it cannot decrypt.
+
+  **The width pre-flight measured the wrong thing after the encoding changed.** It sized the ciphertext from the PLAINTEXT's byte length while the cipher is handed the JSON encoding — two characters more at minimum, and more for every escape. Measured on a real MariaDB: a 63-byte value in a `varchar(135)` passed the check and the UPDATE answered `ER_DATA_TOO_LONG`, which is the failure that check exists to prevent, mid-column with the rest already converted. It measures the encoded length now, and the refusal says "encodes to" rather than "is" so an operator measuring their own column finds the number it names.
+
+  **Two dialect defects, both found by running the command against real servers.** SQL Server reports `-1` for `NVARCHAR(MAX)` — its spelling of unbounded — and the pre-flight read it as a one-character column, so it refused the widest column the dialect has and printed `declared as -1` at the operator. And SQLITE has no `information_schema` at all: the shared catalog query died there with `Failed to prepare statement` and no statement attached, on a dialect the command claims to support. It uses `pragma_table_info` now, reporting no length because sqlite enforces none.
+
+  Measured end to end on postgres, mysql, mariadb, mssql and sqlite: a table holding plaintext, the old encoding and the current encoding side by side converts, every row decodes back to its original value, a re-run writes nothing, and a wrong key refuses with exit 1.
+
+  **Backups and restores were never affected and now say so.** `voltro data export` reads through the raw dialect store, so ciphertext travels verbatim in either encoding — pinned by a test, because a future change that wrapped that store would put plaintext credentials in a bundle.
+- **@voltro/protocol, @voltro/cli** — Three findings from one consumer round, all of the same shape: something the framework knows and does not say.
+
+  **A decode failure on a GUARDED procedure now says the guard did not run.** The payload decodes before the handler, so a guard on a procedure with a malformed payload never gets the chance to refuse. A consumer auditing a guard called one with an incomplete payload, got a decode error instead of a `ScopeError`, and concluded the guard was not applied — the wrong conclusion in the dangerous direction. The title now carries `(guarded — the guard did NOT run: the payload failed to decode first, so this says nothing about access)`. It discloses nothing new: that a procedure is guarded is already visible to anyone who sends a VALID payload. An `openAccess:` declaration is not an enforced guard and gets no such sentence — `hasEnforcedGuard` is the one predicate, read by both the label and the wire error union, because two copies of that rule would disagree invisibly.
+
+  **`middleware.ts`'s `httpOnly` default is documented at the field, and warned about.** It defaults to `HttpOnly`, which is wrong for a session cookie a browser SDK reads back: Supabase's `createBrowserClient` reads `document.cookie`, so a forgotten `httpOnly: false` gives the browser a session it cannot see — the SSR render is perfect and the user is signed out at the first client-side call. The consumer only avoided shipping it because their probes already set the flag. `voltro dev` warns once per cookie when a session-shaped name is written with no `httpOnly` decision; an explicit decision either way silences it, because warning on a decision is how a diagnostic becomes noise.
+
+  **`voltro dev` restarts when `middleware.ts` changes.** It is loaded once per boot, that is documented, and a consumer read it and still lost an afternoon: they sabotaged the middleware, saw no change, and concluded it was not wired — in an environment where everything else hot-reloads. It now restarts through the same respawn a hard-restart field in `app.config.ts` uses, extracted so there is one copy of the `execArgv` inheritance and the signal forwarding.
+- **@voltro/cli** — `middleware.ts` now produces ONE view of the request that every downstream reader takes. Previously only `buildLoaderQuery` saw the hook's result, while the loader context (`ctx.headers`), the SSR request snapshot (`useServerRequest()`) and the locale resolver kept reading the raw request — four readers, two answers, within eighty lines of one function.
+
+  The consequence was worse than an inconsistency: a hook that renews purely via `setCookies` — no `headers` at all, which is the normal shape for a cookie-session IdP and the reason the response half exists — moved nothing for the render that ran it. The rpc call still sent the old `Cookie` header, because a renewed cookie only reached the browser.
+
+  `setCookies` is applied to the cookie jar before the render, the `Cookie` header is rebuilt from that jar (an explicit `cookie` in the hook's own `headers` still wins), and `maxAge <= 0` deletes, so a hook that signs someone out renders them signed out. Both SSR boot paths shadow the raw headers out of scope after the hook runs, so a new reader added below is correct without knowing any of this.
+- **@voltro/cli** — `voltro start` dropped `middleware.ts`'s `Set-Cookie` on **streamed** responses — which is the arm a plain `renderMode: 'ssr'` page takes, so it was the common case. The hook renewed the session server-side, the render used the fresh value, and the browser kept the consumed one. Against an IdP that rotates refresh tokens and detects reuse, that is worse than not renewing at all.
+
+  The cause is worth stating because it read as handled: a streamed response hands the socket to `stream(res)` and the caller never looks at the returned `headers`, so the `withCookies(...)` wrapper on that arm was dead code — sitting under a comment promising the cookies were written on every arm. The cookies now travel with the headers `streamSsrResponse` itself writes, and the dead wrapper is gone.
+
+  Found by booting real `voltro dev` and `voltro start` servers against a fixture and reading the response. Every unit test was green throughout, and the render's own HTML was correct — only the wire was wrong.
+
+---
+
 ## [0.40.0] — 2026-08-16
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -5,12 +5,15 @@ import { AuthMiddleware } from '@voltro/protocol';
 import { AuthStrategy } from '@voltro/protocol';
 import { CaughtUpVerdict } from '@voltro/database';
 import { ChangeEvent } from '@voltro/database';
+import { classifyConstraintViolation } from '@voltro/database';
 import { clearRetentions } from '@voltro/database';
 import { ConnectionCredential } from '@voltro/protocol';
 import { ConnectionInfo } from '@voltro/protocol';
 import { ConnectionInfoMiddleware } from '@voltro/protocol';
 import { ConnectionKind } from '@voltro/protocol';
 import { ConnectionState } from '@voltro/protocol';
+import { ConstraintFacts } from '@voltro/database';
+import { ConstraintKind } from '@voltro/database';
 import { Context } from 'effect';
 import { createServer } from 'node:http';
 import { Cron } from 'effect';
@@ -27,6 +30,7 @@ import { EventPayloadInvalid } from '@voltro/protocol';
 import { EventPayloadTooLarge } from '@voltro/protocol';
 import { EventResumePoint } from '@voltro/protocol';
 import { EventStreamEvent } from '@voltro/protocol';
+import { extractDbCause } from '@voltro/database';
 import { Fiber } from 'effect';
 import { FieldCipher } from '@voltro/database';
 import * as http from 'node:http';
@@ -40,6 +44,8 @@ import { InspectedStep } from '@voltro/workflow';
 import { InspectedWorkflow } from '@voltro/workflow';
 import { InspectStore } from '@voltro/workflow';
 import { inspectWorkflow } from '@voltro/workflow';
+import { isForeignKeyViolation } from '@voltro/database';
+import { isQueryTimeout } from '@voltro/database';
 import { Kv } from '@voltro/kv';
 import { KvStoreShape } from '@voltro/kv';
 import { Layer } from 'effect';
@@ -1864,6 +1870,8 @@ export declare const CLAIM_RETENTION_BUCKETS = 64;
  */
 export declare const claimGraceMs: (bucketWidthMs: number | undefined) => number;
 
+export { classifyConstraintViolation }
+
 /**
  * Decide whether a state-changing request may proceed.
  *
@@ -2129,6 +2137,68 @@ export declare interface ConnectionTokens {
     readonly scopes: ReadonlyArray<string>;
 }
 
+export { ConstraintFacts }
+
+export { ConstraintKind }
+
+/**
+ * The database refused a write because it broke an integrity rule the SCHEMA
+ * declares — a foreign key, a unique index, a NOT NULL, a CHECK.
+ *
+ * **Why this is typed at all.** Without it the driver failure is a `SqlError`,
+ * which the rpc layer collapses to a bare `InternalError` on purpose (a
+ * `SqlError`'s text is not safe to forward — see below). The caller then gets
+ * "something went wrong" for a failure that is entirely about the input it just
+ * sent, and the only way to find out which rule fired is to re-run the
+ * statement by hand against the database. A consumer reported doing exactly
+ * that.
+ *
+ * **Why it carries names and not the driver's sentence.** The temptation is to
+ * forward `cause.message`, and it is measured to be wrong: postgres attaches
+ * `Failing row contains (…)` — the complete row, every column — to a not-null
+ * and a check violation; mysql and mssql echo the duplicate VALUE on a unique
+ * violation. A constraint or column NAME is schema, which this framework
+ * already puts on the wire (`TableValidationFailed.table`). A row is data, and
+ * the caller who provoked the error is not automatically entitled to it.
+ *
+ * **Not every dialect can fill every field.** sqlite reports a foreign-key
+ * failure as the bare sentence `FOREIGN KEY constraint failed` — no name, no
+ * column, no direction — so `constraint` is absent there and the direction is
+ * inferred from the operation. `kind` is the field that is always right.
+ */
+export declare class ConstraintViolation extends ConstraintViolation_base {
+    /**
+     * A sentence built from the fields above and nothing else.
+     *
+     * It exists because an undeclared tagged error reaches the client through
+     * `defectMessage`, which renders `String(error)` — and a `Schema.TaggedError`
+     * with no `message` renders as `[object Object]`. Without this getter the
+     * caller would get a correctly-typed error carrying no information, which is
+     * the same dead end in a different shape.
+     */
+    get message(): string;
+}
+
+declare const ConstraintViolation_base: Schema.TaggedErrorClass<ConstraintViolation, "ConstraintViolation", {
+    readonly _tag: Schema.tag<"ConstraintViolation">;
+} & {
+    /**
+     * Which rule fired. `foreignKey` = the row you referenced does not exist;
+     * `foreignKeyInUse` = this row may not go, others still reference it. They
+     * are opposite situations with opposite fixes, so a UI branches on them
+     * separately.
+     */
+    kind: Schema.Literal<["foreignKey", "foreignKeyInUse", "unique", "notNull", "check"]>;
+    /** The table the write targeted — the framework's own name for it, not the driver's. */
+    table: typeof Schema.String;
+    /** Which store op was attempted: 'insert' | 'update' | 'delete' | …. */
+    operation: typeof Schema.String;
+    /** The constraint / index name, when the dialect names one. */
+    constraint: Schema.optional<typeof Schema.String>;
+    /** The column, when the dialect names one instead of (or beside) a constraint. */
+    column: Schema.optional<typeof Schema.String>;
+}>;
+
 export declare type CoordinatedEffect = () => void | CoordinatedTickOutcome | Promise<void | CoordinatedTickOutcome>;
 
 export declare interface CoordinatedScheduleDeps {
@@ -2742,11 +2812,19 @@ export declare const decideApprovalInvocation: (input: {
     readonly status: "approved" | "rejected";
 }>;
 
-/** Decrypt a value produced by `encryptField` / an `.encrypted()` column. A
- *  value that is NOT ciphertext (`enc:v1:…`) is returned unchanged — so a
- *  raw-SQL read path can be switched to encryption while pre-existing plaintext
- *  rows keep working until they're re-written encrypted. Throws only when no
- *  cipher is registered (a genuine ciphertext with a wrong key throws GCM). */
+/**
+ * Decrypt a value produced by `encryptField` or by an `.encrypted()` column —
+ * one encoding, so that sentence is now true in both directions.
+ *
+ * A value that is NOT ciphertext (`enc:v1:…`) is returned unchanged, so a
+ * raw-SQL read path can be switched to encryption while pre-existing plaintext
+ * rows keep working until they're re-written encrypted.
+ *
+ * Values written under the OLD raw encoding still read: the decode resolves both
+ * forms deterministically from what the plaintext parses to. That matters because
+ * the old form is already on production disks, and a fix that needs the data
+ * rewritten before the app works is an outage with a migration attached.
+ */
 export declare const decryptField: (value: string) => string;
 
 export declare const DEFAULT_ANALYTICS_MIRROR_TUNABLES: AnalyticsMirrorTunables;
@@ -3347,8 +3425,18 @@ export declare const emptySchemaRegistry: SchemaRegistry;
  *  should be observed are constructed — `observeStore` decides once, per store. */
 export declare const enableGraphObservation: () => void;
 
-/** Encrypt a value with the registered field cipher (same one `.encrypted()`
- *  columns use). Throws if no cipher is registered. */
+/**
+ * Encrypt a value with the registered field cipher, in the SAME encoding an
+ * `.encrypted()` column uses. Throws if no cipher is registered.
+ *
+ * It used to be `cipher.encrypt(plaintext)` while the store wrote
+ * `cipher.encrypt(JSON.stringify(v))` — two encodings, one `enc:v1:` envelope,
+ * nothing to tell them apart. The doc above promises these helpers "expose the
+ * SAME registered cipher so those paths can encrypt on write and decrypt on read
+ * by hand", and a consumer read that as interchangeable, which it said and was
+ * not: their session rows written here were unreadable through the store, and
+ * the error blamed the key.
+ */
 export declare const encryptField: (plaintext: string) => string;
 
 /**
@@ -4286,7 +4374,7 @@ export declare interface ExperimentVariantSpec {
  *  when the header is missing/invalid (no parent → a fresh root span). */
 export declare const externalSpanFromTraceparent: (header: string | undefined | null) => Tracer.ExternalSpan | undefined;
 
-export declare const extractDbCause: (err: unknown) => Record<string, unknown>;
+export { extractDbCause }
 
 export declare interface FieldChange {
     readonly from: unknown;
@@ -4859,10 +4947,7 @@ export declare const isExpectationDefinition: (value: unknown) => value is Expec
 
 export declare const isExperimentDefinition: (value: unknown) => value is ExperimentDefinition;
 
-/** Foreign-key-violation SQLSTATE / errno across dialects (pg 23503, mysql/maria
- *  1452, mssql 547, sqlite). Used to turn an opaque tenant-FK SqlError into a
- *  typed error. */
-export declare const isForeignKeyViolation: (dbCause: Record<string, unknown>) => boolean;
+export { isForeignKeyViolation }
 
 /**
  * True iff the app is idle at this instant on every axis AND no wakeup is
@@ -4917,14 +5002,7 @@ export declare const isOrglessUserSubject: (subject: {
     readonly tenantId?: string | null;
 } | null | undefined) => boolean;
 
-/** A query cancelled for exceeding the `statementTimeoutMs` deadline, across
- *  dialects: pg `57014` (query_canceled — what `statement_timeout` raises),
- *  MySQL `3024` (ER_QUERY_TIMEOUT), MariaDB `1969` (ER_STATEMENT_TIMEOUT), mssql
- *  `ETIMEOUT` (tedious request timeout), sqlite `SQLITE_INTERRUPT`. NOT a
- *  transient error — a re-run just repeats the runaway, so it must not retry
- *  (`servePipeline`'s transient set deliberately excludes it). Lets a consumer /
- *  observability layer name the failure instead of reading an opaque SqlError. */
-export declare const isQueryTimeout: (dbCause: Record<string, unknown>) => boolean;
+export { isQueryTimeout }
 
 /**
  * Optimistic-concurrency guard: an undo is safe only when the row still looks
@@ -9028,7 +9106,7 @@ export declare interface StoreCredentialInput {
  * a mutation's `error:` schema when you want every kind surfaced
  * typed to the client.
  */
-export declare type StoreError = TenantScopeViolation | TenantRowNotFound | ServerOnlyColumnWrite | StoreOperationFailed | TableValidationFailed;
+export declare type StoreError = TenantScopeViolation | TenantRowNotFound | ServerOnlyColumnWrite | StoreOperationFailed | TableValidationFailed | ConstraintViolation;
 
 export declare interface StoreMiddlewareContext {
     readonly subject: Subject;