@voltro/cli 0.47.0 → 0.48.0

package/dist/serveCommand-ZP_Cb-yz.js

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

package/dist/{webhooksCommand-BqcWcbuW.js → webhooksCommand-QlAk_tED.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-cGGsLNn6.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.48.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -739,22 +739,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.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",
     "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.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. |
 | 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.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. |
 | 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.
 
@@ -2893,6 +2895,59 @@ 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
+
+Over `--target api` the import runs 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 — 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.
+
+**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.
+api import: uploading the bundle — this request stays open until the instance has imported it
+```
+
+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_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:
+
+```
+$ voltro data imports --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
+```
+
+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.
+
 ### 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.48.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,78 @@ 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/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** — The declared framework schema no longer depends on `NODE_ENV`.
+
+  `_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.
+
+  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.
+
+  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.
+
+  **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.
+
+  `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.
+
+### 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.
+
+  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.
+
+  `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:
+
+  SqlError: Failed to enable Turso MVCC (journal_mode=experimental_mvcc): database is locked
+
+  `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.
+
+  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.
+
+  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.
+
+  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.
 
-  **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.
+  **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 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.
+  **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`.
 
-  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.
+  **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.
 
-  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.
+  **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.
 
-  **`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 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.
 
-  **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.
+### Internal (no consumer-facing effect)
 
-  **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.
+- **@voltro/data-transfer** — `SAVEPOINT_BATCH_SIZE` carries its documentation again.
 
-  **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.
+  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.
 
-  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.
+  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.
 
-  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.
+  Documentation only; no behaviour, no signature change.
 
-  **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.
+  **`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.

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.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",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.48.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.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",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.48.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.48.0",
+    "@voltro/database": "0.48.0",
+    "@voltro/env": "0.48.0",
+    "@voltro/plugin-multitenancy": "0.48.0",
+    "@voltro/protocol": "0.48.0",
+    "@voltro/runtime": "0.48.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.48.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.48.0",
+    "@voltro/database": "0.48.0",
+    "@voltro/env": "0.48.0",
+    "@voltro/plugin-deactivation": "0.48.0",
+    "@voltro/protocol": "0.48.0",
+    "@voltro/runtime": "0.48.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.48.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.48.0",
+    "@voltro/database": "0.48.0",
+    "@voltro/env": "0.48.0",
+    "@voltro/plugin-mail": "0.48.0",
+    "@voltro/plugin-multitenancy": "0.48.0",
+    "@voltro/protocol": "0.48.0",
+    "@voltro/runtime": "0.48.0",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.48.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

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

@@ -13,18 +13,18 @@
   "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/plugin-storage": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
-    "@voltro/sql-mysql": "0.47.0",
+    "@voltro/cli": "0.48.0",
+    "@voltro/database": "0.48.0",
+    "@voltro/env": "0.48.0",
+    "@voltro/plugin-multitenancy": "0.48.0",
+    "@voltro/plugin-storage": "0.48.0",
+    "@voltro/protocol": "0.48.0",
+    "@voltro/runtime": "0.48.0",
+    "@voltro/sql-mysql": "0.48.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.48.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-backend-sqlite/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-multitenancy": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
-    "@voltro/sql-sqlite": "0.47.0",
+    "@voltro/cli": "0.48.0",
+    "@voltro/database": "0.48.0",
+    "@voltro/env": "0.48.0",
+    "@voltro/plugin-multitenancy": "0.48.0",
+    "@voltro/protocol": "0.48.0",
+    "@voltro/runtime": "0.48.0",
+    "@voltro/sql-sqlite": "0.48.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.48.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

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

@@ -11,17 +11,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.47.0",
-    "@voltro/database": "0.47.0",
-    "@voltro/env": "0.47.0",
-    "@voltro/plugin-multitenancy": "0.47.0",
-    "@voltro/plugin-storage": "0.47.0",
-    "@voltro/protocol": "0.47.0",
-    "@voltro/runtime": "0.47.0",
+    "@voltro/cli": "0.48.0",
+    "@voltro/database": "0.48.0",
+    "@voltro/env": "0.48.0",
+    "@voltro/plugin-multitenancy": "0.48.0",
+    "@voltro/plugin-storage": "0.48.0",
+    "@voltro/protocol": "0.48.0",
+    "@voltro/runtime": "0.48.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.47.0",
+    "@voltro/testing": "0.48.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

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

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