@happyvertical/smrt-cli 0.47.1 → 0.47.2

package/AGENTS.md

@@ -10,6 +10,7 @@ smrt doctor                  # Umbrella diagnostics; can verify a generation sna
 smrt doctor --db             # Add the live-schema parity section (see below)
 smrt db:status               # Pending schema changes + failed migration classification
 smrt db:status --parity      # Same, plus live-schema parity (see below)
+smrt db:orphans              # agents/db-orphans.md
 smrt db:migrate              # Apply migrations
 smrt db:migrate --postgres-safe # PostgreSQL concurrent-index mode (see below)
 smrt db:migrate --force-migration <exact-id> [--force-migration <exact-id>...] # Force exact generated migrations in one atomic batch
@@ -19,7 +20,7 @@ smrt db:drop-framework-base-tables # One-time drop of the five #2644-orphaned fr
 smrt db:drop-framework-base-tables --dry-run # Print the drop plan without executing
 smrt db:diff                 # Show schema differences without generating migration files
 smrt db:rollback             # Roll back migrations by executing their recorded DOWN
-smrt db:rollback --mark-only # Record-only flip; schema deliberately untouched
+smrt db:rollback --mark-only # Record-only flip; schema untouched
 smrt db:prune                # Prune framework system tables to their retention windows
 smrt db:prune --dry-run      # Same predicates, counted rather than deleted
 smrt docs:agents             # Generate .agents/smrt-framework.md

package/agents/db-orphans.md

@@ -0,0 +1,46 @@
+# `db:orphans` — per-foreign-key orphan count report (#2753)
+
+`db:migrate`'s orphan probe already gates `ADD CONSTRAINT` with a `LIMIT 1`
+existence check and prints a suggested repair (see the PostgreSQL section of
+`packages/cli/AGENTS.md`); it cannot say *how many* orphans exist or across
+which relationships. `db:orphans` runs core's `collectForeignKeyOrphanCounts()`,
+which probes every manifest-declared foreign key from
+`ObjectRegistry.getAllSchemasAsDefinitions()` as a `COUNT(*)` aggregate —
+reusing `renderForeignKeyOrphanDetector()`'s exact FROM/JOIN/WHERE predicate
+via its `countOnly` option, never a second hand-written copy — and reports
+child/parent table and column, the live orphan count, and whether the child
+column is `NOT NULL` (so the two dispositions the repair-SQL builder already
+distinguishes — manual repair vs. an executable null-out — are visible up
+front, without hand-writing the same SQL against the database). Results print
+sorted by count descending. A relationship whose child or parent table does
+not exist live is skipped and listed separately rather than failing the whole
+report.
+
+Strictly read-only and diagnostic: it never repairs anything, and the orphan
+counts themselves never affect the exit code — a database full of orphans
+still exits 0, matching the existing "no foreign-key orphan repair, by
+design" boundary. It exits non-zero only on a configuration or runtime error
+(no database configured, or the report itself could not run). `--json` emits
+the full report for scripting; `--verbose` also lists foreign keys with zero
+orphans.
+
+`ForeignKeyOrphanSkipped.kind` distinguishes a benign `missing_table` skip
+(a manifest table not yet migrated) from `probe_failed` (the `COUNT(*)`
+query itself errored — permissions, a malformed live column, a genuine SQL
+failure). `smrt db:orphans` marks a `probe_failed` skip `[PROBE FAILED]` in
+its Skipped section and never reports the "No orphan rows found" clean
+summary while any probe has failed, since an incomplete scan is not the same
+claim as a clean one.
+
+`db:status` runs the same probe unconditionally (not gated behind `--parity`,
+and independent of whether the configured adapter supports
+`getTableSchema` — the probe only needs `db.query()`) and, when any manifest
+foreign key has live orphans, prints one compact line per affected foreign
+key plus a pointer to `smrt db:orphans` for the full report. A `probe_failed`
+skip surfaces as its own distinct warning (`status.orphanProbeFailures`)
+rather than being read as "no orphans found"; `missing_table` skips stay
+silent in `db:status` (benign, and already visible in full via
+`smrt db:orphans`). Never a new `SchemaDiff` finding kind, and never
+touching `db:status`'s exit code. A total probe failure (the collector call
+itself throws, e.g. it cannot list live tables at all) is reported as
+"Foreign-key orphan check unavailable" rather than failing `db:status`.

package/dist/{commands-BiXRxejk.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) {
@@ -6525,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:
 *
@@ -6540,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.
@@ -6573,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.
@@ -6597,11 +6774,84 @@ 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
@@ -6619,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;
 		}
@@ -6809,17 +7061,48 @@ async function convertPostgresUuidColumns(db, declaredUuid, dryRun, renderDryRun
 		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
+			nonUuid,
+			duplicateNormalized
 		});
 		defaults.set(declaredUuidKey(table, column), row.column_default == null ? null : String(row.column_default));
 	}
