@voltro/cli 0.49.0 → 0.50.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.49.0",
+  "version": "0.50.1",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -676,6 +676,30 @@
         "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.51.0",
+        "id": "0.51.0/01_computed-source-keeps-its-names",
+        "title": "A COMPUTED `source:` can keep its typed names — do not widen the whole registry",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -751,22 +775,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.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",
+    "@voltro/ai": "0.50.1",
+    "@voltro/cache": "0.50.1",
+    "@voltro/data-transfer": "0.50.1",
+    "@voltro/database": "0.50.1",
+    "@voltro/env": "0.50.1",
+    "@voltro/kv": "0.50.1",
+    "@voltro/logger": "0.50.1",
+    "@voltro/plugin-auth": "0.50.1",
+    "@voltro/plugin-broadcast": "0.50.1",
+    "@voltro/plugin-mail": "0.50.1",
+    "@voltro/plugin-storage": "0.50.1",
+    "@voltro/plugin-webhooks": "0.50.1",
+    "@voltro/protocol": "0.50.1",
+    "@voltro/runtime": "0.50.1",
+    "@voltro/serverless": "0.50.1",
+    "@voltro/workflow": "0.50.1",
     "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.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. |
+| **What's new in 0.50.1** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | 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.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. |
+| **What's new in 0.50.1** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | 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

@@ -290,6 +290,19 @@ carries its own guards, or it is a UI-affordance scope that `useCan` reads to
 hide a button and no server check backs on purpose. All three are fine. Not
 knowing which is not.
 
+`rbac/unguarded-mutation` flags a mutation that declares neither a guard nor an
+`openAccess:` reason. It skips **`internal: true`** procedures: those are in no
+rpc group and on no route, so "any caller who can reach the rpc surface" names a
+surface that does not exist — and neither remedy applies either, since a guard
+would protect nothing and `openAccess` is refused outright on an internal
+descriptor. This is the same `isWireReachable` predicate the boot access gate and
+all three rpc-group assemblies use, so `check` and `voltro doctor` cannot answer
+the question differently.
+
+A manifest that does not carry the field at all — an api older than it — is read
+as *reachable*, not as internal. The rule stays loud rather than going quiet on
+the apps least able to notice.
+
 #### Declared vs OBSERVED — reconciled against reality
 
 A query's `source` and a mutation's `targets` are not documentation: the
@@ -323,6 +336,30 @@ Three things about that output are deliberate:
   about the runs that happened, not a proof about the ones that didn't, and
   `check`'s exit code gates CI. They are always warnings.
 
+A fourth thing is not visible in that output and matters more than any of the
+three: **the recorder only knows what ran.** A boot is not a run. An idle dev
+instance that started, served nothing and stopped produces
+
+```
+observed: 0/2755 procedures exercised (0%)
+  2753 unexercised — no recording, so nothing is claimed about them
+```
+
+which is the honest answer and also a useless one — the section says nothing
+about 99.9% of the surface. If you want this as a CI gate, the recording pass has
+to be a run that actually *calls* the procedures. `voltro e2e` is one: it spawns
+`voltro dev` for the api, which turns recording on, and then drives the specs. A
+harness of your own that boots the app in its own process needs
+`VOLTRO_OBSERVE_GRAPH=1` set before anything is imported. Either way, booting the
+app and then running `check` measures nothing, and the report will not pretend
+otherwise.
+
+It is still worth wiring up at low coverage, because the findings are per
+procedure and do not need company. One deployment had exactly one procedure
+observed, and that one produced a real defect: a mutation upserting
+`push_subscriptions` with no declared target while two queries read that table as
+their `source`, so a registered device never appeared in any running subscription.
+
 No file → the section is skipped silently. This is not derived by parsing your
 handlers: a static pass over code that reaches the store through shared helpers,
 behind conditionals, has a long tail of both false positives and false negatives
@@ -2996,7 +3033,7 @@ $ voltro data transfers --target api --api-url https://app.example
   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.
