@atscript/db 0.1.127 → 0.1.128

package/dist/sync.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_view = require("./db-view-BP0Qbeux.cjs");
+const require_db_view = require("./db-view-C8-MsjND.cjs");
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {
@@ -65,18 +65,46 @@ function computeViewSnapshot(view) {
 		fields
 	};
 	const plan = view.viewPlan;
+	const qualify = (ref) => view.resolveFieldRef(ref, (n) => n);
 	const result = {
 		tableName: view.tableName,
 		viewType: plan.materialized ? "M" : "V",
 		entryTable: plan.entryTable,
-		joinTables: plan.joins.map((j) => j.targetTable),
+		joinTables: plan.joins.map((j) => ({
+			targetTable: j.targetTable,
+			condition: JSON.stringify(canonicalizeQueryNode(j.condition, qualify))
+		})),
 		materialized: plan.materialized || void 0,
 		fields
 	};
-	if (plan.filter) result.filterHash = fnv1a(JSON.stringify(plan.filter, (_, v) => typeof v === "function" ? "[fn]" : v));
+	if (plan.filter) result.filterHash = fnv1a(JSON.stringify(canonicalizeQueryNode(plan.filter, qualify)));
+	if (plan.having) result.havingHash = fnv1a(JSON.stringify(canonicalizeQueryNode(plan.having, qualify)));
 	return result;
 }
 /**
+* Converts a view predicate (join condition, `@db.view.filter`,
+* `@db.view.having`) into a serializable structure whose JSON is a stable
+* function of its MEANING: field refs become `qualify(ref)` — the view's
+* `resolveFieldRef(ref, (n) => n)`, i.e. `"<table>.<field>"`, so a predicate
+* retargeted to another table with the same field name changes — operators
+* and literal values are kept as-is, `$and`/`$or` keep declaration order, and
+* no function references survive. Two identical models produce byte-identical
+* JSON.
+* @since 0.1.128
+*/
+function canonicalizeQueryNode(node, qualify) {
+	if ("$and" in node) return { and: node.$and.map((n) => canonicalizeQueryNode(n, qualify)) };
+	if ("$or" in node) return { or: node.$or.map((n) => canonicalizeQueryNode(n, qualify)) };
+	if ("$not" in node) return { not: canonicalizeQueryNode(node.$not, qualify) };
+	const comp = node;
+	const out = {
+		l: qualify(comp.left),
+		op: comp.op
+	};
+	if (comp.right !== void 0) out.r = comp.right !== null && typeof comp.right === "object" && "field" in comp.right ? { f: qualify(comp.right) } : comp.right;
+	return out;
+}
+/**
 * Computes a deterministic hash string from multiple table snapshots.
 * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
 */
@@ -131,6 +159,52 @@ function fnv1a(str) {
 	return Math.trunc(hash).toString(16).padStart(8, "0");
 }
 //#endregion
