@happyvertical/smrt-core 0.51.38 → 0.52.0

package/dist/migrations/differ.js

@@ -1,12 +1,12 @@
+import { conflictIndexName, isLegacyNaturalKeyIndex } from "../schema/conflict-target.js";
 import { normalizeForeignKeyAction, requireForeignKeyAction } from "../schema/foreign-key-policy.js";
 import { isJsonPathIndex, isStiSubtypeUniqueIndex, renderIndexTarget, shortenIdentifier } from "../schema/index-utils.js";
-import { foreignKeyConstraintName, foreignKeyRelationshipKey, renderForeignKeyAddStatements, renderForeignKeyOrphanDetector, renderForeignKeyOrphanRepair, schemaForeignKeys, schemaForeignKeysForEngine } from "../schema/foreign-key-ddl.js";
+import { foreignKeyConstraintName, foreignKeyRelationshipKey, renderForeignKeyAddStatements, renderForeignKeyOrphanDetector, renderForeignKeyOrphanRepair, renderForeignKeyReplaceStatements, schemaForeignKeys, schemaForeignKeysForEngine } from "../schema/foreign-key-ddl.js";
 import { renderNullEqualConflictIndex } from "../schema/ddl/null-equal-index.js";
 import { detectEngine, getDDLStrategy } from "../schema/ddl/index.js";
-import { conflictIndexName } from "../schema/conflict-target.js";
 import { mapWithConcurrency } from "../schema/bounded-concurrency.js";
 import { columnsAllValuesUuidShapedBatch, columnsHaveNonEmptyValueBatch, nonEmptyValuePredicate, resolveRenameDataPendingCandidates, uuidInvalidShapePredicate } from "../schema/column-data-probes.js";
-import { maskSampleValue, probeCastSafety, renderJsonbColumnConversion, renderTimestamptzColumnConversion } from "../schema/text-cast-probe.js";
+import { isEmptyTextOnlyProbe, maskSampleValue, probeCastSafety, renderEmptyTextAsNullExpression, renderEmptyTextPredicate, renderJsonbColumnConversion, renderTimestamptzColumnConversion } from "../schema/text-cast-probe.js";
 import { describeForeignKeyTypeConflict, planUuidConvergence, renderUuidConvergenceRepairHint, renderUuidShapeProbe } from "../schema/uuid-convergence.js";
 import "../schema/utils.js";
 import { planSqliteTableRebuilds, sqliteBackfillPlaceholderSql, sqliteRebuildPlaceholderSql } from "./sqlite-rebuild.js";
@@ -19,6 +19,12 @@ import { createLogger } from "@happyvertical/logger";
 * a SchemaDiff with the differences.
 */
 var logger = createLogger({ level: "info" });
+/** Actions that change child rows when the parent is deleted or updated. */
+var ROW_CHANGING_FOREIGN_KEY_ACTIONS = /* @__PURE__ */ new Set([
+	"CASCADE",
+	"SET NULL",
+	"SET DEFAULT"
+]);
 /**
 * `mismatch.actual` of the manual change reported when a required column
 * could not be added to a populated table (#3008): the column is absent.
@@ -330,6 +336,8 @@ var SchemaComparer = class SchemaComparer {
 	liveSchemas = /* @__PURE__ */ new Map();
 	/** Convergence plan for this run; `null` on non-PostgreSQL engines. */
 	uuidConvergence = null;
