@prisma-next/cli 0.5.0-dev.74 → 0.5.0-dev.76

package/src/control-api/types.ts

@@ -18,6 +18,7 @@ import type {
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
 import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
+import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import type { Result } from '@prisma-next/utils/result';
 import type { ExecuteDbVerifyResult } from './operations/db-verify';
 
@@ -308,6 +309,42 @@ export interface EmitOptions {
 // Result Types
 // ============================================================================
 
+/**
+ * Per-space breakdown of an aggregate plan / apply.
+ *
+ * Surfaces the canonical schedule shape — extensions alphabetically,
+ * then app — together with the operations attributed to each space and,
+ * when the run was applied, the resulting per-space marker hash.
+ *
+ * M6 sub-spec § Output shape contract — every space involved in a run
+ * is observable in the success summary, including its post-apply
+ * marker, so the per-space invariant is visible to the user (closing
+ * F4 / F7 from `e2e-verification.md`).
+ */
+export interface AggregatePerSpaceExecutionEntry {
+  readonly spaceId: string;
+  /** `'app'` for the application's contract space; `'extension'` for any extension space. */
+  readonly kind: 'app' | 'extension';
+  /**
+   * Operations attributed to this space (display ops). In `mode: 'plan'`
+   * this is the planned set; in `mode: 'apply'` it is the same set
+   * (every op was executed in order, the runner does not skip).
+   */
+  readonly operations: ReadonlyArray<{
+    readonly id: string;
+    readonly label: string;
+    readonly operationClass: string;
+  }>;
+  /**
+   * Post-apply marker hash for this space. Present only when the run
+   * was applied (i.e. `mode: 'apply'` and the runner returned ok).
+   * Equals the per-space plan's `destination.storageHash`.
+   */
+  readonly marker?: {
+    readonly storageHash: string;
+  };
+}
+
 /**
  * Successful dbInit result.
  */
@@ -340,6 +377,14 @@ export interface DbInitSuccess {
     readonly storageHash: string;
     readonly profileHash?: string;
   };
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). Present whenever the aggregate flow
+   * produced one — both `mode: 'plan'` and `mode: 'apply'`.
+   *
+   * See {@link AggregatePerSpaceExecutionEntry}.
+   */
+  readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
   readonly summary: string;
 }
 
@@ -405,6 +450,11 @@ export interface DbUpdateSuccess {
     readonly storageHash: string;
     readonly profileHash?: string;
   };
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). See {@link AggregatePerSpaceExecutionEntry}.
+   */
+  readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
   readonly summary: string;
 }
 
@@ -477,44 +527,48 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
 // ============================================================================
 
 /**
- * A pre-planned migration step ready for execution.
- * Contains the manifest metadata and the serialized operations from ops.json.
+ * Options for the aggregate-walking `migrationApply` operation.
+ *
+ * The control-api operation is responsible for: loading the
+ * contract-space aggregate, reading per-space marker rows from the
+ * live database, plotting per-space paths via `graphWalkStrategy`
+ * (replay-only — no synth, no introspection), and dispatching
+ * through the shared `applyAggregate` primitive. The CLI command
+ * just resolves the descriptor surface (config, refs, contract
+ * envelope, app-space migration packages) and hands the inputs in.
+ *
+ * Sub-spec § `migration apply` semantics + § Required changes 1.
  */
