feat(sql-orm-client): complete id-less ORM support

[jkomyno]

Linear: TML-2432 — sql-orm-client: complete id-less ORM mutation paths

Stacked on #424. Targets feat/idless-models so the doc section it references lands in the same chain; rebase on main once #424 merges.

Intent

Make id-less SQL models (tables emitted from PSL without @id/@@id) work end-to-end through the ORM lane. This PR landed in three increments along the plan in plans/feat-complete-idless-orm-support.md. After this PR, the doc section docs/architecture docs/subsystems/3. Query Lanes.md § "Id-less tables" describes a stable end state with no "future work" bullets.

What changed

M0 — Typed-error gate (eabd81a3b)

Convert the silent 'id' default in resolvePrimaryKeyColumn into an operation-tagged error. Stops the silent-failure mode where ORM helpers built SQL referencing a literal id column that may not exist on id-less tables.

M1 — Counts via UPDATE/DELETE…RETURNING (b6b7eba8e)

Replace the SELECT-PK-first-then-UPDATE pattern in updateCount() / deleteCount() with a single UPDATE … RETURNING / DELETE … RETURNING that counts the streamed rows. Side effects:

• No PK fallback at these sites — id-less compatible.
• One round-trip instead of two.
• Closes the prior SELECT-then-UPDATE race window.
• updateCount/deleteCount now formally require the returning capability.

M2 — Row-identity criterion for mutation reload (f977896b7)

Rename buildPrimaryKeyFilterFromRow to buildRowIdentityCriterion with two paths:

• PK fast path: when the table declares a primary key, build a PK-keyed criterion. Composite PKs include every PK column (the previous helper used only columns[0], a latent bug).
• Id-less path: build a criterion from the row's mapped non-null column values. The row was just produced by RETURNING in the open mutation transaction, so the criterion matches by construction.

Drop the #reloadMutationRowByPrimaryKey wrapper; both nested-mutation reload sites now call #reloadMutationRowByCriterion directly.

M3 — Doc rewrite + id-less integration tests (90043c101)

Rewrite docs/architecture docs/subsystems/3. Query Lanes.md § "Id-less tables" as the live end state. Drop the "Future work" bullets. Narrow the PK-required call list to MTI polymorphism (which is PK-required by design — the variant join cannot be expressed in one statement without a stable identity column).

Add test/integration/idless.test.ts exercising updateCount() and deleteCount() on a Tag collection bound to a contract with primaryKey stripped from the storage table.

Behavior change summary

Surface	Before	After
resolvePrimaryKeyColumn on id-less tables	returns 'id' (silent)	throws operation-tagged error
updateCount / deleteCount	SELECT id WHERE … then UPDATE / DELETE	UPDATE / DELETE … RETURNING + count rows
Mutation reload after nested create/update	PK-only criterion (single column)	composite-PK aware on PK tables; row-tuple criterion on id-less tables
MTI polymorphism on id-less base table	silently used 'id' (broken)	throws operation-tagged error (intentional design constraint)

No previously valid PK-tabled contract regresses: every M1/M2 change preserves PK-table behavior on the fast path. The composite-PK widening at M2 fixes a latent bug where the previous helper ignored every PK column except the first.

Validation

• pnpm --filter @prisma-next/sql-orm-client test — 498 pass, 3 skipped (no regressions; +5 new tests across M1/M2/M3).
• pnpm --filter @prisma-next/sql-orm-client typecheck — clean.
• pnpm test:packages — 110 / 110 tasks green.
• pnpm lint:deps — 0 dependency violations.

Test plan

• Unit: updateCount() issues a single UPDATE…RETURNING, applies generated updatedAt defaults to the SET clause.
• Unit: buildRowIdentityCriterion PK fast path (single + composite PK), id-less path (non-null criterion + empty-row error).
• Integration: id-less updateCount() + deleteCount() against PGlite with a real PG table whose primaryKey is stripped from the contract.
• Existing PK integration tests for updateCount/deleteCount/update/delete continue to pass — regression guard.

Out of scope (deferred, documented in plan)

• Per-model capability primitive in the contract schema (models.<X>.capabilities.pkRequired). Not needed once all PK-fallback sites are resolved or design-required.
• Explicit-predicate variants of count helpers — COUNT(*)-equivalent via RETURNING already removes the dependency.
• findUnique analogues keyed on non-PK uniques — where(uniqueShape).first() already covers it.
• MySQL adapter changes — no MySQL adapter in tree.
• Compile-time TS gating of MTI methods on id-less base tables — runtime gate is sufficient.

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for ORM operations on tables without primary keys, using unique constraints or row-identity criteria for mutations.

