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

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)
 

package/dist/exports/{chunk-3HYKCN35.js → chunk-2L5DCW2L.js}

@@ -86,4 +86,4 @@ export {
   readMarker,
   collectSupportedCodecTypeIds
 };
-//# sourceMappingURL=chunk-3HYKCN35.js.map
+//# sourceMappingURL=chunk-2L5DCW2L.js.map

package/dist/exports/chunk-2L5DCW2L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/verify.ts"],"sourcesContent":["import type { ContractMarkerRecord } from '@prisma-next/contract/types';\nimport type {\n  ControlAdapterDescriptor,\n  ControlDriverInstance,\n  ControlExtensionDescriptor,\n  ControlTargetDescriptor,\n} from '@prisma-next/core-control-plane/types';\nimport { type } from 'arktype';\n\nconst MetaSchema = type({ '[string]': 'unknown' });\n\nfunction parseMeta(meta: unknown): Record<string, unknown> {\n  if (meta === null || meta === undefined) {\n    return {};\n  }\n\n  let parsed: unknown;\n  if (typeof meta === 'string') {\n    try {\n      parsed = JSON.parse(meta);\n    } catch {\n      return {};\n    }\n  } else {\n    parsed = meta;\n  }\n\n  const result = MetaSchema(parsed);\n  if (result instanceof type.errors) {\n    return {};\n  }\n\n  return result as Record<string, unknown>;\n}\n\nconst ContractMarkerRowSchema = type({\n  core_hash: 'string',\n  profile_hash: 'string',\n  'contract_json?': 'unknown | null',\n  'canonical_version?': 'number | null',\n  'updated_at?': 'Date | string',\n  'app_tag?': 'string | null',\n  'meta?': 'unknown | null',\n});\n\n/**\n * Parses a contract marker row from database query result.\n * This is SQL-specific parsing logic (handles SQL row structure with snake_case columns).\n */\nexport function parseContractMarkerRow(row: unknown): ContractMarkerRecord {\n  const result = ContractMarkerRowSchema(row);\n  if (result instanceof type.errors) {\n    const messages = result.map((p: { message: string }) => p.message).join('; ');\n    throw new Error(`Invalid contract marker row: ${messages}`);\n  }\n\n  const validatedRow = result as {\n    core_hash: string;\n    profile_hash: string;\n    contract_json?: unknown | null;\n    canonical_version?: number | null;\n    updated_at?: Date | string;\n    app_tag?: string | null;\n    meta?: unknown | null;\n  };\n\n  const updatedAt = validatedRow.updated_at\n    ? validatedRow.updated_at instanceof Date\n      ? validatedRow.updated_at\n      : new Date(validatedRow.updated_at)\n    : new Date();\n\n  return {\n    coreHash: validatedRow.core_hash,\n    profileHash: validatedRow.profile_hash,\n    contractJson: validatedRow.contract_json ?? null,\n    canonicalVersion: validatedRow.canonical_version ?? null,\n    updatedAt,\n    appTag: validatedRow.app_tag ?? null,\n    meta: parseMeta(validatedRow.meta),\n  };\n}\n\n/**\n * Returns the SQL statement to read the contract marker.\n * This is a migration-plane helper (no runtime imports).\n * @internal - Used internally by readMarker(). Prefer readMarker() for Control Plane usage.\n */\nexport function readMarkerSql(): { readonly sql: string; readonly params: readonly unknown[] } {\n  return {\n    sql: `select\n      core_hash,\n      profile_hash,\n      contract_json,\n      canonical_version,\n      updated_at,\n      app_tag,\n      meta\n    from prisma_contract.marker\n    where id = $1`,\n    params: [1],\n  };\n}\n\n/**\n * Reads the contract marker from the database using the provided driver.\n * Returns the parsed marker record or null if no marker is found.\n * This abstracts SQL-specific details from the Control Plane.\n *\n * @param driver - ControlDriverInstance instance for executing queries\n * @returns Promise resolving to ContractMarkerRecord or null if marker not found\n */\nexport async function readMarker(\n  driver: ControlDriverInstance<'sql', string>,\n): Promise<ContractMarkerRecord | null> {\n  const markerStatement = readMarkerSql();\n  const queryResult = await driver.query<{\n    core_hash: string;\n    profile_hash: string;\n    contract_json: unknown | null;\n    canonical_version: number | null;\n    updated_at: Date | string;\n    app_tag: string | null;\n    meta: unknown | null;\n  }>(markerStatement.sql, markerStatement.params);\n\n  if (queryResult.rows.length === 0) {\n    return null;\n  }\n\n  const markerRow = queryResult.rows[0];\n  if (!markerRow) {\n    // If rows array has length > 0 but first element is undefined, this is an unexpected result structure\n    throw new Error('Database query returned unexpected result structure');\n  }\n\n  return parseContractMarkerRow(markerRow);\n}\n\n/**\n * Collects supported codec type IDs from adapter and extension manifests.\n * Returns a sorted, unique array of type IDs that are declared in the manifests.\n * This enables coverage checks by comparing contract column types against supported types.\n *\n * Note: This extracts type IDs from manifest type imports, not from runtime codec registries.\n * The manifests declare which codec types are available, but the actual type IDs\n * are defined in the codec-types TypeScript modules that are imported.\n *\n * For MVP, we return an empty array since extracting type IDs from TypeScript modules\n * would require runtime evaluation or static analysis. This can be enhanced later.\n */\nexport function collectSupportedCodecTypeIds<TFamilyId extends string, TTargetId extends string>(\n  descriptors: ReadonlyArray<\n    | ControlTargetDescriptor<TFamilyId, TTargetId>\n    | ControlAdapterDescriptor<TFamilyId, TTargetId>\n    | ControlExtensionDescriptor<TFamilyId, TTargetId>\n  >,\n): readonly string[] {\n  // For MVP, return empty array\n  // Future enhancement: Extract type IDs from codec-types modules via static analysis\n  // or require manifests to explicitly list supported type IDs\n  void descriptors;\n  return [];\n}\n"],"mappings":";AAOA,SAAS,YAAY;AAErB,IAAM,aAAa,KAAK,EAAE,YAAY,UAAU,CAAC;AAEjD,SAAS,UAAU,MAAwC;AACzD,MAAI,SAAS,QAAQ,SAAS,QAAW;AACvC,WAAO,CAAC;AAAA,EACV;AAEA,MAAI;AACJ,MAAI,OAAO,SAAS,UAAU;AAC5B,QAAI;AACF,eAAS,KAAK,MAAM,IAAI;AAAA,IAC1B,QAAQ;AACN,aAAO,CAAC;AAAA,IACV;AAAA,EACF,OAAO;AACL,aAAS;AAAA,EACX;AAEA,QAAM,SAAS,WAAW,MAAM;AAChC,MAAI,kBAAkB,KAAK,QAAQ;AACjC,WAAO,CAAC;AAAA,EACV;AAEA,SAAO;AACT;AAEA,IAAM,0BAA0B,KAAK;AAAA,EACnC,WAAW;AAAA,EACX,cAAc;AAAA,EACd,kBAAkB;AAAA,EAClB,sBAAsB;AAAA,EACtB,eAAe;AAAA,EACf,YAAY;AAAA,EACZ,SAAS;AACX,CAAC;AAMM,SAAS,uBAAuB,KAAoC;AACzE,QAAM,SAAS,wBAAwB,GAAG;AAC1C,MAAI,kBAAkB,KAAK,QAAQ;AACjC,UAAM,WAAW,OAAO,IAAI,CAAC,MAA2B,EAAE,OAAO,EAAE,KAAK,IAAI;AAC5E,UAAM,IAAI,MAAM,gCAAgC,QAAQ,EAAE;AAAA,EAC5D;AAEA,QAAM,eAAe;AAUrB,QAAM,YAAY,aAAa,aAC3B,aAAa,sBAAsB,OACjC,aAAa,aACb,IAAI,KAAK,aAAa,UAAU,IAClC,oBAAI,KAAK;AAEb,SAAO;AAAA,IACL,UAAU,aAAa;AAAA,IACvB,aAAa,aAAa;AAAA,IAC1B,cAAc,aAAa,iBAAiB;AAAA,IAC5C,kBAAkB,aAAa,qBAAqB;AAAA,IACpD;AAAA,IACA,QAAQ,aAAa,WAAW;AAAA,IAChC,MAAM,UAAU,aAAa,IAAI;AAAA,EACnC;AACF;AAOO,SAAS,gBAA+E;AAC7F,SAAO;AAAA,IACL,KAAK;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAUL,QAAQ,CAAC,CAAC;AAAA,EACZ;AACF;AAUA,eAAsB,WACpB,QACsC;AACtC,QAAM,kBAAkB,cAAc;AACtC,QAAM,cAAc,MAAM,OAAO,MAQ9B,gBAAgB,KAAK,gBAAgB,MAAM;AAE9C,MAAI,YAAY,KAAK,WAAW,GAAG;AACjC,WAAO;AAAA,EACT;AAEA,QAAM,YAAY,YAAY,KAAK,CAAC;AACpC,MAAI,CAAC,WAAW;AAEd,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACvE;AAEA,SAAO,uBAAuB,SAAS;AACzC;AAcO,SAAS,6BACd,aAKmB;AAInB,OAAK;AACL,SAAO,CAAC;AACV;","names":[]}