Add many-to-many include support via a single correlated subquery that
joins the child table to the junction on junction.childColumns = child.targetColumns
and correlates to the parent via WHERE junction.parentColumns = parent.parentLocalColumns.
Composite keys AND across all column pairs. No LATERAL joins.

- IncludeExpr gains `through?: IncludeThroughDescriptor` carrying junction table
  name, parentColumns, childColumns, targetColumns, and parentLocalColumns.
- `resolveIncludeRelation` in collection-contract.ts surfaces `through` from the
  contract relation when present, resolving field names to column names for the
  parent local columns.
- `Collection.include()` propagates `through` into IncludeExpr via spread.
- `buildManyToManyJunctionArtifacts` in query-plan-select.ts builds the JOIN ON
  expression (BinaryExpr or AndExpr over child column pairs) and the correlated
  WHERE (BinaryExpr or AndExpr over parent column pairs), producing a non-lateral
  inner JoinAst to the junction table.
- `buildIncludeChildRowsSelect` detects `include.through` and uses the M:N
  artifacts instead of the FK equality WHERE; `buildDistinctNonLeafChildRowsSelect`
  receives and applies the same junction joins.
- `dispatchWithIncludes` in collection-dispatch.ts forces all `through.parentLocalColumns`
  (not just `localColumn`) into the parent SELECT augmentation for composite M:N keys.
- `buildManyToManyContract` test helper and M:N unit tests covering single-column
  and composite-key junction shapes, plus a FK path non-regression test.

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

…ManyJunctionArtifacts; add M:N+distinct+non-leaf test

F1: the two bare `as AnyExpression` casts in `buildManyToManyJunctionArtifacts` are replaced with
`castAs<AnyExpression>(…!)` — BinaryExpr is a union member of AnyExpression, so the assertion is
type-checked; the non-null assertion is safe because the branch is only taken when `length === 1`.
Adds the `castAs` import from `@prisma-next/utils/casts`. `lint:casts` delta: -1.

F2: new unit test `attaches junction join to baseInner in M:N + distinct + nested non-leaf path`
in the `M:N include correlated subquery` describe block. Constructs a contract with
parents→children (M:N via parent_child junction) + children→grandchildren (FK), sets
`distinct: ['name']` and a nested grandchild include on the M:N IncludeExpr, calls
`compileSelectWithIncludes`, and asserts:
  - junction join (`INNER JOIN parent_child`, `lateral: false`) attaches to `baseInner`
    (the innermost scalar SELECT inside the ROW_NUMBER wrap), not to the dedup wrapper or
    outer distinct SELECT
  - correlated WHERE (`parent_child.parent_id = parents.id`) is present at `baseInner`
  - no junction join leaks to `innerSelect` or the outer `childRows`

All 493 tests pass; typecheck clean.

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

Adds `mn-include.test.ts` covering the end-to-end M:N include path for
`User.tags` via the `user_tags` junction, using the PGlite harness.

Tests satisfy the operator integration-test standard:
- Whole-row toEqual assertions on every test
- Explicit .select() on 6/7 tests
- One implicit/default-selection test (full User + tags: Tag[] shape)
- Single-execution assertion + no LATERAL in emitted SQL
- Depth-2: M:N tags nested under invitedUsers (1:N self-relation)
- Sibling depth-2: include("tags") alongside include("posts") in one execution
- Edge: user with no tags returns tags: []
- Edge: tag shared by multiple users resolves independently for each

Also extends `setupTestSchema` and adds `seedTags`/`seedUserTags` helpers
to `runtime-helpers.ts` to support the junction table in integration tests.

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

… (TML-2785)

Orchestrator artifacts for the read slice (fixture / read-path / integration
dispatches; read-path took 3 rounds incl. a truncation recovery). Review log
under reviews/ is gitignored.

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

…-2605 rebase

Carry the resolved junction namespaceId onto IncludeThroughDescriptor and
build the correlated include's junction TableSource with it, so the read
path emits namespace-qualified SQL for the junction like the rest of the
runtime after TML-2605.

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