+//#region src/schema/fk-diff.ts
+/** Canonical key for an FK: sorted local field names, comma-joined. */
+function fkKey(fields) {
+	return [...fields].toSorted().join(",");
+}
+/**
+* Compares desired FK constraints against stored snapshot to detect
+* additions, removals, and property changes (target table, target fields,
+* onDelete, onUpdate).
+*/
+function computeForeignKeyDiff(desired, existingSnapshot) {
+	const added = [];
+	const removed = [];
+	const changed = [];
+	const existingByKey = /* @__PURE__ */ new Map();
+	for (const fk of existingSnapshot) existingByKey.set(fkKey(fk.fields), fk);
+	const desiredKeys = /* @__PURE__ */ new Set();
+	for (const fk of desired.values()) {
+		const key = fkKey(fk.fields);
+		desiredKeys.add(key);
+		const existing = existingByKey.get(key);
+		if (!existing) added.push(fk);
+		else if (fkPropertiesDiffer(fk, existing)) changed.push({
+			desired: fk,
+			existing
+		});
+	}
+	for (const [key, fk] of existingByKey) if (!desiredKeys.has(key)) removed.push(fk);
+	return {
+		added,
+		removed,
+		changed
+	};
+}
+/** Whether the FK diff contains any changes. */
+function hasForeignKeyChanges(diff) {
+	return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
+}
+function fkPropertiesDiffer(desired, existing) {
+	if (desired.targetTable !== existing.targetTable) return true;
+	if (fkKey(desired.targetFields) !== fkKey(existing.targetFields)) return true;
+	if ((desired.onDelete ?? void 0) !== (existing.onDelete ?? void 0)) return true;
+	if ((desired.onUpdate ?? void 0) !== (existing.onUpdate ?? void 0)) return true;
+	return false;
+}
+//#endregion
 //#region src/schema/column-diff.ts
 /**
 * Computes the difference between desired schema fields and existing database columns.
@@ -192,7 +266,7 @@ function computeColumnDiff(desired, existing, typeMapper) {
 			renamedOldNames.add(field.renamedFrom);
 		} else added.push(field);
 	}
-	return {
+	const diff = {
 		added,
 		removed: existing.filter((c) => !desiredByName.has(c.name) && !renamedOldNames.has(c.name)),
 		renamed,
@@ -201,52 +275,16 @@ function computeColumnDiff(desired, existing, typeMapper) {
 		defaultChanged,
 		conflicts
 	};
-}
-//#endregion
-//#region src/schema/fk-diff.ts
-/** Canonical key for an FK: sorted local field names, comma-joined. */
-function fkKey(fields) {
-	return [...fields].toSorted().join(",");
-}
-/**
-* Compares desired FK constraints against stored snapshot to detect
-* additions, removals, and property changes (target table, target fields,
-* onDelete, onUpdate).
-*/
-function computeForeignKeyDiff(desired, existingSnapshot) {
-	const added = [];
-	const removed = [];
-	const changed = [];
-	const existingByKey = /* @__PURE__ */ new Map();
-	for (const fk of existingSnapshot) existingByKey.set(fkKey(fk.fields), fk);
-	const desiredKeys = /* @__PURE__ */ new Set();
-	for (const fk of desired.values()) {
-		const key = fkKey(fk.fields);
-		desiredKeys.add(key);
-		const existing = existingByKey.get(key);
-		if (!existing) added.push(fk);
-		else if (fkPropertiesDiffer(fk, existing)) changed.push({
-			desired: fk,
-			existing
-		});
+	if (existing.length > 0) {
+		const newNameByOld = new Map(renamed.map((r) => [r.oldName, r.field.physicalName]));
+		const from = existing.filter((c) => c.pk).map((c) => newNameByOld.get(c.name) ?? c.name);
+		const to = desired.filter((f) => !f.ignored && f.isPrimaryKey).map((f) => f.physicalName);
+		if (fkKey(from) !== fkKey(to)) diff.primaryKeyChanged = {
+			from,
+			to
+		};
 	}
-	for (const [key, fk] of existingByKey) if (!desiredKeys.has(key)) removed.push(fk);
-	return {
-		added,
-		removed,
-		changed
-	};
-}
-/** Whether the FK diff contains any changes. */
-function hasForeignKeyChanges(diff) {
-	return diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0;
-}
-function fkPropertiesDiffer(desired, existing) {
-	if (desired.targetTable !== existing.targetTable) return true;
-	if (fkKey(desired.targetFields) !== fkKey(existing.targetFields)) return true;
-	if ((desired.onDelete ?? void 0) !== (existing.onDelete ?? void 0)) return true;
-	if ((desired.onUpdate ?? void 0) !== (existing.onUpdate ?? void 0)) return true;
-	return false;
+	return diff;
 }
 //#endregion
 //#region src/schema/table-option-diff.ts
@@ -276,6 +314,80 @@ function computeTableOptionDiff(desired, existing, destructiveKeys) {
 	return { changed };
 }
 //#endregion
+//#region src/schema/dependency-order.ts
+/**
+* Orders `nodes` so that dependencies come first. Returns the strongly-
+* connected components in dependency order: every group appears AFTER each
+* group it depends on (parents first). Singleton groups are ordinary tables;
+* groups of size > 1 are cycles. Members are name-sorted.
+*
+* - Edges referencing a name outside `nodes` are ignored (external tables
+*   impose no ordering).
+* - Self-loops are ignored (a self-referential FK is legal inline everywhere).
+* - Deterministic: nodes and adjacency lists are sorted by name before the
+*   traversal, so two processes with different inventory orders compute the
+*   same plan.
+*/
+function topoOrder(nodes, edges) {
+	const names = [...new Set(nodes)].toSorted();
+	const nodeSet = new Set(names);
+	const adjacency = new Map(names.map((n) => [n, /* @__PURE__ */ new Set()]));
+	for (const [from, to] of edges) {
+		if (from === to || !nodeSet.has(from) || !nodeSet.has(to)) continue;
+		adjacency.get(from).add(to);
+	}
+	const index = /* @__PURE__ */ new Map();
+	const lowlink = /* @__PURE__ */ new Map();
+	const onStack = /* @__PURE__ */ new Set();
+	const stack = [];
+	const order = [];
+	let counter = 0;
+	const visit = (node) => {
+		index.set(node, counter);
+		lowlink.set(node, counter);
+		counter++;
+		stack.push(node);
+		onStack.add(node);
+		for (const next of [...adjacency.get(node)].toSorted()) if (!index.has(next)) {
+			visit(next);
+			lowlink.set(node, Math.min(lowlink.get(node), lowlink.get(next)));
+		} else if (onStack.has(next)) lowlink.set(node, Math.min(lowlink.get(node), index.get(next)));
+		if (lowlink.get(node) === index.get(node)) {
+			const group = [];
+			let member;
+			do {
+				member = stack.pop();
+				onStack.delete(member);
+				group.push(member);
+			} while (member !== node);
+			group.sort();
+			order.push(group);
+		}
+	};
+	for (const name of names) if (!index.has(name)) visit(name);
+	return order;
+}
+/**
+* The dependents closure of `seeds`: the seeds themselves plus every node
+* that depends on one of them — directly or through other dependents — along
+* `edges` (`from` depends on `to`). A fixed point over the edge list, so the
+* edges may come in any order. Schema sync uses it over the removed-table
+* graph: the removed tables that block a drop, plus their own removed
+* children, which must go first.
+*/
+function reachable(seeds, edges) {
+	const out = new Set(seeds);
+	const edgeList = [...edges];
+	for (let grew = out.size > 0; grew;) {
+		grew = false;
+		for (const [from, to] of edgeList) if (out.has(to) && !out.has(from)) {
+			out.add(from);
+			grew = true;
+		}
+	}
+	return out;
+}
+//#endregion
 //#region src/schema/sync-store.ts
 var SyncStore = class {
 	space;
@@ -336,7 +448,14 @@ var SyncStore = class {
 		for (const e of entries) e.viewType ??= e.isView ? "V" : void 0;
 		return entries;
 	}
-	async writeTrackedList(readables) {
+	/**
+	* Writes the tracked list: the current readables plus `retained` — entries
+	* from the previous list that were scheduled for removal but NOT dropped
+	* (safe mode, blocked or failed drop). Tracking must keep describing what
+	* sync believes exists, so a later run that actually executes still drops
+	* them instead of orphaning them behind a matching hash.
+	*/
+	async writeTrackedList(readables, retained = []) {
 		const entries = readables.map((r) => {
 			const isView = r.isView;
 			let viewType;
@@ -350,6 +469,15 @@ var SyncStore = class {
 				viewType
 			};
 		});
+		const current = new Set(entries.map((e) => e.name));
+		for (const e of retained) if (!current.has(e.name)) {
+			entries.push({
+				name: e.name,
+				isView: e.isView,
+				viewType: e.viewType
+			});
+			current.add(e.name);
+		}
 		entries.sort((a, b) => a.name.localeCompare(b.name));
 		await this.writeControlValue("synced_tables", JSON.stringify(entries));
 	}
@@ -463,6 +591,16 @@ var SyncEntry = class {
 	recreated;
 	errors;
 	renamedFrom;
+	/** @since 0.1.128 — see {@link TSyncEntryInit.pkChange}. */
+	pkChange;
+	/** @since 0.1.128 — see {@link TSyncEntryInit.skipped}. */
+	skipped;
+	/** @since 0.1.128 — see {@link TSyncEntryInit.dependsOn}. */
+	dependsOn;
+	/** @since 0.1.128 — see {@link TSyncEntryInit.dropGroup}. */
+	dropGroup;
+	/** @since 0.1.128 — see {@link TSyncEntryInit.refused}. */
+	refused;
 	constructor(init) {
 		this.name = init.name;
 		this.viewType = init.viewType;
@@ -484,11 +622,35 @@ var SyncEntry = class {
 		this.recreated = init.recreated ?? false;
 		this.errors = init.errors ?? [];
 		this.renamedFrom = init.renamedFrom;
+		this.pkChange = init.pkChange;
+		this.skipped = init.skipped ?? [];
+		this.dependsOn = init.dependsOn ?? [];
+		this.dropGroup = init.dropGroup;
+		this.refused = init.refused ?? false;
+	}
+	/**
+	* The init object this entry was built from — lets callers derive a
+	* modified copy (`new SyncEntry({ ...entry.toInit(), status: "error" })`).
+	* @since 0.1.128
+	*/
+	toInit() {
+		return { ...this };
+	}
+	/**
+	* Whether desired work is still pending after this entry — DDL that was
+	* not issued because the entry errored or safe mode skipped it (see
+	* `skipped`). A pending entry withholds its snapshot and the schema hash,
+	* so the next run retries / applies it. External views are advisory and
+	* never pending.
+	* @since 0.1.128
+	*/
+	get pending() {
+		return this.status === "error" && this.viewType !== "E" || this.skipped.length > 0;
 	}
-	/** Whether this entry involves destructive operations */
+	/** Whether this entry involves destructive operations (pending work safe mode skipped is not) */
 	get destructive() {
 		if (this.status === "drop") return this.viewType !== "V" && this.viewType !== "E";
-		return this.columnsToDrop.length > 0 || this.typeChanges.length > 0 || this.recreated || this.optionChanges.some((c) => c.destructive);
+		return this.columnsToDrop.length > 0 || this.typeChanges.length > 0 && !this.skipped.includes("recreate") || this.recreated || this.pkChange?.rebuild === true || this.optionChanges.some((c) => c.destructive) && !this.skipped.includes("table-options");
 	}
 	/** Whether this entry represents any change (not in-sync) */
 	get hasChanges() {
@@ -510,18 +672,73 @@ var SyncEntry = class {
 		};
 	}
 	printError(c, label, vp) {
-		return [`  ${c.red(`✗ ${vp}${label} — error`)}`, ...this.errors.map((err) => `      ${c.red(err)}`)];
+		const head = this.refused ? `✖ refused: ${vp}${label}` : `✗ ${vp}${label} — error`;
+		return [`  ${c.red(head)}`, ...this.errors.map((err) => `      ${c.red(err)}`)];
+	}
+	/** `! PK (id) → (code) — rebuild (table is empty)` / `— skipped (safe mode)` */
+	printPkChange(c, mode) {
+		const pk = this.pkChange;
+		if (!pk) return [];
+		const cols = `PK (${pk.from.join(", ")}) → (${pk.to.join(", ")})`;
+		if (!pk.rebuild) return [`      ${c.yellow(`! ${cols} — skipped (safe mode)`)}`];
+		return mode === "plan" ? [`      ${c.red(`! ${cols} — rebuild (table is empty)`)}`] : [`      ${c.yellow(`~ ${cols} — rebuilt`)}`];
+	}
+	/**
+	* `! col: t1 → t2 — drop` (plan), or `! type col (t1 → t2) — skipped (safe
+	* mode)` in plan and result when the `'drop'` recreate was skipped.
+	*/
+	printTypeChanges(c) {
+		if (this.skipped.includes("recreate")) return this.typeChanges.map((tc) => `      ${c.yellow(`! type ${tc.column} (${tc.fromType} → ${tc.toType}) — skipped (safe mode)`)}`);
+		return this.typeChanges.map((tc) => {
+			const action = this.syncMethod ? ` — ${this.syncMethod}` : " — requires migration";
+			return `      ${c.red(`! ${tc.column}: ${tc.fromType} → ${tc.toType}${action}`)}`;
+		});
+	}
+	/** `~ col — nullable` / `~ col — default a → b`, `— skipped (safe mode)` when pending. */
+	printNullableDefaults(c) {
+		const suffix = this.skipped.includes("nullable-defaults") ? " — skipped (safe mode)" : "";
+		return [...this.nullableChanges.map((nc) => `      ${c.yellow(`~ ${nc.column} — ${nc.toNullable ? "nullable" : "non-nullable"}${suffix}`)}`), ...this.defaultChanges.map((dc) => `      ${c.yellow(`~ ${dc.column} — default ${dc.oldDefault ?? "none"} → ${dc.newDefault ?? "none"}${suffix}`)}`)];
+	}
+	/**
+	* Plan: `~ option k: a → b`, or `! option k: a → b — requires recreation`
+	* for a destructive change. Result: `~ option k: a → b` for an applied
+	* change. Both: `! option k: a → b — skipped (safe mode)` when pending.
+	*/
+	printOptionChanges(c, mode) {
+		const skipped = this.skipped.includes("table-options");
+		return this.optionChanges.map((oc) => {
+			if (oc.destructive && skipped) return `      ${c.red("!")} ${c.cyan(`option ${oc.key}`)}: ${oc.oldValue} → ${oc.newValue} — skipped (safe mode)`;
+			if (mode === "result") return `      ${c.cyan(`~ option ${oc.key}: ${oc.oldValue} → ${oc.newValue}`)}`;
+			const tag = oc.destructive ? c.red("!") : c.yellow("~");
+			const action = oc.destructive ? " — requires recreation" : "";
+			return `      ${tag} ${c.cyan(`option ${oc.key}`)}: ${oc.oldValue} → ${oc.newValue}${action}`;
+		});
+	}
+	/** `· after: a, b` (plan only — the executor already runs in this order). */
+	printDependsOn(c) {
+		if (this.dependsOn.length === 0) return [];
+		return [`      ${c.dim(`· after: ${this.dependsOn.join(", ")}`)}`];
+	}
+	printDropGroup(c) {
+		const others = this.dropGroup?.filter((n) => n !== this.name) ?? [];
+		if (others.length === 0) return [];
+		return [`      ${c.dim(`· dropped with: ${others.join(", ")}`)}`];
 	}
 	printPlan(c) {
 		const { label, vp } = this.labelAndPrefix(c);
 		if (this.status === "error") return this.printError(c, label, vp);
 		if (this.status === "drop") {
 			const kind = this.viewType ? "drop view" : "drop table";
-			return [`  ${c.red(`- ${vp}${label} — ${kind}`)}`];
+			return [
+				`  ${c.red(`- ${vp}${label} — ${kind}`)}`,
+				...this.printDependsOn(c),
+				...this.printDropGroup(c)
+			];
 		}
 		if (this.status === "create") return [
 			`  ${c.green(`+ ${vp}${label} — create`)}`,
 			...this.columnsToAdd.map((col) => `      ${c.green(`+ ${col.physicalName} (${col.designType})${col.isPrimaryKey ? " PK" : ""}${col.optional ? " nullable" : ""} — add`)}`),
+			...this.printDependsOn(c),
 			""
 		];
 		if (this.status === "alter") {
@@ -530,21 +747,15 @@ var SyncEntry = class {
 				`  ${c.cyan(`~ ${vp}${label} — alter${renameInfo}`)}`,
 				...this.columnsToAdd.map((col) => `      ${c.green(`+ ${col.physicalName} (${col.designType}) — add`)}`),
 				...this.columnsToRename.map((r) => `      ${c.yellow(`~ ${r.from} → ${r.to} — rename`)}`),
-				...this.typeChanges.map((tc) => {
-					const action = this.syncMethod ? ` — ${this.syncMethod}` : " — requires migration";
-					return `      ${c.red(`! ${tc.column}: ${tc.fromType} → ${tc.toType}${action}`)}`;
-				}),
-				...this.nullableChanges.map((nc) => `      ${c.yellow(`~ ${nc.column} — ${nc.toNullable ? "nullable" : "non-nullable"}`)}`),
-				...this.defaultChanges.map((dc) => `      ${c.yellow(`~ ${dc.column} — default ${dc.oldDefault ?? "none"} → ${dc.newDefault ?? "none"}`)}`),
+				...this.printTypeChanges(c),
+				...this.printNullableDefaults(c),
+				...this.printPkChange(c, "plan"),
 				...this.columnsToDrop.map((col) => `      ${c.red(`- ${col} — drop`)}`),
-				...this.optionChanges.map((oc) => {
-					const tag = oc.destructive ? c.red("!") : c.yellow("~");
-					const action = oc.destructive ? " — requires recreation" : "";
-					return `      ${tag} ${c.cyan(`option ${oc.key}`)}: ${oc.oldValue} → ${oc.newValue}${action}`;
-				}),
+				...this.printOptionChanges(c, "plan"),
 				...this.fkAdded.map((fk) => `      ${c.green(`+ FK(${fk.fields.join(",")}) → ${fk.targetTable} — add`)}`),
 				...this.fkRemoved.map((fk) => `      ${c.red(`- FK(${fk.fields.join(",")}) → ${fk.targetTable} — remove`)}`),
 				...this.fkChanged.map((fk) => `      ${c.yellow(`~ FK(${fk.fields.join(",")}) → ${fk.targetTable} — ${fk.details}`)}`),
+				...this.printDependsOn(c),
 				""
 			];
 		}
@@ -555,22 +766,25 @@ var SyncEntry = class {
 		if (this.status === "error") return this.printError(c, label, vp);
 		if (this.status === "drop") {
 			const kind = this.viewType ? "dropped view" : "dropped table";
-			return [`  ${c.red(`- ${vp}${label} — ${kind}`)}`];
+			return [`  ${c.red(`- ${vp}${label} — ${kind}`)}`, ...this.printDropGroup(c)];
 		}
 		if (this.status === "create") return [
 			`  ${c.green(`+ ${vp}${label} — created`)}`,
 			...this.columnsAdded.map((col) => `      ${c.green(`+ ${col} — added`)}`),
 			""
 		];
-		if (this.columnsAdded.length > 0 || this.columnsRenamed.length > 0 || this.columnsDropped.length > 0 || this.optionChanges.length > 0 || this.recreated || this.renamedFrom) {
+		if (this.columnsAdded.length > 0 || this.columnsRenamed.length > 0 || this.columnsDropped.length > 0 || this.optionChanges.length > 0 || this.pkChange !== void 0 || this.skipped.length > 0 || this.recreated || this.renamedFrom) {
 			const rlabel = this.recreated ? "recreated" : "altered";
 			const renameInfo = this.renamedFrom ? ` ${c.yellow(`(renamed from ${this.renamedFrom})`)}` : "";
 			return [
 				`  ${(this.recreated ? (s) => c.yellow(s) : (s) => c.cyan(s))(`~ ${vp}${label} — ${rlabel}${renameInfo}`)}`,
 				...this.columnsAdded.map((col) => `      ${c.green(`+ ${col} — added`)}`),
 				...this.columnsRenamed.map((col) => `      ${c.yellow(`~ ${col} — renamed`)}`),
+				...this.printPkChange(c, "result"),
+				...this.printTypeChanges(c),
+				...this.printNullableDefaults(c),
 				...this.columnsDropped.map((col) => `      ${c.red(`- ${col} — dropped`)}`),
-				...this.optionChanges.map((oc) => `      ${c.cyan(`~ option ${oc.key}: ${oc.oldValue} → ${oc.newValue}`)}`),
+				...this.printOptionChanges(c, "result"),
 				""
 			];
 		}
@@ -592,88 +806,94 @@ async function viewDefinitionChanged(view, store) {
 	const currentHash = computeTableHash(computeViewSnapshot(view));
 	return computeTableHash(storedSnapshot) !== currentHash;
 }
-async function executeSyncTable(readable, safe, trackedNames, deps) {
+async function executeSyncTable(facts, safe, deps, exec) {
+	const { readable, name, storedSnapshot, fkDiff } = facts;
 	const adapter = readable.dbAdapter;
-	const name = readable.tableName;
 	const init = {
 		name,
 		status: "in-sync",
-		syncMethod: readable.syncMethod
+		syncMethod: readable.syncMethod,
+		dependsOn: exec.dependsOn
 	};
-	if (readable.renamedFrom && trackedNames.has(readable.renamedFrom) && adapter.renameTable) {
-		await adapter.renameTable(readable.renamedFrom);
-		init.renamedFrom = readable.renamedFrom;
+	const ensureOpts = exec.deferForeignKeysTo ? { deferForeignKeysTo: exec.deferForeignKeysTo } : void 0;
+	if (facts.pendingRename && adapter.renameTable) {
+		await adapter.renameTable(facts.pendingRename);
+		init.renamedFrom = facts.pendingRename;
 		init.status = "alter";
 	}
-	let fkDiff;
-	const fkSnapshotName = init.renamedFrom ?? name;
-	const storedSnapshot = await deps.store.readTableSnapshot(fkSnapshotName);
-	if (storedSnapshot) fkDiff = computeForeignKeyDiff(readable.foreignKeys, storedSnapshot.foreignKeys);
 	const hasFkChanges = fkDiff ? hasForeignKeyChanges(fkDiff) : false;
 	if (adapter.getExistingColumns && adapter.syncColumns) {
-		const existing = await adapter.getExistingColumns();
+		const existing = facts.existing ?? await adapter.getExistingColumns();
 		if (existing.length === 0 && !init.renamedFrom) {
-			await adapter.ensureTable();
+			await adapter.ensureTable(ensureOpts);
 			init.status = "create";
-		} else if (existing.length > 0) if (hasFkChanges && !init.recreated && !adapter.syncForeignKeys && adapter.recreateTable) {
-			await adapter.recreateTable();
-			init.recreated = true;
-			init.status = "alter";
-		} else {
-			if (hasFkChanges && fkDiff && adapter.dropForeignKeys) {
-				const keysToDrop = [...fkDiff.removed.map((fk) => fkKey(fk.fields)), ...fkDiff.changed.map((fk) => fkKey(fk.desired.fields))];
-				if (keysToDrop.length > 0) {
-					await adapter.dropForeignKeys(keysToDrop);
-					init.status = "alter";
+		} else if (existing.length > 0) {
+			const diff = facts.diff ?? computeColumnDiff(readable.fieldDescriptors, existing, adapter.typeMapper?.bind(adapter));
+			if (hasFkChanges && !adapter.syncForeignKeys && adapter.recreateTable) {
+				await adapter.recreateTable();
+				init.recreated = true;
+				init.status = "alter";
+				if (diff.primaryKeyChanged) init.pkChange = {
+					...diff.primaryKeyChanged,
+					rebuild: true
+				};
+			} else {
+				if (hasFkChanges && fkDiff && adapter.dropForeignKeys) {
+					const keysToDrop = [...fkDiff.removed.map((fk) => fkKey(fk.fields)), ...fkDiff.changed.map((fk) => fkKey(fk.desired.fields))];
+					if (keysToDrop.length > 0) {
+						await adapter.dropForeignKeys(keysToDrop);
+						init.status = "alter";
+					}
 				}
+				await applyColumnDiff(adapter, readable, diff, init, safe, deps.logger, ensureOpts);
 			}
-			const typeMapper = adapter.typeMapper?.bind(adapter);
-			await applyColumnDiff(adapter, readable, computeColumnDiff(readable.fieldDescriptors, existing, typeMapper), init, safe, deps.logger);
 		}
 	} else if (adapter.syncColumns) if (!storedSnapshot) {
 		const existed = adapter.tableExists ? await adapter.tableExists() : false;
-		await adapter.ensureTable();
+		await adapter.ensureTable(ensureOpts);
 		if (!existed) init.status = "create";
-	} else {
-		const existing = snapshotToExistingColumns(storedSnapshot);
-		await applyColumnDiff(adapter, readable, computeColumnDiff(readable.fieldDescriptors, existing, deps.resolveTypeMapper(adapter)), init, safe, deps.logger);
-	}
+	} else await applyColumnDiff(adapter, readable, facts.diff ?? computeColumnDiff(readable.fieldDescriptors, snapshotToExistingColumns(storedSnapshot), deps.resolveTypeMapper(adapter)), init, safe, deps.logger, ensureOpts);
 	else {
 		const existed = adapter.tableExists ? await adapter.tableExists() : true;
 		if (!init.recreated) {
-			await adapter.ensureTable();
+			await adapter.ensureTable(ensureOpts);
 			if (!existed) init.status = "create";
 		}
 	}
-	if (init.status !== "create" && !init.recreated && !safe) {
-		const optionDiff = await deps.diffTableOptions(readable);
-		if (optionDiff && optionDiff.changed.length > 0) {
+	const optionDiff = facts.optionDiff;
+	if (init.status !== "create" && !init.recreated && init.status !== "error" && optionDiff && optionDiff.changed.length > 0) {
+		const hasDestructive = optionDiff.changed.some((c) => c.destructive);
+		if (safe) {
+			if (hasDestructive) {
+				init.optionChanges = optionDiff.changed;
+				init.status = "alter";
+				markSkipped(init, "table-options");
+				deps.logger.warn?.(`[schema-sync] Destructive table option change on "${name}" — recreate skipped (safe mode)`);
+			}
+		} else {
 			init.optionChanges = optionDiff.changed;
-			const hasDestructive = optionDiff.changed.some((c) => c.destructive);
 			const nonDestructive = optionDiff.changed.filter((c) => !c.destructive);
 			if (nonDestructive.length > 0 && adapter.applyTableOptions) {
 				await adapter.applyTableOptions(nonDestructive);
 				init.status = "alter";
 			}
 			if (hasDestructive) {
-				if (readable.syncMethod === "recreate" && adapter.recreateTable) {
+				if (willDropRecreate(readable, void 0, optionDiff)) {
+					deps.logger.warn?.(`[schema-sync] Destructive table option change on "${name}" — dropping and recreating`);
+					await dropAndRecreate(adapter, init, name, deps.logger, ensureOpts);
+				} else if (readable.syncMethod === "recreate" && adapter.recreateTable) {
 					deps.logger.warn?.(`[schema-sync] Destructive table option change on "${name}" — recreating with data preservation`);
 					await adapter.recreateTable();
 					init.status = "alter";
 					init.recreated = true;
-				} else if (adapter.dropTable) {
-					deps.logger.warn?.(`[schema-sync] Destructive table option change on "${name}" — dropping and recreating`);
-					await adapter.dropTable();
-					await adapter.ensureTable();
-					init.status = "alter";
-					init.recreated = true;
 				}
 			}
 		}
 	}
+	if (init.status === "error") return new SyncEntry(init);
 	try {
 		await adapter.syncIndexes();
-		if (adapter.syncForeignKeys) await adapter.syncForeignKeys();
+		if (adapter.syncForeignKeys && !exec.deferForeignKeysTo) await adapter.syncForeignKeys();
 		if (adapter.afterSyncTable) await adapter.afterSyncTable();
 	} catch (error) {
 		const msg = `Index/FK sync failed on ${name}: ${error.message}`;
@@ -683,6 +903,28 @@ async function executeSyncTable(readable, safe, trackedNames, deps) {
 	}
 	return new SyncEntry(init);
 }
+/**
+* Deferred foreign-key pass for the members of a foreign-key cycle: runs
+* `syncForeignKeys()` (which adds every FK missing from the live table) now
+* that all members exist. A failure turns the table's entry into an error
+* entry — the run continues and the hash is withheld.
+*/
+async function executeDeferredForeignKeys(readable, entry, deps) {
+	const adapter = readable.dbAdapter;
+	if (!adapter.syncForeignKeys || entry.status === "error") return entry;
+	try {
+		await adapter.syncForeignKeys();
+		return entry;
+	} catch (error) {
+		const msg = `FK sync failed on ${readable.tableName}: ${error.message}`;
+		deps.logger.error?.(`[schema-sync] ${msg}`);
+		return new SyncEntry({
+			...entry.toInit(),
+			status: "error",
+			errors: [...entry.errors, msg]
+		});
+	}
+}
 /** Determines whether a view's predecessor (on rename) or stale definition must be dropped. */
 async function planViewSync(view, trackedNames, store) {
 	const isRenamed = !!(view.renamedFrom && trackedNames.has(view.renamedFrom));
@@ -696,27 +938,114 @@ async function dropOutdatedView(view, plan, space) {
 	if (plan.isRenamed) await space.dropViewByName(view.renamedFrom);
 	else if (plan.definitionChanged) await space.dropViewByName(view.tableName);
 }
-async function executeSyncView(view, trackedNames, deps, plan) {
-	if (!plan) {
-		plan = await planViewSync(view, trackedNames, deps.store);
-		await dropOutdatedView(view, plan, deps.space);
-	}
-	const { isRenamed, definitionChanged } = plan;
+/** Status a managed view's entry gets for a given plan. */
+function viewPlanStatus(view, plan, trackedNames) {
+	if (plan.isRenamed || plan.definitionChanged) return "alter";
+	return trackedNames.has(view.tableName) ? "in-sync" : "create";
+}
+/**
+* Creates (or recreates) a managed view. The stale/renamed predecessor was
+* dropped by `SchemaSync.execute()` before the table ops; `planned` is the
+* entry discovery computed for it and is returned as the run entry.
+*/
+async function executeSyncView(view, planned) {
 	await view.dbAdapter.ensureTable();
-	const viewType = view.viewPlan.materialized ? "M" : "V";
-	let status;
-	if (isRenamed || definitionChanged) status = "alter";
-	else if (trackedNames.has(view.tableName)) status = "in-sync";
-	else status = "create";
-	return new SyncEntry({
-		name: view.tableName,
-		status,
-		viewType,
-		renamedFrom: isRenamed ? view.renamedFrom : void 0,
-		recreated: definitionChanged || void 0
-	});
+	return planned;
+}
+/** The plan-shaped summary of a diff's type changes (`entry.typeChanges`). */
+function describeTypeChanges(diff) {
+	return diff.typeChanged.map((tc) => ({
+		column: tc.field.physicalName,
+		fromType: tc.existingType,
+		toType: tc.field.designType
+	}));
+}
+/**
+* Whether the run drops and recreates this table's physical table — the two
+* `dropAndRecreate` sites: a `@db.sync.method "drop"` type change (`diff`),
+* or a destructive table-option change (`optionDiff`) on a table that does
+* not resolve it with `@db.sync.method "recreate"` (PostgreSQL / MySQL
+* `recreateTable` handle inbound FKs themselves, so `'recreate'` is not a
+* trigger). Both need `dropTable`. One predicate for discovery (which
+* schedules the removed tables that block the drop right before it — both
+* halves are covered since 0.1.128) and for the executor, whose two sites
+* each pass the half they decide and perform the drop — or, in safe mode,
+* record it as skipped — so they cannot drift.
+*/
+function willDropRecreate(readable, diff, optionDiff) {
+	const adapter = readable.dbAdapter;
+	if (!adapter.dropTable) return false;
+	if (readable.syncMethod === "drop" && (diff?.typeChanged.length ?? 0) > 0) return true;
+	return (optionDiff?.changed.some((c) => c.destructive) ?? false) && !(readable.syncMethod === "recreate" && !!adapter.recreateTable);
 }
-async function applyColumnDiff(adapter, readable, diff, init, safe, logger) {
+/** Records work safe mode skipped on the entry (see `SyncEntry.skipped`). */
+function markSkipped(init, kind) {
+	init.skipped = [...init.skipped ?? [], kind];
+}
+/** Whether nullable/default changes need DDL on this adapter (schema-less ones only update the snapshot). */
+function needsDdlForNullableDefaults(adapter) {
+	return !!adapter.supportsColumnModify && !!adapter.syncColumns || !!adapter.recreateTable;
+}
+/**
+* The work `run({ safe: true })` skips on this table, in the order the
+* executor records it — the plan's safe branch reports exactly what the run
+* reports. A recreate that runs even in safe mode (an FK change on an adapter
+* without `syncForeignKeys`, a `'recreate'` type change) carries every other
+* change with it, so nothing is skipped then; an errored plan entry issues no
+* DDL either way.
+*/
+function safeModeSkips(facts) {
+	const { readable, diff, optionDiff, fkDiff } = facts;
+	const adapter = readable.dbAdapter;
+	const out = [];
+	if (facts.planEntry.status === "error") return out;
+	if (fkDiff && hasForeignKeyChanges(fkDiff) && !adapter.syncForeignKeys && adapter.recreateTable) return out;
+	let recreated = false;
+	if (diff && diff.typeChanged.length > 0) {
+		if (willDropRecreate(readable, diff, void 0)) out.push("recreate");
+		else if (readable.syncMethod === "recreate" && adapter.recreateTable) recreated = true;
+	}
+	if (recreated) return out;
+	if (diff && (diff.nullableChanged.length > 0 || diff.defaultChanged.length > 0) && needsDdlForNullableDefaults(adapter)) out.push("nullable-defaults");
+	if (diff?.primaryKeyChanged) out.push("pk-rebuild");
+	if (optionDiff?.changed.some((c) => c.destructive)) out.push("table-options");
+	return out;
+}
+/** The plan-shaped nullable / default change summaries of a diff. */
+function describeNullableDefaults(diff) {
+	return {
+		nullableChanges: diff.nullableChanged.map((nc) => ({
+			column: nc.field.physicalName,
+			toNullable: nc.field.optional
+		})),
+		defaultChanges: diff.defaultChanged.map((dc) => ({
+			column: dc.field.physicalName,
+			oldDefault: dc.oldDefault,
+			newDefault: dc.newDefault
+		}))
+	};
+}
+/**
+* `dropTable()` + `ensureTable()` for `@db.sync.method "drop"` and destructive
+* option changes. Sync-owned drops never CASCADE: when something outside the
+* sync inventory (a user view, an unmanaged FK) still depends on the table the
+* engine refuses, and that becomes an error entry for this table — not a
+* thrown run.
+*/
+async function dropAndRecreate(adapter, init, name, logger, ensureOpts) {
+	try {
+		await adapter.dropTable();
+		await adapter.ensureTable(ensureOpts);
+		init.recreated = true;
+		init.status = "alter";
+	} catch (error) {
+		const msg = `Drop of "${name}" failed: ${error.message}`;
+		logger.error?.(`[schema-sync] ${msg}`);
+		init.errors = [...init.errors ?? [], msg];
+		init.status = "error";
+	}
+}
+async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensureOpts) {
 	const name = readable.tableName;
 	if (diff.conflicts.length > 0) {
 		const errors = diff.conflicts.map((c) => `Column rename conflict on ${name}: cannot rename "${c.oldName}" → "${c.field.physicalName}" because "${c.conflictsWith}" already exists.`);
@@ -727,12 +1056,14 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger) {
 	let needsSyncColumns = false;
 	if (diff.typeChanged.length > 0 && init.status !== "error") {
 		const syncMethod = readable.syncMethod;
-		if (syncMethod === "drop" && adapter.dropTable) {
-			await adapter.dropTable();
-			await adapter.ensureTable();
-			init.recreated = true;
+		if (willDropRecreate(readable, diff, void 0)) if (safe) {
+			init.typeChanges = describeTypeChanges(diff);
+			markSkipped(init, "recreate");
 			init.status = "alter";
-		} else if (syncMethod === "recreate" && adapter.recreateTable) {
+			const cols = init.typeChanges.map((tc) => `${tc.column}: ${tc.fromType} → ${tc.toType}`).join(", ");
+			logger.warn?.(`[schema-sync] Type change on "${name}" (${cols}) — drop-and-recreate skipped (safe mode)`);
+		} else await dropAndRecreate(adapter, init, name, logger, ensureOpts);
+		else if (syncMethod === "recreate" && adapter.recreateTable) {
 			await adapter.recreateTable();
 			init.recreated = true;
 			init.status = "alter";
@@ -750,21 +1081,69 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger) {
 			init.status = "error";
 		}
 	}
-	if (!safe && !init.recreated && init.status !== "error" && (diff.nullableChanged.length > 0 || diff.defaultChanged.length > 0)) if (adapter.supportsColumnModify && adapter.syncColumns) {
-		needsSyncColumns = true;
-		init.status = "alter";
-	} else if (adapter.recreateTable) {
-		await adapter.recreateTable();
-		init.recreated = true;
-		init.status = "alter";
-	} else init.status = "alter";
-	else if (diff.nullableChanged.length > 0 || diff.defaultChanged.length > 0) init.status = "alter";
+	if (diff.nullableChanged.length > 0 || diff.defaultChanged.length > 0) {
+		if (!safe && !init.recreated && init.status !== "error") if (adapter.supportsColumnModify && adapter.syncColumns) {
+			needsSyncColumns = true;
+			init.status = "alter";
+		} else if (adapter.recreateTable) {
+			await adapter.recreateTable();
+			init.recreated = true;
+			init.status = "alter";
+		} else init.status = "alter";
+		else if (init.status !== "error") {
+			if (safe && !init.recreated && needsDdlForNullableDefaults(adapter)) {
+				Object.assign(init, describeNullableDefaults(diff));
+				markSkipped(init, "nullable-defaults");
+				logger.warn?.(`[schema-sync] Nullable/default change on "${name}" — skipped (safe mode)`);
+			}
+			init.status = "alter";
+		}
+	}
 	if (!init.recreated && init.status !== "error" && (diff.added.length > 0 || diff.renamed.length > 0 || needsSyncColumns) && adapter.syncColumns) {
 		const syncResult = await adapter.syncColumns(diff);
 		init.columnsAdded = syncResult.added;
 		init.columnsRenamed = syncResult.renamed;
 		if (syncResult.added.length > 0 || (syncResult.renamed?.length ?? 0) > 0 || needsSyncColumns) init.status = "alter";
 	}
+	if (diff.primaryKeyChanged && init.status !== "error") {
+		const { from, to } = diff.primaryKeyChanged;
+		const label = `(${from.join(", ")} → ${to.join(", ")})`;
+		if (init.recreated) init.pkChange = {
+			from,
+			to,
+			rebuild: true
+		};
+		else if (safe) {
+			logger.warn?.(`[schema-sync] Primary key of "${name}" changed ${label} — rebuild skipped (safe mode)`);
+			init.pkChange = {
+				from,
+				to,
+				rebuild: false
+			};
+			markSkipped(init, "pk-rebuild");
+			init.status = "alter";
+		} else if (adapter.rebuildPrimaryKey || adapter.recreateTable) {
+			if (adapter.rebuildPrimaryKey) await adapter.rebuildPrimaryKey({
+				from,
+				to
+			});
+			else {
+				await adapter.recreateTable();
+				init.recreated = true;
+			}
+			init.pkChange = {
+				from,
+				to,
+				rebuild: true
+			};
+			init.status = "alter";
+		} else {
+			const msg = `Primary key of "${name}" changed ${label} but the adapter cannot rebuild primary keys. Migrate manually and re-run.`;
+			logger.error?.(`[schema-sync] ${msg}`);
+			init.errors = [...init.errors ?? [], msg];
+			init.status = "error";
+		}
+	}
 	if (!safe && !init.recreated && init.status !== "error" && diff.removed.length > 0 && adapter.dropColumns) {
 		const colNames = diff.removed.map((c) => c.name);
 		if (adapter.dropIndexesForColumns) await adapter.dropIndexesForColumns(colNames);
@@ -775,6 +1154,10 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger) {
 }
 //#endregion
 //#region src/schema/schema-sync.ts
+/** Keeps a removed-table group tracked (safe mode, blocked or failed drop). */
+function retain(group, ctx) {
+	ctx.retained.push(...group.map((name) => ctx.d.removedByName.get(name)));
+}
 /** Builds a human-readable description of what changed in an FK constraint. */
 function buildFkChangeDetails(desired, existing) {
 	const parts = [];
@@ -784,6 +1167,49 @@ function buildFkChangeDetails(desired, existing) {
 	if ((existing.onUpdate ?? void 0) !== (desired.onUpdate ?? void 0)) parts.push(`onUpdate ${existing.onUpdate ?? "noAction"} → ${desired.onUpdate ?? "noAction"}`);
 	return parts.join(", ");
 }
+function pkLabel(change) {
+	return `(${change.from.join(", ")} → ${change.to.join(", ")})`;
+}
+function sortedUnique(names) {
+	return [...new Set(names)].toSorted();
+}
+/** Adds `msg` to the refusal list of `name`. */
+function addRefusal(refusals, name, msg) {
+	const list = refusals.get(name);
+	if (list) list.push(msg);
+	else refusals.set(name, [msg]);
+}
+/** The entry with the refusal texts folded in as a refused `error` entry. */
+function withRefusals(init, msgs) {
+	if (!msgs || msgs.length === 0) return new SyncEntry(init);
+	return new SyncEntry({
+		...init,
+		status: "error",
+		errors: [...init.errors ?? [], ...msgs],
+		refused: true
+	});
+}
+/** Human label of each kind of skipped work, for the safe-mode warning. */
+const SKIPPED_LABELS = {
+	"pk-rebuild": "primary-key rebuild",
+	recreate: "drop-and-recreate",
+	"table-options": "table-option recreate",
+	"nullable-defaults": "nullable/default change"
+};
+/**
+* The removed tables whose drop must precede `t`'s own drop/rebuild: those
+* with a live FK to `t` (its probed inbound FKs; when the adapter cannot
+* probe them, the removed tables' stored snapshots — the same fallback as
+* the drop graph), closed over the removed-table graph (child → parent) so
+* a referencer's own removed children come first.
+*/
+function removedBlockers(t, removedTables, removedTableSet, dropEdges) {
+	const direct = [];
+	if (t.inboundFks) {
+		for (const fk of t.inboundFks) if (removedTableSet.has(fk.table)) direct.push(fk.table);
+	} else for (const r of removedTables) if (r.snapshot && "foreignKeys" in r.snapshot && r.snapshot.foreignKeys.some((fk) => fk.targetTable === t.dbName)) direct.push(r.name);
+	return reachable(direct, dropEdges);
+}
 var SchemaSync = class {
 	space;
 	store;
@@ -806,7 +1232,7 @@ var SchemaSync = class {
 			if (readable.isView) {
 				const view = readable;
 				if (view.isExternal) externalViews.push(view);
-				else views.push(readable);
+				else views.push(view);
 			} else tables.push(readable);
 		}
 		const allReadables = [
@@ -871,20 +1297,13 @@ var SchemaSync = class {
 		});
 	}
 	/**
-	* Detects tables/views present in the previous sync but absent from the current schema.
-	* Returns SyncEntry instances with status 'drop'.
+	* Detects tables/views present in the previous sync but absent from the
+	* current schema (external views excluded — sync owns no DDL for them).
 	*/
-	async detectRemoved(currentReadables, previous) {
-		previous ??= await this.store.readTrackedList();
+	detectRemoved(currentReadables, previous) {
 		const currentSet = new Set(currentReadables.map((t) => t.tableName));
 		const renameFromSet = new Set(currentReadables.map((r) => r.renamedFrom).filter(Boolean));
-		const removed = [];
-		for (const entry of previous) if (!currentSet.has(entry.name) && !renameFromSet.has(entry.name)) removed.push(new SyncEntry({
-			name: entry.name,
-			viewType: entry.viewType,
-			status: "drop"
-		}));
-		return removed;
+		return previous.filter((entry) => !currentSet.has(entry.name) && !renameFromSet.has(entry.name) && entry.viewType !== "E");
 	}
 	/**
 	* Starts a periodic heartbeat that extends the lock's TTL while sync runs.
@@ -927,7 +1346,19 @@ var SchemaSync = class {
 		if (reason) throw new Error(reason);
 	}
 	/**
-	* Runs schema synchronization with distributed locking.
+	* Runs schema synchronization with distributed locking, in three phases:
+	*
+	* 1. **Discover** (read-only, under the lock): introspect every table once,
+	*    diff columns/FKs, read tracking, build the dependency graph.
+	* 2. **Pre-flight** (pure): every change that no order of DDL can apply
+	*    safely becomes a refusal. One refusal → `status: "refused"`, no DDL,
+	*    nothing persisted, lock released.
+	* 3. **Execute** in dependency order: stale/removed views → inbound FKs of
+	*    key-changing tables → tables (parents first; a removed table that
+	*    blocks a table's drop-and-recreate or key rebuild is dropped right
+	*    before it) → deferred FKs of cycles → managed views → external-view
+	*    checks → remaining removed tables (children first) →
+	*    snapshots/tracking/hash.
 	*/
 	async run(types, opts) {
 		this.logger = opts?.logger ?? this.logger;
@@ -937,7 +1368,9 @@ var SchemaSync = class {
 		const pollIntervalMs = opts?.pollIntervalMs ?? 500;
 		const force = opts?.force ?? false;
 		const safe = opts?.safe ?? false;
-		const { tables, views, externalViews, hash } = await this.resolveAndHash(types);
+		const onError = opts?.onError ?? "warn";
+		const resolved = await this.resolveAndHash(types);
+		const { hash } = resolved;
 		await this.store.ensureControlTable();
 		if (!force) {
 			if (await this.store.readHash() === hash) return {
@@ -964,163 +1397,151 @@ var SchemaSync = class {
 					entries: []
 				};
 			}
-			const allReadables = [
-				...tables,
-				...views,
-				...externalViews
-			];
-			const previouslyTracked = await this.store.readTrackedList();
-			const trackedNames = new Set(previouslyTracked.map((e) => e.name));
-			const deps = this.buildExecutorDeps();
-			const viewPlans = /* @__PURE__ */ new Map();
-			for (const readable of views) {
-				const view = readable;
-				const plan = await planViewSync(view, trackedNames, this.store);
-				viewPlans.set(view.tableName, plan);
-				await dropOutdatedView(view, plan, this.space);
-			}
-			const entries = [];
-			for (const readable of tables) {
-				this.assertLockHeld(heartbeat.getAbortReason);
-				entries.push(await executeSyncTable(readable, safe, trackedNames, deps));
-			}
-			this.assertLockHeld(heartbeat.getAbortReason);
-			const removed = await this.detectRemoved(allReadables, previouslyTracked);
-			for (const readable of views) {
-				this.assertLockHeld(heartbeat.getAbortReason);
-				entries.push(await executeSyncView(readable, trackedNames, deps, viewPlans.get(readable.tableName)));
-			}
-			const externalEntries = await Promise.all(externalViews.map((v) => this.checkExternalView(v)));
-			entries.push(...externalEntries);
-			this.assertLockHeld(heartbeat.getAbortReason);
-			if (!safe) {
-				for (const entry of removed) {
-					if (entry.viewType === "E") continue;
-					if (entry.viewType) await this.space.dropViewByName(entry.name);
-					else await this.space.dropTableByName(entry.name);
-				}
-				entries.push(...removed.filter((e) => e.viewType !== "E"));
-			}
+			const d = await this.discover(resolved, safe);
 			this.assertLockHeld(heartbeat.getAbortReason);
-			const erroredNames = new Set(entries.filter((e) => e.status === "error" && e.viewType !== "E").map((e) => e.name));
-			for (const readable of allReadables) {
-				if (erroredNames.has(readable.tableName)) continue;
-				const adapter = readable.dbAdapter;
-				const tm = adapter.typeMapper?.bind(adapter);
-				const opts = adapter.getDesiredTableOptions?.();
-				const snapshot = readable.isView ? computeViewSnapshot(readable) : computeTableSnapshot(readable, tm, opts);
-				await this.store.writeTableSnapshot(readable.tableName, snapshot);
-			}
-			if (!safe) for (const entry of removed) {
-				if (entry.viewType === "E") continue;
-				await this.store.deleteTableSnapshot(entry.name);
+			const refusals = this.preflight(d, safe);
+			if (refusals.size > 0) {
+				const result = {
+					status: "refused",
+					schemaHash: hash,
+					entries: this.buildPlanEntries(d, safe, refusals)
+				};
+				this.reportOutcome(result, onError);
+				return result;
 			}
-			for (const readable of allReadables) if (readable.renamedFrom) await this.store.deleteTableSnapshot(readable.renamedFrom);
-			await this.store.writeTrackedList(allReadables);
-			if (erroredNames.size === 0) await this.store.writeHash(hash);
-			const result = {
-				status: "synced",
-				schemaHash: hash,
-				entries
-			};
-			this.reportOutcome(result, opts?.onError ?? "warn");
+			const result = await this.execute(d, safe, heartbeat.getAbortReason);
+			this.reportOutcome(result, onError);
 			return result;
 		} finally {
 			heartbeat.stop();
 			await this.store.releaseLock(podId);
 		}
 	}
-	/**
-	* Surfaces the run outcome per the `onError` policy. Reporting must never be
-	* silently lost to the NoopLogger default — when no real logger is
-	* configured, warnings/errors go to `console` (a production consumer lost
-	* months of failed-index errors to the silent default).
-	*/
-	reportOutcome(result, onError) {
-		if (onError === "silent" || result.entries.length === 0) return;
-		const out = this.logger === require_db_view.NoopLogger ? console : this.logger;
-		const counts = /* @__PURE__ */ new Map();
-		for (const entry of result.entries) counts.set(entry.status, (counts.get(entry.status) ?? 0) + 1);
-		const summary = [...counts.entries()].map(([status, n]) => `${n} ${status}`).join(", ");
-		out.log(`[schema-sync] ${result.status}: ${summary}`);
-		const errored = result.entries.filter((e) => e.hasErrors);
-		if (errored.length === 0) return;
-		const lines = errored.map((e) => `[schema-sync] "${e.name}" failed: ${e.errors.join("; ") || e.status}`);
-		for (const line of lines) out.error(line);
-		if (onError === "throw") throw new Error(`[schema-sync] ${errored.length} entr${errored.length === 1 ? "y" : "ies"} failed:\n${lines.join("\n")}`);
-	}
-	/**
-	* Computes a dry-run plan showing what `run()` would do, without executing any DDL.
-	*/
-	async plan(types, opts) {
-		const force = opts?.force ?? false;
-		const safe = opts?.safe ?? false;
-		const { tables, views, externalViews, hash } = await this.resolveAndHash(types);
+	async discover(resolved, safe) {
+		const { tables, views, externalViews, hash } = resolved;
 		const allReadables = [
 			...tables,
 			...views,
 			...externalViews
 		];
-		await this.store.ensureControlTable();
 		const previouslyTracked = await this.store.readTrackedList();
 		const trackedNames = new Set(previouslyTracked.map((e) => e.name));
-		let planEntries = await Promise.all(tables.map((r) => this.planTable(r, trackedNames)));
-		const viewEntries = await Promise.all(views.map((v) => this.planView(v, trackedNames)));
+		const removedTracked = this.detectRemoved(allReadables, previouslyTracked);
+		const probeRecreateInbound = !safe && removedTracked.some((r) => !r.isView);
+		const tableFacts = await Promise.all(tables.map((r) => this.discoverTable(r, trackedNames, probeRecreateInbound)));
+		const tableNames = new Set(tableFacts.map((t) => t.name));
+		const tableByName = new Map(tableFacts.map((t) => [t.name, t]));
+		const tableByDbName = new Map(tableFacts.map((t) => [t.dbName, t]));
+		const viewFacts = await Promise.all(views.map(async (view) => ({
+			plan: await planViewSync(view, trackedNames, this.store),
+			kind: await view.dbAdapter.getObjectKind?.(view.tableName)
+		})));
+		const viewPlans = /* @__PURE__ */ new Map();
+		const viewEntries = [];
+		const viewObjectKinds = /* @__PURE__ */ new Map();
+		for (const [i, view] of views.entries()) {
+			const { plan, kind } = viewFacts[i];
+			viewPlans.set(view.tableName, plan);
+			viewObjectKinds.set(view.tableName, kind);
+			viewEntries.push(new SyncEntry({
+				name: view.tableName,
+				status: viewPlanStatus(view, plan, trackedNames),
+				viewType: view.viewPlan.materialized ? "M" : "V",
+				renamedFrom: plan.isRenamed ? view.renamedFrom : void 0,
+				recreated: plan.definitionChanged || void 0,
+				dependsOn: sortedUnique([view.viewPlan.entryTable, ...view.viewPlan.joins.map((j) => j.targetTable)].filter((n) => tableNames.has(n)))
+			}));
+		}
 		const externalEntries = await Promise.all(externalViews.map((v) => this.checkExternalView(v)));
-		if (!force) {
-			if (await this.store.readHash() === hash) return {
-				status: "up-to-date",
-				schemaHash: hash,
-				entries: [
-					...planEntries,
-					...viewEntries,
-					...externalEntries
-				]
-			};
+		const probeInbound = !safe && removedTracked.filter((r) => !r.isView).length >= 2;
+		const removed = await Promise.all(removedTracked.map(async (entry) => ({
+			...entry,
+			snapshot: await this.store.readTableSnapshot(entry.name),
+			inbound: probeInbound && !entry.isView ? await this.space.getReferencingForeignKeys(entry.name) : void 0
+		})));
+		const removedByName = new Map(removed.map((r) => [r.name, r]));
+		const externalTargetAdapters = /* @__PURE__ */ new Map();
+		for (const t of tableFacts) for (const fk of t.readable.foreignKeys.values()) if (fk.targetTable !== t.name && !tableNames.has(fk.targetTable)) externalTargetAdapters.set(fk.targetTable, t.readable.dbAdapter);
+		const externalTargets = new Map(await Promise.all([...externalTargetAdapters].map(async ([target, adapter]) => [target, await this.objectPresent(adapter, target)])));
+		const createEdges = [];
+		const tableDependsOn = /* @__PURE__ */ new Map();
+		for (const t of tableFacts) {
+			const parents = /* @__PURE__ */ new Set();
+			for (const fk of t.readable.foreignKeys.values()) if (fk.targetTable !== t.name && tableNames.has(fk.targetTable)) {
+				createEdges.push([t.name, fk.targetTable]);
+				parents.add(fk.targetTable);
+			}
+			tableDependsOn.set(t.name, sortedUnique(parents));
 		}
-		let removed = await this.detectRemoved(allReadables, previouslyTracked);
-		if (safe) {
-			planEntries = planEntries.map((e) => new SyncEntry({
-				name: e.name,
-				viewType: e.viewType,
-				status: e.status,
-				syncMethod: e.syncMethod,
-				columnsToAdd: e.columnsToAdd,
-				columnsToRename: e.columnsToRename,
-				nullableChanges: e.nullableChanges,
-				defaultChanges: e.defaultChanges,
-				optionChanges: e.optionChanges,
-				fkAdded: e.fkAdded,
-				fkRemoved: e.fkRemoved,
-				fkChanged: e.fkChanged,
-				columnsAdded: e.columnsAdded,
-				columnsRenamed: e.columnsRenamed,
-				columnsDropped: e.columnsDropped,
-				errors: e.errors,
-				renamedFrom: e.renamedFrom,
-				columnsToDrop: [],
-				typeChanges: [],
-				recreated: false
-			}));
-			removed = [];
+		const createOrder = topoOrder(tableNames, createEdges);
+		const removedTables = removed.filter((r) => !r.isView);
+		const removedTableSet = new Set(removedTables.map((r) => r.name));
+		const dropEdges = [];
+		for (const r of removedTables) if (r.inbound) {
+			for (const fk of r.inbound) if (fk.table !== r.name && removedTableSet.has(fk.table)) dropEdges.push([fk.table, r.name]);
+		} else if (r.snapshot && "foreignKeys" in r.snapshot) {
+			for (const fk of r.snapshot.foreignKeys) if (fk.targetTable !== r.name && removedTableSet.has(fk.targetTable)) dropEdges.push([r.name, fk.targetTable]);
+		}
+		const dropOrder = topoOrder(removedTableSet, dropEdges).toReversed();
+		const earlyDrops = /* @__PURE__ */ new Map();
+		const earlyGroups = /* @__PURE__ */ new Set();
+		if (!safe) for (const name of createOrder.flat()) {
+			const t = tableByName.get(name);
+			if (!t.dropsTable) continue;
+			const blockers = removedBlockers(t, removedTables, removedTableSet, dropEdges);
+			const groups = dropOrder.filter((group) => !earlyGroups.has(group) && group.some((n) => blockers.has(n)));
+			if (groups.length === 0) continue;
+			for (const group of groups) earlyGroups.add(group);
+			earlyDrops.set(name, groups);
+			tableDependsOn.set(name, sortedUnique([...tableDependsOn.get(name), ...groups.flat()]));
 		}
-		removed = removed.filter((e) => e.viewType !== "E");
+		const lateDropOrder = dropOrder.filter((group) => !earlyGroups.has(group));
+		const dropEntries = /* @__PURE__ */ new Map();
+		for (const r of removed) if (r.isView) dropEntries.set(r.name, new SyncEntry({
+			name: r.name,
+			viewType: r.viewType,
+			status: "drop"
+		}));
+		for (const group of dropOrder) for (const name of group) dropEntries.set(name, new SyncEntry({
+			name,
+			status: "drop",
+			dependsOn: sortedUnique(dropEdges.filter(([, to]) => to === name).map(([from]) => from)),
+			dropGroup: group.length > 1 ? group : void 0
+		}));
 		return {
-			status: "changes-needed",
-			schemaHash: hash,
-			entries: [
-				...planEntries,
-				...viewEntries,
-				...externalEntries,
-				...removed
-			]
+			tables: tableFacts,
+			tableByName,
+			tableByDbName,
+			views,
+			externalViews,
+			allReadables,
+			hash,
+			trackedNames,
+			viewPlans,
+			viewEntries,
+			viewObjectKinds,
+			externalEntries,
+			removed,
+			removedByName,
+			removedTableSet,
+			dropEntries,
+			createOrder,
+			earlyDrops,
+			lateDropOrder,
+			tableDependsOn,
+			externalTargets
 		};
 	}
-	/** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
-	resolveTypeMapper(adapter) {
-		return adapter.typeMapper?.bind(adapter) ?? ((f) => f.designType === "union" ? "union" : f.designType);
+	/** Whether an object named `name` exists, or `undefined` when the adapter cannot tell. */
+	async objectPresent(adapter, name) {
+		return adapter.getObjectKind ? await adapter.getObjectKind(name) !== void 0 : void 0;
 	}
-	async planTable(readable, trackedNames) {
+	/**
+	* Introspects one desired table and computes its plan entry.
+	* `probeRecreateInbound` — whether a drop-and-recreate's live inbound FKs
+	* are worth probing (a removed table exists that could block it).
+	*/
+	async discoverTable(readable, trackedNames, probeRecreateInbound) {
 		const adapter = readable.dbAdapter;
 		const name = readable.tableName;
 		const init = {
@@ -1129,22 +1550,33 @@ var SchemaSync = class {
 			syncMethod: readable.syncMethod
 		};
 		const renamedFrom = readable.renamedFrom;
-		const pendingRename = renamedFrom && trackedNames.has(renamedFrom);
+		const pendingRename = renamedFrom && trackedNames.has(renamedFrom) ? renamedFrom : void 0;
 		if (pendingRename) {
-			init.renamedFrom = renamedFrom;
+			init.renamedFrom = pendingRename;
 			init.status = "alter";
 		}
-		const fkSnapshotName = pendingRename ? renamedFrom : name;
-		const storedSnapshot = await this.store.readTableSnapshot(fkSnapshotName);
+		const dbName = pendingRename ?? name;
+		const storedSnapshot = await this.store.readTableSnapshot(dbName);
+		const facts = {
+			readable,
+			name,
+			pendingRename,
+			dbName,
+			storedSnapshot,
+			fkDiff: storedSnapshot ? computeForeignKeyDiff(readable.foreignKeys, storedSnapshot.foreignKeys) : void 0,
+			dropsTable: false,
+			planEntry: init
+		};
 		if (adapter.getExistingColumns) {
-			const existing = pendingRename && adapter.getExistingColumnsForTable ? await adapter.getExistingColumnsForTable(renamedFrom) : await adapter.getExistingColumns();
-			if (existing.length === 0 && !pendingRename) {
+			const liveColumns = pendingRename ? adapter.getExistingColumnsForTable ? await adapter.getExistingColumnsForTable(pendingRename) : void 0 : await adapter.getExistingColumns();
+			facts.existing = pendingRename && liveColumns?.length === 0 ? void 0 : liveColumns;
+			if (facts.existing && facts.existing.length === 0) {
 				init.status = "create";
 				init.columnsToAdd = readable.fieldDescriptors.filter((f) => !f.ignored);
-			} else if (existing.length > 0) {
+			} else if (facts.existing && facts.existing.length > 0) {
 				const typeMapper = adapter.typeMapper?.bind(adapter);
-				const diff = computeColumnDiff(readable.fieldDescriptors, existing, typeMapper);
-				this.populatePlanFromDiff(diff, init, name, readable.syncMethod, adapter.supportsColumnModify);
+				facts.diff = computeColumnDiff(readable.fieldDescriptors, facts.existing, typeMapper);
+				this.populatePlanFromDiff(facts.diff, init, name, readable.syncMethod, adapter.supportsColumnModify);
 			}
 		} else if (adapter.syncColumns) if (!storedSnapshot) {
 			if (!pendingRename) {
@@ -1155,40 +1587,369 @@ var SchemaSync = class {
 			}
 		} else {
 			const existing = snapshotToExistingColumns(storedSnapshot);
-			const diff = computeColumnDiff(readable.fieldDescriptors, existing, this.resolveTypeMapper(adapter));
-			this.populatePlanFromDiff(diff, init, name, readable.syncMethod, adapter.supportsColumnModify);
+			facts.diff = computeColumnDiff(readable.fieldDescriptors, existing, this.resolveTypeMapper(adapter));
+			this.populatePlanFromDiff(facts.diff, init, name, readable.syncMethod, adapter.supportsColumnModify);
 		}
 		else if (adapter.tableExists) {
 			if (!await adapter.tableExists()) init.status = "create";
 		} else init.status = "create";
 		if (init.status !== "create") {
-			const optionDiff = await this.diffTableOptions(readable);
-			if (optionDiff && optionDiff.changed.length > 0) {
+			facts.optionDiff = await this.diffTableOptions(readable, pendingRename);
+			const optionDiff = facts.optionDiff;
+			if (init.status !== "error" && optionDiff && optionDiff.changed.length > 0) {
 				init.status = "alter";
 				init.optionChanges = optionDiff.changed;
 				if (optionDiff.changed.some((c) => c.destructive)) init.recreated = true;
 			}
 		}
-		if (init.status !== "create" && storedSnapshot) {
-			const fkDiff = computeForeignKeyDiff(readable.foreignKeys, storedSnapshot.foreignKeys);
-			if (hasForeignKeyChanges(fkDiff)) {
-				init.status = "alter";
-				init.fkAdded = fkDiff.added.map((fk) => ({
-					fields: fk.fields,
-					targetTable: fk.targetTable
-				}));
-				init.fkRemoved = fkDiff.removed.map((fk) => ({
-					fields: fk.fields,
-					targetTable: fk.targetTable
-				}));
-				init.fkChanged = fkDiff.changed.map((fk) => ({
-					fields: fk.desired.fields,
-					targetTable: fk.desired.targetTable,
-					details: buildFkChangeDetails(fk.desired, fk.existing)
+		if (init.status !== "create" && init.status !== "error" && facts.fkDiff && hasForeignKeyChanges(facts.fkDiff)) {
+			const fkDiff = facts.fkDiff;
+			init.status = "alter";
+			init.fkAdded = fkDiff.added.map((fk) => ({
+				fields: fk.fields,
+				targetTable: fk.targetTable
+			}));
+			init.fkRemoved = fkDiff.removed.map((fk) => ({
+				fields: fk.fields,
+				targetTable: fk.targetTable
+			}));
+			init.fkChanged = fkDiff.changed.map((fk) => ({
+				fields: fk.desired.fields,
+				targetTable: fk.desired.targetTable,
+				details: buildFkChangeDetails(fk.desired, fk.existing)
+			}));
+		}
+		if (facts.diff?.primaryKeyChanged) facts.populated = await adapter.hasRows(pendingRename ? dbName : void 0) ?? "unknown";
+		facts.dropsTable = !!facts.diff?.primaryKeyChanged || willDropRecreate(readable, facts.diff, facts.optionDiff);
+		if (facts.diff?.primaryKeyChanged || probeRecreateInbound && facts.dropsTable) facts.inboundFks = await adapter.getReferencingForeignKeys?.(dbName);
+		if (adapter.getObjectKind) facts.objectKind = await adapter.getObjectKind(dbName);
+		return facts;
+	}
+	/**
+	* Pure validation over the discovery facts. Every refusal is a change that
+	* no order of DDL can apply safely; the messages are user-facing.
+	*/
+	preflight(d, safe) {
+		const refusals = /* @__PURE__ */ new Map();
+		for (const t of d.tables) {
+			if (t.objectKind === "view" || t.objectKind === "materialized") addRefusal(refusals, t.name, `A view "${t.dbName}" exists where table "${t.name}" is declared — drop or rename it`);
+			const pk = t.diff?.primaryKeyChanged;
+			if (pk) {
+				const label = pkLabel(pk);
+				if (t.populated === true) addRefusal(refusals, t.name, `Primary key of "${t.name}" changed ${label} but the table has rows; schema sync cannot rebuild a populated primary key. Migrate manually (or empty the table) and re-run.`);
+				else if (t.populated === "unknown") addRefusal(refusals, t.name, `Primary key of "${t.name}" changed ${label} but the adapter cannot tell whether the table has rows under its old name "${t.dbName}" — implement hasRows(tableName) on the adapter, or rename the table in a separate run first.`);
+				if (!safe) {
+					for (const fk of t.inboundFks ?? []) {
+						const removed = d.removedByName.get(fk.table);
+						if (removed && !removed.isView) continue;
+						const child = d.tableByDbName.get(fk.table);
+						if (child?.pendingRename) {
+							addRefusal(refusals, t.name, `Primary key of "${t.name}" changed ${label} but the referencing table "${child.name}" is renamed in the same run (from "${child.pendingRename}") — rename it in a separate run first, then retarget the foreign key and re-run.`);
+							continue;
+						}
+						if (!(child !== void 0 && [...child.readable.foreignKeys.values()].some((desired) => desired.targetTable === t.name && fkKey(desired.fields) === fkKey(fk.fields) && fkKey(desired.targetFields) === fkKey(pk.to)))) addRefusal(refusals, t.name, `Primary key of "${t.name}" changed ${label} but "${fk.table}.${fk.fields.join(",")}" still references the old key — retarget the foreign key (or migrate manually) and re-run.`);
+					}
+					for (const f of t.readable.fieldDescriptors) if (!f.ignored && !f.isPrimaryKey && f.defaultValue?.kind === "fn" && f.defaultValue.fn === "increment") addRefusal(refusals, t.name, `"${t.name}.${f.physicalName}" is auto-increment but no longer part of the primary key; auto-increment columns must be primary-key columns.`);
+				}
+			}
+			for (const fk of t.readable.foreignKeys.values()) {
+				if (fk.targetTable === t.name || d.tableByName.has(fk.targetTable)) continue;
+				if (d.externalTargets.get(fk.targetTable) === false) addRefusal(refusals, t.name, `FK ${t.name}.${fk.fields.join(",")} references "${fk.targetTable}" which is neither in the sync inventory nor present in the database`);
+			}
+		}
+		for (const view of d.views) if (d.viewObjectKinds.get(view.tableName) === "table") addRefusal(refusals, view.tableName, `A physical table "${view.tableName}" exists where managed view "${view.tableName}" is declared — drop or rename it`);
+		if (!safe) for (const r of d.removed) {
+			if (r.isView) continue;
+			const referencers = [];
+			for (const t of d.tables) for (const fk of t.readable.foreignKeys.values()) if (fk.targetTable === r.name) referencers.push(`${t.name}.${fk.fields.join(",")} (@db.rel.FK)`);
+			for (const view of d.views) {
+				const plan = view.viewPlan;
+				if (plan.entryTable === r.name || plan.joins.some((j) => j.targetTable === r.name)) referencers.push(`view "${view.tableName}"`);
+			}
+			if (referencers.length > 0) addRefusal(refusals, r.name, `Cannot drop "${r.name}": it is still referenced by ${referencers.join(", ")}. Add "${r.name}" to the sync inventory or remove the reference.`);
+		}
+		return refusals;
+	}
+	/**
+	* The one ordering walk `plan()` and `run()` share: tables parents-first,
+	* each preceded by the removed tables that block its drop/rebuild; the
+	* deferred FK pass; managed views; external-view checks; removed views;
+	* the remaining removed tables children-first.
+	*/
+	*orderedSteps(d) {
+		for (const group of d.createOrder) {
+			const cycle = group.length > 1 ? new Set(group) : void 0;
+			for (const name of group) {
+				for (const early of d.earlyDrops.get(name) ?? []) yield {
+					kind: "drop",
+					group: early
+				};
+				yield {
+					kind: "table",
+					name,
+					cycle
+				};
+			}
+		}
+		yield { kind: "deferred-fks" };
+		for (const [index] of d.views.entries()) yield {
+			kind: "view",
+			index
+		};
+		for (const [index] of d.externalEntries.entries()) yield {
+			kind: "external",
+			index
+		};
+		for (const r of d.removed) if (r.isView) yield {
+			kind: "drop-view",
+			name: r.name
+		};
+		for (const group of d.lateDropOrder) yield {
+			kind: "drop",
+			group
+		};
+	}
+	/** The plan entries in execution order, refusals folded in as `error` entries. */
+	buildPlanEntries(d, safe, refusals) {
+		const refused = (e) => refusals.has(e.name) ? withRefusals(e.toInit(), refusals.get(e.name)) : e;
+		const entries = [];
+		for (const step of this.orderedSteps(d)) switch (step.kind) {
+			case "drop":
+				if (!safe) entries.push(...step.group.map((name) => refused(d.dropEntries.get(name))));
+				break;
+			case "table": {
+				const t = d.tableByName.get(step.name);
+				let init = {
+					...t.planEntry,
+					dependsOn: d.tableDependsOn.get(step.name)
+				};
+				const skipped = safe ? safeModeSkips(t) : [];
+				const pk = t.diff?.primaryKeyChanged;
+				if (pk) init.pkChange = {
+					from: pk.from,
+					to: pk.to,
+					rebuild: !skipped.includes("pk-rebuild")
+				};
+				if (safe) init = {
+					...init,
+					columnsToDrop: [],
+					typeChanges: skipped.includes("recreate") ? init.typeChanges : [],
+					skipped: skipped.length > 0 ? skipped : void 0,
+					recreated: false
+				};
+				entries.push(withRefusals(init, refusals.get(step.name)));
+				break;
+			}
+			case "deferred-fks": break;
+			case "view":
+				entries.push(refused(d.viewEntries[step.index]));
+				break;
+			case "external":
+				entries.push(d.externalEntries[step.index]);
+				break;
+			case "drop-view":
+				if (!safe) entries.push(refused(d.dropEntries.get(step.name)));
+				break;
+		}
+		return entries;
+	}
+	async execute(d, safe, getAbortReason) {
+		const { hash, allReadables } = d;
+		const deps = this.buildExecutorDeps();
+		const entries = [];
+		/** Removed entries that were NOT dropped — they stay tracked (I2). */
+		const retained = [];
+		const droppedNames = /* @__PURE__ */ new Set();
+		for (const view of d.views) await dropOutdatedView(view, d.viewPlans.get(view.tableName), this.space);
+		const droppedViewEntries = /* @__PURE__ */ new Map();
+		for (const r of d.removed) {
+			if (!r.isView) continue;
+			if (safe) {
+				retained.push(r);
+				continue;
+			}
+			try {
+				await this.space.dropViewByName(r.name);
+				droppedViewEntries.set(r.name, d.dropEntries.get(r.name));
+				droppedNames.add(r.name);
+			} catch (error) {
+				const msg = `Drop of view "${r.name}" failed: ${error.message}`;
+				this.logger.error?.(`[schema-sync] ${msg}`);
+				droppedViewEntries.set(r.name, new SyncEntry({
+					name: r.name,
+					viewType: r.viewType,
+					status: "error",
+					errors: [msg]
 				}));
+				retained.push(r);
+			}
+		}
+		if (!safe) for (const t of d.tables) {
+			if (!t.diff?.primaryKeyChanged) continue;
+			const keysByChild = /* @__PURE__ */ new Map();
+			for (const fk of t.inboundFks ?? []) keysByChild.set(fk.table, [...keysByChild.get(fk.table) ?? [], fkKey(fk.fields)]);
+			for (const [childName, fkKeys] of keysByChild) await d.tableByDbName.get(childName)?.readable.dbAdapter.dropForeignKeys?.(fkKeys);
+		}
+		const deferred = [];
+		const drops = {
+			d,
+			retained,
+			droppedNames
+		};
+		for (const step of this.orderedSteps(d)) {
+			this.assertLockHeld(getAbortReason);
+			switch (step.kind) {
+				case "drop":
+					if (safe) retain(step.group, drops);
+					else entries.push(...await this.dropRemovedGroup(step.group, drops));
+					break;
+				case "table": {
+					const t = d.tableByName.get(step.name);
+					const entry = await executeSyncTable(t, safe, deps, {
+						deferForeignKeysTo: step.cycle,
+						dependsOn: d.tableDependsOn.get(step.name)
+					});
+					if (step.cycle) deferred.push({
+						readable: t.readable,
+						index: entries.length
+					});
+					entries.push(entry);
+					break;
+				}
+				case "deferred-fks":
+					for (const { readable, index } of deferred) {
+						this.assertLockHeld(getAbortReason);
+						entries[index] = await executeDeferredForeignKeys(readable, entries[index], deps);
+					}
+					break;
+				case "view":
+					entries.push(await executeSyncView(d.views[step.index], d.viewEntries[step.index]));
+					break;
+				case "external":
+					entries.push(d.externalEntries[step.index]);
+					break;
+				case "drop-view": {
+					const entry = droppedViewEntries.get(step.name);
+					if (entry) entries.push(entry);
+					break;
+				}
 			}
 		}
-		return new SyncEntry(init);
+		if (safe && retained.length > 0) this.logger.warn?.(`[schema-sync] Safe mode: ${retained.map((r) => `"${r.name}"`).join(", ")} no longer in the schema — kept (still tracked; dropped by the next run that executes)`);
+		this.assertLockHeld(getAbortReason);
+		for (const e of entries) if (e.status !== "error" && e.skipped.length > 0) {
+			const work = e.skipped.map((k) => SKIPPED_LABELS[k]).join(", ");
+			this.logger.warn?.(`[schema-sync] Safe mode: "${e.name}" — ${work} skipped, snapshot and hash withheld; the next run without safe applies it`);
+		}
+		const pendingNames = new Set(entries.filter((e) => e.pending).map((e) => e.name));
+		for (const readable of allReadables) {
+			if (pendingNames.has(readable.tableName)) continue;
+			const adapter = readable.dbAdapter;
+			const tm = adapter.typeMapper?.bind(adapter);
+			const opts = adapter.getDesiredTableOptions?.();
+			const snapshot = readable.isView ? computeViewSnapshot(readable) : computeTableSnapshot(readable, tm, opts);
+			await this.store.writeTableSnapshot(readable.tableName, snapshot);
+		}
+		for (const name of droppedNames) await this.store.deleteTableSnapshot(name);
+		for (const readable of allReadables) if (readable.renamedFrom) await this.store.deleteTableSnapshot(readable.renamedFrom);
+		await this.store.writeTrackedList(allReadables, retained);
+		if (pendingNames.size === 0) await this.store.writeHash(hash);
+		return {
+			status: "synced",
+			schemaHash: hash,
+			entries
+		};
+	}
+	/**
+	* Drops one removed-table group (a table, or a foreign-key cycle as one
+	* operation) and returns its entries. A live inbound FK from outside the
+	* removed set blocks the group — error entries, kept tracked — instead of
+	* leaving a dangling constraint or cascading. The probe runs at execution
+	* time, so an inventory child whose FK to the group was dropped earlier in
+	* this run does not block it. Called from the walk for early groups (right
+	* before the table they block) and late groups (after the views) alike.
+	*/
+	async dropRemovedGroup(group, ctx) {
+		const { d, droppedNames } = ctx;
+		const dropGroup = group.length > 1 ? group : void 0;
+		const failed = (message) => {
+			retain(group, ctx);
+			return group.map((name) => {
+				const msg = message(name);
+				this.logger.error?.(`[schema-sync] ${msg}`);
+				return new SyncEntry({
+					name,
+					status: "error",
+					errors: [msg],
+					dropGroup
+				});
+			});
+		};
+		const inbounds = await Promise.all(group.map((name) => this.space.getReferencingForeignKeys(name)));
+		const blockers = [];
+		for (const [i, name] of group.entries()) for (const fk of inbounds[i] ?? []) if (!d.removedTableSet.has(fk.table)) blockers.push(`${fk.table}.${fk.fields.join(",")} → ${name}`);
+		if (blockers.length > 0) return failed((name) => `Cannot drop "${name}": it is still referenced by ${blockers.join(", ")}. Drop the referencing constraint (or add the table back) and re-run.`);
+		try {
+			if (group.length === 1) await this.space.dropTableByName(group[0]);
+			else await this.space.dropTablesByName(group);
+		} catch (error) {
+			return failed((name) => `Drop of "${name}" failed: ${error.message}`);
+		}
+		for (const name of group) droppedNames.add(name);
+		return group.map((name) => d.dropEntries.get(name));
+	}
+	/**
+	* Surfaces the run outcome per the `onError` policy. Reporting must never be
+	* silently lost to the NoopLogger default — when no real logger is
+	* configured, warnings/errors go to `console` (a production consumer lost
+	* months of failed-index errors to the silent default).
+	*/
+	reportOutcome(result, onError) {
+		if (onError === "silent" || result.entries.length === 0) return;
+		const out = this.logger === require_db_view.NoopLogger ? console : this.logger;
+		const counts = /* @__PURE__ */ new Map();
+		for (const entry of result.entries) counts.set(entry.status, (counts.get(entry.status) ?? 0) + 1);
+		const summary = [...counts.entries()].map(([status, n]) => `${n} ${status}`).join(", ");
+		out.log(`[schema-sync] ${result.status}: ${summary}`);
+		const errored = result.entries.filter((e) => e.hasErrors);
+		if (errored.length === 0) return;
+		const lines = errored.map((e) => `[schema-sync] "${e.name}" ${e.refused ? "refused" : "failed"}: ${e.errors.join("; ") || e.status}`);
+		for (const line of lines) out.error(line);
+		if (onError === "throw") {
+			const verb = result.status === "refused" ? "refused" : "failed";
+			throw new Error(`[schema-sync] ${errored.length} entr${errored.length === 1 ? "y" : "ies"} ${verb}:\n${lines.join("\n")}`);
+		}
+	}
+	/**
+	* Computes a dry-run plan showing what `run()` would do, without executing
+	* any DDL. Entries come back in execution order; pre-flight refusals appear
+	* as `error` entries (`refused: true`) exactly as `run()` would report them.
+	*/
+	async plan(types, opts) {
+		const force = opts?.force ?? false;
+		const safe = opts?.safe ?? false;
+		const resolved = await this.resolveAndHash(types);
+		const { hash } = resolved;
+		await this.store.ensureControlTable();
+		const d = await this.discover(resolved, safe);
+		const refusals = this.preflight(d, safe);
+		const entries = this.buildPlanEntries(d, safe, refusals);
+		if (!force) {
+			if (await this.store.readHash() === hash) return {
+				status: "up-to-date",
+				schemaHash: hash,
+				entries
+			};
+		}
+		return {
+			status: "changes-needed",
+			schemaHash: hash,
+			entries
+		};
+	}
+	/** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
+	resolveTypeMapper(adapter) {
+		return adapter.typeMapper?.bind(adapter) ?? ((f) => f.designType === "union" ? "union" : f.designType);
 	}
 	/**
 	* Populates plan init from a column diff (shared by Path A and Path B).
@@ -1199,22 +1960,10 @@ var SchemaSync = class {
 			from: r.oldName,
 			to: r.field.physicalName
 		}));
-		init.typeChanges = diff.typeChanged.map((tc) => ({
-			column: tc.field.physicalName,
-			fromType: tc.existingType,
-			toType: tc.field.designType
-		}));
-		init.nullableChanges = diff.nullableChanged.map((nc) => ({
-			column: nc.field.physicalName,
-			toNullable: nc.field.optional
-		}));
-		init.defaultChanges = diff.defaultChanged.map((dc) => ({
-			column: dc.field.physicalName,
-			oldDefault: dc.oldDefault,
-			newDefault: dc.newDefault
-		}));
+		init.typeChanges = describeTypeChanges(diff);
+		Object.assign(init, describeNullableDefaults(diff));
 		init.columnsToDrop = diff.removed.map((c) => c.name);
-		if (diff.added.length > 0 || diff.renamed.length > 0 || diff.typeChanged.length > 0 || diff.nullableChanged.length > 0 || diff.defaultChanged.length > 0 || diff.removed.length > 0) init.status = "alter";
+		if (diff.added.length > 0 || diff.renamed.length > 0 || diff.typeChanged.length > 0 || diff.nullableChanged.length > 0 || diff.defaultChanged.length > 0 || diff.removed.length > 0 || diff.primaryKeyChanged !== void 0) init.status = "alter";
 		if (diff.conflicts.length > 0) {
 			init.status = "error";
 			init.errors = [...init.errors ?? [], ...diff.conflicts.map((c) => `Column rename conflict on ${name}: cannot rename "${c.oldName}" → "${c.field.physicalName}" because "${c.conflictsWith}" already exists.`)];
@@ -1226,45 +1975,29 @@ var SchemaSync = class {
 	}
 	/**
 	* Computes table option diff using DB-first introspection with snapshot fallback.
-	* Returns null if the adapter has no table options.
+	* Returns null if the adapter has no table options. `tableName` is the name
+	* the table has in the database right now — the OLD name of a pending
+	* `@db.table.renamed` (the adapter's bound name is the new one, which does
+	* not exist yet); omitted for a table that is not being renamed.
 	*/
-	async diffTableOptions(readable) {
+	async diffTableOptions(readable, tableName) {
 		const adapter = readable.dbAdapter;
 		const desired = adapter.getDesiredTableOptions?.();
 		if (!desired || desired.length === 0) return null;
 		let existing;
-		if (adapter.getExistingTableOptions) existing = await adapter.getExistingTableOptions();
+		if (adapter.getExistingTableOptions) existing = await adapter.getExistingTableOptions(tableName);
 		else {
-			const snapshot = await this.store.readTableSnapshot(readable.tableName);
+			const snapshot = await this.store.readTableSnapshot(tableName ?? readable.tableName);
 			existing = snapshot ? snapshotToExistingTableOptions(snapshot) : [];
 		}
 		if (existing.length === 0) return null;
 		const destructiveKeys = adapter.destructiveOptionKeys?.();
 		return computeTableOptionDiff(desired, existing, destructiveKeys);
 	}
-	async planView(view, trackedNames) {
-		const viewType = view.viewPlan.materialized ? "M" : "V";
-		const renamedFrom = view.renamedFrom;
-		const isRenamed = renamedFrom && trackedNames.has(renamedFrom);
-		let status;
-		if (isRenamed) status = "alter";
-		else if (trackedNames.has(view.tableName)) status = await viewDefinitionChanged(view, this.store) ? "alter" : "in-sync";
-		else status = "create";
-		return new SyncEntry({
-			name: view.tableName,
-			status,
-			viewType,
-			renamedFrom: isRenamed ? renamedFrom : void 0,
-			recreated: status === "alter" && !isRenamed ? true : void 0
-		});
-	}
 	buildExecutorDeps() {
 		return {
-			store: this.store,
-			space: this.space,
 			logger: this.logger,
-			resolveTypeMapper: this.resolveTypeMapper.bind(this),
-			diffTableOptions: this.diffTableOptions.bind(this)
+			resolveTypeMapper: this.resolveTypeMapper.bind(this)
 		};
 	}
 };
@@ -1322,6 +2055,7 @@ async function planSchema(space, types, opts) {
 //#endregion
 exports.SchemaSync = SchemaSync;
 exports.SyncEntry = SyncEntry;
+exports.canonicalizeQueryNode = canonicalizeQueryNode;
 exports.computeColumnDiff = computeColumnDiff;
 exports.computeForeignKeyDiff = computeForeignKeyDiff;
 exports.computeSchemaHash = computeSchemaHash;
@@ -1336,3 +2070,4 @@ exports.readStoredSnapshot = readStoredSnapshot;
 exports.snapshotToExistingColumns = snapshotToExistingColumns;
 exports.snapshotToExistingTableOptions = snapshotToExistingTableOptions;
 exports.syncSchema = syncSchema;
+exports.topoOrder = topoOrder;