@prisma-next/core-control-plane 0.1.0-pr.57.2 → 0.1.0-pr.57.3

package/README.md

@@ -17,6 +17,7 @@ This package provides the core domain logic for control plane operations (contra
 Note: Contract emission is implemented on family instances (e.g., `familyInstance.emitContract()`), not as a core domain action.
 - **Error Factories**: Domain error factories (`CliStructuredError`, config errors, runtime errors)
 - **Pack Manifest Types**: Type definitions for extension pack manifests
+- **Migration SPI**: Generic migration planner/runner interfaces (`MigrationPlanner<TFamilyId, TTargetId>`, `MigrationRunner<TFamilyId, TTargetId>`, `TargetMigrationsCapability<TFamilyId, TTargetId, TFamilyInstance>`) that thread family/target IDs for compile-time component compatibility enforcement
 
 ## Dependencies
 
@@ -102,6 +103,30 @@ throw errorConfigFileNotFound('prisma-next.config.ts', {
 });
 ```
 
+## Migration SPI Design
+
+The migration planner/runner interfaces are generic over `TFamilyId` and `TTargetId` to enable compile-time enforcement of component compatibility:
+
+- **`MigrationPlanner<TFamilyId, TTargetId>`**: Generic planner interface that accepts `TargetBoundComponentDescriptor<TFamilyId, TTargetId>[]`
+- **`MigrationRunner<TFamilyId, TTargetId>`**: Generic runner interface that accepts `TargetBoundComponentDescriptor<TFamilyId, TTargetId>[]`
+- **`TargetMigrationsCapability<TFamilyId, TTargetId, TFamilyInstance>`**: Generic capability interface for targets that support migrations
+
+The CLI performs runtime validation at the composition boundary using `assertFrameworkComponentsCompatible()` before calling typed planner/runner instances. This validates that all components have matching `familyId` and `targetId`, then returns a typed `TargetBoundComponentDescriptor` array that satisfies the planner/runner interface requirements.
+
+```typescript
+// CLI composition boundary - runtime assertion + type narrowing
+const rawComponents = [config.target, config.adapter, ...(config.extensions ?? [])];
+const frameworkComponents = assertFrameworkComponentsCompatible(
+  config.family.familyId,
+  config.target.targetId,
+  rawComponents,
+);
+
+// Now frameworkComponents is typed as TargetBoundComponentDescriptor<TFamilyId, TTargetId>[]
+const planner = target.migrations.createPlanner(familyInstance);
+planner.plan({ contract, schema, policy, frameworkComponents });
+```
+
 ## Package Location
 
 This package is part of the **framework domain**, **core layer**, **migration plane**:

package/dist/exports/types.d.ts

@@ -1,4 +1,4 @@
-import { ComponentDescriptor, FamilyInstance, DriverInstance, FamilyDescriptor, TargetInstance, TargetDescriptor, AdapterInstance, AdapterDescriptor, DriverDescriptor, ExtensionInstance, ExtensionDescriptor } from '@prisma-next/contract/framework-components';
+import { TargetBoundComponentDescriptor, FamilyInstance, DriverInstance, FamilyDescriptor, TargetInstance, TargetDescriptor, AdapterInstance, AdapterDescriptor, DriverDescriptor, ExtensionInstance, ExtensionDescriptor } from '@prisma-next/contract/framework-components';
 import { ContractIR } from '@prisma-next/contract/ir';
 import { TargetFamilyHook } from '@prisma-next/contract/types';
 import { Result } from '@prisma-next/utils/result';
@@ -109,8 +109,11 @@ type MigrationRunnerResult = Result<MigrationRunnerSuccessValue, MigrationRunner
 /**
  * Migration planner interface for planning schema changes.
  * This is the minimal interface that CLI commands use.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
  */
-interface MigrationPlanner {
+interface MigrationPlanner<TFamilyId extends string = string, TTargetId extends string = string> {
     plan(options: {
         readonly contract: unknown;
         readonly schema: unknown;
@@ -118,18 +121,22 @@ interface MigrationPlanner {
         /**
          * Active framework components participating in this composition.
          * Families/targets can interpret this bag to derive family-specific metadata.
+         * All components must have matching familyId and targetId.
          */
-        readonly frameworkComponents: ReadonlyArray<ComponentDescriptor<string>>;
+        readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
     }): MigrationPlannerResult;
 }
 /**
  * Migration runner interface for executing migration plans.
  * This is the minimal interface that CLI commands use.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
  */
-interface MigrationRunner {
+interface MigrationRunner<TFamilyId extends string = string, TTargetId extends string = string> {
     execute(options: {
         readonly plan: MigrationPlan;
-        readonly driver: ControlDriverInstance<string, string>;
+        readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
         readonly destinationContract: unknown;
         readonly policy: MigrationOperationPolicy;
         readonly callbacks?: {
@@ -139,19 +146,22 @@ interface MigrationRunner {
         /**
          * Active framework components participating in this composition.
          * Families/targets can interpret this bag to derive family-specific metadata.
+         * All components must have matching familyId and targetId.
          */
-        readonly frameworkComponents: ReadonlyArray<ComponentDescriptor<string>>;
+        readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
     }): Promise<MigrationRunnerResult>;
 }
 /**
  * Optional capability interface for targets that support migrations.
  * Targets that implement migrations expose this via their descriptor.
  *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
  * @template TFamilyInstance - The family instance type (e.g., SqlControlFamilyInstance)
  */
-interface TargetMigrationsCapability<TFamilyInstance extends ControlFamilyInstance<string> = ControlFamilyInstance<string>> {
-    createPlanner(family: TFamilyInstance): MigrationPlanner;
-    createRunner(family: TFamilyInstance): MigrationRunner;
+interface TargetMigrationsCapability<TFamilyId extends string = string, TTargetId extends string = string, TFamilyInstance extends ControlFamilyInstance<TFamilyId> = ControlFamilyInstance<TFamilyId>> {
+    createPlanner(family: TFamilyInstance): MigrationPlanner<TFamilyId, TTargetId>;
+    createRunner(family: TFamilyInstance): MigrationRunner<TFamilyId, TTargetId>;
 }
 
 /**
@@ -196,7 +206,11 @@ interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR = unknown> e
         readonly strict: boolean;
         readonly contractPath: string;
         readonly configPath?: string;
-        readonly frameworkComponents: ReadonlyArray<ComponentDescriptor<string>>;
+        /**
+         * Active framework components participating in this composition.
+         * All components must have matching familyId and targetId.
+         */
+        readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, string>>;
     }): Promise<VerifyDatabaseSchemaResult>;
     /**
      * Signs the database with the contract marker.
@@ -348,8 +362,10 @@ interface ControlTargetDescriptor<TFamilyId extends string, TTargetId extends st
     /**
      * Optional migrations capability.
      * Targets that support migrations expose this property.
+     * The capability is parameterized by family and target IDs to ensure type-level
+     * compatibility of framework components.
      */
-    readonly migrations?: TargetMigrationsCapability<TFamilyInstance>;
+    readonly migrations?: TargetMigrationsCapability<TFamilyId, TTargetId, TFamilyInstance>;
     create(): TTargetInstance;
 }
 /**

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@prisma-next/core-control-plane",
-  "version": "0.1.0-pr.57.2",
+  "version": "0.1.0-pr.57.3",
   "type": "module",
   "sideEffects": false,
   "description": "Control plane domain actions, config types, validation, and error factories for Prisma Next",
   "dependencies": {
     "arktype": "^2.1.26",
     "prettier": "^3.3.3",
-    "@prisma-next/contract": "0.1.0-pr.57.2",
-    "@prisma-next/operations": "0.1.0-pr.57.2",
-    "@prisma-next/utils": "0.1.0-pr.57.2"
+    "@prisma-next/contract": "0.1.0-pr.57.3",
+    "@prisma-next/operations": "0.1.0-pr.57.3",
+    "@prisma-next/utils": "0.1.0-pr.57.3"
   },
   "devDependencies": {
     "tsup": "^8.3.0",