@prisma-next/family-sql 0.3.0-dev.12 → 0.3.0-dev.122

package/src/core/migrations/types.ts

@@ -1,12 +1,7 @@
-/**
- * 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 { ColumnDefault, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
 import type {
+  ControlAdapterDescriptor,
   ControlDriverInstance,
   ControlExtensionDescriptor,
   ControlTargetDescriptor,
@@ -23,109 +18,229 @@ 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
-// ============================================================================
+type ControlMutationDefaultSpan = {
+  readonly start: {
+    readonly offset: number;
+    readonly line: number;
+    readonly column: number;
+  };
+  readonly end: {
+    readonly offset: number;
+    readonly line: number;
+    readonly column: number;
+  };
+};
+
+type ControlMutationDefaultFunctionCall = {
+  readonly name: string;
+  readonly raw: string;
+  readonly args: readonly {
+    readonly raw: string;
+    readonly span: ControlMutationDefaultSpan;
+  }[];
+  readonly span: ControlMutationDefaultSpan;
+};
+
+type ControlMutationDefaultLoweringContext = {
+  readonly sourceId: string;
+  readonly modelName: string;
+  readonly fieldName: string;
+  readonly columnCodecId?: string;
+};
+
+export type ControlMutationDefaultFunctionResult =
+  | {
+      readonly ok: true;
+      readonly value:
+        | { readonly kind: 'storage'; readonly defaultValue: ColumnDefault }
+        | { readonly kind: 'execution'; readonly generated: ExecutionMutationDefaultValue };
+    }
+  | {
+      readonly ok: false;
+      readonly diagnostic: {
+        readonly code: string;
+        readonly message: string;
+        readonly sourceId?: string;
+        readonly span?: ControlMutationDefaultSpan;
+      };
+    };
+
+export type ControlMutationDefaultFunctionHandler = (input: {
+  readonly call: ControlMutationDefaultFunctionCall;
+  readonly context: ControlMutationDefaultLoweringContext;
+}) => ControlMutationDefaultFunctionResult;
+
+export interface ControlMutationDefaultFunctionEntry {
+  readonly lower: ControlMutationDefaultFunctionHandler;
+  readonly usageSignatures?: readonly string[];
+}
+
+export interface ControlMutationDefaultGeneratorDescriptor {
+  readonly id: string;
+  readonly applicableCodecIds: readonly string[];
+  readonly resolveGeneratedColumnDescriptor?: (input: {
+    readonly generated: {
+      readonly kind: string;
+      readonly id: string;
+      readonly params?: Record<string, unknown>;
+    };
+  }) =>
+    | {
+        readonly codecId: string;
+        readonly nativeType: string;
+        readonly typeRef?: string;
+        readonly typeParams?: Record<string, unknown>;
+      }
+    | undefined;
+}
+
+export interface PslScalarTypeDescriptor {
+  readonly codecId: string;
+  readonly nativeType: string;
+  readonly typeRef?: string;
+  readonly typeParams?: Record<string, unknown>;
+}
+
+export interface SqlControlStaticContributions {
+  readonly operationSignatures: () => ReadonlyArray<SqlOperationSignature>;
+  readonly controlMutationDefaults?: () => {
+    readonly defaultFunctionRegistry: ReadonlyMap<string, ControlMutationDefaultFunctionEntry>;
+    readonly generatorDescriptors: ReadonlyArray<ControlMutationDefaultGeneratorDescriptor>;
+  };
+  readonly pslTypeDescriptors?: () => {
+    readonly scalarTypeDescriptors: ReadonlyMap<string, PslScalarTypeDescriptor>;
+  };
+}
 
-/**
- * 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 function isDatabaseDependencyProvider(value: unknown): value is DatabaseDependencyProvider {
+  return typeof value === 'object' && value !== null && 'databaseDependencies' in value;
+}
+
+export function collectInitDependencies(
+  components: ReadonlyArray<unknown>,
+): readonly ComponentDatabaseDependency<unknown>[] {
+  const result: ComponentDatabaseDependency<unknown>[] = [];
+  for (const component of components) {
+    if (!isDatabaseDependencyProvider(component)) continue;
+    const deps = component.databaseDependencies?.init;
+    if (!deps) continue;
+    result.push(...deps);
+  }
+  return result;
+}
+
+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.
+ * Input for expanding parameterized native types.
+ */
+export interface ExpandNativeTypeInput {
+  readonly nativeType: string;
+  readonly codecId?: string;
+  readonly typeParams?: Record<string, unknown>;
+}
+
+/**
+ * Input for resolving an identity-value SQL literal used to backfill existing rows when
+ * adding a NOT NULL column without an explicit default.
  *
- * Database dependencies are attached to the descriptor (not the instance) because
- * they are declarative metadata that planner/verifier need without constructing instances.
+ * "Identity value" in the algebraic (monoid) sense: the neutral element for the type
+ * (0 for numbers, '' for strings, false for booleans, etc.).
  */
+export interface ResolveIdentityValueInput {
+  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;
+  /**
+   * Resolves the identity value (monoid neutral element) as a SQL literal for safely adding
+   * a NOT NULL column without an explicit default to a non-empty table.
+   *
+   * Return semantics:
+   * - string: use this literal
+   * - null: explicitly no safe identity value is known; fall back to another strategy
+   * - undefined: no opinion; planner may use built-in fallbacks
+   */
+  resolveIdentityValue?: (input: ResolveIdentityValueInput) => string | null | undefined;
+}
+
 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,23 +249,15 @@ 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.
-   * If omitted, the runner treats the origin as "no marker present" (empty database),
-   * and will only proceed if no marker exists (or if the marker already matches destination).
+   * If omitted or null, the runner skips origin validation entirely.
    */
   readonly origin?: SqlMigrationPlanContractInfo | null;
   /**
@@ -161,71 +268,43 @@ export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
   readonly meta?: AnyRecord;
 }
 
-// ============================================================================
-// SQL-Specific Planner Types
-// ============================================================================
-
-/**
- * Specific conflict kinds for SQL migrations.
- */
 export type SqlPlannerConflictKind =
   | 'typeMismatch'
   | 'nullabilityConflict'
   | 'indexIncompatible'
   | 'foreignKeyConflict'
   | 'missingButNonAdditive'
-  | 'unsupportedExtension'
-  | '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 +318,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 +357,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 +366,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);