@prisma-next/sql-runtime 0.3.0-dev.6 → 0.3.0-dev.63

package/src/sql-context.ts

@@ -1,156 +1,443 @@
+import { checkContractComponentRequirements } from '@prisma-next/contract/framework-components';
+import type { ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
+import { createExecutionStack, type ExecutionStack } from '@prisma-next/core-execution-plane/stack';
 import type {
   RuntimeAdapterDescriptor,
   RuntimeAdapterInstance,
+  RuntimeDriverDescriptor,
+  RuntimeDriverInstance,
   RuntimeExtensionDescriptor,
   RuntimeExtensionInstance,
   RuntimeTargetDescriptor,
+  RuntimeTargetInstance,
 } from '@prisma-next/core-execution-plane/types';
+import { generateId } from '@prisma-next/ids/runtime';
 import { createOperationRegistry } from '@prisma-next/operations';
-import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import { runtimeError } from '@prisma-next/runtime-executor';
+import type { SqlContract, SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
 import type { SqlOperationSignature } from '@prisma-next/sql-operations';
 import type {
   Adapter,
+  CodecParamsDescriptor,
   CodecRegistry,
   LoweredStatement,
   QueryAst,
+  SqlDriver,
 } from '@prisma-next/sql-relational-core/ast';
 import { createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
-import type { QueryLaneContext } from '@prisma-next/sql-relational-core/query-lane-context';
-
-// ============================================================================
-// SQL Runtime Extension Types
-// ============================================================================
+import type {
+  AppliedMutationDefault,
+  ExecutionContext,
+  JsonSchemaValidateFn,
+  JsonSchemaValidatorRegistry,
+  MutationDefaultsOptions,
+  TypeHelperRegistry,
+} from '@prisma-next/sql-relational-core/query-lane-context';
+import { type as arktype } from 'arktype';
 
 /**
- * SQL runtime extension instance.
- * Extends the framework RuntimeExtensionInstance with SQL-specific hooks
- * for contributing codecs and operations to the runtime context.
+ * Runtime parameterized codec descriptor.
+ * Provides validation schema and optional init hook for codecs that support type parameters.
+ * Used at runtime to validate typeParams and create type helpers.
  *
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * This is a type alias for `CodecParamsDescriptor` from the AST layer,
+ * which is the shared definition used by both adapter and runtime.
  */
-export interface SqlRuntimeExtensionInstance<TTargetId extends string>
-  extends RuntimeExtensionInstance<'sql', TTargetId> {
-  /** Returns codecs to register in the runtime context. */
-  codecs?(): CodecRegistry;
-  /** Returns operations to register in the runtime context. */
-  operations?(): ReadonlyArray<SqlOperationSignature>;
+export type RuntimeParameterizedCodecDescriptor<
+  TParams = Record<string, unknown>,
+  THelper = unknown,
+> = CodecParamsDescriptor<TParams, THelper>;
+
+export interface SqlStaticContributions {
+  readonly codecs: () => CodecRegistry;
+  readonly operationSignatures: () => ReadonlyArray<SqlOperationSignature>;
+  // biome-ignore lint/suspicious/noExplicitAny: needed for covariance with concrete descriptor types
+  readonly parameterizedCodecs: () => ReadonlyArray<RuntimeParameterizedCodecDescriptor<any, any>>;
 }
 
-/**
- * SQL runtime extension descriptor.
- * Extends the framework RuntimeExtensionDescriptor with SQL-specific instance type.
- *
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
- */
-export interface SqlRuntimeExtensionDescriptor<TTargetId extends string>
-  extends RuntimeExtensionDescriptor<'sql', TTargetId, SqlRuntimeExtensionInstance<TTargetId>> {
+export interface SqlRuntimeTargetDescriptor<
+  TTargetId extends string = string,
+  TTargetInstance extends RuntimeTargetInstance<'sql', TTargetId> = RuntimeTargetInstance<
+    'sql',
+    TTargetId
+  >,
+> extends RuntimeTargetDescriptor<'sql', TTargetId, TTargetInstance>,
+    SqlStaticContributions {}
+
+export interface SqlRuntimeAdapterDescriptor<
+  TTargetId extends string = string,
+  TAdapterInstance extends RuntimeAdapterInstance<
+    'sql',
+    TTargetId
+  > = SqlRuntimeAdapterInstance<TTargetId>,
+> extends RuntimeAdapterDescriptor<'sql', TTargetId, TAdapterInstance>,
+    SqlStaticContributions {}
+
+export interface SqlRuntimeExtensionDescriptor<TTargetId extends string = string>
+  extends RuntimeExtensionDescriptor<'sql', TTargetId, SqlRuntimeExtensionInstance<TTargetId>>,
+    SqlStaticContributions {
   create(): SqlRuntimeExtensionInstance<TTargetId>;
 }
 
-// ============================================================================
-// SQL Runtime Adapter Instance
-// ============================================================================
+export interface SqlExecutionStack<TTargetId extends string = string> {
+  readonly target: SqlRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: SqlRuntimeAdapterDescriptor<TTargetId>;
+  readonly extensionPacks: readonly SqlRuntimeExtensionDescriptor<TTargetId>[];
+}
+
+export type SqlExecutionStackWithDriver<TTargetId extends string = string> = Omit<
+  ExecutionStack<
+    'sql',
+    TTargetId,
+    SqlRuntimeAdapterInstance<TTargetId>,
+    SqlRuntimeDriverInstance<TTargetId>,
+    SqlRuntimeExtensionInstance<TTargetId>
+  >,
+  'target' | 'adapter' | 'driver' | 'extensionPacks'
+> & {
+  readonly target: SqlRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: SqlRuntimeAdapterDescriptor<TTargetId, SqlRuntimeAdapterInstance<TTargetId>>;
+  readonly driver:
+    | RuntimeDriverDescriptor<'sql', TTargetId, unknown, SqlRuntimeDriverInstance<TTargetId>>
+    | undefined;
+  readonly extensionPacks: readonly SqlRuntimeExtensionDescriptor<TTargetId>[];
+};
+
+export interface SqlRuntimeExtensionInstance<TTargetId extends string>
+  extends RuntimeExtensionInstance<'sql', TTargetId> {}
 
-/**
- * SQL runtime adapter instance interface.
- * Combines RuntimeAdapterInstance identity with SQL Adapter behavior.
- * The instance IS an Adapter (via intersection), not HAS an adapter property.
- *
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
- */
 export type SqlRuntimeAdapterInstance<TTargetId extends string = string> = RuntimeAdapterInstance<
   'sql',
   TTargetId
 > &
   Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
 
-// ============================================================================
-// SQL Runtime Context
-// ============================================================================
+/**
+ * NOTE: Binding type is intentionally erased to unknown at this shared runtime layer.
+ * Target clients (for example `postgres()`) validate and construct the concrete binding
+ * before calling `driver.connect(binding)`, which keeps runtime behavior safe today.
+ * A future follow-up can preserve TBinding through stack/context generics end-to-end.
+ */
+export type SqlRuntimeDriverInstance<TTargetId extends string = string> = RuntimeDriverInstance<
+  'sql',
+  TTargetId
+> &
+  SqlDriver<unknown>;
 
-export interface RuntimeContext<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>>
-  extends QueryLaneContext<TContract> {
-  readonly adapter:
-    | Adapter<QueryAst, TContract, LoweredStatement>
-    | Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
+export function createSqlExecutionStack<TTargetId extends string>(options: {
+  readonly target: SqlRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: SqlRuntimeAdapterDescriptor<TTargetId>;
+  readonly driver?:
+    | RuntimeDriverDescriptor<'sql', TTargetId, unknown, SqlRuntimeDriverInstance<TTargetId>>
+    | undefined;
+  readonly extensionPacks?: readonly SqlRuntimeExtensionDescriptor<TTargetId>[] | undefined;
+}): SqlExecutionStackWithDriver<TTargetId> {
+  return createExecutionStack({
+    target: options.target,
+    adapter: options.adapter,
+    driver: options.driver,
+    extensionPacks: options.extensionPacks,
+  });
 }
 
-/**
- * Descriptor-first options for creating a SQL runtime context.
- * Takes the same framework composition as control-plane: target, adapter, extensionPacks.
- *
- * @template TContract - The SQL contract type
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
- */
-export interface CreateRuntimeContextOptions<
-  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
-  TTargetId extends string = string,
-> {
-  readonly contract: TContract;
-  readonly target: RuntimeTargetDescriptor<'sql', TTargetId>;
-  readonly adapter: RuntimeAdapterDescriptor<
-    'sql',
-    TTargetId,
-    SqlRuntimeAdapterInstance<TTargetId>
-  >;
-  readonly extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<TTargetId>>;
+export type { ExecutionContext, JsonSchemaValidatorRegistry, TypeHelperRegistry };
+
+export function assertExecutionStackContractRequirements(
+  contract: SqlContract<SqlStorage>,
+  stack: SqlExecutionStack,
+): void {
+  const providedComponentIds = new Set<string>([
+    stack.target.id,
+    stack.adapter.id,
+    ...stack.extensionPacks.map((pack) => pack.id),
+  ]);
+
+  const result = checkContractComponentRequirements({
+    contract,
+    expectedTargetFamily: 'sql',
+    expectedTargetId: stack.target.targetId,
+    providedComponentIds,
+  });
+
+  if (result.familyMismatch) {
+    throw runtimeError(
+      'RUNTIME.CONTRACT_FAMILY_MISMATCH',
+      `Contract target family '${result.familyMismatch.actual}' does not match runtime family '${result.familyMismatch.expected}'.`,
+      {
+        actual: result.familyMismatch.actual,
+        expected: result.familyMismatch.expected,
+      },
+    );
+  }
+
+  if (result.targetMismatch) {
+    throw runtimeError(
+      'RUNTIME.CONTRACT_TARGET_MISMATCH',
+      `Contract target '${result.targetMismatch.actual}' does not match runtime target descriptor '${result.targetMismatch.expected}'.`,
+      {
+        actual: result.targetMismatch.actual,
+        expected: result.targetMismatch.expected,
+      },
+    );
+  }
+
+  if (result.missingExtensionPackIds.length > 0) {
+    const packIds = result.missingExtensionPackIds;
+    const packList = packIds.map((id) => `'${id}'`).join(', ');
+    throw runtimeError(
+      'RUNTIME.MISSING_EXTENSION_PACK',
+      `Contract requires extension pack(s) ${packList}, but runtime descriptors do not provide matching component(s).`,
+      { packIds },
+    );
+  }
+}
+
+function validateTypeParams(
+  typeParams: Record<string, unknown>,
+  codecDescriptor: RuntimeParameterizedCodecDescriptor,
+  context: { typeName?: string; tableName?: string; columnName?: string },
+): Record<string, unknown> {
+  const result = codecDescriptor.paramsSchema(typeParams);
+  if (result instanceof arktype.errors) {
+    const messages = result.map((p: { message: string }) => p.message).join('; ');
+    const locationInfo = context.typeName
+      ? `type '${context.typeName}'`
+      : `column '${context.tableName}.${context.columnName}'`;
+    throw runtimeError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
+      `Invalid typeParams for ${locationInfo} (codecId: ${codecDescriptor.codecId}): ${messages}`,
+      { ...context, codecId: codecDescriptor.codecId, typeParams },
+    );
+  }
+  return result as Record<string, unknown>;
+}
+
+function collectParameterizedCodecDescriptors(
+  contributors: ReadonlyArray<SqlStaticContributions>,
+): Map<string, RuntimeParameterizedCodecDescriptor> {
+  const descriptors = new Map<string, RuntimeParameterizedCodecDescriptor>();
+
+  for (const contributor of contributors) {
+    for (const descriptor of contributor.parameterizedCodecs()) {
+      if (descriptors.has(descriptor.codecId)) {
+        throw runtimeError(
+          'RUNTIME.DUPLICATE_PARAMETERIZED_CODEC',
+          `Duplicate parameterized codec descriptor for codecId '${descriptor.codecId}'.`,
+          { codecId: descriptor.codecId },
+        );
+      }
+      descriptors.set(descriptor.codecId, descriptor);
+    }
+  }
+
+  return descriptors;
+}
+
+function initializeTypeHelpers(
+  storageTypes: Record<string, StorageTypeInstance> | undefined,
+  codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): TypeHelperRegistry {
+  const helpers: TypeHelperRegistry = {};
+
+  if (!storageTypes) {
+    return helpers;
+  }
+
+  for (const [typeName, typeInstance] of Object.entries(storageTypes)) {
+    const descriptor = codecDescriptors.get(typeInstance.codecId);
+
+    if (descriptor) {
+      const validatedParams = validateTypeParams(typeInstance.typeParams, descriptor, {
+        typeName,
+      });
+
+      if (descriptor.init) {
+        helpers[typeName] = descriptor.init(validatedParams);
+      } else {
+        helpers[typeName] = typeInstance;
+      }
+    } else {
+      helpers[typeName] = typeInstance;
+    }
+  }
+
+  return helpers;
+}
+
+function validateColumnTypeParams(
+  storage: SqlStorage,
+  codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): void {
+  for (const [tableName, table] of Object.entries(storage.tables)) {
+    for (const [columnName, column] of Object.entries(table.columns)) {
+      if (column.typeParams) {
+        const descriptor = codecDescriptors.get(column.codecId);
+        if (descriptor) {
+          validateTypeParams(column.typeParams, descriptor, { tableName, columnName });
+        }
+      }
+    }
+  }
 }
 
 /**
- * Creates a SQL runtime context from descriptor-first composition.
- *
- * The context includes:
- * - The validated contract
- * - The adapter instance (created from descriptor)
- * - Codec registry (populated from adapter + extension instances)
- * - Operation registry (populated from extension instances)
+ * Builds a registry of compiled JSON Schema validators by scanning the contract
+ * for columns whose codec descriptor provides an `init` hook returning `{ validate }`.
  *
- * @param options - Descriptor-first composition options
- * @returns RuntimeContext with registries wired from all components
+ * Handles both:
+ * - Inline `typeParams.schema` on columns
+ * - `typeRef` → `storage.types[ref]` with init hook results already in `types` registry
  */
-export function createRuntimeContext<
+function buildJsonSchemaValidatorRegistry(
+  contract: SqlContract<SqlStorage>,
+  types: TypeHelperRegistry,
+  codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): JsonSchemaValidatorRegistry | undefined {
+  const validators = new Map<string, JsonSchemaValidateFn>();
+
+  // Collect codec IDs that have init hooks (these produce { validate } helpers)
+  const codecIdsWithInit = new Set<string>();
+  for (const [codecId, descriptor] of codecDescriptors) {
+    if (descriptor.init) {
+      codecIdsWithInit.add(codecId);
+    }
+  }
+
+  if (codecIdsWithInit.size === 0) {
+    return undefined;
+  }
+
+  for (const [tableName, table] of Object.entries(contract.storage.tables)) {
+    for (const [columnName, column] of Object.entries(table.columns)) {
+      if (!codecIdsWithInit.has(column.codecId)) continue;
+
+      const key = `${tableName}.${columnName}`;
+
+      // Case 1: column references a named type → validator already compiled via init hook
+      if (column.typeRef) {
+        const helper = types[column.typeRef] as { validate?: JsonSchemaValidateFn } | undefined;
+        if (helper?.validate) {
+          validators.set(key, helper.validate);
+        }
+        continue;
+      }
+
+      // Case 2: inline typeParams with schema → compile via init hook
+      if (column.typeParams) {
+        const descriptor = codecDescriptors.get(column.codecId);
+        if (descriptor?.init) {
+          const helper = descriptor.init(column.typeParams) as
+            | { validate?: JsonSchemaValidateFn }
+            | undefined;
+          if (helper?.validate) {
+            validators.set(key, helper.validate);
+          }
+        }
+      }
+    }
+  }
+
+  if (validators.size === 0) return undefined;
+  return {
+    get: (key: string) => validators.get(key),
+    size: validators.size,
+  };
+}
+
+function computeExecutionDefaultValue(spec: ExecutionMutationDefaultValue): unknown {
+  switch (spec.kind) {
+    case 'generator':
+      return generateId(spec.params ? { id: spec.id, params: spec.params } : { id: spec.id });
+  }
+}
+
+function applyMutationDefaults(
+  contract: SqlContract<SqlStorage>,
+  options: MutationDefaultsOptions,
+): ReadonlyArray<AppliedMutationDefault> {
+  const defaults = contract.execution?.mutations.defaults ?? [];
+  if (defaults.length === 0) {
+    return [];
+  }
+
+  const applied: AppliedMutationDefault[] = [];
+  const appliedColumns = new Set<string>();
+
+  for (const mutationDefault of defaults) {
+    if (mutationDefault.ref.table !== options.table) {
+      continue;
+    }
+
+    const defaultSpec =
+      options.op === 'create' ? mutationDefault.onCreate : mutationDefault.onUpdate;
+    if (!defaultSpec) {
+      continue;
+    }
+
+    const columnName = mutationDefault.ref.column;
+    if (Object.hasOwn(options.values, columnName) || appliedColumns.has(columnName)) {
+      continue;
+    }
+
+    applied.push({
+      column: columnName,
+      value: computeExecutionDefaultValue(defaultSpec),
+    });
+    appliedColumns.add(columnName);
+  }
+
+  return applied;
+}
+
+export function createExecutionContext<
   TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
   TTargetId extends string = string,
->(options: CreateRuntimeContextOptions<TContract, TTargetId>): RuntimeContext<TContract> {
-  const { contract, adapter: adapterDescriptor, extensionPacks } = options;
+>(options: {
+  readonly contract: TContract;
+  readonly stack: SqlExecutionStack<TTargetId>;
+}): ExecutionContext<TContract> {
+  const { contract, stack } = options;
 
-  // Create adapter instance from descriptor
-  // The adapter instance IS an Adapter (via intersection)
-  const adapterInstance = adapterDescriptor.create();
+  assertExecutionStackContractRequirements(contract, stack);
 
-  // Create registries
   const codecRegistry = createCodecRegistry();
   const operationRegistry = createOperationRegistry();
 
-  // Register adapter codecs (adapter instance has profile.codecs())
-  const adapterCodecs = adapterInstance.profile.codecs();
-  for (const codec of adapterCodecs.values()) {
-    codecRegistry.register(codec);
-  }
+  const contributors: SqlStaticContributions[] = [
+    stack.target,
+    stack.adapter,
+    ...stack.extensionPacks,
+  ];
 
-  // Create extension instances and register their codecs/operations
-  for (const extDescriptor of extensionPacks ?? []) {
-    const extInstance = extDescriptor.create();
-
-    const extCodecs = extInstance.codecs?.();
-    if (extCodecs) {
-      for (const codec of extCodecs.values()) {
-        codecRegistry.register(codec);
-      }
+  for (const contributor of contributors) {
+    for (const c of contributor.codecs().values()) {
+      codecRegistry.register(c);
     }
-
-    const extOperations = extInstance.operations?.();
-    if (extOperations) {
-      for (const operation of extOperations) {
-        operationRegistry.register(operation);
-      }
+    for (const operation of contributor.operationSignatures()) {
+      operationRegistry.register(operation);
     }
   }
 
+  const parameterizedCodecDescriptors = collectParameterizedCodecDescriptors(contributors);
+
+  if (parameterizedCodecDescriptors.size > 0) {
+    validateColumnTypeParams(contract.storage, parameterizedCodecDescriptors);
+  }
+
+  const types = initializeTypeHelpers(contract.storage.types, parameterizedCodecDescriptors);
+
+  const jsonSchemaValidators = buildJsonSchemaValidatorRegistry(
+    contract,
+    types,
+    parameterizedCodecDescriptors,
+  );
+
   return {
     contract,
-    adapter: adapterInstance,
     operations: operationRegistry,
     codecs: codecRegistry,
+    types,
+    ...(jsonSchemaValidators ? { jsonSchemaValidators } : {}),
+    applyMutationDefaults: (options) => applyMutationDefaults(contract, options),
   };
 }

package/src/sql-family-adapter.ts

@@ -33,11 +33,15 @@ export class SqlFamilyAdapter<TContract extends SqlContract<SqlStorage>>
       });
     }
 
-    if (plan.meta.coreHash !== contract.coreHash) {
-      throw runtimeError('PLAN.HASH_MISMATCH', 'Plan core hash does not match runtime contract', {
-        planCoreHash: plan.meta.coreHash,
-        runtimeCoreHash: contract.coreHash,
-      });
+    if (plan.meta.storageHash !== contract.storageHash) {
+      throw runtimeError(
+        'PLAN.HASH_MISMATCH',
+        'Plan storage hash does not match runtime contract',
+        {
+          planStorageHash: plan.meta.storageHash,
+          runtimeStorageHash: contract.storageHash,
+        },
+      );
     }
   }
 }

package/src/sql-marker.ts

@@ -6,7 +6,7 @@ export interface SqlStatement {
 }
 
 export interface WriteMarkerInput {
-  readonly coreHash: string;
+  readonly storageHash: string;
   readonly profileHash: string;
   readonly contractJson?: unknown;
   readonly canonicalVersion?: number;
@@ -57,7 +57,7 @@ export interface WriteContractMarkerStatements {
 export function writeContractMarker(input: WriteMarkerInput): WriteContractMarkerStatements {
   const baseParams: readonly unknown[] = [
     1,
-    input.coreHash,
+    input.storageHash,
     input.profileHash,
     input.contractJson ?? null,
     input.canonicalVersion ?? null,