@prisma-next/sql-orm-client 0.5.0-dev.8 → 0.5.0-dev.87

package/package.json

@@ -1,37 +1,37 @@
 {
   "name": "@prisma-next/sql-orm-client",
-  "version": "0.5.0-dev.8",
+  "version": "0.5.0-dev.87",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "ORM client for Prisma Next — fluent, type-safe model collections",
   "dependencies": {
-    "@prisma-next/operations": "0.5.0-dev.8",
-    "@prisma-next/sql-contract": "0.5.0-dev.8",
-    "@prisma-next/contract": "0.5.0-dev.8",
-    "@prisma-next/runtime-executor": "0.5.0-dev.8",
-    "@prisma-next/sql-runtime": "0.5.0-dev.8",
-    "@prisma-next/sql-operations": "0.5.0-dev.8",
-    "@prisma-next/utils": "0.5.0-dev.8",
-    "@prisma-next/sql-relational-core": "0.5.0-dev.8"
+    "@prisma-next/contract": "0.5.0-dev.87",
+    "@prisma-next/framework-components": "0.5.0-dev.87",
+    "@prisma-next/operations": "0.5.0-dev.87",
+    "@prisma-next/sql-contract": "0.5.0-dev.87",
+    "@prisma-next/sql-operations": "0.5.0-dev.87",
+    "@prisma-next/sql-relational-core": "0.5.0-dev.87",
+    "@prisma-next/utils": "0.5.0-dev.87",
+    "@prisma-next/sql-runtime": "0.5.0-dev.87"
   },
   "devDependencies": {
-    "@types/pg": "8.16.0",
-    "pg": "8.16.3",
-    "tsdown": "0.18.4",
+    "@types/pg": "8.20.0",
+    "pg": "8.20.0",
+    "tsdown": "0.22.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.17",
-    "@prisma-next/adapter-postgres": "0.5.0-dev.8",
-    "@prisma-next/cli": "0.5.0-dev.8",
-    "@prisma-next/driver-postgres": "0.5.0-dev.8",
-    "@prisma-next/extension-pgvector": "0.5.0-dev.8",
-    "@prisma-next/family-sql": "0.5.0-dev.8",
-    "@prisma-next/ids": "0.5.0-dev.8",
-    "@prisma-next/framework-components": "0.5.0-dev.8",
-    "@prisma-next/sql-contract-ts": "0.5.0-dev.8",
-    "@prisma-next/target-postgres": "0.5.0-dev.8",
+    "vitest": "4.1.5",
+    "@prisma-next/adapter-postgres": "0.5.0-dev.87",
+    "@prisma-next/extension-pgvector": "0.5.0-dev.87",
+    "@prisma-next/driver-postgres": "0.5.0-dev.87",
+    "@prisma-next/family-sql": "0.5.0-dev.87",
+    "@prisma-next/cli": "0.5.0-dev.87",
+    "@prisma-next/ids": "0.5.0-dev.87",
+    "@prisma-next/sql-contract-ts": "0.5.0-dev.87",
+    "@prisma-next/target-postgres": "0.5.0-dev.87",
     "@prisma-next/test-utils": "0.0.1",
-    "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/tsdown": "0.0.0"
+    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/tsconfig": "0.0.0"
   },
   "files": [
     "dist",
@@ -44,8 +44,6 @@
     ".": "./dist/index.mjs",
     "./package.json": "./package.json"
   },
-  "main": "./dist/index.mjs",
-  "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "repository": {
     "type": "git",

package/src/collection-contract.ts

@@ -322,6 +322,25 @@ export function resolvePrimaryKeyColumn(contract: Contract<SqlStorage>, tableNam
   return contract.storage.tables[tableName]?.primaryKey?.columns[0] ?? 'id';
 }
 
+export function resolveRowIdentityColumns(
+  contract: Contract<SqlStorage>,
+  tableName: string,
+): readonly string[] {
+  const table = contract.storage.tables[tableName];
+  if (!table) {
+    return [];
+  }
+  if (table.primaryKey && table.primaryKey.columns.length > 0) {
+    return table.primaryKey.columns;
+  }
+  for (const unique of table.uniques) {
+    if (unique.columns.length > 0) {
+      return unique.columns;
+    }
+  }
+  return [];
+}
+
 export function assertReturningCapability(contract: Contract<SqlStorage>, action: string): void {
   if (hasContractCapability(contract, 'returning')) {
     return;

package/src/collection-dispatch.ts

@@ -15,8 +15,9 @@
  */
 
 import type { Contract } from '@prisma-next/contract/types';
-import { AsyncIterableResult } from '@prisma-next/runtime-executor';
+import { AsyncIterableResult } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import type { RuntimeScope } from '@prisma-next/sql-relational-core/types';
 import { isToOneCardinality, resolvePolymorphismInfo } from './collection-contract';
 import {
   acquireRuntimeScope,
@@ -41,7 +42,6 @@ import type {
   IncludeExpr,
   IncludeScalar,
   RelationCardinalityTag,
-  RuntimeScope,
 } from './types';
 
 export function dispatchCollectionRows<Row>(options: {

package/src/collection-mutation-dispatch.ts

@@ -1,5 +1,5 @@
 import type { Contract } from '@prisma-next/contract/types';
-import { AsyncIterableResult } from '@prisma-next/runtime-executor';
+import { AsyncIterableResult } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
 import { stitchIncludes } from './collection-dispatch';

package/src/collection-runtime.ts

@@ -1,13 +1,14 @@
 import type { Contract } from '@prisma-next/contract/types';
-import { AsyncIterableResult } from '@prisma-next/runtime-executor';
+import { AsyncIterableResult } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import type { RuntimeScope } from '@prisma-next/sql-relational-core/types';
 import {
   getColumnToFieldMap,
   getCompleteColumnToFieldMap,
   getFieldToColumnMap,
   type PolymorphismInfo,
 } from './collection-contract';
-import type { CollectionContext, RuntimeConnection, RuntimeScope } from './types';
+import type { CollectionContext, RuntimeConnection } from './types';
 
 export interface RowEnvelope {
   readonly raw: Record<string, unknown>;

package/src/collection.ts

@@ -1,7 +1,8 @@
 import type { Contract } from '@prisma-next/contract/types';
-import { AsyncIterableResult } from '@prisma-next/runtime-executor';
+import { AsyncIterableResult } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import {
+  type AnyExpression,
   BinaryExpr,
   ColumnRef,
   isWhereExpr,
@@ -25,6 +26,7 @@ import {
   resolveModelTableName,
   resolvePolymorphismInfo,
   resolvePrimaryKeyColumn,
+  resolveRowIdentityColumns,
   resolveUpsertConflictColumns,
 } from './collection-contract';
 import { dispatchCollectionRows } from './collection-dispatch';
@@ -107,6 +109,7 @@ import {
   type RelatedModelName,
   type RelationNames,
   type ResolvedCreateInput,
+  type RuntimeQueryable,
   type ShorthandWhereFilter,
   type UniqueConstraintCriterion,
   type VariantModelRow,
@@ -119,11 +122,17 @@ function applyCreateDefaults(
   tableName: string,
   rows: Record<string, unknown>[],
 ): void {
+  // Per-operation cache for generators with `stability: 'query'` (e.g.
+  // `timestampNow` for `temporal.updatedAt()`): one generated value
+  // shared across every row in this insert. Per-field generators
+  // (e.g. `cuid`) ignore the cache and vary per row.
+  const defaultValueCache = rows.length > 1 ? new Map<string, unknown>() : undefined;
   for (const row of rows) {
     const applied = ctx.context.applyMutationDefaults({
       op: 'create',
       table: tableName,
       values: row,
+      ...(defaultValueCache ? { defaultValueCache } : {}),
     });
     for (const def of applied) {
       row[def.column] = def.value;
@@ -131,6 +140,21 @@ function applyCreateDefaults(
   }
 }
 
+function applyUpdateDefaults(
+  ctx: CollectionContext<Contract<SqlStorage>>,
+  tableName: string,
+  values: Record<string, unknown>,
+): void {
+  const applied = ctx.context.applyMutationDefaults({
+    op: 'update',
+    table: tableName,
+    values,
+  });
+  for (const def of applied) {
+    values[def.column] = def.value;
+  }
+}
+
 type WhereDirectInput = WhereArg;
 
 function isToWhereExprInput(value: unknown): value is ToWhereExpr {
@@ -965,6 +989,9 @@ export class Collection<
     applyCreateDefaults(this.ctx, this.tableName, [createValues]);
     const updateValues = mapModelDataToStorageRow(this.contract, this.modelName, input.update);
     const hasUpdateValues = Object.keys(updateValues).length > 0;
+    if (hasUpdateValues) {
+      applyUpdateDefaults(this.ctx, this.tableName, updateValues);
+    }
     const conflictColumns = resolveUpsertConflictColumns(
       this.contract,
       this.modelName,
@@ -1038,12 +1065,20 @@ export class Collection<
       return this.#reloadMutationRowByPrimaryKey(pkCriterion);
     }
 
-    const rows = await this.updateAll(
-      data as State['hasWhere'] extends true
-        ? Partial<DefaultModelRow<TContract, ModelName>>
-        : never,
-    );
-    return rows[0] ?? null;
+    return withMutationScope(this.ctx.runtime, async (scope) => {
+      const scoped = this.#withRuntime(scope);
+      const identityWhere = await scoped.#findFirstMatchingRowIdentityWhere();
+      if (!identityWhere) {
+        return null;
+      }
+      const narrowed = scoped.#clone({ filters: [identityWhere] });
+      const rows = await narrowed.updateAll(
+        data as State['hasWhere'] extends true
+          ? Partial<DefaultModelRow<TContract, ModelName>>
+          : never,
+      );
+      return rows[0] ?? null;
+    });
   }
 
   updateAll(
@@ -1057,6 +1092,8 @@ export class Collection<
       return new AsyncIterableResult(generator());
     }
 
+    applyUpdateDefaults(this.ctx, this.tableName, mappedData);
+
     const parentJoinColumns = this.state.includes.map((include) => include.localColumn);
     const { selectedForQuery: selectedForUpdate, hiddenColumns } = augmentSelectionForJoinColumns(
       this.state.selectedFields,
@@ -1088,6 +1125,8 @@ export class Collection<
       return 0;
     }
 
+    applyUpdateDefaults(this.ctx, this.tableName, mappedData);
+
     const primaryKeyColumn = resolvePrimaryKeyColumn(this.contract, this.tableName);
     const countState: CollectionState = {
       ...emptyState(),
@@ -1115,15 +1154,26 @@ export class Collection<
     this: State['hasWhere'] extends true ? Collection<TContract, ModelName, Row, State> : never,
   ): Promise<Row | null> {
     assertReturningCapability(this.contract, 'delete()');
-    const rows = await this.deleteAll().toArray();
-    return rows[0] ?? null;
+    return withMutationScope(this.ctx.runtime, async (scope) => {
+      const scoped = this.#withRuntime(scope);
+      const identityWhere = await scoped.#findFirstMatchingRowIdentityWhere();
+      if (!identityWhere) {
+        return null;
+      }
+      const narrowed = scoped.#clone({ filters: [identityWhere] });
+      const rows = await narrowed.#executeDeleteReturning().toArray();
+      return rows[0] ?? null;
+    });
   }
 
   deleteAll(
     this: State['hasWhere'] extends true ? Collection<TContract, ModelName, Row, State> : never,
   ): AsyncIterableResult<Row> {
     assertReturningCapability(this.contract, 'deleteAll()');
+    return this.#executeDeleteReturning();
+  }
 
+  #executeDeleteReturning(): AsyncIterableResult<Row> {
     const parentJoinColumns = this.state.includes.map((include) => include.localColumn);
     const { selectedForQuery: selectedForDelete, hiddenColumns } = augmentSelectionForJoinColumns(
       this.state.selectedFields,
@@ -1188,6 +1238,41 @@ export class Collection<
     return criterion;
   }
 
+  async #findFirstMatchingRowIdentityWhere(): Promise<AnyExpression | null> {
+    const identityColumns = resolveRowIdentityColumns(this.contract, this.tableName);
+    if (identityColumns.length === 0) {
+      throw new Error(
+        `update()/delete() on model "${this.modelName}" requires the table to have a primary key or unique constraint`,
+      );
+    }
+    const firstRow = await this.#clone({
+      selectedFields: [...identityColumns],
+      includes: [],
+    }).first();
+    if (!firstRow) {
+      return null;
+    }
+    const columnToField = getColumnToFieldMap(this.contract, this.modelName);
+    const criterion: Record<string, unknown> = {};
+    for (const column of identityColumns) {
+      const fieldName = columnToField[column] ?? column;
+      const value = (firstRow as Record<string, unknown>)[fieldName];
+      if (value === undefined) {
+        throw new Error(
+          `Missing identity field "${fieldName}" while resolving single-row scope for model "${this.modelName}"`,
+        );
+      }
+      criterion[fieldName] = value;
+    }
+    return (
+      shorthandToWhereExpr(
+        this.ctx.context,
+        this.modelName,
+        criterion as ShorthandWhereFilter<TContract, ModelName>,
+      ) ?? null
+    );
+  }
+
   async #reloadMutationRowByPrimaryKey(criterion: Record<string, unknown>): Promise<Row | null> {
     return this.#reloadMutationRowByCriterion(criterion, 'primary key');
   }
@@ -1242,6 +1327,16 @@ export class Collection<
     });
   }
 
+  #withRuntime(runtime: RuntimeQueryable): Collection<TContract, ModelName, Row, State> {
+    const Ctor = this.constructor as CollectionConstructor<TContract>;
+    return new Ctor({ ...this.ctx, runtime }, this.modelName, {
+      tableName: this.tableName,
+      state: this.state,
+      registry: this.registry,
+      includeRefinementMode: this.includeRefinementMode,
+    }) as unknown as Collection<TContract, ModelName, Row, State>;
+  }
+
   #cloneWithRow<NextRow, NextState extends CollectionTypeState = State>(
     overrides: Partial<CollectionState>,
   ): Collection<TContract, ModelName, NextRow, NextState> {

package/src/execute-query-plan.ts

@@ -1,11 +1,10 @@
-import type { ExecutionPlan } from '@prisma-next/contract/types';
-import type { AsyncIterableResult } from '@prisma-next/runtime-executor';
-import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
-import type { RuntimeScope } from './types';
+import type { AsyncIterableResult } from '@prisma-next/framework-components/runtime';
+import type { SqlExecutionPlan, SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import type { RuntimeScope } from '@prisma-next/sql-relational-core/types';
 
 export function executeQueryPlan<Row>(
   scope: RuntimeScope,
-  plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+  plan: SqlExecutionPlan<Row> | SqlQueryPlan<Row>,
 ): AsyncIterableResult<Row> {
   return scope.execute(plan);
 }

package/src/filters.ts

@@ -73,7 +73,7 @@ function assertFieldHasEqualityTrait(
 ): void {
   const fieldType = modelOf(context.contract, modelName)?.fields?.[fieldName]?.type;
   const codecId = fieldType?.kind === 'scalar' ? fieldType.codecId : undefined;
-  const traits = codecId ? context.codecs.traitsOf(codecId) : [];
+  const traits = codecId ? (context.codecDescriptors.descriptorFor(codecId)?.traits ?? []) : [];
   if (!traits.includes('equality')) {
     throw new Error(
       `Shorthand filter on "${modelName}.${fieldName}": field does not support equality comparisons`,

package/src/include-strategy.ts

@@ -3,10 +3,29 @@ import type { SqlStorage } from '@prisma-next/sql-contract/types';
 
 export type IncludeStrategy = 'lateral' | 'correlated' | 'multiQuery';
 
+/**
+ * Choose the SQL emission strategy for nested includes based on the
+ * contract's declared capabilities.
+ *
+ * - `'lateral'`: outer SELECT with one LATERAL JOIN per relation,
+ *   aggregating to JSON. Requires both `lateral` and `jsonAgg`.
+ *   Postgres has both.
+ * - `'correlated'`: outer SELECT with one correlated subquery per
+ *   relation, aggregating to JSON. Requires `jsonAgg` only.
+ *   SQLite has `jsonAgg` (via `json_group_array`) but no LATERAL.
+ * - `'multiQuery'`: fallback. One SELECT per relation, stitched
+ *   together in JS via `WHERE pk IN (parent-pk-values)`. Always
+ *   correct; just N+1 round-trips.
+ *
+ * The capability flags are looked up under the contract's
+ * `targetFamily` and `target` namespaces — the two layers the contract
+ * emitter actually populates. Cross-namespace ("`postgres.lateral`
+ * found while running SQLite") false positives are impossible because
+ * we only inspect the running target's namespaces.
+ */
 export function selectIncludeStrategy(contract: Contract<SqlStorage>): IncludeStrategy {
-  const capabilities = contract.capabilities as Record<string, unknown> | undefined;
-  const hasLateral = hasCapability(capabilities?.['lateral']);
-  const hasJsonAgg = hasCapability(capabilities?.['jsonAgg']);
+  const hasLateral = capabilityFlag(contract, 'lateral');
+  const hasJsonAgg = capabilityFlag(contract, 'jsonAgg');
 
   if (hasLateral && hasJsonAgg) {
     return 'lateral';
@@ -19,15 +38,18 @@ export function selectIncludeStrategy(contract: Contract<SqlStorage>): IncludeSt
   return 'multiQuery';
 }
 
-function hasCapability(value: unknown): boolean {
-  if (value === true) {
-    return true;
-  }
-
-  if (typeof value !== 'object' || value === null) {
-    return false;
-  }
-
-  const flags = value as Record<string, unknown>;
-  return Object.values(flags).some((flag) => flag === true);
+/**
+ * Read a capability flag from the contract's target/family namespaces.
+ *
+ * The contract emitter populates `capabilities[targetFamily]` (universal
+ * SQL flags like `jsonAgg`, `returning`) and `capabilities[target]`
+ * (target-specific flags like `lateral` on Postgres). Either may
+ * declare a given flag; the family namespace declares the floor and the
+ * target namespace can extend on top.
+ */
+function capabilityFlag(contract: Contract<SqlStorage>, flag: string): boolean {
+  return (
+    contract.capabilities[contract.targetFamily]?.[flag] === true ||
+    contract.capabilities[contract.target]?.[flag] === true
+  );
 }

package/src/model-accessor.ts

@@ -7,12 +7,11 @@ import {
   BinaryExpr,
   ColumnRef,
   ExistsExpr,
-  OperationExpr,
-  ParamRef,
   ProjectionItem,
   SelectAst,
   TableSource,
 } from '@prisma-next/sql-relational-core/ast';
+import type { Expression, ScopeField } from '@prisma-next/sql-relational-core/expression';
 import type { ExecutionContext } from '@prisma-next/sql-relational-core/query-lane-context';
 import {
   getFieldToColumnMap,
@@ -67,15 +66,16 @@ export function createModelAccessor<
   }
 
   for (const [name, entry] of Object.entries(context.queryOperations.entries())) {
-    const self = entry.args[0];
     const op: NamedOp = [name, entry];
-    if (self?.codecId) {
+    const self = entry.self;
+    if (!self) continue;
+    if (self.codecId !== undefined) {
       registerOp(self.codecId, op);
-    } else if (self?.traits) {
-      for (const codec of context.codecs.values()) {
-        const codecTraits: readonly string[] = codec.traits ?? [];
-        if (self.traits.every((t) => codecTraits.includes(t))) {
-          registerOp(codec.id, op);
+    } else if (self.traits !== undefined) {
+      for (const descriptor of context.codecDescriptors.values()) {
+        const descriptorTraits: readonly string[] = descriptor.traits;
+        if (self.traits.every((t) => descriptorTraits.includes(t))) {
+          registerOp(descriptor.codecId, op);
         }
       }
     }
@@ -93,96 +93,96 @@ export function createModelAccessor<
       }
 
       const columnName = fieldToColumn[prop] ?? prop;
-      const traits = resolveFieldTraits(contract, modelName, prop, context);
-      const codecId = resolveFieldCodecId(contract, tableName, columnName);
-      const operations = codecId ? (opsByCodecId.get(codecId) ?? []) : [];
-      return createScalarFieldAccessor(tableName, columnName, codecId, traits, operations, context);
+      const column = resolveColumn(contract, tableName, columnName);
+      // Unknown fields return `undefined`, matching plain JS object semantics.
+      // The `ModelAccessor<TContract, ModelName>` type already rejects typos
+      // at compile time for TS consumers, and contexts that iterate accessor
+      // keys (e.g. relation-shorthand predicates) can detect missing fields
+      // with an `undefined` check and raise their own, domain-specific error.
+      if (!column) {
+        return undefined;
+      }
+      const traits = context.codecDescriptors.descriptorFor(column.codecId)?.traits ?? [];
+      const operations = opsByCodecId.get(column.codecId) ?? [];
+      return createScalarFieldAccessor(
+        tableName,
+        columnName,
+        column.codecId,
+        column.nullable,
+        traits,
+        operations,
+        context,
+      );
     },
   });
 }
 
-function resolveFieldTraits(
-  contract: Contract<SqlStorage>,
-  modelName: string,
-  fieldName: string,
-  context: ExecutionContext,
-): readonly string[] {
-  const fieldType = modelOf(contract, modelName)?.fields?.[fieldName]?.type;
-  const codecId = fieldType?.kind === 'scalar' ? fieldType.codecId : undefined;
-  if (!codecId) return [];
-  return context.codecs.traitsOf(codecId);
-}
-
-function resolveFieldCodecId(
+function resolveColumn(
   contract: Contract<SqlStorage>,
   tableName: string,
   columnName: string,
-): string | undefined {
-  const table = contract.storage.tables?.[tableName];
-  return table?.columns?.[columnName]?.codecId;
+): { readonly codecId: string; readonly nullable: boolean } | undefined {
+  const column = contract.storage.tables?.[tableName]?.columns?.[columnName];
+  if (!column) return undefined;
+  return { codecId: column.codecId, nullable: column.nullable };
 }
 
 function createScalarFieldAccessor(
   tableName: string,
   columnName: string,
-  codecId: string | undefined,
+  codecId: string,
+  nullable: boolean,
   traits: readonly string[],
   operations: readonly NamedOp[],
   context: ExecutionContext,
 ): Partial<ComparisonMethodFns<unknown>> {
   const column = ColumnRef.of(tableName, columnName);
-  const methods: Record<string, unknown> = {};
-
+  const comparisonEntries: Array<[string, unknown]> = [];
   for (const [name, meta] of Object.entries(COMPARISON_METHODS_META)) {
-    if (meta.traits.some((t) => !traits.includes(t))) {
-      continue;
-    }
-    methods[name] = meta.create(column, codecId);
+    if (meta.traits.some((t) => !traits.includes(t))) continue;
+    comparisonEntries.push([name, meta.create(column, codecId)]);
   }
 
+  const accessor = {
+    returnType: { codecId, nullable },
+    buildAst: () => column,
+    ...Object.fromEntries(comparisonEntries),
+  } as Expression<ScopeField> & Record<string, unknown>;
+
   for (const [name, entry] of operations) {
-    methods[name] = createExtensionMethodFactory(column, name, entry, context);
+    accessor[name] = createExtensionMethodFactory(accessor, entry, context);
   }
 
-  return methods as Partial<ComparisonMethodFns<unknown>>;
+  return accessor as Partial<ComparisonMethodFns<unknown>>;
 }
 
 function createExtensionMethodFactory(
-  column: ColumnRef,
-  methodName: string,
+  selfExpr: Expression<ScopeField>,
   entry: SqlOperationEntry,
   context: ExecutionContext,
 ): (...args: unknown[]) => unknown {
-  const returnTraits = context.codecs.traitsOf(entry.returns.codecId);
-  const isPredicate = returnTraits.includes('boolean');
-
   return (...args: unknown[]) => {
-    const userArgSpecs = entry.args.slice(1);
-    const astArgs = userArgSpecs.map((argSpec, i) => {
-      return ParamRef.of(args[i], argSpec.codecId ? { codecId: argSpec.codecId } : undefined);
-    });
-
-    const opExpr = new OperationExpr({
-      method: methodName,
-      self: column,
-      args: astArgs,
-      returns: entry.returns,
-      lowering: entry.lowering,
-    });
+    // `entry.impl` is typed `(...args: never[]) => QueryOperationReturn` —
+    // `never[]` args block direct invocation with unknown values, and the
+    // declared return omits `buildAst` (sql-contract intentionally doesn't
+    // depend on relational-core). Cast here to the practical shape: authors
+    // always return Expression<ScopeField> via `buildOperation`.
+    const impl = entry.impl as (self: unknown, ...args: unknown[]) => Expression<ScopeField>;
+    const result = impl(selfExpr, ...args);
+    const returnCodecId = result.returnType.codecId;
+    const returnTraits = context.codecDescriptors.descriptorFor(returnCodecId)?.traits ?? [];
+    const isPredicate = returnTraits.includes('boolean');
 
     if (isPredicate) {
-      return opExpr;
+      return result.buildAst();
     }
 
+    const resultAst = result.buildAst();
     const methods: Record<string, unknown> = {};
-
     for (const [resultMethodName, meta] of Object.entries(COMPARISON_METHODS_META)) {
-      if (meta.traits.some((t) => !returnTraits.includes(t))) {
-        continue;
-      }
-      methods[resultMethodName] = meta.create(opExpr, entry.returns.codecId);
+      if (meta.traits.some((t) => !returnTraits.includes(t))) continue;
+      methods[resultMethodName] = meta.create(resultAst, returnCodecId);
     }
-
     return methods;
   };
 }
@@ -293,8 +293,14 @@ function toRelationWhereExpr<TContract extends Contract<SqlStorage>>(
     const fieldAccessor = (accessor as Record<string, Partial<ComparisonMethodFns<unknown>>>)[
       fieldName
     ];
+    // Unknown field in the shorthand predicate — the Proxy returns undefined
+    // for fields the contract doesn't declare. Surface it explicitly: silent
+    // skip would drop user intent (e.g. a typo'd `nmae: 'Alice'` filter would
+    // match every row).
     if (!fieldAccessor) {
-      continue;
+      throw new Error(
+        `Shorthand filter on "${relatedModelName}.${fieldName}": field is not defined on the model`,
+      );
     }
 
     if (value === null) {