@voltro/data-transfer 0.85.0 → 0.87.0

package/dist/nativeDump.js

@@ -0,0 +1,418 @@
+import { NativeToolError as e } from "./errors.js";
+import { Effect as t } from "effect";
+import { DATA_TRANSFERS_TABLE as n, REPLACE_IN_PROGRESS_TABLE as r } from "@voltro/database";
+import { randomUUID as i } from "node:crypto";
+import { copyFile as a, createReadStream as o, createWriteStream as s, existsSync as c, rename as l, statSync as u, unlinkSync as d } from "node:fs";
+import { basename as f, delimiter as p, join as m } from "node:path";
+import { spawn as h } from "node:child_process";
+//#region src/nativeDump.ts
+var g = (e, t) => {
+	let n = t === "dump" ? "mariadb-dump" : "mariadb", r = t === "dump" ? "mysqldump" : "mysql";
+	return e === "mariadb" ? _(n) ? { tool: n } : {
+		tool: r,
+		hint: `'${n}' is not on PATH, so this ran '${r}' instead. If that binary came from Oracle's MySQL client it queries information_schema.COLUMN_STATISTICS, which MariaDB does not have, and the run dies with error 1109 after the first table. Install the MariaDB client package (which ships '${n}') and re-run. Do NOT reach for --column-statistics=0: that flag does not exist on '${n}', so it fixes the wrong client and breaks the right one. Note: a MariaDB 12.x client requires TLS by default, so running '${n}' BY HAND against a server without it fails with "TLS/SSL error: SSL is required" (2026) and needs --skip-ssl. This command is not affected.`
+	} : { tool: r };
+}, _ = (e) => (process.env.PATH ?? "").split(p).filter((e) => e !== "").some((t) => c(m(t, e))), v = (e) => {
+	switch (e) {
+		case "postgres": return "db.dump";
+		case "mysql":
+		case "mariadb": return "db.sql";
+		case "sqlite":
+		case "turso": return "db.sqlite";
+		case "mssql": return "db.bacpac";
+		default: return "db.dump";
+	}
+}, y = (e) => e.filename ?? e.database ?? ((e.url ?? "").replace(/^file:/, "") || "app.sqlite"), b = (e, t = 3306) => {
+	if (e.host || e.database) return {
+		host: e.host ?? "localhost",
+		port: e.port ?? t,
+		username: e.username ?? "root",
+		password: e.password ?? "",
+		database: e.database ?? ""
+	};
+	let n = new URL(e.url ?? "");
+	return {
+		host: n.hostname || "localhost",
+		port: e.port ?? (n.port ? Number(n.port) : t),
+		username: decodeURIComponent(n.username) || "root",
+		password: decodeURIComponent(n.password) || "",
+		database: n.pathname.replace(/^\//, "") || ""
+	};
+}, x = (e) => `Server=${e.host},${e.port};Database=${e.database};User ID=${e.username};Password=${e.password};TrustServerCertificate=True`, S = (t, n, r) => {
+	switch (t) {
+		case "postgres": {
+			if (n.url) return {
+				kind: "spawn",
+				tool: "pg_dump",
+				args: [
+					"--format=custom",
+					"--no-owner",
+					"--no-privileges",
+					...w,
+					"--dbname",
+					n.url,
+					"--file",
+					r
+				],
+				env: {}
+			};
+			let e = b(n, 5432);
+			return {
+				kind: "spawn",
+				tool: "pg_dump",
+				args: [
+					"--format=custom",
+					"--no-owner",
+					"--no-privileges",
+					...w,
+					"-h",
+					e.host,
+					"-p",
+					String(e.port),
+					"-U",
+					e.username,
+					"-d",
+					e.database,
+					"--file",
+					r
+				],
+				env: { PGPASSWORD: e.password }
+			};
+		}
+		case "mysql":
+		case "mariadb": {
+			let e = b(n);
+			return {
+				kind: "spawn",
+				...g(t, "dump"),
+				args: [
+					"--single-transaction",
+					"--routines",
+					"--triggers",
+					"--no-tablespaces",
+					"--protocol=TCP",
+					...C.map((t) => `--ignore-table=${e.database}.${t}`),
+					"-h",
+					e.host,
+					"-P",
+					String(e.port),
+					"-u",
+					e.username,
+					e.database
+				],
+				env: { MYSQL_PWD: e.password },
+				stdoutFile: r
+			};
+		}
+		case "sqlite": return {
+			kind: "sqlite-backup",
+			from: y(n),
+			to: r
+		};
+		case "turso": return {
+			kind: "vacuum-into",
+			conn: n,
+			to: r
+		};
+		case "mssql": return {
+			kind: "spawn",
+			tool: "sqlpackage",
+			args: [
+				"/Action:Export",
+				`/SourceConnectionString:${x(b(n, 1433))}`,
+				`/TargetFile:${r}`
+			],
+			env: {}
+		};
+		default: throw new e({
+			tool: "backup",
+			reason: `no native backup for dialect '${t}'`
+		});
+	}
+}, C = [r, n], w = C.flatMap((e) => ["--exclude-table", e]), T = (e) => e === "postgres" || e === "mysql" || e === "mariadb" ? C : [], E = (t, n, r) => {
+	switch (t) {
+		case "postgres": {
+			if (n.url) return {
+				kind: "spawn",
+				tool: "pg_restore",
+				args: [
+					"--clean",
+					"--if-exists",
+					"--no-owner",
+					"--dbname",
+					n.url,
+					r
+				],
+				env: {}
+			};
+			let e = b(n, 5432);
+			return {
+				kind: "spawn",
+				tool: "pg_restore",
+				args: [
+					"--clean",
+					"--if-exists",
+					"--no-owner",
+					"-h",
+					e.host,
+					"-p",
+					String(e.port),
+					"-U",
+					e.username,
+					"-d",
+					e.database,
+					r
+				],
+				env: { PGPASSWORD: e.password }
+			};
+		}
+		case "mysql":
+		case "mariadb": {
+			let e = b(n);
+			return {
+				kind: "spawn",
+				...g(t, "client"),
+				args: [
+					"--protocol=TCP",
+					"-h",
+					e.host,
+					"-P",
+					String(e.port),
+					"-u",
+					e.username,
+					e.database
+				],
+				env: { MYSQL_PWD: e.password },
+				stdinFile: r
+			};
+		}
+		case "sqlite":
+		case "turso": return {
+			kind: "copy",
+			from: r,
+			to: y(n)
+		};
+		case "mssql": {
+			let e = b(n, 1433), t = A(e.database);
+			return {
+				kind: "mssql-replace",
+				load: {
+					kind: "spawn",
+					tool: "sqlpackage",
+					args: [
+						"/Action:Import",
+						`/TargetConnectionString:${x({
+							...e,
+							database: t
+						})}`,
+						`/SourceFile:${r}`
+					],
+					env: {}
+				},
+				server: {
+					host: e.host,
+					port: e.port,
+					username: e.username,
+					password: e.password,
+					database: "master"
+				},
+				live: e.database,
+				scratch: t,
+				carry: C
+			};
+		}
+		default: throw new e({
+			tool: "restore",
+			reason: `no native restore for dialect '${t}'`
+		});
+	}
+}, D = (e) => `[${e.replaceAll("]", "]]")}]`, O = (e) => `N'${e.replaceAll("'", "''")}'`, k = "__voltro_restore_", A = (e, t = i().slice(0, 8)) => `${e}${k}${t}`, j = (e) => e.replace(k, "__voltro_replaced_"), M = (e) => `IF DB_ID(${O(e)}) IS NOT NULL BEGIN ALTER DATABASE ${D(e)} SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE ${D(e)} END`, N = (e) => `DECLARE @leftover sysname, @drop nvarchar(max);
+DECLARE leftovers CURSOR LOCAL FAST_FORWARD FOR SELECT name FROM sys.databases WHERE name LIKE ${O(`${`${e}${k}`.replace(/[\\%_[]/g, (e) => `\\${e}`)}%`)} ESCAPE N'\\';
+OPEN leftovers; FETCH NEXT FROM leftovers INTO @leftover;
+WHILE @@FETCH_STATUS = 0 BEGIN
+  SET @drop = N'ALTER DATABASE ' + QUOTENAME(@leftover) + N' SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE ' + QUOTENAME(@leftover);
+  EXEC(@drop);
+  FETCH NEXT FROM leftovers INTO @leftover;
+END`, P = (e) => {
+	let t = D(e.live), n = D(e.scratch), r = j(e.scratch);
+	return {
+		prepare: [N(e.live)],
+		carry: e.carry.map((e) => {
+			let r = O(`${n}.dbo.${D(e)}`), i = O(`${t}.dbo.${D(e)}`);
+			return `IF OBJECT_ID(${r}) IS NOT NULL BEGIN
+  DELETE FROM ${n}.dbo.${D(e)};
+  IF OBJECT_ID(${i}) IS NOT NULL BEGIN
+    DECLARE @columns nvarchar(max) = (SELECT STRING_AGG(QUOTENAME(s.name), ',') FROM ${n}.sys.columns s
+      JOIN ${t}.sys.columns l ON l.name = s.name AND l.object_id = OBJECT_ID(${i})
+      WHERE s.object_id = OBJECT_ID(${r}) AND s.is_computed = 0);
+    EXEC(N'INSERT INTO ${n.replaceAll("'", "''")}.dbo.${D(e).replaceAll("'", "''")} (' + @columns + N') SELECT ' + @columns + N' FROM ${t.replaceAll("'", "''")}.dbo.${D(e).replaceAll("'", "''")}');
+  END
+END`;
+		}),
+		swap: [
+			`ALTER DATABASE ${t} SET SINGLE_USER WITH ROLLBACK IMMEDIATE`,
+			`ALTER DATABASE ${t} MODIFY NAME = ${D(r)}`,
+			`ALTER DATABASE ${n} MODIFY NAME = ${t}`,
+			M(r)
+		],
+		undoSwap: [`IF DB_ID(${O(e.live)}) IS NULL AND DB_ID(${O(r)}) IS NOT NULL ALTER DATABASE ${D(r)} MODIFY NAME = ${t}`, `IF DB_ID(${O(e.live)}) IS NOT NULL ALTER DATABASE ${t} SET MULTI_USER`],
+		cleanup: [M(e.scratch)]
+	};
+}, F = (e) => {
+	let t = [];
+	for (let n = e, r = 0; n != null && r < 4; r++) {
+		let e = n instanceof Error ? n.message : typeof n == "object" && "message" in n ? String(n.message) : String(n);
+		e && !t.includes(e) && t.push(e), n = typeof n == "object" && "cause" in n ? n.cause : void 0;
+	}
+	return t.join(": ");
+}, I = (n, r) => {
+	if (r === void 0) return t.fail(new e({
+		tool: "sqlpackage",
+		reason: "an mssql restore swaps databases and needs a SQL connection to the server; none was provided"
+	}));
+	let i = P(n), a = (i, a) => r(n.server, a).pipe(t.mapError((t) => new e({
+		tool: "sqlpackage",
+		reason: `${i}: ${F(t)}`
+	}))), o = a("dropping the scratch database", i.cleanup).pipe(t.ignore);
+	return t.gen(function* () {
+		yield* a(`preparing ${n.scratch}`, i.prepare), yield* L(n.load).pipe(t.tapError(() => o)), yield* a(`carrying ${n.carry.join(", ")} into the imported copy`, i.carry).pipe(t.tapError(() => o)), yield* a(`swapping ${n.scratch} in as ${n.live}`, i.swap).pipe(t.tapError(() => a("putting the original database back", i.undoSwap).pipe(t.ignore)));
+	});
+}, L = (n, r) => {
+	if (n.kind === "mssql-replace") return I(n, r);
+	if (n.kind === "vacuum-into") {
+		if (r === void 0) return t.fail(new e({
+			tool: "vacuum-into",
+			reason: "a VACUUM INTO backup needs a SQL connection to the database"
+		}));
+		let a = `${n.to}.backing-up-${i()}`;
+		return r(n.conn, [`VACUUM INTO '${a.replaceAll("'", "''")}'`]).pipe(t.flatMap(() => t.callback((e) => {
+			l(a, n.to, (n) => e(n ? t.fail(n) : t.void));
+		})), t.mapError((t) => {
+			try {
+				d(a);
+			} catch {}
+			return new e({
+				tool: "vacuum-into",
+				reason: `VACUUM INTO ${n.to}: ${t instanceof Error ? t.message : String(t)}`
+			});
+		}));
+	}
+	return n.kind === "sqlite-backup" ? t.tryPromise({
+		try: async () => {
+			let { backup: e, DatabaseSync: t } = await import("node:sqlite"), r = `${n.to}.backing-up-${i()}`, a = new t(n.from, { readOnly: !0 });
+			try {
+				await e(a, r);
+			} catch (e) {
+				try {
+					d(r);
+				} catch {}
+				throw e;
+			} finally {
+				a.close();
+			}
+			await new Promise((e, t) => {
+				l(r, n.to, (n) => {
+					n ? t(n) : e();
+				});
+			});
+		},
+		catch: (t) => new e({
+			tool: "sqlite-backup",
+			reason: `backup ${n.from} → ${n.to}: ${t instanceof Error ? t.message : String(t)}`
+		})
+	}) : n.kind === "copy" ? t.callback((r) => {
+		let o = `${n.to}.restoring-${i()}`, s = (n) => {
+			try {
+				d(o);
+			} catch {}
+			r(t.fail(new e({
+				tool: "copy",
+				reason: n
+			})));
+		};
+		a(n.from, o, (e) => {
+			if (e) s(`copy ${n.from} → ${n.to}: ${e.message}`);
+			else {
+				for (let e of [
+					`${n.to}-wal`,
+					`${n.to}-shm`,
+					`${n.to}-journal`,
+					`${n.to}-log`
+				]) try {
+					d(e);
+				} catch {}
+				l(o, n.to, (e) => {
+					e ? s(`copy ${n.from} → ${n.to}: ${e.message}`) : r(t.void);
+				});
+			}
+		});
+	}) : t.callback((r) => {
+		let i = h(n.tool, [...n.args], {
+			env: {
+				...process.env,
+				...n.env
+			},
+			stdio: [
+				"pipe",
+				n.stdoutFile ? "pipe" : "inherit",
+				"pipe"
+			]
+		}), a = "";
+		i.stderr?.on("data", (e) => {
+			a += String(e);
+		});
+		let c = !1, l = (e) => {
+			c || (c = !0, r(e));
+		}, u, p = (e) => {
+			u ??= e;
+		};
+		if (n.stdoutFile && i.stdout) {
+			let e = s(n.stdoutFile);
+			e.on("error", (e) => p(`writing ${f(n.stdoutFile)}: ${e.message}`)), i.stdout.on("error", (e) => p(`reading the tool's output: ${e.message}`)), i.stdout.pipe(e);
+		}
+		let m = 0;
+		if (n.stdinFile && i.stdin) {
+			let e = o(n.stdinFile);
+			e.on("data", (e) => {
+				m += e.length;
+			}), e.on("error", (e) => {
+				p(`reading ${f(n.stdinFile)}: ${e.message}`), i.stdin?.end();
+			}), i.stdin.on("error", (e) => {
+				e.code !== "EPIPE" && p(`feeding ${f(n.stdinFile)} to ${n.tool}: ${e.message}`);
+			}), e.pipe(i.stdin);
+		}
+		let g = () => {
+			if (n.stdoutFile !== void 0) try {
+				d(n.stdoutFile);
+			} catch {}
+		};
+		i.on("error", (r) => {
+			g(), l(t.fail(new e({
+				tool: n.tool,
+				reason: `failed to launch (is '${n.tool}' installed + on PATH?): ${r.message}`,
+				...n.hint === void 0 ? {} : { hint: n.hint }
+			})));
+		}), i.on("close", (r) => {
+			if (r === 0 && u === void 0) {
+				l(t.void);
+				return;
+			}
+			g();
+			let i = n.stdinFile === void 0 ? "" : ` — ${m} of ${R(n.stdinFile)} byte(s) of ${f(n.stdinFile)} had been fed to it`;
+			l(t.fail(new e({
+				tool: n.tool,
+				reason: (r === 0 ? `exited cleanly, but ${u}` : `exited with code ${r}${u === void 0 ? "" : ` (${u})`}`) + i + (n.stdoutFile === void 0 ? "" : ` — the partial ${f(n.stdoutFile)} was removed, so it cannot be mistaken for a backup`),
+				stderr: a.trim() === "" ? `(${n.tool} printed nothing to stderr)` : a.slice(-2e3),
+				...n.hint === void 0 ? {} : { hint: n.hint }
+			})));
+		});
+	});
+}, R = (e) => {
+	try {
+		return String(u(e).size);
+	} catch {
+		return "?";
+	}
+};
+//#endregion
+export { C as EXCLUDED_FROM_DUMP, v as backupArtifactName, S as backupCommand, T as dumpExcludedTables, P as mssqlReplaceStatements, A as mssqlScratchName, E as restoreCommand, L as runNativeStep };

package/dist/ndjson.js

@@ -0,0 +1,13 @@
+import { CodecError as e } from "./errors.js";
+import { decodeRow as t, encodeRow as n } from "./typedCodec.js";
+import { Effect as r, Stream as i } from "effect";
+//#region src/ndjson.ts
+var a = new TextEncoder(), o = (e, t) => e.pipe(i.map((e) => a.encode(`${JSON.stringify(n(e, t))}\n`))), s = (n, a, o) => n.pipe(i.decodeText(), i.splitLines, i.filter((e) => e.trim().length > 0), i.mapEffect((n) => r.try({
+	try: () => t(JSON.parse(n), o),
+	catch: (t) => new e({
+		table: a,
+		reason: String(t?.message ?? t)
+	})
+})));
+//#endregion
+export { s as ndjsonToRows, o as rowsToNdjson };

package/dist/physicalRequest.js

@@ -0,0 +1,10 @@
+import { Effect as e } from "effect";
+//#region src/physicalRequest.ts
+var t = (t, n) => e.callback((r) => {
+	let i = new AbortController(), a = Promise.resolve().then(() => t(i.signal));
+	return a.then((t) => r(e.succeed(t)), (t) => r(e.fail(n(t)))), e.sync(() => {
+		i.abort();
+	}).pipe(e.andThen(e.promise(() => a.then(() => void 0, () => void 0))));
+});
+//#endregion
+export { t as physicalRequest };

package/dist/profile.js

@@ -0,0 +1,4 @@
+//#region src/profile.ts
+var e = (e) => e;
+//#endregion
+export { e as defineDataProfile };

package/dist/progress.js

@@ -0,0 +1,17 @@
+import { Effect as e, Metric as t } from "effect";
+//#region src/progress.ts
+var n = t.counter("voltro_data_transfer_rows", { description: "Rows exported/imported by @voltro/data-transfer, tagged by phase + table." }), r = Array.from({ length: 16 }, (e, t) => .01 * 2 ** t), i = t.histogram("voltro_data_transfer_table_seconds", {
+	boundaries: r,
+	description: "Per-table export/import duration in seconds, tagged by phase."
+}), a = (e, t) => {
+	if (e) try {
+		e(t);
+	} catch {}
+}, o = (r, a, o, s, c, l) => e.Do.pipe(e.bind("start", () => e.clockWith((e) => e.currentTimeMillis)), e.bind("result", () => l), e.tap(({ start: o, result: s }) => e.clockWith((e) => e.currentTimeMillis).pipe(e.flatMap((l) => e.andThen(i.pipe(t.withAttributes({ phase: r }), t.update((l - o) / 1e3)), n.pipe(t.withAttributes({ phase: r }), t.withAttributes({ table: a }), t.update(c(s))))))), e.map(({ result: e }) => e), e.withSpan(`data-transfer.${r}.table`, { attributes: {
+	table: a,
+	index: o,
+	tableCount: s,
+	phase: r
+} }));
+//#endregion
+export { a as reportProgress, o as withTableSpan };

package/dist/readme.js

@@ -0,0 +1,43 @@
+//#region src/readme.ts
+var e = (e) => e.kind === "tenant" ? `tenant \`${e.tenantId}\`` : e.kind === "tables" ? `tables \`${(e.tables ?? []).join(", ")}\`` : "all tables", t = (t, n) => {
+	let r = t.tables.reduce((e, t) => e + t.rowCount, 0), i = t.masking ? `✅ **Masked at the source** — ${t.masking.transformed.length} column(s) transformed${t.masking.policyId ? ` (policy \`${t.masking.policyId}\`)` : ""}. Personal data was replaced with realistic, referentially-consistent fakes before any byte was written.` : "⚠️ **NOT masked — this bundle contains REAL data (PII included).** Treat it as production data: do not copy it into a lower environment or share it without review. To produce a safe copy, re-export under a masking profile (`--profile`).", a = t.masking && t.masking.transformed.length > 0 ? `\n\nMasked columns: ${t.masking.transformed.map((e) => `\`${e}\``).join(", ")}.` : "", o = t.assets.count > 0 ? `${t.assets.count} object(s), ${t.assets.totalBytes} bytes` : "none", s = t.tables.map((e) => `| \`${e.name}\` | ${e.rowCount} |`).join("\n");
+	return `# Voltro data export
+
+The machine-readable manifest is \`manifest.json\`; this file is a human summary.
+
+| | |
+|---|---|
+| **Generated** | ${t.createdAt} |
+| **Exported from** | \`${n.hostname}\` |
+| **Source dialect** | \`${t.source.dialect}\` |
+| **Format version** | ${t.formatVersion} |
+| **Consistency** | ${t.consistency} |
+| **Compression** | ${t.compression} |
+| **Scope** | ${e(t.scope)} |
+| **Tables** | ${t.tables.length} |
+| **Rows (total)** | ${r} |
+| **Assets** | ${o} |
+
+## Data sensitivity
+
+${i}${a}
+
+## Tables
+
+| Table | Rows |
+|---|---|
+${s}
+
+## Restore
+
+\`\`\`bash
+# into a stopped/replica DB directly:
+voltro data import <this-directory>
+
+# or into a running instance (needs the data-transfer secret):
+voltro data import <this-directory> --target api --api-url <url> --token <secret>
+\`\`\`
+`;
+};
+//#endregion
+export { t as buildReadme };

package/dist/replacePreflight.js

@@ -0,0 +1,23 @@
+//#region src/replacePreflight.ts
+var e = (e, t) => {
+	let n = new Set(t), r = [];
+	for (let t of e.tables) if (!n.has(t.name)) for (let e of t.columns) {
+		let i = e.references?.table;
+		i !== void 0 && n.has(i) && r.push({
+			from: t.name,
+			column: e.name,
+			to: i
+		});
+	}
+	return r;
+}, t = (e) => {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e) t.set(n.from, [...t.get(n.from) ?? [], n]);
+	let n = [...t.entries()].map(([e, t]) => {
+		let n = t[0].rowCount, r = t.map((e) => `${e.column} → ${e.to}`).join(", ");
+		return `  ${e} (${n} row${n === 1 ? "" : "s"}): ${r}`;
+	});
+	return `replace cannot empty this target: ${t.size} table(s) OUTSIDE the bundle hold rows that reference tables INSIDE it. Emptying the bundle's tables would leave those rows pointing at nothing, and the bundle cannot restore them.\n${n.join("\n")}\nNothing has been deleted. Either re-export with a scope that includes those tables, or use --mode upsert if those rows are meant to survive.`;
+};
+//#endregion
+export { t as outsideReferenceRefusal, e as outsideReferencesInto };

