@prisma-next/sql-relational-core 0.5.0-dev.60 → 0.5.0-dev.61

package/src/ast/sql-codec-helpers.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared encode/decode/render constants and codec id literals for the six SQL base codecs (`sql/char@1`, `sql/varchar@1`, `sql/int@1`, `sql/float@1`, `sql/text@1`, `sql/timestamp@1`).
+ *
+ * The codec implementations live in `sql-codecs.ts` (TML-2357). This module retains only the conversion helpers + emit-path renderers the codec methods compose with — keeping a single source of truth for non-trivial conversions while the codec methods provide the framework-required `Promise<…>` boundary.
+ */
+
+import type { JsonValue } from '@prisma-next/contract/types';
+
+export const SQL_CHAR_CODEC_ID = 'sql/char@1' as const;
+export const SQL_VARCHAR_CODEC_ID = 'sql/varchar@1' as const;
+export const SQL_INT_CODEC_ID = 'sql/int@1' as const;
+export const SQL_FLOAT_CODEC_ID = 'sql/float@1' as const;
+export const SQL_TEXT_CODEC_ID = 'sql/text@1' as const;
+export const SQL_TIMESTAMP_CODEC_ID = 'sql/timestamp@1' as const;
+
+export const sqlCharEncode = (value: string): string => value;
+export const sqlCharDecode = (wire: string): string => wire.trimEnd();
+export const sqlCharRenderOutputType = (typeParams: { readonly length?: number }) => {
+  const length = typeParams.length;
+  if (length === undefined) return undefined;
+  if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
+    throw new Error(
+      `renderOutputType: expected integer "length" in typeParams for Char, got ${String(length)}`,
+    );
+  }
+  return `Char<${length}>`;
+};
+
+export const sqlVarcharEncode = (value: string): string => value;
+export const sqlVarcharDecode = (wire: string): string => wire;
+export const sqlVarcharRenderOutputType = (typeParams: { readonly length?: number }) => {
+  const length = typeParams.length;
+  if (length === undefined) return undefined;
+  if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
+    throw new Error(
+      `renderOutputType: expected integer "length" in typeParams for Varchar, got ${String(length)}`,
+    );
+  }
+  return `Varchar<${length}>`;
+};
+
+export const sqlIntEncode = (value: number): number => value;
+export const sqlIntDecode = (wire: number): number => wire;
+
+export const sqlFloatEncode = (value: number): number => value;
+export const sqlFloatDecode = (wire: number): number => wire;
+
+export const sqlTextEncode = (value: string): string => value;
+export const sqlTextDecode = (wire: string): string => wire;
+
+export const sqlTimestampEncode = (value: Date): Date => value;
+export const sqlTimestampDecode = (wire: Date): Date => wire;
+export const sqlTimestampEncodeJson = (value: Date): JsonValue => value.toISOString();
+export const sqlTimestampDecodeJson = (json: JsonValue): Date => {
+  if (typeof json !== 'string') {
+    throw new Error(`Expected ISO date string for sql/timestamp@1, got ${typeof json}`);
+  }
+  const date = new Date(json);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`Invalid ISO date string for sql/timestamp@1: ${json}`);
+  }
+  return date;
+};
+export const sqlTimestampRenderOutputType = (typeParams: { readonly precision?: number }) => {
+  const precision = typeParams.precision;
+  if (precision === undefined) {
+    return 'Timestamp';
+  }
+  if (
+    typeof precision !== 'number' ||
+    !Number.isFinite(precision) ||
+    !Number.isInteger(precision)
+  ) {
+    throw new Error(
+      `renderOutputType: expected integer "precision" in typeParams for Timestamp, got ${String(precision)}`,
+    );
+  }
+  return `Timestamp<${precision}>`;
+};

package/src/ast/sql-codecs.ts

