@kequtech/tenon-orm 0.2.1 → 0.3.0

package/docs/agent-guide.md

@@ -1,35 +1,27 @@
 # Tenon agent guide
 
-Tenon executes PostgreSQL SQL through Postgres.js, with parameter binding, transactions, optional write
-limits, SQL migrations, and generated row and mutation input types. Use ordinary functions for reusable queries.
-This guide contains the setup and contracts needed for routine implementation; the
-[reference](reference.md) covers additional options.
-
-## Working conventions
-
-1. Inspect the application's connection setup, migrations, generated types, query modules, and check
-   commands. Reuse them. Do not replace a working migration runner just to use Tenon queries.
-   For new schemas, prefer plural `snake_case` table names and `snake_case` column names; preserve
-   existing schemas' names.
-2. Write straightforward SQL with explicit selected columns. Use separate complete queries when
-   variants return different shapes. Introduce fragments only for actual reuse or variable
-   composition.
-3. Put reusable queries in functions. Accept a `QueryClient` and named object inputs when useful;
-   keep SQL and query options together. Call the same function with `db` or `tx`.
-4. After SQL changes, inspect the completed queries and run typechecking and relevant database
-   assertions. Cover meaningful runtime variants and verify declared result contracts against
-   complete relevant rows.
-5. Keep validation, authorization, retries, and parser configuration in the application. A quoted
-   identifier or correct row count does not prove authorization.
-
-## Install and connect
-
-Requires Node.js 24+, PostgreSQL 16+, ESM, TypeScript 6+, and Node development typings. Keep the
-application's strict TypeScript configuration.
-
-```sh
-npm install @kequtech/tenon-orm
-```
+Tenon executes explicit PostgreSQL SQL through pg. Use ordinary functions for reusable queries. This
+guide covers routine implementation; the [reference](reference.md) defines the full API and the
+[human guide](human-guide.md) gives a step-by-step introduction.
+
+## Start with the existing project
+
+Inspect its connection configuration, migration runner, generated types, query functions, and check
+commands. Preserve those conventions. Tenon queries and type generation do not require Tenon
+migration history. Keep input validation, authorization, domain conversion, and retry policy in the
+application.
+
+For an upgrade, record the previous resolved Tenon version from the lockfile or installed package
+and read the [Changelog](../CHANGELOG.md) entries through the target version before changing code.
+It ships with the package alongside this guide. Follow its upgrade instructions, regenerate types
+when mappings change, and run the project's typechecks and relevant database tests. Use the
+[adoption guide](adoption-guide.md) when replacing another ORM or transferring migration ownership.
+
+## Connect
+
+Requires Node.js 24+, PostgreSQL 16+, ESM, TypeScript 6+, and Node development typings. Install with
+`npm install @kequtech/tenon-orm`; retain the project's package manager and TypeScript
+configuration.
 
 ```ts
 import { createTenon } from '@kequtech/tenon-orm';
@@ -39,19 +31,15 @@ if (!connection) throw new Error('DATABASE_URL is required');
 export const db = createTenon({ connection });
 ```
 
