@prisma-next/family-sql 0.1.0-dev.3 → 0.1.0-dev.30

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.extensionPacks`).
 
 ## 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)
 

package/dist/exports/chunk-6P44BVZ4.js

@@ -0,0 +1,580 @@
+import {
+  collectSupportedCodecTypeIds,
+  readMarker
+} from "./chunk-C3GKWCKA.js";
+import {
+  verifySqlSchema
+} from "./chunk-F252JMEU.js";
+
+// src/core/assembly.ts
+import { createOperationRegistry } from "@prisma-next/operations";
+function assembleOperationRegistry(descriptors, convertOperationManifest2) {
+  const registry = createOperationRegistry();
+  for (const descriptor of descriptors) {
+    const operations = descriptor.operations ?? [];
+    for (const operationManifest of operations) {
+      const signature = convertOperationManifest2(operationManifest);
+      registry.register(signature);
+    }
+  }
+  return registry;
+}
+function extractCodecTypeImports(descriptors) {
+  const imports = [];
+  for (const descriptor of descriptors) {
+    const types = descriptor.types;
+    const codecTypes = types?.codecTypes;
+    if (codecTypes?.import) {
+      imports.push(codecTypes.import);
+    }
+  }
+  return imports;
+}
+function extractOperationTypeImports(descriptors) {
+  const imports = [];
+  for (const descriptor of descriptors) {
+    const types = descriptor.types;
+    const operationTypes = types?.operationTypes;
+    if (operationTypes?.import) {
+      imports.push(operationTypes.import);
+    }
+  }
+  return imports;
+}
+function extractExtensionIds(adapter, target, extensions) {
+  const ids = [];
+  const seen = /* @__PURE__ */ new Set();
+  if (!seen.has(adapter.id)) {
+    ids.push(adapter.id);
+    seen.add(adapter.id);
+  }
+  if (!seen.has(target.id)) {
+    ids.push(target.id);
+    seen.add(target.id);
+  }
+  for (const ext of extensions) {
+    if (!seen.has(ext.id)) {
+      ids.push(ext.id);
+      seen.add(ext.id);
+    }
+  }
+  return ids;
+}
+
+// src/core/instance.ts
+import { emit } from "@prisma-next/core-control-plane/emission";
+import { sqlTargetFamilyHook } from "@prisma-next/sql-contract-emitter";
+import { validateContract } from "@prisma-next/sql-contract-ts/contract";
+import {
+  ensureSchemaStatement,
+  ensureTableStatement,
+  writeContractMarker
+} from "@prisma-next/sql-runtime";
+import { ifDefined } from "@prisma-next/utils/defined";
+function convertOperationManifest(manifest) {
+  return {
+    forTypeId: manifest.for,
+    method: manifest.method,
+    args: manifest.args.map((arg) => {
+      if (arg.kind === "typeId") {
+        if (!arg.type) {
+          throw new Error("typeId arg must have type property");
+        }
+        return { kind: "typeId", type: arg.type };
+      }
+      if (arg.kind === "param") {
+        return { kind: "param" };
+      }
+      if (arg.kind === "literal") {
+        return { kind: "literal" };
+      }
+      throw new Error(`Invalid arg kind: ${arg.kind}`);
+    }),
+    returns: (() => {
+      if (manifest.returns.kind === "typeId") {
+        return { kind: "typeId", type: manifest.returns.type };
+      }
+      if (manifest.returns.kind === "builtin") {
+        return {
+          kind: "builtin",
+          type: manifest.returns.type
+        };
+      }
+      throw new Error(`Invalid return kind: ${manifest.returns.kind}`);
+    })(),
+    lowering: {
+      targetFamily: "sql",
+      strategy: manifest.lowering.strategy,
+      template: manifest.lowering.template
+    },
+    ...manifest.capabilities ? { capabilities: manifest.capabilities } : {}
+  };
+}
+function extractCodecTypeIdsFromContract(contract) {
+  const typeIds = /* @__PURE__ */ new Set();
+  if (typeof contract === "object" && contract !== null && "storage" in contract && typeof contract.storage === "object" && contract.storage !== null && "tables" in contract.storage) {
+    const storage = contract.storage;
+    if (storage.tables && typeof storage.tables === "object") {
+      for (const table of Object.values(storage.tables)) {
+        if (typeof table === "object" && table !== null && "columns" in table && typeof table.columns === "object" && table.columns !== null) {
+          const columns = table.columns;
+          for (const column of Object.values(columns)) {
+            if (column && typeof column === "object" && "codecId" in column && typeof column.codecId === "string") {
+              typeIds.add(column.codecId);
+            }
+          }
+        }
+      }
+    }
+  }
+  return Array.from(typeIds).sort();
+}
+function createVerifyResult(options) {
+  const contract = {
+    coreHash: options.contractCoreHash
+  };
+  if (options.contractProfileHash) {
+    contract.profileHash = options.contractProfileHash;
+  }
+  const target = {
+    expected: options.expectedTargetId
+  };
+  if (options.actualTargetId) {
+    target.actual = options.actualTargetId;
+  }
+  const meta = {
+    contractPath: options.contractPath
+  };
+  if (options.configPath) {
+    meta.configPath = options.configPath;
+  }
+  const result = {
+    ok: options.ok,
+    summary: options.summary,
+    contract,
+    target,
+    meta,
+    timings: {
+      total: options.totalTime
+    }
+  };
+  if (options.code) {
+    result.code = options.code;
+  }
+  if (options.marker) {
+    result.marker = {
+      coreHash: options.marker.coreHash,
+      profileHash: options.marker.profileHash
+    };
+  }
+  if (options.missingCodecs) {
+    result.missingCodecs = options.missingCodecs;
+  }
+  if (options.codecCoverageSkipped) {
+    result.codecCoverageSkipped = options.codecCoverageSkipped;
+  }
+  return result;
+}
+function buildSqlTypeMetadataRegistry(options) {
+  const { target, adapter, extensionPacks: extensions } = options;
+  const registry = /* @__PURE__ */ new Map();
+  const targetId = adapter.targetId;
+  const descriptors = [target, adapter, ...extensions];
+  for (const descriptor of descriptors) {
+    const types = descriptor.types;
+    const storageTypes = types?.storage;
+    if (!storageTypes) {
+      continue;
+    }
+    for (const storageType of storageTypes) {
+      if (storageType.familyId === "sql" && storageType.targetId === targetId) {
+        registry.set(storageType.typeId, {
+          typeId: storageType.typeId,
+          familyId: "sql",
+          targetId: storageType.targetId,
+          ...storageType.nativeType !== void 0 ? { nativeType: storageType.nativeType } : {}
+        });
+      }
+    }
+  }
+  return registry;
+}
+function createSqlFamilyInstance(options) {
+  const { target, adapter, extensionPacks: extensions = [] } = options;
+  const descriptors = [target, adapter, ...extensions];
+  const operationRegistry = assembleOperationRegistry(descriptors, convertOperationManifest);
+  const codecTypeImports = extractCodecTypeImports(descriptors);
+  const operationTypeImports = extractOperationTypeImports(descriptors);
+  const extensionIds = extractExtensionIds(adapter, target, extensions);
+  const typeMetadataRegistry = buildSqlTypeMetadataRegistry({
+    target,
+    adapter,
+    extensionPacks: extensions
+  });
+  function stripMappings(contract) {
+    if (typeof contract === "object" && contract !== null && "mappings" in contract) {
+      const { mappings: _mappings, ...contractIR } = contract;
+      return contractIR;
+    }
+    return contract;
+  }
+  return {
+    familyId: "sql",
+    operationRegistry,
+    codecTypeImports,
+    operationTypeImports,
+    extensionIds,
+    typeMetadataRegistry,
+    validateContractIR(contractJson) {
+      const validated = validateContract(contractJson);
+      const { mappings: _mappings, ...contractIR } = validated;
+      return contractIR;
+    },
+    async verify(verifyOptions) {
+      const { driver, contractIR, expectedTargetId, contractPath, configPath } = verifyOptions;
+      const startTime = Date.now();
+      if (typeof contractIR !== "object" || contractIR === null || !("coreHash" in contractIR) || !("target" in contractIR) || typeof contractIR.coreHash !== "string" || typeof contractIR.target !== "string") {
+        throw new Error("Contract is missing required fields: coreHash or target");
+      }
+      const contractCoreHash = contractIR.coreHash;
+      const contractProfileHash = "profileHash" in contractIR && typeof contractIR.profileHash === "string" ? contractIR.profileHash : void 0;
+      const contractTarget = contractIR.target;
+      const marker = await readMarker(driver);
+      let missingCodecs;
+      let codecCoverageSkipped = false;
+      const supportedTypeIds = collectSupportedCodecTypeIds([
+        adapter,
+        target,
+        ...extensions
+      ]);
+      if (supportedTypeIds.length === 0) {
+        codecCoverageSkipped = true;
+      } else {
+        const supportedSet = new Set(supportedTypeIds);
+        const usedTypeIds = extractCodecTypeIdsFromContract(contractIR);
+        const missing = usedTypeIds.filter((id) => !supportedSet.has(id));
+        if (missing.length > 0) {
+          missingCodecs = missing;
+        }
+      }
+      if (!marker) {
+        const totalTime2 = Date.now() - startTime;
+        return createVerifyResult({
+          ok: false,
+          code: "PN-RTM-3001",
+          summary: "Marker missing",
+          contractCoreHash,
+          expectedTargetId,
+          contractPath,
+          totalTime: totalTime2,
+          ...contractProfileHash ? { contractProfileHash } : {},
+          ...missingCodecs ? { missingCodecs } : {},
+          ...codecCoverageSkipped ? { codecCoverageSkipped } : {},
+          ...configPath ? { configPath } : {}
+        });
+      }
+      if (contractTarget !== expectedTargetId) {
+        const totalTime2 = Date.now() - startTime;
+        return createVerifyResult({
+          ok: false,
+          code: "PN-RTM-3003",
+          summary: "Target mismatch",
+          contractCoreHash,
+          marker,
+          expectedTargetId,
+          actualTargetId: contractTarget,
+          contractPath,
+          totalTime: totalTime2,
+          ...contractProfileHash ? { contractProfileHash } : {},
+          ...missingCodecs ? { missingCodecs } : {},
+          ...codecCoverageSkipped ? { codecCoverageSkipped } : {},
+          ...configPath ? { configPath } : {}
+        });
+      }
+      if (marker.coreHash !== contractCoreHash) {
+        const totalTime2 = Date.now() - startTime;
+        return createVerifyResult({
+          ok: false,
+          code: "PN-RTM-3002",
+          summary: "Hash mismatch",
+          contractCoreHash,
+          marker,
+          expectedTargetId,
+          contractPath,
+          totalTime: totalTime2,
+          ...contractProfileHash ? { contractProfileHash } : {},
+          ...missingCodecs ? { missingCodecs } : {},
+          ...codecCoverageSkipped ? { codecCoverageSkipped } : {},
+          ...configPath ? { configPath } : {}
+        });
+      }
+      if (contractProfileHash && marker.profileHash !== contractProfileHash) {
+        const totalTime2 = Date.now() - startTime;
+        return createVerifyResult({
+          ok: false,
+          code: "PN-RTM-3002",
+          summary: "Hash mismatch",
+          contractCoreHash,
+          contractProfileHash,
+          marker,
+          expectedTargetId,
+          contractPath,
+          totalTime: totalTime2,
+          ...missingCodecs ? { missingCodecs } : {},
+          ...codecCoverageSkipped ? { codecCoverageSkipped } : {},
+          ...configPath ? { configPath } : {}
+        });
+      }
+      const totalTime = Date.now() - startTime;
+      return createVerifyResult({
+        ok: true,
+        summary: "Database matches contract",
+        contractCoreHash,
+        marker,
+        expectedTargetId,
+        contractPath,
+        totalTime,
+        ...contractProfileHash ? { contractProfileHash } : {},
+        ...missingCodecs ? { missingCodecs } : {},
+        ...codecCoverageSkipped ? { codecCoverageSkipped } : {},
+        ...configPath ? { configPath } : {}
+      });
+    },
+    async schemaVerify(options2) {
+      const { driver, contractIR, strict, context, frameworkComponents } = options2;
+      const contract = validateContract(contractIR);
+      const controlAdapter = adapter.create();
+      const schemaIR = await controlAdapter.introspect(driver, contractIR);
+      return verifySqlSchema({
+        contract,
+        schema: schemaIR,
+        strict,
+        ...ifDefined("context", context),
+        typeMetadataRegistry,
+        frameworkComponents
+      });
+    },
+    async sign(options2) {
+      const { driver, contractIR, contractPath, configPath } = options2;
+      const startTime = Date.now();
+      const contract = validateContract(contractIR);
+      const contractCoreHash = contract.coreHash;
+      const contractProfileHash = "profileHash" in contract && typeof contract.profileHash === "string" ? contract.profileHash : contractCoreHash;
+      const contractTarget = contract.target;
+      await driver.query(ensureSchemaStatement.sql, ensureSchemaStatement.params);
+      await driver.query(ensureTableStatement.sql, ensureTableStatement.params);
+      const existingMarker = await readMarker(driver);
+      let markerCreated = false;
+      let markerUpdated = false;
+      let previousHashes;
+      if (!existingMarker) {
+        const write = writeContractMarker({
+          coreHash: contractCoreHash,
+          profileHash: contractProfileHash,
+          contractJson: contractIR,
+          canonicalVersion: 1
+        });
+        await driver.query(write.insert.sql, write.insert.params);
+        markerCreated = true;
+      } else {
+        const existingCoreHash = existingMarker.coreHash;
+        const existingProfileHash = existingMarker.profileHash;
+        const coreHashMatches = existingCoreHash === contractCoreHash;
+        const profileHashMatches = existingProfileHash === contractProfileHash;
+        if (!coreHashMatches || !profileHashMatches) {
+          previousHashes = {
+            coreHash: existingCoreHash,
+            profileHash: existingProfileHash
+          };
+          const write = writeContractMarker({
+            coreHash: contractCoreHash,
+            profileHash: contractProfileHash,
+            contractJson: contractIR,
+            canonicalVersion: existingMarker.canonicalVersion ?? 1
+          });
+          await driver.query(write.update.sql, write.update.params);
+          markerUpdated = true;
+        }
+      }
+      let summary;
+      if (markerCreated) {
+        summary = "Database signed (marker created)";
+      } else if (markerUpdated) {
+        summary = `Database signed (marker updated from ${previousHashes?.coreHash ?? "unknown"})`;
+      } else {
+        summary = "Database already signed with this contract";
+      }
+      const totalTime = Date.now() - startTime;
+      return {
+        ok: true,
+        summary,
+        contract: {
+          coreHash: contractCoreHash,
+          profileHash: contractProfileHash
+        },
+        target: {
+          expected: contractTarget,
+          actual: contractTarget
+        },
+        marker: {
+          created: markerCreated,
+          updated: markerUpdated,
+          ...previousHashes ? { previous: previousHashes } : {}
+        },
+        meta: {
+          contractPath,
+          ...configPath ? { configPath } : {}
+        },
+        timings: {
+          total: totalTime
+        }
+      };
+    },
+    async readMarker(options2) {
+      return readMarker(options2.driver);
+    },
+    async introspect(options2) {
+      const { driver, contractIR } = options2;
+      const controlAdapter = adapter.create();
+      return controlAdapter.introspect(driver, contractIR);
+    },
+    toSchemaView(schema) {
+      const rootLabel = "contract";
+      const tableNodes = Object.entries(schema.tables).map(
+        ([tableName, table]) => {
+          const children = [];
+          const columnNodes = [];
+          for (const [columnName, column] of Object.entries(table.columns)) {
+            const nullableText = column.nullable ? "(nullable)" : "(not nullable)";
+            const typeDisplay = column.nativeType;
+            const label = `${columnName}: ${typeDisplay} ${nullableText}`;
+            columnNodes.push({
+              kind: "field",
+              id: `column-${tableName}-${columnName}`,
+              label,
+              meta: {
+                nativeType: column.nativeType,
+                nullable: column.nullable
+              }
+            });
+          }
+          if (columnNodes.length > 0) {
+            children.push({
+              kind: "collection",
+              id: `columns-${tableName}`,
+              label: "columns",
+              children: columnNodes
+            });
+          }
+          if (table.primaryKey) {
+            const pkColumns = table.primaryKey.columns.join(", ");
+            children.push({
+              kind: "index",
+              id: `primary-key-${tableName}`,
+              label: `primary key: ${pkColumns}`,
+              meta: {
+                columns: table.primaryKey.columns,
+                ...table.primaryKey.name ? { name: table.primaryKey.name } : {}
+              }
+            });
+          }
+          for (const unique of table.uniques) {
+            const name = unique.name ?? `${tableName}_${unique.columns.join("_")}_unique`;
+            const label = `unique ${name}`;
+            children.push({
+              kind: "index",
+              id: `unique-${tableName}-${name}`,
+              label,
+              meta: {
+                columns: unique.columns,
+                unique: true
+              }
+            });
+          }
+          for (const index of table.indexes) {
+            const name = index.name ?? `${tableName}_${index.columns.join("_")}_idx`;
+            const label = index.unique ? `unique index ${name}` : `index ${name}`;
+            children.push({
+              kind: "index",
+              id: `index-${tableName}-${name}`,
+              label,
+              meta: {
+                columns: index.columns,
+                unique: index.unique
+              }
+            });
+          }
+          const tableMeta = {};
+          if (table.primaryKey) {
+            tableMeta["primaryKey"] = table.primaryKey.columns;
+            if (table.primaryKey.name) {
+              tableMeta["primaryKeyName"] = table.primaryKey.name;
+            }
+          }
+          if (table.foreignKeys.length > 0) {
+            tableMeta["foreignKeys"] = table.foreignKeys.map((fk) => ({
+              columns: fk.columns,
+              referencedTable: fk.referencedTable,
+              referencedColumns: fk.referencedColumns,
+              ...fk.name ? { name: fk.name } : {}
+            }));
+          }
+          const node = {
+            kind: "entity",
+            id: `table-${tableName}`,
+            label: `table ${tableName}`,
+            ...Object.keys(tableMeta).length > 0 ? { meta: tableMeta } : {},
+            ...children.length > 0 ? { children } : {}
+          };
+          return node;
+        }
+      );
+      const extensionNodes = schema.extensions.map((extName) => ({
+        kind: "extension",
+        id: `extension-${extName}`,
+        label: `${extName} extension is enabled`
+      }));
+      const rootChildren = [...tableNodes, ...extensionNodes];
+      const rootNode = {
+        kind: "root",
+        id: "sql-schema",
+        label: rootLabel,
+        ...rootChildren.length > 0 ? { children: rootChildren } : {}
+      };
+      return {
+        root: rootNode
+      };
+    },
+    async emitContract({ contractIR }) {
+      const contractWithoutMappings = stripMappings(contractIR);
+      const validatedIR = this.validateContractIR(contractWithoutMappings);
+      const result = await emit(
+        validatedIR,
+        {
+          outputDir: "",
+          operationRegistry,
+          codecTypeImports,
+          operationTypeImports,
+          extensionIds
+        },
+        sqlTargetFamilyHook
+      );
+      return {
+        contractJson: result.contractJson,
+        contractDts: result.contractDts,
+        coreHash: result.coreHash,
+        profileHash: result.profileHash
+      };
+    }
+  };
+}
+
+export {
+  assembleOperationRegistry,
+  extractCodecTypeImports,
+  extractOperationTypeImports,
+  extractExtensionIds,
+  convertOperationManifest,
+  createSqlFamilyInstance
+};
+//# sourceMappingURL=chunk-6P44BVZ4.js.map