@@ -3330,12 +3367,85 @@ 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`.
 
+On **mariadb** the MariaDB-named binaries (`mariadb-dump`, `mariadb`) are preferred and Oracle's (`mysqldump`, `mysql`) are the fallback — with the reason carried into the failure, because the error that fallback produces (`Unknown table 'COLUMN_STATISTICS' in information_schema`, 1109) names a table nobody asked for. Two things worth knowing before you go and install the MariaDB client package:
+
+- Do **not** reach for `--column-statistics=0`. That flag does not exist on `mariadb-dump`, so it patches the wrong client and breaks the right one.
+- A MariaDB **12.x** client requires TLS by default. Running it *by hand* against a server without TLS fails with `TLS/SSL error: SSL is required` (2026) and needs `--skip-ssl`. These commands are not affected — it is the first manual call after installing that trips.
+
+### `--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.
+
+The backend it reads is the one your app **configured** — `storagePlugin({ provider: s3(…) })` if you installed it, the `STORAGE_*` env otherwise. (The commands used to resolve the env default unconditionally, so an app that configured its provider in code had its export, import and backup reading a different backend than the rest of it.)
+
+`--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. "Configured" means one of the two things a person actually did: installed `storagePlugin(...)`, or set `STORAGE_PROVIDER`. An in-memory provider nobody asked for is not a decision — and until recently it was what this check saw, which is why the refusal never fired and `--assets` wrote artifacts stamped as carrying blobs that held none.
+- **`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`.
+
+**A reference the provider cannot resolve is reported, not fatal.** A row in `_voltro_storage_refs` can point at an object that was deleted, or that never arrived because an earlier import ran without `--assets`. That is a fact about your data, and no backup can put back bytes that are not there — so the capture records the key, steps over it, and the run says how many:
+
+```
+warn  177 of 178 blob reference(s) point at objects the storage provider does not have;
+      they are NOT in this backup and no restore can bring them back.
+```
+
+Aborting on the first one made `--assets` unusable for exactly the deployment that needed it: 178 references, one resolvable, and the run stopped at the second — leaving an `assets/` directory with a single blob, **no `voltro-backup-stamp.json`** (the writer never got that far), and nothing anywhere saying 177 objects had been skipped. The stamp is now written on every path, including the one where the asset phase fails, because it describes the **dump** and the dump is already on disk and correct. Without it, `restore` greeted an artifact this tool had written minutes earlier with *"an older/handmade backup. Cannot verify dialect or schema version."*
+
+Only a genuine *not found* is treated this way. A 403 from a rotated credential or a 5xx from a backend outage still fails the capture — calling those "the object is gone" would turn a recoverable outage into a backup that quietly contains nothing.
+
+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.
+
+**The restore artifact can erase the marker, and this table said otherwise.** It read "postgres, mysql, mariadb: drops only the objects the dump names — the marker survives". The reasoning is right and the premise was wrong: a native dump names the *whole* database, `_voltro_replace_in_progress` included, and a mysql-family restore writes `DROP TABLE IF EXISTS` in front of each table. The table sorts early, so the guard was removed near the *start* of the window it covers. Measured downstream: one row before the restore, zero after, twice.
+
+Two changes, covering different dumps:
+
+- **A backup taken by `voltro data backup` excludes the marker table** (`--exclude-table` / `--ignore-table`). It can no longer carry the thing that erases the guard on the way back in.
+- **`restore` writes the marker back after the tool exits**, on the failing path as well as the succeeding one. That covers dumps taken before this version and dumps made by hand. If it was removed and rewritten you get a warning saying so; if it could not be rewritten you get an error, because the guard is then off for that run and nothing will stop the next boot.
+
+| dialect | shape | effect |
+|---|---|---|
+| postgres, mysql, mariadb | the dump names the whole database, so the restore drops the marker table too | our backups exclude it; for any other dump the marker is written back after the tool exits |
+| 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/data.md

@@ -1700,6 +1700,32 @@ That matters because the failure it replaces is silent. A `source:` is matched b
 
 The file is generated, so **commit it** like the rpc group and let `voltro dev` rewrite it. Before the first run — and in a project that never generates it — `source:` is plain `string` again, which is exactly the previous behaviour; there is no configuration and nothing to opt into.
 
+The error carries a suggestion when the name is close to a real one — `Did you mean '"error_logs"'?` — so a rename usually resolves without leaving the editor.
+
+#### A COMPUTED `source:` can keep its names
+
+A generic reader — the table arrives in `input`, the caller picks it out of a registry — is computed, and yet every name it can produce is known. The obvious derivation is not assignable:
+
+```ts
+source: Object.keys(JUNCTION_REGISTRY),   // string[] — ✗
+```
+
+The tempting exit is a cast, or annotating `ReactivitySourceValue` (the wide `string | ReactivityChannel` shape, exported from `@voltro/protocol`). Both compile at once and take that **entire** set of tables out of the check permanently. Keep the literal's keys instead:
+
+```ts
+const REGISTRY = { … } as const satisfies Readonly<Record<string, JunctionMeta>>
+
+// consumers that index with a plain string still get the wide type
+export const JUNCTION_REGISTRY: Readonly<Record<string, JunctionMeta>> = REGISTRY
+
+// … and the source list keeps its literal names
+export const JUNCTION_TABLE_NAMES = Object.keys(REGISTRY) as ReadonlyArray<keyof typeof REGISTRY>
+```
+
+The part that is easy to get wrong: an **annotation widens the keys back**, even when the literal carries `as const`. A registry written as `export const R: Readonly<Record<string, Meta>> = { … } as const` has `keyof typeof R === string`, and nothing about it looks wrong — the annotation is checked against the literal and then replaces its type. `satisfies` checks without replacing. That is the whole reason for the two-line split above.
+
+Reach for `ReactivitySourceValue` when there genuinely is no key set to keep — a name read from a config file, or assembled at runtime. Not when recovering one takes two lines.
+
 Two things it deliberately does not narrow. A **plugin's** route `source:` stays `string`: a plugin ships against many apps and cannot know any of their tables. And nothing that READS a descriptor's source at runtime narrows either — a reader that refused an unknown name would reject the stale name it exists to report.
 
 **It does not check the other direction — except for relations.** A `source:` that omits a table the query genuinely reads is silent: the name is right, the table exists, and nothing has an opinion. That is the failure that costs a user report — they type, the row lands, and the panel does not move.
@@ -1714,6 +1740,16 @@ Two things it deliberately does not narrow. A **plugin's** route `source:` stays
 
 An eager-loaded relation is composition by definition — its rows are IN the result — and its table comes from the relation registry, so the rule has no heuristic and no exception list. A **many-to-many** wants the junction table too, and says so separately: adding or removing a link writes only the junction row, so declaring the target alone leaves the list stale on exactly the operation a user performs to change it.
 
+Nested relations resolve in the **same** pass: a relation loaded under `.with({ subTasks: { with: { watchers: true } } })` is looked up on `task_sub_tasks`, not on the query's base, so both levels are reported at once rather than one per run.
+
+The one thing it still cannot see is a base table it cannot find — neither declared in `source:` nor written as `database.<name>` / `.select('<name>')`. There is then no table to resolve the relations against, and the query would otherwise report clean while every relation on it is unchecked. So doctor says so:
+
+```
+⚠  1 query could not be fully checked — the base table is neither declared nor readable from the executor:
+   reports.byKind: `blocked` resolved against no table
+   declare the base table in `source:` and re-run — relations under it are unchecked until then.
+```
+
 What doctor deliberately does NOT do is derive every table an executor reads. That needs a judgement — does this read **compose** the result or merely **restrict** it? — and only composing reads belong in `source:`; a restricting one re-running on every unrelated write puts a hundred lists back on the wire. A scan has to infer that from syntax, and a rule that guesses on a correct codebase teaches you to ignore it.
 
 So: when a live view does not update, check the writing table is in the reading query's `source:` before anything else.

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

@@ -1,4 +1,4 @@
-# What's new in 0.49.0
+# What's new in 0.50.1
 
 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,65 +7,54 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
-### ⚠ BREAKING
-
-- **@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.
-
-  **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.
-
-  **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.
-
-  **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.
-
-  **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.
-
-  **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.
+### Added
 
-  **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.
+- **@voltro/cli** — A `0.51.0` upgrade note for the case 0.45.0's typed-`source:` note left open: a source that is COMPUTED but whose names are all known — a generic reader that takes its table from `input` or a registry. Both remedies the original offered are wrong there. There is no misspelled name to fix, and widening to `ReactivitySourceValue` (or casting) compiles instantly while taking that entire set of tables permanently out of the check the narrowing exists to provide.
 
-  **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`.
+  The note carries the recipe that keeps the names — `as const satisfies`, with the key set recovered separately — and the trap under it: an ANNOTATION widens the keys back even when the literal carries `as const`, because it is checked against the literal and then replaces its type. Filed under an unreached version because codemod selection is `from < version <= to`: 0.45.0's note can never fire again for anyone already past it. Documented on the subscriptions page in both languages.
 
