@prisma-next/sql-runtime 0.3.0-dev.4 → 0.3.0-dev.5

package/src/codecs/validation.ts

@@ -0,0 +1,67 @@
+import { runtimeError } from '@prisma-next/runtime-executor';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { CodecRegistry } from '@prisma-next/sql-relational-core/ast';
+
+export function extractCodecIds(contract: SqlContract<SqlStorage>): Set<string> {
+  const codecIds = new Set<string>();
+
+  for (const table of Object.values(contract.storage.tables)) {
+    for (const column of Object.values(table.columns)) {
+      const codecId = column.codecId;
+      codecIds.add(codecId);
+    }
+  }
+
+  return codecIds;
+}
+
+function extractCodecIdsFromColumns(contract: SqlContract<SqlStorage>): Map<string, string> {
+  const codecIds = new Map<string, string>();
+
+  for (const [tableName, table] of Object.entries(contract.storage.tables)) {
+    for (const [columnName, column] of Object.entries(table.columns)) {
+      const codecId = column.codecId;
+      const key = `${tableName}.${columnName}`;
+      codecIds.set(key, codecId);
+    }
+  }
+
+  return codecIds;
+}
+
+export function validateContractCodecMappings(
+  registry: CodecRegistry,
+  contract: SqlContract<SqlStorage>,
+): void {
+  const codecIds = extractCodecIdsFromColumns(contract);
+  const invalidCodecs: Array<{ table: string; column: string; codecId: string }> = [];
+
+  for (const [key, codecId] of codecIds.entries()) {
+    if (!registry.has(codecId)) {
+      const parts = key.split('.');
+      const table = parts[0] ?? '';
+      const column = parts[1] ?? '';
+      invalidCodecs.push({ table, column, codecId });
+    }
+  }
+
+  if (invalidCodecs.length > 0) {
+    const details: Record<string, unknown> = {
+      contractTarget: contract.target,
+      invalidCodecs,
+    };
+
+    throw runtimeError(
+      'RUNTIME.CODEC_MISSING',
+      `Missing codec implementations for column codecIds: ${invalidCodecs.map((c) => `${c.table}.${c.column} (${c.codecId})`).join(', ')}`,
+      details,
+    );
+  }
+}
+
+export function validateCodecRegistryCompleteness(
+  registry: CodecRegistry,
+  contract: SqlContract<SqlStorage>,
+): void {
+  validateContractCodecMappings(registry, contract);
+}

package/src/exports/index.ts

@@ -0,0 +1,38 @@
+export type {
+  AfterExecuteResult,
+  BudgetsOptions,
+  LintsOptions,
+  Log,
+  Plugin,
+  PluginContext,
+} from '@prisma-next/runtime-executor';
+export { budgets, lints } from '@prisma-next/runtime-executor';
+export {
+  extractCodecIds,
+  validateCodecRegistryCompleteness,
+  validateContractCodecMappings,
+} from '../codecs/validation';
+export { lowerSqlPlan } from '../lower-sql-plan';
+export type {
+  CreateRuntimeContextOptions,
+  RuntimeContext,
+  SqlRuntimeAdapterInstance,
+  SqlRuntimeExtensionDescriptor,
+  SqlRuntimeExtensionInstance,
+} from '../sql-context';
+export { createRuntimeContext } from '../sql-context';
+export type { SqlStatement } from '../sql-marker';
+export {
+  ensureSchemaStatement,
+  ensureTableStatement,
+  readContractMarker,
+  writeContractMarker,
+} from '../sql-marker';
+export type {
+  Runtime,
+  RuntimeOptions,
+  RuntimeTelemetryEvent,
+  RuntimeVerifyOptions,
+  TelemetryOutcome,
+} from '../sql-runtime';
+export { createRuntime } from '../sql-runtime';

package/src/index.ts

@@ -0,0 +1 @@
+export * from './exports';

package/src/lower-sql-plan.ts