-`connection` accepts a URL, Postgres.js options, or an existing Postgres.js client. An explicit `{}` selects the driver's
-environment defaults. Reuse one instance per database connection. `close()` closes owned pools;
-supplied clients remain application-owned. The driver retains its native connection callbacks. Await
-outstanding work before closing. Environment files are not loaded automatically. Qualify SQL names
-or configure `search_path`; CLI `--namespace` does not change runtime query names.
-
-Use `db.native` for Postgres.js features such as LISTEN, cursors, and COPY without another driver
-installation. It is the existing pool-level client. Native calls bypass Tenon's guards and `onQuery`,
-and do not join a Tenon transaction; transaction callbacks expose only `tx.query`. `db.close()` ends
-owned clients and their listeners; borrowed clients stay application-owned. Follow the
-[native access contract](reference.md#native-driver-access) for initialization and shutdown.
+`connection` accepts a URI string, pg `PoolConfig` (including `connectionString`), or an existing
+`pg.Pool`. Reuse an instance for each database configuration. `db.close()` ends internally created
+pools with a default 5,000 ms grace period; supplied pools remain application-owned. Configure
+shutdown with `db.close({ timeoutMs })`; concurrent callers share its outcome. Finish outstanding
+work before closing. Tenon loads no environment files. Qualify table names or set runtime
+`search_path`; CLI `--namespace` selects tooling scope, not runtime query names. See
+[connection options](reference.md#installation-and-connection).
 
-## Query contracts
+## Query and result contracts
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
@@ -59,211 +47,119 @@ import type { Rows } from './generated-schema.js';
 
 type Summary = Pick<Rows['users'], 'id' | 'email'>;
 
-function userByIdQuery({ id }: { id: number }) {
-  return sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`;
+function userById(client: QueryClient, { id }: { id: number }) {
+  return client.query(sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`, {
+    returns: 'oneOrNone',
+  });
 }
-
-function userById(client: QueryClient, input: { id: number }) {
-  return client.query(userByIdQuery(input), { returns: 'oneOrNone' });
-}
-
-const user = await userById(db, { id: 42 });
-// In a transaction, call userById(tx, { id: 42 }).
 ```
 
-`sql<Row>` describes one selected row. It does not prove SQL/type agreement or validate JSON.
-Unannotated fields stay `unknown`. Generated types describe full table rows; joins, aliases,
-aggregates, and expressions need projection-specific types.
+`QueryClient` accepts either `db` or a transaction's `tx`. Keep SQL and execution options together.
+`sql<Row>` declares one selected row; it does not verify SQL or validate data. Unannotated fields
+are `unknown`. Generated table types can describe full rows or `Pick` projections; joins and
+aggregates need types for their actual output.
 
-| `returns`          | Result                               | Row-count contract |
-| ------------------ | ------------------------------------ | ------------------ |
-| `native` (default) | Postgres.js `QueryResult<Row>` array | Any                |
-| `many`             | `Row[]`                              | Any                |
-| `oneOrNone`        | `Row \| undefined`                   | At most one        |
-| `one`              | `Row`                                | Exactly one        |
+| `returns`          | Result                                             | Required returned rows |
+| ------------------ | -------------------------------------------------- | ---------------------- |
+| `native` (default) | Driver object with `.rows`, `.rowCount`, `.fields` | Any                    |
+| `many`             | Plain `Row[]`                                      | Any                    |
+| `oneOrNone`        | `Row \| undefined`                                 | Zero or one            |
+| `one`              | `Row`                                              | Exactly one            |
 
-`query` options are `{ returns?, affectedRows?, label? }`; unknown options fail. Return modes never
-insert `LIMIT` or `RETURNING`. Returned-row checks alone do not undo autocommitted writes. `label`
-is an optional nonempty diagnostic string. Native results are row arrays with `.count`, `.command`,
-and `.columns`; `many` returns a plain row array.
-
-The Postgres.js driver is included. Undefined bound parameters fail. Pass JSON values directly,
-including arrays, rather than calling `JSON.stringify`. Numeric and bigint scalars and arrays read
-as strings. Dates read as `Date`, including invalid dates for timestamp infinities; check validity
-before using them. SQL NULL array elements read as JavaScript null.
+Options are `{ returns?, affectedRows?, label? }`; unknown keys fail. Modes do not add SQL limits or
+`RETURNING`. A returned-row mismatch throws `CardinalityError` with code
+`TENON_CARDINALITY_MISMATCH`; it alone does not undo an autocommitted write.
 
 ## Parameters and composition
 
-- Ordinary interpolations bind values. Do not quote them or author manual `$n` placeholders inside
-  templates. `undefined` is rejected; use `null` for SQL null.
-- PostgreSQL infers parameter types from SQL. Cast standalone projections, e.g.
-  `SELECT ${value}::float8 AS value`, so inspection and execution use the same type.
-- Use `id = ANY(${ids}::integer[])` for an array of IDs. Do not build a comma-separated string of
-  values.
-- `identifier(schema, table)` quotes separate application-approved components. Ordinary strings such
-  as `'DESC'` remain bound values, not SQL syntax.
-- `sql.fragment` carries SQL and bound values without a row type. Use it for shared predicates or
-  partial SQL. Fragments cannot execute alone; full `sql` and `unsafeSql` queries cannot be nested.
-- `sql.join(fragments, separator)` combines a variable-length list of fragments using `'AND'`,
-  `'OR'`, or `','`. Use it for optional filters, search terms, or lists of SQL expressions. The list
-  must be nonempty; group mixed `AND`/`OR` predicates with parentheses.
-- `unsafeSql<Row>(text, values)` accepts trusted external SQL with an explicit values array. Never
-  concatenate request input into its text. Each query executes one statement.
-
-For example, share a search condition between a page and count query:
+- Interpolate values without quotes. Do not author `$n` placeholders inside templates. `undefined`
+  and `null` bind as SQL null, following pg.
+- Use `id = ANY(${ids}::integer[])` for a set of IDs. Cast standalone parameters such as
+  `SELECT ${value}::integer AS value` when SQL must establish the type for inspection.
+- `identifier(schema, table)` quotes separate approved names. Strings such as `'DESC'` remain bound
+  values; choose SQL syntax through fixed query alternatives or fragments.
+- `sql.fragment` creates partial SQL with bound values; `sql.join(parts, 'AND' | 'OR' | ',')`
+  combines a nonempty list. Blank fragments fail. Group mixed conditions with parentheses.
+- Full `sql` or `unsafeSql` queries cannot be nested. `unsafeSql<Row>(text, values)` is for trusted
+  external SQL with an explicit values array. Each Tenon query executes one statement.
 
-```ts
-const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
-const page = sql<Summary>`SELECT id, email FROM public.users
-  WHERE ${search} ORDER BY id LIMIT ${limit}`;
-const count = sql<{ count: string }>`SELECT count(*) AS count FROM public.users
-  WHERE ${search}`;
-```
+Use fragments for actual reuse or variable composition. Keep fixed structure in SQL, and retain
+mandatory authorization predicates when optional filters are absent.
 
-`pattern` and `limit` are validated application inputs. See the
-[composition reference](reference.md#sql-fragments-and-joins) for grouping and list examples.
+## Writes and generated values
 
-## Object-based writes
+`sql.insertValues(rowOrRows, columns?)` builds column/value fragments;
+`sql.assignments(patch, columns?)` builds assignments. Missing/undefined insert fields use defaults;
+update fields are omitted. Explicit null stays null. Empty batches and empty assignments fail.
+Selected columns ignore unlisted fields and can discard required inputs. Put expressions, conflict
+policy, and `RETURNING` in the surrounding SQL. Batch in the caller below the query-wide
+65,535-parameter limit.
 
-Use official `sql.insertValues(rowOrRows, columns?)` and `sql.assignments(patch, columns?)` fragments
-instead of application helpers that enumerate object keys. Keep tables, authorization predicates,
-expressions, conflict behavior and `RETURNING` visible in SQL. Insert missing/undefined fields use
-PostgreSQL defaults; update missing/undefined fields are omitted. Explicit null stays null. Empty
-batches/updates throw; a single default-only insert works. Omit generated columns and batch large
-writes explicitly below the query-wide limit of 65,533 parameters. Expressions and queries are
-rejected as cell values; write arithmetic, `DEFAULT`, and `excluded.column` in the surrounding SQL.
+Use generated `Rows.Insert['users']` and `Rows.Update['users']` inputs; narrow editable fields with
+`Pick`. These types account for defaults, writable columns, domains, and driver representations.
+They do not validate constraints or JSON contents. See [mutation examples](mutations.md).
 
-Use generated `Rows.Insert['table']` and `Rows.Update['table']` for mutation inputs when available;
-narrow editable fields with `Pick`. They account for defaults, nullability, domains, and generated
-columns. Write mappings differ from returned rows: timestamps use `Date | string`, bigint uses
-`string | bigint`, and JSON accepts native JavaScript values through Tenon's exported `JSONValue` type. See the [input types](reference.md#insert-and-update-inputs).
+Use `JSON.stringify(value)` for JSON write inputs; arrays otherwise bind as PostgreSQL arrays.
+Bigint and numeric scalars read as strings, while numeric arrays read as numbers and can lose
+precision. Temporal reads use `Date | number` for finite dates and infinities. SQL NULL array
+elements remain JavaScript null. Keep domain validation at the persistence boundary. See
+[value mappings](reference.md#generated-types-and-checking).
 
-Selected columns choose and order fields, e.g. `sql.insertValues(rows, ['name', 'score'])`. Unlisted
-fields are ignored. See the [mutation contract](reference.md#object-based-mutation-fragments) and
-[cookbook](mutations.md).
+## Transactions and native access
 
-## Inspect and test completed queries
-
-Inspection ships with Tenon and needs no additional setup:
+For an existing user with id 42:
 
 ```ts
-import { describeQuery } from '@kequtech/tenon-orm';
-
-const query = userByIdQuery({ id: 42 });
-const description = await describeQuery({ connection, query });
-```
-
-Pass the actual query object that will go to `db.query`, including fragments and conditional
-predicates. A small ordinary query-building function can make the same statement available to
-inspection and execution tests. Keep authorization policy inside the builder or shared fragments.
-
-For a SQL file with PostgreSQL `$n` placeholders:
-
-```sh
-npx tenon describe query.sql
+await db.transaction(async (tx) => {
+  await tx.query(sql`UPDATE public.users SET active = false WHERE id = ${42}`, {
+    affectedRows: { exact: 1 },
+  });
+});
 ```
 
-Supply `DATABASE_URL` through the application's existing environment setup. Match its role,
-`search_path`, and timezone through the connection URI or optional `session` settings. Review
-the returned `context`; this is a separate connection with Postgres.js read mappings. It does not
-inherit custom parsers, temporary tables, or transaction-local state.
-
-The report contains parameter/column types and findings with stable issue codes. Result nullability
-is unknown, source `NOT NULL` is informational, and JSON remains unknown. CLI success means the
-statement was described, not that `sql<Row>`, values, permissions, or business behavior were verified.
-
-With a test fixture containing user 42, check the database projection and the actual value separately:
-
-```ts
-import assert from 'node:assert/strict';
-
-assert.deepEqual(
-  description.columns.map(({ name, readType }) => [name, readType]),
-  [
-    ['id', 'number'],
-    ['email', 'string'],
-  ],
-);
-const expected = { id: 42, email: 'reader@example.test' } satisfies Summary;
-assert.deepEqual(await userById(db, { id: expected.id }), expected);
-```
-
-The builder keeps inspection and application SQL together; the query function keeps execution options
-and its `db`/`tx` contract together. Keep simple queries inline when they do not need a shared builder.
-The typed fixture checks the declared shape, the description checks PostgreSQL's projection, and
-execution checks the actual row. None of these proves coverage of other inputs or authorization rules.
-
-Run the same query through the real application connection against its test database. Assert full
-relevant rows/effects and exercise meaningful branches: ownership, optional filters, absent joins,
-empty aggregates, pagination ties, JSON validation, and failed/replayed/rolled-back writes as
-applicable. Keep these tests alongside the query; describing a single instance covers only that
-instance. See [query inspection](query-inspection.md) for session options, limits, and issue codes.
-
-## Transactions and writes
-
-Use `db.transaction(async (tx) => ...)`; use `tx` for every query in scope and await all work. The
-callback commits on success and rolls back on an escaping error. Do not issue direct
-BEGIN/COMMIT/ROLLBACK boundaries or use `tx` after return. Transactions do not span database
-instances. Nested callback transactions and automatic retries are not provided.
-
-Use `affectedRows: { exact: n }` or `{ max: n }` for INSERT/UPDATE/DELETE/MERGE when a write must
-respect a count. Bounds are nonnegative safe integers. A guarded `db.query` uses a transaction; a
-guarded `tx.query` uses a savepoint. Rejected writes are rolled back before throwing. A caught
-guarded failure permits continued work; ordinary SQL failures may abort the transaction. Reserve
-savepoint names beginning with `tenon_affected_rows_`.
-
-Affected counts cover the final command, not extra trigger/cascade/CTE effects. They cannot detect
-the wrong single row. Sequence advances and external effects are not reversible. A lost commit
-acknowledgment may leave the outcome unknown; retry only according to application policy. Native Postgres.js
-errors retain their details; `AffectedRowsError` has codes `TENON_AFFECTED_ROWS_MISMATCH` and
-`TENON_AFFECTED_ROWS_UNSUPPORTED`. Cleanup failures can produce `AggregateError`.
-
-Optional `onQuery` observes labels, duration, outcome, and available command/count/ error code,
-without SQL or values. Observers are not awaited. Query success inside a callback does not mean the
-outer transaction committed.
+Use `tx` for every operation in the callback and await the work. Tenon commits on success and rolls
+back on an escaping error; the callback client expires when the callback finishes. Direct
+BEGIN/COMMIT/ROLLBACK boundaries, nested callback transactions, and automatic retries are not
+provided. Transactions belong to one database instance.
+
+`affectedRows: { exact: n }` or `{ max: n }` checks the final INSERT/UPDATE/DELETE/MERGE count.
+Bounds are nonnegative safe integers. A guarded `db.query` uses a transaction; a guarded `tx.query`
+uses a savepoint. Rejection rolls back that operation. A caught guarded failure permits continued
+work; an unguarded SQL error normally aborts the transaction. Counts exclude extra trigger/cascade
+and CTE effects. Reserve `tenon_affected_rows_` savepoint names for Tenon. A lost commit
+acknowledgment can leave the outcome unknown.
+
+`db.native` exposes the existing pool for driver features. Native calls bypass Tenon's guards and
+`onQuery`; they do not join a Tenon transaction. Close owned pools through `db.close()`. Follow the
+[native access contract](reference.md#native-driver-access) for resource ownership and LISTEN.
+Optional `onQuery` reports completion metadata without SQL or values; success inside a callback does
+not establish that the outer transaction committed.
+
+## Inspect and validate
+
+Use `describeQuery({ connection, query })` on completed SQL or `tenon describe query.sql` on a file.
+Inspection owns a separate connection. Match the runtime role, search path, and timezone. Temporary
+tables and transaction-local state are not inherited; reported mappings assume pg's default parsers.
+Result nullability is unknown and JSON structure is unchecked. A successful description does not
+verify `sql<Row>`, bound values, execution permission, or effects.
+
+Pair inspection with database assertions for complete relevant rows, meaningful query variants, and
+rollback. A small query-building function can share the same statement with inspection and
+execution; keep simple queries inline when that is sufficient. See
+[query inspection](query-inspection.md).
 
 ## Schema changes
 
-Reuse the application's migration setup. With Tenon's runner and generated table types, use this
-development script in `package.json`:
-
-```json
-{
-  "scripts": {
-    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.d.ts"
-  }
-}
-```
-
-```sh
-npx tenon new create_users
-# Fill the generated up/down SQL before migrating.
-npm run db:migrate
-npx tenon generate --out src/generated-schema.d.ts --check
-npx tenon status
-npx tenon rollback --steps 1
-```
-
-Commit migrations and generated types together. Production runs only `npx tenon migrate` and deploys
-the already-built application. Omit generation from the development script if table types are
-unused.
-
-Database commands require `DATABASE_URL`. Migration commands accept `--directory` (default
-`migrations`) and `--namespace` (default `public`); generation accepts `--namespace`. Files use
-`<numeric-id>_<name>.up.sql` with optional matching down SQL. Omit a down file for an intentionally
-irreversible migration. Never edit applied files. For a custom namespace, pass it to both commands
-in the development script.
-
-Each migration commits with its history entry; earlier files remain applied if a later one fails.
-Tools use session advisory locks: use a direct connection or session pooling and application
-timeouts. Nontransactional DDL needs a separate procedure. `generate --check` detects representation
-drift, not pending migrations or every possible schema change. Generation covers ordinary tables and
-partitioned roots; views/foreign tables need authored query types.
-
-When replacing another ORM, preserve its schema and behavior. If transferring migration ownership,
-capture one reviewed baseline with `tenon baseline capture`, record it only on matching existing
-databases with `tenon baseline adopt`, and use `tenon migrate` on fresh databases. Adoption does not
-compare schemas or run baseline SQL. Fresh replay omits ownership and grants; apply deployment
-security provisioning before application access, especially for `SECURITY DEFINER` functions.
-See [adoption](adoption-guide.md) for the full transition procedure. A down migration or schema-only
-baseline is not a data backup.
+With Tenon's runner, development can use
+`tenon migrate && tenon generate --out src/generated-schema.d.ts`. Commit migrations and exact
+generated output together; exclude the generated file from automatic formatting. Production runs
+migrations and deploys committed types. `generate --check` detects representation drift, not pending
+migrations or every schema change.
+
+All database CLI commands require `DATABASE_URL`. `tenon new <name>` creates empty up/down files
+offline; fill them before migrating. Migration commands use `--directory migrations` and
+`--namespace public` by default; generation also accepts `--namespace`. Pass a custom namespace to
+both migration and generation. Omit the down file for an irreversible migration; never edit applied
+history. Each file commits independently with its history entry. Tools use session advisory locks,
+so use a direct or session-pooled connection. Nontransactional DDL needs a separate procedure. See
+the [command reference](reference.md#command-reference).

package/docs/human-guide.md

@@ -1,12 +1,12 @@
 # Using Tenon: a human guide
 
 Tenon lets you use PostgreSQL directly from TypeScript. You write SQL; Tenon binds its inputs and
-executes it through Postgres.js. This guide follows a small application from its first table to reusable
+executes it through pg. This guide follows a small application from its first table to reusable
 queries, transactions, and result checking.
 
-Use the [reference](reference.md) when you need exact options or unusual cases. The
-[agent guide](agent-guide.md) is a separate working guide for coding agents;
-[adoption](adoption-guide.md) covers moving an existing application to Tenon.
+Use the [reference](reference.md) for exact contracts and [adoption](adoption-guide.md) when
+replacing an existing ORM. Code blocks build on the connection and table introduced below;
+query-function examples belong in their own module.
 
 ## Connect to your database
 
@@ -29,15 +29,13 @@ if (!connection) throw new Error('DATABASE_URL is required');
 export const db = createTenon({ connection });
 ```
 
-Reuse this instance across the application and call `await db.close()` at shutdown. For multiple
-databases, create an instance for each connection. You can also supply an existing Postgres.js client; your
-application then closes that pool.
+Reuse this instance across the application and call `await db.close()` at shutdown. You can also
+supply an existing `pg.Pool`; your application then owns its shutdown.
 
 ## Create a table
 
-If you already have a schema and migration runner, you can keep them. For new schemas, prefer plural
-`snake_case` table names and `snake_case` column names. Tenon preserves your schema's exact names.
-Create a migration:
+If you already have a schema and migration runner, keep them. For a fresh example database, create a
+migration:
 
 ```sh
 npx tenon new create_users
@@ -101,8 +99,8 @@ separately from the SQL text, even when the value contains SQL.
 
 The type describes one selected row. `returns: 'oneOrNone'` gives you that row or `undefined`; it
 throws if the query returns more than one row. Use `'one'` when absence should also be an error,
-`'many'` for an array, or omit `returns` for the native result array with `.count` and `.columns`.
-These options do not change your SQL.
+`'many'` for an array, or omit `returns` for the native result object with `.rows`, `.rowCount`, and
+`.fields`. These options do not change your SQL.
 
 Generated table types can help describe projections without repeating every field:
 
@@ -132,16 +130,16 @@ export function userByEmail(client: QueryClient, { email }: { email: string }) {
     returns: 'oneOrNone',
   });
 }
-
-const user = await userByEmail(db, { email: 'reader@example.test' });
 ```
 
-`QueryClient` means the function accepts either your database instance or a transaction client. Keep
-the SQL and execution options together in the function.
+Call `userByEmail(db, { email: 'reader@example.test' })` at the call site, or pass a transaction's
+`tx`. Keep the SQL and execution options together in the function.
 
 ## Change data in a transaction
 
 ```ts
+import { userByEmail } from './queries.js';
+
 await db.transaction(async (tx) => {
   const user = await userByEmail(tx, { email: 'reader@example.test' });
   if (!user) throw new Error('User not found');
@@ -179,50 +177,31 @@ await db.query(sql`UPDATE public.users SET ${sql.assignments(patch, ['active'])}
   WHERE email = ${input.email}`);
 ```
 
-Generated insert types distinguish required fields from defaults and nullable fields. Update types
-make writable fields optional; use `Pick` to limit what an action may edit. See the
-[input-type reference](reference.md#insert-and-update-inputs) for write-value mappings.
-
-Keep expressions, authorization, conflict handling and `RETURNING` in SQL. Selected column lists
-choose which fields to write; they do not validate the complete object. See the
-[mutation cookbook](mutations.md) for batches and upserts.
+Use `Pick` to limit editable fields. Keep expressions, predicates, conflict handling, and
+`RETURNING` in SQL. Selected columns choose fields; they do not validate the complete object. See
+[input types](reference.md#insert-and-update-inputs) for mappings and the
+[mutation cookbook](mutations.md) for defaults, batches, and upserts.
 
 ## Check your SQL and result types
 
-Use `describeQuery({ connection, query })` on the completed query object, or
-`npx tenon describe query.sql` on a SQL file, to inspect the server's parameter and result types.
-This works with dynamic fragments and needs no additional checking setup. Match the application's
-connection settings and keep database assertions for actual rows, nulls, JSON, permissions, and
-transaction effects. See [query inspection](query-inspection.md).
-
-TypeScript checks the application code and the result types you declare. Describe reports
-PostgreSQL metadata; it does not generate or verify a TypeScript annotation. Use generated table
-types where appropriate, declare projections explicitly, and check complete returned rows in tests.
+Use `describeQuery({ connection, query })` on completed SQL, or `npx tenon describe query.sql` on a
+file. It reports PostgreSQL metadata and a conservative `rowType` declaration; it does not update or
+verify the application's `sql<Row>` annotation. Inspection uses a separate session, so match the
+runtime role and settings. See [query inspection](query-inspection.md) for a worked test.
 
-1. Run `npm run db:migrate` against the development/test database.
-2. Inspect the completed SQL and review the reported types and unresolved findings.
-3. Run TypeScript and database tests. Keep these checks in routine CI validation.
-
-Input validation and authorization remain application responsibilities. Describe cannot establish
-that a request is authorized, that its values are valid, or that returned JSON has an
-application-specific shape.
+After migrating the development/test database, inspect meaningful query variants, run TypeScript,
+and test actual rows and effects. Keep those checks in CI. Execution assertions cover values, nulls,
+JSON, authorization, and rollback that description alone cannot establish.
 
 ## Reuse or assemble parts of SQL when needed
 
-For fixed conditions, write them directly:
-
-```ts
-const users = await db.query(
-  sql<UserSummary>`SELECT id, email FROM public.users WHERE active = ${true}`,
-  { returns: 'many' },
-);
-```
-
 A fragment is a piece of SQL that carries its bound values with it. It is useful when multiple
 queries share a condition. For example, a search can use the same predicate for its result page and
 its count:
 
 ```ts
+const pattern = '%example%';
+const limit = 20;
 const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
 const page = sql<UserSummary>`SELECT id, email FROM public.users
   WHERE ${search} ORDER BY id LIMIT ${limit}`;
@@ -230,8 +209,8 @@ const count = sql<{ count: string }>`SELECT count(*) AS count FROM public.users
   WHERE ${search}`;
 ```
 
-Here `pattern` is an application-supplied search pattern and `limit` is a validated page size.
-Execute each query with `db.query`. The complete query supplies the result type.
+Execute each query with `db.query`. Validate application-supplied patterns and page sizes before
+building queries. The complete query supplies the result type.
 
 Use `sql.join` when the number of fragments varies, such as one search condition per word or a set
 of optional filters. It combines fragments with `'AND'`, `'OR'`, or `','` and preserves their bound
@@ -248,10 +227,20 @@ const query = sql<UserSummary>`SELECT id, email FROM public.users
   WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
 ```
 
-This matches active users whose email contains every term. With no terms, the active condition
-still applies. The list must be nonempty; `join` inserts separators, so use parentheses as usual
+This matches active users whose email contains every term. With no terms, the active condition still
+applies. For an entirely optional set of filters, omit the whole `WHERE` clause when the list is
+empty:
+
+```ts
+const optionalFilters = terms.map((term) => sql.fragment`email ILIKE ${'%' + term + '%'}`);
+const unfilteredOrMatching = optionalFilters.length
+  ? sql<UserSummary>`SELECT id, email FROM public.users WHERE ${sql.join(optionalFilters, 'AND')} ORDER BY id`
+  : sql<UserSummary>`SELECT id, email FROM public.users ORDER BY id`;
+```
+
+`sql.join` and fragments require nonempty input. Keep mandatory authorization predicates in the
+initial list when applicable; an empty optional-filter list must not remove them. Use parentheses
 when mixing `AND` and `OR`. See the [composition reference](reference.md#sql-fragments-and-joins).
 
-For arrays, identifiers, type mappings, CLI options, and error behavior, use the
-[reference](reference.md). You do not need fragments or a query builder to use PostgreSQL joins,
-aggregates, upserts, or other SQL features.
+Use fixed SQL when composition is unnecessary. See the [reference](reference.md) for arrays,
+identifiers, value mappings, CLI options, and error behavior.