@voltro/cli 0.47.0 → 0.49.0

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-BU0wfV6V.js";
-export { e as loadDotEnv, t as registerAppModules, n as registerDriver, r as runServe };
+import { t as e } from "./serveCommand-N3udT49p.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-BlyXavoG.js → updateCommand-2BfbeMvp.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-De1_316I.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-CtYm7aKH.js

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

package/dist/{webhooksCommand-BqcWcbuW.js → webhooksCommand-CwX9IzvJ.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-CaIfZnw5.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-DFVuzOj7.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.47.0",
+  "version": "0.49.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",
@@ -739,22 +751,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.47.0",
-    "@voltro/cache": "0.47.0",
-    "@voltro/data-transfer": "0.47.0",
-    "@voltro/database": "0.47.0",
-    "@voltro/env": "0.47.0",
-    "@voltro/kv": "0.47.0",
-    "@voltro/logger": "0.47.0",
-    "@voltro/plugin-auth": "0.47.0",
-    "@voltro/plugin-broadcast": "0.47.0",
-    "@voltro/plugin-mail": "0.47.0",
-    "@voltro/plugin-storage": "0.47.0",
-    "@voltro/plugin-webhooks": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
-    "@voltro/serverless": "0.47.0",
-    "@voltro/workflow": "0.47.0",
+    "@voltro/ai": "0.49.0",
+    "@voltro/cache": "0.49.0",
+    "@voltro/data-transfer": "0.49.0",
+    "@voltro/database": "0.49.0",
+    "@voltro/env": "0.49.0",
+    "@voltro/kv": "0.49.0",
+    "@voltro/logger": "0.49.0",
+    "@voltro/plugin-auth": "0.49.0",
+    "@voltro/plugin-broadcast": "0.49.0",
+    "@voltro/plugin-mail": "0.49.0",
+    "@voltro/plugin-storage": "0.49.0",
+    "@voltro/plugin-webhooks": "0.49.0",
+    "@voltro/protocol": "0.49.0",
+    "@voltro/runtime": "0.49.0",
+    "@voltro/serverless": "0.49.0",
+    "@voltro/workflow": "0.49.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.47.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.49.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.47.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.49.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

@@ -2613,11 +2613,13 @@ Rows are written as newline-delimited JSON — streamable, resumable by line, an
 | *(none)* | Every table the app has DATA in (the default) — see the note below on the handful that describe a deployment rather than filling it. |
 | `--tenant <id>` | Every `tenant()`-scoped table filtered to that tenant, **plus** the FK closure in BOTH directions: (1) the transitive **FK-parent** closure of those rows — closure-pulled shared tables (a global `users` / reference table) are **row-subset to the ids the tenant's rows actually reference**, never exported in full; and (2) the **child** closure — rows that *reference* the tenant's rows (the comments on the tenant's projects) come along too, each scoped to the ids that actually point into the tenant set. The child walk is anchored on the `tenant()` tables, so a row that references **only a shared parent** (a global `users` another tenant also references) is **not** pulled — that would be a cross-tenant leak. A `--tenant` bundle therefore carries the tenant's parents AND children and **no other tenant's rows** — that's what makes it safe as a GDPR / per-tenant takeout. |
 | `--tables a,b` | An explicit set (you own referential integrity; the importer's deferred-FK resolution covers load-order dangles, see below). |
-| `--exclude a,b` | Everything EXCEPT these, expanded against the live table list. Direct target only. Cannot be combined with `--tables` or `--tenant`; a name that does not exist is refused, because an exclusion that excludes nothing leaves the run looking like it worked. |
+| `--exclude a,b` | Everything EXCEPT these. The scope stays `all` and records what was left out — so the deployment-describing tables are still filtered, and `replace` still accepts the bundle. Works on both targets (the instance resolves it against its own live list). Cannot be combined with `--tables` or `--tenant`; a name that does not exist is refused, because an exclusion that excludes nothing leaves the run looking like it worked. |
 
 #### What `all` deliberately leaves out
 
-A few framework tables hold rows **about a deployment** rather than an app's data — its migration ledger, its file-migration and seed records, its CDC offsets, its schedule claims and wakeups, its workflow watermarks / pending starts / admissions / pauses. They are dropped from `all`, skipped on import, and never emptied by a `replace`, and the run says which ones and why.
+A number of framework tables hold rows **about a deployment** rather than an app's data. The test is: would a row from elsewhere make this target *act* — send, run, admit, refuse, skip a delivery — or assert something untrue about its own history? That covers its migration ledger, file-migration and seed records, CDC offsets and change log, schedule claims, wakeups and firing history, workflow watermarks / pending starts / admissions / pauses / delivered events, its outbox and delivery attempts, its idempotency keys, its storage grants, its spend and usage accounting, and its own traces and undo log. They are dropped from `all`, skipped on import, and never emptied by a `replace`, and the run says which ones and why.
+
+Every framework table is classified one way or the other, and a new one fails the build until somebody decides — the classification used to live in two places, the module and a hand-kept copy in its test, and the two disagreed about exactly the tables that later caused trouble.
 
 The reason is worth one paragraph, because it cost a real environment ninety minutes. A `scope: all` bundle carried `_voltro_migration_plans`, `replace` wrote it, and the target's next boot refused:
 
@@ -2625,7 +2627,7 @@ The reason is worth one paragraph, because it cost a real environment ninety min
 auto-migrate: SCHEMA FINGERPRINT MISMATCH — declared=6e2c61081a9ed80c  live=28af9a54414f22f1
 ```
 
-The refusal was right. That fingerprint is computed over the **declared table set**, which legitimately differs per environment — `NODE_ENV=production` declares `_voltro_traces` and `_voltro_undo_log`, a `development` run does not. So the imported row was not out of date, it was **foreign**: it stated a schema decision made somewhere else. Two of the others would have made the target *act* — a pending workflow start runs a workflow somebody queued elsewhere, a pause silently stops one here.
+The refusal was right. That fingerprint is computed over the **declared table set**, so the imported row was not out of date, it was **foreign**: it stated a schema decision made somewhere else. (The declared set could also differ per environment then, because `NODE_ENV` decided two of the tables. It no longer does — but that removes one *way* for two deployments to differ, not the reason a foreign ledger row is wrong.) Two of the others would have made the target *act* — a pending workflow start runs a workflow somebody queued elsewhere, a pause silently stops one here.
 
 `all` is the only scope filtered. **Name one of these in `--tables` and you get it** — an explicit name is an expectation, and this command refuses to drop those silently.
 
@@ -2883,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.
@@ -2893,6 +2895,117 @@ 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.
 
+### Every request fits a budget
+
+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
+read that log either. The run is also deliberately decoupled from the caller:
+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 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
+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.
+  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
+the instance reads the table list out of the archive itself — 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.
+
+If it will not stage, the line says so and names the reason — a bundle table the
+target does not have, a foreign-key cycle, a dialect this build cannot stage on.
+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_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 transfers --target api --api-url https://app.example
+1 import(s) IN FLIGHT — re-run this to watch the counters move
+  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
+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.

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

@@ -3179,14 +3179,28 @@ flag flipped alone:
 
 **From 0.35.0 none of them does.** `_voltro_cdc_offsets` follows the DIALECT, so
 a mariadb/mssql app declares it either way; the other two are declared in
-`app.config.ts` and the env vars only choose what a process captures:
+`app.config.ts` and the env vars only choose what a process captures.
+
+**And from 0.48.0 `NODE_ENV` does not either.** Until then, `_voltro_traces` and
+`_voltro_undo_log` defaulted to on outside production — safe for the
+fingerprint, which only ever compares processes inside ONE deployment, and
+unsafe for the reader that spans two. `voltro data` is that reader: 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. One source tree therefore produced a bundle a production target could
+not stage, and the run fell back to truncating it — with nothing red anywhere.
+
+Both are declared in every environment now. An unused declared table is an empty
+table; a schema that differs per environment is a class of failure. Declare them
+only to leave one OUT:
 
 ```ts
 export default {
-  // Both default to on outside production. Declare them when you want the
-  // table in a production schema — `VOLTRO_UNDO` / `VOLTRO_TRACING_PERSIST`
-  // alone is no longer enough, because your migrate job does not carry them.
-  schema: { undo: true, traces: true },
+  // Declared in EVERY environment by default. Set `false` to keep a table out —
+  // and then set it in every environment, or two deployments of one source tree
+  // declare different schemas again. `VOLTRO_UNDO` / `VOLTRO_TRACING_PERSIST`
+  // still decide what a process WRITES; they no longer decide what exists.
+  schema: { undo: false, traces: false },
 }
 ```
 

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

@@ -1,4 +1,4 @@
-# What's new in 0.47.0
+# What's new in 0.49.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,28 +7,65 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
-### Changed
+### ⚠ BREAKING
 
-- **@voltro/database, @voltro/data-transfer, @voltro/cli, @voltro/plugin-storage** — A `--mode replace` no longer writes per-row history, and three things that were reported alongside it.
+- **@voltro/cli, @voltro/data-transfer, @voltro/database, @voltro/sql-sqlite, @voltro/voltro** — A data transfer is a series of short requests now — no single one may outlive a caller's budget.
 
-  **Write recorders are suspended for a `replace`.** A replace SETS a state; it does not change rows, so a per-row history entry describes something that did not happen. A deployment measured what that costs: they run `versioningPlugin({ timing: 'in-transaction' })` on 70 of 80 tables, so one import wrote 242 950 history rows and doubled the write load of the most expensive run they make — and those rows were the source of refused writes they spent three rounds diagnosing.
+  **The rule:** *a request that carries bytes never runs a transfer; a request that starts a transfer never carries bytes.* It was broken in the worst available place. The upload was already chunked and resumable — many short requests, each abandonable — and then the FINAL chunk fell through and ran the whole import. So the longest request of the flow arrived AFTER the entire upload had succeeded, and a caller under a policy that caps a single request (a job runner that kills a client at ten minutes; a 30 s ingress ceiling) lost the most expensive thing they had already paid for. A single-request upload had the same shape without the excuse, and the export had no protocol at all: one request that read the whole database and streamed it back.
 
-  The deciding argument is not the cost. **The import path had already decided this, and the recorder was the one layer that did not hear.** These routes write through the RAW store on purpose — no tenant scoping, no row filter, no `audit()` stamping. A recorder fired anyway because it hangs one level below the wrapper. Suspending it makes the layers agree.
+  **Import.** `POST /_voltro/admin/import` accumulates and answers `202`. `POST /_voltro/admin/import/start` begins the run and answers `202 { runId }` as soon as the run's first row exists. `start` is idempotent per upload — it is a short request and therefore a retryable one, and without a claim a retry would begin a second destructive run from the same bytes. A claim whose run has ENDED is taken over rather than honoured forever, so a process that dies holding one cannot poison a bundle.
 
-  Suspended for `replace` only: an `upsert` or an `append` CHANGES existing state, which is exactly what a recorder is for. Scoped per execution context rather than by a switch, because an import runs while the app serves requests and a process-global flag would silently drop recording for everything concurrent with it. And every such run SAYS what it suspended — dropping history quietly would be the same defect in a nicer costume.
+  **Export.** `POST /_voltro/admin/export` answers `202 { runId }` and produces in the background; the bytes come back from `GET /_voltro/admin/export/download?runId=&offset=&length=` in ranges, resumable, with the total in a header. Object storage (`--bundle-key`) remains for a bundle you want to KEEP — it is no longer the only way to get one out, because requiring it would leave an instance without storage unable to export at all.
 
-  This also removes the reason a staged `replace` used to fall back. A recorder is keyed by table name, so a staged write found none and the recorder never ran; rather than record inconsistently, the run took the slower path. For the deployment above that meant the staged path could never activate — permanently, on every environment.
+  **The client.** `--max-request-seconds` (or `VOLTRO_MAX_REQUEST_SECONDS`) declares the budget — declared rather than probed, because the thing that kills a request is a policy on the caller's side and only they know it. `--detach` returns once the run has started and says the outcome is NOT known. Attached, the CLI polls the record and prints per-table progress; Ctrl-C then loses the watching and never the run.
 
-  **`voltro codegen` wrote a truncated table declaration.** It discovered tables with the walk that collects the rpc GROUP's inputs — descriptors, workflows, events, and deliberately no `*.entity.ts`. So the generated `voltro-tables.generated.d.ts` listed the framework's tables plus `actors`, which the framework injects. Measured downstream: 37 names where a `voltro dev` boot writes 117, and 299 `TS2322` errors from every `source:` naming one of their own tables. The way in was our own message — `voltro test` refuses a stale rpc group and tells you to run `voltro codegen`. Table discovery has its own walk now, and a test compares the two walks' RESULTS on a real tree rather than trusting they mean the same thing.
+  **The trap, stated because it is the one way to get this wrong:** a failure used to arrive in the response (409 on drift, 409 on a refused mode, 500 otherwise). After the split the response is a `202`, so **a client deriving its exit code from the status line reports a failed import as a success.** The exit code comes from the polled record, in one shared function, and the drift check moved into `start` where it can still be a refusal that leaves no history.
 
-  **The eager-relation doctor rule missed the state that is most wrong.** It resolved relations only against the tables a query already DECLARED, on the reasoning that the base is virtually always in `source:`. Measured: a query reading `projects` while declaring only `projectTeams` produced no finding at all, while the same query with the base added produced two. The base is a fact about the executor, so it is read from the executor now.
+  **Two knobs that were constants.** `VOLTRO_IMPORT_UPLOAD_DIR` and `VOLTRO_EXPORT_ARTIFACT_DIR` move the staging areas off the default temp filesystem — which on a container is frequently a small tmpfs, so an instance simply could not accept a bundle the size a grown database produces, and the failure arrived as a write error halfway through an upload somebody had been waiting on.
 
-  **A rollback capture says when its path shares the root filesystem.** The 409 answered "is storage configured", which is not the question — a `filesystem` provider pointed at a container directory with no volume behind it passes it and dies with the pod. What a process CAN observe is that a mounted volume is a different filesystem: `pathDurability` compares device ids, and a capture landing on the same device as `/` says so. Three-valued on purpose, and explicitly not an alarm on a development machine, where everything is one device and nothing is a pod.
+  **Renamed:** `voltro data imports` → `voltro data transfers`, and `_voltro_data_imports` → `_voltro_data_transfers` with a `direction` column. The command showed one direction and now shows both; the table rename carries its rows via the declarative differ on every dialect and needs nothing from you. The CLI rename ships a `manual` codemod — the command lives in scripts, CI jobs and runbooks, which `voltro update` cannot see or rewrite. The four PUBLIC exports that named the same record were renamed with it (`ImportRun`, `describeImportRun`, `IMPORT_RUNS_TABLE`, `_voltroImportRunsTable`); those are application source, they ship their own `transform` codemod, and they have their own entry.
+- **@voltro/database, @voltro/voltro** — The run-history exports say `transfer`, not `import`.
 
-  **And the import records ITSELF, once.** Dropping per-row history left an operator asking "was this data imported, and when" with nothing to read, and trading too much for none is not obviously the better trade. `_voltro_data_imports` carries one row per RUN: the mode, the transport, the bundle, the SOURCE deployment's schema fingerprint, the counts, and — for the run an operator is actually looking for — the failure. It is written for a failed import as well as a finished one; a trail that only records successes goes quiet exactly when it is needed.
+  `@voltro/database` (and `voltro/database`) renamed four public exports along with the table behind them:
 
-  Best effort, unlike the interrupted-replace marker, and the difference is deliberate: the marker is a safety interlock and a run that cannot write it must not proceed, while history is valuable and not load-bearing. A target that has not been migrated yet still imports, and says the trace could not be written.
+  | was | is | |---|---| | `ImportRun` | `DataTransferRun` | | `describeImportRun` | `describeTransferRun` | | `IMPORT_RUNS_TABLE` | `DATA_TRANSFERS_TABLE` | | `_voltroImportRunsTable` | `_voltroDataTransfersTable` |
 
-  Two things it learned from being wired. The table is `.nonReactive()` — nobody subscribes to "an import happened", and a reactive bookkeeping write showed up in every suite that counts the LOAD's writes. And it is written only when the target actually DECLARES the table: the in-memory store accepts a write to any name, so an absent table cannot be detected by the write failing, and inventing the row would put a framework write into every embedder's counts.
+  An EXPORT writes to this record now — the row carries a `direction` — so every one of those names described half of what it holds.
 
-  **Measured at the reported magnitude.** 114 tables, 243 048 rows, real MariaDB, staged replace: the whole run takes 56.5s and the DESTRUCTIVE TRANSACTION takes **1.13s**. The window in which a dead process can leave a half-replaced target is the second number; before this it was the first.
+  A `transform` codemod rewrites all four, alias-aware, from either module spelling. It also rewrites a hand-spelled `_voltro_data_imports` in a string, template or raw-SQL fragment, and that is the half worth stating: the four identifiers announce themselves as compile errors, while a query that addresses the table by name has nothing to fail on. The table itself moves with its rows via the declarative differ on every dialect.
+
+  This is filed apart from the transfer-protocol entry beside it deliberately. That one's codemod is `manual` and is about a CLI invocation living in scripts and CI jobs; this one is application source and is rewritten for you. Reading the first as covering both is what would leave a build broken with a note saying nothing in your source was affected.
+
+### Added
+
+- **@voltro/database, @voltro/data-transfer, @voltro/cli** — An import records WHETHER it staged, and a soft-dropped column says so in a drift refusal.
+
+  **`_voltro_data_imports.staged`.** The pre-upload preflight says what the instance WILL do; the run's own line says what it did — and that line is printed inside the instance, which is exactly where an operator using `--target api` cannot read it. So "we were told it would stage" and "it staged" were two claims with no way to close the gap between them from outside. The column is `null` for a mode where the question does not arise; `voltro data imports` and `GET /_voltro/admin/imports` both carry it.
+
+  **A soft-dropped column is named as one.** `<original>__dropped_<stamp>` is what the differ leaves behind when an app stops declaring a column — only the database that did the drop has it, so it drifts against every target. The refusal reported it as an ordinary missing column ("the value has nowhere to go"), which points at the TARGET's schema: the one place the fix does not lie. It now says where the column lives and how to reclaim it.
+
+### Fixed
+
+- **@voltro/data-transfer, @voltro/sql-sqlite, @voltro/database** — A successful `--mode replace --no-atomic` left a marker that refused the next boot.
+
+  Two defects, one visible symptom, and both were silent by construction.
+
+  **The clear was gated on the WRITE's condition.** `!(useLedger && ledger.truncated)` means "an earlier attempt already recorded this destructive run, do not write a second row" — correct on the write. Copied down to the clear its meaning inverts: `ledger.truncated` is set by the emptying step of THIS run, so on `--no-atomic` (the only mode where `useLedger` is true) the clear was skipped by the very run that wrote the marker.
+
+  **And a `Date` in a predicate is not bindable on sqlite.** `better-sqlite3` binds numbers, strings, bigints, buffers and null; the row path has coerced Dates since that store was written, and the eager-join compiler carried its own private copy of the fix, but `query` / `updateMany` / `deleteMany` bound the raw value. So every comparison of a timestamp column against a `Date` failed with `Failed to execute statement` — including the marker's clear, which swallows its errors ON PURPOSE (a store with no marker table must not fail an import over a bookkeeping row) and therefore said nothing. The retention sweep compares `lt(column, cutoff)` the same way.
+
+  Together: a fully successful replace left the marker standing, and the next boot REFUSED with "a destructive import did not finish" over a database that was completely fine. The one recovery is a command the operator has no reason to think they need. It stayed invisible because `atomic` defaults to true for `replace`, and because a staged replace writes no marker at all — two defaults hiding the one mode that exists for large, interruptible loads.
+
+  The coercion is shared now and applied at all three predicate sites, with a guard that fails on a fourth that forgets. A dry run also closes its trace row: a preview that finished instantly used to leave the record open, so a polling caller waited out its whole budget over a run that was long done.
+- **@voltro/cli** — `voltro codegen` declared twenty framework tables fewer than a boot.
+
+  The app half of this was fixed last release and looked like the whole thing. It was not: `codegen` derived the FEATURE MIX from the file list it had just walked, and that list is the entity/relations set — which contains no `*.workflow.tsx`, no `*.agent.ts`, no `*.cron.tsx`. So every feature flag came back false, and the dialect was never passed at all, taking `_voltro_cdc_offsets` with it. Measured on an app with two workflow files: 18 framework tables where the shared assembly produces 33.
+
+  It calls `assembleFrameworkTables({ root })` now — the same entry `voltro db plan/apply` uses, which detects the mix from the root rather than being handed one.
+
+  The parity guard moved with it. Comparing the two WALKS could not see this: both walks were right about files, and the divergence was introduced one layer past them. It compares the assembled SETS now, and runs codegen's own table function on a tree whose only feature signals are a workflow file and an agent file — a source assertion that the right function is CALLED cannot see a wrong argument handed to it, and a wrong argument is what this was.
+- **@voltro/cli** — `voltro data --help` advertised four subcommands out of nine.
+
+  It printed `<export|import|backup|restore>` while the command dispatched those four plus `imports`, `inspect`, `unpack`, `clear-replace-marker` and `clear-staging`. A quoted enumeration is read as exhaustive — the same failure `subcommandNames.ts` was written for after a `db` list cost two wrong conclusions — and the missing entry here is the one that answers "what is my import doing right now" for somebody who cannot reach the pod.
+
+  `subcommandHelpParity.test.ts` had listed `data` among the commands it could not check, loudly and correctly: there was no name list to check against. There is one now (`DATA_SUBCOMMANDS`), the dispatch is a keyed `Record`, so a subcommand with no name and a name with no handler are both compile errors, and the usage line is generated from the same array. `data` is out of the unchecked list.

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.47.0",
-    "@voltro/cli": "0.47.0",
-    "@voltro/database": "0.47.0",
-    "@voltro/env": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
+    "@voltro/ai": "0.49.0",
+    "@voltro/cli": "0.49.0",
+    "@voltro/database": "0.49.0",
+    "@voltro/env": "0.49.0",
+    "@voltro/protocol": "0.49.0",
+    "@voltro/runtime": "0.49.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.49.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.47.0",
-    "@voltro/database": "0.47.0",
-    "@voltro/env": "0.47.0",
-    "@voltro/plugin-auth": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
-    "@voltro/sql-postgres": "0.47.0",
+    "@voltro/cli": "0.49.0",
+    "@voltro/database": "0.49.0",
+    "@voltro/env": "0.49.0",
+    "@voltro/plugin-auth": "0.49.0",
+    "@voltro/protocol": "0.49.0",
+    "@voltro/runtime": "0.49.0",
+    "@voltro/sql-postgres": "0.49.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.49.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.47.0",
-    "@voltro/database": "0.47.0",
-    "@voltro/env": "0.47.0",
-    "@voltro/plugin-multitenancy": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
+    "@voltro/cli": "0.49.0",
+    "@voltro/database": "0.49.0",
+    "@voltro/env": "0.49.0",
+    "@voltro/plugin-multitenancy": "0.49.0",
+    "@voltro/protocol": "0.49.0",
+    "@voltro/runtime": "0.49.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.49.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.47.0",
-    "@voltro/database": "0.47.0",
-    "@voltro/env": "0.47.0",
-    "@voltro/plugin-deactivation": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
+    "@voltro/cli": "0.49.0",
+    "@voltro/database": "0.49.0",
+    "@voltro/env": "0.49.0",
+    "@voltro/plugin-deactivation": "0.49.0",
+    "@voltro/protocol": "0.49.0",
+    "@voltro/runtime": "0.49.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.49.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.47.0",
-    "@voltro/database": "0.47.0",
-    "@voltro/env": "0.47.0",
-    "@voltro/plugin-mail": "0.47.0",
-    "@voltro/plugin-multitenancy": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
+    "@voltro/cli": "0.49.0",
+    "@voltro/database": "0.49.0",
+    "@voltro/env": "0.49.0",
+    "@voltro/plugin-mail": "0.49.0",
+    "@voltro/plugin-multitenancy": "0.49.0",
+    "@voltro/protocol": "0.49.0",
+    "@voltro/runtime": "0.49.0",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.49.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"