@prisma-next/sql-runtime 0.4.1 → 0.4.3

package/src/sql-runtime.ts

@@ -1,38 +1,50 @@
-import type { Contract, ExecutionPlan } from '@prisma-next/contract/types';
+import type { Contract } from '@prisma-next/contract/types';
 import type {
   ExecutionStackInstance,
   RuntimeDriverInstance,
 } from '@prisma-next/framework-components/execution';
-import { checkMiddlewareCompatibility } from '@prisma-next/framework-components/runtime';
-import type {
-  Log,
-  Middleware,
-  RuntimeCore,
-  RuntimeCoreOptions,
-  RuntimeTelemetryEvent,
-  RuntimeVerifyOptions,
-  TelemetryOutcome,
-} from '@prisma-next/runtime-executor';
 import {
   AsyncIterableResult,
-  createRuntimeCore,
+  checkAborted,
+  checkMiddlewareCompatibility,
+  RuntimeCore,
+  type RuntimeExecuteOptions,
+  type RuntimeLog,
   runtimeError,
-} from '@prisma-next/runtime-executor';
+  runWithMiddleware,
+} from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type {
   Adapter,
   AnyQueryAst,
   CodecRegistry,
+  ContractCodecRegistry,
   LoweredStatement,
+  SqlCodecCallContext,
   SqlDriver,
+  SqlQueryable,
+  SqlTransaction,
 } from '@prisma-next/sql-relational-core/ast';
