@prisma-next/sql-runtime 0.5.0-dev.1 → 0.5.0-dev.11

package/src/guardrails/raw.ts

@@ -0,0 +1,214 @@
+import type { PlanMeta, PlanRefs } 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'],
+        },
+      ),
+    );
+  }
+
+  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();
+
+  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,82 @@
+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;
+}
+
+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',
+});
+
+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 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)
+    : new Date();
+
+  return {
+    storageHash: validatedRow.core_hash,
+    profileHash: validatedRow.profile_hash,
+    contractJson: validatedRow.contract_json ?? null,
+    canonicalVersion: validatedRow.canonical_version ?? null,
+    updatedAt,
+    appTag: validatedRow.app_tag ?? null,
+    meta: parseMeta(validatedRow.meta),
+  };
+}

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

@@ -0,0 +1,59 @@
+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(
+  middleware: readonly SqlMiddleware[],
+  initial: DraftPlan,
+  ctx: SqlMiddlewareContext,
+): Promise<DraftPlan> {
+  let current = initial;
+  for (const mw of middleware) {
+    if (!mw.beforeCompile) {
+      continue;
+    }
+    const result = await mw.beforeCompile(current, ctx);
+    if (result === undefined) {
+      continue;
+    }
+    if (result.ast === current.ast) {
+      continue;
+    }
+    ctx.log.debug?.({
+      event: 'middleware.rewrite',
+      middleware: mw.name,
+      lane: current.meta.lane,
+    });
+    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;
+}

package/src/middleware/budgets.ts

@@ -1,11 +1,11 @@
-import type { ExecutionPlan } from '@prisma-next/contract/types';
-import { type RuntimeErrorEnvelope, runtimeError } from '@prisma-next/framework-components/runtime';
-import type {
-  AfterExecuteResult,
-  Middleware,
-  MiddlewareContext,
-} 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 {
   readonly maxRows?: number;
@@ -51,7 +51,7 @@ function estimateRowsFromAst(
 }
 
 function estimateRowsFromHeuristics(
-  plan: ExecutionPlan,
+  plan: SqlExecutionPlan,
   tableRows: Record<string, number>,
   defaultTableRows: number,
 ): number | null {
@@ -70,14 +70,14 @@ function estimateRowsFromHeuristics(
   return tableEstimate;
 }
 
-function hasDetectableLimitFromHeuristics(plan: ExecutionPlan): boolean {
+function hasDetectableLimitFromHeuristics(plan: SqlExecutionPlan): boolean {
   return typeof plan.meta.annotations?.['limit'] === 'number';
 }
 
 function emitBudgetViolation(
   error: RuntimeErrorEnvelope,
   shouldBlock: boolean,
-  ctx: MiddlewareContext<unknown>,
+  ctx: SqlMiddlewareContext,
 ): void {
   if (shouldBlock) {
     throw error;
@@ -89,20 +89,20 @@ function emitBudgetViolation(
   });
 }
 
-export function budgets<TContract = unknown>(options?: BudgetsOptions): Middleware<TContract> {
+export function budgets(options?: BudgetsOptions): SqlMiddleware {
   const maxRows = options?.maxRows ?? 10_000;
   const defaultTableRows = options?.defaultTableRows ?? 10_000;
   const tableRows = options?.tableRows ?? {};
   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: MiddlewareContext<TContract>) {
+    async beforeExecute(plan: SqlExecutionPlan, ctx: SqlMiddlewareContext) {
       observedRowsByPlan.set(plan, { count: 0 });
 
       if (isQueryAst(plan.ast)) {
@@ -115,11 +115,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
       return evaluateWithHeuristics(plan, ctx);
     },
 
-    async onRow(
-      _row: Record<string, unknown>,
-      plan: ExecutionPlan,
-      _ctx: MiddlewareContext<TContract>,
-    ) {
+    async onRow(_row: Record<string, unknown>, plan: SqlExecutionPlan, _ctx: SqlMiddlewareContext) {
       const state = observedRowsByPlan.get(plan);
       if (!state) return;
       state.count += 1;
@@ -133,9 +129,9 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
     },
 
     async afterExecute(
-      _plan: ExecutionPlan,
+      _plan: SqlExecutionPlan,
       result: AfterExecuteResult,
-      ctx: MiddlewareContext<TContract>,
+      ctx: SqlMiddlewareContext,
     ) {
       const latencyMs = result.latencyMs;
       if (latencyMs > maxLatencyMs) {
@@ -146,17 +142,13 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
             maxLatencyMs,
           }),
           shouldBlock,
-          ctx as MiddlewareContext<unknown>,
+          ctx,
         );
       }
     },
   });
 
-  function evaluateSelectAst(
-    plan: ExecutionPlan,
-    ast: SelectAst,
-    ctx: MiddlewareContext<TContract>,
-  ) {
+  function evaluateSelectAst(plan: SqlExecutionPlan, ast: SelectAst, ctx: SqlMiddlewareContext) {
     const hasAggNoGroup = hasAggregateWithoutGroupBy(ast);
     const estimated = estimateRowsFromAst(
       ast,
@@ -177,7 +169,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
             maxRows,
           }),
           shouldBlock,
-          ctx as MiddlewareContext<unknown>,
+          ctx,
         );
         return;
       }
@@ -188,7 +180,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
           maxRows,
         }),
         shouldBlock,
