@prisma-next/sql-runtime 0.3.0-dev.3 → 0.3.0-dev.31

package/src/sql-context.ts

@@ -0,0 +1,402 @@
+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 {
+  Adapter,
+  CodecRegistry,
+  LoweredStatement,
+  QueryAst,
+} from '@prisma-next/sql-relational-core/ast';
+import { createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import type {
+  QueryLaneContext,
+  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.
+ */
+export interface 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;
+}
+
+// ============================================================================
+// 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.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: needed for covariance with concrete descriptor types
+  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>> {
+  create(): SqlRuntimeExtensionInstance<TTargetId>;
+}
+
+// ============================================================================
+// SQL Runtime Adapter Instance
+// ============================================================================
+
+/**
+ * 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;
+}
+
+/**
+ * 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>>;
+}
+
+// ============================================================================
+// Runtime Error Types and Helpers
+// ============================================================================
+
+/**
+ * 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>;
+}
+
+/**
+ * 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,
+  });
+}
+
+// ============================================================================
+// Parameterized Type Validation
+// ============================================================================
+
+/**
+ * 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,
+  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 runtimeTypeParamsInvalid(
+      `Invalid typeParams for ${locationInfo} (codecId: ${codecDescriptor.codecId}): ${messages}`,
+      { ...context, codecId: codecDescriptor.codecId, typeParams },
+    );
+  }
+  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>>,
+): 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);
+      }
+    }
+  }
+
+  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>,
+): TypeHelperRegistry {
+  const helpers: TypeHelperRegistry = {};
+
+  if (!storageTypes) {
+    return helpers;
+  }
+
+  for (const [typeName, typeInstance] of Object.entries(storageTypes)) {
+    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;
+    }
+  }
+
+  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>,
+): 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)
+ * - Types registry (initialized helpers from storage.types)
+ *
+ * @param options - Descriptor-first composition options
+ * @returns RuntimeContext with registries wired from all components
+ */
+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;
+
+  // Create adapter instance from descriptor
+  // The adapter instance IS an Adapter (via intersection)
+  const adapterInstance = adapterDescriptor.create();
+
+  // 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);
+  }
+
+  // Create extension instances and collect their contributions
+  const extensionInstances: SqlRuntimeExtensionInstance<TTargetId>[] = [];
+
+  for (const extDescriptor of extensionPacks ?? []) {
+    const extInstance = extDescriptor.create();
+    extensionInstances.push(extInstance);
+
+    const extCodecs = extInstance.codecs?.();
+    if (extCodecs) {
+      for (const codec of extCodecs.values()) {
+        codecRegistry.register(codec);
+      }
+    }
+
+    const extOperations = extInstance.operations?.();
+    if (extOperations) {
+      for (const operation of extOperations) {
+        operationRegistry.register(operation);
+      }
+    }
+  }
+
+  // Collect parameterized codec descriptors from extensions
+  const parameterizedCodecDescriptors = collectParameterizedCodecDescriptors(extensionInstances);
+
+  // 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);
+
+  return {
+    contract,
+    adapter: adapterInstance,
+    operations: operationRegistry,
+    codecs: codecRegistry,
+    types,
+  };
+}

package/src/sql-family-adapter.ts

@@ -0,0 +1,43 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type {
+  MarkerReader,
+  MarkerStatement,
+  RuntimeFamilyAdapter,
+} from '@prisma-next/runtime-executor';
+import { runtimeError } from '@prisma-next/runtime-executor';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import { readContractMarker } from './sql-marker';
+
+class SqlMarkerReader implements MarkerReader {
+  readMarkerStatement(): MarkerStatement {
+    return readContractMarker();
+  }
+}
+
+export class SqlFamilyAdapter<TContract extends SqlContract<SqlStorage>>
+  implements RuntimeFamilyAdapter<TContract>
+{
+  readonly contract: TContract;
+  readonly markerReader: MarkerReader;
+
+  constructor(contract: TContract) {
+    this.contract = contract;
+    this.markerReader = new SqlMarkerReader();
+  }
+
+  validatePlan(plan: ExecutionPlan, contract: TContract): void {
+    if (plan.meta.target !== contract.target) {
+      throw runtimeError('PLAN.TARGET_MISMATCH', 'Plan target does not match runtime target', {
+        planTarget: plan.meta.target,
+        runtimeTarget: contract.target,
+      });
+    }
+
+    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,
+      });
+    }
+  }
+}

package/src/sql-marker.ts

@@ -0,0 +1,105 @@
+import type { MarkerStatement } from '@prisma-next/runtime-executor';
+
+export interface SqlStatement {
+  readonly sql: string;
+  readonly params: readonly unknown[];
+}
+
+export interface WriteMarkerInput {
+  readonly coreHash: string;
+  readonly profileHash: string;
+  readonly contractJson?: unknown;
+  readonly canonicalVersion?: number;
+  readonly appTag?: string;
+  readonly meta?: Record<string, unknown>;
+}
+
+export const ensureSchemaStatement: SqlStatement = {
+  sql: 'create schema if not exists prisma_contract',
+  params: [],
+};
+
+export const ensureTableStatement: SqlStatement = {
+  sql: `create table if not exists prisma_contract.marker (
+    id smallint primary key default 1,
+    core_hash text not null,
+    profile_hash text not null,
+    contract_json jsonb,
+    canonical_version int,
+    updated_at timestamptz not null default now(),
+    app_tag text,
+    meta jsonb not null default '{}'
+  )`,
+  params: [],
+};
+
+export function readContractMarker(): MarkerStatement {
+  return {
+    sql: `select
+      core_hash,
+      profile_hash,
+      contract_json,
+      canonical_version,
+      updated_at,
+      app_tag,
+      meta
+    from prisma_contract.marker
+    where id = $1`,
+    params: [1],
+  };
+}
+
+export interface WriteContractMarkerStatements {
+  readonly insert: SqlStatement;
+  readonly update: SqlStatement;
+}
+
+export function writeContractMarker(input: WriteMarkerInput): WriteContractMarkerStatements {
+  const baseParams: readonly unknown[] = [
+    1,
+    input.coreHash,
+    input.profileHash,
+    input.contractJson ?? null,
+    input.canonicalVersion ?? null,
+    input.appTag ?? null,
+    JSON.stringify(input.meta ?? {}),
+  ];
+
+  const insert: SqlStatement = {
+    sql: `insert into prisma_contract.marker (
+        id,
+        core_hash,
+        profile_hash,
+        contract_json,
+        canonical_version,
+        updated_at,
+        app_tag,
+        meta
+      ) values (
+        $1,
+        $2,
+        $3,
+        $4::jsonb,
+        $5,
+        now(),
+        $6,
+        $7::jsonb
+      )`,
+    params: baseParams,
+  };
+
+  const update: SqlStatement = {
+    sql: `update prisma_contract.marker set
+        core_hash = $2,
+        profile_hash = $3,
+        contract_json = $4::jsonb,
+        canonical_version = $5,
+        updated_at = now(),
+        app_tag = $6,
+        meta = $7::jsonb
+      where id = $1`,
+    params: baseParams,
+  };
+
+  return { insert, update };
+}