@voltro/cli 0.43.1 → 0.44.0

package/dist/serveCommand-Dg_E1ev4.js

@@ -0,0 +1,2 @@
+import { n as e } from "./serveCommand-BlnAlNQg.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-C8xzYCwa.js";
+import { t as r } from "./serveCommand-BlnAlNQg.js";
 export { e as loadDotEnv, t as registerAppModules, n as registerDriver, r as runServe };

package/dist/{updateCommand-CrI9B4d7.js → updateCommand-BvRidHp6.js}

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-Cnnz4-I7.js";
+import { n as e, r as t, t as n } from "./codemodRunner-BKTnaGOz.js";
 import { basename as r, dirname as i, join as a, relative as o, resolve as s } from "node:path";
 import { existsSync as c, readFileSync as l, readdirSync as u, statSync as d, writeFileSync as f } from "node:fs";
 import { totalmem as p } from "node:os";

package/dist/updateCommand-DcKVmLVN.js

@@ -0,0 +1,2 @@
+import { f as e, p as t } from "./updateCommand-BvRidHp6.js";
+export { e as runApplyCodemods, t as runUpdateCommand };

package/dist/{webhooksCommand-BXUP5YjW.js → webhooksCommand-BfO_JF2b.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-D0E5x2Ue.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-BZO5aLdr.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.43.1",
+  "version": "0.44.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -634,6 +634,12 @@
         "title": "`DanglingReferenceError` → `RowsRefusedError` (named for the outcome, not a guessed cause)",
         "kind": "transform"
       },