@@ -0,0 +1,32 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import type { RuntimeContext } from './sql-context';
+
+/**
+ * Lowers a SQL query plan to an executable Plan by calling the adapter's lower method.
+ *
+ * This function is responsible for converting a lane-produced SqlQueryPlan (which contains
+ * AST and params but no SQL) into a fully executable Plan (which includes SQL string).
+ *
+ * @param context - Runtime context containing the adapter
+ * @param queryPlan - SQL query plan from a lane (contains AST, params, meta, but no SQL)
+ * @returns Fully executable Plan with SQL string
+ */
+export function lowerSqlPlan<Row>(
+  context: RuntimeContext,
+  queryPlan: SqlQueryPlan<Row>,
+): ExecutionPlan<Row> {
+  const lowered = context.adapter.lower(queryPlan.ast, {
+    contract: context.contract,
+    params: queryPlan.params,
+  });
+
+  const body = lowered.body;
+
+  return Object.freeze({
+    sql: body.sql,
+    params: body.params ?? queryPlan.params,
+    ast: queryPlan.ast,
+    meta: queryPlan.meta,
+  });
+}

package/src/sql-context.ts

@@ -0,0 +1,156 @@
+import type {
+  RuntimeAdapterDescriptor,
+  RuntimeAdapterInstance,
+  RuntimeExtensionDescriptor,
+  RuntimeExtensionInstance,
+  RuntimeTargetDescriptor,
+} from '@prisma-next/core-execution-plane/types';
+import { createOperationRegistry } from '@prisma-next/operations';
+import type { SqlContract, SqlStorage } 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 } from '@prisma-next/sql-relational-core/query-lane-context';
+
+// ============================================================================
+// 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>;
+}
+
+/**
+ * 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 interface RuntimeContext<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>>
+  extends QueryLaneContext<TContract> {
+  readonly adapter:
+    | Adapter<QueryAst, TContract, LoweredStatement>
+    | Adapter<QueryAst, SqlContract<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')
+ */
+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>>;
+}
+
+/**
+ * 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)
+ *
+ * @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 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);
+      }
+    }
+
+    const extOperations = extInstance.operations?.();
+    if (extOperations) {
+      for (const operation of extOperations) {
+        operationRegistry.register(operation);
+      }
+    }
+  }
+
+  return {
+    contract,
+    adapter: adapterInstance,
+    operations: operationRegistry,
+    codecs: codecRegistry,
+  };
+}

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 };
+}

package/src/sql-runtime.ts

@@ -0,0 +1,166 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type { OperationRegistry } from '@prisma-next/operations';
+import type {
+  Log,
+  Plugin,
+  RuntimeCore,
+  RuntimeCoreOptions,
+  RuntimeTelemetryEvent,
+  RuntimeVerifyOptions,
+  TelemetryOutcome,
+} from '@prisma-next/runtime-executor';
+import { AsyncIterableResult, createRuntimeCore } from '@prisma-next/runtime-executor';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type {
+  Adapter,
+  CodecRegistry,
+  LoweredStatement,
+  SelectAst,
+  SqlDriver,
+} from '@prisma-next/sql-relational-core/ast';
+import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import { decodeRow } from './codecs/decoding';
+import { encodeParams } from './codecs/encoding';
+import { validateCodecRegistryCompleteness } from './codecs/validation';
+import { lowerSqlPlan } from './lower-sql-plan';
+import type { RuntimeContext } from './sql-context';
+import { SqlFamilyAdapter } from './sql-family-adapter';
+
+export interface RuntimeOptions<
+  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
+> {
+  readonly driver: SqlDriver;
+  readonly verify: RuntimeVerifyOptions;
+  readonly context: RuntimeContext<TContract>;
+  readonly plugins?: readonly Plugin<
+    TContract,
+    Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+    SqlDriver
+  >[];
+  readonly mode?: 'strict' | 'permissive';
+  readonly log?: Log;
+}
+
+export interface Runtime {
+  execute<Row = Record<string, unknown>>(
+    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+  ): AsyncIterableResult<Row>;
+  telemetry(): RuntimeTelemetryEvent | null;
+  close(): Promise<void>;
+  operations(): OperationRegistry;
+}
+
+export type { RuntimeTelemetryEvent, RuntimeVerifyOptions, TelemetryOutcome };
+
+class SqlRuntimeImpl<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>>
+  implements Runtime
+{
+  private readonly core: RuntimeCore<
+    TContract,
+    Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+    SqlDriver
+  >;
+  private readonly contract: TContract;
+  private readonly context: RuntimeContext<TContract>;
+  private readonly codecRegistry: CodecRegistry;
+  private codecRegistryValidated: boolean;
+
+  constructor(options: RuntimeOptions<TContract>) {
+    const { context, driver, verify, plugins, mode, log } = options;
+    this.contract = context.contract;
+    this.context = context;
+    this.codecRegistry = context.codecs;
+    this.codecRegistryValidated = false;
+
+    const familyAdapter = new SqlFamilyAdapter(context.contract);
+
+    const coreOptions: RuntimeCoreOptions<
+      TContract,
+      Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+      SqlDriver
+    > = {
+      familyAdapter,
+      driver,
+      verify,
+      plugins: plugins as readonly Plugin<
+        TContract,
+        Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+        SqlDriver
+      >[],
+      ...(mode !== undefined ? { mode } : {}),
+      ...(log !== undefined ? { log } : {}),
+      operationRegistry: context.operations,
+    };
+
+    this.core = createRuntimeCore(coreOptions);
+
+    if (verify.mode === 'startup') {
+      validateCodecRegistryCompleteness(this.codecRegistry, context.contract);
+      this.codecRegistryValidated = true;
+    }
+  }
+
+  private ensureCodecRegistryValidated(contract: SqlContract<SqlStorage>): void {
+    if (!this.codecRegistryValidated) {
+      validateCodecRegistryCompleteness(this.codecRegistry, contract);
+      this.codecRegistryValidated = true;
+    }
+  }
+
+  execute<Row = Record<string, unknown>>(
+    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+  ): AsyncIterableResult<Row> {
+    this.ensureCodecRegistryValidated(this.contract);
+
+    // Check if plan is SqlQueryPlan (has ast but no sql)
+    const isSqlQueryPlan = (p: ExecutionPlan<Row> | SqlQueryPlan<Row>): p is SqlQueryPlan<Row> => {
+      return 'ast' in p && !('sql' in p);
+    };
+
+    // Lower SqlQueryPlan to Plan if needed
+    const executablePlan: ExecutionPlan<Row> = isSqlQueryPlan(plan)
+      ? lowerSqlPlan(this.context, plan)
+      : plan;
+
+    const iterator = async function* (
+      self: SqlRuntimeImpl<TContract>,
+    ): AsyncGenerator<Row, void, unknown> {
+      const encodedParams = encodeParams(executablePlan, self.codecRegistry);
+      const planWithEncodedParams: ExecutionPlan<Row> = {
+        ...executablePlan,
+        params: encodedParams,
+      };
+
+      const coreIterator = self.core.execute(planWithEncodedParams);
+
+      for await (const rawRow of coreIterator) {
+        const decodedRow = decodeRow(
+          rawRow as Record<string, unknown>,
+          executablePlan,
+          self.codecRegistry,
+        );
+        yield decodedRow as Row;
+      }
+    };
+
+    return new AsyncIterableResult(iterator(this));
+  }
+
+  telemetry(): RuntimeTelemetryEvent | null {
+    return this.core.telemetry();
+  }
+
+  operations(): OperationRegistry {
+    return this.core.operations();
+  }
+
+  close(): Promise<void> {
+    return this.core.close();
+  }
+}
+
+export function createRuntime<TContract extends SqlContract<SqlStorage>>(
+  options: RuntimeOptions<TContract>,
+): Runtime {
+  return new SqlRuntimeImpl(options);
+}