@happyvertical/smrt-core 0.47.1 → 0.48.0

package/dist/migrations/differ.d.ts

@@ -70,10 +70,6 @@ export interface DiffOptions {
  * constraint-owned.
  */
 export declare function uniqueColumnIndexName(tableName: string, columnName: string): string;
-/**
- * True when a change is report-only: it carries an advisory and no
- * executable statement. Such changes never reach the migration stream.
- */
 export declare function isAdvisoryOnlyChange(change: SchemaChange): boolean;
 /**
  * True for an info-level report-only change: listed in `SchemaDiff.changes`
@@ -189,6 +185,16 @@ export declare class SchemaComparer {
      * planner treats as a block — SMRT never coerces identifier values.
      */
     private probeUuidShape;
+    /**
+     * Probe a candidate `text` -> `timestamptz`/`jsonb` column (#2771, #2772)
+     * with a real, exception-safe cast attempt (see `text-cast-probe.ts`).
+     * Unlike {@link probeUuidShape}, a failed/unrealistic probe
+     * (`unavailable`) is the caller's cue to fall back to the pre-existing
+     * behavior for that pair rather than surface a new finding — this keeps
+     * the new convergence strictly additive for every case that isn't
+     * affirmatively confirmed safe or affirmatively confirmed unsafe.
+     */
+    private probeTextCastShape;
     /**
      * Turn the convergence plan into diff entries: executable `type_upgrade`
      * conversions marked `phase: 'pre_foreign_key'`, plus report-only warnings
@@ -220,6 +226,84 @@ export declare class SchemaComparer {
      *    that orphan gets an executable `DROP NOT NULL` where the engine allows.
      */
     private compareColumns;
+    /**
+     * Detect a pending rename backfill (#2752): a manifest-declared column
+     * that exists live but holds no data, paired with an orphan (undeclared)
+     * live column of a compatible type that does hold data — the shape a
+     * framework field rename leaves behind when `db:migrate` adds the new
+     * column additively and never moves data into it. For each such pair,
+     * emit the copy-then-drop repair as an advisory: never executed,
+     * PostgreSQL and SQLite only (DuckDB/JSON are out of scope). The repair
+     * is genuinely idempotent SQL on PostgreSQL (a self-guarding
+     * `DO $$ ... $$` block); SQLite has no conditional-DDL construct, so its
+     * repair is operator-mediated instead — a guard query plus instructions,
+     * not a blind-rerun-safe statement. See {@link describeRenameDataPending}.
+     */
+    private detectRenameDataPending;
+    /**
+     * Live-data probe: does the column hold any non-null, non-empty value?
+     * Used by {@link detectRenameDataPending}. Errors propagate to the
+     * caller, which skips the pair rather than guessing (#2752).
+     */
+    private columnHasNonEmptyValue;
+    /**
+     * Live-data probe: are every one of a column's non-empty values
+     * UUID-shaped ({@link CANONICAL_UUID_PATTERN})? PostgreSQL pushes the
+     * check into the query with its regex operator; SQLite has no regex
+     * operator, but its case-sensitive `GLOB` can still express the fixed
+     * 36-character canonical shape ({@link CANONICAL_UUID_SQLITE_GLOB_PATTERN}
+     * against `LOWER(...)`, guarded by an exact `LENGTH(...) = 36` check), so
+     * both engines run one server-side aggregate `count(*)` rather than
+     * fetching every non-empty value into JS to test in a loop — important on
+     * a production table with many rows (#2767 review).
+     */
+    private allNonEmptyValuesUuidShaped;
+    /**
+     * Render the repair for one rename-data-pending pair (#2752): copy
+     * non-empty `oldColumn` into `newColumn` only where `newColumn` is still
+     * empty (casting to `uuid` when the new column is native uuid, otherwise a
+     * plain copy), then drop `oldColumn`.
+     *
+     * Idempotency review findings and the fix:
+     *
+     * - (P1) The `newColumn`-is-empty predicate previously compared any
+     *   non-uuid destination to `''` (`col IS NULL OR col = ''`), which is
+     *   only valid for text-affinity types — PostgreSQL rejects `col = ''`
+     *   for `integer`/`boolean`/`timestamp`/etc. before a same-type rename
+     *   pair of one of those types ever copies anything. Fixed by comparing
+     *   `CAST(col AS TEXT) = ''` instead, mirroring the same portable
+     *   emptiness check {@link columnHasNonEmptyValue} already uses for
+     *   detection, so the predicate is valid for every column type.
+     * - (P2) An `UPDATE` unconditionally naming `oldColumn` fails once that
+     *   column is gone, on either engine, regardless of the DROP's own
+     *   idempotency — a guard query placed before the DROP (or even before
+     *   the UPDATE) still leaves a human decision between "run" and "don't",
+     *   which is not genuine SQL-level idempotency. PostgreSQL CAN express a
+     *   truly self-contained, unconditionally-safe-to-rerun statement here:
+     *   an anonymous `DO $$ ... $$` block (the same idiom this file already
+     *   uses for `generatePostgresIntegerPreflightSQL`) that checks
+     *   `information_schema.columns` and only runs the UPDATE + DROP when the
+     *   old column still exists — one executable statement, no operator
+     *   judgment required, safe to rerun any number of times. SQLite has no
+     *   procedural block or conditional-DDL construct at all (confirmed
+     *   against a real connection), so there the contract is explicitly
+     *   downgraded from "idempotent SQL" to "operator-mediated": a guard
+     *   query plus instructions, not a single statement that is itself safe
+     *   to blindly rerun.
+     *
+     * This is report-only either way: `db:migrate` never executes it.
+     */
+    private describeRenameDataPending;
+    /**
+     * Render the advisory for an ambiguous rename-data-pending match (#2767
+     * review): more than one orphan column is a populated, type-compatible
+     * candidate for the same empty declared column, so the real rename source
+     * cannot be inferred. Unlike {@link describeRenameDataPending}, this
+     * carries no `suggestedSql` — running a per-candidate copy-and-drop would
+     * let output order decide which candidate's data wins and then drop every
+     * one of them, which is not a repair an advisory should suggest blindly.
+     */
+    private describeRenameDataPendingAmbiguous;
     /**
      * Compare nullability and default between a manifest column and the live
      * column, emitting `alter_column` changes (#2369).

package/dist/migrations/differ.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/migrations/differ.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/migrations/differ.ts"],"names":[],"mappings":"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"}

package/dist/migrations/differ.js

@@ -1,7 +1,8 @@
 import { normalizeForeignKeyAction, requireForeignKeyAction } from "../schema/foreign-key-policy.js";
 import { isJsonPathIndex, isStiSubtypeUniqueIndex, renderIndexTarget } from "../schema/index-utils.js";
-import { foreignKeyConstraintName, foreignKeyRelationshipKey, renderForeignKeyConstraint, renderForeignKeyOrphanDetector, renderForeignKeyOrphanRepair, schemaForeignKeys, schemaForeignKeysForEngine } from "../schema/foreign-key-ddl.js";
+import { CANONICAL_UUID_PATTERN, CANONICAL_UUID_SQLITE_GLOB_PATTERN, foreignKeyConstraintName, foreignKeyRelationshipKey, renderForeignKeyAddStatements, renderForeignKeyOrphanDetector, renderForeignKeyOrphanRepair, schemaForeignKeys, schemaForeignKeysForEngine } from "../schema/foreign-key-ddl.js";
 import { detectEngine, getDDLStrategy } from "../schema/ddl/index.js";
+import { maskSampleValue, probeCastSafety, renderJsonbColumnConversion, renderTimestamptzColumnConversion } from "../schema/text-cast-probe.js";
 import { describeForeignKeyTypeConflict, planUuidConvergence, renderUuidConvergenceRepairHint, renderUuidShapeProbe } from "../schema/uuid-convergence.js";
 import "../schema/utils.js";
 import { planSqliteTableRebuilds, sqliteRebuildPlaceholderSql } from "./sqlite-rebuild.js";
@@ -64,6 +65,18 @@ function uniqueColumnIndexName(tableName, columnName) {
 * True when a change is report-only: it carries an advisory and no
 * executable statement. Such changes never reach the migration stream.
 */
+/**
+* Single- vs double-precision float classification for #2770's float-width
+* drift detection. `null` for anything that isn't unambiguously one or the
+* other (DECIMAL/NUMERIC have no fixed binary width and are out of scope).
+*/
+function floatPrecisionOf(type, engine) {
+	const upper = type.toUpperCase().trim().replace(/\(\s*\d+(\s*,\s*\d+)?\s*\)/g, "");
+	if (/^(REAL|FLOAT4)$/.test(upper)) return "single";
+	if (engine === "duckdb" && upper === "FLOAT") return "single";
+	if (/^(FLOAT8|DOUBLE|DOUBLE PRECISION|FLOAT)$/.test(upper)) return "double";
+	return null;
+}
 function isAdvisoryOnlyChange(change) {
 	if (!change.advisory) return false;
 	return (change.sqlStatements ?? (change.sql ? [change.sql] : [])).length === 0;
@@ -475,6 +488,18 @@ var SchemaComparer = class {
 		}
 	}
 	/**
+	* Probe a candidate `text` -> `timestamptz`/`jsonb` column (#2771, #2772)
+	* with a real, exception-safe cast attempt (see `text-cast-probe.ts`).
+	* Unlike {@link probeUuidShape}, a failed/unrealistic probe
+	* (`unavailable`) is the caller's cue to fall back to the pre-existing
+	* behavior for that pair rather than surface a new finding — this keeps
+	* the new convergence strictly additive for every case that isn't
+	* affirmatively confirmed safe or affirmatively confirmed unsafe.
+	*/
+	async probeTextCastShape(tableName, columnName, kind) {
+		return probeCastSafety(this.db, tableName, columnName, kind);
+	}
+	/**
 	* Turn the convergence plan into diff entries: executable `type_upgrade`
 	* conversions marked `phase: 'pre_foreign_key'`, plus report-only warnings
 	* for components the planner refused.
@@ -608,6 +633,7 @@ var SchemaComparer = class {
 					table: tableName,
 					name: foreignKeyConstraintName(tableName, foreignKey),
 					foreignKey,
+					engineUnsupported: true,
 					advisory: {
 						severity: "warning",
 						message: `${engineReason} Run the orphan detector, repair rows, and rebuild the table with the generated constraint.`,
@@ -645,6 +671,8 @@ var SchemaComparer = class {
 					table: tableName,
 					name: foreignKeyConstraintName(tableName, foreignKey),
 					foreignKey,
+					orphanBlocked: true,
+					orphanNullable: orphanOptions.nullable,
 					advisory: {
 						severity: "warning",
 						message: `Cannot add foreign key ${tableName}.${foreignKey.column}: existing rows do not match ${foreignKey.referencesTable}.${foreignKey.referencesColumn}. Repair them, then rerun.`,
@@ -659,7 +687,7 @@ var SchemaComparer = class {
 				table: tableName,
 				name: constraintName,
 				foreignKey,
-				sqlStatements: [`ALTER TABLE ${this.quoteIdentifier(tableName)} ADD ${renderForeignKeyConstraint(tableName, foreignKey)} NOT VALID`, `ALTER TABLE ${this.quoteIdentifier(tableName)} VALIDATE CONSTRAINT ${this.quoteIdentifier(constraintName)}`]
+				sqlStatements: renderForeignKeyAddStatements(tableName, foreignKey)
 			});
 		}
 		return changes;
@@ -680,7 +708,9 @@ var SchemaComparer = class {
 	async getForeignKeyOrphanOptions(tableName, manifest, dbSchema, foreignKey, manifestSchemas) {
 		const sourceColumn = manifest.columns[foreignKey.column];
 		const targetColumn = manifestSchemas[foreignKey.referencesTable]?.columns[foreignKey.referencesColumn];
-		const nullable = sourceColumn?.notNull !== true;
+		const manifestNullable = sourceColumn?.notNull !== true;
+		const liveNotNull = dbSchema.columns[foreignKey.column]?.notNull === true;
+		const nullable = manifestNullable && !liveNotNull;
 		const uuidComparison = sourceColumn?.type === "UUID" && (targetColumn === void 0 || targetColumn.type === "UUID");
 		if (!uuidComparison) return {
 			nullable,
@@ -743,10 +773,148 @@ var SchemaComparer = class {
 			const expectedEngineType = this.ddlStrategy.mapType(validatedType);
 			const normalizedExpected = this.normalizeType(expectedEngineType);
 			const normalizedActual = this.normalizeType(dbCol.type);
+			if ((this.engine === "postgres" || this.engine === "duckdb") && normalizedExpected === "REAL" && normalizedActual === "REAL") {
+				const expectedPrecision = floatPrecisionOf(expectedEngineType, this.engine);
+				const actualPrecision = floatPrecisionOf(dbCol.type, this.engine);
+				if (expectedPrecision && actualPrecision && expectedPrecision !== actualPrecision) {
+					typeDrifted = true;
+					const table = this.quoteIdentifier(tableName);
+					const column = this.quoteIdentifier(colName);
+					if (expectedPrecision === "double" && actualPrecision === "single") {
+						const targetType = this.engine === "postgres" ? "DOUBLE PRECISION" : "DOUBLE";
+						changes.push({
+							type: "type_upgrade",
+							table: tableName,
+							name: colName,
+							column: colDef,
+							mismatch: {
+								expected: expectedEngineType,
+								actual: dbCol.type
+							},
+							sql: `ALTER TABLE ${table} ALTER COLUMN ${column} TYPE ${targetType} USING ${column}::${targetType}`
+						});
+					} else changes.push({
+						type: "type_upgrade",
+						table: tableName,
+						name: colName,
+						column: colDef,
+						mismatch: {
+							expected: expectedEngineType,
+							actual: dbCol.type
+						},
+						advisory: {
+							severity: "warning",
+							message: `blocked: ${tableName}.${colName} is declared single-precision (${expectedEngineType}) but the live column is double-precision (${dbCol.type}). Narrowing loses precision, so this stays manual: confirm the narrower declaration is intentional, or widen the manifest field instead of the column.`,
+							suggestedSql: [`ALTER TABLE ${table} ALTER COLUMN ${column} TYPE ${expectedEngineType} USING ${column}::${expectedEngineType}`]
+						}
+					});
+				}
+			}
 			const isUuidTextEquivalent = this.isUuidTextEquivalentColumn(colName, colDef, normalizedExpected, normalizedActual);
-			if (normalizedExpected !== normalizedActual && !isUuidTextEquivalent && !(normalizedExpected === "JSON" && normalizedActual === "TEXT" || normalizedExpected === "TEXT" && normalizedActual === "JSON")) {
+			const jsonUpgradeCandidate = this.engine === "postgres" && normalizedExpected === "JSON" && normalizedActual === "TEXT";
+			let jsonProbe;
+			if (jsonUpgradeCandidate) jsonProbe = await this.probeTextCastShape(tableName, colName, "jsonb");
+			const isJsonTextEquivalent = normalizedExpected === "TEXT" && normalizedActual === "JSON" || normalizedExpected === "JSON" && normalizedActual === "TEXT" && (!jsonUpgradeCandidate || jsonProbe?.status === "unavailable");
+			const timestamptzUpgradeCandidate = this.engine === "postgres" && this.normalizeType(colDef.type) === "TIMESTAMP" && normalizedActual === "TEXT" && normalizedExpected === "TIMESTAMPTZ" && !this.isCompatibleTypeUpgrade(colDef.type, dbCol.type);
+			let timestamptzProbe;
+			if (timestamptzUpgradeCandidate) timestamptzProbe = await this.probeTextCastShape(tableName, colName, "timestamptz");
+			if (normalizedExpected !== normalizedActual && !isUuidTextEquivalent && !isJsonTextEquivalent) {
 				typeDrifted = true;
-				if (this.isCompatibleTypeUpgrade(colDef.type, dbCol.type)) {
+				const hasLiveDefault = dbCol.defaultValue !== null && dbCol.defaultValue !== void 0;
+				const conversionOptions = {
+					hasLiveDefault,
+					manifestDefaultValue: colDef.defaultValue
+				};
+				const liveOnlyDefaultNeedsRelaxOptIn = hasLiveDefault && colDef.defaultValue === void 0 && !this.options.relaxColumns;
+				if (jsonUpgradeCandidate && jsonProbe?.status === "clean" && liveOnlyDefaultNeedsRelaxOptIn) changes.push({
+					type: "type_upgrade",
+					table: tableName,
+					name: colName,
+					column: colDef,
+					mismatch: {
+						expected: colDef.type,
+						actual: dbCol.type
+					},
+					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)
+					}
+				});
+				else if (jsonUpgradeCandidate && jsonProbe?.status === "clean") {
+					const statements = renderJsonbColumnConversion(tableName, colName, conversionOptions);
+					changes.push({
+						type: "type_upgrade",
+						table: tableName,
+						name: colName,
+						column: colDef,
+						mismatch: {
+							expected: colDef.type,
+							actual: dbCol.type
+						},
+						sql: statements[statements.length - 1],
+						sqlStatements: statements
+					});
+				} else if (jsonUpgradeCandidate && jsonProbe?.status === "dirty") changes.push({
+					type: "type_upgrade",
+					table: tableName,
+					name: colName,
+					column: colDef,
+					mismatch: {
+						expected: colDef.type,
+						actual: dbCol.type
+					},
+					advisory: {
+						severity: "warning",
+						message: `blocked: ${tableName}.${colName} is declared JSON but ${jsonProbe.count} live value(s) are not valid JSON (sample: ${jsonProbe.sample ? maskSampleValue(jsonProbe.sample) : "unavailable"}). Repair or clear the offending value(s), then rerun \`smrt db:migrate\`.`,
+						suggestedSql: renderJsonbColumnConversion(tableName, colName, conversionOptions)
+					}
+				});
+				else if (timestamptzUpgradeCandidate && timestamptzProbe?.status === "clean" && liveOnlyDefaultNeedsRelaxOptIn) changes.push({
+					type: "type_upgrade",
+					table: tableName,
+					name: colName,
+					column: colDef,
+					mismatch: {
+						expected: colDef.type,
+						actual: dbCol.type
+					},
+					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)
+					}
+				});
+				else if (timestamptzUpgradeCandidate && timestamptzProbe?.status === "clean") {
+					const statements = renderTimestamptzColumnConversion(tableName, colName, conversionOptions);
+					changes.push({
+						type: "type_upgrade",
+						table: tableName,
+						name: colName,
+						column: colDef,
+						mismatch: {
+							expected: colDef.type,
+							actual: dbCol.type
+						},
+						sql: statements[statements.length - 1],
+						sqlStatements: statements
+					});
+				} else if (timestamptzUpgradeCandidate && timestamptzProbe?.status === "dirty") changes.push({
+					type: "type_upgrade",
+					table: tableName,
+					name: colName,
+					column: colDef,
+					mismatch: {
+						expected: colDef.type,
+						actual: dbCol.type
+					},
+					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)
+					}
+				});
+				else if (this.isCompatibleTypeUpgrade(colDef.type, dbCol.type)) {
 					const generatedSQL = this.generateTypeUpgradeSQL(tableName, colName, colDef, dbCol.type);
 					changes.push({
 						type: "type_upgrade",
@@ -791,9 +959,199 @@ var SchemaComparer = class {
 			}
 			changes.push(this.describeOrphanColumn(tableName, colName, dbCol));
 		}
+		changes.push(...await this.detectRenameDataPending(tableName, manifest, dbSchema));
 		return changes;
 	}
 	/**
+	* Detect a pending rename backfill (#2752): a manifest-declared column
+	* that exists live but holds no data, paired with an orphan (undeclared)
+	* live column of a compatible type that does hold data — the shape a
+	* framework field rename leaves behind when `db:migrate` adds the new
+	* column additively and never moves data into it. For each such pair,
+	* emit the copy-then-drop repair as an advisory: never executed,
+	* PostgreSQL and SQLite only (DuckDB/JSON are out of scope). The repair
+	* is genuinely idempotent SQL on PostgreSQL (a self-guarding
+	* `DO $$ ... $$` block); SQLite has no conditional-DDL construct, so its
+	* repair is operator-mediated instead — a guard query plus instructions,
+	* not a blind-rerun-safe statement. See {@link describeRenameDataPending}.
+	*/
+	async detectRenameDataPending(tableName, manifest, dbSchema) {
+		if (this.engine !== "postgres" && this.engine !== "sqlite") return [];
+		const dbColumnNames = new Set(Object.keys(dbSchema.columns));
+		const manifestColumnNames = new Set(Object.keys(manifest.columns));
+		const orphanColumnNames = [...dbColumnNames].filter((name) => !manifestColumnNames.has(name));
+		if (orphanColumnNames.length === 0) return [];
+		const changes = [];
+		for (const [colName, colDef] of Object.entries(manifest.columns)) {
+			if (!dbSchema.columns[colName]) continue;
+			let declaredHasData;
+			try {
+				declaredHasData = await this.columnHasNonEmptyValue(tableName, colName);
+			} catch {
+				continue;
+			}
+			if (declaredHasData) continue;
+			const validatedType = isValidSQLDataType(colDef.type) ? colDef.type : "TEXT";
+			const isLogicalUuid = validatedType === "UUID";
+			const declaredNormalized = this.normalizeType(this.ddlStrategy.mapType(validatedType));
+			const candidates = [];
+			for (const orphanName of orphanColumnNames) {
+				const orphanCol = dbSchema.columns[orphanName];
+				const orphanNormalized = this.normalizeType(orphanCol.type);
+				const requiresShapeCheck = isLogicalUuid && orphanNormalized === "TEXT";
+				if (!requiresShapeCheck && !(orphanNormalized === declaredNormalized)) continue;
+				let orphanHasData;
+				try {
+					orphanHasData = await this.columnHasNonEmptyValue(tableName, orphanName);
+				} catch {
+					continue;
+				}
+				if (!orphanHasData) continue;
+				if (requiresShapeCheck) {
+					let shaped;
+					try {
+						shaped = await this.allNonEmptyValuesUuidShaped(tableName, orphanName);
+					} catch {
+						continue;
+					}
+					if (!shaped) continue;
+				}
+				candidates.push({
+					orphanName,
+					isUuidCast: declaredNormalized === "UUID"
+				});
+			}
+			if (candidates.length === 1) changes.push(this.describeRenameDataPending(tableName, colName, candidates[0].orphanName, candidates[0].isUuidCast));
+			else if (candidates.length > 1) changes.push(this.describeRenameDataPendingAmbiguous(tableName, colName, candidates.map((c) => c.orphanName)));
+		}
+		return changes;
+	}
+	/**
+	* Live-data probe: does the column hold any non-null, non-empty value?
+	* Used by {@link detectRenameDataPending}. Errors propagate to the
+	* caller, which skips the pair rather than guessing (#2752).
+	*/
+	async columnHasNonEmptyValue(tableName, colName) {
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedCol = this.quoteIdentifier(colName);
+		return ((await this.db.query(`SELECT 1 AS present FROM ${quotedTable} WHERE ${quotedCol} IS NOT NULL AND CAST(${quotedCol} AS TEXT) <> '' LIMIT 1`)).rows?.length ?? 0) > 0;
+	}
+	/**
+	* Live-data probe: are every one of a column's non-empty values
+	* UUID-shaped ({@link CANONICAL_UUID_PATTERN})? PostgreSQL pushes the
+	* check into the query with its regex operator; SQLite has no regex
+	* operator, but its case-sensitive `GLOB` can still express the fixed
+	* 36-character canonical shape ({@link CANONICAL_UUID_SQLITE_GLOB_PATTERN}
+	* against `LOWER(...)`, guarded by an exact `LENGTH(...) = 36` check), so
+	* both engines run one server-side aggregate `count(*)` rather than
+	* fetching every non-empty value into JS to test in a loop — important on
+	* a production table with many rows (#2767 review).
+	*/
+	async allNonEmptyValuesUuidShaped(tableName, colName) {
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedCol = this.quoteIdentifier(colName);
+		const nonEmptyPredicate = `${quotedCol} IS NOT NULL AND CAST(${quotedCol} AS TEXT) <> ''`;
+		if (this.engine === "postgres") {
+			const row = (await this.db.query(`SELECT count(*) AS invalid_count FROM ${quotedTable} WHERE ${nonEmptyPredicate} AND CAST(${quotedCol} AS TEXT) !~* '${CANONICAL_UUID_PATTERN}'`)).rows?.[0];
+			return Number(row?.invalid_count ?? 0) === 0;
+		}
+		const row = (await this.db.query(`SELECT count(*) AS invalid_count FROM ${quotedTable} WHERE ${nonEmptyPredicate} AND NOT (LENGTH(CAST(${quotedCol} AS TEXT)) = 36 AND LOWER(CAST(${quotedCol} AS TEXT)) GLOB '${CANONICAL_UUID_SQLITE_GLOB_PATTERN}')`)).rows?.[0];
+		return Number(row?.invalid_count ?? 0) === 0;
+	}
+	/**
+	* Render the repair for one rename-data-pending pair (#2752): copy
+	* non-empty `oldColumn` into `newColumn` only where `newColumn` is still
+	* empty (casting to `uuid` when the new column is native uuid, otherwise a
+	* plain copy), then drop `oldColumn`.
+	*
+	* Idempotency review findings and the fix:
+	*
+	* - (P1) The `newColumn`-is-empty predicate previously compared any
+	*   non-uuid destination to `''` (`col IS NULL OR col = ''`), which is
+	*   only valid for text-affinity types — PostgreSQL rejects `col = ''`
+	*   for `integer`/`boolean`/`timestamp`/etc. before a same-type rename
+	*   pair of one of those types ever copies anything. Fixed by comparing
+	*   `CAST(col AS TEXT) = ''` instead, mirroring the same portable
+	*   emptiness check {@link columnHasNonEmptyValue} already uses for
+	*   detection, so the predicate is valid for every column type.
+	* - (P2) An `UPDATE` unconditionally naming `oldColumn` fails once that
+	*   column is gone, on either engine, regardless of the DROP's own
+	*   idempotency — a guard query placed before the DROP (or even before
+	*   the UPDATE) still leaves a human decision between "run" and "don't",
+	*   which is not genuine SQL-level idempotency. PostgreSQL CAN express a
+	*   truly self-contained, unconditionally-safe-to-rerun statement here:
+	*   an anonymous `DO $$ ... $$` block (the same idiom this file already
+	*   uses for `generatePostgresIntegerPreflightSQL`) that checks
+	*   `information_schema.columns` and only runs the UPDATE + DROP when the
+	*   old column still exists — one executable statement, no operator
+	*   judgment required, safe to rerun any number of times. SQLite has no
+	*   procedural block or conditional-DDL construct at all (confirmed
+	*   against a real connection), so there the contract is explicitly
+	*   downgraded from "idempotent SQL" to "operator-mediated": a guard
+	*   query plus instructions, not a single statement that is itself safe
+	*   to blindly rerun.
+	*
+	* This is report-only either way: `db:migrate` never executes it.
+	*/
+	describeRenameDataPending(tableName, newColumn, oldColumn, newIsNativeUuid) {
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedNew = this.quoteIdentifier(newColumn);
+		const quotedOld = this.quoteIdentifier(oldColumn);
+		const copySql = `UPDATE ${quotedTable} SET ${quotedNew} = ${newIsNativeUuid ? `${quotedOld}::uuid` : quotedOld} WHERE ${newIsNativeUuid ? `${quotedNew} IS NULL` : `(${quotedNew} IS NULL OR CAST(${quotedNew} AS TEXT) = '')`} AND ${quotedOld} IS NOT NULL AND CAST(${quotedOld} AS TEXT) <> ''`;
+		let suggestedSql;
+		let dropIdempotencyNote;
+		if (this.engine === "postgres") {
+			suggestedSql = [`DO $$ BEGIN IF ${`EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ${this.quoteLiteral(tableName)} AND column_name = ${this.quoteLiteral(oldColumn)})`} THEN ${copySql}; ${`ALTER TABLE ${quotedTable} DROP COLUMN ${quotedOld}`}; END IF; END $$`];
+			dropIdempotencyNote = `This single statement is idempotent: rerunning it after the rename is complete is a genuine no-op, because it only touches ${oldColumn} when the block finds it still exists.`;
+		} else {
+			suggestedSql = [
+				`SELECT count(*) AS old_column_still_present FROM pragma_table_info(${this.quoteLiteral(tableName)}) WHERE name = ${this.quoteLiteral(oldColumn)}`,
+				copySql,
+				this.generateDropColumnSQL(tableName, oldColumn)
+			];
+			dropIdempotencyNote = `SQLite has no conditional-DDL construct, so this is operator-mediated, not self-contained idempotent SQL: run the guard query first, and only run the UPDATE and DROP below when it reports ${oldColumn} still present.`;
+		}
+		return {
+			type: "rename_data_pending",
+			table: tableName,
+			name: newColumn,
+			mismatch: {
+				expected: `data in ${newColumn}`,
+				actual: `data appears to still be in ${oldColumn}`
+			},
+			advisory: {
+				severity: "warning",
+				message: `${tableName}.${newColumn} is declared but empty, while undeclared column ${tableName}.${oldColumn} holds data of a compatible type. This looks like a framework field rename whose data was never moved (db:migrate adds columns additively and never drops the old one). ${dropIdempotencyNote}`,
+				suggestedSql
+			}
+		};
+	}
+	/**
+	* Render the advisory for an ambiguous rename-data-pending match (#2767
+	* review): more than one orphan column is a populated, type-compatible
+	* candidate for the same empty declared column, so the real rename source
+	* cannot be inferred. Unlike {@link describeRenameDataPending}, this
+	* carries no `suggestedSql` — running a per-candidate copy-and-drop would
+	* let output order decide which candidate's data wins and then drop every
+	* one of them, which is not a repair an advisory should suggest blindly.
+	*/
+	describeRenameDataPendingAmbiguous(tableName, newColumn, candidateColumns) {
+		const candidateList = candidateColumns.map((name) => `${tableName}.${name}`).join(", ");
+		return {
+			type: "rename_data_pending",
+			table: tableName,
+			name: newColumn,
+			mismatch: {
+				expected: `data in ${newColumn}`,
+				actual: `data appears to still be in one of several columns: ${candidateList}`
+			},
+			advisory: {
+				severity: "warning",
+				message: `${tableName}.${newColumn} is declared but empty, while ${candidateColumns.length} undeclared columns of a compatible type hold data (${candidateList}). This looks like a framework field rename, but which column is the actual rename source is ambiguous — no suggested repair SQL is printed. An operator must identify the correct source column and write its own targeted copy-then-drop.`
+			}
+		};
+	}
+	/**
 	* Compare nullability and default between a manifest column and the live
 	* column, emitting `alter_column` changes (#2369).
 	*