-  `@voltro/database` (and `voltro/database`) renamed four public exports along with the table behind them:
+### Changed
 
-  | was | is | |---|---| | `ImportRun` | `DataTransferRun` | | `describeImportRun` | `describeTransferRun` | | `IMPORT_RUNS_TABLE` | `DATA_TRANSFERS_TABLE` | | `_voltroImportRunsTable` | `_voltroDataTransfersTable` |
+- **@voltro/data-transfer** — The `mariadb-dump`-not-on-PATH hint now also warns that a MariaDB 12.x client requires TLS by default, so running it BY HAND against a server without TLS fails with `TLS/SSL error: SSL is required` (2026) and needs `--skip-ssl`. Our own invocation is unaffected. It is said here because this hint is what sends people to install that client package, and the next thing many of them do is run the tool by hand — where the failure reads like a broken install of the thing we just told them to install.
 
-  An EXPORT writes to this record now — the row carries a `direction` — so every one of those names described half of what it holds.
+### Fixed
 
-  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.
+- **@voltro/cli, @voltro/mcp** — `voltro check`'s `rbac/unguarded-mutation` no longer fires on `internal: true` procedures. Those are in no rpc group and on no route, so the finding's own sentence — "any caller who can reach the rpc surface can invoke it" — named a surface that does not exist, and neither remedy it offered was available: a guard protects nothing there, and `openAccess` is refused outright on an internal descriptor. An app with 990 internal mutations got 990 warnings and a `FAILED` exit from the same tree on which `voltro doctor` reported zero procedures without an access decision, which made `check` unusable as the CI gate it exists to be.
 
