TML-2597: SQL ORM many-to-many — project spec + plan

[tensordreams]

Shaping artifacts for the SQL ORM: Many-to-Many End to End project. No code changes — projects/sql-orm-many-to-many/ only (spec, plan, README, trace).

Stacked on #667 (TML-2729, correlated-only read path). Review/merge that first; this PR is based on its branch, not main.

What this adds

• spec.md — system-level intent: restore the relation-shaped ORM API (include / filter / nested write) over M:N, so users stop hand-wiring explicit junction models and the Pothos plugin stops rejecting M:N at build.
• plan.md — 4 slices: slice 0 (contract + resolver foundation) gates a parallel fan-out of read / filter / write.

Key decisions captured

• The ticket was stale. Its Phase 1/2 (LATERAL path, multi-query fallback) were deleted by TML-2729: drop LATERAL include codegen for correlated-only read path #667 (TML-2729) and TML-2657. The work now extends the correlated builder; there is no LATERAL or fallback path to teach.
• Surprise found while shaping: an emitted M:N contract does not validate today — the relation validator rejects cardinality: N:M and the undeclared through key. Slice 0 closes that; it is a real gap, not prep.
• Representation: a uniform through descriptor on the single shared resolver, consumed three ways (not junction-as-nested-include, which does not generalise to filter/write).
• Scope: write vocabulary is the three kinds that exist (connect/disconnect/create); nested update/upsert/delete/set are out of scope → TML-2781.

Linear

Promoted from TML-2597 to a dedicated Linear Project (SQL ORM: Many-to-Many End to End). Slices: TML-2784 (0) / TML-2785 (1) / TML-2786 (2) / TML-2787 (3).

Scope statement

Planning artifacts only. No package code, no fixtures, no behavior change. Refs: TML-2597.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (4)

• projects/sql-orm-many-to-many/README.md is excluded by !projects/**
• projects/sql-orm-many-to-many/plan.md is excluded by !projects/**
• projects/sql-orm-many-to-many/spec.md is excluded by !projects/**
• projects/sql-orm-many-to-many/trace.jsonl is excluded by !projects/**

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 85c98717-6d8d-4529-a1e6-77c9435be0d5

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-2597-sql-orm-complete-end-to-end-many-to-many-support-include

---

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	137.29 KB (0%)
postgres / emit	108.81 KB (0%)
mongo / no-emit	75.77 KB (0%)
mongo / emit	70.78 KB (0%)
cf-worker / no-emit	166.3 KB (0%)
cf-worker / emit	134.51 KB (0%)

[pkg-pr-new]

Open in StackBlitz

@prisma-next/extension-author-tools

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

@prisma-next/mongo-runtime

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

@prisma-next/family-mongo

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

@prisma-next/sql-runtime

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

@prisma-next/family-sql

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

@prisma-next/extension-arktype-json

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

@prisma-next/middleware-cache

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

@prisma-next/mongo

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

@prisma-next/extension-paradedb

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

@prisma-next/extension-pgvector

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

@prisma-next/extension-postgis

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

@prisma-next/postgres

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

@prisma-next/sql-orm-client

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

@prisma-next/sqlite

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

@prisma-next/target-mongo

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

@prisma-next/adapter-mongo

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

@prisma-next/driver-mongo

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

@prisma-next/contract

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

@prisma-next/utils

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

@prisma-next/config

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

@prisma-next/errors

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

@prisma-next/framework-components

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

@prisma-next/operations

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

@prisma-next/ts-render

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

@prisma-next/contract-authoring

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

@prisma-next/ids

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

@prisma-next/psl-parser

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

@prisma-next/psl-printer

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

@prisma-next/cli

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

@prisma-next/cli-telemetry

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

@prisma-next/emitter

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

@prisma-next/migration-tools

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

prisma-next

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

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

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

@prisma-next/mongo-codec

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

@prisma-next/mongo-contract

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

@prisma-next/mongo-value

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

@prisma-next/mongo-contract-psl

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

@prisma-next/mongo-contract-ts

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

@prisma-next/mongo-emitter

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

@prisma-next/mongo-schema-ir

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

@prisma-next/mongo-query-ast

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

@prisma-next/mongo-orm

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

@prisma-next/mongo-query-builder

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

@prisma-next/mongo-lowering

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

@prisma-next/mongo-wire

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

@prisma-next/sql-contract

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

@prisma-next/sql-errors

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

@prisma-next/sql-operations

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

@prisma-next/sql-schema-ir

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

@prisma-next/sql-contract-psl

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

@prisma-next/sql-contract-ts

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

@prisma-next/sql-contract-emitter

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

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

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

@prisma-next/sql-relational-core

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

@prisma-next/sql-builder

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

@prisma-next/target-postgres

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

@prisma-next/target-sqlite

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

@prisma-next/adapter-postgres

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

@prisma-next/adapter-sqlite

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

@prisma-next/driver-postgres

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

@prisma-next/driver-sqlite

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

commit: 433e9bb