@voltro/cli 0.41.0 → 0.42.0

package/dist/serveCommand-gj7MsqXY.js

@@ -0,0 +1,2 @@
+import { n as e } from "./serveCommand-C512kzZA.js";
+export { e as runServeDispatch };

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
 import { t as e } from "./loadEnv-D9nEOClM.js";
 import { r as t } from "./appModuleLoader-C9r9mxZt.js";
 import { i as n } from "./dialectDriver-czCHYpeH.js";
-import { t as r } from "./serveCommand-Cba_M2Su.js";
+import { t as r } from "./serveCommand-C512kzZA.js";
 export { e as loadDotEnv, t as registerAppModules, n as registerDriver, r as runServe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -715,22 +715,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.41.0",
-    "@voltro/cache": "0.41.0",
-    "@voltro/data-transfer": "0.41.0",
-    "@voltro/database": "0.41.0",
-    "@voltro/env": "0.41.0",
-    "@voltro/kv": "0.41.0",
-    "@voltro/logger": "0.41.0",
-    "@voltro/plugin-auth": "0.41.0",
-    "@voltro/plugin-broadcast": "0.41.0",
-    "@voltro/plugin-mail": "0.41.0",
-    "@voltro/plugin-storage": "0.41.0",
-    "@voltro/plugin-webhooks": "0.41.0",
-    "@voltro/protocol": "0.41.0",
-    "@voltro/runtime": "0.41.0",
-    "@voltro/serverless": "0.41.0",
-    "@voltro/workflow": "0.41.0",
+    "@voltro/ai": "0.42.0",
+    "@voltro/cache": "0.42.0",
+    "@voltro/data-transfer": "0.42.0",
+    "@voltro/database": "0.42.0",
+    "@voltro/env": "0.42.0",
+    "@voltro/kv": "0.42.0",
+    "@voltro/logger": "0.42.0",
+    "@voltro/plugin-auth": "0.42.0",
+    "@voltro/plugin-broadcast": "0.42.0",
+    "@voltro/plugin-mail": "0.42.0",
+    "@voltro/plugin-storage": "0.42.0",
+    "@voltro/plugin-webhooks": "0.42.0",
+    "@voltro/protocol": "0.42.0",
+    "@voltro/runtime": "0.42.0",
+    "@voltro/serverless": "0.42.0",
+    "@voltro/workflow": "0.42.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -707,7 +707,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.41.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.42.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.41.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.42.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/cli.md

@@ -2625,8 +2625,42 @@ voltro data import --target api --api-url https://api.example.com --token $SECRE
 voltro data import ./out --assets            # also restore blobs
 voltro data import ./out --no-verify         # skip checksum/row-count verification
 voltro data import ./out --force             # import despite schema drift AND cross-dialect warnings
+voltro data import ./out --tables users,teams   # load only these tables out of the bundle
+voltro data import ./out --dry-run              # report what would move; write nothing
 ```
 
+**`--dry-run` and `--tables` work on BOTH targets**, including `--target api`. On the api
+path they travel as `x-import-dry-run` / `x-import-tables`, and the response echoes
+`{ "dryRun": true, "wrote": false }` so a preview is never mistaken for a write.
+
+A dry run reaches every verdict a real run reaches — schema fit, cross-dialect portability,
+mode legality, the table selection — and stops at the first line that would write. It does
+NOT read per-table checksums (those stream during the load) and cannot see a conflict that
+depends on the target's current rows; the command says both out loud, because a preview
+over-read is worse than no preview.
+
+`--tables` names tables the BUNDLE carries. A name it does not carry is refused, listing
+what it does — a silently-ignored table name is how a run scoped to one table writes the
+whole bundle.
+
+### A flag this command does not read is an ERROR
+
+Every `voltro data` subcommand declares the flags it reads, per target, and refuses anything
+else instead of ignoring it:
+
+```text
+✗ voltro data import: --no-verify is not read with --target api (it is a --target direct
+  flag). Remove it, or change --target.
+✗ voltro data export: --mode is not a `export` flag (it belongs to `voltro data import`).
+✗ voltro data import: unknown flag --drynrun. Run `voltro data --help` for the flags this
+  command reads.
+```
+
+The refusal happens before anything boots, so a mistyped flag costs you a message rather
+than a run. On a command whose job is moving data into a live system, silence is the wrong
+default: an accepted-and-ignored flag turns a typo into a no-op whose only evidence of
+working is that nothing complained.
+
 Import is **integrity-checked** (each table's checksum + row count verified as it decodes; each asset re-hashed against its content address), applies tables in **FK-parent-first order**, and a resumed run skips already-applied tables via the ledger.
 
 ### Postgres targets bulk-load via COPY
@@ -2651,16 +2685,31 @@ identical, only the speed differs.
 
 ### Schema-drift pre-flight
 
-Every bundle records the **schema fingerprint** of the source it was exported from (a stable hash of the schema shape — the same fingerprint prod boot uses to detect drift). Before touching the target, `import` **recomputes the target app's fingerprint the same way** and compares it to the bundle's. On a mismatch it **refuses, fail-closed, before any row lands** — a drifted target (a missing column, a renamed table) would otherwise fail mid-load with a raw database error after some rows already committed:
+The question the pre-flight asks is **"will the rows this bundle carries fit this target?"** — not "are these two schemas identical". It compares the **intersection**: for every table the bundle carries, the columns and types must exist on the target, and a column the target REQUIRES (NOT NULL, no default) that the bundle carries no value for is refused too. On a problem it **refuses, fail-closed, before any row lands**:
 
 ```text
-✗ schema drift: the target schema (fingerprint d6ba94b0…) differs from the bundle's
-  source (f67942f6…). Refusing before the table phase.
-    items.extra: in the target, not in the bundle
-  Re-export against the current schema, or pass --force to import anyway.
+✗ schema drift: refusing before the table phase.
+    table 'items' is in the bundle but MISSING from the target — its rows have nowhere to go
+    orders.total: type 'integer' (bundle) vs 'text' (target)
+    users.region: the target requires it (NOT NULL, no default) and the bundle carries no
+      value — every row of this table would fail
 ```
 
-The error names the drift — the tables/columns that moved (down to per-column granularity for the tables the bundle carries) — so you can see exactly what changed. **`--force`** downgrades the refusal to a **loud warning** and proceeds (the operator has accepted that the shapes differ). Over the `--target api` path the same check runs **on the instance** against its declared schema and returns **`409` schema drift** with the fingerprints + diff; `--force` sends `x-import-force: 1` to override.
+Every line is something that would break the load. Tables and columns the target has and
+the bundle does not are **untouched by definition** and are never reported — that is the
+normal shape of any cross-environment seed, and refusing on it would make `--force` the
+routine way to run an import and take the protection with it.
+
+Both fingerprints are still reported (they are what you paste when asking for help), and an
+identical pair is a fast path that skips the comparison. But **differing fingerprints are
+not on their own a refusal**: a bundle's fingerprint covers its SOURCE schema regardless of
+export scope, so a one-table export out of a 75-table database carries the 75-table
+fingerprint.
+
+**`--force`** downgrades the refusal to a **loud warning** and proceeds. Over the
+`--target api` path the same check runs **on the instance** against its declared schema and
+returns **`409` schema drift** with the fingerprints + diff; `--force` sends
+`x-import-force: 1` to override.
 
 The pre-flight only runs when the importer has a target schema (the CLI introspects it; the API endpoint uses the instance's declared schema). Importing into a fresh/empty database with no comparable schema simply skips the check.
 
@@ -2757,6 +2806,17 @@ Both export and import checkpoint into a small **`.ledger.json`** and can be re-
 
 Net: interrupt an export or import at any point — network drop, `Ctrl-C`, OOM-killed pod — and re-running the same command finishes the job without duplicating work or corrupting the target.
 
+**A re-run of a COMPLETED import writes nothing, and says so.** The ledger lives in the bundle directory, so re-importing a bundle whose tables are all recorded skips every one of them. That is resume working — but the returned report counts the BUNDLE's rows either way, so `import complete … 10593 rows` would otherwise print over a target you had just truncated. The import warns instead:
+
+```text
+⚠ resume: 5 of 5 table(s) were already applied by an earlier run of THIS bundle
+  directory, so this run wrote NO rows for them — that is every table in the
+  bundle, so nothing was written at all. Tables: tenants, teams, projects,
+  actors, auditLogs. Delete ./out/.import.ledger.json to force a full re-import.
+```
+
+The `--target api` path is unaffected: the instance unpacks each upload into a fresh temp directory, so it never carries a ledger between runs.
+
 ### Progress & observability
 
 A multi-hour job is not a black box. Both pipelines signal per **table** — never per row, so the reporting never slows the hot path:
@@ -2927,6 +2987,13 @@ The opt-out is `onUnclassified: 'keep'` (or `'null'`), which makes masking **fai
 unclassified columns. Discouraged — it defeats the guarantee; prefer classifying the column.
 See [why fail-closed](/docs/database/sensitivity#why-fail-closed).
 
+**A policy this build cannot carry out is refused too**, before a row is read. An action of a
+shape the applier does not understand — a typo like `{ action: 'fake', kind: 'email' }` where
+the shape is `{ fake: 'email' }` — used to fall through to "copy the value", so the export
+succeeded and shipped the raw column while the audit line counted it as masked. It is now a
+`MaskingError` with `invalidActions`, reported separately from `unclassified` because the two
+have different fixes: one needs a classification, the other needs the policy corrected.
+
 ## `--dry-run` — preview without writing
 
 Preview a masking export **without writing a bundle** — the trust surface before real data

package/templates/agent-docs/data.md

@@ -4767,6 +4767,7 @@ declared it anyway, that is harmless — the union is the same either way.
 | `ServerOnlyColumnWrite` | `@voltro/runtime` | A `crud.create` / `crud.update` input tried to set a [`.serverOnly()`](/docs/database/sensitivity) column — `{ table, columns }`. |
 | `StoreOperationFailed` | `@voltro/runtime` | The underlying store operation failed (transient). |
 | `TableValidationFailed` | `@voltro/runtime` | A `table().validate(Schema)` row check rejected the write. |
+| `ConstraintViolation` | `@voltro/runtime` | The database refused the write on a foreign key / unique / NOT NULL / CHECK — `{ kind, table, operation, constraint?, column? }`. See below. |
 | `CacheError` | `@voltro/cache` | A cache backend op failed — `{ operation, key, cause }`. |
 | `RateLimited` | `@voltro/plugin-ratelimit` | The limiter rejected the call — `{ limit, retryAfterMs, resetAtMs }`. |
 | `TenantMismatch` | `@voltro/plugin-multitenancy` | `assertOwnTenant(input.tenantId, subject)` rejected a cross-tenant write. |
@@ -4775,6 +4776,38 @@ Each plugin that ships an error (`RateLimited`, `EntitlementExceeded`, `StorageE
 
 All carry `_tag` + typed payloads, all narrow correctly on the client.
 
+### When the database refuses the write
+
+An integrity rule your schema declares — a `reference()`, a `.unique()`, a non-nullable column, a `.check()` — is enforced by the database, not by the handler. When it fires you get a `ConstraintViolation`:
+
+```ts
+{ _tag: 'ConstraintViolation',
+  kind: 'foreignKey', table: 'tasks', operation: 'insert',
+  constraint: 'tasks_laneId_fkey' }
+```
+
+`kind` is the field to branch on, and it is the one field every dialect can always fill:
+
+| `kind` | Means | The caller's fix |
+|---|---|---|
+| `foreignKey` | the row you referenced does not exist | point at a real row |
+| `foreignKeyInUse` | this row may not go — others still reference it | delete the children first, or don't delete |
+| `unique` | a row with this value already exists | pick another value |
+| `notNull` | the column requires a value | send one |
+| `check` | the row does not satisfy a declared `.check()` | fix the value |
+
+`constraint` and `column` are filled where the dialect names them. sqlite reports a foreign-key failure as the bare sentence `FOREIGN KEY constraint failed` — no name, no column — so `constraint` is absent there and the direction is inferred from the operation.
+
+**It carries names, never the driver's sentence, and that is deliberate.** The message the database produces contains row DATA on most engines: postgres attaches `Failing row contains (…)` — the *complete* row, every column, [`.sensitive()`](/docs/database/sensitivity) ones included — to a not-null and a check violation; mysql and mssql echo the duplicate value on a unique violation. A constraint name is schema, the same class of fact `TableValidationFailed.table` already puts on the wire. A row is data, and the caller who provoked the error is not automatically entitled to it. The full driver text is in the server log, with the trace id.
+
+Declare it in `error:` to pattern-match it:
+
+```ts
+error: Schema.Union(ConstraintViolation, MyDomainError),
+```
+
+If you do not, it still reaches the client — collapsed to `InternalError` like any undeclared error, but carrying its own sentence (`ConstraintViolation: foreign key tasks_laneId_fkey on tasks: the referenced row does not exist`) rather than the opaque `Failed to execute statement` a raw `SqlError` produces.
+
 ## Loader errors
 
 Loaders run in the web app — they receive `{ params, query, headers, signal }`, NOT a server `ctx` with `.store`. A loader reaches the backend through `query(...)` (the `POST /rpc` path, server-side only). It short-circuits with the branded control-flow signals `NotFoundError` / `RedirectError`:

package/templates/agent-docs/whats-new.md

@@ -1,4 +1,4 @@
-# What's new in 0.41.0
+# What's new in 0.42.0
 
 Read this FIRST when a task touches an area you have not worked in recently.
 It is the cheapest way to notice that the framework grew the thing you were
@@ -9,70 +9,93 @@ BREAKING entries name a codemod; run `voltro update` to apply it.
 
 ### ⚠ 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**.
+- **@voltro/cli, @voltro/data-transfer** — **Two security defects on the data-transfer surface, both found by using the feature rather than by reading it.**
 
-  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`.
+  **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.
 
-  **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.
+  `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`.
 
-  **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 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.
 
-  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 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.
 
-  **The web bundle budget moved UP, and the split is worth stating** because only one half is a cost the framework imposes:
+### Added
 
-  | measured | before | after | | --- | --- | --- | | first load | 184 955 B | 185 309 B (**+354**) | | lazy route chunks | 3 502 B | 4 415 B (+913) |
+- **@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`.
 
-  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.
+  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.
 
-  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.
+  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/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.
+- **@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.
 
-  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 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.
 
-  **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.
+  **`--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.
 
-  **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.
+  **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.
 
-  **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.
+  **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.
 
-  **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.
+  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`).
 
