prisma-next 0.5.0-dev.74 → 0.5.0-dev.76

package/dist/{client-0ZX24FXF.mjs → client-qVH-rEgd.mjs}

@@ -1,12 +1,15 @@
 import { p as errorRunnerFailed, t as CliStructuredError } from "./cli-errors-D3_sMh2K.mjs";
-import { t as assertFrameworkComponentsCompatible } from "./framework-components-gwAHl7ml.mjs";
-import { t as enrichContract } from "./contract-enrichment-CF6ogEJ_.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 { loadContractSpaceAggregate, planAggregate, verifyAggregate } from "@prisma-next/migration-tools/aggregate";
+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;
@@ -19,38 +22,6 @@ var ContractValidationError = class extends Error {
 //#endregion
 //#region src/utils/contract-space-aggregate-loader.ts
 /**
-* Convert the CLI's `Config.extensionPacks` array into the loader's
-* `DeclaredExtensionEntry[]` shape.
-*
-* The loader hashes `contractSpace.contractJson` to compare against the
-* on-disk `refs/head.json.hash` (drift detection). Rather than re-running
-* the canonical-JSON + SHA-256 pipeline at the CLI surface, we look up
-* the descriptor's pre-computed `headRef.hash` via reference identity
-* on the contract JSON value — the loader passes the same
-* `entry.contractSpace.contractJson` reference through to the hasher,
-* so identity-keyed lookup is safe.
-*/
-function toDeclaredExtensions(extensionPacks) {
-	const entries = [];
-	const hashByContractJson = /* @__PURE__ */ new Map();
-	for (const pack of extensionPacks) {
-		const entry = pack.contractSpace ? {
-			id: pack.id,
-			targetId: pack.targetId,
-			contractSpace: { contractJson: pack.contractSpace.contractJson }
-		} : {
-			id: pack.id,
-			targetId: pack.targetId
-		};
-		entries.push(entry);
-		if (pack.contractSpace) hashByContractJson.set(pack.contractSpace.contractJson, pack.contractSpace.headRef.hash);
-	}
-	return {
-		entries,
-		hashByContractJson
-	};
-}
-/**
 * 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
@@ -132,15 +103,18 @@ function mapLoadAggregateError(error) {
 * Run the aggregate loader at the CLI surface, mapping any
 * {@link LoadAggregateError} into a {@link CliStructuredError} envelope.
 *
-* App-side migration packages are intentionally not threaded through:
-* `db init` / `db update` go through the planner's `synth` strategy for
-* the app member (driven by `callerPolicy.ignoreGraphFor`), so the
-* app's authored `migrations/` graph is not walked.
+* 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(inputs.extensionPacks);
+	const { entries, hashByContractJson } = toDeclaredExtensions(toExtensionInputs(inputs.extensionPacks));
 	const result = await loadContractSpaceAggregate({
 		targetId: inputs.targetId,
 		migrationsDir: inputs.migrationsDir,
@@ -152,12 +126,157 @@ async function buildContractSpaceAggregate(inputs) {
 			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: []
+		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).
@@ -175,12 +294,13 @@ function stripOperations(operations) {
 /**
 * 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.
+* 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",
-	apply: "apply"
+	plan: "plan"
 };
 /**
 * Loader → planner → runner pipeline shared by `db init` and `db update`.
@@ -268,71 +388,41 @@ async function executeAggregateApply(options) {
 	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 runner = migrations.createRunner(familyInstance);
-	if (!hasMultiSpaceRunner(runner)) throw errorRunnerFailed(`Runner for target "${aggregate.targetId}" does not implement \`executeAcrossSpaces\``, { why: `${action === "dbInit" ? "db init" : "db update"} requires multi-space-capable runners (today: every SQL family runner).` });
-	onProgress?.({
-		action,
-		kind: "spanStart",
-		spanId: SPAN_IDS$1.apply,
-		label: "Applying migration plan across spaces"
-	});
-	const perSpaceOptions = orderedResolutions.map((r) => ({
-		space: r.spaceId,
-		plan: r.entry.plan,
+	const applied = await applyAggregate({
+		aggregate,
+		perSpacePlans: planResult.value.perSpace,
+		applyOrder: planResult.value.applyOrder,
 		driver,
-		destinationContract: r.entry.destinationContract,
-		policy,
-		executionChecks: {
-			prechecks: false,
-			postchecks: false,
-			idempotencyChecks: false
-		},
+		familyInstance,
+		migrations,
 		frameworkComponents,
-		strictVerification: false
-	}));
-	const runnerResult = await runner.executeAcrossSpaces({
-		driver,
-		perSpaceOptions
-	});
-	if (!runnerResult.ok) {
-		onProgress?.({
-			action,
-			kind: "spanEnd",
-			spanId: SPAN_IDS$1.apply,
-			outcome: "error"
-		});
-		return buildRunnerFailure({
-			summary: runnerResult.failure.summary,
-			...ifDefined("why", runnerResult.failure.why),
-			meta: {
-				...runnerResult.failure.meta ?? {},
-				failingSpace: runnerResult.failure.failingSpace
-			}
-		});
-	}
-	onProgress?.({
+		policy,
 		action,
-		kind: "spanEnd",
-		spanId: SPAN_IDS$1.apply,
-		outcome: "ok"
+		...ifDefined("onProgress", onProgress)
+	});
+	if (!applied.ok) return buildRunnerFailure({
+		summary: applied.failure.summary,
+		...ifDefined("why", applied.failure.why),
+		meta: applied.failure.meta
 	});
-	const totalOpsPlanned = runnerResult.value.perSpaceResults.reduce((sum, r) => sum + r.value.operationsPlanned, 0);
-	const totalOpsExecuted = runnerResult.value.perSpaceResults.reduce((sum, r) => sum + r.value.operationsExecuted, 0);
-	const aggregateOps = orderedResolutions.flatMap((r) => r.entry.displayOps);
-	const summary = action === "dbInit" ? `Applied ${totalOpsExecuted} operation(s) across ${orderedResolutions.length} space(s), database signed` : totalOpsExecuted === 0 ? `Database already matches contract across ${orderedResolutions.length} space(s), signature updated` : `Applied ${totalOpsExecuted} operation(s) across ${orderedResolutions.length} space(s), signature updated`;
+	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: totalOpsPlanned,
-		operationsExecuted: totalOpsExecuted,
+		operationsPlanned: applied.value.totalOpsPlanned,
+		operationsExecuted: applied.value.totalOpsExecuted,
+		perSpace: applied.value.perSpace,
 		summary
 	});
 }
@@ -367,16 +457,6 @@ function detectOrphanMarkers(aggregate, markerRows) {
 		})) }
 	});
 }
-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
-		};
-	});
-}
 function mapPlannerError(error) {
 	if (error.kind === "appSynthFailure") return notOk({
 		code: "PLANNING_FAILED",
@@ -418,6 +498,7 @@ function wrapPlanResult(args) {
 			storageHash: args.destination.storageHash,
 			...ifDefined("profileHash", args.destination.profileHash)
 		},
+		perSpace: args.perSpace,
 		summary: args.summary
 	});
 }
@@ -437,6 +518,7 @@ function wrapApplyResult(args) {
 			storageHash: args.destination.storageHash,
 			profileHash: args.destination.profileHash
 		} : { storageHash: args.destination.storageHash },
+		perSpace: args.perSpace,
 		summary: args.summary
 	});
 }
@@ -764,150 +846,255 @@ function mapMarkerCheckFailures(appSpaceId, section) {
 //#endregion
 //#region src/control-api/operations/migration-apply.ts
 /**
-* Apply a sequence of migration packages against the configured driver.
+* 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:
 *
-* Validates the path's continuity (origin → ... → destination, no gaps),
-* then drives the family/target's migration runner over each package's
-* operations in order, surfacing per-migration progress through `onProgress`.
+* 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.
 *
-* The `pendingMigrations` parameter is trusted input. Callers are responsible
-* for upstream verification of the originating migration packages — typically
-* by loading them via `readMigrationPackage` from
-* `@prisma-next/migration-tools/io`, which performs hash-integrity checks at
-* the load boundary. This operation does not re-verify the packages and
-* assumes the `(metadata, ops)` pairs on disk have not been tampered with
-* since emit.
+* Sub-spec § `migration apply` semantics + § Required changes 1.
 */
 async function executeMigrationApply(options) {
-	const { driver, familyInstance, originHash, destinationHash, pendingMigrations, migrations, frameworkComponents, targetId, onProgress } = options;
-	if (pendingMigrations.length === 0) {
-		if (originHash !== destinationHash) return notOk({
-			code: "MIGRATION_PATH_NOT_FOUND",
-			summary: "No migrations provided for requested origin and destination",
-			why: `Requested ${originHash} -> ${destinationHash} but pendingMigrations is empty`,
-			meta: {
-				originHash,
-				destinationHash
+	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 ok({
-			migrationsApplied: 0,
-			markerHash: originHash,
-			applied: [],
-			summary: "Already up to date"
-		});
-	}
-	const firstMigration = pendingMigrations[0];
-	const lastMigration = pendingMigrations[pendingMigrations.length - 1];
-	const firstFromMarker = firstMigration.from ?? EMPTY_CONTRACT_HASH;
-	if (firstFromMarker !== originHash || lastMigration.to !== destinationHash) return notOk({
-		code: "MIGRATION_PATH_NOT_FOUND",
-		summary: "Migration apply path does not match requested origin and destination",
-		why: `Path resolved as ${firstFromMarker} -> ${lastMigration.to}, but requested ${originHash} -> ${destinationHash}`,
-		meta: {
-			originHash,
-			destinationHash,
-			pathOrigin: firstFromMarker,
-			pathDestination: lastMigration.to
+			return notOk(buildNeverPlannedFailure(member.spaceId, targetHash));
 		}
-	});
-	for (let i = 1; i < pendingMigrations.length; i++) {
-		const previous = pendingMigrations[i - 1];
-		const current = pendingMigrations[i];
-		const currentFromMarker = current.from ?? EMPTY_CONTRACT_HASH;
-		if (previous.to !== currentFromMarker) return notOk({
-			code: "MIGRATION_PATH_NOT_FOUND",
-			summary: "Migration apply path contains a discontinuity between adjacent migrations",
-			why: `Migration "${previous.dirName}" ends at ${previous.to}, but next migration "${current.dirName}" starts at ${currentFromMarker}`,
-			meta: {
-				originHash,
-				destinationHash,
-				previousDirName: previous.dirName,
-				previousTo: previous.to,
-				currentDirName: current.dirName,
-				currentFrom: currentFromMarker,
-				discontinuityIndex: i
+		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 runner = migrations.createRunner(familyInstance);
-	const applied = [];
-	for (const migration of pendingMigrations) {
-		const migrationSpanId = `migration:${migration.dirName}`;
-		onProgress?.({
-			action: "migrationApply",
-			kind: "spanStart",
-			spanId: migrationSpanId,
-			label: `Applying ${migration.dirName}`
+	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 { operations } = migration;
-		const policy = { allowedOperationClasses: [
+		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"
-		] };
-		const plan = {
-			targetId,
-			spaceId: APP_SPACE_ID,
-			origin: migration.from === null ? null : { storageHash: migration.from },
-			destination: { storageHash: migration.to },
-			operations,
-			providedInvariants: migration.providedInvariants
-		};
-		const destinationContract = familyInstance.validateContract(migration.toContract);
-		const runnerResult = await runner.execute({
-			plan,
-			driver,
-			destinationContract,
-			policy,
-			executionChecks: {
-				prechecks: true,
-				postchecks: true,
-				idempotencyChecks: true
-			},
-			frameworkComponents
-		});
-		if (!runnerResult.ok) {
-			onProgress?.({
-				action: "migrationApply",
-				kind: "spanEnd",
-				spanId: migrationSpanId,
-				outcome: "error"
-			});
-			return notOk({
-				code: "RUNNER_FAILED",
-				summary: runnerResult.failure.summary,
-				why: runnerResult.failure.why,
-				meta: {
-					migration: migration.dirName,
-					from: migration.from,
-					to: migration.to,
-					...runnerResult.failure.meta ?? {}
-				}
-			});
+		] },
+		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;
 		}
-		onProgress?.({
-			action: "migrationApply",
-			kind: "spanEnd",
-			spanId: migrationSpanId,
-			outcome: "ok"
-		});
-		applied.push({
-			dirName: migration.dirName,
-			from: migration.from,
-			to: migration.to,
-			operationsExecuted: runnerResult.value.operationsExecuted
-		});
+		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;
 	}
-	const finalHash = pendingMigrations[pendingMigrations.length - 1].to;
-	const totalOps = applied.reduce((sum, a) => sum + a.operationsExecuted, 0);
-	return ok({
+	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: finalHash,
+		markerHash: appMarkerHash,
 		applied,
-		summary: `Applied ${applied.length} migration(s) (${totalOps} operation(s)), marker at ${finalHash}`
-	});
+		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
@@ -1218,16 +1405,26 @@ var ControlClientImpl = class {
 		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,
-			originHash: options.originHash,
-			destinationHash: options.destinationHash,
-			pendingMigrations: options.pendingMigrations,
+			contract,
 			migrations: this.options.target.migrations,
 			frameworkComponents,
+			migrationsDir: options.migrationsDir,
+			extensionPacks: this.options.extensionPacks ?? [],
 			targetId: this.options.target.targetId,
-			...onProgress ? { onProgress } : {}
+			appMigrationPackages: options.appMigrationPackages,
+			...ifDefined("refHash", options.refHash),
+			...ifDefined("refInvariants", options.refInvariants),
+			...ifDefined("refName", options.refName),
+			...ifDefined("onProgress", onProgress)
 		});
 	}
 	async introspect(options) {
@@ -1393,6 +1590,6 @@ var ControlClientImpl = class {
 	}
 };
 //#endregion
-export { ContractValidationError as a, executeDbInit as i, executeDbVerify as n, executeDbUpdate as r, createControlClient as t };
+export { buildContractSpaceAggregate as a, executeDbInit as i, executeDbVerify as n, ContractValidationError as o, executeDbUpdate as r, createControlClient as t };
 
-//# sourceMappingURL=client-0ZX24FXF.mjs.map
+//# sourceMappingURL=client-qVH-rEgd.mjs.map