-  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.
+  The capability manifest now carries `internal: true` per procedure (present only when true), and the rule reads it through `isWireReachable` — the same predicate the boot access gate and all three rpc-group assemblies use, rather than a fourth spelling of the same flag. A manifest that does not carry the field is read as REACHABLE, so the rule stays loud on an api older than the field rather than going quiet on it.
+- **@voltro/data-transfer, @voltro/cli** — `--assets` aborted the whole capture at the first blob reference the storage provider could not resolve. A dangling reference is a fact about the source data — a row pointing at an object that was deleted, or that never arrived because an earlier import ran without the flag — and no backup can put back bytes that are not there. Aborting made the flag unusable for exactly the deployment that needed it: 178 references, one resolvable, and the run stopped at the second.
 
-### Added
+  The phase now records the key, steps over it, and the run reports how many were skipped. Only a genuine not-found (`status === 404`) is treated this way; a 403 from a rotated credential or a 5xx from a backend outage still fails the capture, because calling those "the object is gone" turns a recoverable outage into a backup that quietly contains nothing.
 
-- **@voltro/database, @voltro/data-transfer, @voltro/cli** — An import records WHETHER it staged, and a soft-dropped column says so in a drift refusal.
+  The same abort also cost the artefact its provenance: `voltro-backup-stamp.json` was written after the asset phase, so a backup taken WITH `--assets` had no stamp at all, and `restore` then greeted an artefact this tool had written minutes earlier as "an older/handmade backup. Cannot verify dialect or schema version." The stamp is now written on every path — it describes the dump, and the dump is on disk and correct by the time the assets run.
+- **@voltro/cli** — `voltro doctor`'s eager-loaded-relation rule resolves nested relations against their PARENT's target table instead of against the query's roots, so every level is reported in one pass. It flattened the `.with({ … })` tree before resolving, which meant a level-2 relation stayed invisible until level 1's table had been added to `source:` — each fix revealed the next level, and a clean run after the first fix meant nothing. One app ran `doctor → fix → doctor` twice before the output stopped producing new findings.
 
