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

package/src/control-api/client.ts

@@ -4,6 +4,7 @@ import type {
   LedgerEntryRecord,
 } from '@prisma-next/contract/types';
 import { emit as emitContractArtifacts } from '@prisma-next/emitter';
+import { CliStructuredError } from '@prisma-next/errors/control';
 import type { AuthoringPslBlockDescriptorNamespace } from '@prisma-next/framework-components/authoring';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -27,13 +28,13 @@ import {
   hasSchemaView,
 } from '@prisma-next/framework-components/control';
 import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
-
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { notOk, ok } from '@prisma-next/utils/result';
+import { structuredError } from '@prisma-next/utils/structured-error';
 
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import { enrichContract } from './contract-enrichment';
-import { ContractValidationError } from './errors';
 import { executeDbInit } from './operations/db-init';
 import { executeDbUpdate } from './operations/db-update';
 import { type ExecuteDbVerifyResult, executeDbVerify } from './operations/db-verify';
@@ -103,7 +104,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 +113,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,
@@ -128,20 +129,25 @@ class ControlClientImpl implements ControlClient {
     this.init();
 
     if (this.driver) {
-      throw new Error('Already connected. Call close() before reconnecting.');
+      throw new CliStructuredError(
+        'DRIVER.ALREADY_CONNECTED',
+        'Already connected. Call close() before reconnecting.',
+      );
     }
 
     // Resolve connection: argument > default from options
     const resolvedConnection = connection ?? this.defaultConnection;
     if (resolvedConnection === undefined) {
-      throw new Error(
+      throw new CliStructuredError(
+        'CONFIG.DB_CONNECTION_REQUIRED',
         'No connection provided. Pass a connection to connect() or provide a default connection when creating the client.',
       );
     }
 
     // Check for driver descriptor
     if (!this.stack?.driver) {
-      throw new Error(
+      throw new CliStructuredError(
+        'CONFIG.DRIVER_REQUIRED',
         'Driver is not configured. Pass a driver descriptor when creating the control client to enable database operations.',
       );
     }
@@ -167,7 +173,8 @@ class ControlClientImpl implements ControlClient {
   private buildControlAdapter(): ControlAdapterInstance<string, string> {
     this.init();
     if (!this.stack?.adapter) {
-      throw new Error(
+      throw new CliStructuredError(
+        'MIGRATION.TARGET_UNSUPPORTED',
         `Target "${this.options.target.targetId}" requires an adapter for migrations`,
       );
     }
@@ -188,7 +195,10 @@ class ControlClientImpl implements ControlClient {
     }
 
     if (!this.driver || !this.familyInstance || !this.frameworkComponents) {
-      throw new Error('Not connected. Call connect(connection) first.');
+      throw new CliStructuredError(
+        'DRIVER.NOT_CONNECTED',
+        'Not connected. Call connect(connection) first.',
+      );
     }
     return {
       driver: this.driver,
@@ -229,7 +239,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     // Emit verify span
@@ -282,7 +292,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     // Emit schemaVerify span
@@ -336,7 +346,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     // Emit sign span
@@ -381,7 +391,10 @@ class ControlClientImpl implements ControlClient {
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     if (!hasMigrations(this.options.target)) {
-      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+      throw new CliStructuredError(
+        'MIGRATION.TARGET_UNSUPPORTED',
+        `Target "${this.options.target.targetId}" does not support migrations`,
+      );
     }
 
     const adapter = this.buildControlAdapter();
@@ -391,7 +404,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     return executeDbInit({
@@ -404,7 +417,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),
     });
   }
@@ -415,7 +428,10 @@ class ControlClientImpl implements ControlClient {
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     if (!hasMigrations(this.options.target)) {
-      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+      throw new CliStructuredError(
+        'MIGRATION.TARGET_UNSUPPORTED',
+        `Target "${this.options.target.targetId}" does not support migrations`,
+      );
     }
 
     const adapter = this.buildControlAdapter();
@@ -425,7 +441,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     return executeDbUpdate({
@@ -438,7 +454,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 +471,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,
@@ -490,7 +506,10 @@ class ControlClientImpl implements ControlClient {
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     if (!hasMigrations(this.options.target)) {
-      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+      throw new CliStructuredError(
+        'MIGRATION.TARGET_UNSUPPORTED',
+        `Target "${this.options.target.targetId}" does not support migrations`,
+      );
     }
 
     let contract: Contract;
@@ -498,7 +517,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     return executeMigrate({
@@ -508,7 +527,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),
@@ -593,7 +612,7 @@ class ControlClientImpl implements ControlClient {
     this.init();
 
     if (!this.familyInstance) {
-      throw new Error('Family instance was not initialized. This is a bug.');
+      throw new InternalError('Family instance was not initialized. This is a bug.');
     }
 
     let contractRaw: unknown;
@@ -607,9 +626,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

@@ -24,6 +24,7 @@ import {
 } from '@prisma-next/migration-tools/aggregate';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { notOk, ok } from '@prisma-next/utils/result';
 import { CliStructuredError } from '../../utils/cli-errors';
 import {
@@ -80,7 +81,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 +120,7 @@ export async function executeRun<TFamilyId extends string, TTargetId extends str
     migrations,
     frameworkComponents,
     migrationsDir,
-    extensionPacks,
+    extensions,
     targetId,
     policy,
     action,
@@ -131,7 +132,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);
@@ -200,7 +201,7 @@ export async function executeRun<TFamilyId extends string, TTargetId extends str
   // `destination` is the storage hash users see in CLI output.
   const appResolution = orderedResolutions.find((r) => r.spaceId === aggregate.app.spaceId);
   if (!appResolution) {
-    throw new Error(
+    throw new InternalError(
       'Aggregate planner returned no plan for the app space — the planner is supposed to always emit one.',
     );
   }
@@ -283,7 +284,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 +320,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

@@ -24,6 +24,7 @@ import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { errorNoInvariantPath } from '@prisma-next/migration-tools/errors';
 import { findPathWithDecision } from '@prisma-next/migration-tools/migration-graph';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { notOk, ok } from '@prisma-next/utils/result';
 import {
   type BuildAggregateInputs,
@@ -60,7 +61,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 +123,7 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
     migrations,
     frameworkComponents,
     migrationsDir,
-    extensionPacks,
+    extensions,
     targetId,
     refHash,
     refInvariants,
@@ -134,7 +135,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);
@@ -247,7 +248,7 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
       .map((spaceId) => {
         const entry = perSpacePlans.get(spaceId) ?? atHeadResolutions.get(spaceId);
         if (entry === undefined) {
-          throw new Error(`Unreachable: missing per-space plan for "${spaceId}"`);
+          throw new InternalError(`Unreachable: missing per-space plan for "${spaceId}"`);
         }
         return { spaceId, entry };
       });
@@ -306,7 +307,7 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
       }
       const entry = atHeadResolutions.get(spaceId);
       if (entry === undefined) {
-        throw new Error(`Unreachable: missing per-space plan for "${spaceId}"`);
+        throw new InternalError(`Unreachable: missing per-space plan for "${spaceId}"`);
       }
       return { spaceId, entry };
     });

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

@@ -12,6 +12,7 @@ import type {
 } from '@prisma-next/framework-components/control';
 import type { ContractSpaceAggregate, PerSpacePlan } from '@prisma-next/migration-tools/aggregate';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import type { OnControlProgress, PerSpaceExecutionEntry } from '../types';
 
@@ -243,7 +244,7 @@ export function collectOrdered(
   return applyOrder.map((spaceId) => {
     const entry = perSpace.get(spaceId);
     if (!entry) {
-      throw new Error(`planner output missing per-space plan for "${spaceId}"`);
+      throw new InternalError(`planner output missing per-space plan for "${spaceId}"`);
     }
     return { spaceId, entry };
   });

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.