@prisma-next/sql-runtime 0.5.0-dev.7 → 0.5.0-dev.9

package/package.json

@@ -1,20 +1,19 @@
 {
   "name": "@prisma-next/sql-runtime",
-  "version": "0.5.0-dev.7",
+  "version": "0.5.0-dev.9",
   "type": "module",
   "sideEffects": false,
   "description": "SQL runtime implementation for Prisma Next",
   "dependencies": {
     "arktype": "^2.1.26",
-    "@prisma-next/contract": "0.5.0-dev.7",
-    "@prisma-next/utils": "0.5.0-dev.7",
-    "@prisma-next/framework-components": "0.5.0-dev.7",
-    "@prisma-next/operations": "0.5.0-dev.7",
-    "@prisma-next/ids": "0.5.0-dev.7",
-    "@prisma-next/sql-contract": "0.5.0-dev.7",
-    "@prisma-next/sql-operations": "0.5.0-dev.7",
-    "@prisma-next/runtime-executor": "0.5.0-dev.7",
-    "@prisma-next/sql-relational-core": "0.5.0-dev.7"
+    "@prisma-next/utils": "0.5.0-dev.9",
+    "@prisma-next/contract": "0.5.0-dev.9",
+    "@prisma-next/framework-components": "0.5.0-dev.9",
+    "@prisma-next/ids": "0.5.0-dev.9",
+    "@prisma-next/operations": "0.5.0-dev.9",
+    "@prisma-next/sql-contract": "0.5.0-dev.9",
+    "@prisma-next/sql-operations": "0.5.0-dev.9",
+    "@prisma-next/sql-relational-core": "0.5.0-dev.9"
   },
   "devDependencies": {
     "@types/pg": "8.16.0",
@@ -22,14 +21,13 @@
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/test-utils": "0.0.1",
     "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/tsdown": "0.0.0"
+    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/test-utils": "0.0.1"
   },
   "files": [
     "dist",
-    "src",
-    "test"
+    "src"
   ],
   "exports": {
     ".": "./dist/index.mjs",

package/src/codecs/decoding.ts

@@ -1,11 +1,17 @@
-import type { ExecutionPlan } from '@prisma-next/contract/types';
+import { isRuntimeError, runtimeError } from '@prisma-next/framework-components/runtime';
 import type { Codec, CodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
 import type { JsonSchemaValidatorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
 import { validateJsonValue } from './json-schema-validation';
 
+type ColumnRef = { table: string; column: string };
+type ColumnRefIndex = Map<string, ColumnRef>;
+
+const WIRE_PREVIEW_LIMIT = 100;
+
 function resolveRowCodec(
   alias: string,
-  plan: ExecutionPlan,
+  plan: SqlExecutionPlan,
   registry: CodecRegistry,
 ): Codec | null {
   const planCodecId = plan.meta.annotations?.codecs?.[alias] as string | undefined;
@@ -29,13 +35,11 @@ function resolveRowCodec(
   return null;
 }
 
-type ColumnRefIndex = Map<string, { table: string; column: string }>;
-
 /**
  * Builds a lookup index from column name → { table, column } ref.
  * Called once per decodeRow invocation to avoid O(aliases × refs) linear scans.
  */
-function buildColumnRefIndex(plan: ExecutionPlan): ColumnRefIndex | null {
+function buildColumnRefIndex(plan: SqlExecutionPlan): ColumnRefIndex | null {
   const columns = plan.meta.refs?.columns;
   if (!columns) return null;
 
@@ -46,7 +50,7 @@ function buildColumnRefIndex(plan: ExecutionPlan): ColumnRefIndex | null {
   return index;
 }
 
-function parseProjectionRef(value: string): { table: string; column: string } | null {
+function parseProjectionRef(value: string): ColumnRef | null {
   if (value.startsWith('include:') || value.startsWith('operation:')) {
     return null;
   }
@@ -64,9 +68,9 @@ function parseProjectionRef(value: string): { table: string; column: string } |
 
 function resolveColumnRefForAlias(
   alias: string,
-  projection: ExecutionPlan['meta']['projection'],
+  projection: SqlExecutionPlan['meta']['projection'],
   fallbackColumnRefIndex: ColumnRefIndex | null,
-): { table: string; column: string } | undefined {
+): ColumnRef | undefined {
   if (projection && !Array.isArray(projection)) {
     const mappedRef = (projection as Record<string, string>)[alias];
     if (typeof mappedRef !== 'string') {
@@ -78,18 +82,144 @@ function resolveColumnRefForAlias(
   return fallbackColumnRefIndex?.get(alias);
 }
 
-export function decodeRow(
+function previewWireValue(wireValue: unknown): string {
+  if (typeof wireValue === 'string') {
+    return wireValue.length > WIRE_PREVIEW_LIMIT
+      ? `${wireValue.substring(0, WIRE_PREVIEW_LIMIT)}...`
+      : wireValue;
+  }
+  return String(wireValue).substring(0, WIRE_PREVIEW_LIMIT);
+}
+
+function isJsonSchemaValidationError(error: unknown): boolean {
+  return isRuntimeError(error) && error.code === 'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED';
+}
+
+function wrapDecodeFailure(
+  error: unknown,
+  alias: string,
+  ref: ColumnRef | undefined,
+  codec: Codec,
+  wireValue: unknown,
+): never {
+  const message = error instanceof Error ? error.message : String(error);
+  const target = ref ? `${ref.table}.${ref.column}` : alias;
+  const wrapped = runtimeError(
+    'RUNTIME.DECODE_FAILED',
+    `Failed to decode column ${target} with codec '${codec.id}': ${message}`,
+    {
+      ...(ref ? { table: ref.table, column: ref.column } : { alias }),
+      codec: codec.id,
+      wirePreview: previewWireValue(wireValue),
+    },
+  );
+  wrapped.cause = error;
+  throw wrapped;
+}
+
+function wrapIncludeAggregateFailure(error: unknown, alias: string, wireValue: unknown): never {
+  const message = error instanceof Error ? error.message : String(error);
+  const wrapped = runtimeError(
+    'RUNTIME.DECODE_FAILED',
+    `Failed to parse JSON array for include alias '${alias}': ${message}`,
+    {
+      alias,
+      wirePreview: previewWireValue(wireValue),
+    },
+  );
+  wrapped.cause = error;
+  throw wrapped;
+}
+
+function decodeIncludeAggregate(alias: string, wireValue: unknown): unknown {
+  if (wireValue === null || wireValue === undefined) {
+    return [];
+  }
+
+  try {
+    let parsed: unknown;
+    if (typeof wireValue === 'string') {
+      parsed = JSON.parse(wireValue);
+    } else if (Array.isArray(wireValue)) {
+      parsed = wireValue;
+    } else {
+      parsed = JSON.parse(String(wireValue));
+    }
+
+    if (!Array.isArray(parsed)) {
+      throw new Error(`Expected array for include alias '${alias}', got ${typeof parsed}`);
+    }
+
+    return parsed;
+  } catch (error) {
+    wrapIncludeAggregateFailure(error, alias, wireValue);
+  }
+}
+
+/**
+ * Decodes a single field. Single-armed: every cell takes the same path —
+ * `codec.decode → await → JSON-Schema validate → return plain value` — so
+ * sync- and async-authored codecs are indistinguishable to callers.
+ */
+async function decodeField(
+  alias: string,
+  wireValue: unknown,
+  plan: SqlExecutionPlan,
+  registry: CodecRegistry,
+  jsonValidators: JsonSchemaValidatorRegistry | undefined,
+  projection: SqlExecutionPlan['meta']['projection'],
+  fallbackColumnRefIndex: ColumnRefIndex | null,
+): Promise<unknown> {
+  if (wireValue === null || wireValue === undefined) {
+    return wireValue;
+  }
+
+  const codec = resolveRowCodec(alias, plan, registry);
+  if (!codec) {
+    return wireValue;
+  }
+
+  const ref = resolveColumnRefForAlias(alias, projection, fallbackColumnRefIndex);
+
+  let decoded: unknown;
+  try {
+    decoded = await codec.decode(wireValue);
+  } catch (error) {
+    wrapDecodeFailure(error, alias, ref, codec, wireValue);
+  }
+
+  if (jsonValidators && ref) {
+    try {
+      validateJsonValue(jsonValidators, ref.table, ref.column, decoded, 'decode', codec.id);
+    } catch (error) {
+      if (isJsonSchemaValidationError(error)) throw error;
+      wrapDecodeFailure(error, alias, ref, codec, wireValue);
+    }
+  }
+
+  return decoded;
+}
+
+/**
+ * Decodes a row by dispatching all per-cell codec calls concurrently via
+ * `Promise.all`. Each cell follows the single-armed `decodeField` path.
+ * Failures are wrapped in `RUNTIME.DECODE_FAILED` with `{ table, column,
+ * codec }` (or `{ alias, codec }` when no column ref is resolvable) and the
+ * original error attached on `cause`.
+ */
+export async function decodeRow(
   row: Record<string, unknown>,
-  plan: ExecutionPlan,
+  plan: SqlExecutionPlan,
   registry: CodecRegistry,
   jsonValidators?: JsonSchemaValidatorRegistry,
-): Record<string, unknown> {
-  const decoded: Record<string, unknown> = {};
+): Promise<Record<string, unknown>> {
   const projection = plan.meta.projection;
 
-  // Fallback for plans that do not provide projection alias -> table.column mapping.
+  // Build a column-ref index when the projection alias-to-ref mapping is
+  // unavailable so that decode failures and JSON-Schema validation can both
+  // surface { table, column } from `meta.refs.columns` when present.
   const fallbackColumnRefIndex =
-    jsonValidators && (!projection || Array.isArray(projection)) ? buildColumnRefIndex(plan) : null;
+    !projection || Array.isArray(projection) ? buildColumnRefIndex(plan) : null;
 
   let aliases: readonly string[];
   if (projection && !Array.isArray(projection)) {
@@ -100,7 +230,11 @@ export function decodeRow(
     aliases = Object.keys(row);
   }
 
-  for (const alias of aliases) {
+  const tasks: Promise<unknown>[] = [];
+  const includeIndices: { index: number; alias: string; value: unknown }[] = [];
+
+  for (let i = 0; i < aliases.length; i++) {
+    const alias = aliases[i] as string;
     const wireValue = row[alias];
 
     const projectionValue =
@@ -109,113 +243,35 @@ export function decodeRow(
         : undefined;
 
     if (typeof projectionValue === 'string' && projectionValue.startsWith('include:')) {
-      if (wireValue === null || wireValue === undefined) {
-        decoded[alias] = [];
-        continue;
-      }
-
-      try {
-        let parsed: unknown;
-        if (typeof wireValue === 'string') {
-          parsed = JSON.parse(wireValue);
-        } else if (Array.isArray(wireValue)) {
-          parsed = wireValue;
-        } else {
-          parsed = JSON.parse(String(wireValue));
-        }
-
-        if (!Array.isArray(parsed)) {
-          throw new Error(`Expected array for include alias '${alias}', got ${typeof parsed}`);
-        }
-
-        decoded[alias] = parsed;
-      } catch (error) {
-        const decodeError = new Error(
-          `Failed to parse JSON array for include alias '${alias}': ${error instanceof Error ? error.message : String(error)}`,
-        ) as Error & {
-          code: string;
-          category: string;
-          severity: string;
-          details?: Record<string, unknown>;
-        };
-        decodeError.code = 'RUNTIME.DECODE_FAILED';
-        decodeError.category = 'RUNTIME';
-        decodeError.severity = 'error';
-        decodeError.details = {
-          alias,
-          wirePreview:
-            typeof wireValue === 'string' && wireValue.length > 100
-              ? `${wireValue.substring(0, 100)}...`
-              : String(wireValue).substring(0, 100),
-        };
-        throw decodeError;
-      }
+      includeIndices.push({ index: i, alias, value: wireValue });
+      tasks.push(Promise.resolve(undefined));
       continue;
     }
 
-    if (wireValue === null || wireValue === undefined) {
-      decoded[alias] = wireValue;
-      continue;
-    }
-
-    const codec = resolveRowCodec(alias, plan, registry);
-
-    if (!codec) {
-      decoded[alias] = wireValue;
-      continue;
-    }
-
-    try {
-      const decodedValue = codec.decode(wireValue);
-
-      // Validate decoded JSON value against schema
-      if (jsonValidators) {
-        const ref = resolveColumnRefForAlias(alias, projection, fallbackColumnRefIndex);
-        if (ref) {
-          validateJsonValue(
-            jsonValidators,
-            ref.table,
-            ref.column,
-            decodedValue,
-            'decode',
-            codec.id,
-          );
-        }
-      }
+    tasks.push(
+      decodeField(
+        alias,
+        wireValue,
+        plan,
+        registry,
+        jsonValidators,
+        projection,
+        fallbackColumnRefIndex,
+      ),
+    );
+  }
 
-      decoded[alias] = decodedValue;
-    } catch (error) {
-      // Re-throw JSON schema validation errors as-is
-      if (
-        error instanceof Error &&
-        'code' in error &&
-        (error as Error & { code: string }).code === 'RUNTIME.JSON_SCHEMA_VALIDATION_FAILED'
-      ) {
-        throw error;
-      }
+  const settled = await Promise.all(tasks);
 
-      const decodeError = new Error(
-        `Failed to decode row alias '${alias}' with codec '${codec.id}': ${error instanceof Error ? error.message : String(error)}`,
-      ) as Error & {
-        code: string;
-        category: string;
-        severity: string;
-        details?: Record<string, unknown>;
-      };
-      decodeError.code = 'RUNTIME.DECODE_FAILED';
-      decodeError.category = 'RUNTIME';
-      decodeError.severity = 'error';
-      decodeError.details = {
-        alias,
-        codec: codec.id,
-        wirePreview:
-          typeof wireValue === 'string' && wireValue.length > 100
-            ? `${wireValue.substring(0, 100)}...`
-            : String(wireValue).substring(0, 100),
-      };
-      throw decodeError;
-    }
+  // Include aggregates are decoded synchronously after concurrent codec
+  // dispatch settles, so any decode failures upstream propagate first.
+  for (const entry of includeIndices) {
+    settled[entry.index] = decodeIncludeAggregate(entry.alias, entry.value);
   }
 
+  const decoded: Record<string, unknown> = {};
+  for (let i = 0; i < aliases.length; i++) {
+    decoded[aliases[i] as string] = settled[i];
+  }
   return decoded;
 }

package/src/codecs/encoding.ts

@@ -1,5 +1,7 @@
-import type { ExecutionPlan, ParamDescriptor } from '@prisma-next/contract/types';
+import type { ParamDescriptor } from '@prisma-next/contract/types';
+import { runtimeError } from '@prisma-next/framework-components/runtime';
 import type { Codec, CodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
 
 function resolveParamCodec(
   paramDescriptor: ParamDescriptor,
@@ -15,12 +17,40 @@ function resolveParamCodec(
   return null;
 }
 
-export function encodeParam(
+function paramLabel(paramDescriptor: ParamDescriptor, paramIndex: number): string {
+  return paramDescriptor.name ?? `param[${paramIndex}]`;
+}
+
+function wrapEncodeFailure(
+  error: unknown,
+  paramDescriptor: ParamDescriptor,
+  paramIndex: number,
+  codecId: string,
+): never {
+  const label = paramLabel(paramDescriptor, 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`.
+ */
+export async function encodeParam(
   value: unknown,
   paramDescriptor: ParamDescriptor,
   paramIndex: number,
   registry: CodecRegistry,
-): unknown {
+): Promise<unknown> {
   if (value === null || value === undefined) {
     return null;
   }
@@ -30,37 +60,45 @@ export function encodeParam(
     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);
+  } catch (error) {
+    wrapEncodeFailure(error, paramDescriptor, 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`.
+ */
+export async function encodeParams(
+  plan: SqlExecutionPlan,
+  registry: CodecRegistry,
+): Promise<readonly unknown[]> {
   if (plan.params.length === 0) {
     return plan.params;
   }
 
-  const encoded: unknown[] = [];
+  const descriptorCount = plan.meta.paramDescriptors.length;
+  const paramCount = plan.params.length;
 
-  for (let i = 0; i < plan.params.length; i++) {
+  const tasks: Promise<unknown>[] = new Array(paramCount);
+  for (let i = 0; i < paramCount; i++) {
     const paramValue = plan.params[i];
     const paramDescriptor = plan.meta.paramDescriptors[i];
 
-    if (paramDescriptor) {
-      encoded.push(encodeParam(paramValue, paramDescriptor, i, registry));
-    } else {
-      encoded.push(paramValue);
+    if (!paramDescriptor) {
+      throw runtimeError(
+        'RUNTIME.MISSING_PARAM_DESCRIPTOR',
+        `Missing paramDescriptor for parameter at index ${i} (plan has ${paramCount} params, ${descriptorCount} descriptors). The planner must emit one descriptor per param; this is a contract violation.`,
+        { paramIndex: i, paramCount, descriptorCount },
+      );
     }
+
+    tasks[i] = encodeParam(paramValue, paramDescriptor, i, registry);
   }
 
+  const encoded = await Promise.all(tasks);
   return Object.freeze(encoded);
 }

package/src/exports/index.ts

@@ -1,9 +1,8 @@
 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,
@@ -15,6 +14,13 @@ 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 +52,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}`;
+}