• Documentation

  • Documented id-less table constraints: nested updates/deletes require a primary key or unique constraint; MTI polymorphism unsupported on id-less base tables.
  • Added SQLite caveat: AFTER triggers may affect id-less mutation reload accuracy.

• Improvements

  • Refactored updateCount() and deleteCount() to use single-statement RETURNING queries instead of separate SELECTs.

• Tests

  • Added integration tests for id-less table mutations and count operations.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces id-less table support to the SQL ORM client by replacing primary-key-based mutation reload with a row-identity criterion derived from RETURNING rows, refactoring count helpers to use single-statement RETURNING iteration instead of separate SELECT, enforcing PK/unique constraints for nested updates, pruning query-plan exports, and providing comprehensive unit/integration tests and decision documentation.

Changes

Id-less ORM Support

Layer / File(s)	Summary
Architecture Documentation docs/architecture docs/subsystems/3. Query Lanes.md, packages/2-sql/2-authoring/contract-psl/test/interpreter.test.ts	Query Lanes doc adds "Id-less tables" specification describing supported ORM operations, reload identity rules, nested-mutation constraints, MTI restrictions, and SQLite AFTER-trigger caveat. PSL interpreter test validates id-less and composite-PK table round-trips.
Contract API Helpers packages/3-extensions/sql-orm-client/src/collection-contract.ts	getPrimaryKeyColumns helper centralizes primary-key access; resolvePrimaryKeyColumn now requires explicit operation context and throws when table lacks PK (removes fallback to 'id').
Row-Identity Criterion packages/3-extensions/sql-orm-client/src/mutation-executor.ts	New buildRowIdentityCriterion builds deterministic identity from RETURNING rows: uses PK-mapped fields when present, otherwise non-null mapped fields; throws when no identity fields exist.
Nested-Update Guards packages/3-extensions/sql-orm-client/src/mutation-executor.ts	updateFirstGraph enforces PK or unique constraint requirement for id-less nested updates; validates unique-constraint columns are non-null when no PK exists; throws descriptive errors.
Collection Reload Refactor packages/3-extensions/sql-orm-client/src/collection.ts	Nested create() and update() now reload via row-identity criterion instead of PK-based reload. MTI create() threads operation message to resolvePrimaryKeyColumn. Removes private #reloadMutationRowByPrimaryKey helper.
Count Helpers via RETURNING packages/3-extensions/sql-orm-client/src/collection.ts	updateCount() and deleteCount() now compile UPDATE/DELETE RETURNING, iterate rows, and return count. New #returningColumnForCount() selects minimal column (preferring PK).
Query-Plan Exports Pruned packages/3-extensions/sql-orm-client/src/query-plan-mutations.ts, packages/3-extensions/sql-orm-client/src/query-plan.ts	compileDeleteCount removed from implementation and re-exports; compileUpdateCount re-exported separately from query-plan-mutations.
MTI and Imports packages/3-extensions/sql-orm-client/src/query-plan-select.ts, packages/3-extensions/sql-orm-client/src/mutation-executor.ts	buildMtiJoins passes explicit operation message to resolvePrimaryKeyColumn. Mutation-executor imports refactored to use buildRowIdentityCriterion and getPrimaryKeyColumns; adds FK-rewrite cleanup comment.
Test Helpers packages/3-extensions/sql-orm-client/test/helpers.ts, packages/3-extensions/sql-orm-client/test/integration/helpers.ts	New withoutPrimaryKey helper strips primaryKey from contract tables; createIdlessTagsCollection and createIdlessUsersCollection return id-less Collection instances with RETURNING capability.
Unit Tests packages/3-extensions/sql-orm-client/test/collection-contract.test.ts, packages/3-extensions/sql-orm-client/test/mutation-executor.test.ts, packages/3-extensions/sql-orm-client/test/collection-mutation-defaults.test.ts, packages/3-extensions/sql-orm-client/test/query-plan-mutations.test.ts	Tests for PK-column resolution with operation context, id-less identity criterion building, single-column and composite PKs, error cases, nested-update guards, count helper capabilities requiring RETURNING, and single-execution behavior.
Integration Tests packages/3-extensions/sql-orm-client/test/integration/idless.test.ts	Three integration tests: updateCount() on id-less tags matching one row; deleteCount() on id-less tags deleting one row; nested update() on id-less users with unique-constraint-based reload and created posts verification.
Decision & Issue Tracking todos/001-* through todos/014-*	P1 correctness guard for silent multi-row updates on id-less duplicate-tuple tables (implemented in updateFirstGraph); P2 performance/capability issues (wide RETURNING payload, materialization via .toArray(), integration test gaps, dead code, capability coverage); P3 refinements (SQLite caveat docs, asymmetric gates, comment clarity, helper extraction, error message trimming, test consolidation).

