@prisma-next/migration-tools 0.11.0 → 0.12.0

package/dist/exports/aggregate.mjs

@@ -1,248 +1,483 @@
-import { t as MigrationToolsError } from "../errors-DGYwcwXs.mjs";
-import { s as readMigrationsDir } from "../io-BPLfzvZe.mjs";
-import "../constants-DWV9_o2Z.mjs";
-import { l as reconstructGraph, o as findPathWithDecision } from "../migration-graph-nlS4TRpn.mjs";
-import { a as APP_SPACE_ID, c as spaceMigrationDirectory, i as readContractSpaceHeadRef, n as listContractSpaceDirectories, t as readContractSpaceContract } from "../read-contract-space-contract-DRueB4Aa.mjs";
+import { E as errorSnapshotMissing, f as errorInvalidJson, i as errorContractDeserializationFailed, l as errorHashNotInGraph, r as errorBundleNotFoundForGraphNode, t as MigrationToolsError, x as errorMissingFile } from "../errors-vFROOhCR.mjs";
+import { s as readMigrationsDir } from "../io-BGlPOt9b.mjs";
+import { t as EMPTY_CONTRACT_HASH } from "../constants-DWV9_o2Z.mjs";
+import { n as isGraphNode } from "../graph-membership-BV23F1IV.mjs";
+import { l as reconstructGraph, o as findPathWithDecision } from "../migration-graph-BMAqSfv9.mjs";
+import { a as readRefsTolerant, t as HEAD_REF_NAME } from "../refs-C-_WUrPw.mjs";
+import { r as readRefSnapshot } from "../snapshot-Bazwo13S.mjs";
+import { a as APP_SPACE_ID, d as spaceRefsDirectory, i as readContractSpaceHeadRef, l as isValidSpaceId, n as listContractSpaceDirectories, o as RESERVED_SPACE_SUBDIR_NAMES, t as readContractSpaceContract, u as spaceMigrationDirectory } from "../read-contract-space-contract-TbeXuJXL.mjs";
+import { join } from "pathe";
+import { readFile } from "node:fs/promises";
 import { notOk, ok } from "@prisma-next/utils/result";
