@atscript/db 0.1.140 → 0.1.141

package/dist/sync.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_column_diff = require("./column-diff-CgxgFKzx.cjs");
+const require_db_error = require("./db-error-DTkkeu5b.cjs");
+const require_column_diff = require("./column-diff-CfPNcP6e.cjs");
 //#region src/schema/table-option-diff.ts
 /**
 * Computes the difference between desired and existing table options.
@@ -100,6 +101,50 @@ function reachable(seeds, edges) {
 	}
 	return out;
 }
+/**
+* Orders `nodes` so that every node comes AFTER the nodes it depends on,
+* keeping the given order wherever the dependencies allow it: a depth-first
+* walk in `nodes` order that emits a node's dependencies (recursively, in
+* their listed order) right before the node itself. Unlike {@link topoOrder}
+* the result follows the caller's order, not the names — schema sync uses it
+* for managed views, which are created upstream-first in inventory order.
+*
+* - Dependencies outside `nodes` are ignored.
+* - A dependency cycle is reported as `cycle` (the closed path, e.g.
+*   `["a", "b", "a"]`) and the order is undefined.
+* @since 0.1.141
+*/
+function stableTopo(nodes, dependsOn) {
+	const listed = [...new Set(nodes)];
+	const nodeSet = new Set(listed);
+	const done = /* @__PURE__ */ new Set();
+	const path = [];
+	const onPath = /* @__PURE__ */ new Set();
+	const order = [];
+	const visit = (node) => {
+		if (done.has(node)) return;
+		if (onPath.has(node)) return [...path.slice(path.indexOf(node)), node];
+		onPath.add(node);
+		path.push(node);
+		for (const dep of dependsOn(node)) {
+			if (dep === node || !nodeSet.has(dep)) continue;
+			const cycle = visit(dep);
+			if (cycle) return cycle;
+		}
+		path.pop();
+		onPath.delete(node);
+		done.add(node);
+		order.push(node);
+	};
+	for (const node of listed) {
+		const cycle = visit(node);
+		if (cycle) return {
+			order,
+			cycle
+		};
+	}
+	return { order };
+}
 //#endregion
 //#region src/schema/sync-store.ts
 var SyncStore = class {
@@ -194,73 +239,93 @@ var SyncStore = class {
 		entries.sort((a, b) => a.name.localeCompare(b.name));
 		await this.writeControlValue("synced_tables", JSON.stringify(entries));
 	}
-	async tryAcquireLock(podId, ttlMs) {
-		const now = Date.now();
-		const existing = await this.controlTable.findOne({
-			filter: { _id: { $eq: "sync_lock" } },
+	async readLock() {
+		return await this.controlTable.findOne({
+			filter: lockFilter(),
 			controls: {}
 		});
+	}
+	/**
+	* Deletes the lock row only while it is still expired — a peer that took
+	* the expired lock over in the meantime keeps its fresh one.
+	*/
+	async deleteExpiredLock(now) {
+		await this.controlTable.deleteMany(lockFilter({ expiresAt: { $lt: now } }));
+	}
+	/**
+	* One acquisition attempt: `true` when this pod now holds the lock, `false`
+	* when a live lock (or a peer's concurrent insert) holds it. Any other error
+	* propagates — a failing insert is not contention.
+	*/
+	async tryAcquireLock(podId, ttlMs) {
+		const now = Date.now();
+		const existing = await this.readLock();
 		if (existing) {
-			const expiresAt = existing.expiresAt;
-			if (expiresAt && expiresAt < now) await this.controlTable.deleteOne("sync_lock");
-			else return false;
+			if (!isExpired(existing, now)) return false;
+			await this.deleteExpiredLock(now);
 		}
 		try {
 			await this.controlTable.insertOne({
-				_id: "sync_lock",
+				_id: LOCK_ID,
 				lockedBy: podId,
 				lockedAt: now,
 				expiresAt: now + ttlMs
 			});
 			return true;
-		} catch {
-			return false;
+		} catch (error) {
+			if (error instanceof require_db_error.DbError && error.code === "CONFLICT") return false;
+			throw error;
 		}
 	}
+	/** Extends this pod's lock; never touches a lock another pod holds. */
 	async refreshLock(podId, ttlMs) {
-		const existing = await this.controlTable.findOne({
-			filter: { _id: { $eq: "sync_lock" } },
-			controls: {}
-		});
-		if (!existing) return "missing";
-		if (existing.lockedBy !== podId) return "stolen";
-		await this.controlTable.replaceOne({
-			_id: "sync_lock",
-			lockedBy: podId,
-			lockedAt: existing.lockedAt,
-			expiresAt: Date.now() + ttlMs
-		});
-		return "refreshed";
+		const { matchedCount } = await this.controlTable.updateMany(lockFilter({ lockedBy: { $eq: podId } }), { expiresAt: Date.now() + ttlMs });
+		if (matchedCount > 0) return "refreshed";
+		return await this.readLock() ? "stolen" : "missing";
 	}
+	/**
+	* Deletes this pod's lock. Resolves `false` when there was none to delete
+	* (it expired and a peer took it over, or it was removed); errors propagate.
+	*/
 	async releaseLock(podId) {
-		try {
-			const existing = await this.controlTable.findOne({
-				filter: { _id: { $eq: "sync_lock" } },
-				controls: {}
-			});
-			if (existing && existing.lockedBy === podId) await this.controlTable.deleteOne("sync_lock");
-		} catch {}
+		const { deletedCount } = await this.controlTable.deleteMany(lockFilter({ lockedBy: { $eq: podId } }));
+		return deletedCount > 0;
 	}
+	/**
+	* Polls until the lock is free (or expired — then it is cleared). Resolves
+	* `true` then, `false` once `timeoutMs` has passed with the lock still held.
+	* Acquiring it is the caller's next step.
+	*/
 	async waitForLock(timeoutMs, pollIntervalMs) {
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() < deadline) {
-			const lock = await this.controlTable.findOne({
-				filter: { _id: { $eq: "sync_lock" } },
-				controls: {}
-			});
-			if (!lock) return;
-			const expiresAt = lock.expiresAt;
-			if (expiresAt && expiresAt < Date.now()) {
-				await this.controlTable.deleteOne("sync_lock");
-				return;
+			const lock = await this.readLock();
+			if (!lock) return true;
+			const now = Date.now();
+			if (isExpired(lock, now)) {
+				await this.deleteExpiredLock(now);
+				return true;
 			}
 			await new Promise((resolve) => {
-				setTimeout(resolve, pollIntervalMs);
+				setTimeout(resolve, Math.min(pollIntervalMs, Math.max(deadline - Date.now(), 0)));
 			});
 		}
-		throw new Error(`Schema sync lock wait timed out after ${timeoutMs}ms`);
+		return false;
 	}
 };
+const LOCK_ID = "sync_lock";
+/** The lock row's filter, narrowed by `conditions` (the compare-and-set part). */
+function lockFilter(conditions) {
+	return {
+		_id: { $eq: LOCK_ID },
+		...conditions
+	};
+}
+/** A lock row without an expiry never expires (it blocks until the wait times out). */
+function isExpired(lock, now) {
+	const expiresAt = Number(lock.expiresAt);
+	return expiresAt > 0 && expiresAt < now;
+}
 async function readStoredSnapshot(space, tableName, _asView) {
 	const { AtscriptControl } = await Promise.resolve().then(() => require("./control-jIVU2hkf.cjs"));
 	const table = space.getTable(AtscriptControl);
@@ -282,6 +347,11 @@ const noColor = {
 	dim: (s) => s,
 	underline: (s) => s
 };
+/** `regular → derived` / `expression changed` / `type changed`. */
+function derivedChangeLabel(change) {
+	if (change.reason === "kind") return change.derived ? "regular → derived" : "derived → regular";
+	return change.reason === "expression" ? "expression changed" : "type changed";
+}
 var SyncEntry = class SyncEntry {
 	name;
 	/** 'V' = virtual view, 'M' = materialized view, 'E' = external view, undefined = table */
@@ -298,6 +368,8 @@ var SyncEntry = class SyncEntry {
 	fkAdded;
 	fkRemoved;
 	fkChanged;
+	/** @since 0.1.141 — see {@link TSyncEntryInit.derivedChanges}. */
+	derivedChanges;
 	columnsAdded;
 	columnsRenamed;
 	columnsDropped;
@@ -314,6 +386,8 @@ var SyncEntry = class SyncEntry {
 	dropGroup;
 	/** @since 0.1.128 — see {@link TSyncEntryInit.refused}. */
 	refused;
+	/** @since 0.1.141 — see {@link TSyncEntryInit.cascadeFrom}. */
+	cascadeFrom;
 	constructor(init) {
 		this.name = init.name;
 		this.viewType = init.viewType;
@@ -329,6 +403,7 @@ var SyncEntry = class SyncEntry {
 		this.fkAdded = init.fkAdded ?? [];
 		this.fkRemoved = init.fkRemoved ?? [];
 		this.fkChanged = init.fkChanged ?? [];
+		this.derivedChanges = init.derivedChanges ?? [];
 		this.columnsAdded = init.columnsAdded ?? [];
 		this.columnsRenamed = init.columnsRenamed ?? [];
 		this.columnsDropped = init.columnsDropped ?? [];
@@ -340,6 +415,7 @@ var SyncEntry = class SyncEntry {
 		this.dependsOn = init.dependsOn ?? [];
 		this.dropGroup = init.dropGroup;
 		this.refused = init.refused ?? false;
+		this.cascadeFrom = init.cascadeFrom ?? [];
 	}
 	/**
 	* The init object this entry was built from — lets callers derive a
@@ -376,7 +452,7 @@ var SyncEntry = class SyncEntry {
 	/** 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.skipped.includes("recreate") || this.recreated || this.pkChange?.rebuild === true || this.optionChanges.some((c) => c.destructive) && !this.skipped.includes("table-options");
+		return this.columnsToDrop.length > 0 || this.typeChanges.length > 0 && !this.skipped.includes("recreate") || this.recreated || this.pkChange?.rebuild === true || this.derivedChanges.some((dc) => dc.reason === "kind") && !this.skipped.includes("derived") || this.optionChanges.some((c) => c.destructive) && !this.skipped.includes("table-options");
 	}
 	/** Whether this entry represents any change (not in-sync) */
 	get hasChanges() {
@@ -420,6 +496,19 @@ var SyncEntry = class SyncEntry {
 			return `      ${c.red(`! ${tc.column}: ${tc.fromType} → ${tc.toType}${action}`)}`;
 		});
 	}
+	/**
+	* `~ col — derived column (expression changed) — drop + add` (plan) /
+	* `— rebuilt` (result), or `! … — skipped (safe mode)` when pending.
+	*/
+	printDerivedChanges(c, mode) {
+		const skipped = this.skipped.includes("derived");
+		return this.derivedChanges.map((dc) => {
+			const head = `${dc.column} — derived column (${derivedChangeLabel(dc)})`;
+			if (skipped) return `      ${c.yellow(`! ${head} — skipped (safe mode)`)}`;
+			const line = `${dc.reason === "kind" ? "!" : "~"} ${head} — ${mode === "plan" ? "drop + add" : "rebuilt"}`;
+			return `      ${dc.reason === "kind" ? c.red(line) : c.yellow(line)}`;
+		});
+	}
 	/** `~ col — nullable` / `~ col — default a → b`, `— skipped (safe mode)` when pending. */
 	printNullableDefaults(c) {
 		const suffix = this.skipped.includes("nullable-defaults") ? " — skipped (safe mode)" : "";
@@ -445,6 +534,10 @@ var SyncEntry = class SyncEntry {
 		if (this.dependsOn.length === 0) return [];
 		return [`      ${c.dim(`· after: ${this.dependsOn.join(", ")}`)}`];
 	}
+	/** `· upstream view "x" recreated` — why an unchanged view is recreated. */
+	printCascade(c) {
+		return this.cascadeFrom.map((name) => `      ${c.dim(`· upstream view "${name}" recreated`)}`);
+	}
 	printDropGroup(c) {
 		const others = this.dropGroup?.filter((n) => n !== this.name) ?? [];
 		if (others.length === 0) return [];
@@ -463,7 +556,7 @@ var SyncEntry = class SyncEntry {
 		}
 		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.columnsToAdd.map((col) => `      ${c.green(`+ ${col.physicalName} (${col.designType})${col.isPrimaryKey ? " PK" : ""}${col.optional ? " nullable" : ""}${col.derived ? " derived" : ""} — add`)}`),
 			...this.printDependsOn(c),
 			""
 		];
@@ -471,16 +564,18 @@ var SyncEntry = class SyncEntry {
 			const renameInfo = this.renamedFrom ? ` ${c.yellow(`(renamed from ${this.renamedFrom})`)}` : "";
 			return [
 				`  ${c.cyan(`~ ${vp}${label} — alter${renameInfo}`)}`,
-				...this.columnsToAdd.map((col) => `      ${c.green(`+ ${col.physicalName} (${col.designType}) — add`)}`),
+				...this.columnsToAdd.map((col) => `      ${c.green(`+ ${col.physicalName} (${col.designType})${col.derived ? " derived" : ""} — add`)}`),
 				...this.columnsToRename.map((r) => `      ${c.yellow(`~ ${r.from} → ${r.to} — rename`)}`),
 				...this.printTypeChanges(c),
 				...this.printNullableDefaults(c),
+				...this.printDerivedChanges(c, "plan"),
 				...this.printPkChange(c, "plan"),
 				...this.columnsToDrop.map((col) => `      ${c.red(`- ${col} — drop`)}`),
 				...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.printCascade(c),
 				...this.printDependsOn(c),
 				""
 			];
@@ -499,7 +594,7 @@ var SyncEntry = class SyncEntry {
 			...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.pkChange !== void 0 || this.skipped.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.derivedChanges.length > 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 [
@@ -509,8 +604,10 @@ var SyncEntry = class SyncEntry {
 				...this.printPkChange(c, "result"),
 				...this.printTypeChanges(c),
 				...this.printNullableDefaults(c),
+				...this.printDerivedChanges(c, "result"),
 				...this.columnsDropped.map((col) => `      ${c.red(`- ${col} — dropped`)}`),
 				...this.printOptionChanges(c, "result"),
+				...this.printCascade(c),
 				""
 			];
 		}
@@ -555,6 +652,7 @@ function planTableInit(facts, safe, dependsOn) {
 		...init,
 		columnsToDrop: [],
 		typeChanges: skipped.includes("recreate") ? init.typeChanges : [],
+		derivedChanges: skipped.includes("derived") ? init.derivedChanges : [],
 		skipped: skipped.length > 0 ? skipped : void 0,
 		recreated: false
 	};
@@ -582,6 +680,10 @@ function typeChangeErrors(readable, diff) {
 	const advice = method ? `@db.sync.method "${method}" is declared but the adapter has no ${method === "recreate" ? "recreateTable" : "dropTable"} — migrate manually.` : `Add @db.sync.method "recreate" or "drop", or migrate manually.`;
 	return diff.typeChanged.map((tc) => `Type change on ${readable.tableName}.${tc.field.physicalName} (${tc.existingType} → ${tc.field.designType}). ${advice}`);
 }
+/** A derived-column rebuild on an adapter without `dropColumns` / `syncColumns`. */
+function derivedRebuildUnsupported(name, columns) {
+	return `Derived column${columns.length === 1 ? "" : "s"} ${columns.map((c) => `"${c}"`).join(", ")} of "${name}" changed but the adapter cannot drop and re-add columns. Migrate manually and re-run.`;
+}
 /** `(a, b → c)` — the key change as the messages print it. */
 function pkLabel(change) {
 	return `(${change.from.join(", ")} → ${change.to.join(", ")})`;
@@ -632,7 +734,7 @@ async function executeSyncTable(facts, safe, deps, exec) {
 				await adapter.ensureTable(ensureOpts);
 				init.status = "create";
 			} else if (existing.length > 0) {
-				const diff = facts.diff ?? require_column_diff.computeColumnDiff(readable.fieldDescriptors, existing, adapter.typeMapper?.bind(adapter));
+				const diff = facts.diff ?? require_column_diff.computeColumnDiff(readable.columnDescriptors, existing, adapter.typeMapper?.bind(adapter), { snapshot: storedSnapshot });
 				if (hasFkChanges && !adapter.syncForeignKeys && adapter.recreateTable) {
 					await adapter.recreateTable();
 					init.recreated = true;
@@ -657,7 +759,7 @@ async function executeSyncTable(facts, safe, deps, exec) {
 			const existed = adapter.tableExists ? await adapter.tableExists() : false;
 			await adapter.ensureTable(ensureOpts);
 			if (!existed) init.status = "create";
-		} else await applyColumnDiff(adapter, readable, facts.diff ?? require_column_diff.computeColumnDiff(readable.fieldDescriptors, require_column_diff.snapshotToExistingColumns(storedSnapshot), deps.resolveTypeMapper(adapter)), init, safe, deps.logger, ensureOpts);
+		} else await applyColumnDiff(adapter, readable, facts.diff ?? require_column_diff.computeColumnDiff(readable.columnDescriptors, require_column_diff.snapshotToExistingColumns(storedSnapshot, readable), deps.resolveTypeMapper(adapter), { snapshot: storedSnapshot }), init, safe, deps.logger, ensureOpts);
 		else {
 			const existed = adapter.tableExists ? await adapter.tableExists() : true;
 			if (!init.recreated) {
@@ -734,6 +836,10 @@ async function executeDeferredForeignKeys(readable, entry, deps) {
 		return entry.withError(msg);
 	}
 }
+/** Whether a plan drops and recreates the view (its own change, or an upstream's). */
+function viewRecreated(plan) {
+	return plan.definitionChanged || (plan.upstreamRecreated?.length ?? 0) > 0;
+}
 /** 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));
@@ -745,11 +851,11 @@ async function planViewSync(view, trackedNames, store) {
 /** Drops the stale view a plan identified — views don't support ALTER VIEW. */
 async function dropOutdatedView(view, plan, space) {
 	if (plan.isRenamed) await space.dropViewByName(view.renamedFrom);
-	else if (plan.definitionChanged) await space.dropViewByName(view.tableName);
+	else if (viewRecreated(plan)) await space.dropViewByName(view.tableName);
 }
 /** Status a managed view's entry gets for a given plan. */
 function viewPlanStatus(view, plan, trackedNames) {
-	if (plan.isRenamed || plan.definitionChanged) return "alter";
+	if (plan.isRenamed || viewRecreated(plan)) return "alter";
 	return trackedNames.has(view.tableName) ? "in-sync" : "create";
 }
 /**
@@ -761,6 +867,14 @@ async function executeSyncView(view, planned) {
 	await view.dbAdapter.ensureTable();
 	return planned;
 }
+/** The plan-shaped summary of a diff's derived-column rebuilds (`entry.derivedChanges`). */
+function describeDerivedChanges(diff) {
+	return (diff.derivedChanged ?? []).map((dc) => ({
+		column: dc.field.physicalName,
+		reason: dc.reason,
+		derived: dc.field.derived !== void 0
+	}));
+}
 /** The plan-shaped summary of a diff's type changes (`entry.typeChanges`). */
 function describeTypeChanges(diff) {
 	return diff.typeChanged.map((tc) => ({
@@ -813,6 +927,7 @@ function safeModeSkips(facts) {
 	if (strategy === "drop") out.push("recreate");
 	else if (strategy === "recreate") return out;
 	if (diff && (diff.nullableChanged.length > 0 || diff.defaultChanged.length > 0) && needsDdlForNullableDefaults(adapter)) out.push("nullable-defaults");
+	if ((diff?.derivedChanged?.length ?? 0) > 0) out.push("derived");
 	if (diff?.primaryKeyChanged) out.push("pk-rebuild");
 	if (optionDiff?.changed.some((c) => c.destructive)) out.push("table-options");
 	return out;
@@ -904,6 +1019,34 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 		init.columnsRenamed = syncResult.renamed;
 		if (syncResult.added.length > 0 || (syncResult.renamed?.length ?? 0) > 0 || needsSyncColumns) init.status = "alter";
 	}
+	const derivedChanged = diff.derivedChanged ?? [];
+	if (derivedChanged.length > 0 && !init.recreated && init.status !== "error") {
+		init.derivedChanges = describeDerivedChanges(diff);
+		const columns = derivedChanged.map((dc) => dc.field.physicalName);
+		if (safe) {
+			markSkipped(init, "derived");
+			init.status = "alter";
+			logger.warn?.(`[schema-sync] Derived column change on "${name}" (${columns.join(", ")}) — rebuild skipped (safe mode)`);
+		} else if (adapter.dropColumns && adapter.syncColumns) {
+			if (adapter.dropIndexesForColumns) await adapter.dropIndexesForColumns(columns);
+			await adapter.dropColumns(columns);
+			await adapter.syncColumns({
+				added: derivedChanged.map((dc) => dc.field),
+				removed: [],
+				renamed: [],
+				typeChanged: [],
+				nullableChanged: [],
+				defaultChanged: [],
+				conflicts: []
+			});
+			init.status = "alter";
+		} else {
+			const msg = derivedRebuildUnsupported(name, columns);
+			logger.error?.(`[schema-sync] ${msg}`);
+			init.errors = [...init.errors ?? [], msg];
+			init.status = "error";
+		}
+	}
 	if (diff.primaryKeyChanged && init.status !== "error") {
 		const { from, to } = diff.primaryKeyChanged;
 		if (init.recreated) init.pkChange = {
@@ -989,7 +1132,8 @@ const SKIPPED_LABELS = {
 	"pk-rebuild": "primary-key rebuild",
 	recreate: "drop-and-recreate",
 	"table-options": "table-option recreate",
-	"nullable-defaults": "nullable/default change"
+	"nullable-defaults": "nullable/default change",
+	derived: "derived-column rebuild"
 };
 /**
 * The removed tables whose drop must precede `t`'s own drop/rebuild: those
@@ -1023,6 +1167,7 @@ var SchemaSync = class {
 		const views = [];
 		const externalViews = [];
 		for (const type of types) {
+			if (require_column_diff.aliasTargetOf(type)) continue;
 			const readable = this.space.get(type);
 			if (readable.isView) {
 				const view = readable;
@@ -1104,13 +1249,17 @@ var SchemaSync = class {
 	* Starts a periodic heartbeat that extends the lock's TTL while sync runs.
 	* Returns a handle with `stop()` to cancel and `getAbortReason()` to check
 	* whether the lock was stolen or unexpectedly removed.
+	*
+	* At most one refresh is in flight; `stop()` resolves once it has settled,
+	* so the lock is released only after the last refresh — a late refresh must
+	* never race the release (or the next holder's lock).
 	*/
 	startHeartbeat(podId, ttlMs) {
 		let abortReason;
 		let stopped = false;
+		let inFlight;
 		const intervalMs = Math.max(Math.floor(ttlMs / 3), 1e3);
-		const timer = setInterval(async () => {
-			if (stopped) return;
+		const refresh = async () => {
 			try {
 				const status = await this.store.refreshLock(podId, ttlMs);
 				if (stopped) return;
@@ -1125,22 +1274,55 @@ var SchemaSync = class {
 				if (stopped) return;
 				this.logger.warn("[schema-sync] Failed to refresh lock heartbeat (will retry):", error instanceof Error ? error.message : error);
 			}
+		};
+		const timer = setInterval(() => {
+			if (stopped || inFlight) return;
+			inFlight = refresh().finally(() => {
+				inFlight = void 0;
+			});
 		}, intervalMs);
 		if (typeof timer === "object" && "unref" in timer) timer.unref();
 		return {
-			stop() {
+			async stop() {
 				stopped = true;
 				clearInterval(timer);
+				await inFlight;
 			},
 			getAbortReason: () => abortReason
 		};
 	}
+	/**
+	* Acquires the sync lock, waiting for a peer that holds it. Resolves
+	* `"acquired"`, or `"synced-by-peer"` when a non-forced run finds, after a
+	* wait, that the peer stored this schema's hash. A forced run never
+	* short-circuits — it waits its turn and runs. Losing the race for a freed
+	* lock to another waiter just waits again, within the same `waitTimeoutMs`.
+	*/
+	async acquireLock(podId, hash, opts) {
+		const deadline = Date.now() + opts.waitTimeoutMs;
+		while (!await this.store.tryAcquireLock(podId, opts.lockTtlMs)) {
+			if (!await this.store.waitForLock(deadline - Date.now(), opts.pollIntervalMs)) throw new Error(`Schema sync lock wait timed out after ${opts.waitTimeoutMs}ms`);
+			if (!opts.force && await this.store.readHash() === hash) return "synced-by-peer";
+		}
+		return "acquired";
+	}
 	/** Throws if the heartbeat detected a stolen/missing lock. */
 	assertLockHeld(getAbortReason) {
 		const reason = getAbortReason();
 		if (reason) throw new Error(reason);
 	}
 	/**
+	* Releases the lock without masking the run's outcome: a failed release is
+	* logged (the row expires after `lockTtlMs`, blocking peers until then).
+	*/
+	async releaseLock(podId) {
+		try {
+			await this.store.releaseLock(podId);
+		} catch (error) {
+			this.logger.warn("[schema-sync] Failed to release the sync lock — peers wait until it expires:", error instanceof Error ? error.message : error);
+		}
+	}
+	/**
 	* Runs schema synchronization with distributed locking, in three phases:
 	*
 	* 1. **Discover** (read-only, under the lock): introspect every table once,
@@ -1148,12 +1330,12 @@ var SchemaSync = class {
 	* 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.
+	* 3. **Execute** in dependency order: removed views, then stale views
+	*    (dependents first) → 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 (upstream views first) → external-view checks →
+	*    remaining removed tables (children first) → snapshots/tracking/hash.
 	*/
 	async run(types, opts) {
 		this.logger = opts?.logger ?? this.logger;
@@ -1174,15 +1356,16 @@ var SchemaSync = class {
 				entries: []
 			};
 		}
-		if (!await this.store.tryAcquireLock(podId, lockTtlMs)) {
-			await this.store.waitForLock(waitTimeoutMs, pollIntervalMs);
-			if (await this.store.readHash() === hash) return {
-				status: "synced-by-peer",
-				schemaHash: hash,
-				entries: []
-			};
-			if (!await this.store.tryAcquireLock(podId, lockTtlMs)) throw new Error("Failed to acquire schema sync lock after waiting");
-		}
+		if (await this.acquireLock(podId, hash, {
+			lockTtlMs,
+			waitTimeoutMs,
+			pollIntervalMs,
+			force
+		}) === "synced-by-peer") return {
+			status: "synced-by-peer",
+			schemaHash: hash,
+			entries: []
+		};
 		const heartbeat = this.startHeartbeat(podId, lockTtlMs);
 		try {
 			if (!force) {
@@ -1208,15 +1391,15 @@ var SchemaSync = class {
 			this.reportOutcome(result, onError);
 			return result;
 		} finally {
-			heartbeat.stop();
-			await this.store.releaseLock(podId);
+			await heartbeat.stop();
+			await this.releaseLock(podId);
 		}
 	}
 	async discover(resolved, safe) {
-		const { tables, views, externalViews, hash } = resolved;
+		const { tables, views: inventoryViews, externalViews, hash } = resolved;
 		const allReadables = [
 			...tables,
-			...views,
+			...inventoryViews,
 			...externalViews
 		];
 		const previouslyTracked = await this.store.readTrackedList();
@@ -1227,6 +1410,16 @@ var SchemaSync = class {
 		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 viewNames = new Set(inventoryViews.map((v) => v.tableName));
+		const externalViewNames = new Set(externalViews.map((v) => v.tableName));
+		const viewSources = /* @__PURE__ */ new Map();
+		for (const view of inventoryViews) {
+			const plan = view.viewPlan;
+			viewSources.set(view.tableName, sortedUnique([plan.entryTable, ...plan.joins.map((j) => j.targetTable)]));
+		}
+		const viewTopo = stableTopo(inventoryViews.map((v) => v.tableName), (name) => viewSources.get(name) ?? []);
+		const viewByName = new Map(inventoryViews.map((v) => [v.tableName, v]));
+		const views = viewTopo.cycle ? inventoryViews : viewTopo.order.map((name) => viewByName.get(name));
 		const viewFacts = await Promise.all(views.map(async (view) => ({
 			plan: await planViewSync(view, trackedNames, this.store),
 			kind: await view.dbAdapter.getObjectKind?.(view.tableName)
@@ -1234,8 +1427,13 @@ var SchemaSync = class {
 		const viewPlans = /* @__PURE__ */ new Map();
 		const viewEntries = [];
 		const viewObjectKinds = /* @__PURE__ */ new Map();
+		/** Managed views the run drops and recreates (own change, rename, or cascade). */
+		const recreatedViews = /* @__PURE__ */ new Set();
 		for (const [i, view] of views.entries()) {
 			const { plan, kind } = viewFacts[i];
+			const upstreamRecreated = viewSources.get(view.tableName).filter((n) => recreatedViews.has(n));
+			if (upstreamRecreated.length > 0 && trackedNames.has(view.tableName) && !plan.isRenamed && !plan.definitionChanged) plan.upstreamRecreated = upstreamRecreated;
+			if (plan.isRenamed || viewRecreated(plan)) recreatedViews.add(view.tableName);
 			viewPlans.set(view.tableName, plan);
 			viewObjectKinds.set(view.tableName, kind);
 			viewEntries.push(new SyncEntry({
@@ -1243,8 +1441,9 @@ var SchemaSync = class {
 				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)))
+				recreated: viewRecreated(plan) || void 0,
+				cascadeFrom: plan.upstreamRecreated,
+				dependsOn: viewSources.get(view.tableName).filter((n) => tableNames.has(n) || viewNames.has(n) || externalViewNames.has(n))
 			}));
 		}
 		const externalEntries = await Promise.all(externalViews.map((v) => this.checkExternalView(v)));
@@ -1257,6 +1456,7 @@ var SchemaSync = class {
 		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);
+		for (const view of views) for (const source of viewSources.get(view.tableName)) if (!tableNames.has(source) && !viewNames.has(source)) externalTargetAdapters.set(source, view.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();
@@ -1291,6 +1491,12 @@ var SchemaSync = class {
 			tableDependsOn.set(name, sortedUnique([...tableDependsOn.get(name), ...groups.flat()]));
 		}
 		const lateDropOrder = dropOrder.filter((group) => !earlyGroups.has(group));
+		const removedViewNames = removed.filter((r) => r.isView).map((r) => r.name);
+		const removedViewTopo = stableTopo(removedViewNames, (name) => {
+			const snapshot = removedByName.get(name)?.snapshot;
+			return snapshot && "viewType" in snapshot ? require_column_diff.viewSnapshotSources(snapshot) : [];
+		});
+		const removedViewOrder = removedViewTopo.cycle ? removedViewNames : removedViewTopo.order.toReversed();
 		const dropEntries = /* @__PURE__ */ new Map();
 		for (const r of removed) if (r.isView) dropEntries.set(r.name, new SyncEntry({
 			name: r.name,
@@ -1314,6 +1520,9 @@ var SchemaSync = class {
 			trackedNames,
 			viewPlans,
 			viewEntries,
+			viewSources,
+			viewCycle: viewTopo.cycle,
+			removedViewOrder,
 			viewObjectKinds,
 			externalEntries,
 			removed,
@@ -1368,22 +1577,22 @@ var SchemaSync = class {
 			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);
+				init.columnsToAdd = [...readable.columnDescriptors];
 			} else if (facts.existing && facts.existing.length > 0) {
 				const typeMapper = adapter.typeMapper?.bind(adapter);
-				facts.diff = require_column_diff.computeColumnDiff(readable.fieldDescriptors, facts.existing, typeMapper);
+				facts.diff = require_column_diff.computeColumnDiff(readable.columnDescriptors, facts.existing, typeMapper, { snapshot: storedSnapshot });
 				this.populatePlanFromDiff(facts.diff, init, readable, safe);
 			}
 		} else if (adapter.syncColumns) if (!storedSnapshot) {
 			if (!pendingRename) {
 				if (!(adapter.tableExists ? await adapter.tableExists() : false)) {
 					init.status = "create";
-					init.columnsToAdd = readable.fieldDescriptors.filter((f) => !f.ignored);
+					init.columnsToAdd = [...readable.columnDescriptors];
 				}
 			}
 		} else {
-			const existing = require_column_diff.snapshotToExistingColumns(storedSnapshot);
-			facts.diff = require_column_diff.computeColumnDiff(readable.fieldDescriptors, existing, this.resolveTypeMapper(adapter));
+			const existing = require_column_diff.snapshotToExistingColumns(storedSnapshot, readable);
+			facts.diff = require_column_diff.computeColumnDiff(readable.columnDescriptors, existing, this.resolveTypeMapper(adapter), { snapshot: storedSnapshot });
 			this.populatePlanFromDiff(facts.diff, init, readable, safe);
 		}
 		else if (adapter.tableExists) {
@@ -1460,20 +1669,20 @@ var SchemaSync = class {
 				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`);
 			}
 		}
+		if (d.viewCycle) for (const name of new Set(d.viewCycle)) addRefusal(refusals, name, `Managed views form a dependency cycle: ${d.viewCycle.join(" → ")}`);
 		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`);
 			const fns = view.dbAdapter.aggregateFns();
 			for (const col of view.getViewColumnMappings()) if (col.aggFn && !fns.has(col.aggFn)) addRefusal(refusals, view.tableName, `View "${view.tableName}" field "${col.viewPath}": aggregate "${col.aggFn}" is not supported by this adapter (aggregateFns())`);
+			for (const source of d.viewSources.get(view.tableName)) if (d.externalTargets.get(source) === false) addRefusal(refusals, view.tableName, `View "${view.tableName}" reads "${source}" which is neither in the sync inventory nor present in the database`);
 		}
 		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 (!r.isView) {
+				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)`);
 			}
-			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.`);
+			for (const view of d.views) if (d.viewSources.get(view.tableName).includes(r.name)) referencers.push(`view "${view.tableName}"`);
+			if (referencers.length > 0) addRefusal(refusals, r.name, `Cannot drop ${r.isView ? "view " : ""}"${r.name}": it is still referenced by ${referencers.join(", ")}. Add "${r.name}" to the sync inventory or remove the reference.`);
 		}
 		return refusals;
 	}
@@ -1507,9 +1716,9 @@ var SchemaSync = class {
 			kind: "external",
 			index
 		};
-		for (const r of d.removed) if (r.isView) yield {
+		for (const name of d.removedViewOrder) yield {
 			kind: "drop-view",
-			name: r.name
+			name
 		};
 		for (const group of d.lateDropOrder) yield {
 			kind: "drop",
@@ -1549,7 +1758,11 @@ var SchemaSync = class {
 		/** Removed entries that were NOT dropped — they stay tracked (I2). */
 		const retained = [];
 		const droppedNames = /* @__PURE__ */ new Set();
-		/** Managed views whose stale definition could not be dropped (→ error entry, not recreated). */
+		/**
+		* Managed views whose step failed, with the message: a stale definition
+		* that could not be dropped (→ error entry, not recreated), or a create
+		* that errored — their dependents are not created over a missing source.
+		*/
 		const failedViews = /* @__PURE__ */ new Map();
 		/**
 		* Pending renames that did NOT run (the rename failed, or the entry
@@ -1558,22 +1771,9 @@ var SchemaSync = class {
 		* rename as pending again. Keyed by the readable's (new) name.
 		*/
 		const stillUnderOldName = /* @__PURE__ */ new Map();
-		for (const view of d.views) {
-			const plan = d.viewPlans.get(view.tableName);
-			try {
-				await dropOutdatedView(view, plan, this.space);
-			} catch (error) {
-				failedViews.set(view.tableName, this.stepFailed(error, "View sync", view.tableName));
-				if (plan.isRenamed) stillUnderOldName.set(view.tableName, {
-					name: view.renamedFrom,
-					isView: true,
-					viewType: view.viewPlan.materialized ? "M" : "V"
-				});
-			}
-		}
 		const droppedViewEntries = /* @__PURE__ */ new Map();
-		for (const r of d.removed) {
-			if (!r.isView) continue;
+		for (const name of d.removedViewOrder) {
+			const r = d.removedByName.get(name);
 			if (safe) {
 				retained.push(r);
 				continue;
@@ -1594,6 +1794,19 @@ var SchemaSync = class {
 				retained.push(r);
 			}
 		}
+		for (const view of d.views.toReversed()) {
+			const plan = d.viewPlans.get(view.tableName);
+			try {
+				await dropOutdatedView(view, plan, this.space);
+			} catch (error) {
+				failedViews.set(view.tableName, this.stepFailed(error, "View sync", view.tableName));
+				if (plan.isRenamed) stillUnderOldName.set(view.tableName, {
+					name: view.renamedFrom,
+					isView: true,
+					viewType: view.viewPlan.materialized ? "M" : "V"
+				});
+			}
+		}
 		/** FK keys dropped here per child (by its name) — named by a later failure on that child. */
 		const preDroppedFks = /* @__PURE__ */ new Map();
 		if (!safe) for (const t of d.tables) {
@@ -1651,12 +1864,20 @@ var SchemaSync = class {
 					const view = d.views[step.index];
 					const planned = d.viewEntries[step.index];
 					let msg = failedViews.get(view.tableName);
+					if (msg === void 0) {
+						const failedUpstream = d.viewSources.get(view.tableName).filter((n) => failedViews.has(n));
+						if (failedUpstream.length > 0) {
+							msg = `Upstream view ${failedUpstream.map((n) => `"${n}"`).join(", ")} failed — "${view.tableName}" was not created over it`;
+							this.logger.error?.(`[schema-sync] ${msg}`);
+						}
+					}
 					if (msg === void 0) try {
 						entries.push(await executeSyncView(view, planned));
 						break;
 					} catch (error) {
 						msg = this.stepFailed(error, "View sync", view.tableName);
 					}
+					failedViews.set(view.tableName, msg);
 					entries.push(planned.withError(msg));
 					break;
 				}
@@ -1812,8 +2033,9 @@ var SchemaSync = class {
 		}));
 		init.typeChanges = describeTypeChanges(diff);
 		Object.assign(init, describeNullableDefaults(diff));
+		init.derivedChanges = describeDerivedChanges(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 || diff.primaryKeyChanged !== void 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 || init.derivedChanges.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.`)];
@@ -1822,6 +2044,10 @@ var SchemaSync = class {
 			init.status = "error";
 			init.errors = [...init.errors ?? [], ...typeChangeErrors(readable, diff)];
 		}
+		if (init.derivedChanges.length > 0 && !safe && (!adapter.dropColumns || !adapter.syncColumns) && init.status !== "error") {
+			init.status = "error";
+			init.errors = [...init.errors ?? [], derivedRebuildUnsupported(name, init.derivedChanges.map((dc) => dc.column))];
+		}
 		if (diff.primaryKeyChanged && !safe && !adapter.rebuildPrimaryKey && !adapter.recreateTable && init.status !== "error") {
 			init.status = "error";
 			init.errors = [...init.errors ?? [], pkRebuildUnsupported(name, diff.primaryKeyChanged)];