@@ -1,159 +1,302 @@
+/**
+ * The six SQL base codecs (TML-2357).
+ *
+ * Each codec ships as three artifacts:
+ *
+ * 1. A `SqlXCodec` class extending {@link CodecImpl} that wraps the module-level encode/decode constants exported from `sql-codec-helpers.ts` (the single source of truth for runtime behaviour). 2. A `SqlXDescriptor` class extending {@link CodecDescriptorImpl} declaring the codec id, traits, target types, params schema, and (where applicable) the emit-path `renderOutputType`. 3. A per-codec column helper (`sqlXColumn`)
+ * that calls `descriptor.factory(...)` directly and packages the result into a {@link ColumnSpec} via the framework {@link column} packager. The helper is tied to its descriptor with `satisfies ColumnHelperFor`.
+ *
+ * After TML-2357 this file is the canonical source of SQL base codec metadata and runtime behaviour — the legacy `mkCodec` / `defineCodec` carriers retired with the deletion sweep.
+ */
+
 import type { JsonValue } from '@prisma-next/contract/types';
+import {
+  type CodecCallContext,
+  CodecDescriptorImpl,
+  CodecImpl,
+  type CodecInstanceContext,
+  type ColumnHelperFor,
+  type ColumnHelperForStrict,
+  column,
+  voidParamsSchema,
+} from '@prisma-next/framework-components/codec';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import { type as arktype } from 'arktype';
-import { codec, defineCodecs } from './codec-types';
+import {
+  SQL_CHAR_CODEC_ID,
+  SQL_FLOAT_CODEC_ID,
+  SQL_INT_CODEC_ID,
+  SQL_TEXT_CODEC_ID,
+  SQL_TIMESTAMP_CODEC_ID,
+  SQL_VARCHAR_CODEC_ID,
+  sqlCharDecode,
+  sqlCharEncode,
+  sqlCharRenderOutputType,
+  sqlFloatDecode,
+  sqlFloatEncode,
+  sqlIntDecode,
+  sqlIntEncode,
+  sqlTextDecode,
+  sqlTextEncode,
+  sqlTimestampDecode,
+  sqlTimestampDecodeJson,
+  sqlTimestampEncode,
+  sqlTimestampEncodeJson,
+  sqlTimestampRenderOutputType,
+  sqlVarcharDecode,
+  sqlVarcharEncode,
+  sqlVarcharRenderOutputType,
+} from './sql-codec-helpers';
 
