@voltro/cli 0.44.1 → 0.46.0

package/dist/serveEntry.d.ts

@@ -20,3 +20,27 @@ export declare const registerDriver: (spec: string, mod: Record<string, unknown>
 export declare const runServe: (args: ReadonlyArray<string>) => Promise<number>;
 
 export { }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'tasks': true;
+        'task_sub_tasks': true;
+        '_voltro_workflow_runs': true;
+        '_voltro_workflow_run_steps': true;
+        '_voltro_workflow_run_events': true;
+        '_voltro_workflow_events': true;
+        '_voltro_workflow_event_deliveries': true;
+        '_voltro_approvals': true;
+        '_voltro_connections': true;
+        '_voltro_undo_log': true;
+    }
+}
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'invoices': true;
+        'invoice_lines': true;
+    }
+}

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

package/dist/{start-Ds3xyn8R.js → start-7HcSIKEp.js}

@@ -1,6 +1,6 @@
 import { i as e, t } from "./nodeEnvironment-cGFAj1J8.js";
 import { r as n } from "./appPort-B_HpJ_ck.js";
-import { A as r, C as i, D as a, E as o, F as s, H as c, I as l, J as ee, L as u, M as d, N as f, O as te, P as p, R as m, S as h, T as ne, V as g, W as re, X as _, Y as v, Z as y, a as b, b as x, d as S, f as C, ht as w, i as ie, j as T, k as E, n as D, nt as O, q as k, s as ae, tt as A, vt as j, x as oe, y as M, z as se } from "./webDev-101csg6Q.js";
+import { A as r, C as i, D as a, E as o, F as s, H as c, I as l, J as ee, L as u, M as d, N as f, O as te, P as p, R as m, S as h, T as ne, V as g, W as re, X as _, Y as v, Z as y, a as b, b as x, d as S, f as C, ht as w, i as ie, j as T, k as E, n as D, nt as O, q as k, s as ae, tt as A, vt as j, x as oe, y as M, z as se } from "./webDev-B4IEMB0n.js";
 import { o as N, t as P } from "./connectionConfig-Bk9IC7D0.js";
 import { A as F, D as I, a as ce, h as le, j as ue, k as de } from "./inspect-B7U7Cl_Z.js";
 import { a as fe, c as L, d as pe, f as R, l as me, p as he, u as ge } from "./renderModeScan-D7J1B7Kw.js";

package/dist/{start-BAlGcjF5.js → start-DvlYDyAr.js}

@@ -1,3 +1,3 @@
 import "./renderModeScan-D7J1B7Kw.js";
-import { t as e } from "./start-Ds3xyn8R.js";
+import { t as e } from "./start-7HcSIKEp.js";
 export { e as runStartCommand };

package/dist/startEntry.d.ts

@@ -3,3 +3,27 @@ export declare const loadDotEnv: (argv: ReadonlyArray<string>) => void;
 export declare const runStartCommand: (args: ReadonlyArray<string>) => Promise<number>;
 
 export { }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'tasks': true;
+        'task_sub_tasks': true;
+        '_voltro_workflow_runs': true;
+        '_voltro_workflow_run_steps': true;
+        '_voltro_workflow_run_events': true;
+        '_voltro_workflow_events': true;
+        '_voltro_workflow_event_deliveries': true;
+        '_voltro_approvals': true;
+        '_voltro_connections': true;
+        '_voltro_undo_log': true;
+    }
+}
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'invoices': true;
+        'invoice_lines': true;
+    }
+}

package/dist/startEntry.js

@@ -1,3 +1,3 @@
 import { t as e } from "./loadEnv-D9nEOClM.js";
-import { t } from "./start-Ds3xyn8R.js";
+import { t } from "./start-7HcSIKEp.js";
 export { e as loadDotEnv, t as runStartCommand };

package/dist/startup.d.ts

@@ -63,3 +63,27 @@ export declare interface StartupHandle {
 export declare const startupTimeoutMsFromEnv: (envValue: string | undefined) => number;
 
 export { }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'tasks': true;
+        'task_sub_tasks': true;
+        '_voltro_workflow_runs': true;
+        '_voltro_workflow_run_steps': true;
+        '_voltro_workflow_run_events': true;
+        '_voltro_workflow_events': true;
+        '_voltro_workflow_event_deliveries': true;
+        '_voltro_approvals': true;
+        '_voltro_connections': true;
+        '_voltro_undo_log': true;
+    }
+}
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'invoices': true;
+        'invoice_lines': true;
+    }
+}

