@prisma/orm-toolchain 0.16.0-dev.36

package/dist/client-75qrAPqf-DZAVUxFa.mjs

@@ -0,0 +1,1606 @@
+import { O as errorNoInvariantPath } from "./errors-IpZm1Skp-BH495dRd.mjs";
+import "./constants-CM-w38DQ-Cz_EXbOc.mjs";
+import { o as findPathWithDecision } from "./migration-graph-CBf9ORe7-B4xAF8GN.mjs";
+import { t as CliStructuredError$1 } from "./command-helpers-CAoXqAY9-DWUBcTXM.mjs";
+import { t as assertFrameworkComponentsCompatible } from "./framework-components-CjshQKHA-Dlp6Leo5.mjs";
+import { t as enrichContract } from "./contract-enrichment-DrMvvY2A-DxNGeF4d.mjs";
+import { t as emit } from "./exports-D3-NwrMA-CadaBGQ3.mjs";
+import { d as resolveRecordedPath, f as verifyMigration, l as planMigration, n as buildFabricatedMigrationEdge, r as collectAggregateNamespaces, t as allStorageElementsExternal, u as requireHeadRef } from "./aggregate-B4mhR4Sk.mjs";
+import { t as buildContractSpaceAggregate } from "./contract-space-aggregate-loader-CFH-336b-BhAyRQEL.mjs";
+import { CliStructuredError } from "@prisma/orm-framework/errors/control";
+import { ifDefined } from "@prisma/orm-framework/utils/defined";
+import { notOk, ok } from "@prisma/orm-framework/utils/result";
+import { APP_SPACE_ID, createControlStack, hasMigrations, hasOperationPreview, hasPslContractInfer, hasSchemaSubjectClassifier, hasSchemaView } from "@prisma/orm-framework/components/control";
+import { blindCast, castAs } from "@prisma/orm-framework/utils/casts";
+import { InternalError } from "@prisma/orm-framework/utils/internal-error";
+import { structuredError } from "@prisma/orm-framework/utils/structured-error";
+//#region ../../../1-framework/3-tooling/cli/dist/client-75qrAPqf.mjs
+/**
+* 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
+	}));
+}
+/**
+* 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
+			}
+		});
+	}
+	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)
+		});
+	}
+	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)
+	});
+	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)
+	}));
+}
+/**
+* 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) {
+		const gate = await guardDestructiveChanges(sharedInputs);
+		if (gate !== null) return gate;
+	}
+	return await executeRun({
+		...sharedInputs,
+		mode: options.mode
+	});
+}
+/**
+* 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;
+	return notOk({
+		code: "DESTRUCTIVE_CHANGES",
+		summary: `Planned ${destructiveOps.length} destructive operation(s) that require confirmation`,
+		why: "Destructive operations require confirmation — re-run with -y to accept",
+		conflicts: void 0,
+		meta: { destructiveOperations: destructiveOps }
+	});
+}
+/**
+* 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 mismatches map to
+*    `CliStructuredError` (code `5002`) so callers (CLI command) can render
+*    and exit. 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
+	});
+}
+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 } = 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 markerError = skipMarker ? null : mapMarkerCheckFailures(aggregate.app.spaceId, verifyResult.value.markerCheck);
+	if (markerError !== null) {
+		emitVerifySpan(onProgress, "spanEndError");
+		return notOk(markerError);
+	}
+	emitVerifySpan(onProgress, "spanEndOk");
+	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
+	});
+}
+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) {
+	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 `prisma-next db update` to advance the marker, or roll the database back to the recorded hash." : `Apply on-disk migrations under \`migrations/${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 \`migrations/${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-next.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 \`migrations/\` 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));
+		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
+	});
+	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) {
+	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 \`migrations/${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 Next 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("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) });
+			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
+			});
+		}
+	}
+};
+//#endregion
+export { planSpacePath as a, executeDbVerify as i, executeDbInit as n, executeDbUpdate as r, createControlClient as t };
+
+//# sourceMappingURL=client-75qrAPqf-DZAVUxFa.mjs.map