@prisma-next/cli 0.5.0-dev.8 → 0.5.0-dev.80

package/src/utils/cli-errors.ts

@@ -1,9 +1,11 @@
 /**
  * Re-export all domain error factories from @prisma-next/errors for convenience.
- * CLI-specific errors (e.g., Commander.js argument validation) can be added here if needed.
+ * CLI-specific errors (e.g., Commander argument validation in the main CLI, or
+ * clipanion parse errors in the migration-file CLI) can be added here if needed.
  */
 export type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/errors/control';
-export {
+
+import {
   CliStructuredError,
   errorConfigFileNotFound,
   errorConfigValidation,
@@ -15,11 +17,33 @@ export {
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
   errorMigrationCliInvalidConfigArg,
+  errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
   errorUnexpected,
 } from '@prisma-next/errors/control';
+import { errorRuntime } from '@prisma-next/errors/execution';
+import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+
+export {
+  CliStructuredError,
+  errorConfigFileNotFound,
+  errorConfigValidation,
+  errorContractConfigMissing,
+  errorContractMissingExtensionPacks,
+  errorContractValidationFailed,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorFamilyReadMarkerSqlRequired,
+  errorFileNotFound,
+  errorMigrationCliInvalidConfigArg,
+  errorMigrationCliUnknownFlag,
+  errorMigrationPlanningFailed,
+  errorQueryRunnerFactoryRequired,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+};
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
   errorDestructiveChanges,
@@ -38,3 +62,26 @@ export {
   errorUnfilledPlaceholder,
   placeholder,
 } from '@prisma-next/errors/migration';
+
+/**
+ * Maps a `MigrationToolsError` raised by the migration-tools loader/graph
+ * surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,
+ * `resolveRef`, `reconstructGraph`, ...) into a CLI `errorRuntime` envelope.
+ *
+ * The full `error.details` payload is forwarded into `meta` so machine
+ * consumers (`--json`) see structural fields like `dir`, `storedHash`,
+ * `computedHash` (for `MIGRATION.HASH_MISMATCH`) alongside the stable
+ * `code`. The user-visible `summary`/`why`/`fix` text is unchanged.
+ *
+ * Callers are expected to gate on `MigrationToolsError.is(error)` first
+ * (mirroring the original inline pattern); non-`MigrationToolsError`
+ * values are caller-classified (rethrow, wrap with command-specific
+ * `errorUnexpected`, etc.).
+ */
+export function mapMigrationToolsError(error: MigrationToolsError): CliStructuredError {
+  return errorRuntime(error.message, {
+    why: error.why,
+    fix: error.fix,
+    meta: { code: error.code, ...(error.details ?? {}) },
+  });
+}

package/src/utils/combine-schema-results.ts

@@ -0,0 +1,84 @@
+import type { VerifyDatabaseSchemaResult } from '@prisma-next/framework-components/control';
+
+/**
+ * Collapse the aggregate verifier's per-space schema results into a
+ * single {@link VerifyDatabaseSchemaResult} for the existing CLI
+ * display surface. Concatenates issues across members; sums counts;
+ * uses the app member's result as the structural envelope (storage
+ * hash, target).
+ *
+ * **Summary policy.** Preserve the per-family phrasing whenever the
+ * combined `ok` flag agrees with the app member's `ok` flag — this is
+ * the common case (single-family deployments, single-app deployments)
+ * and the family's "satisfies / does not satisfy contract" phrasing
+ * stays user-visible. When the app passes but an extension fails (or
+ * vice versa) the app's summary contradicts the envelope, so fall back
+ * to the first failing member's summary. This keeps family phrasing
+ * intact and the envelope internally consistent (`ok: false` ↔ failure
+ * summary).
+ */
+export function combineSchemaResults(
+  perSpace: ReadonlyMap<string, VerifyDatabaseSchemaResult>,
+  appSpaceId: string,
+  strict: boolean,
+): VerifyDatabaseSchemaResult {
+  const appResult = perSpace.get(appSpaceId) ?? perSpace.values().next().value;
+  if (appResult === undefined) {
+    throw new Error('Aggregate verifier returned no schema results — this is a wiring bug.');
+  }
+
+  let okAll = true;
+  let firstFailure: VerifyDatabaseSchemaResult | undefined;
+  let issues: VerifyDatabaseSchemaResult['schema']['issues'] = [];
+  const counts = { pass: 0, warn: 0, fail: 0, totalNodes: 0 };
+  const childRoots: Array<VerifyDatabaseSchemaResult['schema']['root']> = [];
+  for (const [, result] of perSpace) {
+    if (!result.ok) {
+      okAll = false;
+      if (firstFailure === undefined) firstFailure = result;
+    }
+    issues = [...issues, ...result.schema.issues];
+    counts.pass += result.schema.counts.pass;
+    counts.warn += result.schema.counts.warn;
+    counts.fail += result.schema.counts.fail;
+    counts.totalNodes += result.schema.counts.totalNodes;
+    childRoots.push(result.schema.root);
+  }
+
+  // When `okAll !== appResult.ok`, exactly one shape is reachable: app passes
+  // (`appResult.ok === true`) and at least one other member failed
+  // (`okAll === false`). In that shape the failure was assigned to
+  // `firstFailure` during iteration, so non-null assertion is safe. The mirror
+  // shape (app fails while every member passes) is impossible because
+  // `appResult` either *is* a member of `perSpace` or is the first iterator
+  // value; either way its `ok` flag participates in `okAll`.
+  const summary =
+    okAll === appResult.ok
+      ? appResult.summary
+      : (firstFailure as VerifyDatabaseSchemaResult).summary;
+
+  return {
+    ok: okAll,
+    ...(okAll ? {} : { code: appResult.code ?? 'PN-RUN-3010' }),
+    summary,
+    contract: appResult.contract,
+    target: appResult.target,
+    schema: {
+      issues,
+      root: {
+        status: okAll ? 'pass' : 'fail',
+        kind: 'aggregate',
+        name: 'aggregate',
+        contractPath: '',
+        code: 'AGGREGATE',
+        message: okAll ? 'Aggregate schema matches' : 'Aggregate schema mismatch',
+        expected: undefined,
+        actual: undefined,
+        children: childRoots,
+      },
+      counts,
+    },
+    meta: { strict },
+    timings: { total: 0 },
+  };
+}

package/src/utils/command-helpers.ts

@@ -1,10 +1,13 @@
 import { readFile } from 'node:fs/promises';
 import type { ControlTargetDescriptor } from '@prisma-next/framework-components/control';
 import { hasMigrations } from '@prisma-next/framework-components/control';
-import type { PathDecision } from '@prisma-next/migration-tools/dag';
-import { reconstructGraph } from '@prisma-next/migration-tools/dag';
+import type { NoInvariantPathStructuralEdge } from '@prisma-next/migration-tools/errors';
+import type { MigrationEdge, MigrationGraph } from '@prisma-next/migration-tools/graph';
 import { readMigrationsDir } from '@prisma-next/migration-tools/io';
-import type { MigrationBundle, MigrationGraph } from '@prisma-next/migration-tools/types';
+import type { PathDecision } from '@prisma-next/migration-tools/migration-graph';
+import { reconstructGraph } from '@prisma-next/migration-tools/migration-graph';
+import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { APP_SPACE_ID, spaceMigrationDirectory } from '@prisma-next/migration-tools/spaces';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
 import { relative, resolve } from 'pathe';
@@ -77,6 +80,16 @@ export function resolveContractPath(config: { contract?: { output?: string } }):
 /**
  * Resolves the migrations directory and config path from CLI options.
  * Shared by migration-apply, migration-plan, and migration-status.
+ *
+ * - `migrationsDir` is the project's top-level `migrations/` directory
+ *   (the root that the aggregate loader walks for every contract space).
+ * - `appMigrationsDir` is the app subspace directory under it
+ *   (`<migrationsDir>/<APP_SPACE_ID>/`). Every per-app reader / writer
+ *   (`migration new`, `migration plan`, `migration apply`,
+ *   `migration status`, `migration show`, `migration ref`) operates on
+ *   this directory. Extensions own their own `migrations/<spaceId>/`.
+ * - `refsDir` is the app's refs directory (`<appMigrationsDir>/refs/`).
+ *   The framework does not maintain refs at the migrations root.
  */
 export function resolveMigrationPaths(
   configOption: string | undefined,
@@ -85,6 +98,8 @@ export function resolveMigrationPaths(
   configPath: string;
   migrationsDir: string;
   migrationsRelative: string;
+  appMigrationsDir: string;
+  appMigrationsRelative: string;
   refsDir: string;
 } {
   const configPath = configOption
@@ -95,8 +110,17 @@ export function resolveMigrationPaths(
     config.migrations?.dir ?? 'migrations',
   );
   const migrationsRelative = relative(process.cwd(), migrationsDir);
-  const refsDir = resolve(migrationsDir, 'refs');
-  return { configPath, migrationsDir, migrationsRelative, refsDir };
+  const appMigrationsDir = spaceMigrationDirectory(migrationsDir, APP_SPACE_ID);
+  const appMigrationsRelative = relative(process.cwd(), appMigrationsDir);
+  const refsDir = resolve(appMigrationsDir, 'refs');
+  return {
+    configPath,
+    migrationsDir,
+    migrationsRelative,
+    appMigrationsDir,
+    appMigrationsRelative,
+    refsDir,
+  };
 }
 
 /**
@@ -109,14 +133,45 @@ export interface PathDecisionResult {
   readonly alternativeCount: number;
   readonly tieBreakReasons: readonly string[];
   readonly refName?: string;
+  readonly requiredInvariants: readonly string[];
+  readonly satisfiedInvariants: readonly string[];
   readonly selectedPath: readonly {
     readonly dirName: string;
-    readonly migrationId: string;
+    readonly migrationHash: string;
     readonly from: string;
     readonly to: string;
+    readonly invariants: readonly string[];
   }[];
 }
 
+export function collectDeclaredInvariants(graph: MigrationGraph): ReadonlySet<string> {
+  const declared = new Set<string>();
+  for (const edges of graph.forwardChain.values()) {
+    for (const edge of edges) {
+      for (const inv of edge.invariants) {
+        declared.add(inv);
+      }
+    }
+  }
+  return declared;
+}
+
+/**
+ * Maps a `MigrationEdge` to the structural-edge shape used in the
+ * `MIGRATION.NO_INVARIANT_PATH` error envelope. Shared between
+ * `migration apply` and `migration status` so both commands surface
+ * the same JSON wire shape when an invariant-aware route is unsatisfiable.
+ */
+export function toStructuralEdge(edge: MigrationEdge): NoInvariantPathStructuralEdge {
+  return {
+    dirName: edge.dirName,
+    migrationHash: edge.migrationHash,
+    from: edge.from,
+    to: edge.to,
+    invariants: edge.invariants,
+  };
+}
+
 /**
  * Maps a PathDecision to the slim CLI output representation.
  */
@@ -126,12 +181,15 @@ export function toPathDecisionResult(decision: PathDecision): PathDecisionResult
     toHash: decision.toHash,
     alternativeCount: decision.alternativeCount,
     tieBreakReasons: decision.tieBreakReasons,
+    requiredInvariants: decision.requiredInvariants ?? [],
+    satisfiedInvariants: decision.satisfiedInvariants ?? [],
     ...ifDefined('refName', decision.refName),
     selectedPath: decision.selectedPath.map((entry) => ({
       dirName: entry.dirName,
-      migrationId: entry.migrationId,
+      migrationHash: entry.migrationHash,
       from: entry.from,
       to: entry.to,
+      invariants: entry.invariants,
     })),
   };
 }
@@ -146,13 +204,13 @@ export function getTargetMigrations(target: ControlTargetDescriptor<string, stri
 
 /**
  * Reads the migrations directory and builds the migration graph from all
- * bundles. Throws on I/O or graph errors — callers handle error mapping.
+ * packages. Throws on I/O or graph errors — callers handle error mapping.
  *
- * Every on-disk bundle is content-addressed (`migrationId` is always a
+ * Every on-disk package is content-addressed (`migrationHash` is always a
  * string); there is no draft state to filter out.
  */
-export async function loadMigrationBundles(migrationsDir: string): Promise<{
-  bundles: readonly MigrationBundle[];
+export async function loadMigrationPackages(migrationsDir: string): Promise<{
+  bundles: readonly OnDiskMigrationPackage[];
   graph: MigrationGraph;
 }> {
   const bundles = await readMigrationsDir(migrationsDir);
@@ -160,20 +218,6 @@ export async function loadMigrationBundles(migrationsDir: string): Promise<{
   return { bundles, graph };
 }
 
-export interface MigrationBundleSet {
-  readonly bundles: readonly MigrationBundle[];
-  readonly graph: MigrationGraph;
-}
-
-/**
- * Alias of `loadMigrationBundles` retained for naming-clarity in commands
- * that previously needed both attested and draft splits. With the
- * collapse of the draft state, both helpers do the same thing.
- */
-export async function loadAllBundles(migrationsDir: string): Promise<MigrationBundleSet> {
-  return loadMigrationBundles(migrationsDir);
-}
-
 /**
  * The subset of the emitted contract.json that the framework layer can
  * safely type. The emitter adds these fields on top of the family-specific

package/src/utils/contract-space-aggregate-loader.ts

@@ -0,0 +1,204 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { ControlExtensionDescriptor } from '@prisma-next/framework-components/control';
+import type {
+  ContractSpaceAggregate,
+  LoadAggregateError,
+  LoadAggregateInput,
+  LoadAggregateOutput,
+} from '@prisma-next/migration-tools/aggregate';
+import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
+import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { CliStructuredError } from './cli-errors';
+import { toDeclaredExtensions, toExtensionInputs } from './extension-pack-inputs';
+
+/**
+ * Render a {@link LoadAggregateError} into a CLI structured-error
+ * envelope. Preserves error codes `5001` (layout) and `5002` (marker /
+ * drift / disjointness / etc.) so existing integration tests and
+ * downstream tooling continue to assert on the same `meta.violations[]`
+ * shape they did under the old precheck/marker-check helpers.
+ */
+export function mapLoadAggregateError(error: LoadAggregateError): CliStructuredError {
+  if (error.kind === 'layoutViolation') {
+    const lines = error.violations.map((v) => `- [${v.kind}] ${v.spaceId}`);
+    const summary =
+      error.violations.length === 1
+        ? 'Contract-space layout violation detected'
+        : `Contract-space layout violations detected (${error.violations.length})`;
+    return new CliStructuredError('5001', summary, {
+      domain: 'MIG',
+      why: `The on-disk \`migrations/\` directory and your \`extensionPacks\` declaration are not in agreement.\n${lines.join('\n')}`,
+      fix: 'Run `prisma-next migrate` to materialise on-disk artefacts for declared extensions, or remove the orphan directory.',
+      docsUrl: 'https://pris.ly/contract-spaces',
+      meta: {
+        violations: error.violations.map((v) => ({
+          kind: v.kind,
+          spaceId: v.spaceId,
+        })),
+      },
+    });
+  }
+  if (error.kind === 'driftViolation') {
+    return new CliStructuredError('5002', `Contract-space drift detected for "${error.spaceId}"`, {
+      domain: 'MIG',
+      why: `The on-disk contract for space "${error.spaceId}" (hash ${error.priorHeadHash}) does not match the live extension descriptor (hash ${error.liveHash}).`,
+      fix: 'Run `prisma-next migrate` to refresh the on-disk artefacts to match the live descriptor.',
+      docsUrl: 'https://pris.ly/contract-spaces',
+      meta: {
+        violations: [
+          {
+            kind: 'drift',
+            spaceId: error.spaceId,
+            priorHeadHash: error.priorHeadHash,
+            liveHash: error.liveHash,
+          },
+        ],
+      },
+    });
+  }
+  if (error.kind === 'disjointnessViolation') {
+    return new CliStructuredError(
+      '5002',
+      `Contract-space disjointness violation: storage element "${error.element}" claimed by multiple spaces`,
+      {
+        domain: 'MIG',
+        why: `Spaces ${error.claimedBy.map((s) => `"${s}"`).join(', ')} all claim the storage element "${error.element}". Each storage element must be owned by exactly one contract space.`,
+        fix: 'Update the conflicting contracts so each storage element is claimed by exactly one space.',
+        docsUrl: 'https://pris.ly/contract-spaces',
+        meta: {
+          violations: [
+            {
+              kind: 'disjointness',
+              spaceId: error.claimedBy.join(','),
+              element: error.element,
+              claimedBy: error.claimedBy,
+            },
+          ],
+        },
+      },
+    );
+  }
+  if (error.kind === 'integrityFailure') {
+    return new CliStructuredError(
+      '5002',
+      `Contract-space integrity failure for "${error.spaceId}"`,
+      {
+        domain: 'MIG',
+        why: error.detail,
+        fix: 'Run `prisma-next migrate` to refresh on-disk artefacts, or restore the on-disk `migrations/` directory from version control.',
+        docsUrl: 'https://pris.ly/contract-spaces',
+        meta: {
+          violations: [{ kind: 'integrity', spaceId: error.spaceId, detail: error.detail }],
+        },
+      },
+    );
+  }
+  if (error.kind === 'validationFailure') {
+    return new CliStructuredError(
+      '5002',
+      `Contract-space contract validation failed for "${error.spaceId}"`,
+      {
+        domain: 'MIG',
+        why: error.detail,
+        fix: 'Run `prisma-next migrate` to refresh on-disk artefacts, or fix the extension descriptor producing the invalid contract.',
+        meta: {
+          violations: [{ kind: 'validation', spaceId: error.spaceId, detail: error.detail }],
+        },
+      },
+    );
+  }
+  // targetMismatch
+  return new CliStructuredError('5002', `Contract-space target mismatch for "${error.spaceId}"`, {
+    domain: 'MIG',
+    why: `Space "${error.spaceId}" targets "${error.actual}" but the project's adapter targets "${error.expected}".`,
+    fix: 'Update the extension descriptor to target the configured database, or change the project adapter.',
+    meta: {
+      violations: [
+        {
+          kind: 'targetMismatch',
+          spaceId: error.spaceId,
+          expected: error.expected,
+          actual: error.actual,
+        },
+      ],
+    },
+  });
+}
+
+/**
+ * Inputs needed to compose the aggregate loader at the CLI surface.
+ *
+ * Keeps the loader framework-neutral (no `Config` import) by accepting
+ * already-resolved structural inputs: validated app contract, target
+ * id, migrations root directory, and the set of extension descriptors.
+ */
+export interface BuildAggregateInputs<TFamilyId extends string, TTargetId extends string> {
+  readonly targetId: TTargetId;
+  readonly migrationsDir: string;
+  readonly appContract: Contract;
+  readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly validateContract: (contractJson: unknown) => Contract;
+  /**
+   * App-space migration packages to hydrate the app member's
+   * migration graph with. Defaults to `[]` (matches the `db init` /
+   * `db update` daily-driver behaviour, where the app's authored
+   * `migrations/` graph is not walked — the planner uses the synth
+   * strategy for the app member instead).
+   *
+   * `migration apply` callers thread the user's authored app-space
+   * packages (loaded via `loadMigrationPackages(appMigrationsDir)`)
+   * through here so the graph-walk strategy can plot a path through
+   * them — the prod-time replay path explicitly forbids synth.
+   */
+  readonly appMigrationPackages?: ReadonlyArray<OnDiskMigrationPackage>;
+}
+
+/**
+ * Run the aggregate loader at the CLI surface, mapping any
+ * {@link LoadAggregateError} into a {@link CliStructuredError} envelope.
+ *
+ * App-side migration packages flow through `inputs.appMigrationPackages`
+ * (defaulting to `[]`). `db init` / `db update` leave it empty: the
+ * planner's `synth` strategy is used for the app member (driven by
+ * `callerPolicy.ignoreGraphFor`), so the app's authored `migrations/`
+ * graph does not need to be walked. `migration apply` threads the
+ * already-loaded app-space packages through so the graph-walk strategy
+ * can plot a path through them — replay forbids synth.
+ *
+ * @see specs/contract-space-aggregate-spec.md § Loader.
+ */
+export async function buildContractSpaceAggregate<
+  TFamilyId extends string,
+  TTargetId extends string,
+>(
+  inputs: BuildAggregateInputs<TFamilyId, TTargetId>,
+): Promise<Result<ContractSpaceAggregate, CliStructuredError>> {
+  const { entries, hashByContractJson } = toDeclaredExtensions(
+    toExtensionInputs(inputs.extensionPacks),
+  );
+
+  const loadInput: LoadAggregateInput = {
+    targetId: inputs.targetId,
+    migrationsDir: inputs.migrationsDir,
+    appContract: inputs.appContract,
+    declaredExtensions: entries,
+    validateContract: inputs.validateContract,
+    hashContract: (contractJson: unknown) => {
+      const precomputed = hashByContractJson.get(contractJson);
+      if (precomputed === undefined) {
+        throw new Error(
+          'CLI aggregate loader: encountered an extension contract without a pre-computed descriptor hash. This is a wiring bug.',
+        );
+      }
+      return precomputed;
+    },
+    appMigrationPackages: inputs.appMigrationPackages ?? [],
+  };
+
+  const result: LoadAggregateOutput = await loadContractSpaceAggregate(loadInput);
+  if (!result.ok) {
+    return notOk(mapLoadAggregateError(result.failure));
+  }
+  return ok(result.value.aggregate);
+}

package/src/utils/contract-space-extension-migrations-pass.ts

@@ -0,0 +1,120 @@
+import { materialiseExtensionMigrationPackageIfMissing } from '@prisma-next/migration-tools/io';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
+import type { MigrationOps } from '@prisma-next/migration-tools/package';
+import {
+  planAllSpaces,
+  type SpacePlanOutput,
+  spaceMigrationDirectory,
+} from '@prisma-next/migration-tools/spaces';
+
+/**
+ * In-memory authored migration package shipped by an extension descriptor.
+ * Mirrors `MigrationPackage` from `@prisma-next/migration-tools/io`
+ * (the on-disk shape minus `dirPath`); redeclared structurally here so
+ * the CLI helper does not couple to the SQL family's `ExtensionMigrationPackage`
+ * type — any family that ships pre-built migration packages can pass them
+ * through unchanged.
+ */
+export interface DescriptorMigrationPackage {
+  readonly dirName: string;
+  readonly metadata: MigrationMetadata;
+  readonly ops: MigrationOps;
+}
+
+/**
+ * Minimal descriptor view consumed by the migration-materialisation pass.
+ * Mirrors {@link import('./contract-space-migrate-pass').MigrateExtensionInput}
+ * but adds the `migrations` field — the canonical set of pre-built
+ * migration packages the extension ships.
+ */
+export interface ExtensionMigrationsExtensionInput {
+  readonly id: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+    readonly migrations: readonly DescriptorMigrationPackage[];
+    readonly headRef: { readonly hash: string; readonly invariants: readonly string[] };
+  };
+}
+
+export interface ContractSpaceExtensionMigrationsPassInputs {
+  readonly migrationsDir: string;
+  readonly extensionPacks: ReadonlyArray<ExtensionMigrationsExtensionInput>;
+}
+
+export interface ContractSpaceExtensionMigrationsPassResult {
+  readonly emitted: readonly { readonly spaceId: string; readonly dirName: string }[];
+  readonly skipped: readonly { readonly spaceId: string; readonly dirName: string }[];
+}
+
+/**
+ * Materialise an extension's pre-built migration packages onto disk
+ * under `migrations/<spaceId>/<dirName>/` for every package that does
+ * not yet exist there.
+ *
+ * Helper-location pattern — the per-space "planner" for extension
+ * spaces is a no-op that just returns the descriptor's `migrations`
+ * verbatim; the value `planAllSpaces` brings to this consumer site is
+ * **deterministic ordering** (alphabetical by spaceId) and
+ * **duplicate-spaceId detection**. The actual write is performed via
+ * `materialiseMigrationPackage` per package.
+ *
+ * Idempotent: an existing `migrations/<spaceId>/<dirName>/` is left
+ * untouched and reported in `result.skipped` — the helper never
+ * overwrites authored migration content, ensuring re-running
+ * `migrate` does not corrupt or churn extension migration packages.
+ *
+ * Per-space artefacts (`contract.json`, `contract.d.ts`,
+ * `refs/head.json`) are emitted by
+ * {@link import('./contract-space-migrate-pass').runContractSpaceMigratePass}
+ * separately — they cover the head-pointer side of the ledger. This
+ * helper covers the migration-graph side.
+ */
+export async function runContractSpaceExtensionMigrationsPass(
+  inputs: ContractSpaceExtensionMigrationsPassInputs,
+): Promise<ContractSpaceExtensionMigrationsPassResult> {
+  const planInputs = inputs.extensionPacks
+    .filter(
+      (
+        pack,
+      ): pack is ExtensionMigrationsExtensionInput & {
+        contractSpace: NonNullable<ExtensionMigrationsExtensionInput['contractSpace']>;
+      } => pack.contractSpace !== undefined,
+    )
+    .map((pack) => ({
+      spaceId: pack.id,
+      priorContract: null,
+      newContract: pack.contractSpace.contractJson,
+      __migrations: pack.contractSpace.migrations,
+    }));
+
+  // Threading the descriptor's pre-built migrations into the
+  // `planAllSpaces` callback by piggybacking on the input shape.
+  // The framework helper is generic over the per-space planner output;
+  // here the "planner" is a no-op that returns the descriptor's
+  // `migrations` array. The benefit of routing through `planAllSpaces`
+  // is duplicate-spaceId detection + alphabetical ordering — failures
+  // there throw `MIGRATION.DUPLICATE_SPACE_ID` before any write.
+  const planned: readonly SpacePlanOutput<DescriptorMigrationPackage>[] = planAllSpaces(
+    planInputs,
+    (input) =>
+      (input as typeof input & { readonly __migrations: readonly DescriptorMigrationPackage[] })
+        .__migrations,
+  );
+
+  const emitted: { spaceId: string; dirName: string }[] = [];
+  const skipped: { spaceId: string; dirName: string }[] = [];
+
+  for (const space of planned) {
+    const spaceDir = spaceMigrationDirectory(inputs.migrationsDir, space.spaceId);
+    for (const pkg of space.migrationPackages) {
+      const { written } = await materialiseExtensionMigrationPackageIfMissing(spaceDir, pkg);
+      if (written) {
+        emitted.push({ spaceId: space.spaceId, dirName: pkg.dirName });
+      } else {
+        skipped.push({ spaceId: space.spaceId, dirName: pkg.dirName });
+      }
+    }
+  }
+
+  return { emitted, skipped };
+}