🎯 4 (Complex) | ⏱️ ~60 minutes

---

🐰 A tale of identity without keys,
Row-returns leap where PK'd please,
Guards prevent the duplicate sprawl,
Counts now iterate through all—
Id-less tables, finally whole! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.88% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(sql-orm-client): complete id-less ORM support' directly and accurately summarizes the main change: completing ORM support for id-less SQL tables across multiple files, tests, and documentation.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/orm-requires-primary-key-gate

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-runtime@440

@prisma-next/family-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-mongo@440

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-arktype-json@440

@prisma-next/extension-cipherstash

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-cipherstash@440

@prisma-next/middleware-telemetry

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/middleware-telemetry@440

@prisma-next/mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo@440

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-paradedb@440

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-pgvector@440

@prisma-next/postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/postgres@440

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-orm-client@440

@prisma-next/sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sqlite@440

@prisma-next/sql-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-runtime@440

@prisma-next/family-sql

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-sql@440

@prisma-next/target-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-mongo@440

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-mongo@440

@prisma-next/driver-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-mongo@440

@prisma-next/contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract@440

@prisma-next/utils

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/utils@440

@prisma-next/config

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/config@440

@prisma-next/errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/errors@440

@prisma-next/framework-components

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/framework-components@440

@prisma-next/operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/operations@440

@prisma-next/ts-render

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ts-render@440

@prisma-next/contract-authoring

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract-authoring@440

@prisma-next/ids

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ids@440

@prisma-next/psl-parser

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-parser@440

@prisma-next/psl-printer

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-printer@440

@prisma-next/cli

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/cli@440

@prisma-next/emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/emitter@440

@prisma-next/migration-tools

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/migration-tools@440

prisma-next

npm i https://pkg.pr.new/prisma/prisma-next@440

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/vite-plugin-contract-emit@440

@prisma-next/mongo-codec

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-codec@440

@prisma-next/mongo-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract@440

@prisma-next/mongo-value

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-value@440

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract-psl@440

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract-ts@440

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-emitter@440

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-schema-ir@440

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-query-ast@440

@prisma-next/mongo-orm

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-orm@440

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-query-builder@440

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-lowering@440

@prisma-next/mongo-wire

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-wire@440

@prisma-next/sql-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract@440

@prisma-next/sql-errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-errors@440

@prisma-next/sql-operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-operations@440

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-schema-ir@440

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-psl@440

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-ts@440

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-emitter@440

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-lane-query-builder@440

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-relational-core@440

@prisma-next/sql-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-builder@440

@prisma-next/target-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-postgres@440

@prisma-next/target-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-sqlite@440

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-postgres@440

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-sqlite@440

@prisma-next/driver-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-postgres@440

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-sqlite@440

commit: 76aca22

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

todos/006-pending-p2-dead-code-compiledeletecount.md (1)

1-61: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

compileDeleteCount dead code should be removed in this PR, not deferred.

This PR (M1, b6b7eba8e) is precisely what rendered compileDeleteCount dead. Deferring the cleanup creates a gap between the milestone that caused the orphan and the commit that cleans it up, making the history harder to follow. Both deletion sites are localized:

• query-plan-mutations.ts:287–299 — remove the function body
• query-plan.ts:6 — remove the re-export

The project's own CLAUDE.md golden rule is quoted in this very document: "Don't add exports for backwards compatibility unless requested". The same principle applies to keeping an unreferenced export around "just in case."

