docs(sql-orm): retire stale includeMany references; align include docs with correlated lowering

`includeMany` is no longer a method on any surface — the ORM exposes
`.include(...)` and the SQL builder has no include method. Clean up the
references this leaves behind, and align the adapter docs with the
correlated-only include lowering this branch introduces:

- Delete the obsolete `include-many-patterns.mdc` rulecard (it documented
  a removed `SelectBuilderImpl.includeMany()` API) and its index entry.
- Remove the dead `HasIncludeManyCapabilities` type (zero usages; it
  encoded the now-defunct lateral+jsonAgg include gate).
- Postgres README: includes now lower to a correlated subquery, not
  `LEFT JOIN LATERAL`; note LATERAL emission is retained only for the
  public `lateralJoin()` DSL.
- SQLite README: rename includeMany -> include; correlated is the
  strategy, not a fallback.
- AGENTS.md (capability-gating example), the queries skill gotcha, and a
  stale e2e describe label: includeMany -> include / a real capability.
- Remove the broken `### Queries with includeMany` SQL-builder example
  from query-patterns.md (it called a nonexistent `.includeMany()`).

ADRs and the Query Lanes subsystem doc are left as-is (historical /
architecture docs handled separately).

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

Author: tensordreams

.agents/rules/README.md

@@ -90,7 +90,6 @@ Rules below are listed by bare filename; the canonical file is `.agents/rules/<n
 ## SQL & Query Patterns
 - `query-patterns.mdc` — Query DSL patterns
 - `postgres-lateral-patterns.mdc` — LATERAL/json_agg patterns
-- `include-many-patterns.mdc` — includeMany type inference
 - `sql-types-imports.mdc` — SQL types import path (use @prisma-next/sql-contract/types)
 
 ## TypeScript & Typing

.agents/rules/include-many-patterns.mdc

@@ -92,7 +92,7 @@ pnpm fixtures:check        # Use this rather than ad-hoc emit-and-diff
 - **ExecutionContext**: Encapsulates contract, codecs, operations, and types. Pass to `schema()`, `sql()`, `orm()`.
 - **Interface + factory pattern for stateful services**: Stateful services (registries, runtimes, adapters, drivers) are exposed through an interface plus a `createX()` factory; the implementing class stays package-private. Consumers depend on the interface, never the implementation. Pattern reference: [`docs/architecture docs/patterns/interface-plus-factory.md`](docs/architecture%20docs/patterns/interface-plus-factory.md).
 - **Three-layer polymorphic IR for AST/IR class hierarchies**: AST/IR nodes (Contract IR, Schema IR, migration ops) are organised as framework interface → family abstract base → target concrete classes. Concrete classes are publicly exported as the target's IR alphabet; `freezeNode(this)` is called in the constructor. Target packs contribute new entity kinds via `AuthoringContributions.entities` (see [`docs/reference/typescript-patterns.md`](docs/reference/typescript-patterns.md) § "AST/IR class hierarchies"). Pattern references: [`three-layer-polymorphic-ir.md`](docs/architecture%20docs/patterns/three-layer-polymorphic-ir.md), [`frozen-class-ast.md`](docs/architecture%20docs/patterns/frozen-class-ast.md), [`json-canonical-class-in-memory.md`](docs/architecture%20docs/patterns/json-canonical-class-in-memory.md).
-- **Capability Gating**: Features like `includeMany` and `returning()` require capabilities in the contract; gating is enforced at authoring time.
+- **Capability Gating**: Features like `returning()` require capabilities in the contract; gating is enforced at authoring time.
 - **Builder chaining**: Methods return new instances — always chain calls.
 - **Column access**: Use `table.columns.fieldName` to avoid conflicts with table properties.
 

AGENTS.md

@@ -152,39 +152,6 @@ const plan = db.sql
 type JoinedRow = ResultType<typeof plan>;
 ```
 