package/dist/rollbackCapture.js

@@ -0,0 +1,36 @@
+import { BundleError as e } from "./errors.js";
+import { runExport as t } from "./exporter.js";
+import { Effect as n } from "effect";
+//#region src/rollbackCapture.ts
+var r = (r) => n.gen(function* () {
+	if (r.mode !== "replace" || r.dir === void 0 || r.tables.length === 0) return;
+	if (r.snapshot === void 0) return yield* n.fail(new e({
+		reason: "rollback capture needs the TARGET's schema, and this run has none.\n  `--mode replace` empties the target first, so a run without a capture can leave it\n  emptied and unfilled if the process does not survive to roll back. Pass the target\n  snapshot, or `--no-rollback` to accept that risk deliberately.",
+		path: r.dir
+	}));
+	let i = {
+		...r.snapshot,
+		tables: r.snapshot.tables.filter((e) => r.tables.includes(e.name))
+	};
+	if (i.tables.length === 0) return;
+	r.onWarn?.(`capturing the target's current rows before emptying it → ${r.dir}\n  This is what a failed replace is restored FROM. It is written before the first delete,
+  so it survives a run whose process does not.`);
+	let a = yield* t({
+		store: r.store,
+		snapshot: i,
+		dialect: r.dialect ?? "unknown",
+		outDir: r.dir,
+		scope: { kind: "all" },
+		compression: "none"
+	}).pipe(n.mapError((t) => new e({
+		reason: `rollback capture failed, so the import did not start and the target is untouched: ${t.reason ?? String(t)}\n  Fix the capture, or re-run with \`--no-rollback\` to proceed without one.`,
+		path: r.dir
+	})));
+	return {
+		dir: r.dir,
+		rows: a.tables.reduce((e, t) => e + t.rowCount, 0),
+		tables: a.tables.length
+	};
+}), i = (e) => `rollback capture: ${e.rows} row(s) across ${e.tables} table(s) → ${e.dir}\n  If this run does not finish, restore with:  voltro data import ${e.dir} --mode replace`;
+//#endregion
+export { r as captureRollback, i as rollbackNotice };