Would you like me to generate the exact diff for the two deletion sites?

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@todos/006-pending-p2-dead-code-compiledeletecount.md` around lines 1 - 61,
Remove the dead helper compileDeleteCount from query-plan-mutations.ts (delete
the entire function definition named compileDeleteCount) and remove its
re-export from query-plan.ts so the symbol is no longer exported; ensure no
other references remain (grep for compileDeleteCount) and run the test suite to
verify nothing broke.

🧹 Nitpick comments (4)

todos/003-pending-p2-wide-returning-payload.md (1)

1-62: ⚡ Quick win

Consider resolving before production usage — the fix is one line per call site.

Solution A (pass a single-column returning list) is a minimal change and the todo correctly identifies the exact call sites. Given the regression only materialises at scale (wide tables × high affected-row counts), P2/deferred is acceptable for this PR, but it's worth closing this before the id-less feature lands in any performance-sensitive environment.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@todos/003-pending-p2-wide-returning-payload.md` around lines 1 - 62,
updateCount and deleteCount call compileUpdateReturning/compileDeleteReturning
with returningColumns undefined which buildReturningColumns expands to every
table column, shipping wide payloads; fix by passing an explicit single-column
returning list (e.g. primaryKeyColumns[0] or first storage column) from the
updateCount and deleteCount call sites instead of undefined so
compileUpdateReturning/compileDeleteReturning emit RETURNING [trivialColumn]
rather than all columns (refer to updateCount, deleteCount,
compileUpdateReturning, compileDeleteReturning, and
primaryKeyColumns/table.columns to locate the spots).

packages/3-extensions/sql-orm-client/src/mutation-executor.ts (1)

141-148: 💤 Low value

Use Object.hasOwn() in the id-less mapped-field loop.

Line 144 uses the in operator, which traverses the prototype chain. Mapped-row objects from mapStorageRowToModelFields are plain enough today that this works in practice, but the surrounding codebase enforces Object.hasOwn() for property-existence checks on row-like objects.

🧹 Switch to Object.hasOwn()

   for (const fieldName of Object.keys(fieldToColumn)) {
-    if (!(fieldName in row)) continue;
+    if (!Object.hasOwn(row, fieldName)) continue;
     const value = row[fieldName];
     if (value === undefined || value === null) continue;
     criterion[fieldName] = value;
   }

As per coding guidelines: "Always use Object.hasOwn() instead of hasOwnProperty() to check for own properties."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/3-extensions/sql-orm-client/src/mutation-executor.ts` around lines
141 - 148, The loop building criterion uses the `in` operator which checks the
prototype chain; change the existence check to use Object.hasOwn(row, fieldName)
instead (keep the surrounding logic: obtain fieldToColumn via
getFieldToColumnMap(contract, modelName), iterate Object.keys(fieldToColumn),
skip when Object.hasOwn(row, fieldName) is false, then keep the existing value
null/undefined checks and assignment to criterion[fieldName]); this aligns with
how mapStorageRowToModelFields produces plain row objects and follows the
codebase guideline to always use Object.hasOwn().

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

1175-1188: ⚡ Quick win

deleteCount() has the same materialize-to-count pattern.

Mirrors the updateCount() concern: .toArray() buffers every deleted row and undefined selection likely returns the full row payload, when all the caller wants is a count. Apply the same fix — iterate the async result and increment a counter, optionally with a minimal projection.

♻️ Stream-count delete result

-    const compiled = compileDeleteReturning(
-      this.contract,
-      this.tableName,
-      this.state.filters,
-      undefined,
-    );
-    const deletedRows = await executeQueryPlan<Record<string, unknown>>(
-      this.ctx.runtime,
-      compiled,
-    ).toArray();
-
-    return deletedRows.length;
+    const compiled = compileDeleteReturning(
+      this.contract,
+      this.tableName,
+      this.state.filters,
+      undefined,
+    );
+    let count = 0;
+    for await (const _ of executeQueryPlan<Record<string, unknown>>(this.ctx.runtime, compiled)) {
+      count++;
+    }
+    return count;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/3-extensions/sql-orm-client/src/collection.ts` around lines 1175 -
1188, deleteCount() currently materializes all deleted rows via .toArray() and
an undefined selection; change it to stream the results and increment a counter
instead. Update the call to compileDeleteReturning(this.contract,
this.tableName, this.state.filters, ...) to request a minimal projection (e.g.,
primary key or a tiny count marker) rather than undefined, then run
executeQueryPlan<Record<string, unknown>>(this.ctx.runtime, compiled) and
consume the async iterator with a for-await loop (or iterator.next loop)
incrementing a local counter for each yielded item; return that counter and
remove the .toArray() call.

---

1113-1135: ⚡ Quick win

updateCount() materializes the entire RETURNING result just to count it.

