@atscript/db 0.1.161 → 0.1.163

package/dist/sync.mjs

@@ -1,6 +1,6 @@
-import { r as DbError } from "./db-error-eSsQX7rt.mjs";
-import { a as computeTableHash, c as serializeDefaultValue, d as viewSnapshotSources, f as computeForeignKeyDiff, ft as relationalColumnName, h as hasForeignKeyChanges, i as computeSchemaHash, j as resolveDesignType, l as snapshotToExistingColumns, m as fkKey, o as computeTableSnapshot, p as fkColumns, pt as aliasTargetOf, r as canonicalizeQueryNode, s as computeViewSnapshot, t as computeColumnDiff, u as snapshotToExistingTableOptions, yt as NoopLogger } from "./column-diff-DR1glykD.mjs";
-import { f as unionValueMembers } from "./validator-B3fPJjS1.mjs";
+import { r as DbError } from "./db-error-hraC12B9.mjs";
+import { A as hasForeignKeyChanges, D as computeForeignKeyDiff, O as fkColumns, P as resolveDesignType, St as NoopLogger, a as computeSchemaHash, c as computeViewSnapshot, d as snapshotToExistingTableOptions, f as viewSnapshotSources, gt as aliasTargetOf, ht as relationalColumnName, i as canonicalizeQueryNode, k as fkKey, l as serializeDefaultValue, o as computeTableHash, r as sameDefaultValue, s as computeTableSnapshot, t as computeColumnDiff, u as snapshotToExistingColumns } from "./column-diff-BfNIlMwX.mjs";
+import { f as unionValueMembers } from "./validator-DuDWsIdQ.mjs";
 //#region src/schema/json-column-copy.ts
 const NONE = {
 	copies: [],
@@ -505,6 +505,24 @@ async function readStoredSnapshot(space, tableName, _asView) {
 }
 //#endregion
 //#region src/schema/sync-entry.ts
+/** How each index change prints: its mark, color and past-tense word. */
+const INDEX_CHANGE_STYLE = {
+	add: {
+		mark: "+",
+		color: "green",
+		done: "added"
+	},
+	drop: {
+		mark: "-",
+		color: "red",
+		done: "dropped"
+	},
+	rebuild: {
+		mark: "~",
+		color: "yellow",
+		done: "rebuilt"
+	}
+};
 const noColor = {
 	green: (s) => s,
 	red: (s) => s,
@@ -559,6 +577,10 @@ var SyncEntry = class SyncEntry {
 	refused;
 	/** @since 0.1.141 — see {@link TSyncEntryInit.cascadeFrom}. */
 	cascadeFrom;
+	/** @since 0.1.162 — see {@link TSyncEntryInit.definitionChanged}. */
+	definitionChanged;
+	/** @since 0.1.162 — see {@link TSyncEntryInit.indexChanges}. */
+	indexChanges;
 	constructor(init) {
 		this.name = init.name;
 		this.viewType = init.viewType;
@@ -589,6 +611,8 @@ var SyncEntry = class SyncEntry {
 		this.dropGroup = init.dropGroup;
 		this.refused = init.refused ?? false;
 		this.cascadeFrom = init.cascadeFrom ?? [];
+		this.definitionChanged = init.definitionChanged ?? false;
+		this.indexChanges = init.indexChanges ?? [];
 	}
 	/**
 	* The init object this entry was built from — lets callers derive a
@@ -659,11 +683,13 @@ var SyncEntry = class SyncEntry {
 		return mode === "plan" ? [`      ${c.red(`! ${cols} — rebuild (${pk.populated ? "rows satisfy the new key" : "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.
+	* `! col: t1 → t2 — drop` (plan), `~ col: t1 → t2 — type changed` (result),
+	* or `! type col (t1 → t2) — skipped (safe mode)` in plan and result when
+	* the `'drop'` recreate was skipped.
 	*/
-	printTypeChanges(c) {
+	printTypeChanges(c, mode) {
 		if (this.skipped.includes("recreate")) return this.typeChanges.map((tc) => `      ${c.yellow(`! type ${tc.column} (${tc.fromType} → ${tc.toType}) — skipped (safe mode)`)}`);
+		if (mode === "result") return this.typeChanges.map((tc) => `      ${c.yellow(`~ ${tc.column}: ${tc.fromType} → ${tc.toType} — type changed`)}`);
 		return this.typeChanges.map((tc) => {
 			const action = this.syncMethod ? ` — ${this.syncMethod}` : " — requires migration";
 			return `      ${c.red(`! ${tc.column}: ${tc.fromType} → ${tc.toType}${action}`)}`;
@@ -707,6 +733,26 @@ var SyncEntry = class SyncEntry {
 			return `      ${tag} ${c.cyan(`option ${oc.key}`)}: ${oc.oldValue} → ${oc.newValue}${action}`;
 		});
 	}
+	/** `+ FK(a) → t — add` / `- … — remove` / `~ … — details` (plan); `added` / `removed` (result). */
+	printForeignKeys(c, mode) {
+		const [add, remove] = mode === "plan" ? ["add", "remove"] : ["added", "removed"];
+		return [
+			...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 ? ` → ${fk.targetTable}` : ""} — ${remove}`)}`),
+			...this.fkChanged.map((fk) => `      ${c.yellow(`~ FK(${fk.fields.join(",")}) → ${fk.targetTable} — ${fk.details}`)}`)
+		];
+	}
+	/** `+ index name — add` / `- … — drop` / `~ … — rebuild` (plan); `added` / `dropped` / `rebuilt` (result). */
+	printIndexChanges(c, mode) {
+		return this.indexChanges.map((ic) => {
+			const { mark, color, done } = INDEX_CHANGE_STYLE[ic.action];
+			return `      ${c[color](`${mark} index ${ic.name} — ${mode === "plan" ? ic.action : done}`)}`;
+		});
+	}
+	/** `· definition changed` — why a managed view is recreated. */
+	printDefinitionChanged(c) {
+		return this.definitionChanged ? [`      ${c.dim("· definition changed")}`] : [];
+	}
 	/** `· after: a, b` (plan only — the executor already runs in this order). */
 	printDependsOn(c) {
 		if (this.dependsOn.length === 0) return [];
@@ -745,15 +791,15 @@ var SyncEntry = class SyncEntry {
 				...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.printJsonMigration(c, "plan"),
-				...this.printTypeChanges(c),
+				...this.printTypeChanges(c, "plan"),
 				...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.printForeignKeys(c, "plan"),
+				...this.printIndexChanges(c, "plan"),
+				...this.printDefinitionChanged(c),
 				...this.printCascade(c),
 				...this.printDependsOn(c),
 				""
@@ -773,7 +819,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.derivedChanges.length > 0 || this.jsonCopies.length > 0 || this.jsonified.length > 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.jsonCopies.length > 0 || this.jsonified.length > 0 || this.typeChanges.length > 0 || this.nullableChanges.length > 0 || this.defaultChanges.length > 0 || this.fkAdded.length > 0 || this.fkRemoved.length > 0 || this.fkChanged.length > 0 || this.indexChanges.length > 0 || this.skipped.length > 0 || this.recreated || this.renamedFrom || this.status === "alter") {
 			const rlabel = this.recreated ? "recreated" : "altered";
 			const renameInfo = this.renamedFrom ? ` ${c.yellow(`(renamed from ${this.renamedFrom})`)}` : "";
 			return [
@@ -782,11 +828,14 @@ var SyncEntry = class SyncEntry {
 				...this.columnsRenamed.map((col) => `      ${c.yellow(`~ ${col} — renamed`)}`),
 				...this.printJsonMigration(c, "result"),
 				...this.printPkChange(c, "result"),
-				...this.printTypeChanges(c),
+				...this.printTypeChanges(c, "result"),
 				...this.printNullableDefaults(c),
 				...this.printDerivedChanges(c, "result"),
 				...this.columnsDropped.map((col) => `      ${c.red(`- ${col} — dropped`)}`),
 				...this.printOptionChanges(c, "result"),
+				...this.printForeignKeys(c, "result"),
+				...this.printIndexChanges(c, "result"),
+				...this.printDefinitionChanged(c),
 				...this.printCascade(c),
 				""
 			];
@@ -920,10 +969,7 @@ async function executeSyncTable(facts, safe, deps, exec) {
 				await adapter.ensureTable(ensureOpts);
 				init.status = "create";
 			} else if (existing.length > 0) {
-				let diff = facts.diff ?? computeColumnDiff(readable.columnDescriptors, existing, adapter.typeMapper?.bind(adapter), {
-					snapshot: storedSnapshot,
-					nativeDefaultFns: adapter.nativeDefaultFns()
-				});
+				let diff = facts.diff ?? computeColumnDiff(readable.columnDescriptors, existing, adapter.typeMapper?.bind(adapter), columnDiffOptions(adapter, storedSnapshot));
 				const migration = facts.jsonMigration ?? planJsonColumnMigration(readable, diff, storedSnapshot);
 				if (migration.errors.length > 0) throw new Error(migration.errors.join(" "));
 				if (migration.copies.length > 0 || migration.jsonify.length > 0) {
@@ -960,10 +1006,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 ?? computeColumnDiff(readable.columnDescriptors, snapshotToExistingColumns(storedSnapshot, readable), deps.resolveTypeMapper(adapter), {
-			snapshot: storedSnapshot,
-			nativeDefaultFns: adapter.nativeDefaultFns()
-		}), init, safe, deps.logger, ensureOpts);
+		} else await applyColumnDiff(adapter, readable, facts.diff ?? computeColumnDiff(readable.columnDescriptors, snapshotToExistingColumns(storedSnapshot, readable), deps.resolveTypeMapper(adapter), columnDiffOptions(adapter, storedSnapshot)), init, safe, deps.logger, ensureOpts);
 		else {
 			const existed = adapter.tableExists ? await adapter.tableExists() : true;
 			if (!init.recreated) {
@@ -971,6 +1014,10 @@ async function executeSyncTable(facts, safe, deps, exec) {
 				if (!existed) init.status = "create";
 			}
 		}
+		if (hasFkChanges && fkDiff && init.status !== "create" && init.status !== "error") {
+			Object.assign(init, describeForeignKeyChanges(fkDiff));
+			init.status = "alter";
+		}
 		phase = "Table option sync";
 		const optionDiff = facts.optionDiff;
 		if (init.status !== "create" && !init.recreated && init.status !== "error" && optionDiff && optionDiff.changed.length > 0) {
@@ -1005,8 +1052,15 @@ async function executeSyncTable(facts, safe, deps, exec) {
 		if (init.pkChange && facts.populated === true) init.pkChange.populated = true;
 		if (init.status === "error") return new SyncEntry(init);
 		phase = "Index/FK sync";
-		await adapter.syncIndexes(keptIndexes(init));
-		if (adapter.syncForeignKeys && !exec.deferForeignKeysTo) await adapter.syncForeignKeys();
+		const indexChanges = await adapter.syncIndexes(keptIndexes(init));
+		if (Array.isArray(indexChanges) && indexChanges.length > 0 && init.status !== "create" && !init.recreated) {
+			init.indexChanges = indexChanges;
+			init.status = "alter";
+		}
+		if (adapter.syncForeignKeys && !exec.deferForeignKeysTo) {
+			const fkChanges = await adapter.syncForeignKeys();
+			if (init.status !== "create" && !init.recreated && mergeLiveForeignKeyChanges(init, fkChanges)) init.status = "alter";
+		}
 		if (adapter.afterSyncTable) await adapter.afterSyncTable();
 	} catch (error) {
 		const dropped = droppedFks.length > 0 ? ` Dropped foreign keys before the failure: ${droppedFks.join(", ")} — the ones still in the model are re-added by the next run's syncForeignKeys.` : "";
@@ -1035,8 +1089,13 @@ async function executeDeferredForeignKeys(readable, entry, deps) {
 	const adapter = readable.dbAdapter;
 	if (!adapter.syncForeignKeys || entry.status === "error") return entry;
 	try {
-		await adapter.syncForeignKeys();
-		return entry;
+		const fkChanges = await adapter.syncForeignKeys();
+		if (entry.status === "create" || entry.recreated) return entry;
+		const init = entry.toInit();
+		return mergeLiveForeignKeyChanges(init, fkChanges) ? new SyncEntry({
+			...init,
+			status: "alter"
+		}) : entry;
 	} catch (error) {
 		const msg = `FK sync failed on ${readable.tableName}: ${error.message}`;
 		deps.logger.error?.(`[schema-sync] ${msg}`);
@@ -1082,6 +1141,14 @@ function describeDerivedChanges(diff) {
 		derived: dc.field.derived !== void 0
 	}));
 }
+/** The {@link computeColumnDiff} options for a table of `adapter`. */
+function columnDiffOptions(adapter, snapshot) {
+	return {
+		snapshot,
+		nativeDefaultFns: adapter.nativeDefaultFns(),
+		reportedDefault: adapter.reportedDefault?.bind(adapter)
+	};
+}
 /** The plan-shaped summary of a diff's type changes (`entry.typeChanges`). */
 function describeTypeChanges(diff) {
 	return diff.typeChanged.map((tc) => ({
@@ -1120,6 +1187,28 @@ function markSkipped(init, kind) {
 	init.skipped = [...init.skipped ?? [], kind];
 }
 /**
+* Whether the run (without safe mode) recreates this existing table — an FK
+* change on an adapter without `syncForeignKeys`, a `'drop'` / `'recreate'`
+* type change, nullable / default DDL through `recreateTable`, or a key
+* rebuild without `rebuildPrimaryKey`. The plan predicts no index work for
+* such a table: the recreate rebuilds every index.
+*/
+function runRecreatesTable(facts, safe = false) {
+	const { readable, fkDiff } = facts;
+	const adapter = readable.dbAdapter;
+	if (!adapter.recreateTable) return false;
+	if (fkDiff && hasForeignKeyChanges(fkDiff) && !adapter.syncForeignKeys) return true;
+	const diff = facts.diff;
+	if (!diff) return false;
+	if (diff.typeChanged.length > 0) {
+		const strategy = typeChangeStrategy(readable, diff);
+		if (strategy === "recreate" || strategy === "drop" && !safe) return true;
+	}
+	if (safe) return false;
+	if ((diff.nullableChanged.length > 0 || diff.defaultChanged.length > 0) && !adapter.supportsColumnModify && !!adapter.getExistingColumns) return true;
+	return !!diff.primaryKeyChanged && !adapter.rebuildPrimaryKey;
+}
+/**
 * Whether nullable/default changes need DDL on this adapter: in-place modify,
 * or a recreate on a live-introspected one (SQLite). Snapshot-based adapters
 * (MongoDB) have no column constraint to change — they only update the
@@ -1129,6 +1218,20 @@ function needsDdlForNullableDefaults(adapter) {
 	return !!adapter.supportsColumnModify && !!adapter.syncColumns || !!adapter.recreateTable && !!adapter.getExistingColumns;
 }
 /**
+* The `syncIndexes` options the run will pass for this table — what the plan
+* passes `planIndexes`, so both report the same index work.
+*/
+function plannedIndexOptions(facts, safe) {
+	if (!safe) return;
+	const diff = afterJsonCopy(facts);
+	return keptIndexes({
+		name: facts.name,
+		status: "alter",
+		skipped: safeModeSkips(facts),
+		typeChanges: diff ? describeTypeChanges(diff) : []
+	});
+}
+/**
 * The indexes `syncIndexes` keeps as they are because safe mode skipped
 * the change they depend on — a skipped key rebuild, the columns of a
 * skipped type-change recreate (see `TSyncIndexesOptions`).
@@ -1177,6 +1280,68 @@ function describeJsonMigration(migration) {
 		jsonified: migration.jsonify.length > 0 ? migration.jsonify : void 0
 	};
 }
+/** Builds a human-readable description of what changed in an FK constraint. */
+function buildFkChangeDetails(desired, existing) {
+	const parts = [];
+	if (existing.targetTable !== desired.targetTable) parts.push(`retarget ${existing.targetTable} → ${desired.targetTable}`);
+	if ([...existing.targetFields].toSorted().join(",") !== [...desired.targetFields].toSorted().join(",")) parts.push(`fields ${existing.targetFields.join(",")} → ${desired.targetFields.join(",")}`);
+	if ((existing.onDelete ?? void 0) !== (desired.onDelete ?? void 0)) parts.push(`onDelete ${existing.onDelete ?? "noAction"} → ${desired.onDelete ?? "noAction"}`);
+	if ((existing.onUpdate ?? void 0) !== (desired.onUpdate ?? void 0)) parts.push(`onUpdate ${existing.onUpdate ?? "noAction"} → ${desired.onUpdate ?? "noAction"}`);
+	return parts.join(", ");
+}
+/**
+* The plan-shaped summaries of a foreign-key diff (`entry.fkAdded` /
+* `fkRemoved` / `fkChanged`) — on plan entries and on the run entries that
+* applied them.
+*/
+function describeForeignKeyChanges(fkDiff) {
+	return {
+		fkAdded: fkDiff.added.map((fk) => ({
+			fields: fkColumns(fk).fields,
+			targetTable: fk.targetTable
+		})),
+		fkRemoved: fkDiff.removed.map((fk) => ({
+			fields: fk.fields,
+			targetTable: fk.targetTable
+		})),
+		fkChanged: fkDiff.changed.map((fk) => ({
+			fields: fkColumns(fk.desired).fields,
+			targetTable: fk.desired.targetTable,
+			details: buildFkChangeDetails({
+				...fk.desired,
+				targetFields: fkColumns(fk.desired).targetFields
+			}, fk.existing)
+		}))
+	};
+}
+/**
+* Folds the live FK changes `syncForeignKeys` / `planForeignKeys` report
+* into the entry: those the snapshot-based FK diff did not already name
+* (a constraint dropped or added by hand) join `fkAdded` / `fkRemoved`.
+* `true` when any was added.
+*/
+function mergeLiveForeignKeyChanges(init, changes) {
+	if (!changes || changes.length === 0) return false;
+	const known = new Set([
+		...init.fkAdded ?? [],
+		...init.fkRemoved ?? [],
+		...init.fkChanged ?? []
+	].map((fk) => fkKey(fk.fields)));
+	let merged = false;
+	for (const change of changes) {
+		const key = fkKey(change.fields);
+		if (known.has(key)) continue;
+		known.add(key);
+		const fk = {
+			fields: change.fields,
+			targetTable: change.targetTable ?? ""
+		};
+		if (change.action === "add") init.fkAdded = [...init.fkAdded ?? [], fk];
+		else init.fkRemoved = [...init.fkRemoved ?? [], fk];
+		merged = true;
+	}
+	return merged;
+}
 /** The plan-shaped nullable / default change summaries of a diff. */
 function describeNullableDefaults(diff) {
 	return {
@@ -1241,11 +1406,12 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 	let needsSyncColumns = false;
 	if (diff.typeChanged.length > 0 && init.status !== "error") {
 		const strategy = typeChangeStrategy(readable, diff);
+		const typeChanges = describeTypeChanges(diff);
+		if (strategy !== "none") init.typeChanges = typeChanges;
 		if (strategy === "drop") if (safe) {
-			init.typeChanges = describeTypeChanges(diff);
 			markSkipped(init, "recreate");
 			init.status = "alter";
-			const cols = init.typeChanges.map((tc) => `${tc.column}: ${tc.fromType} → ${tc.toType}`).join(", ");
+			const cols = 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, ensureOpts);
 		else if (strategy === "recreate") await recreateKeepingRenames(adapter, diff, init);
@@ -1260,12 +1426,15 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 		}
 	}
 	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 (needsDdlForNullableDefaults(adapter)) await recreateKeepingRenames(adapter, diff, init);
-		else init.status = "alter";
-		else if (init.status !== "error") {
+		if (!safe && !init.recreated && init.status !== "error") {
+			if (adapter.supportsColumnModify && adapter.syncColumns) {
+				needsSyncColumns = true;
+				init.status = "alter";
+			} else if (needsDdlForNullableDefaults(adapter)) await recreateKeepingRenames(adapter, diff, init);
+			else init.status = "alter";
+			Object.assign(init, describeNullableDefaults(diff));
+		} else if (init.status !== "error") {
+			if (!safe || !needsDdlForNullableDefaults(adapter) || init.recreated) Object.assign(init, describeNullableDefaults(diff));
 			if (safe && !init.recreated && needsDdlForNullableDefaults(adapter)) {
 				Object.assign(init, describeNullableDefaults(diff));
 				markSkipped(init, "nullable-defaults");
@@ -1360,15 +1529,6 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 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 = [];
-	if (existing.targetTable !== desired.targetTable) parts.push(`retarget ${existing.targetTable} → ${desired.targetTable}`);
-	if ([...existing.targetFields].toSorted().join(",") !== [...desired.targetFields].toSorted().join(",")) parts.push(`fields ${existing.targetFields.join(",")} → ${desired.targetFields.join(",")}`);
-	if ((existing.onDelete ?? void 0) !== (desired.onDelete ?? void 0)) parts.push(`onDelete ${existing.onDelete ?? "noAction"} → ${desired.onDelete ?? "noAction"}`);
-	if ((existing.onUpdate ?? void 0) !== (desired.onUpdate ?? void 0)) parts.push(`onUpdate ${existing.onUpdate ?? "noAction"} → ${desired.onUpdate ?? "noAction"}`);
-	return parts.join(", ");
-}
 function sortedUnique(names) {
 	return [...new Set(names)].toSorted();
 }
@@ -1640,6 +1800,7 @@ var SchemaSync = class {
 			this.assertLockHeld(heartbeat.getAbortReason);
 			const refusals = this.preflight(d, safe);
 			if (refusals.size > 0) {
+				await this.planLiveWork(d, safe);
 				const result = {
 					status: "refused",
 					schemaHash: hash,
@@ -1704,6 +1865,7 @@ var SchemaSync = class {
 				renamedFrom: plan.isRenamed ? view.renamedFrom : void 0,
 				recreated: viewRecreated(plan) || void 0,
 				cascadeFrom: plan.upstreamRecreated,
+				definitionChanged: plan.definitionChanged || void 0,
 				dependsOn: viewSources.get(view.tableName).filter((n) => tableNames.has(n) || viewNames.has(n) || externalViewNames.has(n))
 			}));
 		}
@@ -1841,10 +2003,7 @@ var SchemaSync = class {
 				init.columnsToAdd = [...readable.columnDescriptors];
 			} else if (facts.existing && facts.existing.length > 0) {
 				const typeMapper = adapter.typeMapper?.bind(adapter);
-				facts.diff = computeColumnDiff(readable.columnDescriptors, facts.existing, typeMapper, {
-					snapshot: storedSnapshot,
-					nativeDefaultFns: adapter.nativeDefaultFns()
-				});
+				facts.diff = computeColumnDiff(readable.columnDescriptors, facts.existing, typeMapper, columnDiffOptions(adapter, storedSnapshot));
 				this.populatePlanFromDiff(facts.diff, init, readable, safe);
 				const migration = planJsonColumnMigration(readable, facts.diff, storedSnapshot);
 				facts.jsonMigration = migration;
@@ -1863,10 +2022,7 @@ var SchemaSync = class {
 			}
 		} else {
 			const existing = snapshotToExistingColumns(storedSnapshot, readable);
-			facts.diff = computeColumnDiff(readable.columnDescriptors, existing, this.resolveTypeMapper(adapter), {
-				snapshot: storedSnapshot,
-				nativeDefaultFns: adapter.nativeDefaultFns()
-			});
+			facts.diff = computeColumnDiff(readable.columnDescriptors, existing, this.resolveTypeMapper(adapter), columnDiffOptions(adapter, storedSnapshot));
 			this.populatePlanFromDiff(facts.diff, init, readable, safe);
 		}
 		else if (adapter.tableExists) {
@@ -1884,22 +2040,7 @@ var SchemaSync = class {
 		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: fkColumns(fk).fields,
-				targetTable: fk.targetTable
-			}));
-			init.fkRemoved = fkDiff.removed.map((fk) => ({
-				fields: fk.fields,
-				targetTable: fk.targetTable
-			}));
-			init.fkChanged = fkDiff.changed.map((fk) => ({
-				fields: fkColumns(fk.desired).fields,
-				targetTable: fk.desired.targetTable,
-				details: buildFkChangeDetails({
-					...fk.desired,
-					targetFields: fkColumns(fk.desired).targetFields
-				}, fk.existing)
-			}));
+			Object.assign(init, describeForeignKeyChanges(fkDiff));
 		}
 		if (facts.diff?.primaryKeyChanged) {
 			const tableName = pendingRename ? dbName : void 0;
@@ -1917,6 +2058,26 @@ var SchemaSync = class {
 		return facts;
 	}
 	/**
+	* Folds the index / foreign-key work on each live table as it is now
+	* (`planIndexes` / `planForeignKeys`) into its plan entry. Read only when
+	* plan entries are reported (`plan()`, a refused run) — a run reports what
+	* `syncIndexes` / `syncForeignKeys` did.
+	*/
+	async planLiveWork(d, safe) {
+		await Promise.all(d.tables.map((t) => this.planTableLiveWork(t, safe)));
+	}
+	async planTableLiveWork(facts, safe) {
+		const adapter = facts.readable.dbAdapter;
+		const init = facts.planEntry;
+		if (!(init.status !== "create" && init.status !== "error" && (safe || !init.recreated) && !facts.pendingRename && !runRecreatesTable(facts, safe))) return;
+		const indexChanges = await adapter.planIndexes(plannedIndexOptions(facts, safe));
+		if (indexChanges.length > 0) {
+			init.indexChanges = indexChanges;
+			init.status = "alter";
+		}
+		if (adapter.planForeignKeys && mergeLiveForeignKeyChanges(init, await adapter.planForeignKeys())) init.status = "alter";
+	}
+	/**
 	* Pure validation over the discovery facts. Every refusal is a change that
 	* no order of DDL can apply safely; the messages are user-facing.
 	*/
@@ -2282,6 +2443,7 @@ var SchemaSync = class {
 		await this.store.ensureControlTable();
 		const d = await this.discover(resolved, safe);
 		const refusals = this.preflight(d, safe);
+		await this.planLiveWork(d, safe);
 		const entries = this.buildPlanEntries(d, safe, refusals);
 		if (!force) {
 			if (await this.store.readHash() === hash) return {
@@ -2420,4 +2582,4 @@ async function planSchema(space, types, opts) {
 	return new SchemaSync(space).plan(types, opts);
 }
 //#endregion
-export { SchemaSync, SyncEntry, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };
+export { SchemaSync, SyncEntry, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, sameDefaultValue, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };

package/dist/{validator-B4YDLUkj.cjs → validator-DK9Ijpo7.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-JcfJqqpk.cjs");
+const require_db_error = require("./db-error-DmF1_xrz.cjs");
 const require_ops = require("./ops.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 //#region src/shared/union-shape.ts
@@ -261,8 +261,9 @@ function createDbValidatorPlugin() {
 			const baseMeta = columnUnionBase(def)?.metadata;
 			const defaulted = !(belowAmbiguous(dbCtx, ctx.path) || ctx.root !== void 0 && pathBelowAmbiguous(ctx.root, ctx.path));
 			const has = (key) => defaulted && (meta.has(key) || baseMeta?.has(key) === true);
-			const serverManaged = has("db.default") || has("db.default.increment") || has("db.default.uuid") || has("db.default.now") || dbCtx.mode === "replace" && has("db.onUpdate.now") || meta.has("db.column.version") || meta.has("db.column.derived");
+			const serverManaged = has("db.default") || has("db.default.increment") || has("db.default.uuid") || has("db.default.now") || dbCtx.mode === "replace" && has("db.onUpdate.now") || meta.has("db.column.version") || meta.has("db.onUpdate.inc") || meta.has("db.column.derived");
 			const hasFK = meta.has("db.rel.FK");
+			if (dbCtx.keyless && meta.has("meta.id") && !ctx.path.includes(".")) return true;
 			if (serverManaged || hasFK) {
 				if (dbCtx.mode === "replace" && meta.has("meta.id") && !ctx.path.includes(".")) return;
 				return true;

package/dist/validator-DX97RzC2.d.cts

@@ -0,0 +1,108 @@
+import { TAtscriptAnnotatedType, TAtscriptTypeArray, TAtscriptTypeObject, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
+
+//#region src/patch/patch-types.d.ts
+interface TArrayPatch<A extends readonly unknown[]> {
+  $replace?: A;
+  $insert?: A;
+  $upsert?: A;
+  $update?: Array<Partial<TArrayElement<A>>>;
+  $remove?: Array<Partial<TArrayElement<A>>>;
+}
+type TArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends ReadonlyArray<infer ElementType> ? ElementType : never;
+/**
+ * Maps each property of T into a patch payload:
+ * - Array properties become `TArrayPatch<T[K]>`
+ * - Non-array properties become `Partial<T[K]>`
+ */
+type TDbPatch<T> = { [K in keyof T]?: T[K] extends Array<infer _> ? TArrayPatch<T[K]> : Partial<T[K]> };
+/**
+ * Extracts `@expect.array.key` properties from an array-of-objects type.
+ * These keys uniquely identify an element inside the array and are used
+ * for `$update`, `$remove`, and `$upsert` operations.
+ *
+ * @param def - Atscript array type definition.
+ * @returns Set of property names marked as keys; empty set if none.
+ */
+declare function getKeyProps(def: TAtscriptAnnotatedType<TAtscriptTypeArray>): Set<string>;
+//#endregion
+//#region src/shared/server-stamped.d.ts
+/**
+ * The annotations whose field the server writes on every update — the write
+ * sets `@db.onUpdate.now` to the current time and increments
+ * `@db.onUpdate.inc` — so a client value is overwritten (now) or dropped
+ * (inc). Dependency-free: UI and plugin code can import it from
+ * `@atscript/db/validator` without pulling the compiler into a bundle.
+ * @since 0.1.163
+ */
+declare const SERVER_STAMPED_ON_UPDATE_KEYS: ReadonlySet<string>;
+/**
+ * Whether a field's metadata marks it as stamped by the server on every
+ * update (`@db.onUpdate.now` or `@db.onUpdate.inc`) — e.g. to render it
+ * read-only in an edit form.
+ * @since 0.1.163
+ */
+declare function isServerStampedOnUpdate(metadata: {
+  has(key: string): boolean;
+}): boolean;
+//#endregion
+//#region src/validator.d.ts
+/** Write operation mode for validator configuration. */
+type ValidatorMode = "insert" | "patch" | "replace";
+/** Singleton db validator plugin — stateless, safe to share across all validators. */
+declare const dbPlugin: TValidatorPlugin;
+/**
+ * Builds a validator for a given write mode.
+ *
+ * Shared between server-side (`AtscriptDbTable`) and client-side (`ClientValidator`).
+ * Both use the same plugin, same `replace`, same `partial` logic.
+ *
+ * @param type - The annotated type to validate against.
+ * @param mode - The write operation mode.
+ * @param extraPlugins - Additional adapter-specific plugins (prepended before the db plugin).
+ * @param opts - `unknownProps` overrides the validator's unknown-property policy
+ *   (used by db-client's `lenientWrites`, where the served type may be a
+ *   projection of the full server-side type).
+ */
+declare function buildDbValidator(type: TAtscriptAnnotatedType, mode: ValidatorMode, extraPlugins?: TValidatorPlugin[], opts?: {
+  unknownProps?: "strip" | "ignore" | "error";
+}): Validator<any>;
+/**
+ * Path-aware `partial` callback for patch/update validation — the single
+ * implementation shared by the server's `bulkUpdate` validator and the
+ * client's patch preflight:
+ *
+ * - the root object is partial (a patch names only the fields it touches)
+ * - nav-relation subtrees are partial (nested data is validated by its own table)
+ * - `@db.patch.strategy "merge"` blocks are partial (the decomposer merges
+ *   per leaf, so absent keys survive server-side by design)
+ *
+ * Every other nested object stays strict: non-merge blocks are `$set` as a
+ * whole (replace semantics), so their required fields really are required.
+ */
+declare function buildPatchPartial(navPaths: ReadonlySet<string>): (def: TAtscriptAnnotatedType<TAtscriptTypeObject>, path: string) => boolean;
+/** Returns true if the annotated type is a navigation relation (TO/FROM/VIA). */
+declare function isNavRelation(type: TAtscriptAnnotatedType): boolean;
+/**
+ * Forces nav fields non-optional so the plugin handles null/undefined checks.
+ * The Validator caches replace results internally, so this allocates at most once per type node.
+ */
+declare function forceNavNonOptional(type: TAtscriptAnnotatedType): TAtscriptAnnotatedType;
+/** Result of {@link buildValidationContext}. */
+interface ValidationContext {
+  /** Flat map of dotted field paths → annotated types (same shape the server builds). */
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  /** Set of field paths that are navigation relations (TO/FROM/VIA). */
+  navFields: ReadonlySet<string>;
+}
+/**
+ * Builds a lightweight validation context from a deserialized Atscript type.
+ *
+ * This is the client-side equivalent of the server's `TableMetadata.build()`,
+ * without any adapter-specific processing (physical columns, index resolution, etc.).
+ *
+ * @param type - A deserialized annotated type (from `deserializeAnnotatedType(meta.type)`).
+ * @returns `flatMap` and `navFields` suitable for passing to `createDbValidatorPlugin` via `DbValidationContext`.
+ */
+declare function buildValidationContext(type: TAtscriptAnnotatedType<TAtscriptTypeObject>): ValidationContext;
+//#endregion
+export { buildValidationContext as a, isNavRelation as c, TArrayPatch as d, TDbPatch as f, buildPatchPartial as i, SERVER_STAMPED_ON_UPDATE_KEYS as l, ValidatorMode as n, dbPlugin as o, getKeyProps as p, buildDbValidator as r, forceNavNonOptional as s, ValidationContext as t, isServerStampedOnUpdate as u };