-export const SQL_CHAR_CODEC_ID = 'sql/char@1' as const;
-export const SQL_VARCHAR_CODEC_ID = 'sql/varchar@1' as const;
-export const SQL_INT_CODEC_ID = 'sql/int@1' as const;
-export const SQL_FLOAT_CODEC_ID = 'sql/float@1' as const;
-export const SQL_TEXT_CODEC_ID = 'sql/text@1' as const;
-export const SQL_TIMESTAMP_CODEC_ID = 'sql/timestamp@1' as const;
+type LengthParams = { readonly length?: number };
+type PrecisionParams = { readonly precision?: number };
 
 const lengthParamsSchema = arktype({
-  length: 'number.integer > 0',
-});
+  'length?': 'number.integer > 0',
+}) satisfies StandardSchemaV1<LengthParams>;
 
 const precisionParamsSchema = arktype({
   'precision?': 'number.integer >= 0 & number.integer <= 6',
-});
-
-type LengthTypeHelper = {
-  readonly kind: 'fixed' | 'variable';
-  readonly maxLength: number;
-};
-
-function createLengthTypeHelper(
-  kind: LengthTypeHelper['kind'],
-): (params: Record<string, unknown>) => LengthTypeHelper {
-  return (params) => ({
-    kind,
-    maxLength: params['length'] as number,
-  });
+}) satisfies StandardSchemaV1<PrecisionParams>;
+
+export class SqlTextCodec extends CodecImpl<
+  typeof SQL_TEXT_CODEC_ID,
+  readonly ['equality', 'order', 'textual'],
+  string,
+  string
+> {
+  async encode(value: string, _ctx: CodecCallContext): Promise<string> {
+    return sqlTextEncode(value);
+  }
+  async decode(wire: string, _ctx: CodecCallContext): Promise<string> {
+    return sqlTextDecode(wire);
+  }
+  encodeJson(value: string): JsonValue {
+    return value;
+  }
+  decodeJson(json: JsonValue): string {
+    return json as string;
+  }
+}
+
+export class SqlTextDescriptor extends CodecDescriptorImpl<void> {
+  override readonly codecId = SQL_TEXT_CODEC_ID;
+  override readonly traits = ['equality', 'order', 'textual'] as const;
+  override readonly targetTypes = ['text'] as const;
+  override readonly paramsSchema: StandardSchemaV1<void> = voidParamsSchema;
+  override factory(): (ctx: CodecInstanceContext) => SqlTextCodec {
+    return () => new SqlTextCodec(this);
+  }
+}
+
+export const sqlTextDescriptor = new SqlTextDescriptor();
+
+export const sqlTextColumn = () =>
+  column(sqlTextDescriptor.factory(), sqlTextDescriptor.codecId, undefined, 'text');
+
+sqlTextColumn satisfies ColumnHelperFor<SqlTextDescriptor>;
+sqlTextColumn satisfies ColumnHelperForStrict<SqlTextDescriptor>;
+
+export class SqlIntCodec extends CodecImpl<
+  typeof SQL_INT_CODEC_ID,
+  readonly ['equality', 'order', 'numeric'],
+  number,
+  number
+> {
+  async encode(value: number, _ctx: CodecCallContext): Promise<number> {
+    return sqlIntEncode(value);
+  }
+  async decode(wire: number, _ctx: CodecCallContext): Promise<number> {
+    return sqlIntDecode(wire);
+  }
+  encodeJson(value: number): JsonValue {
+    return value;
+  }
+  decodeJson(json: JsonValue): number {
+    return json as number;
+  }
+}
+
+export class SqlIntDescriptor extends CodecDescriptorImpl<void> {
+  override readonly codecId = SQL_INT_CODEC_ID;
+  override readonly traits = ['equality', 'order', 'numeric'] as const;
+  override readonly targetTypes = ['int'] as const;
+  override readonly paramsSchema: StandardSchemaV1<void> = voidParamsSchema;
+  override factory(): (ctx: CodecInstanceContext) => SqlIntCodec {
+    return () => new SqlIntCodec(this);
+  }
 }
 
-const sqlCharCodec = codec<
+export const sqlIntDescriptor = new SqlIntDescriptor();
+
+export const sqlIntColumn = () =>
+  column(sqlIntDescriptor.factory(), sqlIntDescriptor.codecId, undefined, 'int');
+
+sqlIntColumn satisfies ColumnHelperFor<SqlIntDescriptor>;
+sqlIntColumn satisfies ColumnHelperForStrict<SqlIntDescriptor>;
+
+export class SqlFloatCodec extends CodecImpl<
+  typeof SQL_FLOAT_CODEC_ID,
+  readonly ['equality', 'order', 'numeric'],
+  number,
+  number
+> {
+  async encode(value: number, _ctx: CodecCallContext): Promise<number> {
+    return sqlFloatEncode(value);
+  }
+  async decode(wire: number, _ctx: CodecCallContext): Promise<number> {
+    return sqlFloatDecode(wire);
+  }
+  encodeJson(value: number): JsonValue {
+    return value;
+  }
+  decodeJson(json: JsonValue): number {
+    return json as number;
+  }
+}
+
+export class SqlFloatDescriptor extends CodecDescriptorImpl<void> {
+  override readonly codecId = SQL_FLOAT_CODEC_ID;
+  override readonly traits = ['equality', 'order', 'numeric'] as const;
+  override readonly targetTypes = ['float'] as const;
+  override readonly paramsSchema: StandardSchemaV1<void> = voidParamsSchema;
+  override factory(): (ctx: CodecInstanceContext) => SqlFloatCodec {
+    return () => new SqlFloatCodec(this);
+  }
+}
+
+export const sqlFloatDescriptor = new SqlFloatDescriptor();
+
+export const sqlFloatColumn = () =>
+  column(sqlFloatDescriptor.factory(), sqlFloatDescriptor.codecId, undefined, 'float');
+
+sqlFloatColumn satisfies ColumnHelperFor<SqlFloatDescriptor>;
+sqlFloatColumn satisfies ColumnHelperForStrict<SqlFloatDescriptor>;
+
+export class SqlCharCodec extends CodecImpl<
   typeof SQL_CHAR_CODEC_ID,
   readonly ['equality', 'order', 'textual'],
   string,
   string