+      {
+        "version": "0.44.0",
+        "id": "0.44.0/01_import-outcome",
+        "title": "`runImport` returns an ImportOutcome — read `.manifest` for the bundle",
+        "kind": "manual"
+      },
       {
         "version": "0.5.0",
         "id": "0.5.0/01_one-terminal-exactly-one",
@@ -721,22 +727,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.43.1",
-    "@voltro/cache": "0.43.1",
-    "@voltro/data-transfer": "0.43.1",
-    "@voltro/database": "0.43.1",
-    "@voltro/env": "0.43.1",
-    "@voltro/kv": "0.43.1",
-    "@voltro/logger": "0.43.1",
-    "@voltro/plugin-auth": "0.43.1",
-    "@voltro/plugin-broadcast": "0.43.1",
-    "@voltro/plugin-mail": "0.43.1",
-    "@voltro/plugin-storage": "0.43.1",
-    "@voltro/plugin-webhooks": "0.43.1",
-    "@voltro/protocol": "0.43.1",
-    "@voltro/runtime": "0.43.1",
-    "@voltro/serverless": "0.43.1",
-    "@voltro/workflow": "0.43.1",
+    "@voltro/ai": "0.44.0",
+    "@voltro/cache": "0.44.0",
+    "@voltro/data-transfer": "0.44.0",
+    "@voltro/database": "0.44.0",
+    "@voltro/env": "0.44.0",
+    "@voltro/kv": "0.44.0",
+    "@voltro/logger": "0.44.0",
+    "@voltro/plugin-auth": "0.44.0",
+    "@voltro/plugin-broadcast": "0.44.0",
+    "@voltro/plugin-mail": "0.44.0",
+    "@voltro/plugin-storage": "0.44.0",
+    "@voltro/plugin-webhooks": "0.44.0",
+    "@voltro/protocol": "0.44.0",
+    "@voltro/runtime": "0.44.0",
+    "@voltro/serverless": "0.44.0",
+    "@voltro/workflow": "0.44.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.43.1** | `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.44.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.43.1** | `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.44.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

@@ -2643,6 +2643,30 @@ over-read is worse than no preview.
 what it does — a silently-ignored table name is how a run scoped to one table writes the
 whole bundle.
 
+### Every `import` option, in one place
+
+| Option | Default | What it does |
+|---|---|---|
+| `--mode upsert\|append\|replace` | `upsert` | How rows are written. See the table below. |
+| `--on-conflict skip\|fail` | `skip` | `append` only: what to do when the primary key already exists. |
+| `--atomic` | **on for `replace`**, off otherwise | Wrap the whole table phase in ONE transaction — readers see the import all-or-nothing. |
+| `--no-atomic` | — | Opt out of that. See the trade below. |
+| `--tables a,b` | every table | Import only these tables from the bundle. |
+| `--dry-run` | off | Run every pre-flight and report what WOULD move; write nothing. |
+| `--force` | off | Proceed despite schema drift AND cross-dialect warnings. |
+| `--no-verify` | off | Skip per-table checksum verification (direct target only). |
+| `--allow-live` | off | Override the refusal to write directly into a database a live instance is serving (direct target only). |
+| `--assets` | off | Restore blobs as well as rows. |
+| `--passphrase <s>` | — | Decrypt an `--encrypt`ed bundle (direct target only; over the api the CLI decrypts before sending). |
+| `--target direct\|api` | `direct` | Write straight to the database, or through a running instance's admin endpoint. |
+| `--api-url <url>` / `--token <secret>` | — | Required by `--target api`. The token must equal the instance's data-transfer secret. |
+| `--bundle-key <key>` | — | `--target api`: have the instance PULL the archive from object storage instead of uploading it. |
+| `--chunk-size <mb>` | 16 | `--target api`: bytes per upload chunk. Chunking engages automatically above one chunk. |
+| `--timeout <seconds>` | none | `--target api`: give up waiting for the instance. Default is to wait as long as the import takes. |
+| `--json` | off | Machine-readable result. |
+
+A flag this subcommand does not read is refused, not ignored — see below.
+
 ### A flag this command does not read is an ERROR
 
 Every `voltro data` subcommand declares the flags it reads, per target, and refuses anything
@@ -2729,9 +2753,67 @@ Anything still unresolvable — the parent row exists in **neither the bundle no
 |---|---|---|---|
 | `upsert` (default) | INSERT-or-UPDATE by primary key | sync / idempotent re-import | overwrites per row |
 | `append` | INSERT only | additive data (event log, new seed) | `--on-conflict skip` (default) or `fail` |
-| `replace` | TRUNCATE the target tables (children-first) then INSERT | full refresh — target ends up **exactly** the bundle | — |
+| `replace` | empty the target tables, then INSERT | full refresh — target ends up **exactly** the bundle | — |
+
+`replace` **refuses a partial bundle** (a subset / tenant / table scope): emptying would delete rows the bundle never carried. Re-export with full scope, or use `upsert`. (`append --on-conflict fail` throws on a duplicate primary key only where the store enforces the constraint — every SQL dialect does; the in-memory dev store overwrites.)
+
+#### How `replace` empties the target, and what it refuses
+
+The bundle's tables are emptied **as one unit, in one transaction, with referential integrity suspended for the duration** — not table by table. Both halves matter:
+
+- **All or nothing — the emptying AND the load.** `--mode replace` runs the whole table phase in ONE transaction by default, so a run that cannot finish leaves the target exactly as it found it. That default is a correction: the guarantee used to cover only the emptying, and a replace that died partway through the *load* left the target emptied of its old rows and holding part of the new ones. There is no useful state for a replace to stop in, which is why it is the default rather than a flag you have to know about.
+
+  One transaction also closes a window that is easy to miss. Between the delete and the load the target is empty, and if the database is being served, the application writes into that gap — a row it creates on demand is then a primary-key conflict against the same row arriving from the bundle. With one transaction the concurrent writer waits instead of racing.
+
+  `--no-atomic` opts out, and the trade is real: every write to those tables waits for the load, so on a bundle that takes minutes, so does the wait. On postgres it also re-enables the bulk `COPY` loader, which cannot join a transaction it does not own — an atomic run says so once rather than being quietly slower.
+- **No ordering can replace the suspension.** MySQL, MariaDB and SQL Server check a foreign key as each *row* is deleted, so a table that references **itself** cannot be emptied at all by ordering tables — the conflict is between two rows of one of them. `createdBy → actors` on the `actors` table is exactly that shape, and it is what an audit mixin on an actor table produces. (Postgres needs no suspension: a multi-table `TRUNCATE` covers the whole set at once.)
+
+What it will **not** do is reach outside the bundle. If a table the bundle does **not** carry holds rows that reference one it does, `replace` refuses **before deleting anything** and names them:
+
+```
+replace cannot empty this target: 1 table(s) OUTSIDE the bundle hold rows that reference
+tables INSIDE it. Emptying the bundle's tables would leave those rows pointing at nothing,
+and the bundle cannot restore them.
+  webhookDeliveries (4021 rows): createdBy → actors, updatedBy → actors
+Nothing has been deleted. Either re-export with a scope that includes those tables, or use
+--mode upsert if those rows are meant to survive.
+```
+
+An **empty** table outside the bundle blocks nothing — a schema always carries tables an environment has never written to.
 
-`replace` **refuses a partial bundle** (a subset / tenant / table scope): truncating would delete rows the bundle never carried. Re-export with full scope, or use `upsert`. (`append --on-conflict fail` throws on a duplicate primary key only where the store enforces the constraint — every SQL dialect does; the in-memory dev store overwrites.)
+One consequence of emptying in bulk: the delete itself emits **no change events** (one per row is not affordable at bundle scale). Over `--target api` that is covered — an import through the instance's own process asks every live subscription to re-read once it lands, the same coarse refresh the framework uses after a broadcast gap. Over `--target direct` there is no live instance to tell, which is the whole reason that path is guarded.
+
+#### Which mode for which job
+
+| You want | Mode | Why |
+|---|---|---|
+| Keep a staging database in step with a production export, re-runnable | `upsert` | Idempotent per row: run it as often as you like, the result is the same. |
+| Add an event log / new seed data without touching what is there | `append --on-conflict skip` | Insert-only, and a row that already exists is left alone rather than overwritten. |
+| Catch a duplicate instead of silently skipping it | `append --on-conflict fail` | The import stops and names the row. Use when a duplicate means the bundle is wrong. |
+| Make a target become **exactly** a bundle — replace an environment | `replace` (full-scope bundle) | Empties the bundle's tables first, so rows the bundle does not carry are gone. |
+| The same, against a database that is being served right now | `replace --atomic` | One transaction: readers see the old state until commit, the new one after. Never a half-loaded table. |
+| The same, against a live instance, honouring app invariants | `replace --target api` | Runs in the instance's process: validation, mixins, field encryption, hooks, and live subscriptions re-read afterwards. |
+
+Two things `replace` will refuse, both before writing anything: a **partial bundle** (subset / tenant / table scope), because emptying would delete rows the bundle never carried; and a target where a table **outside** the bundle holds rows referencing one inside it, because those rows cannot be put back. Both refusals name what to do instead.
+
+#### Recipe: replace a dev environment from your local database
+
+```sh
+# 1. Full-scope export of the source, locally.
+voltro data export ./dev-refresh
+
+# 2. Preview against the target first — every pre-flight runs, nothing is written.
+voltro data import ./dev-refresh --target api \
+  --api-url https://dev.example --token "$VOLTRO_DATA_TRANSFER_SECRET" \
+  --mode replace --dry-run
+
+# 3. Do it. A big bundle chunks itself; a failed run can be re-run and resumes.
+voltro data import ./dev-refresh --target api \
+  --api-url https://dev.example --token "$VOLTRO_DATA_TRANSFER_SECRET" \
+  --mode replace --atomic
+```
+
+If step 3 dies halfway — a dropped connection, a laptop closing — run **exactly the same command again**. The upload continues where it stopped, and the import is a single all-or-nothing step, so the target is either the old state or the new one.
 
 ### Importing into a LIVE instance
 
@@ -2740,10 +2822,10 @@ A plain import connects **straight to the database** (not through the running ap
 | Target | How | Guarantees | Use for |
 |---|---|---|---|
 | **direct** (default) | writes straight to the DB | none while live — **guarded**; pass `--allow-live` to override | a stopped target, a replica, a dev/staging DB not serving traffic |
-| **direct + `--atomic`** | wraps truncate+load in ONE transaction | MVCC readers see the import **all-or-nothing** (old until commit, new after) — the live-safe `replace` | replacing a live target's data with no partial-state window |
+| **direct + `--atomic`** (the default for `replace`) | wraps empty+load in ONE transaction | MVCC readers see the import **all-or-nothing** (old until commit, new after) — the live-safe `replace` | replacing a live target's data with no partial-state window |
 | **in-process (`--target api`)** | `voltro data import <dir> --target api --api-url <url> --token <secret>` **uploads** the packed bundle (or, with `--bundle-key`, has the instance **pull it from storage**) to the instance's secret-gated admin endpoint, which imports it **in its own process** through its store | full app pipeline — validation, mixins, **field encryption**, hooks — AND automatic reactivity (in-process writes emit change events, so subscriptions update; no separate resync) | a live merge (incl. PROD) that must honour app invariants |
 
-`--atomic` is the recommended live `replace`: one transaction, so live reads never see a half-loaded table. (It holds a write transaction for the load duration — writes to those tables block, readers don't. A shadow-table rename would shorten that lock window, but for a full replace concurrent writes are discarded on swap anyway, so it isn't the default.)
+`--atomic` is what `replace` does by default (see above): one transaction, so live reads never see a half-loaded table. (It holds a write transaction for the load duration — writes to those tables block, readers don't. A shadow-table rename would shorten that lock window, but for a full replace concurrent writes are discarded on swap anyway, so it isn't the default.)
 
 ### The `--target api` data-transfer endpoints (prod-safe)
 
@@ -2753,6 +2835,49 @@ A plain import connects **straight to the database** (not through the running ap
 - **Secret gate, constant-time.** Every request must present that secret as a **Bearer token** (`Authorization: Bearer <secret>`), compared in constant time over SHA-256 digests (neither length nor content leaks via timing). The gate is a framework-owned secret **independent of app RBAC** — enabling data transfer can never accidentally ride on a user role. The CLI sends it via `--token` / `VOLTRO_DATA_TRANSFER_SECRET` (it must equal the server's secret). Wrong/absent token → `401`.
 - **One secret, both directions.** The same secret gates export (read) and import (write). If you need to grant export without import (e.g. a backup job that must never overwrite), split it into a per-operation credential deliberately — the default is one credential for the whole surface.
 
+#### A big bundle goes up in chunks, and resumes (`--chunk-size`)
+
+A bundle bigger than one chunk is uploaded as a **series of short requests** instead of one long one, and the switch is automatic: the packer's stream is buffered one chunk ahead, so a bundle that fits inside that buffer is sent exactly as before — one request, no protocol — and a bigger one chunks itself. **You never have to know in advance which table is the big one.**
+
+Each chunk is its own request, so a proxy body cap or an ingress read timeout has nothing large to choke on. The **import still runs once**, at the end, over the whole bundle — same modes, same deferred-FK repair, same all-or-nothing emptying. Only the transport changes.
+
+**Resume is real.** The upload id is derived from the bundle itself, so re-running the same command after a failure asks the instance how far it got and continues from there:
+
+```
+api import: resuming a chunked upload the instance already holds { bytes: 50331648 }
+api import: uploaded in chunks { chunks: 7, bytes: 62914560, resumedFrom: 50331648 }
+```
+
+That is safe because `packBundle` over a bundle directory is byte-identical across runs, and because each chunk carries the bundle's **key** (the hash of its manifest). Uploading a *different* bundle under the same id is refused rather than spliced into the partial one, and a chunk that does not start exactly where the instance left off is refused with the offset it does expect.
+
+`--chunk-size <mb>` overrides the default of 16 MiB. Unfinished uploads are discarded by the instance after 24 hours.
+
+##### The chunk protocol, for when you are reading proxy logs
+
+Worth knowing if an ingress sits in the way, because these requests are what it will show you. All of them are `POST` to the same `/_voltro/admin/import` path, gated by the same Bearer secret:
+
+| Request | Headers | Answer |
+|---|---|---|
+| probe | `x-import-upload-id`, `x-import-probe: 1`, empty body | `200 {uploadId, bytes}` — how much the instance already holds |
+| chunk | `x-import-upload-id`, `x-import-upload-key`, `x-import-chunk-offset` | `202 {uploadId, bytes}` — accepted, nothing imported yet |
+| final chunk | the same plus `x-import-chunk-final: 1` | `200` with the import's own result — this is the long one |
+
+A `409` means the instance refused the chunk and says which of three things happened: `offset-mismatch` (with the `expectedOffset` to continue from), `key-mismatch` (a different bundle under this upload id — use a new id), or `bad-id`. None of them is retryable by simply repeating the request, which is why each one names the fix.
+
+Only the FINAL request runs the import, so only that one is long. If it is the request your proxy times out on, that is the one to raise `proxy_read_timeout` for — or use `--bundle-key` and have the instance pull the archive from object storage instead of receiving it.
+
+#### How long an `--target api` call may take (`--timeout`)
+
+Both api-target calls **wait as long as the instance needs**. There is no default deadline, and that is deliberate: the response arrives only when the *import* (or export) has finished, so any fixed bound is really a bound on the size of your database. A full bundle of a grown database routinely takes longer than five minutes to apply.
+
+Pass `--timeout <seconds>` when you want one. If it is hit, the message says what it means — the upload finished long ago and **the instance is very probably still importing**:
+
+```
+voltro data import ./out --target api --api-url https://api.example --token $SECRET --timeout 900
+```
+
+Note the asymmetry when a deadline *is* hit: re-running an `upsert` after the first run has finished is safe (it is idempotent); re-running a **`replace`** while the first is still mid-flight would empty the target under it. Check the instance's log before deciding — the message says so too.
+
 **Import** (`POST /_voltro/admin/import`) applies a bundle **in the instance's own process** through its store — full app pipeline (validation, mixins, **field encryption**, hooks) AND automatic reactivity. Two transports, neither needs a server-readable path:
   - **upload** (default) — the CLI **packs the bundle and uploads the bytes**; the server unpacks to its own temp dir, imports in-process, cleans up. Buffered → small/moderate bundles.
   - **storage-pull** (`--bundle-key <key>`) — the CLI sends only `{ "bundleKey": "<key>" }`; the instance **streams that archive from its configured object storage** (S3 / Azure / MinIO / filesystem, resolved from the storage env — `STORAGE_PROVIDER`, `S3_*`, `AZURE_*`, …), no body buffering → arbitrarily large bundles.
@@ -2817,6 +2942,17 @@ Net: interrupt an export or import at any point — network drop, `Ctrl-C`, OOM-
 
 The `--target api` path is unaffected: the instance unpacks each upload into a fresh temp directory, so it never carries a ledger between runs.
 
+### What the summary line counts
+
+`import complete … rows: N` counts the rows **this run wrote**, not the rows the bundle carries. The two differ more often than you would think, and the case where they differ most used to read as a success:
+
+```
+import complete — 0 rows written, every table was already applied by an earlier run
+of this bundle directory { rows: 0, carried: 242950, skippedTables: 114, skippedRows: 242950 }
+```
+
+The resume ledger lives **inside the bundle directory**, so copying a bundle copies its ledger, and the copy then imports nothing — correctly, and with a warning that says so and names the file to delete. But the warning is not the last line, and an operator piping the output through `tail -1` sees only the last line. So the last line now tells the truth on its own: `rows` is what was written, `carried` is what the bundle holds, and `skippedRows` is what an earlier run had already applied.
+
 ### 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:
@@ -3128,6 +3264,10 @@ flag is the one-off override.
 | GDPR / per-tenant takeout | `voltro data export --tenant <id> --assets` |
 | A small self-consistent slice of the data | `voltro data export --profile <env>` with a `subset` |
 | Move Postgres → MySQL | `voltro data export` then `import` (cross-dialect lint applies) |
+| Replace a dev/staging environment with your local state | `voltro data import <dir> --target api --mode replace --atomic` |
+| Seed a fresh cluster through the running app (invariants + encryption) | `voltro data import <dir> --target api` (default `upsert`) |
+| Move a bundle too big for one request | nothing extra — the upload chunks itself; `--chunk-size` only if you need a different size |
+| Resume an upload that died | re-run the identical command |
 
 
 

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

@@ -1004,6 +1004,18 @@ The usual cause on MariaDB is a **UNIQUE constraint on an unbounded text column*
 
 The reader finds such tables when CDC starts, reports each once, and **excludes** it — so there is no reconnect loop. Cross-instance change events for that table are lost; own-node reactivity is unaffected, because writes still emit inline.
 
+**How long that verdict lasts.** It is a reading of the schema at the moment the reader attached, and applying the remedy does not lift it by itself. `voltro dev` builds its store before it migrates — kv, cross-replica broadcast and the analytics mirror all need one — so on a boot whose own migration bounds the column, the finding is a second older than the fix. That boot therefore **re-checks the exclusion set once all its schema work is done and re-admits the table in the same run**:
+
+```
+cdc: table 'sessions' looks undecodable … Not a verdict yet; the definitive line follows.
+auto-migrate: applied 74 op(s) in 1157ms
+cdc: table 'sessions' re-admitted to binlog capture — the hidden-column condition is gone.
+```
+
+The re-check runs in both directions: schema work that *creates* an unbounded unique on a captured table excludes it there and then, rather than after the reader has failed on three writes.
+
+`voltro serve` has no equivalent step and needs none — it builds its store *after* every schema step and never applies DDL itself, so its reading at attach is already the final one. Everywhere else the exclusion holds until the process restarts.
+
 **The remedy is to bound the column:**
 
 ```ts

package/templates/agent-docs/plugins/versioning.md

@@ -134,6 +134,8 @@ Version numbers are 1-based in **both** timings, so switching `timing` does not
 
 **The price is not optional.** That guarantee is only obtainable by being willing to REFUSE. When the history insert fails — disk, lock timeout, constraint, dropped connection — a transaction offers exactly two outcomes: the mutation fails with it, or the error is swallowed and the change commits without its entry, which is post-commit's hole with the cost already paid. There is no third option, so a rare, explained rejection is the shape of the guarantee rather than a defect.
 
+**The refusal takes the row with it.** When the trail's insert fails, the write it covers is rolled back — including a write made OUTSIDE any transaction of your own. That has not always been true: the row's statement committed on its own and the trail ran as a second statement afterwards, so a failing trail left a committed row behind a write that reported failure. Anything that retried that write then met its own row and reported a duplicate key for a row nobody wrote twice. A table with recorders is written inside a transaction now, on every SQL dialect, so "the mutation fails with it" means what it says.
+
 **Why the default is still `'post-commit'`.** In-transaction makes `_voltro_row_history` a hard dependency of every write path it covers: its availability becomes your write path's availability, and every covered write holds its locks longer. Post-commit loses at worst *one entry*; in-transaction can, at worst, stop writes to the covered tables entirely. For a compliance trail the second trade is the right one — for the undo / time-travel use this plugin also serves, it is not.
 
 ### Under CDC, and inside a transaction

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

@@ -1,4 +1,4 @@
-# What's new in 0.43.1
+# What's new in 0.44.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
@@ -7,67 +7,32 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
-### Fixed
-
-- **@voltro/database** — A write recorder that fails inside someone's transaction now says which recorder, on which write, and what the database actually said.
-
-  `@effect/sql` renders every driver failure as `SqlError: Failed to execute statement` — one sentence that fits a missing column, a dangling foreign key, an over-long value and a duplicate key equally. The driver's own words hang off a SYMBOL on a `FiberFailure`, so a caller who reaches for `.cause` gets `undefined` and concludes there is nothing there.
-
-  That is expensive precisely where recorders run: the caller's write was ordinary, and what failed was framework machinery one table over. The message now reads
-
-  ```
-  write recorder '_voltro_row_history' failed while recording an update on 'users':
-  Duplicate entry 'rowver_…' for key 'PRIMARY' [code=ER_DUP_ENTRY errno=1062 …]
-  ```
-
-  and the original error is kept as `cause` for anyone who does walk the chain. The failure still takes the transaction down — that is the guarantee and it is unchanged.
-
-  `describeDriverError` (`@voltro/database`) is the shared summariser, built on the existing cause extractor rather than a second walker. It returns nothing when the chain carries nothing driver-shaped, so an ordinary programming error from a recorder arrives as itself instead of wrapped in prose about a database.
-- **@voltro/database** — On MariaDB, a `varchar` column could introspect as `json` because a DIFFERENT table had a json column with the same column name.
+### ⚠ BREAKING
 
-  MariaDB names a column-level CHECK after the COLUMN, and those names are unique per table, not per schema. `information_schema.check_constraints` on MySQL has no `TABLE_NAME`, so the introspector recovered it by joining `table_constraints` on `(schema, constraint_name)` — which on MariaDB cross-products every same-named check across every table. Measured on 11.8:
+- **@voltro/data-transfer, @voltro/cli** — `runImport` returns an `ImportOutcome` instead of the bundle's `Manifest`, and `--mode replace` runs as ONE transaction by default.
 
-  ```
-  a.payload  LONGTEXT      CHECK (json_valid(`payload`))
-  b.payload  VARCHAR(255)  CHECK (`payload` in ('x','y'))
-  
-  join result:  a → json_valid, a → in(…), b → json_valid, b → in(…)
-  ```
+  **Why the return type changed.** The summary line counted the rows the BUNDLE carries, not the rows the run wrote. Those differ most exactly where it matters: a bundle directory carries its own resume ledger, so a copied directory imports nothing — correctly, with a warning naming the file to delete — and the run then printed `import complete … rows: 242950` over a target it had not touched. The warning was one line above, which is one line too far for anyone piping the output through `tail -1`. The outcome carries `rowsWritten`, `rowsSkipped` and `fullyResumed`, the CLI reports written-vs-carried, and a fully-skipped run says so on its LAST line.
 
-  So `b.payload` reads as `json`, and `a.payload` picks up an enum it does not have. Downstream that is not a cosmetic label: the planner emits a blocked `alter-column-type` with `from: 'json'` that no `.narrowedFrom()` can honestly acknowledge, because the premise is false — and since the data-transfer manifest records introspected types, the same misreading travels into the bundle and reappears as schema drift on import.
+  Migration: `runImport(...)` now resolves to `{ manifest, tablesWritten, rowsWritten, tablesSkipped, rowsSkipped, fullyResumed }`. Read `.manifest` where you read the manifest before.
 
-  MariaDB's own `check_constraints` HAS `TABLE_NAME`. The introspector asks for it directly now and keeps the join as the MySQL path, where check-constraint names are schema-unique and the join is sound. That asymmetry is why a single-engine test could not see this: the wrong query passes on MySQL.
-- **@voltro/database** — `voltro db apply` could not drop a CHECK constraint on the mysql family at all, and each of the three reasons hid the next.
+  **Why replace is atomic now.** The all-or-nothing guarantee was written for the emptying step, and read — reasonably — as covering the run. A replace that died partway through the LOAD left the target emptied of its old rows and holding part of the new ones, measured on a live instance over sixteen minutes. There is no useful state for a replace to stop in, so it is a default rather than a flag you have to know about. It also closes the window that produced that failure: with the tables emptied and the load uncommitted, a concurrent writer in the application waits instead of inserting a row the bundle is about to insert too.
 
-  **1. `DROP CHECK` is MySQL-8 syntax.** MariaDB has never had it — measured on 11.8, `ALTER TABLE t DROP CHECK c` is `ERROR 1064`, while `DROP CONSTRAINT c` works on both engines. A plan containing a `drop-check` therefore died on the first one, on a family whose migrations are NOT atomic: the run stopped with the earlier statements committed and no rollback.
+  `--no-atomic` (CLI) / `atomic: false` (API) opts out. The trade is stated where it bites: every write to those tables waits for the load, and on postgres the bulk `COPY` loader cannot join a transaction it does not own — an atomic run now says that once rather than being quietly slower.
 
-  **2. The name was assumed, not read.** The applier dropped `<table>_<column>_check` — which is only what its own `add-check` would have named it. A CHECK created at table bring-up is INLINE and UNNAMED, so the server names it (`CONSTRAINT_1` / `<table>_chk_1` / the column name). Dropping a name that does not exist reports "does not exist", which is indistinguishable from the "already gone" a resume legitimately produces — so the statement succeeded, the constraint stayed, and the plan re-proposed the identical `drop-check` forever. The name comes from the catalog now.
+  Two smaller things from the same report: `--mode replace` against a running instance warns about the empty-target window when it is NOT atomic, and the `--target api` upload reports progress per chunk plus a line explaining that the final request stays open for the whole import — sixteen minutes of silence is indistinguishable from a hang, and one operator killed a run that had finished.
 
-  **3. A column-level CHECK cannot be dropped by name on MariaDB at all.** Measured: the catalog lists it under the column's name, `DROP CONSTRAINT` on that name answers 1091, and only redefining the column removes it. The applier now drops by catalog name, ASKS whether the constraint survived, and redefines the column when it did — so a rebuild happens only in the case that needs one.
+  **`voltro update` carries you across this** — codemod `0.44.0/01_import-outcome`.
 
-  **And the same investigation closed the MySQL `.oneOf()` round-trip gap.** `parseEnumCheck` was documented as handling MySQL's rendering and did not: MySQL backslash-escapes the string DELIMITERS (`_utf8mb4\'draft\'`), and the parser rewrote those to the SQL doubling `''` — which is how a quote INSIDE a value is written. Every delimiter became escaped content, every value came back empty, and the filter dropped them. `.oneOf()` now round-trips on MySQL, and the suite that asserted the gap as a known one asserts the round-trip instead.
-
-  Plus, on a failed apply: the error now states how many operations were already applied and whether this dialect rolls back. The ledger held that number; it never reached the operator, who had to re-plan and diff the counts to learn how far the run got.
-- **@voltro/plugin-versioning** — `versioningPlugin({ timing: 'in-transaction' })` built its history row's primary key from `(rowId, version)` while the version counter three lines above was scoped to `(tableName, rowId)`. Two versioned tables carrying the same row id therefore collided — permanently.
-
-  The shape is not exotic: `actors.id === users.id` is what the framework's own audit trail asks for, an `actors` row whose id is the user's so an audited write satisfies `createdBy → actors`. In an app that follows it, every user row has a twin.
-
-  The collision does not heal, and that is what turns a duplicate into an outage. The second table's insert fails, so its history row is never written, so `maxOf` for that table stays `null`, so the next attempt computes the same version and the same id. Every write to that row is dead from then on — surfacing as `ER_DUP_ENTRY` on an ordinary `store.update`, naming a row id in a table the caller never wrote to.
-
-  The key is `(table, rowId, version)` now — the same shape the post-commit path always built. It stays deterministic (no clock, no process-local counter), which is what lets it survive a replica restart; it just carries every part of the key it claims to be unique over.
-
-  **No cleanup is needed for rows already written.** They keep their old ids and belong to whichever table wrote them; the new keys cannot collide with them, and `byRow` is not unique. An app blocked by this is unblocked by the upgrade alone.
-
-  Covered twice: the recorder against a port that refuses duplicates (the mechanism, including that a repeat does not settle), and two versioned tables sharing an id against live postgres (the real primary key, inside the caller's transaction). The suite that existed exercised ONE table, which cannot produce a collision at all — and read exactly like a suite that covered this.
+### Fixed
 
-### Internal (no consumer-facing effect)
+- **@voltro/sql-mysql, @voltro/sql-postgres, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/data-transfer** — A write and its write-recorders now succeed or fail together on every SQL dialect, and the data importer's retry is idempotent.
 
-- **@voltro/sql-mysql** — Two test-only defects in `sql-mysql`, both found by a release gate, both of the same family: a check that could not fail, and a failure reported in the wrong place. No product code changed.
+  A recorder (a versioning trail, an audit log) runs on the caller's connection and is ALLOWED to fail — a recorder that throws must take the write down with it, that is its contract. Outside a caller transaction the two were not one unit: the row's statement committed on its own, and the recorder's INSERT ran afterwards as a second autocommit statement. So a recorder that threw left a COMMITTED row behind a write that reported failure. Measured directly: `insert` throws, the row is in the table, and a second attempt at the same row is `ER_DUP_ENTRY` on PRIMARY.
 
-  **An assertion that could not fail.** `dropCheckSyntax.integration.test.ts` fell back to a HAND-BUILT plan when the planner produced no operations — and the fabricated operation was a `drop-check`, which is exactly what the next line asserts the plan contains. So an engine whose planner stopped emitting it would have been handed one and reported green. The fallback is deleted; both engines produce the operation now, which is what this release fixed, and the assertion is load-bearing again (4/4 on mysql AND mariadb without it).
+  Anything that retries a failed write then meets its own row. The data importer retries by design — it holds a row whose write failed and tries again once the remaining tables have streamed — so a `--mode replace` that had just emptied a table failed on a duplicate key IN that table. From outside, that is the impossible-looking thing: an import that emptied a table and then failed because something was already in it. Reproduced verbatim, including the table name and `[ER_DUP_ENTRY/1062]`, by putting the old retry back.
 
-  It surfaced as a TYPE error rather than a false pass, because the fallback's object widened `plan` into a union `applyPlan` does not accept. Worth noting which check caught it: `vitest` transpiles without type-checking, so the suite was green and only `tsc` objected — the gate's `typecheck` and `lint` steps are what went red.
+  Both ends are closed, and they are independent on purpose:
 
-  **A wait that gave up in silence.** `waitFor` in both binlog CDC suites looped to a deadline and then RETURNED, so a "prove the reader is live" wait that expired let the test carry on, kill the binlog dump thread, and fail twenty lines later on `expect(ids).toContain('todo_wd_before')` — an assertion about a different claim, in a different place. It throws now, naming the wait and the window, and all twelve call sites carry a label.
+  - **The cause.** A table that HAS recorders writes inside a transaction now, so the row and the trail commit together or not at all — on mysql, mariadb, postgres, sqlite and mssql, verified by one suite that asks all five the same question. A table with no recorders — the default — takes the direct path unchanged; `recordsTable` is a Map-size check first, so it costs one comparison. - **The defence.** The importer's retry upserts instead of inserting in `replace` mode. That covers every OTHER way a write can land while reporting failure: a driver timeout on a write the server applied, a connection lost after the commit, a concurrent writer inserting the same key. It is sound precisely because the table was emptied by this same run — there is nothing in it that is not ours.
 
-  The window is named too: `FIRST_ATTACH_MS = 30_000`, up from 12 s. The reasoning is the 40 s window already in the same file, whose comment says a re-attach plus binlog catch-up takes longer under a loaded full-suite run — a FIRST attach does both and only skips the backoff, so 12 s beside 40 s was an asymmetry the file's own reasoning did not support. That is an argument from the neighbouring comment, not a measurement; if it expires again, `waitFor` now says which wait and for how long, and that number is the one to argue with rather than raising this one twice.
+  The test that pinned the divergence went red when the fix landed, exactly as its own note said it would, and is inverted with that note kept.

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.43.1",
-    "@voltro/cli": "0.43.1",
-    "@voltro/database": "0.43.1",
-    "@voltro/env": "0.43.1",
-    "@voltro/protocol": "0.43.1",
-    "@voltro/runtime": "0.43.1",
+    "@voltro/ai": "0.44.0",
+    "@voltro/cli": "0.44.0",
+    "@voltro/database": "0.44.0",
+    "@voltro/env": "0.44.0",
+    "@voltro/protocol": "0.44.0",
+    "@voltro/runtime": "0.44.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.1",
+    "@voltro/testing": "0.44.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.43.1",
-    "@voltro/database": "0.43.1",
-    "@voltro/env": "0.43.1",
-    "@voltro/plugin-auth": "0.43.1",
-    "@voltro/protocol": "0.43.1",
-    "@voltro/runtime": "0.43.1",
-    "@voltro/sql-postgres": "0.43.1",
+    "@voltro/cli": "0.44.0",
+    "@voltro/database": "0.44.0",
+    "@voltro/env": "0.44.0",
+    "@voltro/plugin-auth": "0.44.0",
+    "@voltro/protocol": "0.44.0",
+    "@voltro/runtime": "0.44.0",
+    "@voltro/sql-postgres": "0.44.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.1",
+    "@voltro/testing": "0.44.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.43.1",
-    "@voltro/database": "0.43.1",
-    "@voltro/env": "0.43.1",
-    "@voltro/plugin-multitenancy": "0.43.1",
-    "@voltro/protocol": "0.43.1",
-    "@voltro/runtime": "0.43.1",
+    "@voltro/cli": "0.44.0",
+    "@voltro/database": "0.44.0",
+    "@voltro/env": "0.44.0",
+    "@voltro/plugin-multitenancy": "0.44.0",
+    "@voltro/protocol": "0.44.0",
+    "@voltro/runtime": "0.44.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.1",
+    "@voltro/testing": "0.44.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.43.1",
-    "@voltro/database": "0.43.1",
-    "@voltro/env": "0.43.1",
-    "@voltro/plugin-deactivation": "0.43.1",
-    "@voltro/protocol": "0.43.1",
-    "@voltro/runtime": "0.43.1",
+    "@voltro/cli": "0.44.0",
+    "@voltro/database": "0.44.0",
+    "@voltro/env": "0.44.0",
+    "@voltro/plugin-deactivation": "0.44.0",
+    "@voltro/protocol": "0.44.0",
+    "@voltro/runtime": "0.44.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.1",
+    "@voltro/testing": "0.44.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

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

@@ -13,18 +13,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.43.1",
-    "@voltro/database": "0.43.1",
-    "@voltro/env": "0.43.1",
-    "@voltro/plugin-mail": "0.43.1",
-    "@voltro/plugin-multitenancy": "0.43.1",
-    "@voltro/protocol": "0.43.1",
-    "@voltro/runtime": "0.43.1",
+    "@voltro/cli": "0.44.0",
+    "@voltro/database": "0.44.0",
+    "@voltro/env": "0.44.0",
+    "@voltro/plugin-mail": "0.44.0",
+    "@voltro/plugin-multitenancy": "0.44.0",
+    "@voltro/protocol": "0.44.0",
+    "@voltro/runtime": "0.44.0",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.1",
+    "@voltro/testing": "0.44.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"