@prisma-next/cli 0.14.0 → 0.15.0-dev.10

package/src/control-api/operations/migrate.ts

@@ -1,5 +1,5 @@
 /**
- * Backs the `migrate` command. Strategy: graph-walk-all-members, replay-only (no introspect/synth/planner).
+ * Backs the `migrate` command. Resolves the recorded path for every space, replay-only (no introspect/diff/planner).
  */
 
 import type { Contract } from '@prisma-next/contract/types';
@@ -11,13 +11,14 @@ import type {
   TargetMigrationsCapability,
 } from '@prisma-next/framework-components/control';
 import {
-  buildSynthMigrationEdge,
+  type AggregateContractSpace,
+  allStorageElementsExternal,
+  buildFabricatedMigrationEdge,
   type ContractMarkerRecordLike,
   type ContractSpaceAggregate,
-  type ContractSpaceMember,
-  graphWalkStrategy,
   type PerSpacePlan,
   requireHeadRef,
+  resolveRecordedPath,
 } from '@prisma-next/migration-tools/aggregate';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { errorNoInvariantPath } from '@prisma-next/migration-tools/errors';
@@ -62,8 +63,8 @@ export interface ExecuteMigrateOptions<TFamilyId extends string, TTargetId exten
   readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   readonly targetId: TTargetId;
   /**
-   * Optional app-space ref override. When provided, the app member's
-   * graph-walk targets this hash instead of `member.headRef.hash`.
+   * Optional app-space ref override. When provided, the app space's
+   * graph-walk targets this hash instead of `space.headRef.hash`.
    * Extensions are unaffected — they always walk to their own head.
    */
   readonly refHash?: string;
@@ -72,7 +73,7 @@ export interface ExecuteMigrateOptions<TFamilyId extends string, TTargetId exten
    * Threaded into the graph-walk's `required` calculation so the
    * planner picks an invariant-bearing path and surfaces the
    * required/satisfied set on the success envelope. When `refHash`