.toArray() collects every updated row into memory and then takes .length. Streaming iteration with a for await loop would avoid materialization. Passing undefined for the projection likely produces a wide RETURNING row payload, so consider also emitting a minimal projection (e.g., a single literal or PK column) for the count path to reduce data transfer.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/3-extensions/sql-orm-client/src/collection.ts` around lines 1113 -
1135, The current updateCount() materializes the full RETURNING set via
.toArray(); change it to stream and count instead: after mapping
(mapModelDataToStorageRow) and applyUpdateDefaults, call compileUpdateReturning
with a minimal projection (not undefined) to reduce payload—e.g., a single
literal or the table PK column (use this.tableName/this.contract to determine
PK)—then call executeQueryPlan(..., compiled) and iterate the returned async
iterable with a for await loop to increment a counter and return the count,
removing the .toArray() allocation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/3-extensions/sql-orm-client/src/mutation-executor.ts`:
- Around line 141-158: The id-less UPDATE guard is unsafe because
buildRowIdentityCriterion drops nulls, allowing a "unique" constraint on a
nullable column to be ignored and UPDATE to match multiple rows; fix by
tightening the nested-update guard so before allowing the UPDATE you verify that
at least one unique constraint’s every mapped column is present and non-null in
the existingRow returned by findFirstByFilters (i.e., for each unique constraint
retrieved from contract, check all its columns exist and are !== null in
existingRow); only allow the id-less UPDATE when such a fully non-null unique
constraint exists (alternatively, if you prefer option 2, change
buildRowIdentityCriterion to include null-valued mapped fields as explicit IS
NULL predicates so nulls are part of the criterion).

In `@todos/001-complete-p1-multirow-update-on-idless-duplicate-tuples.md`:
- Line 2: The todo mistakenly marks "status: complete" while acceptance
criterion 2 (an integration test exercising duplicate-tuple behavior using a
schema without UNIQUE (name)) is not implemented: either revert the status to
"pending" and check only criteria 1 and 3, or actually implement criterion 2 by
adding a new integration test that uses a fixtures schema (not the current tags
PG schema) with the UNIQUE (name) constraint removed, exercise the id-less
duplicate-tuple scenario, and then update the checklist to mark all three
criteria; reference the checklist items (criteria 1, 2, 3), the id-less
integration tests, and the tags PG schema/UNIQUE (name) constraint when making
the change.

In `@todos/002-pending-p2-test-new-returning-required-gate.md`:
- Around line 9-52: Add unit tests that assert updateCount() and deleteCount()
throw when contract lacks the returning capability: create a contract with empty
capabilities via getTestContract() (or withCapabilities(getTestContract(), {})),
build an execution context with createExecutionContext(...), instantiate
Collection and call collection.where({}).updateCount(...) and
collection.where({}).deleteCount(), and expect rejects.toThrow matching
/updateCount\(\) requires contract capability "returning"/ and /deleteCount\(\)
requires contract capability "returning"/ respectively; this ensures the
assertReturningCapability(...) checks wired into updateCount and deleteCount are
covered.

---

Outside diff comments:
In `@todos/006-pending-p2-dead-code-compiledeletecount.md`:
- Around line 1-61: Remove the dead helper compileDeleteCount from
query-plan-mutations.ts (delete the entire function definition named
compileDeleteCount) and remove its re-export from query-plan.ts so the symbol is
no longer exported; ensure no other references remain (grep for
compileDeleteCount) and run the test suite to verify nothing broke.

---

Nitpick comments:
In `@packages/3-extensions/sql-orm-client/src/collection.ts`:
- Around line 1175-1188: deleteCount() currently materializes all deleted rows
via .toArray() and an undefined selection; change it to stream the results and
increment a counter instead. Update the call to
compileDeleteReturning(this.contract, this.tableName, this.state.filters, ...)
to request a minimal projection (e.g., primary key or a tiny count marker)
rather than undefined, then run executeQueryPlan<Record<string,
unknown>>(this.ctx.runtime, compiled) and consume the async iterator with a
for-await loop (or iterator.next loop) incrementing a local counter for each
yielded item; return that counter and remove the .toArray() call.
- Around line 1113-1135: The current updateCount() materializes the full
RETURNING set via .toArray(); change it to stream and count instead: after
mapping (mapModelDataToStorageRow) and applyUpdateDefaults, call
compileUpdateReturning with a minimal projection (not undefined) to reduce
payload—e.g., a single literal or the table PK column (use
this.tableName/this.contract to determine PK)—then call executeQueryPlan(...,
compiled) and iterate the returned async iterable with a for await loop to
increment a counter and return the count, removing the .toArray() allocation.