package/dist/{test-CLYXrZ2F.js → test-CHb7UwvE.js}

@@ -79,7 +79,7 @@ var d = l({ scope: "voltro:test" }), f = (e) => {
 }, C = async (e) => {
 	let t = m(e);
 	if (!o(t.root)) return console.error(`voltro test: no such directory: ${t.root}`), 1;
-	let { checkRpcGroupFreshness: n } = await import("./codegen-i8QGcHsi.js"), r = await n(t.root);
+	let { checkRpcGroupFreshness: n } = await import("./codegen-DcE2li1i.js"), r = await n(t.root);
 	if (r.kind === "stale") return console.error(`voltro test: ${r.file} is stale — ${r.reason}.`), console.error("  The tests would run against the previously generated procedure group, pass, and prove nothing about the descriptors you just edited.\n  Run `voltro codegen` (or boot `voltro dev` once) and try again."), 1;
 	d.info("running vitest", {
 		root: t.root,

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

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-BKTnaGOz.js";
+import { n as e, r as t, t as n } from "./codemodRunner-DSZjgyCL.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-CT5AvVg7.js

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

package/dist/{webDev-101csg6Q.js → webDev-B4IEMB0n.js}

@@ -14,8 +14,8 @@ import { existsSync as j, promises as M, readFileSync as N, readdirSync as P, st
 import { fileURLToPath as te, pathToFileURL as L } from "node:url";
 import { addSink as R, createLogger as z, printReadyBlock as ne } from "@voltro/logger";
 import { createRequire as B } from "node:module";
-import { homedir as V } from "node:os";
-import { currentTraceContext as re, resolveSecret as H } from "@voltro/runtime";
+import { currentTraceContext as V, resolveSecret as re } from "@voltro/runtime";
+import { homedir as H } from "node:os";
 import { FRAMEWORK_ENV_CATALOG as U, appEnvEntries as ie, checkEnvNaming as W, formatEnvErrors as ae, installEnvSnapshot as G, isEnvContract as oe, pluginEnvEntries as se, renderDotEnvExample as ce, resolveEnv as le } from "@voltro/env";
 import { __installPublicEnv as ue } from "@voltro/env/public";
 import { mkdir as de, writeFile as fe } from "node:fs/promises";
@@ -68,7 +68,7 @@ __installPublicEnv(publicEnvValues)
 }, Ce = async (e) => {
 	let t = oe(e.rawEnv) ? e.rawEnv : void 0, n = await le({
 		contract: t,
-		resolveSecret: H
+		resolveSecret: re
 	}), r = [...n.errors, ...W(t, e.appType)];
 	if (r.length > 0) throw Error(ae(r));
 	G(n.values), e.appType === "web" && ue(n.publicValues);
@@ -780,7 +780,7 @@ __installPublicEnv(publicEnvValues)
 		if (zt(t[i], a), !r) {
 			r = !0;
 			try {
-				let t = a.length > 0 ? It(a[0]) : "", r = t.length > 500 ? t.slice(0, 500) + "…" : t, o = re();
+				let t = a.length > 0 ? It(a[0]) : "", r = t.length > 500 ? t.slice(0, 500) + "…" : t, o = V();
 				e.emit("log", {
 					level: i,
 					message: r,
@@ -818,7 +818,7 @@ __installPublicEnv(publicEnvValues)
 					argsCount: 1,
 					...t.scope === void 0 ? {} : { scope: t.scope }
 				});
-				let a = re(), o = a !== void 0 && t.fields.traceId === void 0 ? {
+				let a = V(), o = a !== void 0 && t.fields.traceId === void 0 ? {
 					...t.fields,
 					traceId: a.traceId
 				} : t.fields;
@@ -1190,7 +1190,7 @@ import {
 		a || (a = !0, i.destroy(), r(e));
 	};
 	i.once("connect", () => o(!0)), i.once("error", () => o(!1)), setTimeout(() => o(!1), n);
-}), Dn = () => !!(process.env.VOLTRO_DASHBOARD === "off" || process.argv.includes("--disable-dashboard")), On = () => process.env[Tn] === "1", kn = () => process.stdout.isTTY === !0, An = O(V(), ".voltro", "dashboard-launch.lock"), jn = 1e4, Mn = async () => {
+}), Dn = () => !!(process.env.VOLTRO_DASHBOARD === "off" || process.argv.includes("--disable-dashboard")), On = () => process.env[Tn] === "1", kn = () => process.stdout.isTTY === !0, An = O(H(), ".voltro", "dashboard-launch.lock"), jn = 1e4, Mn = async () => {
 	try {
 		await M.mkdir(D(An), { recursive: !0 });
 		let e = await M.open(An, "wx");

package/dist/webDev-B79ji8M5.js

@@ -0,0 +1,2 @@
+import { _ as e, y as t } from "./webDev-B4IEMB0n.js";
+export { e as tryRunWebServe, t as walkPagesTree };

package/dist/{webhooksCommand-BfO_JF2b.js → webhooksCommand-BRrG_sGf.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-BZO5aLdr.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-DyoYst4j.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.44.1",
+  "version": "0.46.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -640,6 +640,18 @@
         "title": "`runImport` returns an ImportOutcome — read `.manifest` for the bundle",
         "kind": "manual"
       },
+      {
+        "version": "0.45.0",
+        "id": "0.45.0/01_typed-source-table-name",
+        "title": "`source:` is typechecked against the app’s tables, from the next `voltro dev`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.46.0",
+        "id": "0.46.0/01_typed-aggregate-source",
+        "title": "an aggregate’s `incremental.source` is typechecked against the app’s tables",
+        "kind": "manual"
+      },
       {
         "version": "0.5.0",
         "id": "0.5.0/01_one-terminal-exactly-one",
@@ -727,22 +739,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.44.1",
-    "@voltro/cache": "0.44.1",
-    "@voltro/data-transfer": "0.44.1",
-    "@voltro/database": "0.44.1",
-    "@voltro/env": "0.44.1",
-    "@voltro/kv": "0.44.1",
-    "@voltro/logger": "0.44.1",
-    "@voltro/plugin-auth": "0.44.1",
-    "@voltro/plugin-broadcast": "0.44.1",
-    "@voltro/plugin-mail": "0.44.1",
-    "@voltro/plugin-storage": "0.44.1",
-    "@voltro/plugin-webhooks": "0.44.1",
-    "@voltro/protocol": "0.44.1",
-    "@voltro/runtime": "0.44.1",
-    "@voltro/serverless": "0.44.1",
-    "@voltro/workflow": "0.44.1",
+    "@voltro/ai": "0.46.0",
+    "@voltro/cache": "0.46.0",
+    "@voltro/data-transfer": "0.46.0",
+    "@voltro/database": "0.46.0",
+    "@voltro/env": "0.46.0",
+    "@voltro/kv": "0.46.0",
+    "@voltro/logger": "0.46.0",
+    "@voltro/plugin-auth": "0.46.0",
+    "@voltro/plugin-broadcast": "0.46.0",
+    "@voltro/plugin-mail": "0.46.0",
+    "@voltro/plugin-storage": "0.46.0",
+    "@voltro/plugin-webhooks": "0.46.0",
+    "@voltro/protocol": "0.46.0",
+    "@voltro/runtime": "0.46.0",
+    "@voltro/serverless": "0.46.0",
+    "@voltro/workflow": "0.46.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.44.1** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.46.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.44.1** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.46.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

@@ -1377,6 +1377,22 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### Relations a query loads but does not declare
+
+An eager-loaded relation is part of the RESULT, so its table has to be in `source:` or the view stops updating when it changes:
+
+```
+✗  1 query loads a relation it does not declare:
+   tasks.getById: eager-loads `subTasks` from 'tasks' but does not declare
+   'task_sub_tasks' in `source:` — the view will not update when 'task_sub_tasks' changes.
+```
+
+This is the failure that looks like a broken feature and is not: the write lands, a reload shows it, and every test of the write path is green. The name in `source:` is spelled right and the table exists, so neither the typed `source:` nor the boot audit has anything to say.
+
+The rule has no exception list, deliberately. It resolves `.with({ … })` keys through the relation registry, so the missing table is a fact rather than an inference — and a **many-to-many** is reported twice when needed, because the junction table is where a link add/remove actually writes.
+
+It reads what it can read literally: a computed `.with()` key yields nothing rather than a guess.
+
 ### The access-decision gate
 
 Before the authz scan below — which is a heuristic over executor SOURCE — doctor
@@ -2594,11 +2610,25 @@ Rows are written as newline-delimited JSON — streamable, resumable by line, an
 
 | Flag | Selects |
 |---|---|
-| *(none)* | Every table (the default). |
+| *(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. |
 
+#### 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.
+
+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:
+
+```
+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.
+
+`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.
+
 **Every table needs a single-column primary key.** The export is keyset-paginated, so it orders by one column and resumes from the last value on the next page. That column comes from the real primary key — a declared `id()` where there is one, otherwise the table's actual PK, whatever it is called.
 
 A table with a **composite** primary key, or none at all, is **refused by name** rather than exported. Ordering by one column of a composite key splits equal values across page boundaries, which drops or duplicates rows into a bundle that reports success — and a short backup is discovered at the restore. Leave such a table out with `--exclude`.
@@ -2737,6 +2767,128 @@ returns **`409` schema drift** with the fingerprints + diff; `--force` sends
 
 The pre-flight only runs when the importer has a target schema (the CLI introspects it; the API endpoint uses the instance's declared schema). Importing into a fresh/empty database with no comparable schema simply skips the check.
 
+### `replace` writes down what it is about to destroy
+
+Before the first delete, a `replace` exports the target's **current** rows for exactly the tables it is going to empty, as an ordinary bundle beside yours:
+
+```
+rollback capture: 240172 row(s) across 75 table(s) → ./out.rollback-2026-08-21T09-10-11-000Z
+  If this run does not finish, restore with:  voltro data import ./out.rollback-… --mode replace
+```
+
+It is on disk **before** anything is destroyed, so it does not depend on a transaction, or on the process being alive to roll one back. That distinction is the whole reason it exists: a deployment lost 240 172 rows to a `replace` whose api pod disappeared nine minutes in, and recovered from an export they had taken twenty minutes earlier out of habit. This is that habit, made into the tool's behaviour.
+
+**It is fail-closed.** A capture that cannot be taken stops the import before it starts, and the target is untouched. A safety net you believe in and do not have is worse than none — the belief is what stops you taking your own export.
+
+`--no-rollback` turns it off, and `--rollback-dir <path>` puts it somewhere else. It is only taken for `replace`: `upsert` and `append` do not destroy, so there is no moment where the old state has silently become unreachable.
+
+**Over `--target api` it goes to the instance's object storage**, because there the process that would roll a transaction back IS the instance — a capture in the pod's filesystem would go away with the failure it exists for. Name a key:
+
+```bash
+voltro data import ./out --target api --api-url <url> --token $SECRET --mode replace --rollback-key backups/before.vbundle
+```
+
+The instance writes the capture there **before the first delete**, and refuses the run (409) if it has no storage configured — asking for a capture and being served without one is the answer that removes your own precaution while looking like agreement. A `replace` that names no key still runs, and says what it did not keep.
+
+### `replace` loads somewhere else first
+
+The target keeps its rows until the load stands. `replace` creates a staging
+table per table, loads the bundle into those, and then swaps the CONTENT across
+in one short transaction of server-side SQL. It says so when it does:
+
+```
+staging 114 table(s) before the swap — the target keeps its rows until the load stands.
+  The destructive step is one server-side transaction at the end, not the whole load.
+```
+
+The difference is what a dead process costs. Loading straight into the target
+holds the destructive transaction open for the whole load — minutes, for a large
+bundle — and the target only survives because the database rolls that
+transaction back. With staging, a process that dies during the load leaves the
+target exactly as it was, because nothing has been deleted yet.
+
+Not every run can take it, and a run that cannot **says why** rather than quietly
+taking the slower path:
+
+- a store the framework cannot send DDL to (the in-memory store).
+- a **write recorder** on any table in the set — `versioningPlugin({ timing:
+  'in-transaction' })` and friends. A recorder is keyed by table name, so a
+  staged write would find none and the recorder would silently not run. Its
+  promise is "if the change committed, the entry is there", so the run keeps the
+  path that can keep it.
+
+**`--no-atomic` stages too, and that is where it changes the most.** The flag
+exists for resumability on a large bundle, and it used to be the mode with the
+worst failure: the target emptied and partially refilled, in neither state.
+Staged, the ledger keeps its exact meaning — a recorded table is one fully
+loaded, it just lands in staging — while the target stays untouched until the
+swap. Resumable and all-or-nothing at once, which the two could not be before.
+
+A resumed run continues from what it already staged rather than reloading it,
+and a run whose swap has not happened keeps its staged rows and says so:
+
+```
+the staged rows are KEPT so a re-run can continue from them rather than reload.
+  If you are not going to re-run this bundle, drop them: voltro data clear-staging --yes
+```
+
+**A failed swap names every offending row, not the first.** Staging carries no
+foreign keys — a staged row whose parent has not been staged yet must not be
+refused — so a dangling reference surfaces at the swap, where the database
+reports one constraint. The importer then asks staging the same question and
+lists every row that fails it:
+
+```
+the swap could not run: 2 row(s) in the bundle reference a row the bundle does not carry.
+    tasks.t_41: ownerId = "u_9" — no such row in users
+    tasks.t_88: ownerId = "u_12" — no such row in users
+  The target is UNCHANGED — the swap runs in one transaction and none of it committed.
+```
+
+Staging tables from a run that died mid-load are collected by the next
+`replace` over the same tables. One over a DIFFERENT set leaves them, and
+nothing else removes them:
+
+```bash
+voltro data clear-staging --yes
+```
+
+Deliberately a command and not a boot sweep: a booting process cannot tell a
+leftover from a staging table another replica is loading into right now, and
+deleting the second would destroy an import in flight.
+
+A **cycle** in the bundle's foreign keys is detected before the load, not after
+it. The swap inserts parents first, so two tables referencing each other cannot
+both be satisfied by a bulk copy on postgres, sqlite or SQL Server — `SET
+CONSTRAINTS ALL DEFERRED` does not help, because postgres only defers a
+constraint declared `DEFERRABLE`. Such a run says so and takes the row-by-row
+path, whose deferred-FK pass exists for exactly that shape. A table referencing
+ITSELF is not a cycle: one statement carries the whole table.
+
+### 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.
+
+So a `replace` writes one row before the first delete and removes it after the last insert. Finding it at boot is a **refusal**, not a warning:
+
+```
+refusing to start: a destructive import did not finish.
+  - a `replace` over api began emptying 114 table(s) 12 minute(s) ago and never reported finishing.
+    The target's previous rows were captured first:
+      ./out.rollback-2026-08-21T09-10-11-000Z
+    Restore them with:  voltro data import ./out.rollback-… --mode replace
+```
+
+The row lives in the same transaction as the emptying, so it is present **exactly when the emptying is**: a run that rolls back cleanly takes the marker with it, and a boot over a database nothing happened to is not refused. A completed `replace` clears its own marker and any older one — so the recovery import both restores the data and silences the alarm, in one command.
+
+Nothing expires. A half-replaced database does not become whole with time, so clearing it is a decision:
+
+```bash
+voltro data clear-replace-marker --yes
+```
+
+The devtools import panel takes the same two precautions as the command line — a capture before the first delete, and the marker — because a button is easier to press than a command is to type.
+
 ### Deferred-FK resolution
 
 A row whose write fails on a foreign-key constraint — a forward reference from a `live`-consistency export, a genuine FK **cycle** between tables (which the exporter orders by breaking the closing edge), or an intra-table self-reference to a later row — does **not** fail the import. It is held and resolved after every table has streamed:
@@ -2757,7 +2909,21 @@ The error carries three things, and they answer different questions:
 | `byTable` | **complete** per-table counts (`refused`, `primary`), worst first. |
 | `rows` | up to 20 refused rows — primary ones first — each with `table`, `id`, `reason`. |
 
-`rows` is **capped and `byTable` is not**, and that distinction is worth one sentence: tallying the tables in the printed list answers "how big is the cap", not "which tables failed". The CLI prints the `byTable` line above the list and says so when the list is truncated.
+`rows` is **capped and `byTable` is not**, and that distinction is worth one sentence: tallying the tables in the printed list answers "how big is the cap", not "which tables failed". The CLI prints the `byTable` line above the list and says so when the list is truncated:
+
+```
+import refused 35 row(s), of which 35 are the actual failures — the rest could not land because a row they reference did not.
+  by table: vacations 26, weeklyUpdates 9
+  vacations v1  not-null constraint userId: the column requires a value [ER_BAD_NULL_ERROR/1048]
+  …
+  (the list above is capped at 20 of 35 — the counts by table are complete)
+```
+
+A refused import ends with a **non-zero exit status and that report** — not with a stack trace. A refusal is a condition with a named cause, not a framework defect, so it is not dressed as one. The report is the same on both transports: over `--target api` the refusal crosses as a 500 whose message embeds it, and the CLI renders that rather than printing the body raw.
+
+**`RowsRefusedError` keeps its tag in every mode, `--atomic` included.** That is worth stating because it is the mode `replace` uses by default: the whole table phase runs in one transaction, and rolling that transaction back needs a rejection — but the rejection carries the typed error, not a rendering of it. So `Effect.catchTag('RowsRefusedError', …)` works on the default path, which is the one most likely to raise one.
+
+One trap if you consume `runImport` yourself: what `Effect.runPromise` **rejects** with is a `FiberFailure`, and `err._tag` on one of those reads `undefined` however good the error inside is. Use `Effect.catchTag` on the effect, or `asImportError(err)` (exported from `@voltro/data-transfer`) on the rejection — reading the tag off the caught value takes the "not my error" branch every time.
 
 A row's `reason` is stated as precisely as the driver allows, in three tiers:
 
@@ -2773,7 +2939,7 @@ Unlike the rpc wire, this string DOES include the driver's own words. The audien
 |---|---|---|---|
 | `upsert` (default) | INSERT-or-UPDATE by primary key | sync / idempotent re-import | overwrites per row |
 | `append` | INSERT only | additive data (event log, new seed) | `--on-conflict skip` (default) or `fail` |
-| `replace` | empty the target tables, then INSERT | full refresh — target ends up **exactly** the bundle | — |
+| `replace` | capture the target, empty it, then INSERT | full refresh — target ends up **exactly** the bundle | — |
 
 `replace` **refuses a partial bundle** (a subset / tenant / table scope): emptying would delete rows the bundle never carried. Re-export with full scope, or use `upsert`. (`append --on-conflict fail` throws on a duplicate primary key only where the store enforces the constraint — every SQL dialect does; the in-memory dev store overwrites.)
 
@@ -2898,6 +3064,16 @@ voltro data import ./out --target api --api-url https://api.example --token $SEC
 
 Note the asymmetry when a deadline *is* hit: re-running an `upsert` after the first run has finished is safe (it is idempotent); re-running a **`replace`** while the first is still mid-flight would empty the target under it. Check the instance's log before deciding — the message says so too.
 
+An instance that is **not answering at all** is a different message, and it names the instance rather than a database:
+
+```
+voltro: api import: the instance at api.example.com is not answering (ETIMEDOUT).
+  That address came from --api-url (or VOLTRO_API_URL) — it is the running instance, not the database.
+  Nothing was sent, so nothing was imported. …
+```
+
+Worth one line because the alternative was measured: a connect failure carries an address, a port and an errno, which is the same shape a database driver's carries — so without this the api host was reported as an unreachable *database*, attributed to `DB_URL`, a variable not in play on that run. Every word after the address was wrong, and the address being right is what made it convincing.
+
 **Import** (`POST /_voltro/admin/import`) applies a bundle **in the instance's own process** through its store — full app pipeline (validation, mixins, **field encryption**, hooks) AND automatic reactivity. Two transports, neither needs a server-readable path:
   - **upload** (default) — the CLI **packs the bundle and uploads the bytes**; the server unpacks to its own temp dir, imports in-process, cleans up. Buffered → small/moderate bundles.
   - **storage-pull** (`--bundle-key <key>`) — the CLI sends only `{ "bundleKey": "<key>" }`; the instance **streams that archive from its configured object storage** (S3 / Azure / MinIO / filesystem, resolved from the storage env — `STORAGE_PROVIDER`, `S3_*`, `AZURE_*`, …), no body buffering → arbitrarily large bundles.