@prisma-next/migration-tools 0.11.0 → 0.12.0

package/src/aggregate/planner.ts

@@ -1,10 +1,6 @@
 import { notOk, ok } from '@prisma-next/utils/result';
-import type {
-  AggregatePerSpacePlan,
-  AggregatePlannerError,
-  AggregatePlannerInput,
-  AggregatePlannerOutput,
-} from './planner-types';
+import { requireHeadRef } from './aggregate';
+import type { PerSpacePlan, PlannerError, PlannerInput, PlannerOutput } from './planner-types';
 import { graphWalkStrategy } from './strategies/graph-walk';
 import { synthStrategy } from './strategies/synth';
 import type { ContractSpaceMember } from './types';
@@ -12,12 +8,12 @@ import type { ContractSpaceMember } from './types';
 export type {
   AggregateCurrentDBState,
   AggregateMigrationEdgeRef,
-  AggregatePerSpacePlan,
-  AggregatePlannerError,
-  AggregatePlannerInput,
-  AggregatePlannerOutput,
-  AggregatePlannerSuccess,
   CallerPolicy,
+  PerSpacePlan,
+  PlannerError,
+  PlannerInput,
+  PlannerOutput,
+  PlannerSuccess,
 } from './planner-types';
 
 /**
@@ -28,7 +24,7 @@ export type {
  * 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` /
@@ -37,18 +33,18 @@ export type {
  * 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.
  */
