@kequtech/tenon-orm 0.2.1 → 0.2.2

package/docs/agent-guide.md

@@ -1,35 +1,26 @@
 # 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 Postgres.js. 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 +30,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.
+`connection` accepts a URI string, `{ url, options? }`, Postgres.js options, or an existing driver
+client. Reuse an instance for each database configuration. `db.close()` ends internally created
+pools with a default 5,000 ms grace period; supplied clients 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).
 
-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.
-
-## Query contracts
+## Query and result contracts
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
@@ -59,211 +46,115 @@ 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, input: { id: number }) {
-  return client.query(userByIdQuery(input), { returns: 'oneOrNone' });
+function userById(client: QueryClient, { id }: { id: number }) {
+  return client.query(sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`, {
+    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 array with `.count`, `.command`, `.columns` | 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:
-
-```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}`;
-```
-
-`pattern` and `limit` are validated application inputs. See the
-[composition reference](reference.md#sql-fragments-and-joins) for grouping and list examples.
-
-## Object-based writes
+- Interpolate values without quotes. Do not author `$n` placeholders inside templates.
+  `undefined` bound values fail; `null` means SQL null.
+- 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.
 
-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 fragments for actual reuse or variable composition. Keep fixed structure in SQL, and retain
+mandatory authorization predicates when optional filters are absent.
 
-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).
+## Writes and generated values
 
-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).
+`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,533-parameter limit.
 
-## Inspect and test completed queries
+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).
 
-Inspection ships with Tenon and needs no additional setup:
+Pass native JSON objects/arrays rather than pre-serialized text. Bigint and numeric reads are
+strings; bigint writes accept `string | bigint`. Dates read as `Date`, including invalid dates for
+infinities; validate before using date methods. SQL NULL array elements are JavaScript null.
+Keep domain validation at the persistence boundary. See [value mappings](reference.md#generated-types-and-checking).
 
-```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
-```
-
-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.
+## Transactions and native access
 
-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:
+For an existing user with id 42:
 
 ```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);
+await db.transaction(async (tx) => {
+  await tx.query(sql`UPDATE public.users SET active = false WHERE id = ${42}`, {
+    affectedRows: { exact: 1 },
+  });
+});
 ```
 
-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.
+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.
 
-## Transactions and writes
+`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.
 
-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.
+`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 clients through `db.close()`. Follow
+the [native access contract](reference.md#native-driver-access) for parser initialization and LISTEN
+limitations. Optional `onQuery` reports completion metadata without SQL or values; success inside
+a callback does not establish that the outer transaction committed.
 
-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_`.
+## Inspect and validate
 
-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`.
+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; custom
+parsers, temporary tables, and transaction-local state are not inherited. Result nullability is
+unknown and JSON structure is unchecked. A successful description does not verify `sql<Row>`,
+bound values, execution permission, or effects.
 
-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.
+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

@@ -4,9 +4,9 @@ Tenon lets you use PostgreSQL directly from TypeScript. You write SQL; Tenon bin
 executes it through Postgres.js. 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,12 @@ 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 Postgres.js client; 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
@@ -179,50 +176,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.
-
-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.
+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.
 
-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 +208,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
@@ -249,9 +227,19 @@ const query = sql<UserSummary>`SELECT id, email FROM public.users
 ```
 
 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
+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.