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

package/src/sql-marker.ts

@@ -1,17 +1,38 @@
+import { APP_SPACE_ID } from '@prisma-next/framework-components/control';
 import type { MarkerStatement } from '@prisma-next/sql-relational-core/ast';
 
+export { APP_SPACE_ID };
+
 export interface SqlStatement {
   readonly sql: string;
   readonly params: readonly unknown[];
 }
 
 export interface WriteMarkerInput {
+  /**
+   * Logical space identifier for this marker row. Required at every
+   * call site so the type system surfaces every place that needs to
+   * thread the value (rather than letting an `?? APP_SPACE_ID`
+   * fall-through silently collapse multi-space markers onto the
+   * `'app'` row). App-plan callers pass {@link APP_SPACE_ID}
+   * (`'app'`); per-extension callers pass the extension's space id.
+   */
+  readonly space: string;
   readonly storageHash: string;
   readonly profileHash: string;
   readonly contractJson?: unknown;
   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 = {
@@ -19,21 +40,33 @@ export const ensureSchemaStatement: SqlStatement = {
   params: [],
 };
 
+/**
+ * Schema for `prisma_contract.marker`. The `space text` primary key
+ * supports one row per loaded contract space (`'app'`,
+ * `'<extension-id>'`, …); brand-new databases create this shape
+ * directly. Pre-1.0 single-row markers (no `space` column) are not
+ * auto-migrated — the target-specific migration runner detects the
+ * legacy shape at boot and surfaces a structured `LEGACY_MARKER_SHAPE`
+ * failure pointing the operator at re-running `dbInit`.
+ *
+ * @see specs/framework-mechanism.spec.md § 2.
+ */
 export const ensureTableStatement: SqlStatement = {
   sql: `create table if not exists prisma_contract.marker (
-    id smallint primary key default 1,
+    space text not null primary key default '${APP_SPACE_ID}',
     core_hash text not null,
     profile_hash text not null,
     contract_json jsonb,
     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: [],
 };
 
-export function readContractMarker(): MarkerStatement {
+export function readContractMarker(space: string): MarkerStatement {
   return {
     sql: `select
       core_hash,
@@ -42,10 +75,11 @@ export function readContractMarker(): MarkerStatement {
       canonical_version,
       updated_at,
       app_tag,
-      meta
+      meta,
+      invariants
     from prisma_contract.marker
-    where id = $1`,
-    params: [1],
+    where space = $1`,
+    params: [space],
   };
 }
 
@@ -54,52 +88,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 `space = $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 `space`; 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[] = [input.space, ...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 = ['space', ...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 space = $1`,
+      params,
+    },
+  };
 }

package/src/sql-runtime.ts

