@prisma-next/sql-runtime 0.3.0-pr.75.6 → 0.3.0-pr.75.7

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@prisma-next/sql-runtime",
-  "version": "0.3.0-pr.75.6",
+  "version": "0.3.0-pr.75.7",
   "type": "module",
   "sideEffects": false,
   "description": "SQL runtime implementation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.3.0-pr.75.6",
-    "@prisma-next/operations": "0.3.0-pr.75.6",
-    "@prisma-next/core-execution-plane": "0.3.0-pr.75.6",
-    "@prisma-next/runtime-executor": "0.3.0-pr.75.6",
-    "@prisma-next/sql-contract": "0.3.0-pr.75.6",
-    "@prisma-next/sql-operations": "0.3.0-pr.75.6",
-    "@prisma-next/sql-relational-core": "0.3.0-pr.75.6"
+    "@prisma-next/contract": "0.3.0-pr.75.7",
+    "@prisma-next/core-execution-plane": "0.3.0-pr.75.7",
+    "@prisma-next/operations": "0.3.0-pr.75.7",
+    "@prisma-next/runtime-executor": "0.3.0-pr.75.7",
+    "@prisma-next/sql-contract": "0.3.0-pr.75.7",
+    "@prisma-next/sql-operations": "0.3.0-pr.75.7",
+    "@prisma-next/sql-relational-core": "0.3.0-pr.75.7"
   },
   "devDependencies": {
     "@types/pg": "8.16.0",
@@ -24,7 +24,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "test"
   ],
   "exports": {
     ".": {

package/test/async-iterable-result.test.ts

@@ -0,0 +1,136 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type { AsyncIterableResult } from '@prisma-next/runtime-executor';
+import { describe, expect, it } from 'vitest';
+import { createRuntime } from '../src/exports';
+import { createStubAdapter, createTestContext, createTestContract } from './utils';
+
+// Mock driver that implements SqlDriver interface
+class MockDriver {
+  private rows: ReadonlyArray<Record<string, unknown>> = [];
+
+  setRows(rows: ReadonlyArray<Record<string, unknown>>): void {
+    this.rows = rows;
+  }
+
+  async query(
+    _sql: string,
+    _params: readonly unknown[],
+  ): Promise<{ rows: ReadonlyArray<unknown> }> {
+    // Return empty marker result for contract verification
+    return { rows: [] };
+  }
+
+  async *execute<Row = Record<string, unknown>>(_options: {
+    sql: string;
+    params: readonly unknown[];
+  }): AsyncIterable<Row> {
+    for (const row of this.rows) {
+      yield row as Row;
+    }
+  }
+
+  async connect(): Promise<void> {
+    // No-op
+  }
+
+  async close(): Promise<void> {
+    // No-op
+  }
+}
+
+const fixtureContract = createTestContract({
+  schemaVersion: '1',
+  targetFamily: 'sql',
+  target: 'postgres',
+  coreHash: 'test-hash',
+  profileHash: 'test-profile-hash',
+  storage: {
+    tables: {
+      user: {
+        columns: {
+          id: { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false },
+          email: { nativeType: 'text', codecId: 'pg/text@1', nullable: false },
+        },
+        uniques: [],
+        indexes: [],
+        foreignKeys: [],
+      },
+    },
+  },
+  models: {},
+  relations: {},
+  mappings: { codecTypes: {}, operationTypes: {} },
+});
+
+describe('SqlRuntime AsyncIterableResult integration', () => {
+  it('returns AsyncIterableResult from execute', async () => {
+    const adapter = createStubAdapter();
+    const driver = new MockDriver();
+    driver.setRows([
+      { id: 1, email: 'test1@example.com' },
+      { id: 2, email: 'test2@example.com' },
+    ]);
+    const context = createTestContext(fixtureContract, adapter);
+    const runtime = createRuntime({
+      driver: driver as unknown as Parameters<typeof createRuntime>[0]['driver'],
+      context,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    const plan: ExecutionPlan<{ id: number; email: string }> = {
+      sql: 'SELECT id, email FROM "user" ORDER BY id',
+      params: [],
+      meta: {
+        target: 'postgres',
+        targetFamily: 'sql',
+        coreHash: 'test-hash',
+        lane: 'sql',
+        paramDescriptors: [],
+      },
+    };
+
+    const result = runtime.execute(plan);
+
+    // Verify it's an AsyncIterableResult
+    expect(result).toBeInstanceOf(Object);
+    expect(typeof result.toArray).toBe('function');
+    expect(typeof result[Symbol.asyncIterator]).toBe('function');
+
+    await runtime.close();
+  });
+
+  it('preserves type information', async () => {
+    const adapter = createStubAdapter();
+    const driver = new MockDriver();
+    driver.setRows([{ id: 1, email: 'test@example.com' }]);
+    const context = createTestContext(fixtureContract, adapter);
+    const runtime = createRuntime({
+      driver: driver as unknown as Parameters<typeof createRuntime>[0]['driver'],
+      context,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    const plan: ExecutionPlan<{ id: number; email: string }> = {
+      sql: 'SELECT id, email FROM "user" LIMIT 1',
+      params: [],
+      meta: {
+        target: 'postgres',
+        targetFamily: 'sql',
+        coreHash: 'test-hash',
+        lane: 'sql',
+        paramDescriptors: [],
+      },
+    };
+
+    const result: AsyncIterableResult<{ id: number; email: string }> = runtime.execute(plan);
+    const rows = await result.toArray();
+
+    expect(rows.length).toBe(1);
+    if (rows[0]) {
+      expect(typeof rows[0].id).toBe('number');
+      expect(typeof rows[0].email).toBe('string');
+    }
+
+    await runtime.close();
+  });
+});

package/test/sql-context.test.ts

@@ -0,0 +1,217 @@
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { SqlOperationSignature } from '@prisma-next/sql-operations';
+import type { CodecRegistry, SelectAst } from '@prisma-next/sql-relational-core/ast';
+import { codec, createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import { describe, expect, it } from 'vitest';
+import {
+  createRuntimeContext,
+  type SqlRuntimeExtensionDescriptor,
+  type SqlRuntimeExtensionInstance,
+} from '../src/sql-context';
+
+// Minimal test contract
+const testContract: SqlContract<SqlStorage> = {
+  schemaVersion: '1',
+  targetFamily: 'sql',
+  target: 'postgres',
+  coreHash: 'sha256:test',
+  models: {},
+  relations: {},
+  storage: { tables: {} },
+  extensionPacks: {},
+  capabilities: {},
+  meta: {},
+  sources: {},
+  mappings: {
+    codecTypes: {},
+    operationTypes: {},
+  },
+};
+
+// Stub adapter codecs
+function createStubCodecs(): CodecRegistry {
+  const registry = createCodecRegistry();
+  registry.register(
+    codec({
+      typeId: 'pg/int4@1',
+      targetTypes: ['int4'],
+      encode: (v: number) => v,
+      decode: (w: number) => w,
+    }),
+  );
+  return registry;
+}
+
+// Create a test adapter descriptor
+function createTestAdapterDescriptor() {
+  const codecs = createStubCodecs();
+  return {
+    kind: 'adapter' as const,
+    id: 'test-adapter',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    create() {
+      return {
+        familyId: 'sql' as const,
+        targetId: 'postgres' as const,
+        profile: {
+          id: 'test-profile',
+          target: 'postgres',
+          capabilities: {},
+          codecs() {
+            return codecs;
+          },
+        },
+        lower(ast: SelectAst) {
+          return {
+            profileId: 'test-profile',
+            body: Object.freeze({ sql: JSON.stringify(ast), params: [] }),
+          };
+        },
+      };
+    },
+  };
+}
+
+// Create a test target descriptor
+function createTestTargetDescriptor() {
+  return {
+    kind: 'target' as const,
+    id: 'postgres',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    create() {
+      return { familyId: 'sql' as const, targetId: 'postgres' as const };
+    },
+  };
+}
+
+// Create a test extension descriptor
+function createTestExtensionDescriptor(options?: {
+  hasCodecs?: boolean;
+  hasOperations?: boolean;
+}): SqlRuntimeExtensionDescriptor<'postgres'> {
+  const { hasCodecs = false, hasOperations = false } = options ?? {};
+
+  // Build the codecs function if needed
+  const codecsFn = hasCodecs
+    ? () => {
+        const registry = createCodecRegistry();
+        registry.register(
+          codec({
+            typeId: 'test/ext@1',
+            targetTypes: ['ext'],
+            encode: (v: string) => v,
+            decode: (w: string) => w,
+          }),
+        );
+        return registry;
+      }
+    : undefined;
+
+  // Build the operations function if needed
+  const operationsFn = hasOperations
+    ? (): ReadonlyArray<SqlOperationSignature> => [
+        {
+          forTypeId: 'test/ext@1',
+          method: 'testOp',
+          args: [],
+          returns: { kind: 'builtin', type: 'number' },
+          lowering: { targetFamily: 'sql', strategy: 'function', template: 'test()' },
+        },
+      ]
+    : undefined;
+
+  return {
+    kind: 'extension' as const,
+    id: 'test-extension',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    create(): SqlRuntimeExtensionInstance<'postgres'> {
+      // Return object with optional methods only if they exist
+      const instance: SqlRuntimeExtensionInstance<'postgres'> = {
+        familyId: 'sql' as const,
+        targetId: 'postgres' as const,
+      };
+      if (codecsFn) {
+        (instance as { codecs?: () => CodecRegistry }).codecs = codecsFn;
+      }
+      if (operationsFn) {
+        (instance as { operations?: () => ReadonlyArray<SqlOperationSignature> }).operations =
+          operationsFn;
+      }
+      return instance;
+    },
+  };
+}
+
+describe('createRuntimeContext', () => {
+  it('creates context with adapter codecs', () => {
+    const context = createRuntimeContext({
+      contract: testContract,
+      target: createTestTargetDescriptor(),
+      adapter: createTestAdapterDescriptor(),
+    });
+
+    expect(context.contract).toBe(testContract);
+    expect(context.adapter).toBeDefined();
+    expect(context.codecs.has('pg/int4@1')).toBe(true);
+    expect(context.operations).toBeDefined();
+  });
+
+  it('creates context with empty extension packs', () => {
+    const context = createRuntimeContext({
+      contract: testContract,
+      target: createTestTargetDescriptor(),
+      adapter: createTestAdapterDescriptor(),
+      extensionPacks: [],
+    });
+
+    expect(context.codecs.has('pg/int4@1')).toBe(true);
+    // No extension codecs registered
+    expect(context.codecs.has('test/ext@1')).toBe(false);
+  });
+
+  it('registers extension codecs', () => {
+    const context = createRuntimeContext({
+      contract: testContract,
+      target: createTestTargetDescriptor(),
+      adapter: createTestAdapterDescriptor(),
+      extensionPacks: [createTestExtensionDescriptor({ hasCodecs: true })],
+    });
+
+    // Adapter codec
+    expect(context.codecs.has('pg/int4@1')).toBe(true);
+    // Extension codec
+    expect(context.codecs.has('test/ext@1')).toBe(true);
+  });
+
+  it('registers extension operations', () => {
+    const context = createRuntimeContext({
+      contract: testContract,
+      target: createTestTargetDescriptor(),
+      adapter: createTestAdapterDescriptor(),
+      extensionPacks: [createTestExtensionDescriptor({ hasOperations: true })],
+    });
+
+    const ops = context.operations.byType('test/ext@1');
+    expect(ops.length).toBe(1);
+    expect(ops[0]?.method).toBe('testOp');
+  });
+
+  it('handles extension without codecs or operations', () => {
+    const context = createRuntimeContext({
+      contract: testContract,
+      target: createTestTargetDescriptor(),
+      adapter: createTestAdapterDescriptor(),
+      extensionPacks: [createTestExtensionDescriptor({ hasCodecs: false, hasOperations: false })],
+    });
+
+    // Only adapter codec
+    expect(context.codecs.has('pg/int4@1')).toBe(true);
+    expect(context.codecs.has('test/ext@1')).toBe(false);
+  });
+});

package/test/sql-family-adapter.test.ts

@@ -0,0 +1,86 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import { describe, expect, it } from 'vitest';
+import { SqlFamilyAdapter } from '../src/sql-family-adapter';
+
+// Minimal test contract
+const testContract: SqlContract<SqlStorage> = {
+  schemaVersion: '1',
+  targetFamily: 'sql',
+  target: 'postgres',
+  coreHash: 'sha256:test-hash',
+  models: {},
+  relations: {},
+  storage: { tables: {} },
+  extensionPacks: {},
+  capabilities: {},
+  meta: {},
+  sources: {},
+  mappings: {
+    codecTypes: {},
+    operationTypes: {},
+  },
+};
+
+describe('SqlFamilyAdapter', () => {
+  it('creates adapter with contract and marker reader', () => {
+    const adapter = new SqlFamilyAdapter(testContract);
+
+    expect(adapter.contract).toBe(testContract);
+    expect(adapter.markerReader).toBeDefined();
+    expect(adapter.markerReader.readMarkerStatement).toBeDefined();
+  });
+
+  it('validates plan with matching target and hash', () => {
+    const adapter = new SqlFamilyAdapter(testContract);
+    const plan: ExecutionPlan = {
+      meta: {
+        target: 'postgres',
+        coreHash: 'sha256:test-hash',
+        lane: 'sql',
+        paramDescriptors: [],
+      },
+      sql: 'SELECT 1',
+      params: [],
+    };
+
+    // Should not throw
+    expect(() => adapter.validatePlan(plan, testContract)).not.toThrow();
+  });
+
+  it('throws on plan target mismatch', () => {
+    const adapter = new SqlFamilyAdapter(testContract);
+    const plan: ExecutionPlan = {
+      meta: {
+        target: 'mysql', // Wrong target
+        coreHash: 'sha256:test-hash',
+        lane: 'sql',
+        paramDescriptors: [],
+      },
+      sql: 'SELECT 1',
+      params: [],
+    };
+
+    expect(() => adapter.validatePlan(plan, testContract)).toThrow(
+      'Plan target does not match runtime target',
+    );
+  });
+
+  it('throws on plan coreHash mismatch', () => {
+    const adapter = new SqlFamilyAdapter(testContract);
+    const plan: ExecutionPlan = {
+      meta: {
+        target: 'postgres',
+        coreHash: 'sha256:different-hash', // Wrong hash
+        lane: 'sql',
+        paramDescriptors: [],
+      },
+      sql: 'SELECT 1',
+      params: [],
+    };
+
+    expect(() => adapter.validatePlan(plan, testContract)).toThrow(
+      'Plan core hash does not match runtime contract',
+    );
+  });
+});

package/test/sql-runtime.test.ts

@@ -0,0 +1,155 @@
+import { createOperationRegistry } from '@prisma-next/operations';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type {
+  CodecRegistry,
+  SelectAst,
+  SqlDriver,
+  SqlExecuteRequest,
+} from '@prisma-next/sql-relational-core/ast';
+import { codec, createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import { describe, expect, it, vi } from 'vitest';
+import type { RuntimeContext } from '../src/sql-context';
+import { createRuntime } from '../src/sql-runtime';
+
+// Minimal test contract
+const testContract: SqlContract<SqlStorage> = {
+  schemaVersion: '1',
+  targetFamily: 'sql',
+  target: 'postgres',
+  coreHash: 'sha256:test',
+  models: {},
+  relations: {},
+  storage: { tables: {} },
+  extensionPacks: {},
+  capabilities: {},
+  meta: {},
+  sources: {},
+  mappings: {
+    codecTypes: {},
+    operationTypes: {},
+  },
+};
+
+// Create a stub codec registry
+function createStubCodecs(): CodecRegistry {
+  const registry = createCodecRegistry();
+  registry.register(
+    codec({
+      typeId: 'pg/int4@1',
+      targetTypes: ['int4'],
+      encode: (v: number) => v,
+      decode: (w: number) => w,
+    }),
+  );
+  return registry;
+}
+
+// Create a stub adapter
+function createStubAdapter() {
+  const codecs = createStubCodecs();
+  return {
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    profile: {
+      id: 'test-profile',
+      target: 'postgres',
+      capabilities: {},
+      codecs() {
+        return codecs;
+      },
+    },
+    lower(ast: SelectAst) {
+      return {
+        profileId: 'test-profile',
+        body: Object.freeze({ sql: JSON.stringify(ast), params: [] }),
+      };
+    },
+  };
+}
+
+// Create a mock driver that implements SqlDriver interface
+function createMockDriver(): SqlDriver {
+  const execute = vi.fn().mockImplementation(async function* (_request: SqlExecuteRequest) {
+    yield { id: 1 };
+  });
+
+  return {
+    connect: vi.fn().mockResolvedValue(undefined),
+    execute,
+    query: vi.fn().mockResolvedValue({ rows: [], rowCount: 0 }),
+    close: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+// Create a test runtime context
+function createTestContext(contract: SqlContract<SqlStorage>): RuntimeContext<typeof contract> {
+  const adapter = createStubAdapter();
+  return {
+    contract,
+    adapter,
+    codecs: adapter.profile.codecs(),
+    operations: createOperationRegistry(),
+  };
+}
+
+describe('createRuntime', () => {
+  it('creates runtime with valid options', () => {
+    const context = createTestContext(testContract);
+    const driver = createMockDriver();
+
+    const runtime = createRuntime({
+      context,
+      driver,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    expect(runtime).toBeDefined();
+    expect(runtime.execute).toBeDefined();
+    expect(runtime.telemetry).toBeDefined();
+    expect(runtime.operations).toBeDefined();
+    expect(runtime.close).toBeDefined();
+  });
+
+  it('returns operations registry', () => {
+    const context = createTestContext(testContract);
+    const driver = createMockDriver();
+
+    const runtime = createRuntime({
+      context,
+      driver,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    const ops = runtime.operations();
+    expect(ops).toBeDefined();
+    expect(ops.byType).toBeDefined();
+  });
+
+  it('returns null telemetry when no events', () => {
+    const context = createTestContext(testContract);
+    const driver = createMockDriver();
+
+    const runtime = createRuntime({
+      context,
+      driver,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    // Before any execution, telemetry should be null
+    expect(runtime.telemetry()).toBeNull();
+  });
+
+  it('closes runtime', async () => {
+    const context = createTestContext(testContract);
+    const driver = createMockDriver();
+
+    const runtime = createRuntime({
+      context,
+      driver,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    await runtime.close();
+    expect(driver.close).toHaveBeenCalled();
+  });
+});

package/test/utils.ts

@@ -0,0 +1,262 @@
+import type { ExecutionPlan, ResultType } from '@prisma-next/contract/types';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { Adapter, LoweredStatement, SelectAst } from '@prisma-next/sql-relational-core/ast';
+import { codec, createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import { collectAsync, drainAsyncIterable } from '@prisma-next/test-utils';
+import type { Client } from 'pg';
+import type { SqlStatement } from '../src/exports';
+import {
+  type createRuntime,
+  createRuntimeContext,
+  ensureSchemaStatement,
+  ensureTableStatement,
+  writeContractMarker,
+} from '../src/exports';
+import type {
+  RuntimeContext,
+  SqlRuntimeAdapterInstance,
+  SqlRuntimeExtensionDescriptor,
+} from '../src/sql-context';
+
+/**
+ * Executes a plan and collects all results into an array.
+ * This helper DRYs up the common pattern of executing plans in tests.
+ * The return type is inferred from the plan's type parameter.
+ */
+export async function executePlanAndCollect<
+  P extends ExecutionPlan<ResultType<P>> | SqlQueryPlan<ResultType<P>>,
+>(runtime: ReturnType<typeof createRuntime>, plan: P): Promise<ResultType<P>[]> {
+  type Row = ResultType<P>;
+  return collectAsync<Row>(runtime.execute<Row>(plan));
+}
+
+/**
+ * Drains a plan execution, consuming all results without collecting them.
+ * Useful for testing side effects without memory overhead.
+ */
+export async function drainPlanExecution(
+  runtime: ReturnType<typeof createRuntime>,
+  plan: ExecutionPlan | SqlQueryPlan<unknown>,
+): Promise<void> {
+  return drainAsyncIterable(runtime.execute(plan));
+}
+
+/**
+ * Executes a SQL statement on a database client.
+ */
+export async function executeStatement(client: Client, statement: SqlStatement): Promise<void> {
+  if (statement.params.length > 0) {
+    await client.query(statement.sql, [...statement.params]);
+    return;
+  }
+
+  await client.query(statement.sql);
+}
+
+/**
+ * Sets up database schema and data, then writes the contract marker.
+ * This helper DRYs up the common pattern of database setup in tests.
+ */
+export async function setupTestDatabase(
+  client: Client,
+  contract: SqlContract<SqlStorage>,
+  setupFn: (client: Client) => Promise<void>,
+): Promise<void> {
+  await client.query('drop schema if exists prisma_contract cascade');
+  await client.query('create schema if not exists public');
+
+  await setupFn(client);
+
+  await executeStatement(client, ensureSchemaStatement);
+  await executeStatement(client, ensureTableStatement);
+  const write = writeContractMarker({
+    coreHash: contract.coreHash,
+    profileHash: contract.profileHash ?? contract.coreHash,
+    contractJson: contract,
+    canonicalVersion: 1,
+  });
+  await executeStatement(client, write.insert);
+}
+
+/**
+ * Writes a contract marker to the database.
+ * This helper DRYs up the common pattern of writing contract markers in tests.
+ */
+export async function writeTestContractMarker(
+  client: Client,
+  contract: SqlContract<SqlStorage>,
+): Promise<void> {
+  const write = writeContractMarker({
+    coreHash: contract.coreHash,
+    profileHash: contract.profileHash ?? contract.coreHash,
+    contractJson: contract,
+    canonicalVersion: 1,
+  });
+  await executeStatement(client, write.insert);
+}
+
+/**
+ * Creates a test adapter descriptor from a raw adapter.
+ * This wraps the adapter in a descriptor for descriptor-first context creation in tests.
+ * The adapter instance IS an Adapter (via intersection), with identity properties added.
+ */
+function createTestAdapterDescriptor(
+  adapter: Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+): {
+  readonly kind: 'adapter';
+  readonly id: string;
+  readonly version: string;
+  readonly familyId: 'sql';
+  readonly targetId: 'postgres';
+  create(): SqlRuntimeAdapterInstance<'postgres'>;
+} {
+  return {
+    kind: 'adapter' as const,
+    id: 'test-adapter',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    create(): SqlRuntimeAdapterInstance<'postgres'> {
+      // Return an object that combines identity properties with the adapter's methods
+      return Object.assign(
+        {
+          familyId: 'sql' as const,
+          targetId: 'postgres' as const,
+        },
+        adapter,
+      );
+    },
+  };
+}
+
+/**
+ * Creates a test target descriptor.
+ * This is a minimal descriptor for descriptor-first context creation in tests.
+ */
+function createTestTargetDescriptor(): {
+  readonly kind: 'target';
+  readonly id: string;
+  readonly version: string;
+  readonly familyId: 'sql';
+  readonly targetId: 'postgres';
+  create(): { readonly familyId: 'sql'; readonly targetId: 'postgres' };
+} {
+  return {
+    kind: 'target' as const,
+    id: 'postgres',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    create() {
+      return { familyId: 'sql' as const, targetId: 'postgres' as const };
+    },
+  };
+}
+
+/**
+ * Creates a runtime context with standard test configuration.
+ * This helper DRYs up the common pattern of context creation in tests.
+ *
+ * Accepts a raw adapter and optional extension descriptors, wrapping the
+ * adapter in a descriptor internally for descriptor-first context creation.
+ */
+export function createTestContext<TContract extends SqlContract<SqlStorage>>(
+  contract: TContract,
+  adapter: Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+  options?: {
+    extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<'postgres'>>;
+  },
+): RuntimeContext<TContract> {
+  return createRuntimeContext<TContract, 'postgres'>({
+    contract,
+    target: createTestTargetDescriptor(),
+    adapter: createTestAdapterDescriptor(adapter),
+    extensionPacks: options?.extensionPacks ?? [],
+  });
+}
+
+/**
+ * Creates a stub adapter for testing.
+ * This helper DRYs up the common pattern of adapter creation in tests.
+ *
+ * The stub adapter includes simple codecs for common test types (pg/int4@1, pg/text@1, pg/timestamptz@1)
+ * to enable type inference in tests without requiring the postgres adapter package.
+ */
+export function createStubAdapter(): Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement> {
+  const codecRegistry = createCodecRegistry();
+
+  // Register stub codecs for common test types
+  // These match the codec IDs used in test contracts (pg/int4@1, pg/text@1, pg/timestamptz@1)
+  // but don't require importing from the postgres adapter package
+  codecRegistry.register(
+    codec({
+      typeId: 'pg/int4@1',
+      targetTypes: ['int4'],
+      encode: (value: number) => value,
+      decode: (wire: number) => wire,
+    }),
+  );
+
+  codecRegistry.register(
+    codec({
+      typeId: 'pg/text@1',
+      targetTypes: ['text'],
+      encode: (value: string) => value,
+      decode: (wire: string) => wire,
+    }),
+  );
+
+  codecRegistry.register(
+    codec({
+      typeId: 'pg/timestamptz@1',
+      targetTypes: ['timestamptz'],
+      encode: (value: string | Date) => (value instanceof Date ? value.toISOString() : value),
+      decode: (wire: string | Date) =>
+        typeof wire === 'string' ? wire : wire instanceof Date ? wire.toISOString() : String(wire),
+    }),
+  );
+
+  return {
+    profile: {
+      id: 'stub-profile',
+      target: 'postgres',
+      capabilities: {},
+      codecs() {
+        return codecRegistry;
+      },
+    },
+    lower(ast: SelectAst, ctx: { contract: SqlContract<SqlStorage>; params?: readonly unknown[] }) {
+      const sqlText = JSON.stringify(ast);
+      return {
+        profileId: this.profile.id,
+        body: Object.freeze({ sql: sqlText, params: ctx.params ? [...ctx.params] : [] }),
+      };
+    },
+  };
+}
+
+/**
+ * Creates a valid test contract without using validateContract.
+ * Ensures mappings are present and returns the contract with proper typing.
+ * This helper allows tests to create contracts without depending on sql-query.
+ */
+export function createTestContract<T extends SqlContract<SqlStorage>>(contract: T): T {
+  // Ensure mappings are present
+  if (!contract.mappings) {
+    return {
+      ...contract,
+      mappings: { codecTypes: {}, operationTypes: {} },
+    } as T;
+  }
+  return contract;
+}
+
+// Re-export generic utilities from test-utils
+export {
+  collectAsync,
+  createDevDatabase,
+  type DevDatabase,
+  teardownTestDatabase,
+  withClient,
+} from '@prisma-next/test-utils';