-import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
-import type { JsonSchemaValidatorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
+import type { SqlExecutionPlan, SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import type {
+  CodecDescriptorRegistry,
+  JsonSchemaValidatorRegistry,
+} from '@prisma-next/sql-relational-core/query-lane-context';
+import type { RuntimeScope } from '@prisma-next/sql-relational-core/types';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { decodeRow } from './codecs/decoding';
 import { encodeParams } from './codecs/encoding';
 import { validateCodecRegistryCompleteness } from './codecs/validation';
+import { computeSqlFingerprint } from './fingerprint';
 import { lowerSqlPlan } from './lower-sql-plan';
+import { runBeforeCompileChain } from './middleware/before-compile-chain';
+import type { SqlMiddleware, SqlMiddlewareContext } from './middleware/sql-middleware';
+import type {
+  RuntimeFamilyAdapter,
+  RuntimeTelemetryEvent,
+  RuntimeVerifyOptions,
+  TelemetryOutcome,
+} from './runtime-spi';
 import type {
   ExecutionContext,
   SqlRuntimeAdapterInstance,
@@ -40,12 +52,14 @@ import type {
 } from './sql-context';
 import { SqlFamilyAdapter } from './sql-family-adapter';
 
+export type Log = RuntimeLog;
+
 export interface RuntimeOptions<TContract extends Contract<SqlStorage> = Contract<SqlStorage>> {
   readonly context: ExecutionContext<TContract>;
   readonly adapter: Adapter<AnyQueryAst, Contract<SqlStorage>, LoweredStatement>;
   readonly driver: SqlDriver<unknown>;
   readonly verify: RuntimeVerifyOptions;
-  readonly middleware?: readonly Middleware<TContract>[];
+  readonly middleware?: readonly SqlMiddleware[];
   readonly mode?: 'strict' | 'permissive';
   readonly log?: Log;
 }
@@ -64,7 +78,7 @@ export interface CreateRuntimeOptions<
   readonly context: ExecutionContext<TContract>;
   readonly driver: SqlDriver<unknown>;
   readonly verify: RuntimeVerifyOptions;
-  readonly middleware?: readonly Middleware<TContract>[];
+  readonly middleware?: readonly SqlMiddleware[];
   readonly mode?: 'strict' | 'permissive';
   readonly log?: Log;
 }
@@ -106,39 +120,39 @@ export interface RuntimeTransaction extends RuntimeQueryable {
   rollback(): Promise<void>;
 }
 
-export interface RuntimeQueryable {
-  execute<Row = Record<string, unknown>>(
-    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
-  ): AsyncIterableResult<Row>;
-}
+export interface RuntimeQueryable extends RuntimeScope {}
 
 export interface TransactionContext extends RuntimeQueryable {
   readonly invalidated: boolean;
 }
 
-interface CoreQueryable {
-  execute<Row = Record<string, unknown>>(plan: ExecutionPlan<Row>): AsyncIterableResult<Row>;
-}
-
 export type { RuntimeTelemetryEvent, RuntimeVerifyOptions, TelemetryOutcome };
 
+function isExecutionPlan(plan: SqlExecutionPlan | SqlQueryPlan): plan is SqlExecutionPlan {
+  return 'sql' in plan;
+}
+
 class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorage>>
+  extends RuntimeCore<SqlQueryPlan, SqlExecutionPlan, SqlMiddleware>
   implements Runtime
 {
-  private readonly core: RuntimeCore<TContract, SqlDriver<unknown>>;
   private readonly contract: TContract;
   private readonly adapter: Adapter<AnyQueryAst, Contract<SqlStorage>, LoweredStatement>;
+  private readonly driver: SqlDriver<unknown>;
+  private readonly familyAdapter: RuntimeFamilyAdapter<Contract<SqlStorage>>;
   private readonly codecRegistry: CodecRegistry;
+  private readonly contractCodecs: ContractCodecRegistry;
+  private readonly codecDescriptors: CodecDescriptorRegistry;
   private readonly jsonSchemaValidators: JsonSchemaValidatorRegistry | undefined;
+  private readonly sqlCtx: SqlMiddlewareContext;
+  private readonly verify: RuntimeVerifyOptions;
   private codecRegistryValidated: boolean;
+  private verified: boolean;
+  private startupVerified: boolean;
+  private _telemetry: RuntimeTelemetryEvent | null;
 
   constructor(options: RuntimeOptions<TContract>) {
     const { context, adapter, driver, verify, middleware, mode, log } = options;
-    this.contract = context.contract;
-    this.adapter = adapter;
-    this.codecRegistry = context.codecs;
-    this.jsonSchemaValidators = context.jsonSchemaValidators;
-    this.codecRegistryValidated = false;
 
     if (middleware) {
       for (const mw of middleware) {
@@ -146,111 +160,331 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
       }
     }
 
-    const familyAdapter = new SqlFamilyAdapter(context.contract, adapter.profile);
-
-    const coreOptions: RuntimeCoreOptions<TContract, SqlDriver<unknown>> = {
-      familyAdapter,
-      driver,
-      verify,
-      ...ifDefined('middleware', middleware),
-      ...ifDefined('mode', mode),
-      ...ifDefined('log', log),
+    const sqlCtx: SqlMiddlewareContext = {
+      contract: context.contract,
+      mode: mode ?? 'strict',
+      now: () => Date.now(),
+      log: log ?? {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+      },
     };
 
-    this.core = createRuntimeCore(coreOptions);
+    super({ middleware: middleware ?? [], ctx: sqlCtx });
+
+    this.contract = context.contract;
+    this.adapter = adapter;
+    this.driver = driver;
+    this.familyAdapter = new SqlFamilyAdapter(context.contract, adapter.profile);
+    this.codecRegistry = context.codecs;
+    this.contractCodecs = context.contractCodecs;
+    this.codecDescriptors = context.codecDescriptors;
+    this.jsonSchemaValidators = context.jsonSchemaValidators;
+    this.sqlCtx = sqlCtx;
+    this.verify = verify;
+    this.codecRegistryValidated = false;
+    this.verified = verify.mode === 'startup' ? false : verify.mode === 'always';
+    this.startupVerified = false;
+    this._telemetry = null;
 
     if (verify.mode === 'startup') {
-      validateCodecRegistryCompleteness(this.codecRegistry, context.contract);
+      validateCodecRegistryCompleteness(this.codecDescriptors, context.contract);
       this.codecRegistryValidated = true;
     }
   }
 
-  private ensureCodecRegistryValidated(contract: Contract<SqlStorage>): void {
-    if (!this.codecRegistryValidated) {
-      validateCodecRegistryCompleteness(this.codecRegistry, contract);
-      this.codecRegistryValidated = true;
-    }
+  /**
+   * Lower a `SqlQueryPlan` (AST + meta) into a `SqlExecutionPlan` with
+   * encoded parameters ready for the driver. This is the single point at
+   * which params transition from app-layer values to driver wire-format.
+   *
+   * `ctx: SqlCodecCallContext` is forwarded to `encodeParams` so per-query
+   * cancellation reaches every codec body during parameter encoding. The
+   * framework abstract typed this as `CodecCallContext`; the SQL family
+   * narrows it to the SQL-specific extension. SQL params do not populate
+   * `ctx.column` — encode-side column metadata is the middleware's domain.
+   */
+  protected override async lower(
+    plan: SqlQueryPlan,
+    ctx: SqlCodecCallContext,
+  ): Promise<SqlExecutionPlan> {
+    const lowered = lowerSqlPlan(this.adapter, this.contract, plan);
+    return Object.freeze({
+      ...lowered,
+      params: await encodeParams(lowered, this.codecRegistry, ctx, this.contractCodecs),
+    });
   }
 
-  private toExecutionPlan<Row>(plan: ExecutionPlan<Row> | SqlQueryPlan<Row>): ExecutionPlan<Row> {
-    const isSqlQueryPlan = (p: ExecutionPlan<Row> | SqlQueryPlan<Row>): p is SqlQueryPlan<Row> => {
-      return 'ast' in p && !('sql' in p);
-    };
+  /**
+   * Default driver invocation. Production execution paths override the
+   * queryable target (e.g. transaction or connection) by going through
+   * `executeAgainstQueryable`; this implementation supports any caller of
+   * `super.execute(plan)` and the abstract-base contract.
+   */
+  protected override runDriver(exec: SqlExecutionPlan): AsyncIterable<Record<string, unknown>> {
+    return this.driver.execute<Record<string, unknown>>({
+      sql: exec.sql,
+      params: exec.params,
+    });
+  }
 
-    return isSqlQueryPlan(plan) ? lowerSqlPlan(this.adapter, this.contract, plan) : plan;
+  /**
+   * SQL pre-compile hook. Runs the registered middleware `beforeCompile`
+   * chain over the plan's draft (AST + meta). Returns the original plan
+   * unchanged when no middleware rewrote the AST; otherwise returns a new
+   * plan carrying the rewritten AST and meta. The AST is the authoritative
+   * source of execution metadata, so a rewrite needs no sidecar
+   * reconciliation here — the lowering adapter and the encoder both walk
+   * the rewritten AST directly.
+   */
+  protected override async runBeforeCompile(plan: SqlQueryPlan): Promise<SqlQueryPlan> {
+    const rewrittenDraft = await runBeforeCompileChain(
+      this.middleware,
+      { ast: plan.ast, meta: plan.meta },
+      this.sqlCtx,
+    );
+    return rewrittenDraft.ast === plan.ast
+      ? plan
+      : { ...plan, ast: rewrittenDraft.ast, meta: rewrittenDraft.meta };
   }
 
-  private executeAgainstQueryable<Row = Record<string, unknown>>(
-    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
-    queryable: CoreQueryable,
+  override execute<Row>(
+    plan: (SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>) & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
   ): AsyncIterableResult<Row> {
-    this.ensureCodecRegistryValidated(this.contract);
-    const executablePlan = this.toExecutionPlan(plan);
-
-    const iterator = async function* (
-      self: SqlRuntimeImpl<TContract>,
-    ): AsyncGenerator<Row, void, unknown> {
-      const encodedParams = encodeParams(executablePlan, self.codecRegistry);
-      const planWithEncodedParams: ExecutionPlan<Row> = {
-        ...executablePlan,
-        params: encodedParams,
-      };
+    return this.executeAgainstQueryable<Row>(plan, this.driver, options);
+  }
+
+  private executeAgainstQueryable<Row>(
+    plan: SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>,
+    queryable: SqlQueryable,
+    options?: RuntimeExecuteOptions,
+  ): AsyncIterableResult<Row> {
+    this.ensureCodecRegistryValidated();
+
+    const self = this;
+    const signal = options?.signal;
+    // One ctx per execute() call — the same reference is shared by
+    // encodeParams (lower), decodeRow (per-row), and the stream loop's
+    // between-row checks. Per-cell ctx allocations inside decodeField add
+    // `column` for resolvable cells without re-wrapping the signal. The
+    // ctx object is always allocated; the `signal` field is only included
+    // when a signal was supplied (exactOptionalPropertyTypes).
+    const codecCtx: SqlCodecCallContext = signal === undefined ? {} : { signal };
+
+    const generator = async function* (): AsyncGenerator<Row, void, unknown> {
+      checkAborted(codecCtx, 'stream');
+
+      const exec: SqlExecutionPlan = isExecutionPlan(plan)
+        ? Object.freeze({
+            ...plan,
+            params: await encodeParams(plan, self.codecRegistry, codecCtx, self.contractCodecs),
+          })
+        : await self.lower(await self.runBeforeCompile(plan), codecCtx);
+
+      self.familyAdapter.validatePlan(exec, self.contract);
+      self._telemetry = null;
+
+      if (!self.startupVerified && self.verify.mode === 'startup') {
+        await self.verifyMarker();
+      }
+
+      if (!self.verified && self.verify.mode === 'onFirstUse') {
+        await self.verifyMarker();
+      }
 
-      const coreIterator = queryable.execute(planWithEncodedParams);
+      const startedAt = Date.now();
+      let outcome: TelemetryOutcome | null = null;
 
-      for await (const rawRow of coreIterator) {
-        const decodedRow = decodeRow(
-          rawRow as Record<string, unknown>,
-          executablePlan,
-          self.codecRegistry,
-          self.jsonSchemaValidators,
+      try {
+        if (self.verify.mode === 'always') {
+          await self.verifyMarker();
+        }
+
+        const stream = runWithMiddleware<SqlExecutionPlan, Record<string, unknown>>(
+          exec,
+          self.middleware,
+          self.ctx,
+          () =>
+            queryable.execute<Record<string, unknown>>({
+              sql: exec.sql,
+              params: exec.params,
+            }),
         );
-        yield decodedRow as Row;
+
+        // Manually drive the driver's async iterator so the between-row
+        // abort check fires *before* requesting the next row. With a
+        // `for await...of` loop the runtime would await `iterator.next()`
+        // first, leaving a window where one extra row is pulled through
+        // the driver after the signal aborted.
+        const iterator = stream[Symbol.asyncIterator]();
+        try {
+          while (true) {
+            checkAborted(codecCtx, 'stream');
+            const next = await iterator.next();
+            if (next.done) {
+              break;
+            }
+            const decodedRow = await decodeRow(
+              next.value,
+              exec,
+              self.codecRegistry,
+              self.jsonSchemaValidators,
+              codecCtx,
+              self.contractCodecs,
+            );
+            yield decodedRow as Row;
+          }
+        } finally {
+          // Best-effort iterator cleanup so the driver can release its
+          // resources whether the stream finished normally, threw, or was
+          // abandoned by the consumer.
+          await iterator.return?.();
+        }
+
+        outcome = 'success';
+      } catch (error) {
+        outcome = 'runtime-error';
+        throw error;
+      } finally {
+        if (outcome !== null) {
+          self.recordTelemetry(exec, outcome, Date.now() - startedAt);
+        }
       }
     };
 
-    return new AsyncIterableResult(iterator(this));
-  }
-
-  execute<Row = Record<string, unknown>>(
-    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
-  ): AsyncIterableResult<Row> {
-    return this.executeAgainstQueryable(plan, this.core);
+    return new AsyncIterableResult(generator());
   }
 
   async connection(): Promise<RuntimeConnection> {
-    const coreConn = await this.core.connection();
+    const driverConn = await this.driver.acquireConnection();
     const self = this;
+
     const wrappedConnection: RuntimeConnection = {
       async transaction(): Promise<RuntimeTransaction> {
-        const coreTx = await coreConn.transaction();
-        return {
-          commit: coreTx.commit.bind(coreTx),
-          rollback: coreTx.rollback.bind(coreTx),
-          execute<Row = Record<string, unknown>>(
-            plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
-          ): AsyncIterableResult<Row> {
-            return self.executeAgainstQueryable(plan, coreTx);
-          },
-        };
+        const driverTx = await driverConn.beginTransaction();
+        return self.wrapTransaction(driverTx);
+      },
+      async release(): Promise<void> {
+        await driverConn.release();
       },
-      release: coreConn.release.bind(coreConn),
-      destroy: coreConn.destroy.bind(coreConn),
-      execute<Row = Record<string, unknown>>(
-        plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+      async destroy(reason?: unknown): Promise<void> {
+        await driverConn.destroy(reason);
+      },
+      execute<Row>(
+        plan: (SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>) & { readonly _row?: Row },
+        options?: RuntimeExecuteOptions,
       ): AsyncIterableResult<Row> {
-        return self.executeAgainstQueryable(plan, coreConn);
+        return self.executeAgainstQueryable<Row>(plan, driverConn, options);
       },
     };
+
     return wrappedConnection;
   }
 
+  private wrapTransaction(driverTx: SqlTransaction): RuntimeTransaction {
+    const self = this;
+    return {
+      async commit(): Promise<void> {
+        await driverTx.commit();
+      },
+      async rollback(): Promise<void> {
+        await driverTx.rollback();
+      },
+      execute<Row>(
+        plan: (SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>) & { readonly _row?: Row },
+        options?: RuntimeExecuteOptions,
+      ): AsyncIterableResult<Row> {
+        return self.executeAgainstQueryable<Row>(plan, driverTx, options);
+      },
+    };
+  }
+
   telemetry(): RuntimeTelemetryEvent | null {
-    return this.core.telemetry();
+    return this._telemetry;
+  }
+
+  async close(): Promise<void> {
+    await this.driver.close();
+  }
+
+  private ensureCodecRegistryValidated(): void {
+    if (!this.codecRegistryValidated) {
+      validateCodecRegistryCompleteness(this.codecDescriptors, this.contract);
+      this.codecRegistryValidated = true;
+    }
+  }
+
+  private async verifyMarker(): Promise<void> {
+    if (this.verify.mode === 'always') {
+      this.verified = false;
+    }
+
+    if (this.verified) {
+      return;
+    }
+
+    const readStatement = this.familyAdapter.markerReader.readMarkerStatement();
+    const result = await this.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 = this.familyAdapter.markerReader.parseMarkerRow(result.rows[0]);
+
+    const contract = this.contract as {
+      storage: { storageHash: string };
+      execution?: { executionHash?: string | null };
+      profileHash?: string | null;
+    };
+
+    if (marker.storageHash !== contract.storage.storageHash) {
+      throw runtimeError(
+        'CONTRACT.MARKER_MISMATCH',
+        'Database storage hash does not match contract',
+        {
+          expected: contract.storage.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;
   }
 
-  close(): Promise<void> {
-    return this.core.close();
+  private recordTelemetry(
+    plan: SqlExecutionPlan,
+    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 } : {}),
+    });
   }
 }
 
@@ -274,13 +508,14 @@ export async function withTransaction<R>(
     get invalidated() {
       return invalidated;
     },
-    execute<Row = Record<string, unknown>>(
-      plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+    execute<Row>(
+      plan: (SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>) & { readonly _row?: Row },
+      options?: RuntimeExecuteOptions,
     ): AsyncIterableResult<Row> {
       if (invalidated) {
         throw transactionClosedError();
       }
-      const inner = transaction.execute(plan);
+      const inner = transaction.execute(plan, options);
       const guarded = async function* (): AsyncGenerator<Row, void, unknown> {
         for await (const row of inner) {
           if (invalidated) {