@voltro/database 0.85.0 → 0.86.0

package/dist/migrations/planner.js

@@ -0,0 +1,775 @@
+import { isSqliteFamily as e } from "../dialect.js";
+import { isFrameworkOwnedLiveTable as t, isSoftDropSnapshotName as n, softDropSnapshotStamp as r } from "./frameworkLiveTables.js";
+import { indexStorageShape as i } from "../indexStorage.js";
+import { findCyclicFkBackEdges as a, fkEdgeKey as o } from "./fkCycles.js";
+import { normalizeIndexPredicate as s } from "./indexPredicate.js";
+import { canonicalIdColumn as c, comparableDefault as l, hasComparableType as u, isPgSequenceDefault as d, isSolePrimaryKeyId as f, isTextStorage as p, normRef as m, normalizeDefault as h, renderedTextWidth as g, resolvedIdStorage as _, sameIdSpelling as v, sameSpatial as y } from "./columnEquivalence.js";
+import { fingerprintSchema as b } from "./fingerprint.js";
+import { charsetColumnsOf as x, columnTakesCharset as S } from "./storeCharset.js";
+import { declaredSnapshot as C } from "./declaredSchema.js";
+//#region src/migrations/planner.ts
+var w = {
+	postgres: !0,
+	mysql: !0,
+	mariadb: !0,
+	mssql: !0,
+	sqlite: !0
+}, T = {
+	postgres: !0,
+	mysql: !1,
+	mariadb: !1,
+	mssql: !0,
+	sqlite: !0
+}, E = (e) => {
+	switch (e) {
+		case "add-column":
+		case "drop-column":
+		case "rename-column":
+		case "alter-column-nullability":
+		case "alter-column-type":
+		case "add-foreign-key":
+		case "add-unique":
+		case "add-unique-composite":
+		case "add-check":
+		case "convert-charset": return T;
+		default: return w;
+	}
+}, ee = (e, t) => {
+	let n = new Map(t.tables.map((e) => [e.name, e]));
+	return new Map(e.map((e) => [e.tableName, {
+		table: e,
+		snapshot: n.get(e.tableName),
+		columnDefs: e.fields
+	}]));
+}, D = (e) => e.type === "id" && e.idScheme?.kind === "numeric", O = (e, t) => {
+	let n = h(e), r = h(t);
+	if (n === r) return !0;
+	let i = d;
+	return e.type === "id" && t.type === "id" && (D(e) && n === null && i(t) || D(t) && r === null && i(e)) ? !0 : l(e) === l(t);
+}, k = (e, t) => {
+	let n = e && e.length > 0 ? e : void 0, r = t && t.length > 0 ? t : void 0;
+	if (!n && !r) return !0;
+	if (!n || !r || n.length !== r.length) return !1;
+	if (n.length >= 32 && j(n) && j(r)) {
+		let e = /* @__PURE__ */ new Map();
+		for (let t of n) e.set(t, (e.get(t) ?? 0) + 1);
+		for (let t of r) {
+			let n = e.get(t);
+			if (n === void 0) return !1;
+			n === 1 ? e.delete(t) : e.set(t, n - 1);
+		}
+		return e.size === 0;
+	}
+	let i = [...n].sort(), a = [...r].sort();
+	return i.every((e, t) => e === a[t]);
+}, A = (t, n, r, i) => r === void 0 || e(r) ? !0 : t.type !== "text" || !p(n) || g(t, r, i) === n.maxLength, j = (e) => {
+	for (let t of [
+		"includes",
+		"every",
+		Symbol.iterator
+	]) {
+		let n = Object.getOwnPropertyDescriptor(e, t);
+		if (n !== void 0 && !("value" in n)) return !1;
+	}
+	if (Object.getPrototypeOf(e) !== Array.prototype || e.includes !== Array.prototype.includes || e.every !== Array.prototype.every || e[Symbol.iterator] !== Array.prototype[Symbol.iterator]) return !1;
+	for (let t = 0; t < e.length; t++) {
+		let n = Object.getOwnPropertyDescriptor(e, t);
+		if (n === void 0 || !("value" in n) || typeof n.value != "string") return !1;
+	}
+	return !0;
+}, M = (e, t) => {
+	if (e.length !== t.length) return !1;
+	let n = e.length >= 32 && j(e) && j(t) ? new Set(t) : void 0;
+	return e.every((e) => n === void 0 ? t.includes(e) : n.has(e));
+}, N = (e) => {
+	for (let t of ["find", Symbol.iterator]) {
+		let n = Object.getOwnPropertyDescriptor(e, t);
+		if (n !== void 0 && !("value" in n)) return;
+	}
+	if (e.length < 32 || Object.getPrototypeOf(e) !== Array.prototype || e.find !== Array.prototype.find || e[Symbol.iterator] !== Array.prototype[Symbol.iterator]) return;
+	let t = /* @__PURE__ */ new Map();
+	for (let n = 0; n < e.length; n++) {
+		let r = Object.getOwnPropertyDescriptor(e, n);
+		if (r === void 0 || !("value" in r) || typeof r.value != "object" || r.value === null || Object.values(Object.getOwnPropertyDescriptors(r.value)).some((e) => !("value" in e))) return;
+		let i = Object.getOwnPropertyDescriptor(r.value, "name");
+		if (i === void 0 || !("value" in i) || typeof i.value != "string") return;
+		t.has(i.value) || t.set(i.value, r.value);
+	}
+	return t;
+}, P = (e, t, n, r, i = !1) => (!u(e) || e.type === t.type || v(e, t, i)) && c(e, i).idStorage === c(t, !1).idStorage && e.nullable === t.nullable && (e.unique === t.unique || v(e, t, i)) && e.jsonValidation === t.jsonValidation && (!u(e) || e.sqliteDecimalEncoding === t.sqliteDecimalEncoding) && (t.enumValues === void 0 || e.enumValues === void 0 || M(e.enumValues, t.enumValues)) && (t.precision === void 0 || e.precision === t.precision && (e.scale ?? 0) === (t.scale ?? 0)) && y(e.spatial, t.spatial) && (e.storageType !== void 0 || t.storageType !== void 0 || t.arrayElement === void 0 || e.arrayElement === void 0 || e.arrayElement === t.arrayElement) && (t.vectorDim === void 0 || e.vectorDim === t.vectorDim) && (e.vectorPrecision ?? "float32") === (t.vectorPrecision ?? "float32") && O(e, t) && A(e, t, n, r) && (e.type !== "reference" || (e.referenceStorage ?? "text") === (t.referenceStorage ?? "text")) && JSON.stringify(m(e.references)) === JSON.stringify(m(t.references)) && k(e.oneOf, t.oneOf), F = (e, t) => t.oneOf && t.oneOf.length > 0 ? L({
+	kind: "add-check",
+	table: e,
+	column: t.name,
+	values: t.oneOf
+}, "safe", `enum-membership CHECK on ${e}.${t.name}`) : void 0, I = (e, t) => e.unique === t.unique && e.valid !== !1 && t.valid !== !1 && s(e.where) === s(t.where) && JSON.stringify(i(e.kind, e.kindOptions)) === JSON.stringify(i(t.kind, t.kindOptions)) && (e.expression ?? !1) === (t.expression ?? !1) && (e.expression === !0 && t.expression === !0 || e.columns.length === t.columns.length && e.columns.every((e, n) => e === t.columns[n])), te = (e, t, n) => {
+	let r = new Map(t.columns.map((e) => [e.name, e])), i = new Map(e.columns.map((e) => [e.name, e])), a = [], o = [], s = [], c = new Set(e.indexes.flatMap((e) => e.columns));
+	for (let t of e.columns) {
+		let i = r.get(t.name);
+		i ? P(t, i, n, c.has(t.name) || t.unique, f(e, t)) || s.push({
+			declared: t,
+			live: i
+		}) : a.push(t);
+	}
+	for (let e of t.columns) i.has(e.name) || o.push(e);
+	return {
+		added: a,
+		removed: o,
+		changed: s
+	};
+}, ne = (e, t, n, r) => {
+	let i = (e) => n === "turso" || n === "sqlite" ? e.toLowerCase() : e, a = r.size > 0 ? /* @__PURE__ */ new Map() : void 0;
+	if (a !== void 0) for (let e of t.indexes) e.unique && !e.expression && e.where === void 0 && e.columns.some((e) => r.has(e)) && a.set(e, {
+		...e,
+		columns: e.columns.map((e) => r.get(e) ?? e)
+	});
+	let o = new Map(t.indexes.map((e) => [i(e.name), a?.get(e) ?? e])), s = new Map(e.indexes.map((e) => [i(e.name), e])), c = [], l = [];
+	for (let t of e.indexes) {
+		let e = o.get(i(t.name));
+		(!e || !I(t, e)) && c.push(t);
+	}
+	for (let e of t.indexes) {
+		let t = s.get(i(e.name));
+		(!t || !I(t, a?.get(e) ?? e)) && l.push(e);
+	}
+	return {
+		added: c,
+		removed: l
+	};
+}, L = (e, t, n, r) => ({
+	op: e,
+	classification: t,
+	atomicByDialect: E(e.kind),
+	...n ? { reason: n } : {},
+	...r ? { blocked: r } : {}
+}), R = (e, t, n, r) => {
+	let i = {
+		kind: "add-column",
+		table: e,
+		column: t
+	};
+	return t.nullable ? L(i, "safe", "nullable column add — no backfill needed") : D(t) && (r === "postgres" || r === "mysql" || r === "mariadb") ? L(i, "needs-default", "numeric id — the auto-increment numbers every existing row") : t.hasDefault && t.defaultValue !== void 0 ? L(i, "needs-default", "NOT NULL with literal default — DDL DEFAULT will populate existing rows") : n?.backfill ? L(i, "needs-backfill", `backfill declared (kind=${n.backfill.kind}) — applier will run 3-step add/update/set-not-null`) : L(i, "needs-backfill", "NOT NULL column on a table whose row count is unknown", { fix: `declare \`${t.name}: <type>().backfill(sql\`...\`)\` OR \`.default(value)\` so existing rows survive the migration` });
+}, z = (e, t, n) => {
+	let r = {
+		kind: "drop-column",
+		table: e,
+		column: t.name
+	};
+	return n?.dropped ? L(r, "lossy", `column dropped via \`${t.name}: dropped()\` marker — intentional`) : L(r, "lossy", "column missing from declared schema", { fix: `if intentional, add \`${t.name}: dropped()\` to the schema. If a typo, restore the field` });
+}, B = (e, t, n, r, i) => L({
+	kind: "create-table",
+	table: e,
+	columns: t,
+	indexes: n,
+	...r && r.length > 0 ? { primaryKey: r } : {}
+}, "safe", i ?? "new table — no data to preserve"), V = (e) => L({
+	kind: "drop-table",
+	table: e
+}, "lossy", "table missing from declared schema", { fix: "if intentional, set VOLTRO_DESTRUCTIVE_OK=1 OR add a file-based migration. If a typo, restore the table declaration" }), H = 5e4, re = (e, t, n, r) => {
+	let i = (n ?? 0) >= r, a;
+	return a = !t.unique || t.where !== void 0 ? {
+		kind: "add-index",
+		table: e,
+		index: t
+	} : t.columns.length === 1 ? {
+		kind: "add-unique",
+		table: e,
+		column: t.columns[0]
+	} : {
+		kind: "add-unique-composite",
+		table: e,
+		name: t.name,
+		fields: t.columns
+	}, i ? L(a, "online-required", `online build on ${n} rows — CONCURRENTLY / INPLACE / WITH(ONLINE=ON) depending on dialect`) : L(a, "safe", t.where === void 0 ? t.unique ? t.columns.length === 1 ? "add unique constraint" : "add composite UNIQUE constraint" : `add ${t.kind === void 0 || t.kind === "btree" ? "B-tree" : t.kind.toUpperCase()} index` : `add ${t.unique ? "unique " : ""}partial index`);
+}, ie = (e, t) => {
+	let n = t.name === `${e}_pkey`;
+	return t.unique && t.where === void 0 && (t.columns.length > 1 || n) ? L({
+		kind: "drop-unique-composite",
+		table: e,
+		name: t.name
+	}, "safe", "drop composite UNIQUE constraint (no data loss — constraint is derived metadata)") : L({
+		kind: "drop-index",
+		table: e,
+		index: t.name
+	}, "safe", "drop index (no data loss — index is derived data)");
+}, U = (t, n) => {
+	let r = t.type;
+	if (r === "id") return _(t) === "numeric" ? "bigint" : "text";
+	if (r === "array") return n === void 0 || n === "postgres" ? "array" : n === "mysql" || n === "mariadb" ? "json" : "text";
+	if (r === "enum") return n === "mssql" || e(n ?? "postgres") ? "text" : "enum";
+	if (r === "reference") return t.referenceStorage === "numeric" ? "bigint" : "text";
+	switch (n) {
+		case "sqlite":
+		case "turso": return r === "timestamp" || r === "date" || r === "json" ? "text" : r === "boolean" || r === "bigint" ? "integer" : r;
+		case "mssql": return r === "json" ? "text" : r;
+		default: return r;
+	}
+}, W = (e, t, n) => {
+	let r = `acknowledge it on the column: \`.narrowedFrom('${e}')\``;
+	return n === "postgres" ? `${r} — add \`{ using: '${t.name}::${t.type}' }\` when the cast is not implicit, or use a file-based migration` : `${r} — ${n === void 0 ? "this dialect" : n} converts in place (\`using\` is postgres-only and is ignored here), so verify the conversion is value-preserving for your data, or use a file-based migration`;
+}, G = (t, n, r, i, a, o) => {
+	let s = [], c = u(n) && (n.sqliteDecimalEncoding !== void 0 || r.sqliteDecimalEncoding !== void 0) && (n.sqliteDecimalEncoding !== r.sqliteDecimalEncoding || n.precision !== r.precision || (n.scale ?? 0) !== (r.scale ?? 0) || n.type !== r.type);
+	if (c && s.push(L({
+		kind: "alter-column-type",
+		table: t,
+		column: n.name,
+		from: r.type,
+		to: n.type
+	}, "multi-step", `physical decimal representation changes on ${t}.${n.name}; encoded keys require explicit data conversion, not a SQL type cast`, { fix: "Use a verified data migration that converts every value and preserves precision, defaults and constraints. Previously rounded NUMERIC values cannot recover their original digits." })), n.nullable !== r.nullable) {
+		let e = {
+			kind: "alter-column-nullability",
+			table: t,
+			column: n.name,
+			toNullable: n.nullable
+		};
+		s.push(n.nullable ? L(e, "safe", `loosen ${t}.${n.name} to nullable`) : L(e, "needs-backfill", `tighten ${t}.${n.name} to NOT NULL — existing rows must already be non-null`));
+	}
+	if (n.unique !== r.unique) {
+		if (n.unique) {
+			let e = {
+				kind: "add-unique",
+				table: t,
+				column: n.name
+			}, r = (a ?? 0) >= o;
+			s.push(r ? L(e, "online-required", `online unique build on ${a} rows — CONCURRENTLY / INPLACE / WITH(ONLINE=ON) depending on dialect`) : L(e, "safe", `add unique constraint on ${t}.${n.name} — existing rows must already be distinct (else the DB rejects at migrate)`));
+		} else s.push(L({
+			kind: "drop-unique",
+			table: t,
+			column: n.name
+		}, "safe", `drop unique constraint on ${t}.${n.name} — constraint is derived metadata, no data loss`));
+	}
+	if (!c && u(n) && U(n, i) !== U(r, i)) {
+		let e = n.narrowedFrom;
+		if (r.type === "integer" && n.type === "bigint" && e === void 0) s.push(L({
+			kind: "alter-column-type",
+			table: t,
+			column: n.name,
+			from: r.type,
+			to: n.type
+		}, "safe", `integer range widens to bigint on ${t}.${n.name} — every stored integer remains representable`));
+		else if (e && e.from === r.type) {
+			let i = {
+				kind: "alter-column-type",
+				table: t,
+				column: n.name,
+				from: r.type,
+				to: n.type,
+				...e.using === void 0 ? {} : { using: e.using }
+			};
+			s.push(L(i, "needs-backfill", `type change ${r.type} → ${n.type} on ${t}.${n.name} — narrowedFrom('${e.from}') declared` + (e.using ? ` with USING ${e.using}` : " (implicit cast)")));
+		} else {
+			let e = {
+				kind: "alter-column-type",
+				table: t,
+				column: n.name,
+				from: r.type,
+				to: n.type
+			};
+			s.push(L(e, "lossy", `type change ${r.type} → ${n.type} on ${t}.${n.name} may not be value-preserving`, { fix: W(r.type, n, i) }));
+		}
+	}
+	if (n.type === "text" && p(r) && !e(i ?? "postgres") && n.maxLength !== r.maxLength) {
+		let e = n.maxLength === void 0 || r.maxLength !== void 0 && n.maxLength > r.maxLength, i = r.maxLength === void 0 ? "unbounded" : `varchar(${r.maxLength})`, a = n.maxLength === void 0 ? "unbounded" : `varchar(${n.maxLength})`;
+		s.push(L({
+			kind: "alter-column-type",
+			table: t,
+			column: n.name,
+			from: "text",
+			to: "text"
+		}, e ? "safe" : "needs-backfill", e ? `text length ${i} → ${a} on ${t}.${n.name} — widening, no data can be lost` : `text length ${i} → ${a} on ${t}.${n.name} — NARROWING; the ALTER fails if any existing value is longer than ${String(n.maxLength)}. Check first: SELECT COUNT(*) FROM ${t} WHERE LENGTH(${n.name}) > ${String(n.maxLength)}`));
+	}
+	if (n.type === "enum" && r.type === "enum" && r.enumValues !== void 0 && n.enumValues !== void 0) {
+		let e = new Set(r.enumValues);
+		new Set(n.enumValues);
+		for (let r of n.enumValues) e.has(r) || s.push(L({
+			kind: "add-enum-value",
+			table: t,
+			column: n.name,
+			value: r,
+			...n.enumName === void 0 ? {} : { enumName: n.enumName }
+		}, "safe", `add '${r}' to the enum on ${t}.${n.name} — existing rows are untouched, and the label is what the declaration already promises`));
+	}
+	if (!y(n.spatial, r.spatial)) {
+		let e = n.spatial, i = r.spatial, a = (e) => e === void 0 ? "plain text" : `${e.kind}(${e.geomKind},${String(e.srid)})`, o = e !== void 0 && i !== void 0 && e.kind === i.kind && e.geomKind.toUpperCase() === i.geomKind.toUpperCase() && e.srid !== i.srid, c = e === void 0 ? void 0 : e.kind === "geography" ? `ST_Transform("${n.name}"::geometry, ${String(e.srid)})::geography` : `ST_Transform("${n.name}", ${String(e.srid)})`, l = n.narrowedFrom, u = l !== void 0 && l.from === r.type, d = o ? c : u ? l.using : void 0;
+		s.push(L({
+			kind: "alter-column-type",
+			table: t,
+			column: n.name,
+			from: r.type,
+			to: n.type,
+			...d === void 0 ? {} : { using: d }
+		}, o || u ? "needs-backfill" : "lossy", o ? `SRID ${String(i.srid)} → ${String(e.srid)} on ${t}.${n.name} — every value is reprojected with ST_Transform; the rewrite touches the whole table` : u ? `spatial type ${a(i)} → ${a(e)} on ${t}.${n.name} — narrowedFrom('${l.from}') declared` + (l.using ? ` with USING ${l.using}` : " (implicit cast)") : `spatial type ${a(i)} → ${a(e)} on ${t}.${n.name} — no transform preserves this; a point is not a polygon, and text is not known to hold geometry at all`, o || u ? void 0 : { fix: `acknowledge it on the column: \`.narrowedFrom('${r.type}')\` — add \`{ using: 'ST_…(${n.name})' }\` with the PostGIS expression that converts your values (the ALTER fails at the database if any existing value does not fit ${a(e)}), or use a file-based migration` }));
+	}
+	if (n.type === "array" && r.type === "array" && r.arrayElement !== void 0 && n.arrayElement !== void 0 && n.arrayElement !== r.arrayElement) {
+		let e = n.narrowedFrom, i = e !== void 0 && e.from === r.type;
+		s.push(L({
+			kind: "alter-column-type",
+			table: t,
+			column: n.name,
+			from: r.type,
+			to: n.type,
+			...i && e.using !== void 0 ? { using: e.using } : {}
+		}, i ? "needs-backfill" : "lossy", i ? `array element ${r.arrayElement} → ${n.arrayElement} on ${t}.${n.name} — narrowedFrom('${e.from}') declared` + (e.using ? ` with USING ${e.using}` : " (implicit cast)") : `array element ${r.arrayElement} → ${n.arrayElement} on ${t}.${n.name} — the engine will not choose a cast for you, and a value that does not parse fails the ALTER`, i ? void 0 : { fix: `acknowledge it on the column: \`.narrowedFrom('${r.type}')\` — add \`{ using: '"${n.name}"::${n.arrayElement}[]' }\` or the expression your values need, or use a file-based migration` }));
+	}
+	if (n.type === "vector" && r.type === "vector" && (r.vectorDim !== void 0 && n.vectorDim !== r.vectorDim || (n.vectorPrecision ?? "float32") !== (r.vectorPrecision ?? "float32"))) {
+		let e = (e) => `${e.vectorPrecision === "half" ? "halfvec" : "vector"}(${String(e.vectorDim ?? "?")})`, i = n.narrowedFrom, a = i !== void 0 && i.from === r.type;
+		s.push(L({
+			kind: "alter-column-type",
+			table: t,
+			column: n.name,
+			from: r.type,
+			to: n.type,
+			...a && i.using !== void 0 ? { using: i.using } : {}
+		}, a ? "needs-backfill" : "lossy", a ? `vector ${e(r)} → ${e(n)} on ${t}.${n.name} — narrowedFrom('${i.from}') declared` + (i.using ? ` with USING ${i.using}` : " (implicit cast)") : `vector ${e(r)} → ${e(n)} on ${t}.${n.name} — an embedding of one dimension is not an embedding of another, and halving the precision discards bits. Existing rows cannot be carried across by the engine.`, a ? void 0 : { fix: `acknowledge it on the column: \`.narrowedFrom('${r.type}')\` — add \`{ using: '…' }\` with the expression that converts your vectors (re-embedding is usually a backfill, not a cast), or use a file-based migration` }));
+	}
+	if (!c && n.type === "decimal" && r.type === "decimal" && r.precision !== void 0 && (n.precision !== r.precision || (n.scale ?? 0) !== (r.scale ?? 0))) {
+		let e = (e) => `${String(e.precision)},${String(e.scale ?? 0)}`, i = n.precision !== void 0 && r.precision !== void 0 && n.precision - (n.scale ?? 0) >= r.precision - (r.scale ?? 0) && (n.scale ?? 0) >= (r.scale ?? 0);
+		s.push(L({
+			kind: "alter-column-type",
+			table: t,
+			column: n.name,
+			from: "decimal",
+			to: "decimal"
+		}, i ? "safe" : "needs-backfill", i ? `decimal(${e(r)}) → decimal(${e(n)}) on ${t}.${n.name} — widening, every value survives` : `decimal(${e(r)}) → decimal(${e(n)}) on ${t}.${n.name} — NARROWING; the engine ROUNDS to the new scale and rejects a value that no longer fits. Check first: SELECT COUNT(*) FROM ${t} WHERE ${n.name} <> ROUND(${n.name}, ${String(n.scale ?? 0)})`));
+	}
+	if (!O(n, r)) {
+		let e = {
+			kind: "alter-column-default",
+			table: t,
+			column: n.name,
+			hasDefault: n.hasDefault,
+			...n.defaultValue === void 0 ? {} : { defaultValue: n.defaultValue }
+		};
+		s.push(L(e, "safe", `default change on ${t}.${n.name} affects only future inserts`));
+	}
+	if (i === "mssql" && n.jsonValidation !== void 0 && n.jsonValidation !== "unverified" && n.jsonValidation !== r.jsonValidation) {
+		let e = n.jsonValidation === "value" && r.jsonValidation === "container";
+		s.push(L({
+			kind: "reconcile-json-check",
+			table: t,
+			column: n.name,
+			validation: n.jsonValidation,
+			previousValidation: r.jsonValidation ?? "absent",
+			dropConstraints: (r.jsonChecks ?? []).map((e) => e.name).sort()
+		}, e ? "safe" : "needs-backfill", e ? `allow every JSON value on ${t}.${n.name}; preserve existing rows` : `validate existing JSON on ${t}.${n.name}; invalid rows refuse the migration without being rewritten`));
+	}
+	if (!k(n.oneOf, r.oneOf)) {
+		r.oneOf && r.oneOf.length > 0 && s.push(L({
+			kind: "drop-check",
+			table: t,
+			column: n.name
+		}, "safe", `drop stale enum CHECK on ${t}.${n.name}`));
+		let e = F(t, n);
+		e && s.push(e);
+	}
+	return JSON.stringify(m(n.references)) !== JSON.stringify(m(r.references)) && (r.references && s.push(L({
+		kind: "drop-foreign-key",
+		table: t,
+		column: n.name
+	}, "safe", `drop FK on ${t}.${n.name} (→ ${r.references.table})`)), s.push(...K(t, n))), s;
+}, K = (e, t) => {
+	let n = [];
+	if (!t.references) return n;
+	let r = t.references.table, i = t.references.orphanPolicy ?? "fail", a = {
+		kind: "add-foreign-key",
+		table: e,
+		column: t.name,
+		targetTable: r,
+		targetColumn: t.references.column,
+		...t.references.onDelete ? { onDelete: t.references.onDelete } : {},
+		...t.references.onUpdate ? { onUpdate: t.references.onUpdate } : {}
+	};
+	return i === "null" && !t.nullable ? n.push(L(a, "lossy", `add FK ${e}.${t.name} → ${r}: orphanPolicy 'null' needs a nullable column (the NULL-out would violate NOT NULL)`, { fix: `make ${t.name} \`.nullable()\`, OR use \`orphanPolicy: 'delete'\`, OR clean the orphans and drop the policy` })) : i === "null" || i === "delete" ? n.push(L({
+		...a,
+		orphanPolicy: i
+	}, "lossy", i === "delete" ? `add FK ${e}.${t.name} → ${r}: orphanPolicy 'delete' first DELETES rows whose ${t.name} points at a missing ${r}` : `add FK ${e}.${t.name} → ${r}: orphanPolicy 'null' first NULLs ${t.name} where it points at a missing ${r}`)) : n.push(L(a, "needs-backfill", `add FK ${e}.${t.name} → ${r} — existing rows must already reference a valid ${r} (else set orphanPolicy:'null'/'delete')`)), n;
+}, ae = (e, t, n) => {
+	let r = [], i = /* @__PURE__ */ new Set(), a = /* @__PURE__ */ new Set(), o = new Set(n.removed.map((e) => e.name)), s = new Set(n.added.map((e) => e.name));
+	for (let [n, c] of Object.entries(t)) {
+		let t = c.renamedFrom;
+		t && o.has(t) && s.has(n) && (i.add(n), a.add(t), r.push(L({
+			kind: "rename-column",
+			table: e.tableName,
+			from: t,
+			to: n
+		}, "safe", `rename via \`.renamedFrom('${t}')\``)));
+	}
+	return {
+		ops: r,
+		consumedAddedNames: i,
+		consumedRemovedNames: a
+	};
+}, q = /* @__PURE__ */ new Set([
+	"postgres",
+	"mysql",
+	"mariadb",
+	"mssql"
+]), J = {
+	ops: [],
+	consumedAddedNames: /* @__PURE__ */ new Set(),
+	consumedRemovedNames: /* @__PURE__ */ new Set()
+}, Y = (e) => !e.unique && !e.expression && e.where === void 0 && (e.kind === void 0 || e.kind === "btree"), oe = (e, t, n, r, i) => {
+	if (i === void 0 || !q.has(i)) return J;
+	let a = t.added.filter((e) => Y(e) && !r.has(e.name));
+	if (a.length === 0) return J;
+	let o = (e) => e.columns.map((e) => n.get(e) ?? e).join("\0"), s = (e) => e.columns.join("\0"), c = new Set(t.added.map((e) => e.name)), l = /* @__PURE__ */ new Map();
+	for (let e of a) {
+		let t = s(e), n = l.get(t);
+		n === void 0 ? l.set(t, [e]) : n.push(e);
+	}
+	let u = [], d = /* @__PURE__ */ new Set(), f = /* @__PURE__ */ new Set();
+	for (let n of t.removed) {
+		if (!Y(n) || c.has(n.name)) continue;
+		let t = o(n), r = l.get(t);
+		if (r === void 0 || r.length !== 1) continue;
+		let i = r[0];
+		d.has(i.name) || i.name !== n.name && (d.add(i.name), f.add(n.name), u.push(L({
+			kind: "rename-index",
+			table: e,
+			from: n.name,
+			to: i.name
+		}, "safe", "rename index in place — catalog-only, no rebuild")));
+	}
+	return {
+		ops: u,
+		consumedAddedNames: d,
+		consumedRemovedNames: f
+	};
+}, se = (e, t, n) => {
+	let r = [], i = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Set(), o = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Set();
+	for (let t of e.tables) t.renamedFrom !== void 0 && (s.set(t.renamedFrom, (s.get(t.renamedFrom) ?? 0) + 1), c.add(t.renamedFrom));
+	for (let c of e.tables) {
+		let e = c.renamedFrom;
+		e !== void 0 && e !== c.name && t.has(e) && (n.has(e) ? o.set(c.name, `.renamedFrom('${e}') NOT applied — '${e}' is still declared by this schema, so it belongs to that declaration. This table is created empty; that is the intended outcome when an app owns a table of the same name.`) : t.has(c.name) ? r.push(L({
+			kind: "rename-table",
+			from: e,
+			to: c.name
+		}, "needs-rename-annotation", `.renamedFrom('${e}') cannot be applied — both '${e}' and '${c.name}' exist in the database`, { fix: `decide which holds the real rows: move them into '${c.name}' and drop '${e}', or drop the empty '${c.name}' so the rename can run. '${e}' is left untouched until you do.` })) : (s.get(e) ?? 0) === 1 ? (i.set(c.name, e), a.add(e), r.push(L({
+			kind: "rename-table",
+			from: e,
+			to: c.name
+		}, "safe", `rename via \`.renamedFrom('${e}')\` — catalog-only, the rows stay put`))) : r.push(L({
+			kind: "rename-table",
+			from: e,
+			to: c.name
+		}, "needs-rename-annotation", `.renamedFrom('${e}') is claimed by ${s.get(e)} tables — nothing says which receives its rows`, { fix: `remove the \`.renamedFrom('${e}')\` marker from all but one of them.` })));
+	}
+	return {
+		ops: r,
+		renamedInto: i,
+		renamedFromNames: a,
+		claimedOldNames: c,
+		refusals: o
+	};
+}, ce = (e, t, n, r) => {
+	if (t === void 0) return {
+		live: e,
+		ops: []
+	};
+	let i = r !== void 0 && q.has(r), a = [], o = e.indexes.map((e) => {
+		if (!e.name.startsWith(t)) return e;
+		let r = `${n}${e.name.slice(t.length)}`;
+		return r === e.name ? e : e.name === `${t}_pkey` ? {
+			...e,
+			name: r,
+			table: n
+		} : i ? (a.push(L({
+			kind: "rename-index",
+			table: n,
+			from: e.name,
+			to: r
+		}, "safe", "auto-named index follows its renamed table — catalog-only, no rebuild")), {
+			...e,
+			name: r,
+			table: n
+		}) : e;
+	});
+	return {
+		live: {
+			...e,
+			indexes: o,
+			name: n
+		},
+		ops: a
+	};
+}, le = (e) => {
+	let t = {
+		safe: 0,
+		needsDefault: 0,
+		needsBackfill: 0,
+		needsRenameAnnotation: 0,
+		lossy: 0,
+		onlineRequired: 0,
+		multiStep: 0,
+		blocked: 0
+	};
+	for (let n of e) switch (n.blocked && t.blocked++, n.classification) {
+		case "safe":
+			t.safe++;
+			break;
+		case "needs-default":
+			t.needsDefault++;
+			break;
+		case "needs-backfill":
+			t.needsBackfill++;
+			break;
+		case "needs-rename-annotation":
+			t.needsRenameAnnotation++;
+			break;
+		case "lossy":
+			t.lossy++;
+			break;
+		case "online-required":
+			t.onlineRequired++;
+			break;
+		case "multi-step": t.multiStep++;
+	}
+	return t;
+}, X = (e, t) => {
+	let n = t.flatMap((e) => [e.table, e.targetTable]).flatMap((e) => {
+		let t = r(e);
+		return t === void 0 ? [] : [t.getTime()];
+	}), i = new Date(Math.max(...n)), a = new Date(Date.UTC(i.getUTCFullYear(), i.getUTCMonth(), i.getUTCDate() + 1)).toISOString().slice(0, 10);
+	return `${e.join("; ")}. Reclaim the snapshots first — \`voltro db gc-snapshots --before ${a}\` drops every snapshot older than that date, so run it with --dry-run to see the list — or, if a snapshot's data is still wanted, bring it back with \`voltro db restore-snapshot <plan-id>\` and declare it, so it converts in the same plan.`;
+}, ue = (e, t, r, i) => {
+	let a = /* @__PURE__ */ new Map();
+	for (let n of e.tables) {
+		let e = t.get(n.name) ?? (r.has(n.name) ? t.get(r.get(n.name)) : void 0);
+		if (e === void 0) continue;
+		let o = new Set(n.columns.filter(S).map((e) => e.name));
+		x(e).filter((e) => o.has(e.column) && e.charset !== i).length > 0 && a.set(n.name, {
+			declared: n,
+			live: e
+		});
+	}
+	if (a.size === 0) return [];
+	let o = /* @__PURE__ */ new Map();
+	for (let e of t.values()) {
+		let t = /* @__PURE__ */ new Map();
+		for (let n of e.columns) t.has(n.name) || t.set(n.name, n);
+		o.set(e.name, t);
+	}
+	let s = /* @__PURE__ */ new Map(), c = (e, t) => {
+		let n = s.get(e);
+		n === void 0 ? s.set(e, [t]) : n.push(t);
+	};
+	for (let e of t.values()) for (let t of e.columns) {
+		if (t.references === void 0) continue;
+		let n = o.get(t.references.table)?.get(t.references.column), r = {
+			name: t.references.constraintName ?? `${e.name}_${t.name}_fkey`,
+			table: e.name,
+			column: t.name,
+			targetTable: t.references.table,
+			targetColumn: t.references.column,
+			...t.references.onDelete === void 0 ? {} : { onDelete: t.references.onDelete },
+			...t.references.onUpdate === void 0 ? {} : { onUpdate: t.references.onUpdate },
+			restore: "here",
+			sourceCharset: t.charset,
+			targetCharset: n?.charset
+		};
+		c(e.name, r), t.references.table !== e.name && c(t.references.table, r);
+	}
+	let l = [];
+	for (let [e, { declared: t, live: r }] of a) {
+		let o = t.columns.filter(S).map((e) => e.name), c = new Map(r.columns.map((e) => [e.name, e])), u = [...new Set(o.flatMap((e) => {
+			let t = c.get(e);
+			return t?.charset === void 0 ? [] : [t.charset];
+		}))].sort(), d = o.filter((e) => c.has(e)), f = s.get(e) ?? [], p = [], m = [], h = f.map((t) => {
+			let r = t.table === e ? t.targetTable : t.table, o = r === e || a.has(r), s = t.table === e ? t.targetCharset : t.sourceCharset;
+			if (!o && s !== void 0 && s !== i) {
+				let e = `${t.name} (${t.table}.${t.column} → ${t.targetTable}.${t.targetColumn})`;
+				n(r) ? m.push(`${e}: "${r}" is a soft-drop snapshot, stored ${s}`) : p.push(`${e}: "${r}" stays ${s} — it is not a declared table, so the plan does not convert it`);
+			}
+			let { sourceCharset: c, targetCharset: l, ...u } = t, d = o && r !== e && r.localeCompare(e) > 0 ? "peer" : "here";
+			return {
+				...u,
+				restore: d
+			};
+		}), g = i === "utf8mb4", _ = `table rewrite: ${d.length} string column${d.length === 1 ? "" : "s"} ${u.join("/")} → ${i}` + (h.length > 0 ? `; ${h.length} foreign key${h.length === 1 ? "" : "s"} dropped and re-created around it` : ""), v = {
+			kind: "convert-charset",
+			table: e,
+			charset: i,
+			columns: d,
+			from: u,
+			foreignKeys: h
+		};
+		if (p.length > 0 || m.length > 0) {
+			let t = [...p.length > 0 ? [`${p.join("; ")}. Declare that table so it converts in the same plan, convert it by hand first, or leave the store charset undeclared.`] : [], ...m.length > 0 ? [X(m, f)] : []];
+			l.push(L(v, "lossy", _, { fix: `converting "${e}" to ${i} would break a foreign key the plan cannot carry: ${t.join(" ")}` }));
+		} else l.push(g ? L(v, "safe", _) : L(v, "lossy", _, { fix: `${e}: narrowing to ${i} can refuse or truncate 4-byte characters the columns already hold. Declare charset: 'utf8mb4' instead, or — after checking the data — allow it with the destructive opt-in (VOLTRO_DESTRUCTIVE_OK=1).` }));
+	}
+	return l;
+}, Z = (e) => {
+	let r = C(e.declared, e.dialect, { charset: e.charset }), i = ee(e.declared, r), s = new Map(e.live.tables.map((e) => [e.name, e])), c = e.onlineAfter ?? H, l = [], u = se(r, s, i);
+	l.push(...u.ops);
+	for (let e of r.tables) if (!u.renamedInto.has(e.name) && !s.has(e.name)) {
+		l.push(B(e.name, e.columns, e.indexes, e.primaryKey, u.refusals.get(e.name)));
+		for (let t of e.columns) {
+			let n = F(e.name, t);
+			n && l.push(n);
+		}
+	}
+	let d = new Set(e.ignoreTables ?? []), f = [];
+	for (let r of e.live.tables) i.has(r.name) || (u.claimedOldNames.has(r.name) || t(r.name) || n(r.name) || d.has(r.name) ? f.push(r.name) : l.push(V(r.name)));
+	for (let t of r.tables) {
+		let r = u.renamedInto.get(t.name), a = s.get(t.name) ?? (r === void 0 ? void 0 : s.get(r));
+		if (!a) continue;
+		let o = ce(a, r, t.name, e.dialect);
+		l.push(...o.ops);
+		let d = o.live, f = i.get(t.name), p = te(t, d, e.dialect), m = ae(f.table, f.columnDefs, p), h = new Map(m.ops.flatMap((e) => e.op.kind === "rename-column" ? [[e.op.from, e.op.to]] : [])), g = ne(t, d, e.dialect, h);
+		l.push(...m.ops);
+		let _ = m.ops.length >= 8 ? N(t.columns) : void 0, v = m.ops.length >= 8 ? N(d.columns) : void 0;
+		for (let { op: n } of m.ops) {
+			if (n.kind !== "rename-column") continue;
+			let r = _ === void 0 ? t.columns.find((e) => e.name === n.to) : _.get(n.to), i = v === void 0 ? d.columns.find((e) => e.name === n.from) : v.get(n.from);
+			r && i && l.push(...G(t.name, r, {
+				...i,
+				name: n.to
+			}, e.dialect, d.rowCount, c));
+		}
+		for (let e of p.removed) {
+			if (m.consumedRemovedNames.has(e.name) || n(e.name)) continue;
+			let r = f.columnDefs[e.name], i = z(t.name, e, r);
+			e.references !== void 0 && l.push({
+				...L({
+					kind: "drop-foreign-key",
+					table: t.name,
+					column: e.name,
+					...e.references.constraintName === void 0 ? {} : { name: e.references.constraintName }
+				}, i.blocked === void 0 ? "safe" : i.classification, `drop FK on ${t.name}.${e.name} (→ ${e.references.table}) before dropping the column`),
+				...i.blocked === void 0 ? {} : { blocked: i.blocked }
+			}), l.push(i);
+		}
+		for (let n of p.added) {
+			if (m.consumedAddedNames.has(n.name)) continue;
+			let r = f.columnDefs[n.name];
+			l.push(R(t.name, n, r, e.dialect));
+			let i = F(t.name, n);
+			i && l.push(i), l.push(...K(t.name, n));
+		}
+		let y = oe(t.name, g, h, new Set(d.indexes.map((e) => e.name)), e.dialect);
+		l.push(...y.ops);
+		let b = p.added.some((e) => D(e) && !m.consumedAddedNames.has(e.name));
+		for (let e of g.added) y.consumedAddedNames.has(e.name) || b && e.name === `${t.name}_pkey` || l.push(re(t.name, e, d.rowCount, c));
+		for (let e of g.removed) y.consumedRemovedNames.has(e.name) || l.push(ie(t.name, e));
+		for (let { declared: n, live: r } of p.changed) l.push(...G(t.name, n, r, e.dialect, d.rowCount, c));
+	}
+	e.charset !== void 0 && l.push(...ue(r, s, u.renamedInto, e.charset));
+	let p = new Set(l.flatMap((e) => e.op.kind === "create-table" ? [e.op.table] : [])), m = new Map(r.tables.map((e) => [e.name, e])), h = (e) => {
+		let t = m.get(e);
+		return t ? t.columns.flatMap((e) => e.references && p.has(e.references.table) ? [{
+			column: e.name,
+			target: e.references.table
+		}] : []) : [];
+	}, g = a([...p], h), _ = [];
+	for (let e of r.tables) if (p.has(e.name)) for (let t of e.columns) t.references && g.has(o(e.name, t.name)) && _.push(L({
+		kind: "add-foreign-key",
+		table: e.name,
+		column: t.name,
+		targetTable: t.references.table,
+		targetColumn: t.references.column,
+		...t.references.onDelete ? { onDelete: t.references.onDelete } : {},
+		...t.references.onUpdate ? { onUpdate: t.references.onUpdate } : {}
+	}, "safe", `deferred FK ${e.name}.${t.name} → ${t.references.table} — breaks a create-time table cycle`));
+	if (g.size > 0) {
+		let e = (e) => e.references ? Object.fromEntries(Object.entries(e).filter(([e]) => e !== "references")) : e;
+		for (let t = 0; t < l.length; t += 1) {
+			let n = l[t];
+			if (n.op.kind !== "create-table") continue;
+			let r = n.op;
+			if (!r.columns.some((e) => g.has(o(r.table, e.name)))) continue;
+			let i = r.columns.map((t) => g.has(o(r.table, t.name)) ? e(t) : t);
+			l[t] = {
+				...n,
+				op: {
+					...r,
+					columns: i
+				}
+			};
+		}
+		l.push(..._);
+	}
+	let v = new Map(r.tables.map((e) => [e.name, e])), y = /* @__PURE__ */ new Map(), x = /* @__PURE__ */ new Set(), S = (e) => {
+		let t = y.get(e);
+		if (t !== void 0) return t;
+		if (x.has(e)) return 0;
+		let n = v.get(e);
+		if (!n) return 0;
+		x.add(e);
+		try {
+			let t = 0;
+			for (let r of n.columns) {
+				let n = r.references?.table;
+				n && n !== e && !g.has(o(e, r.name)) && (t = Math.max(t, S(n) + 1));
+			}
+			return y.set(e, t), t;
+		} finally {
+			x.delete(e);
+		}
+	}, w = (e) => e === "rename-table" ? -1 : e === "create-table" ? 0 : e === "drop-table" ? 2 : 1, T = (e) => {
+		let t = "table" in e ? e.table : "";
+		return e.kind === "create-table" ? S(t) : e.kind === "drop-table" ? -S(t) : 0;
+	}, E = {
+		"add-column": 0,
+		"rename-column": 1,
+		"rename-index": 1,
+		"alter-column-nullability": 2,
+		"alter-column-type": 2,
+		"alter-column-default": 2,
+		"drop-index": 3,
+		"drop-check": 3,
+		"drop-unique": 3,
+		"drop-unique-composite": 3,
+		"drop-foreign-key": 3,
+		"drop-column": 4,
+		"convert-charset": 5,
+		"add-index": 6,
+		"add-unique": 6,
+		"add-unique-composite": 6,
+		"add-foreign-key": 6,
+		"add-check": 6,
+		"reconcile-json-check": 6
+	}, O = (e) => E[e] ?? 9, k = (e) => e.kind === "drop-unique-composite" && e.name === `${e.table}_pkey`, A = (e) => k(e) ? -1 : O(e.kind), j = new Set(l.flatMap((e) => "table" in e.op && O(e.op.kind) < O("convert-charset") ? [e.op.table] : [])), M = (e) => e.kind === "convert-charset" && !j.has(e.table) ? -.5 : w(e.kind), P = [...l].sort((e, t) => {
+		let n = M(e.op), r = M(t.op);
+		if (n !== r) return n - r;
+		let i = T(e.op), a = T(t.op);
+		if (i !== a) return i - a;
+		let o = "table" in e.op ? e.op.table : "", s = "table" in t.op ? t.op.table : "";
+		if (o !== s) return o.localeCompare(s);
+		let c = A(e.op), l = A(t.op);
+		return c === l ? e.op.kind.localeCompare(t.op.kind) : c - l;
+	}), I = new Set(l.flatMap((e) => e.op.kind === "convert-charset" ? [e.op.table] : [])), U = new Set(l.flatMap((e) => e.op.kind === "create-table" ? [e.op.table] : [])), W = /* @__PURE__ */ new Set(), q = [], J = [], Y = (e) => !U.has(e) || W.has(e), X = (e) => {
+		let t = e.op;
+		return t.kind === "create-table" ? t.columns.every((e) => {
+			let n = e.references?.table;
+			return n === void 0 || n === t.table || g.has(o(t.table, e.name)) || !I.has(n) && Y(n);
+		}) : "table" in t && !Y(t.table) ? !1 : t.kind !== "add-foreign-key" || !I.has(t.table) && !I.has(t.targetTable) && Y(t.targetTable);
+	}, Z = (e) => {
+		J.push(e), e.op.kind === "convert-charset" && I.delete(e.op.table), e.op.kind === "create-table" && W.add(e.op.table);
+	};
+	for (let e of P) for (X(e) ? Z(e) : q.push(e); q.length > 0;) {
+		let e = q.findIndex(X);
+		if (e < 0) break;
+		Z(q.splice(e, 1)[0]);
+	}
+	J.push(...q);
+	let Q = /* @__PURE__ */ new Set();
+	for (let e of J) "table" in e.op && Q.add(e.op.table);
+	let $ = [];
+	for (let e of r.tables) {
+		if (Q.has(e.name) || u.renamedInto.has(e.name)) continue;
+		let t = s.get(e.name);
+		t !== void 0 && b({ tables: [t] }) !== b({ tables: [e] }) && $.push(e.name);
+	}
+	return {
+		operations: J,
+		fromFingerprint: b(e.live),
+		toFingerprint: b(r),
+		summary: le(J),
+		fingerprintDivergence: {
+			outsideDiff: f,
+			diffEquivalent: $
+		}
+	};
+};
+//#endregion
+export { Z as planMigrations };