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

package/src/load-ts-contract.ts

@@ -2,6 +2,8 @@ import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import type { Contract } from '@prisma-next/contract/types';
+import { CliStructuredError } from '@prisma-next/errors/control';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import type { Plugin } from 'esbuild';
 import { build } from 'esbuild';
 import { join, resolve as resolvePath } from 'pathe';
@@ -10,6 +12,30 @@ export interface LoadTsContractOptions {
   readonly allowlist?: ReadonlyArray<string>;
 }
 
+type ContractSourceErrorCode =
+  | 'CONTRACT.EXPORT_INVALID'
+  | 'CONTRACT.SOURCE_LOAD_FAILED'
+  | 'CONTRACT.SOURCE_IMPORT_DISALLOWED';
+
+function contractSourceError(
+  code: ContractSourceErrorCode,
+  message: string,
+  options?: {
+    readonly meta?: Record<string, unknown>;
+    readonly cause?: unknown;
+  },
+): CliStructuredError {
+  const error = new CliStructuredError(
+    code,
+    message,
+    options?.meta !== undefined ? { meta: options.meta } : undefined,
+  );
+  if (options?.cause !== undefined) {
+    error.cause = options.cause;
+  }
+  return error;
+}
+
 const DEFAULT_ALLOWLIST = ['@prisma-next/*', 'node:crypto'];
 
 function isAllowedImport(importPath: string, allowlist: ReadonlyArray<string>): boolean {
@@ -31,7 +57,7 @@ function isAllowedImport(importPath: string, allowlist: ReadonlyArray<string>):
   return false;
 }
 