-export async function planAggregate<TFamilyId extends string, TTargetId extends string>(
-  input: AggregatePlannerInput<TFamilyId, TTargetId>,
-): Promise<AggregatePlannerOutput> {
+export async function planMigration<TFamilyId extends string, TTargetId extends string>(
+  input: PlannerInput<TFamilyId, TTargetId>,
+): Promise<PlannerOutput> {
   const { aggregate, currentDBState, callerPolicy } = input;
   const allMembers: ReadonlyArray<ContractSpaceMember> = [aggregate.app, ...aggregate.extensions];
 
-  const perSpace = new Map<string, AggregatePerSpacePlan>();
+  const perSpace = new Map<string, PerSpacePlan>();
 
   // Iterate in apply order so a per-member error short-circuits the
   // walk in the same order the runner would walk inputs.
@@ -60,15 +56,16 @@ export async function planAggregate<TFamilyId extends string, TTargetId extends
   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) {
-      const conflict: AggregatePlannerError = {
+      const conflict: PlannerError = {
         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.`,
       };
       return notOk(conflict);
     }
@@ -97,7 +94,7 @@ export async function planAggregate<TFamilyId extends string, TTargetId extends
 
     // Try graph-walk first when the graph has nodes; fall back to synth
     // when the graph is empty AND no invariants are required.
-    if (member.migrations.graph.nodes.size > 0) {
+    if (member.graph().nodes.size > 0) {
       const walked = graphWalkStrategy({
         aggregateTargetId: aggregate.targetId,
         member,
@@ -111,7 +108,7 @@ export async function planAggregate<TFamilyId extends string, TTargetId extends
         return notOk({
           kind: 'extensionPathUnreachable',
           spaceId: member.spaceId,
-          target: member.headRef.hash,
+          target: headRef.hash,
         });
       }
       // unsatisfiable — surface
@@ -128,7 +125,7 @@ export async function planAggregate<TFamilyId extends string, TTargetId extends
       return notOk({
         kind: 'extensionPathUnsatisfiable',
         spaceId: member.spaceId,
-        missingInvariants: [...member.headRef.invariants].sort(),
+        missingInvariants: [...headRef.invariants].sort(),
       });
     }
 

package/src/aggregate/project-schema-to-space.ts

@@ -1,4 +1,4 @@
-import { extractStorageElementNames } from './extract-storage-element-names';
+import { elementCoordinates } from '@prisma-next/framework-components/ir';
 import type { ContractSpaceMember } from './types';
 
 /**
@@ -90,11 +90,6 @@ export function projectSchemaToSpace(
   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: ContractSpaceMember,
   otherMembers: ReadonlyArray<ContractSpaceMember>,
@@ -102,8 +97,8 @@ function collectOwnedNames(
   const owned = new Set<string>();
   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;

package/src/aggregate/strategies/graph-walk.ts

@@ -1,21 +1,22 @@
 import type { MigrationPlan } from '@prisma-next/framework-components/control';
 import { EMPTY_CONTRACT_HASH } from '../../constants';
 import { findPathWithDecision } from '../../migration-graph';
-import type { MigrationOps } from '../../package';
+import type { MigrationOps, OnDiskMigrationPackage } from '../../package';
+import { requireHeadRef } from '../aggregate';
 import type { ContractMarkerRecordLike } from '../marker-types';
-import type { AggregatePerSpacePlan } from '../planner-types';
+import type { PerSpacePlan } from '../planner-types';
 import type { ContractSpaceMember } from '../types';
 
 /**
  * Outcome variants for the graph-walk strategy. Mirrors
  * {@link import('../../compute-extension-space-apply-path').ExtensionSpaceApplyPathOutcome}
- * but operates against the **already-hydrated** `member.migrations.graph`
+ * but operates against the member's lazily-reconstructed `graph()`
  * instead of re-reading from disk. The aggregate planner converts
- * these into {@link import('../planner-types').AggregatePlannerError}
+ * these into {@link import('../planner-types').PlannerError}
  * variants.
  */
 export type GraphWalkOutcome =
-  | { readonly kind: 'ok'; readonly result: AggregatePerSpacePlan }
+  | { readonly kind: 'ok'; readonly result: PerSpacePlan }
   | { readonly kind: 'unreachable' }
   | { readonly kind: 'unsatisfiable'; readonly missing: readonly string[] };
 
@@ -49,13 +50,17 @@ export interface GraphWalkStrategyInputs {
  */
 export function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOutcome {
   const { aggregateTargetId, member, currentMarker, refName } = input;
-  const { graph, packagesByMigrationHash } = member.migrations;
+  const headRef = requireHeadRef(member);
+  const graph = member.graph();
+  const packagesByMigrationHash = new Map<string, OnDiskMigrationPackage>(
+    member.packages.map((pkg) => [pkg.metadata.migrationHash, pkg]),
+  );
 
   const fromHash = currentMarker?.storageHash ?? EMPTY_CONTRACT_HASH;
   const markerInvariants = new Set(currentMarker?.invariants ?? []);
-  const required = new Set(member.headRef.invariants.filter((id) => !markerInvariants.has(id)));
+  const required = new Set(headRef.invariants.filter((id) => !markerInvariants.has(id)));
 
-  const outcome = findPathWithDecision(graph, fromHash, member.headRef.hash, {
+  const outcome = findPathWithDecision(graph, fromHash, headRef.hash, {
     required,
     ...(refName !== undefined ? { refName } : {}),
   });
@@ -98,7 +103,7 @@ export function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOutc
     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(),
   };
@@ -108,7 +113,7 @@ export function graphWalkStrategy(input: GraphWalkStrategyInputs): GraphWalkOutc
     result: {
       plan,
       displayOps: pathOps,
-      destinationContract: member.contract,
+      destinationContract: member.contract(),
       strategy: 'graph-walk',
       migrationEdges: edgeRefs,
       pathDecision: outcome.decision,

package/src/aggregate/strategies/synth.ts

@@ -7,7 +7,7 @@ import type {
   MigrationPlannerResult,
   TargetMigrationsCapability,
 } from '@prisma-next/framework-components/control';
-import type { AggregatePerSpacePlan } from '../planner-types';
+import type { PerSpacePlan } from '../planner-types';
 import { projectSchemaToSpace } from '../project-schema-to-space';
 import type { ContractSpaceMember } from '../types';
 
@@ -27,7 +27,7 @@ export interface SynthStrategyInputs<TFamilyId extends string, TTargetId extends
 }
 
 export type SynthStrategyOutcome =
-  | { readonly kind: 'ok'; readonly result: AggregatePerSpacePlan }
+  | { readonly kind: 'ok'; readonly result: PerSpacePlan }
   | { readonly kind: 'failure'; readonly conflicts: readonly MigrationPlannerConflict[] };
 
 /**
@@ -73,7 +73,7 @@ export async function synthStrategy<TFamilyId extends string, TTargetId extends
 
   const planner = input.migrations.createPlanner(input.familyInstance);
   const plannerResult: MigrationPlannerResult = await (planner.plan({
-    contract: input.member.contract,
+    contract: input.member.contract(),
     schema: projectedSchema,
     policy: input.operationPolicy,
     fromContract: null,
@@ -114,7 +114,7 @@ export async function synthStrategy<TFamilyId extends string, TTargetId extends
     result: {
       plan,
       displayOps: synthedPlan.operations,
-      destinationContract: input.member.contract,
+      destinationContract: input.member.contract(),
       strategy: 'synth',
     },
   };

package/src/aggregate/types.ts

@@ -1,89 +1,108 @@
 import type { Contract } from '@prisma-next/contract/types';
 import type { MigrationGraph } from '../graph';
+import type { IntegrityQueryOptions, IntegrityViolation } from '../integrity-violation';
 import type { OnDiskMigrationPackage } from '../package';
+import type { Refs } from '../refs';
+import type { ContractSpaceHeadRecord } from '../verify-contract-spaces';
 
-/**
- * Hydrated migration graph for a single contract space.
- *
- * `graph` is the structural shortest-path graph (forward / reverse chain,
- * deterministic tie-break order) reconstructed from a set of on-disk
- * migration packages. `packagesByMigrationHash` is the lookup table the
- * graph-walk strategy uses to resolve a path's edge sequence back to the
- * concrete `OnDiskMigrationPackage` (and therefore the operation list) for
- * apply.
- *
- * Eagerly hydrated by the loader. Once a `ContractSpaceAggregate` exists,
- * downstream consumers do **not** touch the filesystem to walk graphs or
- * resolve packages — the aggregate is the boundary.
- */
-export interface HydratedMigrationGraph {
-  readonly graph: MigrationGraph;
-  readonly packagesByMigrationHash: ReadonlyMap<string, OnDiskMigrationPackage>;
+export interface ContractAtOptions {
+  readonly refName?: string;
 }
 
+export type ContractAtResult =
+  | {
+      readonly provenance: 'snapshot';
+      readonly hash: string;
+      readonly contractJson: unknown;
+      readonly contractDts: string;
+      readonly contract: Contract;
+    }
+  | {
+      readonly provenance: 'graph-node';
+      readonly sourceDir: string;
+      readonly hash: string;
+      readonly contractJson: unknown;
+      readonly contractDts: string;
+      readonly contract: Contract;
+    };
+
 /**
  * One contract space — app or extension — as a member of a
  * {@link ContractSpaceAggregate}. Every member has the same shape.
  *
+ * A member is a tolerant snapshot of one space's on-disk state, not a
+ * validated value: `packages` is the raw migration-package list as read
+ * from disk (a hash- or invariants-mismatched package is retained here;
+ * a genuinely unparseable one is omitted), and integrity is judged
+ * separately by {@link ContractSpaceAggregate.checkIntegrity}.
+ *
  * - `spaceId`: `'app'` for the application, otherwise the extension's
  *   id (validated against `[a-z][a-z0-9_-]{0,63}`).
- * - `contract`: the validated contract value for this member. For the
- *   app, the user's authored contract; for an extension, the on-disk
- *   `migrations/<spaceId>/contract.json`. Both have already passed the
- *   family's `deserializeContract` at the loader boundary.
- * - `headRef.hash`: the storage hash this member is targeting. For the
- *   app, equals `contract.storage.storageHash`. For extensions, the
- *   on-disk `refs/head.json.hash`.
- * - `headRef.invariants`: alphabetically sorted, deduplicated invariant
- *   ids declared on the head ref. Empty for the app member (the app's
- *   plan is synthesised from the contract IR, no invariants required).
- * - `migrations`: the hydrated migration graph for this space. Possibly
- *   empty (an extension whose on-disk head ref points at the
- *   empty-contract sentinel and ships no migrations yet, or the app
- *   when the user hasn't authored any).
+ * - `packages`: raw on-disk migration packages, as read; never
+ *   integrity-validated at load.
+ * - `refs`: the user-authored refs under `migrations/<spaceId>/refs/*.json`.
+ * - `headRef`: the system head ref read from
+ *   `migrations/<spaceId>/refs/head.json`, or `null` when absent
+ *   (represented as a `headRefMissing` violation, never fatal). The app
+ *   member's head ref is always synthesised from its live contract's
+ *   storage hash, so it is never `null`.
+ * - `graph()`: the migration graph this space's packages induce —
+ *   lazily reconstructed on first call and memoised. Pure structure: a
+ *   `from === to` self-edge is represented, not rejected.
+ * - `contract()`: the deserialized contract for this member — lazily
+ *   produced on first call and memoised. For the app it is the live
+ *   contract the caller supplied; for an extension it is the on-disk
+ *   `migrations/<spaceId>/contract.json` run through the family's
+ *   `deserializeContract`. Throws if the on-disk contract is missing or
+ *   undeserializable (surfaced as `contractUnreadable` by `checkIntegrity`
+ *   under `checkContracts`); callers gate before querying it.
+ * - `contractAt(hash, opts?)`: materializes the contract at an arbitrary
+ *   graph node — when `opts.refName` is set, prefer the ref's paired
+ *   snapshot; else find the package whose `metadata.to === hash` and read
+ *   its `end-contract.*`. Lazy per `(hash, refName?)` memoisation; throws
+ *   typed {@link MigrationToolsError} values compatible with CLI mappers.
  */
 export interface ContractSpaceMember {
   readonly spaceId: string;
-  readonly contract: Contract;
-  readonly headRef: {
-    readonly hash: string;
-    readonly invariants: readonly string[];
-  };
-  readonly migrations: HydratedMigrationGraph;
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly refs: Refs;
+  readonly headRef: ContractSpaceHeadRecord | null;
+  graph(): MigrationGraph;
+  contract(): Contract;
+  contractAt(hash: string, opts?: ContractAtOptions): Promise<ContractAtResult>;
 }
 
 /**
- * Typed value carrying the user's app contract plus every loaded
- * extension contract space, fully hydrated and internally consistent.
+ * Tolerant, queryable snapshot of a project's on-disk migration state:
+ * the app contract space plus every extension contract space, each a
+ * {@link ContractSpaceMember}.
  *
  * Produced once per CLI invocation by `loadContractSpaceAggregate`.
- * Every downstream component (planner, verifier, runner adapter)
- * consumes this value rather than rebuilding state from disk.
- *
- * Invariants the loader enforces at construction:
- *
- * 1. `targetId` is consistent across every member (`contract.target`
- *    matches `aggregate.targetId`). The aggregate's `targetId` is the
- *    `Config.adapter.targetId` value the loader was told to use.
- * 2. `aggregate.extensions` is sorted alphabetically by `spaceId`.
- *    Mirrors {@link import('../concatenate-space-apply-inputs').concatenateSpaceApplyInputs}'s
- *    extension ordering convention so downstream apply order matches
- *    today's behaviour byte-for-byte.
- * 3. No two members claim the same storage element (table / type / etc.).
- * 4. For each extension member: `member.headRef.hash` is reachable from
- *    the empty-contract sentinel in `member.migrations.graph` (or the
- *    graph is empty and `member.headRef.hash === EMPTY_CONTRACT_HASH`).
- * 5. For the app member: `member.headRef.hash` equals
- *    `member.contract.storage.storageHash`. The app's `migrations`
- *    is hydrated from the user's authored `migrations/` (or empty if
- *    none).
+ * Building the aggregate never throws on disk content; every consumer
+ * obtains spaces / packages / refs / graphs from this one value rather
+ * than re-deriving them from disk.
  *
- * The aggregate is **type-uniform** post-construction: app/extension
- * distinguishability survives only at the caller-policy layer
- * (`ignoreGraphFor: new Set([appSpaceId])`), not on member shape.
+ * - `targetId`: the app contract's target; every member is expected to
+ *   share it (a mismatch surfaces as a `targetMismatch` violation under
+ *   `checkContracts`).
+ * - `app` / `extensions`: retained as fields for the existing planner /
+ *   verifier / runner consumers. `extensions` is sorted alphabetically
+ *   by `spaceId` (the apply-ordering convention).
+ * - `listSpaces()` / `hasSpace()` / `space()` / `spaces()`: the query
+ *   surface the read commands consume — `app` first, then extension ids
+ *   lex-ascending.
+ * - `checkIntegrity()`: judges the loaded model and returns every
+ *   violation (never bailing at the first). Config/contract-dependent
+ *   checks run only when the matching {@link IntegrityQueryOptions} opt
+ *   is set.
  */
 export interface ContractSpaceAggregate {
   readonly targetId: string;
   readonly app: ContractSpaceMember;
   readonly extensions: readonly ContractSpaceMember[];
+  listSpaces(): readonly string[];
+  hasSpace(id: string): boolean;
+  space(id: string): ContractSpaceMember | undefined;
+  spaces(): readonly ContractSpaceMember[];
+  checkIntegrity(opts?: IntegrityQueryOptions): readonly IntegrityViolation[];
 }

package/src/aggregate/verifier.ts

@@ -1,17 +1,18 @@
+import { elementCoordinates } from '@prisma-next/framework-components/ir';
 import type { Result } from '@prisma-next/utils/result';
 import { notOk, ok } from '@prisma-next/utils/result';
-import { extractStorageElementNames } from './extract-storage-element-names';
+import { requireHeadRef } from './aggregate';
 import type { ContractMarkerRecordLike } from './marker-types';
 import { projectSchemaToSpace } from './project-schema-to-space';
 import type { ContractSpaceAggregate, ContractSpaceMember } from './types';
 
 /**
- * Caller policy for the aggregate verifier. Today's only knob is
+ * Caller policy for the verifier. Today's only knob is
  * `mode`: `strict` treats orphan elements (live tables not claimed by
  * any aggregate member) as errors; `lenient` treats them as
  * informational. Maps directly to `db verify --strict`.
  */
-export interface AggregateVerifierInput<TSchemaResult> {
+export interface VerifierInput<TSchemaResult> {
   readonly aggregate: ContractSpaceAggregate;
   readonly markersBySpaceId: ReadonlyMap<string, ContractMarkerRecordLike | null>;
   readonly schemaIntrospection: unknown;
@@ -19,7 +20,7 @@ export interface AggregateVerifierInput<TSchemaResult> {
   /**
    * Caller-supplied per-space schema verifier. The CLI wires this to
    * the family's `verifySqlSchema` (SQL) / equivalent (other
-   * families). The aggregate verifier projects the schema to the
+   * families). The verifier projects the schema to the
    * member's slice via {@link projectSchemaToSpace} before invoking
    * the callback, so single-contract semantics are preserved.
    *
@@ -61,7 +62,7 @@ export interface MarkerCheckSection {
 
 /**
  * A live storage element (today: a top-level table) not claimed by any
- * member of the aggregate. The aggregate verifier always reports these;
+ * member of the aggregate. The verifier always reports these;
  * the caller decides what to do — `db verify --strict` treats them as
  * errors, the lenient default treats them as informational.
  *
@@ -80,20 +81,17 @@ export interface SchemaCheckSection<TSchemaResult> {
   readonly orphanElements: readonly OrphanElement[];
 }
 
-export interface AggregateVerifierSuccess<TSchemaResult> {
+export interface VerifierSuccess<TSchemaResult> {
   readonly markerCheck: MarkerCheckSection;
   readonly schemaCheck: SchemaCheckSection<TSchemaResult>;
 }
 
-export type AggregateVerifierError = {
+export type VerifierError = {
   readonly kind: 'introspectionFailure';
   readonly detail: string;
 };
 
-export type AggregateVerifierOutput<TSchemaResult> = Result<
-  AggregateVerifierSuccess<TSchemaResult>,
-  AggregateVerifierError
->;
+export type VerifierOutput<TSchemaResult> = Result<VerifierSuccess<TSchemaResult>, VerifierError>;
 
 /**
  * Verify a {@link ContractSpaceAggregate} against the live database
@@ -117,11 +115,11 @@ export type AggregateVerifierOutput<TSchemaResult> = Result<
  * Pure synchronous function; no I/O. The caller (CLI) gathers
  * `markersBySpaceId` and `schemaIntrospection` ahead of the call.
  */
-export function verifyAggregate<TSchemaResult>(
-  input: AggregateVerifierInput<TSchemaResult>,
-): AggregateVerifierOutput<TSchemaResult> {
+export function verifyMigration<TSchemaResult>(
+  input: VerifierInput<TSchemaResult>,
+): VerifierOutput<TSchemaResult> {
   try {
-    return runVerifyAggregate(input);
+    return runVerifyMigration(input);
   } catch (error) {
     return notOk({
       kind: 'introspectionFailure',
@@ -130,9 +128,9 @@ export function verifyAggregate<TSchemaResult>(
   }
 }
 
-function runVerifyAggregate<TSchemaResult>(
-  input: AggregateVerifierInput<TSchemaResult>,
-): AggregateVerifierOutput<TSchemaResult> {
+function runVerifyMigration<TSchemaResult>(
+  input: VerifierInput<TSchemaResult>,
+): VerifierOutput<TSchemaResult> {
   const { aggregate, markersBySpaceId, schemaIntrospection, mode, verifySchemaForMember } = input;
   const allMembers: ReadonlyArray<ContractSpaceMember> = [aggregate.app, ...aggregate.extensions];
   const memberSpaceIds = new Set(allMembers.map((m) => m.spaceId));
@@ -145,16 +143,17 @@ function runVerifyAggregate<TSchemaResult>(
       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',
@@ -211,8 +210,9 @@ function detectOrphanElements(
 
   const claimedTables = new Set<string>();
   for (const member of members) {
-    for (const name of extractStorageElementNames(member.contract)) {
-      claimedTables.add(name);
+    const contract = member.contract();
+    for (const { entityName } of elementCoordinates(contract.storage)) {
+      claimedTables.add(entityName);
     }
   }
 

package/src/assert-descriptor-self-consistency.ts

@@ -1,4 +1,6 @@
+import type { PreserveEmptyPredicate, StorageSort } from '@prisma-next/contract/hashing';
 import { computeStorageHash } from '@prisma-next/contract/hashing';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { errorDescriptorHeadHashMismatch } from './errors';
 
 function stripNamespaceKinds(storage: Record<string, unknown>): Record<string, unknown> {
@@ -35,6 +37,8 @@ export interface DescriptorSelfConsistencyInputs {
    */
   readonly storage: unknown;
   readonly headRefHash: string;
+  readonly shouldPreserveEmpty?: PreserveEmptyPredicate;
+  readonly sortStorage?: StorageSort;
 }
 
 /**
@@ -82,6 +86,8 @@ export function assertDescriptorSelfConsistency(inputs: DescriptorSelfConsistenc
     target: inputs.target,
     targetFamily: inputs.targetFamily,
     storage: normalizedStorage,
+    ...ifDefined('shouldPreserveEmpty', inputs.shouldPreserveEmpty),
+    ...ifDefined('sortStorage', inputs.sortStorage),
   });
   if (recomputed !== inputs.headRefHash) {
     throw errorDescriptorHeadHashMismatch({

package/src/compute-extension-space-apply-path.ts

@@ -97,7 +97,7 @@ export async function computeExtensionSpaceApplyPath(
   }
 
   const spaceDir = spaceMigrationDirectory(projectMigrationsDir, spaceId);
-  const packages = await readMigrationsDir(spaceDir);
+  const { packages } = await readMigrationsDir(spaceDir);
   const graph = reconstructGraph(packages);
 
   // Live-marker layer encodes "no prior state" as EMPTY_CONTRACT_HASH;

package/src/emit-contract-space-artefacts.ts

@@ -2,7 +2,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { canonicalizeJson } from '@prisma-next/framework-components/utils';
 import { join } from 'pathe';
 import type { ContractSpaceHeadRef } from './read-contract-space-head-ref';
-import { assertValidSpaceId } from './space-layout';
+import { assertValidSpaceId, spaceRefsDirectory } from './space-layout';
 
 /**
  * Inputs for {@link emitContractSpaceArtefacts}.
@@ -56,7 +56,8 @@ export async function emitContractSpaceArtefacts(
   assertValidSpaceId(spaceId);
 
   const dir = join(projectMigrationsDir, spaceId);
-  await mkdir(join(dir, 'refs'), { recursive: true });
+  const refsDir = spaceRefsDirectory(dir);
+  await mkdir(refsDir, { recursive: true });
 
   await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(inputs.contract)}\n`);
   await writeFile(join(dir, 'contract.d.ts'), inputs.contractDts);
@@ -66,5 +67,5 @@ export async function emitContractSpaceArtefacts(
     hash: inputs.headRef.hash,
     invariants: sortedInvariants,
   });
-  await writeFile(join(dir, 'refs', 'head.json'), `${headJson}\n`);
+  await writeFile(join(refsDir, 'head.json'), `${headJson}\n`);
 }