@happyvertical/smrt-cli 0.47.1 → 0.48.0

package/dist/{commands-BiXRxejk.js → commands-DEHkYYWF.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";
@@ -22,8 +22,10 @@ import https from "node:https";
 import { homedir, tmpdir } from "node:os";
 import { extract } from "tar";
 import { importWorkspaceModule } from "@happyvertical/smrt-core/utils/import-workspace-module";
+import { renderForeignKeyAddStatements } from "@happyvertical/smrt-core/schema";
 import { FRAMEWORK_BASE_TABLE_NAMES, buildIntegerWidthTableStatements, collectIntegerWidthTargets, dropFrameworkBaseTables, parsePostgresTimeoutMs, planFrameworkBaseTableDrop, preflightIntegerWidthWidening, widenIntegerColumnsToBigInt } from "@happyvertical/smrt-core/migrations";
 import { buildArchitectureContext, buildKnowledgeIndex, buildReviewContext, checkKnowledgeFreshness, compactContextResult, diffKnowledgeIndex, renderFreshnessResult, renderKnowledgeIndexMarkdown } from "@happyvertical/smrt-dev-mcp/knowledge";
+import { RUNTIME_TOOLS } from "@happyvertical/smrt-dev-mcp/runtime";
 //#region src/commands/db-command-utils.ts
 var SENSITIVE_QUERY_PARAMS = /* @__PURE__ */ new Set([
 	"access_token",
@@ -623,6 +625,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,
@@ -732,7 +735,11 @@ function partitionSchemaChanges(changes, getClassForTable) {
 					className,
 					sql: change.sql,
 					...change.sqlStatements ? { sqlStatements: change.sqlStatements } : {},
-					advisory: change.advisory
+					advisory: change.advisory,
+					...change.foreignKey ? { foreignKey: change.foreignKey } : {},
+					...change.orphanBlocked !== void 0 ? { orphanBlocked: change.orphanBlocked } : {},
+					...change.orphanNullable !== void 0 ? { orphanNullable: change.orphanNullable } : {},
+					...change.engineUnsupported !== void 0 ? { engineUnsupported: change.engineUnsupported } : {}
 				};
 				if (isAdvisoryOnlyChangeLike(change)) manualInterventions.push(action);
 				else migrations.push(action);
@@ -856,9 +863,274 @@ 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})` : ""}`;
 	}
 }
