@prisma-next/sql-relational-core 0.3.0-dev.9 → 0.3.0-pr.100.2

package/dist/utils/guards.d.ts

@@ -1,13 +1,12 @@
 import type { StorageColumn } from '@prisma-next/sql-contract/types';
-import type { ColumnRef, LiteralExpr, OperationExpr, ParamRef } from '../ast/types';
-import type { AnyColumnBuilder, ParamPlaceholder } from '../types';
+import type { ColumnRef, Expression, ExpressionSource, LiteralExpr, OperationExpr, ParamRef } from '../ast/types';
+import type { AnyColumnBuilder, AnyExpressionSource, ExpressionBuilder, ParamPlaceholder, ValueSource } from '../types';
 /**
- * Helper to extract columnMeta from a ColumnBuilder.
+ * Helper to extract columnMeta from a ColumnBuilder or ExpressionBuilder.
  * Returns StorageColumn if present, undefined otherwise.
- * AnyColumnBuilder is a union that includes types with columnMeta property,
- * so we can safely access it after checking for existence.
+ * Both ColumnBuilder and ExpressionBuilder have columnMeta property.
  */
-export declare function getColumnMeta(expr: AnyColumnBuilder): StorageColumn | undefined;
+export declare function getColumnMeta(expr: AnyExpressionSource): StorageColumn | undefined;
 /**
  * Type predicate to check if a value is a ParamPlaceholder.
  */
