refactor(sql-orm): address PR review — AST-level adapter docs, leaner nested-include helper

- Rename `buildNestedIncludeArtifacts` -> `buildNestedIncludeProjections` and
  return the projection array directly instead of wrapping it in an object.
- Postgres/SQLite READMEs: describe what the adapter actually renders at the
  AST level (JSON aggregation functions, scalar subqueries, LATERAL joins) and
  drop all references to `.include(...)`, lanes, and the ORM client — the
  adapter does not know which lane produced the AST.
- include.test.ts: drop transient ticket IDs from test names/comments.
- nested-includes-strategy.test.ts: assert `ast.joins` is exactly `[]`
  (strictly stronger than "no lateral join") in the lateral-flag-inert guard.

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

Author: tensordreams

packages/3-extensions/sql-orm-client/src/query-plan-select.ts

@@ -271,25 +271,21 @@ function wrapWithRowNumberDedup(options: {
 }
 
 /**
- * Recursively build the projection artifacts for the nested includes
- * attached to a child SELECT. Used by `buildIncludeChildRowsSelect` to
- * wire depth-2+ aggregates into the inner SELECT at each level.
+ * Recursively build the correlated-subquery projections for the nested
+ * includes attached to a child SELECT. Used by `buildIncludeChildRowsSelect`
+ * to wire depth-2+ aggregates into the inner SELECT at each level.
  *
  * Each nested include contributes a single projection item whose
- * expression is a correlated subquery; no joins are produced.
+ * expression is a correlated subquery.
  */
-function buildNestedIncludeArtifacts(
+function buildNestedIncludeProjections(
   contract: Contract<SqlStorage>,
   parentTableRef: string,
   includes: readonly IncludeExpr[],
-): {
-  readonly projections: ReadonlyArray<ProjectionItem>;
-} {
-  const projections = includes.map(
+): ReadonlyArray<ProjectionItem> {
+  return includes.map(
     (nested) => buildCorrelatedIncludeProjection(contract, parentTableRef, nested).projection,
   );
-
-  return { projections };
 }
 
 function buildIncludeChildRowsSelect(
@@ -373,7 +369,7 @@ function buildIncludeChildRowsSelect(
   // projection. The nested aggregates are attached to *this* child
   // SELECT, so they correlate against `childTableRef` — which may itself
   // be an alias if the relation is self-referential.
-  const { projections: nestedProjections } = buildNestedIncludeArtifacts(
+  const nestedProjections = buildNestedIncludeProjections(
     contract,
     childTableRef,
     childState.includes,
@@ -564,7 +560,7 @@ function buildDistinctNonLeafChildRowsSelect(options: {
     childState.selectedFields,
     distinctAlias,
   );
-  const { projections: outerNestedProjections } = buildNestedIncludeArtifacts(
+  const outerNestedProjections = buildNestedIncludeProjections(
     contract,
     distinctAlias,
     childState.includes,

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

@@ -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 `.include(...)` as a correlated subquery with `json_agg` for nested array includes
+  - Render JSON aggregation (`json_agg`, `json_build_object`) and scalar subqueries
   - Advertise PostgreSQL capabilities (`lateral`, `jsonAgg`)
   - Normalize PostgreSQL EXPLAIN output
   - Map PostgreSQL errors to `RuntimeError` envelope
@@ -89,8 +89,8 @@ flowchart TD
 **Adapter (`adapter.ts`)**
 - Main adapter implementation
 - Lowers SQL ASTs to PostgreSQL SQL
-- Renders joins (INNER, LEFT, RIGHT, FULL) with ON conditions
-- Renders `.include(...)` as a correlated subquery with `json_agg` for nested array includes
+- Renders joins (INNER, LEFT, RIGHT, FULL, LATERAL) with ON conditions
+- Renders JSON aggregation (`json_agg`, `json_build_object`) and scalar subqueries
 - 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 (used by the SQL-builder `lateralJoin()` DSL)
-- **`jsonAgg: true`** - Supports JSON aggregation functions (`json_agg`) used to lower `.include(...)` to correlated subqueries
+- **`lateral: true`** - Supports LATERAL joins
+- **`jsonAgg: true`** - Supports JSON aggregation functions (`json_agg`)
 - **`returning: true`** - Supports RETURNING clauses for DML operations (INSERT, UPDATE, DELETE)
 - **`sql.enums: true`** - Supports contract-defined enum storage types
 
@@ -205,17 +205,13 @@ 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.
 
-## Include Support
+## JSON Aggregation
 
-The adapter lowers `.include(...)` for nested array includes to a correlated subquery in the SELECT list, using `json_agg`:
+The renderer lowers JSON-aggregation AST nodes to PostgreSQL's `json_agg`:
 
-**Lowering Strategy:**
-- 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:**
-- `jsonAgg: true` - Enables `json_agg` function support
+- `json_agg(json_build_object(...))` aggregates a row set into a JSON array of objects
+- A scalar subquery (`SubqueryExpr`) in the SELECT list correlates against the outer row through its WHERE clause
+- When the subquery carries an inner `ORDER BY` and `LIMIT`, its rows are wrapped in an inner SELECT, then aggregated with `json_agg(row_to_json(sub.*))`
 
 **Example SQL Output:**
 ```sql
@@ -227,8 +223,6 @@ SELECT "user"."id" AS "id", (
 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/sqlite/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 `.include(...)` as correlated subquery with `json_group_array(json_object(...))` for nested array includes
+  - Render JSON aggregation (`json_group_array`, `json_object`) and scalar subqueries
   - 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 `.include(...)` as correlated subquery with `json_group_array(json_object(...))` for nested array includes
+- Renders JSON aggregation (`json_group_array`, `json_object`) and scalar subqueries
 - 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,18 +148,18 @@ 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; `.include(...)` uses correlated subqueries
-- **`sql.jsonAgg: true`** -- Supports JSON aggregation via `json_group_array()` for `.include(...)`
+- **`sql.lateral: false`** -- No LATERAL join support
+- **`sql.jsonAgg: true`** -- Supports JSON aggregation via `json_group_array()`
 - **`sql.returning: true`** -- Supports RETURNING clauses for DML operations (SQLite 3.35+)
 - **`sql.enums: false`** -- No native enum support
 
-## Include Support
+## JSON Aggregation
 
-The adapter lowers `.include(...)` for nested array includes using SQLite's `json_group_array()` and `json_object()`:
+The renderer lowers JSON-aggregation AST nodes using SQLite's `json_group_array()` and `json_object()`:
 
-**Lowering Strategy:**
-- 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
+- `json_group_array(json_object(...))` inside a scalar subquery aggregates a row set into a JSON array of objects
+- The scalar subquery correlates against the outer row through its WHERE clause
+- `COALESCE(..., '[]')` yields an empty array when the row set is empty
 
 **Example SQL Output:**
 ```sql

test/integration/test/sql-orm-client/include.test.ts

@@ -420,13 +420,13 @@ describe('integration/include', () => {
     timeouts.spinUpPpgDev,
   );
 
-  // TML-2595 worked example: the Pothos `totalCount` shape — a paginated
-  // row branch alongside a count() scalar branch. This is the headline
-  // case that motivated single-query combine emission: one correlated
+  // Worked example: the Pothos `totalCount` shape — a paginated row
+  // branch alongside a count() scalar branch. This is the headline case
+  // that motivated single-query combine emission: one correlated
   // subquery packs both branches; the parent + count + page roll up to
   // one SQL execution per query.
   it(
-    'TML-2595: include().combine({ recent: take(N), count: count() }) resolves in a single execution',
+    'include().combine({ recent: take(N), count: count() }) resolves in a single execution',
     async () => {
       await withCollectionRuntime(async (runtime) => {
         const users = createUsersCollection(runtime);
@@ -928,9 +928,8 @@ describe('integration/include', () => {
             ],
           },
         ]);
-        // TML-2594 acceptance: depth-2 on the default postgres test
-        // contract must collapse to a single SQL execution via nested
-        // correlated subqueries.
+        // Depth-2 on the default postgres test contract must collapse to
+        // a single SQL execution via nested correlated subqueries.
         expect(runtime.executions).toHaveLength(1);
       });
     },

test/integration/test/sql-orm-client/nested-includes-strategy.test.ts

@@ -141,9 +141,9 @@ describe('integration/nested-includes/strategy', () => {
           const ast = execution?.ast;
           expect(isSelectAst(ast)).toBe(true);
           if (!isSelectAst(ast)) return;
-          // No include join is emitted; the include rides on a
-          // SubqueryExpr projection instead.
-          expect((ast.joins ?? []).some((join) => join.lateral)).toBe(false);
+          // No join at all is emitted (a fortiori no lateral join); the
+          // include rides on a `SubqueryExpr` projection instead.
+          expect(ast.joins ?? []).toEqual([]);
           expect(ast.projection.some((item) => item.alias === 'posts')).toBe(true);
           // The lowered SQL carries no LATERAL keyword either.
           expect(execution?.sql).not.toContain('LATERAL');