@@ -5,8 +5,10 @@ import type {
 } from '@prisma-next/framework-components/execution';
 import {
   AsyncIterableResult,
+  checkAborted,
   checkMiddlewareCompatibility,
   RuntimeCore,
+  type RuntimeExecuteOptions,
   type RuntimeLog,
   runtimeError,
   runWithMiddleware,
@@ -15,22 +17,29 @@ 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 { validateParamRefRefs } from '@prisma-next/sql-relational-core/ast';
+import {
+  createSqlParamRefMutator,
+  type SqlParamRefMutator,
+  type SqlParamRefMutatorInternal,
+} from '@prisma-next/sql-relational-core/middleware';
 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 { CodecDescriptorRegistry } 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 { computeSqlContentHash } from './content-hash';
 import { computeSqlFingerprint } from './fingerprint';
 import { lowerSqlPlan } from './lower-sql-plan';
-import { parseContractMarkerRow } from './marker';
 import { runBeforeCompileChain } from './middleware/before-compile-chain';
 import type { SqlMiddleware, SqlMiddlewareContext } from './middleware/sql-middleware';
 import type {
@@ -86,25 +95,15 @@ export interface Runtime extends RuntimeQueryable {
 export interface RuntimeConnection extends RuntimeQueryable {
   transaction(): Promise<RuntimeTransaction>;
   /**
-   * Returns the connection to the pool for reuse. Only call this when the
-   * connection is known to be in a clean state. If a transaction
-   * commit/rollback failed or the connection is otherwise suspect, call
-   * `destroy(reason)` instead.
+   * Returns the connection to the pool for reuse. Only call this when the connection is known to be in a clean state. If a transaction commit/rollback failed or the connection is otherwise suspect, call `destroy(reason)` instead.
    */
   release(): Promise<void>;
   /**
-   * Evicts the connection so it is never reused. Call this when the
-   * connection may be in an indeterminate state (e.g. a failed rollback
-   * leaving an open transaction, or a broken socket).
+   * Evicts the connection so it is never reused. Call this when the connection may be in an indeterminate state (e.g. a failed rollback leaving an open transaction, or a broken socket).
    *
-   * If teardown fails the error is propagated and the connection remains
-   * retryable, so the caller can decide whether to swallow the failure or
-   * retry cleanup. Calling destroy() or release() more than once after a
-   * successful teardown is caller error.
+   * If teardown fails the error is propagated and the connection remains retryable, so the caller can decide whether to swallow the failure or retry cleanup. Calling destroy() or release() more than once after a successful teardown is caller error.
    *
-   * `reason` is advisory context only. It may be surfaced to driver-level
-   * observability hooks (e.g. pg-pool's `'release'` event) but does not
-   * influence eviction behavior and is not rethrown.
+   * `reason` is advisory context only. It may be surfaced to driver-level observability hooks (e.g. pg-pool's `'release'` event) but does not influence eviction behavior and is not rethrown.
    */
   destroy(reason?: unknown): Promise<void>;
 }
@@ -126,6 +125,10 @@ function isExecutionPlan(plan: SqlExecutionPlan | SqlQueryPlan): plan is SqlExec
   return 'sql' in plan;
 }
 
+// v8 ignore next 2
+const noopLogSink = (): void => {};
+const noopLog: Log = { info: noopLogSink, warn: noopLogSink, error: noopLogSink };
+
 class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorage>>
   extends RuntimeCore<SqlQueryPlan, SqlExecutionPlan, SqlMiddleware>
   implements Runtime
@@ -134,8 +137,8 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
   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 contractCodecs: ContractCodecRegistry;
+  private readonly codecDescriptors: CodecDescriptorRegistry;
   private readonly sqlCtx: SqlMiddlewareContext;
   private readonly verify: RuntimeVerifyOptions;
   private codecRegistryValidated: boolean;
@@ -156,11 +159,9 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
       contract: context.contract,
       mode: mode ?? 'strict',
       now: () => Date.now(),
-      log: log ?? {
-        info: () => {},
-        warn: () => {},
-        error: () => {},
-      },
+      log: log ?? noopLog,
+      // ctx is only invoked by runWithMiddleware with execs this runtime lowered; the framework parameter type is the cross-family base.
+      contentHash: (exec) => computeSqlContentHash(exec as SqlExecutionPlan),
     };
 
     super({ middleware: middleware ?? [], ctx: sqlCtx });
@@ -169,8 +170,8 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
     this.adapter = adapter;
     this.driver = driver;
     this.familyAdapter = new SqlFamilyAdapter(context.contract, adapter.profile);
-    this.codecRegistry = context.codecs;
-    this.jsonSchemaValidators = context.jsonSchemaValidators;
+    this.contractCodecs = context.contractCodecs;
+    this.codecDescriptors = context.codecDescriptors;
     this.sqlCtx = sqlCtx;
     this.verify = verify;
     this.codecRegistryValidated = false;
@@ -179,30 +180,32 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
     this._telemetry = null;
 
     if (verify.mode === 'startup') {
-      validateCodecRegistryCompleteness(this.codecRegistry, context.contract);
+      validateCodecRegistryCompleteness(this.codecDescriptors, context.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.
+   * 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): Promise<SqlExecutionPlan> {
+  protected override async lower(
+    plan: SqlQueryPlan,
+    ctx: SqlCodecCallContext,
+  ): Promise<SqlExecutionPlan> {
+    validateParamRefRefs(plan.ast, this.codecDescriptors);
     const lowered = lowerSqlPlan(this.adapter, this.contract, plan);
     return Object.freeze({
       ...lowered,
-      params: await encodeParams(lowered, this.codecRegistry),
+      params: await encodeParams(lowered, ctx, this.contractCodecs),
     });
   }
 
   /**
-   * 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.
+   * Default driver invocation required by the abstract `RuntimeCore` contract. Every production path overrides `execute()` and routes through `executeAgainstQueryable`, so this hook is defensive only — subclasses that delegate back to `super.execute()` would land here.
    */
+  // v8 ignore next 6
   protected override runDriver(exec: SqlExecutionPlan): AsyncIterable<Record<string, unknown>> {
     return this.driver.execute<Record<string, unknown>>({
       sql: exec.sql,
@@ -211,11 +214,8 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
   }
 
   /**
-   * 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.
+   * 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(
@@ -230,24 +230,43 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
 
   override execute<Row>(
     plan: (SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>) & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
   ): AsyncIterableResult<Row> {
-    return this.executeAgainstQueryable<Row>(plan, this.driver);
+    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 };
+    // Per-execute view of the middleware ctx that carries the per-query
+    // signal. `self.ctx` is allocated once at construction (no signal); we
+    // shallow-clone it here so middleware sees the same `AbortSignal`
+    // reference threaded into `codecCtx.signal` (ADR 207 identity).
+    const execMiddlewareCtx = signal === undefined ? self.ctx : { ...self.ctx, signal };
+
     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));
+      checkAborted(codecCtx, 'stream');
+
+      let exec: SqlExecutionPlan;
+      if (isExecutionPlan(plan)) {
+        if (plan.ast) {
+          validateParamRefRefs(plan.ast, self.codecDescriptors);
+        }
+        exec = Object.freeze({
+          ...plan,
+          params: await encodeParams(plan, codecCtx, self.contractCodecs),
+        });
+      } else {
+        exec = await self.lower(await self.runBeforeCompile(plan), codecCtx);
+      }
 
       self.familyAdapter.validatePlan(exec, self.contract);
       self._telemetry = null;
@@ -268,25 +287,42 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
           await self.verifyMarker();
         }
 
-        const stream = runWithMiddleware<SqlExecutionPlan, Record<string, unknown>>(
+        const paramsMutator: SqlParamRefMutatorInternal = createSqlParamRefMutator(exec);
+        const stream = runWithMiddleware<
+          SqlExecutionPlan,
+          Record<string, unknown>,
+          SqlParamRefMutator
+        >(
           exec,
           self.middleware,
-          self.ctx,
+          execMiddlewareCtx,
           () =>
             queryable.execute<Record<string, unknown>>({
               sql: exec.sql,
-              params: exec.params,
+              // Read params after the `beforeExecute` middleware chain has
+              // run so that any `mutator.replaceValue(...)` calls land in
+              // the driver-bound params array. When no middleware mutated,
+              // `currentParams()` returns `exec.params` by reference identity.
+              params: paramsMutator.currentParams(),
             }),
+          paramsMutator,
         );
 
-        for await (const rawRow of stream) {
-          const decodedRow = await decodeRow(
-            rawRow,
-            exec,
-            self.codecRegistry,
-            self.jsonSchemaValidators,
-          );
-          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, 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';
@@ -320,8 +356,9 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
       },
       execute<Row>(
         plan: (SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>) & { readonly _row?: Row },
+        options?: RuntimeExecuteOptions,
       ): AsyncIterableResult<Row> {
-        return self.executeAgainstQueryable<Row>(plan, driverConn);
+        return self.executeAgainstQueryable<Row>(plan, driverConn, options);
       },
     };
 
@@ -339,8 +376,9 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
       },
       execute<Row>(
         plan: (SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>) & { readonly _row?: Row },
+        options?: RuntimeExecuteOptions,
       ): AsyncIterableResult<Row> {
-        return self.executeAgainstQueryable<Row>(plan, driverTx);
+        return self.executeAgainstQueryable<Row>(plan, driverTx, options);
       },
     };
   }
@@ -355,24 +393,15 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
 
   private ensureCodecRegistryValidated(): void {
     if (!this.codecRegistryValidated) {
-      validateCodecRegistryCompleteness(this.codecRegistry, this.contract);
+      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);
+    const readResult = await this.familyAdapter.markerReader.readMarker(this.driver);
 
-    if (result.rows.length === 0) {
+    if (readResult.kind !== 'present') {
       if (this.verify.requireMarker) {
         throw runtimeError('CONTRACT.MARKER_MISSING', 'Contract marker not found in database');
       }
@@ -381,7 +410,7 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
       return;
     }
 
-    const marker = parseContractMarkerRow(result.rows[0]);
+    const marker = readResult.record;
 
     const contract = this.contract as {
       storage: { storageHash: string };
@@ -454,11 +483,12 @@ export async function withTransaction<R>(
     },
     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) {
@@ -475,11 +505,7 @@ export async function withTransaction<R>(
   const destroyConnection = async (reason: unknown): Promise<void> => {
     if (connectionDisposed) return;
     connectionDisposed = true;
-    // SqlConnection.destroy() propagates teardown errors so callers can
-    // decide what to do with them. Here, we're already about to throw a
-    // more informative error describing why we're evicting the connection
-    // (rollback/commit failure), so swallowing the teardown error is the
-    // right call — surfacing it would mask the original cause.
+    // SqlConnection.destroy() propagates teardown errors so callers can decide what to do with them. Here, we're already about to throw a more informative error describing why we're evicting the connection (rollback/commit failure), so swallowing the teardown error is the right call — surfacing it would mask the original cause.
     await connection.destroy(reason).catch(() => undefined);
   };
 
@@ -508,17 +534,9 @@ export async function withTransaction<R>(
     try {
       await transaction.commit();
     } catch (commitError) {
-      // After a failed COMMIT the server-side transaction may be: (a) already
-      // committed (error on response path), (b) already rolled back (deferred
-      // constraint / serialization failure), or (c) still open (COMMIT never
-      // reached the server). Attempt a best-effort rollback to cover (c) and
-      // confirm the protocol is healthy.
+      // After a failed COMMIT the server-side transaction may be: (a) already committed (error on response path), (b) already rolled back (deferred constraint / serialization failure), or (c) still open (COMMIT never reached the server). Attempt a best-effort rollback to cover (c) and confirm the protocol is healthy.
       //
-      // If rollback succeeds, the server is definitely no longer in a
-      // transaction (no-op in (a)/(b), real cleanup in (c)) and we've just
-      // proved the connection round-trips correctly — it's safe to return
-      // to the pool. If rollback fails, the connection state is ambiguous
-      // (broken socket, protocol desync, etc.) and we must destroy it.
+      // If rollback succeeds, the server is definitely no longer in a transaction (no-op in (a)/(b), real cleanup in (c)) and we've just proved the connection round-trips correctly — it's safe to return to the pool. If rollback fails, the connection state is ambiguous (broken socket, protocol desync, etc.) and we must destroy it.
       try {
         await transaction.rollback();
       } catch {