-        ctx as MiddlewareContext<unknown>,
+        ctx,
       );
       return;
     }
@@ -201,12 +193,12 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
           maxRows,
         }),
         shouldBlock,
-        ctx as MiddlewareContext<unknown>,
+        ctx,
       );
     }
   }
 
-  async function evaluateWithHeuristics(plan: ExecutionPlan, ctx: MiddlewareContext<TContract>) {
+  async function evaluateWithHeuristics(plan: SqlExecutionPlan, ctx: SqlMiddlewareContext) {
     const estimated = estimateRowsFromHeuristics(plan, tableRows, defaultTableRows);
     const isUnbounded = !hasDetectableLimitFromHeuristics(plan);
     const sqlUpper = plan.sql.trimStart().toUpperCase();
@@ -222,7 +214,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
             maxRows,
           }),
           shouldBlock,
-          ctx as MiddlewareContext<unknown>,
+          ctx,
         );
         return;
       }
@@ -233,7 +225,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
           maxRows,
         }),
         shouldBlock,
-        ctx as MiddlewareContext<unknown>,
+        ctx,
       );
       return;
     }
@@ -247,7 +239,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
             maxRows,
           }),
           shouldBlock,
-          ctx as MiddlewareContext<unknown>,
+          ctx,
         );
       }
       return;

package/src/middleware/lints.ts

@@ -1,13 +1,13 @@
-import type { ExecutionPlan } from '@prisma-next/contract/types';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import type { Middleware, MiddlewareContext } from '@prisma-next/runtime-executor';
-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 {
   readonly severities?: {
@@ -138,14 +138,14 @@ function getConfiguredSeverity(code: string, options?: LintsOptions): 'warn' | '
  * Fallback: When ast is missing, `fallbackWhenAstMissing: 'raw'` uses heuristic
  * SQL parsing; `'skip'` skips all lints. Default is `'raw'`.
  */
-export function lints<TContract = unknown>(options?: LintsOptions): Middleware<TContract> {
+export function lints(options?: LintsOptions): SqlMiddleware {
   const fallback = options?.fallbackWhenAstMissing ?? 'raw';
 
   return Object.freeze({
     name: 'lints',
     familyId: 'sql' as const,
 
-    async beforeExecute(plan: ExecutionPlan, ctx: MiddlewareContext<TContract>) {
+    async beforeExecute(plan: SqlExecutionPlan, ctx: SqlMiddlewareContext) {
       if (isQueryAst(plan.ast)) {
         const findings = evaluateAstLints(plan.ast);
 

package/src/middleware/sql-middleware.ts

@@ -1,25 +1,55 @@
-import type { Contract, ExecutionPlan } from '@prisma-next/contract/types';
+import type { Contract, PlanMeta } from '@prisma-next/contract/types';
 import type {
   AfterExecuteResult,
   RuntimeMiddleware,
   RuntimeMiddlewareContext,
 } 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>;
 }
 
-export interface SqlMiddleware extends RuntimeMiddleware {
-  readonly familyId: 'sql';
-  beforeExecute?(plan: ExecutionPlan, ctx: SqlMiddlewareContext): Promise<void>;
+/**
+ * Pre-lowering query view passed to `beforeCompile`. Carries the typed SQL
+ * AST and plan metadata; `sql`/`params` are produced later by the adapter.
+ */
+export interface DraftPlan {
+  readonly ast: AnyQueryAst;
+  readonly meta: PlanMeta;
+}
+
+export interface SqlMiddleware extends RuntimeMiddleware<SqlExecutionPlan> {
+  readonly familyId?: 'sql';
+  /**
+   * Rewrite the query AST before it is lowered to SQL. Middlewares run in
+   * registration order; each sees the predecessor's output, so rewrites
+   * compose (e.g. soft-delete + tenant isolation).
+   *
+   * Return `undefined` (or a draft whose `ast` reference equals the input's)
+   * to pass through. Return a draft with a new `ast` reference to replace it;
+   * the runtime emits a `middleware.rewrite` debug log event and continues
+   * with the new draft. `adapter.lower()` runs once after the chain.
+   *
+   * Use `AstRewriter` / `SelectAst.withWhere` / `AndExpr.of` etc. to build
+   * the rewritten AST. Predicates and literals go through parameterized
+   * constructors by default — no SQL-injection surface is added. **Warning:**
+   * constructing `LiteralExpr.of(userInput)` from untrusted input bypasses
+   * that guarantee; use `ParamRef.of(userInput, ...)` instead.
+   *
+   * 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>;
   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,43 @@
+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).
+ *
+ * Structurally satisfied by `AdapterProfile`, which already exposes
+ * `readMarkerStatement(): MarkerStatement` for adapter-level introspection.
+ */
+export interface MarkerReader {
+  readMarkerStatement(): MarkerStatement;
+}
+
+/**
+ * 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;
+}