@prisma-next/family-sql 0.1.0-dev.2 → 0.1.0-dev.21

package/README.md

@@ -12,8 +12,10 @@ Provides the SQL family descriptor (`ControlFamilyDescriptor`) that includes:
 
 - **Family Descriptor Export**: Exports the SQL `ControlFamilyDescriptor` for use in CLI configuration files
 - **Family Instance Creation**: Creates `SqlFamilyInstance` objects that implement control-plane domain actions (`verify`, `schemaVerify`, `introspect`, `emitContract`, `validateContractIR`)
+- **Planner & Runner SPI**: Owns the `MigrationPlanner` / `MigrationRunner` interfaces plus the `SqlControlTargetDescriptor` helper so targets can expose planners and runners (e.g., Postgres init planner/runner)
 - **Family Hook Integration**: Integrates the SQL target family hook (`sqlTargetFamilyHook`) from `@prisma-next/sql-contract-emitter`
 - **Control Plane Entry Point**: Serves as the control plane entry point for the SQL family, enabling the CLI to select the family hook and create family instances
+- **Component Database Dependencies**: Consumes database dependencies declared by framework components (target/adapter/extensions). Callers pass the active `frameworkComponents` list into planning/execution/verification; SQL layers structurally narrow to components that declare `databaseDependencies` and use their pure verification hooks (no fuzzy matching against `contract.extensions`).
 
 ## Usage
 
@@ -39,6 +41,33 @@ const familyInstance = sql.create({
 const contractIR = familyInstance.validateContractIR(contractJson);
 const verifyResult = await familyInstance.verify({ driver, contractIR, ... });
 const emitResult = await familyInstance.emitContract({ contractIR: rawContract }); // Handles stripping mappings and validation internally
+
+// Targets that implement SqlControlTargetDescriptor can build planners
+const planner = postgresTargetDescriptor.createPlanner(familyInstance);
+// frameworkComponents should include the active target, adapter, and any extension descriptors so
+// planner/runner can resolve database dependencies declared by those components.
+const planResult = planner.plan({
+  contract: sqlContract,
+  schema,
+  policy,
+  frameworkComponents: [postgresTargetDescriptor, postgresAdapterDescriptor, pgVectorExtensionDescriptor],
+});
+
+// Targets also provide runners for executing plans
+const runner = postgresTargetDescriptor.createRunner(familyInstance);
+const executeResult = await runner.execute({
+  plan: planResult.plan,
+  driver,
+  destinationContract: sqlContract,
+  frameworkComponents: [postgresTargetDescriptor, postgresAdapterDescriptor, pgVectorExtensionDescriptor],
+});
+
+// executeResult is a Result<MigrationRunnerSuccessValue, MigrationRunnerFailure>
+if (executeResult.ok) {
+  console.log(`Executed ${executeResult.value.operationsExecuted} operations`);
+} else {
+  console.error(`Migration failed: ${executeResult.failure.code} - ${executeResult.failure.summary}`);
+}
 ```
 
 ## Architecture
@@ -68,6 +97,19 @@ The descriptor is "pure data + factory" - it only provides the hook and factory
 - **`src/core/assembly.ts`**: Assembly helpers for building operation registries and extracting type imports from descriptors. Test utilities import `convertOperationManifest` from the same package via relative path.
 - **`src/core/verify.ts`**: Verification helpers (`readMarker`, `collectSupportedCodecTypeIds`)
 - **`src/core/control-adapter.ts`**: SQL control adapter interface (`SqlControlAdapter`) for control-plane operations
+- **`src/core/migrations/`**: Migration IR helpers plus planner and runner SPI types (`MigrationPlanner`, `MigrationRunner`, `SqlControlTargetDescriptor`). Runners return `MigrationRunnerResult` which is a union of success/failure.
+
+### Migration Runner Error Codes
+
+The runner returns structured errors with the following codes:
+
+- **`DESTINATION_CONTRACT_MISMATCH`**: Plan destination hash doesn't match provided contract hash
+- **`MARKER_ORIGIN_MISMATCH`**: Existing marker doesn't match plan's expected origin
+- **`POLICY_VIOLATION`**: Operation class is not allowed by the plan's policy
+- **`PRECHECK_FAILED`**: Operation precheck returned false
+- **`POSTCHECK_FAILED`**: Operation postcheck returned false after execution
+- **`SCHEMA_VERIFY_FAILED`**: Resulting schema doesn't satisfy the destination contract
+- **`EXECUTION_FAILED`**: SQL execution error during operation execution
 - **`src/exports/control.ts`**: Control plane entry point (exports `SqlFamilyDescriptor` instance)
 - **`src/exports/runtime.ts`**: Runtime entry point (placeholder for future functionality)