docs(sql-orm-many-to-many): slice 3 specs/briefs/trace/learnings (TML-2787)

Write slice artifacts. Spec corrected mid-flight (decision #9: connect also
disabled on required-payload junctions). Type-level .create disable deferred
(decision #8 — needs a contract .d.ts emitter change, operator decision).

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

Author: tensordreams

projects/sql-orm-many-to-many/learnings.md

@@ -10,6 +10,8 @@ This harness exposes no `SendMessage`/resume for spawned subagents — the `Agen
 
 `pnpm fixtures:check` fails at `fixtures:emit` in this sandbox (CLI not on PATH / "Failed to load config" for sql-builder + sql-orm-client emit scripts) — pre-existing, not introduced (matches the TML-2729 gotcha). Additivity is verified instead via a direct golden git-diff (`git diff -- ':(glob)**/contract.json' …`); CI runs the real gate. Don't treat the local `fixtures:check` red as a dispatch failure.
 
+**Correction (slice 3):** the canonical CLI emit **does** work in this sandbox — run it **from the repo root**: `node packages/1-framework/3-tooling/cli/dist/cli.js contract emit --config test/integration/test/sql-orm-client/fixtures/prisma-next.config.ts`, then `pnpm --filter @prisma-next/sql-orm-client emit` (package-local copy + pgvector strip). The earlier "config-load failure" was from running with the wrong cwd (`test/integration`). **Prefer the canonical emit from root over a `tsx` bypass** — no golden-stability risk.
+
 ## PGlite/WASM JIT flakiness on broad integration runs
 
 Running the whole sql-orm-client integration suite at once (`cd test/integration && pnpm test test/sql-orm-client/`) can crash with V8 `jit_page.has_value()` (WASM JIT) failures — **pre-existing PGlite/Node env flakiness**, reproduces on the parent branch, not introduced by M:N work. Targeted reruns (per-file, or the same suite again) pass cleanly. Verify integration blast radius with targeted per-file runs; don't trust a single broad-run red.

projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/01-write-path.md

@@ -0,0 +1,43 @@
+# Brief: S3-D1 — runtime junction write path
+
+## Task
+
+Lift the M:N nested-mutation guard and route nested writes through the junction. Today `partitionByOwnership` (`packages/3-extensions/sql-orm-client/src/mutation-executor.ts:~351`) throws `'N:M nested mutations are not supported yet'`. Replace that with a third bucket — **`junctionOwned`** (relations carrying `through`) — and execute junction mutations in the `create()` and `update()` graph flows **after the parent row exists** (parent PK known):
+
+- **`connect({criteria})`** → resolve the target row(s) by criteria, then `INSERT INTO junction (parentColumns…, childColumns…) VALUES (parentPk…, targetPk…)` per resolved target.
+- **`disconnect({criteria})`** → `DELETE FROM junction WHERE parentColumns = parentPk AND childColumns = targetPk`. (Keep `disconnect` gated to the `update()` flow — the existing rule.)
+- **`create(data)`** → insert the target row, then INSERT the junction link. (For THIS dispatch, the junction is the pure `User↔Tag` one — no required payload; the required-payload guard is D3. Don't build the guard here.)
+
+Composite keys: INSERT/DELETE across all `parentColumns`/`childColumns` pairs. Use slice 0's `ResolvedRelation.through`.
+
+**Flip the rejection unit test** (`mutation-executor.test.ts`, currently `.rejects.toThrow(/N:M nested mutations are not supported yet/)`) to a **positive** assertion that the M:N nested mutation now produces the expected junction write. Add unit tests for connect/disconnect/create junction DML (both flows).
+
+## Scope
+
+**In:** `partitionByOwnership` + the `junctionOwned` execution branch in the `create()`/`update()` graph flows (`mutation-executor.ts`); composite-key junction INSERT/DELETE; flip + extend the rejection unit test.
+
+**Out:** the required-payload guard (D3); the required-payload fixture (D2); integration tests (D4); `set`/`connectOrCreate`/nested-`update` kinds (TML-2781). Don't regress FK (parent/child-owned) nested writes.
+
+## Completed when
+
+- [ ] `connect`/`disconnect`/`create` over the pure M:N relation route to junction INSERT/DELETE (create = target-insert + link), under both `create()` and `update()`; the `'not supported yet'` guard is gone.
+- [ ] The rejection unit test is flipped to a positive assertion; unit tests cover connect/disconnect/create junction DML (composite-key AND-ed).
+- [ ] FK nested writes unchanged (existing mutation-executor tests pass).
+- [ ] Gate: `pnpm --filter @prisma-next/sql-orm-client typecheck` + `test` green.
+
+## Standing instruction
+
+Stay focused on the junction write routing. Mirror the existing parent/child-owned flow structure (ordering relative to the parent insert). No bare `as` casts (use `castAs`/`blindCast` or a type predicate — siblings were bounced for bare casts; a `hasThrough` predicate already exists in `model-accessor.ts` if useful). Implement → unit-test → gate; don't over-explore (sibling write/judgment dispatches truncated from over-exploration).
+
+## References
+
+- Slice spec: `projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/spec.md`.
+- `mutation-executor.ts`: `partitionByOwnership` (~338), the `create()` graph flow (~159-200) + `update()` flow (~206-290) — the parent/child-owned execution to mirror.
+- Slice 0 `ResolvedRelation.through`; slice 2's `hasThrough` type predicate (`model-accessor.ts`).
+
+## Operational metadata
+
+- **Model tier:** **opus** — complex routing across two graph flows + composite keys; the slice's main runtime judgment.
+- **Branch:** `tml-2787-slice-3-write`. Explicit staging + `-s` sign-off. **Do not push.**
+- **Time-box:** ~90 min. Commit when the gate is green even if you'd like to polish — bank the work.
+- **Halt + surface to me:** if junction writes can't be ordered correctly within the existing graph-flow structure (parent PK not available where needed); if completing the routing requires touching the required-payload guard (that's D3) or an out-of-scope kind.

projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/02-required-payload-fixture.md

@@ -0,0 +1,40 @@
+# Brief: S3-D2 — required-payload-junction fixture
+
+## Task
+
+Add a second M:N relation to the integration fixture whose junction has a **required non-FK payload column**, so D3 can test the `.create` disable. Add to the fixture **source** (`test/integration/test/sql-orm-client/fixtures/contract.ts`):
+
+- A `Role` model (`id`, `name`) — mirror the existing `Tag` shape.
+- A `UserRole` junction with `userId`, `roleId`, **and a required non-FK column** — e.g. `level` (`int`/`text`, **NOT NULL, no default**) — composite PK `(userId, roleId)`, table `user_roles`.
+- `User.roles = rel.manyToMany(() => Role, { through: () => UserRole, from: 'userId', to: 'roleId' })` (the `User.roles` direction only — the reverse is unnecessary, consistent with the project's one-directional convention).
+
+Re-emit `contract.json` + `contract.d.ts`. After emit, `resolveModelRelations` must resolve `User.roles`'s `through.requiredPayloadColumns` to **`['level']`** (the NOT-NULL no-default non-FK column) — this is what D3's disable keys on.
+
+## Scope
+
+**In:** the fixture source (`Role` + `UserRole` w/ required `level` + `User.roles`); the re-emitted `contract.json`/`contract.d.ts`.
+
+**Out:** the disable logic (D3); the write path (D1, done); integration tests (D4); the existing `User.tags` relation. Don't hand-edit generated files except as the emitter produces them.
+
+## Completed when
+
+- [ ] The fixture declares `User.roles` M:N via `UserRole(user_id, role_id, level NOT NULL no-default)`; emits `cardinality:'N:M'` + populated `through`.
+- [ ] For `User.roles`, `resolveModelRelations(...).through.requiredPayloadColumns` resolves to `['level']` (verify with a tiny scratch assertion or by inspecting the junction storage in the emitted `contract.json` — `level` is NOT NULL, no default, not a FK col).
+- [ ] Re-emitted `contract.json`/`.d.ts` committed; additive (existing models + `User.tags` unchanged).
+
+## Standing instruction
+
+Add exactly the `Role`/`UserRole`/`User.roles` shapes with one required payload column (`level`). No reverse relation, no extra columns beyond the required one. Same emit approach as slice 1's fixture dispatch.
+
+## References
+
+- Slice spec: `projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/spec.md`.
+- Slice 1 fixture dispatch (commit `fcecac5b3`) added `User.tags`/`UserTag` + re-emitted the same way — mirror it (incl. the `tsx`-bypass emit; CLI `contract emit` fails on the known config-load env issue).
+- Slice 0 `requiredPayloadColumns` derivation (NOT NULL ∧ no default ∧ not FK) in `collection-contract.ts`.
+
+## Operational metadata
+
+- **Model tier:** sonnet — schema authoring + re-emit (mechanical, mirrors slice 1).
+- **Branch:** `tml-2787-slice-3-write`. Explicit staging + `-s` sign-off. **Do not push.** Commit the re-emit (don't leave uncommitted).
+- **Time-box:** ~50 min.
+- **Halt + known-env:** local `fixtures:emit`/CLI fails on the pre-existing config-load issue — emit via the same `tsx`-bypass slice 1 used; verify the generated `contract.json` by inspection + that `requiredPayloadColumns` resolves to `['level']`; note it. If re-emit is genuinely impossible in-sandbox, surface to me (don't hand-fabricate). Halt if adding the relation forces touching the disable logic (D3) or trips a type regression in existing tests (describe it).

projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/03-runtime-disable.md

@@ -0,0 +1,42 @@
+# Brief: S3-D3 — runtime `.create` disable on required-payload junctions (runtime half only)
+
+> **Scope note (orchestrator decision, unattended):** the **type-level** disable is **deferred** — it requires the contract `.d.ts` type emitter to carry `through` (it currently doesn't), which is a contract-surface decision for the operator (see `wip/unattended-decisions.md` #8). This dispatch does the **runtime** disable only. Do **not** attempt the type-level/conditional-type disable; do **not** change the contract `.d.ts` emitter.
+
+## Task
+
+In the `junctionOwned` `create` branch added in S3-D1 (`mutation-executor.ts`, `applyJunctionOwnedMutation` / the create path), guard against nested `.create` when the junction has required payload columns. The resolved relation's `through.requiredPayloadColumns` (slice 0, runtime) lists them. When a nested `create` targets an M:N relation whose `requiredPayloadColumns` is non-empty:
+
+- **Throw a clear, actionable error** naming the relation + the offending column(s), and pointing the user to the junction model's own relations / the SQL query builder (the supported path for payload-bearing junctions). E.g. *"Cannot nest `create` on relation `roles`: its junction `user_roles` has required column(s) `level` the relation API can't populate. Use the `UserRole` model directly or the SQL builder."*
+- **`connect` and `disconnect` are unaffected** — they only touch the FK pair, never the payload columns; they must still work on a required-payload junction.
+
+Write a **runtime** test: nested `.create` on `User.roles` (the required-payload junction from S3-D2) throws the guard error; `connect`/`disconnect` on `User.roles` succeed (compile the expected junction DML). The pure `User.tags` junction's nested `create` is unaffected (still works).
+
+## Scope
+
+**In:** the runtime required-payload guard in the junction `create` branch (`mutation-executor.ts`); a unit/runtime test for the throw + connect/disconnect-still-work.
+
+**Out:** the **type-level** disable (deferred — operator decision; do not touch `.d.ts` emission or add conditional types); the write path (D1, done); integration tests (D4); other kinds.
+
+## Completed when
+
+- [ ] Nested `.create` on a required-payload junction (`User.roles`) throws a clear error naming the relation + required column(s) + the recommended alternative; uses runtime `requiredPayloadColumns`.
+- [ ] `connect`/`disconnect` on the required-payload junction still produce correct junction DML (unaffected by the guard).
+- [ ] Nested `.create` on the pure junction (`User.tags`, no required payload) is unaffected.
+- [ ] Gate: `pnpm --filter @prisma-next/sql-orm-client typecheck` + `test` green.
+
+## Standing instruction
+
+Runtime guard only. Do NOT attempt the type-level disable (it's blocked on an operator contract decision — see the scope note). No bare `as` casts.
+
+## References
+
+- Slice spec: `projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/spec.md` (note the type-level disable is deferred per decision #8).
+- S3-D1 junction write path (`applyJunctionOwnedMutation`, commit `74a778816`); slice 0 `through.requiredPayloadColumns` (`collection-contract.ts`).
+- S3-D2 fixture: `User.roles` via `UserRole` w/ required `level` (commit `926bdc849`).
+
+## Operational metadata
+
+- **Model tier:** sonnet — bounded runtime guard + test.
+- **Branch:** `tml-2787-slice-3-write`. Explicit staging + `-s` sign-off. **Do not push.** Commit when green.
+- **Time-box:** ~40 min.
+- **Halt + surface to me:** if the runtime guard can't access `requiredPayloadColumns` at the create branch (it should — `RelationDefinition.through` carries it after D1); if anything pulls you toward the type-level disable.

projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/dispatches/04-integration-tests.md

@@ -0,0 +1,43 @@
+# Brief: S3-D4 — M:N nested-write integration tests (operator standard)
+
+## Task
+
+Prove M:N nested writes work end-to-end against the database, following the project's **integration-test standard**. D1 added the junction write path; D2 added the `User.roles` required-payload fixture; D3 added the runtime `.create` disable. Add integration tests under `test/integration/test/sql-orm-client/` (PGlite, `withCollectionRuntime`). Reuse slice 1's `seedTags`/`seedUserTags` + add `Role`/`UserRole` seeds as needed.
+
+**Cases (all required):**
+- **`connect`** — `db.orm.User.update({ ... tags: (t) => t.connect({ id }) })`; read back via `include('tags')` → the tag is linked. Also exercise `connect` in the **`create()`** parent flow.
+- **`disconnect`** — link then `disconnect`; read back → gone. (`update()` flow — disconnect is update-only.)
+- **`create`** (pure junction `User.tags`) — nested `create` inserts the target Tag + the junction link; read back → present.
+- **Runtime disable** — nested `create` on `User.roles` (required-payload junction) **throws** the D3 guard error (`expect(...).rejects.toThrow(/required column.*level/)` or similar); `connect`/`disconnect` on `User.roles` **succeed** + read back.
+- Cover **both `create()` and `update()`** parent flows for connect/create.
+
+**Standard (all three):** (1) whole-row `toEqual` on the readback (via `include('tags')`); (2) explicit `.select(...)` in most tests; (3) **≥1** implicit/default-selection readback.
+
+## Scope
+
+**In:** new integration test file under `test/integration/test/sql-orm-client/`; `Role`/`UserRole` seed helpers if needed (extend `runtime-helpers.ts`).
+
+**Out:** production changes (D1/D3 own the write path + guard — if a test reveals a write bug, surface it, don't patch production here); the **type-level** disable (deferred — only the **runtime** throw is testable now). Don't modify the fixture contract (D2 owns it).
+
+## Completed when
+
+- [ ] Integration tests pass on PGlite: connect (both flows) / disconnect / create (pure junction) with whole-row readback via `include('tags')`; the runtime `.create` disable on `User.roles` throws; connect/disconnect on `User.roles` succeed.
+- [ ] Most tests explicit `.select`; **≥1** implicit/default-selection readback.
+- [ ] Gate: `cd test/integration && pnpm test test/sql-orm-client/<your-file>` green.
+
+## Standing instruction
+
+Match the existing integration corpus. The type-level disable is NOT testable here (deferred) — only assert the **runtime** throw for required-payload `create`. If a write returns the wrong state on readback, **surface it to me** (a D1/D3 bug — must-fix), don't patch the test around it.
+
+## References
+
+- Slice spec: `projects/sql-orm-many-to-many/slices/03-nested-write-through-junction/spec.md` (note: type-level disable deferred per `wip/unattended-decisions.md` #8).
+- Slice 1's `mn-include.test.ts` (readback-via-include pattern) + `runtime-helpers.ts` seeds; slice 2's `mn-filter.test.ts`.
+- D1 write path (`74a778816`), D3 runtime guard (`3bccd80b3`), D2 fixture (`926bdc849`).
+
+## Operational metadata
+
+- **Model tier:** sonnet.
+- **Branch:** `tml-2787-slice-3-write`. Explicit staging + `-s` sign-off. **Do not push.** Commit when green.
+- **Time-box:** ~75 min — core connect/disconnect/create readback first, then both-flows + the runtime-disable + implicit-selection; don't over-explore.
+- **Halt + surface to me:** if the harness can't run in-sandbox (PGlite spin-up failure unrelated to your tests — describe it, don't fake green); if a nested write produces the wrong readback state (D1/D3 bug).