->({
-  typeId: SQL_CHAR_CODEC_ID,
-  targetTypes: ['char'],
-  traits: ['equality', 'order', 'textual'],
-  encode: (value: string): string => value,
-  decode: (wire: string): string => wire.trimEnd(),
-  paramsSchema: lengthParamsSchema,
-  init: createLengthTypeHelper('fixed'),
-  renderOutputType: (typeParams) => {
-    const length = typeParams['length'];
-    if (length === undefined) return undefined;
-    if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
-      throw new Error(
-        `renderOutputType: expected integer "length" in typeParams for Char, got ${String(length)}`,
-      );
-    }
-    return `Char<${length}>`;
-  },
-});
-
-const sqlVarcharCodec = codec<
+> {
+  async encode(value: string, _ctx: CodecCallContext): Promise<string> {
+    return sqlCharEncode(value);
+  }
+  async decode(wire: string, _ctx: CodecCallContext): Promise<string> {
+    return sqlCharDecode(wire);
+  }
+  encodeJson(value: string): JsonValue {
+    return value;
+  }
+  decodeJson(json: JsonValue): string {
+    return json as string;
+  }
+}
+
+export class SqlCharDescriptor extends CodecDescriptorImpl<LengthParams> {
+  override readonly codecId = SQL_CHAR_CODEC_ID;
+  override readonly traits = ['equality', 'order', 'textual'] as const;
+  override readonly targetTypes = ['char'] as const;
+  override readonly paramsSchema: StandardSchemaV1<LengthParams> = lengthParamsSchema;
+  override renderOutputType(params: LengthParams): string | undefined {
+    return sqlCharRenderOutputType(params);
+  }
+  override factory(_params: LengthParams): (ctx: CodecInstanceContext) => SqlCharCodec {
+    return () => new SqlCharCodec(this);
+  }
+}
+
+export const sqlCharDescriptor = new SqlCharDescriptor();
+
+export const sqlCharColumn = (params: LengthParams = {}) =>
+  column(sqlCharDescriptor.factory(params), sqlCharDescriptor.codecId, params, 'char');
+
+sqlCharColumn satisfies ColumnHelperFor<SqlCharDescriptor>;
+sqlCharColumn satisfies ColumnHelperForStrict<SqlCharDescriptor>;
+
+export class SqlVarcharCodec extends CodecImpl<
   typeof SQL_VARCHAR_CODEC_ID,
   readonly ['equality', 'order', 'textual'],
   string,
   string