@@ -6837,10 +7120,14 @@ async function convertPostgresUuidColumns(db, declaredUuid, dryRun, renderDryRun
           AND btrim(${quoteIdentifier(spec.from)}) !~* '${UUID_RE}'`);
 		destination.nonUuid += Number(rows[0]?.n ?? 0);
 	}
-	const { convert, skipDirtyData, skipNotDeclared } = planUuidConversions(liveColumns, declaredUuid);
-	console.log(`Found ${candidateRows.length} TEXT id/FK column(s): ${convert.length} convertible, ${skipDirtyData.length + skipNotDeclared.length} skipped.`);
-	for (const item of skipDirtyData) console.log(`  SKIP ${item.table}.${item.column}: ${item.nonUuid} non-uuid value(s)`);
+	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;
@@ -7017,7 +7304,7 @@ async function snapshotGeneratedBridges(db, columns) {
 		].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)} !~ '${UUID_RE}'`);
+          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),
@@ -7078,9 +7365,139 @@ async function snapshotBridgeIndexes(db, table, column) {
 		};
 	});
 }
+/**
+* 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,
@@ -7097,11 +7514,12 @@ async function snapshotForeignKeys(db, columns, bridges) {
        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'`);
+      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));
@@ -9730,6 +10148,7 @@ export default testManifest;
 	"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,

package/dist/index.js

@@ -49,63 +49,63 @@ var _playgroundCommands = null;
 var _workbenchCommands = null;
 async function getGnodeCommands() {
 	if (!_gnodeCommands) {
-		const { gnodeCommands } = await import("./commands-BiXRxejk.js");
+		const { gnodeCommands } = await import("./commands-uHfUPryV.js");
 		_gnodeCommands = gnodeCommands;
 	}
 	return _gnodeCommands;
 }
 async function getGitCommands() {
 	if (!_gitCommands) {
-		const { gitCommands } = await import("./commands-BiXRxejk.js");
+		const { gitCommands } = await import("./commands-uHfUPryV.js");
 		_gitCommands = gitCommands;
 	}
 	return _gitCommands;
 }
 async function getGenerateCommands() {
 	if (!_generateCommands) {
-		const { generateCommands } = await import("./commands-BiXRxejk.js");
+		const { generateCommands } = await import("./commands-uHfUPryV.js");
 		_generateCommands = generateCommands;
 	}
 	return _generateCommands;
 }
 async function getInitCommands() {
 	if (!_initCommands) {
-		const { initCommands } = await import("./commands-BiXRxejk.js");
+		const { initCommands } = await import("./commands-uHfUPryV.js");
 		_initCommands = initCommands;
 	}
 	return _initCommands;
 }
 async function getUtilityCommands() {
 	if (!_utilityCommands) {
-		const { utilityCommands } = await import("./commands-BiXRxejk.js");
+		const { utilityCommands } = await import("./commands-uHfUPryV.js");
 		_utilityCommands = utilityCommands;
 	}
 	return _utilityCommands;
 }
 async function getDispatchCommands() {
 	if (!_dispatchCommands) {
-		const { dispatchCommands } = await import("./commands-BiXRxejk.js");
+		const { dispatchCommands } = await import("./commands-uHfUPryV.js");
 		_dispatchCommands = dispatchCommands;
 	}
 	return _dispatchCommands;
 }
 async function getDocsCommands() {
 	if (!_docsCommands) {
-		const { docsCommands } = await import("./commands-BiXRxejk.js");
+		const { docsCommands } = await import("./commands-uHfUPryV.js");
 		_docsCommands = docsCommands;
 	}
 	return _docsCommands;
 }
 async function getPlaygroundCommands() {
 	if (!_playgroundCommands) {
-		const { playgroundCommands } = await import("./commands-BiXRxejk.js");
+		const { playgroundCommands } = await import("./commands-uHfUPryV.js");
 		_playgroundCommands = playgroundCommands;
 	}
 	return _playgroundCommands;
 }
 async function getWorkbenchCommands() {
 	if (!_workbenchCommands) {
-		const { workbenchCommands } = await import("./commands-BiXRxejk.js");
+		const { workbenchCommands } = await import("./commands-uHfUPryV.js");
 		_workbenchCommands = workbenchCommands;
 	}
 	return _workbenchCommands;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-cli",
-  "version": "0.47.1",
+  "version": "0.47.2",
   "description": "Developer CLI for SMRT framework - introspection, testing, and project management",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,8 @@
     "scripts",
     "README.md",
     "CLAUDE.md",
-    "AGENTS.md"
+    "AGENTS.md",
+    "agents"
   ],
   "exports": {
     ".": {
@@ -27,12 +28,12 @@
     "@happyvertical/ai": "^0.89.6",
     "@happyvertical/files": "^0.89.6",
     "@happyvertical/logger": "^0.89.6",
-    "@happyvertical/smrt-agents": "0.47.1",
-    "@happyvertical/smrt-config": "0.47.1",
-    "@happyvertical/smrt-core": "0.47.1",
-    "@happyvertical/smrt-dev-mcp": "0.47.1",
-    "@happyvertical/smrt-playground": "0.47.1",
-    "@happyvertical/smrt-types": "0.47.1",
+    "@happyvertical/smrt-agents": "0.47.2",
+    "@happyvertical/smrt-config": "0.47.2",
+    "@happyvertical/smrt-core": "0.47.2",
+    "@happyvertical/smrt-dev-mcp": "0.47.2",
+    "@happyvertical/smrt-playground": "0.47.2",
+    "@happyvertical/smrt-types": "0.47.2",
     "@happyvertical/sql": "^0.89.6",
     "@happyvertical/utils": "^0.89.6",
     "acorn": "^8.17.0",