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

package/src/content-hash.ts

@@ -0,0 +1,44 @@
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
+import { canonicalStringify } from '@prisma-next/utils/canonical-stringify';
+import { hashContent } from '@prisma-next/utils/hash-content';
+
+/**
+ * Computes a stable content hash for a lowered SQL execution plan.
+ *
+ * Internally builds an unambiguous canonical-stringified preimage from
+ * three components:
+ *
+ * 1. `meta.storageHash` — discriminates by schema. A migration changes the
+ *    storage hash, which invalidates cached entries automatically.
+ * 2. `exec.sql` — the raw lowered SQL text. Two queries with different
+ *    structure produce different keys. Note that we deliberately do **not**
+ *    use `computeSqlFingerprint` here: that helper strips literals to group
+ *    executions by statement shape (used by telemetry), which is the
+ *    opposite of what a content hash needs — we want per-execution
+ *    discrimination, not per-statement-shape grouping.
+ * 3. `exec.params` — the bound parameters. `canonicalStringify` produces a
+ *    deterministic serialization that is stable across object key
+ *    insertion order and that distinguishes types JSON would otherwise
+ *    conflate (e.g. `BigInt(1)` vs `1`).
+ *
+ * The components are wrapped in an object and canonicalized as a single
+ * unit (rather than concatenated with a delimiter) so component
+ * boundaries are unambiguous: any character appearing inside `sql` or
+ * `storageHash` cannot bleed across components and produce a collision
+ * with a different split of the same characters.
+ *
+ * The canonical string is then piped through `hashContent` to produce a
+ * bounded, opaque digest. See `@prisma-next/utils/hash-content` for the
+ * rationale.
+ *
+ * @internal
+ */
+export function computeSqlContentHash(exec: SqlExecutionPlan): Promise<string> {
+  return hashContent(
+    canonicalStringify({
+      storageHash: exec.meta.storageHash,
+      sql: exec.sql,
+      params: exec.params,
+    }),
+  );
+}

package/src/exports/index.ts

@@ -2,13 +2,14 @@ export type {
   AfterExecuteResult,
   RuntimeLog as Log,
 } from '@prisma-next/framework-components/runtime';
