@prisma-next/runtime-executor 0.3.0-dev.1 → 0.3.0-dev.100

package/src/fingerprint.ts

@@ -0,0 +1,14 @@
+import { createHash } from 'node:crypto';
+
+const STRING_LITERAL_REGEX = /'(?:''|[^'])*'/g;
+const NUMERIC_LITERAL_REGEX = /\b\d+(?:\.\d+)?\b/g;
+const WHITESPACE_REGEX = /\s+/g;
+
+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,204 @@
+import type { ExecutionPlan, 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';
+}
+
+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: ExecutionPlan,
+  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/index.ts

@@ -0,0 +1 @@
+export * from './exports';

package/src/marker.ts

@@ -0,0 +1,85 @@
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import { type } from 'arktype';
+
+// Re-export for backward compatibility
+export type { ContractMarkerRecord } from '@prisma-next/contract/types';
+
+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/plugins/types.ts

@@ -0,0 +1,42 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+
+export type Severity = 'error' | 'warn' | 'info';
+
+export interface Log {
+  info(event: unknown): void;
+  warn(event: unknown): void;
+  error(event: unknown): void;
+}
+
+export interface PluginContext<TContract = unknown, TAdapter = unknown, TDriver = unknown> {
+  readonly contract: TContract;
+  readonly adapter: TAdapter;
+  readonly driver: TDriver;
+  readonly mode: 'strict' | 'permissive';
+  readonly now: () => number;
+  readonly log: Log;
+}
+
+export interface AfterExecuteResult {
+  readonly rowCount: number;
+  readonly latencyMs: number;
+  readonly completed: boolean;
+}
+
+export interface Plugin<TContract = unknown, TAdapter = unknown, TDriver = unknown> {
+  readonly name: string;
+  beforeExecute?(
+    plan: ExecutionPlan,
+    ctx: PluginContext<TContract, TAdapter, TDriver>,
+  ): Promise<void>;
+  onRow?(
+    row: Record<string, unknown>,
+    plan: ExecutionPlan,
+    ctx: PluginContext<TContract, TAdapter, TDriver>,
+  ): Promise<void>;
+  afterExecute?(
+    plan: ExecutionPlan,
+    result: AfterExecuteResult,
+    ctx: PluginContext<TContract, TAdapter, TDriver>,
+  ): Promise<void>;
+}

package/src/runtime-core.ts