->({
-  typeId: SQL_VARCHAR_CODEC_ID,
-  targetTypes: ['varchar'],
-  traits: ['equality', 'order', 'textual'],
-  encode: (value: string): string => value,
-  decode: (wire: string): string => wire,
-  paramsSchema: lengthParamsSchema,
-  init: createLengthTypeHelper('variable'),
-  renderOutputType: (typeParams) => {
-    const length = typeParams['length'];
-    if (length === undefined) return undefined;
-    if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
-      throw new Error(
-        `renderOutputType: expected integer "length" in typeParams for Varchar, got ${String(length)}`,
-      );
-    }
-    return `Varchar<${length}>`;
-  },
-});
-
-const sqlIntCodec = codec({
-  typeId: SQL_INT_CODEC_ID,
-  targetTypes: ['int'],
-  traits: ['equality', 'order', 'numeric'],
-  encode: (value: number): number => value,
-  decode: (wire: number): number => wire,
-});
-
-const sqlFloatCodec = codec({
-  typeId: SQL_FLOAT_CODEC_ID,
-  targetTypes: ['float'],
-  traits: ['equality', 'order', 'numeric'],
-  encode: (value: number): number => value,
-  decode: (wire: number): number => wire,
-});
-
-const sqlTextCodec = codec({
-  typeId: SQL_TEXT_CODEC_ID,
-  targetTypes: ['text'],
-  traits: ['equality', 'order', 'textual'],
-  encode: (value: string): string => value,
-  decode: (wire: string): string => wire,
-});
-
-const sqlTimestampCodec = codec<
+> {
+  async encode(value: string, _ctx: CodecCallContext): Promise<string> {
+    return sqlVarcharEncode(value);
+  }
+  async decode(wire: string, _ctx: CodecCallContext): Promise<string> {
+    return sqlVarcharDecode(wire);
+  }
+  encodeJson(value: string): JsonValue {
+    return value;
+  }
+  decodeJson(json: JsonValue): string {
+    return json as string;
+  }
+}
+
+export class SqlVarcharDescriptor extends CodecDescriptorImpl<LengthParams> {
+  override readonly codecId = SQL_VARCHAR_CODEC_ID;
+  override readonly traits = ['equality', 'order', 'textual'] as const;
+  override readonly targetTypes = ['varchar'] as const;
+  override readonly paramsSchema: StandardSchemaV1<LengthParams> = lengthParamsSchema;
+  override renderOutputType(params: LengthParams): string | undefined {
+    return sqlVarcharRenderOutputType(params);
+  }
+  override factory(_params: LengthParams): (ctx: CodecInstanceContext) => SqlVarcharCodec {
+    return () => new SqlVarcharCodec(this);
+  }
+}
+
+export const sqlVarcharDescriptor = new SqlVarcharDescriptor();
+
+export const sqlVarcharColumn = (params: LengthParams = {}) =>
+  column(sqlVarcharDescriptor.factory(params), sqlVarcharDescriptor.codecId, params, 'varchar');
+
+sqlVarcharColumn satisfies ColumnHelperFor<SqlVarcharDescriptor>;
+sqlVarcharColumn satisfies ColumnHelperForStrict<SqlVarcharDescriptor>;
+
+export class SqlTimestampCodec extends CodecImpl<
   typeof SQL_TIMESTAMP_CODEC_ID,
   readonly ['equality', 'order'],
   Date,
   Date
