@prisma-next/cli 0.16.0-dev.3 → 0.16.0-dev.30

package/src/commands/migration-show.ts

@@ -119,7 +119,7 @@ async function executeMigrationShowCommand(
     target: config.target,
     adapter: config.adapter,
     ...ifDefined('driver', config.driver),
-    extensionPacks: config.extensionPacks ?? [],
+    extensions: config.extensions ?? [],
   });
 
   let contractJsonContent: string;
@@ -228,7 +228,7 @@ export function createMigrationShowCommand(): Command {
   );
   setCommandExamples(command, [
     'prisma-next migration show 20260101_100000_add_user',
-    'prisma-next migration show sha256:a1b2c3',
+    'prisma-next migration show a1b2c3',
     'prisma-next migration show 20260101_100000_add_user --json',
   ]);
   setCommandSeeAlso(command, [

package/src/commands/migration-status.ts

@@ -111,8 +111,7 @@ interface MigrationStatusCommandResult {
 }
 
 function shortDisplayHash(hash: string): string {
-  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
-  return stripped.slice(0, 12);
+  return hash.slice(0, 12);
 }
 
 function resolveTarget(contractHash: string, activeRefHash: string | undefined): string {
@@ -421,7 +420,7 @@ export async function executeMigrationStatusCommand(
       target: config.target,
       adapter: config.adapter,
       driver: config.driver,
-      extensionPacks: config.extensionPacks ?? [],
+      extensions: config.extensions ?? [],
     });
     try {
       await client.connect(dbConnection);
@@ -660,10 +659,10 @@ export function createMigrationStatusCommand(): Command {
   setCommandExamples(command, [
     'prisma-next migration status --db $DATABASE_URL',
     'prisma-next migration status --to production --db $DATABASE_URL',
-    'prisma-next migration status --from sha256:abc --to production',
-    'prisma-next migration status --from sha256:abc --to production --json',
-    'prisma-next migration status --ascii --from sha256:abc --to production',
-    'prisma-next migration status --legend --from sha256:abc --to production',
+    'prisma-next migration status --from abc123 --to production',
+    'prisma-next migration status --from abc123 --to production --json',
+    'prisma-next migration status --ascii --from abc123 --to production',
+    'prisma-next migration status --legend --from abc123 --to production',
   ]);
   setCommandSeeAlso(command, [
     { verb: 'migration log', oneLiner: 'Show executed migration history' },

package/src/commands/ref.ts

@@ -1,16 +1,19 @@
-import { readFile } from 'node:fs/promises';
 import { loadConfig } from '@prisma-next/config-loader';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import {
+  contractSnapshotDir,
+  readContractSnapshotJson,
+} from '@prisma-next/migration-tools/contract-snapshot-store';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { findLatestMigration, isGraphNode } from '@prisma-next/migration-tools/migration-graph';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import {
-  deleteRefPaired,
+  deleteRef,
   readRefs,
   validateRefName,
   validateRefValue,
-  writeRefPaired,
+  writeRef,
 } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -34,7 +37,6 @@ import {
 import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatCommandHelp } from '../utils/formatters/help';
 import { parseGlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
-import { readContractIR } from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI } from '../utils/terminal-ui';
 
@@ -114,26 +116,29 @@ export async function executeRefSetCommand(
       return notOk(errorRefSetBundleNotFound(resolvedHash));
     }
 
-    const contractJsonPath = join(matchingBundle.dirPath, 'end-contract.json');
-    let contractJson: Record<string, unknown>;
+    const contractJsonPath = join(
+      contractSnapshotDir(migrationsDir, resolvedHash),
+      'contract.json',
+    );
     try {
-      const raw = await readFile(contractJsonPath, 'utf-8');
-      contractJson = JSON.parse(raw) as Record<string, unknown>;
+      await readContractSnapshotJson(migrationsDir, resolvedHash);
     } catch (readError) {
-      if (readError instanceof Error && (readError as NodeJS.ErrnoException).code === 'ENOENT') {
+      if (
+        MigrationToolsError.is(readError) &&
+        readError.code === 'MIGRATION.CONTRACT_SNAPSHOT_MISSING'
+      ) {
         return notOk(
           errorFileNotFound(contractJsonPath, {
-            why: `Migration bundle for hash ${resolvedHash} is missing its end-contract snapshot at ${contractJsonPath}`,
-            fix: 'Run `pnpm fixtures:check`, or re-emit the migration so its end-contract.json is restored.',
+            why: `Migration bundle for hash ${resolvedHash} is missing its contract snapshot at ${contractJsonPath}`,
+            fix: 'Restore migrations/snapshots/ from version control, or re-run the command that produced this migration to regenerate its snapshot.',
           }),
         );
       }
       throw readError;
     }
 
-    const contractIR = await readContractIR(contractJson, contractJsonPath);
     const entry: RefEntry = { hash: resolvedHash, invariants: [] };
-    await writeRefPaired(refsDir, name, entry, contractIR);
+    await writeRef(refsDir, name, entry);
     return ok({ ok: true as const, ref: name, hash: resolvedHash, invariants: [] });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
@@ -148,7 +153,7 @@ export async function executeRefDeleteCommand(
   try {
     const config = await loadConfig(options.config);
     const { refsDir } = resolveMigrationPaths(options.config, config);
-    await deleteRefPaired(refsDir, name);
+    await deleteRef(refsDir, name);
     return ok({ ok: true as const, ref: name, deleted: true as const });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);

package/src/control-api/client.ts

@@ -103,7 +103,7 @@ class ControlClientImpl implements ControlClient {
       target: this.options.target,
       adapter: this.options.adapter,
       driver: this.options.driver,
-      extensionPacks: this.options.extensionPacks,
+      extensions: this.options.extensions,
     });
 
     this.familyInstance = this.options.family.create(this.stack);
@@ -112,7 +112,7 @@ class ControlClientImpl implements ControlClient {
     const rawComponents = [
       this.options.target,
       this.options.adapter,
-      ...(this.options.extensionPacks ?? []),
+      ...(this.options.extensions ?? []),
     ];
     this.frameworkComponents = assertFrameworkComponentsCompatible(
       this.options.family.familyId,
@@ -404,7 +404,7 @@ class ControlClientImpl implements ControlClient {
       frameworkComponents,
       migrationsDir: options.migrationsDir,
       targetId: this.options.target.targetId,
-      extensionPacks: this.options.extensionPacks ?? [],
+      extensions: this.options.extensions ?? [],
       ...ifDefined('onProgress', onProgress),
     });
   }
@@ -438,7 +438,7 @@ class ControlClientImpl implements ControlClient {
       frameworkComponents,
       migrationsDir: options.migrationsDir,
       targetId: this.options.target.targetId,
-      extensionPacks: this.options.extensionPacks ?? [],
+      extensions: this.options.extensions ?? [],
       ...ifDefined('acceptDataLoss', options.acceptDataLoss),
       ...ifDefined('onProgress', onProgress),
     });
@@ -455,7 +455,7 @@ class ControlClientImpl implements ControlClient {
       contract: options.contract,
       migrationsDir: options.migrationsDir,
       targetId: this.options.target.targetId,
-      extensionPacks: this.options.extensionPacks ?? [],
+      extensions: this.options.extensions ?? [],
       frameworkComponents,
       mode: options.strict ? 'strict' : 'lenient',
       skipSchema: options.skipSchema,
@@ -508,7 +508,7 @@ class ControlClientImpl implements ControlClient {
       migrations: this.options.target.migrations,
       frameworkComponents,
       migrationsDir: options.migrationsDir,
-      extensionPacks: this.options.extensionPacks ?? [],
+      extensions: this.options.extensions ?? [],
       targetId: this.options.target.targetId,
       ...ifDefined('refHash', options.refHash),
       ...ifDefined('refInvariants', options.refInvariants),
@@ -607,9 +607,8 @@ class ControlClientImpl implements ControlClient {
     try {
       const stack = this.stack!;
       const sourceContext = {
-        composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
+        composedExtensions: stack.extensions.map((p) => p.id),
         composedExtensionContracts: stack.extensionContracts,
-        scalarTypeDescriptors: stack.scalarTypeDescriptors,
         authoringContributions: stack.authoringContributions,
         codecLookup: stack.codecLookup,
         controlMutationDefaults: stack.controlMutationDefaults,

package/src/control-api/contract-enrichment.ts

@@ -65,21 +65,21 @@ export function enrichContract(
 ): Contract {
   const mergedCapabilities = mergeCapabilityMatrices(ir.capabilities, components);
 
-  const extensionPacksMeta: Record<string, unknown> = {};
+  const extensionsMeta: Record<string, unknown> = {};
   for (const component of components) {
     if (component.kind === 'extension') {
-      extensionPacksMeta[component.id] = extractExtensionPackMeta(component);
+      extensionsMeta[component.id] = extractExtensionPackMeta(component);
     }
   }
 
-  const extensionPacks =
-    Object.keys(extensionPacksMeta).length > 0
-      ? { ...ir.extensionPacks, ...extensionPacksMeta }
-      : ir.extensionPacks;
+  const extensions =
+    Object.keys(extensionsMeta).length > 0
+      ? { ...ir.extensions, ...extensionsMeta }
+      : ir.extensions;
 
   return {
     ...ir,
     capabilities: sortDeepTyped(mergedCapabilities),
-    extensionPacks: sortDeepTyped(extensionPacks),
+    extensions: sortDeepTyped(extensions),
   };
 }

package/src/control-api/operations/contract-emit.ts

@@ -195,9 +195,8 @@ export async function executeContractEmit(
     const stack = createControlStack(config);
 
     const sourceContext = {
-      composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
+      composedExtensions: stack.extensions.map((p) => p.id),
       composedExtensionContracts: stack.extensionContracts,
-      scalarTypeDescriptors: stack.scalarTypeDescriptors,
       authoringContributions: stack.authoringContributions,
       codecLookup: stack.codecLookup,
       controlMutationDefaults: stack.controlMutationDefaults,
@@ -231,7 +230,7 @@ export async function executeContractEmit(
     let emitResult: Awaited<ReturnType<typeof emit>>;
     try {
       const familyInstance = config.family.create(stack);
-      const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+      const rawComponents = [config.target, config.adapter, ...(config.extensions ?? [])];
       const frameworkComponents = assertFrameworkComponentsCompatible(
         config.family.familyId,
         config.target.targetId,

package/src/control-api/operations/db-init.ts

@@ -25,7 +25,7 @@ import { executeRun } from './db-run';
  * 3. The runner's `execute` applies the per-space plans
  *    inside one outer transaction.
  *
- * `extensionPacks` mirrors `Config.extensionPacks` (descriptor list).
+ * `extensions` mirrors `Config.extensions` (descriptor list).
  * The loader (sub-spec § Loader) is the sole descriptor-import boundary.
  */
 export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extends string> {
@@ -55,7 +55,7 @@ export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extend
    * routes through the same loader → planner → runner pipeline with no
    * extension spaces in the aggregate.
    */
-  readonly extensionPacks?: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly extensions?: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
@@ -80,7 +80,7 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
     frameworkComponents: options.frameworkComponents,
     migrationsDir: options.migrationsDir,
     targetId: options.targetId,
-    extensionPacks: options.extensionPacks ?? [],
+    extensions: options.extensions ?? [],
     policy: { allowedOperationClasses: ['additive'] },
     action: 'dbInit',
     ...ifDefined('onProgress', options.onProgress),

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

@@ -80,7 +80,7 @@ export interface ExecuteRunOptions<TFamilyId extends string, TTargetId extends s
   >;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
   readonly migrationsDir: string;
-  readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly extensions: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   readonly targetId: TTargetId;
   readonly policy: MigrationOperationPolicy;
   readonly action: 'dbInit' | 'dbUpdate';
@@ -119,7 +119,7 @@ export async function executeRun<TFamilyId extends string, TTargetId extends str
     migrations,
     frameworkComponents,
     migrationsDir,
-    extensionPacks,
+    extensions,
     targetId,
     policy,
     action,
@@ -131,7 +131,7 @@ export async function executeRun<TFamilyId extends string, TTargetId extends str
     targetId,
     migrationsDir,
     appContract: contract,
-    extensionPacks,
+    extensions,
     deserializeContract: (json) => familyInstance.deserializeContract(json),
   };
   const loaded = await buildContractSpaceAggregate(loadInputs);
@@ -283,7 +283,7 @@ function aggregatePlannerWarnings(
  * Compare the live `_prisma_marker` rows against the aggregate's
  * declared contract spaces. Any marker row whose `space` is not a space of
  * the aggregate is an "orphan" — typically a marker left behind by
- * an extension that was removed from `extensionPacks` without first
+ * an extension that was removed from `extensions` without first
  * cleaning up its on-disk migrations / database tables.
  *
  * Returns a {@link CliStructuredError} envelope (code
@@ -319,8 +319,8 @@ function detectOrphanMarkers(
       .map((s) => `"${s}"`)
       .join(
         ', ',
-      )}) that are not declared in the project's \`extensionPacks\`. The aggregate pipeline refuses to advance markers it cannot account for.`,
-    fix: 'Either re-declare the missing extension(s) in `extensionPacks` (so the aggregate owns them again), or remove the orphan marker row(s) from `_prisma_marker` once you have confirmed the corresponding tables can be safely retired.',
+      )}) that are not declared in the project's \`extensions\`. The aggregate pipeline refuses to advance markers it cannot account for.`,
+    fix: 'Either re-declare the missing extension(s) in `extensions` (so the aggregate owns them again), or remove the orphan marker row(s) from `_prisma_marker` once you have confirmed the corresponding tables can be safely retired.',
     docsUrl: 'https://pris.ly/contract-spaces',
     meta: {
       violations: orphans.map((spaceId) => ({ kind: 'orphanMarker', spaceId })),

package/src/control-api/operations/db-update.ts

@@ -40,7 +40,7 @@ export interface ExecuteDbUpdateOptions<TFamilyId extends string, TTargetId exte
   readonly acceptDataLoss?: boolean;
   readonly migrationsDir: string;
   readonly targetId: TTargetId;
-  readonly extensionPacks?: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly extensions?: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   readonly onProgress?: OnControlProgress;
 }
 
@@ -65,7 +65,7 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
     frameworkComponents: options.frameworkComponents,
     migrationsDir: options.migrationsDir,
     targetId: options.targetId,
-    extensionPacks: options.extensionPacks ?? [],
+    extensions: options.extensions ?? [],
     policy: DB_UPDATE_POLICY,
     action: 'dbUpdate' as const,
     ...ifDefined('onProgress', options.onProgress),

package/src/control-api/operations/db-verify.ts

@@ -50,7 +50,7 @@ export interface ExecuteDbVerifyOptions<TFamilyId extends string, TTargetId exte
   readonly contract: Contract;
   readonly migrationsDir: string;
   readonly targetId: TTargetId;
-  readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly extensions: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
   readonly mode: 'strict' | 'lenient';
   readonly skipSchema: boolean;
@@ -149,7 +149,7 @@ function buildLoadInputs<TFamilyId extends string, TTargetId extends string>(
     targetId: options.targetId,
     migrationsDir: options.migrationsDir,
     appContract: options.contract,
-    extensionPacks: options.extensionPacks,
+    extensions: options.extensions,
     deserializeContract: (json) => options.familyInstance.deserializeContract(json),
   };
 }
@@ -349,7 +349,7 @@ function mapMarkerCheckFailures(
     violations.push({
       kind: 'orphanMarker',
       spaceId: orphan.spaceId,
-      remediation: `Add the corresponding extension to \`extensionPacks\` in \`prisma-next.config.ts\`, or delete the orphan marker row for "${orphan.spaceId}".`,
+      remediation: `Add the corresponding extension to \`extensions\` in \`prisma-next.config.ts\`, or delete the orphan marker row for "${orphan.spaceId}".`,
     });
   }
   if (violations.length === 0) return null;
@@ -359,7 +359,7 @@ function mapMarkerCheckFailures(
       ? 'Contract-space verifier found a violation'
       : `Contract-space verifier found violations (${violations.length})`;
   return new CliStructuredError('MIGRATION.CONTRACT_SPACE_VIOLATION', summary, {
-    why: `The on-disk \`migrations/\` directory, the \`extensionPacks\` declaration, and the live database marker rows are not in agreement.\n${lines.join('\n')}`,
+    why: `The on-disk \`migrations/\` directory, the \`extensions\` declaration, and the live database marker rows are not in agreement.\n${lines.join('\n')}`,
     fix: violations[0]?.remediation ?? 'Review and reconcile the violations listed above.',
     docsUrl: 'https://pris.ly/contract-spaces',
     meta: { violations },

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

@@ -1,8 +1,9 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { EOL } from 'node:os';
 import { loadConfig } from '@prisma-next/config-loader';
-import { type FormatOptions, format, PslFormatError } from '@prisma-next/psl-parser/format';
+import { type FormatOptions, format } from '@prisma-next/psl-parser/format';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { isStructuredError } from '@prisma-next/utils/structured-error';
 import { CliStructuredError, errorRuntime, errorUnexpected } from '../../utils/cli-errors';
 
 export interface FormatOperationOptions {
@@ -41,7 +42,7 @@ export async function executeFormat(
   }
 
   const source = config.contract?.source;
-  if (source?.sourceFormat !== 'psl') {
+  if (source?.format !== 'psl') {
     return ok({ formatted: false });
   }
 
@@ -71,12 +72,12 @@ export async function executeFormat(
   try {
     formatted = format(contents, formatOptions);
   } catch (error) {
-    if (error instanceof PslFormatError) {
+    if (isStructuredError(error) && error.code === 'PSL.PARSE_FAILED') {
       return notOk(
         errorRuntime('Cannot format PSL with parse errors', {
           why: error.message,
           fix: 'Fix the parse errors in your schema and try again.',
-          meta: { diagnostics: error.diagnostics },
+          meta: { diagnostics: error.meta?.['diagnostics'] },
         }),
       );
     }

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

@@ -60,7 +60,7 @@ export interface ExecuteMigrateOptions<TFamilyId extends string, TTargetId exten
   >;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
   readonly migrationsDir: string;
-  readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly extensions: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   readonly targetId: TTargetId;
   /**
    * Optional app-space ref override. When provided, the app space's
@@ -122,7 +122,7 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
     migrations,
     frameworkComponents,
     migrationsDir,
-    extensionPacks,
+    extensions,
     targetId,
     refHash,
     refInvariants,
@@ -134,7 +134,7 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
     targetId,
     migrationsDir,
     appContract: contract,
-    extensionPacks,
+    extensions,
     deserializeContract: (json) => familyInstance.deserializeContract(json),
   };
   const loaded = await buildContractSpaceAggregate(loadInputs);

package/src/control-api/types.ts

@@ -52,7 +52,7 @@ export interface ControlClientOptions {
   // biome-ignore lint/suspicious/noExplicitAny: required for contravariance in driver.create()
   readonly driver?: ControlDriverDescriptor<any, any, any, any>;
   // biome-ignore lint/suspicious/noExplicitAny: required for contravariance in extension.create()
-  readonly extensionPacks?: ReadonlyArray<ControlExtensionDescriptor<any, any, any>>;
+  readonly extensions?: ReadonlyArray<ControlExtensionDescriptor<any, any, any>>;
   /**
    * Optional default connection for auto-connect.
    * When provided, operations will auto-connect if not already connected.

package/src/utils/cli-errors.ts

@@ -10,7 +10,7 @@ import {
   errorConfigFileNotFound,
   errorConfigValidation,
   errorContractConfigMissing,
-  errorContractMissingExtensionPacks,
+  errorContractMissingExtensions,
   errorContractValidationFailed,
   errorDatabaseConnectionRequired,
   errorDriverRequired,
@@ -54,7 +54,7 @@ export {
   errorConfigFileNotFound,
   errorConfigValidation,
   errorContractConfigMissing,
-  errorContractMissingExtensionPacks,
+  errorContractMissingExtensions,
   errorContractValidationFailed,
   errorDatabaseConnectionRequired,
   errorDriverRequired,
@@ -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',

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

@@ -114,8 +114,8 @@ export function mapIntegrityViolations(
         ? 'Contract-space layout violation detected'
         : `Contract-space layout violations detected (${layout.length})`;
     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.',
+      why: `The on-disk \`migrations/\` directory and your \`extensions\` declaration are not in agreement.\n${lines.join('\n')}`,
+      fix: 'Declare the extension in `extensions` and re-emit its contract-space artefacts, or remove the orphan `migrations/<space>` directory.',
       docsUrl: CONTRACT_SPACES_DOCS_URL,
       meta: { violations: layout },
     });
@@ -177,14 +177,14 @@ export interface BuildAggregateInputs<TFamilyId extends string, TTargetId extend
   readonly targetId: TTargetId;
   readonly migrationsDir: string;
   readonly appContract: Contract;
-  readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly extensions: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   readonly deserializeContract: (contractJson: unknown) => Contract;
 }
 
 function declaredExtensionsFromInputs(
-  extensionPacks: BuildAggregateInputs<string, string>['extensionPacks'],
+  extensions: BuildAggregateInputs<string, string>['extensions'],
 ): readonly DeclaredExtensionEntry[] {
-  return toDeclaredExtensionsFromRaw(extensionPacks as ReadonlyArray<unknown>);
+  return toDeclaredExtensionsFromRaw(extensions as ReadonlyArray<unknown>);
 }
 
 /**
@@ -195,7 +195,7 @@ export function refuseDeclaredExtensionTargetMismatch<
   TFamilyId extends string,
   TTargetId extends string,
 >(inputs: BuildAggregateInputs<TFamilyId, TTargetId>): CliStructuredError | null {
-  for (const declared of declaredExtensionsFromInputs(inputs.extensionPacks)) {
+  for (const declared of declaredExtensionsFromInputs(inputs.extensions)) {
     if (declared.targetId !== inputs.targetId) {
       return targetMismatchError(declared.id, inputs.targetId, declared.targetId);
     }
@@ -271,7 +271,7 @@ export async function buildContractSpaceAggregate<
 >(
   inputs: BuildAggregateInputs<TFamilyId, TTargetId>,
 ): Promise<Result<ContractSpaceAggregate, CliStructuredError>> {
-  const declaredExtensions = declaredExtensionsFromInputs(inputs.extensionPacks);
+  const declaredExtensions = declaredExtensionsFromInputs(inputs.extensions);
   const loaded = await loadContractSpaceAggregateForCli(inputs);
   if (!loaded.ok) {
     return loaded;
@@ -375,7 +375,7 @@ export async function buildReadAggregate(
       targetId: config.target.id,
       migrationsDir: options.migrationsDir,
       appContract: appContractForLoad,
-      extensionPacks: config.extensionPacks ?? [],
+      extensions: config.extensions ?? [],
       deserializeContract,
     });
     if (!loaded.ok) {