@prisma-next/sql-runtime 0.5.0-dev.2 → 0.5.0-dev.21

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,
+    },
+  };
 }

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,26 @@ 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 { 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 +45,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 +113,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 +151,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,107 +183,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 };
-
-    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 = 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 = 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 = 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 } : {}),
+    });
   }
 }
 
@@ -290,8 +451,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();