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

package/src/sql-runtime.ts

@@ -1,22 +1,16 @@
-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,
-  RuntimeCore,
-  RuntimeCoreOptions,
-  RuntimeTelemetryEvent,
-  RuntimeVerifyOptions,
-  TelemetryOutcome,
-} from '@prisma-next/runtime-executor';
 import {
   AsyncIterableResult,
-  createRuntimeCore,
+  checkMiddlewareCompatibility,
+  RuntimeCore,
+  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,
@@ -24,16 +18,27 @@ import type {
   CodecRegistry,
   LoweredStatement,
   SqlDriver,
+  SqlQueryable,
+  SqlTransaction,
 } 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';
 import type { 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 { parseContractMarkerRow } from './marker';
 import { runBeforeCompileChain } from './middleware/before-compile-chain';
-import type { SqlMiddleware } from './middleware/sql-middleware';
+import type { SqlMiddleware, SqlMiddlewareContext } from './middleware/sql-middleware';
+import type {
+  RuntimeFamilyAdapter,
+  RuntimeTelemetryEvent,
+  RuntimeVerifyOptions,
+  TelemetryOutcome,
+} from './runtime-spi';
 import type {
   ExecutionContext,
   SqlRuntimeAdapterInstance,
@@ -41,6 +46,8 @@ 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>;
@@ -107,39 +114,37 @@ 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>, SqlMiddleware>;
   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 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) {
@@ -147,18 +152,31 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
       }
     }
 
-    const familyAdapter = new SqlFamilyAdapter(context.contract, adapter.profile);
-
-    const coreOptions: RuntimeCoreOptions<TContract, SqlDriver<unknown>, SqlMiddleware> = {
-      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.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);
@@ -166,109 +184,251 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
     }
   }
 
-  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.
+   */
+  protected override async lower(plan: SqlQueryPlan): Promise<SqlExecutionPlan> {
+    const lowered = lowerSqlPlan(this.adapter, this.contract, plan);
+    return Object.freeze({
+      ...lowered,
+      params: await encodeParams(lowered, this.codecRegistry),
+    });
   }
 
-  private async toExecutionPlan<Row>(
-    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
-  ): Promise<ExecutionPlan<Row>> {
-    const isSqlQueryPlan = (p: ExecutionPlan<Row> | SqlQueryPlan<Row>): p is SqlQueryPlan<Row> => {
-      return 'ast' in p && !('sql' in p);
-    };
-
-    if (!isSqlQueryPlan(plan)) {
-      return plan;
-    }
+  /**
+   * 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,
+    });
+  }
 
+  /**
+   * SQL pre-compile hook. Runs the registered middleware `beforeCompile`
+   * chain over the plan's draft (AST + meta) and returns a `SqlQueryPlan`
+   * with the rewritten AST and meta when the chain mutates them. The chain
+   * re-derives `meta.paramDescriptors` from the rewritten AST so descriptors
+   * stay in lockstep with the params the adapter will emit during lowering.
+   */
+  protected override async runBeforeCompile(plan: SqlQueryPlan): Promise<SqlQueryPlan> {
     const rewrittenDraft = await runBeforeCompileChain(
-      this.core.middleware,
+      this.middleware,
       { ast: plan.ast, meta: plan.meta },
-      this.core.middlewareContext,
+      this.sqlCtx,
     );
+    return rewrittenDraft.ast === plan.ast
+      ? plan
+      : { ...plan, ast: rewrittenDraft.ast, meta: rewrittenDraft.meta };
+  }
 
-    const planToLower: SqlQueryPlan<Row> =
-      rewrittenDraft.ast === plan.ast
-        ? plan
-        : { ...plan, ast: rewrittenDraft.ast, meta: rewrittenDraft.meta };
-
-    return lowerSqlPlan(this.adapter, this.contract, planToLower);
+  override execute<Row>(
+    plan: (SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>) & { readonly _row?: Row },
+  ): AsyncIterableResult<Row> {
+    return this.executeAgainstQueryable<Row>(plan, this.driver);
   }
 
-  private executeAgainstQueryable<Row = Record<string, unknown>>(
-    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
-    queryable: CoreQueryable,
+  private executeAgainstQueryable<Row>(
+    plan: SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>,
+    queryable: SqlQueryable,
   ): AsyncIterableResult<Row> {
-    this.ensureCodecRegistryValidated(this.contract);
-
-    const iterator = async function* (
-      self: SqlRuntimeImpl<TContract>,
-    ): AsyncGenerator<Row, void, unknown> {
-      const executablePlan = await self.toExecutionPlan(plan);
-      const encodedParams = await encodeParams(executablePlan, self.codecRegistry);
-      const planWithEncodedParams: ExecutionPlan<Row> = {
-        ...executablePlan,
-        params: encodedParams,
-      };
+    this.ensureCodecRegistryValidated();
+
+    const self = this;
+    const generator = async function* (): AsyncGenerator<Row, void, unknown> {
+      const exec: SqlExecutionPlan = isExecutionPlan(plan)
+        ? Object.freeze({
+            ...plan,
+            params: await encodeParams(plan, self.codecRegistry),
+          })
+        : await self.lower(await self.runBeforeCompile(plan));
+
+      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 startedAt = Date.now();
+      let outcome: TelemetryOutcome | null = null;
 
-      const coreIterator = queryable.execute(planWithEncodedParams);
+      try {
+        if (self.verify.mode === 'always') {
+          await self.verifyMarker();
+        }
 
-      for await (const rawRow of coreIterator) {
-        const decodedRow = await decodeRow(
-          rawRow as Record<string, unknown>,
-          executablePlan,
-          self.codecRegistry,
-          self.jsonSchemaValidators,
+        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;
+
+        for await (const rawRow of stream) {
+          const decodedRow = await decodeRow(
+            rawRow,
+            exec,
+            self.codecRegistry,
+            self.jsonSchemaValidators,
+          );
+          yield decodedRow as Row;
+        }
+
+        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 },
       ): AsyncIterableResult<Row> {
-        return self.executeAgainstQueryable(plan, coreConn);
+        return self.executeAgainstQueryable<Row>(plan, driverConn);
       },
     };
+
     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 },
+      ): AsyncIterableResult<Row> {
+        return self.executeAgainstQueryable<Row>(plan, driverTx);
+      },
+    };
+  }
+
   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.codecRegistry, 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 = parseContractMarkerRow(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 } : {}),
+    });
   }
 }
 
@@ -292,8 +452,8 @@ 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 },
     ): AsyncIterableResult<Row> {
       if (invalidated) {
         throw transactionClosedError();