@kequtech/tenon-orm 0.3.1 → 0.4.2

package/docs/reference.md

@@ -1,299 +1,166 @@
-# Tenon reference
+# API and CLI reference
 
-Exact API contracts and limitations. The [human guide](human-guide.md) introduces the workflow; the
-[agent guide](agent-guide.md) covers routine implementation. Examples below use the `public.users`
-table from the human guide and an existing `db` instance, unless stated otherwise.
+For a complete first setup, follow [Getting started](human-guide.md). Task guides explain
+[queries](sql.md), [writes](mutations.md), [schema types](schema-types.md),
+[migrations](migrations.md), and [connections](connections.md).
 
 ## Installation and connection
 
-Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and Node
-development typings. Tenon includes `pg@8.23.1` and its TypeScript declarations; no driver peer or
-special compiler plugin is required. A usual Node TypeScript setup uses `module: "NodeNext"`.
+Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and Node.js
+development typings. Install `@kequtech/tenon-orm`; pgclear is included as a runtime dependency.
 
-```sh
-npm install @kequtech/tenon-orm
-```
-
-`createTenon({ connection, onQuery? })` returns a `Database` with `query`, `transaction`, `native`,
-and `close`. The required `connection` accepts:
-
-- A PostgreSQL URI string.
-- A pg `PoolConfig` object; an explicit `{}` uses the driver's environment defaults.
-- An existing `pg.Pool`, borrowed by identity.
-
-```ts
-const db = createTenon({
-  connection: {
-    connectionString: connection,
-    max: 10,
-    idleTimeoutMillis: 30_000,
-    connectionTimeoutMillis: 30_000,
-    options: '-c search_path=app,public',
-  },
-});
+```text
+createTenon({ connection, onQuery? }): Database
 ```
 
-Strings become pg's `connectionString`; configuration objects pass to `new Pool(config)`.
-`ConnectionOptions` is an alias for pg's `PoolConfig`. Driver options and defaults are unchanged,
-including no acquisition timeout unless `connectionTimeoutMillis` is configured. Pool timeouts use
-milliseconds. pg parses the URI for connection fields; matching URI values override client
-configuration, including an `options` URI parameter overriding the configuration's `options` string.
-The pool sizes and timeouts above are application choices. Configure pool policy in `PoolConfig`;
-old driver-specific URI settings such as `idle_timeout` do not configure pg's idle timeout. Preserve
-existing URI startup options when appending settings such as UTC and `search_path`.
-Preserve deployment credentials and TLS requirements; see
-[pg connection configuration](https://node-postgres.com/features/connecting).
-
-Reuse an instance for each database configuration. `db.close({ timeoutMs? })` immediately rejects
-new Tenon work. For owned pools, accepted Tenon operations can drain for up to 5,000 ms by default;
-at the deadline, remaining operations reject and Tenon requests driver termination. `0` skips the
-grace period. The timeout must be an integer from 0 to 2,147,483,647 milliseconds; `CloseOptions` is
-exported. This bounds Tenon's wait, not every native transport's teardown or server execution. It
-sends no PostgreSQL cancellation request and does not cancel JavaScript callbacks. An unbounded
-authentication attempt can keep a connection open after close resolves. Configure pg's
-`connectionTimeoutMillis` when connection establishment also needs a deadline.
-
-The first valid close call chooses the timeout. Concurrent and later calls share the same promise
-and outcome. Invalid initial options reject without closing the instance. For borrowed pools, close
-only disables the Tenon wrapper; the application retains the pool and outstanding work. Tenon does
-not load environment files.
-
-Qualify SQL names or configure runtime `search_path`. CLI `--namespace` selects tooling scope; it
-does not configure application queries. Baseline capture and Describe accept connection strings
-rather than the runtime connection union.
+`connection` is required: a PostgreSQL URI string, pgclear `PoolOptions`, or an existing pgclear
+`Pool`. `Connection` names this union; `ConnectionOptions` aliases `PoolOptions`. A supplied pool
+retains application ownership. Unknown Tenon or driver configuration options reject.
 
-## Native driver access
+The returned `Database` provides:
 
-`db.native` is the actual `pg.Pool`, readonly in TypeScript. Native calls bypass Tenon's result
-modes, affected-row guards, SQL checks, and `onQuery`. They follow pg's query configuration and do
-not join a Tenon transaction; callback clients expose only `tx.query`.
+| Member                   | Contract                                                                                 |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| `query(query, options?)` | Execute a Tenon `SqlQuery` and apply result/count options                                |
+| `transaction(callback)`  | Commit on callback success, roll back on an escaping error; return the callback's result |
+| `generateTypes(options)` | Write or check schema declarations using this instance's pool/codecs                     |
+| `native`                 | The underlying pgclear pool                                                              |
+| `close({ timeoutMs? }?)` | Disable the wrapper and close an owned pool; default grace 5,000 ms                      |
 
-Use pg's [native APIs](https://node-postgres.com/apis/pool) and compatible cursor/COPY packages when
-needed. For LISTEN, check out a client with `await db.native.connect()`, attach `notification`,
-`error`, and `end` listeners, and issue `LISTEN` on that client. Keep it checked out while listening;
-release it after `UNLISTEN`. Native queued acquisitions follow pg's shutdown behavior and must be
-settled by their caller before closing. A disconnected client does not reconnect. The application owns
-resubscription and catch-up; notifications are not replayed.
+`onQuery(event)` observes completed Tenon query calls. It may return void or a promise; it is not
+awaited. Observer failures emit warnings without changing the outcome. `QueryEvent` contains
+`durationMs`, `outcome: 'success' | 'error'`, and optional `label`, `command`, `rowCount`, and
+`errorCode`. SQL and values are excluded. Validation failures before execution are not observed.
 
-Close owned pools through `db.close()` for bounded shutdown, including checked-out native clients.
-Borrowed pools and their listeners remain usable after wrapper close until their owner ends them.
+See [connection configuration and shutdown](connections.md) for pool settings, TLS, environment
+handling, timeout bounds, and lifecycle examples. Runtime `search_path` is independent of tooling
+`namespace` options.
 
-### LISTEN lifecycle example
+### Driver updates
 
-This helper owns a dedicated single-client pool. It returns an intentional-close function only
-after LISTEN is ready. Callbacks are synchronous; notification exceptions are isolated, and an
-unexpected disconnect invalidates this generation once before notifying its consumer. Failed
-connection acquisition or LISTEN setup closes the owned resources and rejects the setup promise.
-
-```ts
-import { createTenon } from '@kequtech/tenon-orm';
-
-async function listenForChanges(
-  connectionString: string,
-  onChange: (payload: string | undefined) => void,
-  onDisconnect: (error: Error) => void,
-) {
-  const db = createTenon({
-    connection: { connectionString, max: 1, idleTimeoutMillis: 0, connectionTimeoutMillis: 30_000 },
-  });
-  const client = await db.native.connect().catch(async (error: unknown) => {
-    await db.close();
-    throw error;
-  });
-  let active = true;
-  let closing: Promise<void> | undefined;
-
-  function stop(error?: Error): Promise<void> {
-    if (closing) return closing;
-    active = false;
-    closing = Promise.resolve().then(async () => {
-      try {
-        if (error) onDisconnect(error);
-      } finally {
-        client.release(true);
-        await db.close();
-      }
-    });
-    return closing;
-  }
-
-  const failed = (error: Error) => {
-    if (active) void stop(error).catch(console.error);
-  };
-  client.on('error', failed);
-  client.on('end', () => failed(new Error('The notification connection ended.')));
-  client.on('notification', (event) => {
-    if (!active || event.channel !== 'app_changes') return;
-    try {
-      onChange(event.payload);
-    } catch (error) {
-      console.error(error);
-    }
-  });
-  try {
-    await client.query('LISTEN "app_changes"');
-    if (!active) throw new Error('The notification connection closed during setup.');
-  } catch (error) {
-    await stop();
-    throw error;
-  }
-  return () => stop();
-}
-```
-
-Both failure and intentional close discard the dedicated checkout with `release(true)` before
-closing its pool, so no UNLISTEN is needed and normal shutdown does not wait for Tenon's deadline.
-The active flag suppresses duplicate error/end callbacks and intentional-close notifications.
-Create a new helper instance to recover, and reconcile missed events through persistent data.
-
-This helper's close function is available after readiness. A manager that also supports replacement
-or shutdown while setup is pending must assign a generation token before awaiting setup. Only the
-current generation may change shared readiness/subscription state or notify its consumers. If stale
-setup later succeeds, close that setup's own listener; if it fails or finishes cleanup, leave the
-replacement alone. Invalidate the current token before intentional shutdown. Keep those guards in
-the application's subscription manager. The fixed channel above is trusted; validate and quote
-application-selected channel names before placing them in native SQL.
+The dependency range is `@kequtech/pgclear: ^0.3.0`. Compatible patches may be updated independently;
+see [driver updates](connections.md#update-the-driver). Tenon re-exports `builtin`, `json`, `param`,
+`defaultCodecs`, and `createTemporalCodecs`, with the driver's `Codec`, `CodecRegistry`, `Parameter`,
+`PgArray`, `TemporalConstructors`, and `TemporalInput` types.
 
 ## Queries and result modes
 
-`sql<Row>` creates a detached `SqlQuery<Row>` with SQL `text` and ordered `values`; it does not
-execute. `Row` declares one selected row. Without an annotation, fields are `unknown`. An annotation
-does not verify the SQL or validate returned data.
+`sql<Row>` is a template tag returning `SqlQuery<Row>` with readonly `text` and `values`. It does
+not execute. `Row` describes one selected record; without it, fields are `unknown`. Neither result
+annotations nor generated types validate data during execution.
 
-```ts
-const user = await db.query(
-  sql<{ id: number; email: string }>`SELECT id, email FROM public.users WHERE id = ${42}`,
-  { returns: 'oneOrNone', label: 'user-by-id' },
-);
-```
+`db.query` and `tx.query` accept `{ returns?, affectedRows?, label? }`. Unknown options reject.
+A supplied label must be a nonblank string.
 
-`query` options are `{ returns?, affectedRows?, label? }`; unknown keys fail. A supplied `label`
-must be a nonempty string.
+| `returns`          | Output             | Allowed returned rows |
+| ------------------ | ------------------ | --------------------- |
+| `native` (default) | `QueryResult<Row>` | Any                   |
+| `many`             | `readonly Row[]`   | Any                   |
+| `oneOrNone`        | `Row \| undefined` | Zero or one           |
+| `one`              | `Row`              | Exactly one           |
 
-| `returns`          | Output                           | Allowed returned rows |
-| ------------------ | -------------------------------- | --------------------- |
-| `native` (default) | `QueryResult<Row>` driver object | Any                   |
-| `many`             | Plain `Row[]`                    | Any                   |
-| `oneOrNone`        | `Row \| undefined`               | Zero or one           |
-| `one`              | `Row`                            | Exactly one           |
+`QueryResult` follows pgclear and includes `rows`, `rowCount`, `command`, `commandTag`, and `fields`.
+`rowCount` is `number | null`, independent of `RETURNING`; unsafe integer counts reject. SQL
+`count(*)` is a column value and defaults to string. Row arrays are readonly.
 
-Native results expose `rows`, `rowCount`, `command`, and `fields`, following pg's `QueryResult`.
-`rowCount` is the command's affected-row count, independent of `RETURNING`; it can be null for
-commands without a count. Result modes never add `LIMIT` or `RETURNING`. A returned-row mismatch
-alone does not undo an autocommitted write; use `affectedRows` for write bounds that roll back.
+Modes do not add `LIMIT` or `RETURNING`. Returned-row mismatches throw `CardinalityError`; alone,
+that does not undo an autocommitted write. For write bounds that roll back, use `affectedRows`.
 
-Functions accepting `QueryClient` can use either `Database` or `Transaction`. Public types also
-include `QueryOptions`, `QueryReturnMode`, and `QueryOutput<Row, Mode>`.
+`QueryClient` is the query-only interface accepted by either a `Database` or callback `Transaction`.
+Other exported types include `QueryOptions`, `QueryReturnMode`, `QueryOutput<Row, Mode>`,
+`SqlQuery`, `SqlFragment`, and `UnknownRow`.
 
 ### Adapting transactional results
 
-For a job library or other adapter expecting `{ rows }`, extract the native result's row array:
+For an adapter expecting `{ rows }`, execute its trusted SQL through the callback's `tx`:
 
 ```ts
 import { unsafeSql, type QueryClient } from '@kequtech/tenon-orm';
 
 async function queryRows(tx: QueryClient, text: string, values: readonly unknown[]) {
   const result = await tx.query(unsafeSql(text, values));
-  return { rows: result.rows };
+  return { rows: [...result.rows] };
 }
 ```
 
-Alternatively, request `{ returns: 'many' }` and wrap the returned array in `{ rows }`. Supply the
-callback's `tx` when the adapter's work must commit with application writes. A native pool query
-uses a separate checkout and does not join that transaction. Await adapter calls before returning
-from the callback, retain commit/rollback tests, and make recording helpers return pg-shaped native
-results. The adapter's SQL text must be trusted and values must remain separately bound.
+The copy supplies a mutable array if the adapter requires one. Values must already be valid driver
+inputs; external arrays/objects need type-aware `param`, `json`, or text encoding. Await adapter
+work inside the callback. Native pool queries use another checkout and do not join it.
+
+For a job-library transaction adapter such as pg-boss's, verify actual SQL inputs and timestamp
+expectations. Enqueueing and returning an ID may need no output conversion; returned timestamps
+follow the database-wide codecs. Keep atomic commit/rollback tests. Tenon provides no per-query
+codec override, and input encoders are independent of output codecs.
 
 ## SQL parameters and identifiers
 
-Ordinary `sql` interpolations bind values. Do not quote them or write manual `$n` placeholders
-inside templates. Values follow pg serialization: `null` and `undefined` bind as SQL null, arrays
-bind as PostgreSQL arrays, and objects use pg's JSON serialization. For JSON input, use
-`JSON.stringify(value)`, including for JSON arrays, strings, and JSON null. Generated JSON write
-types accept encoded strings. Cast standalone parameters when SQL must establish their type.
+| API                            | Contract                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------ |
+| `sql<Row>` template tag        | Bind ordinary values; interpolate Tenon fragments and identifiers structurally |
+| `identifier(...names)`         | Quote components separately, e.g. `"public"."users"`                           |
+| `unsafeSql<Row>(text, values)` | Trusted external SQL with an explicit values array, including `[]`             |
+| `json(value, type?)`           | Encode JSON; default type is jsonb                                             |
+| `param(value, codec, format?)` | Choose an explicit driver parameter type and encoder                           |
 
-```ts
-const ids = [1, 2, 3];
-const query = sql<{ id: number }>`SELECT id FROM public.users
-  WHERE id = ANY(${ids}::integer[])`;
-```
+Do not quote interpolations or mix manual `$n` placeholders into templates. Plain binds accept null,
+string, finite number, bigint, boolean, valid Date, supported Temporal values, and Uint8Array.
+Undefined, plain objects/arrays, nonfinite numbers, and unsafe integer numbers reject.
 
-`identifier(schema, table)` quotes components separately. Names must contain 1–63 UTF-8 bytes and no
-NUL. Choose application-approved names; quoting does not authorize access. SQL syntax such as `DESC`
-belongs in fixed query alternatives or fragments, not a string parameter.
+Strings, numbers, bigint, Date, and supported Temporal values use server type inference. Date
+encodes in UTC. Cast standalone parameters when PostgreSQL needs type context. Use `json` for JSON
+and `param` for PostgreSQL arrays/custom encodings. Do not mutate bound values before settlement.
 
-`unsafeSql<Row>(text, values)` accepts trusted external SQL and an explicit values array, including
-`[]`. Never concatenate request input into its text. Full `sql` and `unsafeSql` queries cannot be
-nested; use fragments for partial SQL.
+Identifier components require 1–63 UTF-8 bytes and no NUL. Choose approved names; quoting is not
+authorization. SQL syntax such as `DESC` belongs in fixed fragments or query alternatives. Never
+concatenate request input into `unsafeSql` text.
 
-Each Tenon query executes one statement through the extended protocol. Application execution uses
-unnamed queries without a `name` or prepared-statement cache. Values remain bound separately.
-Migrations deliberately support multi-statement scripts.
+A query executes one statement through the extended protocol. Tenon does not expose a prepared
+statement cache or query `name` option. See [writing queries](sql.md) for examples.
 
 ## SQL fragments and joins
 
-`sql.fragment` creates immutable partial SQL with bound values. It has no row type, cannot execute
-alone, and rejects blank SQL. Insert it into a complete `sql<Row>` query.
+- `sql.fragment` creates immutable partial SQL with bound values. It has no row type and
+  cannot execute alone. Blank fragments reject.
+- `sql.join(fragments, 'AND' | 'OR' | ',')` requires a nonempty array of fragments. It does not add
+  parentheses or alter precedence.
+- Nested/repeated fragments preserve ordered parameters. Full `sql`/`unsafeSql` queries cannot be
+  nested. Literal `$1` text in SQL strings/comments is not rewritten.
 
-`sql.join(fragments, separator)` requires a nonempty list. Separators are `'AND'`, `'OR'`, and
-`','`. It does not add parentheses or change SQL precedence. Each fragment use receives correctly
-ordered parameters, including repeated and nested uses; literal `$1` text in strings/comments is
-unchanged.
+See [composition examples](sql.md#compose-sql-fragments), including the empty-filter case.
 
-```ts
-const email: string | undefined = 'reader@example.test';
-const conditions = [sql.fragment`active = ${true}`];
-if (email !== undefined) conditions.push(sql.fragment`email = ${email}`);
-const query = sql<{ id: number }>`SELECT id FROM public.users
-  WHERE ${sql.join(conditions, 'AND')} ORDER BY id`;
+## Object-based mutation fragments
+
+```text
+sql.insertValues<Input>(rowOrRows, columns?): SqlFragment
+sql.assignments<Input>(patch, columns?): SqlFragment
 ```
 
