@prisma/orm-mongo 8.0.0-rc.9-dev.7 → 8.0.0-rc.9-dev.9

package/skills/prisma-8/references/queries-postgres.md

@@ -8,8 +8,8 @@ Shared concepts (result consumption, script teardown, cross-target pitfalls, cap
 
 **Postgres** (`postgres<Contract>(...)` from `@internal/postgres/runtime`):
 
-- **`db.orm.<Model>`** — ORM, PascalCase model name (`db.orm.User`). Fluent `.where(...).select(...).orderBy(...).all()`, fully typed against `Contract`. Default lane for CRUD with relations.
-- **`db.sql.<table>`** — SQL builder, lowercase storage name (`db.sql.user`). Produces a *plan* executed via `db.runtime().execute(plan)`. Use when the ORM is too high-level — explicit `JOIN`, computed projections, set operations, window functions.
+- **`db.orm.<ns>.<Model>`** — ORM, PascalCase model name (`db.orm.public.User`). Fluent `.where(...).select(...).orderBy(...).all()`, fully typed against `Contract`. Default lane for CRUD with relations.
+- **`db.sql.<ns>.<table>`** — SQL builder, lowercase storage name (`db.sql.public.user`). Produces a *plan*. A plan that returns rows (`select`, or a write with `.returning(...)`) runs through `db.runtime().query(plan)`; a write with no `RETURNING` runs through `db.runtime().execute(plan)`, which resolves `{ affectedRows }`. Use when the ORM is too high-level — explicit `JOIN`, computed projections, set operations, window functions.
 
 Reach for the ORM first; drop to `db.sql` when the ORM can't express the shape. Lane choice is local — one query function picks one lane, not the whole app.
 
@@ -17,33 +17,33 @@ Reach for the ORM first; drop to `db.sql` when the ORM can't express the shape.
 
 | Need | Choose | Why |
 | --- | --- | --- |
-| Standard CRUD with relations | **ORM (`db.orm.<Model>`)** | Highest ergonomics; fully typed; model-shaped. |
+| Standard CRUD with relations | **ORM (`db.orm.<ns>.<Model>`)** | Highest ergonomics; fully typed; model-shaped. |
 | Eager-load related records | **ORM `.include(...)`** | Composes with `.where` / `.select` / `.orderBy` / `.limit` per branch. |
 | Aggregate (count, sum, avg) | **ORM `.aggregate(...)`** | Typed result; works with grouping (`.groupBy(...).aggregate(...)`). |
-| `INSERT ... RETURNING` / `UPDATE ... RETURNING` typed result | **ORM mutations** (returns updated rows) or **`db.sql.<t>.insert(...).returning(...)`** | ORM returns inserted/updated rows; SQL builder exposes `.returning(...)` explicitly. |
-| Computed projection (e.g. `ST_DistanceSphere(location, point) AS meters`) alongside model fields | **SQL builder (`db.sql.<t>`)** | The ORM projects model fields; arbitrary expression projection is the SQL builder's seam. |
+| `INSERT ... RETURNING` / `UPDATE ... RETURNING` typed result | **ORM mutations** (returns updated rows) or **`db.sql.<ns>.<t>.insert(...).returning(...)`** | ORM returns inserted/updated rows; SQL builder exposes `.returning(...)` explicitly. |
+| Computed projection (e.g. `ST_DistanceSphere(location, point) AS meters`) alongside model fields | **SQL builder (`db.sql.<ns>.<t>`)** | The ORM projects model fields; arbitrary expression projection is the SQL builder's seam. |
 | Complex `JOIN`, set operation, window function | **SQL builder** | The ORM doesn't express arbitrary joins. |
-| Postgres-specific feature (`LATERAL`, `FILTER`, custom aggregates) | **SQL builder**, falling back to extension operators when the extension provides them | DSL first; extensions can contribute operators (`postgis`, `pgvector`, `cipherstash`). |
+| Postgres-specific feature (`LATERAL`, `FILTER`, custom aggregates) | **SQL builder**, falling back to extension operators when the extension provides them | DSL first; extensions can contribute operators (`postgis`, `pgvector`). |
 
 ## Workflow — ORM reads
 
-The concept: `db.orm.<Model>` returns a *collection* you compose method-by-method. Each call returns a new collection (immutable chaining); the terminal verb (`.all()` / `.first()` / `.count()` / `.aggregate(...)`) issues the query. Predicates are lambdas over a field proxy: `u.field.<op>(value)`.
+The concept: `db.orm.<ns>.<Model>` returns a *collection* you compose method-by-method. Each call returns a new collection (immutable chaining); the terminal verb (`.all()` / `.first()` / `.aggregate(...)`) issues the query. There is no `.count()` terminal on the collection — `count()` is an `include` reducer and an `aggregate(...)` operation (both below). Predicates are lambdas over a field proxy: `u.field.<op>(value)`.
 
 ```typescript
 // src/queries/users.ts — one directory deep under src/, so the import is '../prisma/db'
 import { db } from '../prisma/db';
 
 // Find one record by primary key shorthand.
-const user = await db.orm.User.first({ id: userId });
+const user = await db.orm.public.User.first({ id: userId });
 // Returns the full row or `null`.
 
 // Find one matching a predicate.
-const alice = await db.orm.User
+const alice = await db.orm.public.User
   .where((u) => u.email.eq('alice@example.com'))
   .first();
 
 // Find many with projection, sort, and limit.
-const recentUsers = await db.orm.User
+const recentUsers = await db.orm.public.User
   .select('id', 'email', 'createdAt')
   .orderBy((u) => u.createdAt.desc())
   .limit(10)
@@ -54,38 +54,38 @@ const recentUsers = await db.orm.User
 
 ```typescript
 // Lambda form — full expression power.
-db.orm.User.where((u) => u.email.eq('alice@example.com'));
+db.orm.public.User.where((u) => u.email.eq('alice@example.com'));
 
 // Shorthand object form — equality on the named fields.
-db.orm.User.where({ kind: 'admin' });
+db.orm.public.User.where({ kind: 'admin' });
 ```
 
-Operators on the field proxy include `.eq`, `.neq`, `.lt`, `.lte`, `.gt`, `.gte`, `.like`, `.ilike`, `.in([...])`, `.isNull()`, `.isNotNull()`. Extensions add target-specific operators on extension-typed columns (`pgvector`'s `.cosineDistance(...)`, `postgis`'s `.within(...)` / `.intersectsBbox(...)` / `.distanceSphere(...)`, `cipherstash`'s `.cipherstashEq(...)` / `.cipherstashGt(...)` / …).
+Operators on the field proxy include `.eq`, `.neq`, `.lt`, `.lte`, `.gt`, `.gte`, `.like`, `.ilike`, `.in([...])`, `.isNull()`, `.isNotNull()`. Extensions add target-specific operators on extension-typed columns (`pgvector`'s `.cosineDistance(...)`, `postgis`'s `.within(...)` / `.intersectsBbox(...)` / `.distanceSphere(...)`).
 
 **There is no `.between(a, b)` operator.** Express ranges either as two chained `.where(...)` clauses (the idiomatic form — clauses AND-compose) or with the `and(...)` combinator inside one clause:
 
 ```typescript
 // Chained .where() — each clause AND-composes with the previous one.
-await db.orm.Sale
+await db.orm.public.Sale
   .where((s) => s.day.gte(start))
   .where((s) => s.day.lte(end))
   .all();
 
 // Equivalent with an explicit `and(...)` inside one clause.
-import { and } from '@internal/sql-orm-client'; // façade re-export pending — see *What PN doesn't do yet* in queries.md
-await db.orm.Sale
+import { and } from '@prisma/orm-postgres/orm-client';
+await db.orm.public.Sale
   .where((s) => and(s.day.gte(start), s.day.lte(end)))
   .all();
 ```
 
 The two forms emit the same SQL. Pick chained `.where()` when each clause adds a separate condition that reads as its own thought; pick `and(...)` when one logical predicate happens to have two parts and you want the visual grouping. Don't reach for a `between` helper — there isn't one.
 
-**Combinators** (`and`, `or`, `not`) compose predicates, and **relation predicates** (`.some(...)`, `.none(...)`, `.every(...)`) recurse into a relation. These currently come from the internal `@internal/sql-orm-client` package — see *What Prisma 8 doesn't do yet* in [`queries.md`](./queries.md):
+**Combinators** (`and`, `or`, `not`) compose predicates, and **relation predicates** (`.some(...)`, `.none(...)`, `.every(...)`) recurse into a relation. The combinators are exported from the façade's `orm-client` subpath:
 
 ```typescript
-import { and, or, not } from '@internal/sql-orm-client';
+import { and, or, not } from '@prisma/orm-postgres/orm-client';
 
-await db.orm.User
+await db.orm.public.User
   .where((u) =>
     and(
       or(u.kind.eq('admin'), u.email.ilike('%@example.com')),
@@ -98,7 +98,7 @@ await db.orm.User
 **Sorting and pagination.** `.orderBy(...)` accepts a single lambda or an array of lambdas (each calling `.asc()` / `.desc()` on a field). `.limit(n)` limits; `.offset(n)` offsets.
 
 ```typescript
-await db.orm.Post
+await db.orm.public.Post
   .where((p) => p.authorId.eq(userId))
   .orderBy([(p) => p.createdAt.desc(), (p) => p.id.desc()])
   .limit(20)
@@ -108,13 +108,13 @@ await db.orm.Post
 **Cursor pagination.** Call `.cursor({ field: lastValue })` after `.orderBy(...)` to resume from a known position. The cursor requires a prior `orderBy` — the type system enforces this. Direction (forward or backward) follows the sort: ascending order means "greater than the cursor value", descending means "less than".
 
 ```typescript
-const page1 = await db.orm.Post
+const page1 = await db.orm.public.Post
   .orderBy((p) => p.createdAt.desc())
   .limit(20)
   .all();
 
 const last = page1[page1.length - 1]!;
-const page2 = await db.orm.Post
+const page2 = await db.orm.public.Post
   .orderBy((p) => p.createdAt.desc())
   .cursor({ createdAt: last.createdAt })
   .limit(20)
@@ -130,7 +130,7 @@ Cursor keys must match fields in the active `orderBy`. For a composite `orderBy`
 The concept: `.include('<relation>', (branch) => branch.<chain>)` adds a relation branch to the parent query. The branch is its own collection — compose `.where` / `.select` / `.orderBy` / `.limit` on it just like the parent.
 
 ```typescript
-await db.orm.User
+await db.orm.public.User
   .select('id', 'email')
   .include('posts', (post) =>
     post
@@ -146,25 +146,25 @@ await db.orm.User
 **Reduce a to-many relation to a scalar.** A refinement callback may return a *reducer* — `count()`, `sum(field)`, `avg(field)`, `min(field)`, `max(field)`, plus the lossless `countBigInt()`, `sumBigInt(field)`, and `avgDecimal(field)` — instead of a collection. The parent's relation field then carries that one value rather than an array. Reducers exist only inside an `include(...)` callback; calling one elsewhere throws.
 
 ```typescript
-await db.orm.User.include('posts', (posts) => posts.count()).all();
+await db.orm.public.User.include('posts', (posts) => posts.count()).all();
 // → Array<{ ...user, posts: number }> — a parent with no posts reads 0
 
-await db.orm.User.include('posts', (posts) => posts.sum('views')).all();
+await db.orm.public.User.include('posts', (posts) => posts.sum('views')).all();
 // → Array<{ ...user, posts: number | null }>
 
-await db.orm.User.include('posts', (posts) => posts.avg('views')).all();
+await db.orm.public.User.include('posts', (posts) => posts.avg('views')).all();
 // → Array<{ ...user, posts: number | null }>
 
-await db.orm.User.include('posts', (posts) => posts.min('views')).all();
-await db.orm.User.include('posts', (posts) => posts.max('views')).all();
+await db.orm.public.User.include('posts', (posts) => posts.min('views')).all();
+await db.orm.public.User.include('posts', (posts) => posts.max('views')).all();
 // → Array<{ ...user, posts: number | null }>
 
 // The lossless form, for a total that may outgrow a JS number:
-await db.orm.User.include('posts', (posts) => posts.sumBigInt('views')).all();
+await db.orm.public.User.include('posts', (posts) => posts.sumBigInt('views')).all();
 // → Array<{ ...user, posts: bigint | null }>
 
 // Several sub-views of one relation at once:
-await db.orm.User.include('posts', (posts) =>
+await db.orm.public.User.include('posts', (posts) =>
   posts.combine({ recent: posts.limit(3), total: posts.count() }),
 ).all();
 // → Array<{ ...user, posts: { recent: Post[]; total: number } }>
@@ -178,27 +178,27 @@ Nested `1:N → 1:N` includes (e.g. `User → posts → comments`) require the c
 
 ```typescript
 // Create — returns the inserted row.
-const user = await db.orm.User.create({ id, email, displayName, kind, createdAt });
+const user = await db.orm.public.User.create({ id, email, displayName, kind, createdAt });
 
 // Create with selected return — narrows the return shape.
-const summary = await db.orm.User
+const summary = await db.orm.public.User
   .select('id', 'email', 'kind')
   .create({ id, email, displayName, kind, createdAt });
 
 // Update by predicate.
-await db.orm.User.where({ id }).update({ email: newEmail });
+await db.orm.public.User.where({ id }).update({ email: newEmail });
 
 // Update with selected return.
-await db.orm.User
+await db.orm.public.User
   .where({ id })
   .select('id', 'email', 'kind')
   .update({ email: newEmail });
 
 // Delete by predicate.
-await db.orm.User.where({ id }).delete();
+await db.orm.public.User.where({ id }).delete();
 
 // Upsert — typed by the create branch's shape.
-await db.orm.User
+await db.orm.public.User
   .select('id', 'email', 'kind', 'createdAt')
   .upsert({
     create: { id, email, displayName, kind, createdAt: new Date() },
@@ -211,18 +211,18 @@ The ORM returns inserted / updated rows by default. The `.returning(...)` select
 ## Workflow — Aggregates
 
 ```typescript
-const totals = await db.orm.User.aggregate((aggregate) => ({
+const totals = await db.orm.public.User.aggregate((aggregate) => ({
   totalUsers: aggregate.count(),
 }));
 
-const adminTotals = await db.orm.User
+const adminTotals = await db.orm.public.User
   .where({ kind: 'admin' })
   .aggregate((aggregate) => ({
     adminUsers: aggregate.count(),
   }));
 
 // Group-by + aggregate.
-const byKind = await db.orm.User
+const byKind = await db.orm.public.User
   .groupBy('kind')
   .having((having) => having.count().gte(minUsers))
   .aggregate((aggregate) => ({
@@ -261,7 +261,7 @@ const byKind = await db.orm.User
 Nullability isn't a typing bug — it's faithful to what the database returns. Coalesce client-side when you want zero-fill:
 
 ```typescript
-const revenue = await db.orm.Sale
+const revenue = await db.orm.public.Sale
   .where((s) => s.day.gte(start))
   .aggregate((a) => ({ total: a.sum('amount') }));
 // revenue.total: number | null
@@ -271,22 +271,22 @@ const safe = revenue.total ?? 0;   // ← apply at the consumption site, not in
 
 If `?? 0` is showing up on every aggregate, that's a signal you're calling `sum` (or peers) over potentially-empty filters — which is exactly when SQL returns NULL. The pattern is correct; the typing is honest.
 
-## Workflow — SQL builder (`db.sql.<table>`)
+## Workflow — SQL builder (`db.sql.<ns>.<table>`)
 
-The concept: `db.sql.<table>` is a table-shaped builder that produces a *plan*. The plan is a serialisable description of the query (AST + parameters); you execute it through the runtime with `db.runtime().execute(plan)`. The builder gives you the lanes the ORM doesn't express — explicit `JOIN`, arbitrary expression projection, target-specific operations through extension helpers — without dropping to raw SQL.
+The concept: `db.sql.<ns>.<table>` is a table-shaped builder that produces a *plan*. The plan is a serialisable description of the query (AST + parameters); you run it through the runtime. Pick the runtime method by the result the plan declares: `db.runtime().query(plan)` for rows (it returns the same `AsyncIterableResult` as `.all()`, so `await` it for an array), `db.runtime().execute(plan)` for a write with no `RETURNING` (it resolves `{ affectedRows }` and returns no rows). The builder gives you the lanes the ORM doesn't express — explicit `JOIN`, arbitrary expression projection, target-specific operations through extension helpers — without dropping to raw SQL.
 
 ```typescript
 // src/queries/posts.ts — adjust the relative import to match file depth.
 import { db } from '../prisma/db';
 
 // Select with predicate and limit.
-const plan = db.sql.post
+const plan = db.sql.public.post
   .select('id', 'title', 'userId', 'createdAt')
   .where((f, fns) => fns.eq(f.userId, userId))
   .limit(limit)
   .build();
 
-const rows = await db.runtime().execute(plan);
+const rows = await db.runtime().query(plan);
 ```
 
 The `.where(...)` callback receives `(fields, fns)` — `fields` is the field proxy (column references), `fns` is the operator namespace (`fns.eq`, `fns.ne`, `fns.gt`, …). Extensions inject extension-shaped helpers into the same `fns` namespace (`fns.distanceSphere`, `fns.cosineDistance`, etc.).
@@ -294,27 +294,27 @@ The `.where(...)` callback receives `(fields, fns)` — `fields` is the field pr
 ### `INSERT` / `UPDATE` / `DELETE` with `RETURNING`
 
 ```typescript
-// Insert and return selected columns.
-const plan = db.sql.user
-  .insert({ email })
+// Insert and return selected columns. `insert()` takes an array of rows.
+const plan = db.sql.public.user
+  .insert([{ email }])
   .returning('id', 'email')
   .build();
-const [row] = await db.runtime().execute(plan);
+const [row] = await db.runtime().query(plan);
 
 // Update with predicate and returning.
-const updatePlan = db.sql.user
+const updatePlan = db.sql.public.user
   .update({ email: newEmail })
   .where((f, fns) => fns.eq(f.id, userId))
   .returning('id', 'email')
   .build();
-const rows = await db.runtime().execute(updatePlan);
+const rows = await db.runtime().query(updatePlan);
 
-// Delete with predicate.
-const deletePlan = db.sql.user
+// Delete with predicate, no RETURNING — `execute` resolves the affected count.
+const deletePlan = db.sql.public.user
   .delete()
   .where((f, fns) => fns.eq(f.id, userId))
   .build();
-await db.runtime().execute(deletePlan);
+const { affectedRows } = await db.runtime().execute(deletePlan);
 ```
 
 `.returning(...)` requires the target adapter to advertise the `returning` capability. The Postgres adapter advertises it by default.
@@ -323,36 +323,36 @@ await db.runtime().execute(deletePlan);
 
 ```typescript
 // Project a computed expression alongside model fields.
-const plan = db.sql.cafe
+const plan = db.sql.public.cafe
   .select('id', 'name')
   .select('meters', (f, fns) => fns.distanceSphere(f.location, point))
   .orderBy((f, fns) => fns.distanceSphere(f.location, point), { direction: 'asc' })
   .orderBy((f) => f.id, { direction: 'asc' })
   .limit(limit)
   .build();
-const rows = await db.runtime().execute(plan);
+const rows = await db.runtime().query(plan);
 
 // Self-join with an alias.
-db.sql.post
-  .innerJoin(db.sql.post.as('p2'), (f, fns) => fns.ne(f.p1.userId, f.p2.userId))
+db.sql.public.post
+  .innerJoin(db.sql.public.post.as('p2'), (f, fns) => fns.ne(f.p1.userId, f.p2.userId))
   // ...
   .build();
 ```
 
 ## Workflow — Transactions
 
-The concept: `db.transaction(fn)` opens a transaction and passes a `tx` context to the callback. `tx.orm` and `tx.sql` mirror `db.orm` / `db.sql` but ride the same transaction; `tx.execute(plan)` executes a SQL-builder plan within it. The transaction commits on the callback's successful return and rolls back on any thrown error.
+The concept: `db.transaction(fn)` opens a transaction and passes a `tx` context to the callback. `tx.orm` and `tx.sql` mirror `db.orm` / `db.sql` but ride the same transaction; `tx.query(plan)` / `tx.execute(plan)` run a SQL-builder plan within it (rows vs affected count, as on the runtime). The transaction commits on the callback's successful return and rolls back on any thrown error.
 
 ```typescript
 await db.transaction(async (tx) => {
-  const user = await tx.orm.User.create({ id, email });
-  await tx.orm.Post.create({ userId: user.id, title: 'hello' });
+  const user = await tx.orm.public.User.create({ id, email });
+  await tx.orm.public.Post.create({ userId: user.id, title: 'hello' });
 
-  // SQL-builder plan inside the transaction.
-  const plan = tx.sql.post.update({ status: 'archived' })
+  // SQL-builder plan inside the transaction — no RETURNING, so `execute`.
+  const plan = tx.sql.public.post.update({ status: 'archived' })
     .where((f, fns) => fns.lt(f.createdAt, cutoff))
     .build();
-  await tx.execute(plan);
+  const { affectedRows } = await tx.execute(plan);
 
   // If anything throws, all three operations roll back.
 });
@@ -362,20 +362,20 @@ The callback's return value passes through `db.transaction(...)`. Capture insert
 
 ## Namespace-aware accessors
 
-When the contract declares multiple namespaces, both `db.sql` and `db.orm` expose a namespace coordinate alongside the flat bare-name surface:
+On Postgres both `db.sql` and `db.orm` are keyed by storage namespace (the Postgres schema) — always, not only when a contract declares more than one. A model outside any `namespace { }` block is in `public`:
 
 ```typescript
 // db.sql.<namespace>.<table>
-const plan = db.sql.public.users.select('id', 'email').build();
+const plan = db.sql.public.user.select('id', 'email').build();
 const authPlan = db.sql.auth.users.select('id', 'token').build();
-await db.runtime().execute(plan);
+const rows = await db.runtime().query(plan);
 
 // db.orm.<namespace>.<Model>
 const user = await db.orm.public.User.create({ id: 1, email: 'a@x.io' });
 const authUser = await db.orm.auth.User.create({ id: 2, token: 'tok' });
 ```
 
-The flat `db.sql.users` / `db.orm.User` form still works when bare names are unique across all namespaces. When the same bare name appears in more than one namespace, use the coordinate form — both the type system and the runtime require it to resolve to the right table.
+There is no flat `db.sql.user` / `db.orm.User` on the Postgres façade (`Db` is "one facet per storage namespace, and nothing else"); reaching for one is a type error. The flat spelling belongs to SQLite, whose façade exposes its single unbound namespace directly — see `references/queries.md` § *Namespace-aware accessors*.
 
 Cross-namespace relations (e.g. `public.Profile` → `auth.User`) follow the same `.include()` syntax; the ORM resolves the correct schema-qualified join automatically.
 
@@ -385,13 +385,13 @@ Cross-namespace relations (e.g. `public.Profile` → `auth.User`) follow the sam
 2. **Using `.all()` when you wanted one row.** `.all()` issues no implicit limit. Use `.first()` or `.first({ pk })`.
 3. **Coalescing `count()` with `?? 0` "just in case".** `count()` is `number`, not `number | null` — SQL answers an empty set with `0`. The `?? 0` belongs on `sum` / `avg` / `min` / `max`, and its zero should match the aggregate's own type (`0` for an integer sum, `0n` for `sumBigInt`, `'0'` where the result is a decimal string).
 4. **Reaching for `.between(a, b)` on a field proxy.** It doesn't exist. Either chain `.where((m) => m.field.gte(a)).where((m) => m.field.lte(b))` or use `and(m.field.gte(a), m.field.lte(b))` inside one `.where()` clause.
-5. **Importing `and` / `or` / `not` from a Postgres façade subpath.** The combinators currently live in `@internal/sql-orm-client` — an internal package. See *What Prisma 8 doesn't do yet* in [`queries.md`](./queries.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: { lateral: true }` in `prisma.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 `references/contract.md`).
-9. **Confabulating a TypedSQL or `.stream()` surface.** Neither exists today. Raw SQL does: the client's raw lane, ``db.raw.sql`…` ``. See *What Prisma 8 doesn't do yet* in [`queries.md`](./queries.md) for all three.
-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. **Ordering grouped rows by an aggregate metric.** The grouped collection supports `.orderBy(...)` on group keys plus `.limit(...)` / `.offset(...)`, but it cannot order by an aggregate alias such as `SUM(amount)`. Sorting the materialized aggregate result in JS is fine at small cardinalities; for large grouped result sets, drop to `db.sql.<table>`.
+5. **Importing `and` / `or` / `not` from an internal package.** They are exported from `@prisma/orm-postgres/orm-client`; do not reach into `@internal/sql-orm-client`.
+6. **Trying to `db.sql.from(tables.user)`.** That surface does not exist. The builder is table-shaped: `db.sql.<ns>.<tableName>.select(...)`. There is no `db.schema.tables` either.
+7. **Trying to `db.execute(plan)` directly, or reading rows with `execute`.** Plans run through the runtime: `db.runtime().query(plan)` for rows, `db.runtime().execute(plan)` for a non-returning write (`{ affectedRows }`). Inside a transaction, `tx.query(plan)` / `tx.execute(plan)`. `execute` never yields rows — a `select` or `.returning(...)` plan passed to it gives you statistics, not data.
+8. **Setting `capabilities: { lateral: true }` in `prisma.config.ts`.** The ORM config (`ormConfig({...})`) 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 `references/contract.md`).
+9. **Confabulating a TypedSQL or `.stream()` surface.** Neither exists. Raw SQL does: the client's raw lane, ``db.raw.sql`…` ``. Reusable statements do: `db.prepare(...)` (see *Prepared statements* in [`queries.md`](./queries.md)). Streaming: `for await` over a read terminal or `runtime.query(plan)` — with the caveats in *Streaming* in [`queries.md`](./queries.md).
+10. **Mixing the ORM mutation return with `runtime.query(plan)` / `runtime.execute(plan)`.** ORM terminals issue the query themselves and return rows. The runtime methods are for SQL-builder plans.
+11. **Ordering grouped rows by an aggregate metric.** The grouped collection supports `.orderBy(...)` on group keys plus `.limit(...)` / `.offset(...)`, but it cannot order by an aggregate alias such as `SUM(amount)`. Sorting the materialized aggregate result in JS is fine at small cardinalities; for large grouped result sets, drop to `db.sql.<ns>.<table>`.
 
 ## Reference Files
 
@@ -408,8 +408,8 @@ Cross-namespace relations (e.g. `public.Profile` → `auth.User`) follow the sam
 - [ ] Compared and serialised aggregate *results* as what they are — a `bigint` from a suffixed variant needs `0n` literals and `String(value)` rather than bare `JSON.stringify` — leaving the ORM's `having(...)` operands as numbers, and matching each SQL-builder comparison literal to the aggregate's own result codec (`fns.gt(fns.count(), 1)`).
 - [ ] Expressed ranges as chained `.where(...)` clauses or a single `and(...)` clause — did NOT reach for a non-existent `.between(...)` operator.
 - [ ] For cursor pagination, used `.orderBy(...).cursor({ field: lastValue }).limit(n).all()` — did NOT hand-write a `.where(p => p.field.lt(cursor))` workaround when the `.cursor()` API serves the same purpose.
-- [ ] For ORM combinators, imported `and` / `or` / `not` from the (currently internal) `@internal/sql-orm-client` and noted the façade gap to the user.
-- [ ] Executed SQL-builder plans via `db.runtime().execute(plan)` (or `tx.execute(plan)` inside a transaction).
+- [ ] For ORM combinators, imported `and` / `or` / `not` from `@prisma/orm-postgres/orm-client`.
+- [ ] Ran SQL-builder plans via `db.runtime().query(plan)` when they return rows and `db.runtime().execute(plan)` only for non-returning writes (`tx.query` / `tx.execute` inside a transaction). Passed `insert()` an array of rows.
 - [ ] Wrapped multi-statement work in `db.transaction(async (tx) => { ... })` where atomicity matters.
-- [ ] For top-N grouped aggregates at meaningful scale, dropped to `db.sql.<table>` rather than JS-side sort + slice over `groupBy(...).aggregate(...)`.
-- [ ] Did NOT confabulate TypedSQL, `.stream()`, `db.batch`, `.between(...)`, a `capabilities` field on `defineConfig`, or a `db.sql.from(tables.user)` API — routed to *What Prisma 8 doesn't do yet* / `references/feedback.md` instead. Raw SQL is spelled `db.raw.sql`, not `db.sql.raw`.
+- [ ] For top-N grouped aggregates at meaningful scale, dropped to `db.sql.<ns>.<table>` rather than JS-side sort + slice over `groupBy(...).aggregate(...)`.
+- [ ] Did NOT confabulate TypedSQL, `.stream()`, `db.batch`, `.between(...)`, a collection-level `.count()`, a `capabilities` field on the config, or a `db.sql.from(tables.user)` API — routed to *What Prisma 8 doesn't do yet* / `references/feedback.md` instead. Raw SQL is spelled `db.raw.sql`, not `db.sql.raw`.

package/skills/prisma-8/references/queries.md

@@ -28,22 +28,22 @@ Prisma 8 ships **two query lanes per target** on the same `db` value from `src/p
 
 | Runtime import in `db.ts` | Load |
 | --- | --- |
-| `@internal/postgres/runtime` | [`queries-postgres.md`](./queries-postgres.md) — `db.orm.<Model>` + `db.sql.<table>` |
+| `@internal/postgres/runtime` | [`queries-postgres.md`](./queries-postgres.md) — `db.orm.<ns>.<Model>` + `db.sql.<ns>.<table>` |
 | `@internal/mongo/runtime` | [`queries-mongo.md`](./queries-mongo.md) — `db.orm.<root>` + `db.query.from(...)` |
-| `@internal/extension-supabase/runtime` | [`queries-postgres.md`](./queries-postgres.md) — a Supabase `RoleBoundDb` is a Postgres surface (`db.orm.<Model>` + `db.sql.<table>`); bind a role first via `references/supabase.md` |
+| `@internal/extension-supabase/runtime` | [`queries-postgres.md`](./queries-postgres.md) — a Supabase `RoleBoundDb` is a Postgres surface (`db.orm.<ns>.<Model>` + `db.sql.<ns>.<table>`); bind a role first via `references/supabase.md` |
 
 Both targets share the contract and connection on one `db` value. Reach for the ORM first; drop to the lower-level lane when the ORM can't express the shape. Lane choice is local — one query function picks one lane, not the whole app.
 
-**Do not mix target examples.** Postgres uses PascalCase model roots (`db.orm.User`) and `db.sql.user`; Mongo uses lowercased plural roots (`db.orm.users`) and `db.query.from('users')`. There is no `db.sql` on Mongo and no `db.query` SQL-builder equivalent on Postgres.
+**Do not mix target examples.** Postgres uses PascalCase model roots (`db.orm.public.User`) and `db.sql.public.user`; Mongo uses lowercased plural roots (`db.orm.users`) and `db.query.from('users')`. There is no `db.sql` on Mongo and no `db.query` SQL-builder equivalent on Postgres.
 
 ## Namespace-aware accessors
 
-When a contract declares more than one namespace (e.g. `public` and `auth`), models and tables are addressed by namespace coordinate:
+On Postgres, models and tables are **always** addressed by namespace coordinate — the storage namespace is the Postgres schema, and a model declared outside any `namespace { }` block lands in `public`:
 
 - **ORM**: `db.orm.<namespace>.<Model>` — e.g. `db.orm.public.User`, `db.orm.auth.User`
-- **SQL builder**: `db.sql.<namespace>.<table>` — e.g. `db.sql.public.users`, `db.sql.auth.users`
+- **SQL builder**: `db.sql.<namespace>.<table>` — e.g. `db.sql.public.user`, `db.sql.auth.users`
 
-The flat `db.orm.User` / `db.sql.users` form still works for single-namespace contracts (or when all table names are unique across namespaces). When the same bare name appears in more than one namespace, you must use the namespace coordinate.
+There is no flat `db.orm.User` / `db.sql.user` on the Postgres façade: `db.sql` is one facet per storage namespace and nothing else, and `db.orm` is keyed the same way (`examples/prisma-8-demo` uses `db.orm.public.User` and `db.sql.public.user` throughout). SQLite has no schemas, so its façade exposes the single unbound namespace directly — `db.orm.User` and `db.sql.user` are the SQLite spellings (`examples/prisma-8-demo-sqlite`). Mongo is keyed by collection storage name (`db.orm.users`).
 
 See [`queries-postgres.md` § Namespace-aware accessors](./queries-postgres.md#namespace-aware-accessors) for a worked example.
 
@@ -52,7 +52,7 @@ See [`queries-postgres.md` § Namespace-aware accessors](./queries-postgres.md#n
 Critical to get right early — on **both Postgres and Mongo**, `.all()` returns an **`AsyncIterableResult<Row>`**, which is *both* a `PromiseLike<Row[]>` and an `AsyncIterable<Row>`. That means three consumption forms all work, and the canonical one is the shortest:
 
 ```typescript
-const users = await db.orm.User.select('id', 'email').all();
+const users = await db.orm.public.User.select('id', 'email').all();
 //    ^? Row[]   ← the Thenable resolves to a real array. This is the default idiom.
 ```
 
@@ -67,12 +67,11 @@ You do **not** need a `collect()` / `toArray()` helper — `await` is enough. In
 // `Promise.race` combinators all accept the thenable directly — those are
 // NOT reasons to call `.toArray()`. Whenever you are just going to await it
 // here, use `await ...all()` and skip `.toArray()`.
-const rows: Promise<User[]> = db.orm.User.select('id', 'email').all().toArray();
+const rows: Promise<User[]> = db.orm.public.User.select('id', 'email').all().toArray();
 
-// Streaming — process rows one at a time without buffering the whole result.
-// Use for genuinely large result sets (anything that wouldn't fit comfortably
-// in memory) or pipelines where you can start work before all rows arrive.
-for await (const user of db.orm.User.select('id', 'email').all()) {
+// Iterate — decode and handle rows one at a time. Whether the raw rows are
+// also fetched incrementally depends on the façade; see *Streaming* below.
+for await (const user of db.orm.public.User.select('id', 'email').all()) {
   process(user);
 }
 ```
@@ -80,9 +79,9 @@ for await (const user of db.orm.User.select('id', 'email').all()) {
 Two single-row shortcuts also exist on the result, in addition to the collection-level `.first()` (which issues `LIMIT 1` on Postgres):
 
 ```typescript
-const user = await db.orm.User.where({ id }).all().first();
+const user = await db.orm.public.User.where({ id }).all().first();
 //    ^? Row | null   ← buffers, returns the first row or null. Issues no LIMIT.
-const required = await db.orm.User.where({ id }).all().firstOrThrow();
+const required = await db.orm.public.User.where({ id }).all().firstOrThrow();
 //    ^? Row          ← buffers; throws `RUNTIME.NO_ROWS` if empty.
 ```
 
@@ -92,12 +91,12 @@ For genuine single-row reads, prefer the *collection*-level `.first()` (which ad
 
 ```typescript
 // Bad — second await throws RUNTIME.ITERATOR_CONSUMED.
-const result = db.orm.User.select('id', 'email').all();
+const result = db.orm.public.User.select('id', 'email').all();
 const a = await result;
 const b = await result;
 
 // Good — buffer once, reuse the array.
-const users = await db.orm.User.select('id', 'email').all();
+const users = await db.orm.public.User.select('id', 'email').all();
 const a = users;
 const b = users;
 ```
@@ -114,7 +113,7 @@ import { db } from '../prisma/db';
 
 // Postgres — PascalCase model root from contract
 for (const u of users) {
-  await db.orm.User.create(u);
+  await db.orm.public.User.create(u);
 }
 
 // Mongo — lowercased plural root from contract (e.g. users, not User)
@@ -126,11 +125,40 @@ console.log('Seeded.');
 await db.close();
 ```
 
+## Streaming
+
+Every read terminal (`.all()`, and `runtime.query(plan)` for a SQL-builder plan) returns an `AsyncIterableResult`, so `for await` is always available. What it buys you depends on the façade:
+
+- **Long-lived `postgres()` façade** (the usual `db.ts`): the driver runs with cursors disabled. The full result set is fetched from the server before the first row is yielded; only *decoding* happens per row. `for await` therefore does not bound the memory held by the raw result. For very large sets, paginate (`.limit()` / `.offset()`, or `.orderBy(...).cursor(...)`) instead.
+- **Serverless façade** (`@prisma/orm-postgres/serverless`, one `connect()` per invocation): the driver reads through a server-side cursor in batches of 100 rows by default (`cursor: { batchSize }` on the façade options), so `for await` really does stream.
+
+There is no `.stream()` method on either façade.
+
+## Prepared statements (Postgres, SQLite)
+
+`db.prepare(declaration, (sql, params) => plan)` builds a statement once and binds it per call. The declaration names each parameter's codec (`{ email: 'pg/text@1' }`); the callback receives the façade's `sql` builder plus typed `params` and returns a plan. A row-returning plan gives a `PreparedStatement` you run with `ps.query(runtime, params)`; a plan whose result is an affected count gives a `PreparedExecution` you run with `ps.execute(runtime, params)`. Declaring a parameter the plan never references throws `RUNTIME.PREPARE_UNUSED_PARAM`. `runtime.prepare(declaration, (params) => plan)` is the same thing on a `Runtime`.
+
+```typescript
+// examples/prisma-8-demo/src/queries/get-user-by-email-prepared.ts
+const ps = await db.prepare({ email: 'pg/text@1' }, (sql, params) =>
+  sql.public.user
+    .select('id', 'email', 'displayName', 'createdAt', 'kind')
+    .where((f, fns) => fns.eq(f.email, params.email))
+    .limit(1)
+    .build(),
+);
+
+const runtime = db.runtime();
+for (const email of emails) {
+  const rows = await ps.query(runtime, { email });
+}
+```
+
 ## Naming model and result types
 
 The model is the whole row plus its relations, and each related model carries its own relations in turn, so no query returns a value of the model type. A query returns the fields it fetched. The default fetch returns `Scalars<Model>`, the model without relations: `db.orm.public.User.first()` returns `Scalars<Model> | null`, and `db.orm.public.User.all()` returns `Scalars<Model>[]` (or its async iterable). Four types cover every case, and none needs a client in scope:
 
-- `Models.<ns>_<Model>` (from `contract.d.ts`) — every scalar field and every relation. On SQLite, which has no schemas, the name is bare: `Models.User` and `typeof models.User`. On Postgres the schema is part of the name: `Models.public_User`, or `typeof models.public.User` by dotted access. A model declared without a schema is in the unbound namespace: `Models.unbound_User` and `typeof models.__unbound__.User`. Mongo names its models the same way. A polymorphic base also emits one member per variant and an `Any<Base>` union (`Models.public_AnyTask`).
+- `Models.<ns>_<Model>` (from `contract.d.ts`) — every scalar field and every relation. On SQLite, which has no schemas, the name is bare: `Models.User` and `typeof models.User`. On Postgres the schema is part of the name: `Models.public_User`, or `typeof models.public.User` by dotted access — a model declared outside any `namespace { }` block is in `public`, so that is also its name. Mongo names its models the same way. A polymorphic base also emits one member per variant and an `Any<Base>` union (`Models.public_AnyTask`).
 - `Scalars<M>` — the model without relations; what a default fetch returns. Distributes over unions, so `Scalars<Models.public_AnyTask>` is the union of variant rows.
 - `Shape<M, Spec>` — a data structure derived from the model, for declaring an endpoint's response type once and having the compiler check the body at the `return`. At every level of `Spec`: `'+'` is a union of scalar and relation names to keep (a relation named there comes with all of its scalars and none of its relations; the scalars are narrowed only when `'+'` names a scalar, so `'+': 'posts'` alone is every scalar plus posts); `'-'` is a union of scalar names to drop; `'+'` naming a scalar beside `'-'` is a compile error, while `{ '-': 'passwordHash'; '+': 'posts' }` is every scalar but the hash plus posts; any other key is a relation whose value is a nested spec that narrows the related model. Relations are absent unless asked for; `X[]`, `X | null`, or `X` comes from the model. Wrong names, a relation in `'-'`, a non-object relation value, and a relation both in `'+'` and as a key are compile errors. No `where`/`orderBy`/`limit`; compose extras with TypeScript (`Shape<M> & { postCount: number }`).
 - `ResultType<typeof query>` — the row of any ORM collection value (plain, `.include()`, `.select()`, `.variant()`), and of SQL lane plans. Bind the query to a name first; `typeof` needs a value.
@@ -179,18 +207,16 @@ Target-specific pitfalls live in the per-target guides.
 
 ## What Prisma 8 doesn't do yet
 
-- **N:M `.include()` across a junction table.** The contract IR supports many-to-many relations with a `through` junction table, and `N:M` relations appear as valid relation names on the ORM collection. However, `.include()` on an N:M relation does not emit the two-step junction join — the query plan builder only handles the direct join columns (`localColumn` / `targetColumn`) and ignores the `through` metadata. Attempting it either produces wrong results or an error. Workaround: express the N:M traversal through `db.sql.<table>` with an explicit join on the junction table.
-- **N:M nested mutations.** `mutation-executor.ts` explicitly throws `'N:M nested mutations are not supported yet'` for nested creates/links through an N:M relation.
-- **`and` / `or` / `not` combinators in the postgres façade.** The combinators currently import from `@internal/sql-orm-client` (an internal package). Workaround today: import them from `@internal/sql-orm-client` directly, the way the example apps do. If you want them on `@internal/postgres/runtime`, file a feature request via `references/feedback.md`.
-- **Ordering grouped aggregates by an aggregate alias (Postgres).** `db.orm.<Model>.groupBy(...)` supports `.orderBy(...)` on group keys plus `.limit(...)` / `.offset(...)`, but the grouped collection cannot order by an aggregate alias such as `SUM(amount)`. A "top-N groups by SUM" query therefore falls back to JS-side sort + slice over the full grouped result, which is fine at small cardinalities and bad at scale. Workarounds: (a) drop to `db.sql.<table>` and write the `GROUP BY` + `ORDER BY` + `LIMIT` against the aggregated table directly; (b) live with the JS-side sort/slice if the grouped cardinality is bounded. File a feature request via `references/feedback.md` if this is hitting you in production.
+- **Many-to-many relations work through the junction.** `.include('tags', (tag) => tag.select(...))` traverses an N:M relation's `through` table, and nested `create` / `connect` / `disconnect` on an N:M relation write the junction rows for you (`examples/prisma-8-demo/src/orm-client/get-post-tags.ts`, `create-post-with-tags.ts`). The one refusal: a junction with required payload columns the relation API cannot populate throws `ORM.RELATION_MUTATION_UNSUPPORTED` — write that junction directly or use the SQL builder.
+- **Ordering grouped aggregates by an aggregate alias (Postgres).** `db.orm.<ns>.<Model>.groupBy(...)` supports `.orderBy(...)` on group keys plus `.limit(...)` / `.offset(...)`, but the grouped collection cannot order by an aggregate alias such as `SUM(amount)`. A "top-N groups by SUM" query therefore falls back to JS-side sort + slice over the full grouped result, which is fine at small cardinalities and bad at scale. Workarounds: (a) drop to `db.sql.<ns>.<table>` and write the `GROUP BY` + `ORDER BY` + `LIMIT` against the aggregated table directly; (b) live with the JS-side sort/slice if the grouped cardinality is bounded. File a feature request via `references/feedback.md` if this is hitting you in production.
 - **A raw-SQL lane.** This one exists. Write whole-query raw SQL through the client's raw lane: ``db.raw.sql`SELECT ...`.returnsRow({ ... }).build()`` for rows, or `.affectedCount()` for a mutation's row count. Each declared column names the codec that decodes it, so the row stays typed. For an expression fragment inside a builder query, use `fns.raw` in a `.select(...)` callback instead.
-- **TypedSQL (`.sql` files compiled into typed callables).** Not implemented. Workaround: stick to the SQL builder; for repeated queries, extract a function that returns the built plan and call `db.runtime().execute(plan)` at the call site. If you want a `.sql`-file compile path, file a feature request via `references/feedback.md`.
+- **TypedSQL (`.sql` files compiled into typed callables).** Not implemented. For a repeated query, use `db.prepare(...)` (see *Prepared statements* above) or a function that returns the built plan and `db.runtime().query(plan)` at the call site. If you want a `.sql`-file compile path, file a feature request via `references/feedback.md`.
 - **`EXPLAIN` / query-plan inspection.** Prisma 8 does not expose an `.explain()` method. Workaround: connect a `pg.Pool` you control via the runtime's `pg:` binding (see `references/runtime.md`) and issue `EXPLAIN ANALYZE` through it. If you want a first-class plan-inspection surface, file a feature request via `references/feedback.md`.
-- **Streaming large result sets.** No `.stream()` cursor today. Workaround: paginate via `.offset(n).limit(m)` for moderate sizes; for very large sets, hold a `pg.Client` from the runtime's `pg:` binding and stream through it directly. If you want a built-in streaming surface, file a feature request via `references/feedback.md`.
+- **Cursor-backed streaming on the long-lived façade.** `for await` works everywhere, but on `postgres()` the raw result is fetched in full before iteration (see *Streaming* above); only the serverless façade reads through a cursor. Paginate for very large sets on the long-lived façade. If you want cursor streaming there, file a feature request via `references/feedback.md`.
 - **Multi-statement batching (Prisma-7-style `db.$transaction([call1, call2])`).** Prisma 8 runs each call sequentially. Workaround: wrap atomically-related work in `db.transaction(async (tx) => { ... })` on Postgres. If you want batch-as-array semantics, file a feature request via `references/feedback.md`.
 - **Mongo façade transactions.** `@internal/mongo/runtime` does not expose `db.transaction(...)`. Multi-document atomicity is not yet wrapped in the Prisma 8 Mongo façade. Workaround: use the MongoDB driver's session API directly if you control the client binding (`mongoClient:` option). File a feature request via `references/feedback.md` if you need a first-class façade surface.
-- **Mongo ORM aggregates.** No `.aggregate(...)` / `.groupBy(...)` on `db.orm.<root>`. Workaround: express aggregations through `db.query.from(...).group(...).build()` and `runtime.execute(plan)`.
-- **Mongo filter helpers on the façade.** Rich filters (`.in`, ranges, boolean composition) currently import from `@internal/mongo-query-ast/execution` (`MongoFieldFilter`, etc.) — not yet re-exported on `@internal/mongo/runtime`. Workaround: use object equality `.where({ field: value })` where possible; import from the internal package only when necessary. Tracked alongside façade-completeness gaps in Linear `TML-2526`.
+- **Mongo ORM aggregates.** No `.aggregate(...)` / `.groupBy(...)` on `db.orm.<root>`. Workaround: express aggregations through `db.query.from(...).group(...).build()` and `runtime.query(plan)`.
+- **Mongo filter helpers on the façade.** Rich filters (`.in`, ranges, boolean composition) currently import from `@prisma/orm-mongo/query-ast/execution` (`MongoFieldFilter`, etc.) — not re-exported on `@internal/mongo/runtime`. Workaround: use object equality `.where({ field: value })` where possible; import from the internal package only when necessary. Tracked alongside façade-completeness gaps in Linear `TML-2526`.
 - **Automatic N+1 detection.** Prisma 8 does not warn when an `.include(...)` is missing. Workaround: be deliberate about `.include(...)` in code review; the `lints` middleware (see `references/runtime.md`) catches the more common authoring slips (missing `WHERE` on a `DELETE` / `UPDATE`, missing `LIMIT` on a `SELECT`).
 
 ## Reference Files
@@ -203,9 +229,9 @@ This skill is split for selective loading. Target-specific reference paths live
 ## Checklist
 
 - [ ] Confirmed the active target from `db.ts` and loaded the matching guide ([`queries-postgres.md`](./queries-postgres.md) or [`queries-mongo.md`](./queries-mongo.md)).
-- [ ] For multi-namespace contracts, used `db.orm.<ns>.<Model>` / `db.sql.<ns>.<table>` coordinates when the same bare name exists in more than one namespace.
+- [ ] On Postgres, used `db.orm.<ns>.<Model>` / `db.sql.<ns>.<table>` coordinates (usually `public`) — not a flat `db.orm.User`, which exists only on SQLite.
 - [ ] Chose the right lane (ORM by default; lower-level builder for shapes the ORM doesn't express).
 - [ ] Used `.first()` / `.first({ pk })` (Postgres) or `.where({ ... }).first()` (Mongo) for single-row reads — not `.all()`.
-- [ ] Consumed `.all()` with plain `await` (not a `collect()` / `toArray()` helper). Used `for await` only when streaming is actually wanted, and never iterated the same result twice.
+- [ ] Consumed `.all()` with plain `await` (not a `collect()` / `toArray()` helper). Used `for await` only when per-row handling is actually wanted — and did not promise it bounds memory on the long-lived façade — and never iterated the same result twice.
 - [ ] Did NOT use `db.sql` on a Mongo project or `db.query` where the Postgres SQL builder is meant.
 - [ ] Completed the target-specific checklist in the loaded guide.