package/dist/rowFailureReason.js

@@ -0,0 +1,36 @@
+import { classifyConstraintViolation as e, extractDbCause as t } from "@voltro/database";
+//#region src/rowFailureReason.ts
+var n = (e) => {
+	let t = e.constraint ?? e.column, n = t === void 0 ? "" : ` ${t}`;
+	switch (e.kind) {
+		case "foreignKey": return `foreign key${n}: the referenced row does not exist (import it first, or check the bundle's table order)`;
+		case "foreignKeyInUse": return `foreign key${n}: the row is still referenced by other rows`;
+		case "unique": return `unique constraint${n}: a row with this value already exists`;
+		case "notNull": return `not-null constraint${n}: the column requires a value`;
+		case "check": return `check constraint${n}: the row does not satisfy it`;
+	}
+}, r = (e) => {
+	let t = [e.dbCode, e.dbErrno ?? e.dbNumber].filter((e) => e !== void 0).map(String);
+	return t.length > 0 ? t.join("/") : void 0;
+}, i = "Failed to execute statement", a = (e) => {
+	let t = (e.split("\n", 1)[0] ?? "").trim();
+	return t === `SqlError: ${i}` ? i : t;
+}, o = (o) => {
+	let s = String(o?.stack ?? o), c = s.length <= 1200 ? s : `${s.slice(0, 1200)}…`, l = (e, t) => ({
+		reason: e.length <= 300 ? e : `${e.slice(0, 300)}…`,
+		unclassified: t,
+		raw: c
+	}), u = t(o), d = e(u), f = r(u), p = f === void 0 ? "" : ` [${f}]`;
+	if (d !== void 0) return l(`${n(d)}${p}`, !1);
+	let m = typeof u.dbMessage == "string" ? u.dbMessage : void 0, h = o?.message, g = a(typeof h == "string" && h.length > 0 ? h : String(o)), _ = m !== void 0 && m !== g && !m.startsWith("SqlError:") ? m : g, v = typeof u.dbCauseChain == "string" ? u.dbCauseChain : void 0, y = v !== void 0 && /[←‖]/.test(v) ? ` (via ${v})` : "";
+	return l(_ === i || _.length === 0 ? `the database refused the write and the driver gave no detail${p}${y}` : `${_}${p}`, _ === i || _.length === 0);
+}, s = (e) => o(e).reason, c = (n) => {
+	let i = t(n), a = e(i);
+	if (a?.kind === "foreignKeyInUse") {
+		let e = a.constraint ?? a.column, t = e === void 0 ? "" : ` ${e}`, n = r(i);
+		return `foreign key${t}: rows elsewhere still reference this table${n === void 0 ? "" : ` [${n}]`}`;
+	}
+	return s(n);
+};
+//#endregion
+export { o as rowFailureDiagnosis, s as rowFailureReason, c as tableFailureReason };