-The mandatory predicate keeps the list nonempty. If every filter is optional, choose a complete
-query without `WHERE` for the empty case. Group mixed `AND`/`OR` expressions explicitly.
+These build fragments, not complete statements. Keep table, predicates, expressions, conflict
+behavior, and `RETURNING` in authored SQL.
 
-## Object-based mutation fragments
+| Cell                          | Insert          | Assignment      |
+| ----------------------------- | --------------- | --------------- |
+| Missing or undefined          | `DEFAULT`       | Omitted         |
+| Null                          | Bound SQL NULL  | Bound SQL NULL  |
+| Other accepted value          | Bound parameter | Bound parameter |
+| SQL fragment/identifier/query | Rejected        | Rejected        |
 
-`sql.insertValues(input, columns?)` and `sql.assignments(input, columns?)` return fragments. Keep
-operation, table, predicates, expressions, conflict policy, and `RETURNING` in SQL:
+Inputs must be plain objects, including null-prototype objects. Only own data properties are read;
+selected accessors reject. Helpers capture fields at construction; mutable bound values must remain
+unchanged until execution settles.
 
-```ts
-const query = sql<{ id: number }>`INSERT INTO public.users
-  ${sql.insertValues({ email: 'reader@example.test' })} RETURNING id`;
-await db.query(query, { returns: 'one' });
-await db.query(sql`UPDATE public.users SET ${sql.assignments({ active: false })} WHERE id = ${42}`);
-```
+Without `columns`, inserts infer the union of enumerable keys with defined values in first-seen
+order. Assignments use own enumerable keys and omit undefined values. Explicit columns must be
+nonempty, unique, and valid identifiers; they select/order keys and ignore unlisted properties.
+TypeScript checks selected names against known input keys. Selection can discard required values.
 
