@prisma-next/sql-runtime 0.4.0-dev.9 → 0.4.2

package/dist/test/utils.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"utils.mjs","names":["collectAsync"],"sources":["../../test/utils.ts"],"sourcesContent":["import type { Contract, ExecutionPlan, ResultType } from '@prisma-next/contract/types';\nimport { coreHash, profileHash } from '@prisma-next/contract/types';\nimport {\n  instantiateExecutionStack,\n  type RuntimeDriverDescriptor,\n} from '@prisma-next/framework-components/execution';\nimport { builtinGeneratorIds } from '@prisma-next/ids';\nimport { generateId } from '@prisma-next/ids/runtime';\nimport type { SqlStorage } from '@prisma-next/sql-contract/types';\nimport type { Adapter, LoweredStatement, SelectAst } from '@prisma-next/sql-relational-core/ast';\nimport { codec, createCodecRegistry } from '@prisma-next/sql-relational-core/ast';\nimport type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';\nimport { collectAsync, drainAsyncIterable } from '@prisma-next/test-utils';\nimport type { Client } from 'pg';\nimport type { SqlStatement } from '../src/exports';\nimport {\n  createExecutionContext,\n  type createRuntime,\n  createSqlExecutionStack,\n  ensureSchemaStatement,\n  ensureTableStatement,\n  writeContractMarker,\n} from '../src/exports';\nimport type {\n  ExecutionContext,\n  SqlRuntimeAdapterDescriptor,\n  SqlRuntimeAdapterInstance,\n  SqlRuntimeDriverInstance,\n  SqlRuntimeExtensionDescriptor,\n  SqlRuntimeTargetDescriptor,\n} from '../src/sql-context';\n\nfunction createTestMutationDefaultGenerators() {\n  return builtinGeneratorIds.map((id) => ({\n    id,\n    generate: (params?: Record<string, unknown>) => generateId(params ? { id, params } : { id }),\n  }));\n}\n\n/**\n * Executes a plan and collects all results into an array.\n * This helper DRYs up the common pattern of executing plans in tests.\n * The return type is inferred from the plan's type parameter.\n */\nexport async function executePlanAndCollect<\n  P extends ExecutionPlan<ResultType<P>> | SqlQueryPlan<ResultType<P>>,\n>(runtime: ReturnType<typeof createRuntime>, plan: P): Promise<ResultType<P>[]> {\n  type Row = ResultType<P>;\n  return collectAsync<Row>(runtime.execute<Row>(plan));\n}\n\n/**\n * Drains a plan execution, consuming all results without collecting them.\n * Useful for testing side effects without memory overhead.\n */\nexport async function drainPlanExecution(\n  runtime: ReturnType<typeof createRuntime>,\n  plan: ExecutionPlan | SqlQueryPlan<unknown>,\n): Promise<void> {\n  return drainAsyncIterable(runtime.execute(plan));\n}\n\n/**\n * Executes a SQL statement on a database client.\n */\nexport async function executeStatement(client: Client, statement: SqlStatement): Promise<void> {\n  if (statement.params.length > 0) {\n    await client.query(statement.sql, [...statement.params]);\n    return;\n  }\n\n  await client.query(statement.sql);\n}\n\n/**\n * Sets up database schema and data, then writes the contract marker.\n * This helper DRYs up the common pattern of database setup in tests.\n */\nexport async function setupTestDatabase(\n  client: Client,\n  contract: Contract<SqlStorage>,\n  setupFn: (client: Client) => Promise<void>,\n): Promise<void> {\n  await client.query('drop schema if exists prisma_contract cascade');\n  await client.query('create schema if not exists public');\n\n  await setupFn(client);\n\n  await executeStatement(client, ensureSchemaStatement);\n  await executeStatement(client, ensureTableStatement);\n  const write = writeContractMarker({\n    storageHash: contract.storage.storageHash,\n    profileHash: contract.profileHash,\n    contractJson: contract,\n    canonicalVersion: 1,\n  });\n  await executeStatement(client, write.insert);\n}\n\n/**\n * Writes a contract marker to the database.\n * This helper DRYs up the common pattern of writing contract markers in tests.\n */\nexport async function writeTestContractMarker(\n  client: Client,\n  contract: Contract<SqlStorage>,\n): Promise<void> {\n  const write = writeContractMarker({\n    storageHash: contract.storage.storageHash,\n    profileHash: contract.profileHash,\n    contractJson: contract,\n    canonicalVersion: 1,\n  });\n  await executeStatement(client, write.insert);\n}\n\n/**\n * Creates a test adapter descriptor from a raw adapter.\n * Wraps the adapter in an SqlRuntimeAdapterDescriptor with static contributions\n * derived from the adapter's codec registry.\n */\nexport function createTestAdapterDescriptor(\n  adapter: Adapter<SelectAst, Contract<SqlStorage>, LoweredStatement>,\n): SqlRuntimeAdapterDescriptor<'postgres'> {\n  const codecRegistry = adapter.profile.codecs();\n  return {\n    kind: 'adapter' as const,\n    id: 'test-adapter',\n    version: '0.0.1',\n    familyId: 'sql' as const,\n    targetId: 'postgres' as const,\n    codecs: () => codecRegistry,\n    parameterizedCodecs: () => [],\n    mutationDefaultGenerators: createTestMutationDefaultGenerators,\n    create(): SqlRuntimeAdapterInstance<'postgres'> {\n      return Object.assign({ familyId: 'sql' as const, targetId: 'postgres' as const }, adapter);\n    },\n  };\n}\n\n/**\n * Creates a test target descriptor with empty static contributions.\n */\nexport function createTestTargetDescriptor(): SqlRuntimeTargetDescriptor<'postgres'> {\n  return {\n    kind: 'target' as const,\n    id: 'postgres',\n    version: '0.0.1',\n    familyId: 'sql' as const,\n    targetId: 'postgres' as const,\n    codecs: () => createCodecRegistry(),\n    parameterizedCodecs: () => [],\n    create() {\n      return { familyId: 'sql' as const, targetId: 'postgres' as const };\n    },\n  };\n}\n\n/**\n * Creates an ExecutionContext for testing.\n * This helper DRYs up the common pattern of context creation in tests.\n *\n * Accepts a raw adapter and optional extension descriptors, wrapping the\n * adapter in a descriptor internally for descriptor-first context creation.\n */\nexport function createTestContext<TContract extends Contract<SqlStorage>>(\n  contract: TContract,\n  adapter: Adapter<SelectAst, Contract<SqlStorage>, LoweredStatement>,\n  options?: {\n    extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<'postgres'>>;\n  },\n): ExecutionContext<TContract> {\n  return createExecutionContext({\n    contract,\n    stack: {\n      target: createTestTargetDescriptor(),\n      adapter: createTestAdapterDescriptor(adapter),\n      extensionPacks: options?.extensionPacks ?? [],\n    },\n  });\n}\n\nexport function createTestStackInstance(options?: {\n  extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<'postgres'>>;\n  driver?: RuntimeDriverDescriptor<\n    'sql',\n    'postgres',\n    unknown,\n    SqlRuntimeDriverInstance<'postgres'>\n  >;\n}) {\n  const stack = createSqlExecutionStack({\n    target: createTestTargetDescriptor(),\n    adapter: createTestAdapterDescriptor(createStubAdapter()),\n    driver: options?.driver,\n    extensionPacks: options?.extensionPacks ?? [],\n  });\n\n  return instantiateExecutionStack(stack);\n}\n\n/**\n * Creates a stub adapter for testing.\n * This helper DRYs up the common pattern of adapter creation in tests.\n *\n * The stub adapter includes simple codecs for common test types (pg/int4@1, pg/text@1, pg/timestamptz@1)\n * to enable type inference in tests without requiring the postgres adapter package.\n */\nexport function createStubAdapter(): Adapter<SelectAst, Contract<SqlStorage>, LoweredStatement> {\n  const codecRegistry = createCodecRegistry();\n\n  // Register stub codecs for common test types\n  // These match the codec IDs used in test contracts (pg/int4@1, pg/text@1, pg/timestamptz@1)\n  // but don't require importing from the postgres adapter package\n  codecRegistry.register(\n    codec({\n      typeId: 'pg/int4@1',\n      targetTypes: ['int4'],\n      encode: (value: number) => value,\n      decode: (wire: number) => wire,\n    }),\n  );\n\n  codecRegistry.register(\n    codec({\n      typeId: 'pg/text@1',\n      targetTypes: ['text'],\n      encode: (value: string) => value,\n      decode: (wire: string) => wire,\n    }),\n  );\n\n  codecRegistry.register(\n    codec({\n      typeId: 'pg/timestamptz@1',\n      targetTypes: ['timestamptz'],\n      encode: (value: string | Date) => (value instanceof Date ? value.toISOString() : value),\n      decode: (wire: string | Date) => (wire instanceof Date ? wire : new Date(wire)),\n    }),\n  );\n\n  return {\n    profile: {\n      id: 'stub-profile',\n      target: 'postgres',\n      capabilities: {},\n      codecs() {\n        return codecRegistry;\n      },\n      readMarkerStatement() {\n        return {\n          sql: 'select core_hash, profile_hash, contract_json, canonical_version, updated_at, app_tag, meta from prisma_contract.marker where id = $1',\n          params: [1],\n        };\n      },\n    },\n    lower(ast: SelectAst, ctx: { contract: Contract<SqlStorage>; params?: readonly unknown[] }) {\n      const sqlText = JSON.stringify(ast);\n      return {\n        profileId: this.profile.id,\n        body: Object.freeze({ sql: sqlText, params: ctx.params ? [...ctx.params] : [] }),\n      };\n    },\n  };\n}\n\nexport function createTestContract(\n  contract: Partial<Omit<Contract<SqlStorage>, 'profileHash' | 'storage'>> & {\n    storageHash?: string;\n    profileHash?: string;\n    storage?: Omit<SqlStorage, 'storageHash'>;\n  },\n): Contract<SqlStorage> {\n  const { execution, ...rest } = contract;\n  const storageHashValue = coreHash(rest['storageHash'] ?? 'sha256:testcore');\n\n  return {\n    target: rest['target'] ?? 'postgres',\n    targetFamily: rest['targetFamily'] ?? 'sql',\n    storage: rest['storage']\n      ? { ...rest['storage'], storageHash: storageHashValue }\n      : { storageHash: storageHashValue, tables: {} },\n    models: rest['models'] ?? {},\n    roots: rest['roots'] ?? {},\n    capabilities: rest['capabilities'] ?? {},\n    extensionPacks: rest['extensionPacks'] ?? {},\n    meta: rest['meta'] ?? {},\n    ...(execution ? { execution } : {}),\n    profileHash: profileHash(rest['profileHash'] ?? 'sha256:testprofile'),\n  };\n}\n\n// Re-export generic utilities from test-utils\nexport {\n  collectAsync,\n  createDevDatabase,\n  type DevDatabase,\n  teardownTestDatabase,\n  withClient,\n} from '@prisma-next/test-utils';\n"],"mappings":"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"}
+{"version":3,"file":"utils.mjs","names":["collectAsync"],"sources":["../../test/utils.ts"],"sourcesContent":["import type { Contract, ExecutionPlan, ResultType } from '@prisma-next/contract/types';\nimport { coreHash, profileHash } from '@prisma-next/contract/types';\nimport {\n  instantiateExecutionStack,\n  type RuntimeDriverDescriptor,\n} from '@prisma-next/framework-components/execution';\nimport { builtinGeneratorIds } from '@prisma-next/ids';\nimport { generateId } from '@prisma-next/ids/runtime';\nimport type { SqlStorage } from '@prisma-next/sql-contract/types';\nimport type { Adapter, LoweredStatement, SelectAst } from '@prisma-next/sql-relational-core/ast';\nimport { codec, createCodecRegistry } from '@prisma-next/sql-relational-core/ast';\nimport type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';\nimport { collectAsync, drainAsyncIterable } from '@prisma-next/test-utils';\nimport type { Client } from 'pg';\nimport type { SqlStatement } from '../src/exports';\nimport {\n  createExecutionContext,\n  type createRuntime,\n  createSqlExecutionStack,\n  ensureSchemaStatement,\n  ensureTableStatement,\n  writeContractMarker,\n} from '../src/exports';\nimport type {\n  ExecutionContext,\n  SqlRuntimeAdapterDescriptor,\n  SqlRuntimeAdapterInstance,\n  SqlRuntimeDriverInstance,\n  SqlRuntimeExtensionDescriptor,\n  SqlRuntimeTargetDescriptor,\n} from '../src/sql-context';\n\nfunction createTestMutationDefaultGenerators() {\n  return builtinGeneratorIds.map((id) => ({\n    id,\n    generate: (params?: Record<string, unknown>) => generateId(params ? { id, params } : { id }),\n  }));\n}\n\n/**\n * Executes a plan and collects all results into an array.\n * This helper DRYs up the common pattern of executing plans in tests.\n * The return type is inferred from the plan's type parameter.\n */\nexport async function executePlanAndCollect<\n  P extends ExecutionPlan<ResultType<P>> | SqlQueryPlan<ResultType<P>>,\n>(runtime: ReturnType<typeof createRuntime>, plan: P): Promise<ResultType<P>[]> {\n  type Row = ResultType<P>;\n  return collectAsync<Row>(runtime.execute<Row>(plan));\n}\n\n/**\n * Drains a plan execution, consuming all results without collecting them.\n * Useful for testing side effects without memory overhead.\n */\nexport async function drainPlanExecution(\n  runtime: ReturnType<typeof createRuntime>,\n  plan: ExecutionPlan | SqlQueryPlan<unknown>,\n): Promise<void> {\n  return drainAsyncIterable(runtime.execute(plan));\n}\n\n/**\n * Executes a SQL statement on a database client.\n */\nexport async function executeStatement(client: Client, statement: SqlStatement): Promise<void> {\n  if (statement.params.length > 0) {\n    await client.query(statement.sql, [...statement.params]);\n    return;\n  }\n\n  await client.query(statement.sql);\n}\n\n/**\n * Sets up database schema and data, then writes the contract marker.\n * This helper DRYs up the common pattern of database setup in tests.\n */\nexport async function setupTestDatabase(\n  client: Client,\n  contract: Contract<SqlStorage>,\n  setupFn: (client: Client) => Promise<void>,\n): Promise<void> {\n  await client.query('drop schema if exists prisma_contract cascade');\n  await client.query('create schema if not exists public');\n\n  await setupFn(client);\n\n  await executeStatement(client, ensureSchemaStatement);\n  await executeStatement(client, ensureTableStatement);\n  const write = writeContractMarker({\n    storageHash: contract.storage.storageHash,\n    profileHash: contract.profileHash,\n    contractJson: contract,\n    canonicalVersion: 1,\n  });\n  await executeStatement(client, write.insert);\n}\n\n/**\n * Writes a contract marker to the database.\n * This helper DRYs up the common pattern of writing contract markers in tests.\n */\nexport async function writeTestContractMarker(\n  client: Client,\n  contract: Contract<SqlStorage>,\n): Promise<void> {\n  const write = writeContractMarker({\n    storageHash: contract.storage.storageHash,\n    profileHash: contract.profileHash,\n    contractJson: contract,\n    canonicalVersion: 1,\n  });\n  await executeStatement(client, write.insert);\n}\n\n/**\n * Creates a test adapter descriptor from a raw adapter.\n * Wraps the adapter in an SqlRuntimeAdapterDescriptor with static contributions\n * derived from the adapter's codec registry.\n */\nexport function createTestAdapterDescriptor(\n  adapter: Adapter<SelectAst, Contract<SqlStorage>, LoweredStatement>,\n): SqlRuntimeAdapterDescriptor<'postgres'> {\n  const codecRegistry = adapter.profile.codecs();\n  return {\n    kind: 'adapter' as const,\n    id: 'test-adapter',\n    version: '0.0.1',\n    familyId: 'sql' as const,\n    targetId: 'postgres' as const,\n    codecs: () => codecRegistry,\n    parameterizedCodecs: () => [],\n    mutationDefaultGenerators: createTestMutationDefaultGenerators,\n    create(_stack): SqlRuntimeAdapterInstance<'postgres'> {\n      return Object.assign({ familyId: 'sql' as const, targetId: 'postgres' as const }, adapter);\n    },\n  };\n}\n\n/**\n * Creates a test target descriptor with empty static contributions.\n */\nexport function createTestTargetDescriptor(): SqlRuntimeTargetDescriptor<'postgres'> {\n  return {\n    kind: 'target' as const,\n    id: 'postgres',\n    version: '0.0.1',\n    familyId: 'sql' as const,\n    targetId: 'postgres' as const,\n    codecs: () => createCodecRegistry(),\n    parameterizedCodecs: () => [],\n    create() {\n      return { familyId: 'sql' as const, targetId: 'postgres' as const };\n    },\n  };\n}\n\n/**\n * Creates an ExecutionContext for testing.\n * This helper DRYs up the common pattern of context creation in tests.\n *\n * Accepts a raw adapter and optional extension descriptors, wrapping the\n * adapter in a descriptor internally for descriptor-first context creation.\n */\nexport function createTestContext<TContract extends Contract<SqlStorage>>(\n  contract: TContract,\n  adapter: Adapter<SelectAst, Contract<SqlStorage>, LoweredStatement>,\n  options?: {\n    extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<'postgres'>>;\n  },\n): ExecutionContext<TContract> {\n  return createExecutionContext({\n    contract,\n    stack: {\n      target: createTestTargetDescriptor(),\n      adapter: createTestAdapterDescriptor(adapter),\n      extensionPacks: options?.extensionPacks ?? [],\n    },\n  });\n}\n\nexport function createTestStackInstance(options?: {\n  extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<'postgres'>>;\n  driver?: RuntimeDriverDescriptor<\n    'sql',\n    'postgres',\n    unknown,\n    SqlRuntimeDriverInstance<'postgres'>\n  >;\n}) {\n  const stack = createSqlExecutionStack({\n    target: createTestTargetDescriptor(),\n    adapter: createTestAdapterDescriptor(createStubAdapter()),\n    driver: options?.driver,\n    extensionPacks: options?.extensionPacks ?? [],\n  });\n\n  return instantiateExecutionStack(stack);\n}\n\n/**\n * Creates a stub adapter for testing.\n * This helper DRYs up the common pattern of adapter creation in tests.\n *\n * The stub adapter includes simple codecs for common test types (pg/int4@1, pg/text@1, pg/timestamptz@1)\n * to enable type inference in tests without requiring the postgres adapter package.\n */\nexport function createStubAdapter(): Adapter<SelectAst, Contract<SqlStorage>, LoweredStatement> {\n  const codecRegistry = createCodecRegistry();\n\n  // Register stub codecs for common test types\n  // These match the codec IDs used in test contracts (pg/int4@1, pg/text@1, pg/timestamptz@1)\n  // but don't require importing from the postgres adapter package\n  codecRegistry.register(\n    codec({\n      typeId: 'pg/int4@1',\n      targetTypes: ['int4'],\n      encode: (value: number) => value,\n      decode: (wire: number) => wire,\n    }),\n  );\n\n  codecRegistry.register(\n    codec({\n      typeId: 'pg/text@1',\n      targetTypes: ['text'],\n      encode: (value: string) => value,\n      decode: (wire: string) => wire,\n    }),\n  );\n\n  codecRegistry.register(\n    codec({\n      typeId: 'pg/timestamptz@1',\n      targetTypes: ['timestamptz'],\n      encode: (value: string | Date) => (value instanceof Date ? value.toISOString() : value),\n      decode: (wire: string | Date) => (wire instanceof Date ? wire : new Date(wire)),\n    }),\n  );\n\n  return {\n    profile: {\n      id: 'stub-profile',\n      target: 'postgres',\n      capabilities: {},\n      codecs() {\n        return codecRegistry;\n      },\n      readMarkerStatement() {\n        return {\n          sql: 'select core_hash, profile_hash, contract_json, canonical_version, updated_at, app_tag, meta from prisma_contract.marker where id = $1',\n          params: [1],\n        };\n      },\n    },\n    lower(ast: SelectAst, ctx: { contract: Contract<SqlStorage>; params?: readonly unknown[] }) {\n      const sqlText = JSON.stringify(ast);\n      return Object.freeze({ sql: sqlText, params: ctx.params ? [...ctx.params] : [] });\n    },\n  };\n}\n\nexport function createTestContract(\n  contract: Partial<Omit<Contract<SqlStorage>, 'profileHash' | 'storage'>> & {\n    storageHash?: string;\n    profileHash?: string;\n    storage?: Omit<SqlStorage, 'storageHash'>;\n  },\n): Contract<SqlStorage> {\n  const { execution, ...rest } = contract;\n  const storageHashValue = coreHash(rest['storageHash'] ?? 'sha256:testcore');\n\n  return {\n    target: rest['target'] ?? 'postgres',\n    targetFamily: rest['targetFamily'] ?? 'sql',\n    storage: rest['storage']\n      ? { ...rest['storage'], storageHash: storageHashValue }\n      : { storageHash: storageHashValue, tables: {} },\n    models: rest['models'] ?? {},\n    roots: rest['roots'] ?? {},\n    capabilities: rest['capabilities'] ?? {},\n    extensionPacks: rest['extensionPacks'] ?? {},\n    meta: rest['meta'] ?? {},\n    ...(execution ? { execution } : {}),\n    profileHash: profileHash(rest['profileHash'] ?? 'sha256:testprofile'),\n  };\n}\n\n// Re-export generic utilities from test-utils\nexport {\n  collectAsync,\n  createDevDatabase,\n  type DevDatabase,\n  teardownTestDatabase,\n  withClient,\n} from '@prisma-next/test-utils';\n"],"mappings":"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"}

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@prisma-next/sql-runtime",
-  "version": "0.4.0-dev.9",
+  "version": "0.4.2",
   "type": "module",
   "sideEffects": false,
   "description": "SQL runtime implementation for Prisma Next",
   "dependencies": {
     "arktype": "^2.1.26",
-    "@prisma-next/contract": "0.4.0-dev.9",
-    "@prisma-next/utils": "0.4.0-dev.9",
-    "@prisma-next/framework-components": "0.4.0-dev.9",
-    "@prisma-next/ids": "0.4.0-dev.9",
-    "@prisma-next/operations": "0.4.0-dev.9",
-    "@prisma-next/sql-operations": "0.4.0-dev.9",
-    "@prisma-next/runtime-executor": "0.4.0-dev.9",
-    "@prisma-next/sql-relational-core": "0.4.0-dev.9",
-    "@prisma-next/sql-contract": "0.4.0-dev.9"
+    "@prisma-next/contract": "0.4.2",
+    "@prisma-next/utils": "0.4.2",
+    "@prisma-next/ids": "0.4.2",
+    "@prisma-next/runtime-executor": "0.4.2",
+    "@prisma-next/operations": "0.4.2",
+    "@prisma-next/framework-components": "0.4.2",
+    "@prisma-next/sql-operations": "0.4.2",
+    "@prisma-next/sql-relational-core": "0.4.2",
+    "@prisma-next/sql-contract": "0.4.2"
   },
   "devDependencies": {
     "@types/pg": "8.16.0",
@@ -22,8 +22,8 @@
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/tsconfig": "0.0.0",
     "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsconfig": "0.0.0",
     "@prisma-next/tsdown": "0.0.0"
   },
   "files": [

package/src/exports/index.ts

@@ -44,8 +44,12 @@ export {
 export type {
   CreateRuntimeOptions,
   Runtime,
+  RuntimeConnection,
+  RuntimeQueryable,
   RuntimeTelemetryEvent,
+  RuntimeTransaction,
   RuntimeVerifyOptions,
   TelemetryOutcome,
+  TransactionContext,
 } from '../sql-runtime';
-export { createRuntime } from '../sql-runtime';
+export { createRuntime, withTransaction } from '../sql-runtime';

package/src/lower-sql-plan.ts

@@ -21,11 +21,9 @@ export function lowerSqlPlan<Row>(
     params: queryPlan.params,
   });
 
-  const body = lowered.body;
-
   return Object.freeze({
-    sql: body.sql,
-    params: body.params ?? queryPlan.params,
+    sql: lowered.sql,
+    params: lowered.params ?? queryPlan.params,
     ast: queryPlan.ast,
     meta: queryPlan.meta,
   });

package/src/middleware/before-compile-chain.ts

@@ -0,0 +1,28 @@
+import type { DraftPlan, SqlMiddleware, SqlMiddlewareContext } from './sql-middleware';
+
+export async function runBeforeCompileChain(
+  middleware: readonly SqlMiddleware[],
+  initial: DraftPlan,
+  ctx: SqlMiddlewareContext,
+): Promise<DraftPlan> {
+  let current = initial;
+  for (const mw of middleware) {
+    if (!mw.beforeCompile) {
+      continue;
+    }
+    const result = await mw.beforeCompile(current, ctx);
+    if (result === undefined) {
+      continue;
+    }
+    if (result.ast === current.ast) {
+      continue;
+    }
+    ctx.log.debug?.({
+      event: 'middleware.rewrite',
+      middleware: mw.name,
+      lane: current.meta.lane,
+    });
+    current = result;
+  }
+  return current;
+}

package/src/middleware/budgets.ts

@@ -1,11 +1,8 @@
 import type { ExecutionPlan } from '@prisma-next/contract/types';
 import { type RuntimeErrorEnvelope, runtimeError } from '@prisma-next/framework-components/runtime';
-import type {
-  AfterExecuteResult,
-  Middleware,
-  MiddlewareContext,
-} from '@prisma-next/runtime-executor';
+import type { AfterExecuteResult } from '@prisma-next/runtime-executor';
 import { isQueryAst, type SelectAst } from '@prisma-next/sql-relational-core/ast';
+import type { SqlMiddleware, SqlMiddlewareContext } from './sql-middleware';
 
 export interface BudgetsOptions {
   readonly maxRows?: number;
@@ -77,7 +74,7 @@ function hasDetectableLimitFromHeuristics(plan: ExecutionPlan): boolean {
 function emitBudgetViolation(
   error: RuntimeErrorEnvelope,
   shouldBlock: boolean,
-  ctx: MiddlewareContext<unknown>,
+  ctx: SqlMiddlewareContext,
 ): void {
   if (shouldBlock) {
     throw error;
@@ -89,7 +86,7 @@ function emitBudgetViolation(
   });
 }
 
-export function budgets<TContract = unknown>(options?: BudgetsOptions): Middleware<TContract> {
+export function budgets(options?: BudgetsOptions): SqlMiddleware {
   const maxRows = options?.maxRows ?? 10_000;
   const defaultTableRows = options?.defaultTableRows ?? 10_000;
   const tableRows = options?.tableRows ?? {};
@@ -102,7 +99,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
     name: 'budgets',
     familyId: 'sql' as const,
 
-    async beforeExecute(plan: ExecutionPlan, ctx: MiddlewareContext<TContract>) {
+    async beforeExecute(plan: ExecutionPlan, ctx: SqlMiddlewareContext) {
       observedRowsByPlan.set(plan, { count: 0 });
 
       if (isQueryAst(plan.ast)) {
@@ -115,11 +112,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
       return evaluateWithHeuristics(plan, ctx);
     },
 
-    async onRow(
-      _row: Record<string, unknown>,
-      plan: ExecutionPlan,
-      _ctx: MiddlewareContext<TContract>,
-    ) {
+    async onRow(_row: Record<string, unknown>, plan: ExecutionPlan, _ctx: SqlMiddlewareContext) {
       const state = observedRowsByPlan.get(plan);
       if (!state) return;
       state.count += 1;
@@ -135,7 +128,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
     async afterExecute(
       _plan: ExecutionPlan,
       result: AfterExecuteResult,
-      ctx: MiddlewareContext<TContract>,
+      ctx: SqlMiddlewareContext,
     ) {
       const latencyMs = result.latencyMs;
       if (latencyMs > maxLatencyMs) {
@@ -146,17 +139,13 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
             maxLatencyMs,
           }),
           shouldBlock,
-          ctx as MiddlewareContext<unknown>,
+          ctx,
         );
       }
     },
   });
 
-  function evaluateSelectAst(
-    plan: ExecutionPlan,
-    ast: SelectAst,
-    ctx: MiddlewareContext<TContract>,
-  ) {
+  function evaluateSelectAst(plan: ExecutionPlan, ast: SelectAst, ctx: SqlMiddlewareContext) {
     const hasAggNoGroup = hasAggregateWithoutGroupBy(ast);
     const estimated = estimateRowsFromAst(
       ast,
@@ -177,7 +166,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
             maxRows,
           }),
           shouldBlock,
-          ctx as MiddlewareContext<unknown>,
+          ctx,
         );
         return;
       }
@@ -188,7 +177,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
           maxRows,
         }),
         shouldBlock,
-        ctx as MiddlewareContext<unknown>,
+        ctx,
       );
       return;
     }