package/dist/schemaDrift.js

@@ -0,0 +1,40 @@
+import { fingerprintSchema as e } from "@voltro/database/sql";
+//#region src/schemaDrift.ts
+var t = /__dropped_\d+$/, n = (e, n) => {
+	let r = [], i = /* @__PURE__ */ new Map();
+	for (let e of n.tables) {
+		let t = e.name;
+		i.has(t) || i.set(t, e);
+	}
+	for (let n of [...e.tables].sort((e, t) => e.name.localeCompare(t.name))) {
+		let e = i.get(n.name);
+		if (e === void 0) {
+			r.push(`table '${n.name}' is in the bundle but MISSING from the target — its rows have nowhere to go`);
+			continue;
+		}
+		let a = new Map(e.columns.map((e) => [e.name, e])), o = new Map(n.columns.map((e) => [e.name, e]));
+		for (let [e, i] of o) {
+			let o = a.get(e);
+			o === void 0 ? r.push(t.test(e) ? `${n.name}.${e}: a soft-dropped column, present only in the SOURCE — reclaim it there (voltro db gc-snapshots --before <date>) or re-export without it; the target is not missing anything` : `${n.name}.${e}: in the bundle, MISSING from the target — the value has nowhere to go`) : o.type !== i.type && r.push(`${n.name}.${e}: type '${i.type}' (bundle) vs '${o.type}' (target)`);
+		}
+		for (let [e, t] of a) o.has(e) || !t.nullable && !t.hasDefault && r.push(`${n.name}.${e}: the target requires it (NOT NULL, no default) and the bundle carries no value — every row of this table would fail`);
+	}
+	return r.length > 30 ? [...r.slice(0, 30), `… and ${r.length - 30} more difference(s)`] : r;
+}, r = (t, r, i) => {
+	let a = e(r);
+	if (a === t || i === void 0) return {
+		drifted: !1,
+		bundleFingerprint: t,
+		targetFingerprint: a,
+		diff: []
+	};
+	let o = n(i, r);
+	return {
+		drifted: o.length > 0,
+		bundleFingerprint: t,
+		targetFingerprint: a,
+		diff: o
+	};
+};
+//#endregion
+export { r as checkSchemaDrift, n as diffSnapshots };