-Both accept plain objects, including null-prototype objects. Columns are quoted as individual
-identifiers. Only own data properties are read; accessors are rejected. Fields are captured at
-fragment construction; nested objects retain ordinary driver serialization behavior.
-
-| Input                                        | Insert                 | Assignment      |
-| -------------------------------------------- | ---------------------- | --------------- |
-| Missing or `undefined`                       | `DEFAULT` for the cell | Omitted         |
-| `null`                                       | Bound SQL null         | Bound SQL null  |
-| Other value                                  | Bound parameter        | Bound parameter |
-| SQL fragment, identifier, or query as a cell | Rejected               | Rejected        |
-
-Inserts accept one object or an array. Without `columns`, they infer the union of enumerable keys
-with defined values in first-seen order. Heterogeneous rows stay aligned. A single default-only row
-emits `DEFAULT VALUES`. Empty batches fail; multiple default-only rows need explicit columns.
-Assignments omit undefined values and fail when no assignments remain, even if surrounding SQL has
-other assignments.
-
-A supplied column list must be nonempty, unique, and valid. It selects and orders fields, ignoring
-unlisted keys. Missing insert cells use defaults; missing update fields are omitted. TypeScript
-checks selected names against known input keys, but selection can still discard required fields.
-Helpers have no schema metadata; PostgreSQL enforces identity, generated-column, and constraint
-rules. Use [generated inputs](#insert-and-update-inputs) and application validation.
-
-Write arithmetic, `column = DEFAULT`, and `excluded.column` in the surrounding SQL. There is no
-expression/default sentinel. A complete query accepts at most 65,535 bound parameters, including
-surrounding interpolations; Tenon does not split batches. See the [mutation cookbook](mutations.md).
+A single default-only insert emits `DEFAULT VALUES`. Empty batches reject; multiple default-only
+rows need explicit columns. Empty assignments always reject. There is no expression/default
+sentinel; author `column = DEFAULT` or arithmetic in SQL. The complete query's limit is 65,535
+parameters; Tenon does not split batches. See [writing data](mutations.md).
 
 ## Transactions, guarded writes, and errors
 
-For an existing user with id 42:
-
 ```ts
 await db.transaction(async (tx) => {
   await tx.query(sql`UPDATE public.users SET active = false WHERE id = ${42}`, {
@@ -302,239 +169,167 @@ await db.transaction(async (tx) => {
 });
 ```
 
-Use `tx` for every operation that must commit together and await the work. The callback commits on
-success, rolls back on an escaping error, and expires before cleanup. Transactions belong to one
-database instance. Nested callbacks and automatic retries are not provided. Tenon owns direct
-BEGIN/COMMIT/ROLLBACK boundaries.
+Use `tx` for every participating query and await all work. The callback commits on success, rolls
+back on an escaping error, and its client expires when the callback finishes. Transactions belong
+to one database instance. Calling the root `db` uses the pool, not the callback session.
 
-`affectedRows: { exact: n }` or `{ max: n }` accepts a nonnegative safe integer. It checks the final
-INSERT/UPDATE/DELETE/MERGE count independently of `RETURNING`. A guarded root call uses a
-transaction; a guarded callback call uses a savepoint. Failed checks and other errors from that
-guarded operation roll it back before throwing. A caught guarded failure permits continued work;
-unguarded SQL errors normally abort the transaction.
+Tenon owns BEGIN/COMMIT/ROLLBACK; direct boundary statements are rejected. `tx` provides no nested
+transaction method. Manual savepoints are supported on the callback session. To choose isolation,
+issue `SET TRANSACTION ISOLATION LEVEL SERIALIZABLE` before data queries; use
+`SET LOCAL statement_timeout = '5s'` to bound statements in that transaction.
 
-Counts exclude extra trigger/cascade and CTE effects and cannot identify the wrong single row.
-Sequence advances and external effects are not reversible. A lost commit acknowledgment can leave
-the outcome unknown; applications own retry and idempotency policy.
+A write guard is exactly one of `{ exact: n }` or `{ max: n }`, with a nonnegative safe integer.
+It checks the final INSERT/UPDATE/DELETE/MERGE count, independently of `RETURNING`:
 
-Set isolation before data queries with `SET TRANSACTION ISOLATION LEVEL SERIALIZABLE`, and use
-`SET LOCAL statement_timeout = '5s'` to bound statements in that transaction. Manual savepoints are
-supported; reserve names beginning with `tenon_affected_rows_` for Tenon.
+| Call                                | Guard behavior                                                               |
+| ----------------------------------- | ---------------------------------------------------------------------------- |
+| `db.query(query, { affectedRows })` | Wrap in a transaction; roll back the operation on a guard/result/SQL failure |
+| `tx.query(query, { affectedRows })` | Wrap in a savepoint; roll back that operation before rejecting               |
 
-SQL errors retain native driver details. Invalid inputs throw ordinary `Error` objects.
-`CardinalityError` has code `TENON_CARDINALITY_MISMATCH`, `expected` (`one` or `oneOrNone`),
-`actual` (returned row count), and optional `label`. It does not change transaction or autocommit
-behavior. `AffectedRowsError` carries `expected`, `actual`, `command`, and code
-`TENON_AFFECTED_ROWS_MISMATCH` or `TENON_AFFECTED_ROWS_UNSUPPORTED`. Work/cleanup failures can
-produce `AggregateError`.
+A caught guarded failure permits continued work. An unguarded PostgreSQL error normally leaves the
+transaction aborted; let it escape so the callback rolls back. Tenon serializes whole guarded
+operations within a transaction, including savepoint handling.
 
-Optional `onQuery` observes completed calls with `label`, `durationMs`, `outcome`, and available
-`command`, `rowCount`, and `errorCode`. It receives no SQL or values. Validation failures before
-execution are not observed. Observers are not awaited; failures emit warnings without changing the
-query outcome. Query success inside a callback does not establish outer commit.
+Counts exclude extra trigger/cascade and CTE effects and cannot identify the wrong single row.
+Sequence advances and external effects may survive rollback. There are no automatic retries. A lost
+COMMIT acknowledgment can leave the outcome unknown; the application owns retry/idempotency policy.
 
-## Generated types and checking
+| Error                               | Code and fields                                                                                                                 |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `CardinalityError`                  | `TENON_CARDINALITY_MISMATCH`; `expected` (`one` or `oneOrNone`), `actual` returned rows, optional `label`                       |
+| `AffectedRowsError`                 | `TENON_AFFECTED_ROWS_MISMATCH` or `TENON_AFFECTED_ROWS_UNSUPPORTED`; `expected` constraint, `actual: number \| null`, `command` |
+| Tenon option/composition validation | Ordinary `Error`                                                                                                                |
+| Driver/server failure               | Native details, including driver `PGCLEAR_*` codes or PostgreSQL SQLSTATE                                                       |
+| Work and cleanup both fail          | May be an `AggregateError`                                                                                                      |
 
-`generateDefinitions({ connection, namespace?, onWarning? })` returns TypeScript declarations from a
-consistent read-only snapshot; it does not need migration files or history. The CLI writes them
-atomically. Default namespace is `public`; default output is `src/generated-schema.ts`. Both `.ts`
-and `.d.ts` outputs are supported. Commit exact output and exclude it from formatting.
+Use codes and structured fields rather than matching message text. Retain unexpected failures.
 
-```sh
-npx tenon generate --out src/generated-schema.d.ts
-npx tenon generate --out src/generated-schema.d.ts --check
+## Generated types and checking
+
+```text
+db.generateTypes({ out, namespace?, check?, onWarning? }): Promise<void>
+generateDefinitions({ connection, namespace?, onWarning? }): Promise<string>
 ```
 
-`--check` never rewrites the file. Missing/stale output fails with a diagnostic and a short diff for
-changes. It compares the generated representation, not pending migrations or every database object.
-Output includes relation/constraint/index summaries and referenced domains, not function bodies,
-grants, or a complete schema fingerprint.
-
-**Generated declarations are not a version-stable schema fingerprint.** TypeScript mappings can
-change without schema drift. The schema-summary comments describe SQL column types, defaults,
-constraints, indexes, and referenced domains independently of those mappings, but their formatting
-and PostgreSQL's rendering of definitions are not a versioned comparison contract either. Preserve
-reviewed generator-specific references if an existing guard hashes this output; see
-[baseline verification](adoption-guide.md#check-and-adopt-an-existing-database).
-
-Generation covers ordinary tables and partitioned roots. Views, foreign tables, and attached
-partitions need query-specific types. A missing namespace fails; an existing empty schema is valid.
-Exact table names are available through `Rows['users']`; valid nonreserved identifiers also receive
-named aliases. Use `Pick` for projections; a join or aggregate needs its actual selected shape.
-
-| PostgreSQL type                                | Read representation  | Generated write input                 |
-| ---------------------------------------------- | -------------------- | ------------------------------------- |
-| smallint, integer, oid, real, double precision | `number`             | `number`                              |
-| bigint                                         | `string`             | `string \| bigint`                    |
-| numeric                                        | `string`             | `string \| number`                    |
-| boolean                                        | `boolean`            | `boolean`                             |
-| text, name, varchar, char, uuid, time, timetz  | `string`             | `string`                              |
-| date, timestamp, timestamptz                   | `Date \| number`     | `Date \| string`                      |
-| enum                                           | String literal union | Same union; `never` for an empty enum |
-| json, jsonb                                    | `unknown`            | `string` containing encoded JSON      |
-| bytea                                          | `Buffer`             | `Buffer`                              |
-
-Nullable columns add null; `unknown` already includes it. Domains retain verified base mappings and
-the column's read nullability. Verified arrays use `PgArray<T> = (T | null | PgArray<T>)[]` for null
-elements and multiple dimensions. Numeric arrays contain numbers and can lose precision; select/cast
-them as text when exact values are required. Bigint arrays contain strings; enum arrays and arrays
-of domains are unverified. Unmapped types warn and use `unknown` reads / `never` non-null writes.
-Custom parsers need matching application types.
-
-Date-only values and timestamps without time zone use Node's local timezone. Infinite temporal reads
-are numbers (`Infinity` or `-Infinity`); narrow with `value instanceof Date` before date methods.
-Temporal write inputs accept `Date | string`; use PostgreSQL's text `infinity` or `-infinity` when
-needed.
+`out` is required for file generation. Namespace defaults to `public`; `check` defaults to false.
+Generation inherits the database registry. Missing/stale output rejects under `check: true` without
+writing. See [schema types and values](schema-types.md) for file guarantees, generated shapes,
+value mappings, codecs, and domain validation. The standalone `tenon generate` command was removed;
+use an application script.
 
-### Persistence and domain values
+### Application aliases
 
-Generated types describe storage representations. Text `CHECK` constraints do not become unions, and
-JSON reads remain unknown. Validate values before narrowing to application domain types.
+Export aliases such as `UserRow = Database['users']['row']` in a handwritten file. See
+[application aliases](schema-types.md#application-aliases).
 
-For example, assume this additional table and regenerate `Rows` from the resulting schema:
+### Persistence and domain values
 
-```sql
-CREATE TABLE public.sessions (
-  id text PRIMARY KEY,
-  data jsonb NOT NULL,
-  expires_at timestamptz NOT NULL
-);
-```
+Generated types describe storage representations. Validate JSON, text refinements, and domain
+values at the application boundary; see [the worked example](schema-types.md#persistence-and-domain-values).
 
-Use the same application validator before encoding a write and when restoring a domain value:
+### Insert and update inputs
 
-```ts
-import { sql } from '@kequtech/tenon-orm';
-import type { Rows } from './generated-schema.js';
-
-function sessionData(value: unknown): { userId: string } {
-  if (
-    typeof value !== 'object' ||
-    value === null ||
-    Array.isArray(value) ||
-    !('userId' in value) ||
-    typeof value.userId !== 'string' ||
-    value.userId.length === 0
-  ) {
-    throw new Error('Expected session data with a nonempty userId');
-  }
-  return { userId: value.userId };
-}
+Generated types account for defaults, identity/computed columns, domains, and nullability. See
+[insert/update rules](schema-types.md#insert-and-update-inputs).
 
-function finiteDate(value: Date | number): Date {
-  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
-    throw new Error('Expected a finite database timestamp');
-  }
-  return value;
-}
+## Choosing a validation tool
 
-const input = {
-  id: 'example-session',
-  data: JSON.stringify(sessionData({ userId: 'user-42' })),
-  expires_at: new Date(Date.now() + 60_000),
-} satisfies Rows.Insert['sessions'];
-await db.query(sql`INSERT INTO public.sessions ${sql.insertValues(input)}`);
-
-const row = await db.query(
-  sql<Rows['sessions']>`SELECT id, data, expires_at FROM public.sessions
-    WHERE id = ${input.id} AND isfinite(expires_at) AND expires_at > now()`,
-  { returns: 'oneOrNone' },
-);
-const session =
-  row === undefined
-    ? undefined
-    : {
-        id: row.id,
-        data: sessionData(row.data),
-        expiresAt: finiteDate(row.expires_at),
-      };
-```
+Use the intended development/test schema and role. TypeScript itself needs no connection.
 
-The generated JSON read remains `unknown` and the timestamp remains `Date | number`. The projection
-validates both without assertions or edits to generated types. Preserve null separately for nullable
-columns. For an authentication policy requiring finite expiry, `isfinite(expires_at)` excludes both
-infinities before the expiry comparison; `expires_at > now()` alone would accept positive infinity.
-Include such predicates in expiry-sensitive updates/deletes too, and test infinite and expired
-values. This example illustrates representation validation; applications must also retain their
-token verification, revocation, and authorization checks. See
-[JSON and PostgreSQL arrays](mutations.md#json-and-postgresql-arrays) for array write boundaries.
+| Tool                                     | Question answered                                                              | Main limit                                                      |
+| ---------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `tsc --noEmit`                           | Does application code satisfy TypeScript contracts?                            | Does not inspect SQL/schema                                     |
+| `tenon check [file.ts[:line]]`           | Does recoverable SQL contradict declared input/result types?                   | Unsupported sites fail; inconclusive properties remain unproven |
+| `tenon describe query.sql`               | What metadata does PostgreSQL report for finished SQL?                         | Does not compare annotations or bind values                     |
+| `db.generateTypes({ out, check: true })` | Does committed output match generation now?                                    | Does not check queries or replace migration status              |
+| Database tests                           | Do exercised queries produce correct rows, effects, permissions, and rollback? | Cover only tested inputs and paths                              |
 
-Bigint and `count(*)` reads are decimal strings. Use SQL or BigInt for exact arithmetic and decimal
-strings at JSON boundaries; convert to number only when bounded or approximate values are intended.
+After schema changes, migrate the test database, regenerate/review declarations, and run typechecks,
+applicable source checks, and database tests. In CI, check generated output without replacing it.
+Source checking and inspection parse/analyze application SQL without executing it; analysis can
+take locks. Neither proves actual bound values or write effects.
 
-### Insert and update inputs
-
-```ts
-import type { Rows } from './generated-schema.js';
+## Source-aware checking
 
-const input: Rows.Insert['users'] = { email: 'reader@example.test' };
-const patch: Pick<Rows.Update['users'], 'active'> = { active: false };
-sql.insertValues(input);
-sql.assignments(patch);
-```
+`checkQueries(options)` is exported from `@kequtech/tenon-orm/check`, alongside its public types.
+The bundled TypeScript compiler loads only through that path or the check command.
 
-Insert fields are required when nonnullable, writable, and without a default. Other writable insert
-fields and all writable update fields are optional and accept explicit undefined, including with
-`exactOptionalPropertyTypes`. Explicit null requires both column and domain-chain permission. Domain
-defaults count; column defaults take precedence.
+Options are `{ connection, target?, project?, session?, timeouts?, codecs?, readTypes? }`.
+Connection is a URI. The report contains `ok`, `project`, `queries`, `diagnostics`, and available
+inspection `context`. Mismatches, unchecked sites, and no sites fail; unproven findings alone do not.
+See [query checking](query-checking.md) for selection, supported composition, and custom decoders.
 
-Computed and `GENERATED ALWAYS` identity columns use optional `never` fields. Serial and
-`GENERATED BY DEFAULT` identities are optional on insert and writable on update; other primary keys
-remain writable. Use `Pick`/`Omit` for application restrictions. Apply the generated types through
-annotations, `satisfies`, or helper generic arguments; they do not validate constraints, JSON
-structure, authorization, or nonempty input.
+## Query inspection
 
-For unverified write mappings, provide a reviewed application-owned replacement, for example
-`Omit<Rows.Insert['events'], 'delay'> & { delay: string }` for interval text input. Selected columns
-can discard required fields; see [the cookbook](mutations.md#input-types-and-runtime-validation).
+```text
+describeQuery({ connection, query, session?, timeouts?, codecs? }): Promise<QueryDescription>
+```
 
-## Query inspection
+Connection is a URI; query is finished SQL text or `{ text, parameterTypes? }`. A `SqlQuery` fits
+because it has `text`; values and its row annotation are not checked. The report includes
+`parameters`, `columns`, `rowType`, `issues`, and `context`. It uses a separate session with bounded
+timeouts. See [query inspection](query-inspection.md) for fields and finding codes.
 
-`describeQuery({ connection, query, session?, timeouts? })` accepts a PostgreSQL URI and a finished
-SQL string or `{ text }` object. It returns PostgreSQL metadata, conservative read mappings and row
-declaration, session context, and coded findings. It does not bind values, execute the statement, or
-verify `sql<Row>`.
+## Native driver access
 
-Inspection owns a separate session with bounded timeouts. Match runtime settings; temporary tables,
-and uncommitted changes are not inherited. Reported mappings assume pg's default parsers; parser
-overrides need matching application types. Nullability stays unknown. See
-[query inspection](query-inspection.md) for settings, result fields, issue codes, and testing.
+`db.native` is the actual pgclear pool. Calls bypass Tenon's guards and observations and do not join
+callback transactions. Use `queryClassic` for text; native `query` accepts only pgclear's own SQL
+tag. See [native driver features](connections.md#use-native-driver-features) for session ownership,
+prepared statements, and dedicated notification listeners.
+
+## Troubleshooting
+
+| Symptom                                      | Response                                                                                                                                                     |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `DATABASE_URL is required`                   | Supply the variable to CLI commands. No `.env` files are loaded automatically. Application configuration is explicit.                                        |
+| `PGCLEAR_ENCODE`                             | Check inputs: objects/arrays need `json`/`param`; direct undefined, unsafe integers, nonfinite numbers, and invalid Dates reject. JSON still rejects bigint. |
+| `CardinalityError`                           | Check the expected row count and predicate. To choose one of several rows, author deterministic `ORDER BY ... LIMIT 1`.                                      |
+| `TENON_AFFECTED_ROWS_MISMATCH`               | The guarded operation rolled back. Inspect `actual` and the predicate; retain the intended bound.                                                            |
+| `TENON_AFFECTED_ROWS_UNSUPPORTED`            | The final command lacks a supported write count. Use guards on INSERT/UPDATE/DELETE/MERGE; result modes check returned rows.                                 |
+| Empty assignments                            | All selected fields were missing/undefined. Skip the update or branch to an expression-only statement.                                                       |
+| Duplicate result columns                     | Alias columns uniquely, especially in joins. The driver rejects duplicate object keys.                                                                       |
+| SQLSTATE `42P18` / `42P08` during inspection | Add the intended parameter cast or Describe OID hints. Inspection binds no values.                                                                           |
+| Checker reports `unchecked`                  | Follow the diagnostic. Runtime fragments and optional patches can execute correctly yet remain unsupported by source recovery.                               |
+| Missing/stale generated output               | Check schema, namespace, registry, driver version, and path. Regenerate, review, and commit intended output.                                                 |
+| Migration history conflict                   | Restore original applied files. Add new changes in a forward migration. Checksums include down SQL too.                                                      |
+| Tooling lock wait                            | Check concurrent migration/DDL work, use direct or session pooling, and configure server timeouts.                                                           |
+
+After a guarded query rejects, savepoint cleanup has finished. An unguarded server error normally
+aborts a transaction. A timeout or lost connection does not itself establish whether a commit
+happened; review the transaction contract before adding retries.
 
 ## Command reference
 
-Database commands require `DATABASE_URL`. `new` and `--help` work offline. No environment files are
-loaded. Paths are relative to the working directory. Explicit flags unsupported by a command are
-rejected; `--check` is only a generation check, not a migration dry run.
+All database commands read `DATABASE_URL`. `new` and `--help` work offline. No environment files
+are loaded. Paths resolve from the working directory; unsupported command flags reject.
 
 ```text
 tenon new <name> [--directory migrations]
 tenon migrate [--directory migrations] [--namespace public]
 tenon status [--directory migrations] [--namespace public]
 tenon rollback [--directory migrations] [--namespace public] [--steps 1]
-tenon generate [--namespace public] [--out src/generated-schema.ts] [--check]
-tenon describe <query.sql> [--role name] [--search-path value] [--time-zone value]
-  [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
 tenon baseline capture [--directory migrations] [--namespace public] [--schema name ...]
 tenon baseline adopt [--directory migrations] [--namespace public]
+tenon check [file.ts[:line]] [--project tsconfig.json] [--json]
+  [--role name] [--search-path value] [--time-zone value]
+  [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
+tenon describe <query.sql> [--role name] [--search-path value] [--time-zone value]
+  [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
 ```
 
-`new` scaffolds empty `<numeric-id>_<name>.up.sql` and `.down.sql` files. Names contain letters,
-digits, underscores, or hyphens. Fill both files or remove the down file for an irreversible change.
-IDs sort numerically. Never edit applied files: checksums cover up and down SQL.
-
-Each migration and history entry commits together; earlier files remain applied if a later one
-fails. Runner search path is the selected namespace followed by `pg_catalog`. `status` returns
-applied/pending IDs as JSON and rejects history conflicts. `rollback` validates that every selected
-file has down SQL before executing any; `steps` is a positive safe integer. Use dollar-quoted
-function bodies and explicit `E'...'` backslash escapes. Nontransactional DDL such as
-`CREATE INDEX CONCURRENTLY` requires a separate procedure.
-
-Migration/status/rollback/adoption use session advisory locks per database and namespace; generation
-uses the same lock in shared mode. Use direct or session-pooled connections and server timeouts to
-bound waits. Baseline capture uses a local creation lock and native `pg_dump`; it does not acquire
-the runner's database advisory lock. See [adoption](adoption-guide.md).
-
-Programmatic `migrate`, `migrationStatus`, and `rollback` accept
-`{ connection, directory?, namespace? }`; rollback also accepts `steps`. Migration/rollback return
-completed IDs. `createMigration({ name, directory? })` returns `{ id, upPath, downPath }`;
-`readMigrations(directory?)` returns validated SQL and checksums.
+| Command                | Output and behavior                                               |
+| ---------------------- | ----------------------------------------------------------------- |
+| `new`                  | Paths of the new empty up/down pair; fill before applying         |
+| `migrate` / `rollback` | Completed IDs or “nothing to do”; each file commits independently |
+| `status`               | JSON `{ applied, pending }`; validates history                    |
+| `baseline capture`     | Writes a reviewed schema-only baseline using native `pg_dump`     |
+| `baseline adopt`       | Records baseline history without executing its SQL                |
+| `check`                | Diagnostics/counts, or a structured report with `--json`          |
+| `describe`             | JSON metadata, including unresolved findings                      |
+
+Successful commands exit 0. Invalid input or a failed operation exits 1. `check` also exits 1 for
+mismatches, unchecked sites, or no sites; unproven findings alone do not fail. `describe` can exit 0
+with unresolved findings. There is no migration dry-run command.
+
+Programmatic runner APIs are [documented with migrations](migrations.md#programmatic-api).
+Baseline APIs and prerequisites are in [adoption](adoption-guide.md#baseline-api).