@@ -201,12 +190,12 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
           maxRows,
         }),
         shouldBlock,
-        ctx as MiddlewareContext<unknown>,
+        ctx,
       );
     }
   }
 
-  async function evaluateWithHeuristics(plan: ExecutionPlan, ctx: MiddlewareContext<TContract>) {
+  async function evaluateWithHeuristics(plan: ExecutionPlan, ctx: SqlMiddlewareContext) {
     const estimated = estimateRowsFromHeuristics(plan, tableRows, defaultTableRows);
     const isUnbounded = !hasDetectableLimitFromHeuristics(plan);
     const sqlUpper = plan.sql.trimStart().toUpperCase();
@@ -222,7 +211,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
             maxRows,
           }),
           shouldBlock,
-          ctx as MiddlewareContext<unknown>,
+          ctx,
         );
         return;
       }
@@ -233,7 +222,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
           maxRows,
         }),
         shouldBlock,
-        ctx as MiddlewareContext<unknown>,
+        ctx,
       );
       return;
     }
@@ -247,7 +236,7 @@ export function budgets<TContract = unknown>(options?: BudgetsOptions): Middlewa
             maxRows,
           }),
           shouldBlock,
-          ctx as MiddlewareContext<unknown>,
+          ctx,
         );
       }
       return;