…ough descriptor

The contract now carries the junction's namespaceId on through (slice 0);
the include descriptor passes it through as a required field instead of
re-deriving it from storage. Re-emit the M:N fixture so the User<->Tag
through block carries it.

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

… M:N contracts (TML-2808 rebase)

Main moved namespace tables under entries.table; the hand-built M:N test
contracts still used the flat tables record, so table resolution missed
them.

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

…eated_at)

The shared fixture's junction declares a nullable note and a defaulted
created_at (exclusion-path coverage for requiredPayloadColumns); create
the columns so the schema matches the contract.

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

…junction artifacts

biome `noNonNullAssertion` (error-on-warnings) flagged the `joinOnPairs[0]!`
/ `correlationPairs[0]!` non-null assertions. Narrow with a truthy guard on
the destructured first element instead, which also removes the castAs (so
its import goes too).

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

…-2841 coordinate rebase

Main un-pinned the ORM client onto ADR 221 coordinates: resolveFieldToColumn
gained a leading namespaceId, IncludeExpr requires relatedNamespaceId, and
compileSelectWithIncludes takes (contract, namespaceId, table, state). Adapt
the M:N parentLocalColumns resolution and the read-path tests accordingly.

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

…tions

Slice 0 (the contract-shape change) merged into main, so its instructions
touch is no longer in the open PRs diff — but slices 1-3 still touch
packages/3-extensions/, which the check:upgrade-coverage gate requires be
accompanied by an instructions touch. Record the M:N runtime slices as
incidental for extension authors (no API/contract change beyond TML-2784).

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

Replace the silent `?? junctionCol` fallback indexing in
buildManyToManyJunctionArtifacts with explicit length invariants over the
through descriptor's column arrays (childColumns/targetColumns and
parentColumns/parentLocalColumns), then index with assertDefined narrowing
so a misalignment throws a clear error instead of emitting a wrong join or
correlation predicate.

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

…spread

Replace the manual `...(x !== undefined ? { through: x } : {})` spreads in
resolveIncludeRelation and the include builder with the ifDefined helper from
@prisma-next/utils/defined, per the use-if-defined convention.

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

Migrate the M:N include query-plan unit tests off the hand-rolled
buildManyToManyContract helper and onto the real emitted fixture's relations:
User.tags via user_tags (single-column), Project.related via project_links
(composite, self-referential), and the distinct + nested-non-leaf lowering via
Project.related distinct('name').include('related'). Each test now asserts the
whole compiled plan.ast with a single toEqual and drops the lateral / 'no
LATERAL' assertions (there is only one strategy). buildManyToManyContract (and
its RawColumn type) had no remaining uses on this branch and is removed.

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

…M:N include

Drop the SQL-string LATERAL assertions from the M:N include integration tests.
LATERAL can't appear (no such strategy exists in code), so the assertion tested
an implementation detail. The real non-functional invariant — the include
resolves in a single SQL execution — is already asserted via
runtime.executions length.

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

The 0.12->0.13 extension-author note overstated delivered functionality: it
claimed EXISTS-through-junction filters (TML-2786) and junction nested writes
(TML-2787) alongside the correlated include read. This slice is read-only, so
narrow the note to TML-2785's M:N correlated include read; the filter and write
paths are documented in their own slices.

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

…suite

The test asserting that a 1:N FK include still lowers without a junction
join carried an opaque name ("FK include path is unchanged (no
regression)") that didn't say what it checks or how it relates to M:N.
Rename it to state the asserted lowering and add a comment marking it as
the control case for the junction-join branch — it pins that the branch
fires only for N:M relations and never leaks into the FK include path.

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

0.13.0 shipped without the sql-orm-client M:N runtime, so the note
describing the correlated include reads belongs in the 0.13→0.14
extension-author instructions, not the now-released 0.12→0.13 doc. The
upgrade-coverage gate targets 0.13→0.14 after the release bump.

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