@voltro/cli 0.48.0 → 0.50.0

package/dist/serveCommand-C_WI4TTG.js

@@ -0,0 +1,2 @@
+import { n as e } from "./serveCommand-8CTzQCY0.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-CV3YO9L3.js";
-export { e as loadDotEnv, t as registerAppModules, n as registerDriver, r as runServe };
+import { t as e } from "./serveCommand-8CTzQCY0.js";
+import { t } from "./loadEnv-D9nEOClM.js";
+import { r as n } from "./appModuleLoader-C9r9mxZt.js";
+import { i as r } from "./dialectDriver-czCHYpeH.js";
+export { t as loadDotEnv, n as registerAppModules, r as registerDriver, e as runServe };

package/dist/{subcommandNames-CKG5Dz3a.js → subcommandNames-DpYs3DXr.js}

@@ -19,9 +19,19 @@ var e = [
 	"scan-credentials",
 	"encrypt-column"
 ], t = [
+	"export",
+	"import",
+	"transfers",
+	"inspect",
+	"unpack",
+	"backup",
+	"restore",
+	"clear-replace-marker",
+	"clear-staging"
+], n = [
 	"scope",
 	"export",
 	"erase"
-], n = (e) => `<${e.join("|")}>`;
+], r = (e) => `<${e.join("|")}>`;
 //#endregion
-export { t as n, n as r, e as t };
+export { r as i, e as n, n as r, t };

package/dist/updateCommand-D91-TZ7E.js

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

package/dist/{updateCommand-BlyXavoG.js → updateCommand-i8JbrLAA.js}

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-DSZjgyCL.js";
+import { n as e, r as t, t as n } from "./codemodRunner-De3k0pRd.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";
@@ -579,6 +579,7 @@ with \`--only\` / \`--root\`.`;
 		for (let e of r.manual) {
 			console.log(`\n▸ ${e.id} — ${e.title}`);
 			for (let t of e.note.split("\n")) console.log(`  ${t}`);
+			e.certain || (console.log(""), console.log("  ── nothing in this repository matched. That is NOT a clean bill of health:"), console.log("     `voltro update` reads the files git tracks here, and a CLI call also lives"), console.log("     in places it cannot reach — an inline script in a CI runner, a CronJob"), console.log("     spec in another repo, a runbook, a deploy job. Search those by hand."));
 		}
 	}
 	return n.dryRun && console.log("\n(dry-run — no files written)"), 0;

package/dist/{webhooksCommand-QlAk_tED.js → webhooksCommand-B0bdyuQ4.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-cGGsLNn6.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-BWwE0QjK.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.48.0",
+  "version": "0.50.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -652,6 +652,18 @@
         "title": "an aggregate’s `incremental.source` is typechecked against the app’s tables",
         "kind": "manual"
       },
+      {
+        "version": "0.49.0",
+        "id": "0.49.0/01_data-imports-to-transfers",
+        "title": "`voltro data imports` → `voltro data transfers`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.49.0",
+        "id": "0.49.0/02_import-run-symbols",
+        "title": "`ImportRun` / `describeImportRun` / `IMPORT_RUNS_TABLE` → their `…TransferRun` names",
+        "kind": "transform"
+      },
       {
         "version": "0.5.0",
         "id": "0.5.0/01_one-terminal-exactly-one",
@@ -664,6 +676,24 @@
         "title": "store.query() now returns the row type — casts on row fields may stop compiling",
         "kind": "manual"
       },
