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

package/src/codecs/encoding.ts

@@ -1,66 +1,191 @@
-import type { ExecutionPlan, ParamDescriptor } from '@prisma-next/contract/types';
-import type { Codec, CodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import {
+  checkAborted,
+  raceAgainstAbort,
+  runtimeError,
+} from '@prisma-next/framework-components/runtime';
+import {
+  type Codec,
+  type CodecRegistry,
+  type ContractCodecRegistry,
+  collectOrderedParamRefs,
+  type SqlCodecCallContext,
+} from '@prisma-next/sql-relational-core/ast';
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
 
+interface ParamMetadata {
+  readonly codecId: string | undefined;
+  readonly name: string | undefined;
+}
+
+const NO_METADATA: ParamMetadata = Object.freeze({ codecId: undefined, name: undefined });
+
+/**
+ * Resolve the codec for an outgoing param.
+ *
+ * Phase B (and AC-5-deferred carve-out): `ParamRef` does not carry a
+ * `(table, column)` ref today — every `ParamRef` carries `codecId` but
+ * not the column it relates to. Encode-side dispatch therefore consults
+ * `contractCodecs.forCodecId(codecId)` (which itself prefers the
+ * contract-walk-derived shared codec, falling back to the legacy
+ * `CodecRegistry.get` for parameterized codec ids whose contracts don't
+ * have a column the walk could resolve through).
+ *
+ * For the parameterized codecs shipped at Phase B (pgvector, postgres
+ * json/jsonb), encode is per-instance-stateless w.r.t. params:
+ * - pgvector formats `[v1,v2,...]` regardless of declared length;
+ * - postgres json/jsonb encode is `JSON.stringify` regardless of schema.
+ *
+ * So the codec-id-keyed lookup yields a structurally equivalent encoder
+ * even when the resolved per-instance codec carries extra state (e.g. a
+ * compiled JSON-Schema validator used only by `decode`). TML-2357 retires
+ * the fallback by threading `ParamRef.refs` through column-bound
+ * construction sites.
+ */
 function resolveParamCodec(
-  paramDescriptor: ParamDescriptor,
+  metadata: ParamMetadata,
   registry: CodecRegistry,
-): Codec | null {
-  if (paramDescriptor.codecId) {
-    const codec = registry.get(paramDescriptor.codecId);
-    if (codec) {
-      return codec;
-    }
-  }
+  contractCodecs: ContractCodecRegistry | undefined,
+): Codec | undefined {
+  if (!metadata.codecId) return undefined;
+  const fromContract = contractCodecs?.forCodecId(metadata.codecId);
+  if (fromContract) return fromContract;
+  return registry.get(metadata.codecId);
+}
 
-  return null;
+function paramLabel(metadata: ParamMetadata, paramIndex: number): string {
+  return metadata.name ?? `param[${paramIndex}]`;
 }
 
-export function encodeParam(
+function wrapEncodeFailure(
+  error: unknown,
+  metadata: ParamMetadata,
+  paramIndex: number,
+  codecId: string,
+): never {
+  const label = paramLabel(metadata, paramIndex);
+  const message = error instanceof Error ? error.message : String(error);
+  const wrapped = runtimeError(
+    'RUNTIME.ENCODE_FAILED',
+    `Failed to encode parameter ${label} with codec '${codecId}': ${message}`,
+    { label, codec: codecId, paramIndex },
+  );
+  wrapped.cause = error;
+  throw wrapped;
+}
+
+/**
+ * Encodes a single parameter through its codec. Always awaits codec.encode so
+ * a Promise can never leak into the driver, even if a sync-authored codec is
+ * lifted to async by the codec() factory. Failures are wrapped in
+ * `RUNTIME.ENCODE_FAILED` with `{ label, codec, paramIndex }` and the original
+ * error attached on `cause`.
+ *
+ * `ctx` is forwarded verbatim to `codec.encode` so codec authors who opt
+ * into the `(value, ctx)` arity see the same `SqlCodecCallContext` the
+ * runtime built for the surrounding `runtime.execute()` call. The ctx is
+ * always present; its `signal` field may be `undefined`. Encode call
+ * sites do not populate `ctx.column` — encode-time column context is the
+ * middleware's domain.
+ */
+export async function encodeParam(
   value: unknown,
-  paramDescriptor: ParamDescriptor,
+  paramRef: { readonly codecId?: string; readonly name?: string },
   paramIndex: number,
   registry: CodecRegistry,
-): unknown {
+  ctx: SqlCodecCallContext,
+  contractCodecs?: ContractCodecRegistry,
+): Promise<unknown> {
+  return encodeParamValue(
+    value,
+    { codecId: paramRef.codecId, name: paramRef.name },
+    paramIndex,
+    registry,
+    ctx,
+    contractCodecs,
+  );
+}
+
+async function encodeParamValue(
+  value: unknown,
+  metadata: ParamMetadata,
+  paramIndex: number,
+  registry: CodecRegistry,
+  ctx: SqlCodecCallContext,
+  contractCodecs: ContractCodecRegistry | undefined,
+): Promise<unknown> {
   if (value === null || value === undefined) {
     return null;
   }
 
-  const codec = resolveParamCodec(paramDescriptor, registry);
+  const codec = resolveParamCodec(metadata, registry, contractCodecs);
   if (!codec) {
     return value;
   }
 
-  if (codec.encode) {
-    try {
-      return codec.encode(value);
-    } catch (error) {
-      const label = paramDescriptor.name ?? `param[${paramIndex}]`;
-      throw new Error(
-        `Failed to encode parameter ${label}: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
+  try {
+    return await codec.encode(value, ctx);
+  } catch (error) {
+    wrapEncodeFailure(error, metadata, paramIndex, codec.id);
   }
-
-  return value;
 }
 
-export function encodeParams(plan: ExecutionPlan, registry: CodecRegistry): readonly unknown[] {
+/**
+ * Encodes all parameters concurrently via `Promise.all`. Per parameter, sync-
+ * and async-authored codecs share the same path: `codec.encode → await →
+ * return`. Param-level failures are wrapped in `RUNTIME.ENCODE_FAILED`.
+ *
+ * When `ctx.signal` is provided:
+ *
+ * - **Already-aborted at entry** short-circuits with `RUNTIME.ABORTED`
+ *   (`{ phase: 'encode' }`) before any `codec.encode` call is made — codecs
+ *   can pin this with a per-call counter that stays at zero.
+ * - **Mid-flight abort** races the per-param `Promise.all` against
+ *   `abortable(ctx.signal)`. The runtime returns `RUNTIME.ABORTED` promptly
+ *   even if codec bodies ignore the signal; the in-flight bodies are
+ *   abandoned and run to completion in the background (cooperative
+ *   cancellation, see ADR 204).
+ * - Existing `RUNTIME.ENCODE_FAILED` envelopes that surface from a codec
+ *   body before the runtime observes the abort pass through unchanged
+ *   (no double wrap).
+ */
+export async function encodeParams(
+  plan: SqlExecutionPlan,
+  registry: CodecRegistry,
+  ctx: SqlCodecCallContext,
+  contractCodecs?: ContractCodecRegistry,
+): Promise<readonly unknown[]> {
+  checkAborted(ctx, 'encode');
+  const signal = ctx.signal;
+
   if (plan.params.length === 0) {
     return plan.params;
   }
 
-  const encoded: unknown[] = [];
-
-  for (let i = 0; i < plan.params.length; i++) {
-    const paramValue = plan.params[i];
-    const paramDescriptor = plan.meta.paramDescriptors[i];
+  const paramCount = plan.params.length;
+  const metadata: ParamMetadata[] = new Array(paramCount).fill(NO_METADATA);
 
-    if (paramDescriptor) {
-      encoded.push(encodeParam(paramValue, paramDescriptor, i, registry));
-    } else {
-      encoded.push(paramValue);
+  if (plan.ast) {
+    const refs = collectOrderedParamRefs(plan.ast);
+    for (let i = 0; i < paramCount && i < refs.length; i++) {
+      const ref = refs[i];
+      if (ref) {
+        metadata[i] = { codecId: ref.codecId, name: ref.name };
+      }
     }
   }
 
-  return Object.freeze(encoded);
+  const tasks: Promise<unknown>[] = new Array(paramCount);
+  for (let i = 0; i < paramCount; i++) {
+    tasks[i] = encodeParamValue(
+      plan.params[i],
+      metadata[i] ?? NO_METADATA,
+      i,
+      registry,
+      ctx,
+      contractCodecs,
+    );
+  }
+
+  const settled = await raceAgainstAbort(Promise.all(tasks), signal, 'encode');
+  return Object.freeze(settled);
 }

package/src/codecs/validation.ts

@@ -2,6 +2,7 @@ import type { Contract } from '@prisma-next/contract/types';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { CodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
 
 export function extractCodecIds(contract: Contract<SqlStorage>): Set<string> {
   const codecIds = new Set<string>();
@@ -30,15 +31,33 @@ function extractCodecIdsFromColumns(contract: Contract<SqlStorage>): Map<string,
   return codecIds;
 }
 
+interface CodecLookupForValidation {
+  has(id: string): boolean;
+}
+
+function adaptDescriptorRegistry(registry: CodecDescriptorRegistry): CodecLookupForValidation {
+  return { has: (id: string) => registry.descriptorFor(id) !== undefined };
+}
+
+function isDescriptorRegistry(
+  registry: CodecRegistry | CodecDescriptorRegistry,
+): registry is CodecDescriptorRegistry {
+  return 'descriptorFor' in registry;
+}
+
 export function validateContractCodecMappings(
-  registry: CodecRegistry,
+  registry: CodecRegistry | CodecDescriptorRegistry,
   contract: Contract<SqlStorage>,
 ): void {
+  const lookup: CodecLookupForValidation = isDescriptorRegistry(registry)
+    ? adaptDescriptorRegistry(registry)
+    : registry;
+
   const codecIds = extractCodecIdsFromColumns(contract);
   const invalidCodecs: Array<{ table: string; column: string; codecId: string }> = [];
 
   for (const [key, codecId] of codecIds.entries()) {
-    if (!registry.has(codecId)) {
+    if (!lookup.has(codecId)) {
       const parts = key.split('.');
       const table = parts[0] ?? '';
       const column = parts[1] ?? '';
@@ -61,7 +80,7 @@ export function validateContractCodecMappings(
 }
 
 export function validateCodecRegistryCompleteness(
-  registry: CodecRegistry,
+  registry: CodecRegistry | CodecDescriptorRegistry,
   contract: Contract<SqlStorage>,
 ): void {
   validateContractCodecMappings(registry, contract);

package/src/exports/index.ts

@@ -1,20 +1,27 @@
 export type {
   AfterExecuteResult,
-  Log,
-  Middleware,
-  MiddlewareContext,
-} from '@prisma-next/runtime-executor';
+  RuntimeLog as Log,
+} from '@prisma-next/framework-components/runtime';
+export type { MarkerStatement } from '@prisma-next/sql-relational-core/ast';
 export {
   extractCodecIds,
   validateCodecRegistryCompleteness,
   validateContractCodecMappings,
 } from '../codecs/validation';
 export { lowerSqlPlan } from '../lower-sql-plan';
+export { parseContractMarkerRow } from '../marker';
 export type { BudgetsOptions } from '../middleware/budgets';
 export { budgets } from '../middleware/budgets';
 export type { LintsOptions } from '../middleware/lints';
 export { lints } from '../middleware/lints';
 export type { SqlMiddleware, SqlMiddlewareContext } from '../middleware/sql-middleware';
+export type {
+  MarkerReader,
+  RuntimeFamilyAdapter,
+  RuntimeTelemetryEvent,
+  RuntimeVerifyOptions,
+  TelemetryOutcome,
+} from '../runtime-spi';
 export type {
   ExecutionContext,
   RuntimeMutationDefaultGenerator,
@@ -46,10 +53,7 @@ export type {
   Runtime,
   RuntimeConnection,
   RuntimeQueryable,
-  RuntimeTelemetryEvent,
   RuntimeTransaction,
-  RuntimeVerifyOptions,
-  TelemetryOutcome,
   TransactionContext,
 } from '../sql-runtime';
 export { createRuntime, withTransaction } from '../sql-runtime';

package/src/fingerprint.ts

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+
+const STRING_LITERAL_REGEX = /'(?:''|[^'])*'/g;
+const NUMERIC_LITERAL_REGEX = /\b\d+(?:\.\d+)?\b/g;
+const WHITESPACE_REGEX = /\s+/g;
+
+/**
+ * Computes a literal-stripped, normalized fingerprint of a SQL statement.
+ *
+ * The function strips string and numeric literals, collapses whitespace, and
+ * lowercases the result before hashing — so two structurally equivalent
+ * statements (with different parameter values) produce the same fingerprint.
+ * Used by SQL telemetry to group queries.
+ */
+export function computeSqlFingerprint(sql: string): string {
+  const withoutStrings = sql.replace(STRING_LITERAL_REGEX, '?');
+  const withoutNumbers = withoutStrings.replace(NUMERIC_LITERAL_REGEX, '?');
+  const normalized = withoutNumbers.replace(WHITESPACE_REGEX, ' ').trim().toLowerCase();
+
+  const hash = createHash('sha256').update(normalized).digest('hex');
+  return `sha256:${hash}`;
+}

package/src/guardrails/raw.ts

@@ -0,0 +1,165 @@
+import type { PlanMeta } from '@prisma-next/contract/types';
+
+export type LintSeverity = 'error' | 'warn';
+export type BudgetSeverity = 'error' | 'warn';
+
+export interface LintFinding {
+  readonly code: `LINT.${string}`;
+  readonly severity: LintSeverity;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+
+export interface BudgetFinding {
+  readonly code: `BUDGET.${string}`;
+  readonly severity: BudgetSeverity;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+
+export interface RawGuardrailConfig {
+  readonly budgets?: {
+    readonly unboundedSelectSeverity?: BudgetSeverity;
+    readonly estimatedRows?: number;
+  };
+}
+
+export interface RawGuardrailResult {
+  readonly lints: LintFinding[];
+  readonly budgets: BudgetFinding[];
+  readonly statement: 'select' | 'mutation' | 'other';
+}
+
+/**
+ * Minimal plan view consumed by raw-SQL guardrails. Structurally satisfied
+ * by `SqlExecutionPlan`; declared inline so this module stays decoupled
+ * from a specific plan type at the call site.
+ */
+interface RawGuardrailPlan {
+  readonly sql: string;
+  readonly meta: PlanMeta;
+}
+
+const SELECT_STAR_REGEX = /select\s+\*/i;
+const LIMIT_REGEX = /\blimit\b/i;
+const MUTATION_PREFIX_REGEX = /^(insert|update|delete|create|alter|drop|truncate)\b/i;
+
+const READ_ONLY_INTENTS = new Set(['read', 'report', 'readonly']);
+
+export function evaluateRawGuardrails(
+  plan: RawGuardrailPlan,
+  config?: RawGuardrailConfig,
+): RawGuardrailResult {
+  const lints: LintFinding[] = [];
+  const budgets: BudgetFinding[] = [];
+
+  const normalized = normalizeWhitespace(plan.sql);
+  const statementType = classifyStatement(normalized);
+
+  if (statementType === 'select') {
+    if (SELECT_STAR_REGEX.test(normalized)) {
+      lints.push(
+        createLint('LINT.SELECT_STAR', 'error', 'Raw SQL plan selects all columns via *', {
+          sql: snippet(plan.sql),
+        }),
+      );
+    }
+
+    if (!LIMIT_REGEX.test(normalized)) {
+      const severity = config?.budgets?.unboundedSelectSeverity ?? 'error';
+      lints.push(
+        createLint('LINT.NO_LIMIT', 'warn', 'Raw SQL plan omits LIMIT clause', {
+          sql: snippet(plan.sql),
+        }),
+      );
+
+      budgets.push(
+        createBudget(
+          'BUDGET.ROWS_EXCEEDED',
+          severity,
+          'Raw SQL plan is unbounded and may exceed row budget',
+          {
+            sql: snippet(plan.sql),
+            ...(config?.budgets?.estimatedRows !== undefined
+              ? { estimatedRows: config.budgets.estimatedRows }
+              : {}),
+          },
+        ),
+      );
+    }
+  }
+
+  if (isMutationStatement(statementType) && isReadOnlyIntent(plan.meta)) {
+    lints.push(
+      createLint(
+        'LINT.READ_ONLY_MUTATION',
+        'error',
+        'Raw SQL plan mutates data despite read-only intent',
+        {
+          sql: snippet(plan.sql),
+          intent: plan.meta.annotations?.['intent'],
+        },
+      ),
+    );
+  }
+
+  return { lints, budgets, statement: statementType };
+}
+
+function classifyStatement(sql: string): 'select' | 'mutation' | 'other' {
+  const trimmed = sql.trim();
+  const lower = trimmed.toLowerCase();
+
+  if (lower.startsWith('with')) {
+    if (lower.includes('select')) {
+      return 'select';
+    }
+  }
+
+  if (lower.startsWith('select')) {
+    return 'select';
+  }
+
+  if (MUTATION_PREFIX_REGEX.test(trimmed)) {
+    return 'mutation';
+  }
+
+  return 'other';
+}
+
+function isMutationStatement(statement: 'select' | 'mutation' | 'other'): boolean {
+  return statement === 'mutation';
+}
+
+function isReadOnlyIntent(meta: PlanMeta): boolean {
+  const annotations = meta.annotations as { intent?: string } | undefined;
+  const intent =
+    typeof annotations?.intent === 'string' ? annotations.intent.toLowerCase() : undefined;
+  return intent !== undefined && READ_ONLY_INTENTS.has(intent);
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function snippet(sql: string): string {
+  return normalizeWhitespace(sql).slice(0, 200);
+}
+
+function createLint(
+  code: LintFinding['code'],
+  severity: LintFinding['severity'],
+  message: string,
+  details?: Record<string, unknown>,
+): LintFinding {
+  return { code, severity, message, ...(details ? { details } : {}) };
+}
+
+function createBudget(
+  code: BudgetFinding['code'],
+  severity: BudgetFinding['severity'],
+  message: string,
+  details?: Record<string, unknown>,
+): BudgetFinding {
+  return { code, severity, message, ...(details ? { details } : {}) };
+}

package/src/lower-sql-plan.ts

@@ -1,7 +1,7 @@
-import type { Contract, ExecutionPlan } from '@prisma-next/contract/types';
+import type { Contract } from '@prisma-next/contract/types';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { Adapter, AnyQueryAst, LoweredStatement } from '@prisma-next/sql-relational-core/ast';
-import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import type { SqlExecutionPlan, SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
 
 /**
  * Lowers a SQL query plan to an executable Plan by calling the adapter's lower method.
@@ -15,7 +15,7 @@ export function lowerSqlPlan<Row>(
   adapter: Adapter<AnyQueryAst, Contract<SqlStorage>, LoweredStatement>,
   contract: Contract<SqlStorage>,
   queryPlan: SqlQueryPlan<Row>,
-): ExecutionPlan<Row> {
+): SqlExecutionPlan<Row> {
   const lowered = adapter.lower(queryPlan.ast, {
     contract,
     params: queryPlan.params,

package/src/marker.ts

@@ -0,0 +1,75 @@
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import { type } from 'arktype';
+
+export interface ContractMarkerRow {
+  core_hash: string;
+  profile_hash: string;
+  contract_json: unknown | null;
+  canonical_version: number | null;
+  updated_at: Date;
+  app_tag: string | null;
+  meta: unknown | null;
+  invariants: readonly string[];
+}
+
+const MetaSchema = type({ '[string]': 'unknown' });
+
+function parseMeta(meta: unknown): Record<string, unknown> {
+  if (meta === null || meta === undefined) {
+    return {};
+  }
+
+  let parsed: unknown;
+  if (typeof meta === 'string') {
+    try {
+      parsed = JSON.parse(meta);
+    } catch {
+      return {};
+    }
+  } else {
+    parsed = meta;
+  }
+
+  const result = MetaSchema(parsed);
+  if (result instanceof type.errors) {
+    return {};
+  }
+
+  return result as Record<string, unknown>;
+}
+
+const ContractMarkerRowSchema = type({
+  core_hash: 'string',
+  profile_hash: 'string',
+  'contract_json?': 'unknown | null',
+  'canonical_version?': 'number | null',
+  'updated_at?': 'Date | string',
+  'app_tag?': 'string | null',
+  'meta?': 'unknown | null',
+  invariants: type('string').array(),
+});
+
+export function parseContractMarkerRow(row: unknown): ContractMarkerRecord {
+  const result = ContractMarkerRowSchema(row);
+  if (result instanceof type.errors) {
+    const messages = result.map((p: { message: string }) => p.message).join('; ');
+    throw new Error(`Invalid contract marker row: ${messages}`);
+  }
+
+  const updatedAt = result.updated_at
+    ? result.updated_at instanceof Date
+      ? result.updated_at
+      : new Date(result.updated_at)
+    : new Date();
+
+  return {
+    storageHash: result.core_hash,
+    profileHash: result.profile_hash,
+    contractJson: result.contract_json ?? null,
+    canonicalVersion: result.canonical_version ?? null,
+    updatedAt,
+    appTag: result.app_tag ?? null,
+    meta: parseMeta(result.meta),
+    invariants: result.invariants,
+  };
+}

package/src/middleware/before-compile-chain.ts

@@ -24,5 +24,6 @@ export async function runBeforeCompileChain(
     });
     current = result;
   }
+
   return current;
 }