-//#region src/aggregate/extract-storage-element-names.ts
+import { elementCoordinates } from "@prisma-next/framework-components/ir";
+//#region src/aggregate/aggregate.ts
+function hasErrnoCode(error, code) {
+	return error instanceof Error && error.code === code;
+}
+function contractAtMemoKey(hash, refName) {
+	return `${hash}\0${refName ?? ""}`;
+}
+function deserializeContractAtPath(filePath, contractJson, deserializeContract) {
+	try {
+		return deserializeContract(contractJson);
+	} catch (error) {
+		if (MigrationToolsError.is(error)) throw error;
+		throw errorContractDeserializationFailed(filePath, error instanceof Error ? error.message : String(error));
+	}
+}
+async function readGraphNodeEndContract(packageDir, deserializeContract) {
+	const jsonPath = join(packageDir, "end-contract.json");
+	const dtsPath = join(packageDir, "end-contract.d.ts");
+	let rawJson;
+	try {
+		rawJson = await readFile(jsonPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile("end-contract.json", packageDir);
+		throw error;
+	}
+	let contractJson;
+	try {
+		contractJson = JSON.parse(rawJson);
+	} catch (error) {
+		throw errorInvalidJson(jsonPath, error instanceof Error ? error.message : String(error));
+	}
+	let contractDts;
+	try {
+		contractDts = await readFile(dtsPath, "utf-8");
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile("end-contract.d.ts", packageDir);
+		throw error;
+	}
+	const contract = deserializeContractAtPath(jsonPath, contractJson, deserializeContract);
+	return {
+		contractJson,
+		contractDts,
+		contract
+	};
+}
+async function resolveContractAt(args) {
+	const { hash, opts, refsDir, packages, graph, deserializeContract } = args;
+	const refName = opts?.refName;
+	if (refName !== void 0) {
+		const snapshot = await readRefSnapshot(refsDir, refName);
+		if (snapshot) {
+			const jsonPath = join(refsDir, `${refName}.contract.json`);
+			return {
+				hash,
+				contractJson: snapshot.contract,
+				contractDts: snapshot.contractDts,
+				contract: deserializeContractAtPath(jsonPath, snapshot.contract, deserializeContract),
+				provenance: "snapshot"
+			};
+		}
+		if (isGraphNode(hash, graph)) return resolveGraphNodeContractAt({
+			hash,
+			packages,
+			deserializeContract,
+			explicitLabel: refName
+		});
+		throw errorSnapshotMissing(refName);
+	}
+	if (isGraphNode(hash, graph)) return resolveGraphNodeContractAt({
+		hash,
+		packages,
+		deserializeContract
+	});
+	throw errorHashNotInGraph(hash, graph);
+}
+async function resolveGraphNodeContractAt(args) {
+	const { hash, packages, deserializeContract, explicitLabel } = args;
+	const matchingBundle = packages.find((pkg) => pkg.metadata.to === hash);
+	if (!matchingBundle) throw errorBundleNotFoundForGraphNode(hash, explicitLabel);
+	const { contractJson, contractDts, contract } = await readGraphNodeEndContract(matchingBundle.dirPath, deserializeContract);
+	return {
+		hash,
+		contractJson,
+		contractDts,
+		contract,
+		provenance: "graph-node",
+		sourceDir: matchingBundle.dirPath
+	};
+}
 /**
-* Extract the set of top-level storage element names a contract claims.
-*
-* Used by the aggregate loader's disjointness check and by
-* `projectSchemaToSpace`'s "names owned by other members" walk.
-*
-* **Stopgap — known layering violation.** This helper duck-types the
-* storage shape from framework-domain code that has no business naming
-* family-specific storage idioms. The framework lacks a typed primitive
-* for storage *topology* — the structural backbone of "what named things
-* does this contract claim?" independent of what those things are.
-*
-* Behavioural notes for the lifetime of this helper:
+* Resolve a member's head ref, asserting it is present. The apply/verify
+* engine only runs after `checkIntegrity` has refused on `headRefMissing`,
+* so a member reaching the planner / verifier without a head ref is a
+* programming error (the integrity gate was skipped), not a user-facing
+* state. The app member's head ref is always synthesised, so this only
+* ever guards an ungated extension space.
+*/
+function requireHeadRef(member) {
+	if (member.headRef === null) throw new Error(`Contract space "${member.spaceId}" has no head ref; the integrity gate must refuse a missing head ref before planning or verifying.`);
+	return member.headRef;
+}
+/**
+* Build a {@link ContractSpaceMember} with lazily-memoised `graph()`,
+* `contract()`, and `contractAt()` facets.
 *
-* - SQL contracts contribute table names from every
-*   `storage.namespaces[namespaceId].tables` map.
-* - Mongo contracts contribute names from each namespace's `tables`
-*   (or `collections`, depending on the per-target Namespace's slot
-*   choice). Per-namespace `collections` may appear as a record or as
-*   an array of `{ name }` entries; both are accepted defensively.
-* - Root-level `tables` / `collections` records (when present) are
-*   also unioned. These root-level walks are belt-and-suspenders for a
-*   defensive helper operating on `unknown`; no in-tree contract emits
-*   the root shape post-namespace flip.
-* - Unrecognised shapes contribute nothing beyond the walks above.
-* - Record-shape detection excludes arrays so array-shaped values aren't
-*   walked as records via numeric keys.
-* - Names that appear in multiple places are deduplicated by the returned
-*   `Set`.
+* `graph()` reconstructs the migration graph from `packages` on first
+* call and caches it. `contract()` calls `resolveContract` on first call
+* and caches the result; a throwing `resolveContract` (e.g. a missing or
+* undeserializable on-disk contract) re-throws on each call rather than
+* caching a value — `checkIntegrity` surfaces that as `contractUnreadable`.
+* `contractAt()` materializes the contract at an arbitrary graph node with
+* the same resolution order as plan-time ref resolution: ref snapshot first
+* (when `opts.refName` is set), else the matching package's `end-contract.*`.
 */
-function extractStorageElementNames(contract) {
-	const names = /* @__PURE__ */ new Set();
-	if (typeof contract !== "object" || contract === null) return names;
-	const storage = contract.storage;
-	if (typeof storage !== "object" || storage === null) return names;
-	const storageObj = storage;
-	if (typeof storageObj.namespaces === "object" && storageObj.namespaces !== null && !Array.isArray(storageObj.namespaces)) for (const ns of Object.values(storageObj.namespaces)) {
-		if (typeof ns !== "object" || ns === null) continue;
-		const nsObj = ns;
-		addRecordKeys(nsObj.tables, names);
-		if (Array.isArray(nsObj.collections)) {
-			for (const entry of nsObj.collections) if (typeof entry === "object" && entry !== null) {
-				const name = entry.name;
-				if (typeof name === "string") names.add(name);
-			}
-		} else addRecordKeys(nsObj.collections, names);
+function createContractSpaceMember(args) {
+	const { spaceId, packages, refs, headRef, refsDir, resolveContract, deserializeContract } = args;
+	let graphMemo;
+	let contractMemo;
+	const contractAtMemo = /* @__PURE__ */ new Map();
+	function memberGraph() {
+		graphMemo ??= reconstructGraph(packages);
+		return graphMemo;
 	}
-	addRecordKeys(storageObj.tables, names);
-	addRecordKeys(storageObj.collections, names);
-	return names;
+	return {
+		spaceId,
+		packages,
+		refs,
+		headRef,
+		graph: memberGraph,
+		contract() {
+			contractMemo ??= resolveContract();
+			return contractMemo;
+		},
+		async contractAt(hash, opts) {
+			const key = contractAtMemoKey(hash, opts?.refName);
+			const cached = contractAtMemo.get(key);
+			if (cached) return cached;
+			const result = await resolveContractAt({
+				hash,
+				opts,
+				refsDir,
+				packages,
+				graph: memberGraph(),
+				deserializeContract
+			});
+			contractAtMemo.set(key, result);
+			return result;
+		}
+	};
 }
-function addRecordKeys(value, names) {
-	if (typeof value === "object" && value !== null && !Array.isArray(value)) for (const name of Object.keys(value)) names.add(name);
+/**
+* Assemble a {@link ContractSpaceAggregate} value from its members and a
+* `checkIntegrity` implementation. The query methods (`listSpaces` /
+* `hasSpace` / `space` / `spaces`) are derived here so every aggregate —
+* loader-built or test-built — shares one query surface: `app` first,
+* then `extensions` in the order supplied (the loader sorts them
+* lex-ascending by `spaceId`).
+*/
+function createContractSpaceAggregate(args) {
+	const { targetId, app, extensions, checkIntegrity } = args;
+	const ordered = [app, ...extensions];
+	const byId = new Map(ordered.map((m) => [m.spaceId, m]));
+	return {
+		targetId,
+		app,
+		extensions,
+		listSpaces: () => ordered.map((m) => m.spaceId),
+		hasSpace: (id) => byId.has(id),
+		space: (id) => byId.get(id),
+		spaces: () => ordered,
+		checkIntegrity
+	};
 }
 //#endregion
-//#region src/aggregate/loader.ts
-function integrityDetail(error) {
-	if (MigrationToolsError.is(error)) return error.why;
-	if (error instanceof Error) return error.message;
-	return String(error);
-}
+//#region src/aggregate/check-integrity.ts
 /**
-* Hydrate a {@link ContractSpaceAggregate} from on-disk state and
-* the app contract value the caller supplies.
-*
-* The loader is the **only** descriptor-import boundary at apply /
-* verify time, but it intentionally does **not** read the extension
-* descriptor's `contractJson` value. Each extension space's contract
-* is read from its on-disk `migrations/<id>/contract.json` mirror; the
-* descriptor's role is exhausted by the seed phase that wrote that
-* mirror in the first place. The loader composes existing
-* migration-tools primitives — layout precheck (via
-* {@link listContractSpaceDirectories}), integrity checks (via
-* {@link readMigrationsDir} / {@link readContractSpaceHeadRef} /
-* {@link readContractSpaceContract} / `deserializeContract`), and
-* disjointness — into a single typed value.
-*
-* Failure semantics: every failure variant in {@link LoadAggregateError}
-* short-circuits the load.
+* Walk the loaded model and return **every** integrity violation — never
+* bailing at the first. Structurally-derivable violations (load-time
+* problems, self-edges, missing / unreachable head refs) are always
+* produced; layout-drift checks require `declaredExtensions`, and
+* contract / target / disjointness checks require `checkContracts`.
 */
-async function loadContractSpaceAggregate(input) {
-	const appContractTarget = input.appContract.target;
-	if (appContractTarget !== input.targetId) return notOk({
-		kind: "targetMismatch",
-		spaceId: APP_SPACE_ID,
-		expected: input.targetId,
-		actual: appContractTarget
-	});
-	for (const entry of input.declaredExtensions) if (entry.targetId !== input.targetId) return notOk({
-		kind: "targetMismatch",
-		spaceId: entry.id,
-		expected: input.targetId,
-		actual: entry.targetId
+function computeIntegrityViolations(input, opts) {
+	const violations = [];
+	for (const { member, problems, refProblems, headRefProblem, isApp } of input.spaces) {
+		const { spaceId } = member;
+		for (const problem of problems) violations.push(loadProblemToViolation(spaceId, problem));
+		for (const refProblem of refProblems) violations.push({
+			kind: "refUnreadable",
+			spaceId,
+			refName: refProblem.refName,
+			detail: refProblem.detail
+		});
+		if (headRefProblem !== null) violations.push({
+			kind: "refUnreadable",
+			spaceId,
+			refName: headRefProblem.refName,
+			detail: headRefProblem.detail
+		});
+		for (const pkg of member.packages) {
+			const from = pkg.metadata.from ?? "sha256:empty";
+			const isSelfEdge = from === pkg.metadata.to;
+			const hasDataOp = pkg.ops.some((op) => op.operationClass === "data");
+			if (isSelfEdge && !hasDataOp) violations.push({
+				kind: "sameSourceAndTarget",
+				spaceId,
+				dirName: pkg.dirName,
+				hash: from
+			});
+		}
+		violations.push(...duplicateMigrationHashViolations(spaceId, member.packages));
+		if (!isApp && headRefProblem === null) {
+			if (member.headRef === null) violations.push({
+				kind: "headRefMissing",
+				spaceId
+			});
+			else if (!headRefPresentInGraph(member, member.headRef.hash)) violations.push({
+				kind: "headRefNotInGraph",
+				spaceId,
+				hash: member.headRef.hash
+			});
+		}
+	}
+	if (opts?.declaredExtensions !== void 0) violations.push(...layoutViolations(input.spaces, opts.declaredExtensions));
+	if (opts?.checkContracts === true) violations.push(...contractViolations(input));
+	return violations;
+}
+function loadProblemToViolation(spaceId, problem) {
+	switch (problem.kind) {
+		case "hashMismatch": return {
+			kind: "hashMismatch",
+			spaceId,
+			dirName: problem.dirName,
+			stored: problem.stored,
+			computed: problem.computed
+		};
+		case "providedInvariantsMismatch": return {
+			kind: "providedInvariantsMismatch",
+			spaceId,
+			dirName: problem.dirName
+		};
+		case "packageUnloadable": return {
+			kind: "packageUnloadable",
+			spaceId,
+			dirName: problem.dirName,
+			detail: problem.detail
+		};
+	}
+}
+function duplicateMigrationHashViolations(spaceId, packages) {
+	const dirNamesByHash = /* @__PURE__ */ new Map();
+	for (const pkg of packages) {
+		const hash = pkg.metadata.migrationHash;
+		const dirNames = dirNamesByHash.get(hash);
+		if (dirNames) dirNames.push(pkg.dirName);
+		else dirNamesByHash.set(hash, [pkg.dirName]);
+	}
+	const out = [];
+	for (const [migrationHash, dirNames] of dirNamesByHash) if (dirNames.length > 1) out.push({
+		kind: "duplicateMigrationHash",
+		spaceId,
+		migrationHash,
+		dirNames: [...dirNames].sort()
 	});
-	const declaredSpaceIds = new Set(input.declaredExtensions.map((e) => e.id));
-	const extensionDirsOnDisk = (await listContractSpaceDirectories(input.migrationsDir)).filter((d) => d !== APP_SPACE_ID);
-	const spaceDirSet = new Set(extensionDirsOnDisk);
-	const layoutViolations = [];
-	for (const dir of extensionDirsOnDisk) if (!declaredSpaceIds.has(dir)) layoutViolations.push({
+	return out;
+}
+/**
+* Whether a space's head-ref hash is present in its reconstructed graph.
+* An empty graph is reachable only by the empty-contract sentinel.
+*/
+function headRefPresentInGraph(member, headHash) {
+	const graph = member.graph();
+	if (graph.nodes.size === 0) return headHash === EMPTY_CONTRACT_HASH;
+	return graph.nodes.has(headHash);
+}
+function layoutViolations(spaces, declaredExtensions) {
+	const out = [];
+	const extensionSpaceIds = new Set(spaces.filter((s) => !s.isApp).map((s) => s.member.spaceId));
+	const declaredIds = new Set(declaredExtensions.map((d) => d.id));
+	for (const id of [...extensionSpaceIds].sort()) if (!declaredIds.has(id)) out.push({
 		kind: "orphanSpaceDir",
-		spaceId: dir
+		spaceId: id
 	});
-	for (const id of [...declaredSpaceIds].sort()) if (!spaceDirSet.has(id)) layoutViolations.push({
+	for (const id of [...declaredIds].sort()) if (!extensionSpaceIds.has(id)) out.push({
 		kind: "declaredButUnmigrated",
 		spaceId: id
 	});
-	if (layoutViolations.length > 0) return notOk({
-		kind: "layoutViolation",
-		violations: layoutViolations
-	});
-	const loadedExtensions = [];
-	for (const entry of [...input.declaredExtensions].sort((a, b) => a.id.localeCompare(b.id))) {
-		const headRef = await readContractSpaceHeadRef(input.migrationsDir, entry.id);
-		if (headRef === null) return notOk({
-			kind: "integrityFailure",
-			spaceId: entry.id,
-			detail: `Head ref \`refs/head.json\` is missing for extension space "${entry.id}".`
-		});
-		let spaceContractRaw;
-		try {
-			spaceContractRaw = await readContractSpaceContract(input.migrationsDir, entry.id);
-		} catch (error) {
-			return notOk({
-				kind: "integrityFailure",
-				spaceId: entry.id,
-				detail: integrityDetail(error)
-			});
-		}
-		let spaceContract;
+	return out;
+}
+function contractViolations(input) {
+	const out = [];
+	const elementClaimedBy = /* @__PURE__ */ new Map();
+	for (const { member } of input.spaces) {
+		let contract;
 		try {
-			spaceContract = input.deserializeContract(spaceContractRaw);
+			contract = member.contract();
 		} catch (error) {
-			return notOk({
-				kind: "validationFailure",
-				spaceId: entry.id,
-				detail: integrityDetail(error)
+			out.push({
+				kind: "contractUnreadable",
+				spaceId: member.spaceId,
+				detail: detailOf$1(error)
 			});
+			continue;
 		}
-		if (spaceContract.target !== input.targetId) return notOk({
+		if (contract.target !== input.targetId) out.push({
 			kind: "targetMismatch",
-			spaceId: entry.id,
+			spaceId: member.spaceId,
 			expected: input.targetId,
-			actual: spaceContract.target
-		});
-		let packages;
-		try {
-			packages = await readMigrationsDir(spaceMigrationDirectory(input.migrationsDir, entry.id));
-		} catch (error) {
-			return notOk({
-				kind: "integrityFailure",
-				spaceId: entry.id,
-				detail: integrityDetail(error)
-			});
-		}
-		let graph;
-		try {
-			graph = reconstructGraph(packages);
-		} catch (error) {
-			return notOk({
-				kind: "integrityFailure",
-				spaceId: entry.id,
-				detail: integrityDetail(error)
-			});
-		}
-		if (graph.nodes.size === 0) {
-			if (headRef.hash !== "sha256:empty") return notOk({
-				kind: "integrityFailure",
-				spaceId: entry.id,
-				detail: `Head ref "${headRef.hash}" is not present in the (empty) on-disk migration graph.`
-			});
-		} else if (!graph.nodes.has(headRef.hash)) return notOk({
-			kind: "integrityFailure",
-			spaceId: entry.id,
-			detail: `Head ref "${headRef.hash}" is not present in the on-disk migration graph.`
-		});
-		const packagesByMigrationHash = new Map(packages.map((p) => [p.metadata.migrationHash, p]));
-		loadedExtensions.push({
-			entry,
-			contract: spaceContract,
-			headRefHash: headRef.hash,
-			headRefInvariants: [...headRef.invariants].sort(),
-			migrations: {
-				graph,
-				packagesByMigrationHash
-			}
-		});
-	}
-	let appGraph;
-	try {
-		appGraph = reconstructGraph(input.appMigrationPackages);
-	} catch (error) {
-		return notOk({
-			kind: "integrityFailure",
-			spaceId: APP_SPACE_ID,
-			detail: error instanceof Error ? error.message : String(error)
+			actual: contract.target
 		});
-	}
-	const appPackagesByMigrationHash = new Map(input.appMigrationPackages.map((p) => [p.metadata.migrationHash, p]));
-	const appMember = {
-		spaceId: APP_SPACE_ID,
-		contract: input.appContract,
-		headRef: {
-			hash: input.appContract.storage.storageHash,
-			invariants: []
-		},
-		migrations: {
-			graph: appGraph,
-			packagesByMigrationHash: appPackagesByMigrationHash
-		}
-	};
-	const extensionMembers = loadedExtensions.map((s) => ({
-		spaceId: s.entry.id,
-		contract: s.contract,
-		headRef: {
-			hash: s.headRefHash,
-			invariants: s.headRefInvariants
-		},
-		migrations: s.migrations
-	}));
-	const elementClaimedBy = /* @__PURE__ */ new Map();
-	for (const member of [appMember, ...extensionMembers]) {
-		const elements = extractStorageElementNames(member.contract);
-		for (const elementName of elements) {
+		for (const { entityName: elementName } of elementCoordinates(contract.storage)) {
 			const claimers = elementClaimedBy.get(elementName);
 			if (claimers) claimers.push(member.spaceId);
 			else elementClaimedBy.set(elementName, [member.spaceId]);
 		}
 	}
-	for (const [element, claimedBy] of elementClaimedBy) if (claimedBy.length > 1) return notOk({
-		kind: "disjointnessViolation",
+	const disjointness = [];
+	for (const [element, claimedBy] of elementClaimedBy) if (claimedBy.length > 1) disjointness.push({
+		kind: "disjointness",
 		element,
 		claimedBy: [...claimedBy].sort()
 	});
-	return ok({ aggregate: {
-		targetId: input.targetId,
-		app: appMember,
-		extensions: extensionMembers
-	} });
+	disjointness.sort((a, b) => a.kind === "disjointness" && b.kind === "disjointness" ? a.element.localeCompare(b.element) : 0);
+	out.push(...disjointness);
+	return out;
+}
+function detailOf$1(error) {
+	if (MigrationToolsError.is(error)) return error.why;
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+//#endregion
+//#region src/aggregate/loader.ts
+/**
+* Build a tolerant, queryable {@link ContractSpaceAggregate} from on-disk
+* migration state plus the caller's live app contract.
+*
+* Building **never throws on disk content**: a hash- or
+* invariants-mismatched package is retained, an unparseable package is
+* omitted, a missing extension head ref leaves `headRef: null`, and an
+* unreadable on-disk contract defers its failure to `member.contract()`.
+* Every such problem is judged by {@link ContractSpaceAggregate.checkIntegrity}
+* rather than aborting the load. The only rejections are catastrophic I/O
+* (a `migrations/` that exists but is unreadable for reasons other than
+* absence).
+*
+* The app space's head ref is synthesised from the live contract's
+* storage hash (the app contract is authored independently of the
+* migration graph), and `app.contract()` returns the supplied contract.
+* Extension spaces read their contract, refs, and head ref from disk.
+*/
+async function loadContractSpaceAggregate(input) {
+	const { migrationsDir, deserializeContract, appContract } = input;
+	const targetId = appContract.target;
+	const appState = await loadAppSpace(migrationsDir, appContract, deserializeContract);
+	const extensionStates = await loadExtensionSpaces(migrationsDir, deserializeContract);
+	const spaces = [appState, ...extensionStates];
+	return createContractSpaceAggregate({
+		targetId,
+		app: appState.member,
+		extensions: extensionStates.map((state) => state.member),
+		checkIntegrity: (opts) => computeIntegrityViolations({
+			targetId,
+			spaces
+		}, opts)
+	});
+}
+async function loadAppSpace(migrationsDir, appContract, deserializeContract) {
+	const spaceDir = spaceMigrationDirectory(migrationsDir, APP_SPACE_ID);
+	const { packages, problems } = await readMigrationsDir(spaceDir);
+	const { refs, problems: refProblems } = await readRefsTolerant(spaceRefsDirectory(spaceDir));
+	return {
+		member: createContractSpaceMember({
+			spaceId: APP_SPACE_ID,
+			packages,
+			refs,
+			headRef: {
+				hash: appContract.storage.storageHash,
+				invariants: []
+			},
+			refsDir: spaceRefsDirectory(spaceDir),
+			resolveContract: () => appContract,
+			deserializeContract
+		}),
+		problems,
+		refProblems,
+		headRefProblem: null,
+		isApp: true
+	};
+}
+async function loadExtensionSpaces(migrationsDir, deserializeContract) {
+	const extensionIds = (await listContractSpaceDirectories(migrationsDir)).filter((name) => name !== APP_SPACE_ID).filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name)).filter(isValidSpaceId).sort();
+	const states = [];
+	for (const spaceId of extensionIds) states.push(await loadExtensionSpace(migrationsDir, spaceId, deserializeContract));
+	return states;
+}
+async function loadExtensionSpace(migrationsDir, spaceId, deserializeContract) {
+	const spaceDir = spaceMigrationDirectory(migrationsDir, spaceId);
+	const { packages, problems } = await readMigrationsDir(spaceDir);
+	const { refs, problems: refProblems } = await readRefsTolerant(spaceRefsDirectory(spaceDir));
+	const { headRef, problem: headRefProblem } = await readHeadRefTolerant(migrationsDir, spaceId);
+	const rawContract = await readRawContractDeferred(migrationsDir, spaceId);
+	return {
+		member: createContractSpaceMember({
+			spaceId,
+			packages,
+			refs,
+			headRef,
+			refsDir: spaceRefsDirectory(spaceDir),
+			resolveContract: () => deserializeContract(rawContract()),
+			deserializeContract
+		}),
+		problems,
+		refProblems,
+		headRefProblem,
+		isApp: false
+	};
+}
+/**
+* Read an extension's head ref, distinguishing a *genuinely absent*
+* `head.json` (`headRef: null`, no problem — judged `headRefMissing`)
+* from one that *exists but cannot be parsed* (`headRef: null` plus a
+* problem — judged `refUnreadable`, not `headRefMissing`).
+* `readContractSpaceHeadRef` already returns `null` only for ENOENT and
+* throws for unparseable / schema-invalid content, so the throw is the
+* corruption signal. Construction never throws on disk content.
+*/
+function isToleratedRefHeadReadError(error) {
+	if (MigrationToolsError.is(error)) return true;
+	if (!(error instanceof Error)) return false;
+	const code = error.code;
+	return code === "ENOENT" || code === "EISDIR";
+}
+async function readHeadRefTolerant(migrationsDir, spaceId) {
+	try {
+		return {
+			headRef: await readContractSpaceHeadRef(migrationsDir, spaceId),
+			problem: null
+		};
+	} catch (error) {
+		if (!isToleratedRefHeadReadError(error)) throw error;
+		return {
+			headRef: null,
+			problem: {
+				refName: HEAD_REF_NAME,
+				detail: detailOf(error)
+			}
+		};
+	}
+}
+function detailOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Read the raw on-disk contract eagerly (cheap I/O) but defer its
+* (throwing) failure to call time, so a missing or unparseable
+* `contract.json` becomes a `contract()` throw — surfaced as
+* `contractUnreadable` — rather than a construction failure.
+*/
+async function readRawContractDeferred(migrationsDir, spaceId) {
+	try {
+		const raw = await readContractSpaceContract(migrationsDir, spaceId);
+		return () => raw;
+	} catch (error) {
+		return () => {
+			throw error;
+		};
+	}
 }
 //#endregion
 //#region src/aggregate/strategies/graph-walk.ts
@@ -263,11 +498,13 @@ async function loadContractSpaceAggregate(input) {
 */
 function graphWalkStrategy(input) {
 	const { aggregateTargetId, member, currentMarker, refName } = input;
-	const { graph, packagesByMigrationHash } = member.migrations;
+	const headRef = requireHeadRef(member);
+	const graph = member.graph();
+	const packagesByMigrationHash = new Map(member.packages.map((pkg) => [pkg.metadata.migrationHash, pkg]));
 	const fromHash = currentMarker?.storageHash ?? "sha256:empty";
 	const markerInvariants = new Set(currentMarker?.invariants ?? []);
-	const required = new Set(member.headRef.invariants.filter((id) => !markerInvariants.has(id)));
-	const outcome = findPathWithDecision(graph, fromHash, member.headRef.hash, {
+	const required = new Set(headRef.invariants.filter((id) => !markerInvariants.has(id)));
+	const outcome = findPathWithDecision(graph, fromHash, headRef.hash, {
 		required,
 		...refName !== void 0 ? { refName } : {}
 	});
@@ -299,12 +536,12 @@ function graphWalkStrategy(input) {
 				targetId: aggregateTargetId,
 				spaceId: member.spaceId,
 				origin: currentMarker === null ? null : { storageHash: currentMarker.storageHash },
-				destination: { storageHash: member.headRef.hash },
+				destination: { storageHash: headRef.hash },
 				operations: pathOps,
 				providedInvariants: [...providedInvariantsSet].sort()
 			},
 			displayOps: pathOps,
-			destinationContract: member.contract,
+			destinationContract: member.contract(),
 			strategy: "graph-walk",
 			migrationEdges: edgeRefs,
 			pathDecision: outcome.decision
@@ -377,16 +614,11 @@ function projectSchemaToSpace(schema, member, otherMembers) {
 	if (typeof schemaObj.collections === "object" && schemaObj.collections !== null && !Array.isArray(schemaObj.collections)) return pruneRecord(schemaObj, "collections", ownedByOthers);
 	return schema;
 }
-/**
-* Collect the set of storage element names claimed by other members.
-* Reuses the loader's `extractStorageElementNames` helper so the
-* tables/collections walk lives in exactly one place.
-*/
 function collectOwnedNames(member, otherMembers) {
 	const owned = /* @__PURE__ */ new Set();
 	for (const other of otherMembers) {
 		if (other.spaceId === member.spaceId) continue;
-		for (const name of extractStorageElementNames(other.contract)) owned.add(name);
+		for (const { entityName } of elementCoordinates(other.contract().storage)) owned.add(entityName);
 	}
 	return owned;
 }
@@ -450,7 +682,7 @@ function pruneCollectionsArray(schemaObj, ownedByOthers) {
 async function synthStrategy(input) {
 	const projectedSchema = projectSchemaToSpace(input.schemaIntrospection, input.member, input.otherMembers);
 	const plannerResult = await input.migrations.createPlanner(input.familyInstance).plan({
-		contract: input.member.contract,
+		contract: input.member.contract(),
 		schema: projectedSchema,
 		policy: input.operationPolicy,
 		fromContract: null,
@@ -476,7 +708,7 @@ async function synthStrategy(input) {
 				}
 			}),
 			displayOps: synthedPlan.operations,
-			destinationContract: input.member.contract,
+			destinationContract: input.member.contract(),
 			strategy: "synth"
 		}
 	};
@@ -491,7 +723,7 @@ async function synthStrategy(input) {
 * 1. If `callerPolicy.ignoreGraphFor.has(member.spaceId)`:
 *    - If `member.headRef.invariants` is empty → synth.
 *    - Else → `policyConflict` (synth cannot satisfy authored invariants).
-* 2. Else if `member.migrations.graph` is non-empty AND graph-walk
+* 2. Else if `member.graph()` is non-empty AND graph-walk
 *    succeeds → graph-walk.
 * 3. Else if `member.headRef.invariants` is empty → synth.
 * 4. Else → graph-walk failure → `extensionPathUnreachable` /
@@ -500,12 +732,12 @@ async function synthStrategy(input) {
 * Output `applyOrder` is `[...aggregate.extensions.map(spaceId), aggregate.app.spaceId]`
 * — extensions alphabetical, then app — matching today's
 * `concatenateSpaceApplyInputs` ordering. This preserves
-* `MultiSpaceRunnerFailure.failingSpace` attribution byte-for-byte.
+* `MigrationRunnerFailure.failingSpace` attribution byte-for-byte.
 *
 * Every emitted `MigrationPlan` has `targetId = aggregate.targetId`.
 * No placeholder cast; no patch step.
 */
-async function planAggregate(input) {
+async function planMigration(input) {
 	const { aggregate, currentDBState, callerPolicy } = input;
 	const allMembers = [aggregate.app, ...aggregate.extensions];
 	const perSpace = /* @__PURE__ */ new Map();
@@ -513,12 +745,13 @@ async function planAggregate(input) {
 	for (const member of orderedMembers) {
 		const otherMembers = allMembers.filter((m) => m.spaceId !== member.spaceId);
 		const currentMarker = currentDBState.markersBySpaceId.get(member.spaceId) ?? null;
+		const headRef = requireHeadRef(member);
 		const ignoreGraph = callerPolicy.ignoreGraphFor.has(member.spaceId);
-		const invariantsRequired = member.headRef.invariants.length > 0;
+		const invariantsRequired = headRef.invariants.length > 0;
 		if (ignoreGraph && invariantsRequired) return notOk({
 			kind: "policyConflict",
 			spaceId: member.spaceId,
-			detail: `\`callerPolicy.ignoreGraphFor\` requested for space "${member.spaceId}", but the member declares non-empty head-ref invariants (${member.headRef.invariants.join(", ")}). Synthesising a plan from the contract IR cannot satisfy authored invariants — the graph must be walked. Either remove "${member.spaceId}" from \`ignoreGraphFor\` or amend the on-disk head ref to declare zero invariants.`
+			detail: `\`callerPolicy.ignoreGraphFor\` requested for space "${member.spaceId}", but the member declares non-empty head-ref invariants (${headRef.invariants.join(", ")}). Synthesising a plan from the contract IR cannot satisfy authored invariants — the graph must be walked. Either remove "${member.spaceId}" from \`ignoreGraphFor\` or amend the on-disk head ref to declare zero invariants.`
 		});
 		if (ignoreGraph) {
 			const synthOutcome = await synthStrategy({
@@ -539,7 +772,7 @@ async function planAggregate(input) {
 			perSpace.set(member.spaceId, synthOutcome.result);
 			continue;
 		}
-		if (member.migrations.graph.nodes.size > 0) {
+		if (member.graph().nodes.size > 0) {
 			const walked = graphWalkStrategy({
 				aggregateTargetId: aggregate.targetId,
 				member,
@@ -552,7 +785,7 @@ async function planAggregate(input) {
 			if (walked.kind === "unreachable") return notOk({
 				kind: "extensionPathUnreachable",
 				spaceId: member.spaceId,
-				target: member.headRef.hash
+				target: headRef.hash
 			});
 			return notOk({
 				kind: "extensionPathUnsatisfiable",
@@ -563,7 +796,7 @@ async function planAggregate(input) {
 		if (invariantsRequired) return notOk({
 			kind: "extensionPathUnsatisfiable",
 			spaceId: member.spaceId,
-			missingInvariants: [...member.headRef.invariants].sort()
+			missingInvariants: [...headRef.invariants].sort()
 		});
 		const synthOutcome = await synthStrategy({
 			aggregateTargetId: aggregate.targetId,
@@ -611,9 +844,9 @@ async function planAggregate(input) {
 * Pure synchronous function; no I/O. The caller (CLI) gathers
 * `markersBySpaceId` and `schemaIntrospection` ahead of the call.
 */
-function verifyAggregate(input) {
+function verifyMigration(input) {
 	try {
-		return runVerifyAggregate(input);
+		return runVerifyMigration(input);
 	} catch (error) {
 		return notOk({
 			kind: "introspectionFailure",
@@ -621,7 +854,7 @@ function verifyAggregate(input) {
 		});
 	}
 }
-function runVerifyAggregate(input) {
+function runVerifyMigration(input) {
 	const { aggregate, markersBySpaceId, schemaIntrospection, mode, verifySchemaForMember } = input;
 	const allMembers = [aggregate.app, ...aggregate.extensions];
 	const memberSpaceIds = new Set(allMembers.map((m) => m.spaceId));
@@ -632,16 +865,17 @@ function runVerifyAggregate(input) {
 			markerPerSpace.set(member.spaceId, { kind: "absent" });
 			continue;
 		}
-		if (marker.storageHash !== member.headRef.hash) {
+		const headRef = requireHeadRef(member);
+		if (marker.storageHash !== headRef.hash) {
 			markerPerSpace.set(member.spaceId, {
 				kind: "hashMismatch",
 				markerHash: marker.storageHash,
-				expected: member.headRef.hash
+				expected: headRef.hash
 			});
 			continue;
 		}
 		const markerInvariants = new Set(marker.invariants);
-		const missing = member.headRef.invariants.filter((id) => !markerInvariants.has(id));
+		const missing = headRef.invariants.filter((id) => !markerInvariants.has(id));
 		if (missing.length > 0) {
 			markerPerSpace.set(member.spaceId, {
 				kind: "missingInvariants",
@@ -684,7 +918,10 @@ function detectOrphanElements(schemaIntrospection, members) {
 	const liveTables = schemaIntrospection.tables;
 	if (typeof liveTables !== "object" || liveTables === null) return [];
 	const claimedTables = /* @__PURE__ */ new Set();
-	for (const member of members) for (const name of extractStorageElementNames(member.contract)) claimedTables.add(name);
+	for (const member of members) {
+		const contract = member.contract();
+		for (const { entityName } of elementCoordinates(contract.storage)) claimedTables.add(entityName);
+	}
 	const orphans = [];
 	for (const tableName of Object.keys(liveTables)) if (!claimedTables.has(tableName)) orphans.push({
 		kind: "table",
@@ -694,6 +931,6 @@ function detectOrphanElements(schemaIntrospection, members) {
 	return orphans;
 }
 //#endregion
-export { graphWalkStrategy, loadContractSpaceAggregate, planAggregate, projectSchemaToSpace, verifyAggregate };
+export { computeIntegrityViolations, createContractSpaceAggregate, createContractSpaceMember, graphWalkStrategy, loadContractSpaceAggregate, loadProblemToViolation, planMigration, projectSchemaToSpace, requireHeadRef, verifyMigration };
 
 //# sourceMappingURL=aggregate.mjs.map