@@ -25,12 +24,12 @@ export declare function collectColumnRefs(expr: ColumnRef | ParamRef | LiteralEx
 /**
  * Type predicate to check if an expression is an OperationExpr.
  */
-export declare function isOperationExpr(expr: AnyColumnBuilder | OperationExpr): expr is OperationExpr;
+export declare function isOperationExpr(expr: AnyExpressionSource | OperationExpr | Expression): expr is OperationExpr;
 /**
- * Helper to extract table and column from a ColumnBuilder or OperationExpr.
- * For OperationExpr, recursively unwraps to find the base ColumnRef.
+ * Helper to extract table and column from a ColumnBuilder, ExpressionBuilder, or OperationExpr.
+ * For ExpressionBuilder or OperationExpr, recursively unwraps to find the base ColumnRef.
  */
-export declare function getColumnInfo(expr: AnyColumnBuilder | OperationExpr): {
+export declare function getColumnInfo(expr: AnyExpressionSource | OperationExpr): {
     table: string;
     column: string;
 };
@@ -38,18 +37,46 @@ export declare function getColumnInfo(expr: AnyColumnBuilder | OperationExpr): {
  * Type predicate to check if a value is a ColumnBuilder.
  */
 export declare function isColumnBuilder(value: unknown): value is AnyColumnBuilder;
+/**
+ * Type predicate to check if a value is an ExpressionBuilder.
+ */
+export declare function isExpressionBuilder(value: unknown): value is ExpressionBuilder;
+/**
+ * Type predicate to check if a value is an ExpressionSource (has toExpr method).
+ */
+export declare function isExpressionSource(value: unknown): value is ExpressionSource;
+/**
+ * Converts any ExpressionSource to an Expression.
+ * This is the canonical way to get an AST Expression from a builder.
+ *
+ * @param source - A ColumnBuilder or ExpressionBuilder
+ * @returns The corresponding Expression (ColumnRef or OperationExpr)
+ */
+export declare function toExpression(source: ExpressionSource): Expression;
+/**
+ * Converts an AnyExpressionSource to an Expression.
+ * Handles both ColumnBuilder and ExpressionBuilder.
+ *
+ * @param source - A ColumnBuilder or ExpressionBuilder
+ * @returns The corresponding Expression (ColumnRef or OperationExpr)
+ */
+export declare function expressionFromSource(source: AnyExpressionSource): Expression;
+/**
+ * Type predicate to check if a value is a ValueSource.
+ * ValueSource is either a ParamPlaceholder or an ExpressionSource.
+ */
+export declare function isValueSource(value: unknown): value is ValueSource;
 /**
  * Extracts and returns an OperationExpr from a builder.
  * Returns the OperationExpr if the builder is an OperationExpr or has an _operationExpr property,
  * otherwise returns undefined.
  *
+ * @deprecated Use isExpressionBuilder() instead. This function exists for backward compatibility
+ * with code that uses the hidden _operationExpr property pattern.
+ *
  * @design-note: This function accesses the hidden `_operationExpr` property, which is a code smell.
- * The issue is that `executeOperation()` in relational-core returns a ColumnBuilder-shaped object
- * with a hidden `_operationExpr` property, creating coupling between lanes and relational-core
- * implementation details. A cleaner design would be to have operation results be a separate
- * type (e.g., `OperationResultBuilder`) that properly represents expression nodes rather than
- * pretending to be a ColumnBuilder. This would require refactoring the operation execution
- * system in relational-core to return proper expression types.
+ * The ExpressionBuilder type (introduced in the operation-expr-refactoring) provides a cleaner
+ * approach by explicitly representing operation results as a distinct type.
  */
 export declare function getOperationExpr(builder: AnyColumnBuilder | OperationExpr): OperationExpr | undefined;
 //# sourceMappingURL=guards.d.ts.map

package/dist/utils/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/utils/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEnE;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa,GAAG,SAAS,CAQ/E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAS5E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,GAAG,SAAS,CAK/E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,GACvD,SAAS,EAAE,CAYb;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa,GAAG,IAAI,IAAI,aAAa,CAE7F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa,GAAG;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAQA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAOzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,GAAG,aAAa,GACxC,aAAa,GAAG,SAAS,CAM3B"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/utils/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,QAAQ,EACT,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACZ,MAAM,UAAU,CAAC;AAElB;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,mBAAmB,GAAG,aAAa,GAAG,SAAS,CAOlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAS5E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,GAAG,SAAS,CAK/E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,GACvD,SAAS,EAAE,CAYb;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,mBAAmB,GAAG,aAAa,GAAG,UAAU,GACrD,IAAI,IAAI,aAAa,CAEvB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,mBAAmB,GAAG,aAAa,GAAG;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAYA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAOzE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAO9E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAO5E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,mBAAmB,GAAG,UAAU,CAE5E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,GAAG,aAAa,GACxC,aAAa,GAAG,SAAS,CAM3B"}

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "@prisma-next/sql-relational-core",
-  "version": "0.3.0-dev.9",
+  "version": "0.3.0-pr.100.2",
   "type": "module",
   "sideEffects": false,
   "description": "Schema and column builders, operation attachment, and AST types for Prisma Next",
   "dependencies": {
     "ts-toolbelt": "^9.6.0",
-    "@prisma-next/contract": "0.3.0-dev.9",
-    "@prisma-next/operations": "0.3.0-dev.9",
-    "@prisma-next/plan": "0.3.0-dev.9",
-    "@prisma-next/sql-contract": "0.3.0-dev.9",
-    "@prisma-next/sql-operations": "0.3.0-dev.9"
+    "@prisma-next/operations": "0.3.0-pr.100.2",
+    "@prisma-next/plan": "0.3.0-pr.100.2",
+    "@prisma-next/sql-contract": "0.3.0-pr.100.2",
+    "@prisma-next/contract": "0.3.0-pr.100.2",
+    "@prisma-next/sql-operations": "0.3.0-pr.100.2"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.16",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@prisma-next/sql-contract-ts": "0.3.0-dev.9",
-    "@prisma-next/test-utils": "0.0.1"
+    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/sql-contract-ts": "0.3.0-pr.100.2"
   },
   "files": [
     "dist",
@@ -71,9 +71,9 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --project tsconfig.json --noEmit",
-    "lint": "biome check . --config-path ../../../../biome.json --error-on-warnings",
-    "lint:fix": "biome check --write . --config-path ../../../../biome.json",
-    "lint:fix:unsafe": "biome check --write --unsafe . --config-path ../../../../biome.json",
-    "clean": "node ../../../../scripts/clean.mjs"
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
   }
 }

package/src/ast/codec-types.ts

@@ -176,11 +176,12 @@ export function codec<Id extends string, TWire, TJs>(config: {
 /**
  * Type helpers to extract codec types.
  */
-export type CodecId<T> = T extends Codec<infer Id, unknown, unknown>
-  ? Id
-  : T extends { readonly id: infer Id }
+export type CodecId<T> =
+  T extends Codec<infer Id, unknown, unknown>
     ? Id
-    : never;
+    : T extends { readonly id: infer Id }
+      ? Id
+      : never;
 export type CodecInput<T> = T extends Codec<string, unknown, infer JsT> ? JsT : never;
 export type CodecOutput<T> = T extends Codec<string, unknown, infer JsT> ? JsT : never;
 

package/src/ast/predicate.ts

@@ -1,17 +1,9 @@
-import type {
-  BinaryExpr,
-  BinaryOp,
-  ColumnRef,
-  ExistsExpr,
-  OperationExpr,
-  ParamRef,
-  SelectAst,
-} from './types';
+import type { BinaryExpr, BinaryOp, ExistsExpr, Expression, ParamRef, SelectAst } from './types';
 
 export function createBinaryExpr(
   op: BinaryOp,
-  left: ColumnRef | OperationExpr,
-  right: ColumnRef | ParamRef,
+  left: Expression,
+  right: Expression | ParamRef,
 ): BinaryExpr {
   return {
     kind: 'bin',

package/src/ast/types.ts

@@ -32,13 +32,27 @@ export interface OperationExpr {
   readonly kind: 'operation';
   readonly method: string;
   readonly forTypeId: string;
-  readonly self: ColumnRef | OperationExpr;
-  readonly args: ReadonlyArray<ColumnRef | ParamRef | LiteralExpr | OperationExpr>;
+  readonly self: Expression;
+  readonly args: ReadonlyArray<Expression | ParamRef | LiteralExpr>;
   readonly returns: ReturnSpec;
   readonly lowering: SqlLoweringSpec;
 }
 
-export function isOperationExpr(expr: ColumnRef | OperationExpr): expr is OperationExpr {
+/**
+ * Unified expression type - the canonical AST representation for column references
+ * and operation expressions. This is what all builders convert to via toExpr().
+ */
+export type Expression = ColumnRef | OperationExpr;
+
+/**
+ * Interface for any builder that can produce an Expression.
+ * Implemented by ColumnBuilder and ExpressionBuilder.
+ */
+export interface ExpressionSource {
+  toExpr(): Expression;
+}
+
+export function isOperationExpr(expr: Expression): expr is OperationExpr {
   return expr.kind === 'operation';
 }
 
@@ -47,8 +61,8 @@ export type BinaryOp = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte';
 export interface BinaryExpr {
   readonly kind: 'bin';
   readonly op: BinaryOp;
-  readonly left: ColumnRef | OperationExpr;
-  readonly right: ColumnRef | ParamRef;
+  readonly left: Expression;
+  readonly right: Expression | ParamRef;
 }
 
 export interface ExistsExpr {
@@ -82,9 +96,9 @@ export interface IncludeAst {
     readonly table: TableRef;
     readonly on: JoinOnExpr;
     readonly where?: BinaryExpr | ExistsExpr;
-    readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+    readonly orderBy?: ReadonlyArray<{ expr: Expression; dir: Direction }>;
     readonly limit?: number;
-    readonly project: ReadonlyArray<{ alias: string; expr: ColumnRef | OperationExpr }>;
+    readonly project: ReadonlyArray<{ alias: string; expr: Expression }>;
   };
 }
 
@@ -95,10 +109,10 @@ export interface SelectAst {
   readonly includes?: ReadonlyArray<IncludeAst>;
   readonly project: ReadonlyArray<{
     alias: string;
-    expr: ColumnRef | IncludeRef | OperationExpr | LiteralExpr;
+    expr: Expression | IncludeRef | LiteralExpr;
   }>;
   readonly where?: BinaryExpr | ExistsExpr;
-  readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+  readonly orderBy?: ReadonlyArray<{ expr: Expression; dir: Direction }>;
   readonly limit?: number;
 }
 

package/src/exports/guards.ts

@@ -1,10 +1,15 @@
 export {
   collectColumnRefs,
+  expressionFromSource,
   extractBaseColumnRef,
   getColumnInfo,
   getColumnMeta,
   getOperationExpr,
   isColumnBuilder,
+  isExpressionBuilder,
+  isExpressionSource,
   isOperationExpr,
   isParamPlaceholder,
+  isValueSource,
+  toExpression,
 } from '../utils/guards';

package/src/operations-registry.ts

@@ -3,59 +3,71 @@ import { hasAllCapabilities } from '@prisma-next/operations';
 import { planInvalid } from '@prisma-next/plan';
 import type { StorageColumn } from '@prisma-next/sql-contract/types';
 import type { SqlOperationSignature } from '@prisma-next/sql-operations';
-import type { BinaryOp, ColumnRef, LiteralExpr, OperationExpr, ParamRef } from './ast/types';
-import type { AnyColumnBuilder, ColumnBuilder, OperationTypes, ParamPlaceholder } from './types';
+import type {
+  BinaryOp,
+  Expression,
+  ExpressionSource,
+  LiteralExpr,
+  OperationExpr,
+  ParamRef,
+} from './ast/types';
+import type {
+  AnyBinaryBuilder,
+  AnyOrderBuilder,
+  ColumnBuilder,
+  ExpressionBuilder,
+  OperationTypes,
+  ParamPlaceholder,
+} from './types';
 import { isParamPlaceholder } from './utils/guards';
 
-function isColumnBuilder(value: unknown): value is AnyColumnBuilder {
+/**
+ * Type guard to check if a value is an ExpressionSource (has toExpr method).
+ */
+function isExpressionSource(value: unknown): value is ExpressionSource {
   return (
     typeof value === 'object' &&
     value !== null &&
-    'kind' in value &&
-    (value as { kind: unknown }).kind === 'column'
+    'toExpr' in value &&
+    typeof (value as ExpressionSource).toExpr === 'function'
   );
 }
 
 /**
- * Executes an operation and returns a column-shaped result object.
+ * Executes an operation and returns an ExpressionBuilder.
  * This is the canonical entrypoint for operation invocation, enabling
  * future enhancements like telemetry, caching, or tracing.
  *
+ * The returned ExpressionBuilder:
+ * - Has `kind: 'expression'` to distinguish it from ColumnBuilder
+ * - Contains the operation expression in `expr`
+ * - Provides `toExpr()` method to get the Expression
+ * - Provides comparison and ordering methods for chaining
+ *
  * @param signature - The operation signature from the registry
- * @param selfBuilder - The column builder that the operation is called on
+ * @param selfBuilder - The expression source that the operation is called on
  * @param args - The arguments passed to the operation
  * @param columnMeta - The metadata of the column the operation is called on
- * @returns A column-shaped builder with the operation expression attached
+ * @returns An ExpressionBuilder containing the operation expression
  */
 function executeOperation(
   signature: SqlOperationSignature,
-  selfBuilder: AnyColumnBuilder,
+  selfBuilder: ExpressionSource,
   args: unknown[],
   columnMeta: StorageColumn,
   operationRegistry?: OperationRegistry,
   contractCapabilities?: Record<string, Record<string, boolean>>,
-): AnyColumnBuilder & { _operationExpr?: OperationExpr } {
+): ExpressionBuilder {
   if (args.length !== signature.args.length) {
     throw planInvalid(
       `Operation ${signature.method} expects ${signature.args.length} arguments, got ${args.length}`,
     );
   }
 
-  // Check if this column builder has an existing operation expression
-  const selfBuilderWithExpr = selfBuilder as unknown as {
-    _operationExpr?: OperationExpr;
-    table: string;
-    column: string;
-  };
-  const selfExpr: ColumnRef | OperationExpr = selfBuilderWithExpr._operationExpr
-    ? selfBuilderWithExpr._operationExpr
-    : {
-        kind: 'col',
-        table: selfBuilderWithExpr.table,
-        column: selfBuilderWithExpr.column,
-      };
-
-  const operationArgs: Array<ColumnRef | ParamRef | LiteralExpr | OperationExpr> = [];
+  // Get the Expression from the self builder using toExpr()
+  const selfExpr: Expression = selfBuilder.toExpr();
+
+  const operationArgs: Array<Expression | ParamRef | LiteralExpr> = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     const argSpec = signature.args[i];
@@ -73,25 +85,14 @@ function executeOperation(
         name: arg.name,
       });
     } else if (argSpec.kind === 'typeId') {
-      if (!isColumnBuilder(arg)) {
-        throw planInvalid(`Argument ${i} must be a ColumnBuilder`);
-      }
-      const colBuilderWithExpr = arg as unknown as {
-        _operationExpr?: OperationExpr;
-        table: string;
-        column: string;
-      };
-      // Check if the column builder has an operation expression
-      if (colBuilderWithExpr._operationExpr) {
-        operationArgs.push(colBuilderWithExpr._operationExpr);
-      } else {
-        // Fall back to raw ColumnRef
-        operationArgs.push({
-          kind: 'col',
-          table: colBuilderWithExpr.table,
-          column: colBuilderWithExpr.column,
-        });
+      // Accept ExpressionSource (ColumnBuilder or ExpressionBuilder)
+      if (!isExpressionSource(arg)) {
+        throw planInvalid(
+          `Argument ${i} must be an ExpressionSource (ColumnBuilder or ExpressionBuilder)`,
+        );
       }
+      // Use toExpr() to get the Expression
+      operationArgs.push(arg.toExpr());
     } else if (argSpec.kind === 'literal') {
       operationArgs.push({
         kind: 'literal',
@@ -118,18 +119,19 @@ function executeOperation(
       }
     : columnMeta;
 
-  const createComparisonMethod = (op: BinaryOp) => (value: ParamPlaceholder) =>
-    Object.freeze({
-      kind: 'binary' as const,
-      op,
-      left: operationExpr,
-      right: value,
-    });
-
-  const baseResult = {
-    kind: 'column' as const,
-    table: selfBuilderWithExpr.table,
-    column: selfBuilderWithExpr.column,
+  const createComparisonMethod =
+    (op: BinaryOp) =>
+    (value: ParamPlaceholder | ExpressionSource): AnyBinaryBuilder =>
+      Object.freeze({
+        kind: 'binary' as const,
+        op,
+        left: operationExpr,
+        right: value,
+      }) as AnyBinaryBuilder;
+
+  const baseResult: ExpressionBuilder = {
+    kind: 'expression' as const,
+    expr: operationExpr,
     get columnMeta() {
       return returnColumnMeta;
     },
@@ -139,41 +141,84 @@ function executeOperation(
     lt: createComparisonMethod('lt'),
     gte: createComparisonMethod('gte'),
     lte: createComparisonMethod('lte'),
-    asc() {
+    asc(): AnyOrderBuilder {
       return Object.freeze({
         kind: 'order' as const,
         expr: operationExpr,
         dir: 'asc' as const,
       });
     },
-    desc() {
+    desc(): AnyOrderBuilder {
       return Object.freeze({
         kind: 'order' as const,
         expr: operationExpr,
         dir: 'desc' as const,
       });
     },
-    _operationExpr: operationExpr,
-  } as unknown as AnyColumnBuilder & {
-    _operationExpr?: OperationExpr;
+    toExpr(): OperationExpr {
+      return operationExpr;
+    },
+    get __jsType(): unknown {
+      return undefined;
+    },
   };
 
   // If the return type is a typeId, attach operations for that type
   if (returnTypeId && operationRegistry) {
-    const resultWithOps = attachOperationsToColumnBuilder(
-      baseResult as ColumnBuilder<string, StorageColumn, unknown, Record<string, never>>,
+    const resultWithOps = attachOperationsToExpressionBuilder(
+      baseResult,
       returnColumnMeta,
       operationRegistry,
       contractCapabilities,
-    ) as AnyColumnBuilder & {
-      _operationExpr?: OperationExpr;
-    };
+    );
     return Object.freeze(resultWithOps);
   }
 
   return Object.freeze(baseResult);
 }
 
+/**
+ * Attaches operation methods to an ExpressionBuilder for chained operations.
+ * When an operation returns a typeId, the result ExpressionBuilder needs
+ * operation methods for that type.
+ */
+function attachOperationsToExpressionBuilder(
+  expressionBuilder: ExpressionBuilder,
+  columnMeta: StorageColumn,
+  registry: OperationRegistry,
+  contractCapabilities?: Record<string, Record<string, boolean>>,
+): ExpressionBuilder {
+  const codecId = columnMeta.codecId;
+  if (!codecId) {
+    return expressionBuilder;
+  }
+
+  const operations = registry.byType(codecId) as SqlOperationSignature[];
+  if (operations.length === 0) {
+    return expressionBuilder;
+  }
+
+  const builderWithOps = expressionBuilder as ExpressionBuilder & Record<string, unknown>;
+
+  for (const operation of operations) {
+    if (operation.capabilities && operation.capabilities.length > 0) {
+      if (!contractCapabilities) {
+        continue;
+      }
+
+      if (!hasAllCapabilities(operation.capabilities, contractCapabilities)) {
+        continue;
+      }
+    }
+    // Method sugar: attach operation as a method on the expression builder
+    builderWithOps[operation.method] = function (this: ExpressionBuilder, ...args: unknown[]) {
+      return executeOperation(operation, this, args, columnMeta, registry, contractCapabilities);
+    };
+  }
+
+  return builderWithOps;
+}
+
 export function attachOperationsToColumnBuilder<
   ColumnName extends string,
   ColumnMeta extends StorageColumn,
@@ -218,18 +263,12 @@ export function attachOperationsToColumnBuilder<
       }
     }
     // Method sugar: attach operation as a method on the column builder
+    // Operations return ExpressionBuilder, not ColumnBuilder
     (builderWithOps as Record<string, unknown>)[operation.method] = function (
       this: ColumnBuilder<ColumnName, ColumnMeta, JsType, Record<string, never>>,
       ...args: unknown[]
     ) {
-      return executeOperation(
-        operation,
-        this as unknown as ColumnBuilder<string, StorageColumn, unknown>,
-        args,
-        columnMeta,
-        registry,
-        contractCapabilities,
-      );
+      return executeOperation(operation, this, args, columnMeta, registry, contractCapabilities);
     };
   }
 

package/src/query-lane-context.ts

@@ -2,6 +2,13 @@ import type { OperationRegistry } from '@prisma-next/operations';
 import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
 import type { CodecRegistry } from './ast/codec-types';
 
+/**
+ * Registry of initialized type helpers from storage.types.
+ * Each key is a type name from storage.types, and the value is the initialized helper
+ * (or validated typeParams if no init hook was provided).
+ */
+export type TypeHelperRegistry = Record<string, unknown>;
+
 /**
  * Minimal context interface for SQL query lanes.
  *
@@ -15,4 +22,9 @@ export interface QueryLaneContext<
   readonly contract: TContract;
   readonly operations: OperationRegistry;
   readonly codecs: CodecRegistry;
+  /**
+   * Optional type helper registry for parameterized types.
+   * When present, schema() will expose these helpers via schema.types.
+   */
+  readonly types?: TypeHelperRegistry;
 }