package/src/middleware/lints.ts

@@ -1,6 +1,5 @@
 import type { ExecutionPlan } from '@prisma-next/contract/types';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import type { Middleware, MiddlewareContext } from '@prisma-next/runtime-executor';
 import { evaluateRawGuardrails } from '@prisma-next/runtime-executor';
 import {
   type AnyFromSource,
@@ -8,6 +7,7 @@ import {
   isQueryAst,
 } from '@prisma-next/sql-relational-core/ast';
 import { ifDefined } from '@prisma-next/utils/defined';
+import type { SqlMiddleware, SqlMiddlewareContext } from './sql-middleware';
 
 export interface LintsOptions {
   readonly severities?: {
@@ -138,14 +138,14 @@ function getConfiguredSeverity(code: string, options?: LintsOptions): 'warn' | '
  * Fallback: When ast is missing, `fallbackWhenAstMissing: 'raw'` uses heuristic
  * SQL parsing; `'skip'` skips all lints. Default is `'raw'`.
  */
-export function lints<TContract = unknown>(options?: LintsOptions): Middleware<TContract> {
+export function lints(options?: LintsOptions): SqlMiddleware {
   const fallback = options?.fallbackWhenAstMissing ?? 'raw';
 
   return Object.freeze({
     name: 'lints',
     familyId: 'sql' as const,
 
-    async beforeExecute(plan: ExecutionPlan, ctx: MiddlewareContext<TContract>) {
+    async beforeExecute(plan: ExecutionPlan, ctx: SqlMiddlewareContext) {
       if (isQueryAst(plan.ast)) {
         const findings = evaluateAstLints(plan.ast);
 

package/src/middleware/sql-middleware.ts

@@ -1,17 +1,46 @@
-import type { Contract, ExecutionPlan } from '@prisma-next/contract/types';
+import type { Contract, ExecutionPlan, PlanMeta } from '@prisma-next/contract/types';
 import type {
   AfterExecuteResult,
   RuntimeMiddleware,
   RuntimeMiddlewareContext,
 } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import type { AnyQueryAst } from '@prisma-next/sql-relational-core/ast';
 
 export interface SqlMiddlewareContext extends RuntimeMiddlewareContext {
   readonly contract: Contract<SqlStorage>;
 }
 
+/**
+ * Pre-lowering query view passed to `beforeCompile`. Carries the typed SQL
+ * AST and plan metadata; `sql`/`params` are produced later by the adapter.
+ */
+export interface DraftPlan {
+  readonly ast: AnyQueryAst;
+  readonly meta: PlanMeta;
+}
+
 export interface SqlMiddleware extends RuntimeMiddleware {
-  readonly familyId: 'sql';
+  readonly familyId?: 'sql';
+  /**
+   * Rewrite the query AST before it is lowered to SQL. Middlewares run in
+   * registration order; each sees the predecessor's output, so rewrites
+   * compose (e.g. soft-delete + tenant isolation).
+   *
+   * Return `undefined` (or a draft whose `ast` reference equals the input's)
+   * to pass through. Return a draft with a new `ast` reference to replace it;
+   * the runtime emits a `middleware.rewrite` debug log event and continues
+   * with the new draft. `adapter.lower()` runs once after the chain.
+   *
+   * Use `AstRewriter` / `SelectAst.withWhere` / `AndExpr.of` etc. to build
+   * the rewritten AST. Predicates and literals go through parameterized
+   * constructors by default — no SQL-injection surface is added. **Warning:**
+   * constructing `LiteralExpr.of(userInput)` from untrusted input bypasses
+   * that guarantee; use `ParamRef.of(userInput, ...)` instead.
+   *
+   * See `docs/architecture docs/subsystems/4. Runtime & Middleware Framework.md`.
+   */
+  beforeCompile?(draft: DraftPlan, ctx: SqlMiddlewareContext): Promise<DraftPlan | undefined>;
   beforeExecute?(plan: ExecutionPlan, ctx: SqlMiddlewareContext): Promise<void>;
   onRow?(
     row: Record<string, unknown>,

package/src/sql-runtime.ts

@@ -6,14 +6,17 @@ import type {
 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 } from '@prisma-next/runtime-executor';
+import {
+  AsyncIterableResult,
+  createRuntimeCore,
+  runtimeError,
+} from '@prisma-next/runtime-executor';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type {
   Adapter,
@@ -29,6 +32,8 @@ import { decodeRow } from './codecs/decoding';
 import { encodeParams } from './codecs/encoding';
 import { validateCodecRegistryCompleteness } from './codecs/validation';
 import { lowerSqlPlan } from './lower-sql-plan';
+import { runBeforeCompileChain } from './middleware/before-compile-chain';
+import type { SqlMiddleware } from './middleware/sql-middleware';
 import type {
   ExecutionContext,
   SqlRuntimeAdapterInstance,
@@ -41,7 +46,7 @@ export interface RuntimeOptions<TContract extends Contract<SqlStorage> = Contrac
   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;
 }
@@ -60,7 +65,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;
 }
@@ -73,7 +78,28 @@ 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.
+   */
   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).
+   *
+   * 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.
+   */
+  destroy(reason?: unknown): Promise<void>;
 }
 
 export interface RuntimeTransaction extends RuntimeQueryable {
@@ -87,6 +113,10 @@ export interface RuntimeQueryable {
   ): AsyncIterableResult<Row>;
 }
 
+export interface TransactionContext extends RuntimeQueryable {
+  readonly invalidated: boolean;
+}
+
 interface CoreQueryable {
   execute<Row = Record<string, unknown>>(plan: ExecutionPlan<Row>): AsyncIterableResult<Row>;
 }
@@ -96,7 +126,7 @@ export type { RuntimeTelemetryEvent, RuntimeVerifyOptions, TelemetryOutcome };
 class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorage>>
   implements Runtime
 {
-  private readonly core: RuntimeCore<TContract, SqlDriver<unknown>>;
+  private readonly core: RuntimeCore<TContract, SqlDriver<unknown>, SqlMiddleware>;
   private readonly contract: TContract;
   private readonly adapter: Adapter<AnyQueryAst, Contract<SqlStorage>, LoweredStatement>;
   private readonly codecRegistry: CodecRegistry;
@@ -119,7 +149,7 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
 
     const familyAdapter = new SqlFamilyAdapter(context.contract, adapter.profile);
 
-    const coreOptions: RuntimeCoreOptions<TContract, SqlDriver<unknown>> = {
+    const coreOptions: RuntimeCoreOptions<TContract, SqlDriver<unknown>, SqlMiddleware> = {
       familyAdapter,
       driver,
       verify,
@@ -143,12 +173,27 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
     }
   }
 
-  private toExecutionPlan<Row>(plan: ExecutionPlan<Row> | SqlQueryPlan<Row>): ExecutionPlan<Row> {
+  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);
     };
 
-    return isSqlQueryPlan(plan) ? lowerSqlPlan(this.adapter, this.contract, plan) : plan;
+    if (!isSqlQueryPlan(plan)) {
+      return plan;
+    }
+
+    const rewrittenDraft = await runBeforeCompileChain(
+      this.core.middleware,
+      { ast: plan.ast, meta: plan.meta },
+      this.core.middlewareContext,
+    );
+
+    const planToLower: SqlQueryPlan<Row> =
+      rewrittenDraft.ast === plan.ast ? plan : { ...plan, ast: rewrittenDraft.ast };
+
+    return lowerSqlPlan(this.adapter, this.contract, planToLower);
   }
 
   private executeAgainstQueryable<Row = Record<string, unknown>>(
@@ -156,11 +201,11 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
     queryable: CoreQueryable,
   ): AsyncIterableResult<Row> {
     this.ensureCodecRegistryValidated(this.contract);
-    const executablePlan = this.toExecutionPlan(plan);
 
     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,
@@ -206,6 +251,7 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
         };
       },
       release: coreConn.release.bind(coreConn),
+      destroy: coreConn.destroy.bind(coreConn),
       execute<Row = Record<string, unknown>>(
         plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
       ): AsyncIterableResult<Row> {
@@ -224,6 +270,114 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
   }
 }
 
+function transactionClosedError(): Error {
+  return runtimeError(
+    'RUNTIME.TRANSACTION_CLOSED',
+    'Cannot read from a query result after the transaction has ended. Await the result or call .toArray() inside the transaction callback.',
+    {},
+  );
+}
+
+export async function withTransaction<R>(
+  runtime: Runtime,
+  fn: (tx: TransactionContext) => PromiseLike<R>,
+): Promise<R> {
+  const connection = await runtime.connection();
+  const transaction = await connection.transaction();
+
+  let invalidated = false;
+  const txContext: TransactionContext = {
+    get invalidated() {
+      return invalidated;
+    },
+    execute<Row = Record<string, unknown>>(
+      plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+    ): AsyncIterableResult<Row> {
+      if (invalidated) {
+        throw transactionClosedError();
+      }
+      const inner = transaction.execute(plan);
+      const guarded = async function* (): AsyncGenerator<Row, void, unknown> {
+        for await (const row of inner) {
+          if (invalidated) {
+            throw transactionClosedError();
+          }
+          yield row;
+        }
+      };
+      return new AsyncIterableResult(guarded());
+    },
+  };
+
+  let connectionDisposed = false;
+  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.
+    await connection.destroy(reason).catch(() => undefined);
+  };
+
+  try {
+    let result: R;
+    try {
+      result = await fn(txContext);
+    } catch (error) {
+      try {
+        await transaction.rollback();
+      } catch (rollbackError) {
+        await destroyConnection(rollbackError);
+        const wrapped = runtimeError(
+          'RUNTIME.TRANSACTION_ROLLBACK_FAILED',
+          'Transaction rollback failed after callback error',
+          { rollbackError },
+        );
+        wrapped.cause = error;
+        throw wrapped;
+      }
+      throw error;
+    } finally {
+      invalidated = true;
+    }
+
+    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.
+      //
+      // 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 {
+        await destroyConnection(commitError);
+      }
+      const wrapped = runtimeError(
+        'RUNTIME.TRANSACTION_COMMIT_FAILED',
+        'Transaction commit failed',
+        { commitError },
+      );
+      wrapped.cause = commitError;
+      throw wrapped;
+    }
+    return result;
+  } finally {
+    if (!connectionDisposed) {
+      await connection.release();
+    }
+  }
+}
+
 export function createRuntime<TContract extends Contract<SqlStorage>, TTargetId extends string>(
   options: CreateRuntimeOptions<TContract, TTargetId>,
 ): Runtime {