-   * is absent the file's `member.headRef.invariants` are used.
+   * is absent the file's `space.headRef.invariants` are used.
    */
   readonly refInvariants?: readonly string[];
   /**
@@ -89,22 +90,26 @@ export interface ExecuteMigrateOptions<TFamilyId extends string, TTargetId exten
 /**
  * Apply pending migrations across every contract space (app +
  * extensions). Replay-only: graph-walk against the on-disk graph for
- * every member; no synth, no introspection.
+ * every contract space; no synth, no introspection.
  *
  * Pipeline:
  *
  * 1. Load aggregate from disk (loader hydrates extension graphs;
  *    caller provides app-space packages).
  * 2. Read live marker rows per space (`familyInstance.readAllMarkers`).
- * 3. Per member: `graphWalkStrategy` plots the path from the live
- *    marker to `member.headRef.hash` (or `refHash` for the app
- *    member when provided). Empty-graph members fail loudly — a
- *    "never planned" space is a user-error condition for replay.
+ * 3. Per space: `resolveRecordedPath` plots the path from the live
+ *    marker to `space.headRef.hash` (or `refHash` for the app
+ *    space when provided). An empty-graph space whose elements are ALL
+ *    externally managed resolves declaratively (marker to head, zero
+ *    ops), mirroring the db-init aggregate planner: such a space ships
+ *    no DDL and has nothing to author. Every other empty-graph space
+ *    fails loudly — "never planned" is a user-error condition for
+ *    replay.
  * 4. Hand off to {@link runMigration} (the runner-driving tail
  *    shared with `db init` / `db update`). Marker advancement is
  *    inside the per-space transaction.
  *
- * Encodes the replay-only contract: every contract space must have an
+ * Encodes the replay-only contract: the app contract space must have an
  * authored migration graph on disk before this operation can advance it.
  */
 export async function executeMigrate<TFamilyId extends string, TTargetId extends string>(
@@ -140,41 +145,41 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
 
   const markerRows = await familyInstance.readAllMarkers({ driver });
 
-  // Plan every member via graph-walk. App member targets `refHash`
+  // Plan every space via graph-walk. App space targets `refHash`
   // when provided, otherwise its own head; extensions always walk
   // to their own head ref.
-  const allMembers: ReadonlyArray<ContractSpaceMember> = [aggregate.app, ...aggregate.extensions];
+  const allSpaces: ReadonlyArray<AggregateContractSpace> = [aggregate.app, ...aggregate.extensions];
   const perSpacePlans = new Map<string, PerSpacePlan>();
-  // Already-at-head empty-graph members (typically extensions whose
+  // Already-at-head empty-graph spaces (typically extensions whose
   // head ref is the empty sentinel, or whose live marker already
   // matches the target). Kept out of the runner schedule so we don't
   // write spurious markers for greenfield extensions, but merged back
-  // into the success envelope so every loaded member is represented.
+  // into the success envelope so every loaded space is represented.
   const atHeadResolutions = new Map<string, PerSpacePlan>();
-  for (const member of allMembers) {
-    const isAppMember = member.spaceId === aggregate.app.spaceId;
-    // The aggregate passed the integrity gate, so every member's head ref
+  for (const space of allSpaces) {
+    const isAppSpace = space.spaceId === aggregate.app.spaceId;
+    // The aggregate passed the integrity gate, so every space's head ref
     // is resolved (the app's is synthesised from the live contract).
-    const headRef = requireHeadRef(member);
-    const memberTargetHash = isAppMember && refHash !== undefined ? refHash : headRef.hash;
-    const memberRefInvariants = isAppMember && refHash !== undefined ? refInvariants : undefined;
-    const liveMarker = markerRows.get(member.spaceId) ?? null;
+    const headRef = requireHeadRef(space);
+    const spaceTargetHash = isAppSpace && refHash !== undefined ? refHash : headRef.hash;
+    const spaceRefInvariants = isAppSpace && refHash !== undefined ? refInvariants : undefined;
+    const liveMarker = markerRows.get(space.spaceId) ?? null;
 
-    const outcome = planMemberPath({
-      member,
+    const outcome = planSpacePath({
+      space,
       aggregate,
-      targetHash: memberTargetHash,
-      refInvariants: memberRefInvariants,
+      targetHash: spaceTargetHash,
+      refInvariants: spaceRefInvariants,
       liveMarker,
-      ...(isAppMember ? { refName } : {}),
+      ...(isAppSpace ? { refName } : {}),
     });
 
     if (outcome.kind === 'at-head') {
-      // Empty-graph member whose live marker already matches the target.
+      // Empty-graph space whose live marker already matches the target.
       // Kept out of the runner schedule so we don't write spurious markers
       // for greenfield extensions, but merged back into the success envelope
-      // so every loaded member is represented.
-      atHeadResolutions.set(member.spaceId, outcome.plan);
+      // so every loaded space is represented.
+      atHeadResolutions.set(space.spaceId, outcome.plan);
       continue;
     }
     if (outcome.kind === 'never-planned') {
@@ -197,9 +202,9 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
       // is never a graph node, producing an empty `structuralPath` and
       // a less actionable diagnostic.
       const structural = findPathWithDecision(
-        outcome.targetMember.graph(),
+        outcome.targetSpace.graph(),
         outcome.liveHash,
-        memberTargetHash,
+        spaceTargetHash,
         { required: new Set<string>() },
       );
       const structuralPath =
@@ -220,18 +225,23 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
       });
     }
 
-    perSpacePlans.set(member.spaceId, outcome.plan);
+    perSpacePlans.set(space.spaceId, outcome.plan);
   }
 
   const canonicalOrder = [...aggregate.extensions.map((m) => m.spaceId), aggregate.app.spaceId];
   const applyOrder = canonicalOrder.filter((spaceId) => perSpacePlans.has(spaceId));
 
   // Short-circuit: nothing pending across any space (no runner-bound
-  // plans). Surfaces every loaded member — including at-head empty-
+  // plans). Surfaces every loaded space — including at-head empty-
   // graph extensions — in `perSpace[]` so the result reflects the
   // full aggregate, not just the spaces the runner would have touched.
-  const totalPlannedOps = sumPlannedOps(applyOrder, perSpacePlans);
-  if (totalPlannedOps === 0) {
+  // A zero-op plan still counts as pending when it advances a marker
+  // (declared-state resolution for an all-external extension space).
+  const hasPendingWork = applyOrder.some((spaceId) => {
+    const entry = perSpacePlans.get(spaceId);
+    return entry !== undefined && planRequiresExecution(entry);
+  });
+  if (!hasPendingWork) {
     const ordered = canonicalOrder
       .filter((spaceId) => perSpacePlans.has(spaceId) || atHeadResolutions.has(spaceId))
       .map((spaceId) => {
@@ -285,7 +295,7 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
   }
 
   // Merge at-head zero-op resolutions back into the canonical order
-  // so the success envelope surfaces every loaded member, not just
+  // so the success envelope surfaces every loaded space, not just
   // those the runner executed.
   const orderedAll = canonicalOrder
     .filter((spaceId) => perSpacePlans.has(spaceId) || atHeadResolutions.has(spaceId))
@@ -321,16 +331,16 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
 }
 
 /**
- * Outcome variants for one member's path computation.
+ * Outcome variants for one space's path computation.
  *
  * Callers switch on `kind` and map to their own error representation:
  * `executeMigrate` throws / returns `notOk`; `executeMigrateShowCommand`
  * returns a CLI structured error. The shared discriminant guarantees both
- * paths feed `graphWalkStrategy` the same inputs.
+ * paths feed `resolveRecordedPath` the same inputs.
  *
  * @internal Exported for `executeMigrateShowCommand` to call.
  */
-export type MemberPathOutcome =
+export type SpacePathOutcome =
   | { readonly kind: 'ok'; readonly plan: PerSpacePlan }
   | { readonly kind: 'at-head'; readonly plan: PerSpacePlan }
   | { readonly kind: 'never-planned'; readonly spaceId: string; readonly targetHash: string }
@@ -343,16 +353,16 @@ export type MemberPathOutcome =
   | {
       readonly kind: 'unsatisfiable';
       readonly spaceId: string;
-      readonly isAppMember: boolean;
+      readonly isAppSpace: boolean;
       readonly missing: readonly string[];
       readonly targetInvariants: readonly string[];
-      readonly targetMember: ContractSpaceMember;
+      readonly targetSpace: AggregateContractSpace;
       readonly liveHash: string;
       readonly refName: string | undefined;
     };
 
 /**
- * Compute the graph-walk path for one contract-space member.
+ * Compute the graph-walk path for one contract space.
  *
  * Encapsulates the invariant-correct input assembly that both
  * `executeMigrate` and `executeMigrateShowCommand` must use:
@@ -361,71 +371,104 @@ export type MemberPathOutcome =
  * - `targetInvariants` uses the caller-supplied `refInvariants` when a
  *   `--to` ref was resolved (not always the file head ref's invariants).
  *
- * Both callers map the returned `MemberPathOutcome` to their own error
+ * Both callers map the returned `SpacePathOutcome` to their own error
  * representation; the path-compute logic is shared and identical.
  *
  * @internal Exported for `executeMigrateShowCommand`.
  */
-export function planMemberPath({
-  member,
+export function planSpacePath({
+  space,
   aggregate,
   targetHash,
   refInvariants,
   liveMarker,
   refName,
 }: {
-  readonly member: ContractSpaceMember;
+  readonly space: AggregateContractSpace;
   readonly aggregate: Pick<ContractSpaceAggregate, 'targetId' | 'app'>;
   readonly targetHash: string;
   readonly refInvariants: readonly string[] | undefined;
   readonly liveMarker: ContractMarkerRecordLike | null;
   readonly refName?: string;
-}): MemberPathOutcome {
-  const isAppMember = member.spaceId === aggregate.app.spaceId;
-  const headRef = requireHeadRef(member);
+}): SpacePathOutcome {
+  const isAppSpace = space.spaceId === aggregate.app.spaceId;
+  const headRef = requireHeadRef(space);
 
-  if (member.graph().nodes.size === 0) {
+  if (space.graph().nodes.size === 0) {
     const liveHash = liveMarker?.storageHash;
     if (targetHash === liveHash || (liveHash === undefined && targetHash === EMPTY_CONTRACT_HASH)) {
       return {
         kind: 'at-head',
         plan: buildAtHeadResolution({
           aggregateTargetId: aggregate.targetId,
-          member,
+          space,
           targetHash,
           liveMarker,
         }),
       };
     }
-    return { kind: 'never-planned', spaceId: member.spaceId, targetHash };
+    // Empty-graph extension space not yet at head: the space ships no
+    // migration packages at all. Advancing the marker without migrations
+    // (the db-init aggregate planner's declared-state strategy, mirrored
+    // here) is valid exclusively when every element the space declares is
+    // externally managed — nothing Prisma Next owns exists in such a space
+    // (e.g. Supabase's auth/storage), so its declared state needs no
+    // migration to be true, and there is no command that could author an
+    // edge for it. A space that declares a managed element but ships no
+    // migration graph is an authoring bug: it falls through to the
+    // never-planned failure, like an app space with no authored graph.
+    if (!isAppSpace && allStorageElementsExternal(space.contract())) {
+      if (headRef.invariants.length > 0) {
+        return {
+          kind: 'unsatisfiable',
+          spaceId: space.spaceId,
+          isAppSpace,
+          missing: [...headRef.invariants].sort(),
+          targetInvariants: headRef.invariants,
+          targetSpace: space,
+          liveHash: liveHash ?? EMPTY_CONTRACT_HASH,
+          refName: undefined,
+        };
+      }
+      return {
+        kind: 'ok',
+        plan: buildAtHeadResolution({
+          aggregateTargetId: aggregate.targetId,
+          space,
+          targetHash,
+          liveMarker,
+        }),
+      };
+    }
+    return { kind: 'never-planned', spaceId: space.spaceId, targetHash };
   }
 
   const targetInvariants =
-    isAppMember && refInvariants !== undefined ? refInvariants : headRef.invariants;
-  const targetMember: ContractSpaceMember =
+    isAppSpace && refInvariants !== undefined ? refInvariants : headRef.invariants;
+  const targetSpace: AggregateContractSpace =
     targetHash === headRef.hash && targetInvariants === headRef.invariants
-      ? member
-      : { ...member, headRef: { hash: targetHash, invariants: targetInvariants } };
+      ? space
+      : { ...space, headRef: { hash: targetHash, invariants: targetInvariants } };
 
-  const walked = graphWalkStrategy({
+  const walked = resolveRecordedPath({
     aggregateTargetId: aggregate.targetId,
-    member: targetMember,
+    space: targetSpace,
     currentMarker: liveMarker,
-    ...(isAppMember && refName !== undefined ? { refName } : {}),
+    ...(isAppSpace && refName !== undefined ? { refName } : {}),
   });
 
   if (walked.kind === 'unreachable') {
-    return { kind: 'unreachable', spaceId: member.spaceId, liveMarker, targetHash };
+    return { kind: 'unreachable', spaceId: space.spaceId, liveMarker, targetHash };
   }
   if (walked.kind === 'unsatisfiable') {
     const liveHash = liveMarker?.storageHash ?? EMPTY_CONTRACT_HASH;
     return {
       kind: 'unsatisfiable',
-      spaceId: member.spaceId,
-      isAppMember,
+      spaceId: space.spaceId,
+      isAppSpace,
       missing: walked.missing,
       targetInvariants,
-      targetMember,
+      targetSpace,
       liveHash,
       refName,
     };
@@ -434,33 +477,35 @@ export function planMemberPath({
 }
 
 /**
- * Build a zero-op {@link PerSpacePlan} for an empty-graph
- * member whose live marker already matches the target. Lets the apply
- * pipeline thread the member through `perSpacePlans` -> `applyOrder`
- * -> the success envelope's `perSpace[]` block so the result reflects
- * every loaded space, even when there is nothing to execute.
+ * Build a zero-op {@link PerSpacePlan} for an empty-graph space —
+ * either one whose live marker already matches the target (at-head), or
+ * an all-external extension space whose marker must advance to the head
+ * ref with no DDL (declared-state). Lets the apply pipeline thread the
+ * space through `perSpacePlans` -> `applyOrder` -> the success
+ * envelope's `perSpace[]` block so the result reflects every loaded
+ * space, even when there is nothing to execute.
  */
 function buildAtHeadResolution(args: {
   readonly aggregateTargetId: string;
-  readonly member: ContractSpaceMember;
+  readonly space: AggregateContractSpace;
   readonly targetHash: string;
   readonly liveMarker: ContractMarkerRecordLike | null;
 }): PerSpacePlan {
-  const { aggregateTargetId, member, targetHash, liveMarker } = args;
+  const { aggregateTargetId, space, targetHash, liveMarker } = args;
   return {
     plan: {
       targetId: aggregateTargetId,
-      spaceId: member.spaceId,
+      spaceId: space.spaceId,
       origin: liveMarker === null ? null : { storageHash: liveMarker.storageHash },
       destination: { storageHash: targetHash },
       operations: [],
       providedInvariants: [],
     },
     displayOps: [],
-    destinationContract: member.contract(),
-    strategy: 'graph-walk',
+    destinationContract: space.contract(),
+    strategy: 'declared-state',
     migrationEdges: [
-      buildSynthMigrationEdge({
+      buildFabricatedMigrationEdge({
         currentMarkerStorageHash: liveMarker?.storageHash,
         destinationStorageHash: targetHash,
         operationCount: 0,
@@ -469,17 +514,14 @@ function buildAtHeadResolution(args: {
   };
 }
 
-function sumPlannedOps(
-  applyOrder: readonly string[],
-  perSpacePlans: ReadonlyMap<string, PerSpacePlan>,
-): number {
-  let total = 0;
-  for (const spaceId of applyOrder) {
-    const entry = perSpacePlans.get(spaceId);
-    if (!entry) continue;
-    total += entry.plan.operations.length;
-  }
-  return total;
+/**
+ * A plan needs the runner when it executes operations or advances the
+ * space's marker (a declared-state resolution has zero operations but a
+ * destination hash the live marker doesn't carry yet).
+ */
+function planRequiresExecution(entry: PerSpacePlan): boolean {
+  if (entry.plan.operations.length > 0) return true;
+  return entry.plan.origin?.storageHash !== entry.plan.destination.storageHash;
 }
 
 interface BuildSuccessArgs {
@@ -494,7 +536,7 @@ interface BuildSuccessArgs {
 }
 
 function buildSuccess(args: BuildSuccessArgs): MigrateSuccess {
-  // The marker hash surfaced at the top level is the **app member's**
+  // The marker hash surfaced at the top level is the **app space's**
   // post-migrate marker (the top-level `markerHash` field).
   // Per-space markers live on `perSpace[].marker.storageHash`.
   const appResolution = args.orderedResolutions.find(
@@ -552,10 +594,12 @@ function buildSuccess(args: BuildSuccessArgs): MigrateSuccess {
 }
 
 /**
- * Build the `neverPlanned` failure raised when a contract space has no on-disk
- * migration graph but migrate was asked to reach a target hash. The `why`
- * states only the condition; the recovery sequence is composed by
- * `errorPathUnreachable`'s `fix`.
+ * Build the `neverPlanned` failure raised when a contract space that
+ * declares managed storage elements has no on-disk migration graph but
+ * migrate was asked to reach a target hash. All-external spaces never reach
+ * this: they resolve declaratively (marker advances to the head ref with
+ * zero operations). The `why` states only the condition; the recovery
+ * sequence is composed by `errorPathUnreachable`'s `fix`.
  *
  * @internal Exported for testing only.
  */
@@ -563,7 +607,7 @@ export function buildNeverPlannedFailure(spaceId: string, targetHash: string): M
   return {
     code: 'MIGRATION_PATH_NOT_FOUND',
     summary: `No on-disk migrations for contract space "${spaceId}"`,
-    why: `migrate is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}".`,
+    why: `migrate is replay-only: a contract space that declares managed storage elements must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}".`,
     meta: { spaceId, target: targetHash, kind: 'neverPlanned' },
   };
 }
@@ -586,7 +630,7 @@ export function buildPathNotFoundFailure(
   const fromHash = marker?.storageHash ?? '<empty>';
   // The app-case phrasing names the user-visible condition (a
   // contract has been emitted that no on-disk migration reaches) so
-  // the error reads naturally for the app member. Extension spaces
+  // the error reads naturally for the app space. Extension spaces
   // see the same condition expressed against the offending space.
   const summary =
     spaceId === 'app'

package/src/control-api/operations/run-migration.ts

@@ -45,10 +45,11 @@ export interface RunMigrationInputs<TFamilyId extends string, TTargetId extends
   readonly aggregate: ContractSpaceAggregate;
   /**
    * Per-space plans, keyed by `spaceId`. Produced by either the full
-   * {@link planMigration} pipeline (`db init` / `db update` — synth
-   * for the app, graph-walk for extensions) or by direct
-   * {@link graphWalkStrategy} calls (`migrate` — graph-walk
-   * for every member). Either way, the runner consumes the same shape.
+   * {@link planMigration} pipeline (`db init` / `db update` —
+   * `planFromDiff` for the app, `resolveRecordedPath` for extensions) or
+   * by direct {@link resolveRecordedPath} calls (`migrate` — resolves
+   * the recorded path for every contract space). Either way, the runner
+   * consumes the same shape.
    */
   readonly perSpacePlans: ReadonlyMap<string, PerSpacePlan>;
   /**
@@ -229,7 +230,7 @@ export function buildPerSpaceBreakdown(
 
 /**
  * Materialise the `applyOrder` ordering into resolved per-space
- * entries. Throws if the planner output is missing a member listed
+ * entries. Throws if the planner output is missing a contract space listed
  * in `applyOrder` — a wiring bug that should never reach runtime.
  *
  * Exported so callers building their own success envelopes after a

package/src/control-api/types.ts

@@ -545,7 +545,7 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
  *
  * 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`
+ * live database, plotting per-space paths via `resolveRecordedPath`
  * (replay-only — no synth, no introspection), and dispatching
  * through the shared `runMigration` primitive. The CLI command
  * just resolves the descriptor surface (config, refs, contract
@@ -557,9 +557,9 @@ export interface MigrateOptions {
   /** Migrations root directory (`migrations/` under the project). */
   readonly migrationsDir: string;
   /**
-   * Optional app-space ref override. When provided, the app member's
+   * Optional app-space ref override. When provided, the app space's
    * graph-walk targets this hash instead of `contract.storage.storageHash`.
-   * Extension members always walk to their own `headRef.hash`.
+   * Extension spaces always walk to their own `headRef.hash`.
    */
   readonly refHash?: string;
   /**
@@ -631,17 +631,17 @@ export interface MigrateRanEntry {
 
 /**
  * Successful migrate result. Carries both the top-level fields
- * (`markerHash` is the **app member's** post-migrate marker) and the
+ * (`markerHash` is the **app space's** post-migrate marker) and the
  * per-space breakdown (`perSpace` — markers / operations in canonical
  * schedule order).
  */
 /**
- * Path-decision summary for the **app member** post-migrate. Surfaced
+ * Path-decision summary for the **app space** post-migrate. Surfaced
  * at the top level (and consumed by the cli-journeys suite, which
  * inspects `requiredInvariants`/`satisfiedInvariants`/
  * `selectedPath` to validate invariant routing).
  *
- * Per-space path decisions for extension members are not surfaced —
+ * Per-space path decisions for extension spaces are not surfaced —
  * extensions own their own ref/invariant control.
  */
 export interface MigratePathDecision {
@@ -673,7 +673,7 @@ export interface MigrateSuccess {
    */
   readonly perSpace: ReadonlyArray<PerSpaceExecutionEntry>;
   /**
-   * Path-decision data for the app member. Present whenever the
+   * Path-decision data for the app space. Present whenever the
    * graph-walk strategy ran for the app (i.e. always for the
    * aggregate-walking migrate path). Absent only for the no-op
    * "Already up to date" early return when the app has no plan.
@@ -864,7 +864,7 @@ export interface ControlClient {
    *   markers, and (unless `skipSchema` is true) per-space schema
    *   verification with pre-projection (closes F23).
    *
-   * @returns Result pattern: per-space schema results on success;
+   * @returns Result pattern: per-space verify results on success;
    *          structured CLI error on marker / loader failure.
    * @throws If not connected or infrastructure failure
    */

package/src/exports/index.ts

@@ -1,4 +1,5 @@
 // CLI-specific exports
 export { createContractEmitCommand } from '../commands/contract-emit';
+export { createFormatCommand } from '../commands/format';
 export type { LoadTsContractOptions } from '../load-ts-contract';
 export { loadContractFromTs } from '../load-ts-contract';

package/src/migration-cli.ts

@@ -45,6 +45,7 @@
 import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import type { Writable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
+import { loadConfig } from '@prisma-next/config-loader';
 import {
   CliStructuredError,
   errorMigrationCliInvalidConfigArg,
@@ -57,7 +58,6 @@ import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import { buildMigrationArtifacts, type Migration } from '@prisma-next/migration-tools/migration';
 import { Cli, Command, Option, UsageError } from 'clipanion';
 import { dirname, join } from 'pathe';
-import { loadConfig } from './config-loader';
 
 /**
  * Constructor shape accepted by `MigrationCLI.run`. `Migration` subclasses

package/src/utils/cli-errors.ts

@@ -287,7 +287,18 @@ export function errorPathUnreachable(failure: MigrateFailure): CliStructuredErro
   // Plan-then-apply recovery. The planner destination is the missing edge's
   // target; `migration plan --to` (built for arbitrary targets) makes this a
   // real command, so the diagnostic that sends you here is now honest.
+  //
+  // Never-planned spaces have an EMPTY migration graph, and contract-ref
+  // resolution only resolves full hashes against graph nodes — a
+  // `--to <hash>` remediation would reject its own input. `migration plan`
+  // without `--to` targets the working contract (the same contract the app
+  // space's synthesized head ref carries), so the bare form is the one that
+  // runs verbatim.
+  const neverPlanned = meta['kind'] === 'neverPlanned';
   const planCommand = (() => {
+    if (neverPlanned) {
+      return 'prisma-next migration plan --name <slug>';
+    }
     if (planFromHash !== null && targetHash !== null) {
       return `prisma-next migration plan --from ${planFromHash} --to ${targetHash} --name <slug>`;
     }
@@ -300,7 +311,9 @@ export function errorPathUnreachable(failure: MigrateFailure): CliStructuredErro
     return 'prisma-next migration plan';
   })();
   const applyCommand =
-    targetHash !== null ? `prisma-next migrate --to ${targetHash}` : 'prisma-next migrate';
+    targetHash !== null && !neverPlanned
+      ? `prisma-next migrate --to ${targetHash}`
+      : 'prisma-next migrate';
   return errorRuntime(failure.summary, {
     why:
       failure.why ??