@prisma-next/sql-runtime 0.3.0-pr.99.6 → 0.3.0

package/src/sql-context.ts

@@ -1,220 +1,206 @@
-import type {
-  RuntimeAdapterDescriptor,
-  RuntimeAdapterInstance,
-  RuntimeExtensionDescriptor,
-  RuntimeExtensionInstance,
-  RuntimeTargetDescriptor,
-} from '@prisma-next/core-execution-plane/types';
-import { createOperationRegistry } from '@prisma-next/operations';
-import type { SqlContract, SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
-import type { SqlOperationSignature } from '@prisma-next/sql-operations';
+import type { Contract, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
+import type { ComponentDescriptor } from '@prisma-next/framework-components/components';
+import { checkContractComponentRequirements } from '@prisma-next/framework-components/components';
+import {
+  createExecutionStack,
+  type ExecutionStack,
+  type RuntimeAdapterDescriptor,
+  type RuntimeAdapterInstance,
+  type RuntimeDriverDescriptor,
+  type RuntimeDriverInstance,
+  type RuntimeExtensionDescriptor,
+  type RuntimeExtensionInstance,
+  type RuntimeTargetDescriptor,
+  type RuntimeTargetInstance,
+} from '@prisma-next/framework-components/execution';
+import { runtimeError } from '@prisma-next/framework-components/runtime';
+import type { SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import {
+  createSqlOperationRegistry,
+  type SqlOperationDescriptor,
+} from '@prisma-next/sql-operations';
 import type {
   Adapter,
+  AnyQueryAst,
+  CodecParamsDescriptor,
   CodecRegistry,
   LoweredStatement,
-  QueryAst,
+  SqlDriver,
 } from '@prisma-next/sql-relational-core/ast';
 import { createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
 import type {
-  QueryLaneContext,
+  AppliedMutationDefault,
+  ExecutionContext,
+  JsonSchemaValidateFn,
+  JsonSchemaValidatorRegistry,
+  MutationDefaultsOptions,
   TypeHelperRegistry,
 } from '@prisma-next/sql-relational-core/query-lane-context';
-import type { Type } from 'arktype';
 import { type as arktype } from 'arktype';
 
-// ============================================================================
-// Runtime Parameterized Codec Descriptor Types
-// ============================================================================
-
 /**
  * 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.
+ *
+ * This is a type alias for `CodecParamsDescriptor` from the AST layer,
+ * which is the shared definition used by both adapter and runtime.
  */
-export interface RuntimeParameterizedCodecDescriptor<
+export type RuntimeParameterizedCodecDescriptor<
   TParams = Record<string, unknown>,
   THelper = unknown,
-> {
-  /** The codec ID this descriptor applies to (e.g., 'pg/vector@1') */
-  readonly codecId: string;
-
-  /**
-   * Arktype schema for validating typeParams.
-   * The schema is used to validate both storage.types entries and inline column typeParams.
-   */
-  readonly paramsSchema: Type<TParams>;
-
-  /**
-   * Optional init hook called during runtime context creation.
-   * Receives validated params and returns a helper object to be stored in context.types.
-   * If not provided, the validated params are stored directly.
-   */
-  readonly init?: (params: TParams) => THelper;
-}
+> = CodecParamsDescriptor<TParams, THelper>;
 
-// ============================================================================
-// SQL Runtime Extension Types
-// ============================================================================
-
-/**
- * SQL runtime extension instance.
- * Extends the framework RuntimeExtensionInstance with SQL-specific hooks
- * for contributing codecs and operations to the runtime context.
- *
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
- */
-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>;
-  /**
-   * Returns parameterized codec descriptors for type validation and helper creation.
-   * Uses unknown for type parameters to allow any concrete descriptor types.
-   */
+export interface SqlStaticContributions {
+  readonly codecs: () => CodecRegistry;
   // biome-ignore lint/suspicious/noExplicitAny: needed for covariance with concrete descriptor types
-  parameterizedCodecs?(): ReadonlyArray<RuntimeParameterizedCodecDescriptor<any, any>>;
+  readonly parameterizedCodecs: () => ReadonlyArray<RuntimeParameterizedCodecDescriptor<any, any>>;
+  readonly queryOperations?: () => ReadonlyArray<SqlOperationDescriptor>;
+  readonly mutationDefaultGenerators?: () => ReadonlyArray<RuntimeMutationDefaultGenerator>;
 }
 
-/**
- * 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 RuntimeMutationDefaultGenerator {
+  readonly id: string;
+  readonly generate: (params?: Record<string, unknown>) => unknown;
+}
+
+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
-// ============================================================================
-
-export type { TypeHelperRegistry };
-
-export interface RuntimeContext<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>>
-  extends QueryLaneContext<TContract> {
-  readonly adapter:
-    | Adapter<QueryAst, TContract, LoweredStatement>
-    | Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
-
-  /**
-   * Initialized type helpers from storage.types.
-   * Each entry corresponds to a named type instance in the contract's storage.types.
-   * The value is the result of calling the codec's init hook (if provided)
-   * or the validated typeParams (if no init hook).
-   */
-  readonly types?: TypeHelperRegistry;
-}
+  Adapter<AnyQueryAst, Contract<SqlStorage>, LoweredStatement>;
 
 /**
- * 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')
+ * 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 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 SqlRuntimeDriverInstance<TTargetId extends string = string> = RuntimeDriverInstance<
+  'sql',
+  TTargetId
+> &
+  SqlDriver<unknown>;
+
+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,
+  });
 }
 
-// ============================================================================
-// Runtime Error Types and Helpers
-// ============================================================================
+export type { ExecutionContext, JsonSchemaValidatorRegistry, TypeHelperRegistry };
 
-/**
- * Structured error thrown by the SQL runtime.
- *
- * Aligns with the repository's error envelope convention:
- * - `code`: Stable error code for programmatic handling (e.g., `RUNTIME.TYPE_PARAMS_INVALID`)
- * - `category`: Error source category (`RUNTIME`)
- * - `severity`: Error severity level (`error`)
- * - `details`: Optional structured details for debugging
- *
- * @example
- * ```typescript
- * try {
- *   createRuntimeContext({ ... });
- * } catch (e) {
- *   if ((e as RuntimeError).code === 'RUNTIME.TYPE_PARAMS_INVALID') {
- *     console.error('Invalid type parameters:', (e as RuntimeError).details);
- *   }
- * }
- * ```
- */
-export interface RuntimeError extends Error {
-  /** Stable error code for programmatic handling (e.g., `RUNTIME.TYPE_PARAMS_INVALID`) */
-  readonly code: string;
-  /** Error source category */
-  readonly category: 'RUNTIME';
-  /** Error severity level */
-  readonly severity: 'error';
-  /** Optional structured details for debugging */
-  readonly details?: Record<string, unknown>;
-}
+export function assertExecutionStackContractRequirements(
+  contract: Contract<SqlStorage>,
+  stack: SqlExecutionStack,
+): void {
+  const providedComponentIds = new Set<string>([
+    stack.target.id,
+    stack.adapter.id,
+    ...stack.extensionPacks.map((pack) => pack.id),
+  ]);
 
-/**
- * Creates a RuntimeError for invalid type parameters.
- *
- * Error code: `RUNTIME.TYPE_PARAMS_INVALID`
- *
- * Thrown when:
- * - `storage.types` entries have typeParams that fail codec schema validation
- * - Column inline typeParams fail codec schema validation
- *
- * @internal
- */
-function runtimeTypeParamsInvalid(
-  message: string,
-  details?: Record<string, unknown>,
-): RuntimeError {
-  const error = new Error(message) as RuntimeError;
-  Object.defineProperty(error, 'name', { value: 'RuntimeError', configurable: true });
-  return Object.assign(error, {
-    code: 'RUNTIME.TYPE_PARAMS_INVALID',
-    category: 'RUNTIME' as const,
-    severity: 'error' as const,
-    details,
+  const result = checkContractComponentRequirements({
+    contract,
+    expectedTargetFamily: 'sql',
+    expectedTargetId: stack.target.targetId,
+    providedComponentIds,
   });
-}
 
-// ============================================================================
-// Parameterized Type Validation
-// ============================================================================
+  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 },
+    );
+  }
+}
 
-/**
- * Validates typeParams against the codec's paramsSchema.
- * @throws RuntimeError with code RUNTIME.TYPE_PARAMS_INVALID if validation fails
- */
 function validateTypeParams(
   typeParams: Record<string, unknown>,
   codecDescriptor: RuntimeParameterizedCodecDescriptor,
@@ -226,7 +212,8 @@ function validateTypeParams(
     const locationInfo = context.typeName
       ? `type '${context.typeName}'`
       : `column '${context.tableName}.${context.columnName}'`;
-    throw runtimeTypeParamsInvalid(
+    throw runtimeError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
       `Invalid typeParams for ${locationInfo} (codecId: ${codecDescriptor.codecId}): ${messages}`,
       { ...context, codecId: codecDescriptor.codecId, typeParams },
     );
@@ -234,43 +221,27 @@ function validateTypeParams(
   return result as Record<string, unknown>;
 }
 
-/**
- * Collects parameterized codec descriptors from extension instances.
- * Returns a map of codecId → descriptor for quick lookup.
- */
 function collectParameterizedCodecDescriptors(
-  extensionInstances: ReadonlyArray<SqlRuntimeExtensionInstance<string>>,
+  contributors: ReadonlyArray<SqlStaticContributions>,
 ): Map<string, RuntimeParameterizedCodecDescriptor> {
   const descriptors = new Map<string, RuntimeParameterizedCodecDescriptor>();
 
-  for (const extInstance of extensionInstances) {
-    const paramCodecs = extInstance.parameterizedCodecs?.();
-    if (paramCodecs) {
-      for (const descriptor of paramCodecs) {
-        if (descriptors.has(descriptor.codecId)) {
-          console.warn(
-            `Duplicate parameterized codec descriptor for codecId '${descriptor.codecId}' - using later registration`,
-          );
-        }
-        descriptors.set(descriptor.codecId, descriptor);
+  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;
 }
 
-/**
- * Initializes type helpers from storage.types using codec descriptors.
- *
- * For each named type instance in `storage.types`:
- * - If a codec descriptor exists with an `init` hook: calls the hook and stores the result
- * - Otherwise: stores the full type instance metadata directly (codecId, nativeType, typeParams)
- *
- * This matches the typing in `ExtractSchemaTypes<Contract>` which extracts
- * `Contract['storage']['types']` directly, ensuring runtime values match static types
- * when no init hook transforms the value.
- */
 function initializeTypeHelpers(
   storageTypes: Record<string, StorageTypeInstance> | undefined,
   codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
@@ -285,20 +256,16 @@ function initializeTypeHelpers(
     const descriptor = codecDescriptors.get(typeInstance.codecId);
 
     if (descriptor) {
-      // Validate typeParams against the codec's schema
       const validatedParams = validateTypeParams(typeInstance.typeParams, descriptor, {
         typeName,
       });
 
-      // Call init hook if provided, otherwise store full type instance
       if (descriptor.init) {
         helpers[typeName] = descriptor.init(validatedParams);
       } else {
-        // No init hook: expose full type instance metadata (matches contract typing)
         helpers[typeName] = typeInstance;
       }
     } else {
-      // No descriptor found: expose full type instance (no validation possible)
       helpers[typeName] = typeInstance;
     }
   }
@@ -306,10 +273,6 @@ function initializeTypeHelpers(
   return helpers;
 }
 
-/**
- * Validates inline column typeParams across all tables.
- * @throws RuntimeError with code RUNTIME.TYPE_PARAMS_INVALID if validation fails
- */
 function validateColumnTypeParams(
   storage: SqlStorage,
   codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
@@ -327,76 +290,213 @@ function validateColumnTypeParams(
 }
 
 /**
- * Creates a SQL runtime context from descriptor-first composition.
+ * Builds a registry of compiled JSON Schema validators by scanning the contract
+ * for columns whose codec descriptor provides an `init` hook returning `{ validate }`.
  *
- * 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)
- * - Types registry (initialized helpers from storage.types)
- *
- * @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<
-  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
-  TTargetId extends string = string,
->(options: CreateRuntimeContextOptions<TContract, TTargetId>): RuntimeContext<TContract> {
-  const { contract, adapter: adapterDescriptor, extensionPacks } = options;
+function buildJsonSchemaValidatorRegistry(
+  contract: Contract<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);
+    }
+  }
 
-  // Create adapter instance from descriptor
-  // The adapter instance IS an Adapter (via intersection)
-  const adapterInstance = adapterDescriptor.create();
+  if (codecIdsWithInit.size === 0) {
+    return undefined;
+  }
 
-  // Create registries
-  const codecRegistry = createCodecRegistry();
-  const operationRegistry = createOperationRegistry();
+  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;
 
-  // Register adapter codecs (adapter instance has profile.codecs())
-  const adapterCodecs = adapterInstance.profile.codecs();
-  for (const codec of adapterCodecs.values()) {
-    codecRegistry.register(codec);
-  }
+      const key = `${tableName}.${columnName}`;
 
-  // Create extension instances and collect their contributions
-  const extensionInstances: SqlRuntimeExtensionInstance<TTargetId>[] = [];
+      // 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;
+      }
 
-  for (const extDescriptor of extensionPacks ?? []) {
-    const extInstance = extDescriptor.create();
-    extensionInstances.push(extInstance);
+      // 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);
+          }
+        }
+      }
+    }
+  }
 
-    const extCodecs = extInstance.codecs?.();
-    if (extCodecs) {
-      for (const codec of extCodecs.values()) {
-        codecRegistry.register(codec);
+  if (validators.size === 0) return undefined;
+  return {
+    get: (key: string) => validators.get(key),
+    size: validators.size,
+  };
+}
+
+function collectMutationDefaultGenerators(
+  contributors: ReadonlyArray<SqlStaticContributions & { readonly id: string }>,
+): ReadonlyMap<string, RuntimeMutationDefaultGenerator> {
+  const generators = new Map<string, RuntimeMutationDefaultGenerator>();
+  const owners = new Map<string, string>();
+
+  for (const contributor of contributors) {
+    const nextGenerators = contributor.mutationDefaultGenerators?.() ?? [];
+    for (const generator of nextGenerators) {
+      const existingOwner = owners.get(generator.id);
+      if (existingOwner !== undefined) {
+        throw runtimeError(
+          'RUNTIME.DUPLICATE_MUTATION_DEFAULT_GENERATOR',
+          `Duplicate mutation default generator '${generator.id}'.`,
+          {
+            id: generator.id,
+            existingOwner,
+            incomingOwner: contributor.id,
+          },
+        );
       }
+      generators.set(generator.id, generator);
+      owners.set(generator.id, contributor.id);
     }
+  }
+
+  return generators;
+}
 
-    const extOperations = extInstance.operations?.();
-    if (extOperations) {
-      for (const operation of extOperations) {
-        operationRegistry.register(operation);
+function computeExecutionDefaultValue(
+  spec: ExecutionMutationDefaultValue,
+  generatorRegistry: ReadonlyMap<string, RuntimeMutationDefaultGenerator>,
+): unknown {
+  switch (spec.kind) {
+    case 'generator': {
+      const generator = generatorRegistry.get(spec.id);
+      if (!generator) {
+        throw runtimeError(
+          'RUNTIME.MUTATION_DEFAULT_GENERATOR_MISSING',
+          `Contract references mutation default generator '${spec.id}' but no runtime component provides it.`,
+          {
+            id: spec.id,
+          },
+        );
       }
+      // nosemgrep: javascript.express.security.express-wkhtml-injection.express-wkhtmltoimage-injection
+      return generator.generate(spec.params);
+    }
+  }
+}
+
+function applyMutationDefaults(
+  contract: Contract<SqlStorage>,
+  generatorRegistry: ReadonlyMap<string, RuntimeMutationDefaultGenerator>,
+  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, generatorRegistry),
+    });
+    appliedColumns.add(columnName);
   }
 
-  // Collect parameterized codec descriptors from extensions
-  const parameterizedCodecDescriptors = collectParameterizedCodecDescriptors(extensionInstances);
+  return applied;
+}
+
+export function createExecutionContext<
+  TContract extends Contract<SqlStorage> = Contract<SqlStorage>,
+  TTargetId extends string = string,
+>(options: {
+  readonly contract: TContract;
+  readonly stack: SqlExecutionStack<TTargetId>;
+}): ExecutionContext<TContract> {
+  const { contract, stack } = options;
+
+  assertExecutionStackContractRequirements(contract, stack);
+
+  const codecRegistry = createCodecRegistry();
+
+  const contributors: Array<SqlStaticContributions & ComponentDescriptor<string>> = [
+    stack.target,
+    stack.adapter,
+    ...stack.extensionPacks,
+  ];
+
+  for (const contributor of contributors) {
+    for (const c of contributor.codecs().values()) {
+      codecRegistry.register(c);
+    }
+  }
+
+  const queryOperationRegistry = createSqlOperationRegistry();
+  for (const contributor of contributors) {
+    for (const op of contributor.queryOperations?.() ?? []) {
+      queryOperationRegistry.register(op);
+    }
+  }
+
+  const parameterizedCodecDescriptors = collectParameterizedCodecDescriptors(contributors);
+  const mutationDefaultGeneratorRegistry = collectMutationDefaultGenerators(contributors);
 
-  // Validate column typeParams if any descriptors are registered
   if (parameterizedCodecDescriptors.size > 0) {
     validateColumnTypeParams(contract.storage, parameterizedCodecDescriptors);
   }
 
-  // Initialize type helpers from storage.types
   const types = initializeTypeHelpers(contract.storage.types, parameterizedCodecDescriptors);
 
+  const jsonSchemaValidators = buildJsonSchemaValidatorRegistry(
+    contract,
+    types,
+    parameterizedCodecDescriptors,
+  );
+
   return {
     contract,
-    adapter: adapterInstance,
-    operations: operationRegistry,
     codecs: codecRegistry,
+    queryOperations: queryOperationRegistry,
     types,
+    ...(jsonSchemaValidators ? { jsonSchemaValidators } : {}),
+    applyMutationDefaults: (options) =>
+      applyMutationDefaults(contract, mutationDefaultGeneratorRegistry, options),
   };
 }