refactor(rawSql): address inline review comments

Renames + cleanup driven by inline REVIEW comments:

- Drop 5 raw-SQL tests from the postgres/sqlite extension packages —
  they duplicated coverage that already lives in
  `@prisma-next/sql-relational-core` (factory shape, AST surface,
  type-level interpolation contract). The extension-level coverage
  was end-to-end via the integration test, not unit-level repetition.

- `Db<C>` in sql-builder: collapse the explicit `TableProxy<C, Name,
  Name, DefaultScope<...>, ContractToQC<C, Name>>` instantiation to
  `TableProxy<C, Name>`, since every argument matches TableProxy's
  default generics.

- `RawExpr` visitor / rewriter / folder arms renamed from `rawSql`
  to `rawExpr` to match the AST kind discriminant (`'raw-expr'`).
  Updates `RawExpr.accept` / `.rewrite` / `.fold` plus the two
  call sites in `@prisma-next/sql-orm-client`
  (`where-binding.ts`, `query-plan-aggregate.ts`) and the relevant
  test arm names.

- `RawCodecInferer` JSDoc rewritten as public-API documentation —
  explains the contract implementers fulfil and how the runtime
  consumes it, without linking to internal symbols.

- `RawSqlLiteral` JSDoc no longer calls out Date specifically; the
  rule is generic: anything outside the literal union is routed
  through `param(value, { codecId })`.

- `create-raw-sql.test.ts`: `stubAdapter` → `stubInferer`; test
  titles + comments use "inferer" terminology to match the renamed
  interface; "defence-in-depth" describe renamed to plain language.

- Drop a tautological test in `raw-expr.test.ts` that asserted
  `RawExpr.baseColumnRef` shares an error message with
  `AggregateExpr.count()` — the wording is not load-bearing.

Signed-off-by: Serhii Tatarintsev <tatarintsev@prisma.io>

Author: SevInf

packages/2-sql/4-lanes/relational-core/src/ast/types.ts

@@ -20,7 +20,7 @@ export type AggregateFn = AggregateCountFn | AggregateOpFn;
  */
 export type WindowFn = 'row_number' | 'rank' | 'dense_rank';
 