-  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).
+  **Three more, found by running the whole thing against live MariaDB and MySQL** rather than against sqlite:
 
-  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.
+  - 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.
 
-  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.
+  `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.
 
-  **`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.
+  `parseEnumCheck` also learned MySQL's rendering. The same clause is stored differently:
 
-  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.
+  mariadb 11 `status` in ('draft','live','done') mysql 8.4 (`status` in (_latin1'draft',_latin1'live',_latin1'done'))
 
-  **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.
+  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`.
 
-  **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.
+  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.
 
-  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.
+  `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.
 
-  **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.
+  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.
 
-  **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.
+  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.
 
-  **`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.
+  **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`).
 
-  **`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.
+  `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.
 
-  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.
+  **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.
 
-  `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.
+  `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.
 
-  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.
+  **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.
 
-  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.
+  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.

package/templates/apps/api-ai/package.json

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.41.0",
-    "@voltro/cli": "0.41.0",
-    "@voltro/database": "0.41.0",
-    "@voltro/env": "0.41.0",
-    "@voltro/protocol": "0.41.0",
-    "@voltro/runtime": "0.41.0",
+    "@voltro/ai": "0.42.0",
+    "@voltro/cli": "0.42.0",
+    "@voltro/database": "0.42.0",
+    "@voltro/env": "0.42.0",
+    "@voltro/protocol": "0.42.0",
+    "@voltro/runtime": "0.42.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.41.0",
+    "@voltro/testing": "0.42.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-auth/package.json

