@atscript/db 0.1.153 → 0.1.155

package/dist/sync.mjs

@@ -1,5 +1,173 @@
 import { r as DbError } from "./db-error-eSsQX7rt.mjs";
-import { _t as NoopLogger, a as computeTableHash, c as snapshotToExistingColumns, d as computeForeignKeyDiff, dt as aliasTargetOf, f as fkColumns, i as computeSchemaHash, l as snapshotToExistingTableOptions, m as hasForeignKeyChanges, o as computeTableSnapshot, p as fkKey, r as canonicalizeQueryNode, s as computeViewSnapshot, t as computeColumnDiff, u as viewSnapshotSources } from "./column-diff-DrE4ho_m.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-C68V_eYM.mjs";
+import { f as unionValueMembers } from "./validator-BC3nwFi4.mjs";
+//#region src/schema/json-column-copy.ts
+const NONE = {
+	copies: [],
+	jsonify: [],
+	errors: []
+};
+/** A text column type of the old layout (`TEXT`, `LONGTEXT`, `VARCHAR(n)`, `character varying`). */
+const TEXT_TYPE = /text|char|clob/i;
+/**
+* Design types a stored snapshot gives a field whose column held a whole
+* value as JSON text: the old union layout (`union`), or `@db.json`.
+*/
+const JSON_TEXT_DESIGN_TYPES = new Set([
+	"union",
+	"json",
+	"object"
+]);
+/** How a target column reads its value out of the JSON, or why it cannot. */
+function targetKind(fd) {
+	if (fd.encrypted) return { problem: "it is @db.encrypted" };
+	if (fd.isGeoPoint) return { problem: "it is a db.geoPoint" };
+	if (fd.storage === "json") return "json";
+	return fd.designType === "boolean" ? "boolean" : "text";
+}
+/** Whether `type` is a union one of whose value members is a string. */
+function hasStringMember(type) {
+	if (type?.type.kind !== "union") return false;
+	return unionValueMembers(type).members.some((m) => resolveDesignType(m) === "string");
+}
+/**
+* Plans {@link TJsonColumnMigration} for one table from its live column diff
+* (and its stored snapshot — on SQLite the old text column and a JSON
+* column have the same type).
+*/
+function planJsonColumnMigration(readable, diff, snapshot) {
+	const meta = readable.getMetadata();
+	if (meta.nestedObjects) return NONE;
+	const adapter = readable.dbAdapter;
+	const name = readable.tableName;
+	const removed = new Set(diff.removed.map((c) => c.name));
+	const snapshotFields = new Map(snapshot?.fields.map((f) => [f.physicalName, f]));
+	const out = {
+		copies: [],
+		jsonify: [],
+		errors: []
+	};
+	if (removed.size > 0) for (const parent of meta.flattenedParents) {
+		const source = relationalColumnName(parent, void 0, parent.includes("."));
+		if (!removed.has(source)) continue;
+		const was = snapshotFields.get(source);
+		if (was && !JSON_TEXT_DESIGN_TYPES.has(was.designType)) continue;
+		const prefix = `${parent}.`;
+		const targets = [];
+		const problems = [];
+		for (const fd of meta.storedDescriptors) {
+			if (!fd.path.startsWith(prefix)) continue;
+			const kind = targetKind(fd);
+			if (typeof kind === "object") {
+				problems.push(`"${fd.physicalName}" (${kind.problem})`);
+				continue;
+			}
+			targets.push({
+				column: fd.physicalName,
+				path: fd.path.slice(prefix.length).split("."),
+				kind,
+				field: fd
+			});
+		}
+		if (targets.length === 0 && problems.length === 0) continue;
+		if (problems.length > 0 || !adapter.copyFromJsonColumn) {
+			const why = problems.length > 0 ? `cannot fill ${problems.join(", ")} from it` : "the adapter cannot copy JSON values into columns";
+			out.errors.push(`Column "${source}" of ${name} holds "${parent}" as JSON text (the layout of atscript-db ≤ 0.1.154) and ${why}. Annotate "${parent}" with @db.json to keep it in one column, or migrate the data and drop "${source}" manually.`);
+			continue;
+		}
+		out.copies.push({
+			source,
+			targets
+		});
+	}
+	const typeChanged = new Map(diff.typeChanged.map((tc) => [tc.field.physicalName, tc]));
+	for (const fd of meta.storedDescriptors) {
+		if (fd.storage !== "json" || !hasStringMember(meta.flatMap.get(fd.path))) continue;
+		const tc = typeChanged.get(fd.physicalName);
+		const old = snapshotFields.get(fd.physicalName);
+		const dotted = `${fd.physicalName}.`;
+		if (!(tc !== void 0 && TEXT_TYPE.test(tc.existingType) || old !== void 0 && old.storage !== "json" && old.designType !== "json" || diff.removed.some((c) => c.name.startsWith(dotted)))) continue;
+		if (!adapter.jsonifyTextColumn) {
+			out.errors.push(`Column "${fd.physicalName}" of ${name} becomes a JSON column but the adapter cannot convert its text values. Migrate them manually.`);
+			continue;
+		}
+		out.jsonify.push(fd.physicalName);
+	}
+	return out.copies.length > 0 || out.jsonify.length > 0 || out.errors.length > 0 ? out : NONE;
+}
+/** The copy targets {@link applyJsonColumnMigration} adds: those not in the table yet. */
+function copyTargetsToAdd(migration, diff) {
+	const targets = new Set(migration.copies.flatMap((c) => c.targets.map((t) => t.column)));
+	return diff.added.filter((fd) => targets.has(fd.physicalName));
+}
+/**
+* The column diff the rest of the table's sync applies after
+* {@link applyJsonColumnMigration}: without the copy targets it added, with
+* their NOT NULL and model default as nullability / default changes. Also
+* what `plan({ safe: true })` reports as skipped — safe mode adds and fills
+* the targets but leaves them nullable and without their default.
+*/
+function diffAfterJsonCopy(migration, diff) {
+	const toAdd = copyTargetsToAdd(migration, diff);
+	if (toAdd.length === 0) return diff;
+	return {
+		...diff,
+		added: diff.added.filter((fd) => !toAdd.includes(fd)),
+		nullableChanged: [...diff.nullableChanged, ...toAdd.filter((fd) => !fd.optional).map((fd) => ({
+			field: fd,
+			wasNullable: true
+		}))],
+		defaultChanged: [...diff.defaultChanged, ...toAdd.filter((fd) => fd.defaultValue !== void 0).map((fd) => ({
+			field: fd,
+			newDefault: serializeDefaultValue(fd.defaultValue)
+		}))]
+	};
+}
+/**
+* Runs a planned {@link TJsonColumnMigration} — first, before any other
+* column work of the table: text columns become JSON text, the copy targets
+* that do not exist yet are added, and the values are copied. Returns the
+* diff without the columns it added ({@link diffAfterJsonCopy}). Idempotent:
+* a re-run converts nothing twice and copies only into rows whose targets
+* are all NULL.
+*
+* The targets are added nullable and WITHOUT a default — `ADD COLUMN …
+* DEFAULT`, or the type default an adapter gives a required column (a
+* leaf every member of a non-null union of objects declares), fills every
+* existing row, so the copy would skip them all. A model default and NOT
+* NULL are returned as default / nullability changes of the diff, which the
+* rest of the table's sync applies after the copy (`SET DEFAULT` / `SET NOT
+* NULL` / `MODIFY COLUMN`, a table recreation on SQLite). Rows the copy
+* leaves NULL keep NULL in a nullable column; a required one backfills them.
+*/
+async function applyJsonColumnMigration(adapter, migration, diff) {
+	for (const column of migration.jsonify) await adapter.jsonifyTextColumn(column);
+	if (migration.copies.length === 0) return {
+		diff,
+		added: []
+	};
+	const toAdd = copyTargetsToAdd(migration, diff);
+	let added = [];
+	if (toAdd.length > 0) added = (await adapter.syncColumns({
+		added: toAdd.map((fd) => ({
+			...fd,
+			optional: true,
+			defaultValue: void 0
+		})),
+		removed: [],
+		renamed: [],
+		typeChanged: [],
+		nullableChanged: [],
+		defaultChanged: [],
+		conflicts: []
+	})).added;
+	for (const copy of migration.copies) await adapter.copyFromJsonColumn(copy.source, copy.targets);
+	return {
+		diff: diffAfterJsonCopy(migration, diff),
+		added
+	};
+}
+//#endregion
 //#region src/schema/table-option-diff.ts
 /**
 * Computes the difference between desired and existing table options.
@@ -369,6 +537,10 @@ var SyncEntry = class SyncEntry {
 	fkChanged;
 	/** @since 0.1.141 — see {@link TSyncEntryInit.derivedChanges}. */
 	derivedChanges;