-  **`_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.
+  The one case that is still genuinely under-reported is now stated instead of being silent: when the executor's base table is neither declared nor textually readable, nothing resolves, and doctor prints which relation names it could not check rather than reporting clean.
+- **@voltro/data-transfer** — A native restore whose client exited before consuming its input took the whole CLI down with an unhandled `EPIPE`. `createReadStream(dump).pipe(child.stdin)` had no `error` listener, so Node threw on a write to a pipe with no reader:
 
-  **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
+  Error: write EPIPE Emitted 'error' event on Socket instance at: at Socket.onerror (node:internal/streams/readable:1045:14)
 
-- **@voltro/data-transfer, @voltro/sql-sqlite, @voltro/database** — A successful `--mode replace --no-atomic` left a marker that refused the next boot.
+  What that cost is the point. The crash landed before `close`, so the step never resumed: the client's stderr — the one place the reason was written down — was discarded, the transfer row was never closed, the in-progress marker was never re-asserted, and the operator got a raw Node stack trace over a database that was now half replaced. A deployment met it on a 64 MB restore and could not diagnose it at all, because the only diagnosis had been thrown away.
 
-  Two defects, one visible symptom, and both were silent by construction.
+  Every stream in the step now carries a handler. `EPIPE` on the child's stdin is deliberately swallowed — a child closes the pipe by dying, and its exit code and stderr are the actual failure — while any other stream error is carried and reported. The failure line now always includes the tool's stderr (and says so explicitly when the tool printed none), plus how many bytes of the artefact had been fed before it stopped. A source error also ends the child's stdin, which turns a restore that used to hang forever on a vanished dump into one that fails, and a clean exit over a broken input stream is reported as a failure rather than as a truncated success.
+- **@voltro/cli** — `voltro check`'s observed-vs-declared findings advised an op that does not exist. The recorder reports what the store did, and `store.upsert` is one call; a `target:` is `InsertTarget | UpdateTarget | DeleteTarget` and has no `upsert` member. So `observed/undeclared-write` said to add `{ table: '…', op: 'upsert' }` — a `TS2322`, from a line whose whole purpose is to be pasted. It now advises both halves, and the observed → declarable mapping is typed `Record<ObservedWriteOp, ReadonlyArray<TargetSpec['op']>>` so a new recorder op cannot ship without a declarable answer.
 
-  **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.
+  The remedy no longer produces a finding of its own either: declared targets are now collected per table as a SET. `new Map(targets.map(t => [t.table, t.op]))` kept only the last op, so the correct two-entry declaration read as "declares update" and the insert half came back as a `wrong-op`.
+- **@voltro/data-transfer, @voltro/cli** — The in-progress restore marker did not survive a native restore, on the exact dialects that were documented as safe. The claim — postgres and the mysql family drop only the objects the dump names, so the marker row survives — had a correct argument and a wrong premise: a native dump names the WHOLE database, `_voltro_replace_in_progress` included, and a mysql-family restore writes `DROP TABLE IF EXISTS` in front of each table. The table sorts early, so the guard was removed near the START of the window it exists to cover. Measured downstream as one row before and zero after, twice, once by hand and once through the command — and then a restore died and left a database with a schema, some of its tables, no users and no blobs, with nothing to stop the next boot.
 
-  **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.
+  Two changes, covering different dumps. `voltro data backup` now excludes the marker table (`--exclude-table` / `--ignore-table`), so an artefact we produce cannot carry the thing that erases the guard on the way back in. And `restore` re-asserts the marker after the tool exits, on the failing path as well as the succeeding one, which covers dumps taken before this change and dumps made by hand: rewritten is a warning, and unwritable is an error, because the guard is then off for that run.
+- **@voltro/plugin-storage, @voltro/cli** — `--assets` could not be refused when no storage was configured, and resolved the wrong backend when it was.
 
-  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.
+  `resolveStorageProvider({})` is total: its final `default:` arm returns an in-process `memoryProvider`. So the three `if (!provider)` refusals in `voltro data backup` / `export` / `restore` — whose entire job is to refuse a flag the app cannot honour — were checking a condition that cannot hold. What they let through is worse than an unchecked flag: with no storage configured, `backup --assets` captured from a fresh memory provider, found nothing in it, and wrote an artefact stamped `assets: { count: 0 }` — a rollback story that says the blobs are in there.
 
-  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.
+  It also ignored the provider the app REGISTERED. An app on `storagePlugin({ provider: s3(…) })` had its export/import/backup read and write the env-derived default instead, which surfaces later as "no object at key" — the exact drift `appStorageProvider()` exists to prevent, in call sites that never adopted it.
 
-  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.
+  `configuredStorageProvider()` is the honest predicate: the app's registered provider, else the env-named one, else `undefined`. A memory provider nobody asked for is not a decision. The CLI now loads the app config BEFORE resolving — `storagePlugin(...)` registers at construction, so asking first answered with the default no matter what the app had configured.
 
-  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.
+### Internal (no consumer-facing effect)
 
-  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.
+- **@voltro/cli** — `voltro data backup` / `restore` / `clear-replace-marker` are now driven end to end, one case per declared option and one per refusal, as real CLI subprocesses against a real database.
 
-  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.
+  Every defect this command has shipped lived in the SEQUENCE rather than in a function — an unhandled `EPIPE` that discarded the client's stderr before `close` fired, a marker erased by the restore's own artefact, an asset abort that skipped the provenance stamp, a refusal that could not fire — so none of them was reachable by testing a part. `nativeBackupRestore.e2e.test.ts` covers the whole surface against sqlite (a file copy: no vendor binary, runs anywhere) and `nativeBackupRestoreDialects.integration.test.ts` runs the vendor-tool half against postgres, mariadb and mysql, skipping BY NAME when the server or the client binary is absent — including when the client is present but too old for the server, which a "is it on PATH" check reports as ready.
 
-  `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.
+  The suite checks itself against `DATA_FLAGS`, the command's own declared option list, so an option cannot be added without a case that drives it.

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