@prisma-next/sql-runtime 0.5.0-dev.3 → 0.5.0-dev.30

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,18 +25,28 @@ function hasAggregateWithoutGroupBy(ast: SelectAst): boolean {
   return ast.projection.some((item) => item.expr.kind === 'aggregate');
 }
 
+function primaryTableFromAst(ast: SelectAst): string | undefined {
+  switch (ast.from.kind) {
+    case 'table-source':
+      return ast.from.name;
+    case 'derived-table-source':
+      return ast.from.alias;
+    default:
+      return undefined;
+  }
+}
+
 function estimateRowsFromAst(
   ast: SelectAst,
   tableRows: Record<string, number>,
   defaultTableRows: number,
-  refs: { tables?: readonly string[] } | undefined,
   hasAggregateWithoutGroup: boolean,
 ): number | null {
   if (hasAggregateWithoutGroup) {
     return 1;
   }
 
-  const table = refs?.tables?.[0];
+  const table = primaryTableFromAst(ast);
   if (!table) {
     return null;
   }
@@ -47,30 +60,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 +82,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 +110,7 @@ export function budgets(options?: BudgetsOptions): SqlMiddleware {
     },
 
     async afterExecute(
-      _plan: ExecutionPlan,
+      _plan: SqlExecutionPlan,
       result: AfterExecuteResult,
       ctx: SqlMiddlewareContext,
     ) {
@@ -145,15 +129,9 @@ 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';
 
@@ -194,52 +172,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;
-    }
-  }
 }

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 {
@@ -145,7 +145,7 @@ export function lints(options?: LintsOptions): SqlMiddleware {
     name: 'lints',
     familyId: 'sql' as const,
 
-    async beforeExecute(plan: ExecutionPlan, ctx: SqlMiddlewareContext) {
+    async beforeExecute(plan: SqlExecutionPlan, ctx: SqlMiddlewareContext) {
       if (isQueryAst(plan.ast)) {
         const findings = evaluateAstLints(plan.ast);
 

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,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 { SqlExecutionPlan } from '@prisma-next/sql-relational-core/plan';
 
 export interface SqlMiddlewareContext extends RuntimeMiddlewareContext {
   readonly contract: Contract<SqlStorage>;
@@ -20,7 +21,7 @@ export interface DraftPlan {
   readonly meta: PlanMeta;
 }
 
-export interface SqlMiddleware extends RuntimeMiddleware {
+export interface SqlMiddleware extends RuntimeMiddleware<SqlExecutionPlan> {
   readonly familyId?: 'sql';
   /**
    * Rewrite the query AST before it is lowered to SQL. Middlewares run in
@@ -41,14 +42,14 @@ 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>;
+  beforeExecute?(plan: SqlExecutionPlan, ctx: SqlMiddlewareContext): 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;
+}

package/src/sql-family-adapter.ts

@@ -1,8 +1,9 @@
-import type { Contract, ExecutionPlan } from '@prisma-next/contract/types';
+import type { Contract } from '@prisma-next/contract/types';
+import type { ExecutionPlan } from '@prisma-next/framework-components/runtime';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import type { MarkerReader, RuntimeFamilyAdapter } from '@prisma-next/runtime-executor';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { AdapterProfile } from '@prisma-next/sql-relational-core/ast';
+import type { MarkerReader, RuntimeFamilyAdapter } from './runtime-spi';
 
 export class SqlFamilyAdapter<TContract extends Contract<SqlStorage>>
   implements RuntimeFamilyAdapter<TContract>

package/src/sql-marker.ts

@@ -1,4 +1,4 @@
-import type { MarkerStatement } from '@prisma-next/runtime-executor';
+import type { MarkerStatement } from '@prisma-next/sql-relational-core/ast';
 
 export interface SqlStatement {
   readonly sql: string;
@@ -12,6 +12,15 @@ export interface WriteMarkerInput {
   readonly canonicalVersion?: number;
   readonly appTag?: string;
   readonly meta?: Record<string, unknown>;
+  /**
+   * Applied-invariants set on the marker.
+   *
+   * - `undefined` → existing column left untouched. Sign and
+   *   verify-database paths use this; they don't accumulate invariants.
+   * - explicit value (including `[]`) → column overwritten with
+   *   exactly that value.
+   */
+  readonly invariants?: readonly string[];
 }
 
 export const ensureSchemaStatement: SqlStatement = {
@@ -28,7 +37,8 @@ export const ensureTableStatement: SqlStatement = {
     canonical_version int,
     updated_at timestamptz not null default now(),
     app_tag text,
-    meta jsonb not null default '{}'
+    meta jsonb not null default '{}',
+    invariants text[] not null default '{}'
   )`,
   params: [],
 };
@@ -42,7 +52,8 @@ export function readContractMarker(): MarkerStatement {
       canonical_version,
       updated_at,
       app_tag,
-      meta
+      meta,
+      invariants
     from prisma_contract.marker
     where id = $1`,
     params: [1],
@@ -54,52 +65,56 @@ export interface WriteContractMarkerStatements {
   readonly update: SqlStatement;
 }
 
-export function writeContractMarker(input: WriteMarkerInput): WriteContractMarkerStatements {
-  const baseParams: readonly unknown[] = [
-    1,
-    input.storageHash,
-    input.profileHash,
-    input.contractJson ?? null,
-    input.canonicalVersion ?? null,
-    input.appTag ?? null,
-    JSON.stringify(input.meta ?? {}),
+/**
+ * Variable columns that participate in INSERT/UPDATE alongside the
+ * always-on `id = $1` and `updated_at = now()`. Each column declares
+ * its name, optional cast type, and parameter value; the placeholder
+ * (`$N`) is computed positionally below — adding or reordering a
+ * column doesn't desync indices. `invariants` only appears when the
+ * caller supplies it — see `WriteMarkerInput.invariants`.
+ */
+function markerColumns(
+  input: WriteMarkerInput,
+): ReadonlyArray<{ readonly name: string; readonly type?: string; readonly param: unknown }> {
+  return [
+    { name: 'core_hash', param: input.storageHash },
+    { name: 'profile_hash', param: input.profileHash },
+    { name: 'contract_json', type: 'jsonb', param: input.contractJson ?? null },
+    { name: 'canonical_version', param: input.canonicalVersion ?? null },
+    { name: 'app_tag', param: input.appTag ?? null },
+    { name: 'meta', type: 'jsonb', param: JSON.stringify(input.meta ?? {}) },
+    ...(input.invariants !== undefined
+      ? [{ name: 'invariants' as const, type: 'text[]' as const, param: input.invariants }]
+      : []),
   ];
+}
 
-  const insert: SqlStatement = {
-    sql: `insert into prisma_contract.marker (
-        id,
-        core_hash,
-        profile_hash,
-        contract_json,
-        canonical_version,
-        updated_at,
-        app_tag,
-        meta
-      ) values (
-        $1,
-        $2,
-        $3,
-        $4::jsonb,
-        $5,
-        now(),
-        $6,
-        $7::jsonb
-      )`,
-    params: baseParams,
-  };
+export function writeContractMarker(input: WriteMarkerInput): WriteContractMarkerStatements {
+  const cols = markerColumns(input);
+  // $1 is reserved for `id`; subsequent positions follow the order of cols.
+  const placed = cols.map((c, i) => ({
+    name: c.name,
+    expr: c.type ? `$${i + 2}::${c.type}` : `$${i + 2}`,
+    param: c.param,
+  }));
+  const params: readonly unknown[] = [1, ...placed.map((c) => c.param)];
 
-  const update: SqlStatement = {
-    sql: `update prisma_contract.marker set
-        core_hash = $2,
-        profile_hash = $3,
-        contract_json = $4::jsonb,
-        canonical_version = $5,
-        updated_at = now(),
-        app_tag = $6,
-        meta = $7::jsonb
-      where id = $1`,
-    params: baseParams,
-  };
+  // `updated_at = now()` is a SQL literal with no parameter slot, so it
+  // sits outside `placed` and is appended directly to each statement.
+  const insertColumns = ['id', ...placed.map((c) => c.name), 'updated_at'].join(', ');
+  const insertValues = ['$1', ...placed.map((c) => c.expr), 'now()'].join(', ');
+  const setClauses = [...placed.map((c) => `${c.name} = ${c.expr}`), 'updated_at = now()'].join(
+    ', ',
+  );
 
-  return { insert, update };
+  return {
+    insert: {
+      sql: `insert into prisma_contract.marker (${insertColumns}) values (${insertValues})`,
+      params,
+    },
+    update: {
+      sql: `update prisma_contract.marker set ${setClauses} where id = $1`,
+      params,
+    },
+  };
 }