+	/** Parents created by this compare() batch, never a standalone compareTable(). */
+	plannedTables = /* @__PURE__ */ new Map();
 	/**
 	* Rename-pending advisory findings for this `compare()` run, keyed by
 	* table name (#2878). `compareTable()` reads from here when it is being
@@ -401,6 +409,7 @@ var SchemaComparer = class SchemaComparer {
 		this.indexPredicateCache = null;
 		try {
 			const existingTables = await this.getExistingTables();
+			this.plannedTables = new Map(Object.entries(manifestSchemas).filter(([name, schema]) => !existingTables.has(name) && schema.tableName === name));
 			await this.prefetchLiveSchemas(Object.keys(manifestSchemas).filter((tableName) => existingTables.has(tableName)));
 			await this.precomputeIndexPredicates();
 			await this.precomputeRenameDataPending(manifestSchemas, existingTables);
@@ -432,6 +441,7 @@ var SchemaComparer = class SchemaComparer {
 			}
 			return diff;
 		} finally {
+			this.plannedTables.clear();
 			this.renameDataPendingCache = null;
 			this.indexPredicateCache = null;
 		}
@@ -671,7 +681,21 @@ var SchemaComparer = class SchemaComparer {
 	* affirmatively confirmed safe or affirmatively confirmed unsafe.
 	*/
 	async probeTextCastShape(tableName, columnName, kind) {
-		return probeCastSafety(this.db, tableName, columnName, kind);
+		return probeCastSafety(this.db, tableName, columnName, kind, { emptyTextAsNull: this.options.emptyTextAsNull === true });
+	}
+	/**
+	* Explain a probe's empty-text finding (#3226) for a blocking advisory:
+	* how many of the offending values are empty text and what the opt-in
+	* would do with them (or why it cannot).
+	*/
+	describeEmptyTextFinding(probe, nullable) {
+		const emptyCount = probe.emptyCount ?? 0;
+		if (emptyCount === 0) return "";
+		const emptyOnly = emptyCount === probe.count;
+		const subject = emptyOnly ? `All ${emptyCount} are empty text ('').` : `${emptyCount} of them are empty text ('').`;
+		if (!nullable) return ` ${subject} The column is NOT NULL, so empty text cannot become NULL; store real values instead.`;
+		if (!emptyOnly) return ` ${subject} \`--empty-text-as-null\` would store those as NULL, but the other value(s) must be repaired first.`;
+		return ` ${subject} Rerun with \`smrt db:migrate --empty-text-as-null\` to store them as NULL (the column is nullable).`;
 	}
 	/**
 	* Turn the convergence plan into diff entries: executable `type_upgrade`
@@ -722,11 +746,12 @@ var SchemaComparer = class SchemaComparer {
 	* `undefined` means the pair is compatible (or unknowable) and the ordinary
 	* add path applies.
 	*/
