@prisma-next/family-sql 0.3.0-dev.5 → 0.3.0-dev.53

package/src/core/migrations/types.ts

@@ -1,12 +1,6 @@
-/**
- * SQL-specific migration types.
- *
- * These types extend the canonical migration types from the framework control plane
- * with SQL-specific fields for execution (precheck SQL, execute SQL, etc.).
- */
-
 import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
 import type {
+  ControlAdapterDescriptor,
   ControlDriverInstance,
   ControlExtensionDescriptor,
   ControlTargetDescriptor,
@@ -23,109 +17,100 @@ import type {
   OperationContext,
   SchemaIssue,
 } from '@prisma-next/core-control-plane/types';
-import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { SqlContract, SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import type { SqlOperationSignature } from '@prisma-next/sql-operations';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import type { Result } from '@prisma-next/utils/result';
-import type { SqlControlFamilyInstance } from '../instance';
+import type { SqlControlFamilyInstance } from '../control-instance';
 
 export type AnyRecord = Readonly<Record<string, unknown>>;
 
-// ============================================================================
-// Component Database Dependencies
-// ============================================================================
+export interface SqlControlStaticContributions {
+  readonly operationSignatures: () => ReadonlyArray<SqlOperationSignature>;
+}
 
-/**
- * A single database dependency declared by a framework component.
- * Uses SqlMigrationPlanOperation so we inherit the existing precheck/execute/postcheck contract.
- *
- * Database dependencies allow components (extensions, adapters) to declare what database-side
- * persistence structures they require (e.g., Postgres extensions, schemas, functions).
- * The planner emits these as migration operations, and the verifier uses the pure verification
- * hook to check satisfaction against the schema IR.
- */
 export interface ComponentDatabaseDependency<TTargetDetails> {
-  /** Stable identifier for the dependency (e.g. 'postgres.extension.vector') */
   readonly id: string;
-  /** Human label for output (e.g. 'Enable vector extension') */
   readonly label: string;
-  /**
-   * Operations that install/ensure the dependency.
-   * Use SqlMigrationPlanOperation so we inherit the existing precheck/execute/postcheck contract.
-   */
   readonly install: readonly SqlMigrationPlanOperation<TTargetDetails>[];
-  /**
-   * Pure verification hook: checks whether this dependency is already installed
-   * based on the in-memory schema IR (no DB I/O).
-   *
-   * This must return structured issues suitable for CLI and tree output, not just a boolean.
-   */
   readonly verifyDatabaseDependencyInstalled: (schema: SqlSchemaIR) => readonly SchemaIssue[];
 }
 
-/**
- * Database dependencies declared by a framework component.
- */
 export interface ComponentDatabaseDependencies<TTargetDetails> {
-  /**
-   * Dependencies required for db init.
-   * Future: update dependencies can be added later (e.g. widening/destructive).
-   */
   readonly init?: readonly ComponentDatabaseDependency<TTargetDetails>[];
 }
 
-/**
- * Minimal structural type implemented by any descriptor that can expose
- * component-owned database dependencies. Targets/adapters typically omit
- * the property, while extensions provide dependency metadata.
- */
 export interface DatabaseDependencyProvider {
   readonly databaseDependencies?: ComponentDatabaseDependencies<unknown>;
 }
 
-// ============================================================================
-// SQL Control Extension Descriptor
-// ============================================================================
+export interface StorageTypePlanResult<TTargetDetails> {
+  readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+}
 
 /**
- * SQL-specific extension descriptor with optional database dependencies.
- * Extends the core ControlExtensionDescriptor with SQL-specific metadata.
- *
- * Database dependencies are attached to the descriptor (not the instance) because
- * they are declarative metadata that planner/verifier need without constructing instances.
+ * Input for expanding parameterized native types.
  */
+export interface ExpandNativeTypeInput {
+  readonly nativeType: string;
+  readonly codecId?: string;
+  readonly typeParams?: Record<string, unknown>;
+}
+
+export interface CodecControlHooks<TTargetDetails = unknown> {
+  planTypeOperations?: (options: {
+    readonly typeName: string;
+    readonly typeInstance: StorageTypeInstance;
+    readonly contract: SqlContract<SqlStorage>;
+    readonly schema: SqlSchemaIR;
+    readonly schemaName?: string;
+    readonly policy: MigrationOperationPolicy;
+  }) => StorageTypePlanResult<TTargetDetails>;
+  verifyType?: (options: {
+    readonly typeName: string;
+    readonly typeInstance: StorageTypeInstance;
+    readonly schema: SqlSchemaIR;
+    readonly schemaName?: string;
+  }) => readonly SchemaIssue[];
+  introspectTypes?: (options: {
+    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly schemaName?: string;
+  }) => Promise<Record<string, StorageTypeInstance>>;
+  /**
+   * Expands a parameterized native type to its full SQL representation.
+   * Used by schema verification to compare contract types against database types.
+   *
+   * For example, expands:
+   * - { nativeType: 'character varying', typeParams: { length: 255 } } -> 'character varying(255)'
+   * - { nativeType: 'numeric', typeParams: { precision: 10, scale: 2 } } -> 'numeric(10,2)'
+   *
+   * Returns the expanded type string, or the original nativeType if no expansion is needed.
+   */
+  expandNativeType?: (input: ExpandNativeTypeInput) => string;
+}
+
 export interface SqlControlExtensionDescriptor<TTargetId extends string>
-  extends ControlExtensionDescriptor<'sql', TTargetId> {
-  /** Optional database dependencies this extension requires. */
+  extends ControlExtensionDescriptor<'sql', TTargetId>,
+    SqlControlStaticContributions {
   readonly databaseDependencies?: ComponentDatabaseDependencies<unknown>;
 }
 
-// ============================================================================
-// SQL-Specific Plan Types
-// ============================================================================
+export interface SqlControlAdapterDescriptor<TTargetId extends string>
+  extends ControlAdapterDescriptor<'sql', TTargetId>,
+    SqlControlStaticContributions {}
 
-/**
- * A single step in a SQL migration operation (precheck, execute, or postcheck).
- */
 export interface SqlMigrationPlanOperationStep {
   readonly description: string;
   readonly sql: string;
   readonly meta?: AnyRecord;
 }
 
-/**
- * Target details for a SQL migration operation (table, column, index, etc.).
- */
 export interface SqlMigrationPlanOperationTarget<TTargetDetails> {
   readonly id: string;
   readonly details?: TTargetDetails;
 }
 
-/**
- * A single SQL migration operation with SQL-specific fields.
- * Extends the core MigrationPlanOperation with SQL execution details.
- */
 export interface SqlMigrationPlanOperation<TTargetDetails> extends MigrationPlanOperation {
-  /** Optional detailed explanation of what this operation does and why. */
   readonly summary?: string;
   readonly target: SqlMigrationPlanOperationTarget<TTargetDetails>;
   readonly precheck: readonly SqlMigrationPlanOperationStep[];
@@ -134,18 +119,11 @@ export interface SqlMigrationPlanOperation<TTargetDetails> extends MigrationPlan
   readonly meta?: AnyRecord;
 }
 
-/**
- * Contract identity information for SQL migrations.
- */
 export interface SqlMigrationPlanContractInfo {
-  readonly coreHash: string;
+  readonly storageHash: string;
   readonly profileHash?: string;
 }
 
-/**
- * A SQL migration plan with SQL-specific fields.
- * Extends the core MigrationPlan with origin tracking and metadata.
- */
 export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
   /**
    * Origin contract identity that the plan expects the database to currently be at.
@@ -161,13 +139,6 @@ export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
   readonly meta?: AnyRecord;
 }
 
-// ============================================================================
-// SQL-Specific Planner Types
-// ============================================================================
-
-/**
- * Specific conflict kinds for SQL migrations.
- */
 export type SqlPlannerConflictKind =
   | 'typeMismatch'
   | 'nullabilityConflict'
@@ -178,54 +149,36 @@ export type SqlPlannerConflictKind =
   | 'extensionMissing'
   | 'unsupportedOperation';
 
-/**
- * Location information for SQL planner conflicts.
- */
 export interface SqlPlannerConflictLocation {
   readonly table?: string;
   readonly column?: string;
   readonly index?: string;
   readonly constraint?: string;
   readonly extension?: string;
+  readonly type?: string;
 }
 
-/**
- * A SQL-specific planner conflict with additional location information.
- * Extends the core MigrationPlannerConflict.
- */
 export interface SqlPlannerConflict extends MigrationPlannerConflict {
   readonly kind: SqlPlannerConflictKind;
   readonly location?: SqlPlannerConflictLocation;
   readonly meta?: AnyRecord;
 }
 
-/**
- * Successful SQL planner result with the migration plan.
- */
 export interface SqlPlannerSuccessResult<TTargetDetails>
   extends Omit<MigrationPlannerSuccessResult, 'plan'> {
   readonly kind: 'success';
   readonly plan: SqlMigrationPlan<TTargetDetails>;
 }
 
-/**
- * Failed SQL planner result with the list of conflicts.
- */
 export interface SqlPlannerFailureResult extends Omit<MigrationPlannerFailureResult, 'conflicts'> {
   readonly kind: 'failure';
   readonly conflicts: readonly SqlPlannerConflict[];
 }
 
-/**
- * Union type for SQL planner results.
- */
 export type SqlPlannerResult<TTargetDetails> =
   | SqlPlannerSuccessResult<TTargetDetails>
   | SqlPlannerFailureResult;
 
-/**
- * Options for SQL migration planner.
- */
 export interface SqlMigrationPlannerPlanOptions {
   readonly contract: SqlContract<SqlStorage>;
   readonly schema: SqlSchemaIR;
@@ -239,29 +192,15 @@ export interface SqlMigrationPlannerPlanOptions {
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
 }
 
-/**
- * SQL migration planner interface.
- * Extends the core MigrationPlanner with SQL-specific types.
- */
 export interface SqlMigrationPlanner<TTargetDetails> {
   plan(options: SqlMigrationPlannerPlanOptions): SqlPlannerResult<TTargetDetails>;
 }
 
-// ============================================================================
-// SQL-Specific Runner Types
-// ============================================================================
-
-/**
- * Callbacks for SQL migration runner execution.
- */
 export interface SqlMigrationRunnerExecuteCallbacks<TTargetDetails> {
   onOperationStart?(operation: SqlMigrationPlanOperation<TTargetDetails>): void;
   onOperationComplete?(operation: SqlMigrationPlanOperation<TTargetDetails>): void;
 }
 
-/**
- * Options for SQL migration runner execution.
- */
 export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
   readonly plan: SqlMigrationPlan<TTargetDetails>;
   readonly driver: ControlDriverInstance<'sql', string>;
@@ -292,9 +231,6 @@ export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
 }
 
-/**
- * Error codes for SQL migration runner failures.
- */
 export type SqlMigrationRunnerErrorCode =
   | 'DESTINATION_CONTRACT_MISMATCH'
   | 'MARKER_ORIGIN_MISMATCH'
@@ -304,73 +240,36 @@ export type SqlMigrationRunnerErrorCode =
   | 'SCHEMA_VERIFY_FAILED'
   | 'EXECUTION_FAILED';
 
-/**
- * Detailed information about a SQL migration runner failure.
- * Extends the core MigrationRunnerFailure with SQL-specific error codes.
- */
 export interface SqlMigrationRunnerFailure extends MigrationRunnerFailure {
   readonly code: SqlMigrationRunnerErrorCode;
   readonly meta?: AnyRecord;
 }
 
-/**
- * Success value for SQL migration runner execution.
- * Extends core type for type branding and potential SQL-specific extensions.
- */
 export interface SqlMigrationRunnerSuccessValue extends MigrationRunnerSuccessValue {}
 
-/**
- * Result type for SQL migration runner execution.
- */
 export type SqlMigrationRunnerResult = Result<
   SqlMigrationRunnerSuccessValue,
   SqlMigrationRunnerFailure
 >;
 
-/**
- * SQL migration runner interface.
- * Extends the core MigrationRunner with SQL-specific types.
- */
 export interface SqlMigrationRunner<TTargetDetails> {
   execute(
     options: SqlMigrationRunnerExecuteOptions<TTargetDetails>,
   ): Promise<SqlMigrationRunnerResult>;
 }
 
-// ============================================================================
-// SQL Control Target Descriptor
-// ============================================================================
-
-/**
- * SQL control target descriptor with migration support.
- * Extends the core ControlTargetDescriptor with SQL-specific migration methods.
- */
 export interface SqlControlTargetDescriptor<TTargetId extends string, TTargetDetails>
   extends ControlTargetDescriptor<
-    'sql',
-    TTargetId,
-    ControlTargetInstance<'sql', TTargetId>,
-    SqlControlFamilyInstance
-  > {
-  /**
-   * Creates a SQL migration planner for this target.
-   * Direct method for SQL-specific usage.
-   */
+      'sql',
+      TTargetId,
+      ControlTargetInstance<'sql', TTargetId>,
+      SqlControlFamilyInstance
+    >,
+    SqlControlStaticContributions {
   createPlanner(family: SqlControlFamilyInstance): SqlMigrationPlanner<TTargetDetails>;
-  /**
-   * Creates a SQL migration runner for this target.
-   * Direct method for SQL-specific usage.
-   */
   createRunner(family: SqlControlFamilyInstance): SqlMigrationRunner<TTargetDetails>;
 }
 
-// ============================================================================
-// Helper Types
-// ============================================================================
-
-/**
- * Options for creating a SQL migration plan.
- */
 export interface CreateSqlMigrationPlanOptions<TTargetDetails> {
   readonly targetId: string;
   readonly origin?: SqlMigrationPlanContractInfo | null;

package/src/core/runtime-descriptor.ts

@@ -1,45 +1,23 @@
-import type {
-  RuntimeAdapterDescriptor,
-  RuntimeDriverDescriptor,
-  RuntimeExtensionDescriptor,
-  RuntimeFamilyDescriptor,
-  RuntimeTargetDescriptor,
-} from '@prisma-next/core-execution-plane/types';
-import {
-  createSqlRuntimeFamilyInstance,
-  type SqlRuntimeAdapterInstance,
-  type SqlRuntimeDriverInstance,
-  type SqlRuntimeFamilyInstance,
-} from './runtime-instance';
+import type { RuntimeFamilyDescriptor } from '@prisma-next/core-execution-plane/types';
+import { createSqlRuntimeFamilyInstance, type SqlRuntimeFamilyInstance } from './runtime-instance';
 
 /**
- * SQL runtime family descriptor implementation.
- * Provides factory method to create SQL runtime family instance.
+ * SQL execution-plane family descriptor.
+ *
+ * Note: this is currently named `sqlRuntimeFamilyDescriptor` because the execution plane
+ * framework types are still using the `Runtime*` naming (`RuntimeFamilyDescriptor`, etc.).
+ *
+ * This will be renamed to `sqlExecutionFamilyDescriptor` as part of `TML-1842`.
  */
-export class SqlRuntimeFamilyDescriptor
-  implements RuntimeFamilyDescriptor<'sql', SqlRuntimeFamilyInstance>
-{
-  readonly kind = 'family' as const;
-  readonly id = 'sql';
-  readonly familyId = 'sql' as const;
-  readonly version = '0.0.1';
+export const sqlRuntimeFamilyDescriptor: RuntimeFamilyDescriptor<'sql', SqlRuntimeFamilyInstance> =
+  {
+    kind: 'family',
+    id: 'sql',
+    familyId: 'sql',
+    version: '0.0.1',
+    create() {
+      return createSqlRuntimeFamilyInstance();
+    },
+  };
 
-  create<TTargetId extends string>(options: {
-    readonly target: RuntimeTargetDescriptor<'sql', TTargetId>;
-    readonly adapter: RuntimeAdapterDescriptor<
-      'sql',
-      TTargetId,
-      SqlRuntimeAdapterInstance<TTargetId>
-    >;
-    readonly driver: RuntimeDriverDescriptor<'sql', TTargetId, SqlRuntimeDriverInstance<TTargetId>>;
-    readonly extensionPacks: readonly RuntimeExtensionDescriptor<'sql', TTargetId>[];
-  }): SqlRuntimeFamilyInstance {
-    return createSqlRuntimeFamilyInstance({
-      family: this,
-      target: options.target,
-      adapter: options.adapter,
-      driver: options.driver,
-      extensionPacks: options.extensionPacks,
-    });
-  }
-}
+Object.freeze(sqlRuntimeFamilyDescriptor);

package/src/core/runtime-instance.ts

@@ -1,144 +1,22 @@
-import { assertRuntimeContractRequirementsSatisfied } from '@prisma-next/core-execution-plane/framework-components';
-import type {
-  RuntimeAdapterDescriptor,
-  RuntimeDriverDescriptor,
-  RuntimeDriverInstance,
-  RuntimeFamilyDescriptor,
-  RuntimeFamilyInstance,
-  RuntimeTargetDescriptor,
-} from '@prisma-next/core-execution-plane/types';
-import type { Log, Plugin, RuntimeVerifyOptions } from '@prisma-next/runtime-executor';
-import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
-import type {
-  Adapter,
-  LoweredStatement,
-  SelectAst,
-  SqlDriver,
-} from '@prisma-next/sql-relational-core/ast';
-import type {
-  Runtime,
-  RuntimeOptions,
-  SqlRuntimeAdapterInstance,
-  SqlRuntimeExtensionDescriptor,
-} from '@prisma-next/sql-runtime';
-import { createRuntime, createRuntimeContext } from '@prisma-next/sql-runtime';
+import type { RuntimeFamilyInstance } from '@prisma-next/core-execution-plane/types';
 
 /**
- * SQL runtime driver instance type.
- * Combines identity properties with SQL-specific behavior methods.
- */
-export type SqlRuntimeDriverInstance<TTargetId extends string = string> = RuntimeDriverInstance<
-  'sql',
-  TTargetId
-> &
-  SqlDriver;
-
-// Re-export SqlRuntimeAdapterInstance from sql-runtime for consumers
-export type { SqlRuntimeAdapterInstance } from '@prisma-next/sql-runtime';
-
-/**
- * SQL runtime family instance interface.
- * Extends base RuntimeFamilyInstance with SQL-specific runtime creation method.
+ * SQL execution-plane family instance interface.
+ *
+ * Note: this is currently named `SqlRuntimeFamilyInstance` because the execution plane
+ * framework types are still using the `Runtime*` naming (`RuntimeFamilyInstance`, etc.).
+ *
+ * This will be renamed to `SqlExecutionFamilyInstance` as part of `TML-1842`.
  */
-export interface SqlRuntimeFamilyInstance extends RuntimeFamilyInstance<'sql'> {
-  /**
-   * Creates a SQL runtime from contract, driver options, and verification settings.
-   *
-   * Extension packs are routed through composition (at instance creation time),
-   * not through this method. This aligns with control-plane composition patterns.
-   *
-   * @param options - Runtime creation options
-   * @param options.contract - SQL contract
-   * @param options.driverOptions - Driver options (e.g., PostgresDriverOptions)
-   * @param options.verify - Runtime verification options
-   * @param options.plugins - Optional plugins
-   * @param options.mode - Optional runtime mode
-   * @param options.log - Optional log instance
-   * @returns Runtime instance
-   */
-  createRuntime<TContract extends SqlContract<SqlStorage>>(options: {
-    readonly contract: TContract;
-    readonly driverOptions: unknown;
-    readonly verify: RuntimeVerifyOptions;
-    readonly plugins?: readonly Plugin<
-      TContract,
-      Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
-      SqlDriver
-    >[];
-    readonly mode?: 'strict' | 'permissive';
-    readonly log?: Log;
-  }): Runtime;
-}
+export interface SqlRuntimeFamilyInstance extends RuntimeFamilyInstance<'sql'> {}
 
 /**
- * Creates a SQL runtime family instance from runtime descriptors.
+ * Creates a SQL execution-plane family instance.
  *
- * Routes the same framework composition as control-plane:
- * family, target, adapter, driver, extensionPacks (all as descriptors with IDs).
+ * This will be renamed to `createSqlExecutionFamilyInstance()` as part of `TML-1842`.
  */
-export function createSqlRuntimeFamilyInstance<TTargetId extends string>(options: {
-  readonly family: RuntimeFamilyDescriptor<'sql'>;
-  readonly target: RuntimeTargetDescriptor<'sql', TTargetId>;
-  readonly adapter: RuntimeAdapterDescriptor<
-    'sql',
-    TTargetId,
-    SqlRuntimeAdapterInstance<TTargetId>
-  >;
-  readonly driver: RuntimeDriverDescriptor<'sql', TTargetId, SqlRuntimeDriverInstance<TTargetId>>;
-  readonly extensionPacks?: readonly SqlRuntimeExtensionDescriptor<TTargetId>[];
-}): SqlRuntimeFamilyInstance {
-  const {
-    family: familyDescriptor,
-    target: targetDescriptor,
-    adapter: adapterDescriptor,
-    driver: driverDescriptor,
-    extensionPacks: extensionDescriptors = [],
-  } = options;
-
+export function createSqlRuntimeFamilyInstance(): SqlRuntimeFamilyInstance {
   return {
     familyId: 'sql' as const,
-    createRuntime<TContract extends SqlContract<SqlStorage>>(runtimeOptions: {
-      readonly contract: TContract;
-      readonly driverOptions: unknown;
-      readonly verify: RuntimeVerifyOptions;
-      readonly plugins?: readonly Plugin<
-        TContract,
-        Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
-        SqlDriver
-      >[];
-      readonly mode?: 'strict' | 'permissive';
-      readonly log?: Log;
-    }): Runtime {
-      // Validate contract requirements against provided descriptors
-      assertRuntimeContractRequirementsSatisfied({
-        contract: runtimeOptions.contract,
-        family: familyDescriptor,
-        target: targetDescriptor,
-        adapter: adapterDescriptor,
-        extensionPacks: extensionDescriptors,
-      });
-
-      // Create driver instance
-      const driverInstance = driverDescriptor.create(runtimeOptions.driverOptions);
-
-      // Create context via descriptor-first API
-      const context = createRuntimeContext<TContract, TTargetId>({
-        contract: runtimeOptions.contract,
-        target: targetDescriptor,
-        adapter: adapterDescriptor,
-        extensionPacks: extensionDescriptors,
-      });
-
-      const runtimeOptions_: RuntimeOptions<TContract> = {
-        driver: driverInstance,
-        verify: runtimeOptions.verify,
-        context,
-        ...(runtimeOptions.plugins ? { plugins: runtimeOptions.plugins } : {}),
-        ...(runtimeOptions.mode ? { mode: runtimeOptions.mode } : {}),
-        ...(runtimeOptions.log ? { log: runtimeOptions.log } : {}),
-      };
-
-      return createRuntime(runtimeOptions_);
-    },
   };
 }