fix(sql-orm-client): scope single-row mutations by full row identity

The previous fix scoped update()/delete() by `resolvePrimaryKeyColumn`,
which only returns the first PK column. Composite primary keys would
collapse to a single column and fail to identify a row uniquely, and
PK-less tables (with a unique constraint instead) had no path at all.

Introduce `resolveRowIdentityColumns`: PK columns if present, else the
first unique constraint, else throw. The lookup helper now projects all
identity columns and builds a multi-column WHERE criterion via
`shorthandToWhereExpr`, which produces the AND-of-equalities filter that
uniquely identifies the row.

Also wrap the SELECT-then-mutate pair in `withMutationScope` so both
queries run against the same transaction-bound scope, matching what
`executeNestedUpdateMutation` already does for the nested-callback path.
A new `#withRuntime` helper clones the collection bound to the scoped
runtime so the existing Collection-level helpers (`first`, `updateAll`,
`#executeDeleteReturning`) continue to work inside the callback.

Author: SevInf

packages/3-extensions/sql-orm-client/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;

packages/3-extensions/sql-orm-client/src/collection.ts

@@ -26,6 +26,7 @@ import {
   resolveModelTableName,
   resolvePolymorphismInfo,
   resolvePrimaryKeyColumn,
+  resolveRowIdentityColumns,
   resolveUpsertConflictColumns,
 } from './collection-contract';
 import { dispatchCollectionRows } from './collection-dispatch';
@@ -108,6 +109,7 @@ import {
   type RelatedModelName,
   type RelationNames,
   type ResolvedCreateInput,
+  type RuntimeQueryable,
   type ShorthandWhereFilter,
   type UniqueConstraintCriterion,
   type VariantModelRow,
@@ -1063,17 +1065,20 @@ export class Collection<
       return this.#reloadMutationRowByPrimaryKey(pkCriterion);
     }
 
-    const pkWhere = await this.#findFirstMatchingPkWhere();
-    if (!pkWhere) {
-      return null;
-    }
-    const narrowed = this.#clone({ filters: [pkWhere] });
-    const rows = await narrowed.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(
@@ -1149,13 +1154,16 @@ export class Collection<
     this: State['hasWhere'] extends true ? Collection<TContract, ModelName, Row, State> : never,
   ): Promise<Row | null> {
     assertReturningCapability(this.contract, 'delete()');
-    const pkWhere = await this.#findFirstMatchingPkWhere();
-    if (!pkWhere) {
-      return null;
-    }
-    const narrowed = this.#clone({ filters: [pkWhere] });
-    const rows = await narrowed.#executeDeleteReturning().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(
@@ -1230,22 +1238,37 @@ export class Collection<
     return criterion;
   }
 
-  async #findFirstMatchingPkWhere(): Promise<AnyExpression | null> {
-    const pkColumn = resolvePrimaryKeyColumn(this.contract, this.tableName);
-    const firstRow = await this.#clone({ selectedFields: [pkColumn], includes: [] }).first();
+  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 pkCriterion = buildPrimaryKeyFilterFromRow(
-      this.contract,
-      this.modelName,
-      firstRow as Record<string, unknown>,
-    );
+    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,
-        pkCriterion as ShorthandWhereFilter<TContract, ModelName>,
+        criterion as ShorthandWhereFilter<TContract, ModelName>,
       ) ?? null
     );
   }
@@ -1304,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> {

packages/3-extensions/sql-orm-client/test/collection-contract.test.ts

@@ -7,6 +7,7 @@ import {
   resolveModelTableName,
   resolvePolymorphismInfo,
   resolvePrimaryKeyColumn,
+  resolveRowIdentityColumns,
   resolveUpsertConflictColumns,
 } from '../src/collection-contract';
 import { buildMixedPolyContract, getTestContract } from './helpers';
@@ -235,6 +236,63 @@ describe('collection-contract capability detection', () => {
     expect(isToOneCardinality('M:N')).toBe(false);
     expect(isToOneCardinality(undefined)).toBe(false);
   });
+
+  describe('resolveRowIdentityColumns()', () => {
+    const buildContract = (table: {
+      primaryKey?: { columns: readonly string[] };
+      uniques?: ReadonlyArray<{ columns: readonly string[] }>;
+    }) =>
+      ({
+        storage: {
+          tables: {
+            t: {
+              primaryKey: table.primaryKey,
+              uniques: table.uniques ?? [],
+            },
+          },
+        },
+      }) as unknown as Parameters<typeof resolveRowIdentityColumns>[0];
+
+    it('returns primary key columns when present', () => {
+      expect(
+        resolveRowIdentityColumns(buildContract({ primaryKey: { columns: ['id'] } }), 't'),
+      ).toEqual(['id']);
+    });
+
+    it('returns composite primary key columns when present', () => {
+      expect(
+        resolveRowIdentityColumns(buildContract({ primaryKey: { columns: ['a', 'b'] } }), 't'),
+      ).toEqual(['a', 'b']);
+    });
+
+    it('falls back to first unique constraint when no primary key', () => {
+      expect(
+        resolveRowIdentityColumns(
+          buildContract({ uniques: [{ columns: ['email'] }, { columns: ['handle'] }] }),
+          't',
+        ),
+      ).toEqual(['email']);
+    });
+
+    it('returns composite unique columns when no primary key', () => {
+      expect(
+        resolveRowIdentityColumns(
+          buildContract({ uniques: [{ columns: ['tenant_id', 'slug'] }] }),
+          't',
+        ),
+      ).toEqual(['tenant_id', 'slug']);
+    });
+
+    it('returns empty array when neither primary key nor uniques are defined', () => {
+      expect(resolveRowIdentityColumns(buildContract({}), 't')).toEqual([]);
+    });
+
+    it('returns empty array for unknown tables', () => {
+      expect(
+        resolveRowIdentityColumns(buildContract({ primaryKey: { columns: ['id'] } }), 'missing'),
+      ).toEqual([]);
+    });
+  });
 });
 
 describe('resolvePolymorphismInfo()', () => {