@prisma-next/migration-tools 0.11.0-dev.46 → 0.11.0-dev.47

package/dist/exports/aggregate.mjs

@@ -1,10 +1,77 @@
-import { t as MigrationToolsError } from "../errors-CoEN114u.mjs";
-import { s as readMigrationsDir } from "../io-Dc64lvaL.mjs";
-import "../constants-DWV9_o2Z.mjs";
-import { l as reconstructGraph, o as findPathWithDecision } from "../migration-graph-D5JeadSE.mjs";
-import { c as spaceMigrationDirectory, r as APP_SPACE_ID, t as listContractSpaceDirectories } from "../verify-contract-spaces-DIdQLGo7.mjs";
-import { n as readContractSpaceHeadRef, t as readContractSpaceContract } from "../read-contract-space-contract-C4fEdoXO.mjs";
+import { t as MigrationToolsError } from "../errors-4YabujxZ.mjs";
+import { s as readMigrationsDir } from "../io-BHl0amF0.mjs";
+import { t as EMPTY_CONTRACT_HASH } from "../constants-DWV9_o2Z.mjs";
+import { l as reconstructGraph, o as findPathWithDecision } from "../migration-graph-kGBkIZDa.mjs";
+import { a as readRefsTolerant, t as HEAD_REF_NAME } from "../refs-BBKNL45K.mjs";
+import { c as spaceMigrationDirectory, i as RESERVED_SPACE_SUBDIR_NAMES, l as spaceRefsDirectory, r as APP_SPACE_ID, s as isValidSpaceId, t as listContractSpaceDirectories } from "../verify-contract-spaces-BJX5gqtD.mjs";
+import { n as readContractSpaceHeadRef, t as readContractSpaceContract } from "../read-contract-space-contract-7-OB-ykY.mjs";
 import { notOk, ok } from "@prisma-next/utils/result";
+//#region src/aggregate/aggregate.ts
+/**
+* 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()` and
+* `contract()` facets.
+*
+* `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`.
+*/
+function createContractSpaceMember(args) {
+	const { spaceId, packages, refs, headRef, resolveContract } = args;
+	let graphMemo;
+	let contractMemo;
+	return {
+		spaceId,
+		packages,
+		refs,
+		headRef,
+		graph() {
+			graphMemo ??= reconstructGraph(packages);
+			return graphMemo;
+		},
+		contract() {
+			contractMemo ??= resolveContract();
+			return contractMemo;
+		}
+	};
+}
+/**
+* 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/extract-storage-element-names.ts
 /**
 * Extract the set of top-level storage element names a contract claims.
@@ -61,189 +128,296 @@ function addRecordKeys(value, names) {
 	if (typeof value === "object" && value !== null && !Array.isArray(value)) for (const name of Object.keys(value)) names.add(name);
 }
 //#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
-			}
+			actual: contract.target
 		});
-	}
-	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)
-		});
-	}
-	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 elementName of extractStorageElementNames(contract)) {
 			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);
+	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) {
+	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: []
+			},
+			resolveContract: () => appContract
+		}),
+		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,
+			resolveContract: () => deserializeContract(rawContract())
+		}),
+		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
@@ -264,11 +438,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 } : {}
 	});
@@ -300,12 +476,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
@@ -387,7 +563,7 @@ 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 name of extractStorageElementNames(other.contract())) owned.add(name);
 	}
 	return owned;
 }
@@ -451,7 +627,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,
@@ -477,7 +653,7 @@ async function synthStrategy(input) {
 				}
 			}),
 			displayOps: synthedPlan.operations,
-			destinationContract: input.member.contract,
+			destinationContract: input.member.contract(),
 			strategy: "synth"
 		}
 	};
@@ -492,7 +668,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` /
@@ -514,12 +690,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({
@@ -540,7 +717,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,
@@ -553,7 +730,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",
@@ -564,7 +741,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,
@@ -633,16 +810,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",
@@ -685,7 +863,7 @@ 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) for (const name of extractStorageElementNames(member.contract())) claimedTables.add(name);
 	const orphans = [];
 	for (const tableName of Object.keys(liveTables)) if (!claimedTables.has(tableName)) orphans.push({
 		kind: "table",
@@ -695,6 +873,6 @@ function detectOrphanElements(schemaIntrospection, members) {
 	return orphans;
 }
 //#endregion
-export { graphWalkStrategy, loadContractSpaceAggregate, planAggregate, projectSchemaToSpace, verifyAggregate };
+export { computeIntegrityViolations, createContractSpaceAggregate, createContractSpaceMember, graphWalkStrategy, loadContractSpaceAggregate, loadProblemToViolation, planAggregate, projectSchemaToSpace, requireHeadRef, verifyAggregate };
 
 //# sourceMappingURL=aggregate.mjs.map