TML-2787: M:N slice 3 — nested writes through the junction

[tensordreams]

Slice 3 (final) of the SQL ORM: Many-to-Many End to End project (Linear project). Nested connect/disconnect/create through the junction + the required-payload safety rail.

⚠ DRAFT — not ready to merge. Runtime-complete, but the type-level .create disable (your non-negotiable, in-slice requirement) is deferred pending your decision — it needs a contract-.d.ts change. See Open decision below + wip/unattended-decisions.md #8. I did not make that contract-surface change unilaterally.

Stacked PR. Base tml-2786 (#680) → tml-2785 (#679) → tml-2784 (#678) → tml-2597 (#673) → tml-2729 (#667) → main. Review/merge bottom-up.

Overview

db.orm.User.update/create({ tags: (t) => t.connect/disconnect/create(...) }) now routes to the UserTag junction (INSERT / DELETE / target-insert+link), under both create() and update(). The N:M not supported yet guard is gone. Junctions with a required non-FK payload column cant be written through the sugar, so create and connect on them are disabled with a clear error (disconnect stays).

Changes (5 commits)

• 74a778816 — runtime junction write path: partitionByOwnership gains a junctionOwned bucket (keyed on through presence); connect→INSERT, disconnect→DELETE, create→target-insert+link, both flows, composite-key AND-ed; the rejection unit test flipped positive. (getRelationDefinitions now carries through.)
• 926bdc849 — required-payload fixture: User ↔ Role via UserRole(user_id, role_id, level NOT NULL) (canonical CLI emit).
• 3bccd80b3 — runtime guard: nested create on a required-payload junction throws.
• e6c641811 — design correction (decision Remove SQL -> Runtime dependency #9): extended the guard to connect too (connect also INSERTs a junction row it cant complete → DB NOT-NULL violation), flipped the unit test, finished the 10 write integration tests.

Integration tests (per the project standard)

mn-nested-write.test.ts — 10 tests, no skips: connect/create on the pure User.tags junction with whole-row readback via include(tags), both create()+update() flows; disconnect; connect AND create on User.roles throw the guard; disconnect on User.roles works. Whole-row toEqual, explicit .select in most, ≥1 implicit/default selection.

AC status

• ✅ AC-1 — connect/disconnect/create route to junction DML, both flows, guard removed, rejection test flipped (unit + integration).
• ✅ AC-3 — write integration tests per the standard.
• ⚠ AC-2 — partial. Runtime disable of create+connect on required-payload junctions: ✅ done + tested. Type-level disable: deferred — see below.

⚠ Open decision (blocks marking this slice done)

The type-level .create disable cant be built as specified: the generated contract.d.ts relation type carries only to/cardinality/on, not through — so a conditional type cant see which model is the junction or that it has a required column. requiredPayloadColumns exists only at runtime. Honouring the type-level disable needs the contract .d.ts type emitter to carry through (a contract-surface change reaching into slice-0 territory). Options (full detail in wip/unattended-decisions.md #8):

• (a) extend the .d.ts emitter to emit through, then a follow-up adds the conditional-type disable + negative type test;
• (b) emit a narrower requiredPayloadColumns/hasRequiredPayload marker into the typed relation;
• (c) accept runtime-only (contradicts the in-slice non-negotiable).

I shipped the runtime guard and left this for you. Once you pick (a)/(b), a small follow-up dispatch completes the type-level disable.

Notes

connect-disabled-on-required-payload was a mid-flight spec correction (the original spec wrongly assumed connect was FK-pair-only safe). The reverse Tag.users/Role.users directions are deferred (one-directional fixture, decision #3). Refs: TML-2787.

Summary by CodeRabbit

Release Notes

• New Features

  • Enabled nested create, connect, and disconnect operations for many-to-many relationships via junction tables.
  • Added compile-time type checking to prevent invalid operations on junction relations with required fields.

• Improvements

  • Enhanced runtime validation with clear error guidance for missing required junction payload fields.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 1957e0ac-65b0-4316-bc62-f42d109dd655

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2787-slice-3-write

---

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.}

[github-actions]

size-limit report 📦

Path	Size
postgres / no-emit	152.96 KB (+0.34% 🔺)
postgres / emit	121.25 KB (+0.43% 🔺)
mongo / no-emit	76.67 KB (0%)
mongo / emit	70.96 KB (0%)
cf-worker / no-emit	180.95 KB (0%)
cf-worker / emit	145.99 KB (0%)

[pkg-pr-new]

Open in StackBlitz

@prisma-next/extension-author-tools

npm i https://pkg.pr.new/@prisma-next/extension-author-tools@683

@prisma-next/mongo-runtime

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

@prisma-next/family-mongo

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

@prisma-next/sql-runtime

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

@prisma-next/family-sql

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

@prisma-next/extension-arktype-json

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

@prisma-next/middleware-cache

npm i https://pkg.pr.new/@prisma-next/middleware-cache@683

@prisma-next/mongo

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

@prisma-next/extension-paradedb

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

@prisma-next/extension-pgvector

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

@prisma-next/extension-postgis

npm i https://pkg.pr.new/@prisma-next/extension-postgis@683

@prisma-next/postgres

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

@prisma-next/sql-orm-client

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

@prisma-next/sqlite

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

@prisma-next/extension-supabase

npm i https://pkg.pr.new/@prisma-next/extension-supabase@683

@prisma-next/target-mongo

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

@prisma-next/adapter-mongo

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

@prisma-next/driver-mongo

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

@prisma-next/contract

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

@prisma-next/utils

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

@prisma-next/config

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

@prisma-next/errors

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

@prisma-next/framework-components

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

@prisma-next/operations

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

@prisma-next/ts-render

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

@prisma-next/contract-authoring

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

@prisma-next/ids

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

@prisma-next/psl-parser

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

@prisma-next/psl-printer

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

@prisma-next/cli

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

@prisma-next/cli-telemetry

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

@prisma-next/emitter

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

@prisma-next/migration-tools

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

prisma-next

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

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

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

@prisma-next/mongo-codec

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

@prisma-next/mongo-contract

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

@prisma-next/mongo-value

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

@prisma-next/mongo-contract-psl

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

@prisma-next/mongo-contract-ts

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

@prisma-next/mongo-emitter

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

@prisma-next/mongo-schema-ir

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

@prisma-next/mongo-query-ast

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

@prisma-next/mongo-orm

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

@prisma-next/mongo-query-builder

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

@prisma-next/mongo-lowering

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

@prisma-next/mongo-wire

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

@prisma-next/sql-contract

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

@prisma-next/sql-errors

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

@prisma-next/sql-operations

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

@prisma-next/sql-schema-ir

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

@prisma-next/sql-contract-psl

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

@prisma-next/sql-contract-ts

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

@prisma-next/sql-contract-emitter

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

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

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

@prisma-next/sql-relational-core

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

@prisma-next/sql-builder

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

@prisma-next/target-postgres

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

@prisma-next/target-sqlite

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

@prisma-next/adapter-postgres

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

@prisma-next/adapter-sqlite

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

@prisma-next/driver-postgres

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

@prisma-next/driver-sqlite

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

commit: 4ea74ff

[tensordreams]

Updated: the type-level .create/.connect disable is now implemented (escalation #8 resolved via the chosen approach — the .d.ts emitter now carries through, landed in slice 0; the type gate derives required-payload purely at the type level, no any). AC-2 is closed at both the runtime and type levels. The whole stack has also been rebased onto the latest origin/main (clean — no fixture re-emit cascade). Negative type test: junction-link-write-disable.test-d.ts. No longer a draft.

[coderabbitai]

🧹 Nitpick comments (1)

test/integration/test/sql-orm-client/mn-nested-write.test.ts (1)

306-317: ⚡ Quick win

Assert no partial writes after guard rejections.

Line 306 and Line 334 only verify the thrown error text. Add post-failure DB assertions to guarantee the rejected nested write didn’t persist partial parent/junction changes.

Proposed test hardening

@@
         await expect(
           users.create({
@@
           }),
         ).rejects.toThrow(/required column.*`level`/);
+
+        const userRows = await runtime.query<{ id: number }>('select id from users');
+        const roleRows = await runtime.query<{ id: string }>('select id from roles');
+        const junctionRows = await runtime.query<{ user_id: number; role_id: string }>(
+          'select user_id, role_id from user_roles',
+        );
+        expect(userRows).toEqual([]);
+        expect(roleRows).toEqual([]);
+        expect(junctionRows).toEqual([]);
@@
         await expect(
           users.create({
@@
           }),
         ).rejects.toThrow(/required column.*`level`/);
+
+        const userRows = await runtime.query<{ id: number }>('select id from users');
+        const roleRows = await runtime.query<{ id: string }>('select id from roles');
+        const junctionRows = await runtime.query<{ user_id: number; role_id: string }>(
+          'select user_id, role_id from user_roles',
+        );
+        expect(userRows).toEqual([]);
+        expect(roleRows).toEqual([{ id: ROLE_ADMIN }]);
+        expect(junctionRows).toEqual([]);

Also applies to: 334-345

🤖 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 `@test/integration/test/sql-orm-client/mn-nested-write.test.ts` around lines
306 - 317, The test currently only asserts the thrown error from users.create
with the nested roles.create and doesn't verify the DB state; after the
expect(...).rejects.toThrow(...) add assertions that the attempted
parent/junction records were not persisted (e.g. call users.findUnique({ where:
{ id: 1 } }) or users.findMany(...) and roles.findMany(...) and assert they
return null/empty), and repeat the same post-failure DB checks for the other
case referenced (the block around lines 334-345) so both rejected nested-write
scenarios confirm no partial writes occurred.

🤖 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.

Nitpick comments:
In `@test/integration/test/sql-orm-client/mn-nested-write.test.ts`:
- Around line 306-317: The test currently only asserts the thrown error from
users.create with the nested roles.create and doesn't verify the DB state; after
the expect(...).rejects.toThrow(...) add assertions that the attempted
parent/junction records were not persisted (e.g. call users.findUnique({ where:
{ id: 1 } }) or users.findMany(...) and roles.findMany(...) and assert they
return null/empty), and repeat the same post-failure DB checks for the other
case referenced (the block around lines 334-345) so both rejected nested-write
scenarios confirm no partial writes occurred.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 39ff8f77-4bad-45e8-96a3-49cc35485a18

📥 Commits

Reviewing files that changed from the base of the PR and between e9d57ac and facaadf.

⛔ Files ignored due to path filters (9)

• projects/sql-orm-many-to-many/learnings.md is excluded by !projects/**
• projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/01-write-path.md is excluded by !projects/**
• projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/02-required-payload-fixture.md is excluded by !projects/**
• projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/03-runtime-disable.md is excluded by !projects/**
• projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/04-integration-tests.md is excluded by !projects/**
• projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/04-integration-tests.r2.md is excluded by !projects/**
• projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/plan.md is excluded by !projects/**
• projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/spec.md is excluded by !projects/**
• projects/sql-orm-many-to-many/trace.jsonl is excluded by !projects/**

📒 Files selected for processing (6)

• packages/3-extensions/sql-orm-client/src/mutation-executor.ts
• packages/3-extensions/sql-orm-client/src/types.ts
• packages/3-extensions/sql-orm-client/test/junction-link-write-disable.test-d.ts
• packages/3-extensions/sql-orm-client/test/mutation-executor.test.ts
• test/integration/test/sql-orm-client/mn-nested-write.test.ts
• test/integration/test/sql-orm-client/runtime-helpers.ts

[tensordreams]

For composite M:N relations where the junction reuses a column on both sides, this merge lets the target row overwrite the parent value. The fixture added in this stack has exactly that shape (parentColumns: [tenant_id, parent_id], childColumns: [tenant_id, child_id]): connecting parent (tenant_id=7, id=1) to target (tenant_id=8, id=10) would insert { tenant_id: 8, parent_id: 1, child_id: 10 }, which no longer points at the parent row we just updated, or trips FK constraints when they exist. The junction merge should detect duplicate junction columns, require the values to match, and keep the same behavior for deletes; a mismatched shared-column test would catch this.

[tensordreams]

On it. I will reject shared junction-column value mismatches when merging link values. 👍

[tensordreams]

Reviewed this PR separately against tml-2786-slice-2-filter (origin/tml-2786-slice-2-filter...origin/tml-2787-slice-3-write). I left one inline correctness comment on the junction-row merge for composite M:N relations with shared columns. Verification while reviewing: pnpm --filter @prisma-next/sql-orm-client test and git diff --check for this PR diff passed.

[tensordreams]

Reviewed this slice against projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/spec.md and the stacked diff vs tml-2786-slice-2-filter.

Well-executed slice that conforms closely to its spec: partitionByOwnership gains the third junctionOwned bucket with a proper hasThrough type guard, junction writes run after the parent PK is known in both create() and update() flows, and the required-payload disable exists at both the type level (with genuine positive and negative .test-d.ts coverage) and at runtime with a clear error naming the columns and the escape hatch. Atomicity rides the pre-existing withMutationScope (transactional when the runtime provides transaction(), sequential fallback otherwise — a pre-existing characteristic, not a regression). Production code correctly uses blindCast with reasons (no bare as, no any); runtime-guard tests bypass the type gate with test-file-exempt casts; test conventions are observed; runtime-helpers.ts extends the existing shared integration helper rather than duplicating it.

One finding I'd want resolved (or explicitly deferred with a spec note) before merge: the undefined duplicate-connect behavior, since it's a first-class user-facing path of this feature. The rest are hardening at the edges — see inline comments.

[tensordreams]

major: insertJunctionLink compiles a plain INSERT (compileInsertCount, no ON CONFLICT), so connect-ing an already-connected row — or repeating the same criterion in one connect([...]) call — surfaces as a raw junction-PK unique-violation from the driver rather than either idempotent success or a domain error naming the relation. Duplicate-link behavior is currently undefined and untested (no unit or integration test connects the same pair twice). Please pick a behavior deliberately — idempotent insert (ON CONFLICT DO NOTHING semantics, matching Prisma's implicit-M:N connect) or a wrapped error naming the relation — and pin it with a test. If it's deferred to a later slice, a code comment + spec note would help.

[tensordreams]

On it. I will define duplicate junction connect behavior and add coverage. 👍

[tensordreams]

minor: Type/runtime mismatch for bare disconnect(): the RelationMutator interface still exposes the zero-arg disconnect() overload for junction relations, and for child-owned (1:N) relations it means "disconnect all" — but the junction path unconditionally throws requires criterion. So t.disconnect() on an M:N relation compiles and always fails at runtime. Either implement disconnect-all for junction relations (DELETE FROM junction WHERE parentCols = parentPk, symmetric with the 1:N behavior) or gate the no-arg overload off at the type level like you did for create/connect. If you keep the throw, the message should say criteria are required for M:N relations — "requires criterion" reads like a missing-argument bug.

[tensordreams]

On it. I will align the bare M:N disconnect type/runtime behavior in this PR. 👍

[tensordreams]

minor: The type gate and the runtime guard disagree on execution-time create defaults. HasRequiredJunctionPayload treats a junction field as optional when IsOptionalCreateField is true, which includes HasExecutionCreateDefault (extension onCreate defaults). The runtime's requiredPayloadColumns (collection-contract.ts:371) only checks storage-level col.default — and insertJunctionLink never calls context.applyMutationDefaults (unlike insertSingleRow, line 948). Net effect: a junction payload column with an execution-only create default passes the type gate but throws the runtime guard. Suggest making insertJunctionLink apply mutation defaults for the junction table and excluding execution-defaulted columns from requiredPayloadColumns, or excluding HasExecutionCreateDefault from the type gate's optionality check so both layers agree.

[tensordreams]

On it. I will make required junction payload checks agree on execution-time create defaults. 👍

[tensordreams]

minor: ModelNameForTable resolves the junction model by scanning all models for a matching storage.table name, ignoring namespaces — a bare-table-name assumption the runtime side just removed (junction DML threads through.namespaceId everywhere after the TML-2841 rebase). Two models in different namespaces with the same table name would make this resolve to a union of model names, producing an unpredictable gate. The emitted through type carries namespaceId, so the fix is cheap: match on readonly storage: { readonly table: TableName; readonly namespaceId: Through['namespaceId'] } and pass the namespace through from HasRequiredJunctionPayload.

[tensordreams]

On it. I will make the junction model lookup namespace-aware in the type gate. 👍

[tensordreams]

minor: readJunctionParentValues/readJunctionTargetValues silently continue when through.parentColumns/childColumns and their paired arrays disagree in length. For insertJunctionLink that yields a NOT-NULL violation (noisy but safe); for deleteJunctionLink a skipped pair drops a WHERE predicate, widening the DELETE to unlink more rows than requested. Contract validation should make misalignment impossible, but since the failure mode here is silent data loss rather than an error, prefer throwing on length mismatch instead of skipping.

[tensordreams]

On it. I will make the junction paired-column readers fail fast on metadata length mismatches. 👍

[tensordreams]

minor (coverage): Failure paths for junction connect/disconnect against a nonexistent target are untested. The runtime path exists (mutation-executor.ts:768-772, did not find a matching row) but neither this file nor mutation-executor.test.ts exercises it for the junction-owned bucket (the existing not-found tests cover the parent-owned path only). Please add at least one test — e.g. users.create({..., tags: (t) => t.connect({ id: 'missing' })}) asserting the rejection, ideally also asserting no partial junction row is left behind, which would double as coverage of the rollback behavior.

[tensordreams]

On it. I will add missing-target connect/disconnect coverage and no-partial-write assertions. 👍

[tensordreams]

nit: All gate assertions here go through MutationCreateInput. The gate also applies to MutationUpdateInput (both reach RelationMutator via the shared RelationMutationFields/RelationMutationCallback), but that's structural rather than asserted — a refactor that gives update its own callback type would silently lose the gate. Two cheap cases (mutator.connect forbidden, disconnect allowed, via MutationUpdateInput<Contract, 'User'>) would pin it.

[tensordreams]

On it. I will add MutationUpdateInput coverage for the junction relation mutator gate. 👍

[tensordreams]

On it. I will add post-failure DB assertions for the required-payload guard cases. 👍