@prisma-next/sql-relational-core 0.13.0 → 0.14.0

package/dist/types-lWs6p0ny.d.mts

@@ -0,0 +1,233 @@
+import { Y as ParamRef, g as ColumnRef } from "./types-DQrmgP8Y.mjs";
+import { r as ExecutionContext } from "./query-lane-context-DFnJVqUH.mjs";
+import { t as SqlExecutionPlan } from "./sql-execution-plan-DjMEAjKK.mjs";
+import { Contract } from "@prisma-next/contract/types";
+import { ExtractFieldOutputTypes, SqlStorage, StorageColumn } from "@prisma-next/sql-contract/types";
+import { ParamSpec } from "@prisma-next/operations";
+import { SqlLoweringSpec } from "@prisma-next/sql-operations";
+
+//#region src/types.d.ts
+type Expr = ColumnRef | ParamRef;
+/**
+ * The minimal contract shape the per-namespace column resolver needs: the
+ * application-domain models and the storage tables, both keyed by namespace
+ * coordinate, plus (via the optional TypeMaps phantom key, read structurally by
+ * {@link ExtractFieldOutputTypes}) the refined field-output map. Every emitted
+ * `Contract<SqlStorage>` satisfies it, as does `sql-builder`'s `TableProxyContract`
+ * — so the resolver indexes the coordinate directly without forcing callers to
+ * carry the full `Contract`.
+ */
+type ColumnResolutionContract = {
+  readonly domain: {
+    readonly namespaces: Readonly<Record<string, {
+      readonly models: Readonly<Record<string, unknown>>;
+    }>>;
+  };
+  readonly storage: {
+    readonly namespaces: Readonly<Record<string, {
+      readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    }>>;
+  };
+};
+type NamespaceModels<TContract extends ColumnResolutionContract, NsId extends string> = TContract['domain']['namespaces'][NsId] extends {
+  readonly models: infer Models extends Record<string, unknown>;
+} ? Models : never;
+type ExtractTableToModel<TContract extends ColumnResolutionContract, NsId extends string, TableName extends string> = NamespaceModels<TContract, NsId> extends infer Models extends Record<string, unknown> ? { [M in keyof Models & string]: Models[M] extends {
+  readonly storage: {
+    readonly table: TableName;
+  };
+} ? M : never }[keyof Models & string] : never;
+type ExtractColumnToField<TContract extends ColumnResolutionContract, NsId extends string, TableName extends string, ColumnName extends string> = ExtractTableToModel<TContract, NsId, TableName> extends infer ModelName extends string ? NamespaceModels<TContract, NsId> extends infer Models extends Record<string, unknown> ? ModelName & keyof Models extends infer MKey extends string ? Models[MKey] extends {
+  readonly storage: {
+    readonly fields: infer Fields extends Record<string, unknown>;
+  };
+} ? { [F in keyof Fields & string]: Fields[F] extends {
+  readonly column: ColumnName;
+} ? F : never }[keyof Fields & string] : never : never : never : never;
+/** Resolves to `never` when the table or column is absent in the namespace. */
+type NamespaceStorageColumn<TContract extends ColumnResolutionContract, NsId extends string, TableName extends string, ColumnName extends string> = TContract['storage']['namespaces'][NsId] extends {
+  readonly entries: {
+    readonly table: infer Tables extends Record<string, unknown>;
+  };
+} ? TableName extends keyof Tables ? Tables[TableName] extends {
+  readonly columns: infer Columns extends Record<string, unknown>;
+} ? ColumnName extends keyof Columns ? Columns[ColumnName] extends StorageColumn ? Columns[ColumnName] : never : never : never : never : never;
+type FallbackCodecLookup<ColumnMeta extends StorageColumn, CodecTypes extends Record<string, {
+  readonly output: unknown;
+}>> = ColumnMeta extends {
+  codecId: infer CodecId extends string;
+} ? CodecId extends keyof CodecTypes ? CodecTypes[CodecId] extends {
+  readonly output: infer O;
+} ? ColumnMeta extends {
+  nullable: true;
+} ? O | null : O : unknown : unknown : unknown;
+/**
+ * The refined (typeParam-applied) JS output type for a field within a namespace
+ * coordinate, read from the emitter's namespace-nested `FieldOutputTypes` map at
+ * `FieldOutputTypes[NsId][Model][Field]`. This preserves parameterized codec
+ * refinements (e.g. `Vector<N>`, `Char<N>`) that a bare codec-output lookup
+ * would drop. Resolves to `never` when the coordinate is absent from the map.
+ */
+type NamespaceFieldOutput<TContract extends ColumnResolutionContract, NsId extends string, ModelName extends string, FieldName extends string> = ExtractFieldOutputTypes<TContract> extends infer Outputs ? NsId extends keyof Outputs ? Outputs[NsId] extends infer NamespaceOutputs ? ModelName extends keyof NamespaceOutputs ? NamespaceOutputs[ModelName] extends infer ModelOutputs ? FieldName extends keyof ModelOutputs ? ModelOutputs[FieldName] : never : never : never : never : never : never;
+/**
+ * The secondary resolution path, taken for a storage column not backed by a
+ * domain model field in the namespace (e.g. a column with no corresponding
+ * field); refined model fields resolve via {@link NamespaceFieldOutput}.
+ */
+type ColumnCodecFallback<TContract extends ColumnResolutionContract, NsId extends string, TableName extends string, ColumnName extends string, CodecTypes extends Record<string, {
+  readonly output: unknown;
+}>> = NamespaceStorageColumn<TContract, NsId, TableName, ColumnName> extends infer ColumnMeta ? [ColumnMeta] extends [never] ? never : ColumnMeta extends StorageColumn ? FallbackCodecLookup<ColumnMeta, CodecTypes> : never : never;
+/**
+ * Type-level operation signature.
+ * Represents an operation at the type level for use in contract type maps.
+ */
+type OperationTypeSignature = {
+  readonly args: ReadonlyArray<ParamSpec>;
+  readonly returns: ParamSpec;
+  readonly lowering: SqlLoweringSpec;
+  readonly capabilities?: ReadonlyArray<string>;
+};
+/**
+ * Type-level operation registry.
+ * Maps typeId → operations, where operations is a record of method name → operation signature.
+ *
+ * Example:
+ * ```typescript
+ * type MyOperations: OperationTypes = {
+ *   'pg/vector@1': {
+ *     cosineDistance: {
+ *       args: [{ codecId: 'pg/vector@1'; nullable: false }];
+ *       returns: { codecId: 'core/float8'; nullable: false };
+ *       lowering: { targetFamily: 'sql'; strategy: 'function'; template: '...' };
+ *     };
+ *   };
+ * };
+ * ```
+ */
+type OperationTypes = Record<string, Record<string, OperationTypeSignature>>;
+/**
+ * CodecTypes represents a map of typeId to codec definitions.
+ * Each codec definition must have an `output` property indicating the JavaScript type.
+ *
+ * Example:
+ * ```typescript
+ * type MyCodecTypes: CodecTypes = {
+ *   'pg/int4@1': { output: number };
+ *   'pg/text@1': { output: string };
+ * };
+ * ```
+ */
+type CodecTypes = Record<string, {
+  readonly output: unknown;
+}>;
+/**
+ * Extracts operations for a given typeId from the operation registry.
+ * Returns an empty record if the typeId is not found.
+ *
+ * @example
+ * ```typescript
+ * type Ops = OperationsForTypeId<'pg/vector@1', MyOperations>;
+ * // Ops = { cosineDistance: { ... }, l2Distance: { ... } }
+ * ```
+ */
+type OperationsForTypeId<TypeId extends string, Operations extends OperationTypes> = Operations extends Record<string, never> ? Record<string, never> : TypeId extends keyof Operations ? Operations[TypeId] : Record<string, never>;
+/**
+ * Resolves the JavaScript output type of a column addressed by an explicit
+ * namespace coordinate.
+ *
+ * The table→model and column→field mapping is resolved per-namespace from
+ * `domain.namespaces[NsId]['models']`, and the refined output type from the
+ * emitter's namespace-nested `FieldOutputTypes[NsId][Model][Field]` — so a bare
+ * table name shared across namespaces resolves to each namespace's own field,
+ * and parameterized codec refinements (e.g. `Vector<N>`) are preserved. A
+ * storage column not backed by a model field in the namespace falls back to a
+ * codec-output lookup; a column absent in the namespace resolves to `never`.
+ */
+type ComputeColumnJsType<TContract extends ColumnResolutionContract, NsId extends string, TableName extends string, ColumnName extends string, CodecTypes extends Record<string, {
+  readonly output: unknown;
+}>> = ExtractTableToModel<TContract, NsId, TableName> extends infer ModelName ? [ModelName] extends [never] ? ColumnCodecFallback<TContract, NsId, TableName, ColumnName, CodecTypes> : ModelName extends string ? ExtractColumnToField<TContract, NsId, TableName, ColumnName> extends infer FieldName ? [FieldName] extends [never] ? ColumnCodecFallback<TContract, NsId, TableName, ColumnName, CodecTypes> : FieldName extends string ? NamespaceFieldOutput<TContract, NsId, ModelName, FieldName> extends infer Out ? [Out] extends [never] ? ColumnCodecFallback<TContract, NsId, TableName, ColumnName, CodecTypes> : Out : never : never : never : never : never;
+/**
+ * Alias for the SQL-domain executable plan, exposed under the legacy
+ * `SqlPlan` name for compatibility with SQL builder/utility call sites.
+ * The canonical name is `SqlExecutionPlan` (`./sql-execution-plan`).
+ */
+type SqlPlan<Row = unknown> = SqlExecutionPlan<Row>;
+/**
+ * Helper types for extracting contract structure.
+ */
+type TablesOf<TContract> = TContract extends {
+  storage: {
+    tables: infer U;
+  };
+} ? U : never;
+type TableKey<TContract> = Extract<keyof TablesOf<TContract>, string>;
+/**
+ * Unique symbol for metadata property to avoid collisions with user-defined properties
+ */
+declare const META: unique symbol;
+/**
+ * Extracts metadata from a type that has a META property
+ */
+type Meta<T extends {
+  [META]: unknown;
+}> = T[typeof META];
+/**
+ * Metadata interface for table definitions
+ */
+interface TableMetadata<Name extends string> {
+  name: Name;
+}
+/**
+ * Metadata interface for model definitions
+ */
+interface ModelMetadata<Name extends string> {
+  name: Name;
+}
+/**
+ * Base interface for table definitions with metadata
+ * Used in contract.d.ts to define storage-level table types
+ */
+interface TableDef<Name extends string> {
+  readonly [META]: TableMetadata<Name>;
+}
+/**
+ * Base interface for model definitions with metadata
+ * Used in contract.d.ts to define application-level model types
+ */
+interface ModelDef<Name extends string> {
+  readonly [META]: ModelMetadata<Name>;
+}
+type ColumnsOf<TContract, K extends TableKey<TContract>> = K extends keyof TablesOf<TContract> ? TablesOf<TContract>[K] extends {
+  columns: infer C;
+} ? C : never : never;
+interface RawTemplateOptions {
+  readonly annotations?: Record<string, unknown>;
+}
+interface RawFunctionOptions extends RawTemplateOptions {
+  readonly params: ReadonlyArray<unknown>;
+}
+type RawTemplateFactory = (strings: TemplateStringsArray, ...values: readonly unknown[]) => SqlExecutionPlan;
+interface RawFactory extends RawTemplateFactory {
+  (text: string, options: RawFunctionOptions): SqlExecutionPlan;
+  with(options: RawTemplateOptions): RawTemplateFactory;
+}
+interface RuntimeError extends Error {
+  readonly code: string;
+  readonly category: 'PLAN';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+  readonly hints?: readonly string[];
+  readonly docs?: readonly string[];
+}
+interface BuildParamsMap {
+  readonly [name: string]: unknown;
+}
+interface BuildOptions {
+  readonly params?: BuildParamsMap;
+}
+interface SqlBuilderOptions<TContract extends Contract<SqlStorage> = Contract<SqlStorage>> {
+  readonly context: ExecutionContext<TContract>;
+}
+//#endregion
+export { TableKey as C, TableDef as S, TablesOf as T, RawTemplateFactory as _, ColumnsOf as a, SqlBuilderOptions as b, META as c, ModelMetadata as d, OperationTypeSignature as f, RawFunctionOptions as g, RawFactory as h, ColumnResolutionContract as i, Meta as l, OperationsForTypeId as m, BuildParamsMap as n, ComputeColumnJsType as o, OperationTypes as p, CodecTypes as r, Expr as s, BuildOptions as t, ModelDef as u, RawTemplateOptions as v, TableMetadata as w, SqlPlan as x, RuntimeError as y };
+//# sourceMappingURL=types-lWs6p0ny.d.mts.map