In `@packages/3-extensions/sql-orm-client/src/mutation-executor.ts`:
- Around line 141-148: The loop building criterion uses the `in` operator which
checks the prototype chain; change the existence check to use Object.hasOwn(row,
fieldName) instead (keep the surrounding logic: obtain fieldToColumn via
getFieldToColumnMap(contract, modelName), iterate Object.keys(fieldToColumn),
skip when Object.hasOwn(row, fieldName) is false, then keep the existing value
null/undefined checks and assignment to criterion[fieldName]); this aligns with
how mapStorageRowToModelFields produces plain row objects and follows the
codebase guideline to always use Object.hasOwn().

In `@todos/003-pending-p2-wide-returning-payload.md`:
- Around line 1-62: updateCount and deleteCount call
compileUpdateReturning/compileDeleteReturning with returningColumns undefined
which buildReturningColumns expands to every table column, shipping wide
payloads; fix by passing an explicit single-column returning list (e.g.
primaryKeyColumns[0] or first storage column) from the updateCount and
deleteCount call sites instead of undefined so
compileUpdateReturning/compileDeleteReturning emit RETURNING [trivialColumn]
rather than all columns (refer to updateCount, deleteCount,
compileUpdateReturning, compileDeleteReturning, and
primaryKeyColumns/table.columns to locate the spots).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: f1705808-eeb8-4603-98e0-1b2d1c5c756d

📥 Commits

Reviewing files that changed from the base of the PR and between 57cdd5e and fbabbdc.

⛔ Files ignored due to path filters (2)