-/** Scalar JS values that map directly to a SQL wire type. `Date` is excluded — it must be routed through `param(date, { codecId })` to select the target codec (timestamp vs. timestamptz, precision, timezone semantics). */
+/** Scalar JS values that map directly to a SQL wire type. Values outside this set must be routed through `param(value, { codecId })` to declare the target codec explicitly. */
 export type RawSqlLiteral = number | bigint | string | boolean | Uint8Array;
 
 export interface ExpressionSource {
@@ -35,7 +35,7 @@ export interface ExpressionRewriter {
   literal?(expr: LiteralExpr): LiteralExpr;
   list?(expr: ListExpression): ListExpression | LiteralExpr;
   select?(ast: SelectAst): SelectAst;
-  rawSql?(expr: RawExpr): AnyExpression;
+  rawExpr?(expr: RawExpr): AnyExpression;
 }
 
 export interface AstRewriter extends ExpressionRewriter {
@@ -62,7 +62,7 @@ export interface ExprVisitor<R> {
   param(expr: ParamRef): R;
   preparedParam(expr: PreparedParamRef): R;
   list(expr: ListExpression): R;
-  rawSql(expr: RawExpr): R;
+  rawExpr(expr: RawExpr): R;
 }
 
 export interface ExpressionFolder<T> {
@@ -76,7 +76,7 @@ export interface ExpressionFolder<T> {
   literal?(expr: LiteralExpr): T;
   list?(expr: ListExpression): T;
   select?(ast: SelectAst): T;
-  rawSql?(expr: RawExpr): T;
+  rawExpr?(expr: RawExpr): T;
 }
 
 export type ProjectionExpr = AnyExpression;
@@ -639,16 +639,16 @@ export class RawExpr extends Expression {
   }
 
   override accept<R>(visitor: ExprVisitor<R>): R {
-    return visitor.rawSql(this);
+    return visitor.rawExpr(this);
   }
 
   override rewrite(rewriter: ExpressionRewriter): AnyExpression {
-    return rewriter.rawSql ? rewriter.rawSql(this) : this;
+    return rewriter.rawExpr ? rewriter.rawExpr(this) : this;
   }
 
   override fold<T>(folder: ExpressionFolder<T>): T {
-    if (folder.rawSql) {
-      return folder.rawSql(this);
+    if (folder.rawExpr) {
+      return folder.rawExpr(this);
     }
     return combineAll(
       folder,

packages/2-sql/4-lanes/relational-core/src/expression.ts

@@ -160,7 +160,18 @@ export function buildOperation<R extends ScopeField>(spec: BuildOperationSpec<R>
   };
 }
 
-/** Minimal contract a target must satisfy to construct a {@link RawSqlTag} via {@link createRawSql} — looks up the codec id for a bare-literal interpolation. */
+/**
+ * Resolves a codec id for a bare JavaScript value interpolated into a raw-SQL
+ * template — e.g. `` rawSql`SELECT ${42}` `` calls `inferCodec(42)` to pick
+ * the codec id (`pg/int4`, `sqlite/integer@1`, etc.) that will encode the
+ * value as a bound parameter.
+ *
+ * Targets implement this once per dialect: examine the JS value's runtime
+ * shape (number, bigint, string, boolean, `Uint8Array`) and return a codec
+ * id known to the target's codec registry. Throw when the value falls
+ * outside the supported set — callers should wrap such values with
+ * `param(value, { codecId })` to declare the codec explicitly.
+ */
 export interface RawCodecInferer {
   inferCodec(value: RawSqlLiteral): string;
 }

packages/2-sql/4-lanes/relational-core/test/ast/raw-expr.test.ts

@@ -1,11 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import {
-  AggregateExpr,
-  type AnyExpression,
-  type ExprVisitor,
-  ParamRef,
-  RawExpr,
-} from '../../src/exports/ast';
+import { type AnyExpression, type ExprVisitor, ParamRef, RawExpr } from '../../src/exports/ast';
 import { col, lit, param } from './test-helpers';
 
 describe('ast/RawExpr', () => {
@@ -52,24 +46,24 @@ describe('ast/RawExpr', () => {
       preparedParam: () => 'preparedParam',
       list: () => 'list',
       windowFunc: () => 'windowFunc',
-      rawSql: (e) => {
-        visited.push(`rawSql:${e.parts.length}`);
-        return 'rawSql';
+      rawExpr: (e) => {
+        visited.push(`rawExpr:${e.parts.length}`);
+        return 'rawExpr';
       },
     };
 
     const result = expr.accept(visitor);
-    expect(result).toBe('rawSql');
-    expect(visited).toEqual(['rawSql:2']);
+    expect(result).toBe('rawExpr');
+    expect(visited).toEqual(['rawExpr:2']);
   });
 
-  it('rewrites expression parts through the optional rawSql rewriter arm', () => {
+  it('rewrites expression parts through the optional rawExpr rewriter arm', () => {
     const ref = param(1, 'x');
     const expr = new RawExpr({ parts: ['prefix ', ref, ' suffix'], returns: returnsSpec });
 
     const newRef = param(99, 'x');
     const rewritten = expr.rewrite({
-      rawSql: (e) =>
+      rawExpr: (e) =>
         new RawExpr({
           parts: e.parts.map((p) => (p instanceof ParamRef ? newRef : p)) as ReadonlyArray<
             string | AnyExpression
@@ -82,26 +76,26 @@ describe('ast/RawExpr', () => {
     expect((rewritten as RawExpr).parts[1]).toBe(newRef);
   });
 
-  it('returns self from rewrite when no rawSql arm is provided', () => {
+  it('returns self from rewrite when no rawExpr arm is provided', () => {
     const expr = new RawExpr({ parts: ['now()'], returns: returnsSpec });
     const rewritten = expr.rewrite({});
     expect(rewritten).toBe(expr);
   });
 
-  it('folds using the optional rawSql folder arm when provided', () => {
+  it('folds using the optional rawExpr folder arm when provided', () => {
     const ref = param(1, 'x');
     const expr = new RawExpr({ parts: ['prefix ', ref], returns: returnsSpec });
 
     const result = expr.fold<string>({
       empty: '',
       combine: (a, b) => `${a}+${b}`,
-      rawSql: (e) => `raw:${e.parts.length}`,
+      rawExpr: (e) => `raw:${e.parts.length}`,
     });
 
     expect(result).toBe('raw:2');
   });
 
-  it('falls back to empty when no rawSql folder arm is provided', () => {
+  it('falls back to empty when no rawExpr folder arm is provided', () => {
     const expr = new RawExpr({ parts: ['now()'], returns: returnsSpec });
 
     const result = expr.fold<string[]>({
@@ -127,14 +121,6 @@ describe('ast/RawExpr', () => {
     expect(collected).toContain(ref3);
   });
 
-  it('baseColumnRef throws the same message as AggregateExpr.count()', () => {
-    const rawExpr = new RawExpr({ parts: ['1'], returns: returnsSpec });
-    const countExpr = AggregateExpr.count();
-
-    expect(() => rawExpr.baseColumnRef()).toThrow('does not expose a base column reference');
-    expect(() => countExpr.baseColumnRef()).toThrow('does not expose a base column reference');
-  });
-
   it('preserves empty-string parts from back-to-back interpolations', () => {
     const a = lit(1);
     const b = lit(2);

packages/2-sql/4-lanes/relational-core/test/expression/create-raw-sql.test.ts

@@ -2,10 +2,10 @@ import { describe, expect, it } from 'vitest';
 import { ColumnRef, ParamRef, RawExpr, type RawSqlLiteral } from '../../src/exports/ast';
 import { buildOperation, createRawSql, param } from '../../src/exports/expression';
 
-// Stub adapter used throughout — applies simple type-based codec resolution.
+// Stub inferer used throughout — applies simple type-based codec resolution.
 // Safe-integer integers → 'test/int'; fractions / out-of-safe-int numbers → 'test/float';
 // bigint → 'test/bigint'; string → 'test/str'; boolean → 'test/bool'; Uint8Array → 'test/bytes'.
-const stubAdapter = {
+const stubInferer = {
   inferCodec(value: RawSqlLiteral): string {
     if (typeof value === 'bigint') return 'test/bigint';
     if (typeof value === 'string') return 'test/str';
@@ -18,7 +18,7 @@ const stubAdapter = {
   },
 };
 
-const rawSql = createRawSql(stubAdapter);
+const rawSql = createRawSql(stubInferer);
 
 describe('createRawSql factory', () => {
   describe('zero-interpolation template', () => {
@@ -47,8 +47,8 @@ describe('createRawSql factory', () => {
     });
   });
 
-  describe('bare RawSqlLiteral interpolation routes through adapter.inferCodec', () => {
-    it('wraps a number (safe integer) as a ParamRef with codec from adapter', () => {
+  describe('bare RawSqlLiteral interpolation routes through inferer.inferCodec', () => {
+    it('wraps a number (safe integer) as a ParamRef with codec from inferer', () => {
       const expr = rawSql`${42}`.returns('test/int');
       const rawExpr = expr.buildAst() as RawExpr;
       const part = rawExpr.parts[1];
@@ -57,7 +57,7 @@ describe('createRawSql factory', () => {
       expect((part as ParamRef).codec?.codecId).toBe('test/int');
     });
 
-    it('wraps a bigint as a ParamRef with codec from adapter', () => {
+    it('wraps a bigint as a ParamRef with codec from inferer', () => {
       const expr = rawSql`${9007199254740993n}`.returns('test/bigint');
       const rawExpr = expr.buildAst() as RawExpr;
       const part = rawExpr.parts[1];
@@ -66,7 +66,7 @@ describe('createRawSql factory', () => {
       expect((part as ParamRef).codec?.codecId).toBe('test/bigint');
     });
 
-    it('wraps a string as a ParamRef with codec from adapter', () => {
+    it('wraps a string as a ParamRef with codec from inferer', () => {
       const expr = rawSql`${'hello'}`.returns('test/str');
       const rawExpr = expr.buildAst() as RawExpr;
       const part = rawExpr.parts[1];
@@ -75,7 +75,7 @@ describe('createRawSql factory', () => {
       expect((part as ParamRef).codec?.codecId).toBe('test/str');
     });
 
-    it('wraps a boolean as a ParamRef with codec from adapter', () => {
+    it('wraps a boolean as a ParamRef with codec from inferer', () => {
       const expr = rawSql`${true}`.returns('test/bool');
       const rawExpr = expr.buildAst() as RawExpr;
       const part = rawExpr.parts[1];
@@ -84,7 +84,7 @@ describe('createRawSql factory', () => {
       expect((part as ParamRef).codec?.codecId).toBe('test/bool');
     });
 
-    it('wraps a Uint8Array as a ParamRef with codec from adapter', () => {
+    it('wraps a Uint8Array as a ParamRef with codec from inferer', () => {
       const bytes = new Uint8Array([1, 2, 3]);
       const expr = rawSql`${bytes}`.returns('test/bytes');
       const rawExpr = expr.buildAst() as RawExpr;
@@ -123,35 +123,35 @@ describe('createRawSql factory', () => {
     });
   });
 
-  describe('number boundary cases routed through adapter', () => {
-    it('routes a safe integer to test/int via stub adapter', () => {
+  describe('number boundary cases routed through inferer', () => {
+    it('routes a safe integer to test/int via stub inferer', () => {
       const expr = rawSql`${42}`.returns('test/int');
       const rawExpr = expr.buildAst() as RawExpr;
       expect((rawExpr.parts[1] as ParamRef).codec?.codecId).toBe('test/int');
     });
 
-    it('routes a fractional number to test/float via stub adapter', () => {
+    it('routes a fractional number to test/float via stub inferer', () => {
       const expr = rawSql`${1.5}`.returns('test/float');
       const rawExpr = expr.buildAst() as RawExpr;
       expect((rawExpr.parts[1] as ParamRef).codec?.codecId).toBe('test/float');
     });
 
-    it('routes a number beyond safe-integer range to test/float via stub adapter', () => {
+    it('routes a number beyond safe-integer range to test/float via stub inferer', () => {
       const beyondSafe = Number.MAX_SAFE_INTEGER + 1;
       const expr = rawSql`${beyondSafe}`.returns('test/float');
       const rawExpr = expr.buildAst() as RawExpr;
       expect((rawExpr.parts[1] as ParamRef).codec?.codecId).toBe('test/float');
     });
 
-    it('routes -0 to test/int via stub adapter (isSafeInteger(-0) is true)', () => {
+    it('routes -0 to test/int via stub inferer (isSafeInteger(-0) is true)', () => {
       const expr = rawSql`${-0}`.returns('test/int');
       const rawExpr = expr.buildAst() as RawExpr;
       expect((rawExpr.parts[1] as ParamRef).codec?.codecId).toBe('test/int');
     });
   });
 
   describe('param() override produces different codec than bare literal', () => {
-    it('bare 42 uses adapter-inferred codec while param(42, { codecId }) uses the specified one', () => {
+    it('bare 42 uses inferer-inferred codec while param(42, { codecId }) uses the specified one', () => {
       const withBare = rawSql`${42}`.returns('test/int').buildAst() as RawExpr;
       const withParam = rawSql`${param(42, { codecId: 'pg/int8' })}`
         .returns('test/int')
@@ -201,7 +201,7 @@ describe('createRawSql factory', () => {
     });
   });
 
-  describe('defence-in-depth throw for off-union values', () => {
+  describe('runtime throw when interpolating an off-union value via type cast', () => {
     type AnyTemplate = (
       strings: TemplateStringsArray,
       ...values: unknown[]

packages/2-sql/4-lanes/sql-builder/src/types/db.ts

@@ -1,6 +1,5 @@
 import type { StorageTable } from '@prisma-next/sql-contract/types';
-import type { DefaultScope } from '../scope';
-import type { ContractToQC, TableProxy } from './table-proxy';
+import type { TableProxy } from './table-proxy';
 
 export type CapabilitiesBase = Record<string, Record<string, boolean>>;
 
@@ -37,11 +36,5 @@ type TableInAnyNamespace<C extends TableProxyContract, Name extends string> = {
 }[keyof C['storage']['namespaces']];
 
 export type Db<C extends TableProxyContract> = {
-  [Name in TableNamesAcrossNamespaces<C>]: TableProxy<
-    C,
-    Name,
-    Name,
-    DefaultScope<Name, UnboundTables<C>[Name]>,
-    ContractToQC<C, Name>
-  >;
+  [Name in TableNamesAcrossNamespaces<C>]: TableProxy<C, Name>;
 };