+	/** @since 0.1.155 — see {@link TSyncEntryInit.jsonCopies}. */
+	jsonCopies;
+	/** @since 0.1.155 — see {@link TSyncEntryInit.jsonified}. */
+	jsonified;
 	columnsAdded;
 	columnsRenamed;
 	columnsDropped;
@@ -403,6 +575,8 @@ var SyncEntry = class SyncEntry {
 		this.fkRemoved = init.fkRemoved ?? [];
 		this.fkChanged = init.fkChanged ?? [];
 		this.derivedChanges = init.derivedChanges ?? [];
+		this.jsonCopies = init.jsonCopies ?? [];
+		this.jsonified = init.jsonified ?? [];
 		this.columnsAdded = init.columnsAdded ?? [];
 		this.columnsRenamed = init.columnsRenamed ?? [];
 		this.columnsDropped = init.columnsDropped ?? [];
@@ -476,13 +650,13 @@ var SyncEntry = class SyncEntry {
 		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)` */
+	/** `! PK (id) → (code) — rebuild (table is empty)` / `— rebuild (rows satisfy the new key)` / `— 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`)}`];
+		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
@@ -508,6 +682,11 @@ var SyncEntry = class SyncEntry {
 			return `      ${dc.reason === "kind" ? c.red(line) : c.yellow(line)}`;
 		});
 	}
