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

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

@@ -12,6 +12,7 @@ import type {
 } from '@prisma-next/framework-components/control';
 import {
   type AggregateContractSpace,
+  allStorageElementsExternal,
   buildFabricatedMigrationEdge,
   type ContractMarkerRecordLike,
   type ContractSpaceAggregate,
@@ -98,13 +99,17 @@ export interface ExecuteMigrateOptions<TFamilyId extends string, TTargetId exten
  * 2. Read live marker rows per space (`familyInstance.readAllMarkers`).
  * 3. Per space: `resolveRecordedPath` plots the path from the live
  *    marker to `space.headRef.hash` (or `refHash` for the app
- *    space when provided). Empty-graph spaces fail loudly — a
- *    "never planned" space is a user-error condition for replay.
+ *    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>(
@@ -230,8 +235,13 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
   // 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) => {
@@ -397,6 +407,39 @@ export function planSpacePath({
         }),
       };
     }
+    // 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 };
   }
 
@@ -434,11 +477,13 @@ export function planSpacePath({
 }
 
 /**
- * Build a zero-op {@link PerSpacePlan} for an empty-graph
- * space whose live marker already matches the target. 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.
+ * 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;
@@ -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 {
@@ -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' },
   };
 }

package/src/control-api/types.ts

@@ -402,7 +402,10 @@ export interface DbInitSuccess {
 /**
  * Failure codes for dbInit operation.
  */
-export type DbInitFailureCode = 'PLANNING_FAILED' | 'MARKER_ORIGIN_MISMATCH' | 'RUNNER_FAILED';
+export type DbInitFailureCode =
+  | 'PLANNING_FAILED'
+  | 'MIGRATION.MARKER_ORIGIN_MISMATCH'
+  | 'RUNNER_FAILED';
 
 /**
  * Failure details for dbInit operation.

package/src/migration-cli.ts

@@ -21,7 +21,7 @@
  *    the CLI commands use, walking up from the migration file's directory.
  * 4. Probe-instantiates the migration class without a stack so it can read
  *    `targetId` and verify it matches `config.target.targetId`
- *    (`PN-MIG-2006` on mismatch) before any stack-driven adapter
+ *    (`MIGRATION.TARGET_MISMATCH` on mismatch) before any stack-driven adapter
  *    construction runs.
  * 5. Assembles a `ControlStack` from the loaded config descriptors and
  *    constructs the migration with that stack.
@@ -269,7 +269,7 @@ async function orchestrate(
 
   // Pre-scan for malformed `--config` (no value, or value-shaped-as-flag)
   // before delegating to clipanion. The legacy parser surfaced both as
-  // `errorMigrationCliInvalidConfigArg` (`PN-CLI-4012`); pre-scanning
+  // `errorMigrationCliInvalidConfigArg` (`CLI.CONFIG_ARG_MISSING_PATH`); pre-scanning
   // here keeps that contract independent of how clipanion classifies
   // the error internally (it variably throws `UnknownSyntaxError` or
   // accepts the flag-shaped token as the value depending on what other
@@ -337,7 +337,7 @@ async function orchestrate(
  * - `--config <empty>` where the value is the empty string. Shells
  *   expand `--config ""` (or `--config "$UNSET_VAR"`) into a real
  *   empty argv token; treating that as a usage error here surfaces
- *   `PN-CLI-4012` instead of a less actionable loader error on an
+ *   `CLI.CONFIG_ARG_MISSING_PATH` instead of a less actionable loader error on an
  *   empty path.
  * - `--config=` (the equals form with an empty value). Same shape as
  *   the empty-string case above; the user expressed intent to override
@@ -425,7 +425,7 @@ function isUnknownSyntaxError(err: unknown): err is Error {
 /**
  * Best-effort: pull the first input token that doesn't match a known
  * flag. Falls back to the first token when we can't pinpoint it. The
- * returned name is rendered into the user-visible PN-CLI-4013 envelope
+ * returned name is rendered into the user-visible CLI.UNKNOWN_FLAG envelope
  * (`Unknown flag \`<name>\``) and round-tripped via `meta.flag` so
  * agent consumers can render their own "did you mean" suggestions.
  */
@@ -556,7 +556,7 @@ async function runMigration(
   // subclasses are required to accept the no-arg form; the abstract
   // `Migration` constructor declares `stack?` and target subclasses
   // (Postgres, Mongo) propagate that optionality. This makes the
-  // target-mismatch guard fail fast with `PN-MIG-2006` before any
+  // target-mismatch guard fail fast with `MIGRATION.TARGET_MISMATCH` before any
   // stack-driven adapter construction begins, even if the wrong-target
   // adapter's `create` would otherwise succeed and silently misshapen
   // the stored adapter cast.

package/src/utils/cli-errors.ts

@@ -215,22 +215,30 @@ export function errorPlanForgotTheFlag(
   });
 }
 