• projects/created-updated-at-authoring/plan.md is excluded by !projects/**
• projects/created-updated-at-authoring/spec.md is excluded by !projects/**

📒 Files selected for processing (42)

• docs/architecture docs/subsystems/3. Query Lanes.md
• packages/1-framework/3-tooling/cli/test/control-api/client.test.ts
• packages/1-framework/3-tooling/cli/vitest.config.ts
• packages/1-framework/3-tooling/emitter/test/emitter.roundtrip.test.ts
• packages/1-framework/3-tooling/vite-plugin-contract-emit/src/plugin.ts
• packages/1-framework/3-tooling/vite-plugin-contract-emit/test/plugin.test.ts
• packages/2-sql/1-core/contract/src/validators.ts
• packages/2-sql/1-core/contract/test/validators.test.ts
• packages/2-sql/2-authoring/contract-psl/src/interpreter.ts
• packages/2-sql/2-authoring/contract-psl/src/psl-attribute-parsing.ts
• packages/2-sql/2-authoring/contract-psl/src/psl-field-resolution.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.diagnostics.test.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.test.ts
• packages/2-sql/2-authoring/contract-ts/src/build-contract.ts
• packages/2-sql/2-authoring/contract-ts/test/contract-builder.contract-definition.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract-builder.dsl.test.ts
• packages/2-sql/3-tooling/emitter/src/index.ts
• packages/2-sql/3-tooling/emitter/test/emitter-hook.structure.test.ts
• packages/3-extensions/sql-orm-client/src/collection-contract.ts
• packages/3-extensions/sql-orm-client/src/collection.ts
• packages/3-extensions/sql-orm-client/src/mutation-executor.ts
• packages/3-extensions/sql-orm-client/src/query-plan-select.ts
• packages/3-extensions/sql-orm-client/test/collection-contract.test.ts
• packages/3-extensions/sql-orm-client/test/collection-mutation-defaults.test.ts
• packages/3-extensions/sql-orm-client/test/integration/helpers.ts
• packages/3-extensions/sql-orm-client/test/integration/idless.test.ts
• packages/3-extensions/sql-orm-client/test/mutation-executor.test.ts
• plans/feat-complete-idless-orm-support.md
• todos/001-complete-p1-multirow-update-on-idless-duplicate-tuples.md
• todos/002-pending-p2-test-new-returning-required-gate.md
• todos/003-pending-p2-wide-returning-payload.md
• todos/004-pending-p2-toarray-materialization-for-counts.md
• todos/005-pending-p2-integration-coverage-idless-reload.md
• todos/006-pending-p2-dead-code-compiledeletecount.md
• todos/007-pending-p3-sqlite-after-trigger-mitigation.md
• todos/008-pending-p3-asymmetric-returning-gate.md
• todos/009-pending-p3-trim-what-comment-in-rowidentitycriterion.md
• todos/010-pending-p3-typed-builder-without-primary-key.md
• todos/011-pending-p3-cut-redundant-idless-zero-test.md
• todos/012-pending-p3-extract-getprimarykeycolumns-helper.md
• todos/013-pending-p3-stale-plan-name-references.md
• todos/014-pending-p3-trim-resolveprimarykey-error-message.md

💤 Files with no reviewable changes (2)

• packages/2-sql/2-authoring/contract-ts/src/build-contract.ts
• packages/2-sql/3-tooling/emitter/src/index.ts

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

packages/3-extensions/sql-orm-client/test/collection-mutation-defaults.test.ts (1)

264-303: ⚡ Quick win

Consider extracting the duplicated capability-stripped setup into a shared helper.

Lines 266–277 and 287–298 are identical. A small helper that mirrors setupTagCollection would eliminate the repetition and make future capability-gate tests one line each.

♻️ Suggested extraction

+function setupTagCollectionWithoutReturning(): {
+  collection: Collection<TestContract, 'Tag'>;
+  runtime: MockRuntime;
+} {
+  const contract = buildTagWithUpdatedAtContract();
+  const stripped = { ...contract, capabilities: {} } as TestContract;
+  const context = createExecutionContext({
+    contract: stripped,
+    stack: createSqlExecutionStack({
+      target: postgresTarget,
+      adapter: postgresAdapter,
+      extensionPacks: [pgvectorRuntime],
+    }),
+  });
+  const runtime: MockRuntime = createMockRuntime();
+  return { collection: new Collection({ context, runtime }, 'Tag'), runtime };
+}

   it('throws when the contract does not declare the returning capability', async () => {
-    // setupTagCollection wires `withReturningCapability`; rebuild without it.
-    const contract = buildTagWithUpdatedAtContract();
-    const stripped = { ...contract, capabilities: {} } as TestContract;
-    const context = createExecutionContext({
-      contract: stripped,
-      stack: createSqlExecutionStack({
-        target: postgresTarget,
-        adapter: postgresAdapter,
-        extensionPacks: [pgvectorRuntime],
-      }),
-    });
-    const runtime: MockRuntime = createMockRuntime();
-    const collection = new Collection({ context, runtime }, 'Tag');
+    const { collection } = setupTagCollectionWithoutReturning();

     await expect(
       collection.where({ id: tagId(TAG_ID_1) }).updateCount({ name: 'x' }),
     ).rejects.toThrow(/updateCount\(\) requires contract capability "returning"/);
   });

Apply the same substitution to the deleteCount block.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/3-extensions/sql-orm-client/test/collection-mutation-defaults.test.ts`
around lines 264 - 303, Extract the duplicated "capability-stripped" test setup
into a reusable helper to remove repetition: create a function (e.g.,
makeStrippedTagCollection or setupStrippedTagCollection) that calls
buildTagWithUpdatedAtContract(), creates stripped = { ...contract, capabilities:
{} } as TestContract, then builds the context via createExecutionContext({
contract: stripped, stack: createSqlExecutionStack({ target: postgresTarget,
adapter: postgresAdapter, extensionPacks: [pgvectorRuntime] }) }), creates
runtime with createMockRuntime(), and returns new Collection({ context, runtime
}, 'Tag'); replace the two duplicated blocks that currently inline those steps
in the updateCount and deleteCount tests with a single call to this helper.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/2-sql/2-authoring/contract-psl/test/interpreter.test.ts`:
- Around line 559-621: Remove the duplicated test block that re-declares
describe('round-trips printer output', ...) with its two it() cases ("accepts
the printer output for an id-less table" and "accepts the printer output for a
composite-PK table"); keep the canonical copy and delete the second identical
describe block so each test (the two it() cases) appears only once in
interpreter.test.ts.

In `@todos/007-complete-p3-sqlite-after-trigger-mitigation.md`:
- Line 2: The TODO file currently sets "status: complete" while the acceptance
checklist still has unchecked items; update the document so the status and
checklist match by either ticking the completed acceptance criteria checkboxes
or reverting "status: complete" to an appropriate in-progress state, and repeat
the same change for the related entries referenced (the entries around the
acceptance checklist items noted as 47-49); ensure the README/rules/links note
is updated to reflect the corrected status so docs remain consistent.

In `@todos/014-complete-p3-trim-resolveprimarykey-error-message.md`:
- Line 2: The frontmatter value "status: complete" conflicts with an unchecked
acceptance-criteria checkbox (the unchecked item at line 47 and similarly lines
45-48); update the frontmatter or the checklist so they match by either changing
"status: complete" to a non-complete state (e.g., "status: in-progress" or
"status: needs-work") or by checking the relevant checkbox(es) to mark those
criteria done, ensuring consistency between the "status: complete" symbol and
the acceptance checklist.

---

Nitpick comments:
In
`@packages/3-extensions/sql-orm-client/test/collection-mutation-defaults.test.ts`:
- Around line 264-303: Extract the duplicated "capability-stripped" test setup
into a reusable helper to remove repetition: create a function (e.g.,
makeStrippedTagCollection or setupStrippedTagCollection) that calls
buildTagWithUpdatedAtContract(), creates stripped = { ...contract, capabilities:
{} } as TestContract, then builds the context via createExecutionContext({
contract: stripped, stack: createSqlExecutionStack({ target: postgresTarget,
adapter: postgresAdapter, extensionPacks: [pgvectorRuntime] }) }), creates
runtime with createMockRuntime(), and returns new Collection({ context, runtime
}, 'Tag'); replace the two duplicated blocks that currently inline those steps
in the updateCount and deleteCount tests with a single call to this helper.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 7516805f-fd4b-441d-b0e5-96f0e3920229

📥 Commits

Reviewing files that changed from the base of the PR and between fbabbdc and ea0a9cd.

📒 Files selected for processing (26)

• packages/2-sql/2-authoring/contract-psl/test/interpreter.test.ts
• packages/3-extensions/sql-orm-client/src/collection-contract.ts
• packages/3-extensions/sql-orm-client/src/collection.ts
• packages/3-extensions/sql-orm-client/src/mutation-executor.ts
• packages/3-extensions/sql-orm-client/src/query-plan-mutations.ts
• packages/3-extensions/sql-orm-client/src/query-plan.ts
• packages/3-extensions/sql-orm-client/test/collection-mutation-defaults.test.ts
• packages/3-extensions/sql-orm-client/test/helpers.ts
• packages/3-extensions/sql-orm-client/test/integration/helpers.ts
• packages/3-extensions/sql-orm-client/test/integration/idless.test.ts
• packages/3-extensions/sql-orm-client/test/mutation-executor.test.ts
• packages/3-extensions/sql-orm-client/test/query-plan-mutations.test.ts
• todos/001-complete-p1-multirow-update-on-idless-duplicate-tuples.md
• todos/002-complete-p2-test-new-returning-required-gate.md
• todos/003-complete-p2-wide-returning-payload.md
• todos/004-complete-p2-toarray-materialization-for-counts.md
• todos/005-complete-p2-integration-coverage-idless-reload.md
• todos/006-complete-p2-dead-code-compiledeletecount.md
• todos/007-complete-p3-sqlite-after-trigger-mitigation.md
• todos/008-complete-p3-asymmetric-returning-gate.md
• todos/009-complete-p3-trim-what-comment-in-rowidentitycriterion.md
• todos/010-complete-p3-typed-builder-without-primary-key.md
• todos/011-complete-p3-cut-redundant-idless-zero-test.md
• todos/012-complete-p3-extract-getprimarykeycolumns-helper.md
• todos/013-complete-p3-stale-plan-name-references.md
• todos/014-complete-p3-trim-resolveprimarykey-error-message.md

💤 Files with no reviewable changes (2)

• packages/3-extensions/sql-orm-client/src/query-plan.ts
• packages/3-extensions/sql-orm-client/src/query-plan-mutations.ts

✅ Files skipped from review due to trivial changes (11)

• todos/003-complete-p2-wide-returning-payload.md
• todos/013-complete-p3-stale-plan-name-references.md
• todos/012-complete-p3-extract-getprimarykeycolumns-helper.md
• todos/010-complete-p3-typed-builder-without-primary-key.md
• todos/009-complete-p3-trim-what-comment-in-rowidentitycriterion.md
• todos/004-complete-p2-toarray-materialization-for-counts.md
• todos/008-complete-p3-asymmetric-returning-gate.md
• todos/011-complete-p3-cut-redundant-idless-zero-test.md
• todos/005-complete-p2-integration-coverage-idless-reload.md
• todos/006-complete-p2-dead-code-compiledeletecount.md
• todos/001-complete-p1-multirow-update-on-idless-duplicate-tuples.md

🚧 Files skipped from review as they are similar to previous changes (4)

• packages/3-extensions/sql-orm-client/src/collection-contract.ts
• packages/3-extensions/sql-orm-client/test/mutation-executor.test.ts
• packages/3-extensions/sql-orm-client/src/collection.ts
• packages/3-extensions/sql-orm-client/src/mutation-executor.ts