+/** `table.column` identity used to key a blocked column across actions. */
+function blockedColumnKey(tableName, columnName) {
+	return `${tableName}.${columnName}`;
+}
+/**
+* Column that a manual-intervention action blocks, if any. `type_mismatch`,
+* a manual `type_upgrade`, and a manual `alter_column` each name exactly one
+* live column via `mismatch.column`; a blocked `add_foreign_key` names its
+* child column via `foreignKey.column` — unless the block reason is
+* `engineUnsupported` (this engine cannot express `ALTER TABLE ADD
+* CONSTRAINT` at all, e.g. SQLite/DuckDB): that says nothing about the
+* column's own state, no rerun on this engine ever resolves it, and
+* treating it as a blocked column would withhold unrelated dependent DDL
+* on that column permanently (review finding, #2748). That case blocks no
+* column identity and is excluded from dependency analysis.
+*/
+function blockedColumnForAction(action) {
+	if (action.type === "add_foreign_key" && action.foreignKey && !action.engineUnsupported) return blockedColumnKey(action.tableName, action.foreignKey.column);
+	const column = action.mismatch?.column ?? action.columnName ?? action.column?.name;
+	return column ? blockedColumnKey(action.tableName, column) : void 0;
+}
+/**
+* Every column a manual intervention blocks, keyed `table.column`, with the
+* human-readable reason (the action's advisory message, or a description of
+* the type mismatch) a dependent change is withheld for. `advisories`
+* includes only report-only `type_upgrade` findings (the #2608 refused
+* uuid convergence) — that shape is a genuine, permanent column-state block
+* that names a column just as concretely as a manual intervention does, so
+* omitting it let `--apply-unblocked` apply an index/alter/drop against a
+* column whose type convergence is itself blocked (review finding, #2748).
+*
+* `alter_column` advisories are deliberately excluded even though the type
+* exists on `SchemaAdvisory`: an advisory-only `alter_column` is produced
+* only by an un-opted-into relaxation (`drop_default`/`drop_not_null` when
+* `--relax-columns` was not passed) — it says the live column is *stricter*
+* than the manifest, not that the column's state blocks anything, and it
+* reappears on every run regardless of `--apply-unblocked`. Treating it as
+* a blocked column reproduced the exact defect this function's
+* `engineUnsupported` exclusion fixed for `add_foreign_key`: permanently
+* withholding unrelated executable DDL on that column (review finding,
+* #2748, second pass). A genuinely blocked `alter_column` (e.g. NOT NULL
+* required with live NULLs and no default) carries executable-looking SQL
+* as a comment and already reaches `manualInterventions` instead, where it
+* is covered by the loop above via `columnName`.
+*/
+function computeBlockedColumns(manualInterventions, advisories = []) {
+	const blocked = /* @__PURE__ */ new Map();
+	for (const action of manualInterventions) {
+		const key = blockedColumnForAction(action);
+		if (!key || blocked.has(key)) continue;
+		blocked.set(key, describeBlockedReason(action));
+	}
+	for (const advisory of advisories) {
+		if (advisory.type !== "type_upgrade") continue;
+		const key = blockedColumnKey(advisory.tableName, advisory.name);
+		if (blocked.has(key)) continue;
+		blocked.set(key, advisory.advisory.message ?? `${advisory.type} requires manual intervention`);
+	}
+	return blocked;
+}
+function describeBlockedReason(action) {
+	if (action.advisory?.message) return action.advisory.message;
+	if (action.mismatch) return `expected ${action.mismatch.expected}, found ${action.mismatch.actual}`;
+	return `${action.type} requires manual intervention`;
+}
+/**
+* `table.column` keys whose only manual-intervention block is an
+* orphan-blocked `add_foreign_key` on that same (child) column — a
+* row-data condition (existing rows don't match a parent), not a
+* column-state one. An un-opted-into `--relax-columns` relaxation on that
+* column (`DROP NOT NULL`/`DROP DEFAULT`) is not unsafe against orphan
+* rows; it is in fact the exact remediation that makes a NOT-NULL-child
+* orphan block eventually resolvable by `--null-orphans` on a later run.
+* Gating that `alter_column` on the orphan block made `--apply-unblocked
+* --relax-columns` withhold it forever — the relaxation never applies, the
+* live column never becomes nullable, the orphan block never clears, in a
+* stable non-converging loop (review finding, #2748). Every other
+* dependent shape on that column (an index, an unrelated foreign key, a
+* `drop_column`) still correctly stays gated by the orphan block; this set
+* narrows the exclusion to `alter_column` alone at the call site.
+*/
+function computeOrphanOnlyBlockedColumns(manualInterventions) {
+	const orphanOnly = /* @__PURE__ */ new Set();
+	const otherwiseBlocked = /* @__PURE__ */ new Set();
+	for (const action of manualInterventions) {
+		const key = blockedColumnForAction(action);
+		if (!key) continue;
+		if (action.type === "add_foreign_key" && action.orphanBlocked) orphanOnly.add(key);
+		else otherwiseBlocked.add(key);
+	}
+	for (const key of otherwiseBlocked) orphanOnly.delete(key);
+	return orphanOnly;
+}
+/**
+* Column(s) an executable migration action reads or writes, for dependency
+* analysis against `computeBlockedColumns()`. An `add_index` depends on
+* every indexed column; an `add_foreign_key` depends on its own child
+* column AND the parent column it references (a parent whose type upgrade
+* is blocked is just as unsafe to reference); `alter_column`/`drop_column`
+* depend on the single column they touch. `add_column`/`type_upgrade`/
+* `drop_index` never depend on another column's state — they are either the
+* fix itself or fully self-contained.
+*/
+function actionColumnDependencies(action) {
+	switch (action.type) {
+		case "add_index": return (action.index?.columns ?? []).map((columnName) => ({
+			tableName: action.tableName,
+			columnName
+		}));
+		case "add_foreign_key":
+			if (!action.foreignKey) return [];
+			return [{
+				tableName: action.tableName,
+				columnName: action.foreignKey.column
+			}, {
+				tableName: action.foreignKey.referencesTable,
+				columnName: action.foreignKey.referencesColumn
+			}];
+		case "alter_column":
+		case "drop_column": {
+			const columnName = action.columnName ?? action.column?.name;
+			return columnName ? [{
+				tableName: action.tableName,
+				columnName
+			}] : [];
+		}
+		default: return [];
+	}
+}
+/**
+* Partition executable migrations (the differ's "safe DDL" bucket) into
+* those independent of every blocked column and those that depend on one
+* (#2748's dependency rule): an index or foreign key on a column whose type
+* upgrade is blocked, or a foreign key whose orphan rows block it, stays
+* withheld; everything else is applied. Pure and order-preserving so a
+* dry-run preview and a real apply partition identically.
+*
+* A `drop_index` carries no column list of its own (a DB-side index being
+* removed; see `MigrationAction.indexName`'s doc comment), so it is never
+* itself a dependency target — EXCEPT when it is the drop half of the
+* #1165 shape-drift recreate pair (`drop_index` then `add_index` for the
+* SAME name, in that order, in the same batch). Withholding the `add_index`
+* half alone while letting its paired `drop_index` proceed would remove the
+* existing index/uniqueness enforcement with no replacement — reachable and
+* unsafe (review, #2748) — so a `drop_index` withholds together with any
+* `add_index` of the same name that this partition withheld.
+*/
+function partitionUnblockedMigrations(migrations, blockedColumns, orphanOnlyBlockedColumns = /* @__PURE__ */ new Set()) {
+	const directDependency = (action) => {
+		const dependency = actionColumnDependencies(action).find((dep) => {
+			const key = blockedColumnKey(dep.tableName, dep.columnName);
+			if (!blockedColumns.has(key)) return false;
+			if (action.type === "alter_column" && orphanOnlyBlockedColumns.has(key)) return false;
+			return true;
+		});
+		if (!dependency) return void 0;
+		const dependsOn = blockedColumnKey(dependency.tableName, dependency.columnName);
+		return {
+			dependsOn,
+			reason: blockedColumns.get(dependsOn) ?? "depends on a blocked change"
+		};
+	};
+	const withheldAddIndexDependency = /* @__PURE__ */ new Map();
+	const direct = migrations.map((action) => {
+		const dependency = directDependency(action);
+		if (dependency && action.type === "add_index" && action.index?.name) withheldAddIndexDependency.set(action.index.name, dependency);
+		return {
+			action,
+			dependency
+		};
+	});
+	const applied = [];
+	const withheld = [];
+	for (const { action, dependency } of direct) {
+		if (dependency) {
+			withheld.push({
+				action,
+				...dependency
+			});
+			continue;
+		}
+		const paired = action.type === "drop_index" && action.indexName ? withheldAddIndexDependency.get(action.indexName) : void 0;
+		if (paired) {
+			withheld.push({
+				action,
+				dependsOn: paired.dependsOn,
+				reason: `paired with the withheld rebuild of index ${action.indexName} (${paired.reason})`
+			});
+			continue;
+		}
+		applied.push(action);
+	}
+	return {
+		applied,
+		withheld
+	};
+}
+/**
+* Drop any pending post-apply report entry whose `action` reference was
+* withheld by `partitionUnblockedMigrations()` (review finding, #2748): a
+* `--null-orphans` combined null+add-FK migration can itself depend on a
+* separately blocked *parent* column and get withheld under
+* `--apply-unblocked` even though it already resolved out of
+* `manualInterventions`. Without this filter, the post-apply report printed
+* a `✓ ... resolved` line for a disposition that never executed — the same
+* relationship the `🔒 Withheld` listing (from `withheld`) already names.
+* Matches by object identity, not by table/column, since the caller pushed
+* the exact `MigrationAction` reference into both `migrations` and the
+* pending entry.
+*/
+function filterUnresolvedOrphanDispositions(pending, withheld) {
+	if (withheld.length === 0) return [...pending];
+	const withheldActions = new Set(withheld.map((item) => item.action));
+	return pending.filter((item) => !withheldActions.has(item.action));
+}
+/**
+* Split `manualInterventions` into orphan-blocked `add_foreign_key` actions
+* whose child column is nullable (an opt-in `--null-orphans` disposition can
+* null the references and proceed) and every other manual intervention,
+* including orphan-blocked FKs on a NOT NULL child column, which keep the
+* existing "Manual repair required" refusal (#2748) unconditionally — a
+* caller must never delete rows to make room for one of these.
+*
+* Reuses the differ's own rendered `advisory.suggestedSql` (detector at
+* index 0, repair at index 1) rather than re-deriving the orphan probe's
+* uuid-cast options, so the disposition always runs exactly the SQL the
+* differ already decided on.
+*/
+function planOrphanDispositions(manualInterventions) {
+	const nullable = [];
+	const notNullable = [];
+	for (const action of manualInterventions) {
+		if (action.type !== "add_foreign_key" || !action.orphanBlocked) continue;
+		if (!action.orphanNullable) {
+			notNullable.push(action);
+			continue;
+		}
+		const [detectorSql, repairSql] = action.advisory?.suggestedSql ?? [];
+		if (!action.foreignKey || !detectorSql || !repairSql) {
+			notNullable.push(action);
+			continue;
+		}
+		nullable.push({
+			action,
+			tableName: action.tableName,
+			column: action.foreignKey.column,
+			detectorSql,
+			repairSql
+		});
+	}
+	return {
+		nullable,
+		notNullable
+	};
+}
+/**
+* Wrap an orphan-probe `SELECT` (the differ's `renderForeignKeyOrphanDetector`
+* output, a bare `SELECT ... orphan_key ...` with no `LIMIT`) as a
+* `COUNT(*)` so `--null-orphans` can report before/after counts without
+* re-deriving the probe's own uuid-cast options.
+*/
+function orphanCountSql(detectorSql) {
+	return `SELECT COUNT(*) AS orphan_count FROM (${detectorSql}) AS smrt_orphan_probe`;
+}
 //#endregion
 //#region src/commands/postgres-timestamp-migration.ts
 /**
@@ -1458,6 +1730,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 +2479,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 +2506,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 +2852,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 +2876,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 +3014,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 +3152,10 @@ var dbStatusCommand = {
 				failedMigrations: summarizeFailedMigrations(failed, null),
 				schemaContract,
 				parity: null,
-				parityError: null
+				parityError: null,
+				orphanedForeignKeys: [],
+				orphanProbeFailures: [],
+				orphansError: null
 			};
 			let diff = {
 				added_tables: [],
@@ -2741,8 +3163,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 +3187,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 +3257,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 +6971,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 +6986,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 +7019,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 +7044,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 +7139,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 +7331,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 +7390,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 +7574,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 +7635,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 +7784,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));
@@ -7489,6 +8177,95 @@ function renderContextMarkdown(result) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/commands/dev-runtime.ts
+/**
+* dev:runtime — client for the runtime dev-plane (#2782).
+*
+* With a running dev server that mounts the in-app plane (`--url` or
+* `SMRT_DEV_PLANE_URL`), the command calls the JSON route and prints the
+* envelope. Without one it falls back to the standalone Level 2 boot in this
+* process, so the same answer is available from a terminal either way.
+*/
+/** Parse repeatable `--arg key=value` flags; numbers/booleans are coerced. */
+function parseToolArgs(raw) {
+	const values = Array.isArray(raw) ? raw : raw ? [raw] : [];
+	const args = {};
+	for (const entry of values) {
+		const eq = entry.indexOf("=");
+		if (eq <= 0) continue;
+		const key = entry.slice(0, eq).trim();
+		const value = entry.slice(eq + 1).trim();
+		if (value === "true") args[key] = true;
+		else if (value === "false") args[key] = false;
+		else if (/^-?\d+(\.\d+)?$/.test(value)) args[key] = Number(value);
+		else if (value.includes(",")) args[key] = value.split(",").map((v) => v.trim());
+		else args[key] = value;
+	}
+	return args;
+}
+/** Call the in-app plane when a URL is configured; otherwise run locally. */
+async function runRuntimeTool(tool, args, options = {}) {
+	const url = options.url?.trim() || process.env.SMRT_DEV_PLANE_URL?.trim();
+	if (url) {
+		const token = options.token?.trim() || process.env.SMRT_DEV_MCP_TOKEN?.trim();
+		if (!token) throw new Error("A dev-plane URL is set but no token: pass --token or set SMRT_DEV_MCP_TOKEN");
+		const response = await (options.fetchImpl ?? fetch)(`${url.replace(/\/+$/, "")}/${tool}`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${token}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify(args)
+		});
+		if (!response.ok) throw new Error(`dev-plane responded ${response.status} for ${tool}`);
+		return {
+			source: "dev-plane",
+			result: await response.json()
+		};
+	}
+	const local = RUNTIME_TOOLS[tool];
+	if (!local) throw new Error(`Unknown runtime tool "${tool}"; known: ${Object.keys(RUNTIME_TOOLS).join(", ")}`);
+	return {
+		source: "local",
+		result: await local(args)
+	};
+}
+var devRuntimeCommands = { "dev:runtime": {
+	name: "dev:runtime",
+	description: "Call a runtime dev-plane tool (runtime-registry, runtime-object, runtime-schema-diff, migration-status, job-health, schedule-health, dispatch-health, recent-changes, registry-drift) against a running dev server or, without one, the local Level 2 boot",
+	args: ["tool"],
+	options: {
+		url: {
+			type: "string",
+			description: "Dev-plane base URL (e.g. http://127.0.0.1:5173/api/_dev); default SMRT_DEV_PLANE_URL"
+		},
+		token: {
+			type: "string",
+			description: "Bearer token; default SMRT_DEV_MCP_TOKEN"
+		},
+		arg: {
+			type: "string",
+			multiple: true,
+			description: "Tool argument as key=value (repeatable; a,b,c becomes an array)"
+		},
+		json: {
+			type: "boolean",
+			description: "Print the raw envelope as JSON (default)",
+			default: true
+		}
+	},
+	handler: async (args, options) => {
+		const tool = args[0];
+		if (!tool) throw new Error("dev:runtime requires a tool name");
+		const { source, result } = await runRuntimeTool(tool, parseToolArgs(options.arg), {
+			url: options.url,
+			token: options.token
+		});
+		console.error(`[smrt] dev:runtime ${tool} via ${source}`);
+		console.log(JSON.stringify(result, null, 2));
+	}
+} };
+//#endregion
 //#region src/runtime-check.ts
 var SYSTEM_FIELDS = /* @__PURE__ */ new Set([
 	"context",
@@ -8070,6 +8847,40 @@ function resolveDDLPreviewEngine(dbType) {
 	}
 }
 /**
+* Run an orphan-count `SELECT COUNT(*)` (from `orphanCountSql()`) and read
+* back the count. Adapters disagree on the query-result envelope (some
+* return `{ rows }`, some a bare array), so normalize both the same way the
+* rest of the migration path does.
+*
+* Deliberately NOT best-effort: `--null-orphans` fails closed (#2748 review)
+* — if the probe itself cannot run (bad SQL shape, a permissions error, an
+* adapter that doesn't support the query), that is exactly the "unexpected
+* shape" case the flag must report and withhold on, not silently treat as
+* "zero orphans" and proceed to mutate data anyway. Callers that want the
+* disposition to abort on a probe failure should let this throw and catch
+* it themselves; there is no built-in fallback to 0.
+*/
+async function countOrphanRows(db, countSql) {
+	const result = await db.query(countSql);
+	const raw = (Array.isArray(result) ? result : result?.rows ?? [])[0]?.orphan_count;
+	const count = Number(raw);
+	if (!Number.isFinite(count)) throw new Error(`orphan-count probe returned a non-numeric count: ${JSON.stringify(raw)}`);
+	return count;
+}
+/**
+* One-line identity for a migration action withheld under
+* `--apply-unblocked`, for the withheld-changes report (#2748).
+*/
+function describeWithheldMigrationAction(action) {
+	switch (action.type) {
+		case "add_index": return `${action.tableName}: index ${action.index?.name ?? "(unnamed)"}`;
+		case "add_foreign_key": return `${action.tableName}: foreign key on ${action.foreignKey?.column ?? "(unknown column)"}`;
+		case "alter_column": return `${action.tableName}.${action.columnName ?? action.column?.name ?? "(unknown column)"}: ${action.alteration ?? "alter_column"}`;
+		case "drop_column": return `${action.tableName}.${action.columnName ?? "(unknown column)"}: drop column`;
+		default: return `${action.tableName}: ${action.type}`;
+	}
+}
+/**
 * Run the framework's deferred system-table compatibility pass after
 * `db:migrate` has created the tables it reshapes (issue #2376).
 *
@@ -8932,6 +9743,16 @@ export default testManifest;
 				description: "Apply constraint relaxations the manifest implies: DROP NOT NULL / DROP DEFAULT on live columns stricter than the manifest, and DROP NOT NULL on orphan NOT NULL columns (PostgreSQL/DuckDB). Off by default; relaxations are always reported.",
 				default: false
 			},
+			"apply-unblocked": {
+				type: "boolean",
+				description: "Withhold only the executable changes that depend on a blocked item (an index or foreign key on a column whose type upgrade is blocked, a foreign key whose orphan rows block it), instead of the default of applying every executable change regardless of dependency. A withheld change is reported with the blocked column it depends on. Off by default: every executable change in the batch still applies even when other items need manual intervention -- this flag makes that dependency-unsafe subset stop applying, it does not add anything that was previously withheld.",
+				default: false
+			},
+			"null-orphans": {
+				type: "boolean",
+				description: "For a foreign key blocked only by orphan child rows: null the orphaned references when the child column is nullable, then add the foreign key. Refuses with the existing manual-repair message when the child column is NOT NULL. Never deletes rows. Off by default.",
+				default: false
+			},
 			verbose: {
 				type: "boolean",
 				description: "Show detailed output",
@@ -9093,6 +9914,57 @@ export default testManifest;
 				migrations.push(...partitionedChanges.migrations);
 				manualInterventions.push(...partitionedChanges.manualInterventions);
 				const advisories = partitionedChanges.advisories;
+				const pendingOrphanDispositions = [];
+				if (options["null-orphans"]) {
+					const { nullable: orphanDispositions } = planOrphanDispositions(manualInterventions);
+					if (orphanDispositions.length > 0) {
+						console.log(`🧹 Orphan-FK disposition (--null-orphans): ${orphanDispositions.length} relationship(s)\n`);
+						for (const item of orphanDispositions) {
+							const countSql = orphanCountSql(item.detectorSql);
+							let beforeCount;
+							try {
+								beforeCount = await countOrphanRows(db, countSql);
+							} catch (error) {
+								console.log(`   ✗ ${item.tableName}.${item.column}: orphan-count probe failed, withholding this disposition: ${error instanceof Error ? error.message : String(error)}`);
+								continue;
+							}
+							if (!item.action.foreignKey) continue;
+							if (isDryRun) {
+								console.log(`   ${item.tableName}.${item.column}: ${beforeCount} orphan reference(s)`);
+								console.log(`     ${item.repairSql};`);
+								console.log(`     → would null ${beforeCount} reference(s), then add the foreign key\n`);
+							}
+							const index = manualInterventions.indexOf(item.action);
+							if (index >= 0) manualInterventions.splice(index, 1);
+							const combinedAction = {
+								type: "add_foreign_key",
+								tableName: item.action.tableName,
+								className: item.action.className,
+								foreignKey: item.action.foreignKey,
+								sqlStatements: [item.repairSql, ...renderForeignKeyAddStatements(item.action.tableName, item.action.foreignKey)]
+							};
+							migrations.push(combinedAction);
+							if (!isDryRun) pendingOrphanDispositions.push({
+								tableName: item.tableName,
+								column: item.column,
+								countSql,
+								beforeCount,
+								action: combinedAction
+							});
+						}
+						console.log();
+					}
+				}
+				let withheldForDependency = [];
+				if (options["apply-unblocked"]) {
+					const partition = partitionUnblockedMigrations(migrations, computeBlockedColumns(manualInterventions, advisories), computeOrphanOnlyBlockedColumns(manualInterventions));
+					withheldForDependency = partition.withheld;
+					migrations.length = 0;
+					migrations.push(...partition.applied);
+					const stillPending = filterUnresolvedOrphanDispositions(pendingOrphanDispositions, withheldForDependency);
+					pendingOrphanDispositions.length = 0;
+					pendingOrphanDispositions.push(...stillPending);
+				}
 				const preForeignKeyMigrations = migrations.filter((migration) => migration.phase === "pre_foreign_key");
 				const remainingMigrations = migrations.filter((migration) => migration.phase !== "pre_foreign_key");
 				assertForceMigrationTargetsExist(forceSelection.forceMigrations, [
@@ -9122,12 +9994,17 @@ export default testManifest;
 					console.log();
 					console.log("   Manual migration required (backup, recreate, restore as needed).\n");
 				}
+				if (withheldForDependency.length > 0) {
+					console.log(`🔒 Withheld — depends on a blocked change (--apply-unblocked, ${withheldForDependency.length}):\n`);
+					for (const { action, dependsOn, reason } of withheldForDependency) console.log(`   ${describeWithheldMigrationAction(action)}: depends on ${dependsOn} (${reason})`);
+					console.log();
+				}
 				printSchemaAdvisories(advisories, {
 					orphanTables: diff.orphan_tables ?? [],
 					verbose: Boolean(options.verbose)
 				});
 				const tablesCreated = diff.added_tables.length > 0;
-				const schemaUpToDate = migrations.length === 0 && manualInterventions.length === 0 && !tablesCreated && systemTimestampPreview.length === 0;
+				const schemaUpToDate = migrations.length === 0 && manualInterventions.length === 0 && withheldForDependency.length === 0 && !tablesCreated && systemTimestampPreview.length === 0;
 				const upToDateMessage = advisories.some((a) => a.advisory.severity === "warning") ? "✅ No migrations needed - see the live schema findings above\n" : "✅ Database schema is up to date - no migrations needed\n";
 				if (isDryRun) {
 					if (schemaUpToDate && !repairData) {
@@ -9219,6 +10096,7 @@ export default testManifest;
 				let skippedCount = 0;
 				let errorCount = 0;
 				let stiErrorCount = 0;
+				let migrationResults = [];
 				const schemaChangeCount = diff.added_tables.length + migrations.length + deferredForeignKeyMigrations.length;
 				if (applySchemaMigrations && schemaChangeCount > 0) {
 					const migrationDefs = [];
@@ -9328,6 +10206,7 @@ export default testManifest;
 								console.log(`  ✓ ${logInfo?.successMessage ?? result.name} (${checksum})`);
 							}
 						});
+						migrationResults = results;
 						const failed = migrationResultFailure(results);
 						if (failed) throw migrationResultError(failed);
 						successCount += results.filter((result) => result.success && result.applied !== false && result.execution_time_ms !== 0).length;
@@ -9341,6 +10220,21 @@ export default testManifest;
 						console.error(deferredIndexMigrations > 0 ? "     Non-index changes in this batch were committed; concurrent index builds that did not finish are recorded failed and will be retried on the next db:migrate." : "     Rolled back all schema changes from this migration batch, including any successful steps shown above.");
 					}
 				}
+				const succeededMigrationNames = new Set(migrationResults.filter((result) => result.success).map((result) => result.name));
+				const resolvedDispositions = pendingOrphanDispositions.filter((pending) => {
+					const migrationName = getSyntheticMigrationNameForAction(pending.action);
+					return migrationName ? succeededMigrationNames.has(migrationName) : false;
+				});
+				if (resolvedDispositions.length > 0) {
+					if (errorCount > 0) console.log("   (some changes in this batch failed; only fully-applied --null-orphans dispositions are listed below)");
+					for (const pending of resolvedDispositions) try {
+						const afterCount = await countOrphanRows(db, pending.countSql);
+						console.log(`   ✓ ${pending.tableName}.${pending.column}: nulled ${Math.max(pending.beforeCount - afterCount, 0)} orphan reference(s) (${afterCount} remaining)`);
+					} catch (error) {
+						console.log(`   ✓ ${pending.tableName}.${pending.column}: orphan references nulled and foreign key added (post-apply count unavailable: ${error instanceof Error ? error.message : String(error)})`);
+					}
+					console.log();
+				}
 				if (schemaUpToDate && !repairData) console.log(upToDateMessage);
 				if (repairData) {
 					console.log("\n🔄 Repairing STI discriminators to qualified names...\n");
@@ -9431,7 +10325,7 @@ export default testManifest;
 					} else console.log("ℹ️  No schema migrations were applied (none matched expected types)\n");
 				}
 				if (shouldFailDbMigrate({
-					manualInterventionCount: manualInterventions.length,
+					manualInterventionCount: manualInterventions.length + withheldForDependency.length,
 					tableErrorCount,
 					migrationErrorCount: errorCount,
 					stiErrorCount,
@@ -9721,6 +10615,7 @@ export default testManifest;
 	},
 	"runtime:check": runtimeCheckCommand,
 	...devKnowledgeCommands,
+	...devRuntimeCommands,
 	"db:status": dbStatusCommand,
 	"db:history": dbHistoryCommand,
 	"db:diff": dbDiffCommand,
@@ -9730,6 +10625,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,