@prisma-next/sql-runtime 0.5.0-dev.8 → 0.5.0-dev.81

package/src/middleware/lints.ts

@@ -1,12 +1,12 @@
-import type { ExecutionPlan } from '@prisma-next/contract/types';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import { evaluateRawGuardrails } from '@prisma-next/runtime-executor';
 import {
   type AnyFromSource,
   type AnyQueryAst,
   isQueryAst,
 } from '@prisma-next/sql-relational-core/ast';
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { evaluateRawGuardrails } from '../guardrails/raw';
 import type { SqlMiddleware, SqlMiddlewareContext } from './sql-middleware';
 
 export interface LintsOptions {
@@ -94,6 +94,12 @@ function evaluateAstLints(ast: AnyQueryAst): LintFinding[] {
     case 'insert':
       break;
 
+    case 'raw-sql':
+      // Raw-SQL ASTs opt out of structural lints (LIMIT / WHERE etc.) —
+      // the embedded SQL fragments are caller-authored and the lint's
+      // shape-based heuristics don't apply.
+      break;
+
     // v8 ignore next 2
     default:
       throw new Error(`Unsupported AST kind: ${(ast satisfies never as { kind: string }).kind}`);
@@ -145,34 +151,22 @@ export function lints(options?: LintsOptions): SqlMiddleware {
     name: 'lints',
     familyId: 'sql' as const,
 
-    async beforeExecute(plan: ExecutionPlan, ctx: SqlMiddlewareContext) {
+    async beforeExecute(plan: SqlExecutionPlan, ctx: SqlMiddlewareContext) {
+      const findings: LintFinding[] = [];
       if (isQueryAst(plan.ast)) {
-        const findings = evaluateAstLints(plan.ast);
-
-        for (const lint of findings) {
-          const configuredSeverity = getConfiguredSeverity(lint.code, options);
-          const effectiveSeverity = configuredSeverity ?? lint.severity;
-
-          if (effectiveSeverity === 'error') {
-            throw runtimeError(lint.code, lint.message, lint.details);
-          }
-          if (effectiveSeverity === 'warn') {
-            ctx.log.warn({
-              code: lint.code,
-              message: lint.message,
-              details: lint.details,
-            });
-          }
+        findings.push(...evaluateAstLints(plan.ast));
+        // Raw-SQL ASTs opt out of structural AST lints (no LIMIT /
+        // WHERE shape to inspect) but the embedded SQL text still
+        // wants the raw-heuristic guardrails. Without this the lint
+        // middleware would silently disable both for raw plans.
+        if (plan.ast.kind === 'raw-sql') {
+          findings.push(...evaluateRawGuardrails(plan).lints);
         }
-        return;
-      }
-
-      if (fallback === 'skip') {
-        return;
+      } else if (fallback !== 'skip') {
+        findings.push(...evaluateRawGuardrails(plan).lints);
       }
 
-      const evaluation = evaluateRawGuardrails(plan);
-      for (const lint of evaluation.lints) {
+      for (const lint of findings) {
         const configuredSeverity = getConfiguredSeverity(lint.code, options);
         const effectiveSeverity = configuredSeverity ?? lint.severity;
 

package/src/middleware/sql-middleware.ts

@@ -1,4 +1,4 @@
-import type { Contract, ExecutionPlan, PlanMeta } from '@prisma-next/contract/types';
+import type { Contract, PlanMeta } from '@prisma-next/contract/types';
 import type {
   AfterExecuteResult,
   RuntimeMiddleware,
@@ -6,6 +6,8 @@ import type {
 } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { AnyQueryAst } from '@prisma-next/sql-relational-core/ast';
+import type { SqlParamRefMutator } from '@prisma-next/sql-relational-core/middleware';
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
 
 export interface SqlMiddlewareContext extends RuntimeMiddlewareContext {
   readonly contract: Contract<SqlStorage>;
@@ -20,7 +22,8 @@ export interface DraftPlan {
   readonly meta: PlanMeta;
 }
 
-export interface SqlMiddleware extends RuntimeMiddleware {
+export interface SqlMiddleware<TCodecMap extends Record<string, unknown> = Record<string, unknown>>
+  extends RuntimeMiddleware<SqlExecutionPlan, SqlParamRefMutator<TCodecMap>> {
   readonly familyId?: 'sql';
   /**
    * Rewrite the query AST before it is lowered to SQL. Middlewares run in
@@ -41,14 +44,31 @@ export interface SqlMiddleware extends RuntimeMiddleware {
    * See `docs/architecture docs/subsystems/4. Runtime & Middleware Framework.md`.
    */
   beforeCompile?(draft: DraftPlan, ctx: SqlMiddlewareContext): Promise<DraftPlan | undefined>;
-  beforeExecute?(plan: ExecutionPlan, ctx: SqlMiddlewareContext): Promise<void>;
+  /**
+   * Mutate `ParamRef.value` slots before encode runs. The third `params`
+   * argument is a {@link SqlParamRefMutator} scoped to value slots only —
+   * SQL strings, projections, and `ParamRef` membership are not mutable.
+   * Existing `(plan)` and `(plan, ctx)` middleware bodies that ignore the
+   * additional argument continue to compile and run unchanged.
+   *
+   * `ctx.signal` carries the per-query `AbortSignal` (ADR 207); middleware
+   * that wraps a network SDK forwards `ctx.signal` to that SDK.
+   * Cooperative cancellation: a body that ignores the signal still
+   * surfaces `RUNTIME.ABORTED { phase: 'beforeExecute' }` promptly via
+   * the runtime's race against the signal.
+   */
+  beforeExecute?(
+    plan: SqlExecutionPlan,
+    ctx: SqlMiddlewareContext,
+    params?: SqlParamRefMutator<TCodecMap>,
+  ): void | Promise<void>;
   onRow?(
     row: Record<string, unknown>,
-    plan: ExecutionPlan,
+    plan: SqlExecutionPlan,
     ctx: SqlMiddlewareContext,
   ): Promise<void>;
   afterExecute?(
-    plan: ExecutionPlan,
+    plan: SqlExecutionPlan,
     result: AfterExecuteResult,
     ctx: SqlMiddlewareContext,
   ): Promise<void>;

package/src/runtime-spi.ts

@@ -0,0 +1,44 @@
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import type { ExecutionPlan } from '@prisma-next/framework-components/runtime';
+import type { MarkerStatement } from '@prisma-next/sql-relational-core/ast';
+
+/**
+ * Reader of the SQL contract marker. SQL runtimes verify the database's
+ * `prisma_contract.marker` row against the runtime's contract by issuing
+ * this statement before executing user queries (when `verify` is enabled).
+ * Each adapter is responsible for any target-specific row decoding before
+ * delegating to the shared row schema.
+ */
+export interface MarkerReader {
+  readMarkerStatement(): MarkerStatement;
+  parseMarkerRow(row: unknown): ContractMarkerRecord;
+}
+
+/**
+ * SQL family adapter SPI consumed by `SqlRuntime`. Encapsulates the
+ * runtime contract, marker reader, and plan validation logic so the
+ * runtime can be unit-tested without a concrete SQL adapter profile.
+ *
+ * Implemented by `SqlFamilyAdapter` for production and by mock classes
+ * in tests.
+ */
+export interface RuntimeFamilyAdapter<TContract = unknown> {
+  readonly contract: TContract;
+  readonly markerReader: MarkerReader;
+  validatePlan(plan: ExecutionPlan, contract: TContract): void;
+}
+
+export interface RuntimeVerifyOptions {
+  readonly mode: 'onFirstUse' | 'startup' | 'always';
+  readonly requireMarker: boolean;
+}
+
+export type TelemetryOutcome = 'success' | 'runtime-error';
+
+export interface RuntimeTelemetryEvent {
+  readonly lane: string;
+  readonly target: string;
+  readonly fingerprint: string;
+  readonly outcome: TelemetryOutcome;
+  readonly durationMs?: number;
+}