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

package/src/ast/types.ts

@@ -1,4 +1,3 @@
-import type { PlanRefs } from '@prisma-next/contract/types';
 import type { ParamSpec } from '@prisma-next/operations';
 import type { SqlLoweringSpec } from '@prisma-next/sql-operations';
 
@@ -146,54 +145,89 @@ function collectParamRefsWith<TNode extends Expression>(node: TNode): ParamRef[]
   });
 }
 
-function sortRefs(
-  tables: ReadonlySet<string>,
-  columns: ReadonlyMap<string, { table: string; column: string }>,
-): PlanRefs {
-  const sortedTables = [...tables].sort((a, b) => a.localeCompare(b));
-  const sortedColumns = [...columns.values()].sort((a, b) => {
-    const tableCompare = a.table.localeCompare(b.table);
-    if (tableCompare !== 0) {
-      return tableCompare;
-    }
-    return a.column.localeCompare(b.column);
-  });
+function rewriteTableSource(table: TableSource, rewriter: AstRewriter): TableSource {
+  return rewriter.tableSource ? rewriter.tableSource(table) : table;
+}
 
-  return {
-    tables: sortedTables,
-    columns: sortedColumns,
-  };
-}
-
-function addColumnRefToRefSets(
-  columnRef: ColumnRef,
-  tables: Set<string>,
-  columns: Map<string, { table: string; column: string }>,
-): void {
-  if (columnRef.table === 'excluded') {
-    return;
-  }
-  tables.add(columnRef.table);
-  const key = `${columnRef.table}.${columnRef.column}`;
-  if (!columns.has(key)) {
-    columns.set(key, {
-      table: columnRef.table,
-      column: columnRef.column,
-    });
+function rewriteProjectionItem(item: ProjectionItem, rewriter: AstRewriter): ProjectionItem {
+  const rewrittenExpr =
+    item.expr.kind === 'literal'
+      ? rewriter.literal
+        ? rewriter.literal(item.expr)
+        : item.expr
+      : item.expr.rewrite(rewriter);
+  return new ProjectionItem(item.alias, rewrittenExpr, item.codecId, item.refs);
+}
+
+function rewriteInsertValue(value: InsertValue, rewriter: AstRewriter): InsertValue {
+  switch (value.kind) {
+    case 'param-ref':
+      return rewriter.paramRef ? rewriteParamRefForInsert(value, rewriter) : value;
+    case 'column-ref':
+      return rewriter.columnRef ? rewriteColumnRefForInsert(value, rewriter) : value;
+    case 'default-value':
+      return value;
+  }
+}
+
+function rewriteParamRefForInsert(value: ParamRef, rewriter: AstRewriter): InsertValue {
+  const rewritten = rewriter.paramRef ? rewriter.paramRef(value) : value;
+  return rewritten.kind === 'param-ref' ? rewritten : value;
+}
+
+function rewriteColumnRefForInsert(value: ColumnRef, rewriter: AstRewriter): InsertValue {
+  const rewritten = rewriter.columnRef ? rewriter.columnRef(value) : value;
+  return rewritten.kind === 'column-ref' ? rewritten : value;
+}
+
+function rewriteInsertRow(
+  row: Readonly<Record<string, InsertValue>>,
+  rewriter: AstRewriter,
+): Record<string, InsertValue> {
+  const result: Record<string, InsertValue> = {};
+  for (const [key, value] of Object.entries(row)) {
+    result[key] = rewriteInsertValue(value, rewriter);
+  }
+  return result;
+}
+
+function rewriteUpdateSetValue(
+  value: ColumnRef | ParamRef,
+  rewriter: AstRewriter,
+): ColumnRef | ParamRef {
+  if (value.kind === 'column-ref') {
+    const rewritten = rewriter.columnRef ? rewriter.columnRef(value) : value;
+    return rewritten.kind === 'column-ref' ? rewritten : value;
   }
+  const rewritten = rewriter.paramRef ? rewriter.paramRef(value) : value;
+  return rewritten.kind === 'param-ref' ? rewritten : value;
 }
 
-function mergeRefsInto(
-  refs: PlanRefs,
-  tables: Set<string>,
-  columns: Map<string, { table: string; column: string }>,
-): void {
-  for (const table of refs.tables ?? []) {
-    tables.add(table);
+function rewriteUpdateSet(
+  set: Readonly<Record<string, ColumnRef | ParamRef>>,
+  rewriter: AstRewriter,
+): Record<string, ColumnRef | ParamRef> {
+  const result: Record<string, ColumnRef | ParamRef> = {};
+  for (const [key, value] of Object.entries(set)) {
+    result[key] = rewriteUpdateSetValue(value, rewriter);
   }
-  for (const column of refs.columns ?? []) {
-    addColumnRefToRefSets(new ColumnRef(column.table, column.column), tables, columns);
+  return result;
+}
+
+function rewriteOnConflict(onConflict: InsertOnConflict, rewriter: AstRewriter): InsertOnConflict {
+  const columns = onConflict.columns.map((columnRef) => {
+    const rewritten = rewriter.columnRef ? rewriter.columnRef(columnRef) : columnRef;
+    return rewritten.kind === 'column-ref' ? rewritten : columnRef;
+  });
+
+  if (onConflict.action.kind === 'do-nothing') {
+    return new InsertOnConflict(columns, new DoNothingConflictAction());
   }
+
+  return new InsertOnConflict(
+    columns,
+    new DoUpdateSetConflictAction(rewriteUpdateSet(onConflict.action.set, rewriter)),
+  );
 }
 
 abstract class AstNode {
@@ -205,18 +239,11 @@ abstract class AstNode {
 }
 
 abstract class QueryAst extends AstNode {
-  abstract collectRefs(): PlanRefs;
   abstract collectParamRefs(): ParamRef[];
   abstract toQueryAst(): AnyQueryAst;
-
-  collectColumnRefs(): ColumnRef[] {
-    const refs = this.collectRefs().columns ?? [];
-    return refs.map((ref) => new ColumnRef(ref.table, ref.column));
-  }
 }
 
 abstract class FromSource extends AstNode {
-  abstract collectRefs(): PlanRefs;
   abstract rewrite(rewriter: AstRewriter): AnyFromSource;
   abstract toFromSource(): AnyFromSource;
 }
@@ -270,13 +297,6 @@ export class TableSource extends FromSource {
   override toFromSource(): AnyFromSource {
     return this;
   }
-
-  override collectRefs(): PlanRefs {
-    return {
-      tables: [this.name],
-      columns: [],
-    };
-  }
 }
 
 export interface TableRef {
@@ -300,9 +320,7 @@ export class DerivedTableSource extends FromSource {
     return new DerivedTableSource(alias, query);
   }
 
-  // Intentionally does not call rewriter.tableSource — derived tables are rewritten
-  // via their inner query, not intercepted at the FromSource level. A future
-  // fromSource?(source: AnyFromSource) callback would be needed for that.
+  // Intentionally does not call rewriter.tableSource — derived tables are rewritten via their inner query, not intercepted at the FromSource level. A future fromSource?(source: AnyFromSource) callback would be needed for that.
   override rewrite(rewriter: AstRewriter): AnyFromSource {
     return new DerivedTableSource(this.alias, this.query.rewrite(rewriter));
   }
@@ -310,10 +328,6 @@ export class DerivedTableSource extends FromSource {
   override toFromSource(): AnyFromSource {
     return this;
   }
-
-  override collectRefs(): PlanRefs {
-    return this.query.collectRefs();
-  }
 }
 
 export class ColumnRef extends Expression {
@@ -376,23 +390,37 @@ export class IdentifierRef extends Expression {
   }
 }
 
+/**
+ * Column ref carried by a {@link ParamRef} that was constructed at a column-bound site (e.g. an INSERT/UPDATE column assignment, a `WHERE column = $param` comparison). The encode-side dispatch path uses `refs` to call `contractCodecs.forColumn(refs.table, refs.column)`, which selects the per-instance parameterized codec for the column — required when a parameterized codec id is shared by multiple columns with distinct
+ * typeParams (e.g. `vector(1024)` vs. `vector(1536)`).
+ *
+ * `refs` may legitimately be `undefined` for `ParamRef`s constructed without a column context — the validator pass (`validateParamRefRefs`) treats refs-less ParamRefs as a hard error only when their codec id is parameterized.
+ */
+export interface ParamRefBindingRefs {
+  readonly table: string;
+  readonly column: string;
+}
+
 export class ParamRef extends Expression {
   readonly kind = 'param-ref' as const;
   readonly value: unknown;
   readonly name: string | undefined;
   readonly codecId: string | undefined;
+  readonly refs: ParamRefBindingRefs | undefined;
 
   constructor(
     value: unknown,
     options?: {
       name?: string;
       codecId?: string;
+      refs?: ParamRefBindingRefs;
     },
   ) {
     super();
     this.value = value;
     this.name = options?.name;
     this.codecId = options?.codecId;
+    this.refs = options?.refs ? Object.freeze({ ...options.refs }) : undefined;
     this.freeze();
   }
 
@@ -401,6 +429,7 @@ export class ParamRef extends Expression {
     options?: {
       name?: string;
       codecId?: string;
+      refs?: ParamRefBindingRefs;
     },
   ): ParamRef {
     return new ParamRef(value, options);
@@ -1052,16 +1081,33 @@ export class ProjectionItem extends AstNode {
   readonly kind = 'projection-item' as const;
   readonly alias: string;
   readonly expr: ProjectionExpr;
+  readonly codecId: string | undefined;
+  /**
+   * Column-bound metadata for the projection. Populated by builder paths that promote a top-level field shortcut (`select('email', ...)`) into a bare `IdentifierRef` AST while still knowing the originating `(table, column)`. Decode-side dispatch consults `refs` to call `forColumn(table, column)` so parameterized codec ids resolve to the per-instance codec — required when multiple columns share a codec id with distinct
+   * typeParams (e.g. `varchar(36)` vs. `varchar(255)`). Stays `undefined` for `column-ref` projections (the AST already carries the binding) and for non-column-bound projections (computed expressions, subqueries, raw aliases).
+   */
+  readonly refs: ParamRefBindingRefs | undefined;
 
-  constructor(alias: string, expr: ProjectionExpr) {
+  constructor(alias: string, expr: ProjectionExpr, codecId?: string, refs?: ParamRefBindingRefs) {
     super();
     this.alias = alias;
     this.expr = expr;
+    this.codecId = codecId;
+    this.refs = refs ? Object.freeze({ ...refs }) : undefined;
     this.freeze();
   }
 
-  static of(alias: string, expr: ProjectionExpr): ProjectionItem {
-    return new ProjectionItem(alias, expr);
+  static of(
+    alias: string,
+    expr: ProjectionExpr,
+    codecId?: string,
+    refs?: ParamRefBindingRefs,
+  ): ProjectionItem {
+    return new ProjectionItem(alias, expr, codecId, refs);
+  }
+
+  withCodecId(codecId: string | undefined): ProjectionItem {
+    return new ProjectionItem(this.alias, this.expr, codecId, this.refs);
   }
 }
 
@@ -1218,6 +1264,8 @@ export class SelectAst extends QueryAst {
                 ? rewriter.literal(projection.expr)
                 : projection.expr
               : projection.expr.rewrite(rewriter),
+            projection.codecId,
+            projection.refs,
           ),
       ),
       where: this.where?.rewrite(rewriter),
@@ -1234,7 +1282,7 @@ export class SelectAst extends QueryAst {
     return rewriter.select ? rewriter.select(rewritten) : rewritten;
   }
 
-  override collectColumnRefs(): ColumnRef[] {
+  collectColumnRefs(): ColumnRef[] {
     const refs: ColumnRef[] = [];
     const pushRefs = (columns: ReadonlyArray<ColumnRef>) => {
       refs.push(...columns);
@@ -1322,35 +1370,6 @@ export class SelectAst extends QueryAst {
     return refs;
   }
 
-  override collectRefs(): PlanRefs {
-    const tables = new Set<string>();
-    const columns = new Map<string, { table: string; column: string }>();
-
-    const addSource = (source: AnyFromSource) => {
-      mergeRefsInto(source.collectRefs(), tables, columns);
-    };
-
-    addSource(this.from);
-
-    for (const join of this.joins ?? []) {
-      addSource(join.source);
-      if (join.on.kind === 'eq-col-join-on') {
-        addColumnRefToRefSets(join.on.left, tables, columns);
-        addColumnRefToRefSets(join.on.right, tables, columns);
-      } else {
-        for (const columnRef of join.on.collectColumnRefs()) {
-          addColumnRefToRefSets(columnRef, tables, columns);
-        }
-      }
-    }
-
-    for (const columnRef of this.collectColumnRefs()) {
-      addColumnRefToRefSets(columnRef, tables, columns);
-    }
-
-    return sortRefs(tables, columns);
-  }
-
   override toQueryAst(): AnyQueryAst {
     return this;
   }
@@ -1418,13 +1437,13 @@ export class InsertAst extends QueryAst {
   readonly table: TableSource;
   readonly rows: ReadonlyArray<Readonly<Record<string, InsertValue>>>;
   readonly onConflict: InsertOnConflict | undefined;
-  readonly returning: ReadonlyArray<ColumnRef> | undefined;
+  readonly returning: ReadonlyArray<ProjectionItem> | undefined;
 
   constructor(
     table: TableSource,
     rows: ReadonlyArray<Record<string, InsertValue>> = [{}],
     onConflict?: InsertOnConflict,
-    returning?: ReadonlyArray<ColumnRef>,
+    returning?: ReadonlyArray<ProjectionItem>,
   ) {
     super();
     this.table = table;
@@ -1451,7 +1470,7 @@ export class InsertAst extends QueryAst {
     );
   }
 
-  withReturning(returning: ReadonlyArray<ColumnRef> | undefined): InsertAst {
+  withReturning(returning: ReadonlyArray<ProjectionItem> | undefined): InsertAst {
     return new InsertAst(
       this.table,
       this.rows.map((row) => ({ ...row })),
@@ -1469,6 +1488,15 @@ export class InsertAst extends QueryAst {
     );
   }
 
+  rewrite(rewriter: AstRewriter): InsertAst {
+    return new InsertAst(
+      rewriteTableSource(this.table, rewriter),
+      this.rows.map((row) => rewriteInsertRow(row, rewriter)),
+      this.onConflict ? rewriteOnConflict(this.onConflict, rewriter) : undefined,
+      this.returning?.map((item) => rewriteProjectionItem(item, rewriter)),
+    );
+  }
+
   override collectParamRefs(): ParamRef[] {
     const refs: ParamRef[] = [];
     for (const row of this.rows) {
@@ -1485,44 +1513,12 @@ export class InsertAst extends QueryAst {
         }
       }
     }
-    return refs;
-  }
-
-  override collectRefs(): PlanRefs {
-    const tables = new Set<string>([this.table.name]);
-    const columns = new Map<string, { table: string; column: string }>();
-
-    const addColumn = (columnRef: ColumnRef) => addColumnRefToRefSets(columnRef, tables, columns);
-    const addValue = (value: InsertValue) => {
-      if (value.kind === 'column-ref') {
-        addColumn(value);
-      }
-    };
-
-    for (const row of this.rows) {
-      for (const value of Object.values(row)) {
-        addValue(value);
+    for (const item of this.returning ?? []) {
+      if (item.expr.kind !== 'literal') {
+        refs.push(...item.expr.collectParamRefs());
       }
     }
-
-    for (const columnRef of this.returning ?? []) {
-      addColumn(columnRef);
-    }
-
-    if (this.onConflict) {
-      for (const columnRef of this.onConflict.columns) {
-        addColumn(columnRef);
-      }
-      if (this.onConflict.action.kind === 'do-update-set') {
-        for (const value of Object.values(this.onConflict.action.set)) {
-          if (value.kind === 'column-ref') {
-            addColumn(value);
-          }
-        }
-      }
-    }
-
-    return sortRefs(tables, columns);
+    return refs;
   }
 
   override toQueryAst(): AnyQueryAst {
@@ -1535,13 +1531,13 @@ export class UpdateAst extends QueryAst {
   readonly table: TableSource;
   readonly set: Readonly<Record<string, ColumnRef | ParamRef>>;
   readonly where: AnyExpression | undefined;
-  readonly returning: ReadonlyArray<ColumnRef> | undefined;
+  readonly returning: ReadonlyArray<ProjectionItem> | undefined;
 
   constructor(
     table: TableSource,
     set: Readonly<Record<string, ColumnRef | ParamRef>> = {},
     where?: AnyExpression,
-    returning?: ReadonlyArray<ColumnRef>,
+    returning?: ReadonlyArray<ProjectionItem>,
   ) {
     super();
     this.table = table;
@@ -1563,10 +1559,19 @@ export class UpdateAst extends QueryAst {
     return new UpdateAst(this.table, this.set, where, this.returning);
   }
 
-  withReturning(returning: ReadonlyArray<ColumnRef> | undefined): UpdateAst {
+  withReturning(returning: ReadonlyArray<ProjectionItem> | undefined): UpdateAst {
     return new UpdateAst(this.table, this.set, this.where, returning);
   }
 
+  rewrite(rewriter: AstRewriter): UpdateAst {
+    return new UpdateAst(
+      rewriteTableSource(this.table, rewriter),
+      rewriteUpdateSet(this.set, rewriter),
+      this.where?.rewrite(rewriter),
+      this.returning?.map((item) => rewriteProjectionItem(item, rewriter)),
+    );
+  }
+
   override collectParamRefs(): ParamRef[] {
     const refs: ParamRef[] = [];
     for (const value of Object.values(this.set)) {
@@ -1577,28 +1582,12 @@ export class UpdateAst extends QueryAst {
     if (this.where) {
       refs.push(...this.where.collectParamRefs());
     }
-    return refs;
-  }
-
-  override collectRefs(): PlanRefs {
-    const tables = new Set<string>([this.table.name]);
-    const columns = new Map<string, { table: string; column: string }>();
-
-    for (const value of Object.values(this.set)) {
-      if (value.kind === 'column-ref') {
-        addColumnRefToRefSets(value, tables, columns);
+    for (const item of this.returning ?? []) {
+      if (item.expr.kind !== 'literal') {
+        refs.push(...item.expr.collectParamRefs());
       }
     }
-
-    for (const columnRef of this.where?.collectColumnRefs() ?? []) {
-      addColumnRefToRefSets(columnRef, tables, columns);
-    }
-
-    for (const columnRef of this.returning ?? []) {
-      addColumnRefToRefSets(columnRef, tables, columns);
-    }
-
-    return sortRefs(tables, columns);
+    return refs;
   }
 
   override toQueryAst(): AnyQueryAst {
@@ -1610,9 +1599,13 @@ export class DeleteAst extends QueryAst {
   readonly kind = 'delete' as const;
   readonly table: TableSource;
   readonly where: AnyExpression | undefined;
-  readonly returning: ReadonlyArray<ColumnRef> | undefined;
+  readonly returning: ReadonlyArray<ProjectionItem> | undefined;
 
-  constructor(table: TableSource, where?: AnyExpression, returning?: ReadonlyArray<ColumnRef>) {
+  constructor(
+    table: TableSource,
+    where?: AnyExpression,
+    returning?: ReadonlyArray<ProjectionItem>,
+  ) {
     super();
     this.table = table;
     this.where = where;
@@ -1628,27 +1621,82 @@ export class DeleteAst extends QueryAst {
     return new DeleteAst(this.table, where, this.returning);
   }
 
-  withReturning(returning: ReadonlyArray<ColumnRef> | undefined): DeleteAst {
+  withReturning(returning: ReadonlyArray<ProjectionItem> | undefined): DeleteAst {
     return new DeleteAst(this.table, this.where, returning);
   }
 
+  rewrite(rewriter: AstRewriter): DeleteAst {
+    return new DeleteAst(
+      rewriteTableSource(this.table, rewriter),
+      this.where?.rewrite(rewriter),
+      this.returning?.map((item) => rewriteProjectionItem(item, rewriter)),
+    );
+  }
+
   override collectParamRefs(): ParamRef[] {
-    return this.where?.collectParamRefs() ?? [];
+    const refs: ParamRef[] = [];
+    if (this.where) {
+      refs.push(...this.where.collectParamRefs());
+    }
+    for (const item of this.returning ?? []) {
+      if (item.expr.kind !== 'literal') {
+        refs.push(...item.expr.collectParamRefs());
+      }
+    }
+    return refs;
   }
 
-  override collectRefs(): PlanRefs {
-    const tables = new Set<string>([this.table.name]);
-    const columns = new Map<string, { table: string; column: string }>();
+  override toQueryAst(): AnyQueryAst {
+    return this;
+  }
+}
 
-    for (const columnRef of this.where?.collectColumnRefs() ?? []) {
-      addColumnRefToRefSets(columnRef, tables, columns);
+/**
+ * Raw-SQL query AST node carrying interpolated parameter / expression nodes
+ * embedded inside literal SQL fragments.
+ *
+ * `fragments` and `args` are interleaved during lowering:
+ * `fragments[0] + lower(args[0]) + fragments[1] + ... + fragments[n]`.
+ * Construction enforces `fragments.length === args.length + 1`.
+ *
+ * Extends {@link QueryAst} (whole-query AST, not a sub-expression).
+ * Construction does not validate that each arg is a `ParamRef` /
+ * `AnyExpression`: the type system already rejects bare values because
+ * `args` is typed `readonly AnyExpression[]`. The user-facing `raw\`...\``
+ * factory (separate `sql-raw-factory` component) layers stricter
+ * type-level rejection on top of this AST node.
+ */
+export class RawSqlExpr extends QueryAst {
+  readonly kind = 'raw-sql' as const;
+  readonly fragments: readonly string[];
+  readonly args: readonly AnyExpression[];
+
+  constructor(fragments: readonly string[], args: readonly AnyExpression[]) {
+    super();
+    if (fragments.length !== args.length + 1) {
+      throw new Error(
+        `RawSqlExpr: fragments.length must equal args.length + 1 (got fragments=${fragments.length}, args=${args.length})`,
+      );
     }
+    this.fragments = Object.freeze([...fragments]);
+    this.args = Object.freeze([...args]);
+    this.freeze();
+  }
 
-    for (const columnRef of this.returning ?? []) {
-      addColumnRefToRefSets(columnRef, tables, columns);
-    }
+  static of(fragments: readonly string[], args: readonly AnyExpression[]): RawSqlExpr {
+    return new RawSqlExpr(fragments, args);
+  }
 
-    return sortRefs(tables, columns);
+  override collectParamRefs(): ParamRef[] {
+    const refs: ParamRef[] = [];
+    for (const arg of this.args) {
+      if (arg.kind === 'param-ref') {
+        refs.push(arg);
+      } else {
+        refs.push(...arg.collectParamRefs());
+      }
+    }
+    return refs;
   }
 
   override toQueryAst(): AnyQueryAst {
@@ -1656,7 +1704,7 @@ export class DeleteAst extends QueryAst {
   }
 }
 
-export type AnyQueryAst = SelectAst | InsertAst | UpdateAst | DeleteAst;
+export type AnyQueryAst = SelectAst | InsertAst | UpdateAst | DeleteAst | RawSqlExpr;
 export type AnyFromSource = TableSource | DerivedTableSource;
 export type AnyExpression =
   | ColumnRef
@@ -1684,6 +1732,7 @@ export const queryAstKinds: ReadonlySet<string> = new Set<AnyQueryAst['kind']>([
   'insert',
   'update',
   'delete',
+  'raw-sql',
 ]);
 export const whereExprKinds: ReadonlySet<string> = new Set<AnyExpression['kind']>([
   'binary',

package/src/ast/util.ts

@@ -1,3 +1,5 @@
+import type { AnyQueryAst, ParamRef } from './types';
+
 export function compact<T extends Record<string, unknown>>(o: T): T {
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(o)) {
@@ -7,3 +9,24 @@ export function compact<T extends Record<string, unknown>>(o: T): T {
   }
   return out as T;
 }
+
+/**
+ * Walks an AST's parameter references in first-encounter order and dedupes
+ * by ParamRef identity. The single canonical helper used by every consumer
+ * that aligns `plan.params` with metadata-by-index — the SQL builder lane,
+ * the SQL ORM client, the SQL runtime encoder, and the Postgres renderer's
+ * `$N` index map — so the four walks cannot drift in dedupe semantics.
+ *
+ * SQLite's `?`-placeholder renderer intentionally does NOT use this helper
+ * because it needs one params entry per occurrence in the SQL.
+ */
+export function collectOrderedParamRefs(ast: AnyQueryAst): ReadonlyArray<ParamRef> {
+  const seen = new Set<ParamRef>();
+  const ordered: ParamRef[] = [];
+  for (const ref of ast.collectParamRefs()) {
+    if (seen.has(ref)) continue;
+    seen.add(ref);
+    ordered.push(ref);
+  }
+  return Object.freeze(ordered);
+}

package/src/ast/validate-param-refs.ts

@@ -0,0 +1,39 @@
+/**
+ * Builder-pipeline validator pass: every {@link ParamRef} whose `codecId` resolves to a *parameterized* descriptor must carry `refs: { table, column }` so encode-side dispatch can call `contractCodecs.forColumn(table, column)`. Refs-less parameterized `ParamRef`s are a hard error — the codec-id-keyed `forCodecId` fallback cannot disambiguate per-instance codecs (e.g. `vector(1024)` vs. `vector(1536)`), so the dispatch
+ * path must reject them at validation time rather than silently bind to the wrong instance.
+ *
+ * Non-parameterized codec ids (the `voidParamsSchema` case) are always dispatch-safe via codec id alone, so refs-less ParamRefs for those ids are accepted unchanged.
+ *
+ * The pass runs post-build / pre-execute — the natural location is the SQL runtime's `lower()` step, between any `beforeCompile` rewrites and `encodeParams`. See AC-5 in the codec-registry-unification spec.
+ */
+
+import { runtimeError } from '@prisma-next/framework-components/runtime';
+import type { CodecDescriptorRegistry } from '../query-lane-context';
+import type { AnyQueryAst, ParamRef } from './types';
+import { collectOrderedParamRefs } from './util';
+
+/**
+ * Validate that every parameterized-codec `ParamRef` in `plan` carries `refs`. Throws `RUNTIME.PARAM_REF_REFS_REQUIRED` (a runtime envelope) naming the codec id and the binding label when the invariant is violated. Returns the plan unchanged on success — callers that prefer a side-effecting assertion can ignore the return value.
+ *
+ * The `registry` is consulted via `descriptorFor(codecId).isParameterized` — `true` whenever the descriptor's `paramsSchema` is not the singleton `voidParamsSchema`.
+ */
+export function validateParamRefRefs(plan: AnyQueryAst, registry: CodecDescriptorRegistry): void {
+  for (const ref of collectOrderedParamRefs(plan)) {
+    diagnoseRef(ref, registry);
+  }
+}
+
+function diagnoseRef(ref: ParamRef, registry: CodecDescriptorRegistry): void {
+  if (!ref.codecId) return;
+  const descriptor = registry.descriptorFor(ref.codecId);
+  if (descriptor === undefined) return;
+  if (!descriptor.isParameterized) return;
+  if (ref.refs) return;
+
+  const label = ref.name ?? '<anonymous>';
+  throw runtimeError(
+    'RUNTIME.PARAM_REF_REFS_REQUIRED',
+    `ParamRef '${label}' for parameterized codec '${ref.codecId}' is missing column refs; column-aware dispatch requires { table, column } at the binding site.`,
+    { codecId: ref.codecId, paramName: ref.name },
+  );
+}