->({
-  typeId: SQL_TIMESTAMP_CODEC_ID,
-  targetTypes: ['timestamp'],
-  traits: ['equality', 'order'],
-  encode: (value: Date): Date => value,
-  decode: (wire: Date): Date => wire,
-  encodeJson: (value: Date): JsonValue => value.toISOString(),
-  decodeJson: (json: JsonValue): Date => {
-    if (typeof json !== 'string') {
-      throw new Error(`Expected ISO date string for sql/timestamp@1, got ${typeof json}`);
-    }
-    const date = new Date(json);
-    if (Number.isNaN(date.getTime())) {
-      throw new Error(`Invalid ISO date string for sql/timestamp@1: ${json}`);
-    }
-    return date;
-  },
-  paramsSchema: precisionParamsSchema,
-  renderOutputType: (typeParams) => {
-    const precision = typeParams['precision'];
-    if (precision === undefined) {
-      return 'Timestamp';
-    }
-    if (
-      typeof precision !== 'number' ||
-      !Number.isFinite(precision) ||
-      !Number.isInteger(precision)
-    ) {
-      throw new Error(
-        `renderOutputType: expected integer "precision" in typeParams for Timestamp, got ${String(precision)}`,
-      );
-    }
-    return `Timestamp<${precision}>`;
-  },
-});
-
-const codecs = defineCodecs()
-  .add('char', sqlCharCodec)
-  .add('varchar', sqlVarcharCodec)
-  .add('int', sqlIntCodec)
-  .add('float', sqlFloatCodec)
-  .add('text', sqlTextCodec)
-  .add('timestamp', sqlTimestampCodec);
-
-export const sqlCodecDefinitions = codecs.codecDefinitions;
-export const sqlDataTypes = codecs.dataTypes;
-export type SqlCodecTypes = typeof codecs.CodecTypes;
+> {
+  async encode(value: Date, _ctx: CodecCallContext): Promise<Date> {
+    return sqlTimestampEncode(value);
+  }
+  async decode(wire: Date, _ctx: CodecCallContext): Promise<Date> {
+    return sqlTimestampDecode(wire);
+  }
+  encodeJson(value: Date): JsonValue {
+    return sqlTimestampEncodeJson(value);
+  }
+  decodeJson(json: JsonValue): Date {
+    return sqlTimestampDecodeJson(json);
+  }
+}
+
+export class SqlTimestampDescriptor extends CodecDescriptorImpl<PrecisionParams> {
+  override readonly codecId = SQL_TIMESTAMP_CODEC_ID;
+  override readonly traits = ['equality', 'order'] as const;
+  override readonly targetTypes = ['timestamp'] as const;
+  override readonly paramsSchema: StandardSchemaV1<PrecisionParams> = precisionParamsSchema;
+  override renderOutputType(params: PrecisionParams): string | undefined {
+    return sqlTimestampRenderOutputType(params);
+  }
+  override factory(_params: PrecisionParams): (ctx: CodecInstanceContext) => SqlTimestampCodec {
+    return () => new SqlTimestampCodec(this);
+  }
+}
+
+export const sqlTimestampDescriptor = new SqlTimestampDescriptor();
+
+export const sqlTimestampColumn = (params: PrecisionParams = {}) =>
+  column(
+    sqlTimestampDescriptor.factory(params),
+    sqlTimestampDescriptor.codecId,
+    params,
+    'timestamp',
+  );
+
+sqlTimestampColumn satisfies ColumnHelperFor<SqlTimestampDescriptor>;
+sqlTimestampColumn satisfies ColumnHelperForStrict<SqlTimestampDescriptor>;

package/src/ast/types.ts

@@ -156,7 +156,7 @@ function rewriteProjectionItem(item: ProjectionItem, rewriter: AstRewriter): Pro
         ? rewriter.literal(item.expr)
         : item.expr
       : item.expr.rewrite(rewriter);
-  return new ProjectionItem(item.alias, rewrittenExpr, item.codecId);
+  return new ProjectionItem(item.alias, rewrittenExpr, item.codecId, item.refs);
 }
 
 function rewriteInsertValue(value: InsertValue, rewriter: AstRewriter): InsertValue {
@@ -320,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));
   }
@@ -392,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();
   }
 
@@ -417,6 +429,7 @@ export class ParamRef extends Expression {
     options?: {
       name?: string;
       codecId?: string;
+      refs?: ParamRefBindingRefs;
     },
   ): ParamRef {
     return new ParamRef(value, options);
@@ -1069,21 +1082,32 @@ export class ProjectionItem extends AstNode {
   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, codecId?: string) {
+  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, codecId?: string): ProjectionItem {
-    return new ProjectionItem(alias, expr, codecId);
+  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);
+    return new ProjectionItem(this.alias, this.expr, codecId, this.refs);
   }
 }
 
@@ -1241,6 +1265,7 @@ export class SelectAst extends QueryAst {
                 : projection.expr
               : projection.expr.rewrite(rewriter),
             projection.codecId,
+            projection.refs,
           ),
       ),
       where: this.where?.rewrite(rewriter),

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 },
+  );
+}