+	/** `~ addr → addr__street, addr__zip — copy JSON values` / `~ extra — text values as JSON`. */
+	printJsonMigration(c, mode) {
+		const copy = mode === "plan" ? "copy JSON values" : "JSON values copied";
+		return [...this.jsonified.map((col) => `      ${c.yellow(`~ ${col} — text values as JSON`)}`), ...this.jsonCopies.map((jc) => `      ${c.yellow(`~ ${jc.from} → ${jc.to.join(", ")} — ${copy}`)}`)];
+	}
 	/** `~ col — nullable` / `~ col — default a → b`, `— skipped (safe mode)` when pending. */
 	printNullableDefaults(c) {
 		const suffix = this.skipped.includes("nullable-defaults") ? " — skipped (safe mode)" : "";
@@ -565,6 +744,7 @@ var SyncEntry = class SyncEntry {
 				`  ${c.cyan(`~ ${vp}${label} — alter${renameInfo}`)}`,
 				...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.printNullableDefaults(c),
 				...this.printDerivedChanges(c, "plan"),
@@ -593,13 +773,14 @@ 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.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.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.printJsonMigration(c, "result"),
 				...this.printPkChange(c, "result"),
 				...this.printTypeChanges(c),
 				...this.printNullableDefaults(c),
@@ -641,14 +822,19 @@ function planTableInit(facts, safe, dependsOn) {
 	};
 	const skipped = safe ? safeModeSkips(facts) : [];
 	const pk = facts.diff?.primaryKeyChanged;
-	if (pk) init.pkChange = {
-		from: pk.from,
-		to: pk.to,
-		rebuild: !skipped.includes("pk-rebuild")
-	};
+	if (pk) {
+		init.pkChange = {
+			from: pk.from,
+			to: pk.to,
+			rebuild: !skipped.includes("pk-rebuild")
+		};
+		if (facts.populated === true) init.pkChange.populated = true;
+	}
 	if (!safe) return init;
+	const diff = afterJsonCopy(facts);
 	return {
 		...init,
+		...diff && describeNullableDefaults(diff),
 		columnsToDrop: [],
 		typeChanges: skipped.includes("recreate") ? init.typeChanges : [],
 		derivedChanges: skipped.includes("derived") ? init.derivedChanges : [],
@@ -666,6 +852,7 @@ function typeChangeStrategy(readable, diff) {
 	const adapter = readable.dbAdapter;
 	if (willDropRecreate(readable, diff, void 0)) return "drop";
 	if (readable.syncMethod === "recreate" && adapter.recreateTable) return "recreate";
+	if (diff.primaryKeyChanged && !adapter.rebuildPrimaryKey && adapter.recreateTable) return "recreate";
 	if (adapter.supportsColumnModify && adapter.syncColumns) return "modify";
 	return "none";
 }
@@ -733,11 +920,23 @@ async function executeSyncTable(facts, safe, deps, exec) {
 				await adapter.ensureTable(ensureOpts);
 				init.status = "create";
 			} else if (existing.length > 0) {
-				const diff = facts.diff ?? computeColumnDiff(readable.columnDescriptors, existing, adapter.typeMapper?.bind(adapter), { snapshot: storedSnapshot });
-				if (hasFkChanges && !adapter.syncForeignKeys && adapter.recreateTable) {
-					await adapter.recreateTable();
-					init.recreated = true;
+				let diff = facts.diff ?? computeColumnDiff(readable.columnDescriptors, existing, adapter.typeMapper?.bind(adapter), {
+					snapshot: storedSnapshot,
+					nativeDefaultFns: adapter.nativeDefaultFns()
+				});
+				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) {
+					phase = "JSON column copy";
+					const applied = await applyJsonColumnMigration(adapter, migration, diff);
+					diff = applied.diff;
+					Object.assign(init, describeJsonMigration(migration));
+					if (applied.added.length > 0) init.columnsAdded = applied.added;
 					init.status = "alter";
+					phase = "Column sync";
+				}
+				if (hasFkChanges && !adapter.syncForeignKeys && adapter.recreateTable) {
+					await recreateKeepingRenames(adapter, diff, init);
 					if (diff.primaryKeyChanged) init.pkChange = {
 						...diff.primaryKeyChanged,
 						rebuild: true
@@ -758,7 +957,10 @@ 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 }), init, safe, deps.logger, ensureOpts);
+		} 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 {
 			const existed = adapter.tableExists ? await adapter.tableExists() : true;
 			if (!init.recreated) {
@@ -900,6 +1102,13 @@ function willDropRecreate(readable, diff, optionDiff) {
 	if (readable.syncMethod === "drop" && (diff?.typeChanged.length ?? 0) > 0) return true;
 	return (optionDiff?.changed.some((c) => c.destructive) ?? false) && !(readable.syncMethod === "recreate" && !!adapter.recreateTable);
 }
+/**
+* The column diff the executor applies after the table's JSON column copy —
+* its targets' NOT NULL and defaults deferred (see {@link diffAfterJsonCopy}).
+*/
+function afterJsonCopy(facts) {
+	return facts.diff && facts.jsonMigration ? diffAfterJsonCopy(facts.jsonMigration, facts.diff) : facts.diff;
+}
 /** Records work safe mode skipped on the entry (see `SyncEntry.skipped`). */
 function markSkipped(init, kind) {
 	init.skipped = [...init.skipped ?? [], kind];
@@ -917,7 +1126,8 @@ function needsDdlForNullableDefaults(adapter) {
 * DDL either way.
 */
 function safeModeSkips(facts) {
-	const { readable, diff, optionDiff, fkDiff } = facts;
+	const { readable, optionDiff, fkDiff } = facts;
+	const diff = afterJsonCopy(facts);
 	const adapter = readable.dbAdapter;
 	const out = [];
 	if (facts.planEntry.status === "error") return out;
@@ -931,6 +1141,16 @@ function safeModeSkips(facts) {
 	if (optionDiff?.changed.some((c) => c.destructive)) out.push("table-options");
 	return out;
 }
+/** The plan-shaped summary of a {@link TJsonColumnMigration}. */
+function describeJsonMigration(migration) {
+	return {
+		jsonCopies: migration.copies.length > 0 ? migration.copies.map((c) => ({
+			from: c.source,
+			to: c.targets.map((t) => t.column)
+		})) : void 0,
+		jsonified: migration.jsonify.length > 0 ? migration.jsonify : void 0
+	};
+}
 /** The plan-shaped nullable / default change summaries of a diff. */
 function describeNullableDefaults(diff) {
 	return {
@@ -962,6 +1182,28 @@ async function dropAndRecreate(adapter, init, name, ensureOpts) {
 	init.recreated = true;
 	init.status = "alter";
 }
+/**
+* `recreateTable()` before the column diff is applied: it copies the rows by
+* column name, so the columns renamed in this run are renamed first — under
+* the old name their values would not be copied.
+*/
+async function recreateKeepingRenames(adapter, diff, init) {
+	if (diff.renamed.length > 0 && adapter.syncColumns) {
+		const { renamed } = await adapter.syncColumns({
+			added: [],
+			removed: [],
+			renamed: diff.renamed,
+			typeChanged: [],
+			nullableChanged: [],
+			defaultChanged: [],
+			conflicts: []
+		});
+		init.columnsRenamed = renamed;
+	}
+	await adapter.recreateTable();
+	init.recreated = true;
+	init.status = "alter";
+}
 async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensureOpts) {
 	const name = readable.tableName;
 	if (diff.conflicts.length > 0) {
@@ -980,11 +1222,8 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 			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, ensureOpts);
-		else if (strategy === "recreate") {
-			await adapter.recreateTable();
-			init.recreated = true;
-			init.status = "alter";
-		} else if (strategy === "modify") {
+		else if (strategy === "recreate") await recreateKeepingRenames(adapter, diff, init);
+		else if (strategy === "modify") {
 			needsSyncColumns = true;
 			init.status = "alter";
 		} else {
@@ -998,11 +1237,8 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 		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 (adapter.recreateTable) await recreateKeepingRenames(adapter, diff, init);
+		else init.status = "alter";
 		else if (init.status !== "error") {
 			if (safe && !init.recreated && needsDdlForNullableDefaults(adapter)) {
 				Object.assign(init, describeNullableDefaults(diff));
@@ -1014,7 +1250,7 @@ async function applyColumnDiff(adapter, readable, diff, init, safe, logger, ensu
 	}
 	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.columnsAdded = [...init.columnsAdded ?? [], ...syncResult.added];
 		init.columnsRenamed = syncResult.renamed;
 		if (syncResult.added.length > 0 || (syncResult.renamed?.length ?? 0) > 0 || needsSyncColumns) init.status = "alter";
 	}
@@ -1579,8 +1815,18 @@ 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 });
+				facts.diff = computeColumnDiff(readable.columnDescriptors, facts.existing, typeMapper, {
+					snapshot: storedSnapshot,
+					nativeDefaultFns: adapter.nativeDefaultFns()
+				});
 				this.populatePlanFromDiff(facts.diff, init, readable, safe);
+				const migration = planJsonColumnMigration(readable, facts.diff, storedSnapshot);
+				facts.jsonMigration = migration;
+				Object.assign(init, describeJsonMigration(migration));
+				if (migration.errors.length > 0) {
+					init.status = "error";
+					init.errors = [...init.errors ?? [], ...migration.errors];
+				} else if (init.status === "in-sync" && (migration.copies.length > 0 || migration.jsonify.length > 0)) init.status = "alter";
 			}
 		} else if (adapter.syncColumns) if (!storedSnapshot) {
 			if (!pendingRename) {
@@ -1591,7 +1837,10 @@ var SchemaSync = class {
 			}
 		} else {
 			const existing = snapshotToExistingColumns(storedSnapshot, readable);
-			facts.diff = computeColumnDiff(readable.columnDescriptors, existing, this.resolveTypeMapper(adapter), { snapshot: storedSnapshot });
+			facts.diff = computeColumnDiff(readable.columnDescriptors, existing, this.resolveTypeMapper(adapter), {
+				snapshot: storedSnapshot,
+				nativeDefaultFns: adapter.nativeDefaultFns()
+			});
 			this.populatePlanFromDiff(facts.diff, init, readable, safe);
 		}
 		else if (adapter.tableExists) {
@@ -1626,7 +1875,16 @@ var SchemaSync = class {
 				}, fk.existing)
 			}));
 		}
-		if (facts.diff?.primaryKeyChanged) facts.populated = await adapter.hasRows(pendingRename ? dbName : void 0) ?? "unknown";
+		if (facts.diff?.primaryKeyChanged) {
+			const tableName = pendingRename ? dbName : void 0;
+			facts.populated = await adapter.hasRows(tableName) ?? "unknown";
+			const { added, renamed } = facts.diff;
+			const { to } = facts.diff.primaryKeyChanged;
+			if (facts.populated === true && adapter.countKeyViolations && !added.some((f) => to.includes(f.physicalName))) {
+				const liveName = new Map(renamed.map((r) => [r.field.physicalName, r.oldName]));
+				facts.keyViolations = await adapter.countKeyViolations(to.map((c) => liveName.get(c) ?? c), tableName);
+			}
+		}
 		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);
@@ -1643,7 +1901,7 @@ var SchemaSync = class {
 			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.`);
+				if (t.populated === true && t.keyViolations !== 0) addRefusal(refusals, t.name, t.keyViolations === void 0 ? `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.` : `Primary key of "${t.name}" changed ${label} but ${t.keyViolations} row${t.keyViolations === 1 ? " has" : "s have"} a NULL or duplicate (${pk.to.join(", ")}) — fix or remove ${t.keyViolations === 1 ? "it" : "them"} (or migrate manually) 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) {
 					const liveInbound = (t.inboundFks ?? []).filter((fk) => {

package/dist/{validation-utils-DqZAH6aT.mjs → validation-utils-DxHIqa36.mjs}

@@ -18,6 +18,22 @@ function primitiveBaseType(def) {
 	const ct = def.config.type;
 	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
 }
+/**
+* Whether a definition is a union with a `null` member — `T | null`, or a
+* ref to an alias of one (compile-time mirror of the runtime nullable union,
+* since 0.1.155).
+*/
+function isNullableUnion(def, doc, depth = 0) {
+	if (!def || depth > 8) return false;
+	if (isRef(def)) {
+		if (def.id === "null") return true;
+		return isNullableUnion(doc.unwindType(def.id, def.chain)?.def, doc, depth + 1);
+	}
+	if (primitiveBaseType(def) === "null") return true;
+	const group = def;
+	if (!group.isGroup || group.op !== "|" || isStructure(def)) return false;
+	return group.unwrap().some((member) => isNullableUnion(member, doc, depth + 1));
+}
 /** Resolves a field/prop's primitive base type, or `undefined` if it isn't a ref-to-primitive. */
 function getPrimitiveBaseType(node, doc) {
 	const def = node.getDefinition();
@@ -50,16 +66,18 @@ function searchFieldVerdict(field, doc) {
 /**
 * Why an integer fulltext member is not index-backed (its exact-number match
 * would scan — or fail on MongoDB next to `$text`), or `undefined`. Backed:
-* `_id`, the first `@meta.id` of the type, or the first field (in declaration
-* order) of a `@db.index.plain` / `@db.index.unique` group.
+* `_id` or the first `@meta.id` of an interface's own fields (an inline
+* nested object's are no key of the row, like at runtime), or the first field
+* (in declaration order) of a `@db.index.plain` / `@db.index.unique` group.
 */
 function integerMemberIndexProblem(token) {
 	const field = token.parentNode;
 	const struct = getParentStruct(token);
 	if (!struct) return void 0;
-	if (field.id === "_id") return void 0;
 	const props = [...struct.props.values()];
-	if (field.countAnnotations("meta.id") > 0 && props.find((p) => p.countAnnotations("meta.id") > 0) === field) return;
+	const topLevel = !!struct.ownerNode && isInterface(struct.ownerNode);
+	if (topLevel && field.id === "_id") return void 0;
+	if (topLevel && field.countAnnotations("meta.id") > 0 && props.find((p) => p.countAnnotations("meta.id") > 0) === field) return;
 	for (const ann of ["db.index.plain", "db.index.unique"]) for (const own of field.annotations?.filter((a) => a.name === ann) ?? []) {
 		const group = own.args[0]?.text ?? field.id;
 		if (props.find((p) => p.annotations?.some((a) => a.name === ann && (a.args[0]?.text ?? p.id) === group)) === field) return void 0;
@@ -450,4 +468,4 @@ function forEachFieldRef(expr, fn) {
 	}
 }
 //#endregion
-export { validateFieldBaseType as C, validateExclusiveWith as S, getParentTypeName as _, hasAnyViewAnnotation as a, refActionAnnotation as b, joinTargets as c, viewJoins as d, viewScopeTypes as f, getParentStruct as g, getNavTargetTypeName as h, forEachFieldRef as i, validateQueryScope as l, getDbTableOwner as m, findFKFieldsPointingTo as n, isAliasDecl as o, getAnnotationAlias as p, findViewCycle as r, isDbSourceDecl as s, earlierJoinTargets as t, validateRefArgument as u, integerMemberIndexProblem as v, validateSiblingStringField as w, searchFieldVerdict as x, primitiveBaseType as y };
+export { validateExclusiveWith as C, searchFieldVerdict as S, validateSiblingStringField as T, getParentTypeName as _, hasAnyViewAnnotation as a, primitiveBaseType as b, joinTargets as c, viewJoins as d, viewScopeTypes as f, getParentStruct as g, getNavTargetTypeName as h, forEachFieldRef as i, validateQueryScope as l, getDbTableOwner as m, findFKFieldsPointingTo as n, isAliasDecl as o, getAnnotationAlias as p, findViewCycle as r, isDbSourceDecl as s, earlierJoinTargets as t, validateRefArgument as u, integerMemberIndexProblem as v, validateFieldBaseType as w, refActionAnnotation as x, isNullableUnion as y };

package/dist/{validation-utils-debIYpq0.cjs → validation-utils-_PA7iSLm.cjs}

@@ -18,6 +18,22 @@ function primitiveBaseType(def) {
 	const ct = def.config.type;
 	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
 }
+/**
+* Whether a definition is a union with a `null` member — `T | null`, or a
+* ref to an alias of one (compile-time mirror of the runtime nullable union,
+* since 0.1.155).
+*/
+function isNullableUnion(def, doc, depth = 0) {
+	if (!def || depth > 8) return false;
+	if ((0, _atscript_core.isRef)(def)) {
+		if (def.id === "null") return true;
+		return isNullableUnion(doc.unwindType(def.id, def.chain)?.def, doc, depth + 1);
+	}
+	if (primitiveBaseType(def) === "null") return true;
+	const group = def;
+	if (!group.isGroup || group.op !== "|" || (0, _atscript_core.isStructure)(def)) return false;
+	return group.unwrap().some((member) => isNullableUnion(member, doc, depth + 1));
+}
 /** Resolves a field/prop's primitive base type, or `undefined` if it isn't a ref-to-primitive. */
 function getPrimitiveBaseType(node, doc) {
 	const def = node.getDefinition();
@@ -50,16 +66,18 @@ function searchFieldVerdict(field, doc) {
 /**
 * Why an integer fulltext member is not index-backed (its exact-number match
 * would scan — or fail on MongoDB next to `$text`), or `undefined`. Backed:
-* `_id`, the first `@meta.id` of the type, or the first field (in declaration
-* order) of a `@db.index.plain` / `@db.index.unique` group.
+* `_id` or the first `@meta.id` of an interface's own fields (an inline
+* nested object's are no key of the row, like at runtime), or the first field
+* (in declaration order) of a `@db.index.plain` / `@db.index.unique` group.
 */
 function integerMemberIndexProblem(token) {
 	const field = token.parentNode;
 	const struct = getParentStruct(token);
 	if (!struct) return void 0;
-	if (field.id === "_id") return void 0;
 	const props = [...struct.props.values()];
-	if (field.countAnnotations("meta.id") > 0 && props.find((p) => p.countAnnotations("meta.id") > 0) === field) return;
+	const topLevel = !!struct.ownerNode && (0, _atscript_core.isInterface)(struct.ownerNode);
+	if (topLevel && field.id === "_id") return void 0;
+	if (topLevel && field.countAnnotations("meta.id") > 0 && props.find((p) => p.countAnnotations("meta.id") > 0) === field) return;
 	for (const ann of ["db.index.plain", "db.index.unique"]) for (const own of field.annotations?.filter((a) => a.name === ann) ?? []) {
 		const group = own.args[0]?.text ?? field.id;
 		if (props.find((p) => p.annotations?.some((a) => a.name === ann && (a.args[0]?.text ?? p.id) === group)) === field) return void 0;
@@ -528,6 +546,12 @@ Object.defineProperty(exports, "isDbSourceDecl", {
 		return isDbSourceDecl;
 	}
 });
+Object.defineProperty(exports, "isNullableUnion", {
+	enumerable: true,
+	get: function() {
+		return isNullableUnion;
+	}
+});
 Object.defineProperty(exports, "joinTargets", {
 	enumerable: true,
 	get: function() {