docs(sql-orm-many-to-many): slice 2 dispatch briefs, trace, learnings (TML-2786)

tensordreams · tensordreams · commit 22d77a3e56d5 · 2026-06-02T18:11:04.000+02:00
Filter slice orchestrator artifacts (filter-code dispatch took 2 rounds incl.
a truncation recovery; integration-tests dispatch one round). Review log
gitignored.

Signed-off-by: Alexey Orlenko's AI Agent &lt;robot@aqrln.net&gt;
diff --git a/projects/sql-orm-many-to-many/learnings.md b/projects/sql-orm-many-to-many/learnings.md
@@ -17,3 +17,5 @@ Running the whole sql-orm-client integration suite at once (`cd test/integration
 ## Dispatch truncation recovery (no subagent resume)
 
 A substantial dispatch can exhaust the implementer's budget mid-work and return a truncated report with **uncommitted WIP** (happened on the slice-1 read path). Recovery: inspect `git status`/`git diff`, then dispatch a fresh continuation implementer pointed at the WIP with a focused completion brief (it commits the WIP + completion as one commit). Keep dispatches tight and tell implementers to implement-then-test-then-gate rather than over-explore (over-exploration is what burned the budget).
+
+**Recurrence (2×):** both the slice-1 read-path dispatch and the slice-2 filter dispatch (the "junction-correlation code + unit tests" judgment dispatches) truncated around 70–135k implementer tokens. The combination of (read corpus) + (design the SQL shape) + (write + iterate tests) reliably exceeds one sonnet budget here. The continue-from-WIP recovery works every time, but for future projects of this shape, consider splitting "implement the builder/accessor branch" and "write its unit tests" into two dispatches, or routing these to a higher-budget tier.
diff --git a/projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/dispatches/01-filter-code.md b/projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/dispatches/01-filter-code.md
@@ -0,0 +1,45 @@
+# Brief: S2-D1 — filter EXISTS walks the junction
+
+## Task
+
+Teach the relation-filter accessor to walk the junction for M:N relations. `db.orm.User.filter((u) => u.tags.some/every/none((t) => …))` must emit an EXISTS / NOT EXISTS subquery that goes through the `UserTag` junction. Today `buildJoinWhere` (`packages/3-extensions/sql-orm-client/src/model-accessor.ts`) reads only `relation.on.localFields/targetFields` — for an M:N relation that emits a wrong-shape EXISTS that skips the junction.
+
+When the resolved relation carries `through` (slice 0 added it to `resolveModelRelations`'s output), build the M:N shape in `buildExistsExpr`/`buildJoinWhere`:
+- **`some(pred)`** → `EXISTS (SELECT 1 FROM target JOIN junction ON junction.childColumns = target.targetColumns WHERE junction.parentColumns = parent.anchor AND <pred>)`.
+- **`none(pred)`** → `NOT EXISTS (… AND <pred>)`.
+- **`every(pred)`** → `NOT EXISTS (… AND NOT(<pred>))` — mirror the existing FK `every` shape, just through the junction.
+
+The parent correlation is on the **junction** side; the target is reached via the junction join; composite keys AND-ed across all pairs. The child predicate is unchanged.
+
+**First confirm** the relation reaching `buildJoinWhere` carries `through` — it should, via `resolveModelRelations` (slice 0). If the filter path uses a relation shape that drops `through`, surface it onto that path (one field; mirror how slice 1 surfaced `through` onto `IncludeExpr`).
+
+**Write unit tests first** asserting the compiled EXISTS AST for `some`/`every`/`none` on an M:N relation joins through the junction (composite-key AND-ed), and that FK relation filters are unchanged.
+
+## Scope
+
+**In:** the M:N branch in `buildExistsExpr`/`buildJoinWhere` (`model-accessor.ts`) for some/every/none; surfacing `through` onto the filter relation if dropped; unit tests for the EXISTS AST.
+
+**Out:** integration tests (S2-D2); include reads (slice 1); nested writes (slice 3); the `through` shape (slice 0). Don't regress FK filters.
+
+## Completed when
+
+- [ ] `some`/`every`/`none` on an M:N relation compile to a correctly-shaped EXISTS/NOT EXISTS through the junction (composite-key AND-ed); unit test asserts the AST.
+- [ ] FK relation filters unchanged (existing model-accessor unit tests pass).
+- [ ] Gate: `pnpm --filter @prisma-next/sql-orm-client typecheck` + `test` green.
+
+## Standing instruction
+
+Stay focused on the junction EXISTS. The judgment site is the junction hop in `buildJoinWhere` and the `every` = `NOT EXISTS(… NOT(pred))` shape; mirror the FK path. No bare `as` casts (use `castAs`/`blindCast` if unavoidable — a sibling slice was bounced for bare casts twice; don't add new ones).
+
+## References
+
+- Slice spec: `projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/spec.md`.
+- `model-accessor.ts`: `createRelationFilterAccessor` (~190), `buildExistsExpr` (~222), `buildJoinWhere` (~331) — the FK path to extend.
+- Slice 0 `ResolvedRelation.through` in `collection-contract.ts`.
+
+## Operational metadata
+
+- **Model tier:** sonnet — bounded judgment (the junction EXISTS + every/none shapes).
+- **Branch:** `tml-2786-slice-2-filter`. Explicit staging + `-s` sign-off. **Do not push.**
+- **Time-box:** ~75 min — implement `some` first + its test, then `none`/`every`, then gate; don't over-explore.
+- **Halt + surface to me:** if `buildJoinWhere`'s EXISTS construction can't host the junction join without a structural change beyond the FK path's shape (surface the obstacle); if `through` is genuinely unavailable on the filter relation and surfacing it touches an out-of-scope consumer.
diff --git a/projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/dispatches/01-filter-code.r2.md b/projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/dispatches/01-filter-code.r2.md
@@ -0,0 +1,39 @@
+# Brief: S2-D1 R2 — finish the filter EXISTS (continue from WIP)
+
+## Situation
+
+The R1 implementer ran out of budget mid-work and **did not commit**. Uncommitted WIP is in the tree (`git status` + `git diff`): `src/model-accessor.ts` (+96) and `test/model-accessor.test.ts` (+182). It was mid-fix on the **parent-anchor correlation** — it had just realised the junction→parent side must resolve from `relation.on.localFields` (the parent's anchor columns), not from `through.parentColumns`, and was about to thread `contract` + `parentModelName` into a `buildManyToManyExistsExpr` helper to resolve them.
+
+## Task
+
+**Read the uncommitted diff first.** Then finish:
+
+1. Complete the M:N EXISTS for `some`/`every`/`none` in `model-accessor.ts`. The correlation has two distinct sides — get both right (this is exactly what slice 1's read path established, mirror it for consistency):
+   - **junction → parent:** `junction.{through.parentColumns} = parent.{on.localFields resolved to columns}` (e.g. `user_tags.user_id = users.id`). Resolve the parent anchor columns via `resolveFieldToColumn(contract, parentModelName, localField)` — thread `contract`/`parentModelName` into the helper as the WIP was starting to do.
+   - **junction → target:** `junction.{through.childColumns} = target.{through.targetColumns}` (e.g. `user_tags.tag_id = tags.id`).
+   - Shapes: `some` = `EXISTS(SELECT 1 FROM target JOIN junction ON <j→t> WHERE <j→parent> AND <pred>)`; `none` = `NOT EXISTS(… AND <pred>)`; `every` = `NOT EXISTS(… AND NOT(<pred>))`. Composite-key AND-ed across all pairs.
+2. Reconcile R1's WIP unit tests so they pass and assert the AST (junction join + both correlation sides; some/every/none). Fix any incoherent WIP test.
+3. Don't regress FK relation filters.
+
+## Completed when
+
+- [ ] `some`/`every`/`none` on M:N compile to the correct junction EXISTS/NOT EXISTS (both correlation sides correct, composite-key AND-ed); unit tests pass.
+- [ ] FK filter tests pass.
+- [ ] `pnpm --filter @prisma-next/sql-orm-client typecheck` + `test` green.
+- [ ] Committed as **one coherent commit** (WIP + completion), explicit staging + `-s` sign-off, **no push**. No bare `as` casts.
+
+## Standing instruction
+
+Finish the goal; keep R1's coherent WIP. Implement → get the targeted test green → run the package gate; don't re-explore.
+
+## References
+
+- R1 brief: `./01-filter-code.md`. Slice spec: `../spec.md`.
+- **Slice 1 read path** (`query-plan-select.ts` `buildManyToManyJunctionArtifacts`, commit `e587b433c`) resolved the same two-sided junction correlation — mirror its parent-anchor resolution for consistency.
+
+## Operational metadata
+
+- **Model tier:** sonnet.
+- **Branch:** `tml-2786-slice-2-filter` (WIP already on it). Explicit staging + `-s`; **no push**. Don't commit under `projects/`.
+- **Time-box:** ~50 min.
+- **Halt + surface to me:** if R1's WIP is incoherent in a way you can't reconcile (describe it); if the junction EXISTS needs a structural change beyond the FK EXISTS shape.
diff --git a/projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/dispatches/02-integration-tests.md b/projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/dispatches/02-integration-tests.md
@@ -0,0 +1,42 @@
+# Brief: S2-D2 — M:N filter integration tests (operator standard)
+
+## Task
+
+Prove M:N relation filters work end-to-end against the database, following the project's **integration-test standard**. D1 made `.some`/`.every`/`.none` emit a junction EXISTS; slice 1's fixture has `User.tags` (→ `Tag` via `UserTag`) and `seedTags`/`seedUserTags` helpers. Add integration tests under `test/integration/test/sql-orm-client/` (PGlite, `withCollectionRuntime`). Seed users/tags/junction rows, then assert `db.orm.User.filter((u) => u.tags.some/every/none(...))` returns the right users.
+
+**Cases (all required):**
+- **`some`** — users having ≥1 tag matching a predicate (e.g. `t.name.eq('x')`).
+- **`none`** — users with no matching tag.
+- **`every`** — users all of whose tags match (include a user with a non-matching tag to prove they're excluded; and verify the vacuous case — a user with **no** tags satisfies `every`).
+- **empty-match edge** — a predicate no tag matches → `some` returns none, `none`/`every` behave correctly.
+
+**Standard (all three):** (1) whole-row `toEqual` on the **filtered result set** (assert exactly which users come back, full row shape); (2) explicit `.select(...)` in **most** tests; (3) **≥1** test uses implicit/default selection (no `.select`, asserts full default row shape of the returned users).
+
+## Scope
+
+**In:** new integration test file under `test/integration/test/sql-orm-client/`; reuse slice 1's seed helpers (extend if a filter test needs more seed data).
+
+**Out:** filter code (D1); include reads (slice 1); writes (slice 3); production changes (if a test reveals a filter bug, surface it — don't patch production here). Don't modify the fixture contract.
+
+## Completed when
+
+- [ ] Integration tests pass on PGlite covering `some`, `none`, `every` (incl. the vacuous no-tags case) and an empty-match edge, asserting the exact filtered user set as **whole rows** (`toEqual`).
+- [ ] Most tests use explicit `.select`; **≥1** uses implicit/default selection.
+- [ ] Gate: `cd test/integration && pnpm test test/sql-orm-client/<your-file>` green (the in-sandbox path for this suite).
+
+## Standing instruction
+
+Match the existing integration corpus style. If a test surfaces a real filter bug (wrong users returned), **surface it to me** with the failing assertion — that's a `must-fix` against D1, not something to patch in the test.
+
+## References
+
+- Slice spec: `projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/spec.md` (§ done conditions — the standard).
+- Slice 1's `mn-include.test.ts` + `runtime-helpers.ts` (`seedTags`/`seedUserTags`) — the harness + seed pattern to reuse.
+- Existing filter integration tests (if any) for `.some/.every/.none` on FK relations — mirror their structure.
+
+## Operational metadata
+
+- **Model tier:** sonnet.
+- **Branch:** `tml-2786-slice-2-filter`. Explicit staging + `-s` sign-off. **Do not push.**
+- **Time-box:** ~60 min — core `some`/`none`/`every` whole-row tests first, then the implicit-selection + empty-match cases; don't over-explore.
+- **Halt + surface to me:** if the integration harness can't run in-sandbox (PGlite spin-up failure unrelated to your tests — describe it, don't fake green); if a filter returns the wrong user set (D1 bug).
diff --git a/projects/sql-orm-many-to-many/trace.jsonl b/projects/sql-orm-many-to-many/trace.jsonl
@@ -48,3 +48,16 @@
 {"event_id":"10edc1f4-e070-4dc6-b0ac-bf8eaf2565a7","schema_version":"1","ts":"2026-06-01T19:14:44.090Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"dispatch-end","dispatch_id":"88c9c264-8edc-4584-b440-7d51eeae37e4","result":"completed","wall_clock_ms":1299697}
 {"event_id":"c766ebb8-dfa9-4f3a-b033-3ce51a3594cc","schema_version":"1","ts":"2026-06-01T19:18:04.849Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"spec-authored","spec_path":"projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/spec.md","spec_kind":"slice","byte_length":4110,"edge_cases_count":3,"open_questions_count":1,"dod_items_count":3}
 {"event_id":"c358128a-8d02-451d-b2d6-ee791793231e","schema_version":"1","ts":"2026-06-01T19:18:05.325Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"plan-authored","plan_path":"projects/sql-orm-many-to-many/slices/02-filter-exists-through-junction/plan.md","plan_kind":"slice","byte_length":2068,"dispatch_count":2,"slice_count":null,"dispatch_size_distribution":{"S":0,"M":2,"L":0,"XL":0},"open_items_count":0}
+{"event_id":"1f4269f6-b643-49cc-b578-486bde519cb2","schema_version":"1","ts":"2026-06-01T19:18:55.231Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"dispatch-start","dispatch_id":"e9a8e215-dd56-4083-8da7-7a662426285d","dispatch_name":"S2-D1 filter EXISTS through junction","subagent_type":"general-purpose","model":"sonnet","parent_dispatch_id":null}
+{"event_id":"0204eb47-f7db-4946-baaf-9ac8e44efa7f","schema_version":"1","ts":"2026-06-01T19:18:55.645Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"round-start","dispatch_id":"e9a8e215-dd56-4083-8da7-7a662426285d","round_id":"c1a6d082-e1ff-4946-85b5-ffdc629907f7","round_number":1}
+{"event_id":"8acf055e-4669-437a-b8d0-c9116fb33f7a","schema_version":"1","ts":"2026-06-01T19:18:56.042Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"brief-issued","dispatch_id":"e9a8e215-dd56-4083-8da7-7a662426285d","round_id":"c1a6d082-e1ff-4946-85b5-ffdc629907f7","brief_byte_length":3636,"brief_content_hash":"4315f8e52c313f3c635deb90d4cfabd34a09475ac2e1f5ddb8c2e283397c93af","brief_disposition":"initial"}
+{"event_id":"d3da2730-50fa-4a39-a20c-0104eac93e3e","schema_version":"1","ts":"2026-06-01T19:24:24.824Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"round-end","dispatch_id":"e9a8e215-dd56-4083-8da7-7a662426285d","round_id":"c1a6d082-e1ff-4946-85b5-ffdc629907f7","verdict":"another-round-needed","findings_filed":0,"wall_clock_ms":328774}
+{"event_id":"f2f19a37-be1f-4344-9bf4-dae9f9325c35","schema_version":"1","ts":"2026-06-01T19:24:25.231Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"round-start","dispatch_id":"e9a8e215-dd56-4083-8da7-7a662426285d","round_id":"42b0293b-0378-47f7-a45b-8ee88eabba48","round_number":2}
+{"event_id":"01685cd6-220a-4ffc-a954-f6f50c0c8e53","schema_version":"1","ts":"2026-06-01T19:24:25.606Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"brief-issued","dispatch_id":"e9a8e215-dd56-4083-8da7-7a662426285d","round_id":"42b0293b-0378-47f7-a45b-8ee88eabba48","brief_byte_length":3019,"brief_content_hash":"78194f31856d295021e8c57a90d3e795311b3aae0c276348a87154e3d31a301f","brief_disposition":"amended"}
+{"event_id":"8d180a85-decb-4192-a567-ee2ecb295f69","schema_version":"1","ts":"2026-06-01T19:32:16.305Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"round-end","dispatch_id":"e9a8e215-dd56-4083-8da7-7a662426285d","round_id":"42b0293b-0378-47f7-a45b-8ee88eabba48","verdict":"satisfied","findings_filed":0,"wall_clock_ms":470687}
+{"event_id":"7a0516c4-2017-4f7c-abf9-a56cb3de8ce8","schema_version":"1","ts":"2026-06-01T19:32:16.709Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"dispatch-end","dispatch_id":"e9a8e215-dd56-4083-8da7-7a662426285d","result":"completed","wall_clock_ms":800687}
+{"event_id":"78b3ccd1-b852-4db1-8345-7473066dd2c6","schema_version":"1","ts":"2026-06-01T19:32:50.761Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"dispatch-start","dispatch_id":"cf687dda-ed46-4038-aa28-ad94ba17dd8f","dispatch_name":"S2-D2 M:N filter integration tests","subagent_type":"general-purpose","model":"sonnet","parent_dispatch_id":null}
+{"event_id":"1ba55c50-3aac-4fa3-83c5-33068f6a3412","schema_version":"1","ts":"2026-06-01T19:32:51.145Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"round-start","dispatch_id":"cf687dda-ed46-4038-aa28-ad94ba17dd8f","round_id":"1f3a01e1-6941-4453-808b-b833c553c03e","round_number":1}
+{"event_id":"2d3e4bc6-9ee3-4c31-a31a-acbdb6aa2281","schema_version":"1","ts":"2026-06-01T19:32:51.521Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"brief-issued","dispatch_id":"cf687dda-ed46-4038-aa28-ad94ba17dd8f","round_id":"1f3a01e1-6941-4453-808b-b833c553c03e","brief_byte_length":3285,"brief_content_hash":"2221c822875da35648cb846f12094465a23c2565d55c8e10f6690482e3bce2e7","brief_disposition":"initial"}
+{"event_id":"5e42b22f-745d-4b15-8352-f874f1873552","schema_version":"1","ts":"2026-06-01T19:41:15.103Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"round-end","dispatch_id":"cf687dda-ed46-4038-aa28-ad94ba17dd8f","round_id":"1f3a01e1-6941-4453-808b-b833c553c03e","verdict":"satisfied","findings_filed":0,"wall_clock_ms":503436}
+{"event_id":"b61b7318-eee7-458f-ad44-0873e860b3c4","schema_version":"1","ts":"2026-06-01T19:41:15.494Z","project_run_id":"sql-orm-many-to-many","orchestrator_agent_id":null,"event_type":"dispatch-end","dispatch_id":"cf687dda-ed46-4038-aa28-ad94ba17dd8f","result":"completed","wall_clock_ms":503820}
