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

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

@@ -1,22 +1,30 @@
 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,
+  GeneratorStability,
   RuntimeMutationDefaultGenerator,
   RuntimeParameterizedCodecDescriptor,
   SqlExecutionStack,
@@ -36,6 +44,7 @@ export {
 } from '../sql-context';
 export type { SqlStatement } from '../sql-marker';
 export {
+  APP_SPACE_ID,
   ensureSchemaStatement,
   ensureTableStatement,
   readContractMarker,
@@ -46,10 +55,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

@@ -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

@@ -1,7 +1,10 @@
-import type { ExecutionPlan } from '@prisma-next/contract/types';
-import { type RuntimeErrorEnvelope, runtimeError } from '@prisma-next/framework-components/runtime';
-import type { AfterExecuteResult } from '@prisma-next/runtime-executor';
+import {
+  type AfterExecuteResult,
+  type RuntimeErrorEnvelope,
+  runtimeError,
+} from '@prisma-next/framework-components/runtime';
 import { isQueryAst, type SelectAst } from '@prisma-next/sql-relational-core/ast';
+import type { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
 import type { SqlMiddleware, SqlMiddlewareContext } from './sql-middleware';
 
 export interface BudgetsOptions {
@@ -22,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);
@@ -47,30 +58,6 @@ function estimateRowsFromAst(
   return tableEstimate;
 }
 
-function estimateRowsFromHeuristics(
-  plan: ExecutionPlan,
-  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: ExecutionPlan): boolean {
-  return typeof plan.meta.annotations?.['limit'] === 'number';
-}
-
 function emitBudgetViolation(
   error: RuntimeErrorEnvelope,
   shouldBlock: boolean,
@@ -93,26 +80,21 @@ export function budgets(options?: BudgetsOptions): SqlMiddleware {
   const maxLatencyMs = options?.maxLatencyMs ?? 1_000;
   const rowSeverity = options?.severities?.rowCount ?? 'error';
 
-  const observedRowsByPlan = new WeakMap<ExecutionPlan, { count: number }>();
+  const observedRowsByPlan = new WeakMap<SqlExecutionPlan, { count: number }>();
 
   return Object.freeze({
     name: 'budgets',
     familyId: 'sql' as const,
 
-    async beforeExecute(plan: ExecutionPlan, ctx: SqlMiddlewareContext) {
+    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: ExecutionPlan, _ctx: SqlMiddlewareContext) {
+    async onRow(_row: Record<string, unknown>, plan: SqlExecutionPlan, _ctx: SqlMiddlewareContext) {
       const state = observedRowsByPlan.get(plan);
       if (!state) return;
       state.count += 1;
@@ -126,7 +108,7 @@ export function budgets(options?: BudgetsOptions): SqlMiddleware {
     },
 
     async afterExecute(
-      _plan: ExecutionPlan,
+      _plan: SqlExecutionPlan,
       result: AfterExecuteResult,
       ctx: SqlMiddlewareContext,
     ) {
@@ -145,44 +127,26 @@ export function budgets(options?: BudgetsOptions): SqlMiddleware {
     },
   });
 
-  function evaluateSelectAst(plan: ExecutionPlan, 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',
@@ -194,52 +158,4 @@ export function budgets(options?: BudgetsOptions): SqlMiddleware {
       );
     }
   }
-
-  async function evaluateWithHeuristics(plan: ExecutionPlan, 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;
-    }
-  }
 }