@happyvertical/smrt-cli 0.47.0 → 0.47.2

package/dist/{commands-C9UEWEvb.js → commands-uHfUPryV.js}

@@ -6,7 +6,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import * as path from "node:path";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { ObjectRegistry, SchemaComparer, checkLiveSchemaParity, createQualifiedName, ensureDeferredSystemTableCompatibility, generateDDLForEngine, getClassName, isQualifiedName, migratePostgresSystemTimestamps, parseQualifiedName, planForeignKeyCreation, planPostgresSystemTimestampMigrations } from "@happyvertical/smrt-core";
+import { ObjectRegistry, SchemaComparer, checkLiveSchemaParity, collectForeignKeyOrphanCounts, createQualifiedName, ensureDeferredSystemTableCompatibility, generateDDLForEngine, getClassName, isQualifiedName, isSmrtCollectionExtendsName, migratePostgresSystemTimestamps, parseQualifiedName, planForeignKeyCreation, planPostgresSystemTimestampMigrations } from "@happyvertical/smrt-core";
 import { loadExternalManifestSync } from "@happyvertical/smrt-core/manifest";
 import { access, cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { createLogger } from "@happyvertical/logger";
@@ -623,6 +623,7 @@ function partitionSchemaChanges(changes, getClassForTable) {
 		switch (change.type) {
 			case "orphan_column":
 			case "orphan_index":
+			case "rename_data_pending":
 				if (!change.name || !change.advisory) continue;
 				advisories.push({
 					type: change.type,
@@ -856,6 +857,7 @@ function describeAdvisory(item) {
 		case "orphan_column": return `${item.tableName}.${item.name}: orphan column${item.actual ? ` (${item.actual})` : ""}`;
 		case "orphan_index": return `${item.tableName}.${item.name}: unique constraint not in manifest${item.actual ? ` (${item.actual})` : ""}`;
 		case "type_upgrade": return `${item.tableName}.${item.name}: type upgrade blocked${item.actual ? ` (live: ${item.actual})` : ""}`;
+		case "rename_data_pending": return `${item.tableName}.${item.name}: rename data pending${item.actual ? ` (${item.actual})` : ""}`;
 		default: return `${item.tableName}.${item.name}: ${item.alteration ?? "alter_column"}${item.actual ? ` (live: ${item.actual})` : ""}`;
 	}
 }
@@ -1458,6 +1460,128 @@ function formatDateTime(date) {
 	return date.toISOString().replace("T", " ").substring(0, 19);
 }
 //#endregion
+//#region src/commands/db-orphans.ts
+/**
+* db:orphans Command (#2753)
+*
+* Read-only per-foreign-key orphan count report. `db:migrate`'s orphan probe
+* already gates `ADD CONSTRAINT` with a `LIMIT 1` existence check and prints a
+* suggested repair; this command runs the identical probe as `COUNT(*)` for
+* every manifest-declared foreign key, so planning a repair no longer starts
+* with hand-writing the same SQL against the live database.
+*
+* Strictly diagnostic: it never repairs anything, and the orphan counts
+* themselves never affect the exit code — a database full of orphans still
+* exits 0. It exits non-zero only on a configuration or runtime error (no
+* database configured, or the report itself could not run), the same
+* contract every other `db:*` command uses. The existing "no foreign-key
+* orphan repair, by design" boundary stays exactly where it is. Use `--json`
+* for scripting.
+*/
+/** Render one count row as a compact, script-friendly line. */
+function formatOrphanCountLine(count) {
+	const marker = count.nullable ? "" : " [NOT NULL]";
+	return `${count.childTable}.${count.childColumn} -> ${count.parentTable}.${count.parentColumn}: ${count.orphanCount} orphan(s)${marker}`;
+}
+/** Render the full report as console lines. */
+function formatOrphanReport(report, options = {}) {
+	const lines = [];
+	const affected = report.counts.filter((count) => count.orphanCount > 0);
+	const failedProbeCount = report.skipped.filter((skip) => skip.kind === "probe_failed").length;
+	lines.push(`   Engine: ${report.engine} · foreign keys checked: ${report.counts.length}` + (report.skipped.length > 0 ? ` · skipped: ${report.skipped.length}` : ""));
+	if (affected.length === 0 && failedProbeCount === 0) lines.push("   ✅ No orphan rows found across any manifest foreign key.");
+	else if (affected.length === 0) lines.push(`   ⚠️  No orphans found among the successfully probed foreign keys, but ${failedProbeCount} probe(s) failed — see Skipped below. The scan is incomplete, not clean.`);
+	else for (const count of affected) {
+		const icon = count.nullable ? "⚠️" : "❌";
+		lines.push(`   ${icon} ${formatOrphanCountLine(count)}`);
+	}
+	if (options.verbose) {
+		const clean = report.counts.filter((count) => count.orphanCount === 0);
+		if (clean.length > 0) {
+			lines.push(`   ✅ Zero orphans (${clean.length}):`);
+			for (const count of clean) lines.push(`      • ${formatOrphanCountLine(count)}`);
+		}
+	}
+	if (report.skipped.length > 0) {
+		lines.push("   Skipped:");
+		for (const skip of report.skipped) {
+			const marker = skip.kind === "probe_failed" ? " [PROBE FAILED]" : "";
+			lines.push(`      • ${skip.childTable}.${skip.childColumn} -> ${skip.parentTable}.${skip.parentColumn}: ${skip.reason}${marker}`);
+		}
+	}
+	return lines;
+}
+/** Foreign keys with at least one orphan row, for `db:status`'s summary. */
+function affectedOrphanCounts(report) {
+	return report.counts.filter((count) => count.orphanCount > 0);
+}
+var dbOrphansCommand = {
+	name: "db:orphans",
+	description: "Read-only per-foreign-key orphan count report: for every manifest foreign key, prints child/parent table and column, the live orphan row count, and whether the child column is NOT NULL. Never repairs. Orphans found never affect the exit code; exits non-zero only on a configuration or runtime error.",
+	aliases: ["orphans", "db-orphans"],
+	args: [],
+	options: {
+		json: {
+			type: "boolean",
+			description: "Output as JSON (for scripting)",
+			default: false,
+			short: "j"
+		},
+		verbose: {
+			type: "boolean",
+			description: "Also list foreign keys with zero orphans",
+			default: false,
+			short: "v"
+		}
+	},
+	handler: async (_args, options) => {
+		let db;
+		try {
+			const { getPackageConfig } = await import("@happyvertical/smrt-config");
+			const { DEFAULT_CLI_CONFIG } = await import("./config-DfBo4hHU.js").then((n) => n.n);
+			const config = getPackageConfig("cli", DEFAULT_CLI_CONFIG);
+			if (!config.database?.url || config.database.url === ":memory:") {
+				if (options.json) console.log(JSON.stringify({ error: "Database not configured" }));
+				else {
+					console.error("\n❌ Database configuration required");
+					console.error("\nPlease configure database in smrt.config.js\n");
+				}
+				process.exitCode = 1;
+				return;
+			}
+			const dbType = config.database.type || "sqlite";
+			const dbUrl = config.database.url;
+			if (!options.json) {
+				console.log("\n🔎 Foreign-key orphan report\n");
+				console.log(`Database: ${formatDatabaseDisplayUrl(dbType, dbUrl)}\n`);
+			}
+			const { getDatabase } = await import("@happyvertical/sql");
+			db = await getDatabase({
+				type: dbType,
+				url: dbUrl
+			});
+			await autoDiscoverAndLoad();
+			const manifestSchemas = ObjectRegistry.getAllSchemasAsDefinitions();
+			const report = await collectForeignKeyOrphanCounts(db, manifestSchemas, { engineHint: dbType });
+			if (options.json) {
+				console.log(JSON.stringify(report, null, 2));
+				return;
+			}
+			for (const line of formatOrphanReport(report, { verbose: options.verbose })) console.log(line);
+			console.log();
+		} catch (error) {
+			if (options.json) console.log(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+			else {
+				console.error("\n❌ Failed to collect the orphan report:");
+				if (error instanceof Error) console.error(`   ${error.message}`);
+			}
+			process.exitCode = 1;
+		} finally {
+			await closeDatabaseConnection(db);
+		}
+	}
+};
+//#endregion
 //#region src/commands/db-permissions.ts
 /** The only mutating caller is the explicit permissions command. */
 async function runPostgresPermissions(options = {}, optional = false) {
@@ -2085,15 +2209,19 @@ var dbRollbackCommand = {
 /**
 * Collect every declared upsert conflict target, keyed by table name.
 *
-* The conflict target is a registry property, not a manifest one: a class may
-* declare `conflictColumns` explicitly, inherit the CTI `(slug, context)`
-* default, or get the STI `(slug, context, _meta_type)` triple. Whatever it
-* resolves to, the live database needs a matching UNIQUE index or every upsert
-* against that table either errors (PostgreSQL) or duplicates rows.
+* The conflict target is a registry property of a persisted object, not a
+* manifest one: an object may declare `conflictColumns` explicitly, inherit
+* the CTI `(slug, context)` default, or get the STI
+* `(slug, context, _meta_type)` triple. Collections share their item table,
+* but never persist through their own conflict target, so they must not add a
+* synthetic default target to the parity check. Every collected target needs a
+* matching UNIQUE index or its object upsert either errors (PostgreSQL) or
+* duplicates rows.
 */
 function collectRegistryConflictTargets() {
 	const targets = {};
 	for (const className of ObjectRegistry.getQualifiedClassNames()) {
+		if (isCollectionRegistration(className)) continue;
 		const tableName = ObjectRegistry.getTableName(className);
 		if (!tableName) continue;
 		const columns = ObjectRegistry.getConflictColumns(className);
@@ -2108,6 +2236,19 @@ function collectRegistryConflictTargets() {
 	return targets;
 }
 /**
+* Matches core's collection classification, including a registered collection
+* subclass whose immediate parent is another collection class. Unknown
+* registrations stay included so a malformed registry cannot hide a real
+* persistence target from a fail-closed parity check.
+*/
+function isCollectionRegistration(className) {
+	for (const name of [className, ...ObjectRegistry.getInheritanceChain(className)]) {
+		const registered = ObjectRegistry.getClass(name);
+		if (registered && isSmrtCollectionExtendsName(registered.extends)) return true;
+	}
+	return false;
+}
+/**
 * Run the parity check against the configured database.
 *
 * Never throws for an operational problem: connection and introspection
@@ -2441,7 +2582,7 @@ function assertSchemaContract(report) {
 * - Pending migrations
 * - Drift detection warnings
 */
-var CANONICAL_UUID_RE = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
+var CANONICAL_UUID_RE$1 = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
 function getSchemaColumn(schema, columnName) {
 	const columns = schema?.columns;
 	if (!columns) return null;
@@ -2465,7 +2606,7 @@ async function countNonUuidTenantIds(db) {
 	const row = (await db.query(`SELECT count(*)::text AS count
        FROM tenants
       WHERE nullif(btrim(id), '') IS NOT NULL
-        AND btrim(id) !~* '${CANONICAL_UUID_RE}'`))?.rows?.[0] ?? {};
+        AND btrim(id) !~* '${CANONICAL_UUID_RE$1}'`))?.rows?.[0] ?? {};
 	return Number(row.count ?? row.n ?? 0);
 }
 async function checkTenantIdUuidPreconditions(input) {
@@ -2603,6 +2744,14 @@ function summarizeSchemaDiff(diff) {
 				recommendation: "Run `smrt db:migrate --drop-columns` to drop this orphan column (destructive)."
 			});
 			break;
+		case "rename_data_pending":
+			if (change.advisory?.severity !== "warning") break;
+			drift.push({
+				name: `${change.table}.${change.name ?? "(unknown)"}`,
+				type: "rename_data_pending",
+				recommendation: change.advisory?.message ?? "A declared column is empty while an undeclared column of a compatible type holds data — data appears to still live in the old column after a field rename. Run `smrt db:diff` for the suggested backfill SQL."
+			});
+			break;
 	}
 	return drift;
 }
@@ -2733,7 +2882,10 @@ var dbStatusCommand = {
 				failedMigrations: summarizeFailedMigrations(failed, null),
 				schemaContract,
 				parity: null,
-				parityError: null
+				parityError: null,
+				orphanedForeignKeys: [],
+				orphanProbeFailures: [],
+				orphansError: null
 			};
 			let diff = {
 				added_tables: [],
@@ -2741,8 +2893,8 @@ var dbStatusCommand = {
 				changes: [],
 				has_changes: false
 			};
+			const manifestSchemas = ObjectRegistry.getAllSchemasAsDefinitions();
 			if (typeof db.getTableSchema === "function") {
-				const manifestSchemas = ObjectRegistry.getAllSchemasAsDefinitions();
 				diff = await new SchemaComparer(db).compare(manifestSchemas);
 				status.drift = summarizeSchemaDiff(diff);
 				status.notes = summarizeSchemaNotes(diff);
@@ -2765,6 +2917,13 @@ var dbStatusCommand = {
 					status.parityError = error instanceof Error ? error.message : String(error);
 				}
 			} else if (options.parity) status.parityError = "The configured database adapter cannot describe tables, so live-schema parity cannot be verified.";
+			try {
+				const orphanReport = await collectForeignKeyOrphanCounts(db, manifestSchemas, { engineHint: dbType });
+				status.orphanedForeignKeys = affectedOrphanCounts(orphanReport);
+				status.orphanProbeFailures = orphanReport.skipped.filter((skip) => skip.kind === "probe_failed");
+			} catch (error) {
+				status.orphansError = error instanceof Error ? error.message : String(error);
+			}
 			const failedAssessments = assessFailedMigrations(failed, typeof db.getTableSchema === "function" ? diff : null);
 			status.migrations.failed = {
 				total: failedAssessments.length,
@@ -2828,6 +2987,23 @@ var dbStatusCommand = {
 				}
 				console.log();
 			}
+			if (status.orphansError) {
+				console.log(`⚠️  Foreign-key orphan check unavailable: ${status.orphansError}`);
+				console.log();
+			} else {
+				if (status.orphanedForeignKeys.length > 0) {
+					console.log(`⚠️  Foreign-key orphans found (${status.orphanedForeignKeys.length}):`);
+					for (const count of status.orphanedForeignKeys) console.log(`   • ${formatOrphanCountLine(count)}`);
+					console.log("   Run `smrt db:orphans` for the full report.");
+					console.log();
+				}
+				if (status.orphanProbeFailures.length > 0) {
+					console.log(`⚠️  ${status.orphanProbeFailures.length} foreign-key orphan probe(s) failed (not counted as clean):`);
+					for (const failure of status.orphanProbeFailures) console.log(`   • ${failure.childTable}.${failure.childColumn} -> ${failure.parentTable}.${failure.parentColumn}: ${failure.reason}`);
+					console.log("   Run `smrt db:orphans` for details.");
+					console.log();
+				}
+			}
 			if (options.parity) {
 				console.log("🗄️  Live Schema Parity:");
 				if (status.parityError) {
@@ -6362,6 +6538,56 @@ var dbDropFrameworkBaseTablesCommand = {
 	}
 };
 //#endregion
+//#region src/commands/db-migrate-agent-schedule-slugs.ts
+var dbMigrateAgentScheduleSlugsCommand = {
+	name: "db:migrate-agent-schedule-slugs",
+	description: "Backfill canonical slugs for legacy framework AgentSchedule rows after db:migrate. Requires a PostgreSQL maintenance window; it never runs schedules.",
+	aliases: ["migrate-agent-schedule-slugs", "db-migrate-schedule-slugs"],
+	args: [],
+	options: { "dry-run": {
+		type: "boolean",
+		description: "Validate legacy schedule identities without writing.",
+		default: false
+	} },
+	handler: async (_args, options) => {
+		let db;
+		try {
+			const { getPackageConfig } = await import("@happyvertical/smrt-config");
+			const { DEFAULT_CLI_CONFIG } = await import("./config-DfBo4hHU.js").then((n) => n.n);
+			const config = getPackageConfig("cli", DEFAULT_CLI_CONFIG);
+			if (!config.database?.url || config.database.url === ":memory:") throw new Error("Database configuration required for db:migrate-agent-schedule-slugs. Configure database.url in smrt.config.ts (or DATABASE_URL).");
+			const dbType = config.database.type || "sqlite";
+			if (dbType !== "postgres") throw new Error("db:migrate-agent-schedule-slugs currently supports PostgreSQL only; no changes were made.");
+			const { getDatabase } = await import("@happyvertical/sql");
+			const { AGENT_SCHEDULE_SLUG_BACKFILL, migrateAgentScheduleSlugs, planAgentScheduleSlugMigration } = await import("@happyvertical/smrt-agents");
+			db = await getDatabase({
+				type: dbType,
+				url: config.database.url
+			});
+			console.log("\n🗓️  AgentSchedule slug migration\n");
+			console.log(`✓ Connected to ${formatDatabaseDisplayUrl(dbType, config.database.url)}\n`);
+			if (options["dry-run"]) {
+				const plan = await planAgentScheduleSlugMigration(db);
+				console.log(`DRY RUN: ${plan.pending} AgentSchedule slug(s) would be backfilled; no schedules run and no changes made.\n`);
+				return;
+			}
+			const postgres = config.migrations?.postgres;
+			const result = await migrateAgentScheduleSlugs(db, {
+				backfillName: AGENT_SCHEDULE_SLUG_BACKFILL,
+				packageName: "@happyvertical/smrt-agents",
+				lockTimeout: parsePostgresTimeoutMs(postgres?.lockTimeout, 3e4),
+				statementTimeout: parsePostgresTimeoutMs(postgres?.statementTimeout, 6e4)
+			});
+			console.log(result.ran ? `✓ Backfilled ${result.updated} AgentSchedule slug(s); no schedules were run.\n` : "No schedule slug migration was needed.\n");
+		} catch (error) {
+			console.error(`\n❌ AgentSchedule slug migration failed: ${error instanceof Error ? error.message : String(error)}\n`);
+			process.exitCode = 1;
+		} finally {
+			await closeDatabaseConnection(db);
+		}
+	}
+};
+//#endregion
 //#region src/commands/db-migrate-int8.ts
 /**
 * db:migrate-int8 Command
@@ -6475,7 +6701,7 @@ var dbMigrateInt8Command = {
 *     drop the old column.
 *
 *  2. **TEXT → native uuid conversion**. Most existing `id`/FK columns already
-*     hold canonical UUID strings in TEXT columns and can be promoted to native
+*     hold UUID-shaped strings in TEXT columns and can be promoted to native
 *     `uuid`. Conversion is gated on TWO independent checks, BOTH of which must
 *     pass for a column to be converted:
 *
@@ -6490,7 +6716,7 @@ var dbMigrateInt8Command = {
 *           Tables not present in the manifest (non-SMRT tables in the `public`
 *           schema) drop out automatically.
 *
-*       (b) **Data-shape** — every non-empty value is already a canonical UUID.
+*       (b) **Data-shape** — every non-empty value is already UUID-shaped.
 *           A declared-UUID column that still holds genuine non-uuid values
 *           (legacy unhyphenated ids, partially-migrated data, …) is SKIPPED and
 *           reported so the operator can clean it before re-running.
@@ -6523,7 +6749,8 @@ var dbMigrateInt8Command = {
 *   smrt db:migrate-uuid --rename "parent_id:source_asset_id" --table assets
 *   smrt db:migrate-uuid --rename "parent_slug:parent_id" --table tags --skip-convert
 */
-var UUID_RE = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
+var UUID_RE = "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{32})$";
+var CANONICAL_UUID_RE = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
 /**
 * Build the set of schema-declared UUID columns from a manifest's
 * `getAllSchemasAsDefinitions()` output.
@@ -6543,12 +6770,88 @@ function buildDeclaredUuidColumnSet(schemaDefinitions) {
 function declaredUuidKey(table, column) {
 	return `${table}|${column}`;
 }
+function renamedSourceColumns(renameSpecs) {
+	return new Set(renameSpecs.map((spec) => declaredUuidKey(spec.table, spec.from)));
+}
+/**
+* Propagate skips across foreign-key edges to a fixpoint.
+*
+* `db:migrate-uuid` converts a column only when BOTH its declared-UUID/clean
+* data gates pass (see `planUuidConversions`) AND every foreign-key partner
+* of it will also convert — otherwise `ALTER TABLE … ADD CONSTRAINT` at
+* recreation time would fail with a text/uuid type mismatch. Rather than
+* aborting the whole run, block the convertible partner too: a column
+* skipped for dirty data or because the schema intentionally keeps it TEXT
+* blocks every foreign-key partner of it, and that block propagates
+* transitively (a two-hop chain blocks both hops).
+*
+* Pure and DB-independent: `edges` is the full set of single-column foreign
+* keys touching the candidate columns, discovered separately. Multi-column
+* foreign keys are out of scope here and stay a hard refusal downstream.
+*/
+/** Human-readable reason for one `skipDirtyData` entry — shared by dry-run/apply logging and FK-block-propagation reasons. */
+function dirtyDataReason(item) {
+	const parts = [];
+	if (item.nonUuid > 0) parts.push(`${item.nonUuid} non-uuid value(s)`);
+	if (item.duplicateNormalized) parts.push(`${item.duplicateNormalized} duplicate value(s) after normalization`);
+	return parts.join(", ");
+}
+function propagateBlockedForeignKeyPartners(plan, edges) {
+	const convertByKey = new Map(plan.convert.map((candidate) => [declaredUuidKey(candidate.table, candidate.column), candidate]));
+	const blockedReason = /* @__PURE__ */ new Map();
+	for (const item of plan.skipDirtyData) blockedReason.set(declaredUuidKey(item.table, item.column), dirtyDataReason(item));
+	for (const item of plan.skipNotDeclared) blockedReason.set(declaredUuidKey(item.table, item.column), "not schema-declared UUID");
+	const skipBlockedPartner = [];
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const edge of edges) {
+			const childKey = declaredUuidKey(edge.childTable, edge.childColumn);
+			const parentKey = declaredUuidKey(edge.parentTable, edge.parentColumn);
+			const childBlockedReason = blockedReason.get(childKey);
+			const parentBlockedReason = blockedReason.get(parentKey);
+			if (childBlockedReason !== void 0 && parentBlockedReason === void 0 && convertByKey.has(parentKey)) {
+				const candidate = convertByKey.get(parentKey);
+				if (!candidate) continue;
+				const reason = `blocked by foreign key ${edge.name} to ${edge.childTable}.${edge.childColumn} (${childBlockedReason})`;
+				blockedReason.set(parentKey, reason);
+				convertByKey.delete(parentKey);
+				skipBlockedPartner.push({
+					table: candidate.table,
+					column: candidate.column,
+					reason
+				});
+				changed = true;
+				continue;
+			}
+			if (parentBlockedReason !== void 0 && childBlockedReason === void 0 && convertByKey.has(childKey)) {
+				const candidate = convertByKey.get(childKey);
+				if (!candidate) continue;
+				const reason = `blocked by foreign key ${edge.name} to ${edge.parentTable}.${edge.parentColumn} (${parentBlockedReason})`;
+				blockedReason.set(childKey, reason);
+				convertByKey.delete(childKey);
+				skipBlockedPartner.push({
+					table: candidate.table,
+					column: candidate.column,
+					reason
+				});
+				changed = true;
+			}
+		}
+	}
+	return {
+		convert: [...convertByKey.values()],
+		skipDirtyData: plan.skipDirtyData,
+		skipNotDeclared: plan.skipNotDeclared,
+		skipBlockedPartner
+	};
+}
 /**
 * Decide which live TEXT columns to convert to native `uuid`.
 *
 * A column is converted ONLY if BOTH gates pass:
 *   1. it is in the schema-declared-UUID set, AND
-*   2. all of its non-empty values are already canonical UUIDs.
+*   2. all of its non-empty values are already UUID-shaped.
 *
 * Declared-UUID columns with dirty data are reported in `skipDirtyData`;
 * undeclared columns (schema-intentional TEXT, or non-SMRT tables) are reported
@@ -6566,11 +6869,13 @@ function planUuidConversions(liveColumns, declaredUuid) {
 			});
 			continue;
 		}
-		if (col.nonUuid > 0) {
+		const duplicateNormalized = col.duplicateNormalized ?? 0;
+		if (col.nonUuid > 0 || duplicateNormalized > 0) {
 			skipDirtyData.push({
 				table: col.table,
 				column: col.column,
-				nonUuid: col.nonUuid
+				nonUuid: col.nonUuid,
+				...duplicateNormalized > 0 ? { duplicateNormalized } : {}
 			});
 			continue;
 		}
@@ -6671,111 +6976,35 @@ var dbMigrateUuidCommand = {
 			const isPostgres = dbType === "postgres" || /^postgres/i.test(dbUrl);
 			const runRenames = renameSpecs.length > 0;
 			const skipConvert = Boolean(options["skip-convert"]);
-			const sharedTxn = runRenames && !skipConvert && isPostgres && !dryRun;
-			let openTxn = false;
-			try {
-				if (runRenames) {
-					if (sharedTxn) {
-						await db.query("BEGIN");
-						openTxn = true;
-					}
-					await applyRenameBackfills(db, isPostgres, renameSpecs, dryRun, { ownTransaction: !sharedTxn });
-				}
-				if (skipConvert) {
-					console.log("Skipping TEXT→uuid conversion (--skip-convert).\n");
-					return;
-				}
-				if (!isPostgres) {
-					console.log(`Database type "${dbType}" has no native uuid column type that needs converting; uuid conversion is a no-op.\n`);
-					return;
-				}
-				const declaredUuid = await loadDeclaredUuidColumns();
-				if (declaredUuid.size === 0) {
-					console.log("No schema-declared UUID columns found in the loaded manifest.");
-					console.log("Skipping TEXT→uuid conversion (fail-closed). Run this command from\nthe project root so the SMRT manifest can be discovered, then re-run.\n");
-					if (openTxn && !dryRun) {
-						await db.query("COMMIT");
-						openTxn = false;
-					}
-					return;
-				}
-				const { rows: candidates } = await db.query(`SELECT table_name, column_name, (column_default IS NOT NULL) AS has_default
-             FROM information_schema.columns
-            WHERE table_schema = 'public'
-              AND data_type = 'text'
-              AND (column_name = 'id' OR column_name ~* '(_id|Id)$')
-            ORDER BY table_name, column_name`);
-				const liveColumns = [];
-				for (const row of candidates) {
-					const declared = declaredUuid.has(`${row.table_name}|${row.column_name}`);
-					let nonUuid = 0;
-					if (declared) {
-						const t = quoteIdentifier(row.table_name);
-						const c = quoteIdentifier(row.column_name);
-						const { rows } = await db.query(`SELECT count(*)::text AS n
-                 FROM ${t}
-                WHERE nullif(btrim(${c}), '') IS NOT NULL
-                  AND btrim(${c}) !~* '${UUID_RE}'`);
-						nonUuid = Number(rows[0]?.n ?? "0");
-					}
-					liveColumns.push({
-						table: row.table_name,
-						column: row.column_name,
-						hasDefault: Boolean(row.has_default),
-						nonUuid
-					});
-				}
-				const { convert, skipDirtyData, skipNotDeclared } = planUuidConversions(liveColumns, declaredUuid);
-				console.log(`Found ${candidates.length} TEXT id/FK column(s): ${convert.length} convertible, ${skipDirtyData.length + skipNotDeclared.length} skipped.`);
-				if (skipDirtyData.length > 0) {
-					console.log("\nSKIP (declared UUID but data still has non-UUID values — clean these first):");
-					for (const s of skipDirtyData) console.log(`  - ${s.table}.${s.column} (${s.nonUuid} non-uuid)`);
-				}
-				if (skipNotDeclared.length > 0) {
-					console.log("\nSKIP (not declared UUID by the SMRT schema, left as TEXT):");
-					for (const s of skipNotDeclared) console.log(`  - ${s.table}.${s.column}`);
-				}
-				if (convert.length === 0) {
-					console.log("\nNothing to convert. Done.\n");
-					if (openTxn && !dryRun) {
-						await db.query("COMMIT");
-						openTxn = false;
-					}
-					return;
-				}
-				console.log(`\n${dryRun ? "DRY RUN — would run" : "Applying"} ${convert.length} conversion(s):`);
-				if (!sharedTxn && !dryRun) {
-					await db.query("BEGIN");
-					openTxn = true;
-				}
-				for (const { table, column, hasDefault } of convert) {
-					const t = quoteIdentifier(table);
-					const c = quoteIdentifier(column);
-					if (hasDefault) {
-						const dropDefault = `ALTER TABLE ${t} ALTER COLUMN ${c} DROP DEFAULT`;
-						console.log(`  ${dropDefault};`);
-						if (!dryRun) await db.query(dropDefault);
-					}
-					const alter = `ALTER TABLE ${t} ALTER COLUMN ${c} TYPE uuid USING NULLIF(btrim(${c}), '')::uuid`;
-					console.log(`  ${alter};`);
-					if (!dryRun) await db.query(alter);
-				}
-				if (!dryRun) {
-					if (openTxn) {
-						await db.query("COMMIT");
-						openTxn = false;
-					}
-					console.log(`\n✓ Converted ${convert.length} column(s) to uuid.\n`);
-				} else console.log("\nDry run complete — no changes applied.\n");
-			} catch (error) {
-				if (openTxn && !dryRun) {
-					try {
-						await db.query("ROLLBACK");
-					} catch {}
-					openTxn = false;
-				}
-				throw error;
+			const runConvert = !skipConvert && isPostgres;
+			if (skipConvert) {
+				await applyRenameOnlyBackfills(db, isPostgres, renameSpecs, dryRun);
+				console.log("Skipping TEXT→uuid conversion (--skip-convert).\n");
+				return;
+			}
+			if (!isPostgres) {
+				await applyRenameOnlyBackfills(db, isPostgres, renameSpecs, dryRun);
+				console.log(`Database type "${dbType}" has no native uuid column type that needs converting; uuid conversion is a no-op.\n`);
+				return;
 			}
+			const declaredUuid = await loadDeclaredUuidColumns();
+			if (declaredUuid.size === 0) {
+				console.log("No schema-declared UUID columns found in the loaded manifest.");
+				console.log("Skipping TEXT→uuid conversion (fail-closed). Run this command from\nthe project root so the SMRT manifest can be discovered, then re-run.\n");
+				await applyRenameOnlyBackfills(db, isPostgres, renameSpecs, dryRun);
+				return;
+			}
+			if (dryRun) {
+				await applyRenameBackfills(db, isPostgres, renameSpecs, true, { ownTransaction: false });
+				await convertPostgresUuidColumns(db, declaredUuid, true, true, renamedSourceColumns(renameSpecs), renameSpecs);
+				return;
+			}
+			if (!db.transaction) throw new Error("PostgreSQL UUID migration requires DatabaseInterface.transaction(); refusing to run unpinned DDL.");
+			if (runRenames && runConvert) await convertPostgresUuidColumns(db, declaredUuid, true, false, renamedSourceColumns(renameSpecs), renameSpecs);
+			await db.transaction(async (tx) => {
+				await applyRenameBackfills(tx, true, renameSpecs, false, { ownTransaction: false });
+				await convertPostgresUuidColumns(tx, declaredUuid, false);
+			});
 		} catch (error) {
 			console.error(`\n❌ uuid migration failed: ${error instanceof Error ? error.message : String(error)}\n`);
 			process.exitCode = 1;
@@ -6787,6 +7016,569 @@ var dbMigrateUuidCommand = {
 function nullifEmpty(isPostgres, quotedCol) {
 	return isPostgres ? `nullif(btrim(${quotedCol}), '')` : `nullif(trim(${quotedCol}), '')`;
 }
+/** Execute a rename-only PostgreSQL mutation on the transaction callback. */
+async function applyRenameOnlyBackfills(db, isPostgres, renameSpecs, dryRun) {
+	if (!isPostgres || dryRun) {
+		await applyRenameBackfills(db, isPostgres, renameSpecs, dryRun, { ownTransaction: !dryRun });
+		return;
+	}
+	if (renameSpecs.length === 0) {
+		await applyRenameBackfills(db, true, renameSpecs, false, { ownTransaction: false });
+		return;
+	}
+	if (!db.transaction) throw new Error("PostgreSQL UUID migration requires DatabaseInterface.transaction(); refusing to run unpinned DDL.");
+	await db.transaction(async (tx) => {
+		await applyRenameBackfills(tx, true, renameSpecs, false, { ownTransaction: false });
+	});
+}
+function quoteLiteral(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+/** PostgreSQL relation reference in the migration's fixed public schema. */
+function pgTable(table) {
+	return `${quoteIdentifier("public")}.${quoteIdentifier(table)}`;
+}
+/**
+* Convert a deliberately narrow PostgreSQL dependency component.  This is
+* intentionally catalog-driven: generated text bridges are consumer schema,
+* not SMRT manifest columns, and are never guessed from a name.
+*/
+async function convertPostgresUuidColumns(db, declaredUuid, dryRun, renderDryRun = true, excludedColumns = /* @__PURE__ */ new Set(), projectedRenames = []) {
+	const { rows: candidateRows } = await db.query(`SELECT cols.table_name, cols.column_name, cols.column_default,
+              relation.oid::text AS relation_oid, attribute.attnum AS attribute_number,
+              format_type(attribute.atttypid, attribute.atttypmod) AS type_name
+         FROM information_schema.columns cols
+         JOIN pg_namespace namespace ON namespace.nspname = cols.table_schema
+         JOIN pg_class relation ON relation.relnamespace = namespace.oid AND relation.relname = cols.table_name
+         JOIN pg_attribute attribute ON attribute.attrelid = relation.oid AND attribute.attname = cols.column_name
+        WHERE cols.table_schema = 'public' AND cols.data_type = 'text'
+        AND (column_name = 'id' OR column_name ~* '(_id|Id)$')
+      ORDER BY table_name, column_name`);
+	const liveColumns = [];
+	const defaults = /* @__PURE__ */ new Map();
+	for (const row of candidateRows) {
+		const table = String(row.table_name);
+		const column = String(row.column_name);
+		if (excludedColumns.has(declaredUuidKey(table, column))) continue;
+		let nonUuid = 0;
+		let duplicateNormalized = 0;
+		if (declaredUuid.has(declaredUuidKey(table, column))) {
+			const { rows } = await db.query(`SELECT count(*)::text AS n FROM ${pgTable(table)}
+          WHERE nullif(btrim(${quoteIdentifier(column)}), '') IS NOT NULL
+            AND btrim(${quoteIdentifier(column)}) !~* '${UUID_RE}'`);
+			nonUuid = Number(rows[0]?.n ?? 0);
+			const uniqueIndexes = await findUniqueIndexKeyColumns(db, String(row.relation_oid), Number(row.attribute_number));
+			for (const { keyColumns, nullsNotDistinct } of uniqueIndexes) {
+				const otherColumns = keyColumns.filter((c) => c.name !== column);
+				const otherColumnExpr = (other) => {
+					const quoted = quoteIdentifier(other.name);
+					if (other.typeName === "uuid") return quoted;
+					if (declaredUuid.has(declaredUuidKey(table, other.name))) return `CASE WHEN btrim(${quoted}) ~* '${UUID_RE}' THEN NULLIF(btrim(${quoted}), '')::uuid::text ELSE ${quoted} END`;
+					return quoted;
+				};
+				const nullGuards = nullsNotDistinct ? [] : otherColumns.map((other) => `${quoteIdentifier(other.name)} IS NOT NULL`);
+				const groupBy = [...otherColumns.map(otherColumnExpr), `NULLIF(btrim(${quoteIdentifier(column)}), '')::uuid`].join(", ");
+				const whereClause = [
+					`nullif(btrim(${quoteIdentifier(column)}), '') IS NOT NULL`,
+					`btrim(${quoteIdentifier(column)}) ~* '${UUID_RE}'`,
+					...nullGuards
+				].join(" AND ");
+				const { rows: dupRows } = await db.query(`SELECT count(*)::text AS n FROM (
+               SELECT 1
+                 FROM ${pgTable(table)}
+                WHERE ${whereClause}
+                GROUP BY ${groupBy}
+               HAVING count(DISTINCT ${quoteIdentifier(column)}) > 1
+             ) collisions`);
+				const found = Number(dupRows[0]?.n ?? 0);
+				if (found > 0) {
+					duplicateNormalized += found;
+					break;
+				}
+			}
+		}
+		liveColumns.push({
+			table,
+			column,
+			hasDefault: row.column_default != null,
+			nonUuid,
+			duplicateNormalized
+		});
+		defaults.set(declaredUuidKey(table, column), row.column_default == null ? null : String(row.column_default));
+	}
+	for (const spec of projectedRenames) {
+		const destination = liveColumns.find((column) => column.table === spec.table && column.column === spec.to);
+		if (!destination || !declaredUuid.has(declaredUuidKey(spec.table, spec.to))) continue;
+		const { rows: source } = await db.query(`SELECT 1 FROM information_schema.columns
+        WHERE table_schema = 'public'
+          AND table_name = ${quoteLiteral(spec.table)}
+          AND column_name = ${quoteLiteral(spec.from)}`);
+		if (source.length === 0) continue;
+		const { rows } = await db.query(`SELECT count(*)::text AS n FROM ${pgTable(spec.table)}
+        WHERE ${nullifEmpty(true, quoteIdentifier(spec.from))} IS NOT NULL
+          AND ${quoteIdentifier(spec.to)} IS NULL
+          AND btrim(${quoteIdentifier(spec.from)}) !~* '${UUID_RE}'`);
+		destination.nonUuid += Number(rows[0]?.n ?? 0);
+	}
+	const initialPlan = planUuidConversions(liveColumns, declaredUuid);
+	const { skipDirtyData, skipNotDeclared } = initialPlan;
+	await assertNoCrossSchemaForeignKeyPartners(db, new Set([...initialPlan.convert, ...skipDirtyData].map((candidate) => declaredUuidKey(candidate.table, candidate.column))));
+	const { convert, skipBlockedPartner = [] } = propagateBlockedForeignKeyPartners(initialPlan, await fetchSingleColumnForeignKeyEdges(db));
+	console.log(`Found ${candidateRows.length} TEXT id/FK column(s): ${convert.length} convertible, ${skipDirtyData.length + skipNotDeclared.length + skipBlockedPartner.length} skipped.`);
+	for (const item of skipDirtyData) console.log(`  SKIP ${item.table}.${item.column}: ${dirtyDataReason(item)}`);
+	for (const item of skipNotDeclared) console.log(`  SKIP ${item.table}.${item.column}: not schema-declared UUID`);
+	for (const item of skipBlockedPartner) console.log(`  SKIP ${item.table}.${item.column}: ${item.reason}`);
+	if (convert.length === 0) {
+		console.log("\nNothing to convert. Done.\n");
+		return;
+	}
+	const columns = convert.map((column) => ({
+		...column,
+		defaultExpression: defaults.get(declaredUuidKey(column.table, column.column)) ?? null,
+		relationOid: String(candidateRows.find((row) => String(row.table_name) === column.table && String(row.column_name) === column.column)?.relation_oid),
+		attributeNumber: Number(candidateRows.find((row) => String(row.table_name) === column.table && String(row.column_name) === column.column)?.attribute_number),
+		typeName: String(candidateRows.find((row) => String(row.table_name) === column.table && String(row.column_name) === column.column)?.type_name)
+	}));
+	await assertSupportedSourceColumns(db, columns);
+	const bridges = await snapshotGeneratedBridges(db, columns);
+	const foreignKeys = await snapshotForeignKeys(db, columns, bridges);
+	await assertSupportedBridgeDependencies(db, bridges, foreignKeys);
+	const tables = [.../* @__PURE__ */ new Set([
+		...columns.map((column) => column.table),
+		...bridges.map((bridge) => bridge.table),
+		...foreignKeys.map((foreignKey) => foreignKey.table)
+	])].sort();
+	if (dryRun) {
+		if (!renderDryRun) return;
+		console.log(`\nDRY RUN — dependency plan for ${columns.length} conversion(s):`);
+		for (const table of tables) console.log(`  LOCK TABLE ${pgTable(table)} IN ACCESS EXCLUSIVE MODE;`);
+		renderUuidConversionSql(columns, bridges, foreignKeys);
+		console.log("\nDry run complete — no changes applied.\n");
+		return;
+	}
+	for (const table of tables) await db.query(`LOCK TABLE ${pgTable(table)} IN ACCESS EXCLUSIVE MODE`);
+	await assertSupportedSourceColumns(db, columns);
+	for (const column of columns) {
+		const { rows } = await db.query(`SELECT cols.column_default, relation.oid::text AS relation_oid,
+              attribute.attnum AS attribute_number,
+              format_type(attribute.atttypid, attribute.atttypmod) AS type_name
+         FROM information_schema.columns cols
+         JOIN pg_namespace namespace ON namespace.nspname = cols.table_schema
+         JOIN pg_class relation ON relation.relnamespace = namespace.oid AND relation.relname = cols.table_name
+         JOIN pg_attribute attribute ON attribute.attrelid = relation.oid AND attribute.attname = cols.column_name
+        WHERE cols.table_schema = 'public'
+          AND cols.table_name = ${quoteLiteral(column.table)}
+          AND cols.column_name = ${quoteLiteral(column.column)}`);
+		const lockedDefault = rows[0]?.column_default == null ? null : String(rows[0].column_default);
+		const locked = rows[0];
+		if (lockedDefault !== column.defaultExpression || String(locked?.relation_oid) !== column.relationOid || Number(locked?.attribute_number) !== column.attributeNumber || String(locked?.type_name) !== column.typeName) throw new Error(`UUID source identity, type, or default changed while locks were acquired for ${column.table}.${column.column}; refusing stale migration plan. Re-run the command.`);
+	}
+	const rescannedBridges = await snapshotGeneratedBridges(db, columns);
+	const rescannedForeignKeys = await snapshotForeignKeys(db, columns, rescannedBridges);
+	await assertSupportedBridgeDependencies(db, rescannedBridges, rescannedForeignKeys);
+	if (JSON.stringify({
+		bridges,
+		foreignKeys
+	}) !== JSON.stringify({
+		bridges: rescannedBridges,
+		foreignKeys: rescannedForeignKeys
+	})) throw new Error("UUID dependency catalog changed while locks were acquired; refusing stale migration plan. Re-run the command.");
+	renderUuidConversionSql(columns, bridges, foreignKeys);
+	for (const foreignKey of foreignKeys) await db.query(`ALTER TABLE ${pgTable(foreignKey.table)} DROP CONSTRAINT ${quoteIdentifier(foreignKey.name)}`);
+	for (const bridge of bridges) await db.query(`ALTER TABLE ${pgTable(bridge.table)} DROP COLUMN ${quoteIdentifier(bridge.column)}`);
+	for (const column of columns) {
+		const table = pgTable(column.table);
+		const name = quoteIdentifier(column.column);
+		if (column.defaultExpression) await db.query(`ALTER TABLE ${table} ALTER COLUMN ${name} DROP DEFAULT`);
+		await db.query(`ALTER TABLE ${table} ALTER COLUMN ${name} TYPE uuid USING NULLIF(btrim(${name}), '')::uuid`);
+		if (column.defaultExpression) await db.query(`ALTER TABLE ${table} ALTER COLUMN ${name} SET DEFAULT (${column.defaultExpression})::uuid`);
+	}
+	for (const bridge of bridges) {
+		await db.query(`ALTER TABLE ${pgTable(bridge.table)} ADD COLUMN ${quoteIdentifier(bridge.column)} text GENERATED ALWAYS AS (${quoteIdentifier(bridge.sourceColumn)}::text) STORED`);
+		if (bridge.statisticsTarget != null && bridge.statisticsTarget !== -1) await db.query(`ALTER TABLE ${pgTable(bridge.table)} ALTER COLUMN ${quoteIdentifier(bridge.column)} SET STATISTICS ${bridge.statisticsTarget}`);
+		if (bridge.compression) await db.query(`ALTER TABLE ${pgTable(bridge.table)} ALTER COLUMN ${quoteIdentifier(bridge.column)} SET COMPRESSION ${bridge.compression === "l" ? "lz4" : "pglz"}`);
+	}
+	for (const { index, table } of uniqueBridgeIndexes(bridges)) {
+		await db.query(index.definition);
+		if (index.comment) await db.query(`COMMENT ON INDEX ${quoteIdentifier(index.schema)}.${quoteIdentifier(index.name)} IS ${quoteLiteral(index.comment)}`);
+		if (index.clustered) await db.query(`ALTER TABLE ${pgTable(table)} CLUSTER ON ${quoteIdentifier(index.name)}`);
+		if (index.replicaIdentity) await db.query(`ALTER TABLE ${pgTable(table)} REPLICA IDENTITY USING INDEX ${quoteIdentifier(index.name)}`);
+	}
+	for (const foreignKey of foreignKeys) {
+		await db.query(`ALTER TABLE ${pgTable(foreignKey.table)} ADD CONSTRAINT ${quoteIdentifier(foreignKey.name)} ${foreignKey.definition}${foreignKey.validated ? "" : " NOT VALID"}`);
+		if (foreignKey.comment) await db.query(`COMMENT ON CONSTRAINT ${quoteIdentifier(foreignKey.name)} ON ${pgTable(foreignKey.table)} IS ${quoteLiteral(foreignKey.comment)}`);
+	}
+	console.log(`\n✓ Converted ${columns.length} column(s) to uuid.\n`);
+}
+function uniqueBridgeIndexes(bridges) {
+	return [...new Map(bridges.flatMap((bridge) => bridge.indexDefinitions.map((index) => [index.oid, {
+		index,
+		table: bridge.table
+	}]))).values()];
+}
+async function assertSupportedSourceColumns(db, columns) {
+	for (const column of columns) {
+		const { rows: shape } = await db.query(`SELECT relispartition AS partitioned,
+              EXISTS (SELECT 1 FROM pg_inherits i WHERE i.inhrelid = c.oid OR i.inhparent = c.oid) AS inherited
+         FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = 'public' AND c.relname = ${quoteLiteral(column.table)} AND c.relkind = 'r'`);
+		if (shape.length !== 1 || shape[0].partitioned || shape[0].inherited) throw new Error(`Unsupported table shape for ${column.table}.${column.column}; UUID conversion supports only non-partitioned, non-inherited public tables.`);
+		const { rows: views } = await db.query(`SELECT dependent.relname AS name
+         FROM pg_depend dep
+         JOIN pg_rewrite rule ON rule.oid = dep.objid
+         JOIN pg_class dependent ON dependent.oid = rule.ev_class
+         JOIN pg_class source ON source.oid = dep.refobjid
+         JOIN pg_namespace source_ns ON source_ns.oid = source.relnamespace
+         JOIN pg_attribute source_attr ON source_attr.attrelid = source.oid AND source_attr.attnum = dep.refobjsubid
+        WHERE dep.classid = 'pg_rewrite'::regclass AND source_ns.nspname = 'public'
+          AND source.relname = ${quoteLiteral(column.table)} AND source_attr.attname = ${quoteLiteral(column.column)}`);
+		if (views.length > 0) throw new Error(`Unsupported view or rule dependency on ${column.table}.${column.column}: ${views.map((view) => String(view.name)).join(", ")}. Remove or migrate it separately before db:migrate-uuid.`);
+	}
+}
+function renderUuidConversionSql(columns, bridges, foreignKeys) {
+	for (const foreignKey of foreignKeys) console.log(`  ALTER TABLE ${pgTable(foreignKey.table)} DROP CONSTRAINT ${quoteIdentifier(foreignKey.name)};`);
+	for (const bridge of bridges) console.log(`  ALTER TABLE ${pgTable(bridge.table)} DROP COLUMN ${quoteIdentifier(bridge.column)};`);
+	for (const column of columns) {
+		const table = pgTable(column.table);
+		const name = quoteIdentifier(column.column);
+		if (column.defaultExpression) console.log(`  ALTER TABLE ${table} ALTER COLUMN ${name} DROP DEFAULT;`);
+		console.log(`  ALTER TABLE ${table} ALTER COLUMN ${name} TYPE uuid USING NULLIF(btrim(${name}), '')::uuid;`);
+		if (column.defaultExpression) console.log(`  ALTER TABLE ${table} ALTER COLUMN ${name} SET DEFAULT (${column.defaultExpression})::uuid;`);
+	}
+	for (const bridge of bridges) {
+		console.log(`  ALTER TABLE ${pgTable(bridge.table)} ADD COLUMN ${quoteIdentifier(bridge.column)} text GENERATED ALWAYS AS (${quoteIdentifier(bridge.sourceColumn)}::text) STORED;`);
+		if (bridge.statisticsTarget != null && bridge.statisticsTarget !== -1) console.log(`  ALTER TABLE ${pgTable(bridge.table)} ALTER COLUMN ${quoteIdentifier(bridge.column)} SET STATISTICS ${bridge.statisticsTarget};`);
+		if (bridge.compression) console.log(`  ALTER TABLE ${pgTable(bridge.table)} ALTER COLUMN ${quoteIdentifier(bridge.column)} SET COMPRESSION ${bridge.compression === "l" ? "lz4" : "pglz"};`);
+	}
+	for (const { index, table } of uniqueBridgeIndexes(bridges)) {
+		console.log(`  ${index.definition};`);
+		if (index.comment) console.log(`  COMMENT ON INDEX ${quoteIdentifier(index.schema)}.${quoteIdentifier(index.name)} IS ${quoteLiteral(index.comment)};`);
+		if (index.clustered) console.log(`  ALTER TABLE ${pgTable(table)} CLUSTER ON ${quoteIdentifier(index.name)};`);
+		if (index.replicaIdentity) console.log(`  ALTER TABLE ${pgTable(table)} REPLICA IDENTITY USING INDEX ${quoteIdentifier(index.name)};`);
+	}
+	for (const foreignKey of foreignKeys) {
+		console.log(`  ALTER TABLE ${pgTable(foreignKey.table)} ADD CONSTRAINT ${quoteIdentifier(foreignKey.name)} ${foreignKey.definition}${foreignKey.validated ? "" : " NOT VALID"};`);
+		if (foreignKey.comment) console.log(`  COMMENT ON CONSTRAINT ${quoteIdentifier(foreignKey.name)} ON ${pgTable(foreignKey.table)} IS ${quoteLiteral(foreignKey.comment)};`);
+	}
+}
+async function snapshotGeneratedBridges(db, columns) {
+	const requested = new Set(columns.map((column) => declaredUuidKey(column.table, column.column)));
+	const { rows } = await db.query(`SELECT generated.oid::text AS table_oid, generated_attr.attnum AS attribute_number,
+            def.oid::text AS attribute_default_oid,
+            generated.relname AS table_name, generated_attr.attname AS column_name,
+            pg_get_expr(def.adbin, def.adrelid) AS expression,
+            format_type(generated_attr.atttypid, generated_attr.atttypmod) AS type_name,
+            generated_attr.attnotnull AS not_null, generated_attr.attstorage AS storage,
+            generated_attr.attstattarget AS statistics_target,
+            generated_attr.attcompression AS compression,
+            generated_attr.attoptions AS options,
+            generated_attr.attacl IS NOT NULL AS has_acl,
+            generated_attr.attcollation <> (SELECT typcollation FROM pg_type WHERE oid = generated_attr.atttypid) AS nondefault_collation,
+            col_description(generated_attr.attrelid, generated_attr.attnum) AS column_comment,
+            generated.relispartition AS partitioned,
+            EXISTS (SELECT 1 FROM pg_inherits i WHERE i.inhrelid = generated.oid OR i.inhparent = generated.oid) AS inherited
+       FROM pg_attrdef def
+       JOIN pg_class generated ON generated.oid = def.adrelid
+       JOIN pg_namespace generated_ns ON generated_ns.oid = generated.relnamespace
+       JOIN pg_attribute generated_attr ON generated_attr.attrelid = generated.oid AND generated_attr.attnum = def.adnum
+      WHERE generated_ns.nspname = 'public'
+        AND generated.relkind = 'r' AND generated_attr.attgenerated = 's'`);
+	const bridges = [];
+	for (const row of rows) {
+		const bridgeTable = String(row.table_name);
+		const bridgeColumn = String(row.column_name);
+		const expression = String(row.expression).replaceAll(" ", "");
+		const sourceColumn = expression.match(/^\(?([a-zA-Z_][a-zA-Z0-9_$]*)\)?(?:::text)?$/)?.[1];
+		if (!sourceColumn) {
+			const sourceColumns = columns.filter((column) => column.table === bridgeTable);
+			if (sourceColumns.length > 0 && await generatedColumnDependsOn(db, String(row.attribute_default_oid), String(row.table_oid), sourceColumns.map((column) => column.attributeNumber))) throw new Error(`Unsupported generated dependency ${bridgeTable}.${bridgeColumn}; only a plain stored TEXT id::text bridge can coexist with a converted UUID column.`);
+			continue;
+		}
+		if (!requested.has(declaredUuidKey(bridgeTable, sourceColumn))) continue;
+		const table = bridgeTable;
+		if (bridgeTable !== table || String(row.type_name) !== "text" || row.not_null || String(row.storage) !== "x" || row.options != null || row.has_acl || row.nondefault_collation || row.column_comment != null || row.partitioned || row.inherited || ![
+			"id",
+			"(id)::text",
+			`${sourceColumn}::text`,
+			`(${sourceColumn})::text`
+		].includes(expression)) throw new Error(`Unsupported generated dependency ${bridgeTable}.${bridgeColumn}; only a plain stored TEXT ${sourceColumn}::text bridge without ACLs, comments, inheritance, partitioning, or extra attributes is supported.`);
+		const { rows: nonCanonical } = await db.query(`SELECT count(*)::text AS n FROM ${pgTable(table)}
+        WHERE ${quoteIdentifier(sourceColumn)} IS NOT NULL
+          AND ${quoteIdentifier(sourceColumn)} !~ '${CANONICAL_UUID_RE}'`);
+		if (Number(nonCanonical[0]?.n ?? 0) > 0) throw new Error(`Refusing ${table}.${sourceColumn}: its generated TEXT bridge requires canonical lower-case UUID text; normalize or remove non-canonical values before migration.`);
+		bridges.push({
+			tableOid: String(row.table_oid),
+			attributeNumber: Number(row.attribute_number),
+			attributeDefaultOid: String(row.attribute_default_oid),
+			statisticsTarget: row.statistics_target == null ? null : Number(row.statistics_target),
+			compression: String(row.compression),
+			table,
+			column: bridgeColumn,
+			sourceColumn,
+			indexDefinitions: await snapshotBridgeIndexes(db, table, bridgeColumn)
+		});
+	}
+	return bridges.sort((a, b) => `${a.table}.${a.column}`.localeCompare(`${b.table}.${b.column}`));
+}
+/** Whether a generated expression actually references a converted source attr. */
+async function generatedColumnDependsOn(db, attributeDefaultOid, tableOid, sourceAttributeNumbers) {
+	const { rows } = await db.query(`SELECT EXISTS (
+       SELECT 1 FROM pg_depend dep
+        WHERE dep.classid = 'pg_attrdef'::regclass
+          AND dep.objid = ${quoteLiteral(attributeDefaultOid)}::oid
+          AND dep.refclassid = 'pg_class'::regclass
+          AND dep.refobjid = ${quoteLiteral(tableOid)}::oid
+          AND dep.refobjsubid IN (${sourceAttributeNumbers.join(", ")})
+     ) AS depends_on_converted_column`);
+	return Boolean(rows[0]?.depends_on_converted_column);
+}
+async function snapshotBridgeIndexes(db, table, column) {
+	const { rows } = await db.query(`SELECT index_rel.oid::text AS oid, index_ns.nspname AS index_schema,
+            index_rel.relname AS index_name, pg_get_indexdef(index_rel.oid) AS definition,
+            obj_description(index_rel.oid, 'pg_class') AS comment,
+            idx.indnkeyatts AS key_count, idx.indpred IS NOT NULL AS partial,
+            idx.indexprs IS NOT NULL AS expression_index, idx.indisvalid AS valid,
+            idx.indisready AS ready, idx.indisclustered AS clustered,
+            idx.indisreplident AS replica_identity,
+            index_rel.reltablespace <> 0 AS nondefault_tablespace,
+            am.amname AS method
+       FROM pg_index idx
+       JOIN pg_class table_rel ON table_rel.oid = idx.indrelid
+       JOIN pg_namespace ns ON ns.oid = table_rel.relnamespace
+       JOIN pg_class index_rel ON index_rel.oid = idx.indexrelid
+       JOIN pg_namespace index_ns ON index_ns.oid = index_rel.relnamespace
+       JOIN pg_am am ON am.oid = index_rel.relam
+       JOIN pg_attribute attr ON attr.attrelid = table_rel.oid AND attr.attnum = ANY(idx.indkey)
+      WHERE ns.nspname = 'public' AND table_rel.relname = ${quoteLiteral(table)}
+        AND attr.attname = ${quoteLiteral(column)}
+       ORDER BY index_ns.nspname, index_rel.relname, index_rel.oid`);
+	return rows.map((row) => {
+		if (Number(row.key_count) !== 1 || row.partial || row.expression_index || !row.valid || !row.ready || row.nondefault_tablespace || row.method !== "btree") throw new Error(`Unsupported index depending on generated bridge ${table}.${column}; only one-key valid btree indexes without a custom tablespace can be reconstructed safely.`);
+		return {
+			oid: String(row.oid),
+			schema: String(row.index_schema),
+			name: String(row.index_name),
+			definition: String(row.definition),
+			comment: row.comment == null ? null : String(row.comment),
+			clustered: Boolean(row.clustered),
+			replicaIdentity: Boolean(row.replica_identity)
+		};
+	});
+}
+/**
+* Every unique or primary-key index that covers `attnum` as a key column
+* (single-key or composite; INCLUDE-only columns are excluded via
+* `indnkeyatts`), returned as one entry per covering index — the probed
+* column included in `keyColumns`, so callers can filter it out to get the
+* index's "other" key columns for a composite collision check.
+*
+* A key column that is itself an expression (not a plain column reference)
+* has no `pg_attribute` row and is silently dropped from `keyColumns` by the
+* inner join below — the resulting collision check under-specifies that
+* index's true key, which only widens (never narrows) what it flags, so it
+* cannot hide a real collision; documented as a known imprecision rather
+* than fully modeled here.
+*/
+async function findUniqueIndexKeyColumns(db, relationOid, attnum) {
+	const { rows } = await db.query(`SELECT to_json(array_agg(json_build_object(
+                'name', key_attr.attname,
+                'type', format_type(key_attr.atttypid, key_attr.atttypmod)
+              ) ORDER BY key_order.ord)) AS key_columns,
+              to_json(coalesce(
+                bool_or((to_jsonb(idx) ->> 'indnullsnotdistinct')::boolean),
+                false
+              )) AS nulls_not_distinct
+         FROM pg_index idx
+         CROSS JOIN LATERAL unnest((idx.indkey::int2[])[0:idx.indnkeyatts - 1]) WITH ORDINALITY AS key_order(attnum, ord)
+         JOIN pg_attribute key_attr
+           ON key_attr.attrelid = idx.indrelid AND key_attr.attnum = key_order.attnum
+        WHERE idx.indrelid = ${quoteLiteral(relationOid)}::oid AND idx.indisunique
+          AND ${attnum} = ANY((idx.indkey::int2[])[0:idx.indnkeyatts - 1])
+        GROUP BY idx.indexrelid`);
+	return rows.map((row) => ({
+		keyColumns: row.key_columns.map((col) => ({
+			name: String(col.name),
+			typeName: String(col.type)
+		})),
+		nullsNotDistinct: Boolean(row.nulls_not_distinct)
+	}));
+}
+/**
+* Discover every single-column foreign key with BOTH endpoints in the public
+* schema — the only schema `db:migrate-uuid` ever converts or recreates DDL
+* against (see `pgTable`). Both `child_ns` and `parent_ns` are filtered to
+* `public` so a same-named table or column living in another schema can
+* never be silently treated as a candidate's FK partner by `declaredUuidKey`,
+* which keys purely on `table|column` with no schema qualifier. A
+* cross-schema partner that actually matters to a converting column is
+* caught separately, and fails closed, by
+* `assertNoCrossSchemaForeignKeyPartners`.
+*/
+async function fetchSingleColumnForeignKeyEdges(db) {
+	const { rows } = await db.query(`SELECT con.conname AS name, child.relname AS child_table,
+            child_attr.attname AS child_column,
+            parent.relname AS parent_table, parent_attr.attname AS parent_column
+       FROM pg_constraint con
+       JOIN pg_class child ON child.oid = con.conrelid
+       JOIN pg_namespace child_ns ON child_ns.oid = child.relnamespace
+       JOIN pg_class parent ON parent.oid = con.confrelid
+       JOIN pg_namespace parent_ns ON parent_ns.oid = parent.relnamespace
+       JOIN pg_attribute child_attr ON child_attr.attrelid = child.oid AND child_attr.attnum = con.conkey[1]
+       JOIN pg_attribute parent_attr ON parent_attr.attrelid = parent.oid AND parent_attr.attnum = con.confkey[1]
+      WHERE con.contype = 'f' AND child_ns.nspname = 'public' AND parent_ns.nspname = 'public'
+        AND array_length(con.conkey, 1) = 1`);
+	return rows.map((row) => ({
+		name: String(row.name),
+		childTable: String(row.child_table),
+		childColumn: String(row.child_column),
+		parentTable: String(row.parent_table),
+		parentColumn: String(row.parent_column)
+	}));
+}
+/**
+* Fail closed when a (single- OR multi-column) foreign key has exactly one
+* endpoint in the public schema and at least one of the public-side key
+* columns is in `relevant` (a schema-declared-UUID column this run treats
+* as a real conversion candidate/participant).
+*
+* `db:migrate-uuid` never converts or recreates DDL outside `public` (see
+* `pgTable`), and `declaredUuidKey` keys purely on `table|column` with no
+* schema — so a same-named table/column pair living in another schema could
+* otherwise be silently mistaken for that candidate's real FK partner
+* (making `propagateBlockedForeignKeyPartners` or `snapshotForeignKeys`
+* reason about the wrong table), or a genuine cross-schema partner could go
+* entirely undiscovered because the edge queries only ever look at
+* public-to-public constraints. Both are correctness bugs, not merely
+* documentation gaps, so this check runs independently of `declaredUuidKey`
+* lookups and fails the whole run with a specific, actionable message
+* instead of silently mis-propagating or mis-recreating a constraint.
+*
+* Deliberately not restricted to single-column FKs: `snapshotForeignKeys`
+* only refuses an unsupported multi-column FK once it has already matched
+* an in-`public` participant via `converted`/`bridgeColumns`, which this
+* cross-schema check runs ahead of and independently from. A composite FK
+* whose public-side key touches a converting column, but whose other
+* endpoint lives outside `public`, must fail closed here at preflight —
+* before `--dry-run` reports a plan `apply` cannot actually execute — the
+* same as the single-column case.
+*/
+async function assertNoCrossSchemaForeignKeyPartners(db, relevant) {
+	const { rows } = await db.query(`SELECT con.conname AS name,
+            child_ns.nspname AS child_schema, child.relname AS child_table,
+            to_json(array_agg(child_attr.attname ORDER BY child_key.ord)) AS child_columns,
+            parent_ns.nspname AS parent_schema, parent.relname AS parent_table,
+            to_json(array_agg(parent_attr.attname ORDER BY child_key.ord)) AS parent_columns
+       FROM pg_constraint con
+       JOIN pg_class child ON child.oid = con.conrelid
+       JOIN pg_namespace child_ns ON child_ns.oid = child.relnamespace
+       JOIN pg_class parent ON parent.oid = con.confrelid
+       JOIN pg_namespace parent_ns ON parent_ns.oid = parent.relnamespace
+       JOIN unnest(con.conkey) WITH ORDINALITY child_key(attnum, ord) ON true
+       JOIN unnest(con.confkey) WITH ORDINALITY parent_key(attnum, ord) ON parent_key.ord = child_key.ord
+       JOIN pg_attribute child_attr ON child_attr.attrelid = child.oid AND child_attr.attnum = child_key.attnum
+       JOIN pg_attribute parent_attr ON parent_attr.attrelid = parent.oid AND parent_attr.attnum = parent_key.attnum
+      WHERE con.contype = 'f'
+        AND (child_ns.nspname = 'public') <> (parent_ns.nspname = 'public')
+      GROUP BY con.oid, con.conname, child_ns.nspname, child.relname,
+               parent_ns.nspname, parent.relname`);
+	for (const row of rows) {
+		const childSchema = String(row.child_schema);
+		const parentSchema = String(row.parent_schema);
+		const childTable = String(row.child_table);
+		const parentTable = String(row.parent_table);
+		const childColumns = row.child_columns;
+		const parentColumns = row.parent_columns;
+		const childOnPublic = childSchema === "public";
+		const publicTable = childOnPublic ? childTable : parentTable;
+		if (!(childOnPublic ? childColumns : parentColumns).some((column) => relevant.has(declaredUuidKey(publicTable, column)))) continue;
+		throw new Error(`Foreign key ${String(row.name)} crosses the public schema boundary (${childSchema}.${childTable}(${childColumns.join(", ")}) → ${parentSchema}.${parentTable}(${parentColumns.join(", ")})); db:migrate-uuid only ever converts or recreates constraints in the public schema.`);
+	}
+}
+async function snapshotForeignKeys(db, columns, bridges) {
+	const converted = new Set(columns.map((column) => declaredUuidKey(column.table, column.column)));
+	const bridgeColumns = new Set(bridges.map((bridge) => declaredUuidKey(bridge.table, bridge.column)));
+	await assertNoCrossSchemaForeignKeyPartners(db, /* @__PURE__ */ new Set([...converted, ...bridgeColumns]));
+	const { rows } = await db.query(`SELECT con.oid, child.relname AS child_table, con.conname AS name,
+            parent.relname AS parent_table, con.convalidated AS validated,
+            pg_get_constraintdef(con.oid) AS definition,
+            obj_description(con.oid, 'pg_constraint') AS comment,
+            EXISTS (
+              SELECT 1 FROM pg_trigger trigger
+               WHERE trigger.tgconstraint = con.oid
+                 AND trigger.tgenabled <> 'O'
+            ) AS nondefault_trigger_mode,
+            array_length(con.conkey, 1) AS child_keys,
+            array_length(con.confkey, 1) AS parent_keys,
+            child_attr.attname AS child_column, parent_attr.attname AS parent_column
+       FROM pg_constraint con
+       JOIN pg_class child ON child.oid = con.conrelid
+       JOIN pg_namespace child_ns ON child_ns.oid = child.relnamespace
+       JOIN pg_class parent ON parent.oid = con.confrelid
+       JOIN pg_namespace parent_ns ON parent_ns.oid = parent.relnamespace
+       JOIN unnest(con.conkey) WITH ORDINALITY child_key(attnum, ord) ON true
+       JOIN unnest(con.confkey) WITH ORDINALITY parent_key(attnum, ord) ON parent_key.ord = child_key.ord
+       JOIN pg_attribute child_attr ON child_attr.attrelid = child.oid AND child_attr.attnum = child_key.attnum
+       JOIN pg_attribute parent_attr ON parent_attr.attrelid = parent.oid AND parent_attr.attnum = parent_key.attnum
+      WHERE con.contype = 'f' AND child_ns.nspname = 'public' AND parent_ns.nspname = 'public'`);
+	const participating = [];
+	for (const row of rows) {
+		const child = declaredUuidKey(String(row.child_table), String(row.child_column));
+		const parent = declaredUuidKey(String(row.parent_table), String(row.parent_column));
+		if (!converted.has(child) && !converted.has(parent) && !bridgeColumns.has(child) && !bridgeColumns.has(parent)) continue;
+		if (Number(row.child_keys) !== 1 || Number(row.parent_keys) !== 1) throw new Error(`Unsupported multi-column foreign key ${String(row.name)} touches UUID migration component.`);
+		const bridgeEdge = bridgeColumns.has(child) || bridgeColumns.has(parent);
+		if (bridgeEdge && (converted.has(child) || converted.has(parent))) throw new Error(`Foreign key ${String(row.name)} mixes a UUID-converted endpoint with a retained TEXT generated bridge; refusing incompatible recreation.`);
+		if (!bridgeEdge && (!converted.has(child) || !converted.has(parent))) throw new Error(`Foreign key ${String(row.name)} crosses a UUID conversion component boundary (${child} → ${parent}); declare both endpoints UUID or migrate it separately.`);
+		if (row.nondefault_trigger_mode) throw new Error(`Unsupported foreign key ${String(row.name)} has nondefault PostgreSQL trigger enforcement; refusing to recreate it with weaker semantics.`);
+		participating.push({
+			oid: String(row.oid),
+			table: String(row.child_table),
+			name: String(row.name),
+			definition: String(row.definition),
+			validated: Boolean(row.validated),
+			comment: row.comment == null ? null : String(row.comment)
+		});
+	}
+	return participating.sort((a, b) => `${a.table}.${a.name}`.localeCompare(`${b.table}.${b.name}`));
+}
+/**
+* A bridge column is dropped and rebuilt. pg_depend is the authoritative
+* catalog for every object which would be removed with it, including objects
+* whose definition does not expose the column name (expression indexes,
+* predicates, and extended statistics). Keep only dependencies we snapshot
+* and recreate exactly; fail closed for every other catalog object.
+*/
+async function assertSupportedBridgeDependencies(db, bridges, foreignKeys) {
+	const foreignKeyOids = new Set(foreignKeys.map((foreignKey) => foreignKey.oid));
+	for (const bridge of bridges) {
+		const indexOids = new Set(bridge.indexDefinitions.map((index) => index.oid));
+		const { rows } = await db.query(`SELECT dep.classid::regclass::text AS class_name,
+              dep.objid::text AS object_oid,
+              dep.objsubid AS object_subid,
+              dep.deptype,
+              coalesce(obj_class.relname, con.conname, stat.stxname, '') AS object_name
+         FROM pg_depend dep
+         LEFT JOIN pg_class obj_class
+           ON dep.classid = 'pg_class'::regclass AND obj_class.oid = dep.objid
+         LEFT JOIN pg_constraint con
+           ON dep.classid = 'pg_constraint'::regclass AND con.oid = dep.objid
+         LEFT JOIN pg_statistic_ext stat
+           ON dep.classid = 'pg_statistic_ext'::regclass AND stat.oid = dep.objid
+        WHERE dep.refclassid = 'pg_class'::regclass
+          AND dep.refobjid = ${quoteLiteral(bridge.tableOid)}::oid
+          AND dep.refobjsubid = ${bridge.attributeNumber}`);
+		for (const row of rows) {
+			const className = String(row.class_name);
+			const objectOid = String(row.object_oid);
+			const knownAttributeDefinition = className === "pg_attrdef" && objectOid === bridge.attributeDefaultOid;
+			const knownIndex = className === "pg_class" && indexOids.has(objectOid);
+			const knownForeignKey = className === "pg_constraint" && foreignKeyOids.has(objectOid);
+			if (knownAttributeDefinition || knownIndex || knownForeignKey) continue;
+			const name = row.object_name ? ` ${String(row.object_name)}` : "";
+			throw new Error(`Unsupported catalog dependency on generated bridge ${bridge.table}.${bridge.column}:${name} (${className} OID ${objectOid}, dependency ${String(row.deptype)}). Remove or migrate it separately before db:migrate-uuid.`);
+		}
+	}
+}
 /**
 * Apply the R3 rename backfills: copy `old → new` where `new` is still empty,
 * then drop `old`. Idempotent (a missing source column is skipped).
@@ -6803,7 +7595,7 @@ async function applyRenameBackfills(db, isPostgres, renameSpecs, dryRun, { ownTr
 	if (useOwnTxn) await db.query("BEGIN");
 	try {
 		for (const spec of renameSpecs) {
-			const t = quoteIdentifier(spec.table);
+			const t = isPostgres ? pgTable(spec.table) : quoteIdentifier(spec.table);
 			const from = quoteIdentifier(spec.from);
 			const to = quoteIdentifier(spec.to);
 			if (!await columnExists(db, isPostgres, spec.table, spec.from)) {
@@ -7905,14 +8697,19 @@ async function readAgentSurfaceReport(cwd) {
 					name: String(playbook.key),
 					detail: `${playbook.steps.length} step(s) · ${playbook.planes.join("+")} · ${playbook.sourceFile}`
 				})),
-				notStatic: (surface?.diagnostics ?? []).map((diagnostic) => ({
-					sourceFile: diagnostic.line ? `${diagnostic.sourceFile}:${diagnostic.line}` : String(diagnostic.sourceFile),
-					message: String(diagnostic.message)
-				}))
+				notStatic: (surface?.diagnostics ?? []).filter((diagnostic) => diagnostic.code !== "tool-name-collision").map(describeAgentSurfaceDiagnostic),
+				toolNameCollisions: (surface?.diagnostics ?? []).filter((diagnostic) => diagnostic.code === "tool-name-collision").map(describeAgentSurfaceDiagnostic)
 			};
 		} catch {}
 	}
 }
+/** Where a diagnostic points, and what it says, in one printable pair. */
+function describeAgentSurfaceDiagnostic(diagnostic) {
+	return {
+		sourceFile: diagnostic.line ? `${diagnostic.sourceFile}:${diagnostic.line}` : String(diagnostic.sourceFile),
+		message: String(diagnostic.message)
+	};
+}
 /** Render the surface report as the lines `smrt doctor` prints. */
 function renderAgentSurfaceReport(report) {
 	if (!report) return ["  ⚠️  No knowledge artifact found — run a build to emit the agent surface"];
@@ -7928,6 +8725,10 @@ function renderAgentSurfaceReport(report) {
 		lines.push(`  ⚠️  Not statically emittable: ${report.notStatic.length}`);
 		for (const entry of report.notStatic) lines.push(`    - ${entry.sourceFile}: ${entry.message}`);
 	}
+	if (report.toolNameCollisions.length > 0) {
+		lines.push(`  ⚠️  Tool name also claimed: ${report.toolNameCollisions.length}`);
+		for (const entry of report.toolNameCollisions) lines.push(`    - ${entry.sourceFile}: ${entry.message}`);
+	}
 	return lines;
 }
 /**
@@ -9266,6 +10067,7 @@ export default testManifest;
 			if (agentSurfaceReport) {
 				check(`${agentSurfaceReport.modelTools.length + agentSurfaceReport.intents.length + agentSurfaceReport.playbooks.length} agent-addressable operation(s) reported`, true);
 				if (agentSurfaceReport.notStatic.length > 0) check("Agent-surface declarations are all static", false, void 0, `${agentSurfaceReport.notStatic.length} declaration(s) could not be read statically and were excluded — use useWebMcpTool for a computed tool set`);
+				if (agentSurfaceReport.toolNameCollisions.length > 0) check("Declared intents own their WebMCP tool names", false, void 0, `${agentSurfaceReport.toolNameCollisions.length} intent(s) derive a tool name a generated or fixed UI tool also claims — namespace the generated tools, reprefix the UI tools, or rename the intent; each message says the runtime condition it assumes`);
 			} else check("Agent surface reported", false, void 0, "No knowledge artifact — run a build first");
 			console.log();
 			console.log("🏃 Runtime\n");
@@ -9344,7 +10146,9 @@ export default testManifest;
 	"db:generate": dbGenerateCommand,
 	"db:migrate-uuid": dbMigrateUuidCommand,
 	"db:migrate-int8": dbMigrateInt8Command,
+	"db:migrate-agent-schedule-slugs": dbMigrateAgentScheduleSlugsCommand,
 	"db:drop-framework-base-tables": dbDropFrameworkBaseTablesCommand,
+	"db:orphans": dbOrphansCommand,
 	"db:prune": dbPruneCommand,
 	"db:permissions": dbPermissionsCommand,
 	"config:export": configExportCommand,