-function validatePurity(value: unknown): void {
+function validatePurity(value: unknown, entryPath: string): void {
   if (typeof value !== 'object' || value === null) {
     return;
   }
@@ -44,7 +70,11 @@ function validatePurity(value: unknown): void {
     }
 
     if (path.has(value)) {
-      throw new Error('Contract export contains circular references');
+      throw contractSourceError(
+        'CONTRACT.EXPORT_INVALID',
+        'Contract export contains circular references',
+        { meta: { path: entryPath, reason: 'circular' } },
+      );
     }
     path.add(value);
 
@@ -52,10 +82,18 @@ function validatePurity(value: unknown): void {
       for (const key in value) {
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
         if (descriptor && (descriptor.get || descriptor.set)) {
-          throw new Error(`Contract export contains getter/setter at key "${key}"`);
+          throw contractSourceError(
+            'CONTRACT.EXPORT_INVALID',
+            `Contract export contains getter/setter at key "${key}"`,
+            { meta: { path: entryPath, reason: 'getter', key } },
+          );
         }
         if (descriptor && typeof descriptor.value === 'function') {
-          throw new Error(`Contract export contains function at key "${key}"`);
+          throw contractSourceError(
+            'CONTRACT.EXPORT_INVALID',
+            `Contract export contains function at key "${key}"`,
+            { meta: { path: entryPath, reason: 'function', key } },
+          );
         }
         check((value as Record<string, unknown>)[key]);
       }
@@ -72,9 +110,17 @@ function validatePurity(value: unknown): void {
       if (error.message.includes('getter') || error.message.includes('circular')) {
         throw error;
       }
-      throw new Error(`Contract export is not JSON-serializable: ${error.message}`);
+      throw contractSourceError(
+        'CONTRACT.EXPORT_INVALID',
+        `Contract export is not JSON-serializable: ${error.message}`,
+        { meta: { path: entryPath, reason: 'not-json-serializable' }, cause: error },
+      );
     }
-    throw new Error('Contract export is not JSON-serializable');
+    throw contractSourceError(
+      'CONTRACT.EXPORT_INVALID',
+      'Contract export is not JSON-serializable',
+      { meta: { path: entryPath, reason: 'not-json-serializable' } },
+    );
   }
 }
 
@@ -129,7 +175,8 @@ function createImportAllowlistPlugin(
  * @param entryPath - Path to the TypeScript contract file
  * @param options - Optional configuration (import allowlist)
  * @returns The contract as Contract (should already be normalized)
- * @throws Error if the contract cannot be loaded or is not JSON-serializable
+ * @throws structured errors: `CLI.FILE_NOT_FOUND`, `CONTRACT.SOURCE_LOAD_FAILED`,
+ *   `CONTRACT.SOURCE_IMPORT_DISALLOWED`, `CONTRACT.MODULE_EXPORT_MISSING`, `CONTRACT.EXPORT_INVALID`
  */
 export async function loadContractFromTs(
   entryPath: string,
@@ -138,7 +185,9 @@ export async function loadContractFromTs(
   const allowlist = options?.allowlist ?? DEFAULT_ALLOWLIST;
 
   if (!existsSync(entryPath)) {
-    throw new Error(`Contract file not found: ${entryPath}`);
+    throw new CliStructuredError('CLI.FILE_NOT_FOUND', `Contract file not found: ${entryPath}`, {
+      where: { path: entryPath },
+    });
   }
 
   const tempFile = join(
@@ -169,22 +218,28 @@ export async function loadContractFromTs(
 
     if (result.errors.length > 0) {
       const errorMessages = result.errors.map((e: { text: string }) => e.text).join('\n');
-      throw new Error(`Failed to bundle contract file: ${errorMessages}`);
+      throw contractSourceError(
+        'CONTRACT.SOURCE_LOAD_FAILED',
+        `Failed to bundle contract file: ${errorMessages}`,
+        { meta: { path: entryPath, stage: 'bundle' } },
+      );
     }
 
     if (!result.outputFiles || result.outputFiles.length === 0) {
-      throw new Error('No output files generated from bundling');
+      throw new InternalError('No output files generated from bundling');
     }
 
     if (disallowedFromEntry.size > 0) {
-      throw new Error(
+      throw contractSourceError(
+        'CONTRACT.SOURCE_IMPORT_DISALLOWED',
         `Disallowed imports detected. Only imports matching the allowlist are permitted:\n  Allowlist: ${allowlist.join(', ')}\n  Disallowed imports: ${[...disallowedFromEntry].join(', ')}`,
+        { meta: { allowlist: [...allowlist], disallowed: [...disallowedFromEntry] } },
       );
     }
 
     const bundleContent = result.outputFiles[0]?.text;
     if (bundleContent === undefined) {
-      throw new Error('Bundle content is undefined');
+      throw new InternalError('Bundle content is undefined');
     }
     writeFileSync(tempFile, bundleContent, 'utf-8');
 
@@ -201,16 +256,22 @@ export async function loadContractFromTs(
     } else if (module.contract !== undefined) {
       contract = module.contract;
     } else {
-      throw new Error(
+      throw new CliStructuredError(
+        'CONTRACT.MODULE_EXPORT_MISSING',
         `Contract file must export a contract as default export or named export 'contract'. Found exports: ${Object.keys(module as Record<string, unknown>).join(', ') || 'none'}`,
+        { where: { path: entryPath } },
       );
     }
 
     if (typeof contract !== 'object' || contract === null) {
-      throw new Error(`Contract export must be an object, got ${typeof contract}`);
+      throw contractSourceError(
+        'CONTRACT.EXPORT_INVALID',
+        `Contract export must be an object, got ${typeof contract}`,
+        { meta: { path: entryPath, reason: 'not-object' } },
+      );
     }
 
-    validatePurity(contract);
+    validatePurity(contract, entryPath);
 
     // Blind cast: the loaded module was authored by user code
     // (typically via `defineContract` / a contract builder) and
@@ -233,6 +294,10 @@ export async function loadContractFromTs(
     if (error instanceof Error) {
       throw error;
     }
-    throw new Error(`Failed to load contract from ${entryPath}: ${String(error)}`);
+    throw contractSourceError(
+      'CONTRACT.SOURCE_LOAD_FAILED',
+      `Failed to load contract from ${entryPath}: ${String(error)}`,
+      { meta: { path: entryPath, stage: 'import' }, cause: error },
+    );
   }
 }

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/combine-verify-results.ts

@@ -1,4 +1,5 @@
 import type { VerifyDatabaseSchemaResult } from '@prisma-next/framework-components/control';
+import { InternalError } from '@prisma-next/utils/internal-error';
 
 /**
  * The combined per-space contract-satisfaction result plus the standalone
@@ -42,7 +43,7 @@ export function combineVerifyResults(
 ): CombinedVerifyResult {
   const appResult = perSpace.get(appSpaceId) ?? perSpace.values().next().value;
   if (appResult === undefined) {
-    throw new Error(
+    throw new InternalError(
       'Aggregate verifier returned no per-space verify results — this is a wiring bug.',
     );
   }

package/src/utils/command-helpers.ts

@@ -8,7 +8,7 @@ import { APP_SPACE_ID, spaceMigrationDirectory } from '@prisma-next/migration-to
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
 import { relative, resolve } from 'pathe';
-import { errorRuntime } from './cli-errors';
+import { CliStructuredError, errorRuntime } from './cli-errors';
 import { formatCommandHelp } from './formatters/help';
 import type { CommonCommandOptions } from './global-flags';
 import { parseGlobalFlags } from './global-flags';
@@ -263,21 +263,31 @@ export async function readContractEnvelope(config: {
   const storageHash = storage?.['storageHash'];
 
   if (typeof storageHash !== 'string') {
-    throw new Error(
+    throw new CliStructuredError(
+      'CONTRACT.VALIDATION_FAILED',
       `Contract at ${relative(process.cwd(), contractPath)} is missing a valid storage.storageHash. Run \`prisma-next contract emit\` to regenerate.`,
+      { where: { path: contractPath } },
     );
   }
   if (typeof schemaVersion !== 'string') {
-    throw new Error(
+    throw new CliStructuredError(
+      'CONTRACT.VALIDATION_FAILED',
       `Contract at ${relative(process.cwd(), contractPath)} is missing schemaVersion.`,
+      { where: { path: contractPath } },
     );
   }
   if (typeof target !== 'string') {
-    throw new Error(`Contract at ${relative(process.cwd(), contractPath)} is missing target.`);
+    throw new CliStructuredError(
+      'CONTRACT.VALIDATION_FAILED',
+      `Contract at ${relative(process.cwd(), contractPath)} is missing target.`,
+      { where: { path: contractPath } },
+    );
   }
   if (typeof targetFamily !== 'string') {
-    throw new Error(
+    throw new CliStructuredError(
+      'CONTRACT.VALIDATION_FAILED',
       `Contract at ${relative(process.cwd(), contractPath)} is missing targetFamily.`,
+      { where: { path: contractPath } },
     );
   }
 

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) {

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,
@@ -39,7 +39,7 @@ export interface SeedPhaseExtensionInput {
 
 export interface ContractSpaceSeedPhaseInputs {
   readonly migrationsDir: string;
-  readonly extensionPacks: ReadonlyArray<SeedPhaseExtensionInput>;
+  readonly extensions: ReadonlyArray<SeedPhaseExtensionInput>;
 }
 
 /**
@@ -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).
@@ -96,7 +98,7 @@ export interface ContractSpaceSeedPhaseResult {
 export async function runContractSpaceSeedPhase(
   inputs: ContractSpaceSeedPhaseInputs,
 ): Promise<ContractSpaceSeedPhaseResult> {
-  const planInputs = inputs.extensionPacks
+  const planInputs = inputs.extensions
     .filter(
       (
         pack,
@@ -132,7 +134,7 @@ export async function runContractSpaceSeedPhase(
     string,
     NonNullable<SeedPhaseExtensionInput['contractSpace']>
   >();
-  for (const pack of inputs.extensionPacks) {
+  for (const pack of inputs.extensions) {
     if (pack.contractSpace !== undefined) descriptorBySpace.set(pack.id, pack.contractSpace);
   }
 
@@ -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/extension-pack-inputs.ts

@@ -1,5 +1,5 @@
 /**
- * Single descriptor-import boundary for CLI consumers of `Config.extensionPacks`.
+ * Single descriptor-import boundary for CLI consumers of `Config.extensions`.
  *
  * Every CLI command / utility that reads an extension descriptor's
  * `contractSpace` projection (loader, migrate-pass, extension-migrations
@@ -54,9 +54,9 @@ export interface ExtensionPackInput {
 }
 
 /**
- * Structural shape we read off each `Config.extensionPacks` entry.
+ * Structural shape we read off each `Config.extensions` entry.
  *
- * The CLI is the descriptor-import boundary; `extensionPacks` is the only
+ * The CLI is the descriptor-import boundary; `extensions` 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
@@ -76,14 +76,14 @@ type ExtensionPackLike = {
 };
 
 /**
- * Project the CLI's `Config.extensionPacks` array into the canonical
+ * Project the CLI's `Config.extensions` 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>,
+  extensions: ReadonlyArray<unknown>,
 ): readonly ExtensionPackInput[] {
-  return extensionPacks.map((raw) => {
+  return extensions.map((raw) => {
     const pack = raw as ExtensionPackLike;
     if (pack.contractSpace === undefined) {
       return { id: pack.id, targetId: pack.targetId };
@@ -147,10 +147,10 @@ export function toDeclaredExtensions(
  * always reads the contract from on-disk artefacts instead.
  */
 export function toDeclaredExtensionsFromRaw(
-  extensionPacks: ReadonlyArray<unknown>,
+  extensions: ReadonlyArray<unknown>,
 ): readonly DeclaredExtensionEntry[] {
   const entries: DeclaredExtensionEntry[] = [];
-  for (const raw of extensionPacks) {
+  for (const raw of extensions) {
     if (typeof raw !== 'object' || raw === null) continue;
     const descriptor = Object.getOwnPropertyDescriptor(raw, 'contractSpace');
     if (descriptor === undefined) continue;

package/src/utils/formatters/migration-graph-grid-layout.ts

@@ -7,6 +7,7 @@
  */
 
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import {
   type Cell,
   type CellLine,
@@ -1124,7 +1125,7 @@ function assertSingleOwner(row: CellsRow, isFocus: boolean): void {
       if (isFocus) {
         const roles = new Set(top.map((cl) => cl.line.role));
         if (roles.size > 1) {
-          throw new Error(
+          throw new InternalError(
             'migration-graph layout: single-owner invariant violated — two differently-roled lines share the top plane in one cell',
           );
         }

package/src/utils/formatters/migration-graph-labels.ts

@@ -104,8 +104,7 @@ function abbreviateHash(hash: string, hashLength: number, emptySource: string):
   if (hash === EMPTY_CONTRACT_HASH) {
     return emptySource;
   }
-  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
-  return stripped.slice(0, hashLength);
+  return hash.slice(0, hashLength);
 }
 
 interface ContractOverlayNames {

package/src/utils/formatters/migration-list-data-column.ts

@@ -18,8 +18,7 @@ export function migrationListEmptySource(glyphMode: GlyphMode): string {
 }
 
 export function abbreviateContractHash(hash: string): string {
-  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
-  return stripped.slice(0, MIGRATION_LIST_HASH_WIDTH);
+  return hash.slice(0, MIGRATION_LIST_HASH_WIDTH);
 }
 
 export function padFromHashColumn(text: string, width: number): string {

package/src/utils/framework-components.ts

@@ -4,7 +4,7 @@ import {
   type TargetBoundComponentDescriptor,
 } from '@prisma-next/framework-components/components';
 import type { ControlStack } from '@prisma-next/framework-components/control';
-import { errorConfigValidation, errorContractMissingExtensionPacks } from './cli-errors';
+import { errorConfigValidation, errorContractMissingExtensions } from './cli-errors';
 
 /**
  * Asserts that all framework components are compatible with the expected family and target.
@@ -27,7 +27,7 @@ import { errorConfigValidation, errorContractMissingExtensionPacks } from './cli
  * @example
  * ```ts
  * const config = await loadConfig();
- * const frameworkComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+ * const frameworkComponents = [config.target, config.adapter, ...(config.extensions ?? [])];
  *
  * // Validate and type-narrow components before passing to planner
  * const typedComponents = assertFrameworkComponentsCompatible(
@@ -114,12 +114,12 @@ export function assertFrameworkComponentsCompatible<
  * This check ensures the emitted contract matches the CLI config before running
  * commands that depend on the contract (e.g., db verify, db sign).
  *
- * @param contract - The contract to validate (must include targetFamily, target, extensionPacks).
- * @param stack - The control plane stack (target, adapter, driver, extensionPacks).
+ * @param contract - The contract to validate (must include targetFamily, target, extensions).
+ * @param stack - The control plane stack (target, adapter, driver, extensions).
  *
  * @throws {CliStructuredError} errorConfigValidation when contract.targetFamily or contract.target
  *   doesn't match the configured family/target.
- * @throws {CliStructuredError} errorContractMissingExtensionPacks when the contract requires
+ * @throws {CliStructuredError} errorContractMissingExtensions when the contract requires
  *   extension packs that are not provided in the config (includes all missing packs in error.meta).
  *
  * @example
@@ -141,14 +141,14 @@ export function assertContractRequirementsSatisfied<
   contract,
   stack,
 }: {
-  readonly contract: Pick<Contract, 'targetFamily' | 'target' | 'extensionPacks'>;
+  readonly contract: Pick<Contract, 'targetFamily' | 'target' | 'extensions'>;
   readonly stack: ControlStack<TFamilyId, TTargetId>;
 }): void {
   const providedComponentIds = new Set<string>([
     stack.target.id,
     ...(stack.adapter ? [stack.adapter.id] : []),
   ]);
-  for (const extension of stack.extensionPacks) {
+  for (const extension of stack.extensions) {
     providedComponentIds.add(extension.id);
   }
 
@@ -172,8 +172,8 @@ export function assertContractRequirementsSatisfied<
   }
 
   if (result.missingExtensionPackIds.length > 0) {
-    throw errorContractMissingExtensionPacks({
-      missingExtensionPacks: result.missingExtensionPackIds,
+    throw errorContractMissingExtensions({
+      missingExtensions: result.missingExtensionPackIds,
       providedComponentIds: [...providedComponentIds],
     });
   }