-### Queries with includeMany
-
-```typescript
-import { db } from '../prisma/db';
-import type { ResultType } from '@prisma-next/sql-query/types';
-
-const userTable = db.schema.tables.user;
-const postTable = db.schema.tables.post;
-
-const plan = db.sql
-  .from(userTable)
-  .includeMany(
-    postTable,
-    (on) => on.eqCol(userTable.columns.id, postTable.columns.userId),
-    (child) =>
-      child
-        .select({
-          id: postTable.columns.id,
-          title: postTable.columns.title,
-        })
-        .orderBy(postTable.columns.createdAt.desc()),
-    { alias: 'posts' },
-  )
-  .select({
-    id: userTable.columns.id,
-    email: userTable.columns.email,
-    posts: true,
-  })
-  .build();
-
-type UserWithPosts = ResultType<typeof plan>;
-```
-
 ## Anti-Patterns
 
 **❌ WRONG: Don't create extra aliases for one-off usage**

docs/reference/query-patterns.md

@@ -151,26 +151,6 @@ export type ComputeColumnJsType<
         : never
     : never;
 
-/**
- * Utility type to check if a contract has the required capabilities for includeMany.
- * Requires both `lateral` and `jsonAgg` to be `true` in the contract's capabilities for the target.
- * Capabilities are nested by target: `{ [target]: { lateral: true, jsonAgg: true } }`
- */
-export type HasIncludeManyCapabilities<TContract extends Contract<SqlStorage>> = TContract extends {
-  capabilities: infer C;
-  target: infer T;
-}
-  ? T extends string
-    ? C extends Record<string, Record<string, boolean>>
-      ? C extends { [K in T]: infer TargetCaps }
-        ? TargetCaps extends { lateral: true; jsonAgg: true }
-          ? true
-          : false
-        : false
-      : false
-    : false
-  : false;
-
 /**
  * Alias for the SQL-domain executable plan, exposed under the legacy
  * `SqlPlan` name for compatibility with SQL builder/utility call sites.

packages/2-sql/4-lanes/relational-core/src/types.ts

@@ -20,7 +20,7 @@ Provide PostgreSQL-specific adapter implementation, codecs, and capabilities. En
 
 - **Adapter Implementation**: Implement `Adapter` SPI for PostgreSQL
   - Lower SQL ASTs to PostgreSQL dialect SQL
-  - Render `includeMany` as `LEFT JOIN LATERAL` with `json_agg` for nested array includes
+  - Render `.include(...)` as a correlated subquery with `json_agg` for nested array includes
   - Advertise PostgreSQL capabilities (`lateral`, `jsonAgg`)
   - Normalize PostgreSQL EXPLAIN output
   - Map PostgreSQL errors to `RuntimeError` envelope
@@ -90,7 +90,7 @@ flowchart TD
 - Main adapter implementation
 - Lowers SQL ASTs to PostgreSQL SQL
 - Renders joins (INNER, LEFT, RIGHT, FULL) with ON conditions
-- Renders `includeMany` as `LEFT JOIN LATERAL` with `json_agg` for nested array includes
+- Renders `.include(...)` as a correlated subquery with `json_agg` for nested array includes
 - Renders DML operations (INSERT, UPDATE, DELETE) with RETURNING clauses
 - Advertises PostgreSQL capabilities (`lateral`, `jsonAgg`, `returning`)
 - Maps PostgreSQL errors to `RuntimeError`
@@ -191,8 +191,8 @@ The adapter declares the following PostgreSQL capabilities:
 
 - **`orderBy: true`** - Supports ORDER BY clauses
 - **`limit: true`** - Supports LIMIT clauses
-- **`lateral: true`** - Supports LATERAL joins for `includeMany` nested array includes
-- **`jsonAgg: true`** - Supports JSON aggregation functions (`json_agg`) for `includeMany`
+- **`lateral: true`** - Supports LATERAL joins (used by the SQL-builder `lateralJoin()` DSL)
+- **`jsonAgg: true`** - Supports JSON aggregation functions (`json_agg`) used to lower `.include(...)` to correlated subqueries
 - **`returning: true`** - Supports RETURNING clauses for DML operations (INSERT, UPDATE, DELETE)
 - **`sql.enums: true`** - Supports contract-defined enum storage types
 
@@ -205,31 +205,30 @@ The capabilities on the descriptor must match the capabilities in code. If they
 
 See `docs/reference/capabilities.md` and `docs/architecture docs/subsystems/5. Adapters & Targets.md` for details.
 
-## includeMany Support
+## Include Support
 
-The adapter supports `includeMany` for nested array includes using PostgreSQL's `LATERAL` joins and `json_agg`:
+The adapter lowers `.include(...)` for nested array includes to a correlated subquery in the SELECT list, using `json_agg`:
 
 **Lowering Strategy:**
-- Renders `includeMany` as `LEFT JOIN LATERAL` with a subquery that uses `json_agg(json_build_object(...))` to aggregate child rows into a JSON array
-- The ON condition from the include is moved into the WHERE clause of the lateral subquery
-- When both `ORDER BY` and `LIMIT` are present, wraps the query in an inner SELECT that projects individual columns with aliases, then uses `json_agg(row_to_json(sub.*))` on the result
-- Uses different aliases for the table (`{alias}_lateral`) and column (`{alias}`) to avoid ambiguity
+- Renders each `.include(...)` as a correlated subquery that uses `json_agg(json_build_object(...))` to aggregate child rows into a JSON array
+- The ON condition from the include becomes the WHERE clause of the correlated subquery, referencing the outer row
+- When both `ORDER BY` and `LIMIT` are present, wraps the child query in an inner SELECT that projects individual columns with aliases, then uses `json_agg(row_to_json(sub.*))` on the result
 
 **Capabilities Required:**
-- `lateral: true` - Enables LATERAL join support
 - `jsonAgg: true` - Enables `json_agg` function support
 
 **Example SQL Output:**
 ```sql
-SELECT "user"."id" AS "id", "posts_lateral"."posts" AS "posts"
-FROM "user"
-LEFT JOIN LATERAL (
+SELECT "user"."id" AS "id", (
   SELECT json_agg(json_build_object('id', "post"."id", 'title', "post"."title")) AS "posts"
   FROM "post"
   WHERE "user"."id" = "post"."userId"
-) AS "posts_lateral" ON true
+) AS "posts"
+FROM "user"
 ```
 
+> LATERAL emission is retained in the renderer (and the `lateral` capability stays advertised) for the public SQL-builder `lateralJoin()` DSL; the ORM include path no longer uses it.
+
 ## DML Operations with RETURNING
 
 The adapter supports RETURNING clauses for DML operations (INSERT, UPDATE, DELETE), allowing you to return affected rows:

packages/3-targets/6-adapters/postgres/README.md

@@ -20,7 +20,7 @@ Provide SQLite-specific adapter implementation, codecs, and capabilities. Enable
 
 - **Adapter Implementation**: Implement `Adapter` SPI for SQLite
   - Lower SQL ASTs to SQLite dialect SQL
-  - Render `includeMany` as correlated subquery with `json_group_array(json_object(...))` for nested array includes
+  - Render `.include(...)` as correlated subquery with `json_group_array(json_object(...))` for nested array includes
   - Advertise SQLite capabilities (`jsonAgg`, `returning`; no `lateral`, no `enums`)
   - Provide target-specific marker SQL via `readMarkerStatement()` on `AdapterProfile`
   - Map SQLite errors to `RuntimeError` envelope
@@ -91,7 +91,7 @@ flowchart TD
 - Main adapter implementation
 - Lowers SQL ASTs to SQLite SQL with `?` positional parameters
 - Renders joins (INNER, LEFT, RIGHT, FULL) with ON conditions
-- Renders `includeMany` as correlated subquery with `json_group_array(json_object(...))` for nested array includes
+- Renders `.include(...)` as correlated subquery with `json_group_array(json_object(...))` for nested array includes
 - Renders DML operations (INSERT, UPDATE, DELETE) with RETURNING clauses
 - Renders ON CONFLICT (DO NOTHING / DO UPDATE SET) for upserts
 - Uses `CAST(expr AS type)` instead of Postgres `::type` syntax
@@ -148,17 +148,17 @@ The adapter declares the following SQLite capabilities:
 
 - **`sql.orderBy: true`** -- Supports ORDER BY clauses
 - **`sql.limit: true`** -- Supports LIMIT clauses
-- **`sql.lateral: false`** -- No LATERAL join support; `includeMany` uses correlated subquery fallback
-- **`sql.jsonAgg: true`** -- Supports JSON aggregation via `json_group_array()` for `includeMany`
+- **`sql.lateral: false`** -- No LATERAL join support; `.include(...)` uses correlated subqueries
+- **`sql.jsonAgg: true`** -- Supports JSON aggregation via `json_group_array()` for `.include(...)`
 - **`sql.returning: true`** -- Supports RETURNING clauses for DML operations (SQLite 3.35+)
 - **`sql.enums: false`** -- No native enum support
 
-## includeMany Support
+## Include Support
 
-The adapter supports `includeMany` for nested array includes using SQLite's `json_group_array()` and `json_object()`:
+The adapter lowers `.include(...)` for nested array includes using SQLite's `json_group_array()` and `json_object()`:
 
 **Lowering Strategy:**
-- Renders `includeMany` as a correlated subquery with `json_group_array(json_object(...))` to aggregate child rows into a JSON array
+- Renders `.include(...)` as a correlated subquery with `json_group_array(json_object(...))` to aggregate child rows into a JSON array
 - Uses `COALESCE(..., '[]')` to handle empty results
 
 **Example SQL Output:**

packages/3-targets/6-adapters/sqlite/README.md

@@ -314,7 +314,7 @@ The callback's return value passes through `db.transaction(...)`. Capture insert
 5. **Importing `and` / `or` / `not` from a Postgres façade subpath.** The combinators currently live in `@prisma-next/sql-orm-client` — an internal package. See *What Prisma Next doesn't do yet* in [`SKILL.md`](./SKILL.md).
 6. **Trying to `db.sql.from(tables.user)`.** That surface does not exist. The builder is table-shaped: `db.sql.<tableName>.select(...)`. There is no `db.schema.tables` either.
 7. **Trying to `db.execute(plan)` directly.** Plans execute through the runtime: `db.runtime().execute(plan)`. Inside a transaction, use `tx.execute(plan)`.
-8. **Setting `capabilities: { includeMany: true }` in `prisma-next.config.ts`.** `defineConfig` does not take `capabilities`. Capabilities are declared by the active adapter and become part of the emitted contract; the Postgres adapter advertises `lateral`, `jsonAgg`, and `returning` out of the box. Enable extension capabilities through `extensions: [...]` in the config (see `prisma-next-contract`).
+8. **Setting `capabilities: { lateral: true }` in `prisma-next.config.ts`.** `defineConfig` does not take `capabilities`. Capabilities are declared by the active adapter and become part of the emitted contract; the Postgres adapter advertises `lateral`, `jsonAgg`, and `returning` out of the box. Enable extension capabilities through `extensions: [...]` in the config (see `prisma-next-contract`).
 9. **Confabulating a `db.sql.raw(...)`, TypedSQL, or `.stream()` surface.** None of those exist today. See *What Prisma Next doesn't do yet* in [`SKILL.md`](./SKILL.md).
 10. **Mixing the ORM mutation return with `runtime.execute(plan)`.** ORM terminals issue the query themselves and return rows. `runtime.execute` is for SQL-builder plans.
 11. **Top-N grouped queries written as `groupBy(...).aggregate(...).sort().slice()` in JS.** That's a fallback because the grouped collection doesn't expose `.orderBy(...)` / `.take(...)`. Fine at small cardinalities; for large grouped result sets, drop to `db.sql.<table>`.

skills/prisma-next-queries/postgres.md

@@ -171,7 +171,7 @@ describe('e2e: ORM on SQLite', { timeout: timeouts.databaseOperation }, () => {
     });
   });
 
-  describe('includeMany', () => {
+  describe('include', () => {
     it('loads 1:N relation via json_group_array', async () => {
       await withSqliteTestRuntime<Contract>(contractJsonPath, async ({ ormClient }) => {
         const users = await ormClient.User.where((u) => u.id.eq(1))