-export type { MarkerStatement } from '@prisma-next/sql-relational-core/ast';
+export type { MarkerReadResult, 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';
@@ -23,6 +24,7 @@ export type {
 } from '../runtime-spi';
 export type {
   ExecutionContext,
+  GeneratorStability,
   RuntimeMutationDefaultGenerator,
   RuntimeParameterizedCodecDescriptor,
   SqlExecutionStack,
@@ -42,6 +44,7 @@ export {
 } from '../sql-context';
 export type { SqlStatement } from '../sql-marker';
 export {
+  APP_SPACE_ID,
   ensureSchemaStatement,
   ensureTableStatement,
   readContractMarker,

package/src/guardrails/raw.ts

@@ -1,4 +1,4 @@
-import type { PlanMeta, PlanRefs } from '@prisma-next/contract/types';
+import type { PlanMeta } from '@prisma-next/contract/types';
 
 export type LintSeverity = 'error' | 'warn';
 export type BudgetSeverity = 'error' | 'warn';
@@ -103,58 +103,9 @@ export function evaluateRawGuardrails(
     );
   }
 
-  const refs = plan.meta.refs;
-  if (refs) {
-    evaluateIndexCoverage(refs, lints);
-  }
-
   return { lints, budgets, statement: statementType };
 }
 
-function evaluateIndexCoverage(refs: PlanRefs, lints: LintFinding[]) {
-  const predicateColumns = refs.columns ?? [];
-  if (predicateColumns.length === 0) {
-    return;
-  }
-
-  const indexes = refs.indexes ?? [];
-
-  if (indexes.length === 0) {
-    lints.push(
-      createLint(
-        'LINT.UNINDEXED_PREDICATE',
-        'warn',
-        'Raw SQL plan predicates lack supporting indexes',
-        {
-          predicates: predicateColumns,
-        },
-      ),
-    );
-    return;
-  }
-
-  const hasSupportingIndex = predicateColumns.every((column) =>
-    indexes.some(
-      (index) =>
-        index.table === column.table &&
-        index.columns.some((col) => col.toLowerCase() === column.column.toLowerCase()),
-    ),
-  );
-
-  if (!hasSupportingIndex) {
-    lints.push(
-      createLint(
-        'LINT.UNINDEXED_PREDICATE',
-        'warn',
-        'Raw SQL plan predicates lack supporting indexes',
-        {
-          predicates: predicateColumns,
-        },
-      ),
-    );
-  }
-}
-
 function classifyStatement(sql: string): 'select' | 'mutation' | 'other' {
   const trimmed = sql.trim();
   const lower = trimmed.toLowerCase();

package/src/marker.ts

@@ -9,6 +9,7 @@ export interface ContractMarkerRow {
   updated_at: Date;
   app_tag: string | null;
   meta: unknown | null;
+  invariants: readonly string[];
 }
 
 const MetaSchema = type({ '[string]': 'unknown' });
@@ -45,6 +46,7 @@ const ContractMarkerRowSchema = type({
   'updated_at?': 'Date | string',
   'app_tag?': 'string | null',
   'meta?': 'unknown | null',
+  invariants: type('string').array(),
 });
 
 export function parseContractMarkerRow(row: unknown): ContractMarkerRecord {
@@ -54,29 +56,20 @@ export function parseContractMarkerRow(row: unknown): ContractMarkerRecord {
     throw new Error(`Invalid contract marker row: ${messages}`);
   }
 
-  const validatedRow = result as {
-    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;
-  };
-
-  const updatedAt = validatedRow.updated_at
-    ? validatedRow.updated_at instanceof Date
-      ? validatedRow.updated_at
-      : new Date(validatedRow.updated_at)
+  const updatedAt = result.updated_at
+    ? result.updated_at instanceof Date
+      ? result.updated_at
+      : new Date(result.updated_at)
     : new Date();
 
   return {
-    storageHash: validatedRow.core_hash,
-    profileHash: validatedRow.profile_hash,
-    contractJson: validatedRow.contract_json ?? null,
-    canonicalVersion: validatedRow.canonical_version ?? null,
+    storageHash: result.core_hash,
+    profileHash: result.profile_hash,
+    contractJson: result.contract_json ?? null,
+    canonicalVersion: result.canonical_version ?? null,
     updatedAt,
-    appTag: validatedRow.app_tag ?? null,
-    meta: parseMeta(validatedRow.meta),
+    appTag: result.app_tag ?? null,
+    meta: parseMeta(result.meta),
+    invariants: result.invariants,
   };
 }

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

@@ -1,5 +1,3 @@
-import type { ParamDescriptor, PlanMeta } from '@prisma-next/contract/types';
-import type { AnyQueryAst } from '@prisma-next/sql-relational-core/ast';
 import type { DraftPlan, SqlMiddleware, SqlMiddlewareContext } from './sql-middleware';
 
 export async function runBeforeCompileChain(
@@ -27,33 +25,5 @@ export async function runBeforeCompileChain(
     current = result;
   }
 
-  if (current.ast === initial.ast) {
-    return current;
-  }
-
-  // The rewritten AST may have introduced, removed, or replaced ParamRefs, so
-  // the descriptors collected at lane build time no longer line up with what
-  // the adapter will emit when it walks the new AST. Re-derive descriptors
-  // from the rewritten AST so `params` and `paramDescriptors` stay in lockstep
-  // by the time `encodeParams` runs.
-  const paramDescriptors = deriveParamDescriptorsFromAst(current.ast);
-  const meta: PlanMeta = { ...current.meta, paramDescriptors };
-  return { ast: current.ast, meta };
-}
-
-function deriveParamDescriptorsFromAst(ast: AnyQueryAst): ReadonlyArray<ParamDescriptor> {
-  const refs = ast.collectParamRefs();
-  const seen = new Set<unknown>();
-  const descriptors: ParamDescriptor[] = [];
-  for (const ref of refs) {
-    if (seen.has(ref)) continue;
-    seen.add(ref);
-    descriptors.push({
-      index: descriptors.length + 1,
-      ...(ref.name !== undefined ? { name: ref.name } : {}),
-      source: 'dsl',
-      ...(ref.codecId !== undefined ? { codecId: ref.codecId } : {}),
-    });
-  }
-  return descriptors;
+  return current;
 }

package/src/middleware/budgets.ts

@@ -25,23 +25,31 @@ function hasAggregateWithoutGroupBy(ast: SelectAst): boolean {
   return ast.projection.some((item) => item.expr.kind === 'aggregate');
 }
 
+function primaryTableFromAst(ast: SelectAst): string {
+  switch (ast.from.kind) {
+    case 'table-source':
+      return ast.from.name;
+    case 'derived-table-source':
+      return ast.from.alias;
+    // v8 ignore next 4
+    default:
+      throw new Error(
+        `Unsupported source kind: ${(ast.from satisfies never as { kind: string }).kind}`,
+      );
+  }
+}
+
 function estimateRowsFromAst(
   ast: SelectAst,
   tableRows: Record<string, number>,
   defaultTableRows: number,
-  refs: { tables?: readonly string[] } | undefined,
   hasAggregateWithoutGroup: boolean,
-): number | null {
+): number {
   if (hasAggregateWithoutGroup) {
     return 1;
   }
 
-  const table = refs?.tables?.[0];
-  if (!table) {
-    return null;
-  }
-
-  const tableEstimate = tableRows[table] ?? defaultTableRows;
+  const tableEstimate = tableRows[primaryTableFromAst(ast)] ?? defaultTableRows;
 
   if (ast.limit !== undefined) {
     return Math.min(ast.limit, tableEstimate);
@@ -50,30 +58,6 @@ function estimateRowsFromAst(
   return tableEstimate;
 }
 
-function estimateRowsFromHeuristics(
-  plan: SqlExecutionPlan,
-  tableRows: Record<string, number>,
-  defaultTableRows: number,
-): number | null {
-  const table = plan.meta.refs?.tables?.[0];
-  if (!table) {
-    return null;
-  }
-
-  const tableEstimate = tableRows[table] ?? defaultTableRows;
-
-  const limit = plan.meta.annotations?.['limit'];
-  if (typeof limit === 'number') {
-    return Math.min(limit, tableEstimate);
-  }
-
-  return tableEstimate;
-}
-
-function hasDetectableLimitFromHeuristics(plan: SqlExecutionPlan): boolean {
-  return typeof plan.meta.annotations?.['limit'] === 'number';
-}
-
 function emitBudgetViolation(
   error: RuntimeErrorEnvelope,
   shouldBlock: boolean,
@@ -105,14 +89,9 @@ export function budgets(options?: BudgetsOptions): SqlMiddleware {
     async beforeExecute(plan: SqlExecutionPlan, ctx: SqlMiddlewareContext) {
       observedRowsByPlan.set(plan, { count: 0 });
 
-      if (isQueryAst(plan.ast)) {
-        if (plan.ast.kind === 'select') {
-          return evaluateSelectAst(plan, plan.ast, ctx);
-        }
-        return;
+      if (isQueryAst(plan.ast) && plan.ast.kind === 'select') {
+        return evaluateSelectAst(plan.ast, ctx);
       }
-
-      return evaluateWithHeuristics(plan, ctx);
     },
 
     async onRow(_row: Record<string, unknown>, plan: SqlExecutionPlan, _ctx: SqlMiddlewareContext) {
@@ -148,44 +127,26 @@ export function budgets(options?: BudgetsOptions): SqlMiddleware {
     },
   });
 
-  function evaluateSelectAst(plan: SqlExecutionPlan, ast: SelectAst, ctx: SqlMiddlewareContext) {
+  function evaluateSelectAst(ast: SelectAst, ctx: SqlMiddlewareContext) {
     const hasAggNoGroup = hasAggregateWithoutGroupBy(ast);
-    const estimated = estimateRowsFromAst(
-      ast,
-      tableRows,
-      defaultTableRows,
-      plan.meta.refs,
-      hasAggNoGroup,
-    );
+    const estimated = estimateRowsFromAst(ast, tableRows, defaultTableRows, hasAggNoGroup);
     const isUnbounded = ast.limit === undefined && !hasAggNoGroup;
     const shouldBlock = rowSeverity === 'error' || ctx.mode === 'strict';
 
     if (isUnbounded) {
-      if (estimated !== null && estimated >= maxRows) {
-        emitBudgetViolation(
-          runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
-            source: 'ast',
-            estimatedRows: estimated,
-            maxRows,
-          }),
-          shouldBlock,
-          ctx,
-        );
-        return;
-      }
-
+      const details =
+        estimated >= maxRows
+          ? { source: 'ast', estimatedRows: estimated, maxRows }
+          : { source: 'ast', maxRows };
       emitBudgetViolation(
-        runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
-          source: 'ast',
-          maxRows,
-        }),
+        runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', details),
         shouldBlock,
         ctx,
       );
       return;
     }
 
-    if (estimated !== null && estimated > maxRows) {
+    if (estimated > maxRows) {
       emitBudgetViolation(
         runtimeError('BUDGET.ROWS_EXCEEDED', 'Estimated row count exceeds budget', {
           source: 'ast',
@@ -197,52 +158,4 @@ export function budgets(options?: BudgetsOptions): SqlMiddleware {
       );
     }
   }
-
-  async function evaluateWithHeuristics(plan: SqlExecutionPlan, ctx: SqlMiddlewareContext) {
-    const estimated = estimateRowsFromHeuristics(plan, tableRows, defaultTableRows);
-    const isUnbounded = !hasDetectableLimitFromHeuristics(plan);
-    const sqlUpper = plan.sql.trimStart().toUpperCase();
-    const isSelect = sqlUpper.startsWith('SELECT');
-    const shouldBlock = rowSeverity === 'error' || ctx.mode === 'strict';
-
-    if (isSelect && isUnbounded) {
-      if (estimated !== null && estimated >= maxRows) {
-        emitBudgetViolation(
-          runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
-            source: 'heuristic',
-            estimatedRows: estimated,
-            maxRows,
-          }),
-          shouldBlock,
-          ctx,
-        );
-        return;
-      }
-
-      emitBudgetViolation(
-        runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
-          source: 'heuristic',
-          maxRows,
-        }),
-        shouldBlock,
-        ctx,
-      );
-      return;
-    }
-
-    if (estimated !== null) {
-      if (estimated > maxRows) {
-        emitBudgetViolation(
-          runtimeError('BUDGET.ROWS_EXCEEDED', 'Estimated row count exceeds budget', {
-            source: 'heuristic',
-            estimatedRows: estimated,
-            maxRows,
-          }),
-          shouldBlock,
-          ctx,
-        );
-      }
-      return;
-    }
-  }
 }

package/src/middleware/lints.ts

@@ -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}`);
@@ -146,33 +152,21 @@ export function lints(options?: LintsOptions): SqlMiddleware {
     familyId: 'sql' as const,
 
     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

@@ -6,6 +6,7 @@ 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 {
@@ -21,7 +22,8 @@ export interface DraftPlan {
   readonly meta: PlanMeta;
 }
 
-export interface SqlMiddleware extends RuntimeMiddleware<SqlExecutionPlan> {
+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
@@ -42,7 +44,24 @@ export interface SqlMiddleware extends RuntimeMiddleware<SqlExecutionPlan> {
    * See `docs/architecture docs/subsystems/4. Runtime & Middleware Framework.md`.
    */
   beforeCompile?(draft: DraftPlan, ctx: SqlMiddlewareContext): Promise<DraftPlan | undefined>;
-  beforeExecute?(plan: SqlExecutionPlan, 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: SqlExecutionPlan,

package/src/runtime-spi.ts

@@ -1,16 +1,11 @@
 import type { ExecutionPlan } from '@prisma-next/framework-components/runtime';
-import type { MarkerStatement } from '@prisma-next/sql-relational-core/ast';
+import type { MarkerReadResult, SqlQueryable } 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).
- *
- * Structurally satisfied by `AdapterProfile`, which already exposes
- * `readMarkerStatement(): MarkerStatement` for adapter-level introspection.
+ * Reader of the SQL contract marker. SQL runtimes call `readMarker` before executing user queries (when `verify` is enabled). The adapter owns the full marker-read flow — probing for storage, issuing the read, decoding the row — and returns a tagged result so callers can distinguish "marker storage missing", "no row for this space", and "present".
  */
 export interface MarkerReader {
-  readMarkerStatement(): MarkerStatement;
+  readMarker(queryable: SqlQueryable): Promise<MarkerReadResult>;
 }
 
 /**