-export interface MigrationApplyStep {
-  readonly dirName: string;
-  readonly from: string | null;
-  readonly to: string;
-  readonly toContract: Contract;
-  readonly operations: readonly MigrationPlanOperation[];
+export interface MigrationApplyOptions {
+  /** Already-validated app contract (the canonical "where we are heading" hash). */
+  readonly contract: unknown;
+  /** Migrations root directory (`migrations/` under the project). */
+  readonly migrationsDir: string;
   /**
-   * Sorted, deduplicated invariant ids from `migration.json.providedInvariants`.
-   * Verified at load time by `readMigrationPackage` (manifest copy must equal
-   * the value derived from `ops.json`). The control-api passes this through
-   * to the runner via `MigrationPlan.providedInvariants` so target runners
-   * read the canonical set instead of re-deriving from `operations`.
+   * Already-loaded app-space migration packages. The CLI loads these
+   * via `loadMigrationPackages(appMigrationsDir)` before invoking
+   * `migrationApply`.
    */
-  readonly providedInvariants: readonly string[];
-}
-
-/**
- * Options for the migrationApply operation.
- */
-export interface MigrationApplyOptions {
+  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
   /**
-   * Hash of the database state this apply path starts from.
-   * This is resolved by the caller (typically the CLI orchestration layer).
+   * Optional app-space ref override. When provided, the app member's
+   * graph-walk targets this hash instead of `contract.storage.storageHash`.
+   * Extension members always walk to their own `headRef.hash`.
    */
-  readonly originHash: string;
+  readonly refHash?: string;
   /**
-   * Hash of the target contract this apply path must reach.
-   * This is resolved by the caller (typically the CLI orchestration layer).
+   * Required invariants on the user-supplied app-space ref. Threaded
+   * into the graph-walk's `required` calculation so the planner picks
+   * an invariant-bearing path. Ignored when `refHash` is absent.
    */
-  readonly destinationHash: string;
+  readonly refInvariants?: readonly string[];
   /**
-   * Ordered list of migrations to execute from originHash to destinationHash.
-   * The execution layer does not choose defaults; it only executes this explicit path.
+   * Resolved name of the user-supplied app-space ref (the literal the
+   * user passed to `--ref`). Decorates `pathDecision.refName` and any
+   * `MIGRATION.NO_INVARIANT_PATH` envelope raised during graph-walk.
+   * Ignored when `refHash` is absent.
    */
-  readonly pendingMigrations: readonly MigrationApplyStep[];
+  readonly refName?: string;
   /**
    * Database connection. If provided, migrationApply will connect before executing.
    * If omitted, the client must already be connected.
@@ -525,23 +579,102 @@ export interface MigrationApplyOptions {
 }
 
 /**
- * Record of a successfully applied migration.
+ * 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.
+ *
+ * (Originally named `MigrationApplyStep` for the legacy single-space
+ * apply path; the name is kept for compatibility with existing CLI
+ * callers and tests.)
  */
-export interface MigrationApplyAppliedEntry {
+export interface MigrationApplyStep {
   readonly dirName: string;
   readonly from: string | null;
   readonly to: string;
+  readonly toContract: Contract;
+  readonly operations: readonly MigrationPlanOperation[];
+  /**
+   * Sorted, deduplicated invariant ids from `migration.json.providedInvariants`.
+   * Verified at load time by `readMigrationPackage` (manifest copy must equal
+   * the value derived from `ops.json`).
+   */
+  readonly providedInvariants: readonly string[];
+}
+
+/**
+ * Record of a successfully applied per-space migration. One entry per
+ * contract space that had pending migrations — empty `applied` means
+ * every space was already at its head.
+ */
+/**
+ * One entry per authored migration package applied. Preserves the
+ * single-space `migrationsApplied` count semantics (each entry is
+ * one migration directory) so `applied.length === migrationsApplied`.
+ *
+ * Per-space aggregate detail (markers, ops grouped by space) lives
+ * on `perSpace[]`; this list is the per-edge view.
+ */
+export interface MigrationApplyAppliedEntry {
+  readonly spaceId: string;
+  readonly dirName: string;
+  readonly migrationHash: string;
+  readonly from: string;
+  readonly to: string;
   readonly operationsExecuted: number;
 }
 
 /**
- * Successful migrationApply result.
+ * Successful migrationApply result. Carries both the legacy
+ * single-space fields (`markerHash` is the **app member's** post-apply
+ * marker, surfaced for back-compat with single-space callers) and the
+ * per-space breakdown (`perSpace` — markers / operations / canonical
+ * order, per M6 sub-spec § Output shape).
  */
+/**
+ * Path-decision summary for the **app member** post-apply. Surfaced
+ * for back-compat with single-space callers (and the cli-journeys
+ * suite, which inspects `requiredInvariants`/`satisfiedInvariants`/
+ * `selectedPath` to validate invariant routing).
+ *
+ * Per-space path decisions for extension members are not surfaced —
+ * extensions own their own ref/invariant control.
+ */
+export interface MigrationApplyPathDecision {
+  readonly fromHash: string;
+  readonly toHash: string;
+  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 migrationHash: string;
+    readonly from: string;
+    readonly to: string;
+    readonly invariants: readonly string[];
+  }[];
+}
+
 export interface MigrationApplySuccess {
   readonly migrationsApplied: number;
   readonly markerHash: string;
   readonly applied: readonly MigrationApplyAppliedEntry[];
   readonly summary: string;
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). See {@link AggregatePerSpaceExecutionEntry}.
+   * Always present for the aggregate-walking operation.
+   */
+  readonly perSpace: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  /**
+   * Path-decision data for the app member. Present whenever the
+   * graph-walk strategy ran for the app (i.e. always for the
+   * aggregate-walking apply path). Absent only for the no-op
+   * "Already up to date" early return when the app has no plan.
+   */
+  readonly pathDecision?: MigrationApplyPathDecision;
 }
 
 /**

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

@@ -2,63 +2,15 @@ import type { Contract } from '@prisma-next/contract/types';
 import type { ControlExtensionDescriptor } from '@prisma-next/framework-components/control';
 import type {
   ContractSpaceAggregate,
-  DeclaredExtensionEntry,
   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';
-
-/**
- * Structural shape the aggregate loader needs from each declared
- * `Config.extensionPacks` entry. Mirrors the SQL family's
- * `SqlControlExtensionDescriptor.contractSpace` shape but kept
- * structural so the loader doesn't depend on the SQL family.
- */
-type ExtensionPackForAggregate = {
-  readonly id: string;
-  readonly targetId: string;
-  readonly contractSpace?: {
-    readonly contractJson: unknown;
-    readonly headRef: { readonly hash: string; readonly invariants: readonly string[] };
-  };
-};
-
-/**
- * Convert the CLI's `Config.extensionPacks` array into the loader's
- * `DeclaredExtensionEntry[]` shape.
- *
- * The loader hashes `contractSpace.contractJson` to compare against the
- * on-disk `refs/head.json.hash` (drift detection). Rather than re-running
- * the canonical-JSON + SHA-256 pipeline at the CLI surface, we look up
- * the descriptor's pre-computed `headRef.hash` via reference identity
- * on the contract JSON value — the loader passes the same
- * `entry.contractSpace.contractJson` reference through to the hasher,
- * so identity-keyed lookup is safe.
- */
-function toDeclaredExtensions(extensionPacks: ReadonlyArray<ExtensionPackForAggregate>): {
-  readonly entries: ReadonlyArray<DeclaredExtensionEntry>;
-  readonly hashByContractJson: Map<unknown, string>;
-} {
-  const entries: DeclaredExtensionEntry[] = [];
-  const hashByContractJson = new Map<unknown, string>();
-  for (const pack of extensionPacks) {
-    const entry: DeclaredExtensionEntry = pack.contractSpace
-      ? {
-          id: pack.id,
-          targetId: pack.targetId,
-          contractSpace: { contractJson: pack.contractSpace.contractJson },
-        }
-      : { id: pack.id, targetId: pack.targetId };
-    entries.push(entry);
-    if (pack.contractSpace) {
-      hashByContractJson.set(pack.contractSpace.contractJson, pack.contractSpace.headRef.hash);
-    }
-  }
-  return { entries, hashByContractJson };
-}
+import { toDeclaredExtensions, toExtensionInputs } from './extension-pack-inputs';
 
 /**
  * Render a {@link LoadAggregateError} into a CLI structured-error
@@ -187,16 +139,32 @@ export interface BuildAggregateInputs<TFamilyId extends string, TTargetId extend
   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 are intentionally not threaded through:
- * `db init` / `db update` go through the planner's `synth` strategy for
- * the app member (driven by `callerPolicy.ignoreGraphFor`), so the
- * app's authored `migrations/` graph is not walked.
+ * 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.
  */
@@ -207,7 +175,7 @@ export async function buildContractSpaceAggregate<
   inputs: BuildAggregateInputs<TFamilyId, TTargetId>,
 ): Promise<Result<ContractSpaceAggregate, CliStructuredError>> {
   const { entries, hashByContractJson } = toDeclaredExtensions(
-    inputs.extensionPacks as ReadonlyArray<ExtensionPackForAggregate>,
+    toExtensionInputs(inputs.extensionPacks),
   );
 
   const loadInput: LoadAggregateInput = {
@@ -225,7 +193,7 @@ export async function buildContractSpaceAggregate<
       }
       return precomputed;
     },