-	async describeForeignKeyTypeBlock(tableName, dbSchema, foreignKey) {
+	async describeForeignKeyTypeBlock(tableName, dbSchema, manifest, foreignKey) {
 		if (this.engine !== "postgres") return void 0;
 		const parentSchema = foreignKey.referencesTable === tableName ? dbSchema : await this.getLiveSchema(foreignKey.referencesTable);
-		const childType = dbSchema.columns[foreignKey.column]?.type;
-		const parentType = parentSchema?.columns[foreignKey.referencesColumn]?.type;
+		const declaredType = (type) => type === void 0 ? void 0 : this.ddlStrategy.mapType(isValidSQLDataType(type) ? type : "TEXT");
+		const childType = dbSchema.columns[foreignKey.column]?.type ?? declaredType(manifest.columns[foreignKey.column]?.type);
+		const parentType = parentSchema?.columns[foreignKey.referencesColumn]?.type ?? declaredType(this.plannedTables.get(foreignKey.referencesTable)?.columns[foreignKey.referencesColumn]?.type);
 		if (!childType || !parentType) return void 0;
 		const plan = this.uuidConvergence;
 		if ((plan?.effectiveType(tableName, foreignKey.column) ?? this.normalizeType(childType)) === (plan?.effectiveType(foreignKey.referencesTable, foreignKey.referencesColumn) ?? this.normalizeType(parentType))) return void 0;
@@ -786,7 +811,13 @@ var SchemaComparer = class SchemaComparer {
 				uuidCastSide: orphanOptions.uuidCastSide,
 				nullable: orphanOptions.nullable
 			});
-			if (liveForeignKeys.some((live) => live.column === foreignKey.column)) {
+			const sameColumn = liveForeignKeys.some((live) => live.column === foreignKey.column);
+			let replacement;
+			if (sameColumn && this.engine === "postgres") replacement = await this.findReplaceableForeignKey(tableName, liveForeignKeys, foreignKey, {
+				onDelete: expectedDelete,
+				onUpdate: expectedUpdate
+			});
+			if (sameColumn && !replacement) {
 				changes.push({
 					type: "add_foreign_key",
 					table: tableName,
@@ -794,7 +825,7 @@ var SchemaComparer = class SchemaComparer {
 					foreignKey,
 					advisory: {
 						severity: "warning",
-						message: `Foreign key ${tableName}.${foreignKey.column} exists with a different target or action. Drop the old constraint deliberately, repair any orphan rows, then rerun the migration.`,
+						message: `Foreign key ${tableName}.${foreignKey.column} exists with a different target or action. ` + (this.engine === "postgres" ? "Drop the old constraint deliberately, repair any orphan rows, then rerun the migration." : this.engine === "sqlite" ? "SQLite cannot drop or alter a foreign key in place: rebuild the table with the generated constraint (repair any orphan rows first)." : "DuckDB cannot alter a foreign key in place: rebuild the table with the generated constraint (repair any orphan rows first)."),
 						suggestedSql: [detectorSql, repairSql]
 					}
 				});
@@ -816,7 +847,7 @@ var SchemaComparer = class SchemaComparer {
 				});
 				continue;
 			}
-			const typeBlock = await this.describeForeignKeyTypeBlock(tableName, dbSchema, foreignKey);
+			const typeBlock = await this.describeForeignKeyTypeBlock(tableName, dbSchema, manifest, foreignKey);
 			if (typeBlock) {
 				const textNodes = manifest.columns[foreignKey.column]?.type === "UUID" && manifestSchemas[foreignKey.referencesTable]?.columns[foreignKey.referencesColumn]?.type === "UUID" ? [this.normalizeType(dbSchema.columns[foreignKey.column]?.type ?? "") === "TEXT" ? {
 					table: tableName,
@@ -839,7 +870,32 @@ var SchemaComparer = class SchemaComparer {
 				});
 				continue;
 			}
-			if (Boolean(dbSchema.columns[foreignKey.column]) && await this.foreignKeyHasOrphans(tableName, foreignKey, orphanOptions)) {
+			const plannedParent = this.liveSchemas.get(foreignKey.referencesTable) ? void 0 : this.plannedTables.get(foreignKey.referencesTable);
+			if (plannedParent) {
+				const parentColumn = plannedParent.columns[foreignKey.referencesColumn];
+				let childEmpty = false;
+				if (parentColumn) try {
+					const result = await this.db.query(`SELECT 1 FROM ${this.quoteIdentifier(tableName)} LIMIT 1`);
+					childEmpty = (Array.isArray(result) ? result : result.rows || []).length === 0;
+				} catch (error) {
+					throw new Error(`[SchemaComparer] Cannot prove ${tableName} empty for planned parent ${foreignKey.referencesTable}; refusing automatic constraint addition: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+				}
+				if (!parentColumn || !childEmpty) {
+					changes.push({
+						type: "add_foreign_key",
+						table: tableName,
+						name: foreignKeyConstraintName(tableName, foreignKey),
+						foreignKey,
+						advisory: {
+							severity: "warning",
+							message: !parentColumn ? `Cannot add foreign key ${tableName}.${foreignKey.column}: planned parent ${foreignKey.referencesTable} has no column ${foreignKey.referencesColumn}. Correct the manifest, then rerun.` : `Cannot add foreign key ${tableName}.${foreignKey.column}: child table is not empty and planned parent ${foreignKey.referencesTable} does not exist yet. Create and populate the parent deliberately, then rerun the orphan preflight.`
+						}
+					});
+					continue;
+				}
+			}
+			const childColumnExists = Boolean(dbSchema.columns[foreignKey.column]);
+			if (!plannedParent && childColumnExists && await this.foreignKeyHasOrphans(tableName, foreignKey, orphanOptions)) {
 				changes.push({
 					type: "add_foreign_key",
 					table: tableName,
@@ -861,11 +917,60 @@ var SchemaComparer = class SchemaComparer {
 				table: tableName,
 				name: constraintName,
 				foreignKey,
-				sqlStatements: renderForeignKeyAddStatements(tableName, foreignKey)
+				sqlStatements: replacement ? renderForeignKeyReplaceStatements(tableName, foreignKey, replacement.constraintName) : renderForeignKeyAddStatements(tableName, foreignKey),
+				...replacement ? { note: replacement.note } : {},
+				...replacement?.destructive ? { advisory: {
+					severity: "warning",
+					message: replacement.destructive
+				} } : {}
 			});
 		}
 		return changes;
 	}
+	/**
+	* Decide whether a live PostgreSQL foreign key on the same column and
+	* target can have its referential actions converged automatically
+	* (#3023). The constraint must be one SMRT rendered: the deterministic
+	* canonical name, one column to one column, MATCH SIMPLE, not deferrable,
+	* already validated, and with default trigger enforcement. Only then is it
+	* replaced build-then-swap (`renderForeignKeyReplaceStatements()`: a staged
+	* constraint added NOT VALID and validated before the old one is dropped
+	* and the staged one renamed; `--postgres-safe` validates and swaps outside
+	* the batch transaction). A change that turns on a row-changing action
+	* carries a `warning` advisory. Everything else keeps the manual advisory, because a
+	* differently named or shaped constraint may be one an operator created on
+	* purpose.
+	*/
+	async findReplaceableForeignKey(tableName, liveForeignKeys, foreignKey, expected) {
+		const onColumn = (liveForeignKeys || []).filter((live) => live.column === foreignKey.column);
+		if (onColumn.length !== 1) return void 0;
+		const [live] = onColumn;
+		if (live.referencesTable !== foreignKey.referencesTable || live.referencesColumn !== foreignKey.referencesColumn) return;
+		const canonicalName = foreignKeyConstraintName(tableName, foreignKey);
+		let rows;
+		try {
+			const result = await this.db.query(`SELECT con.conname AS constraint_name, con.convalidated AS validated, con.condeferrable AS deferrable, con.confmatchtype AS match_type, cardinality(con.conkey) AS child_keys, cardinality(con.confkey) AS parent_keys, child_attr.attname AS child_column, parent.relname AS parent_table, parent_attr.attname AS parent_column, EXISTS (SELECT 1 FROM pg_trigger AS trg WHERE trg.tgconstraint = con.oid AND trg.tgenabled <> 'O') AS nondefault_trigger_mode FROM pg_constraint AS con JOIN pg_class AS child ON child.oid = con.conrelid JOIN pg_namespace AS child_ns ON child_ns.oid = child.relnamespace JOIN pg_class AS parent ON parent.oid = con.confrelid JOIN pg_attribute AS child_attr ON child_attr.attrelid = con.conrelid AND child_attr.attnum = con.conkey[1] JOIN pg_attribute AS parent_attr ON parent_attr.attrelid = con.confrelid AND parent_attr.attnum = con.confkey[1] WHERE con.contype = 'f' AND child_ns.nspname = 'public' AND child.relname = ${this.quoteLiteral(tableName)} AND child_attr.attname = ${this.quoteLiteral(foreignKey.column)}`);
+			rows = Array.isArray(result) ? result : result.rows || [];
+		} catch {
+			return;
+		}
+		if (rows.length !== 1) return void 0;
+		const [row] = rows;
+		if (row.constraint_name !== canonicalName || row.parent_table !== foreignKey.referencesTable || row.parent_column !== foreignKey.referencesColumn || Number(row.child_keys) !== 1 || Number(row.parent_keys) !== 1 || row.validated !== true || row.deferrable === true || row.match_type !== "s" || row.nondefault_trigger_mode === true) return;
+		const liveDelete = normalizeForeignKeyAction(live.onDelete) || "NO ACTION";
+		const liveUpdate = normalizeForeignKeyAction(live.onUpdate) || "NO ACTION";
+		const parts = [];
+		if (liveDelete !== expected.onDelete) parts.push(`ON DELETE ${liveDelete} → ${expected.onDelete}`);
+		if (liveUpdate !== expected.onUpdate) parts.push(`ON UPDATE ${liveUpdate} → ${expected.onUpdate}`);
+		const destructive = [];
+		if (liveDelete !== expected.onDelete && ROW_CHANGING_FOREIGN_KEY_ACTIONS.has(expected.onDelete)) destructive.push(`deleting a ${foreignKey.referencesTable} row will now ${expected.onDelete === "CASCADE" ? "DELETE" : `${expected.onDelete} on`} its ${tableName} rows (was ${liveDelete})`);
+		if (liveUpdate !== expected.onUpdate && ROW_CHANGING_FOREIGN_KEY_ACTIONS.has(expected.onUpdate)) destructive.push(`changing a ${foreignKey.referencesTable}.${foreignKey.referencesColumn} value will now ${expected.onUpdate} ${tableName}.${foreignKey.column} (was ${liveUpdate})`);
+		return {
+			constraintName: canonicalName,
+			note: `replaces ${canonicalName}: ${parts.join(", ")}`,
+			...destructive.length > 0 ? { destructive: `DESTRUCTIVE foreign-key change on ${tableName}.${foreignKey.column}: ${destructive.join("; ")}. This applies to every delete, including raw SQL, admin tooling and tenant purges. Review it before migrating; declare a different onDelete/onUpdate to keep the old behaviour.` } : {}
+		};
+	}
 	async foreignKeyHasOrphans(tableName, foreignKey, options) {
 		try {
 			const result = await this.db.query(renderForeignKeyOrphanDetector(tableName, foreignKey, {
@@ -994,6 +1099,12 @@ var SchemaComparer = class SchemaComparer {
 			let timestamptzProbe;
 			if (timestamptzUpgradeCandidate) timestamptzProbe = await this.probeTextCastShape(tableName, colName, "timestamptz");
 			const nativeJsonDrift = nativeJsonToJsonb && (jsonProbe?.status === "clean" || jsonProbe?.status === "dirty");
+			const emptyTextNullable = colDef.notNull !== true && dbCol.notNull !== true;
+			const convertEmptyText = this.options.emptyTextAsNull === true && emptyTextNullable;
+			const jsonEmptyTextToNull = convertEmptyText && isEmptyTextOnlyProbe(jsonProbe);
+			const timestamptzEmptyTextToNull = convertEmptyText && isEmptyTextOnlyProbe(timestamptzProbe);
+			const jsonConvertible = jsonProbe?.status === "clean" || jsonEmptyTextToNull;
+			const timestamptzConvertible = timestamptzProbe?.status === "clean" || timestamptzEmptyTextToNull;
 			if ((normalizedExpected !== normalizedActual || nativeJsonDrift) && !isUuidTextEquivalent && !isJsonTextEquivalent) {
 				typeDrifted = !(nativeJsonToJsonb && jsonProbe?.status === "dirty");
 				const hasLiveDefault = dbCol.defaultValue !== null && dbCol.defaultValue !== void 0;
@@ -1001,12 +1112,21 @@ var SchemaComparer = class SchemaComparer {
 					hasLiveDefault,
 					manifestDefaultValue: colDef.defaultValue
 				};
+				const jsonConversionOptions = {
+					...conversionOptions,
+					...jsonEmptyTextToNull ? { emptyTextAsNull: true } : {}
+				};
+				const timestamptzConversionOptions = {
+					...conversionOptions,
+					...timestamptzEmptyTextToNull ? { emptyTextAsNull: true } : {}
+				};
+				const emptyTextNote = (probe) => isEmptyTextOnlyProbe(probe) ? { note: `${probe.emptyCount} empty-text value(s) become NULL (--empty-text-as-null)` } : {};
 				const liveOnlyDefaultNeedsRelaxOptIn = hasLiveDefault && colDef.defaultValue === void 0 && !this.options.relaxColumns;
 				const jsonMismatch = {
 					expected: nativeJsonToJsonb ? expectedEngineType : colDef.type,
 					actual: dbCol.type
 				};
-				if (jsonUpgradeCandidate && jsonProbe?.status === "clean" && liveOnlyDefaultNeedsRelaxOptIn) changes.push({
+				if (jsonUpgradeCandidate && jsonConvertible && liveOnlyDefaultNeedsRelaxOptIn) changes.push({
 					type: "type_upgrade",
 					table: tableName,
 					name: colName,
@@ -1015,11 +1135,11 @@ var SchemaComparer = class SchemaComparer {
 					advisory: {
 						severity: "warning",
 						message: `blocked: ${tableName}.${colName} has a live default (${String(dbCol.defaultValue)}) the manifest no longer declares; converging to jsonb requires dropping it first. ${this.relaxHint("drop it as part of this conversion")}`,
-						suggestedSql: renderJsonbColumnConversion(tableName, colName, conversionOptions)
+						suggestedSql: renderJsonbColumnConversion(tableName, colName, jsonConversionOptions)
 					}
 				});
-				else if (jsonUpgradeCandidate && jsonProbe?.status === "clean") {
-					const statements = renderJsonbColumnConversion(tableName, colName, conversionOptions);
+				else if (jsonUpgradeCandidate && jsonConvertible) {
+					const statements = renderJsonbColumnConversion(tableName, colName, jsonConversionOptions);
 					changes.push({
 						type: "type_upgrade",
 						table: tableName,
@@ -1027,7 +1147,8 @@ var SchemaComparer = class SchemaComparer {
 						column: colDef,
 						mismatch: jsonMismatch,
 						sql: statements[statements.length - 1],
-						sqlStatements: statements
+						sqlStatements: statements,
+						...jsonEmptyTextToNull ? emptyTextNote(jsonProbe) : {}
 					});
 				} else if (jsonUpgradeCandidate && jsonProbe?.status === "dirty" && jsonProbe.reason === "preservation_unverified") changes.push({
 					type: "type_upgrade",
@@ -1048,11 +1169,11 @@ var SchemaComparer = class SchemaComparer {
 					mismatch: jsonMismatch,
 					advisory: {
 						severity: "warning",
-						message: `blocked: ${tableName}.${colName} is declared JSON but ${jsonProbe.count} ${jsonProbe.reason === "duplicate_keys" ? "JSON object(s) carry duplicate keys that jsonb would silently collapse" : `live value(s) ${nativeJsonToJsonb ? "cannot be stored as jsonb (e.g. a \\u0000 escape)" : "are not valid JSON"}`} (sample: ${jsonProbe.sample ? maskSampleValue(jsonProbe.sample) : "unavailable"}). ${jsonProbe.reason === "duplicate_keys" ? "Converting keeps only the last value of each duplicated key; deduplicate the keys (deciding which value to keep), then rerun " : "Repair or clear the offending value(s), then rerun "}\`smrt db:migrate\`.`,
+						message: `blocked: ${tableName}.${colName} is declared JSON but ${jsonProbe.count} ${jsonProbe.reason === "duplicate_keys" ? "JSON object(s) carry duplicate keys that jsonb would silently collapse" : `live value(s) ${nativeJsonToJsonb ? "cannot be stored as jsonb (e.g. a \\u0000 escape)" : "are not valid JSON"}`} (sample: ${jsonProbe.sample !== void 0 ? maskSampleValue(jsonProbe.sample) : "unavailable"}).${jsonProbe.reason === void 0 ? this.describeEmptyTextFinding(jsonProbe, emptyTextNullable) : ""} ${jsonProbe.reason === "duplicate_keys" ? "Converting keeps only the last value of each duplicated key; deduplicate the keys (deciding which value to keep), then rerun " : "Repair or clear the offending value(s), then rerun "}\`smrt db:migrate\`.`,
 						...jsonProbe.reason === "duplicate_keys" ? {} : { suggestedSql: renderJsonbColumnConversion(tableName, colName, conversionOptions) }
 					}
 				});
-				else if (timestamptzUpgradeCandidate && timestamptzProbe?.status === "clean" && liveOnlyDefaultNeedsRelaxOptIn) changes.push({
+				else if (timestamptzUpgradeCandidate && timestamptzConvertible && liveOnlyDefaultNeedsRelaxOptIn) changes.push({
 					type: "type_upgrade",
 					table: tableName,
 					name: colName,
@@ -1064,11 +1185,11 @@ var SchemaComparer = class SchemaComparer {
 					advisory: {
 						severity: "warning",
 						message: `blocked: ${tableName}.${colName} has a live default (${String(dbCol.defaultValue)}) the manifest no longer declares; converging to timestamptz requires dropping it first. ${this.relaxHint("drop it as part of this conversion")}`,
-						suggestedSql: renderTimestamptzColumnConversion(tableName, colName, conversionOptions)
+						suggestedSql: renderTimestamptzColumnConversion(tableName, colName, timestamptzConversionOptions)
 					}
 				});
-				else if (timestamptzUpgradeCandidate && timestamptzProbe?.status === "clean") {
-					const statements = renderTimestamptzColumnConversion(tableName, colName, conversionOptions);
+				else if (timestamptzUpgradeCandidate && timestamptzConvertible) {
+					const statements = renderTimestamptzColumnConversion(tableName, colName, timestamptzConversionOptions);
 					changes.push({
 						type: "type_upgrade",
 						table: tableName,
@@ -1079,7 +1200,8 @@ var SchemaComparer = class SchemaComparer {
 							actual: dbCol.type
 						},
 						sql: statements[statements.length - 1],
-						sqlStatements: statements
+						sqlStatements: statements,
+						...timestamptzEmptyTextToNull ? emptyTextNote(timestamptzProbe) : {}
 					});
 				} else if (timestamptzUpgradeCandidate && timestamptzProbe?.status === "dirty") changes.push({
 					type: "type_upgrade",
@@ -1092,12 +1214,16 @@ var SchemaComparer = class SchemaComparer {
 					},
 					advisory: {
 						severity: "warning",
-						message: `blocked: ${tableName}.${colName} is declared TIMESTAMP but ${timestamptzProbe.count} live value(s) do not parse as an unambiguous timestamp (sample: ${timestamptzProbe.sample ? maskSampleValue(timestamptzProbe.sample) : "unavailable"}). Repair the offending value(s), or confirm legacy naive wall-clock provenance with \`smrt db:migrate --postgres-timestamp-legacy-timezone=UTC\`, then rerun.`,
-						suggestedSql: renderTimestamptzColumnConversion(tableName, colName, conversionOptions)
+						message: `blocked: ${tableName}.${colName} is declared TIMESTAMP but ${timestamptzProbe.count} live value(s) do not parse as an unambiguous timestamp (sample: ${timestamptzProbe.sample !== void 0 ? maskSampleValue(timestamptzProbe.sample) : "unavailable"}).${this.describeEmptyTextFinding(timestamptzProbe, emptyTextNullable)}${isEmptyTextOnlyProbe(timestamptzProbe) ? "" : " Repair the offending value(s), or confirm legacy naive wall-clock provenance with `smrt db:migrate --postgres-timestamp-legacy-timezone=UTC`, then rerun."}`,
+						suggestedSql: renderTimestamptzColumnConversion(tableName, colName, isEmptyTextOnlyProbe(timestamptzProbe) && emptyTextNullable ? {
+							...conversionOptions,
+							emptyTextAsNull: true
+						} : conversionOptions)
 					}
 				});
 				else if (this.isCompatibleTypeUpgrade(colDef.type, dbCol.type)) {
-					const generatedSQL = this.generateTypeUpgradeSQL(tableName, colName, colDef, dbCol.type);
+					const integerEmptyTextToNull = convertEmptyText && this.engine === "postgres" && this.normalizeType(colDef.type) === "INTEGER" && normalizedActual === "TEXT";
+					const generatedSQL = this.generateTypeUpgradeSQL(tableName, colName, colDef, dbCol.type, { emptyTextAsNull: integerEmptyTextToNull });
 					changes.push({
 						type: "type_upgrade",
 						table: tableName,
@@ -1108,7 +1234,8 @@ var SchemaComparer = class SchemaComparer {
 							actual: dbCol.type
 						},
 						sql: generatedSQL.sql,
-						...generatedSQL.statements ? { sqlStatements: generatedSQL.statements } : {}
+						...generatedSQL.statements ? { sqlStatements: generatedSQL.statements } : {},
+						...integerEmptyTextToNull ? { note: "empty-text value(s), if any, become NULL (--empty-text-as-null)" } : {}
 					});
 				} else if (!this.options.ignoreTypeMismatches) changes.push({
 					type: "type_mismatch",
@@ -1989,6 +2116,19 @@ var SchemaComparer = class SchemaComparer {
 			const equivalentIndexNames = dbIndexSignatures.get(manifestSignature);
 			if (equivalentIndexNames && equivalentIndexNames.size > 0) {
 				for (const name of equivalentIndexNames) claimedDbIndexes.add(name);
+				const legacyName = this.legacyTenantLedIndexName(tableName, idx);
+				if (legacyName && this.engine === "postgres" && equivalentIndexNames.has(legacyName) && !dbIndexesByName.has(idx.name)) {
+					const renameSql = `ALTER INDEX IF EXISTS ${this.quoteIdentifier(legacyName)} RENAME TO ${this.quoteIdentifier(idx.name)}`;
+					changes.push({
+						type: "add_index",
+						table: tableName,
+						name: idx.name,
+						index: idx,
+						note: `renames ${legacyName} (same columns)`,
+						sql: renameSql,
+						sqlStatements: [renameSql]
+					});
+				}
 				continue;
 			}
 			changes.push({
@@ -2025,6 +2165,7 @@ var SchemaComparer = class SchemaComparer {
 			}
 			const redundantPrimaryKeyIndex = idx.unique !== true && idx.columns.length === 1 && dbPredicateFor(idx.name) === "" && primaryKeyColumns.length === 1 && primaryKeyColumns[0] === idx.columns[0];
 			const supersededConflictIndex = idx.unique === true && predicateAware && dbPredicateFor(idx.name) === "" && idx.columns.length > 0 && idx.name === shortenIdentifier(conflictIndexName(tableName, idx.columns)) && manifestIndexes.some((declared) => declared.unique === true && !declared.where && declared.columns.length > idx.columns.length && idx.columns.every((column) => declared.columns.includes(column)) && declared.columns.every((column) => column in dbSchema.columns));
+			if (supersededConflictIndex && manifestIndexes.some((declared) => declared.unique === true && !declared.where && isLegacyNaturalKeyIndex(idx.columns, declared.columns)) && !this.options.dropLegacyNaturalKey) continue;
 			if (!redundantPrimaryKeyIndex && !supersededConflictIndex && !this.options.includeDroppedIndexes) continue;
 			changes.push({
 				type: "drop_index",
@@ -2036,6 +2177,20 @@ var SchemaComparer = class SchemaComparer {
 		return changes;
 	}
 	/**
+	* The framework's pre-release name for a manifest's tenant-led default
+	* natural key: `<table>_slug_context_idx` (CTI) or
+	* `<table>_slug_context_meta_type_idx` (STI), when `idx` is a unique,
+	* unqualified default key led by one ownership column and its manifest name
+	* differs (an inferred owner, see `conflictIndexName()`). `undefined`
+	* otherwise.
+	*/
+	legacyTenantLedIndexName(tableName, idx) {
+		const columns = idx.columns ?? [];
+		if (idx.unique !== true || idx.where || isJsonPathIndex(idx) || columns.length < 3 || !isLegacyNaturalKeyIndex(columns.slice(1), columns)) return;
+		const legacyName = shortenIdentifier(conflictIndexName(tableName, columns.slice(1)));
+		return legacyName === idx.name ? void 0 : legacyName;
+	}
+	/**
 	* Generate a signature for an index based on its columns, uniqueness, and
 	* (normalized) partial-index predicate. Used for functional equivalence
 	* checking (Issue #741) and predicate-drift detection (Issue #1692).
@@ -2196,7 +2351,7 @@ var SchemaComparer = class SchemaComparer {
 	* - DuckDB: ALTER COLUMN TYPE (native type conversion)
 	* - PostgreSQL: ALTER COLUMN TYPE with USING clause
 	*/
-	generateTypeUpgradeSQL(tableName, colName, colDef, dbType) {
+	generateTypeUpgradeSQL(tableName, colName, colDef, dbType, options = {}) {
 		const quotedTable = this.quoteIdentifier(tableName);
 		const quotedCol = this.quoteIdentifier(colName);
 		const manifestType = colDef.type;
@@ -2209,7 +2364,7 @@ var SchemaComparer = class SchemaComparer {
 			case "postgres": {
 				const manifestNormalized = this.normalizeType(manifestType);
 				const dbNormalized = this.normalizeType(dbType);
-				const preflightSQL = manifestNormalized === "INTEGER" && (dbNormalized === "TEXT" || dbNormalized === "REAL") ? this.generatePostgresIntegerPreflightSQL(quotedTable, quotedCol, tableName, colName, dbNormalized) : manifestNormalized === "TIMESTAMP" && [
+				const preflightSQL = manifestNormalized === "INTEGER" && (dbNormalized === "TEXT" || dbNormalized === "REAL") ? this.generatePostgresIntegerPreflightSQL(quotedTable, quotedCol, tableName, colName, dbNormalized, options.emptyTextAsNull === true && dbNormalized === "TEXT") : manifestNormalized === "TIMESTAMP" && [
 					"TIMESTAMP",
 					"TEXT",
 					"JSON"
@@ -2220,7 +2375,7 @@ var SchemaComparer = class SchemaComparer {
 				if (manifestNormalized === "JSON" && dbNormalized === "TEXT") typeClause += ` USING to_jsonb(${quotedCol})`;
 				else if (manifestNormalized === "TEXT" && dbNormalized === "JSON") typeClause += ` USING ${quotedCol}::text`;
 				else if (manifestNormalized === "TEXT" && dbNormalized === "UUID") typeClause += ` USING ${quotedCol}::text`;
-				else if (manifestNormalized === "INTEGER" && dbNormalized === "TEXT") typeClause += ` USING trim(${quotedCol}::text)::bigint`;
+				else if (manifestNormalized === "INTEGER" && dbNormalized === "TEXT") typeClause += options.emptyTextAsNull ? ` USING trim((${renderEmptyTextAsNullExpression(quotedCol)}))::bigint` : ` USING trim(${quotedCol}::text)::bigint`;
 				else if (manifestNormalized === "INTEGER" && dbNormalized === "REAL") typeClause += ` USING ${quotedCol}::bigint`;
 				else if (manifestNormalized === "TIMESTAMP" && (dbNormalized === "TEXT" || dbNormalized === "JSON")) typeClause += ` USING NULLIF(NULLIF(trim(both '"' from ${quotedCol}::text), ''), 'null')::timestamptz`;
 				else if (manifestNormalized === "TIMESTAMP" && dbNormalized === "TIMESTAMP" && this.normalizeType(targetType) === "TIMESTAMPTZ") typeClause += ` USING ${quotedCol} AT TIME ZONE 'UTC'`;
@@ -2251,8 +2406,8 @@ var SchemaComparer = class SchemaComparer {
 	* INTEGER. PostgreSQL's REAL→INTEGER cast rounds fractional values, so the
 	* generated migration must fail before the ALTER can silently change data.
 	*/
-	generatePostgresIntegerPreflightSQL(quotedTable, quotedCol, tableName, colName, dbNormalized) {
-		const invalidCondition = dbNormalized === "REAL" ? `${quotedCol} IS NOT NULL AND ${quotedCol} <> trunc(${quotedCol})` : `${quotedCol} IS NOT NULL AND trim(${quotedCol}::text) !~ '^[+-]?[0-9]+$'`;
+	generatePostgresIntegerPreflightSQL(quotedTable, quotedCol, tableName, colName, dbNormalized, emptyTextAsNull = false) {
+		const invalidCondition = dbNormalized === "REAL" ? `${quotedCol} IS NOT NULL AND ${quotedCol} <> trunc(${quotedCol})` : emptyTextAsNull ? `${quotedCol} IS NOT NULL AND NOT ${renderEmptyTextPredicate(quotedCol)} AND trim(${quotedCol}::text) !~ '^[+-]?[0-9]+$'` : `${quotedCol} IS NOT NULL AND trim(${quotedCol}::text) !~ '^[+-]?[0-9]+$'`;
 		const message = `Cannot convert ${tableName}.${colName} to INTEGER: found non-integer values`;
 		return `DO $$ BEGIN IF EXISTS (SELECT 1 FROM ${quotedTable} WHERE ${invalidCondition}) THEN RAISE EXCEPTION ${this.quoteLiteral(message)}; END IF; END $$`;
 	}