+      {
+        "version": "0.50.0",
+        "id": "0.50.0/01_transfer-runs-endpoint",
+        "title": "`GET /_voltro/admin/imports` → `GET /_voltro/admin/transfers`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.50.0",
+        "id": "0.50.0/02_reissue-data-imports-rename",
+        "title": "RE-CHECK: `voltro data imports` → `voltro data transfers` (0.49.0's note could not see your scripts)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.50.0",
+        "id": "0.50.0/03_interrupted-replace-tables-nullable",
+        "title": "`InterruptedReplace.tables` is `number | null`",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -739,22 +769,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.48.0",
-    "@voltro/cache": "0.48.0",
-    "@voltro/data-transfer": "0.48.0",
-    "@voltro/database": "0.48.0",
-    "@voltro/env": "0.48.0",
-    "@voltro/kv": "0.48.0",
-    "@voltro/logger": "0.48.0",
-    "@voltro/plugin-auth": "0.48.0",
-    "@voltro/plugin-broadcast": "0.48.0",
-    "@voltro/plugin-mail": "0.48.0",
-    "@voltro/plugin-storage": "0.48.0",
-    "@voltro/plugin-webhooks": "0.48.0",
-    "@voltro/protocol": "0.48.0",
-    "@voltro/runtime": "0.48.0",
-    "@voltro/serverless": "0.48.0",
-    "@voltro/workflow": "0.48.0",
+    "@voltro/ai": "0.50.0",
+    "@voltro/cache": "0.50.0",
+    "@voltro/data-transfer": "0.50.0",
+    "@voltro/database": "0.50.0",
+    "@voltro/env": "0.50.0",
+    "@voltro/kv": "0.50.0",
+    "@voltro/logger": "0.50.0",
+    "@voltro/plugin-auth": "0.50.0",
+    "@voltro/plugin-broadcast": "0.50.0",
+    "@voltro/plugin-mail": "0.50.0",
+    "@voltro/plugin-storage": "0.50.0",
+    "@voltro/plugin-webhooks": "0.50.0",
+    "@voltro/protocol": "0.50.0",
+    "@voltro/runtime": "0.50.0",
+    "@voltro/serverless": "0.50.0",
+    "@voltro/workflow": "0.50.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.48.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.50.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.48.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.50.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

@@ -2885,7 +2885,7 @@ recorder is for. Every suspended run says so, and the suspension is scoped to th
 run rather than the process, so requests served alongside it keep recording.
 
 Instead of per-row history, the operation records **itself**. One row in
-`_voltro_data_imports` per run: the mode, the transport, the bundle, the source
+`_voltro_data_transfers` per run — in either direction: the mode, the transport, the bundle, the source
 deployment's schema fingerprint, the counts — and the failure, for the run you
 are usually looking for. A trail that only records successes goes quiet exactly
 when it is needed.
@@ -2895,9 +2895,57 @@ interlock and a run which cannot write it must not proceed, while this is
 history. A target whose schema is not migrated yet still imports, and says the
 trace could not be written.
 
-### Watching an import you cannot see
+### Every request fits a budget
 
-Over `--target api` the import runs INSIDE the instance. Everything it decides
+Some environments cap a single request: a job runner that kills a client after
+ten minutes, an ingress with a 30-second ceiling, a CI step with a deadline. A
+whole transfer may still take an hour — it just has to do so as a series of short
+requests, each individually abandonable and individually retryable.
+
+The rule the endpoints follow:
+
+> **A request that carries bytes never runs a transfer. A request that starts a
+> transfer never carries bytes.**
+
+```bash
+# Nothing here may take longer than 30 seconds per request.
+voltro data import ./bundle --target api --api-url https://app.example \
+  --mode replace --max-request-seconds 30
+
+# Or: start it and walk away. The outcome is NOT known when this returns.
+voltro data import ./bundle --target api --api-url https://app.example --detach
+```
+
+Both staging areas — the uploaded bundle on its way in, the produced one on its
+way out — sit in the system temp directory by default and move with
+`VOLTRO_IMPORT_UPLOAD_DIR` / `VOLTRO_EXPORT_ARTIFACT_DIR`. Worth setting on a
+container: a bundle is the size your database is, and a default `/tmp` is
+frequently a small tmpfs.
+
+`--max-request-seconds` is DECLARED rather than probed. The thing that kills a
+request is a policy on your side, and only you know it — in the one environment
+this was measured against, the ingress would happily hold a connection for an
+hour and the caller's own toolchain killed the client at ten minutes.
+
+**An import is three steps.** The bundle goes up (in 16 MiB chunks when it is
+big, resumable, one plain request when it is small); `import/start` begins the
+run and answers as soon as the run is recorded; then the client watches the
+record. `start` is idempotent — retrying it under a budget returns the run that
+is already going rather than beginning a second destructive one.
+
+**An export is three steps too.** Ask, wait for the record, then fetch the bytes
+in ranges from `GET /_voltro/admin/export/download`. The archive used to arrive
+in the response body, which made the request last as long as reading your whole
+database.
+
+**`--detach` returns once the run has started** and says so plainly: exit `0`
+there means "it started", not "it worked". Attached, the exit code comes from the
+run's record — `0` finished, `1` failed, `2` still going when you stopped
+watching. Ctrl-C loses the watching and never the run.
+
+### Watching a transfer you cannot see
+
+Over `--target api` the run happens INSIDE the instance. Everything it decides
 — whether it stages, whether recorders are suspended, how far it has got — is
 printed in the pod's log, and someone reaching for `--target api` is by
 construction someone who cannot reach the database directly and usually cannot
@@ -2906,9 +2954,12 @@ killing the client does not stop it, which is what keeps a dead client from
 leaving a half-emptied target. Both properties are right, and together they used
 to mean an operator could neither see the run nor learn how it ended.
 
-Two things close that, and neither is a streamed response — a chunked body has
-to survive every proxy in between, and a buffering reverse proxy turns a
-progress feed into exactly the silence it was meant to replace.
+Two things close that, and neither is a streamed response on the upload
+connection. That connection is the thing an operator is most likely to lose: a
+client killed by a job timeout while the import runs on inside the instance is
+the ordinary case, and a stream would go quiet at exactly the moment somebody
+needs to know what happened. A poll can be run from a different machine than
+the one that started the import.
 
 **Ask before you upload.** A `replace` over the api asks the instance what it is
 going to do, before a byte of the bundle goes up. The instance answers from the
@@ -2918,7 +2969,8 @@ same function the run itself calls, so the answer cannot drift from the run:
 $ voltro data import ./bundle --target api --api-url https://app.example --mode replace
 api replace: the instance WILL stage — 104 table(s) load into copies and the
   target keeps its rows until one short swap at the end. Interrupting the load leaves the target intact.
-api import: uploading the bundle — this request stays open until the instance has imported it
+  importing — 41200 row(s) across 18 table(s) (staged; the target still holds its own rows)
+  done — 228866 row(s) across 104 table(s)
 ```
 
 With `--bundle-key` the client never holds the bundle, so it sends the key and
@@ -2932,22 +2984,28 @@ That is the difference between "interrupting this is safe" and "interrupting
 this empties the target", which is exactly the decision an operator is making
 while they watch.
 
-**Read the run from anywhere.** `_voltro_data_imports` is opened before the
-first table, advanced every couple of seconds as tables land, and closed with the
-outcome — so polling it IS the progress feed:
+**Read the run from anywhere.** `_voltro_data_transfers` carries one row per run
+in EITHER direction: opened before the first table, advanced every couple of
+seconds as tables land, closed with the outcome — so polling it IS the progress
+feed:
 
 ```
-$ voltro data imports --target api --api-url https://app.example
+$ voltro data transfers --target api --api-url https://app.example
 1 import(s) IN FLIGHT — re-run this to watch the counters move
-  2026-08-22T09:04:01.000Z · replace — started and never reported finishing · via api · from /tmp/b
-  2026-08-20T10:00:00.000Z · replace — 228866 row(s) across 104 table(s) · via api · from /tmp/a
+  2026-08-23T09:04:01.000Z · replace — started and never reported finishing · via api · staged (target untouched until the swap) · from /tmp/b
+  2026-08-23T08:00:00.000Z · export all — 228866 row(s) across 104 table(s) · via api · from backups/nightly.vbundle
 ```
 
-Same data over `GET /_voltro/admin/imports?limit=20`, behind the same
+Same data over `GET /_voltro/admin/transfers?limit=20`, behind the same
 data-transfer secret (the row names bundles and schema fingerprints). It works
 from a different machine than the one that started the import, and through
 anything that forwards a GET.
 
+The `staged` part is a separate claim from the preflight's, and both are needed.
+The preflight says what the instance WILL do; this says what it did. Without it
+the two could only be closed by reading the pod's log, which is the one place a
+`--target api` caller cannot reach.
+
 ### An interrupted `replace` cannot be silent
 
 The capture only helps if somebody knows to reach for it. A half-replaced database is indistinguishable from an empty one **from the inside** — every table exists, every constraint holds, every query returns nothing without erroring — so a run that emptied a target and disappeared can be served over for hours before anyone asks the right question.
@@ -3272,12 +3330,62 @@ yield* runImport({ store: target, bundleDir: './backup', targetSnapshot }).pipe(
 ## Native backup / restore
 
 ```bash
-voltro data backup ./backups/2026-07-01     # pg_dump --format=custom / mysqldump --single-transaction / …
-voltro data restore ./backups/2026-07-01    # pg_restore / mysql / …
+voltro data backup ./backups/2026-07-01              # pg_dump --format=custom / mariadb-dump --single-transaction / …
+voltro data backup ./backups/2026-07-01 --assets     # rows AND the stored blobs
+voltro data restore ./backups/2026-07-01 --assets    # pg_restore / mariadb / … + the blobs
 ```
 
 These shell out to the vendor tools resolved from your `DB_DIALECT` + connection env. They produce a dialect-native artifact (`db.dump`, `db.sql`, `db.sqlite`, `db.bacpac`) that is lossless and point-in-time consistent for **same-dialect** restore — the right tool for disaster recovery. Secrets are passed via the tools' environment variables (`PGPASSWORD`, `MYSQL_PWD`), never on the command line, where the tool supports it. The named tool must be installed and on `PATH`.
 
+### `--assets` — the blobs are not in the dump
+
+A vendor dump contains rows. Your blobs are in object storage, and no `pg_dump` has ever seen them. So a rows-only backup restores a database whose rows reference objects that are not there — and the reference and the object are checked at different times, which is why that state is discovered by a user, months later, rather than by the restore.
+
+`--assets` captures them alongside the dump, through the same content-addressed pipeline `voltro data export --assets` uses: each blob is streamed (never buffered whole), stored under `assets/<sha256>` so identical content is stored once, and listed in `assets/index.ndjson`. `restore --assets` streams them back and **re-hashes on the way**, so a corrupted artifact can never silently overwrite good bytes.
+
+```
+backups/2026-07-01/
+├─ db.dump                       # the vendor artifact (rows)
+├─ voltro-backup-stamp.json      # provenance, incl. what --assets captured
+├─ assets/index.ndjson           # key → sha256 → size → contentType
+└─ assets/<sha256>               # the blob bodies, deduped by content
+```
+
+Three refusals, each for a belief that is otherwise acted on silently:
+
+- **`backup --assets` with no storage provider configured → refused.** There is nothing to capture, and a flag that is accepted and ignored lets you build a rollback story on an artifact that does not contain what you asked for.
+- **`restore --assets` on a rows-only backup → refused.** You believe the blobs are in there. Restoring the rows anyway produces exactly the dangling state this exists to prevent.
+- **restore *without* `--assets` on a backup that HAS them → warned, not refused.** Restoring rows without blobs is legitimate (a schema drill, a lower environment), and refusing it would push people at `--force`.
+
+Resume is per blob key, so re-running a `--assets` capture that was interrupted transfers only what is missing. The **dump itself has no resume** — a vendor artifact is one opaque file with no offset to restart from. If you need a resumable, chunkable, observable transfer, that is the logical path (`export` / `import`), and it is why the logical path exists.
+
+### A restore that is interrupted refuses the next boot
+
+`restore` writes one row into `_voltro_replace_in_progress` **before** the first destructive statement and removes it **after** the last write — the blobs included. Its presence at boot is a refusal naming the artifact that was going in.
+
+This is the counterpart to `--allow-live`, and it guards from the other side: `--allow-live` asks you not to restore over a running instance, and this says *this database is mid-restore, do not serve it*. A half-restored database looks exactly like a normal one from the inside — every query answers, nothing errors.
+
+Whether the marker survives the restore depends on the dialect's restore shape, and that is stated rather than implied:
+
+| dialect | shape | effect |
+|---|---|---|
+| postgres, mysql, mariadb | drops only the objects the dump names | the marker survives, so a killed restore is caught at the next boot |
+| sqlite, turso | whole-file replacement — made **atomic** (temp file + rename) | there is no half-restored state to catch; a killed restore leaves the live file untouched |
+| mssql | `sqlpackage /Action:Import` replaces the database | a *failed* import is the one case not covered here — verify with `--drill` |
+
+Clear a marker deliberately with `voltro data clear-replace-marker --yes` once you have decided the current state is correct.
+
+### Both directions are in the history
+
+`backup` and `restore` write a row to the same `_voltro_data_transfers` record `import` and `export` use, so `voltro data transfers` answers "did last night's backup finish" from the instance that ran it:
+
+```
+2026-08-23T02:00:00.000Z · backup native postgres + assets — finished (412 blob(s)) · via cli · from ./backups/2026-08-23/db.dump
+2026-08-22T09:14:02.000Z · FAILED restore native mariadb — mariadb-dump: exited with code 2 · via cli · from ./backups/2026-08-21/db.sql
+```
+
+A native run reports **blobs**, not rows: the vendor tool reports no row count we can trust, and printing `0 row(s)` over a `pg_dump` that worked would be a measurement, and a wrong one. A target with no `_voltro_data_transfers` table still gets its backup — the closing line says it was not recorded, rather than implying it was.
+
 ### The provenance stamp — a restore that refuses the wrong DB
 
 A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the live schema `fingerprint`, the `@voltro/cli` version, and the timestamp.

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

@@ -1,4 +1,4 @@
-# What's new in 0.48.0
+# What's new in 0.50.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,78 +7,56 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
-### Added
-
-- **@voltro/cli, @voltro/data-transfer** — An import over `--target api` can be asked what it will do, and watched while it does it.
-
-  The transport's two correct properties combined into one blind spot: the run happens INSIDE the instance, so every line it produces goes to a pod log; and it is deliberately decoupled from the caller, so killing the client does not stop it (which is what keeps a dead client from leaving a half-emptied target). Someone reaching for `--target api` cannot reach the database directly and usually cannot read that log either, so "watch for the staging line" was advice they could not follow.
-
-  **A preflight, before a byte is uploaded.** A `replace` over the api now asks the instance whether it will stage, and prints the answer — including the reason when it will not. It answers from `decideStaging`, the same function the run itself calls, so the two cannot drift; a second copy of that decision would answer confidently and diverge on the next change. With `--bundle-key`, where the client never holds the bundle, it sends the key and the instance reads the table list out of the archive's own manifest — the caller about to have an instance empty its own database is the last one who should be told to check a log they cannot read.
-
-  **`voltro data imports`** (and `GET /_voltro/admin/imports`, behind the same data-transfer secret) reads the history and the run in flight. `_voltro_data_imports` was write-only; it is now opened before the first table, **advanced every couple of seconds as tables land**, and closed with the outcome — so polling it is the progress feed. Not a streamed response on the upload connection: a chunked body has to survive every proxy in between, and a buffering reverse proxy turns a progress feed into exactly the silence it was meant to replace.
-
-  **And a `replace` that does not stage now says why.** The staging set was an early `return []` three conditions deep, and the empty array met a `length > 0` further down and read as "do not stage". A bundle table the target does not have — the ordinary case for a development source against a production target — turned the non-destructive path off in silence. Every reason routes through one message now; the cycle case additionally used to be gated on `atomic`, so the mode where an interrupted run leaves the worst outcome was also the one that said the least.
-
-### Changed
-
-- **@voltro/cli** — The declared framework schema no longer depends on `NODE_ENV`.
+### ⚠ BREAKING
 
-  `_voltro_traces` and `_voltro_undo_log` defaulted to on outside production. That was allowed with an explicit justification — one decider makes every command in a deployment agree — and the justification was about the schema FINGERPRINT, which only ever compares processes inside ONE deployment.
+- **@voltro/cli** — The read-only run-history endpoint moved:
 
-  The declared set has a second reader that spans two, and it was never considered: `voltro data`. A bundle exported from a development database carries the tables that database has, and a staged (non-destructive) `replace` needs every bundle table to exist in the target. So one source tree produced a bundle a production target could not stage, and the run fell back to truncating it — with nothing red anywhere, on the one path where that difference is the entire point.
+  GET /_voltro/admin/imports → GET /_voltro/admin/transfers
 
-  Both tables are declared in **every environment** now. The trade is the one `_voltro_cdc_offsets` already makes: an unused declared table costs one empty table and buys agreement. `VOLTRO_UNDO` / `VOLTRO_TRACING_PERSIST` still decide what a process WRITES; they never decided the schema and still do not. Set `schema: { traces: false, undo: false }` in `app.config.ts` to keep one out — in every environment, or the divergence is back by hand.
+  Same secret, same query parameters, same response shape. Only the path changed.
 
-  **Upgrade:** a production app that never declared them gains two empty tables. `voltro db apply` (or a `voltro dev` boot) plans and applies them like any other framework table, on every dialect. Run it before the pods roll, as with any schema change — a migrate job and a fleet that disagree is exactly what this removes.
+  It answers for four directions now — import, export, native backup, native restore — and it named one of them. The subcommand and the table were renamed for exactly that reason in 0.49.0 and this path was left behind, which is worse than renaming none of them: a reader who follows a rename tries the matching path, gets a 404, and concludes the instance is too old.
 
-  `voltro doctor` now prints the three decided tables and what decided each, on a HEALTHY run. That text existed and was reachable only from the `prod-mismatch` refusal — a message that appears exclusively after a fleet is down is an explanation, not a warning.
+  `voltro data transfers --target api` uses the new path for you. What needs a hand is anything calling it directly — a monitoring check, an uptime probe, a curl in a runbook, a dashboard datasource. The codemod is `manual` and declares `reach: 'beyond-source'`, so it prints whether or not the path is found in your repository.
+- **@voltro/database, @voltro/voltro** — `InterruptedReplace.tables` is `number | null`, and the interface gains `kind?: 'replace' | 'restore'`.
 
-### Fixed
-
-- **@voltro/cli, @voltro/data-transfer** — `voltro data export --exclude a,b` made the bundle BIGGER, and made it unusable for a `replace`.
-
-  It expanded into `{ kind: 'tables', tables: <everything else> }`, on the reasoning that a manifest should record what was exported rather than claim "everything". Right goal, wrong mechanism, and it cost two things at once. `all` is the only scope that filters out the tables which describe a deployment, so excluding two names silently added nine others back — the migration ledger among them, whose foreign row takes an environment down at the next boot. And `replace` refuses a named scope, so the honest way to leave a table out was also the way to make the bundle unusable for the mode it was being prepared for.
-
-  The exclusion is a FIELD of the `all` scope now: the filter still runs, the manifest still says "everything except these" (a different and truer claim than "these"), and `replace` accepts it while naming the tables it will therefore not touch. `--exclude` also works over `--target api` now — it no longer expands against a table list only the instance has, so the instance resolves it where that list already is.
+  `_voltro_replace_in_progress` records two destructive operations now — an import's `--mode replace` and a native `voltro data restore`. A restore replaces the whole database from an artefact, so "how many tables was this going to empty and refill" has no answer: not known up front, not meaningful after.
 
-  Every framework table is classified as portable or environment-local, with the reason, and a new one fails the build until somebody decides. That guard existed and did not help: it was satisfied by a second, hand-kept list inside its own test, and the two disagreed about `_voltro_traces` and `_voltro_undo_log` — nothing was unclassified, something was classified twice, once wrongly. There is one list now, read by both guards. Traces, undo, the outbox and its attempts, idempotency keys, storage grants, spend and usage accounting, delivery attempts and schedule-firing history joined the environment-local side: a row from elsewhere would make the target act, or claim history it did not live.
-- **@voltro/sql-turso** — Opening a second pooled turso connection could fail instantly with `database is locked` — from inside the constructor, before a single query ran.
+  Writing `0` would have preserved the type and been worse. That number is rendered into the boot refusal, which is read under pressure, and it would have said `began emptying 0 table(s)` — a measurement that was never taken. The framework's own text says "this database" instead; `Number(null)` is `0`, so coercing it reintroduces exactly the sentence being avoided.
 
-  `makeConnection` set its pragmas in the order `journal_mode` → `foreign_keys` → `busy_timeout`. The engine defaults `busy_timeout` to **0**, so a statement that meets a held lock fails on the spot instead of waiting — and `journal_mode= experimental_mvcc` needs the file exclusively. Since `makeConnection` runs once per POOLED connection (default 4), opening connection two while connection one held the file hit that exclusive pragma with no lock-wait configured yet:
+  `DataTransferRun.direction` also widens to name `'backup'` and `'restore'` explicitly. That one is documentary — the union already ended in `| string`, so no assignability changes.
 
-  SqlError: Failed to enable Turso MVCC (journal_mode=experimental_mvcc): database is locked
+  **`voltro update` carries you across this** — codemod `0.50.0/03_interrupted-replace-tables-nullable`.
 
-  `busy_timeout` is set FIRST now. Nothing else changed — same value, same pragmas, same connection.
-
-  **Why it hid for so long.** The file already carried a long, correct note about `busy_timeout` being mandatory with a pool, and a separate fix had closed the DDL half (`retryFilter` + bounded retries in `applySchema`). Both are about the same lock class, so the constructor read as covered — but a setting cannot protect the two pragmas that run before it.
-
-  It surfaces as an unrelated flaky test, because the failure lands wherever the second connection happens to be opened: a `CREATE TABLE` in one run, an MVCC pragma in the next. It cost three release gates — twice locally, once on a CI runner — and was twice diagnosed as machine contention and closed. It is contention-DEPENDENT, which is not the same as being the machine's fault.
+### Added
 
-  Verified: 8 serial runs and 6 concurrent suites at load 12 — 0 failures, 0 occurrences of the message. The failure was intermittent before, so this is evidence rather than proof; the mechanism, however, is not in doubt.
-- **@voltro/runtime, @voltro/data-transfer, @voltro/cli** — The `source:` recorder broke every WRITE on the in-memory store, and actions are recorded now.
+- **@voltro/cli, @voltro/data-transfer, @voltro/database** — `voltro data backup --assets` and `voltro data restore --assets` now move the stored blobs alongside the vendor dump, through the same content-addressed phase the logical `export` / `import` path uses — streamed, deduped by sha256, verified on the way back, resumable per key.
 
-  The recording wrapper is a `Proxy`, and it handed methods back unbound — so `this` was the PROXY, and a class with `#private` fields answers that with `TypeError: Receiver must be an instance of class InMemoryDataStore`. Under `voltro dev` on the memory store, where the recorder is installed by default, that is every write in the app.
+  `--assets` was accepted by `backup` and silently ignored, with the only signal a field in the closing JSON reading `NOT included`; `restore` did not accept it at all. A rows-only backup restores a database whose rows reference objects nothing puts back, and the reference and the object are checked at different times, so that state is discovered by a user rather than by the restore.
 
-  Every test passed throughout, and the reason is worth more than the fix: `query` is the one method the wrapper invokes with an explicit receiver, so everything that only READ through it worked. The wrapper's whole purpose is reading, so nothing in its own suite ever wrote. It was found by a test about something else entirely — asking what `crud.create` reads — which needed a write to answer.
+  Three refusals, each for a belief that is otherwise acted on silently: `backup --assets` with no storage provider is refused rather than swallowed; `restore --assets` on a rows-only artefact is refused; a restore WITHOUT `--assets` over an artefact that has them warns and proceeds, because restoring rows without blobs is legitimate and refusing it would push people at `--force`.
 
-  **Actions are recorded too now**, and an action's `source:` means something different from a query's. A query's is a reactive trigger set; an action's declares what it TOUCHES, and the field's own documentation records what an undeclared read costs: `voltro check` reported a table five action paths read and wrote as an orphan, and advised removing it. That is not a quiet subscription, it is advice to delete a live table.
+  The dump itself still has no resume — a vendor artefact is one opaque file with no offset to restart from, and the logical path is what exists for that.
+- **@voltro/cli, @voltro/database, @voltro/data-transfer** — A native `backup` / `restore` now writes to the same `_voltro_data_transfers` record `import` and `export` use, so `voltro data transfers` answers "did last night's backup finish" from the instance that ran it. A native run reports blobs rather than rows — a vendor tool reports no row count we can trust, and printing `0 row(s)` over a dump that worked would be a wrong measurement.
 
-  **Measured rather than reasoned about:** `crud.create`, `crud.update` and `crud.remove` issue NO read at all, so a read recorder has nothing to say about them — but `crud.getById` does read, and with `include:` it eager-loads, so it is covered like `crud.list`.
+  `restore` also writes the `_voltro_replace_in_progress` marker before its first destructive statement and clears it after the last write, blobs included, so a killed restore refuses the next boot instead of serving a half-loaded database. `--allow-live` guards from the wrong side — it asks you not to — and this guards from the right one. The marker carries a `kind` so the refusal can say something different for a `replace` (re-import the capture) and a `restore` (finish the restore), and `tables` is nullable because a native restore has no table count to claim.
 
-  **And a kill test for the one moment nobody had reproduced.** The existing test kills mid-LOAD, which staging turned into the harmless part; the destructive second went untested precisely because it became short. The new case kills as the swap begins and asserts the property rather than the race: the target is one state or the other, never a mix, and never empty. Two defects in the harness came out of writing it — a worker that died SILENTLY (its failure now goes into the marker the parent already reads, instead of looking like a slow start), and an `exit` listener attached only after the SIGKILL, which hung to the full timeout whenever the child finished first.
+  The sqlite / turso restore is atomic now (temp file + rename): its marker lives in the very file being replaced, so a plain in-place copy would leave a truncated database with nothing left to catch it.
 
-  **And the import trace was never written on the path most likely to be used.** A deployment ran a successful `voltro data import` against a database that HAD the table, and got no row and no message at all. The write was gated on this PROCESS's table registry, and `voltro data`'s own boot builds a store and introspects the live schema — it never registers the framework set, so the gate was `undefined` exactly there. The authority for "does the target have this table" is the target's SCHEMA, which that boot already introspects; the table is also registered before the write, because a CLI run has not done it and the write needs the column metadata.
+  A target with no `_voltro_data_transfers` table still gets its backup; the closing line says it was not recorded rather than implying it was.
+- **@voltro/cli** — A re-issued migration note for the `voltro data imports` → `voltro data transfers` rename that shipped in 0.49.0.
 
-  The sharper half is the silence, and it was self-inflicted: the skip was written three lines under a comment about how an absent table cannot be detected by the write failing. The message now lives in `voltro data import`, which is the layer that INTROSPECTED — a first attempt put it in the importer, where a `targetSnapshot` may legitimately be narrow rather than complete, so it fired at callers whose snapshot simply did not mention a framework table.
+  Codemods are selected by `from < version <= to`, so the 0.49.0 note fires once, on the jump that crosses 0.49.0, and cannot be corrected for anyone already past it. Its gate searched `.ts` / `.tsx` while the command it is about lives in shell scripts, CI job definitions and runbooks — so a project whose only occurrence sat in `.gitlab-ci.yml` crossed 0.49.0 and was told there was nothing to apply.
 
-### Internal (no consumer-facing effect)
+  The re-issue is filed under 0.50.0, prints unconditionally, and says what to grep for. Redundant for anyone already fixed; the alternative is firing for nobody.
 
-- **@voltro/data-transfer** — `SAVEPOINT_BATCH_SIZE` carries its documentation again.
+### Fixed
 
-  A new `TRACE_ADVANCE_MS` was declared BETWEEN the constant's doc block and the constant, so TypeScript attached the block to whatever now followed it and the exported symbol was left bare — the api golden recorded it as `// @public (undocumented)` and the published report shipped it that way.
+- **@voltro/cli** — A `manual` codemod's `appliesTo` can now search every text file the project owns — `.sh`, `.yml`, `.json`, `.md`, `Makefile`, the `.js` scripts — through a new `ctx.text` on the predicate context, and a codemod may declare `reach: 'beyond-source'` to print its note even when nothing matched.
 
-  Third time this exact shape has appeared (`sourceKeys`, `recordsTable`, now this one), always the same mechanism: an insertion above a documented declaration silently re-homes the comment. Nothing warns, because both the code and the doc block are individually valid — only the golden's `(undocumented)` marker notices, and it reads as noise unless someone diffs it against the last TAG.
+  Both halves close the same gap, and it was in the codemod most in need of a gate. A manual codemod exists BECAUSE its subject could not be transformed, which usually means it is not source at all — and `appliesTo` was reading the ts-morph project, which holds `.ts` / `.tsx` and nothing else. Measured with one identical CLI invocation in four files: the `.ts` one printed the note, the `.sh`, `.yml` and `.md` ones printed nothing, and the run reported `codemods: nothing to apply for this jump`. That is an acquittal from a check that never looked at the file, and an acquittal gets acted on.
 
-  Documentation only; no behaviour, no signature change.
+  `reach: 'beyond-source'` covers what no scan of one repository can reach — an inline script in a CI runner's own UI, a CronJob spec in another repo, a wiki runbook. The note prints either way; only its framing changes, and an uncertain one says plainly that we could not look there.
+- **@voltro/data-transfer** — When `mariadb-dump` is absent and the mysql-family fallback runs Oracle's `mysqldump` against a MariaDB server, the failure now names the way out.
 
-  **`apiSurface: compatible`, and the reason is the whole point of the change.** The golden line that moved is `// @public (undocumented)` → `// @public`: an api-extractor MARKER describing whether a doc comment is present. No type, no signature, no name. `SAVEPOINT_BATCH_SIZE` is still `= 200`, still exported, still the same literal type — nothing that compiled can stop compiling.
+  The stderr it prints is the child's own words and is the right first thing to show — and on its own it is a dead end: `Unknown table 'COLUMN_STATISTICS' in information_schema (1109)` names a table nobody asked for, in a schema nobody wrote, about a feature nobody enabled. Everything needed to act on it was known where the fallback was DECIDED: which binary we wanted, which one we took, and why the difference matters. That travels with the step now and prints under the stderr, including the counter-move a reader reaches for on their own (`--column-statistics=0` does not exist on `mariadb-dump`, so it fixes the wrong client and breaks the right one).

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.48.0",
-    "@voltro/cli": "0.48.0",
-    "@voltro/database": "0.48.0",
-    "@voltro/env": "0.48.0",
-    "@voltro/protocol": "0.48.0",
-    "@voltro/runtime": "0.48.0",
+    "@voltro/ai": "0.50.0",
+    "@voltro/cli": "0.50.0",
+    "@voltro/database": "0.50.0",
+    "@voltro/env": "0.50.0",
+    "@voltro/protocol": "0.50.0",
+    "@voltro/runtime": "0.50.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.48.0",
+    "@voltro/testing": "0.50.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.48.0",
-    "@voltro/database": "0.48.0",
-    "@voltro/env": "0.48.0",
-    "@voltro/plugin-auth": "0.48.0",
-    "@voltro/protocol": "0.48.0",
-    "@voltro/runtime": "0.48.0",
-    "@voltro/sql-postgres": "0.48.0",
+    "@voltro/cli": "0.50.0",
+    "@voltro/database": "0.50.0",
+    "@voltro/env": "0.50.0",
+    "@voltro/plugin-auth": "0.50.0",
+    "@voltro/protocol": "0.50.0",
+    "@voltro/runtime": "0.50.0",
+    "@voltro/sql-postgres": "0.50.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.48.0",
+    "@voltro/testing": "0.50.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"