prisma-next 0.5.0-dev.9 → 0.5.0

package/dist/client-qVH-rEgd.mjs

@@ -0,0 +1,1595 @@
+import { p as errorRunnerFailed, t as CliStructuredError } from "./cli-errors-D3_sMh2K.mjs";
+import { t as assertFrameworkComponentsCompatible } from "./framework-components-ChqVUxR-.mjs";
+import { t as enrichContract } from "./contract-enrichment-Dani0mMW.mjs";
+import { n as toExtensionInputs, t as toDeclaredExtensions } from "./extension-pack-inputs-C7xgE-vv.mjs";
+import { emit } from "@prisma-next/emitter";
+import { ifDefined } from "@prisma-next/utils/defined";
+import { notOk, ok } from "@prisma-next/utils/result";
+import { APP_SPACE_ID, createControlStack, hasMigrations, hasMultiSpaceRunner, hasOperationPreview, hasPslContractInfer, hasSchemaView } from "@prisma-next/framework-components/control";
+import { findPathWithDecision } from "@prisma-next/migration-tools/migration-graph";
+import { graphWalkStrategy, loadContractSpaceAggregate, planAggregate, verifyAggregate } from "@prisma-next/migration-tools/aggregate";
+import { EMPTY_CONTRACT_HASH } from "@prisma-next/migration-tools/constants";
+import { errorNoInvariantPath } from "@prisma-next/migration-tools/errors";
+//#region src/control-api/errors.ts
+var ContractValidationError = class extends Error {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.name = "ContractValidationError";
+		this.cause = cause;
+	}
+};
+//#endregion
+//#region src/utils/contract-space-aggregate-loader.ts
+/**
+* Render a {@link LoadAggregateError} into a CLI structured-error
+* envelope. Preserves error codes `5001` (layout) and `5002` (marker /
+* drift / disjointness / etc.) so existing integration tests and
+* downstream tooling continue to assert on the same `meta.violations[]`
+* shape they did under the old precheck/marker-check helpers.
+*/
+function mapLoadAggregateError(error) {
+	if (error.kind === "layoutViolation") {
+		const lines = error.violations.map((v) => `- [${v.kind}] ${v.spaceId}`);
+		return new CliStructuredError("5001", error.violations.length === 1 ? "Contract-space layout violation detected" : `Contract-space layout violations detected (${error.violations.length})`, {
+			domain: "MIG",
+			why: `The on-disk \`migrations/\` directory and your \`extensionPacks\` declaration are not in agreement.\n${lines.join("\n")}`,
+			fix: "Run `prisma-next migrate` to materialise on-disk artefacts for declared extensions, or remove the orphan directory.",
+			docsUrl: "https://pris.ly/contract-spaces",
+			meta: { violations: error.violations.map((v) => ({
+				kind: v.kind,
+				spaceId: v.spaceId
+			})) }
+		});
+	}
+	if (error.kind === "driftViolation") return new CliStructuredError("5002", `Contract-space drift detected for "${error.spaceId}"`, {
+		domain: "MIG",
+		why: `The on-disk contract for space "${error.spaceId}" (hash ${error.priorHeadHash}) does not match the live extension descriptor (hash ${error.liveHash}).`,
+		fix: "Run `prisma-next migrate` to refresh the on-disk artefacts to match the live descriptor.",
+		docsUrl: "https://pris.ly/contract-spaces",
+		meta: { violations: [{
+			kind: "drift",
+			spaceId: error.spaceId,
+			priorHeadHash: error.priorHeadHash,
+			liveHash: error.liveHash
+		}] }
+	});
+	if (error.kind === "disjointnessViolation") return new CliStructuredError("5002", `Contract-space disjointness violation: storage element "${error.element}" claimed by multiple spaces`, {
+		domain: "MIG",
+		why: `Spaces ${error.claimedBy.map((s) => `"${s}"`).join(", ")} all claim the storage element "${error.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.",
+		docsUrl: "https://pris.ly/contract-spaces",
+		meta: { violations: [{
+			kind: "disjointness",
+			spaceId: error.claimedBy.join(","),
+			element: error.element,
+			claimedBy: error.claimedBy
+		}] }
+	});
+	if (error.kind === "integrityFailure") return new CliStructuredError("5002", `Contract-space integrity failure for "${error.spaceId}"`, {
+		domain: "MIG",
+		why: error.detail,
+		fix: "Run `prisma-next migrate` to refresh on-disk artefacts, or restore the on-disk `migrations/` directory from version control.",
+		docsUrl: "https://pris.ly/contract-spaces",
+		meta: { violations: [{
+			kind: "integrity",
+			spaceId: error.spaceId,
+			detail: error.detail
+		}] }
+	});
+	if (error.kind === "validationFailure") return new CliStructuredError("5002", `Contract-space contract validation failed for "${error.spaceId}"`, {
+		domain: "MIG",
+		why: error.detail,
+		fix: "Run `prisma-next migrate` to refresh on-disk artefacts, or fix the extension descriptor producing the invalid contract.",
+		meta: { violations: [{
+			kind: "validation",
+			spaceId: error.spaceId,
+			detail: error.detail
+		}] }
+	});
+	return new CliStructuredError("5002", `Contract-space target mismatch for "${error.spaceId}"`, {
+		domain: "MIG",
+		why: `Space "${error.spaceId}" targets "${error.actual}" but the project's adapter targets "${error.expected}".`,
+		fix: "Update the extension descriptor to target the configured database, or change the project adapter.",
+		meta: { violations: [{
+			kind: "targetMismatch",
+			spaceId: error.spaceId,
+			expected: error.expected,
+			actual: error.actual
+		}] }
+	});
+}
+/**
+* Run the aggregate loader at the CLI surface, mapping any
+* {@link LoadAggregateError} into a {@link CliStructuredError} envelope.
+*
+* App-side migration packages flow through `inputs.appMigrationPackages`
+* (defaulting to `[]`). `db init` / `db update` leave it empty: the
+* planner's `synth` strategy is used for the app member (driven by
+* `callerPolicy.ignoreGraphFor`), so the app's authored `migrations/`
+* graph does not need to be walked. `migration apply` threads the
+* already-loaded app-space packages through so the graph-walk strategy
+* can plot a path through them — replay forbids synth.
+*
+* @see specs/contract-space-aggregate-spec.md § Loader.
+*/
+async function buildContractSpaceAggregate(inputs) {
+	const { entries, hashByContractJson } = toDeclaredExtensions(toExtensionInputs(inputs.extensionPacks));
+	const result = await loadContractSpaceAggregate({
+		targetId: inputs.targetId,
+		migrationsDir: inputs.migrationsDir,
+		appContract: inputs.appContract,
+		declaredExtensions: entries,
+		validateContract: inputs.validateContract,
+		hashContract: (contractJson) => {
+			const precomputed = hashByContractJson.get(contractJson);
+			if (precomputed === void 0) throw new Error("CLI aggregate loader: encountered an extension contract without a pre-computed descriptor hash. This is a wiring bug.");
+			return precomputed;
+		},
+		appMigrationPackages: inputs.appMigrationPackages ?? []
+	});
+	if (!result.ok) return notOk(mapLoadAggregateError(result.failure));
+	return ok(result.value.aggregate);
+}
+//#endregion
+//#region src/control-api/operations/apply-aggregate.ts
+/**
+* Span id emitted via `onProgress` for the apply phase. Stable
+* identifier consumed by the structured-output renderer and by tests.
+*/
+const APPLY_SPAN_ID = "apply";
+/**
+* Runner-driving tail shared by every aggregate apply caller — `db init`,
+* `db update`, and `migration apply`. Consumes already-resolved per-space
+* plans (the planner-vs-replay distinction is owned by the caller) and
+* dispatches them to the multi-space 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 `executeAcrossSpaces` 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 applyAggregate(inputs) {
+	const { aggregate, perSpacePlans, applyOrder, driver, familyInstance, migrations, frameworkComponents, policy, action, onProgress } = inputs;
+	const orderedResolutions = collectOrdered(applyOrder, perSpacePlans);
+	const runner = migrations.createRunner(familyInstance);
+	if (!hasMultiSpaceRunner(runner)) throw errorRunnerFailed(`Runner for target "${aggregate.targetId}" does not implement \`executeAcrossSpaces\``, { why: `${labelForAction(action)} requires multi-space-capable runners (today: every SQL family runner).` });
+	onProgress?.({
+		action,
+		kind: "spanStart",
+		spanId: APPLY_SPAN_ID,
+		label: progressLabelForAction(action)
+	});
+	const perSpaceOptions = orderedResolutions.map((r) => ({
+		space: r.spaceId,
+		plan: r.entry.plan,
+		driver,
+		destinationContract: r.entry.destinationContract,
+		policy,
+		frameworkComponents,
+		strictVerification: false
+	}));
+	const runnerResult = await runner.executeAcrossSpaces({
+		driver,
+		perSpaceOptions
+	});
+	if (!runnerResult.ok) {
+		onProgress?.({
+			action,
+			kind: "spanEnd",
+			spanId: APPLY_SPAN_ID,
+			outcome: "error"
+		});
+		return notOk({
+			summary: runnerResult.failure.summary,
+			...ifDefined("why", runnerResult.failure.why),
+			meta: {
+				...runnerResult.failure.meta ?? {},
+				failingSpace: runnerResult.failure.failingSpace
+			}
+		});
+	}
+	onProgress?.({
+		action,
+		kind: "spanEnd",
+		spanId: APPLY_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
+* `AggregatePerSpaceExecutionEntry[]` 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 applyAggregate} 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 member 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 Error(`Aggregate planner output missing per-space plan for "${spaceId}"`);
+		return {
+			spaceId,
+			entry
+		};
+	});
+}
+/**
+* Action-appropriate label for the `spanStart` event the apply
+* primitive emits. `applyAggregate` is shared by `db init`, `db update`,
+* and `migration apply`; 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 "migrationApply": return "Applying migration plan across spaces";
+	}
+}
+function labelForAction(action) {
+	switch (action) {
+		case "dbInit": return "db init";
+		case "dbUpdate": return "db update";
+		case "migrationApply": return "migration apply";
+	}
+}
+//#endregion
+//#region src/control-api/operations/migration-helpers.ts
+/**
+* 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
+	}));
+}
+//#endregion
+//#region src/control-api/operations/db-apply-aggregate.ts
+/**
+* Span IDs emitted via `onProgress` during the aggregate apply 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 applyAggregate} 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 planAggregate} chooses graph-walk vs synth per
+*    member according to `callerPolicy.ignoreGraphFor`. The app member
+*    is forced through synth (today's daily-driver behaviour); every
+*    extension member walks its on-disk graph.
+* 4. **Apply** (when `mode === 'apply'`): every per-space `MigrationPlan`
+*    feeds into the runner's `executeAcrossSpaces` — one outer
+*    transaction across every space; failure on any space rolls back
+*    every space's writes.
+*/
+async function executeAggregateApply(options) {
+	const { driver, familyInstance, contract, mode, migrations, frameworkComponents, migrationsDir, extensionPacks, targetId, policy, action, onProgress } = options;
+	const loaded = await buildContractSpaceAggregate({
+		targetId,
+		migrationsDir,
+		appContract: contract,
+		extensionPacks,
+		validateContract: (json) => familyInstance.validateContract(json)
+	});
+	if (!loaded.ok) throw loaded.failure;
+	const aggregate = loaded.value;
+	const markerRows = await familyInstance.readAllMarkers({ driver });
+	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 });
+	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 planAggregate({
+		aggregate,
+		currentDBState: {
+			markersBySpaceId: markerRows,
+			schemaIntrospection: schemaIR
+		},
+		familyInstance,
+		migrations,
+		frameworkComponents,
+		callerPolicy: { ignoreGraphFor: 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 appResolution = orderedResolutions.find((r) => r.spaceId === aggregate.app.spaceId);
+	if (!appResolution) throw new Error("Aggregate planner returned no plan for the app member — 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
+		});
+	}
+	const applied = await applyAggregate({
+		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
+	});
+	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
+	});
+}
+/**
+* Compare the live `_prisma_marker` rows against the aggregate's
+* declared members. Any marker row whose `space` is not a member of
+* the aggregate is an "orphan" — typically a marker left behind by
+* an extension that was removed from `extensionPacks` without first
+* cleaning up its on-disk migrations / database tables.
+*
+* Returns a {@link CliStructuredError} envelope (code `5002`,
+* `kind: 'orphanMarker'`) for the first orphan it finds, or `null`
+* when every marker row maps to a declared member. Mirrors the M2
+* `runContractSpaceVerifierMarkerCheck` envelope so downstream
+* tooling (integration tests, JSON consumers) keeps asserting on the
+* same shape.
+*/
+function detectOrphanMarkers(aggregate, markerRows) {
+	const memberSpaceIds = 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 && !memberSpaceIds.has(spaceId)) orphans.push(spaceId);
+	if (orphans.length === 0) return null;
+	orphans.sort((a, b) => a.localeCompare(b));
+	return new CliStructuredError("5002", orphans.length === 1 ? `Orphan contract-space marker detected for "${orphans[0]}"` : `Orphan contract-space markers detected for ${orphans.length} spaces`, {
+		domain: "MIG",
+		why: `The database has \`_prisma_marker\` rows for spaces (${orphans.map((s) => `"${s}"`).join(", ")}) that are not declared in the project's \`extensionPacks\`. The aggregate pipeline refuses to advance markers it cannot account for.`,
+		fix: "Either re-declare the missing extension(s) in `extensionPacks` (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 === "appSynthFailure") return 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
+	});
+}
+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
+	});
+}
+function buildRunnerFailure(args) {
+	return notOk({
+		code: "RUNNER_FAILED",
+		summary: args.summary,
+		why: args.why,
+		meta: args.meta,
+		conflicts: void 0
+	});
+}
+//#endregion
+//#region src/control-api/operations/db-init.ts
+/**
+* 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 executeAggregateApply({
+		driver: options.driver,
+		familyInstance: options.familyInstance,
+		contract: options.contract,
+		mode: options.mode,
+		migrations: options.migrations,
+		frameworkComponents: options.frameworkComponents,
+		migrationsDir: options.migrationsDir,
+		targetId: options.targetId,
+		extensionPacks: options.extensionPacks ?? [],
+		policy: { allowedOperationClasses: ["additive"] },
+		action: "dbInit",
+		...ifDefined("onProgress", options.onProgress)
+	});
+}
+//#endregion
+//#region src/control-api/operations/db-update.ts
+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,
+		familyInstance: options.familyInstance,
+		contract: options.contract,
+		migrations: options.migrations,
+		frameworkComponents: options.frameworkComponents,
+		migrationsDir: options.migrationsDir,
+		targetId: options.targetId,
+		extensionPacks: options.extensionPacks ?? [],
+		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 executeAggregateApply({
+		...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 executeAggregateApply({
+		...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 }
+	});
+}
+//#endregion
+//#region src/control-api/operations/db-verify.ts
+/**
+* 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('@prisma-next/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 verifyAggregate} returns per-space
+*    `markerCheck` + per-space pre-projected `schemaCheck` (closes F23).
+*    Marker mismatches map to `CliStructuredError` (code `5002`) so
+*    callers (CLI command) can render and exit. Schema 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
+	});
+	emitVerifySpan(onProgress, "spanStart");
+	return finaliseVerifyResult({
+		verifyResult: verifyAggregate({
+			aggregate,
+			markersBySpaceId,
+			schemaIntrospection,
+			mode: options.mode,
+			verifySchemaForMember: createPerMemberVerifier(options)
+		}),
+		aggregate,
+		skipMarker,
+		onProgress
+	});
+}
+function buildLoadInputs(options) {
+	return {
+		targetId: options.targetId,
+		migrationsDir: options.migrationsDir,
+		appContract: options.contract,
+		extensionPacks: options.extensionPacks,
+		validateContract: (json) => options.familyInstance.validateContract(json)
+	};
+}
+async function runIntrospection(args) {
+	const { driver, familyInstance, onProgress } = args;
+	onProgress?.({
+		action: "dbVerify",
+		kind: "spanStart",
+		spanId: SPAN_IDS.introspect,
+		label: "Introspecting database schema"
+	});
+	try {
+		const result = await familyInstance.introspect({ driver });
+		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-member 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 createPerMemberVerifier(options) {
+	const { skipSchema, familyInstance, frameworkComponents } = options;
+	return (projectedSchema, member, verifyMode) => {
+		if (skipSchema) return buildSkippedSchemaResult(member);
+		return familyInstance.schemaVerifyAgainstSchema({
+			contract: member.contract,
+			schema: projectedSchema,
+			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 AggregateVerifierOutput} 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("5002", "Aggregate verifier introspection failed", {
+			domain: "MIG",
+			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,
+		memberOrder: [aggregate.app.spaceId, ...aggregate.extensions.map((e) => e.spaceId)],
+		appSpaceId: aggregate.app.spaceId
+	});
+}
+function buildSkippedSchemaResult(member) {
+	const profileHash = member.contract.profileHash;
+	return {
+		ok: true,
+		summary: "Schema verification skipped",
+		contract: {
+			storageHash: member.headRef.hash,
+			...profileHash ? { profileHash } : {}
+		},
+		target: { expected: member.contract.target },
+		schema: {
+			issues: [],
+			root: {
+				status: "pass",
+				kind: "skipped",
+				name: member.spaceId,
+				contractPath: "",
+				code: "SKIPPED",
+				message: "Schema verification skipped",
+				expected: void 0,
+				actual: void 0,
+				children: []
+			},
+			counts: {
+				pass: 0,
+				warn: 0,
+				fail: 0,
+				totalNodes: 0
+			}
+		},
+		timings: { total: 0 }
+	};
+}
+/**
+* Translate per-space marker check failures and orphan markers into a
+* single CLI structured error envelope. Preserves the legacy code
+* `5002` (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 \`extensionPacks\` 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("5002", violations.length === 1 ? "Contract-space verifier found a violation" : `Contract-space verifier found violations (${violations.length})`, {
+		domain: "MIG",
+		why: `The on-disk \`migrations/\` directory, the \`extensionPacks\` 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 }
+	});
+}
+//#endregion
+//#region src/control-api/operations/migration-apply.ts
+/**
+* Apply pending migrations across every contract space (app +
+* extensions). Replay-only: graph-walk against the on-disk graph for
+* every member; 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 member: `graphWalkStrategy` plots the path from the live
+*    marker to `member.headRef.hash` (or `refHash` for the app
+*    member when provided). Empty-graph members fail loudly — a
+*    "never planned" space is a user-error condition for replay.
+* 4. Hand off to {@link applyAggregate} (the runner-driving tail
+*    shared with `db init` / `db update`). Marker advancement is
+*    inside the per-space transaction.
+*
+* Sub-spec § `migration apply` semantics + § Required changes 1.
+*/
+async function executeMigrationApply(options) {
+	const { driver, familyInstance, contract, migrations, frameworkComponents, migrationsDir, extensionPacks, targetId, appMigrationPackages, refHash, refInvariants, refName, onProgress } = options;
+	const loaded = await buildContractSpaceAggregate({
+		targetId,
+		migrationsDir,
+		appContract: contract,
+		extensionPacks,
+		validateContract: (json) => familyInstance.validateContract(json),
+		appMigrationPackages
+	});
+	if (!loaded.ok) throw loaded.failure;
+	const aggregate = loaded.value;
+	const markerRows = await familyInstance.readAllMarkers({ driver });
+	const allMembers = [aggregate.app, ...aggregate.extensions];
+	const perSpacePlans = /* @__PURE__ */ new Map();
+	const atHeadResolutions = /* @__PURE__ */ new Map();
+	for (const member of allMembers) {
+		const isAppMember = member.spaceId === aggregate.app.spaceId;
+		const targetHash = isAppMember && refHash !== void 0 ? refHash : member.headRef.hash;
+		const liveMarker = markerRows.get(member.spaceId) ?? null;
+		if (member.migrations.graph.nodes.size === 0) {
+			const liveHash = liveMarker?.storageHash;
+			if (targetHash === liveHash || liveHash === void 0 && targetHash === EMPTY_CONTRACT_HASH) {
+				atHeadResolutions.set(member.spaceId, buildAtHeadResolution({
+					aggregateTargetId: aggregate.targetId,
+					member,
+					targetHash,
+					liveMarker
+				}));
+				continue;
+			}
+			return notOk(buildNeverPlannedFailure(member.spaceId, targetHash));
+		}
+		const targetInvariants = isAppMember && refHash !== void 0 && refInvariants !== void 0 ? refInvariants : member.headRef.invariants;
+		const targetMember = targetHash === member.headRef.hash && targetInvariants === member.headRef.invariants ? member : {
+			...member,
+			headRef: {
+				hash: targetHash,
+				invariants: targetInvariants
+			}
+		};
+		const walked = graphWalkStrategy({
+			aggregateTargetId: aggregate.targetId,
+			member: targetMember,
+			currentMarker: liveMarker,
+			...isAppMember && refName !== void 0 ? { refName } : {}
+		});
+		if (walked.kind === "unreachable") return notOk(buildPathNotFoundFailure(member.spaceId, liveMarker, targetHash));
+		if (walked.kind === "unsatisfiable") {
+			const fromHash = liveMarker?.storageHash ?? "";
+			const structural = findPathWithDecision(targetMember.migrations.graph, fromHash, targetHash, { 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({
+				...isAppMember && refName !== void 0 ? { refName } : {},
+				required: targetInvariants,
+				missing: walked.missing,
+				structuralPath
+			});
+		}
+		perSpacePlans.set(member.spaceId, walked.result);
+	}
+	const canonicalOrder = [...aggregate.extensions.map((m) => m.spaceId), aggregate.app.spaceId];
+	const applyOrder = canonicalOrder.filter((spaceId) => perSpacePlans.has(spaceId));
+	if (sumPlannedOps(applyOrder, perSpacePlans) === 0) {
+		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 Error(`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 applyAggregate({
+		aggregate,
+		perSpacePlans,
+		applyOrder,
+		driver,
+		familyInstance,
+		migrations,
+		frameworkComponents,
+		policy: { allowedOperationClasses: [
+			"additive",
+			"widening",
+			"destructive",
+			"data"
+		] },
+		action: "migrationApply",
+		...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 Error(`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), 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
+	}));
+}
+/**
+* Build a zero-op {@link AggregatePerSpacePlan} for an empty-graph
+* member whose live marker already matches the target. Lets the apply
+* pipeline thread the member 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, member, targetHash, liveMarker } = args;
+	return {
+		plan: {
+			targetId: aggregateTargetId,
+			spaceId: member.spaceId,
+			origin: liveMarker === null ? null : { storageHash: liveMarker.storageHash },
+			destination: { storageHash: targetHash },
+			operations: [],
+			providedInvariants: []
+		},
+		displayOps: [],
+		destinationContract: member.contract,
+		strategy: "graph-walk",
+		migrationEdges: []
+	};
+}
+function sumPlannedOps(applyOrder, perSpacePlans) {
+	let total = 0;
+	for (const spaceId of applyOrder) {
+		const entry = perSpacePlans.get(spaceId);
+		if (!entry) continue;
+		total += entry.plan.operations.length;
+	}
+	return total;
+}
+function buildSuccess(args) {
+	const appResolution = args.orderedResolutions.find((r) => r.spaceId === args.aggregate.app.spaceId);
+	const appMarkerHash = appResolution?.entry.plan.destination.storageHash ?? args.aggregate.app.headRef.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 } : {}
+	};
+}
+function buildNeverPlannedFailure(spaceId, targetHash) {
+	return {
+		code: "MIGRATION_PATH_NOT_FOUND",
+		summary: `No on-disk migrations for contract space "${spaceId}"`,
+		why: `migration apply is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}". Run \`prisma-next migration plan\` first to materialise the path.`,
+		meta: {
+			spaceId,
+			target: targetHash,
+			kind: "neverPlanned"
+		}
+	};
+}
+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: `Cannot reach target "${targetHash}" from current marker "${fromHash}" in space "${spaceId}". The on-disk migration graph for this space does not connect the two states. Run \`prisma-next migration plan\` to materialise the path.`,
+		meta: {
+			spaceId,
+			fromHash,
+			targetHash,
+			kind: "pathUnreachable"
+		}
+	};
+}
+//#endregion
+//#region src/control-api/client.ts
+/**
+* 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,
+			extensionPacks: this.options.extensionPacks
+		});
+		this.familyInstance = this.options.family.create(this.stack);
+		const rawComponents = [
+			this.options.target,
+			this.options.adapter,
+			...this.options.extensionPacks ?? []
+		];
+		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 Error("Already connected. Call close() before reconnecting.");
+		const resolvedConnection = connection ?? this.defaultConnection;
+		if (resolvedConnection === void 0) throw new Error("No connection provided. Pass a connection to connect() or provide a default connection when creating the client.");
+		if (!this.stack?.driver) throw new Error("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;
+		}
+	}
+	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 Error("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.validateContract(options.contract);
+		} catch (error) {
+			throw new ContractValidationError(error instanceof Error ? error.message : String(error), 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.validateContract(options.contract);
+		} catch (error) {
+			throw new ContractValidationError(error instanceof Error ? error.message : String(error), error);
+		}
+		onProgress?.({
+			action: "schemaVerify",
+			kind: "spanStart",
+			spanId: "schemaVerify",
+			label: "Verifying database schema..."
+		});
+		try {
+			const result = await familyInstance.schemaVerify({
+				driver,
+				contract,
+				strict: options.strict ?? false,
+				contractPath: "",
+				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.validateContract(options.contract);
+		} catch (error) {
+			throw new ContractValidationError(error instanceof Error ? error.message : String(error), 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 Error(`Target "${this.options.target.targetId}" does not support migrations`);
+		let contract;
+		try {
+			contract = familyInstance.validateContract(options.contract);
+		} catch (error) {
+			throw new ContractValidationError(error instanceof Error ? error.message : String(error), error);
+		}
+		return executeDbInit({
+			driver,
+			familyInstance,
+			contract,
+			mode: options.mode,
+			migrations: this.options.target.migrations,
+			frameworkComponents,
+			migrationsDir: options.migrationsDir,
+			targetId: this.options.target.targetId,
+			extensionPacks: this.options.extensionPacks ?? [],
+			...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 Error(`Target "${this.options.target.targetId}" does not support migrations`);
+		let contract;
+		try {
+			contract = familyInstance.validateContract(options.contract);
+		} catch (error) {
+			throw new ContractValidationError(error instanceof Error ? error.message : String(error), error);
+		}
+		return executeDbUpdate({
+			driver,
+			familyInstance,
+			contract,
+			mode: options.mode,
+			migrations: this.options.target.migrations,
+			frameworkComponents,
+			migrationsDir: options.migrationsDir,
+			targetId: this.options.target.targetId,
+			extensionPacks: this.options.extensionPacks ?? [],
+			...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();
+		let contract;
+		try {
+			contract = familyInstance.validateContract(options.contract);
+		} catch (error) {
+			throw new ContractValidationError(error instanceof Error ? error.message : String(error), error);
+		}
+		return executeDbVerify({
+			driver,
+			familyInstance,
+			contract,
+			migrationsDir: options.migrationsDir,
+			targetId: this.options.target.targetId,
+			extensionPacks: this.options.extensionPacks ?? [],
+			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 });
+	}
+	async migrationApply(options) {
+		const { onProgress } = options;
+		await this.connectWithProgress(options.connection, "migrationApply", onProgress);
+		const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+		if (!hasMigrations(this.options.target)) throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+		let contract;
+		try {
+			contract = familyInstance.validateContract(options.contract);
+		} catch (error) {
+			throw new ContractValidationError(error instanceof Error ? error.message : String(error), error);
+		}
+		return executeMigrationApply({
+			driver,
+			familyInstance,
+			contract,
+			migrations: this.options.target.migrations,
+			frameworkComponents,
+			migrationsDir: options.migrationsDir,
+			extensionPacks: this.options.extensionPacks ?? [],
+			targetId: this.options.target.targetId,
+			appMigrationPackages: options.appMigrationPackages,
+			...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);
+	}
+	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 Error("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 = {
+				composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
+				scalarTypeDescriptors: stack.scalarTypeDescriptors,
+				authoringContributions: stack.authoringContributions,
+				codecLookup: stack.codecLookup,
+				controlMutationDefaults: stack.controlMutationDefaults,
+				resolvedInputs: contractConfig.source.inputs ?? []
+			};
+			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 ?? []);
+			try {
+				this.familyInstance.validateContract(enrichedIR);
+			} 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(enrichedIR, this.stack, this.options.family.emission);
+			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 { buildContractSpaceAggregate as a, executeDbInit as i, executeDbVerify as n, ContractValidationError as o, executeDbUpdate as r, createControlClient as t };
+
+//# sourceMappingURL=client-qVH-rEgd.mjs.map