@prisma-next/cli 0.11.0-dev.59 → 0.11.0-dev.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma-next/cli",
-  "version": "0.11.0-dev.59",
+  "version": "0.11.0-dev.60",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
@@ -14,15 +14,15 @@
   "dependencies": {
     "@clack/prompts": "^1.4.0",
     "@dagrejs/dagre": "^3.0.0",
-    "@prisma-next/config": "0.11.0-dev.59",
-    "@prisma-next/contract": "0.11.0-dev.59",
-    "@prisma-next/emitter": "0.11.0-dev.59",
-    "@prisma-next/errors": "0.11.0-dev.59",
-    "@prisma-next/framework-components": "0.11.0-dev.59",
-    "@prisma-next/migration-tools": "0.11.0-dev.59",
-    "@prisma-next/psl-printer": "0.11.0-dev.59",
-    "@prisma-next/cli-telemetry": "0.11.0-dev.59",
-    "@prisma-next/utils": "0.11.0-dev.59",
+    "@prisma-next/config": "0.11.0-dev.60",
+    "@prisma-next/contract": "0.11.0-dev.60",
+    "@prisma-next/emitter": "0.11.0-dev.60",
+    "@prisma-next/errors": "0.11.0-dev.60",
+    "@prisma-next/framework-components": "0.11.0-dev.60",
+    "@prisma-next/migration-tools": "0.11.0-dev.60",
+    "@prisma-next/psl-printer": "0.11.0-dev.60",
+    "@prisma-next/cli-telemetry": "0.11.0-dev.60",
+    "@prisma-next/utils": "0.11.0-dev.60",
     "arktype": "^2.2.0",
     "c12": "^3.3.4",
     "ci-info": "^4.3.1",
@@ -39,14 +39,14 @@
     "wrap-ansi": "^10.0.0"
   },
   "devDependencies": {
-    "@prisma-next/sql-contract": "0.11.0-dev.59",
-    "@prisma-next/sql-contract-emitter": "0.11.0-dev.59",
-    "@prisma-next/sql-contract-ts": "0.11.0-dev.59",
-    "@prisma-next/sql-operations": "0.11.0-dev.59",
-    "@prisma-next/sql-runtime": "0.11.0-dev.59",
-    "@prisma-next/test-utils": "0.11.0-dev.59",
-    "@prisma-next/tsconfig": "0.11.0-dev.59",
-    "@prisma-next/tsdown": "0.11.0-dev.59",
+    "@prisma-next/sql-contract": "0.11.0-dev.60",
+    "@prisma-next/sql-contract-emitter": "0.11.0-dev.60",
+    "@prisma-next/sql-contract-ts": "0.11.0-dev.60",
+    "@prisma-next/sql-operations": "0.11.0-dev.60",
+    "@prisma-next/sql-runtime": "0.11.0-dev.60",
+    "@prisma-next/test-utils": "0.11.0-dev.60",
+    "@prisma-next/tsconfig": "0.11.0-dev.60",
+    "@prisma-next/tsdown": "0.11.0-dev.60",
     "@types/node": "25.6.0",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",

package/src/commands/db-sign.ts

@@ -5,7 +5,6 @@ import type {
 } from '@prisma-next/framework-components/control';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
-import { readRefs } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { join, relative, resolve } from 'pathe';
@@ -25,13 +24,13 @@ import {
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
   maskConnectionUrl,
   resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import {
   formatSchemaVerifyJson,
@@ -99,9 +98,14 @@ async function executeDbSignCommand(
 
   if (effectiveContractArg) {
     try {
-      const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
-      const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
-      const refs = await readRefs(refsDir);
+      const { migrationsDir } = resolveMigrationPaths(options.config, config);
+      const loaded = await buildReadAggregate(config, { migrationsDir });
+      if (!loaded.ok) {
+        return notOk(loaded.failure);
+      }
+      const graph = loaded.value.aggregate.app.graph();
+      const bundles = loaded.value.aggregate.app.packages;
+      const refs = loaded.value.aggregate.app.refs;
       const refResult = parseContractRef(effectiveContractArg, { graph, refs });
       if (!refResult.ok) {
         return notOk(mapRefResolutionError(refResult.failure));

package/src/commands/db-update.ts

@@ -1,7 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
-import { readRefs } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -21,12 +20,12 @@ import {
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
-  loadMigrationPackages,
   resolveMigrationPaths,
   sanitizeErrorMessage,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import {
   formatMigrationApplyOutput,
   formatMigrationJson,
@@ -109,15 +108,17 @@ async function executeDbUpdateCommand(
   const { client, config, dbConnection, onProgress, contractPathAbsolute } = ctxResult.value;
   let { contractJson } = ctxResult.value;
   let contractJsonPathForSnapshot = contractPathAbsolute;
-  const { migrationsDir, appMigrationsDir, refsDir } = resolveMigrationPaths(
-    options.config,
-    config,
-  );
+  const { migrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
 
   if (options.to) {
     try {
-      const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
-      const refs = await readRefs(refsDir);
+      const loaded = await buildReadAggregate(config, { migrationsDir });
+      if (!loaded.ok) {
+        return notOk(loaded.failure);
+      }
+      const graph = loaded.value.aggregate.app.graph();
+      const bundles = loaded.value.aggregate.app.packages;
+      const refs = loaded.value.aggregate.app.refs;
       const refResult = parseContractRef(options.to, { graph, refs });
       if (!refResult.ok) {
         return notOk(mapRefResolutionError(refResult.failure));

package/src/commands/migration-graph.ts

@@ -1,24 +1,17 @@
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
-import { readRefs } from '@prisma-next/migration-tools/refs';
-import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
-import {
-  type CliStructuredError,
-  errorUnexpected,
-  mapMigrationToolsError,
-} from '../utils/cli-errors';
+import type { CliStructuredError } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
-  readContractEnvelope,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   setCommandSeeAlso,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { migrationGraphToRenderInput } from '../utils/formatters/graph-migration-mapper';
 import { graphRenderer } from '../utils/formatters/graph-render';
 import { formatStyledHeader } from '../utils/formatters/styled';
@@ -41,13 +34,13 @@ export interface MigrationGraphResult {
   readonly summary: string;
 }
 
-async function executeMigrationGraphCommand(
+export async function executeMigrationGraphCommand(
   options: MigrationGraphOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationGraphResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
+  const { configPath, appMigrationsRelative, migrationsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -65,37 +58,18 @@ async function executeMigrationGraphCommand(
     ui.stderr(header);
   }
 
-  let graph: MigrationGraph;
-  try {
-    ({ graph } = await loadMigrationPackages(appMigrationsDir));
-  } catch (error) {
-    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
-    return notOk(
-      errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
-  }
-
-  let contractHash: string | null = null;
-  try {
-    const envelope = await readContractEnvelope(config);
-    contractHash = envelope.storageHash;
-  } catch {
-    // Contract unreadable — render graph without contract marker
+  const loaded = await buildReadAggregate(config, { migrationsDir });
+  if (!loaded.ok) {
+    return loaded;
   }
 
-  let refs: readonly StatusRef[] = [];
-  try {
-    const allRefs = await readRefs(refsDir);
-    refs = Object.entries(allRefs).map(([name, entry]) => ({
-      name,
-      hash: entry.hash,
-      active: false,
-    }));
-  } catch {
-    // Refs unreadable — render graph without ref markers
-  }
+  const { aggregate, contractHash } = loaded.value;
+  const graph = aggregate.app.graph();
+  const refs: readonly StatusRef[] = Object.entries(aggregate.app.refs).map(([name, entry]) => ({
+    name,
+    hash: entry.hash,
+    active: false,
+  }));
 
   return ok({
     ok: true,

package/src/commands/migration-list.ts

@@ -1,10 +1,14 @@
-import { enumerateMigrationSpaces } from '@prisma-next/migration-tools/enumerate-migration-spaces';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type {
-  MigrationListResult,
-  MigrationSpaceListEntry,
-} from '@prisma-next/migration-tools/migration-list-types';
-import { APP_SPACE_ID, isValidSpaceId } from '@prisma-next/migration-tools/spaces';
+  ContractSpaceAggregate,
+  ContractSpaceMember,
+} from '@prisma-next/migration-tools/aggregate';
+import { HEAD_REF_NAME, refsByContractHash } from '@prisma-next/migration-tools/refs';
+import {
+  APP_SPACE_ID,
+  isValidSpaceId,
+  listContractSpaceDirectories,
+  RESERVED_SPACE_SUBDIR_NAMES,
+} from '@prisma-next/migration-tools/spaces';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -13,8 +17,6 @@ import {
   type CliStructuredError,
   errorInvalidSpaceId,
   errorSpaceNotFound,
-  errorUnexpected,
-  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -23,6 +25,7 @@ import {
   setCommandExamples,
   setCommandSeeAlso,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import {
   type GlyphMode,
   renderMigrationListGraphResult,
@@ -32,12 +35,101 @@ import {
   renderMigrationListWithStyle,
 } from '../utils/formatters/migration-list-render';
 import { createAnsiMigrationListStyler } from '../utils/formatters/migration-list-styler';
+import type {
+  MigrationListEntry,
+  MigrationListResult,
+  MigrationSpaceListEntry,
+} from '../utils/formatters/migration-list-types';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
+function compareSpaceIds(a: string, b: string): number {
+  if (a === APP_SPACE_ID) return b === APP_SPACE_ID ? 0 : -1;
+  if (b === APP_SPACE_ID) return 1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function compareDirNamesDescending(a: MigrationListEntry, b: MigrationListEntry): number {
+  if (a.dirName < b.dirName) return 1;
+  if (a.dirName > b.dirName) return -1;
+  return 0;
+}
+
+/**
+ * Ref names decorating a space's destination contract hashes. The
+ * tolerant `member.refs` deliberately omits the structural `head.json`;
+ * for extension spaces the old enumerator surfaced it as a `head`
+ * decoration on the tip migration, so fold `member.headRef` back in to
+ * keep that output. The app space synthesises its head, so it carries
+ * no on-disk `head` ref to restore.
+ */
+function listRefsByContractHash(
+  member: ContractSpaceMember,
+): ReadonlyMap<string, readonly string[]> {
+  const byHash = new Map(refsByContractHash(member.refs));
+  if (member.spaceId !== APP_SPACE_ID && member.headRef !== null) {
+    const hash = member.headRef.hash;
+    const bucket = byHash.get(hash) ?? [];
+    if (!bucket.includes(HEAD_REF_NAME)) {
+      byHash.set(hash, [...bucket, HEAD_REF_NAME].sort());
+    }
+  }
+  return byHash;
+}
+
+async function orderedOnDiskSpaceIds(projectMigrationsDir: string): Promise<readonly string[]> {
+  const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
+  return candidateDirs
+    .filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name))
+    .filter(isValidSpaceId)
+    .sort(compareSpaceIds);
+}
+
+/**
+ * Project the loaded {@link ContractSpaceAggregate} into the render-ready
+ * {@link MigrationSpaceListEntry} rows `migration list` displays.
+ *
+ * Space membership matches the on-disk contract-space directories (not the
+ * aggregate's always-present synthesized app member when `migrations/app/`
+ * is absent); package and ref data come from `aggregate.space(id)`.
+ */
+export async function migrationSpaceListEntriesFromAggregate(
+  aggregate: ContractSpaceAggregate,
+  projectMigrationsDir: string,
+): Promise<readonly MigrationSpaceListEntry[]> {
+  const spaceIds = await orderedOnDiskSpaceIds(projectMigrationsDir);
+  const spaces: MigrationSpaceListEntry[] = [];
+
+  for (const spaceId of spaceIds) {
+    const member = aggregate.space(spaceId);
+    if (member === undefined) {
+      continue;
+    }
+    const refsByHash = listRefsByContractHash(member);
+    const migrations: MigrationListEntry[] = member.packages
+      .map((pkg) => ({
+        dirName: pkg.dirName,
+        from: pkg.metadata.from,
+        to: pkg.metadata.to,
+        migrationHash: pkg.metadata.migrationHash,
+        operationCount: pkg.ops.length,
+        createdAt: pkg.metadata.createdAt,
+        refs: refsByHash.get(pkg.metadata.to) ?? [],
+        providedInvariants: pkg.metadata.providedInvariants,
+      }))
+      .sort(compareDirNamesDescending);
+
+    spaces.push({ spaceId, migrations });
+  }
+
+  return spaces;
+}
+
 interface MigrationListOptions extends CommonCommandOptions {
   readonly config?: string;
   readonly space?: string;
@@ -64,23 +156,15 @@ export function renderMigrationListHumanOutput(
 }
 
 /**
- * Inputs for {@link runMigrationList} — the pure-ish data-and-policy core
- * of `migration list` that tests exercise directly.
+ * Inputs for {@link runMigrationList} — the policy core of `migration list`
+ * that tests exercise directly.
  *
- * The core depends only on the filesystem rooted at `migrationsDir`. It
- * does NOT call `loadConfig`, parse CLI flags, render a styled header,
- * or write to any stream. Output rendering is the caller's concern (the
- * CLI shell renders via {@link renderMigrationList}; JSON callers
- * serialize the {@link MigrationListResult} directly).
+ * The core does not call `loadConfig`, parse CLI flags, render a styled
+ * header, or write to any stream. Enumeration is supplied by the caller
+ * (the CLI shell builds it from {@link migrationSpaceListEntriesFromAggregate}).
  */
 export interface RunMigrationListInputs {
-  /** Absolute path to the project's `migrations/` directory. */
-  readonly migrationsDir: string;
-  /**
-   * Optional contract-space id to narrow the result to a single space.
-   * Same validation rules as {@link isValidSpaceId}. When absent, every
-   * on-disk space contributes.
-   */
+  readonly spaces: readonly MigrationSpaceListEntry[];
   readonly spaceFilter?: string;
 }
 
@@ -93,59 +177,23 @@ function computeSummary(spaces: readonly MigrationSpaceListEntry[]): string {
 }
 
 /**
- * The unit-testable core of `migration list`. Given an absolute
- * `migrationsDir` and an optional `spaceFilter`, enumerates every
- * on-disk migration (via {@link enumerateMigrationSpaces}), narrows to
- * the requested space if any, and assembles a {@link MigrationListResult}
- * ready for the renderer or JSON serializer.
- *
- * The enumerator is the single source of truth for "what is a contract
- * space": existence, the `--space` candidate-suggestion list, and
- * scoping are all derived from one {@link enumerateMigrationSpaces}
- * traversal. This means the reserved-name exclusion the enumerator
- * applies (e.g. the per-space `refs/` subdirectory) is honoured here for
- * free — a `--space refs` request resolves to `SPACE_NOT_FOUND`, not a
- * synthesized empty-state.
- *
- * Distinct empty-state paths:
+ * Policy core of `migration list`: validates `--space`, narrows the
+ * pre-enumerated spaces, and assembles a {@link MigrationListResult}.
  *
  * - `migrations/` missing or contains no valid space directories →
- *   synthesizes `[{ spaceId: APP_SPACE_ID, migrations: [] }]` so the
- *   renderer's empty-state path can name a directory (spec § Empty-state +
- *   the `migrations/` missing edge case).
- * - `--space <id>` on an existing-but-empty space dir → the enumerator
- *   surfaces `{ spaceId, migrations: [] }`; `<id>` is in the set, so it
- *   scopes to that entry and renders the empty-state the same way.
- * - `--space <id>` on a non-existent (or reserved) space → structured
- *   `MIGRATION.SPACE_NOT_FOUND` error (NOT empty-state).
- *
- * Errors caught here:
- *
- * - {@link MigrationToolsError} from the enumerator → mapped through
- *   {@link mapMigrationToolsError} so callers see the catalogue code.
- * - Anything else (filesystem etc.) → wrapped via {@link errorUnexpected}.
+ *   caller passes `spaces: []`; this synthesizes `[{ spaceId: APP_SPACE_ID, migrations: [] }]`.
+ * - `--space <id>` on an existing-but-empty space → `{ spaceId, migrations: [] }` in the input.
+ * - `--space <id>` on a non-existent (or reserved) space → `SPACE_NOT_FOUND`.
  */
-export async function runMigrationList(
+export function runMigrationList(
   inputs: RunMigrationListInputs,
-): Promise<Result<MigrationListResult, CliStructuredError>> {
-  const { migrationsDir, spaceFilter } = inputs;
+): Result<MigrationListResult, CliStructuredError> {
+  const { spaces, spaceFilter } = inputs;
 
   if (spaceFilter !== undefined && !isValidSpaceId(spaceFilter)) {
     return notOk(errorInvalidSpaceId(spaceFilter));
   }
 
-  let spaces: readonly MigrationSpaceListEntry[];
-  try {
-    spaces = await enumerateMigrationSpaces({ projectMigrationsDir: migrationsDir });
-  } catch (error) {
-    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
-    return notOk(
-      errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to enumerate migrations: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
-  }
-
   if (spaceFilter !== undefined && !spaces.some((s) => s.spaceId === spaceFilter)) {
     return notOk(errorSpaceNotFound(spaceFilter, spaces.map((s) => s.spaceId).sort()));
   }
@@ -168,7 +216,7 @@ export async function runMigrationList(
  * stderr (interactive mode only), and delegates to {@link runMigrationList}.
  * Kept intentionally thin so the unit-testable surface lives in the core.
  */
-async function executeMigrationListCommand(
+export async function executeMigrationListCommand(
   options: MigrationListOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
@@ -193,8 +241,18 @@ async function executeMigrationListCommand(
     ui.stderr(header);
   }
 
-  return runMigrationList({
+  const loaded = await buildReadAggregate(config, { migrationsDir });
+  if (!loaded.ok) {
+    return notOk(loaded.failure);
+  }
+
+  const spaces = await migrationSpaceListEntriesFromAggregate(
+    loaded.value.aggregate,
     migrationsDir,
+  );
+
+  return runMigrationList({
+    spaces,
     ...ifDefined('spaceFilter', options.space),
   });
 }

package/src/commands/migration-log.ts

@@ -16,7 +16,6 @@ import {
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
   maskConnectionUrl,
   resolveMigrationPaths,
   setCommandDescriptions,
@@ -24,6 +23,7 @@ import {
   setCommandSeeAlso,
   targetSupportsMigrations,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
@@ -51,13 +51,13 @@ export interface MigrationLogResult {
   readonly summary: string;
 }
 
-async function executeMigrationLogCommand(
+export async function executeMigrationLogCommand(
   options: MigrationLogOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationLogResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+  const { configPath, appMigrationsRelative, migrationsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -94,18 +94,12 @@ async function executeMigrationLogCommand(
     ui.stderr(header);
   }
 
-  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
-  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
-  try {
-    ({ bundles, graph } = await loadMigrationPackages(appMigrationsDir));
-  } catch (error) {
-    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
-    return notOk(
-      errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
+  const loaded = await buildReadAggregate(config, { migrationsDir });
+  if (!loaded.ok) {
+    return loaded;
   }
+  const graph = loaded.value.aggregate.app.graph();
+  const bundles = loaded.value.aggregate.app.packages;
 
   const client = createControlClient({
     family: config.family,

package/src/commands/migration-status.ts

@@ -26,7 +26,6 @@ import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/packag
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry, Refs } from '@prisma-next/migration-tools/refs';
 import { readRefs } from '@prisma-next/migration-tools/refs';
-import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { cyan, dim, magenta, yellow } from 'colorette';
@@ -54,6 +53,8 @@ import {
   toStructuralEdge,
 } from '../utils/command-helpers';
 import {
+  appContractStandInFromIdentity,
+  loadContractRawSafely,
   refuseContractSpaceIntegrity,
   refusePackageCorruptionOnAggregate,
 } from '../utils/contract-space-aggregate-loader';
@@ -531,33 +532,6 @@ export async function loadAggregateStatusSpaces(args: {
  * problem via a status diagnostic, no need to double-surface.
  */
 
-function appContractShellForAggregateLoad(args: {
-  readonly contractHash: string;
-  readonly targetId: string;
-  readonly targetFamily: string;
-}): Contract {
-  return blindCast<Contract, 'status aggregate load without contract.json'>({
-    storage: { storageHash: args.contractHash },
-    schemaVersion: '0.0.0',
-    target: args.targetId,
-    targetFamily: args.targetFamily,
-    models: {},
-    profileHash: EMPTY_CONTRACT_HASH,
-  });
-}
-
-async function loadContractRawSafely(config: {
-  contract?: { output?: string };
-}): Promise<unknown | null> {
-  try {
-    const path = (await import('../utils/command-helpers')).resolveContractPath(config);
-    const raw = await (await import('node:fs/promises')).readFile(path, 'utf-8');
-    return JSON.parse(raw) as unknown;
-  } catch {
-    return null;
-  }
-}
-
 async function validateOnlineMarkerRead(
   config: Awaited<ReturnType<typeof loadConfig>>,
   dbConnection: unknown,
@@ -637,12 +611,12 @@ async function executeMigrationStatusCommand(
   const stack = createControlStack(config);
   const familyInstance = config.family.create(stack);
   const deserializeContract = (json: unknown): Contract => familyInstance.deserializeContract(json);
-  const appContractShell = appContractShellForAggregateLoad({
+  const appContractStandIn = appContractStandInFromIdentity({
     contractHash,
     targetId: config.target.id,
     targetFamily: config.target.familyId,
   });
-  let appContractForLoad: Contract = appContractShell;
+  let appContractForLoad: Contract = appContractStandIn;
   if (contractRawForAggregate !== null) {
     try {
       appContractForLoad = deserializeContract(contractRawForAggregate);

package/src/commands/ref.ts

@@ -28,10 +28,10 @@ import {
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
   resolveMigrationPaths,
   setCommandDescriptions,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatCommandHelp } from '../utils/formatters/help';
 import { parseGlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { readContractIR } from '../utils/ref-advancement';
@@ -81,9 +81,14 @@ export async function executeRefSetCommand(
 
   try {
     const config = await loadConfig(options.config);
-    const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
-    const { graph, bundles } = await loadMigrationPackages(appMigrationsDir);
-    const refs = await readRefs(refsDir);
+    const { migrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+    const loaded = await buildReadAggregate(config, { migrationsDir });
+    if (!loaded.ok) {
+      return notOk(loaded.failure);
+    }
+    const graph = loaded.value.aggregate.app.graph();
+    const bundles = loaded.value.aggregate.app.packages;
+    const refs = loaded.value.aggregate.app.refs;
 
     let resolvedHash: string;
     if (validateRefValue(contractInput)) {

package/src/control-api/types.ts

@@ -577,9 +577,9 @@ export interface MigrationApplyOptions {
 
 /**
  * A single on-disk migration package surfaced to the operation. The
- * SQL family already produces this shape via `loadMigrationPackages`;
- * the operation hands it through to the framework-neutral aggregate
- * loader's `appMigrationPackages` slot.
+ * SQL family surfaces this shape from the tolerant contract-space
+ * aggregate's app packages; the operation hands it through to the
+ * framework-neutral aggregate loader's `appMigrationPackages` slot.
  *
  * (Originally named `MigrationApplyStep` for the legacy single-space
  * apply path; the name is kept for compatibility with existing CLI