@@ -0,0 +1,362 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type { OperationRegistry } from '@prisma-next/operations';
+import { AsyncIterableResult } from './async-iterable-result';
+import { runtimeError } from './errors';
+import { computeSqlFingerprint } from './fingerprint';
+import { parseContractMarkerRow } from './marker';
+import type { Log, Plugin, PluginContext } from './plugins/types';
+import type { RuntimeFamilyAdapter } from './runtime-spi';
+
+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;
+}
+
+export interface RuntimeCoreOptions<TContract = unknown, TAdapter = unknown, TDriver = unknown> {
+  readonly familyAdapter: RuntimeFamilyAdapter<TContract>;
+  readonly driver: TDriver;
+  readonly verify: RuntimeVerifyOptions;
+  readonly plugins?: readonly Plugin<TContract, TAdapter, TDriver>[];
+  readonly mode?: 'strict' | 'permissive';
+  readonly log?: Log;
+  readonly operationRegistry: OperationRegistry;
+}
+
+export interface RuntimeCore<TContract = unknown, TAdapter = unknown, TDriver = unknown>
+  extends RuntimeQueryable {
+  // Type parameters are used in the implementation for type safety
+  readonly _typeContract?: TContract;
+  readonly _typeAdapter?: TAdapter;
+  readonly _typeDriver?: TDriver;
+  connection(): Promise<RuntimeConnection>;
+  telemetry(): RuntimeTelemetryEvent | null;
+  close(): Promise<void>;
+  operations(): OperationRegistry;
+}
+
+export interface RuntimeConnection extends RuntimeQueryable {
+  transaction(): Promise<RuntimeTransaction>;
+  release(): Promise<void>;
+}
+
+export interface RuntimeTransaction extends RuntimeQueryable {
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+export interface RuntimeQueryable {
+  execute<Row = Record<string, unknown>>(plan: ExecutionPlan<Row>): AsyncIterableResult<Row>;
+}
+
+interface DriverWithQuery<_TDriver> {
+  query(sql: string, params: readonly unknown[]): Promise<{ rows: ReadonlyArray<unknown> }>;
+}
+
+interface DriverWithConnection<_TDriver> {
+  acquireConnection(): Promise<DriverConnection>;
+}
+
+export interface DriverConnection extends Queryable {
+  beginTransaction(): Promise<DriverTransaction>;
+  release(): Promise<void>;
+}
+
+export interface DriverTransaction extends Queryable {
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+export interface Queryable {
+  execute<Row = Record<string, unknown>>(options: {
+    sql: string;
+    params: readonly unknown[];
+  }): AsyncIterable<Row>;
+}
+
+interface DriverWithClose<_TDriver> {
+  close(): Promise<void>;
+}
+
+class RuntimeCoreImpl<TContract = unknown, TAdapter = unknown, TDriver = unknown>
+  implements RuntimeCore<TContract, TAdapter, TDriver>
+{
+  readonly _typeContract?: TContract;
+  readonly _typeAdapter?: TAdapter;
+  readonly _typeDriver?: TDriver;
+  private readonly contract: TContract;
+  private readonly familyAdapter: RuntimeFamilyAdapter<TContract>;
+  private readonly driver: TDriver;
+  private readonly plugins: readonly Plugin<TContract, TAdapter, TDriver>[];
+  private readonly mode: 'strict' | 'permissive';
+  private readonly verify: RuntimeVerifyOptions;
+  private readonly operationRegistry: OperationRegistry;
+  private readonly pluginContext: PluginContext<TContract, TAdapter, TDriver>;
+
+  private verified: boolean;
+  private startupVerified: boolean;
+  private _telemetry: RuntimeTelemetryEvent | null;
+
+  constructor(options: RuntimeCoreOptions<TContract, TAdapter, TDriver>) {
+    const { familyAdapter, driver } = options;
+    this.contract = familyAdapter.contract;
+    this.familyAdapter = familyAdapter;
+    this.driver = driver;
+    this.plugins = options.plugins ?? [];
+    this.mode = options.mode ?? 'strict';
+    this.verify = options.verify;
+    this.operationRegistry = options.operationRegistry;
+
+    this.verified = options.verify.mode === 'startup' ? false : options.verify.mode === 'always';
+    this.startupVerified = false;
+    this._telemetry = null;
+
+    this.pluginContext = {
+      contract: this.contract,
+      adapter: options.familyAdapter as unknown as TAdapter,
+      driver: this.driver,
+      mode: this.mode,
+      now: () => Date.now(),
+      log: options.log ?? {
+        info: () => {
+          // No-op in MVP - diagnostics stay out of runtime core
+        },
+        warn: () => {
+          // No-op in MVP - diagnostics stay out of runtime core
+        },
+        error: () => {
+          // No-op in MVP - diagnostics stay out of runtime core
+        },
+      },
+    };
+  }
+
+  private async verifyPlanIfNeeded(_plan: ExecutionPlan): Promise<void> {
+    void _plan;
+    if (this.verify.mode === 'always') {
+      this.verified = false;
+    }
+
+    if (this.verified) {
+      return;
+    }
+
+    const readStatement = this.familyAdapter.markerReader.readMarkerStatement();
+    const driver = this.driver as unknown as DriverWithQuery<TDriver>;
+    const result = await driver.query(readStatement.sql, readStatement.params);
+
+    if (result.rows.length === 0) {
+      if (this.verify.requireMarker) {
+        throw runtimeError('CONTRACT.MARKER_MISSING', 'Contract marker not found in database');
+      }
+
+      this.verified = true;
+      return;
+    }
+
+    const marker = parseContractMarkerRow(result.rows[0]);
+
+    const contract = this.contract as {
+      storageHash: string;
+      executionHash?: string | null;
+      profileHash?: string | null;
+    };
+    if (marker.storageHash !== contract.storageHash) {
+      throw runtimeError(
+        'CONTRACT.MARKER_MISMATCH',
+        'Database storage hash does not match contract',
+        {
+          expected: contract.storageHash,
+          actual: marker.storageHash,
+        },
+      );
+    }
+
+    const expectedProfile = contract.profileHash ?? null;
+    if (expectedProfile !== null && marker.profileHash !== expectedProfile) {
+      throw runtimeError(
+        'CONTRACT.MARKER_MISMATCH',
+        'Database profile hash does not match contract',
+        {
+          expectedProfile,
+          actualProfile: marker.profileHash,
+        },
+      );
+    }
+
+    this.verified = true;
+    this.startupVerified = true;
+  }
+
+  private validatePlan(plan: ExecutionPlan): void {
+    this.familyAdapter.validatePlan(plan, this.contract);
+  }
+
+  private recordTelemetry(
+    plan: ExecutionPlan,
+    outcome: TelemetryOutcome,
+    durationMs?: number,
+  ): void {
+    const contract = this.contract as { target: string };
+    this._telemetry = Object.freeze({
+      lane: plan.meta.lane,
+      target: contract.target,
+      fingerprint: computeSqlFingerprint(plan.sql),
+      outcome,
+      ...(durationMs !== undefined ? { durationMs } : {}),
+    });
+  }
+
+  execute<Row = Record<string, unknown>>(plan: ExecutionPlan<Row>): AsyncIterableResult<Row> {
+    return this.#executeWith(plan, this.driver as Queryable);
+  }
+
+  async connection(): Promise<RuntimeConnection> {
+    const driver = this.driver as unknown as DriverWithConnection<TDriver>;
+    const driverConn = await driver.acquireConnection();
+    const self = this;
+
+    const runtimeConnection: RuntimeConnection = {
+      async transaction(): Promise<RuntimeTransaction> {
+        const driverTx = await driverConn.beginTransaction();
+        const runtimeTx: RuntimeTransaction = {
+          async commit(): Promise<void> {
+            await driverTx.commit();
+          },
+          async rollback(): Promise<void> {
+            await driverTx.rollback();
+          },
+          execute<Row = Record<string, unknown>>(
+            plan: ExecutionPlan<Row>,
+          ): AsyncIterableResult<Row> {
+            return self.#executeWith(plan, driverTx);
+          },
+        };
+        return runtimeTx;
+      },
+      execute<Row = Record<string, unknown>>(plan: ExecutionPlan<Row>): AsyncIterableResult<Row> {
+        return self.#executeWith(plan, driverConn);
+      },
+      async release(): Promise<void> {
+        await driverConn.release();
+      },
+    };
+
+    return runtimeConnection;
+  }
+
+  telemetry(): RuntimeTelemetryEvent | null {
+    return this._telemetry;
+  }
+
+  operations(): OperationRegistry {
+    return this.operationRegistry;
+  }
+
+  close(): Promise<void> {
+    const driver = this.driver as unknown as DriverWithClose<TDriver>;
+    if (typeof driver.close === 'function') {
+      return driver.close();
+    }
+    return Promise.resolve();
+  }
+
+  #executeWith<Row = Record<string, unknown>>(
+    plan: ExecutionPlan<Row>,
+    queryable: Queryable,
+  ): AsyncIterableResult<Row> {
+    this.validatePlan(plan);
+    this._telemetry = null;
+
+    const iterator = async function* (
+      self: RuntimeCoreImpl<TContract, TAdapter, TDriver>,
+    ): AsyncGenerator<Row, void, unknown> {
+      const startedAt = Date.now();
+      let rowCount = 0;
+      let completed = false;
+
+      if (!self.startupVerified && self.verify.mode === 'startup') {
+        await self.verifyPlanIfNeeded(plan);
+      }
+
+      if (self.verify.mode === 'onFirstUse') {
+        await self.verifyPlanIfNeeded(plan);
+      }
+
+      try {
+        if (self.verify.mode === 'always') {
+          await self.verifyPlanIfNeeded(plan);
+        }
+
+        for (const plugin of self.plugins) {
+          if (plugin.beforeExecute) {
+            await plugin.beforeExecute(plan, self.pluginContext);
+          }
+        }
+
+        const encodedParams = plan.params;
+
+        for await (const row of queryable.execute<Record<string, unknown>>({
+          sql: plan.sql,
+          params: encodedParams,
+        })) {
+          for (const plugin of self.plugins) {
+            if (plugin.onRow) {
+              await plugin.onRow(row, plan, self.pluginContext);
+            }
+          }
+          rowCount++;
+          yield row as Row;
+        }
+
+        completed = true;
+        self.recordTelemetry(plan, 'success', Date.now() - startedAt);
+      } catch (error) {
+        if (self._telemetry === null) {
+          self.recordTelemetry(plan, 'runtime-error', Date.now() - startedAt);
+        }
+
+        const latencyMs = Date.now() - startedAt;
+        for (const plugin of self.plugins) {
+          if (plugin.afterExecute) {
+            try {
+              await plugin.afterExecute(
+                plan,
+                { rowCount, latencyMs, completed },
+                self.pluginContext,
+              );
+            } catch {
+              // Ignore errors from afterExecute hooks
+            }
+          }
+        }
+
+        throw error;
+      }
+
+      const latencyMs = Date.now() - startedAt;
+      for (const plugin of self.plugins) {
+        if (plugin.afterExecute) {
+          await plugin.afterExecute(plan, { rowCount, latencyMs, completed }, self.pluginContext);
+        }
+      }
+    };
+
+    return new AsyncIterableResult(iterator(this));
+  }
+}
+
+export function createRuntimeCore<TContract = unknown, TAdapter = unknown, TDriver = unknown>(
+  options: RuntimeCoreOptions<TContract, TAdapter, TDriver>,
+): RuntimeCore<TContract, TAdapter, TDriver> {
+  return new RuntimeCoreImpl(options);
+}