@@ -13,17 +13,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.41.0",
-    "@voltro/database": "0.41.0",
-    "@voltro/env": "0.41.0",
-    "@voltro/plugin-auth": "0.41.0",
-    "@voltro/protocol": "0.41.0",
-    "@voltro/runtime": "0.41.0",
-    "@voltro/sql-postgres": "0.41.0",
+    "@voltro/cli": "0.42.0",
+    "@voltro/database": "0.42.0",
+    "@voltro/env": "0.42.0",
+    "@voltro/plugin-auth": "0.42.0",
+    "@voltro/protocol": "0.42.0",
+    "@voltro/runtime": "0.42.0",
+    "@voltro/sql-postgres": "0.42.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.41.0",
+    "@voltro/testing": "0.42.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-backend/package.json

@@ -16,16 +16,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.41.0",
-    "@voltro/database": "0.41.0",
-    "@voltro/env": "0.41.0",
-    "@voltro/plugin-multitenancy": "0.41.0",
-    "@voltro/protocol": "0.41.0",
-    "@voltro/runtime": "0.41.0",
+    "@voltro/cli": "0.42.0",
+    "@voltro/database": "0.42.0",
+    "@voltro/env": "0.42.0",
+    "@voltro/plugin-multitenancy": "0.42.0",
+    "@voltro/protocol": "0.42.0",
+    "@voltro/runtime": "0.42.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.41.0",
+    "@voltro/testing": "0.42.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-backend-deactivation/package.json

@@ -13,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.41.0",
-    "@voltro/database": "0.41.0",
-    "@voltro/env": "0.41.0",
-    "@voltro/plugin-deactivation": "0.41.0",
-    "@voltro/protocol": "0.41.0",
-    "@voltro/runtime": "0.41.0",
+    "@voltro/cli": "0.42.0",
+    "@voltro/database": "0.42.0",
+    "@voltro/env": "0.42.0",
+    "@voltro/plugin-deactivation": "0.42.0",
+    "@voltro/protocol": "0.42.0",
+    "@voltro/runtime": "0.42.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.41.0",
+    "@voltro/testing": "0.42.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"