+/**
+ * `viaRef: true` (the default) mirrors migration-tools' `errorRefNotResolvable`:
+ * a ref name with no pointer file, where the fallback hash isn't a graph
+ * node either — there's nothing to materialize a contract from.
+ * `viaRef: false` is a distinct, ref-independent case: an explicit `--from
+ * <hash>` that doesn't name a ref, on an empty migration graph, so there is
+ * no graph node and no ref to resolve a contract through.
+ */
 export function errorSnapshotMissing(
   identifier: string,
   options?: { readonly viaRef?: boolean },
 ): CliStructuredError {
   const viaRef = options?.viaRef !== false;
   const fix = viaRef
-    ? `Run "prisma-next db update --advance-ref ${identifier}" to repopulate the snapshot, or "prisma-next ref delete ${identifier}" to clear the orphan pointer.`
-    : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name that has a paired snapshot, or run db update first.`;
+    ? `Create the ref with "prisma-next ref set ${identifier} <hash>" (or advance it via "prisma-next db update --advance-ref ${identifier}"), or pass a hash that is a node in the migration graph.`
+    : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name (its contract resolves through the snapshot store), or run db update first.`;
   return errorRuntime(
     viaRef
-      ? `Ref "${identifier}" has no paired contract snapshot`
+      ? `Ref "${identifier}" is not resolvable`
       : `No contract source for from-hash "${identifier}"`,
     {
       why: viaRef
-        ? `Ref "${identifier}" exists but its paired snapshot files are missing.`
-        : `Hash "${identifier}" is not a graph node and no paired ref snapshot supplies a contract.`,
+        ? `Ref "${identifier}" has no pointer file, and the hash being resolved is not a node in the migration graph either.`
+        : `Hash "${identifier}" is not a node in the migration graph (the graph is empty), and it does not name a ref either.`,
       fix,
       meta: {
         code: 'MIGRATION.SNAPSHOT_MISSING',
@@ -287,7 +295,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 +319,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 ??
@@ -347,7 +368,7 @@ export function mapMigrationToolsError(error: MigrationToolsError): CliStructure
  * Shared "needs a live database" precondition for read verbs that consult the
  * marker/ledger (`migration log`, `migration status`). A command needs both a
  * connection string and a control-plane driver; either missing yields the same
- * `PN-CLI-4005` envelope with `meta.missingFlags` (canonical long-form flags
+ * `CONFIG.DB_CONNECTION_REQUIRED` envelope with `meta.missingFlags` (canonical long-form flags
  * per CLI Style Guide §Errors) so callers can react programmatically. Returns
  * `null` when both are present.
  */

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

@@ -78,7 +78,7 @@ export function combineVerifyResults(
   return {
     result: {
       ok,
-      ...(ok ? {} : { code: appResult.code ?? 'PN-RUN-3010' }),
+      ...(ok ? {} : { code: appResult.code ?? 'CONTRACT.MARKER_REQUIRED' }),
       summary,
       contract: appResult.contract,
       target: appResult.target,

package/src/utils/contract-at-errors.ts

@@ -1,6 +1,5 @@
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { notOk, type Result } from '@prisma-next/utils/result';
-import { join } from 'pathe';
 import {
   CliStructuredError,
   errorContractValidationFailed,
@@ -16,7 +15,7 @@ export function mapContractAtError(
 ): Result<never, CliStructuredError> {
   if (MigrationToolsError.is(error)) {
     switch (error.code) {
-      case 'MIGRATION.SNAPSHOT_MISSING': {
+      case 'MIGRATION.REF_NOT_RESOLVABLE': {
         const refName =
           typeof error.details?.['refName'] === 'string'
             ? error.details['refName']
@@ -27,18 +26,13 @@ export function mapContractAtError(
       }
       case 'MIGRATION.CONTRACT_DESERIALIZATION_FAILED': {
         const filePath =
-          typeof error.details?.['filePath'] === 'string'
-            ? error.details['filePath']
-            : 'ref-snapshot';
+          typeof error.details?.['filePath'] === 'string' ? error.details['filePath'] : 'unknown';
         const message =
           typeof error.details?.['message'] === 'string' ? error.details['message'] : error.message;
-        const isRefSnapshot = filePath.endsWith('.contract.json');
         return notOk(
           errorContractValidationFailed(
-            isRefSnapshot
-              ? `Ref snapshot contract failed to deserialize: ${message}`
-              : `Predecessor contract at ${filePath} failed to deserialize: ${message}`,
-            { where: { path: isRefSnapshot ? 'ref-snapshot' : filePath } },
+            `Predecessor contract at ${filePath} failed to deserialize: ${message}`,
+            { where: { path: filePath } },
           ),
         );
       }
@@ -66,22 +60,19 @@ export function mapContractAtError(
             fix: error.fix,
           }),
         );
-      case 'MIGRATION.FILE_MISSING': {
-        const file =
-          typeof error.details?.['file'] === 'string' ? error.details['file'] : 'end-contract.json';
-        const dir = typeof error.details?.['dir'] === 'string' ? error.details['dir'] : '';
-        const jsonPath = dir ? join(dir, 'end-contract.json') : file;
+      case 'MIGRATION.CONTRACT_SNAPSHOT_MISSING': {
+        const expectedPath =
+          typeof error.details?.['expectedPath'] === 'string'
+            ? error.details['expectedPath']
+            : 'migrations/snapshots/';
         const role = options?.artifactRole ?? 'from';
         return notOk(
-          errorFileNotFound(jsonPath, {
+          errorFileNotFound(expectedPath, {
             why:
               role === 'to'
-                ? `Target migration is missing its destination contract snapshot at ${jsonPath}`
-                : `Predecessor migration is missing its destination contract snapshot at ${jsonPath}`,
-            fix:
-              role === 'to'
-                ? 'Re-emit the target migration so its sibling `end-contract.json` / `end-contract.d.ts` are restored, then re-run this command.'
-                : 'Re-emit the predecessor migration (`prisma-next migration plan` from its source) so its sibling `end-contract.json` is restored, then re-run this command.',
+                ? `Target migration is missing its contract snapshot at ${expectedPath}`
+                : `Predecessor migration is missing its contract snapshot at ${expectedPath}`,
+            fix: 'Restore migrations/snapshots/ from version control, or re-run the command that produced this migration to regenerate its snapshot.',
           }),
         );
       }

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

@@ -20,7 +20,7 @@ import { toDeclaredExtensionsFromRaw } from './extension-pack-inputs';
 
 const CONTRACT_SPACES_DOCS_URL = 'https://pris.ly/contract-spaces';
 
-function contractSpaceError5002(
+function contractSpaceViolationError(
   summary: string,
   options: {
     readonly why: string;
@@ -28,8 +28,7 @@ function contractSpaceError5002(
     readonly violations: readonly IntegrityViolation[];
   },
 ): CliStructuredError {
-  return new CliStructuredError('5002', summary, {
-    domain: 'MIG',
+  return new CliStructuredError('MIGRATION.CONTRACT_SPACE_VIOLATION', summary, {
     why: options.why,
     fix: options.fix,
     docsUrl: CONTRACT_SPACES_DOCS_URL,
@@ -38,7 +37,7 @@ function contractSpaceError5002(
 }
 
 /**
- * Build the `5002` structured-error envelope for a contract-space
+ * Build the `MIGRATION.CONTRACT_SPACE_VIOLATION` structured-error envelope for a contract-space
  * target mismatch. Shared between the declared-extension precheck (the
  * descriptor's configured target disagrees with the project target) and
  * the on-disk-contract check surfaced by `checkIntegrity`.
@@ -48,7 +47,7 @@ function targetMismatchError(
   expected: string,
   actual: string,
 ): CliStructuredError {
-  return contractSpaceError5002(`Contract-space target mismatch for "${spaceId}"`, {
+  return contractSpaceViolationError(`Contract-space target mismatch for "${spaceId}"`, {
     why: `Space "${spaceId}" targets "${actual}" but the project's adapter targets "${expected}".`,
     fix: 'Update the extension descriptor to target the configured database, or change the project adapter.',
     violations: [{ kind: 'targetMismatch', spaceId, expected, actual }],
@@ -89,9 +88,10 @@ function describeIntegrityViolation(violation: IntegrityViolation): string {
 /**
  * Map the integrity violations `checkIntegrity` reports into a single
  * CLI structured-error envelope, preserving the error codes the prior
- * throw-on-load loader emitted: `5001` (layout drift, bundled) and
- * `5002` (target / disjointness / contract-validation / structural
- * integrity). Returns `null` when there is nothing to refuse on.
+ * throw-on-load loader emitted: `MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION`
+ * (layout drift, bundled) and `MIGRATION.CONTRACT_SPACE_VIOLATION` (target /
+ * disjointness / contract-validation / structural integrity). Returns
+ * `null` when there is nothing to refuse on.
  *
  * Precedence reproduces the prior loader's first-failure ordering:
  * layout drift first (every offence bundled into one envelope), then
@@ -113,8 +113,7 @@ export function mapIntegrityViolations(
       layout.length === 1
         ? 'Contract-space layout violation detected'
         : `Contract-space layout violations detected (${layout.length})`;
-    return new CliStructuredError('5001', summary, {
-      domain: 'MIG',
+    return new CliStructuredError('MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION', summary, {
       why: `The on-disk \`migrations/\` directory and your \`extensionPacks\` declaration are not in agreement.\n${lines.join('\n')}`,
       fix: 'Declare the extension in `extensionPacks` and re-emit its contract-space artefacts, or remove the orphan `migrations/<space>` directory.',
       docsUrl: CONTRACT_SPACES_DOCS_URL,
@@ -133,7 +132,7 @@ export function mapIntegrityViolations(
 
   const disjointness = violations.find((v) => v.kind === 'disjointness');
   if (disjointness && disjointness.kind === 'disjointness') {
-    return contractSpaceError5002(
+    return contractSpaceViolationError(
       `Contract-space disjointness violation: storage element "${disjointness.element}" claimed by multiple spaces`,
       {
         why: `Spaces ${disjointness.claimedBy.map((s) => `"${s}"`).join(', ')} all claim the storage element "${disjointness.element}". Each storage element must be owned by exactly one contract space.`,
@@ -145,7 +144,7 @@ export function mapIntegrityViolations(
 
   const contractUnreadable = violations.find((v) => v.kind === 'contractUnreadable');
   if (contractUnreadable && contractUnreadable.kind === 'contractUnreadable') {
-    return contractSpaceError5002(
+    return contractSpaceViolationError(
       `Contract-space contract validation failed for "${contractUnreadable.spaceId}"`,
       {
         why: contractUnreadable.detail,
@@ -160,7 +159,7 @@ export function mapIntegrityViolations(
   // is still computed; the gate just renders one envelope).
   const structural = violations[0]!;
   const spaceId = 'spaceId' in structural ? structural.spaceId : '*';
-  return contractSpaceError5002(`Contract-space integrity failure for "${spaceId}"`, {
+  return contractSpaceViolationError(`Contract-space integrity failure for "${spaceId}"`, {
     why: describeIntegrityViolation(structural),
     fix: 'Re-emit the affected migration package(s) or restore the on-disk `migrations/` directory from version control.',
     violations: [structural],

package/src/utils/contract-space-seed-phase.ts

@@ -2,7 +2,7 @@ import { materialiseExtensionMigrationPackageIfMissing } from '@prisma-next/migr
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import type { MigrationOps } from '@prisma-next/migration-tools/package';
 import {
-  emitContractSpaceArtefacts,
+  emitContractSpaceArtifacts,
   planAllSpaces,
   readContractSpaceHeadRef,
   type SpacePlanOutput,
@@ -53,7 +53,7 @@ export interface ContractSpaceSeedPhaseInputs {
  * - `action: 'unchanged'` — the on-disk head already matched the
  *   descriptor and no new migration packages needed to be written.
  *
- * Either way, the artefacts (`contract.json`, `contract.d.ts`,
+ * Either way, the artifacts (`contract.json`, `contract.d.ts`,
  * `refs/head.json`) are re-emitted: the framework owns those files and
  * makes the re-emit observably idempotent at the byte level.
  */
@@ -75,9 +75,11 @@ export interface ContractSpaceSeedPhaseResult {
  * For every extension that exposes a `contractSpace`:
  *
  * 1. Read the on-disk head ref (returns `null` on first emit).
- * 2. Re-emit `contract.json` / `contract.d.ts` / `refs/head.json`
- *    unconditionally via {@link emitContractSpaceArtefacts}. The
- *    framework owns these files; re-emit is the contract.
+ * 2. Write the head contract into the migrations-root snapshot store
+ *    (write-if-absent, keyed by hash) and unconditionally re-emit
+ *    `refs/head.json`, via {@link emitContractSpaceArtifacts}. The
+ *    framework owns `refs/head.json`; re-emit is the contract for that
+ *    file. The snapshot itself is only written once per distinct hash.
  * 3. Materialise any descriptor-shipped migration packages not yet on
  *    disk via {@link materialiseExtensionMigrationPackageIfMissing}.
  *    Existing packages are left untouched (by-existence skip).
@@ -144,7 +146,7 @@ export async function runContractSpaceSeedPhase(
     const onDiskHeadRef = await readContractSpaceHeadRef(inputs.migrationsDir, space.spaceId);
     const priorHash = onDiskHeadRef?.hash ?? null;
 
-    await emitContractSpaceArtefacts(inputs.migrationsDir, space.spaceId, {
+    await emitContractSpaceArtifacts(inputs.migrationsDir, space.spaceId, {
       contract: descriptor.contractJson,
       contractDts: buildPlaceholderContractDts(space.spaceId),
       headRef: { hash: descriptor.headRef.hash, invariants: descriptor.headRef.invariants },

package/src/utils/formatters/errors.ts

@@ -7,6 +7,25 @@ import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
 import { formatPlannerWarningsBlock } from './migrations';
 
+/**
+ * The display label for a schema-diff issue in the shared error envelope,
+ * derived from which sides are present: expected-only is a missing object,
+ * actual-only an extra one, both a mismatch. `undefined` when the entry is not
+ * a schema-diff issue (it carries neither side) so the caller can fall through
+ * to its generic label.
+ */
+function schemaDiffIssueLabel(issue: {
+  readonly expected?: unknown;
+  readonly actual?: unknown;
+}): 'missing' | 'extra' | 'mismatch' | undefined {
+  const hasExpected = issue.expected !== undefined;
+  const hasActual = issue.actual !== undefined;
+  if (hasExpected && hasActual) return 'mismatch';
+  if (hasExpected) return 'missing';
+  if (hasActual) return 'extra';
+  return undefined;
+}
+
 /**
  * Formats error output for human-readable display.
  */
@@ -51,13 +70,15 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
   // Show issues list if present (always show a short list; show full list when verbose).
   // `issues` is a shared error-envelope field: PSL interpretation diagnostics stamp
   // `kind` and `message` (their diagnostic code and prose); schema-diff issues
-  // (`SchemaDiffIssue`) carry no `message` and stamp `reason` and `path` instead.
+  // (`SchemaDiffIssue`) carry no `message` and stamp `path` plus the
+  // `expected`/`actual` presence a label is derived from.
   if (error.meta?.['issues']) {
     const issues = error.meta['issues'] as readonly {
       kind?: string;
-      reason?: string;
       message?: string;
       path?: readonly string[];
+      expected?: unknown;
+      actual?: unknown;
     }[];
     if (issues.length > 0) {
       const maxToShow = isVerbose(flags, 1) ? issues.length : Math.min(3, issues.length);
@@ -66,7 +87,7 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
         : `  Issues (showing ${maxToShow} of ${issues.length}):`;
       lines.push(`${formatDimText(header)}`);
       for (const issue of issues.slice(0, maxToShow)) {
-        const label = issue.kind ?? issue.reason ?? 'issue';
+        const label = issue.kind ?? schemaDiffIssueLabel(issue) ?? 'issue';
         const message = issue.message ?? issue.path?.join('/') ?? '';
         lines.push(`${formatDimText(`    - [${label}] ${message}`)}`);
       }

package/src/utils/formatters/verify.ts

@@ -8,13 +8,14 @@ import type {
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
+import { issueOutcome } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { bold, cyan, dim, green, magenta, red, yellow } from 'colorette';
 import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
 
-/** Human-readable label for each failure reason, prefixed onto an issue's message for display. */
-const REASON_LABEL: Record<ExpectationFailureReason, string> = {
+/** Human-readable label for each outcome, prefixed onto an issue's message for display. */
+const OUTCOME_LABEL: Record<ExpectationFailureReason, string> = {
   'not-found': 'missing',
   'not-expected': 'extra',
   'not-equal': 'mismatch',
@@ -22,12 +23,12 @@ const REASON_LABEL: Record<ExpectationFailureReason, string> = {
 
 /**
  * The issue's display text: its own path, prefixed with a human label for
- * why it's flagged. Turning `reason` (and the path) into prose is this
- * formatter's job, not the differ's — the differ's issue is data (`path` +
- * `reason` + nodes), not prose.
+ * why it's flagged. Turning the presence-derived outcome (and the path) into
+ * prose is this formatter's job, not the differ's — the differ's issue is
+ * data (`path` + nodes), not prose.
  */
 function formatIssueMessage(issue: SchemaDiffIssue): string {
-  return `${REASON_LABEL[issue.reason]}: ${issue.path.join('/')}`;
+  return `${OUTCOME_LABEL[issueOutcome(issue)]}: ${issue.path.join('/')}`;
 }
 
 // ============================================================================