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

package/src/sql-context.ts

@@ -0,0 +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 { 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 {
+  AppliedMutationDefault,
+  ExecutionContext,
+  JsonSchemaValidateFn,
+  JsonSchemaValidatorRegistry,
+  MutationDefaultsOptions,
+  TypeHelperRegistry,
+} from '@prisma-next/sql-relational-core/query-lane-context';
+import { type as arktype } from 'arktype';
+
+/**
+ * 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 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>>;
+}
+
+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>;
+}
+
+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> {}
+
+export type SqlRuntimeAdapterInstance<TTargetId extends string = string> = RuntimeAdapterInstance<
+  'sql',
+  TTargetId
+> &
+  Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
+
+/**
+ * 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 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,
+  });
+}
+
+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 });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Builds a registry of compiled JSON Schema validators by scanning the contract
+ * for columns whose codec descriptor provides an `init` hook returning `{ validate }`.
+ *
+ * Handles both:
+ * - Inline `typeParams.schema` on columns
+ * - `typeRef` → `storage.types[ref]` with init hook results already in `types` registry
+ */
+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: {
+  readonly contract: TContract;
+  readonly stack: SqlExecutionStack<TTargetId>;
+}): ExecutionContext<TContract> {
+  const { contract, stack } = options;
+
+  assertExecutionStackContractRequirements(contract, stack);
+
+  const codecRegistry = createCodecRegistry();
+  const operationRegistry = createOperationRegistry();
+
+  const contributors: SqlStaticContributions[] = [
+    stack.target,
+    stack.adapter,
+    ...stack.extensionPacks,
+  ];
+
+  for (const contributor of contributors) {
+    for (const c of contributor.codecs().values()) {
+      codecRegistry.register(c);
+    }
+    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,
+    operations: operationRegistry,
+    codecs: codecRegistry,
+    types,
+    ...(jsonSchemaValidators ? { jsonSchemaValidators } : {}),
+    applyMutationDefaults: (options) => applyMutationDefaults(contract, options),
+  };
+}

package/src/sql-family-adapter.ts

@@ -0,0 +1,47 @@
+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.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

@@ -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 storageHash: 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.storageHash,
+    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 };
+}