@prisma/orm-toolchain 8.0.0-rc.1-dev.45 → 8.0.0-rc.10

package/dist/ref-DcqFmceq-QaUjgZeM.mjs

@@ -0,0 +1,4789 @@
+import { r as getEmittedArtifactPaths, t as emit } from "./exports-CE6OD63o-4Qpqr2W7.mjs";
+import { O as errorNoInvariantPath, P as errorUnknownInvariant, b as errorInvalidRefName, i as errorContractDeserializationFailed, t as MigrationToolsError } from "./errors-SoLLYLtw-DMxVbVs9.mjs";
+import { a as snapshotsImportPathFrom, o as writeContractSnapshot, r as readContractSnapshotJson, t as contractSnapshotDir } from "./contract-snapshot-store-qGrwlGmt-Cf2NFzRL.mjs";
+import { n as verifyMigrationHash, t as computeMigrationHash } from "./hash-DH8hl5Rq-BpM2t3Nu.mjs";
+import { t as deriveProvidedInvariants } from "./invariants-Cww4bv0v-BEiFxmbX.mjs";
+import { i as materialiseExtensionMigrationPackageIfMissing, r as formatMigrationDirName, u as writeMigrationPackage } from "./io-BmWQNxRP-DQqbcPsS.mjs";
+import { t as EMPTY_CONTRACT_HASH } from "./constants-CM-w38DQ-Cz_EXbOc.mjs";
+import { n as isGraphNode, t as assertHashIsGraphNode } from "./graph-membership-DY1Onbc3-CwBd6wuB.mjs";
+import { a as findPath, o as findPathWithDecision, r as findLatestMigration } from "./migration-graph-CW4bMmTz-B5xFtFVB.mjs";
+import { d as writeRef, i as readRefs, l as validateRefName, n as deleteRef, o as refsByContractHash, t as HEAD_REF_NAME, u as validateRefValue } from "./refs-BpSpzdYB-BcDelHGt.mjs";
+import { a as isValidSpaceId, c as spaceMigrationDirectory, l as spaceRefsDirectory, o as listContractSpaceDirectories, s as readContractSpaceHeadRef, t as APP_SPACE_ID$1 } from "./verify-contract-spaces-CrxvgpwD-D5LLXGci.mjs";
+import { d as resolveRecordedPath, f as verifyMigration, l as planMigration, n as buildFabricatedMigrationEdge, r as collectAggregateNamespaces, s as loadContractSpaceAggregate, t as allStorageElementsExternal, u as requireHeadRef } from "./aggregate-B4HKshLQ.mjs";
+import { i as emitContractSpaceArtifacts, o as planAllSpaces } from "./spaces-BCZiAZQn.mjs";
+import { c as internalImportRoot, o as importRootForDependencies, r as createImportSpecifierResolver } from "./import-roots-BHOrDJbI.mjs";
+import { n as parseContractRef, r as parseMigrationRef } from "./ref-resolution-BWpwb8_b.mjs";
+import { i as writeMigrationTs } from "./migration-ts-DdVm0rws.mjs";
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { ifDefined } from "@prisma/orm-framework/utils/defined";
+import { structuredError } from "@prisma/orm-framework/utils/structured-error";
+import { blindCast, castAs } from "@prisma/orm-framework/utils/casts";
+import { InternalError } from "@prisma/orm-framework/utils/internal-error";
+import { CliStructuredError, CliStructuredError as CliStructuredError$1, errorConfigValidation as errorConfigValidation$1, errorContractConfigMissing, errorContractValidationFailed, errorDatabaseConnectionRequired, errorDriverRequired, errorFileNotFound, errorMigrationPlanningFailed, errorTargetMigrationNotSupported, errorUnexpected } from "@prisma/orm-framework/errors/control";
+import { APP_SPACE_ID, createControlStack, hasMigrations, hasOperationPreview, hasPslContractInfer, hasSchemaSubjectClassifier, hasSchemaView } from "@prisma/orm-framework/components/control";
+import { notOk, ok } from "@prisma/orm-framework/utils/result";
+import { mergeCapabilityMatrices } from "@prisma/orm-framework/components/components";
+import { errorConsentPlanMismatch, errorDestructiveChanges, errorHashMismatch, errorMarkerMissing, errorRunnerFailed, errorRuntime, errorTargetMismatch } from "@prisma/orm-framework/errors/execution";
+import "@prisma/orm-framework/errors/migration";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "pathe";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { canonicalizeJson } from "@prisma/orm-framework/components/utils";
+import { abortable } from "@prisma/orm-framework/utils/abortable";
+import { resolve as resolve$1 } from "node:path";
+//#region ../../../1-framework/3-tooling/cli/dist/ref-DcqFmceq.mjs
+/**
+* The typed remediation the CLI attaches to its own errors and findings.
+* Constructors live here rather than in any library the CLI calls: naming a
+* runnable invocation is something only the CLI can do.
+*/
+function runCommandAction(label, command) {
+	return {
+		kind: "run-command",
+		label,
+		command
+	};
+}
+/** Advice the user acts on themselves — there is no command to run. */
+function chooseAction(label) {
+	return {
+		kind: "user-choice",
+		label
+	};
+}
+/**
+* A CLI-raised error that carries the typed remediation as well as the prose.
+* Only the CLI knows which invocation fixes a failure, so only errors raised
+* here spell one; the foundation classes every library also raises keep
+* carrying `code`, `why` and `fix` alone.
+*
+* Both fields are required: the `fix` prose is what the commander shell still
+* renders, and the handler boundary drops it in favour of `nextActions` when it
+* settles the engine's envelope.
+*/
+var ActionableCliError = class extends CliStructuredError$1 {
+	nextActions;
+	constructor(code, summary, options) {
+		super(code, summary, options);
+		this.nextActions = options.nextActions;
+	}
+};
+/**
+* A command that accepts a contract reference both as a positional and as a
+* flag was given both. Structured rather than a bare stderr line, so a script
+* sees the same envelope every other invocation failure produces.
+*/
+function errorContractArgConflict(options) {
+	const fix = "Pass the contract reference once — either as the positional argument or as --contract.";
+	return new ActionableCliError("CLI.CONTRACT_ARG_CONFLICT", "Cannot specify both a positional contract argument and --contract", {
+		why: `The positional argument names "${options.positional}" and --contract names "${options.flag}"; there is no rule for which wins.`,
+		fix,
+		nextActions: [chooseAction(fix)],
+		meta: {
+			positional: options.positional,
+			flag: options.flag
+		}
+	});
+}
+/**
+* A command was told both which ref to advance and not to advance any ref.
+* Same envelope as the positional/flag contract conflict, so a script sees
+* every invocation conflict in one shape.
+*/
+function errorAdvanceRefArgConflict(options) {
+	const fix = "Pass either --advance-ref <name> or --no-advance-ref, not both.";
+	return new ActionableCliError("CLI.ADVANCE_REF_ARG_CONFLICT", "Cannot specify both --advance-ref and --no-advance-ref", {
+		why: `--advance-ref names "${options.advanceRef}" while --no-advance-ref asks for no ref to be written; there is no rule for which wins.`,
+		fix,
+		nextActions: [chooseAction(fix)],
+		meta: { advanceRef: options.advanceRef }
+	});
+}
+function errorRefSetHashNotInGraph(resolvedHash, reachableHashes, graphTipHash) {
+	const reachableList = reachableHashes.length > 0 ? reachableHashes.join(", ") : "(none — migration graph is empty)";
+	const fix = reachableHashes.length > 0 ? graphTipHash !== null ? `Set the ref to a graph-node hash such as ${graphTipHash}, or run \`{bin} migration plan\` to extend the graph.` : "Set the ref to a hash that appears in the migration graph." : "Run `{bin} migration plan` first.";
+	const nextActions = reachableHashes.length > 0 ? graphTipHash !== null ? [chooseAction(`Set the ref to a graph-node hash such as ${graphTipHash}`), runCommandAction("Extend the migration graph", "{bin} migration plan")] : [chooseAction("Set the ref to a hash that appears in the migration graph")] : [runCommandAction("Plan the first migration", "{bin} migration plan")];
+	return new ActionableCliError("MIGRATION.HASH_NOT_IN_GRAPH", `Resolved contract hash is not in the migration graph: ${resolvedHash}`, {
+		why: reachableHashes.length > 0 ? `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.` : "The migration graph is empty — no hashes reachable.",
+		fix,
+		nextActions,
+		meta: {
+			resolvedHash,
+			reachableHashes: [...reachableHashes],
+			...graphTipHash !== null ? { graphTipHash } : {}
+		}
+	});
+}
+function errorRefSetEmptySentinel(hash) {
+	return new ActionableCliError("MIGRATION.REF_SET_EMPTY_SENTINEL", `Cannot set ref to the empty-database sentinel: ${hash}`, {
+		why: "The empty-database sentinel is a planner internal; it is not a valid ref target.",
+		fix: "Set the ref to a contract hash from the migration graph, or use another ref name.",
+		nextActions: [chooseAction("Set the ref to a contract hash from the migration graph"), chooseAction("Or use another ref name")],
+		meta: { hash }
+	});
+}
+/**
+* `--legend` was combined with a machine-readable or silent output flag.
+* The legend is human-only decoration on stderr.
+*/
+function errorLegendHumanOnly(conflictingFlag) {
+	return new ActionableCliError("MIGRATION.LEGEND_HUMAN_ONLY", "`--legend` is only available for human-readable output", {
+		why: `\`--legend\` prints a glyph key to stderr and cannot be combined with ${conflictingFlag}.`,
+		fix: `Omit ${conflictingFlag} to print the legend alongside the tree, or omit --legend when using ${conflictingFlag}.`,
+		nextActions: [chooseAction(`Omit ${conflictingFlag} to print the legend alongside the tree`), chooseAction(`Or omit --legend when using ${conflictingFlag}`)],
+		meta: { conflictingFlag }
+	});
+}
+/**
+* `--space <id>` was given a value that doesn't satisfy the contract-space
+* naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before
+* any fs work — the input is syntactically rejected the same way an on-disk
+* directory with that name would be skipped by the enumerator.
+*/
+function errorInvalidSpaceId(spaceId) {
+	return new ActionableCliError("MIGRATION.INVALID_SPACE_ID", `Invalid contract space id: ${spaceId}`, {
+		why: "Contract space ids must match [a-z][a-z0-9_-]{0,63} (lowercase, starts with a letter, max 64 characters — the rule applied to every on-disk space directory).",
+		fix: "Pass a space id that matches the directory naming rule, or omit --space to list every space.",
+		nextActions: [chooseAction("Pass a space id matching [a-z][a-z0-9_-]{0,63}"), runCommandAction("Or list every space", "{bin} migration list")],
+		meta: { spaceId }
+	});
+}
+/**
+* `migration list --space <id>` was given a contract-space id that has no
+* directory under `migrations/`. Distinct from "the space exists but is
+* empty" — that path renders the empty-state line and exits 0 per the
+* slice spec § Empty-state. This error fires only when `<projectMigrationsDir>/<spaceId>`
+* does not exist on disk.
+*
+* `availableSpaces` lists the contract-space directory names actually
+* present, sorted lex-asc, so the diagnostic can suggest a near match
+* without making the user reach for `ls`.
+*/
+function errorSpaceNotFound(spaceId, availableSpaces) {
+	const availableList = availableSpaces.length > 0 ? availableSpaces.join(", ") : "(none — no contract spaces on disk yet)";
+	const fix = availableSpaces.length > 0 ? `Pick one of: ${availableList}. Run \`{bin} migration list\` (no --space) to see every space's migrations.` : "Author a migration with `{bin} migration new` to create the first contract-space directory.";
+	const nextActions = availableSpaces.length > 0 ? [chooseAction(`Pick one of: ${availableList}`), runCommandAction("See every space's migrations", "{bin} migration list")] : [runCommandAction("Author the first migration, which creates the contract-space directory", "{bin} migration new")];
+	return new ActionableCliError("MIGRATION.SPACE_NOT_FOUND", `Unknown contract space: ${spaceId}`, {
+		why: `No directory named "${spaceId}" exists under the migrations root.`,
+		fix,
+		nextActions,
+		meta: {
+			spaceId,
+			availableSpaces: [...availableSpaces]
+		}
+	});
+}
+/**
+* A `migration show` target resolved to a directory or a graph node, but no
+* on-disk package was loaded for it.
+*/
+function errorMigrationPackageNotFound(why) {
+	return new ActionableCliError("MIGRATION.PACKAGE_NOT_FOUND", "Migration package not found", {
+		why,
+		fix: "Pass a directory name, hash prefix, or path to an on-disk app-space migration package.",
+		nextActions: [chooseAction("Pass a directory name, hash prefix, or path to an on-disk app-space migration package"), runCommandAction("List what is on disk", "{bin} migration list")]
+	});
+}
+/** The app space has no migration packages at all, so no target can resolve. */
+function errorNoMigrations(appMigrationsRelative) {
+	return new ActionableCliError("MIGRATION.NO_MIGRATIONS", "No migrations found", {
+		why: `No migration packages found in ${appMigrationsRelative}`,
+		fix: "Run `{bin} migration plan` to create a migration first.",
+		nextActions: [runCommandAction("Create the first migration", "{bin} migration plan")]
+	});
+}
+function errorRefSetBundleNotFound(hash) {
+	return new ActionableCliError("MIGRATION.REF_SET_BUNDLE_NOT_FOUND", `No migration bundle matches graph-node hash ${hash}`, {
+		why: `The hash is a graph node but no on-disk bundle has metadata.to = ${hash}.`,
+		fix: "Run `pnpm fixtures:check`, or re-emit the migration that produces this hash so its bundle is restored.",
+		nextActions: [runCommandAction("Restore the checked-in fixtures", "pnpm fixtures:check"), chooseAction("Or re-emit the migration that produces this hash")],
+		meta: { hash }
+	});
+}
+function errorPlanForgotTheFlag(resolvedHash, reachableRefs, graphTipHash, options) {
+	const reachableList = reachableRefs.length > 0 ? reachableRefs.map((r) => `${r.name} (${r.hash})`).join(", ") : "(none)";
+	const refFix = reachableRefs.length > 0 ? `Run migration plan with ${reachableRefs.map((r) => `--from ${r.name}`).join(" or ")}.` : graphTipHash !== null ? `Run migration plan --from ${graphTipHash}.` : "Commit pending migrations first, then run migration plan.";
+	const nextActions = reachableRefs.length > 0 ? reachableRefs.map((ref) => runCommandAction(`Plan from ${ref.name}`, `{bin} migration plan --from ${ref.name}`)) : graphTipHash !== null ? [runCommandAction("Plan from the graph tip", `{bin} migration plan --from ${graphTipHash}`)] : [chooseAction("Commit pending migrations first, then run migration plan")];
+	return new ActionableCliError("MIGRATION.HASH_NOT_IN_GRAPH", `Resolved from-hash is not in the migration graph: ${resolvedHash}`, {
+		why: `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`,
+		fix: refFix,
+		nextActions,
+		meta: {
+			resolvedHash,
+			reachableRefs: reachableRefs.map((r) => r.name),
+			...graphTipHash !== null ? { graphTipHash } : {}
+		},
+		...ifDefined("cause", options?.cause)
+	});
+}
+/**
+* `viaRef: true` (the default) mirrors migration-tools' `errorRefNotResolvable`:
+* a ref name with no pointer file, where the fallback hash isn't a graph
+* node either — there's nothing to materialize a contract from.
+* `viaRef: false` is a distinct, ref-independent case: an explicit `--from
+* <hash>` that doesn't name a ref, on an empty migration graph, so there is
+* no graph node and no ref to resolve a contract through.
+*/
+function errorSnapshotMissing(identifier, options) {
+	const viaRef = options?.viaRef !== false;
+	const fix = viaRef ? `Create the ref with "{bin} migration ref set ${identifier} <hash>" (or advance it via "{bin} db update --advance-ref ${identifier}"), or pass a hash that is a node in the migration graph.` : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name (its contract resolves through the snapshot store), or run db update first.`;
+	const nextActions = viaRef ? [
+		runCommandAction(`Create the ref "${identifier}"`, `{bin} migration ref set ${identifier} <hash>`),
+		runCommandAction("Or advance it from the database", `{bin} db update --advance-ref ${identifier}`),
+		chooseAction("Or pass a hash that is a node in the migration graph")
+	] : [chooseAction("Pass --from a ref name, whose contract resolves through the snapshot store"), runCommandAction("Or populate the graph first", "{bin} db update")];
+	return new ActionableCliError("MIGRATION.SNAPSHOT_MISSING", viaRef ? `Ref "${identifier}" is not resolvable` : `No contract source for from-hash "${identifier}"`, {
+		why: viaRef ? `Ref "${identifier}" has no pointer file, and the hash being resolved is not a node in the migration graph either.` : `Hash "${identifier}" is not a node in the migration graph (the graph is empty), and it does not name a ref either.`,
+		fix,
+		nextActions,
+		meta: {
+			identifier,
+			viaRef
+		},
+		...ifDefined("cause", options?.cause)
+	});
+}
+/**
+* Default origin resolution for `migration plan` found nothing (no `--from`,
+* no `db` ref) while migrations already exist on disk. Planning would silently
+* produce an empty-origin migration that ignores the existing history — almost
+* always a mistake — so the command refuses and names the three exits.
+*/
+function errorPlanOriginUnknown(reachableRefs, graphTipHash) {
+	const fromSuggestion = reachableRefs.length > 0 ? reachableRefs.map((r) => `--from ${r.name}`).join(" or ") : graphTipHash !== null ? `--from ${graphTipHash}` : "--from <contract>";
+	const refSetCommand = graphTipHash !== null ? `{bin} migration ref set db ${graphTipHash}` : "{bin} migration ref set db <contract>";
+	return new ActionableCliError("MIGRATION.PLAN_ORIGIN_UNKNOWN", "Cannot determine the plan origin: migrations exist but no origin is named", {
+		why: "Migrations exist on disk, but there is no `db` ref and no --from was given, so the plan origin would silently fall back to an empty database and the resulting migration would recreate everything the existing migrations already create.",
+		fix: [
+			`Set the \`db\` ref to the contract your dev database is at (\`${refSetCommand}\`), or advance it via \`{bin} db update\`.`,
+			`Or pass the origin explicitly: \`{bin} migration plan ${fromSuggestion}\`.`,
+			"Or pass --from @empty to deliberately plan from an empty database."
+		].join("\n"),
+		nextActions: [
+			runCommandAction("Point the db ref at the origin contract", refSetCommand),
+			...reachableRefs.length > 0 ? reachableRefs.map((ref) => runCommandAction(`Plan from ${ref.name}`, `{bin} migration plan --from ${ref.name}`)) : [runCommandAction("Plan from an explicit origin", `{bin} migration plan ${fromSuggestion}`)],
+			runCommandAction("Plan from an empty database deliberately", "{bin} migration plan --from @empty")
+		],
+		meta: {
+			reachableRefs: reachableRefs.map((r) => r.name),
+			...graphTipHash !== null ? { graphTipHash } : {}
+		}
+	});
+}
+function errorMarkerMismatch(markerHash, reachableHashes, graphTip) {
+	const reachableList = reachableHashes.length > 0 ? reachableHashes.join(", ") : "(none — migration graph is empty)";
+	const planFromFix = graphTip !== null ? `Run \`{bin} migration plan --from ${graphTip}\` if the live marker is canonical and the on-disk graph needs catching up.` : "Run `{bin} migration plan` if the live marker is canonical and the on-disk graph needs catching up.";
+	const planCommand = graphTip !== null ? `{bin} migration plan --from ${graphTip}` : "{bin} migration plan";
+	return new ActionableCliError("MIGRATION.MARKER_MISMATCH", "Database marker is not reachable in the on-disk migration graph", {
+		why: `DB marker is ${markerHash}, but the on-disk migration graph reaches: ${reachableList}.`,
+		fix: [
+			planFromFix,
+			`Run \`{bin} migration ref set db ${markerHash}\` if the on-disk graph is canonical and the local \`db\` ref drifted.`,
+			"Investigate whether the database was migrated by an out-of-band process."
+		].join("\n"),
+		nextActions: [
+			runCommandAction("Catch the on-disk graph up to the live marker", planCommand),
+			runCommandAction("Point the local db ref at the live marker", `{bin} migration ref set db ${markerHash}`),
+			chooseAction("Investigate whether the database was migrated by an out-of-band process")
+		],
+		meta: {
+			markerHash,
+			reachableHashes: [...reachableHashes],
+			...graphTip !== null ? { graphTip } : {}
+		}
+	});
+}
+const ROLLBACK_IS_DESTRUCTIVE = "A rollback (reverse) plan is expected to contain destructive (DROP) operations — review them before applying";
+const NARROWER_CASES_NEED_A_HINT = "Narrower cases (rename inference, re-adding a required field without a safe default, or a type change that needs data) may additionally need a hint in the planned migration";
+function errorPathUnreachable(failure) {
+	const meta = failure.meta ?? {};
+	const fromHashMeta = typeof meta["fromHash"] === "string" ? meta["fromHash"] : null;
+	const planFromHash = fromHashMeta === "<empty>" ? null : fromHashMeta;
+	const targetHash = typeof meta["targetHash"] === "string" ? meta["targetHash"] : typeof meta["target"] === "string" ? meta["target"] : null;
+	const deadEnds = meta["deadEnds"];
+	const deadEndsSuffix = Array.isArray(deadEnds) && deadEnds.length > 0 ? ` Dead-ends: ${deadEnds.map(String).join(", ")}.` : "";
+	const neverPlanned = meta["kind"] === "neverPlanned";
+	const planCommand = (() => {
+		if (neverPlanned) return "{bin} migration plan --name <slug>";
+		if (planFromHash !== null && targetHash !== null) return `{bin} migration plan --from ${planFromHash} --to ${targetHash} --name <slug>`;
+		if (targetHash !== null) return `{bin} migration plan --to ${targetHash} --name <slug>`;
+		if (planFromHash !== null) return `{bin} migration plan --from ${planFromHash} --name <slug>`;
+		return "{bin} migration plan";
+	})();
+	const applyCommand = targetHash !== null && !neverPlanned ? `{bin} db migrate --to ${targetHash}` : "{bin} db migrate";
+	return new ActionableCliError("MIGRATION.PATH_UNREACHABLE", failure.summary, {
+		why: failure.why ?? `Cannot reach target "${targetHash ?? "<unknown>"}" from current marker "${fromHashMeta ?? "<unknown>"}".${deadEndsSuffix}`,
+		fix: [
+			"Plan the missing edge, then apply it:",
+			`  1. ${planCommand}`,
+			`  2. ${applyCommand}`,
+			`${ROLLBACK_IS_DESTRUCTIVE}.`,
+			`${NARROWER_CASES_NEED_A_HINT}.`,
+			"Inspect the on-disk graph with `{bin} migration list`, or `{bin} migration show <bundle>` for any bundle in the path you expected."
+		].join("\n"),
+		nextActions: [
+			runCommandAction("Plan the missing edge", planCommand),
+			runCommandAction("Apply it", applyCommand),
+			chooseAction(ROLLBACK_IS_DESTRUCTIVE),
+			chooseAction(NARROWER_CASES_NEED_A_HINT),
+			runCommandAction("Inspect the on-disk graph", "{bin} migration list"),
+			runCommandAction("Inspect a bundle in the path you expected", "{bin} migration show <bundle>")
+		],
+		meta: { ...meta }
+	});
+}
+/**
+* Shared "needs a live database" precondition for read verbs that consult the
+* marker/ledger (`migration log`, `migration status`). A command needs both a
+* connection string and a control-plane driver; either missing yields the same
+* `CONFIG.DB_CONNECTION_REQUIRED` envelope with `meta.missingFlags` (canonical long-form flags
+* per CLI Style Guide §Errors) so callers can react programmatically. Returns
+* `null` when both are present.
+*/
+function requireLiveDatabase(args) {
+	if (args.dbConnection && args.hasDriver) return null;
+	const missingFlags = args.dbConnection ? [] : ["--db"];
+	return errorDatabaseConnectionRequired({
+		why: args.why,
+		missingFlags,
+		...ifDefined("commandName", args.commandName),
+		...ifDefined("retryCommand", args.retryCommand)
+	});
+}
+/**
+* Maps a `RefResolutionError` from the contract/migration reference
+* resolver into a CLI structured error envelope.
+*/
+/**
+* A migration ref (dirName or hash-prefix) resolves in more than one contract
+* space. The user must qualify with `--space <id>` to disambiguate.
+*/
+function errorAmbiguousMigrationRef(ref, spaceIds) {
+	const spaceList = spaceIds.join(", ");
+	return new ActionableCliError("MIGRATION.AMBIGUOUS_MIGRATION_REF", `Ambiguous migration reference: "${ref}" resolves in multiple spaces — qualify with --space <id>`, {
+		why: `"${ref}" matches migrations in spaces: ${spaceList}.`,
+		fix: `Qualify with --space <id> to select one space. Available matching spaces: ${spaceList}.`,
+		nextActions: [chooseAction(`Qualify with --space <id>, one of: ${spaceList}`)],
+		meta: {
+			ref,
+			spaceIds: [...spaceIds]
+		}
+	});
+}
+function mapRefResolutionError(error) {
+	switch (error.kind) {
+		case "not-found": {
+			const fix = error.grammar === "contract" ? "Provide a valid contract hash, ref name, or migration directory name." : "Provide a valid migration directory name or migration hash.";
+			return new ActionableCliError("MIGRATION.REF_NOT_FOUND", `Not a known ${error.grammar} reference: "${error.input}"`, {
+				why: `No ${error.grammar} matching "${error.input}" exists in the migration graph or refs index.`,
+				fix,
+				nextActions: [chooseAction(fix)],
+				meta: {
+					input: error.input,
+					grammar: error.grammar
+				}
+			});
+		}
+		case "ambiguous": return new ActionableCliError("MIGRATION.REF_AMBIGUOUS", `Ambiguous ${error.grammar} reference: "${error.input}"`, {
+			why: `"${error.input}" matches multiple ${error.grammar}s: ${error.candidates.join(", ")}`,
+			fix: "Provide a longer prefix or use the full hash to disambiguate.",
+			nextActions: [chooseAction("Provide a longer prefix or use the full hash to disambiguate")],
+			meta: {
+				input: error.input,
+				candidates: error.candidates,
+				grammar: error.grammar
+			}
+		});
+		case "wrong-grammar": return new ActionableCliError("MIGRATION.REF_WRONG_GRAMMAR", error.message, {
+			why: error.message,
+			fix: error.fix,
+			nextActions: [chooseAction(error.fix)],
+			meta: {
+				input: error.input,
+				expectedGrammar: error.expectedGrammar
+			}
+		});
+		case "invalid-format": return new ActionableCliError("MIGRATION.REF_INVALID_FORMAT", `Invalid reference format: "${error.input}"`, {
+			why: error.reason,
+			fix: "Provide a valid contract hash, ref name, or migration directory name.",
+			nextActions: [chooseAction("Provide a valid contract hash, ref name, or migration directory name")],
+			meta: { input: error.input }
+		});
+	}
+}
+/**
+* Asserts that all framework components are compatible with the expected family and target.
+*
+* This function validates that each component in the framework components array:
+* - Has kind 'target', 'adapter', 'extension', or 'driver'
+* - Has familyId matching expectedFamilyId
+* - Has targetId matching expectedTargetId
+*
+* This validation happens at the CLI composition boundary, before passing components
+* to typed planner/runner instances. It fills the gap between runtime validation
+* (via the config loader's `collectConfigIssues` diagnostics) and compile-time
+* type enforcement.
+*
+* @param expectedFamilyId - The expected family ID (e.g., 'sql')
+* @param expectedTargetId - The expected target ID (e.g., 'postgres')
+* @param frameworkComponents - Array of framework components to validate
+* @returns The same array typed as TargetBoundComponentDescriptor
+* @throws CliStructuredError if any component is incompatible
+*
+* @example
+* ```ts
+* const configResult = await loadConfigForSections(undefined, ['family', 'target', 'adapter', 'extensions']);
+* const config = configResult.assertOk();
+* const frameworkComponents = [config.target, config.adapter, ...(config.extensions ?? [])];
+*
+* // Validate and type-narrow components before passing to planner
+* const typedComponents = assertFrameworkComponentsCompatible(
+*   config.family.familyId,
+*   config.target.targetId,
+*   frameworkComponents
+* );
+*
+* const planner = target.migrations.createPlanner(familyInstance);
+* planner.plan({ contract, schema, policy, frameworkComponents: typedComponents });
+* ```
+*/
+function assertFrameworkComponentsCompatible(expectedFamilyId, expectedTargetId, frameworkComponents) {
+	for (let i = 0; i < frameworkComponents.length; i++) {
+		const component = frameworkComponents[i];
+		if (typeof component !== "object" || component === null) throw errorConfigValidation$1("frameworkComponents[]", { why: `Framework component at index ${i} must be an object` });
+		const record = component;
+		if (!Object.hasOwn(record, "kind")) throw errorConfigValidation$1("frameworkComponents[].kind", { why: `Framework component at index ${i} must have 'kind' property` });
+		const kind = record["kind"];
+		if (kind !== "target" && kind !== "adapter" && kind !== "extension" && kind !== "driver") throw errorConfigValidation$1("frameworkComponents[].kind", { why: `Framework component at index ${i} has invalid kind '${String(kind)}' (must be 'target', 'adapter', 'extension', or 'driver')` });
+		if (!Object.hasOwn(record, "familyId")) throw errorConfigValidation$1("frameworkComponents[].familyId", { why: `Framework component at index ${i} (kind: ${String(kind)}) must have 'familyId' property` });
+		const familyId = record["familyId"];
+		if (familyId !== expectedFamilyId) throw errorConfigValidation$1("frameworkComponents[].familyId", { why: `Framework component at index ${i} (kind: ${String(kind)}) has familyId '${String(familyId)}' but expected '${expectedFamilyId}'` });
+		if (!Object.hasOwn(record, "targetId")) throw errorConfigValidation$1("frameworkComponents[].targetId", { why: `Framework component at index ${i} (kind: ${String(kind)}) must have 'targetId' property` });
+		const targetId = record["targetId"];
+		if (targetId !== expectedTargetId) throw errorConfigValidation$1("frameworkComponents[].targetId", { why: `Framework component at index ${i} (kind: ${String(kind)}) has targetId '${String(targetId)}' but expected '${expectedTargetId}'` });
+	}
+	return frameworkComponents;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sortDeep(value) {
+	if (Array.isArray(value)) return value.map(sortDeep);
+	if (!isPlainObject(value)) return value;
+	const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+	const next = {};
+	for (const [key, child] of entries) next[key] = sortDeep(child);
+	return next;
+}
+function sortDeepTyped(value) {
+	return sortDeep(value);
+}
+function extractExtensionPackMeta(component) {
+	const { kind, id, version, capabilities, types } = component;
+	const base = {
+		kind,
+		id,
+		familyId: component.familyId,
+		targetId: component.targetId,
+		version
+	};
+	if (capabilities) base["capabilities"] = capabilities;
+	if (types) if (types.codecTypes) {
+		const { controlPlaneHooks: _, codecDescriptors: _cd, ...cleanedCodecTypes } = types.codecTypes;
+		base["types"] = {
+			...types,
+			codecTypes: cleanedCodecTypes
+		};
+	} else base["types"] = types;
+	return base;
+}
+/**
+* Enriches a raw contract with framework-derived metadata: capabilities from all component descriptors and extension pack metadata from extension descriptors. Produces deterministically sorted output.
+*/
+function enrichContract(ir, components) {
+	const mergedCapabilities = mergeCapabilityMatrices(ir.capabilities, components);
+	const extensionsMeta = {};
+	for (const component of components) if (component.kind === "extension") extensionsMeta[component.id] = extractExtensionPackMeta(component);
+	const extensions = Object.keys(extensionsMeta).length > 0 ? {
+		...ir.extensions,
+		...extensionsMeta
+	} : ir.extensions;
+	return {
+		...ir,
+		capabilities: sortDeepTyped(mergedCapabilities),
+		extensions: sortDeepTyped(extensions)
+	};
+}
+/**
+* Resolves the absolute path to contract.json from the config.
+*/
+function resolveContractPath(config) {
+	if (config.contract?.output === void 0) throw errorRuntime("CONFIG.VALIDATION_FAILED", "config.contract.output is required to resolve the contract path", {
+		why: "CLI commands read the emitted contract from config.contract.output; the config has no value to read.",
+		fix: "Ensure your prisma.config.ts goes through `defineConfig()`, which normalises a default output when the provider supplies an input path, or set `contract.output` explicitly."
+	});
+	return resolve(config.contract.output);
+}
+/**
+* Resolves the migrations directory and config path from CLI options.
+* Shared by migrate, migration-plan, and migration-status.
+*
+* - `migrationsDir` is the project's top-level `migrations/` directory
+*   (the root that the aggregate loader walks for every contract space).
+* - `appMigrationsDir` is the app subspace directory under it
+*   (`<migrationsDir>/<APP_SPACE_ID>/`). Every per-app reader / writer
+*   (`migration new`, `migration plan`, `migrate`,
+*   `migration status`, `migration show`, `migration ref`) operates on
+*   this directory. Extensions own their own `migrations/<spaceId>/`.
+* - `refsDir` is the app's refs directory (`<appMigrationsDir>/refs/`).
+*   The framework does not maintain refs at the migrations root.
+*
+* `cwd` is the directory the command was invoked from; every relative path in
+* the result is computed against it.
+*/
+function resolveMigrationPaths(configOption, config, cwd) {
+	const resolvedConfigPath = configOption ? resolve(cwd, configOption) : void 0;
+	const configPath = resolvedConfigPath ? relative(cwd, resolvedConfigPath) : "prisma.config.ts";
+	const migrationsDir = resolve(resolvedConfigPath ? resolve(resolvedConfigPath, "..") : cwd, config.migrations?.dir ?? "migrations");
+	const migrationsRelative = relative(cwd, migrationsDir);
+	const appMigrationsDir = spaceMigrationDirectory(migrationsDir, APP_SPACE_ID$1);
+	return {
+		configPath,
+		migrationsDir,
+		migrationsRelative,
+		appMigrationsDir,
+		appMigrationsRelative: relative(cwd, appMigrationsDir),
+		refsDir: resolve(appMigrationsDir, "refs")
+	};
+}
+function collectDeclaredInvariants(graph) {
+	const declared = /* @__PURE__ */ new Set();
+	for (const edges of graph.forwardChain.values()) for (const edge of edges) for (const inv of edge.invariants) declared.add(inv);
+	return declared;
+}
+/**
+* Maps a `MigrationEdge` to the structural-edge shape used in the
+* `MIGRATION.NO_INVARIANT_PATH` error envelope. Shared between
+* `migrate` and `migration status` so both commands surface
+* the same JSON wire shape when an invariant-aware route is unsatisfiable.
+*/
+function toStructuralEdge(edge) {
+	return {
+		dirName: edge.dirName,
+		migrationHash: edge.migrationHash,
+		from: edge.from,
+		to: edge.to,
+		invariants: edge.invariants
+	};
+}
+function targetSupportsMigrations(target) {
+	return hasMigrations(target);
+}
+/**
+* Hangs up without letting the hang-up decide the command's result. A rejection out of a
+* `finally` replaces the value the `try`/`catch` already returned, so an unguarded close turns a
+* mapped connection error into an unmapped one — and that is the case it hits most, because a
+* `connect()` that failed leaves nothing to close.
+*/
+async function closeQuietly(client) {
+	try {
+		await client.close();
+	} catch {}
+}
+function getTargetMigrations(target) {
+	return hasMigrations(target) ? target.migrations : void 0;
+}
+/**
+* Reads and parses contract.json, validating the framework-level envelope
+* fields (storageHash, schemaVersion, target, targetFamily).
+*
+* Family-specific validation (storage structure, codec mappings, etc.)
+* happens downstream in the control client via the family instance.
+*/
+async function readContractEnvelope(config) {
+	const contractPath = resolveContractPath(config);
+	const content = await readFile(contractPath, "utf-8");
+	const json = JSON.parse(content);
+	const { schemaVersion, target, targetFamily, profileHash } = json;
+	const storageHash = json["storage"]?.["storageHash"];
+	if (typeof storageHash !== "string") throw new CliStructuredError$1("CONTRACT.VALIDATION_FAILED", `Contract at ${relative(process.cwd(), contractPath)} is missing a valid storage.storageHash. Run \`{bin} contract emit\` to regenerate.`, { where: { path: contractPath } });
+	if (typeof schemaVersion !== "string") throw new CliStructuredError$1("CONTRACT.VALIDATION_FAILED", `Contract at ${relative(process.cwd(), contractPath)} is missing schemaVersion.`, { where: { path: contractPath } });
+	if (typeof target !== "string") throw new CliStructuredError$1("CONTRACT.VALIDATION_FAILED", `Contract at ${relative(process.cwd(), contractPath)} is missing target.`, { where: { path: contractPath } });
+	if (typeof targetFamily !== "string") throw new CliStructuredError$1("CONTRACT.VALIDATION_FAILED", `Contract at ${relative(process.cwd(), contractPath)} is missing targetFamily.`, { where: { path: contractPath } });
+	return {
+		...json,
+		storageHash,
+		schemaVersion,
+		target,
+		targetFamily,
+		...typeof profileHash === "string" ? { profileHash } : {}
+	};
+}
+/**
+* Masks credentials in a database connection URL.
+* Handles standard URLs (username + password + query params) and libpq-style key=value strings.
+*/
+function maskConnectionUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (parsed.username) parsed.username = "****";
+		if (parsed.password) parsed.password = "****";
+		for (const key of [...parsed.searchParams.keys()]) if (/password/i.test(key)) parsed.searchParams.set(key, "****");
+		return parsed.toString();
+	} catch {
+		return url.replace(/password\s*=\s*\S+/gi, "password=****").replace(/user\s*=\s*\S+/gi, "user=****");
+	}
+}
+/**
+* Strips raw connection URL fragments from an error message to prevent credential leakage.
+* Call this before surfacing driver errors to the user.
+*/
+function sanitizeErrorMessage(message, connectionUrl) {
+	if (!connectionUrl) return message;
+	try {
+		const parsed = new URL(connectionUrl);
+		let sanitized = message;
+		sanitized = sanitized.replaceAll(connectionUrl, maskConnectionUrl(connectionUrl));
+		if (parsed.password) sanitized = sanitized.replaceAll(parsed.password, "****");
+		if (parsed.username) sanitized = sanitized.replaceAll(parsed.username, "****");
+		return sanitized;
+	} catch {
+		return message.replace(/password\s*=\s*\S+/gi, "password=****").replace(/user\s*=\s*\S+/gi, "user=****");
+	}
+}
+/**
+* Project the CLI's `Config.extensions` array into the canonical
+* {@link ExtensionPackInput} shape. The single `as ExtensionPackLike`
+* structural cast in the CLI lives inside this function.
+*/
+function toExtensionInputs(extensions) {
+	return extensions.map((raw) => {
+		const pack = raw;
+		if (pack.contractSpace === void 0) return {
+			id: pack.id,
+			targetId: pack.targetId
+		};
+		return {
+			id: pack.id,
+			targetId: pack.targetId,
+			contractSpace: {
+				contractJson: pack.contractSpace.contractJson,
+				headRef: pack.contractSpace.headRef,
+				migrations: pack.contractSpace.migrations ?? []
+			}
+		};
+	});
+}
+/**
+* Minimal aggregate-loader projection that extracts `id` + `targetId`
+* from raw extension pack descriptors **without invoking any
+* `contractSpace` accessor**. Inspects the own-property descriptor so
+* that getter-backed `contractSpace` declarations are detected but
+* never called.
+*
+* Inclusion semantics match {@link toDeclaredExtensions}: a data
+* property whose value is explicitly `undefined` is treated as "no
+* contract-space declaration" and skipped, mirroring the
+* `pack.contractSpace === undefined` check used on canonicalised
+* inputs. Prototype-chain `contractSpace` properties (no own
+* descriptor) are also skipped.
+*
+* This variant must be used by `buildContractSpaceAggregate` so that
+* the aggregate path (including `db verify`) never reads
+* `contractSpace.contractJson` from extension descriptors — the loader
+* always reads the contract from on-disk artefacts instead.
+*/
+function toDeclaredExtensionsFromRaw(extensions) {
+	const entries = [];
+	for (const raw of extensions) {
+		if (typeof raw !== "object" || raw === null) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(raw, "contractSpace");
+		if (descriptor === void 0) continue;
+		if ("value" in descriptor && descriptor.value === void 0) continue;
+		const pack = raw;
+		entries.push({
+			id: pack.id,
+			targetId: pack.targetId
+		});
+	}
+	return entries;
+}
+const CONTRACT_SPACES_DOCS_URL = "https://pris.ly/contract-spaces";
+function contractSpaceViolationError(summary, options) {
+	return new CliStructuredError$1("MIGRATION.CONTRACT_SPACE_VIOLATION", summary, {
+		why: options.why,
+		fix: options.fix,
+		docsUrl: CONTRACT_SPACES_DOCS_URL,
+		meta: { violations: options.violations }
+	});
+}
+/**
+* Build the `MIGRATION.CONTRACT_SPACE_VIOLATION` structured-error envelope for a contract-space
+* target mismatch. Shared between the declared-extension precheck (the
+* descriptor's configured target disagrees with the project target) and
+* the on-disk-contract check surfaced by `checkIntegrity`.
+*/
+function targetMismatchError(spaceId, expected, actual) {
+	return contractSpaceViolationError(`Contract-space target mismatch for "${spaceId}"`, {
+		why: `Space "${spaceId}" targets "${actual}" but the project's adapter targets "${expected}".`,
+		fix: "Update the extension descriptor to target the configured database, or change the project adapter.",
+		violations: [{
+			kind: "targetMismatch",
+			spaceId,
+			expected,
+			actual
+		}]
+	});
+}
+/**
+* Human-readable detail for an integrity violation, used as the `why`
+* of the `integrityFailure` envelope. Mirrors the messages the prior
+* throw-on-load loader produced so downstream consumers see the same
+* text for the same on-disk state.
+*/
+function describeIntegrityViolation(violation) {
+	switch (violation.kind) {
+		case "hashMismatch": return `Migration "${violation.dirName}" stored hash "${violation.stored}" does not match computed hash "${violation.computed}".`;
+		case "providedInvariantsMismatch": return `Migration "${violation.dirName}" providedInvariants in migration.json disagrees with ops.json.`;
+		case "packageUnloadable": return `Migration "${violation.dirName}" could not be loaded: ${violation.detail}`;
+		case "sameSourceAndTarget": return `Migration "${violation.dirName}" has source equal to target (${violation.hash}) with no data invariant — a true no-op self-edge.`;
+		case "headRefMissing": return `Head ref \`refs/head.json\` is missing for contract space "${violation.spaceId}".`;
+		case "headRefNotInGraph": return `Head ref ${violation.hash} for contract space "${violation.spaceId}" is not present in the migration graph.`;
+		case "refUnreadable": return `Ref "${violation.refName}" for contract space "${violation.spaceId}" is unreadable: ${violation.detail}`;
+		case "duplicateMigrationHash": return `Multiple migrations in space "${violation.spaceId}" share migrationHash "${violation.migrationHash}" (${violation.dirNames.join(", ")}).`;
+		default: {
+			const spaceId = "spaceId" in violation ? violation.spaceId : "*";
+			return `Integrity violation "${violation.kind}" for contract space "${spaceId}".`;
+		}
+	}
+}
+/**
+* Map the integrity violations `checkIntegrity` reports into a single
+* CLI structured-error envelope, preserving the error codes the prior
+* throw-on-load loader emitted: `MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION`
+* (layout drift, bundled) and `MIGRATION.CONTRACT_SPACE_VIOLATION` (target /
+* disjointness / contract-validation / structural integrity). Returns
+* `null` when there is nothing to refuse on.
+*
+* Precedence reproduces the prior loader's first-failure ordering:
+* layout drift first (every offence bundled into one envelope), then
+* target mismatch, then disjointness, then a contract-validation
+* failure, then any remaining structural integrity violation.
+*/
+function mapIntegrityViolations(violations, migrationsDir) {
+	if (violations.length === 0) return null;
+	const layout = violations.filter((v) => v.kind === "orphanSpaceDir" || v.kind === "declaredButUnmigrated");
+	if (layout.length > 0) {
+		const lines = layout.map((v) => `- [${v.kind}] ${v.spaceId}`);
+		return new CliStructuredError$1("MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION", layout.length === 1 ? "Contract-space layout violation detected" : `Contract-space layout violations detected (${layout.length})`, {
+			why: `The on-disk \`${migrationsDir}/\` directory and your \`extensions\` declaration are not in agreement.\n${lines.join("\n")}`,
+			fix: `Declare the extension in \`extensions\` and re-emit its contract-space artefacts, or remove the orphan \`${migrationsDir}/<space>\` directory.`,
+			docsUrl: CONTRACT_SPACES_DOCS_URL,
+			meta: { violations: layout }
+		});
+	}
+	const targetMismatch = violations.find((v) => v.kind === "targetMismatch");
+	if (targetMismatch && targetMismatch.kind === "targetMismatch") return targetMismatchError(targetMismatch.spaceId, targetMismatch.expected, targetMismatch.actual);
+	const disjointness = violations.find((v) => v.kind === "disjointness");
+	if (disjointness && disjointness.kind === "disjointness") return contractSpaceViolationError(`Contract-space disjointness violation: storage element "${disjointness.element}" claimed by multiple spaces`, {
+		why: `Spaces ${disjointness.claimedBy.map((s) => `"${s}"`).join(", ")} all claim the storage element "${disjointness.element}". Each storage element must be owned by exactly one contract space.`,
+		fix: "Update the conflicting contracts so each storage element is claimed by exactly one space.",
+		violations: [disjointness]
+	});
+	const contractUnreadable = violations.find((v) => v.kind === "contractUnreadable");
+	if (contractUnreadable && contractUnreadable.kind === "contractUnreadable") return contractSpaceViolationError(`Contract-space contract validation failed for "${contractUnreadable.spaceId}"`, {
+		why: contractUnreadable.detail,
+		fix: "Re-emit the extension contract with `{bin} contract emit`, or fix the extension pack descriptor producing the invalid contract.",
+		violations: [contractUnreadable]
+	});
+	const structural = violations[0];
+	return contractSpaceViolationError(`Contract-space integrity failure for "${"spaceId" in structural ? structural.spaceId : "*"}"`, {
+		why: describeIntegrityViolation(structural),
+		fix: `Re-emit the affected migration package(s) or restore the on-disk \`${migrationsDir}\` directory from version control.`,
+		violations: [structural]
+	});
+}
+function declaredExtensionsFromInputs(extensions) {
+	return toDeclaredExtensionsFromRaw(extensions);
+}
+/**
+* Reject extension descriptors whose configured target disagrees with
+* the project target before any on-disk read.
+*/
+function refuseDeclaredExtensionTargetMismatch(inputs) {
+	for (const declared of declaredExtensionsFromInputs(inputs.extensions)) if (declared.targetId !== inputs.targetId) return targetMismatchError(declared.id, inputs.targetId, declared.targetId);
+	return null;
+}
+/**
+* Load the tolerant {@link ContractSpaceAggregate} once at the CLI
+* surface. Construction never throws on disk content; callers query
+* {@link ContractSpaceAggregate.app} / extension facets instead of
+* re-reading `migrations/`.
+*/
+async function loadContractSpaceAggregateForCli(inputs) {
+	const targetFailure = refuseDeclaredExtensionTargetMismatch(inputs);
+	if (targetFailure) return notOk(targetFailure);
+	return ok(await loadContractSpaceAggregate({
+		migrationsDir: inputs.migrationsDir,
+		deserializeContract: inputs.deserializeContract,
+		appContract: inputs.appContract
+	}));
+}
+/**
+* Run `checkIntegrity` on a loaded aggregate and map violations into
+* the contract-space refusal envelope, or return `null` when the model
+* is acceptable for the requested check scope.
+*/
+function refuseContractSpaceIntegrity(aggregate, options, migrationsDir) {
+	return mapIntegrityViolations(aggregate.checkIntegrity(options), migrationsDir);
+}
+const PACKAGE_CORRUPTION_KINDS = /* @__PURE__ */ new Set([
+	"hashMismatch",
+	"providedInvariantsMismatch",
+	"packageUnloadable"
+]);
+/**
+* Reader-subset integrity refusal for `migration status`: package
+* corruptions only (`hashMismatch`, `providedInvariantsMismatch`,
+* `packageUnloadable`).
+*/
+function refusePackageCorruptionOnAggregate(aggregate, migrationsDir) {
+	return mapIntegrityViolations(aggregate.checkIntegrity().filter((v) => PACKAGE_CORRUPTION_KINDS.has(v.kind)), migrationsDir);
+}
+/**
+* Construct the tolerant {@link ContractSpaceAggregate} at the CLI
+* surface and apply the explicit integrity refusal.
+*
+* App-space migration packages are read from `migrations/<app>/` by the
+* loader itself; callers no longer thread them through.
+*/
+async function buildContractSpaceAggregate(inputs) {
+	const declaredExtensions = declaredExtensionsFromInputs(inputs.extensions);
+	const loaded = await loadContractSpaceAggregateForCli(inputs);
+	if (!loaded.ok) return loaded;
+	const failure = refuseContractSpaceIntegrity(loaded.value, {
+		declaredExtensions,
+		checkContracts: true
+	}, inputs.migrationsDir);
+	if (failure) return notOk(failure);
+	return ok(loaded.value);
+}
+/**
+* Build a minimal app {@link Contract} carrying only the project's
+* contract-identity (`storage.storageHash` + `target` / `targetFamily`)
+* when the real `contract.json` is absent or undeserializable.
+*
+* `loadContractSpaceAggregate` requires an `appContract` to synthesise the
+* app space's head ref from its storage hash. Read commands query only that
+* hash and the target — never `models` — so an empty-`models` stand-in is
+* sufficient for them. It is *not* a valid contract for any consumer that
+* reads schema, which is why this is confined to the read-aggregate path.
+*/
+function appContractStandInFromIdentity(args) {
+	return blindCast({
+		storage: { storageHash: args.contractHash },
+		schemaVersion: "0.0.0",
+		target: args.targetId,
+		targetFamily: args.targetFamily,
+		models: {},
+		profileHash: EMPTY_CONTRACT_HASH
+	});
+}
+async function loadContractRawSafely(config) {
+	try {
+		const raw = await readFile(resolveContractPath(config), "utf-8");
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+/**
+* Tolerant {@link ContractSpaceAggregate} assembly for read-only CLI
+* commands. No integrity gate — callers query `aggregate.app` (or other
+* facets) without re-reading `migrations/`. When `contract.json` is absent
+* or undeserializable, the app contract falls back to an identity-only
+* stand-in ({@link appContractStandInFromIdentity}), so these commands
+* load without requiring a readable contract.
+*/
+async function buildReadAggregate(config, options) {
+	let contractHash = EMPTY_CONTRACT_HASH;
+	try {
+		contractHash = (await readContractEnvelope(config)).storageHash;
+	} catch {}
+	try {
+		const contractRawForAggregate = await loadContractRawSafely(config);
+		const stack = createControlStack(config);
+		const familyInstance = config.family.create(stack);
+		const deserializeContract = (json) => familyInstance.deserializeContract(json);
+		let appContractForLoad = appContractStandInFromIdentity({
+			contractHash,
+			targetId: config.target.id,
+			targetFamily: config.target.familyId
+		});
+		if (contractRawForAggregate !== null) try {
+			appContractForLoad = deserializeContract(contractRawForAggregate);
+		} catch {}
+		const loaded = await loadContractSpaceAggregateForCli({
+			targetId: config.target.id,
+			migrationsDir: options.migrationsDir,
+			appContract: appContractForLoad,
+			extensions: config.extensions ?? [],
+			deserializeContract
+		});
+		if (!loaded.ok) return loaded;
+		return ok({
+			aggregate: loaded.value,
+			contractHash
+		});
+	} catch (error) {
+		if (MigrationToolsError.is(error)) return notOk(error);
+		return notOk(errorUnexpected(error instanceof Error ? error.message : String(error), { why: `Failed to read migrations directory: ${error instanceof Error ? error.message : String(error)}` }));
+	}
+}
+/**
+* Strips operation objects to their public shape (id, label, operationClass).
+* Used at the API boundary to avoid leaking internal fields (precheck, execute, postcheck, etc.).
+*/
+function stripOperations(operations) {
+	return operations.map((op) => ({
+		id: op.id,
+		label: op.label,
+		operationClass: op.operationClass
+	}));
+}
+/**
+* Content identity of a `db update` plan: what it does (the ordered display
+* operations) and where it lands (the destination storage hash). A
+* `DESTRUCTIVE_CHANGES` refusal names the refused plan by this hash, and the
+* apply that carries the consent back recomputes it to prove it is still
+* applying the plan that was consented to.
+*/
+function computePlanHash(plan) {
+	const canonical = canonicalizeJson({
+		operations: plan.operations,
+		destination: { storageHash: plan.destination.storageHash }
+	});
+	return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+* Span id emitted via `onProgress` for the run phase. Stable
+* identifier consumed by the structured-output renderer and by tests.
+*/
+const RUN_SPAN_ID = "apply";
+/**
+* Runner-driving tail shared by every run caller — `db init`,
+* `db update`, and `migrate`. Consumes already-resolved per-space
+* plans (the planner-vs-replay distinction is owned by the caller) and
+* dispatches them to the runner in canonical order.
+*
+* Marker advancement is part of the runner's per-space transaction
+* (the SQL family runner writes the marker as the last step of each
+* space's transaction), so this primitive does not advance markers
+* separately — by the time `execute` returns ok, every
+* space's marker has been advanced to its plan's destination.
+*
+* Span emission (`spanStart 'apply'` / `spanEnd 'apply'`) is owned here
+* so callers don't have to duplicate it; the `action` field on each
+* progress event is taken from the caller's `action` argument.
+*/
+async function runMigration(inputs) {
+	const { aggregate, perSpacePlans, applyOrder, driver, familyInstance, migrations, frameworkComponents, policy, action, onProgress } = inputs;
+	const orderedResolutions = collectOrdered(applyOrder, perSpacePlans);
+	const runner = migrations.createRunner(familyInstance);
+	onProgress?.({
+		action,
+		kind: "spanStart",
+		spanId: RUN_SPAN_ID,
+		label: progressLabelForAction(action)
+	});
+	const perSpaceOptions = orderedResolutions.map((r) => ({
+		space: r.spaceId,
+		plan: r.entry.plan,
+		driver,
+		destinationContract: r.entry.destinationContract,
+		policy,
+		frameworkComponents,
+		migrationEdges: r.entry.migrationEdges,
+		strictVerification: false
+	}));
+	const runnerResult = await runner.execute({
+		driver,
+		perSpaceOptions
+	});
+	if (!runnerResult.ok) {
+		onProgress?.({
+			action,
+			kind: "spanEnd",
+			spanId: RUN_SPAN_ID,
+			outcome: "error"
+		});
+		return notOk({
+			summary: runnerResult.failure.summary,
+			...ifDefined("why", runnerResult.failure.why),
+			meta: {
+				...runnerResult.failure.meta ?? {},
+				failingSpace: runnerResult.failure.failingSpace,
+				runnerErrorCode: runnerResult.failure.code
+			},
+			cause: runnerResult.failure
+		});
+	}
+	onProgress?.({
+		action,
+		kind: "spanEnd",
+		spanId: RUN_SPAN_ID,
+		outcome: "ok"
+	});
+	return ok({
+		orderedResolutions,
+		totalOpsPlanned: runnerResult.value.perSpaceResults.reduce((sum, r) => sum + r.value.operationsPlanned, 0),
+		totalOpsExecuted: runnerResult.value.perSpaceResults.reduce((sum, r) => sum + r.value.operationsExecuted, 0),
+		perSpace: buildPerSpaceBreakdown(orderedResolutions, aggregate.app.spaceId, { includeMarkers: true })
+	});
+}
+/**
+* Project the planner's per-space resolutions into the
+* `PerSpaceExecutionEntry[]` shape the CLI surfaces.
+*
+* `includeMarkers` is `true` for apply-mode (each space's marker is
+* the `destination.storageHash` of its plan, which the runner
+* advances as the last step of each space's transaction) and `false`
+* for plan-mode (no marker has been written yet).
+*
+* Exported alongside {@link runMigration} so plan-mode callers can
+* assemble the same per-space block without going through the runner.
+*/
+function buildPerSpaceBreakdown(orderedResolutions, appSpaceId, options) {
+	return orderedResolutions.map((r) => {
+		const operations = r.entry.displayOps.map((op) => ({
+			id: op.id,
+			label: op.label,
+			operationClass: op.operationClass
+		}));
+		const base = {
+			spaceId: r.spaceId,
+			kind: r.spaceId === appSpaceId ? "app" : "extension",
+			operations
+		};
+		if (!options.includeMarkers) return base;
+		return {
+			...base,
+			marker: { storageHash: r.entry.plan.destination.storageHash }
+		};
+	});
+}
+/**
+* Materialise the `applyOrder` ordering into resolved per-space
+* entries. Throws if the planner output is missing a contract space listed
+* in `applyOrder` — a wiring bug that should never reach runtime.
+*
+* Exported so callers building their own success envelopes after a
+* plan-mode dispatch can replay the same ordering.
+*/
+function collectOrdered(applyOrder, perSpace) {
+	return applyOrder.map((spaceId) => {
+		const entry = perSpace.get(spaceId);
+		if (!entry) throw new InternalError(`planner output missing per-space plan for "${spaceId}"`);
+		return {
+			spaceId,
+			entry
+		};
+	});
+}
+/**
+* Action-appropriate label for the `spanStart` event the run
+* primitive emits. `runMigration` is shared by `db init`, `db update`,
+* and `migrate`; the span label tracks the user-visible action
+* so structured-progress output reads naturally for each surface.
+*/
+function progressLabelForAction(action) {
+	switch (action) {
+		case "dbInit": return "Initialising database across spaces";
+		case "dbUpdate": return "Updating database across spaces";
+		case "migrate": return "Running migration plan across spaces";
+	}
+}
+/**
+* Span IDs emitted via `onProgress` during the run flow.
+* Stable identifiers consumed by the structured-output renderer and by
+* tests asserting on span ids. The `apply` span itself is owned by
+* the {@link runMigration} primitive — only the introspect / plan
+* spans are emitted directly here.
+*/
+const SPAN_IDS$1 = {
+	introspect: "introspect",
+	plan: "plan"
+};
+/**
+* Loader → planner → runner pipeline shared by `db init` and `db update`.
+*
+* The pipeline:
+*
+* 1. **Load**: build a {@link ContractSpaceAggregate} from the descriptor
+*    set + on-disk on-disk artefacts. Any layout / drift / disjointness /
+*    integrity violation short-circuits with a structured error.
+* 2. **Read DB state**: marker rows (`familyInstance.readAllMarkers`)
+*    + introspected schema (`familyInstance.introspect`).
+* 3. **Plan**: {@link planMigration} chooses `resolveRecordedPath` vs
+*    `planFromDiff` per space according to `callerPolicy.ignoreGraphFor`.
+*    The app space is forced through `planFromDiff` (today's daily-driver
+*    behaviour); every extension space walks its on-disk graph via
+*    `resolveRecordedPath`.
+* 4. **Apply** (when `mode === 'apply'`): every per-space `MigrationPlan`
+*    feeds into the runner's `execute` — one outer
+*    transaction across every space; failure on any space rolls back
+*    every space's writes.
+*/
+async function executeRun(options) {
+	const { driver, adapter, familyInstance, contract, mode, migrations, frameworkComponents, migrationsDir, extensions, targetId, policy, action, onProgress } = options;
+	const loaded = await buildContractSpaceAggregate({
+		targetId,
+		migrationsDir,
+		appContract: contract,
+		extensions,
+		deserializeContract: (json) => familyInstance.deserializeContract(json)
+	});
+	if (!loaded.ok) throw loaded.failure;
+	const aggregate = loaded.value;
+	const markerRows = await familyInstance.readAllMarkers({ driver });
+	if (mode === "apply") {
+		const orphanMarkerError = detectOrphanMarkers(aggregate, markerRows);
+		if (orphanMarkerError !== null) throw orphanMarkerError;
+	}
+	onProgress?.({
+		action,
+		kind: "spanStart",
+		spanId: SPAN_IDS$1.introspect,
+		label: "Introspecting database schema"
+	});
+	const schemaIR = await familyInstance.introspect({
+		driver,
+		contract: collectAggregateNamespaces(aggregate)
+	});
+	onProgress?.({
+		action,
+		kind: "spanEnd",
+		spanId: SPAN_IDS$1.introspect,
+		outcome: "ok"
+	});
+	onProgress?.({
+		action,
+		kind: "spanStart",
+		spanId: SPAN_IDS$1.plan,
+		label: "Planning migration"
+	});
+	const planResult = await planMigration({
+		aggregate,
+		currentDBState: {
+			markersBySpaceId: markerRows,
+			schemaIntrospection: schemaIR
+		},
+		adapter,
+		migrations,
+		frameworkComponents,
+		callerPolicy: { ignoreGraphFor: /* @__PURE__ */ new Set([aggregate.app.spaceId]) },
+		operationPolicy: policy
+	});
+	if (!planResult.ok) {
+		onProgress?.({
+			action,
+			kind: "spanEnd",
+			spanId: SPAN_IDS$1.plan,
+			outcome: "error"
+		});
+		return mapPlannerError(planResult.failure);
+	}
+	onProgress?.({
+		action,
+		kind: "spanEnd",
+		spanId: SPAN_IDS$1.plan,
+		outcome: "ok"
+	});
+	const orderedResolutions = collectOrdered(planResult.value.applyOrder, planResult.value.perSpace);
+	const plannerWarnings = aggregatePlannerWarnings(orderedResolutions);
+	const appResolution = orderedResolutions.find((r) => r.spaceId === aggregate.app.spaceId);
+	if (!appResolution) throw new InternalError("Aggregate planner returned no plan for the app space — the planner is supposed to always emit one.");
+	const appPlan = appResolution.entry.plan;
+	if (mode === "plan") {
+		const aggregateOps = orderedResolutions.flatMap((r) => r.entry.displayOps);
+		const preview = hasOperationPreview(familyInstance) ? familyInstance.toOperationPreview(aggregateOps) : void 0;
+		const perSpace = buildPerSpaceBreakdown(orderedResolutions, aggregate.app.spaceId, { includeMarkers: false });
+		const summary = `Planned ${aggregateOps.length} operation(s) across ${orderedResolutions.length} space(s)`;
+		return wrapPlanResult({
+			operations: aggregateOps,
+			destination: appPlan.destination,
+			preview,
+			perSpace,
+			summary,
+			...ifDefined("warnings", plannerWarnings)
+		});
+	}
+	if (options.consentedPlanHash !== void 0) {
+		const planHash = computePlanHash({
+			operations: stripOperations(orderedResolutions.flatMap((r) => r.entry.displayOps)),
+			destination: appPlan.destination
+		});
+		if (planHash !== options.consentedPlanHash) return notOk({
+			code: "CONSENT_PLAN_MISMATCH",
+			summary: "The plan changed between consent and apply",
+			why: "The plan recomputed for the consented apply is not the plan that was consented to, so applying it could destroy something nobody agreed to.",
+			conflicts: void 0,
+			meta: void 0,
+			consentPlanMismatch: {
+				consentedPlanHash: options.consentedPlanHash,
+				planHash
+			},
+			...ifDefined("warnings", plannerWarnings)
+		});
+	}
+	const applied = await runMigration({
+		aggregate,
+		perSpacePlans: planResult.value.perSpace,
+		applyOrder: planResult.value.applyOrder,
+		driver,
+		familyInstance,
+		migrations,
+		frameworkComponents,
+		policy,
+		action,
+		...ifDefined("onProgress", onProgress)
+	});
+	if (!applied.ok) return buildRunnerFailure({
+		summary: applied.failure.summary,
+		...ifDefined("why", applied.failure.why),
+		meta: applied.failure.meta,
+		...ifDefined("warnings", plannerWarnings),
+		...ifDefined("cause", applied.failure.cause)
+	});
+	const aggregateOps = applied.value.orderedResolutions.flatMap((r) => r.entry.displayOps);
+	const summary = action === "dbInit" ? `Applied ${applied.value.totalOpsExecuted} operation(s) across ${applied.value.orderedResolutions.length} space(s), database signed` : applied.value.totalOpsExecuted === 0 ? `Database already matches contract across ${applied.value.orderedResolutions.length} space(s), signature updated` : `Applied ${applied.value.totalOpsExecuted} operation(s) across ${applied.value.orderedResolutions.length} space(s), signature updated`;
+	return wrapApplyResult({
+		operations: aggregateOps,
+		destination: appPlan.destination,
+		operationsPlanned: applied.value.totalOpsPlanned,
+		operationsExecuted: applied.value.totalOpsExecuted,
+		perSpace: applied.value.perSpace,
+		summary,
+		...ifDefined("warnings", plannerWarnings)
+	});
+}
+function aggregatePlannerWarnings(orderedResolutions) {
+	const warnings = orderedResolutions.flatMap((r) => r.entry.warnings ?? []);
+	return warnings.length > 0 ? warnings : void 0;
+}
+/**
+* Compare the live `_prisma_marker` rows against the aggregate's
+* declared contract spaces. Any marker row whose `space` is not a space of
+* the aggregate is an "orphan" — typically a marker left behind by
+* an extension that was removed from `extensions` without first
+* cleaning up its on-disk migrations / database tables.
+*
+* Returns a {@link CliStructuredError} envelope (code
+* `MIGRATION.CONTRACT_SPACE_VIOLATION`, `kind: 'orphanMarker'`) for the
+* first orphan it finds, or `null`
+* when every marker row maps to a declared contract space. Mirrors the M2
+* `runContractSpaceVerifierMarkerCheck` envelope so downstream
+* tooling (integration tests, JSON consumers) keeps asserting on the
+* same shape.
+*/
+function detectOrphanMarkers(aggregate, markerRows) {
+	const aggregateSpaceIds = /* @__PURE__ */ new Set([aggregate.app.spaceId, ...aggregate.extensions.map((m) => m.spaceId)]);
+	const orphans = [];
+	for (const [spaceId, row] of markerRows) if (row !== null && row !== void 0 && !aggregateSpaceIds.has(spaceId)) orphans.push(spaceId);
+	if (orphans.length === 0) return null;
+	orphans.sort((a, b) => a.localeCompare(b));
+	return new CliStructuredError$1("MIGRATION.CONTRACT_SPACE_VIOLATION", orphans.length === 1 ? `Orphan contract-space marker detected for "${orphans[0]}"` : `Orphan contract-space markers detected for ${orphans.length} spaces`, {
+		why: `The database has \`_prisma_marker\` rows for spaces (${orphans.map((s) => `"${s}"`).join(", ")}) that are not declared in the project's \`extensions\`. The aggregate pipeline refuses to advance markers it cannot account for.`,
+		fix: "Either re-declare the missing extension(s) in `extensions` (so the aggregate owns them again), or remove the orphan marker row(s) from `_prisma_marker` once you have confirmed the corresponding tables can be safely retired.",
+		docsUrl: "https://pris.ly/contract-spaces",
+		meta: { violations: orphans.map((spaceId) => ({
+			kind: "orphanMarker",
+			spaceId
+		})) }
+	});
+}
+function mapPlannerError(error) {
+	if (error.kind === "planFromDiffFailed") return blindCast(notOk({
+		code: "PLANNING_FAILED",
+		summary: "Migration planning failed due to conflicts",
+		conflicts: error.conflicts,
+		why: void 0,
+		meta: void 0
+	}));
+	if (error.kind === "extensionPathUnreachable") return buildRunnerFailure({
+		summary: `Cannot resolve apply path for extension space "${error.spaceId}"`,
+		why: `No path in the on-disk migration graph for extension space "${error.spaceId}" reaches the on-disk head ref hash "${error.target}".`,
+		meta: {
+			spaceId: error.spaceId,
+			target: error.target
+		}
+	});
+	if (error.kind === "extensionPathUnsatisfiable") return buildRunnerFailure({
+		summary: `Cannot resolve apply path for extension space "${error.spaceId}"`,
+		why: `On-disk migration graph for extension space "${error.spaceId}" reaches the on-disk head ref but does not cover required invariants: ${error.missingInvariants.join(", ")}.`,
+		meta: {
+			spaceId: error.spaceId,
+			missingInvariants: error.missingInvariants
+		}
+	});
+	return buildRunnerFailure({
+		summary: `Aggregate planner policy conflict for space "${error.spaceId}"`,
+		why: error.detail,
+		meta: { spaceId: error.spaceId }
+	});
+}
+function wrapPlanResult(args) {
+	return ok({
+		mode: "plan",
+		plan: {
+			operations: stripOperations(args.operations),
+			...ifDefined("preview", args.preview)
+		},
+		destination: {
+			storageHash: args.destination.storageHash,
+			...ifDefined("profileHash", args.destination.profileHash)
+		},
+		perSpace: args.perSpace,
+		summary: args.summary,
+		...ifDefined("warnings", args.warnings)
+	});
+}
+function wrapApplyResult(args) {
+	return ok({
+		mode: "apply",
+		plan: { operations: stripOperations(args.operations) },
+		destination: {
+			storageHash: args.destination.storageHash,
+			...ifDefined("profileHash", args.destination.profileHash)
+		},
+		execution: {
+			operationsPlanned: args.operationsPlanned,
+			operationsExecuted: args.operationsExecuted
+		},
+		marker: args.destination.profileHash ? {
+			storageHash: args.destination.storageHash,
+			profileHash: args.destination.profileHash
+		} : { storageHash: args.destination.storageHash },
+		perSpace: args.perSpace,
+		summary: args.summary,
+		...ifDefined("warnings", args.warnings)
+	});
+}
+function buildRunnerFailure(args) {
+	return blindCast(notOk({
+		code: "RUNNER_FAILED",
+		summary: args.summary,
+		why: args.why,
+		meta: args.meta,
+		conflicts: void 0,
+		...ifDefined("warnings", args.warnings),
+		...ifDefined("cause", args.cause)
+	}));
+}
+/**
+* Execute `db init` against the configured contract.
+*
+* Routes through the loader → planner → runner pipeline (sub-spec
+* "Commit-by-commit § Commit 4"). Always additive-only; destructive
+* changes belong to `db update`.
+*/
+async function executeDbInit(options) {
+	return await executeRun({
+		driver: options.driver,
+		adapter: options.adapter,
+		familyInstance: options.familyInstance,
+		contract: options.contract,
+		mode: options.mode,
+		migrations: options.migrations,
+		frameworkComponents: options.frameworkComponents,
+		migrationsDir: options.migrationsDir,
+		targetId: options.targetId,
+		extensions: options.extensions ?? [],
+		policy: { allowedOperationClasses: ["additive"] },
+		action: "dbInit",
+		...ifDefined("onProgress", options.onProgress)
+	});
+}
+const DB_UPDATE_POLICY = { allowedOperationClasses: [
+	"additive",
+	"widening",
+	"destructive"
+] };
+/**
+* Execute `db update` against the configured contract.
+*
+* Routes through the loader → planner → runner pipeline. Destructive
+* operations require either `acceptDataLoss: true` or a prior
+* `mode: 'plan'` invocation that surfaces the destructive ops; the
+* confirmation gate is implemented here so the lower-level applier
+* remains policy-agnostic.
+*/
+async function executeDbUpdate(options) {
+	const sharedInputs = {
+		driver: options.driver,
+		adapter: options.adapter,
+		familyInstance: options.familyInstance,
+		contract: options.contract,
+		migrations: options.migrations,
+		frameworkComponents: options.frameworkComponents,
+		migrationsDir: options.migrationsDir,
+		targetId: options.targetId,
+		extensions: options.extensions ?? [],
+		policy: DB_UPDATE_POLICY,
+		action: "dbUpdate",
+		...ifDefined("onProgress", options.onProgress)
+	};
+	if (options.mode === "apply" && !options.acceptDataLoss && options.consent === void 0) {
+		const refusal = await guardDestructiveChanges(sharedInputs);
+		if (refusal !== null) return refusal;
+	}
+	return await executeRun({
+		...sharedInputs,
+		mode: options.mode,
+		...ifDefined("consentedPlanHash", options.consent?.planHash)
+	});
+}
+/**
+* Pre-plan once when running `db update apply` without `acceptDataLoss`.
+* Surfaces destructive operations across every space; if any are
+* planned, returns a `DESTRUCTIVE_CHANGES` failure that the CLI shows
+* as a confirmation prompt. Returns `null` when the apply is safe to
+* run.
+*/
+async function guardDestructiveChanges(sharedInputs) {
+	const planResult = await executeRun({
+		...sharedInputs,
+		mode: "plan"
+	});
+	if (!planResult.ok) return planResult;
+	const destructiveOps = planResult.value.plan.operations.filter((op) => op.operationClass === "destructive").map((op) => ({
+		id: op.id,
+		label: op.label
+	}));
+	if (destructiveOps.length === 0) return null;
+	const databaseName = await sharedInputs.driver.databaseName?.();
+	return notOk({
+		code: "DESTRUCTIVE_CHANGES",
+		summary: `Planned ${destructiveOps.length} destructive operation(s) that require confirmation`,
+		why: "Destructive operations require explicit consent, which the caller has not given",
+		conflicts: void 0,
+		meta: void 0,
+		destructiveChanges: {
+			destructiveOperations: destructiveOps,
+			databaseName,
+			planHash: computePlanHash({
+				operations: planResult.value.plan.operations,
+				destination: planResult.value.destination
+			})
+		},
+		...ifDefined("warnings", planResult.value.warnings)
+	});
+}
+/**
+* Span IDs emitted via `onProgress` during the aggregate verify flow.
+* Mirrors the span identifiers used by the legacy precheck / marker-check
+* helpers so structured-output renderers and progress tests keep working.
+*/
+const SPAN_IDS = {
+	introspect: "introspect",
+	verify: "verify"
+};
+/**
+* Loader → verifier pipeline shared by `db verify` modes (`full`,
+* `marker-only`, `schema-only`).
+*
+* 1. **Load**: build a {@link import('@internal/migration-tools/aggregate').ContractSpaceAggregate}
+*    from descriptors + on-disk on-disk artefacts. Layout / drift /
+*    integrity / disjointness violations short-circuit with a
+*    structured CLI error.
+* 2. **Read DB state**: marker rows + (when `skipSchema` is `false`)
+*    schema introspection.
+* 3. **Verify**: {@link verifyMigration} returns per-space `markerCheck` +
+*    per-space `schemaCheck` (each contract space verified against the full schema,
+*    then scoped to its own contract space). Marker drift is returned as the
+*    success value's `markerDrift` envelope for callers to settle as a
+*    finding. Verify results are returned to the caller verbatim.
+*/
+async function executeDbVerify(options) {
+	const { driver, familyInstance, onProgress, skipSchema, skipMarker } = options;
+	const loaded = await buildContractSpaceAggregate(buildLoadInputs(options));
+	if (!loaded.ok) return notOk(loaded.failure);
+	const aggregate = loaded.value;
+	const markersBySpaceId = await familyInstance.readAllMarkers({ driver });
+	const schemaIntrospection = skipSchema ? null : await runIntrospection({
+		driver,
+		familyInstance,
+		onProgress,
+		contract: collectAggregateNamespaces(aggregate)
+	});
+	const classifySubjectGranularity = hasSchemaSubjectClassifier(familyInstance) ? (issue) => familyInstance.classifySubjectGranularity(issue) : void 0;
+	const classifyEntityKind = hasSchemaSubjectClassifier(familyInstance) ? (issue) => familyInstance.classifyEntityKind(issue) : void 0;
+	emitVerifySpan(onProgress, "spanStart");
+	return finaliseVerifyResult({
+		verifyResult: verifyMigration({
+			aggregate,
+			markersBySpaceId,
+			schemaIntrospection,
+			mode: options.mode,
+			verifySchemaForSpace: createPerSpaceVerifier(options),
+			...ifDefined("classifySubjectGranularity", classifySubjectGranularity),
+			...ifDefined("classifyEntityKind", classifyEntityKind)
+		}),
+		aggregate,
+		skipMarker,
+		onProgress,
+		migrationsDir: options.migrationsDir
+	});
+}
+function buildLoadInputs(options) {
+	return {
+		targetId: options.targetId,
+		migrationsDir: options.migrationsDir,
+		appContract: options.contract,
+		extensions: options.extensions,
+		deserializeContract: (json) => options.familyInstance.deserializeContract(json)
+	};
+}
+async function runIntrospection(args) {
+	const { driver, familyInstance, onProgress, contract } = args;
+	onProgress?.({
+		action: "dbVerify",
+		kind: "spanStart",
+		spanId: SPAN_IDS.introspect,
+		label: "Introspecting database schema"
+	});
+	try {
+		const result = await familyInstance.introspect({
+			driver,
+			contract
+		});
+		onProgress?.({
+			action: "dbVerify",
+			kind: "spanEnd",
+			spanId: SPAN_IDS.introspect,
+			outcome: "ok"
+		});
+		return result;
+	} catch (error) {
+		onProgress?.({
+			action: "dbVerify",
+			kind: "spanEnd",
+			spanId: SPAN_IDS.introspect,
+			outcome: "error"
+		});
+		throw error;
+	}
+}
+/**
+* Build the per-space schema callback handed to the aggregate verifier.
+* When `skipSchema` is true the callback short-circuits with a synthetic
+* `ok` result so the verifier still runs the (cheap) schemaCheck loop
+* without invoking the family's verification path.
+*/
+function createPerSpaceVerifier(options) {
+	const { skipSchema, familyInstance, frameworkComponents } = options;
+	return (schema, space, verifyMode) => {
+		if (skipSchema) return buildSkippedSchemaResult(space);
+		return familyInstance.verifySchema({
+			contract: space.contract(),
+			schema,
+			strict: verifyMode === "strict",
+			frameworkComponents
+		});
+	};
+}
+function emitVerifySpan(onProgress, kind) {
+	if (kind === "spanStart") {
+		onProgress?.({
+			action: "dbVerify",
+			kind: "spanStart",
+			spanId: SPAN_IDS.verify,
+			label: "Verifying contract spaces"
+		});
+		return;
+	}
+	onProgress?.({
+		action: "dbVerify",
+		kind: "spanEnd",
+		spanId: SPAN_IDS.verify,
+		outcome: kind === "spanEndOk" ? "ok" : "error"
+	});
+}
+/**
+* Map an {@link VerifierOutput} to the operation's
+* {@link ExecuteDbVerifyResult}, applying the `skipMarker` policy used
+* by the CLI's `--schema-only` mode.
+*/
+function finaliseVerifyResult(args) {
+	const { verifyResult, aggregate, skipMarker, onProgress, migrationsDir } = args;
+	if (!verifyResult.ok) {
+		emitVerifySpan(onProgress, "spanEndError");
+		return notOk(new CliStructuredError$1("MIGRATION.CONTRACT_SPACE_VIOLATION", "Aggregate verifier introspection failed", {
+			why: verifyResult.failure.detail,
+			fix: "Check database connectivity and the introspection tooling.",
+			docsUrl: "https://pris.ly/contract-spaces"
+		}));
+	}
+	const markerDrift = skipMarker ? null : mapMarkerCheckFailures(aggregate.app.spaceId, verifyResult.value.markerCheck, migrationsDir);
+	emitVerifySpan(onProgress, markerDrift === null ? "spanEndOk" : "spanEndError");
+	return ok({
+		schemaResults: verifyResult.value.schemaCheck.perSpace,
+		unclaimed: verifyResult.value.schemaCheck.unclaimed,
+		spaceOrder: [aggregate.app.spaceId, ...aggregate.extensions.map((e) => e.spaceId)],
+		appSpaceId: aggregate.app.spaceId,
+		markerDrift
+	});
+}
+function buildSkippedSchemaResult(space) {
+	const contract = space.contract();
+	const headRef = requireHeadRef(space);
+	const profileHash = castAs(contract).profileHash;
+	return {
+		ok: true,
+		summary: "Schema verification skipped",
+		contract: {
+			storageHash: headRef.hash,
+			...profileHash ? { profileHash } : {}
+		},
+		target: { expected: contract.target },
+		schema: { issues: [] },
+		timings: { total: 0 }
+	};
+}
+/**
+* Translate per-space marker check failures and orphan markers into a
+* single CLI structured error envelope. Preserves the legacy code
+* `MIGRATION.CONTRACT_SPACE_VIOLATION` (was emitted by
+* `runContractSpaceVerifierMarkerCheck`).
+*/
+function mapMarkerCheckFailures(appSpaceId, section, migrationsDir) {
+	const violations = [];
+	for (const [spaceId, result] of section.perSpace) {
+		if (result.kind === "ok" || result.kind === "absent") continue;
+		if (result.kind === "hashMismatch") {
+			violations.push({
+				kind: "hashMismatch",
+				spaceId,
+				remediation: spaceId === appSpaceId ? "Run `{bin} db update` to advance the marker, or roll the database back to the recorded hash." : `Apply on-disk migrations under \`${migrationsDir}/${spaceId}/\` to advance the marker, or remove the conflicting marker row.`
+			});
+			continue;
+		}
+		if (result.kind === "missingInvariants") violations.push({
+			kind: "invariantsMismatch",
+			spaceId,
+			remediation: `Re-apply the migrations under \`${migrationsDir}/${spaceId}/\` so the marker carries invariants: ${result.missing.join(", ")}.`
+		});
+	}
+	for (const orphan of section.orphanMarkers) violations.push({
+		kind: "orphanMarker",
+		spaceId: orphan.spaceId,
+		remediation: `Add the corresponding extension to \`extensions\` in \`prisma.config.ts\`, or delete the orphan marker row for "${orphan.spaceId}".`
+	});
+	if (violations.length === 0) return null;
+	const lines = violations.map((v) => `- [${v.kind}] ${v.spaceId}: ${v.remediation}`);
+	return new CliStructuredError$1("MIGRATION.CONTRACT_SPACE_VIOLATION", violations.length === 1 ? "Contract-space verifier found a violation" : `Contract-space verifier found violations (${violations.length})`, {
+		why: `The on-disk \`${migrationsDir}/\` directory, the \`extensions\` declaration, and the live database marker rows are not in agreement.\n${lines.join("\n")}`,
+		fix: violations[0]?.remediation ?? "Review and reconcile the violations listed above.",
+		docsUrl: "https://pris.ly/contract-spaces",
+		meta: { violations }
+	});
+}
+/**
+* Apply pending migrations across every contract space (app +
+* extensions). Replay-only: graph-walk against the on-disk graph for
+* every contract space; no synth, no introspection.
+*
+* Pipeline:
+*
+* 1. Load aggregate from disk (loader hydrates extension graphs;
+*    caller provides app-space packages).
+* 2. Read live marker rows per space (`familyInstance.readAllMarkers`).
+* 3. Per space: `resolveRecordedPath` plots the path from the live
+*    marker to `space.headRef.hash` (or `refHash` for the app
+*    space when provided). An empty-graph space whose elements are ALL
+*    externally managed resolves declaratively (marker to head, zero
+*    ops), mirroring the db-init aggregate planner: such a space ships
+*    no DDL and has nothing to author. Every other empty-graph space
+*    fails loudly — "never planned" is a user-error condition for
+*    replay.
+* 4. Hand off to {@link runMigration} (the runner-driving tail
+*    shared with `db init` / `db update`). Marker advancement is
+*    inside the per-space transaction.
+*
+* Encodes the replay-only contract: the app contract space must have an
+* authored migration graph on disk before this operation can advance it.
+*/
+async function executeMigrate(options) {
+	const { driver, familyInstance, contract, migrations, frameworkComponents, migrationsDir, extensions, targetId, refHash, refInvariants, refName, onProgress } = options;
+	const loaded = await buildContractSpaceAggregate({
+		targetId,
+		migrationsDir,
+		appContract: contract,
+		extensions,
+		deserializeContract: (json) => familyInstance.deserializeContract(json)
+	});
+	if (!loaded.ok) throw loaded.failure;
+	const aggregate = loaded.value;
+	const markerRows = await familyInstance.readAllMarkers({ driver });
+	const allSpaces = [aggregate.app, ...aggregate.extensions];
+	const perSpacePlans = /* @__PURE__ */ new Map();
+	const atHeadResolutions = /* @__PURE__ */ new Map();
+	for (const space of allSpaces) {
+		const isAppSpace = space.spaceId === aggregate.app.spaceId;
+		const headRef = requireHeadRef(space);
+		const spaceTargetHash = isAppSpace && refHash !== void 0 ? refHash : headRef.hash;
+		const outcome = planSpacePath({
+			space,
+			aggregate,
+			targetHash: spaceTargetHash,
+			refInvariants: isAppSpace && refHash !== void 0 ? refInvariants : void 0,
+			liveMarker: markerRows.get(space.spaceId) ?? null,
+			...isAppSpace ? { refName } : {}
+		});
+		if (outcome.kind === "at-head") {
+			atHeadResolutions.set(space.spaceId, outcome.plan);
+			continue;
+		}
+		if (outcome.kind === "never-planned") return notOk(buildNeverPlannedFailure(outcome.spaceId, outcome.targetHash, migrationsDir));
+		if (outcome.kind === "unreachable") return notOk(buildPathNotFoundFailure(outcome.spaceId, outcome.liveMarker, outcome.targetHash));
+		if (outcome.kind === "unsatisfiable") {
+			const structural = findPathWithDecision(outcome.targetSpace.graph(), outcome.liveHash, spaceTargetHash, { required: /* @__PURE__ */ new Set() });
+			const structuralPath = structural.kind === "ok" ? structural.decision.selectedPath.map((edge) => ({
+				dirName: edge.dirName,
+				migrationHash: edge.migrationHash,
+				from: edge.from,
+				to: edge.to,
+				invariants: edge.invariants
+			})) : [];
+			throw errorNoInvariantPath({
+				...outcome.refName !== void 0 ? { refName: outcome.refName } : {},
+				required: outcome.targetInvariants,
+				missing: outcome.missing,
+				structuralPath
+			});
+		}
+		perSpacePlans.set(space.spaceId, outcome.plan);
+	}
+	const canonicalOrder = [...aggregate.extensions.map((m) => m.spaceId), aggregate.app.spaceId];
+	const applyOrder = canonicalOrder.filter((spaceId) => perSpacePlans.has(spaceId));
+	if (!applyOrder.some((spaceId) => {
+		const entry = perSpacePlans.get(spaceId);
+		return entry !== void 0 && planRequiresExecution(entry);
+	})) {
+		const ordered = canonicalOrder.filter((spaceId) => perSpacePlans.has(spaceId) || atHeadResolutions.has(spaceId)).map((spaceId) => {
+			const entry = perSpacePlans.get(spaceId) ?? atHeadResolutions.get(spaceId);
+			if (entry === void 0) throw new InternalError(`Unreachable: missing per-space plan for "${spaceId}"`);
+			return {
+				spaceId,
+				entry
+			};
+		});
+		const perSpace = buildPerSpaceBreakdown(ordered, aggregate.app.spaceId, { includeMarkers: true });
+		const totalSpaces = ordered.length;
+		return ok(buildSuccess({
+			aggregate,
+			orderedResolutions: ordered,
+			perSpace,
+			totalOpsExecuted: 0,
+			summary: totalSpaces === 0 ? "Already up to date — no contract spaces are loaded" : totalSpaces === 1 ? "Already up to date" : `Already up to date across ${totalSpaces} space(s)`
+		}));
+	}
+	const applied = await runMigration({
+		aggregate,
+		perSpacePlans,
+		applyOrder,
+		driver,
+		familyInstance,
+		migrations,
+		frameworkComponents,
+		policy: { allowedOperationClasses: [
+			"additive",
+			"widening",
+			"destructive",
+			"data"
+		] },
+		action: "migrate",
+		...ifDefined("onProgress", onProgress)
+	});
+	if (!applied.ok) return notOk({
+		code: "RUNNER_FAILED",
+		summary: applied.failure.summary,
+		why: applied.failure.why,
+		meta: applied.failure.meta,
+		...ifDefined("cause", applied.failure.cause)
+	});
+	const orderedAll = canonicalOrder.filter((spaceId) => perSpacePlans.has(spaceId) || atHeadResolutions.has(spaceId)).map((spaceId) => {
+		if (perSpacePlans.has(spaceId)) {
+			const fromRunner = applied.value.orderedResolutions.find((r) => r.spaceId === spaceId);
+			if (fromRunner !== void 0) return fromRunner;
+		}
+		const entry = atHeadResolutions.get(spaceId);
+		if (entry === void 0) throw new InternalError(`Unreachable: missing per-space plan for "${spaceId}"`);
+		return {
+			spaceId,
+			entry
+		};
+	});
+	const perSpaceAll = buildPerSpaceBreakdown(orderedAll, aggregate.app.spaceId, { includeMarkers: true });
+	const summary = `Applied ${applied.value.orderedResolutions.reduce((sum, r) => sum + r.entry.migrationEdges.length, 0)} migration(s) (${applied.value.totalOpsExecuted} operation(s)) across ${orderedAll.length} contract space(s)`;
+	return ok(buildSuccess({
+		aggregate,
+		orderedResolutions: orderedAll,
+		perSpace: perSpaceAll,
+		totalOpsExecuted: applied.value.totalOpsExecuted,
+		summary
+	}));
+}
+/**
+* Compute the graph-walk path for one contract space.
+*
+* Encapsulates the invariant-correct input assembly that both
+* `executeMigrate` and `executeMigrateShowCommand` must use:
+* - `currentMarker` carries the full live marker including `invariants`
+*   (not a stripped `{ storageHash, invariants: [] }` shell).
+* - `targetInvariants` uses the caller-supplied `refInvariants` when a
+*   `--to` ref was resolved (not always the file head ref's invariants).
+*
+* Both callers map the returned `SpacePathOutcome` to their own error
+* representation; the path-compute logic is shared and identical.
+*
+* @internal Exported for `executeMigrateShowCommand`.
+*/
+function planSpacePath({ space, aggregate, targetHash, refInvariants, liveMarker, refName }) {
+	const isAppSpace = space.spaceId === aggregate.app.spaceId;
+	const headRef = requireHeadRef(space);
+	if (space.graph().nodes.size === 0) {
+		const liveHash = liveMarker?.storageHash;
+		if (targetHash === liveHash || liveHash === void 0 && targetHash === "empty") return {
+			kind: "at-head",
+			plan: buildAtHeadResolution({
+				aggregateTargetId: aggregate.targetId,
+				space,
+				targetHash,
+				liveMarker
+			})
+		};
+		if (!isAppSpace && allStorageElementsExternal(space.contract())) {
+			if (headRef.invariants.length > 0) return {
+				kind: "unsatisfiable",
+				spaceId: space.spaceId,
+				isAppSpace,
+				missing: [...headRef.invariants].sort(),
+				targetInvariants: headRef.invariants,
+				targetSpace: space,
+				liveHash: liveHash ?? "empty",
+				refName: void 0
+			};
+			return {
+				kind: "ok",
+				plan: buildAtHeadResolution({
+					aggregateTargetId: aggregate.targetId,
+					space,
+					targetHash,
+					liveMarker
+				})
+			};
+		}
+		return {
+			kind: "never-planned",
+			spaceId: space.spaceId,
+			targetHash
+		};
+	}
+	const targetInvariants = isAppSpace && refInvariants !== void 0 ? refInvariants : headRef.invariants;
+	const targetSpace = targetHash === headRef.hash && targetInvariants === headRef.invariants ? space : {
+		...space,
+		headRef: {
+			hash: targetHash,
+			invariants: targetInvariants
+		}
+	};
+	const walked = resolveRecordedPath({
+		aggregateTargetId: aggregate.targetId,
+		space: targetSpace,
+		currentMarker: liveMarker,
+		...isAppSpace && refName !== void 0 ? { refName } : {}
+	});
+	if (walked.kind === "unreachable") return {
+		kind: "unreachable",
+		spaceId: space.spaceId,
+		liveMarker,
+		targetHash
+	};
+	if (walked.kind === "unsatisfiable") {
+		const liveHash = liveMarker?.storageHash ?? "empty";
+		return {
+			kind: "unsatisfiable",
+			spaceId: space.spaceId,
+			isAppSpace,
+			missing: walked.missing,
+			targetInvariants,
+			targetSpace,
+			liveHash,
+			refName
+		};
+	}
+	return {
+		kind: "ok",
+		plan: walked.result
+	};
+}
+/**
+* Build a zero-op {@link PerSpacePlan} for an empty-graph space —
+* either one whose live marker already matches the target (at-head), or
+* an all-external extension space whose marker must advance to the head
+* ref with no DDL (declared-state). Lets the apply pipeline thread the
+* space through `perSpacePlans` -> `applyOrder` -> the success
+* envelope's `perSpace[]` block so the result reflects every loaded
+* space, even when there is nothing to execute.
+*/
+function buildAtHeadResolution(args) {
+	const { aggregateTargetId, space, targetHash, liveMarker } = args;
+	return {
+		plan: {
+			targetId: aggregateTargetId,
+			spaceId: space.spaceId,
+			origin: liveMarker === null ? null : { storageHash: liveMarker.storageHash },
+			destination: { storageHash: targetHash },
+			operations: [],
+			providedInvariants: []
+		},
+		displayOps: [],
+		destinationContract: space.contract(),
+		strategy: "declared-state",
+		migrationEdges: [buildFabricatedMigrationEdge({
+			currentMarkerStorageHash: liveMarker?.storageHash,
+			destinationStorageHash: targetHash,
+			operationCount: 0
+		})]
+	};
+}
+/**
+* A plan needs the runner when it executes operations or advances the
+* space's marker (a declared-state resolution has zero operations but a
+* destination hash the live marker doesn't carry yet).
+*/
+function planRequiresExecution(entry) {
+	if (entry.plan.operations.length > 0) return true;
+	return entry.plan.origin?.storageHash !== entry.plan.destination.storageHash;
+}
+function buildSuccess(args) {
+	const appResolution = args.orderedResolutions.find((r) => r.spaceId === args.aggregate.app.spaceId);
+	const appMarkerHash = appResolution?.entry.plan.destination.storageHash ?? requireHeadRef(args.aggregate.app).hash;
+	const applied = args.orderedResolutions.flatMap((r) => {
+		return r.entry.migrationEdges.map((edge) => ({
+			spaceId: r.spaceId,
+			dirName: edge.dirName,
+			migrationHash: edge.migrationHash,
+			from: edge.from,
+			to: edge.to,
+			operationsExecuted: edge.operationCount
+		}));
+	});
+	const appPlan = appResolution?.entry;
+	const pathDecision = appPlan?.pathDecision ? {
+		fromHash: appPlan.pathDecision.fromHash,
+		toHash: appPlan.pathDecision.toHash,
+		alternativeCount: appPlan.pathDecision.alternativeCount,
+		tieBreakReasons: appPlan.pathDecision.tieBreakReasons,
+		...appPlan.pathDecision.refName !== void 0 ? { refName: appPlan.pathDecision.refName } : {},
+		requiredInvariants: appPlan.pathDecision.requiredInvariants ?? [],
+		satisfiedInvariants: appPlan.pathDecision.satisfiedInvariants ?? [],
+		selectedPath: appPlan.pathDecision.selectedPath.map((entry) => ({
+			dirName: entry.dirName,
+			migrationHash: entry.migrationHash,
+			from: entry.from,
+			to: entry.to,
+			invariants: entry.invariants
+		}))
+	} : void 0;
+	return {
+		migrationsApplied: applied.length,
+		markerHash: appMarkerHash,
+		applied,
+		summary: args.summary,
+		perSpace: args.perSpace,
+		...pathDecision !== void 0 ? { pathDecision } : {}
+	};
+}
+/**
+* Build the `neverPlanned` failure raised when a contract space that
+* declares managed storage elements has no on-disk migration graph but
+* migrate was asked to reach a target hash. All-external spaces never reach
+* this: they resolve declaratively (marker advances to the head ref with
+* zero operations). The `why` states only the condition; the recovery
+* sequence is composed by `errorPathUnreachable`'s `fix`.
+*
+* @internal Exported for testing only.
+*/
+function buildNeverPlannedFailure(spaceId, targetHash, migrationsDir) {
+	return {
+		code: "MIGRATION_PATH_NOT_FOUND",
+		summary: `No on-disk migrations for contract space "${spaceId}"`,
+		why: `migrate is replay-only: a contract space that declares managed storage elements must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`${migrationsDir}/${spaceId}/\` but its head ref targets "${targetHash}".`,
+		meta: {
+			spaceId,
+			target: targetHash,
+			kind: "neverPlanned"
+		}
+	};
+}
+/**
+* Build the `pathUnreachable` failure raised when an emitted contract has no
+* on-disk migration edge from the current marker to the target. The `why`
+* states only the condition (no edge between the two named states, and migrate
+* replays edges rather than inventing them); the recovery sequence — plan the
+* edge, then re-apply — is composed by `errorPathUnreachable`'s `fix`, so the
+* two read as one non-redundant plan-then-apply story.
+*
+* @internal Exported for testing only.
+*/
+function buildPathNotFoundFailure(spaceId, marker, targetHash) {
+	const fromHash = marker?.storageHash ?? "<empty>";
+	return {
+		code: "MIGRATION_PATH_NOT_FOUND",
+		summary: spaceId === "app" ? "Current contract has no planned migration path" : `Current contract has no planned migration path for contract space "${spaceId}"`,
+		why: `No migration edge connects the current state "${fromHash}" to the target "${targetHash}" in contract space "${spaceId}". The on-disk migration graph does not join the two, and migrate replays existing edges — it never invents one.`,
+		meta: {
+			spaceId,
+			fromHash,
+			targetHash,
+			kind: "pathUnreachable"
+		}
+	};
+}
+/**
+* Creates a programmatic control client for Prisma ORM operations.
+*
+* The client accepts framework component descriptors at creation time,
+* manages driver lifecycle via connect()/close(), and exposes domain
+* operations that delegate to the existing family instance methods.
+*
+* @see {@link ControlClient} for the client interface
+* @see README.md "Programmatic Control API" section for usage examples
+*/
+function createControlClient(options) {
+	return new ControlClientImpl(options);
+}
+/**
+* Implementation of ControlClient.
+* Manages initialization and connection state, delegates operations to family instance.
+*/
+var ControlClientImpl = class {
+	options;
+	stack = null;
+	driver = null;
+	familyInstance = null;
+	frameworkComponents = null;
+	initialized = false;
+	defaultConnection;
+	constructor(options) {
+		this.options = options;
+		this.defaultConnection = options.connection;
+	}
+	init() {
+		if (this.initialized) return;
+		this.stack = createControlStack({
+			family: this.options.family,
+			target: this.options.target,
+			adapter: this.options.adapter,
+			driver: this.options.driver,
+			extensions: this.options.extensions
+		});
+		this.familyInstance = this.options.family.create(this.stack);
+		const rawComponents = [
+			this.options.target,
+			this.options.adapter,
+			...this.options.extensions ?? []
+		];
+		this.frameworkComponents = assertFrameworkComponentsCompatible(this.options.family.familyId, this.options.target.targetId, rawComponents);
+		this.initialized = true;
+	}
+	async connect(connection) {
+		this.init();
+		if (this.driver) throw new CliStructuredError("DRIVER.ALREADY_CONNECTED", "Already connected. Call close() before reconnecting.");
+		const resolvedConnection = connection ?? this.defaultConnection;
+		if (resolvedConnection === void 0) throw new CliStructuredError("CONFIG.DB_CONNECTION_REQUIRED", "No connection provided. Pass a connection to connect() or provide a default connection when creating the client.");
+		if (!this.stack?.driver) throw new CliStructuredError("CONFIG.DRIVER_REQUIRED", "Driver is not configured. Pass a driver descriptor when creating the control client to enable database operations.");
+		this.driver = await this.stack.driver.create(resolvedConnection);
+	}
+	async close() {
+		if (this.driver) {
+			await this.driver.close();
+			this.driver = null;
+		}
+	}
+	/**
+	* Construct the control adapter once for a migration operation and return
+	* it, mirroring how the runtime plane builds the execution adapter once in
+	* `createExecutionStack`. Only `dbInit` / `dbUpdate` need it (it lowers the
+	* planner's DDL); read-only operations never build it. The descriptor is
+	* optional on the stack — targets without migrations omit it.
+	*/
+	buildControlAdapter() {
+		this.init();
+		if (!this.stack?.adapter) throw new CliStructuredError("MIGRATION.TARGET_UNSUPPORTED", `Target "${this.options.target.targetId}" requires an adapter for migrations`);
+		return this.stack.adapter.create(this.stack);
+	}
+	async ensureConnected() {
+		this.init();
+		if (!this.driver && this.defaultConnection !== void 0) await this.connect(this.defaultConnection);
+		if (!this.driver || !this.familyInstance || !this.frameworkComponents) throw new CliStructuredError("DRIVER.NOT_CONNECTED", "Not connected. Call connect(connection) first.");
+		return {
+			driver: this.driver,
+			familyInstance: this.familyInstance,
+			frameworkComponents: this.frameworkComponents
+		};
+	}
+	async connectWithProgress(connection, action, onProgress) {
+		if (connection === void 0) return;
+		onProgress?.({
+			action,
+			kind: "spanStart",
+			spanId: "connect",
+			label: "Connecting to database..."
+		});
+		try {
+			await this.connect(connection);
+			onProgress?.({
+				action,
+				kind: "spanEnd",
+				spanId: "connect",
+				outcome: "ok"
+			});
+		} catch (error) {
+			onProgress?.({
+				action,
+				kind: "spanEnd",
+				spanId: "connect",
+				outcome: "error"
+			});
+			throw error;
+		}
+	}
+	async verify(options) {
+		const { onProgress } = options;
+		await this.connectWithProgress(options.connection, "verify", onProgress);
+		const { driver, familyInstance } = await this.ensureConnected();
+		let contract;
+		try {
+			contract = familyInstance.deserializeContract(options.contract);
+		} catch (error) {
+			throw structuredError("CONTRACT.VALIDATION_FAILED", error instanceof Error ? error.message : String(error), { cause: error });
+		}
+		onProgress?.({
+			action: "verify",
+			kind: "spanStart",
+			spanId: "verify",
+			label: "Verifying database marker..."
+		});
+		try {
+			const result = await familyInstance.verify({
+				driver,
+				contract,
+				expectedTargetId: this.options.target.targetId,
+				contractPath: ""
+			});
+			onProgress?.({
+				action: "verify",
+				kind: "spanEnd",
+				spanId: "verify",
+				outcome: result.ok ? "ok" : "error"
+			});
+			return result;
+		} catch (error) {
+			onProgress?.({
+				action: "verify",
+				kind: "spanEnd",
+				spanId: "verify",
+				outcome: "error"
+			});
+			throw error;
+		}
+	}
+	async schemaVerify(options) {
+		const { onProgress } = options;
+		await this.connectWithProgress(options.connection, "schemaVerify", onProgress);
+		const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+		let contract;
+		try {
+			contract = familyInstance.deserializeContract(options.contract);
+		} catch (error) {
+			throw structuredError("CONTRACT.VALIDATION_FAILED", error instanceof Error ? error.message : String(error), { cause: error });
+		}
+		onProgress?.({
+			action: "schemaVerify",
+			kind: "spanStart",
+			spanId: "schemaVerify",
+			label: "Verifying database schema..."
+		});
+		try {
+			const schema = await familyInstance.introspect({
+				driver,
+				contract
+			});
+			const result = familyInstance.verifySchema({
+				contract,
+				schema,
+				strict: options.strict ?? false,
+				frameworkComponents
+			});
+			onProgress?.({
+				action: "schemaVerify",
+				kind: "spanEnd",
+				spanId: "schemaVerify",
+				outcome: result.ok ? "ok" : "error"
+			});
+			return result;
+		} catch (error) {
+			onProgress?.({
+				action: "schemaVerify",
+				kind: "spanEnd",
+				spanId: "schemaVerify",
+				outcome: "error"
+			});
+			throw error;
+		}
+	}
+	async sign(options) {
+		const { onProgress } = options;
+		await this.connectWithProgress(options.connection, "sign", onProgress);
+		const { driver, familyInstance } = await this.ensureConnected();
+		let contract;
+		try {
+			contract = familyInstance.deserializeContract(options.contract);
+		} catch (error) {
+			throw structuredError("CONTRACT.VALIDATION_FAILED", error instanceof Error ? error.message : String(error), { cause: error });
+		}
+		onProgress?.({
+			action: "sign",
+			kind: "spanStart",
+			spanId: "sign",
+			label: "Signing database..."
+		});
+		try {
+			const result = await familyInstance.sign({
+				driver,
+				contract,
+				contractPath: options.contractPath ?? "",
+				...ifDefined("configPath", options.configPath)
+			});
+			onProgress?.({
+				action: "sign",
+				kind: "spanEnd",
+				spanId: "sign",
+				outcome: "ok"
+			});
+			return result;
+		} catch (error) {
+			onProgress?.({
+				action: "sign",
+				kind: "spanEnd",
+				spanId: "sign",
+				outcome: "error"
+			});
+			throw error;
+		}
+	}
+	async dbInit(options) {
+		const { onProgress } = options;
+		await this.connectWithProgress(options.connection, "dbInit", onProgress);
+		const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+		if (!hasMigrations(this.options.target)) throw new CliStructuredError("MIGRATION.TARGET_UNSUPPORTED", `Target "${this.options.target.targetId}" does not support migrations`);
+		const adapter = this.buildControlAdapter();
+		let contract;
+		try {
+			contract = familyInstance.deserializeContract(options.contract);
+		} catch (error) {
+			throw structuredError("CONTRACT.VALIDATION_FAILED", error instanceof Error ? error.message : String(error), { cause: error });
+		}
+		return executeDbInit({
+			driver,
+			adapter,
+			familyInstance,
+			contract,
+			mode: options.mode,
+			migrations: this.options.target.migrations,
+			frameworkComponents,
+			migrationsDir: options.migrationsDir,
+			targetId: this.options.target.targetId,
+			extensions: this.options.extensions ?? [],
+			...ifDefined("onProgress", onProgress)
+		});
+	}
+	async dbUpdate(options) {
+		const { onProgress } = options;
+		await this.connectWithProgress(options.connection, "dbUpdate", onProgress);
+		const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+		if (!hasMigrations(this.options.target)) throw new CliStructuredError("MIGRATION.TARGET_UNSUPPORTED", `Target "${this.options.target.targetId}" does not support migrations`);
+		const adapter = this.buildControlAdapter();
+		let contract;
+		try {
+			contract = familyInstance.deserializeContract(options.contract);
+		} catch (error) {
+			throw structuredError("CONTRACT.VALIDATION_FAILED", error instanceof Error ? error.message : String(error), { cause: error });
+		}
+		return executeDbUpdate({
+			driver,
+			adapter,
+			familyInstance,
+			contract,
+			mode: options.mode,
+			migrations: this.options.target.migrations,
+			frameworkComponents,
+			migrationsDir: options.migrationsDir,
+			targetId: this.options.target.targetId,
+			extensions: this.options.extensions ?? [],
+			...ifDefined("acceptDataLoss", options.acceptDataLoss),
+			...ifDefined("consent", options.consent),
+			...ifDefined("onProgress", onProgress)
+		});
+	}
+	async dbVerify(options) {
+		const { onProgress } = options;
+		await this.connectWithProgress(options.connection, "dbVerify", onProgress);
+		const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+		return executeDbVerify({
+			driver,
+			familyInstance,
+			contract: options.contract,
+			migrationsDir: options.migrationsDir,
+			targetId: this.options.target.targetId,
+			extensions: this.options.extensions ?? [],
+			frameworkComponents,
+			mode: options.strict ? "strict" : "lenient",
+			skipSchema: options.skipSchema,
+			skipMarker: options.skipMarker,
+			...ifDefined("onProgress", onProgress)
+		});
+	}
+	async readMarker() {
+		const { driver, familyInstance } = await this.ensureConnected();
+		return familyInstance.readMarker({
+			driver,
+			space: APP_SPACE_ID
+		});
+	}
+	async readAllMarkers() {
+		const { driver, familyInstance } = await this.ensureConnected();
+		return familyInstance.readAllMarkers({ driver });
+	}
+	/** Reads the per-migration journal; omit `space` to return every space. */
+	async readLedger(space) {
+		const { driver, familyInstance } = await this.ensureConnected();
+		return familyInstance.readLedger({
+			driver,
+			...ifDefined("space", space)
+		});
+	}
+	async migrate(options) {
+		const { onProgress } = options;
+		await this.connectWithProgress(options.connection, "migrate", onProgress);
+		const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+		if (!hasMigrations(this.options.target)) throw new CliStructuredError("MIGRATION.TARGET_UNSUPPORTED", `Target "${this.options.target.targetId}" does not support migrations`);
+		let contract;
+		try {
+			contract = familyInstance.deserializeContract(options.contract);
+		} catch (error) {
+			throw structuredError("CONTRACT.VALIDATION_FAILED", error instanceof Error ? error.message : String(error), { cause: error });
+		}
+		return executeMigrate({
+			driver,
+			familyInstance,
+			contract,
+			migrations: this.options.target.migrations,
+			frameworkComponents,
+			migrationsDir: options.migrationsDir,
+			extensions: this.options.extensions ?? [],
+			targetId: this.options.target.targetId,
+			...ifDefined("refHash", options.refHash),
+			...ifDefined("refInvariants", options.refInvariants),
+			...ifDefined("refName", options.refName),
+			...ifDefined("onProgress", onProgress)
+		});
+	}
+	async introspect(options) {
+		const onProgress = options?.onProgress;
+		await this.connectWithProgress(options?.connection, "introspect", onProgress);
+		const { driver, familyInstance } = await this.ensureConnected();
+		options?.schema;
+		onProgress?.({
+			action: "introspect",
+			kind: "spanStart",
+			spanId: "introspect",
+			label: "Introspecting database schema..."
+		});
+		try {
+			const result = await familyInstance.introspect({ driver });
+			onProgress?.({
+				action: "introspect",
+				kind: "spanEnd",
+				spanId: "introspect",
+				outcome: "ok"
+			});
+			return result;
+		} catch (error) {
+			onProgress?.({
+				action: "introspect",
+				kind: "spanEnd",
+				spanId: "introspect",
+				outcome: "error"
+			});
+			throw error;
+		}
+	}
+	toSchemaView(schemaIR) {
+		this.init();
+		if (this.familyInstance && hasSchemaView(this.familyInstance)) return this.familyInstance.toSchemaView(schemaIR);
+	}
+	inferPslContract(schemaIR) {
+		this.init();
+		if (this.familyInstance && hasPslContractInfer(this.familyInstance)) return this.familyInstance.inferPslContract(schemaIR);
+	}
+	getPslBlockDescriptors() {
+		this.init();
+		return this.stack.authoringContributions.pslBlockDescriptors;
+	}
+	toOperationPreview(operations) {
+		this.init();
+		if (this.familyInstance && hasOperationPreview(this.familyInstance)) return this.familyInstance.toOperationPreview(operations);
+	}
+	async emit(options) {
+		const { onProgress, contractConfig } = options;
+		this.init();
+		if (!this.familyInstance) throw new InternalError("Family instance was not initialized. This is a bug.");
+		let contractRaw;
+		onProgress?.({
+			action: "emit",
+			kind: "spanStart",
+			spanId: "resolveSource",
+			label: "Resolving contract source..."
+		});
+		try {
+			const stack = this.stack;
+			const sourceContext = {
+				composedExtensions: stack.extensions.map((p) => p.id),
+				composedExtensionContracts: stack.extensionContracts,
+				authoringContributions: stack.authoringContributions,
+				codecLookup: stack.codecLookup,
+				controlMutationDefaults: stack.controlMutationDefaults,
+				resolvedInputs: contractConfig.source.inputs ?? [],
+				capabilities: stack.capabilities
+			};
+			const providerResult = await contractConfig.source.load(sourceContext);
+			if (!providerResult.ok) {
+				onProgress?.({
+					action: "emit",
+					kind: "spanEnd",
+					spanId: "resolveSource",
+					outcome: "error"
+				});
+				return notOk({
+					code: "CONTRACT_SOURCE_INVALID",
+					summary: providerResult.failure.summary,
+					why: providerResult.failure.summary,
+					meta: providerResult.failure.meta,
+					diagnostics: providerResult.failure
+				});
+			}
+			contractRaw = providerResult.value;
+			onProgress?.({
+				action: "emit",
+				kind: "spanEnd",
+				spanId: "resolveSource",
+				outcome: "ok"
+			});
+		} catch (error) {
+			onProgress?.({
+				action: "emit",
+				kind: "spanEnd",
+				spanId: "resolveSource",
+				outcome: "error"
+			});
+			const message = error instanceof Error ? error.message : String(error);
+			return notOk({
+				code: "CONTRACT_SOURCE_INVALID",
+				summary: "Failed to resolve contract source",
+				why: message,
+				diagnostics: {
+					summary: "Contract source provider threw an exception",
+					diagnostics: [{
+						code: "PROVIDER_THROW",
+						message
+					}]
+				},
+				meta: void 0
+			});
+		}
+		onProgress?.({
+			action: "emit",
+			kind: "spanStart",
+			spanId: "emit",
+			label: "Emitting contract..."
+		});
+		try {
+			const enrichedIR = enrichContract(contractRaw, this.frameworkComponents ?? []);
+			const rawContractJson = this.options.target.contractSerializer.serializeContract(enrichedIR);
+			let deserializedContract;
+			try {
+				deserializedContract = this.familyInstance.deserializeContract(rawContractJson);
+			} catch (error) {
+				onProgress?.({
+					action: "emit",
+					kind: "spanEnd",
+					spanId: "emit",
+					outcome: "error"
+				});
+				return notOk({
+					code: "CONTRACT_VALIDATION_FAILED",
+					summary: "Contract validation failed",
+					why: error instanceof Error ? error.message : String(error),
+					meta: void 0
+				});
+			}
+			const result = await emit(deserializedContract, this.stack, this.options.family.emission, {
+				serializeContract: (contract) => this.options.target.contractSerializer.serializeContract(contract),
+				...ifDefined("supportsNamespaces", this.options.target.supportsNamespaces)
+			});
+			onProgress?.({
+				action: "emit",
+				kind: "spanEnd",
+				spanId: "emit",
+				outcome: "ok"
+			});
+			return ok({
+				storageHash: result.storageHash,
+				...ifDefined("executionHash", result.executionHash),
+				profileHash: result.profileHash,
+				contractJson: result.contractJson,
+				contractDts: result.contractDts
+			});
+		} catch (error) {
+			onProgress?.({
+				action: "emit",
+				kind: "spanEnd",
+				spanId: "emit",
+				outcome: "error"
+			});
+			return notOk({
+				code: "EMIT_FAILED",
+				summary: "Failed to emit contract",
+				why: error instanceof Error ? error.message : String(error),
+				meta: void 0
+			});
+		}
+	}
+};
+/**
+* Per-output FIFO queue for `executeContractEmit`.
+*
+* Ensures that at most one emit (load → resolve source → emit bytes → publish)
+* runs per output JSON path at a time. Concurrent calls for the same path
+* line up behind the in-flight one and run in submission order; the user-visible
+* outcome is "last submission wins on disk" without any supersession bookkeeping.
+*
+* Long-lived hosts (Vite dev server, watch CLIs) must call `disposeEmitQueue`
+* when they stop publishing to a path, otherwise the module-global `Map`
+* accumulates one entry per unique output path for the lifetime of the process.
+*/
+const emitQueues = /* @__PURE__ */ new Map();
+function queueEmitByOutput(outputJsonPath, action) {
+	const next = (emitQueues.get(outputJsonPath) ?? Promise.resolve()).then(action, action);
+	emitQueues.set(outputJsonPath, next);
+	return next;
+}
+function disposeEmitQueue(outputJsonPath) {
+	emitQueues.delete(outputJsonPath);
+}
+/**
+* The import root of the project being emitted for, read from its own
+* manifest.
+*
+* Generated files are kept by the application, so every package name in them
+* has to be one the application can resolve — which means one of its direct
+* dependencies (ADR 242). The application already states those in
+* `package.json`, so emission reads them instead of taking a mode from
+* configuration that could disagree with what is installed.
+*/
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies"];
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The error codes that mean "no manifest here", as opposed to "cannot read it". */
+const MANIFEST_ABSENT_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR"]);
+function errorCode(error) {
+	if (!isRecord$2(error)) return void 0;
+	const code = error["code"];
+	return typeof code === "string" ? code : void 0;
+}
+/**
+* The nearest `package.json` at or above `from`, or `undefined` if there is
+* none. The nearest one wins: a package inside a workspace states its own
+* dependencies, and the workspace root's are somebody else's.
+*
+* @throws {CliStructuredError} when a manifest is there but cannot be used —
+* unreadable, not valid JSON, or not a JSON object. Only "there is no manifest
+* at this level" continues the walk up; treating a permissions failure that
+* way would silently emit against the wrong project's dependencies.
+*/
+function nearestManifest(from) {
+	let dir = from;
+	while (true) {
+		const path = join(dir, "package.json");
+		let raw;
+		try {
+			raw = readFileSync(path, "utf8");
+		} catch (cause) {
+			if (!MANIFEST_ABSENT_CODES.has(errorCode(cause) ?? "")) throw errorRuntime("CLI.PROJECT_MANIFEST_UNREADABLE", `Failed to read ${path}`, {
+				why: `\`${path}\` exists but could not be read: ${cause instanceof Error ? cause.message : String(cause)}`,
+				fix: `Make \`${path}\` readable, then re-run the command. Emission reads it to decide which package names generated files should import.`,
+				meta: { path },
+				cause
+			});
+			const parent = dirname(dir);
+			if (parent === dir) return void 0;
+			dir = parent;
+			continue;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch (cause) {
+			throw errorRuntime("CLI.PROJECT_MANIFEST_INVALID", `Failed to parse ${path}`, {
+				why: `\`${path}\` is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+				fix: `Fix the JSON syntax in \`${path}\` (a missing comma or unbalanced brace is the most common cause), then re-run the command. Emission reads it to decide which package names generated files should import.`,
+				meta: { path },
+				cause
+			});
+		}
+		if (!isRecord$2(parsed)) throw errorRuntime("CLI.PROJECT_MANIFEST_INVALID", `Failed to read ${path}`, {
+			why: `\`${path}\` is valid JSON but not a JSON object, so it states no dependencies.`,
+			fix: `Make \`${path}\` a JSON object with the usual manifest fields, then re-run the command. Emission reads it to decide which package names generated files should import.`,
+			meta: { path }
+		});
+		return parsed;
+	}
+}
+function declaredDependencies(manifest) {
+	return DEPENDENCY_FIELDS.flatMap((field) => {
+		const value = manifest[field];
+		return isRecord$2(value) ? Object.keys(value) : [];
+	});
+}
+/**
+* The import root for the project that owns `configPath`, or for the working
+* directory when the config was discovered rather than named.
+*
+* A project with no manifest, or one that names no published package, is on
+* the internal root — which emits every specifier exactly as authored, so a
+* project that has not moved to published names is unaffected.
+*/
+function projectImportRoot(configPath) {
+	const manifest = nearestManifest(configPath === void 0 ? resolve(".") : dirname(resolve(configPath)));
+	if (manifest === void 0) return internalImportRoot;
+	return importRootForDependencies(declaredDependencies(manifest));
+}
+/** The specifier resolver emission should use for the project owning `configPath`. */
+function createProjectSpecifierResolver(configPath) {
+	return createImportSpecifierResolver(projectImportRoot(configPath));
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null;
+}
+function createTempArtifactPath(path, publicationToken, phase) {
+	return join(dirname(path), `.${basename(path)}.${process.pid}.${publicationToken}.${phase}.tmp`);
+}
+async function readExistingArtifact(path) {
+	try {
+		return { content: await readFile(path, "utf-8") };
+	} catch (error) {
+		if (isRecord$1(error) && error["code"] === "ENOENT") return "remove";
+		throw error;
+	}
+}
+async function restoreArtifact(path, previous, publicationToken) {
+	if (previous === "remove") {
+		await rm(path, { force: true });
+		return;
+	}
+	const restorePath = createTempArtifactPath(path, publicationToken, "rollback");
+	await writeFile(restorePath, previous.content, "utf-8");
+	try {
+		await rename(restorePath, path);
+	} finally {
+		await rm(restorePath, { force: true });
+	}
+}
+function withRollbackFailureCause(error, rollbackFailures) {
+	const rollbackCause = new AggregateError(rollbackFailures, "Failed to restore published artifacts");
+	if (error instanceof Error) {
+		Object.defineProperty(error, "cause", {
+			value: rollbackCause,
+			configurable: true,
+			writable: true
+		});
+		return error;
+	}
+	return new Error(String(error), { cause: rollbackCause });
+}
+async function publishPairWithRollback(entries, publicationToken) {
+	const replaced = [];
+	try {
+		for (const entry of entries) {
+			await rename(entry.tempPath, entry.outputPath);
+			replaced.push(entry);
+		}
+	} catch (error) {
+		const rollbackFailures = (await Promise.allSettled(replaced.map((entry) => restoreArtifact(entry.outputPath, entry.previous, publicationToken)))).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+		if (rollbackFailures.length > 0) throw withRollbackFailureCause(error, rollbackFailures);
+		throw error;
+	}
+}
+async function publishContractArtifactPair({ outputJsonPath, outputDtsPath, contractJson, contractDts, publicationToken, beforePublish }) {
+	const tempJsonPath = createTempArtifactPath(outputJsonPath, publicationToken, "next");
+	const tempDtsPath = createTempArtifactPath(outputDtsPath, publicationToken, "next");
+	try {
+		await writeFile(tempJsonPath, contractJson, "utf-8");
+		await writeFile(tempDtsPath, contractDts, "utf-8");
+		if (await beforePublish?.() === false) return false;
+		const previousJson = await readExistingArtifact(outputJsonPath);
+		await publishPairWithRollback([{
+			tempPath: tempDtsPath,
+			outputPath: outputDtsPath,
+			previous: await readExistingArtifact(outputDtsPath)
+		}, {
+			tempPath: tempJsonPath,
+			outputPath: outputJsonPath,
+			previous: previousJson
+		}], publicationToken);
+		return true;
+	} finally {
+		await Promise.allSettled([rm(tempJsonPath, { force: true }), rm(tempDtsPath, { force: true })]);
+	}
+}
+const IMPORT_PATTERN = /import\s+type\s+.*?\s+from\s+['"](@[^/]+\/[^/'"]+)/g;
+function extractPackageSpecifiers(dtsContent) {
+	const packages = /* @__PURE__ */ new Set();
+	for (const match of dtsContent.matchAll(IMPORT_PATTERN)) {
+		const pkg = match[1];
+		if (pkg) packages.add(pkg);
+	}
+	return [...packages];
+}
+function validateContractDeps(dtsContent, projectRoot) {
+	const packages = extractPackageSpecifiers(dtsContent);
+	const resolve = createRequire(resolve$1(projectRoot, "package.json"));
+	const missing = [];
+	for (const pkg of packages) try {
+		resolve.resolve(`${pkg}/package.json`);
+	} catch {
+		missing.push(pkg);
+	}
+	if (missing.length === 0) return { missing };
+	return {
+		missing,
+		warning: [
+			"contract.d.ts imports types from packages that are not installed:",
+			missing.map((p) => `  - ${p}`).join("\n"),
+			"",
+			"Install them with your package manager:",
+			...missing.map((p) => `  ${p}`)
+		].join("\n")
+	};
+}
+const EMIT_ACTION = "emit";
+const defaultContractEmitDependencies = { emit };
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function startSpan(onProgress, spanId, label) {
+	onProgress?.({
+		action: EMIT_ACTION,
+		kind: "spanStart",
+		spanId,
+		label
+	});
+}
+function endSpan(onProgress, spanId, outcome) {
+	onProgress?.({
+		action: EMIT_ACTION,
+		kind: "spanEnd",
+		spanId,
+		outcome
+	});
+}
+function failedToResolveContractSource(why, fix, meta, cause) {
+	return errorRuntime("CONTRACT.SOURCE_LOAD_FAILED", "Failed to resolve contract source", {
+		why,
+		fix,
+		...ifDefined("meta", meta),
+		...ifDefined("cause", cause)
+	});
+}
+function diagnosticLocationSuffix(diagnostic) {
+	const sourceId = typeof diagnostic["sourceId"] === "string" ? diagnostic["sourceId"] : void 0;
+	const span = isRecord(diagnostic["span"]) ? diagnostic["span"] : void 0;
+	const start = span && isRecord(span["start"]) ? span["start"] : void 0;
+	const line = start && typeof start["line"] === "number" ? start["line"] : void 0;
+	const column = start && typeof start["column"] === "number" ? start["column"] : void 0;
+	if (sourceId && line !== void 0 && column !== void 0) return ` (${sourceId}:${line}:${column})`;
+	if (sourceId) return ` (${sourceId})`;
+	return "";
+}
+function mapDiagnosticsToIssues(diagnostics) {
+	const issues = [];
+	for (const raw of diagnostics) {
+		if (!isRecord(raw)) continue;
+		const code = typeof raw["code"] === "string" ? raw["code"] : "diagnostic";
+		const message = typeof raw["message"] === "string" ? raw["message"] : "";
+		issues.push({
+			kind: code,
+			message: `${message}${diagnosticLocationSuffix(raw)}`
+		});
+	}
+	return issues;
+}
+function validateProviderResult(providerResult) {
+	if (!isRecord(providerResult) || typeof providerResult["ok"] !== "boolean") return {
+		ok: false,
+		error: failedToResolveContractSource("Contract source provider returned malformed result shape.", "Ensure contract.source.load resolves to ok(Contract) or notOk({ summary, diagnostics }).")
+	};
+	if (providerResult["ok"]) {
+		if (!("value" in providerResult)) return {
+			ok: false,
+			error: failedToResolveContractSource("Contract source provider returned malformed success result: missing value.", "Ensure contract.source.load success payload is ok(Contract).")
+		};
+		return {
+			ok: true,
+			value: providerResult["value"]
+		};
+	}
+	const failure = providerResult["failure"];
+	if (!isRecord(failure) || typeof failure["summary"] !== "string" || !Array.isArray(failure["diagnostics"])) return {
+		ok: false,
+		error: failedToResolveContractSource("Contract source provider returned malformed failure result: expected summary and diagnostics.", "Ensure contract.source.load failure payload is notOk({ summary, diagnostics, meta? }).")
+	};
+	return {
+		ok: false,
+		error: failedToResolveContractSource(String(failure["summary"]), "Fix contract source diagnostics and return ok(Contract).", {
+			diagnostics: failure["diagnostics"],
+			issues: mapDiagnosticsToIssues(failure["diagnostics"]),
+			...ifDefined("providerMeta", failure["meta"])
+		})
+	};
+}
+/**
+* Canonical contract emit operation.
+*
+* This is the SINGLE publication path used by both the CLI command
+* (`prisma contract emit`) and the Vite plugin
+* (`@internal/vite-plugin-contract-emit`). New callers must go through this
+* function rather than re-implementing load → emit → publish.
+*
+* The whole flow (load config → resolve source → emit bytes → atomic publish)
+* is serialized per output JSON path via `queueEmitByOutput`. Concurrent calls
+* for the same output line up FIFO; the user-visible outcome is "last
+* submission wins on disk" without any supersession bookkeeping. Within a
+* single emit, `publishContractArtifactPair` stages temp files, renames
+* `contract.d.ts` before `contract.json`, and attempts to restore the previous
+* pair if either rename fails — so type-only consumers never observe a
+* mismatched pair.
+*
+* @throws {CliStructuredError} on config/source/validation problems
+* @throws {DOMException} `AbortError` if cancelled via `signal`
+*/
+async function executeContractEmit(options, dependencies = defaultContractEmitDependencies) {
+	const { config, configPath, outputPath, signal = new AbortController().signal, onProgress } = options;
+	const unlessAborted = abortable(signal);
+	if (!config.contract) throw errorContractConfigMissing({ why: "Config.contract is required for emit. Define it in your config: contract: { source: ..., output: ... }" });
+	const contractConfig = config.contract;
+	const effectiveOutput = outputPath !== void 0 ? join(outputPath, "contract.json") : contractConfig.output;
+	if (!effectiveOutput) throw errorContractConfigMissing({ why: "Contract config must have output path. This should not happen if defineConfig() was used." });
+	if (typeof contractConfig.source?.load !== "function") throw errorContractConfigMissing({ why: "Contract config must include a valid source provider object" });
+	let outputPaths;
+	try {
+		outputPaths = getEmittedArtifactPaths(effectiveOutput);
+	} catch (error) {
+		throw errorContractConfigMissing({ why: error instanceof Error ? error.message : String(error) });
+	}
+	const { jsonPath: outputJsonPath, dtsPath: outputDtsPath } = outputPaths;
+	return queueEmitByOutput(outputJsonPath, async () => {
+		const stack = createControlStack(config);
+		const sourceContext = {
+			composedExtensions: stack.extensions.map((p) => p.id),
+			composedExtensionContracts: stack.extensionContracts,
+			authoringContributions: stack.authoringContributions,
+			codecLookup: stack.codecLookup,
+			controlMutationDefaults: stack.controlMutationDefaults,
+			resolvedInputs: contractConfig.source.inputs ?? [],
+			capabilities: stack.capabilities
+		};
+		startSpan(onProgress, "resolveSource", "Resolving contract source...");
+		let providerResult;
+		try {
+			providerResult = await unlessAborted(contractConfig.source.load(sourceContext));
+		} catch (error) {
+			endSpan(onProgress, "resolveSource", "error");
+			if (signal.aborted || isRecord(error) && error["name"] === "AbortError") throw error;
+			throw failedToResolveContractSource(error instanceof Error ? error.message : String(error), "Ensure contract.source.load resolves to ok(Contract) or returns structured diagnostics.", void 0, error);
+		}
+		const validatedContract = validateProviderResult(providerResult);
+		if (!validatedContract.ok) {
+			endSpan(onProgress, "resolveSource", "error");
+			throw validatedContract.error;
+		}
+		endSpan(onProgress, "resolveSource", "ok");
+		startSpan(onProgress, "emit", "Emitting contract...");
+		let emitResult;
+		try {
+			const familyInstance = config.family.create(stack);
+			const rawComponents = [
+				config.target,
+				config.adapter,
+				...config.extensions ?? []
+			];
+			const frameworkComponents = assertFrameworkComponentsCompatible(config.family.familyId, config.target.targetId, rawComponents);
+			const enrichedIR = enrichContract(validatedContract.value, frameworkComponents);
+			const rawContractJson = config.target.contractSerializer.serializeContract(enrichedIR);
+			const deserializedContract = familyInstance.deserializeContract(rawContractJson);
+			const { contractSerializer } = config.target;
+			const serializeContract = (c) => contractSerializer.serializeContract(c);
+			emitResult = await unlessAborted(dependencies.emit(deserializedContract, stack, config.family.emission, {
+				outputJsonPath,
+				serializeContract,
+				resolveImportSpecifier: createProjectSpecifierResolver(configPath ?? outputJsonPath),
+				...ifDefined("shouldPreserveEmpty", contractSerializer.shouldPreserveEmpty),
+				...ifDefined("sortStorage", contractSerializer.sortStorage),
+				...ifDefined("supportsNamespaces", config.target.supportsNamespaces)
+			}));
+		} catch (error) {
+			endSpan(onProgress, "emit", "error");
+			throw error;
+		}
+		endSpan(onProgress, "emit", "ok");
+		await unlessAborted(mkdir(dirname(outputJsonPath), { recursive: true }));
+		await publishContractArtifactPair({
+			outputJsonPath,
+			outputDtsPath,
+			contractJson: emitResult.contractJson,
+			contractDts: emitResult.contractDts,
+			publicationToken: String(process.hrtime.bigint())
+		});
+		const validationWarning = validateContractDeps(emitResult.contractDts, dirname(outputDtsPath)).warning;
+		return {
+			storageHash: emitResult.storageHash,
+			...ifDefined("executionHash", emitResult.executionHash),
+			profileHash: emitResult.profileHash,
+			files: {
+				json: outputJsonPath,
+				dts: outputDtsPath
+			},
+			...ifDefined("validationWarning", validationWarning)
+		};
+	});
+}
+function computeRefAdvancementName(options) {
+	if (options.advanceRef !== void 0) return options.advanceRef;
+	if (options.db === void 0) return "db";
+	return null;
+}
+function contractDtsPathOf(contractJsonPath) {
+	return contractJsonPath.replace(/\.json$/i, ".d.ts");
+}
+async function readContractIR(contractJson, contractJsonPath) {
+	return {
+		contract: contractJson,
+		contractDts: await readFile(contractDtsPathOf(contractJsonPath), "utf-8")
+	};
+}
+function fsErrorCodeOf(error) {
+	const code = error instanceof Error ? Reflect.get(error, "code") : void 0;
+	return typeof code === "string" ? code : void 0;
+}
+function errorUnreadableContractDts(contractJsonPath, cause) {
+	const contractDtsPath = contractDtsPathOf(contractJsonPath);
+	const code = fsErrorCodeOf(cause);
+	return errorFileNotFound(contractDtsPath, {
+		why: code === "ENOENT" ? `The contract types next to ${contractJsonPath} are missing: ${contractDtsPath}` : `The contract types next to ${contractJsonPath} could not be read${code === void 0 ? "" : ` (${code})`}: ${contractDtsPath}`,
+		fix: "Run {bin} contract emit to regenerate the contract artifacts, then advance the ref again.",
+		cause
+	});
+}
+/**
+* Everything `advanceRefSafely` needs from disk, loaded before a command does
+* the work that precedes the ref write: the ref name is validated and the
+* sibling `.d.ts` of the contract to snapshot is read. The returned
+* `ContractIR` is what the command then hands to `advanceRefSafely`, so no
+* file is read after the database is signed.
+*/
+async function preflightRefAdvancement(args) {
+	if (!validateRefName(args.name)) return notOk(errorInvalidRefName(args.name));
+	try {
+		return ok(await readContractIR(args.contractJson, args.contractJsonPath));
+	} catch (error) {
+		return notOk(errorUnreadableContractDts(args.contractJsonPath, error));
+	}
+}
+async function executeRefAdvancement(refsDir, migrationsDir, name, hash, contractIR) {
+	if (!validateRefName(name)) throw errorInvalidRefName(name);
+	await writeContractSnapshot(migrationsDir, hash, {
+		contractJson: contractIR.contract,
+		contractDts: contractIR.contractDts
+	});
+	await writeRef(refsDir, name, {
+		hash,
+		invariants: []
+	});
+	return {
+		name,
+		hash
+	};
+}
+async function buildRefAdvancementFields(options) {
+	const name = computeRefAdvancementName({
+		...ifDefined("advanceRef", options.advanceRef),
+		...ifDefined("db", options.db)
+	});
+	if (name === null) return {
+		advancedRef: null,
+		plannedAdvanceRef: null
+	};
+	if (options.mode === "plan") return {
+		advancedRef: null,
+		plannedAdvanceRef: {
+			name,
+			hash: options.hash
+		}
+	};
+	return {
+		advancedRef: await executeRefAdvancement(options.refsDir, options.migrationsDir, name, options.hash, options.contractIR),
+		plannedAdvanceRef: null
+	};
+}
+/**
+* Full ref-advancement phase for db init/update: ok({advancedRef:null, plannedAdvanceRef:null})
+* when computeRefAdvancementName is null; else readContractIR + buildRefAdvancementFields with
+* MigrationToolsError mapped, other errors rethrown.
+*/
+async function resolveRefAdvancementFields(options) {
+	if (computeRefAdvancementName({
+		...ifDefined("advanceRef", options.advanceRef),
+		...ifDefined("db", options.db)
+	}) === null) return ok({
+		advancedRef: null,
+		plannedAdvanceRef: null
+	});
+	try {
+		const contractIR = await readContractIR(options.contractJson, options.contractJsonPath);
+		return ok(await buildRefAdvancementFields({
+			...ifDefined("advanceRef", options.advanceRef),
+			...ifDefined("db", options.db),
+			refsDir: options.refsDir,
+			migrationsDir: options.migrationsDir,
+			contractIR,
+			mode: options.mode,
+			hash: options.hash
+		}));
+	} catch (error) {
+		if (MigrationToolsError.is(error)) return notOk(error);
+		throw error;
+	}
+}
+/**
+* The --advance-ref tail of migrate and db sign: executeRefAdvancement with
+* MigrationToolsError failures passed through as notOk, others rethrown.
+*/
+async function advanceRefSafely(args) {
+	try {
+		return ok(await executeRefAdvancement(args.refsDir, args.migrationsDir, args.name, args.hash, args.contractIR));
+	} catch (error) {
+		if (MigrationToolsError.is(error)) return notOk(error);
+		throw error;
+	}
+}
+/**
+* Resolves a user-supplied contract reference to an on-disk contract JSON (snapshot store or emitted contract), shared by db sign and db update --to.
+*/
+function isEnoent$1(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function resolveContractRefToSnapshot(options) {
+	try {
+		const loaded = await buildReadAggregate(options.config, { migrationsDir: options.migrationsDir });
+		if (!loaded.ok) return notOk(loaded.failure);
+		const graph = loaded.value.aggregate.app.graph();
+		const bundles = loaded.value.aggregate.app.packages;
+		const refs = loaded.value.aggregate.app.refs;
+		const refResult = parseContractRef(options.refInput, {
+			graph,
+			refs
+		});
+		if (!refResult.ok) return notOk(mapRefResolutionError(refResult.failure));
+		const targetHash = refResult.value.hash;
+		if (bundles.find((p) => p.metadata.to === targetHash)) return ok({
+			hash: targetHash,
+			contractJson: blindCast(await readContractSnapshotJson(options.migrationsDir, targetHash)),
+			contractJsonPath: join(contractSnapshotDir(options.migrationsDir, targetHash), "contract.json"),
+			source: "snapshot"
+		});
+		if (!options.fallbackToEmitted) return notOk(errorUnexpected(`No migration bundle found for ${options.missingBundleFlag} "${options.refInput}" (resolved hash: ${targetHash})`, {
+			why: `The ref resolved successfully but no on-disk migration package has a destination (\`to\`) hash matching ${targetHash}.`,
+			fix: "Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations."
+		}));
+		let defaultRaw;
+		try {
+			defaultRaw = await readFile(options.contractPathAbsolute, "utf-8");
+		} catch (error) {
+			if (isEnoent$1(error)) return notOk(errorFileNotFound(options.contractPathAbsolute, {
+				why: `Contract file not found at ${options.contractPathAbsolute}`,
+				fix: "Run `{bin} contract emit` first to generate the contract",
+				cause: error
+			}));
+			return notOk(errorUnexpected(error instanceof Error ? error.message : String(error), {
+				why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
+				cause: error
+			}));
+		}
+		let parsed;
+		try {
+			parsed = castAs(JSON.parse(defaultRaw));
+		} catch (error) {
+			return notOk(errorContractDeserializationFailed(options.contractPathAbsolute, error instanceof Error ? error.message : String(error), { cause: error }));
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return notOk(errorContractDeserializationFailed(options.contractPathAbsolute, `expected a JSON object, got ${parsed === null ? "null" : Array.isArray(parsed) ? "an array" : `a ${typeof parsed}`}`));
+		const defaultContract = blindCast(parsed);
+		const storage = defaultContract["storage"];
+		if ((storage !== null && typeof storage === "object" ? blindCast(storage)["storageHash"] : void 0) === targetHash) return ok({
+			hash: targetHash,
+			contractJson: defaultContract,
+			contractJsonPath: options.contractPathAbsolute,
+			source: "emitted"
+		});
+		return notOk(errorRuntime("MIGRATION.SNAPSHOT_MISSING", `No contract file found for hash "${targetHash}"`, {
+			why: `Resolved contract reference "${options.refInput}" to hash "${targetHash}" but no migration produces that hash and the emitted contract does not match.`,
+			fix: "Ensure the target contract exists on disk — either as a migration endpoint or as the emitted contract.json."
+		}));
+	} catch (error) {
+		if (MigrationToolsError.is(error)) return notOk(error);
+		if (CliStructuredError$1.is(error)) return notOk(error);
+		throw error;
+	}
+}
+/**
+* Classifies errors caught around migration-tools calls so commands never import the MigrationToolsError class directly.
+*/
+/** CliStructuredError (including MigrationToolsError) → identity; anything else → null (caller rethrows/wraps). */
+function mapCaughtMigrationError(error) {
+	if (CliStructuredError$1.is(error)) return error;
+	return null;
+}
+function mapContractAtError(error, options) {
+	if (MigrationToolsError.is(error)) switch (error.code) {
+		case "MIGRATION.REF_NOT_RESOLVABLE": return notOk(errorSnapshotMissing(typeof error.meta?.["refName"] === "string" ? error.meta["refName"] : typeof error.meta?.["identifier"] === "string" ? error.meta["identifier"] : "unknown", { cause: error }));
+		case "MIGRATION.CONTRACT_DESERIALIZATION_FAILED": {
+			const filePath = typeof error.meta?.["filePath"] === "string" ? error.meta["filePath"] : "unknown";
+			return notOk(errorContractValidationFailed(`Predecessor contract at ${filePath} failed to deserialize: ${typeof error.meta?.["message"] === "string" ? error.meta["message"] : error.message}`, {
+				where: { path: filePath },
+				cause: error
+			}));
+		}
+		case "MIGRATION.INVALID_JSON": {
+			const filePath = typeof error.meta?.["filePath"] === "string" ? error.meta["filePath"] : "unknown";
+			const message = typeof error.meta?.["parseError"] === "string" ? error.meta["parseError"] : error.message;
+			return notOk(errorContractValidationFailed((options?.artifactRole ?? "from") === "to" ? `Target contract at ${filePath} failed to deserialize: ${message}` : `Predecessor contract at ${filePath} failed to deserialize: ${message}`, {
+				where: { path: filePath },
+				cause: error
+			}));
+		}
+		case "MIGRATION.BUNDLE_NOT_FOUND_FOR_GRAPH_NODE": return notOk(errorUnexpected(error.message, {
+			why: error.why,
+			fix: error.fix,
+			cause: error
+		}));
+		case "MIGRATION.CONTRACT_SNAPSHOT_MISSING": {
+			const expectedPath = typeof error.meta?.["expectedPath"] === "string" ? error.meta["expectedPath"] : "migrations/snapshots/";
+			return notOk(errorFileNotFound(expectedPath, {
+				why: (options?.artifactRole ?? "from") === "to" ? `Target migration is missing its contract snapshot at ${expectedPath}` : `Predecessor migration is missing its contract snapshot at ${expectedPath}`,
+				fix: "Restore migrations/snapshots/ from version control, or re-run the command that produced this migration to regenerate its snapshot.",
+				cause: error
+			}));
+		}
+		default: return notOk(error);
+	}
+	if (CliStructuredError$1.is(error)) return notOk(error);
+	throw error;
+}
+/** True when the on-disk graph contains a path fromHash → toHash. */
+function hasMigrationPath(graph, fromHash, toHash) {
+	return findPath(graph, fromHash, toHash) !== null;
+}
+/**
+* Refusal for a live marker hash that is not a node of the on-disk app graph.
+* Same errorMarkerMismatch envelope migrate raises today, or null when the marker is a node.
+*/
+function refuseMarkerOutsideGraph(args) {
+	if (isGraphNode(args.markerHash, args.graph)) return null;
+	return errorMarkerMismatch(args.markerHash, [...args.graph.nodes].sort(), findLatestMigration(args.graph)?.to ?? null);
+}
+/**
+* Invariant refusals shared by migrate and migration status: unknown ref invariants and unsatisfiable invariant paths.
+*/
+/** Refuses ref invariants neither declared on any graph edge nor present on the live marker. */
+function refuseUnknownInvariants(args) {
+	const declared = collectDeclaredInvariants(args.graph);
+	const known = new Set(declared);
+	for (const id of args.markerInvariants) known.add(id);
+	const unknown = args.refInvariants.filter((id) => !known.has(id));
+	if (unknown.length === 0) return null;
+	return errorUnknownInvariant({
+		...ifDefined("refName", args.refName),
+		unknown,
+		declared: [...declared].sort()
+	});
+}
+/** Refuses a --to target whose missing invariants no path from originHash satisfies. */
+function refuseMissingInvariantPath(args) {
+	const outcome = findPathWithDecision(args.graph, args.originHash, args.targetHash, {
+		...ifDefined("refName", args.refName),
+		required: new Set(args.missing)
+	});
+	if (outcome.kind !== "unsatisfiable") return null;
+	return errorNoInvariantPath({
+		...ifDefined("refName", args.refName),
+		required: [...args.missing].sort(),
+		missing: outcome.missing,
+		structuralPath: outcome.structuralPath.map(toStructuralEdge)
+	});
+}
+/**
+* Computes the path through the SAME seam as `executeMigrate`:
+* - `readAllMarkers()` for the from-state (when no `--from` is given), preserving
+*   the full marker including `invariants` (not just `storageHash`).
+* - `planSpacePath()` (shared with `executeMigrate`) for per-space path selection,
+*   which feeds `resolveRecordedPath()` with the same target hash, target invariants,
+*   and current marker as the real apply path uses.
+*
+* Returns BEFORE any write boundary (`runMigration` / marker / DDL). No
+* DB state is mutated.
+*/
+async function executeMigrateShowPlan(options) {
+	const config = options.config;
+	const { configPath, migrationsDir, migrationsRelative, refsDir } = resolveMigrationPaths(options.configPath, config, options.cwd);
+	const dbConnection = options.db ?? config.db?.connection;
+	const hasDriver = !!config.driver;
+	const hasExplicitFrom = options.from !== void 0;
+	if (!hasExplicitFrom) {
+		const missingDb = requireLiveDatabase({
+			dbConnection,
+			hasDriver,
+			why: "migrate --show needs a database connection to read the live marker (or pass --from <contract> for an offline preview)",
+			retryCommand: "{bin} db migrate --show --from <contract>"
+		});
+		if (missingDb) return notOk(missingDb);
+	}
+	let allRefs = {};
+	try {
+		allRefs = await readRefs(refsDir);
+	} catch (error) {
+		if (MigrationToolsError.is(error)) return notOk(error);
+		throw error;
+	}
+	const loaded = await buildReadAggregate(config, { migrationsDir });
+	if (!loaded.ok) return notOk(loaded.failure);
+	const { aggregate, contractHash } = loaded.value;
+	const appGraph = aggregate.app.graph();
+	let targetHash = contractHash;
+	let refInvariants;
+	if (options.to) {
+		const toResult = parseContractRef(options.to, {
+			graph: appGraph,
+			refs: allRefs,
+			contractHash
+		});
+		if (!toResult.ok) return notOk(mapRefResolutionError(toResult.failure));
+		if (toResult.value.provenance.kind === "reserved-db") return notOk(errorDatabaseConnectionRequired({
+			why: "@db is not valid as a --to target; it names the live database state, not a target contract.",
+			commandName: "migrate --show"
+		}));
+		targetHash = toResult.value.hash;
+		if (toResult.value.provenance.kind === "ref") {
+			const refEntry = allRefs[toResult.value.provenance.refName];
+			if (refEntry) refInvariants = refEntry.invariants;
+		}
+	}
+	options.onPreflightComplete?.({
+		configPath,
+		migrationsRelative,
+		dbConnection,
+		hasExplicitFrom
+	});
+	const markerBySpace = /* @__PURE__ */ new Map();
+	const allSpaces = [aggregate.app, ...aggregate.extensions];
+	if (hasExplicitFrom) if (options.from === "@db") {
+		const missingDb = requireLiveDatabase({
+			dbConnection,
+			hasDriver,
+			why: "@db resolves to the live database marker and requires a --db connection",
+			retryCommand: "{bin} db migrate --show --from @db --db $DATABASE_URL"
+		});
+		if (missingDb) return notOk(missingDb);
+	} else {
+		const fromResult = parseContractRef(options.from, {
+			graph: appGraph,
+			refs: allRefs,
+			contractHash
+		});
+		if (!fromResult.ok) return notOk(mapRefResolutionError(fromResult.failure));
+		if (fromResult.value.provenance.kind === "reserved-db") {
+			const missingDb = requireLiveDatabase({
+				dbConnection,
+				hasDriver,
+				why: "@db resolves to the live database marker and requires a --db connection"
+			});
+			if (missingDb) return notOk(missingDb);
+		} else {
+			const fromHash = fromResult.value.hash;
+			const offlineMarker = fromHash === "empty" ? null : {
+				storageHash: fromHash,
+				invariants: []
+			};
+			markerBySpace.set(aggregate.app.spaceId, offlineMarker);
+		}
+	}
+	const needsLiveMarker = !hasExplicitFrom || options.from === "@db";
+	if (needsLiveMarker) {
+		if (!dbConnection || !hasDriver) return notOk(errorDatabaseConnectionRequired({
+			why: "A database connection is required to read the live marker for migrate --show",
+			commandName: "migrate --show"
+		}));
+		const client = (options.createClient ?? createControlClient)({
+			family: config.family,
+			target: config.target,
+			adapter: config.adapter,
+			driver: config.driver,
+			extensions: config.extensions ?? []
+		});
+		try {
+			await client.connect(dbConnection);
+			const allMarkers = await client.readAllMarkers();
+			for (const space of allSpaces) {
+				const marker = allMarkers.get(space.spaceId);
+				markerBySpace.set(space.spaceId, marker ?? null);
+			}
+		} catch (error) {
+			if (CliStructuredError$1.is(error)) return notOk(error);
+			return notOk(errorUnexpected(error instanceof Error ? error.message : String(error), { why: `Failed to read live DB marker: ${error instanceof Error ? error.message : String(error)}` }));
+		} finally {
+			await closeQuietly(client);
+		}
+	}
+	const canonicalOrderSpaces = [...aggregate.extensions, aggregate.app];
+	const orderedMigrations = [];
+	for (const space of canonicalOrderSpaces) {
+		const isAppSpace = space.spaceId === aggregate.app.spaceId;
+		const headRef = requireHeadRef(space);
+		const outcome = planSpacePath({
+			space,
+			aggregate,
+			targetHash: isAppSpace ? targetHash : headRef.hash,
+			refInvariants: isAppSpace ? refInvariants : void 0,
+			liveMarker: markerBySpace.get(space.spaceId) ?? null
+		});
+		if (outcome.kind === "at-head") continue;
+		if (outcome.kind === "never-planned") return notOk(errorPathUnreachable({
+			code: "MIGRATION_PATH_NOT_FOUND",
+			summary: `No on-disk migrations for contract space "${outcome.spaceId}"`,
+			why: `migrate is replay-only: space "${outcome.spaceId}" has no on-disk migrations but its head ref targets "${outcome.targetHash}".`,
+			meta: {
+				spaceId: outcome.spaceId,
+				target: outcome.targetHash,
+				kind: "neverPlanned"
+			}
+		}));
+		if (outcome.kind === "unreachable") {
+			const fromHash = outcome.liveMarker?.storageHash ?? "empty";
+			return notOk(errorPathUnreachable({
+				code: "MIGRATION_PATH_NOT_FOUND",
+				summary: `No migration path from ${fromHash.slice(0, 14)} to ${outcome.targetHash.slice(0, 14)} in space "${outcome.spaceId}".`,
+				why: `The migration graph has no path from the from-state to the target in space "${outcome.spaceId}".`,
+				meta: {
+					spaceId: outcome.spaceId,
+					from: fromHash,
+					to: outcome.targetHash
+				}
+			}));
+		}
+		if (outcome.kind === "unsatisfiable") return notOk(errorRuntime("MIGRATION.NO_INVARIANT_PATH", `Missing required invariants for space "${outcome.spaceId}"`, {
+			why: `The path requires invariants not available on disk: ${outcome.missing.join(", ")}`,
+			fix: "Add a migration on the path that runs `dataTransform({ invariantId: \"<id>\", … })` for each missing invariant, or retarget the ref to a hash whose path already provides them.",
+			meta: {
+				spaceId: outcome.spaceId,
+				missing: [...outcome.missing]
+			}
+		}));
+		for (const edge of outcome.plan.migrationEdges) orderedMigrations.push({
+			spaceId: space.spaceId,
+			dirName: edge.dirName,
+			migrationHash: edge.migrationHash,
+			from: edge.from,
+			to: edge.to
+		});
+	}
+	const count = orderedMigrations.length;
+	return ok({
+		aggregate,
+		contractHash,
+		migrations: orderedMigrations,
+		summary: count === 0 ? "Already up to date — nothing to run" : `${count} migration${count === 1 ? "" : "s"} will run`,
+		renderMarkerHashBySpace: new Map(allSpaces.map((s) => [s.spaceId, markerBySpace.get(s.spaceId)?.storageHash ?? "empty"])),
+		usedLiveMarker: needsLiveMarker
+	});
+}
+function resolveContractRef$1(input, context) {
+	const result = parseContractRef(input, context);
+	return result.ok ? ok(result.value) : notOk(mapRefResolutionError(result.failure));
+}
+function resolveMigrationRef(input, context) {
+	const result = parseMigrationRef(input, context);
+	return result.ok ? ok(result.value) : notOk(mapRefResolutionError(result.failure));
+}
+function compareSpaceIds(a, b) {
+	if (a === APP_SPACE_ID$1) return b === APP_SPACE_ID$1 ? 0 : -1;
+	if (b === APP_SPACE_ID$1) return 1;
+	if (a < b) return -1;
+	if (a > b) return 1;
+	return 0;
+}
+function compareDirNamesDescending(a, b) {
+	if (a.name < b.name) return 1;
+	if (a.name > b.name) return -1;
+	return 0;
+}
+/**
+* Ref names decorating a space's destination contract hashes. The
+* tolerant `space.refs` deliberately omits the structural `head.json`;
+* for extension spaces the old enumerator surfaced it as a `head`
+* decoration on the tip migration, so fold `space.headRef` back in to
+* keep that output. The app space synthesises its head, so it carries
+* no on-disk `head` ref to restore.
+*/
+function listRefsByContractHash(space) {
+	const byHash = new Map(refsByContractHash(space.refs));
+	if (space.spaceId !== APP_SPACE_ID$1 && space.headRef !== null) {
+		const hash = space.headRef.hash;
+		const bucket = byHash.get(hash) ?? [];
+		if (!bucket.includes("head")) byHash.set(hash, [...bucket, HEAD_REF_NAME].sort());
+	}
+	return byHash;
+}
+async function orderedOnDiskSpaceIds(projectMigrationsDir) {
+	return (await listContractSpaceDirectories(projectMigrationsDir)).filter(isValidSpaceId).sort(compareSpaceIds);
+}
+/**
+* Project the loaded {@link ContractSpaceAggregate} into the render-ready
+* {@link MigrationSpaceListEntry} rows `migration list` displays.
+*
+* Space membership matches the on-disk contract-space directories (not the
+* aggregate's always-present synthesized app space when `migrations/app/`
+* is absent); package and ref data come from `aggregate.space(id)`.
+*/
+async function migrationSpaceListEntriesFromAggregate(aggregate, projectMigrationsDir) {
+	const spaceIds = await orderedOnDiskSpaceIds(projectMigrationsDir);
+	const spaces = [];
+	for (const spaceId of spaceIds) {
+		const space = aggregate.space(spaceId);
+		if (space === void 0) continue;
+		const refsByHash = listRefsByContractHash(space);
+		const migrations = space.packages.map((pkg) => ({
+			name: pkg.dirName,
+			hash: pkg.metadata.migrationHash,
+			fromContract: pkg.metadata.from,
+			toContract: pkg.metadata.to,
+			operationCount: pkg.ops.length,
+			createdAt: pkg.metadata.createdAt,
+			refs: [...refsByHash.get(pkg.metadata.to) ?? []],
+			providedInvariants: [...pkg.metadata.providedInvariants]
+		})).sort(compareDirNamesDescending);
+		spaces.push({
+			space: spaceId,
+			migrations
+		});
+	}
+	return spaces;
+}
+function computeSummary(spaces) {
+	const totalMigrations = spaces.reduce((count, space) => count + space.migrations.length, 0);
+	if (spaces.length <= 1) return `${totalMigrations} migration(s) on disk`;
+	return `${totalMigrations} migration(s) across ${spaces.length} contract space(s)`;
+}
+/**
+* Policy core of `migration list`: validates `--space`, narrows the
+* pre-enumerated spaces, and assembles a {@link MigrationListResult}.
+*
+* - `migrations/` missing or contains no valid space directories →
+*   caller passes `spaces: []`; this synthesizes `[{ spaceId: APP_SPACE_ID, migrations: [] }]`.
+* - `--space <id>` on an existing-but-empty space → `{ spaceId, migrations: [] }` in the input.
+* - `--space <id>` on a non-existent (or reserved) space → `SPACE_NOT_FOUND`.
+*/
+function runMigrationList(inputs) {
+	const { spaces, spaceFilter } = inputs;
+	if (spaceFilter !== void 0 && !isValidSpaceId(spaceFilter)) return notOk(errorInvalidSpaceId(spaceFilter));
+	if (spaceFilter !== void 0 && !spaces.some((s) => s.space === spaceFilter)) return notOk(errorSpaceNotFound(spaceFilter, spaces.map((s) => s.space).sort()));
+	const scopedSpaces = spaceFilter !== void 0 ? spaces.filter((s) => s.space === spaceFilter) : spaces;
+	const resultSpaces = scopedSpaces.length === 0 ? [{
+		space: APP_SPACE_ID$1,
+		migrations: []
+	}] : scopedSpaces;
+	return ok({
+		ok: true,
+		spaces: [...resultSpaces],
+		summary: computeSummary(resultSpaces)
+	});
+}
+function looksLikePath(target) {
+	return target.includes("/") || target.includes("\\");
+}
+function resolveAppTargetPath(cwd, target, appMigrationsDir, appMigrationsRelative) {
+	const targetPath = resolve(cwd, target);
+	const relativeToApp = relative(appMigrationsDir, targetPath);
+	if (relativeToApp === "" || relativeToApp === "." || relativeToApp.startsWith("..") || isAbsolute(relativeToApp)) return notOk(errorRuntime("MIGRATION.TARGET_NOT_APP_SPACE", "Target must point to an app-space migration", {
+		why: `Expected a path under ${appMigrationsRelative}, got ${target}`,
+		fix: "Pass an app-space migration directory or use a hash prefix."
+	}));
+	return ok(targetPath);
+}
+/**
+* Resolve a filesystem-path target to the migration dir that contains it,
+* searching each in-scope space's `migrationsDir`. A path is explicit, so
+* it can belong to at most one space — returns the first match, or `null`
+* when the path falls outside every space dir.
+*/
+function resolveTargetPathAcrossSpaces(cwd, target, spaces) {
+	const targetPath = resolve(cwd, target);
+	for (const space of spaces) {
+		const rel = relative(space.migrationsDir, targetPath);
+		if (!(rel === "" || rel === "." || rel.startsWith("..") || isAbsolute(rel))) return targetPath;
+	}
+	return null;
+}
+function findPackageByDirPath(packages, resolvedDirPath) {
+	const normalized = resolve(resolvedDirPath);
+	return packages.find((p) => resolve(p.dirPath) === normalized);
+}
+/**
+* Policy core of `migration check`: per-space explicit graph checks, aggregate-integrity loading, and single-target resolution.
+*/
+function migrationPathRelative(cwd, dirPath) {
+	return relative(cwd, dirPath);
+}
+function migrationFileRelative(cwd, dirPath, fileName) {
+	return join(migrationPathRelative(cwd, dirPath), fileName);
+}
+function checkFileExists(space, dirPath, dirName, fileName) {
+	if (!existsSync(join(dirPath, fileName))) return {
+		space: space.spaceId,
+		code: "MIGRATION.CHECK_FILE_MISSING",
+		where: migrationFileRelative(space.cwd, dirPath, fileName),
+		why: `${fileName} is missing from ${dirName}`,
+		nextActions: [chooseAction("Re-emit the migration package, or restore it from version control")]
+	};
+	return null;
+}
+/**
+* Snapshot-store consistency check for one migration package (D6.5):
+* absent store entry is not an issue (runner independence, ADR 199 — a
+* package dir with only `migration.json` + `ops.json` is legitimate); a
+* present entry whose inner `storage.storageHash` disagrees with
+* `pkg.metadata.to` is `MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH`; an unparseable store
+* entry (or a malformed `to`) is `MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE`.
+*/
+async function checkSnapshotConsistency(space, pkg, migrationsDir) {
+	const spaceId = space.spaceId;
+	let snapshotDir;
+	try {
+		snapshotDir = contractSnapshotDir(migrationsDir, pkg.metadata.to);
+	} catch {
+		return {
+			space: spaceId,
+			code: "MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE",
+			where: migrationPathRelative(space.cwd, pkg.dirPath),
+			why: `Migration "${pkg.dirName}" declares to="${pkg.metadata.to}", which is not a well-formed contract snapshot hash.`,
+			nextActions: [chooseAction("Re-emit the migration package so migration.json declares a valid 64-hex to-hash")]
+		};
+	}
+	let raw;
+	try {
+		raw = await readContractSnapshotJson(migrationsDir, pkg.metadata.to);
+	} catch (error) {
+		if (MigrationToolsError.is(error) && error.code === "MIGRATION.CONTRACT_SNAPSHOT_MISSING") return null;
+		return {
+			space: spaceId,
+			code: "MIGRATION.CHECK_SNAPSHOT_UNPARSEABLE",
+			where: migrationPathRelative(space.cwd, pkg.dirPath),
+			why: `Migration "${pkg.dirName}" has an unparseable contract snapshot at ${snapshotDir}/contract.json.`,
+			nextActions: [chooseAction("Restore migrations/snapshots/ from version control"), chooseAction("Or re-run the command that produced this migration to regenerate its snapshot")]
+		};
+	}
+	const snapshotHash = (raw !== null && typeof raw === "object" ? raw : {})["storage"]?.["storageHash"];
+	if (typeof snapshotHash === "string" && snapshotHash !== pkg.metadata.to) return {
+		space: spaceId,
+		code: "MIGRATION.CHECK_SNAPSHOT_HASH_MISMATCH",
+		where: migrationPathRelative(space.cwd, pkg.dirPath),
+		why: `Migration "${pkg.dirName}" declares to=${pkg.metadata.to} but its contract snapshot has storageHash=${snapshotHash}`,
+		nextActions: [chooseAction("Re-emit the migration package so migration.json and its contract snapshot agree")]
+	};
+	return null;
+}
+/**
+* Project the loaded {@link ContractSpaceAggregate} into the
+* {@link CheckSpace} rows the multi-space check iterates — one per on-disk
+* contract-space directory, in the aggregate's `app`-first ordering. Mirrors
+* `migration list`'s `migrationSpaceListEntriesFromAggregate`: space
+* membership matches the on-disk directories, package / ref / graph data come
+* from `aggregate.space(id)`.
+*/
+async function enumerateCheckSpaces(aggregate, projectMigrationsDir, cwd) {
+	const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
+	const onDiskSpaceIds = new Set(candidateDirs.filter(isValidSpaceId));
+	const spaces = [];
+	for (const space of aggregate.spaces()) {
+		const spaceId = space.spaceId;
+		if (!isValidSpaceId(spaceId)) continue;
+		if (!onDiskSpaceIds.has(spaceId)) continue;
+		const migrationsDir = spaceMigrationDirectory(projectMigrationsDir, spaceId);
+		spaces.push({
+			spaceId,
+			packages: space.packages,
+			refs: space.refs,
+			graph: space.graph(),
+			migrationsDir,
+			refsDir: spaceRefsDirectory(migrationsDir),
+			projectMigrationsDir,
+			cwd
+		});
+	}
+	return spaces;
+}
+function checkManifestFilesPresent(space) {
+	if (!existsSync(space.migrationsDir)) return [];
+	const loadedDirNames = new Set(space.packages.map((p) => p.dirName));
+	const failures = [];
+	let entries;
+	try {
+		entries = readdirSync(space.migrationsDir);
+	} catch {
+		return failures;
+	}
+	for (const entry of entries) {
+		if (entry.startsWith(".") || entry.startsWith("_") || entry === "refs") continue;
+		const entryPath = join(space.migrationsDir, entry);
+		try {
+			if (!statSync(entryPath).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		if (!loadedDirNames.has(entry)) for (const f of ["migration.json", "ops.json"]) {
+			const fail = checkFileExists(space, entryPath, entry, f);
+			if (fail) failures.push(fail);
+		}
+	}
+	return failures;
+}
+function checkReachability(space) {
+	const allToHashes = new Set(space.packages.map((p) => p.metadata.to));
+	const failures = [];
+	for (const pkg of space.packages) if (!(pkg.metadata.from === null || allToHashes.has(pkg.metadata.from) || pkg.metadata.from === "empty")) failures.push({
+		space: space.spaceId,
+		code: "MIGRATION.CHECK_UNREACHABLE_MIGRATION",
+		where: migrationPathRelative(space.cwd, pkg.dirPath),
+		why: `Migration "${pkg.dirName}" starts from ${pkg.metadata.from} which no other migration produces`,
+		nextActions: [chooseAction("Delete the unreachable migration"), chooseAction("Or re-emit a migration that connects it to the graph")]
+	});
+	return failures;
+}
+function checkDanglingRefs(space) {
+	const failures = [];
+	for (const [name, entry] of Object.entries(space.refs)) if (!space.graph.nodes.has(entry.hash)) failures.push({
+		space: space.spaceId,
+		code: "MIGRATION.CHECK_DANGLING_REF",
+		where: relative(space.cwd, join(space.refsDir, `${name}.json`)),
+		why: `Ref "${name}" points at ${entry.hash} which does not exist in the migration graph`,
+		nextActions: [runCommandAction("Point the ref at a graph node", `{bin} migration ref set ${name} <valid-hash>`), chooseAction("Or delete the ref")]
+	});
+	return failures;
+}
+async function checkSpace(space) {
+	const snapshotFailures = await Promise.all(space.packages.map((pkg) => checkSnapshotConsistency(space, pkg, space.projectMigrationsDir)));
+	return [
+		...checkManifestFilesPresent(space),
+		...snapshotFailures.filter((f) => f !== null),
+		...checkReachability(space),
+		...checkDanglingRefs(space)
+	];
+}
+/**
+* Policy core of the holistic `migration check`: validates `--space`,
+* narrows the pre-enumerated spaces, and runs the per-space explicit graph
+* checks (file-existence, snapshot consistency, reachability, dangling
+* refs), aggregating every failure into one {@link MigrationCheckResult}.
+*
+* `--space` validation mirrors `migration list`: an invalid id →
+* {@link errorInvalidSpaceId}; an id with no on-disk space →
+* {@link errorSpaceNotFound}. Both map to exit `PRECONDITION` at the shell.
+* Aggregate-integrity violations (which already span every space) are folded
+* in by the caller, not here.
+*/
+async function runMigrationCheck(inputs) {
+	const { spaces, spaceFilter } = inputs;
+	if (spaceFilter !== void 0 && !isValidSpaceId(spaceFilter)) return notOk(errorInvalidSpaceId(spaceFilter));
+	if (spaceFilter !== void 0 && !spaces.some((s) => s.spaceId === spaceFilter)) return notOk(errorSpaceNotFound(spaceFilter, spaces.map((s) => s.spaceId).sort()));
+	const scopedSpaces = spaceFilter !== void 0 ? spaces.filter((s) => s.spaceId === spaceFilter) : spaces;
+	const failures = (await Promise.all(scopedSpaces.map(checkSpace))).flat();
+	if (failures.length === 0) return ok({
+		ok: true,
+		failures: [],
+		summary: "All checks passed"
+	});
+	return ok({
+		ok: false,
+		failures,
+		summary: `${failures.length} integrity failure(s)`
+	});
+}
+async function loadAggregateIntegrityViolations(config, migrationsDir) {
+	try {
+		const contractJsonContent = await readFile(resolveContractPath(config), "utf-8");
+		const familyInstance = config.family.create(createControlStack(config));
+		const declaredExtensions = toDeclaredExtensionsFromRaw(config.extensions ?? []);
+		const parsedAppContract = JSON.parse(contractJsonContent);
+		return (await loadContractSpaceAggregate({
+			migrationsDir,
+			deserializeContract: (json) => familyInstance.deserializeContract(json),
+			appContract: familyInstance.deserializeContract(parsedAppContract)
+		})).checkIntegrity({
+			declaredExtensions,
+			checkContracts: true
+		});
+	} catch {
+		return [];
+	}
+}
+/**
+* Ranks ref-resolution failure kinds by how informative they are, so a
+* single-target check surfaces the most useful failure across spaces instead of
+* whichever space failed first. `not-found` (the input matched nothing here)
+* says the least; a malformed input, a wrong grammar, or an in-space ambiguity
+* all say more.
+*/
+function refFailureSpecificity(error) {
+	switch (error.kind) {
+		case "wrong-grammar": return 3;
+		case "ambiguous": return 2;
+		case "invalid-format": return 1;
+		case "not-found": return 0;
+	}
+}
+/**
+* Single-target (`check <ref/path>`) mode — resolves a migration reference
+* across all contract spaces (or the one space narrowed by `--space <id>`).
+*
+* Resolution:
+*   - filesystem path → find the owning space by checking which space's
+*     `migrationsDir` contains the resolved path; falls back to app-relative
+*     validation when the path is outside every space dir.
+*   - ref → `parseMigrationRef` against each in-scope space; collect every
+*     (space, package) hit; 0 hits = not-found, 1 = check it, >1 = ambiguity
+*     error (qualify with `--space`).
+*
+* `--space <id>` is validated the same way the holistic path does it:
+* invalid id → `errorInvalidSpaceId`; no on-disk space → `errorSpaceNotFound`.
+*/
+async function checkSingleTarget(target, inputs) {
+	const { spaces, spaceFilter, appMigrationsDir, appMigrationsRelative, cwd } = inputs;
+	if (spaceFilter !== void 0 && !isValidSpaceId(spaceFilter)) return {
+		error: errorInvalidSpaceId(spaceFilter),
+		exitCode: 2
+	};
+	if (spaceFilter !== void 0 && !spaces.some((s) => s.spaceId === spaceFilter)) return {
+		error: errorSpaceNotFound(spaceFilter, spaces.map((s) => s.spaceId).sort()),
+		exitCode: 2
+	};
+	const scopedSpaces = spaceFilter !== void 0 ? spaces.filter((s) => s.spaceId === spaceFilter) : spaces;
+	let matchedSpace;
+	let matchedPkg;
+	if (looksLikePath(target)) {
+		const resolvedPath = resolveTargetPathAcrossSpaces(cwd, target, scopedSpaces);
+		if (resolvedPath !== null) for (const space of scopedSpaces) {
+			const found = findPackageByDirPath(space.packages, resolvedPath);
+			if (found) {
+				matchedSpace = space;
+				matchedPkg = found;
+				break;
+			}
+		}
+		else {
+			const resolved = resolveAppTargetPath(cwd, target, appMigrationsDir, appMigrationsRelative);
+			if (!resolved.ok) return {
+				error: resolved.failure,
+				exitCode: 2
+			};
+			const appSpace = scopedSpaces.find((s) => s.spaceId === "app");
+			if (appSpace) {
+				matchedSpace = appSpace;
+				matchedPkg = findPackageByDirPath(appSpace.packages, resolved.value);
+			}
+		}
+	} else {
+		const hits = [];
+		let bestParseFailure;
+		for (const space of scopedSpaces) {
+			const migResult = parseMigrationRef(target, {
+				graph: space.graph,
+				refs: space.refs
+			});
+			if (!migResult.ok) {
+				if (bestParseFailure === void 0 || refFailureSpecificity(migResult.failure) > refFailureSpecificity(bestParseFailure)) bestParseFailure = migResult.failure;
+				continue;
+			}
+			const pkg = space.packages.find((p) => p.metadata.migrationHash === migResult.value.migrationHash);
+			if (pkg) hits.push({
+				space,
+				pkg
+			});
+		}
+		if (hits.length > 1) return {
+			error: errorAmbiguousMigrationRef(target, hits.map((h) => h.space.spaceId)),
+			exitCode: 2
+		};
+		if (hits.length === 1) {
+			matchedSpace = hits[0].space;
+			matchedPkg = hits[0].pkg;
+		} else if (bestParseFailure !== void 0) return {
+			error: mapRefResolutionError(bestParseFailure),
+			exitCode: 2
+		};
+	}
+	if (!matchedPkg || !matchedSpace) return {
+		result: {
+			ok: false,
+			failures: [],
+			summary: `Migration package for "${target}" not found on disk`
+		},
+		exitCode: 2
+	};
+	const failures = [...checkManifestFilesPresent(matchedSpace)];
+	for (const f of ["migration.json", "ops.json"]) {
+		const fail = checkFileExists(matchedSpace, matchedPkg.dirPath, matchedPkg.dirName, f);
+		if (fail) failures.push(fail);
+	}
+	const verification = verifyMigrationHash(matchedPkg);
+	if (!verification.ok) failures.push({
+		space: matchedSpace.spaceId,
+		code: "MIGRATION.CHECK_HASH_MISMATCH",
+		where: migrationFileRelative(matchedSpace.cwd, matchedPkg.dirPath, "migration.json"),
+		why: `Stored hash ${verification.storedHash} does not match recomputed hash ${verification.computedHash}`,
+		nextActions: [chooseAction("Re-emit the migration package, or restore it from version control")]
+	});
+	const snapshotFailure = await checkSnapshotConsistency(matchedSpace, matchedPkg, matchedSpace.projectMigrationsDir);
+	if (snapshotFailure) failures.push(snapshotFailure);
+	const resolvedSpaceId = matchedSpace.spaceId !== "app" ? matchedSpace.spaceId : void 0;
+	if (failures.length === 0) return {
+		result: {
+			ok: true,
+			failures: [],
+			summary: "All checks passed"
+		},
+		exitCode: 0,
+		...ifDefined("resolvedSpaceId", resolvedSpaceId)
+	};
+	return {
+		result: {
+			ok: false,
+			failures,
+			summary: `${failures.length} integrity failure(s)`
+		},
+		exitCode: 4,
+		...ifDefined("resolvedSpaceId", resolvedSpaceId)
+	};
+}
+/**
+* Project scoped list entries into the per-space contracts+migrations rows the migration
+* graph --json output serializes (EMPTY_CONTRACT_HASH from-hash → null). Skips space ids
+* the aggregate no longer resolves, mirroring the command loop.
+*/
+function buildMigrationSpaceGraphEntries(args) {
+	const spaces = [];
+	for (const spaceEntry of args.scopedSpaces) {
+		const space = args.aggregate.space(spaceEntry.space);
+		if (space === void 0) continue;
+		const graph = space.graph();
+		const refsByHash = listRefsByContractHash(space);
+		spaces.push({
+			space: spaceEntry.space,
+			contracts: [...graph.nodes].map((hash) => ({
+				hash,
+				refs: [...refsByHash.get(hash) ?? []]
+			})),
+			migrations: [...graph.migrationByHash.values()].map((edge) => ({
+				name: edge.dirName,
+				hash: edge.migrationHash,
+				fromContract: edge.from === "empty" ? null : edge.from,
+				toContract: edge.to
+			}))
+		});
+	}
+	return spaces;
+}
+/**
+* Policy core of `migration new`: scaffolds a migration package with a `migration.ts` stub for manual authoring.
+*/
+async function executeMigrationNewCommand(options) {
+	const config = options.config;
+	const cwd = options.cwd;
+	const { migrationsDir, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(options.configPath, config, cwd);
+	const stack = createControlStack(config);
+	const familyInstance = config.family.create(stack);
+	const controlAdapter = config.adapter.create(stack);
+	const contractPathAbsolute = resolveContractPath(config);
+	let contractJsonContent;
+	try {
+		contractJsonContent = await readFile(contractPathAbsolute, "utf-8");
+	} catch (error) {
+		if (error instanceof Error && error.code === "ENOENT") return notOk(errorRuntime("CLI.FILE_NOT_FOUND", `Contract file not found at ${contractPathAbsolute}`, {
+			why: `Contract file not found at ${contractPathAbsolute}`,
+			fix: "Run `{bin} contract emit` first to generate the contract"
+		}));
+		throw error;
+	}
+	let toContract;
+	try {
+		const parsedContract = JSON.parse(contractJsonContent);
+		toContract = familyInstance.deserializeContract(parsedContract);
+	} catch (error) {
+		return notOk(errorRuntime("MIGRATION.CONTRACT_DESERIALIZATION_FAILED", "Contract JSON is invalid", {
+			why: `Failed to deserialize ${contractPathAbsolute}: ${error instanceof Error ? error.message : String(error)}`,
+			fix: "Run `{bin} contract emit` to regenerate the contract",
+			cause: error
+		}));
+	}
+	const toStorageHash = toContract.storage?.storageHash;
+	if (typeof toStorageHash !== "string") return notOk(errorRuntime("CONTRACT.VALIDATION_FAILED", "Contract is missing storageHash", {
+		why: `Contract at ${contractPathAbsolute} has no storageHash`,
+		fix: "Run `{bin} contract emit` to regenerate the contract"
+	}));
+	const aggregate = await loadContractSpaceAggregate({
+		migrationsDir,
+		deserializeContract: (json) => familyInstance.deserializeContract(json),
+		appContract: toContract
+	});
+	const packageCorruptionFailure = refusePackageCorruptionOnAggregate(aggregate, migrationsDir);
+	if (packageCorruptionFailure) return notOk(packageCorruptionFailure);
+	const packages = aggregate.app.packages;
+	const graph = aggregate.app.graph();
+	let fromHash = null;
+	if (packages.length > 0) if (options.from) {
+		const match = packages.find((p) => p.metadata.to.startsWith(options.from));
+		if (!match) return notOk(errorRuntime("MIGRATION.HASH_NOT_IN_GRAPH", "Starting contract not found", {
+			why: `No migration with to hash matching "${options.from}" exists in ${appMigrationsRelative}`,
+			fix: "Check that the --from hash matches a known migration target hash."
+		}));
+		fromHash = match.metadata.to;
+	} else {
+		const latestMigration = findLatestMigration(graph);
+		if (latestMigration) fromHash = latestMigration.to;
+	}
+	if (fromHash === toStorageHash && !options.from) return notOk(errorRuntime("MIGRATION.NO_CHANGES", "No changes detected", {
+		why: "The from and to contract hashes are identical — there is nothing to migrate.",
+		fix: "Change the contract and run `{bin} contract emit` before creating a new migration. To author a data-only migration on the current contract hash, pass `--from <hash>` explicitly."
+	}));
+	const timestamp = /* @__PURE__ */ new Date();
+	const packageDir = join(appMigrationsDir, formatMigrationDirName(timestamp, options.name ?? "migration"));
+	const baseMetadata = {
+		from: fromHash,
+		to: toStorageHash,
+		providedInvariants: [],
+		createdAt: timestamp.toISOString()
+	};
+	const metadata = {
+		...baseMetadata,
+		migrationHash: computeMigrationHash(baseMetadata, [])
+	};
+	const migrations = getTargetMigrations(config.target);
+	if (!migrations) return notOk(errorTargetMigrationNotSupported({ why: `Target "${config.target.targetId}" does not support migrations` }));
+	try {
+		assertFrameworkComponentsCompatible(config.family.familyId, config.target.targetId, [
+			config.target,
+			config.adapter,
+			...config.extensions ?? []
+		]);
+		const resolveSpecifier = createProjectSpecifierResolver(options.configPath);
+		await writeMigrationPackage(packageDir, metadata, []);
+		const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
+		const [contractJsonRaw, contractDts] = await Promise.all([readFile(destinationArtifacts.jsonPath, "utf-8"), readFile(destinationArtifacts.dtsPath, "utf-8")]);
+		await writeContractSnapshot(migrationsDir, toStorageHash, {
+			contractJson: JSON.parse(contractJsonRaw),
+			contractDts
+		});
+		await writeMigrationTs(packageDir, migrations.createPlanner(controlAdapter).emptyMigration({
+			packageDir,
+			contractJsonPath: join(contractSnapshotDir(migrationsDir, toStorageHash), "contract.json"),
+			fromHash,
+			toHash: toStorageHash,
+			snapshotsImportPath: snapshotsImportPathFrom(packageDir, migrationsDir)
+		}, APP_SPACE_ID).renderTypeScript(resolveSpecifier));
+		return ok({
+			ok: true,
+			dir: relative(cwd, packageDir),
+			from: fromHash,
+			to: toStorageHash,
+			summary: `Scaffolded migration at ${relative(cwd, packageDir)}`
+		});
+	} catch (error) {
+		if (CliStructuredError$1.is(error)) return notOk(error);
+		return notOk(errorUnexpected(error instanceof Error ? error.message : String(error), { why: `Failed to scaffold migration: ${error instanceof Error ? error.message : String(error)}` }));
+	}
+}
+/**
+* Phase-1 of the two-phase `migration plan` pipeline (sub-spec § 4).
+*
+* For every extension that exposes a `contractSpace`:
+*
+* 1. Read the on-disk head ref (returns `null` on first emit).
+* 2. Write the head contract into the migrations-root snapshot store
+*    (write-if-absent, keyed by hash) and unconditionally re-emit
+*    `refs/head.json`, via {@link emitContractSpaceArtifacts}. The
+*    framework owns `refs/head.json`; re-emit is the contract for that
+*    file. The snapshot itself is only written once per distinct hash.
+* 3. Materialise any descriptor-shipped migration packages not yet on
+*    disk via {@link materialiseExtensionMigrationPackageIfMissing}.
+*    Existing packages are left untouched (by-existence skip).
+*
+* The return value lets the caller render a per-space status line and
+* lets the phase-2 aggregate loader run on a now-consistent disk state
+* (every loaded extension is guaranteed to have its head ref pinned
+* to the descriptor's hash and to ship every package the descriptor
+* declares).
+*
+* Output ordering is deterministic and alphabetical by spaceId (via
+* {@link planAllSpaces}, which also detects duplicate spaceIds). This
+* matches the canonical sort order used by every other aggregate
+* surface (`migrate`, `migration status`, the runner).
+*/
+async function runContractSpaceSeedPhase(inputs) {
+	const planned = planAllSpaces(inputs.extensions.filter((pack) => pack.contractSpace !== void 0).map((pack) => ({
+		spaceId: pack.id,
+		priorContract: null,
+		newContract: pack.contractSpace.contractJson,
+		__pack: pack.contractSpace
+	})), (input) => input.__pack.migrations);
+	const descriptorBySpace = /* @__PURE__ */ new Map();
+	for (const pack of inputs.extensions) if (pack.contractSpace !== void 0) descriptorBySpace.set(pack.id, pack.contractSpace);
+	const seeded = [];
+	for (const space of planned) {
+		const descriptor = descriptorBySpace.get(space.spaceId);
+		if (descriptor === void 0) continue;
+		const priorHash = (await readContractSpaceHeadRef(inputs.migrationsDir, space.spaceId))?.hash ?? null;
+		await emitContractSpaceArtifacts(inputs.migrationsDir, space.spaceId, {
+			contract: descriptor.contractJson,
+			contractDts: buildPlaceholderContractDts(space.spaceId),
+			headRef: {
+				hash: descriptor.headRef.hash,
+				invariants: descriptor.headRef.invariants
+			}
+		});
+		const spaceDir = spaceMigrationDirectory(inputs.migrationsDir, space.spaceId);
+		const newMigrationDirs = [];
+		for (const pkg of space.migrationPackages) {
+			const { written } = await materialiseExtensionMigrationPackageIfMissing(spaceDir, pkg);
+			if (written) newMigrationDirs.push(pkg.dirName);
+		}
+		const action = priorHash !== descriptor.headRef.hash || newMigrationDirs.length > 0 ? "updated" : "unchanged";
+		seeded.push({
+			spaceId: space.spaceId,
+			action,
+			priorHash,
+			newHash: descriptor.headRef.hash,
+			newMigrationDirs
+		});
+	}
+	return { seeded };
+}
+/**
+* Placeholder `.d.ts` content for an extension space's on-disk mirror.
+*
+* Rendering a fully-typed `.d.ts` for an extension contract requires
+* the SQL-family renderer with the codec / typemap registry threaded
+* through; until that integration ships, the on-disk `.d.ts` is a
+* stub `export {};` module that documents how consumers should
+* validate the sibling `contract.json`. The stub typechecks on its
+* own and does not need any TypeScript suppressions.
+*/
+function buildPlaceholderContractDts(spaceId) {
+	return [
+		"/**",
+		` * Placeholder \`.d.ts\` for extension space "${spaceId}".`,
+		" *",
+		" * The framework re-emits this file on every `migration plan` run",
+		" * alongside `contract.json` and `refs/head.json`. A typed `.d.ts`",
+		" * rendering pass for extension contracts is tracked separately;",
+		" * until that ships, consumers should import `contract.json`",
+		" * and pass it through the target descriptor’s `contractSerializer`.",
+		" */",
+		"export {};",
+		""
+	].join("\n");
+}
+const FULL_HASH_PATTERN = /^([0-9a-f]{64}|empty)$/;
+function looksLikeFullHash(input) {
+	return FULL_HASH_PATTERN.test(input);
+}
+function graphIsEmpty(space) {
+	return space.packages.length === 0;
+}
+function getReachableRefs(refs, graph) {
+	return Object.entries(refs).flatMap(([name, entry]) => entry && isGraphNode(entry.hash, graph) ? [{
+		name,
+		hash: entry.hash
+	}] : []).sort((a, b) => a.name.localeCompare(b.name));
+}
+function assertFromIsGraphNode(fromHash, graph, refs, graphTipHash) {
+	try {
+		assertHashIsGraphNode(fromHash, graph);
+	} catch (error) {
+		if (MigrationToolsError.is(error) && error.code === "MIGRATION.HASH_NOT_IN_GRAPH") throw errorPlanForgotTheFlag(fromHash, getReachableRefs(refs, graph), graphTipHash, { cause: error });
+		throw error;
+	}
+}
+async function resolveContractRef(parsed, space, options) {
+	const { hash, provenance } = parsed;
+	const refName = provenance.kind === "ref" ? provenance.refName : void 0;
+	try {
+		const at = await space.contractAt(hash, refName !== void 0 ? { refName } : void 0);
+		if (at.provenance === "ref") return ok({
+			kind: "ref",
+			hash: at.hash,
+			contract: at.contract,
+			contractJson: at.contractJson,
+			contractDts: at.contractDts
+		});
+		return ok({
+			kind: "graph-node",
+			hash: at.hash,
+			contract: at.contract,
+			contractJson: at.contractJson,
+			contractDts: at.contractDts
+		});
+	} catch (error) {
+		return mapContractAtError(error, options?.artifactRole !== void 0 ? { artifactRole: options.artifactRole } : void 0);
+	}
+}
+async function resolveFromPolicy(parsed, input, refs, explicitFromLabel) {
+	const resolution = await resolveContractRef(parsed, input.space, {
+		...explicitFromLabel !== void 0 ? { explicitLabel: explicitFromLabel } : {},
+		artifactRole: "from"
+	});
+	if (!resolution.ok) return resolution;
+	if (resolution.value.kind === "graph-node") return ok({
+		kind: "graph-node",
+		fromHash: resolution.value.hash,
+		fromContract: resolution.value.contract
+	});
+	const { hash, contract, contractJson, contractDts } = resolution.value;
+	if (graphIsEmpty(input.space)) return ok({
+		kind: "auto-baseline",
+		fromHash: hash,
+		fromContract: contract,
+		contractDts,
+		contractJson
+	});
+	const graph = input.space.graph();
+	const graphTip = findLatestMigration(graph)?.to ?? null;
+	try {
+		assertFromIsGraphNode(hash, graph, refs, graphTip);
+	} catch (error) {
+		if (CliStructuredError$1.is(error)) return notOk(error);
+		throw error;
+	}
+	return ok({
+		kind: "ref",
+		fromHash: hash,
+		fromContract: contract,
+		contractDts,
+		contractJson
+	});
+}
+async function resolveFromForPlan(input) {
+	const { optionsFrom, space } = input;
+	const graph = space.graph();
+	const refs = space.refs;
+	if (optionsFrom === void 0) {
+		const dbRef = refs["db"];
+		if (!dbRef) {
+			if (graphIsEmpty(space)) return ok({
+				kind: "greenfield",
+				fromHash: null,
+				fromContract: null,
+				defaulted: true
+			});
+			return notOk(errorPlanOriginUnknown(getReachableRefs(refs, graph), findLatestMigration(graph)?.to ?? null));
+		}
+		return resolveFromPolicy({
+			hash: dbRef.hash,
+			provenance: {
+				kind: "ref",
+				refName: "db"
+			}
+		}, input, refs);
+	}
+	const refResult = parseContractRef(optionsFrom, {
+		graph,
+		refs
+	});
+	if (!refResult.ok) {
+		if (looksLikeFullHash(optionsFrom)) {
+			const empty = graphIsEmpty(space);
+			const graphTip = findLatestMigration(graph)?.to ?? null;
+			if (empty) return notOk(errorSnapshotMissing(optionsFrom, { viaRef: false }));
+			return notOk(errorPlanForgotTheFlag(optionsFrom, getReachableRefs(refs, graph), graphTip));
+		}
+		return notOk(mapRefResolutionError(refResult.failure));
+	}
+	if (refResult.value.provenance.kind === "reserved-empty") return ok({
+		kind: "greenfield",
+		fromHash: null,
+		fromContract: null,
+		defaulted: false
+	});
+	return resolveFromPolicy(refResult.value, input, refs, optionsFrom);
+}
+async function resolveToForPlan(optionsTo, input) {
+	const { space } = input;
+	const graph = space.graph();
+	const refs = space.refs;
+	const refResult = parseContractRef(optionsTo, {
+		graph,
+		refs
+	});
+	if (!refResult.ok) return notOk(mapRefResolutionError(refResult.failure));
+	if (refResult.value.provenance.kind === "reserved-empty") return notOk(mapRefResolutionError({
+		kind: "wrong-grammar",
+		input: optionsTo,
+		expectedGrammar: "contract",
+		message: "`@empty` is only valid as an origin (`--from`); planning a migration to the empty contract is not supported through this shortcut",
+		fix: "Pass `--to` a contract hash, ref name, or migration directory name. To plan starting from an empty database, use `--from @empty`."
+	}));
+	const resolution = await resolveContractRef(refResult.value, space, {
+		explicitLabel: optionsTo,
+		artifactRole: "to"
+	});
+	if (!resolution.ok) return resolution;
+	const { hash, contract, contractJson, contractDts } = resolution.value;
+	return ok({
+		hash,
+		contract,
+		contractJson,
+		contractDts
+	});
+}
+/**
+* Policy core of `migration plan`: resolves from/to contracts, runs the planner legs, and writes the planned migration packages.
+*/
+function isEnoent(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function runPlannerLeg(planner, migrations, frameworkComponents, contract, fromContract, spaceId, ownership, snapshotsImportPath, resolveImportSpecifier) {
+	const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
+	const plannerResult = planner.plan({
+		contract,
+		schema: fromSchema,
+		policy: { allowedOperationClasses: [
+			"additive",
+			"widening",
+			"destructive",
+			"data"
+		] },
+		fromContract,
+		frameworkComponents,
+		spaceId,
+		ownership,
+		snapshotsImportPath
+	});
+	if (plannerResult.kind === "failure") return notOk(errorMigrationPlanningFailed({ conflicts: castAs(plannerResult.conflicts) }));
+	let plannedOps = [];
+	let hasPlaceholders = false;
+	try {
+		plannedOps = await Promise.all(plannerResult.plan.operations);
+		if (plannedOps.length === 0) return notOk(errorMigrationPlanningFailed({ conflicts: [{
+			kind: "unsupportedChange",
+			summary: "Contract changed but planner produced no operations. This indicates unsupported or ignored changes."
+		}] }));
+	} catch (e) {
+		if (CliStructuredError$1.is(e) && e.code === "MIGRATION.UNFILLED_PLACEHOLDER") hasPlaceholders = true;
+		else throw e;
+	}
+	return ok({
+		plannedOps,
+		migrationTsContent: plannerResult.plan.renderTypeScript(resolveImportSpecifier),
+		hasPlaceholders
+	});
+}
+async function writePlannedMigrationPackage(packageDir, fromHash, toHash, createdAt, leg) {
+	const opsForWrite = leg.hasPlaceholders ? [] : leg.plannedOps;
+	const metadataWithInvariants = {
+		from: fromHash,
+		to: toHash,
+		providedInvariants: deriveProvidedInvariants(opsForWrite),
+		createdAt: createdAt.toISOString()
+	};
+	await writeMigrationPackage(packageDir, {
+		...metadataWithInvariants,
+		migrationHash: computeMigrationHash(metadataWithInvariants, opsForWrite)
+	}, opsForWrite);
+	await writeMigrationTs(packageDir, leg.migrationTsContent);
+}
+async function executeMigrationPlanCommand(options, startTime, callbacks) {
+	try {
+		return await executeMigrationPlanCommandInner(options, startTime, callbacks);
+	} catch (error) {
+		if (CliStructuredError$1.is(error)) return notOk(error);
+		const message = error instanceof Error ? error.message : String(error);
+		return notOk(errorUnexpected(message, { why: `Unexpected error during migration plan: ${message}` }));
+	}
+}
+async function executeMigrationPlanCommandInner(options, startTime, callbacks) {
+	const config = options.config;
+	const cwd = options.cwd;
+	const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(options.configPath, config, cwd);
+	const contractPathAbsolute = resolveContractPath(config);
+	const contractPath = relative(cwd, contractPathAbsolute);
+	callbacks?.onContextResolved?.({
+		configPath,
+		contractPath,
+		appMigrationsRelative
+	});
+	let contractJsonContent;
+	try {
+		contractJsonContent = await readFile(contractPathAbsolute, "utf-8");
+	} catch (error) {
+		if (isEnoent(error)) return notOk(errorFileNotFound(contractPathAbsolute, {
+			why: `Contract file not found at ${contractPathAbsolute}`,
+			fix: `Run \`{bin} contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`
+		}));
+		return notOk(errorUnexpected(error instanceof Error ? error.message : String(error), { why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}` }));
+	}
+	const stack = createControlStack(config);
+	const familyInstance = config.family.create(stack);
+	const controlAdapter = config.adapter.create(stack);
+	let toContract;
+	try {
+		toContract = familyInstance.deserializeContract(castAs(JSON.parse(contractJsonContent)));
+	} catch (error) {
+		return notOk(errorContractValidationFailed(`Contract at ${contractPathAbsolute} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`, { where: { path: contractPathAbsolute } }));
+	}
+	const rawStorageHash = toContract.storage?.storageHash;
+	if (typeof rawStorageHash !== "string") return notOk(errorContractValidationFailed("Contract is missing storageHash", { where: { path: contractPathAbsolute } }));
+	let toStorageHash = rawStorageHash;
+	let toArtifacts = null;
+	let fromContract = null;
+	let fromHash = null;
+	let snapshotStartContract = null;
+	let isAutoBaseline = false;
+	let fromDefaulted = false;
+	const tolerantAggregateResult = await loadContractSpaceAggregateForCli({
+		targetId: config.target.targetId,
+		migrationsDir,
+		appContract: toContract,
+		extensions: config.extensions ?? [],
+		deserializeContract: (json) => familyInstance.deserializeContract(json)
+	});
+	if (!tolerantAggregateResult.ok) return notOk(tolerantAggregateResult.failure);
+	const resolutionSpace = tolerantAggregateResult.value.app;
+	const resolutionResult = await resolveFromForPlan({
+		optionsFrom: options.from,
+		space: resolutionSpace
+	});
+	if (!resolutionResult.ok) return notOk(resolutionResult.failure);
+	switch (resolutionResult.value.kind) {
+		case "greenfield":
+			fromDefaulted = resolutionResult.value.defaulted;
+			break;
+		case "graph-node":
+			fromHash = resolutionResult.value.fromHash;
+			fromContract = resolutionResult.value.fromContract;
+			break;
+		case "ref":
+			fromHash = resolutionResult.value.fromHash;
+			fromContract = resolutionResult.value.fromContract;
+			snapshotStartContract = {
+				fromHash: resolutionResult.value.fromHash,
+				contractJson: resolutionResult.value.contractJson,
+				contractDts: resolutionResult.value.contractDts
+			};
+			break;
+		case "auto-baseline":
+			fromHash = resolutionResult.value.fromHash;
+			fromContract = resolutionResult.value.fromContract;
+			snapshotStartContract = {
+				fromHash: resolutionResult.value.fromHash,
+				contractJson: resolutionResult.value.contractJson,
+				contractDts: resolutionResult.value.contractDts
+			};
+			isAutoBaseline = true;
+			break;
+	}
+	if (options.to !== void 0) {
+		const toResolution = await resolveToForPlan(options.to, { space: resolutionSpace });
+		if (!toResolution.ok) return notOk(toResolution.failure);
+		toContract = toResolution.value.contract;
+		toStorageHash = toResolution.value.hash;
+		toArtifacts = {
+			contractJson: toResolution.value.contractJson,
+			contractDts: toResolution.value.contractDts
+		};
+	}
+	const resolveImportSpecifier = createProjectSpecifierResolver(options.configPath);
+	const seedResult = await runContractSpaceSeedPhase({
+		migrationsDir,
+		extensions: toExtensionInputs(config.extensions ?? [])
+	});
+	for (const record of seedResult.seeded) callbacks?.onSeeded?.(record);
+	const emittedExtensionDirs = seedResult.seeded.flatMap((r) => r.newMigrationDirs.map((dirName) => ({
+		spaceId: r.spaceId,
+		dirName
+	})));
+	if (fromHash === toStorageHash && !isAutoBaseline) return ok({
+		ok: true,
+		noOp: true,
+		from: fromHash,
+		to: toStorageHash,
+		operations: [],
+		emittedExtensionDirs,
+		summary: "No changes detected between contracts",
+		timings: { total: Date.now() - startTime }
+	});
+	const migrations = getTargetMigrations(config.target);
+	if (!migrations) return notOk(errorTargetMigrationNotSupported({ why: `Target "${config.target.id}" does not support migrations` }));
+	const aggregateResult = await buildContractSpaceAggregate({
+		targetId: config.target.targetId,
+		migrationsDir,
+		appContract: toContract,
+		extensions: config.extensions ?? [],
+		deserializeContract: (json) => familyInstance.deserializeContract(json)
+	});
+	if (!aggregateResult.ok) return notOk(aggregateResult.failure);
+	const aggregate = aggregateResult.value;
+	const frameworkComponents = assertFrameworkComponentsCompatible(config.family.familyId, config.target.targetId, [
+		config.target,
+		config.adapter,
+		...config.extensions ?? []
+	]);
+	async function writeDestinationSnapshot(destHash) {
+		if (toArtifacts !== null) {
+			await writeContractSnapshot(migrationsDir, destHash, {
+				contractJson: toArtifacts.contractJson,
+				contractDts: toArtifacts.contractDts
+			});
+			return;
+		}
+		const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
+		const [contractJsonRaw, contractDts] = await Promise.all([readFile(destinationArtifacts.jsonPath, "utf-8"), readFile(destinationArtifacts.dtsPath, "utf-8")]);
+		await writeContractSnapshot(migrationsDir, destHash, {
+			contractJson: castAs(JSON.parse(contractJsonRaw)),
+			contractDts
+		});
+	}
+	try {
+		const planner = migrations.createPlanner(controlAdapter);
+		if (isAutoBaseline && fromHash !== null && fromContract !== null && snapshotStartContract !== null) {
+			const baselineTimestamp = /* @__PURE__ */ new Date();
+			const deltaTimestamp = new Date(baselineTimestamp.getTime() + 6e4);
+			const baselineDirName = formatMigrationDirName(baselineTimestamp, "baseline");
+			const deltaDirName = formatMigrationDirName(deltaTimestamp, options.name ?? "migration");
+			const baselinePackageDir = join(appMigrationsDir, baselineDirName);
+			const deltaPackageDir = join(appMigrationsDir, deltaDirName);
+			const baselineLeg = await runPlannerLeg(planner, migrations, frameworkComponents, fromContract, null, aggregate.app.spaceId, aggregate, snapshotsImportPathFrom(baselinePackageDir, migrationsDir), resolveImportSpecifier);
+			if (!baselineLeg.ok) return notOk(baselineLeg.failure);
+			await writePlannedMigrationPackage(baselinePackageDir, null, fromHash, baselineTimestamp, baselineLeg.value);
+			await writeContractSnapshot(migrationsDir, fromHash, {
+				contractJson: snapshotStartContract.contractJson,
+				contractDts: snapshotStartContract.contractDts
+			});
+			if (fromHash === toStorageHash) {
+				const baselineOps = baselineLeg.value.hasPlaceholders ? [] : baselineLeg.value.plannedOps;
+				if (baselineLeg.value.hasPlaceholders) {
+					const baselineDir = relative(cwd, baselinePackageDir);
+					return ok({
+						ok: true,
+						noOp: false,
+						from: fromHash,
+						to: toStorageHash,
+						dir: baselineDir,
+						baselineDir,
+						operations: [],
+						emittedExtensionDirs,
+						pendingPlaceholders: true,
+						summary: "Planned baseline with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit",
+						timings: { total: Date.now() - startTime }
+					});
+				}
+				const preview = hasOperationPreview(familyInstance) ? familyInstance.toOperationPreview(baselineOps) : void 0;
+				return ok({
+					ok: true,
+					noOp: false,
+					from: fromHash,
+					to: toStorageHash,
+					baselineDir: relative(cwd, baselinePackageDir),
+					operations: baselineOps.map((op) => ({
+						id: op.id,
+						label: op.label,
+						operationClass: op.operationClass
+					})),
+					emittedExtensionDirs,
+					...preview !== void 0 ? { preview } : {},
+					summary: buildAutoBaselinePlanSummary(0, emittedExtensionDirs.length),
+					timings: { total: Date.now() - startTime }
+				});
+			}
+			const deltaLeg = await runPlannerLeg(planner, migrations, frameworkComponents, aggregate.app.contract(), fromContract, aggregate.app.spaceId, aggregate, snapshotsImportPathFrom(deltaPackageDir, migrationsDir), resolveImportSpecifier);
+			if (!deltaLeg.ok) return notOk(deltaLeg.failure);
+			await writePlannedMigrationPackage(deltaPackageDir, fromHash, toStorageHash, deltaTimestamp, deltaLeg.value);
+			await writeDestinationSnapshot(toStorageHash);
+			await writeContractSnapshot(migrationsDir, fromHash, {
+				contractJson: snapshotStartContract.contractJson,
+				contractDts: snapshotStartContract.contractDts
+			});
+			const deltaOps = deltaLeg.value.hasPlaceholders ? [] : deltaLeg.value.plannedOps;
+			if (deltaLeg.value.hasPlaceholders) return ok({
+				ok: true,
+				noOp: false,
+				from: fromHash,
+				to: toStorageHash,
+				dir: relative(cwd, deltaPackageDir),
+				baselineDir: relative(cwd, baselinePackageDir),
+				operations: [],
+				emittedExtensionDirs,
+				pendingPlaceholders: true,
+				summary: "Planned baseline + migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit",
+				timings: { total: Date.now() - startTime }
+			});
+			const preview = hasOperationPreview(familyInstance) ? familyInstance.toOperationPreview(deltaOps) : void 0;
+			return ok({
+				ok: true,
+				noOp: false,
+				from: fromHash,
+				to: toStorageHash,
+				dir: relative(cwd, deltaPackageDir),
+				baselineDir: relative(cwd, baselinePackageDir),
+				operations: deltaOps.map((op) => ({
+					id: op.id,
+					label: op.label,
+					operationClass: op.operationClass
+				})),
+				emittedExtensionDirs,
+				...preview !== void 0 ? { preview } : {},
+				summary: buildAutoBaselinePlanSummary(deltaOps.length, emittedExtensionDirs.length),
+				timings: { total: Date.now() - startTime }
+			});
+		}
+		const timestamp = /* @__PURE__ */ new Date();
+		const packageDir = join(appMigrationsDir, formatMigrationDirName(timestamp, options.name ?? "migration"));
+		const deltaLeg = await runPlannerLeg(planner, migrations, frameworkComponents, aggregate.app.contract(), fromContract, aggregate.app.spaceId, aggregate, snapshotsImportPathFrom(packageDir, migrationsDir), resolveImportSpecifier);
+		if (!deltaLeg.ok) return notOk(deltaLeg.failure);
+		await writePlannedMigrationPackage(packageDir, fromHash, toStorageHash, timestamp, deltaLeg.value);
+		await writeDestinationSnapshot(toStorageHash);
+		if (snapshotStartContract !== null) await writeContractSnapshot(migrationsDir, snapshotStartContract.fromHash, {
+			contractJson: snapshotStartContract.contractJson,
+			contractDts: snapshotStartContract.contractDts
+		});
+		if (deltaLeg.value.hasPlaceholders) return ok({
+			ok: true,
+			noOp: false,
+			from: fromHash,
+			to: toStorageHash,
+			dir: relative(cwd, packageDir),
+			operations: [],
+			emittedExtensionDirs,
+			pendingPlaceholders: true,
+			...fromDefaulted ? { fromDefaulted } : {},
+			summary: "Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit",
+			timings: { total: Date.now() - startTime }
+		});
+		const plannedOps = deltaLeg.value.plannedOps;
+		const preview = hasOperationPreview(familyInstance) ? familyInstance.toOperationPreview(plannedOps) : void 0;
+		return ok({
+			ok: true,
+			noOp: false,
+			from: fromHash,
+			to: toStorageHash,
+			dir: relative(cwd, packageDir),
+			operations: plannedOps.map((op) => ({
+				id: op.id,
+				label: op.label,
+				operationClass: op.operationClass
+			})),
+			emittedExtensionDirs,
+			...preview !== void 0 ? { preview } : {},
+			...fromDefaulted ? { fromDefaulted } : {},
+			summary: buildPlanSummary(plannedOps.length, emittedExtensionDirs.length),
+			timings: { total: Date.now() - startTime }
+		});
+	} catch (error) {
+		if (CliStructuredError$1.is(error)) return notOk(error);
+		if (MigrationToolsError.is(error)) return notOk(error);
+		const message = error instanceof Error ? error.message : String(error);
+		return notOk(errorUnexpected(message, { why: `Unexpected error during migration plan: ${message}` }));
+	}
+}
+/**
+* Compose the success-line summary so the cross-space side effect
+* (extension-space migration packages materialised on disk during
+* this `plan` run) is visible in the top line — not just in the
+* step log above it.
+*
+* Example outputs:
+*   - `Planned 3 operation(s)` (app-space-only project)
+*   - `Planned 3 operation(s); materialised 1 extension-space migration` (one extension)
+*   - `Planned 3 operation(s); materialised 2 extension-space migrations` (two extensions)
+*
+* Locks AC3 at the summary-line level: a reader of the success line
+* can tell that something happened beyond the app space.
+*/
+function buildPlanSummary(plannedOpsCount, emittedExtensionDirsCount) {
+	const base = `Planned ${plannedOpsCount} operation(s)`;
+	if (emittedExtensionDirsCount === 0) return base;
+	return `${base}; materialised ${emittedExtensionDirsCount} ${emittedExtensionDirsCount === 1 ? "extension-space migration" : "extension-space migrations"}`;
+}
+function buildAutoBaselinePlanSummary(deltaOpsCount, emittedExtensionDirsCount) {
+	const base = `Planned baseline + ${deltaOpsCount} operation(s)`;
+	if (emittedExtensionDirsCount === 0) return base;
+	return `${base}; materialised ${emittedExtensionDirsCount} ${emittedExtensionDirsCount === 1 ? "extension-space migration" : "extension-space migrations"}`;
+}
+/** Origin hash for status path computation: the live/override marker, or the empty-contract sentinel. */
+function originHashForStatus(markerHash) {
+	return markerHash ?? "empty";
+}
+function deriveStatusEdgeAnnotations(input) {
+	const annotations = /* @__PURE__ */ new Map();
+	if (input.showAppliedOverlay) {
+		for (const edge of input.graph.migrationByHash.values()) if (input.appliedMigrationHashes.has(edge.migrationHash)) annotations.set(edge.migrationHash, { status: "applied" });
+	}
+	if (!input.graph.nodes.has(input.originHash)) return annotations;
+	const pendingPath = findPath(input.graph, input.originHash, input.targetHash);
+	if (!pendingPath) return annotations;
+	for (const edge of pendingPath) {
+		if (input.appliedMigrationHashes.has(edge.migrationHash)) continue;
+		if (annotations.get(edge.migrationHash)?.status === "applied") continue;
+		annotations.set(edge.migrationHash, { status: "pending" });
+	}
+	return annotations;
+}
+function appliedHashesFromLedger(ledgerEntries) {
+	return new Set(ledgerEntries.map((entry) => entry.migrationHash));
+}
+function statusForMigrationHash(migrationHash, annotations) {
+	return annotations.get(migrationHash)?.status ?? null;
+}
+/**
+* Reads the migrations refs index for commands, mapping MigrationToolsError into the CLI envelope.
+*/
+/** Reads migrations/<app>/refs, passing MigrationToolsError through; other errors rethrow. */
+async function readMigrationRefs(refsDir) {
+	try {
+		return ok(await readRefs(refsDir));
+	} catch (error) {
+		if (MigrationToolsError.is(error)) return notOk(error);
+		throw error;
+	}
+}
+function mapError(error) {
+	if (MigrationToolsError.is(error)) return error;
+	return errorUnexpected(error instanceof Error ? error.message : String(error));
+}
+function cliErrorInvalidRefName(name) {
+	return errorRuntime("MIGRATION.INVALID_REF_NAME", `Invalid ref name "${name}"`, {
+		why: `Ref name "${name}" does not match the required format`,
+		fix: "Ref names must be lowercase alphanumeric with hyphens or forward slashes, no `.` or `..` segments"
+	});
+}
+async function executeRefSetCommand(name, contractInput, options) {
+	if (!validateRefName(name)) return notOk(cliErrorInvalidRefName(name));
+	const config = options.config;
+	try {
+		const { migrationsDir, refsDir } = resolveMigrationPaths(options.configPath, config, options.cwd);
+		const loaded = await buildReadAggregate(config, { migrationsDir });
+		if (!loaded.ok) return notOk(loaded.failure);
+		const graph = loaded.value.aggregate.app.graph();
+		const bundles = loaded.value.aggregate.app.packages;
+		const refs = loaded.value.aggregate.app.refs;
+		let resolvedHash;
+		if (validateRefValue(contractInput)) resolvedHash = contractInput;
+		else {
+			const refResult = parseContractRef(contractInput, {
+				graph,
+				refs
+			});
+			if (!refResult.ok) return notOk(mapRefResolutionError(refResult.failure));
+			resolvedHash = refResult.value.hash;
+		}
+		if (resolvedHash === "empty") return notOk(errorRefSetEmptySentinel(resolvedHash));
+		if (!isGraphNode(resolvedHash, graph)) {
+			const graphTip = findLatestMigration(graph)?.to ?? null;
+			return notOk(errorRefSetHashNotInGraph(resolvedHash, [...graph.nodes].sort(), graphTip));
+		}
+		if (!bundles.find((bundle) => bundle.metadata.to === resolvedHash)) return notOk(errorRefSetBundleNotFound(resolvedHash));
+		const contractJsonPath = join(contractSnapshotDir(migrationsDir, resolvedHash), "contract.json");
+		try {
+			await readContractSnapshotJson(migrationsDir, resolvedHash);
+		} catch (readError) {
+			if (MigrationToolsError.is(readError) && readError.code === "MIGRATION.CONTRACT_SNAPSHOT_MISSING") return notOk(errorFileNotFound(contractJsonPath, {
+				why: `Migration bundle for hash ${resolvedHash} is missing its contract snapshot at ${contractJsonPath}`,
+				fix: "Restore migrations/snapshots/ from version control, or re-run the command that produced this migration to regenerate its snapshot."
+			}));
+			throw readError;
+		}
+		await writeRef(refsDir, name, {
+			hash: resolvedHash,
+			invariants: []
+		});
+		return ok({
+			ok: true,
+			ref: name,
+			hash: resolvedHash,
+			invariants: []
+		});
+	} catch (error) {
+		if (error instanceof CliStructuredError$1) return notOk(error);
+		return notOk(mapError(error));
+	}
+}
+async function executeRefDeleteCommand(name, options) {
+	try {
+		const { refsDir } = resolveMigrationPaths(options.configPath, options.config, options.cwd);
+		await deleteRef(refsDir, name);
+		return ok({
+			ok: true,
+			ref: name,
+			deleted: true
+		});
+	} catch (error) {
+		if (error instanceof CliStructuredError$1) return notOk(error);
+		return notOk(mapError(error));
+	}
+}
+async function executeRefListCommand(options) {
+	try {
+		const { refsDir } = resolveMigrationPaths(options.configPath, options.config, options.cwd);
+		return ok({
+			ok: true,
+			refs: await readRefs(refsDir)
+		});
+	} catch (error) {
+		if (error instanceof CliStructuredError$1) return notOk(error);
+		return notOk(mapError(error));
+	}
+}
+//#endregion
+export { loadAggregateIntegrityViolations as $, errorMigrationPackageNotFound as A, runMigrationList as At, executeDbInit as B, errorDatabaseConnectionRequired as C, resolveFromForPlan as Ct, errorHashMismatch as D, runCommandAction as Dt, errorFileNotFound as E, resolveToForPlan as Et, errorRuntime as F, executeMigrationPlanCommand as G, executeDbVerify as H, errorTargetMigrationNotSupported as I, executeRefListCommand as J, executeRefAdvancement as K, errorTargetMismatch as L, errorNoMigrations as M, statusForMigrationHash as Mt, errorPathUnreachable as N, targetSupportsMigrations as Nt, errorLegendHumanOnly as O, runContractSpaceSeedPhase as Ot, errorRunnerFailed as P, toDeclaredExtensionsFromRaw as Pt, listRefsByContractHash as Q, errorUnexpected as R, errorContractValidationFailed as S, resolveContractRefToSnapshot as St, errorDriverRequired as T, resolveRefAdvancementFields as Tt, executeMigrateShowPlan as U, executeDbUpdate as V, executeMigrationNewCommand as W, findPackageByDirPath as X, executeRefSetCommand as Y, hasMigrationPath as Z, enumerateCheckSpaces as _, refusePackageCorruptionOnAggregate as _t, buildContractSpaceAggregate as a, mapIntegrityViolations as at, errorConsentPlanMismatch as b, resolveAppTargetPath as bt, buildRefAdvancementFields as c, originHashForStatus as ct, closeQuietly as d, readContractIR as dt, loadContractRawSafely as et, computeRefAdvancementName as f, readMigrationRefs as ft, enrichContract as g, refuseMissingInvariantPath as gt, disposeEmitQueue as h, refuseMarkerOutsideGraph as ht, appliedHashesFromLedger as i, mapContractAtError as it, errorMigrationPlanningFailed as j, sanitizeErrorMessage as jt, errorMarkerMissing as k, runMigrationCheck as kt, checkSingleTarget as l, preflightRefAdvancement as lt, deriveStatusEdgeAnnotations as m, refuseDeclaredExtensionTargetMismatch as mt, advanceRefSafely as n, looksLikePath as nt, buildMigrationSpaceGraphEntries as o, maskConnectionUrl as ot, createControlClient as p, refuseContractSpaceIntegrity as pt, executeRefDeleteCommand as q, appContractStandInFromIdentity as r, mapCaughtMigrationError as rt, buildReadAggregate as s, migrationSpaceListEntriesFromAggregate as st, CliStructuredError$1 as t, loadContractSpaceAggregateForCli as tt, chooseAction as u, readContractEnvelope as ut, errorAdvanceRefArgConflict as v, refuseUnknownInvariants as vt, errorDestructiveChanges as w, resolveMigrationRef as wt, errorContractArgConflict as x, resolveContractRef$1 as xt, errorConfigValidation$1 as y, requireLiveDatabase as yt, executeContractEmit as z };
+
+//# sourceMappingURL=ref-DcqFmceq-QaUjgZeM.mjs.map