-    appMigrationPackages: [],
+    appMigrationPackages: inputs.appMigrationPackages ?? [],
   };
 
   const result: LoadAggregateOutput = await loadContractSpaceAggregate(loadInput);

package/src/utils/extension-pack-inputs.ts

@@ -0,0 +1,170 @@
+/**
+ * Single descriptor-import boundary for CLI consumers of `Config.extensionPacks`.
+ *
+ * Every CLI command / utility that reads an extension descriptor's
+ * `contractSpace` projection (loader, migrate-pass, extension-migrations
+ * pass, migration commands) goes through {@link toExtensionInputs}. The
+ * structural cast `pack as { contractSpace?: ... }` lives **only** here —
+ * downstream code consumes the canonical shape and maps it to its own
+ * narrower shape via the per-consumer adapters below.
+ *
+ * The CLI receives extension descriptors typed against the SQL family
+ * (or any other family in the future); this helper only depends on the
+ * structural shape of `contractSpace`. SQL-family callers pass the same
+ * `contractJson` / `headRef.hash` value through unchanged.
+ */
+import type { DeclaredExtensionEntry } from '@prisma-next/migration-tools/aggregate';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
+import type { MigrationOps } from '@prisma-next/migration-tools/package';
+import type { ExtensionMigrationsExtensionInput } from './contract-space-extension-migrations-pass';
+import type { MigrateExtensionInput } from './contract-space-migrate-pass';
+
+/**
+ * In-memory authored migration package shipped by an extension descriptor.
+ * Mirrors the `MigrationPackage` shape from
+ * `@prisma-next/framework-components/control` minus `dirPath`; redeclared
+ * structurally here so the helper does not couple to the SQL family's
+ * `ExtensionMigrationPackage` type.
+ */
+export interface DescriptorMigrationPackage {
+  readonly dirName: string;
+  readonly metadata: MigrationMetadata;
+  readonly ops: MigrationOps;
+}
+
+/**
+ * The most-general projection of a single declared extension pack
+ * needed by the CLI's descriptor-import boundary.
+ *
+ * - `id` / `targetId` are always present.
+ * - `contractSpace` is present only when the extension declares one.
+ *   When present, it carries the canonical inputs every downstream
+ *   consumer needs — `contractJson`, `headRef`, and the descriptor's
+ *   pre-built migration packages.
+ */
+export interface ExtensionPackInput {
+  readonly id: string;
+  readonly targetId: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+    readonly headRef: {
+      readonly hash: string;
+      readonly invariants: readonly string[];
+    };
+    readonly migrations: readonly DescriptorMigrationPackage[];
+  };
+}
+
+/**
+ * Structural shape we read off each `Config.extensionPacks` entry.
+ *
+ * The CLI is the descriptor-import boundary; `extensionPacks` is the only
+ * surface where the SQL-family-typed `ControlExtensionDescriptor` flows
+ * into framework-neutral helpers. The structural cast lives here, and
+ * here alone — every other CLI consumer reads the canonical
+ * {@link ExtensionPackInput} shape produced by {@link toExtensionInputs}.
+ */
+type ExtensionPackLike = {
+  readonly id: string;
+  readonly targetId: string;
+  readonly contractSpace?: {
+    readonly contractJson: unknown;
+    readonly headRef: {
+      readonly hash: string;
+      readonly invariants: readonly string[];
+    };
+    readonly migrations?: readonly DescriptorMigrationPackage[];
+  };
+};
+
+/**
+ * Project the CLI's `Config.extensionPacks` array into the canonical
+ * {@link ExtensionPackInput} shape. The single `as ExtensionPackLike`
+ * structural cast in the CLI lives inside this function.
+ */
+export function toExtensionInputs(
+  extensionPacks: ReadonlyArray<unknown>,
+): readonly ExtensionPackInput[] {
+  return extensionPacks.map((raw) => {
+    const pack = raw as ExtensionPackLike;
+    if (pack.contractSpace === undefined) {
+      return { id: pack.id, targetId: pack.targetId };
+    }
+    return {
+      id: pack.id,
+      targetId: pack.targetId,
+      contractSpace: {
+        contractJson: pack.contractSpace.contractJson,
+        headRef: pack.contractSpace.headRef,
+        migrations: pack.contractSpace.migrations ?? [],
+      },
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Per-consumer adapters: take the canonical `ExtensionPackInput[]` and
+// project to whatever narrower shape the downstream primitive needs.
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregate-loader projection: surfaces `targetId` + `contractSpace.contractJson`
+ * to {@link import('./contract-space-aggregate-loader').buildContractSpaceAggregate}
+ * and a `hashByContractJson` map keyed by the same `contractJson` reference
+ * the loader hands to its hash callback.
+ */
+export function toDeclaredExtensions(inputs: ReadonlyArray<ExtensionPackInput>): {
+  readonly entries: ReadonlyArray<DeclaredExtensionEntry>;
+  readonly hashByContractJson: Map<unknown, string>;
+} {
+  const entries: DeclaredExtensionEntry[] = [];
+  const hashByContractJson = new Map<unknown, string>();
+  for (const pack of inputs) {
+    if (pack.contractSpace) {
+      entries.push({
+        id: pack.id,
+        targetId: pack.targetId,
+        contractSpace: { contractJson: pack.contractSpace.contractJson },
+      });
+      hashByContractJson.set(pack.contractSpace.contractJson, pack.contractSpace.headRef.hash);
+    } else {
+      entries.push({ id: pack.id, targetId: pack.targetId });
+    }
+  }
+  return { entries, hashByContractJson };
+}
+
+/** Migrate-time per-space pass projection. */
+export function toMigratePassInputs(
+  inputs: ReadonlyArray<ExtensionPackInput>,
+): readonly MigrateExtensionInput[] {
+  return inputs.map((pack) =>
+    pack.contractSpace
+      ? {
+          id: pack.id,
+          contractSpace: {
+            contractJson: pack.contractSpace.contractJson,
+            headRef: pack.contractSpace.headRef,
+          },
+        }
+      : { id: pack.id },
+  );
+}
+
+/** Extension-migrations materialisation pass projection. */
+export function toExtensionMigrationsInputs(
+  inputs: ReadonlyArray<ExtensionPackInput>,
+): readonly ExtensionMigrationsExtensionInput[] {
+  return inputs.map((pack) =>
+    pack.contractSpace
+      ? {
+          id: pack.id,
+          contractSpace: {
+            contractJson: pack.contractSpace.contractJson,
+            headRef: pack.contractSpace.headRef,
+            migrations: pack.contractSpace.migrations,
+          },
+        }
+      : { id: pack.id },
+  );
+}