package/dist/types-lWs6p0ny.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-lWs6p0ny.d.mts","names":[],"sources":["../src/types.ts"],"mappings":"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"}

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@prisma-next/sql-relational-core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "AST types, query lane context, and type utilities for Prisma Next SQL lanes",
   "dependencies": {
-    "@prisma-next/contract": "0.13.0",
-    "@prisma-next/framework-components": "0.13.0",
-    "@prisma-next/operations": "0.13.0",
-    "@prisma-next/sql-contract": "0.13.0",
-    "@prisma-next/sql-operations": "0.13.0",
-    "@prisma-next/utils": "0.13.0",
+    "@prisma-next/contract": "0.14.0",
+    "@prisma-next/framework-components": "0.14.0",
+    "@prisma-next/operations": "0.14.0",
+    "@prisma-next/sql-contract": "0.14.0",
+    "@prisma-next/sql-operations": "0.14.0",
+    "@prisma-next/utils": "0.14.0",
     "@standard-schema/spec": "^1.1.0",
     "arktype": "^2.2.0",
     "ts-toolbelt": "^9.6.0"
   },
   "devDependencies": {
-    "@prisma-next/sql-contract-ts": "0.13.0",
-    "@prisma-next/test-utils": "0.13.0",
-    "@prisma-next/tsconfig": "0.13.0",
-    "@prisma-next/tsdown": "0.13.0",
+    "@prisma-next/sql-contract-ts": "0.14.0",
+    "@prisma-next/test-utils": "0.14.0",
+    "@prisma-next/tsconfig": "0.14.0",
+    "@prisma-next/tsdown": "0.14.0",
     "tsdown": "0.22.1",
     "typescript": "5.9.3",
     "vitest": "4.1.8"

package/src/ast/ddl-types.ts

@@ -1,6 +1,7 @@
 import type { ColumnDefaultLiteralInputValue } from '@prisma-next/contract/types';
 import { isColumnDefaultLiteralInputValue } from '@prisma-next/contract/types';
 import type { ReferentialAction } from '@prisma-next/sql-contract/types';
+import type { CodecRef } from './codec-types';
 import type { AnyParamRef } from './types';
 
 /**
@@ -71,6 +72,8 @@ export class DdlColumn {
   readonly notNull?: boolean | undefined;
   readonly primaryKey?: boolean | undefined;
   readonly default?: AnyDdlColumnDefault | undefined;
+  /** Codec identity for this column. When present, the DDL walker resolves the codec via `codecLookup.get(codecRef.codecId)` and calls `codec.encode(default.value, {})` to obtain the wire value before inlining the literal default into the DDL string. When absent, literal defaults follow RawSqlLiteral wire-scalar semantics (string / number / boolean / bigint / null / Uint8Array / Date inlined directly). */
+  readonly codecRef?: CodecRef | undefined;
 
   constructor(options: {
     readonly name: string;
@@ -78,12 +81,14 @@ export class DdlColumn {
     readonly notNull?: boolean;
     readonly primaryKey?: boolean;
     readonly default?: AnyDdlColumnDefault;
+    readonly codecRef?: CodecRef;
   }) {
     this.name = options.name;
     this.type = options.type;
     this.notNull = options.notNull;
     this.primaryKey = options.primaryKey;
     this.default = options.default;
+    this.codecRef = options.codecRef;
     Object.freeze(this);
   }
 }

package/src/ast/driver-types.ts

@@ -1,3 +1,11 @@
+/**
+ * A fully lowered SQL statement ready for a driver to execute: SQL text plus
+ * driver-ready (codec-encoded) parameter values. The output of the control
+ * adapter's `lowerToExecuteRequest`, handed to a driver via `SqlQueryable.query`
+ * or `execute`. Inline-substituted positions (e.g. DDL `DEFAULT`
+ * clauses) carry no param; `params` holds the wire values for the `$N`/`?`
+ * positions, in order.
+ */
 export interface SqlExecuteRequest {
   readonly sql: string;
   readonly params?: readonly unknown[];

package/src/ast/types.ts

@@ -378,6 +378,35 @@ export class DerivedTableSource extends FromSource {
   }
 }
 
+export class FunctionSource extends FromSource {
+  readonly kind = 'function-source' as const;
+  readonly fn: string;
+  readonly args: ReadonlyArray<AnyExpression>;
+  readonly alias: string | undefined;
+
+  protected constructor(fn: string, args: ReadonlyArray<AnyExpression>, alias?: string) {
+    super();
+    this.fn = fn;
+    this.args = frozenArrayCopy(args);
+    this.alias = alias;
+    this.freeze();
+  }
+
+  static of(fn: string, args: ReadonlyArray<AnyExpression>, alias?: string): FunctionSource {
+    return new FunctionSource(fn, args, alias);
+  }
+
+  override rewrite(rewriter: AstRewriter): AnyFromSource {
+    const rewrittenArgs = this.args.map((arg) => rewriteComparable(arg, rewriter));
+    if (rewrittenArgs.every((arg, i) => arg === this.args[i])) return this;
+    return new FunctionSource(this.fn, rewrittenArgs, this.alias);
+  }
+
+  override toFromSource(): AnyFromSource {
+    return this;
+  }
+}
+
 export class ColumnRef extends Expression {
   readonly kind = 'column-ref' as const;
   readonly table: string;
@@ -1299,7 +1328,7 @@ export class ProjectionItem extends AstNode {
 export type LimitOffsetValue = number | AnyExpression;
 
 export interface SelectAstOptions {
-  readonly from: AnyFromSource;
+  readonly from?: AnyFromSource;
   readonly joins: ReadonlyArray<JoinAst> | undefined;
   readonly projection: ReadonlyArray<ProjectionItem>;
   readonly where: AnyExpression | undefined;
@@ -1315,7 +1344,7 @@ export interface SelectAstOptions {
 
 export class SelectAst extends QueryAst {
   readonly kind = 'select' as const;
-  readonly from: AnyFromSource;
+  readonly from: AnyFromSource | undefined;
   readonly joins: ReadonlyArray<JoinAst> | undefined;
   readonly projection: ReadonlyArray<ProjectionItem>;
   readonly where: AnyExpression | undefined;
@@ -1368,79 +1397,113 @@ export class SelectAst extends QueryAst {
     });
   }
 
+  static noFrom(): SelectAst {
+    return new SelectAst({
+      joins: undefined,
+      projection: [],
+      where: undefined,
+      orderBy: undefined,
+      distinct: undefined,
+      distinctOn: undefined,
+      groupBy: undefined,
+      having: undefined,
+      limit: undefined,
+      offset: undefined,
+      selectAllIntent: undefined,
+    });
+  }
+
+  private toOptions(): SelectAstOptions {
+    return {
+      ...(this.from !== undefined ? { from: this.from } : {}),
+      joins: this.joins,
+      projection: this.projection,
+      where: this.where,
+      orderBy: this.orderBy,
+      distinct: this.distinct,
+      distinctOn: this.distinctOn,
+      groupBy: this.groupBy,
+      having: this.having,
+      limit: this.limit,
+      offset: this.offset,
+      selectAllIntent: this.selectAllIntent,
+    };
+  }
+
   withFrom(from: AnyFromSource): SelectAst {
-    return new SelectAst({ ...this, from });
+    return new SelectAst({ ...this.toOptions(), from });
   }
 
   withJoins(joins: ReadonlyArray<JoinAst>): SelectAst {
     return new SelectAst({
-      ...this,
+      ...this.toOptions(),
       joins: joins.length > 0 ? joins : undefined,
     });
   }
 
   withProjection(projection: ReadonlyArray<ProjectionItem>): SelectAst {
-    return new SelectAst({ ...this, projection });
+    return new SelectAst({ ...this.toOptions(), projection });
   }
 
   addProjection(alias: string, expr: ProjectionExpr): SelectAst {
     return new SelectAst({
-      ...this,
+      ...this.toOptions(),
       projection: [...this.projection, new ProjectionItem(alias, expr)],
     });
   }
 
   withWhere(where: AnyExpression | undefined): SelectAst {
-    return new SelectAst({ ...this, where });
+    return new SelectAst({ ...this.toOptions(), where });
   }
 
   withOrderBy(orderBy: ReadonlyArray<OrderByItem>): SelectAst {
     return new SelectAst({
-      ...this,
+      ...this.toOptions(),
       orderBy: orderBy.length > 0 ? orderBy : undefined,
     });
   }
 
   withDistinct(enabled = true): SelectAst {
     return new SelectAst({
-      ...this,
+      ...this.toOptions(),
       distinct: enabled ? true : undefined,
     });
   }
 
   withDistinctOn(distinctOn: ReadonlyArray<AnyExpression>): SelectAst {
     return new SelectAst({
-      ...this,
+      ...this.toOptions(),
       distinctOn: distinctOn.length > 0 ? distinctOn : undefined,
     });
   }
 
   withGroupBy(groupBy: ReadonlyArray<AnyExpression>): SelectAst {
     return new SelectAst({
-      ...this,
+      ...this.toOptions(),
       groupBy: groupBy.length > 0 ? groupBy : undefined,
     });
   }
 
   withHaving(having: AnyExpression | undefined): SelectAst {
-    return new SelectAst({ ...this, having });
+    return new SelectAst({ ...this.toOptions(), having });
   }
 
   withLimit(limit: LimitOffsetValue | undefined): SelectAst {
-    return new SelectAst({ ...this, limit });
+    return new SelectAst({ ...this.toOptions(), limit });
   }
 
   withOffset(offset: LimitOffsetValue | undefined): SelectAst {
-    return new SelectAst({ ...this, offset });
+    return new SelectAst({ ...this.toOptions(), offset });
   }
 
   withSelectAllIntent(selectAllIntent: { readonly table?: string } | undefined): SelectAst {
-    return new SelectAst({ ...this, selectAllIntent });
+    return new SelectAst({ ...this.toOptions(), selectAllIntent });
   }
 
   rewrite(rewriter: AstRewriter): SelectAst {
+    const rewrittenFrom = this.from?.rewrite(rewriter);
     const rewritten = new SelectAst({
-      from: this.from.rewrite(rewriter),
+      ...(rewrittenFrom !== undefined ? { from: rewrittenFrom } : {}),
       joins: this.joins?.map((join) => join.rewrite(rewriter)),
       projection: this.projection.map(
         (projection) =>
@@ -1474,8 +1537,12 @@ export class SelectAst extends QueryAst {
       refs.push(...columns);
     };
 
-    if (this.from.kind === 'derived-table-source') {
+    if (this.from?.kind === 'derived-table-source') {
       pushRefs(this.from.query.collectColumnRefs());
+    } else if (this.from?.kind === 'function-source') {
+      for (const arg of this.from.args) {
+        pushRefs(arg.collectColumnRefs());
+      }
     }
 
     for (const projection of this.projection) {
@@ -1502,6 +1569,10 @@ export class SelectAst extends QueryAst {
     for (const join of this.joins ?? []) {
       if (join.source.kind === 'derived-table-source') {
         pushRefs(join.source.query.collectColumnRefs());
+      } else if (join.source.kind === 'function-source') {
+        for (const arg of join.source.args) {
+          pushRefs(arg.collectColumnRefs());
+        }
       }
       if (join.on.kind === 'eq-col-join-on') {
         refs.push(join.on.left, join.on.right);
@@ -1525,8 +1596,12 @@ export class SelectAst extends QueryAst {
       refs.push(...params);
     };
 
-    if (this.from.kind === 'derived-table-source') {
+    if (this.from?.kind === 'derived-table-source') {
       pushRefs(this.from.query.collectParamRefs());
+    } else if (this.from?.kind === 'function-source') {
+      for (const arg of this.from.args) {
+        pushRefs(arg.collectParamRefs());
+      }
     }
 
     for (const projection of this.projection) {
@@ -1553,6 +1628,10 @@ export class SelectAst extends QueryAst {
     for (const join of this.joins ?? []) {
       if (join.source.kind === 'derived-table-source') {
         pushRefs(join.source.query.collectParamRefs());
+      } else if (join.source.kind === 'function-source') {
+        for (const arg of join.source.args) {
+          pushRefs(arg.collectParamRefs());
+        }
       }
       if (!(join.on.kind === 'eq-col-join-on')) {
         pushRefs(join.on.collectParamRefs());
@@ -1899,7 +1978,7 @@ export class RawSqlExpr extends QueryAst {
 }
 
 export type AnyQueryAst = SelectAst | InsertAst | UpdateAst | DeleteAst | RawSqlExpr;
-export type AnyFromSource = TableSource | DerivedTableSource;
+export type AnyFromSource = TableSource | DerivedTableSource | FunctionSource;
 export type AnyExpression =
   | ColumnRef
   | IdentifierRef

package/src/codec-ref-for-column.ts

@@ -1,11 +1,7 @@
 import type { JsonValue } from '@prisma-next/contract/types';
 import type { CodecRef } from '@prisma-next/framework-components/codec';
 import { resolveStorageTable } from '@prisma-next/sql-contract/resolve-storage-table';
-import {
-  isPostgresEnumStorageEntry,
-  isStorageTypeInstance,
-  type SqlStorage,
-} from '@prisma-next/sql-contract/types';
+import { isStorageTypeInstance, type SqlStorage } from '@prisma-next/sql-contract/types';
 
 /**
  * Derive the canonical {@link CodecRef} for a `(table, column)` pair against a {@link SqlStorage}. This is the build-time path every column-bound `ParamRef` / `ProjectionItem` uses to stamp its `codec` slot before the AST is handed to the runtime — the runtime resolver then materialises a memoised {@link import('@prisma-next/sql-relational-core/ast').Codec} for the same `CodecRef` via `forCodecRef`.
@@ -34,38 +30,9 @@ export function codecRefForStorageColumn(
   const columnDef = tableDef.columns[columnName];
   if (!columnDef) return undefined;
   if (columnDef.typeRef !== undefined) {
-    let instance: unknown = storage.types?.[columnDef.typeRef];
-    if (!instance) {
-      for (const ns of Object.values(storage.namespaces)) {
-        const typeSlot = (ns.entries as { type?: Record<string, unknown> }).type;
-        const nsEntry = typeSlot?.[columnDef.typeRef];
-        if (nsEntry !== undefined) {
-          instance = nsEntry;
-          break;
-        }
-      }
-    }
+    const instance = storage.types?.[columnDef.typeRef];
     if (!instance) return undefined;
-    if (isPostgresEnumStorageEntry(instance)) {
-      // Canonical path: the entry is a live `PostgresEnumType` IR
-      // instance reached through the per-target serializer's
-      // hydration. Raw JSON envelopes carrying `kind: 'postgres-enum'`
-      // never reach this site — `SqlStorage.normaliseTypeEntry`
-      // rejects them upstream (F09). Read `codecId` and `values` off
-      // the structural shape (enumerable own properties on the live
-      // instance) so the dispatch stays layered against the family
-      // alphabet rather than a target-specific class import.
-      return {
-        codecId: instance.codecId,
-        typeParams: { values: instance.values } as unknown as JsonValue,
-      };
-    }
     if (isStorageTypeInstance(instance)) {
-      // Empty-state canonicalization: a `StorageTypeInstance` with absent
-      // (or empty) `typeParams` produces a `CodecRef` with no `typeParams`
-      // field. Equivalent to the non-parameterized-column branch below.
-      // Carrying `{}` here would break content-keyed memoisation and trip
-      // the runtime validator against non-parameterized codec descriptors.
       const instanceParams = instance.typeParams;
       const hasParamKeys = instanceParams !== undefined && Object.keys(instanceParams).length > 0;
       return hasParamKeys

package/src/contract-free/column.ts

@@ -1,5 +1,6 @@
 import type { ColumnDefaultLiteralInputValue } from '@prisma-next/contract/types';
 import type { ReferentialAction } from '@prisma-next/sql-contract/types';
+import type { CodecRef } from '../ast/codec-types';
 import type { AnyDdlColumnDefault } from '../ast/ddl-types';
 import {
   DdlColumn,
@@ -14,6 +15,7 @@ export interface DdlColumnOptions {
   readonly notNull?: boolean;
   readonly primaryKey?: boolean;
   readonly default?: AnyDdlColumnDefault;
+  readonly codecRef?: CodecRef;
 }
 
 export function lit(value: ColumnDefaultLiteralInputValue): LiteralColumnDefault {

package/src/contract-free/dml.ts

@@ -1,6 +1,8 @@
 export {
   CfConflictClause,
   CfExpr,
+  CfExprSelectQuery,
+  type CfFnOptions,
   CfInsertQuery,
   CfSelectQuery,
   CfUpdateQuery,
@@ -9,7 +11,10 @@ export {
   type ColumnDescriptor,
   type ColumnProxy,
   type ColumnSchema,
+  cfExpr,
+  cfTable,
   type ExcludedProxy,
+  exprSelect,
   type TableHandle,
   type TableInsertRow,
   type TableSetValues,