@kequtech/tenon-orm 0.2.2 → 0.3.1

package/dist/transaction.js

@@ -1,11 +1,11 @@
-import { reserveConnection } from './driver/session.js';
-import { executeSql } from './connection.js';
+import { executeSql, watchClient } from './connection.js';
 /** The callback owns one connection and expires before commit or rollback begins. */
 export async function withTransaction(pool, work) {
-    const connection = await reserveConnection(pool, 'BEGIN');
-    const client = connection.sql;
+    const client = await pool.connect();
+    const connection = watchClient(client);
     let active = true;
-    let discard = false;
+    let began = false;
+    let releaseError;
     let savepointId = 0;
     let pending = Promise.resolve();
     let recoveryFailure;
@@ -21,16 +21,16 @@ export async function withTransaction(pool, work) {
             if (!guarded)
                 return readResult(await executeSql(client, text, input));
             const savepoint = `tenon_affected_rows_${++savepointId}`;
-            await client.unsafe(`SAVEPOINT ${savepoint}`);
+            await client.query(`SAVEPOINT ${savepoint}`);
             try {
                 const result = readResult(await executeSql(client, text, input));
-                await client.unsafe(`RELEASE SAVEPOINT ${savepoint}`);
+                await client.query(`RELEASE SAVEPOINT ${savepoint}`);
                 return result;
             }
             catch (error) {
                 try {
-                    await client.unsafe(`ROLLBACK TO SAVEPOINT ${savepoint}`);
-                    await client.unsafe(`RELEASE SAVEPOINT ${savepoint}`);
+                    await client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+                    await client.query(`RELEASE SAVEPOINT ${savepoint}`);
                 }
                 catch (rollbackError) {
                     // Even if application code catches this error, the outer transaction
@@ -45,13 +45,15 @@ export async function withTransaction(pool, work) {
         return operation;
     };
     try {
+        await client.query('BEGIN');
+        began = true;
         const result = await work(query);
         active = false;
         await pending;
         connection.check();
         if (recoveryFailure)
             throw recoveryFailure;
-        const committed = await client.unsafe('COMMIT');
+        const committed = await client.query('COMMIT');
         if (committed.command !== 'COMMIT') {
             throw new Error('PostgreSQL rolled back the aborted transaction.');
         }
@@ -60,17 +62,20 @@ export async function withTransaction(pool, work) {
     catch (error) {
         active = false;
         await pending;
+        if (!began) {
+            releaseError = error instanceof Error ? error : new Error('BEGIN failed.');
+            throw error;
+        }
         try {
-            connection.check();
-            await client.unsafe('ROLLBACK');
+            await client.query('ROLLBACK');
         }
         catch (rollbackError) {
-            discard = true;
+            releaseError = rollbackError instanceof Error ? rollbackError : new Error('Rollback failed.');
             throw new AggregateError([error, rollbackError], 'Transaction and rollback failed.');
         }
         throw error;
     }
     finally {
-        await connection.release(discard);
+        connection.release(releaseError);
     }
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type postgres from 'postgres';
+import type { Pool } from 'pg';
 import type { QueryResult } from './connection.js';
 import type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 import type { SqlQuery } from './query.js';
@@ -18,7 +18,7 @@ export interface CloseOptions {
 }
 export type Database = Transaction & {
     /** The underlying pool-level driver client; native calls bypass Tenon's query and transaction guards. */
-    readonly native: postgres.Sql;
+    readonly native: Pool;
     /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
     transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
     close(options?: CloseOptions): Promise<void>;

package/docs/adoption-guide.md

@@ -1,32 +1,34 @@
 # Adopting Tenon
 
-Replace application queries independently of migration ownership. Tenon can query an existing
-schema and generate types while the current migration runner stays in place. For a Tenon version
-upgrade, read the [Changelog](../CHANGELOG.md).
+Replace application queries independently of migration ownership. Tenon can query an existing schema
+and generate types while the current migration runner stays in place. For a Tenon version upgrade,
+read the [Changelog](../CHANGELOG.md).
 
 ## Preserve connections and behavior
 
 Keep the existing database URI, credentials, TLS requirements, schema, and data. Tenon can add
-driver settings without parsing the URI:
+driver settings through pg configuration:
 
 ```ts
 import { createTenon } from '@kequtech/tenon-orm';
 
 const db = createTenon({
-  connection: { url: existingUri, options: { connect_timeout: 5, idle_timeout: 10 } },
+  connection: {
+    connectionString: existingUri,
+    connectionTimeoutMillis: 5000,
+  },
 });
 ```
 
-Translate old driver configuration into Postgres.js options rather than passing it through.
-For example, pg's `connectionTimeoutMillis: 5000` becomes `connect_timeout: 5`, and
-`idleTimeoutMillis: 10000` becomes `idle_timeout: 10`; both native options use seconds. Preserve
-runtime `search_path` through URI startup parameters or `options.connection.search_path`.
-URI startup parameters take precedence when both are supplied. CLI `--namespace` does not change
-runtime queries. See [connection options](reference.md#installation-and-connection).
+Translate old driver configuration into pg `PoolConfig` rather than passing it through. Pool
+timeouts use milliseconds. Preserve runtime `search_path` through the pg startup options string, for
+example `options: '-c search_path=app,public'`. URI startup options take precedence when both are
+supplied. CLI `--namespace` does not change runtime queries. See
+[connection options](reference.md#installation-and-connection).
 
-Before conversion, identify behavior supplied by the old ORM: IDs/defaults, timestamps,
-validation, hooks, serialization, relationships, and transaction boundaries. Preserve it explicitly
-in application code or SQL where required.
+Before conversion, identify behavior supplied by the old ORM: IDs/defaults, timestamps, validation,
+hooks, serialization, relationships, and transaction boundaries. Preserve it explicitly in
+application code or SQL where required.
 
 ## Replace queries
 
@@ -41,7 +43,7 @@ in application code or SQL where required.
 2. Replace queries with parameterized SQL in ordinary functions accepting `QueryClient` where
    callers may supply `db` or `tx`. Retain projections, ordering, null handling, and authorization.
 3. Review value conversions against [Tenon's mappings](reference.md#generated-types-and-checking):
-   bigint/numeric strings, dates, arrays, and native JSON may differ from the previous driver.
+   numeric values, dates, arrays, and JSON serialization may differ from the previous driver.
    Generated declarations do not replace domain validation.
 4. Inspect meaningful completed query variants and run database assertions for actual rows,
    permissions, write effects, and rollback. See [query inspection](query-inspection.md).
@@ -74,9 +76,9 @@ For an application owning `app` in a shared database:
 npx tenon baseline capture --directory migrations --namespace app --schema app
 ```
 
-The directory must contain no SQL files. Capture uses native `pg_dump --schema-only --no-owner
---no-privileges` and writes `0001_baseline.up.sql` with no down file. Install compatible PostgreSQL
-client tools on PATH; prefer the server's major version.
+The directory must contain no SQL files. Capture uses native
+`pg_dump --schema-only --no-owner --no-privileges` and writes `0001_baseline.up.sql` with no down
+file. Install compatible PostgreSQL client tools on PATH; prefer the server's major version.
 
 | Option                | Scope                                                                                |
 | --------------------- | ------------------------------------------------------------------------------------ |
@@ -101,20 +103,30 @@ reference definitions rather than comparing against types regenerated after late
 `generateDefinitions` covers relation metadata, not functions or privileges; include reviewed
 catalog checks for other objects the application needs. Tenon does not perform these comparisons.
 
+Generated declaration text is not a version-stable schema fingerprint: driver mappings and generator
+changes can alter it without schema drift. The schema-summary comments expose SQL definitions, but
+their formatting and PostgreSQL's rendering of those definitions are not a stable comparison format
+either. If an existing adoption guard hashes generated text, preserve its original reference and
+freeze a separate reference for each supported generator version from a disposable replay of the
+immutable checkpoint. Compare the replay's metadata with the reviewed checkpoint before accepting
+the new reference; never derive a replacement from whichever live database is configured. Keep
+independent function and privilege checks, and test both matching adoption and refusal after drift.
+This application guard is separate from Tenon's migration checksums; keep applied SQL unchanged.
+
 ```sh
 npx tenon baseline adopt --directory migrations --namespace app
 npx tenon migrate --directory migrations --namespace app
 ```
 
-Adoption records the baseline checksum without executing its SQL. The namespace must already
-exist. Repeating matching adoption is harmless, including after later migrations; history conflicts
-fail. Once Tenon owns history, add forward migrations rather than editing the baseline.
+Adoption records the baseline checksum without executing its SQL. The namespace must already exist.
+Repeating matching adoption is harmless, including after later migrations; history conflicts fail.
+Once Tenon owns history, add forward migrations rather than editing the baseline.
 
 ### Replay a fresh database
 
 Run `tenon migrate --directory migrations --namespace app`, without adoption. It executes the same
-committed baseline and subsequent migrations. Apply the deployment's required roles, ownership,
-and grants before application access.
+committed baseline and subsequent migrations. Apply the deployment's required roles, ownership, and
+grants before application access.
 
 The portable baseline omits ownership, grants/revokes, and default privileges. Objects are recreated
 under the migration role. For `SECURITY DEFINER` functions, that owner controls execution authority,
@@ -129,7 +141,8 @@ types. Test existing-row preservation, repeatable adoption, subsequent migration
 A schema-only baseline and down migration are not backups. The missing down file prevents rollback
 across the baseline; use the application's backup/recovery procedure for that boundary.
 
-Programmatic capture is `captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })`
-and returns `{ id, upPath }`. It requires a native libpq connection string; an explicitly empty
-`schemas` list fails. `adoptBaseline({ connection, directory?, namespace? })` accepts Tenon's runtime
-connection forms and returns newly recorded IDs.
+Programmatic capture is
+`captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })` and returns
+`{ id, upPath }`. It requires a native libpq connection string; an explicitly empty `schemas` list
+fails. `adoptBaseline({ connection, directory?, namespace? })` accepts Tenon's runtime connection
+forms and returns newly recorded IDs.

package/docs/agent-guide.md

@@ -1,8 +1,8 @@
 # Tenon agent guide
 
-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.
+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
 
@@ -11,16 +11,17 @@ commands. Preserve those conventions. Tenon queries and type generation do not r
 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
+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.
+`npm install @kequtech/tenon-orm`; retain the project's package manager and TypeScript
+configuration.
 
 ```ts
 import { createTenon } from '@kequtech/tenon-orm';
@@ -30,13 +31,13 @@ if (!connection) throw new Error('DATABASE_URL is required');
 export const db = createTenon({ connection });
 ```
 
-`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
+`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).
+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 and result contracts
 
@@ -60,23 +61,23 @@ aggregates need types for their actual output.
 
 | `returns`          | Result                                             | Required returned rows |
 | ------------------ | -------------------------------------------------- | ---------------------- |
-| `native` (default) | Driver array with `.count`, `.command`, `.columns` | Any                    |
+| `native` (default) | Driver object with `.rows`, `.rowCount`, `.fields` | Any                    |
 | `many`             | Plain `Row[]`                                      | Any                    |
 | `oneOrNone`        | `Row \| undefined`                                 | Zero or one            |
 | `one`              | `Row`                                              | Exactly one            |
 
-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.
+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
 
-- Interpolate values without quotes. Do not author `$n` placeholders inside templates.
-  `undefined` bound values fail; `null` means SQL null.
+- 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.
+- `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
@@ -87,20 +88,24 @@ mandatory authorization predicates when optional filters are absent.
 
 ## Writes and generated values
 
-`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.
+`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 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).
 
-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).
+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) and the
+[JSON/finite-date projection](reference.md#persistence-and-domain-values). For authentication policy
+requiring finite expiry, include `isfinite(expires_at)` alongside the SQL expiry comparison.
 
 ## Transactions and native access
 
@@ -127,34 +132,36 @@ and CTE effects. Reserve `tenon_affected_rows_` savepoint names for Tenon. A los
 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 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.
+`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; 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.
+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).
+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
 
-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.
+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).
+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,7 +1,7 @@
 # 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) for exact contracts and [adoption](adoption-guide.md) when
@@ -29,12 +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. You can also supply an existing Postgres.js client; your application then owns its shutdown.
+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, keep them. For a fresh example database,
-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
@@ -98,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:
 
@@ -113,6 +114,10 @@ needs a type for what that particular query selects. An annotation is a declarat
 the SQL matches. Without one, result fields are `unknown`. Use the inspection and database-test
 workflow below to check the declared contract against the query's behavior.
 
+Keep storage types conservative and validate them when projecting domain values. The
+[persistence-to-domain example](reference.md#persistence-and-domain-values) shows validated JSON
+writes and reads, finite dates, and an SQL predicate that rejects infinite session expiry.
+
 ## Reuse a query with a function
 
 Use an ordinary function when several callers need the same query. An object input makes the
@@ -129,16 +134,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');
@@ -177,20 +182,20 @@ await db.query(sql`UPDATE public.users SET ${sql.assignments(patch, ['active'])}
 ```
 
 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
+`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 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.
+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.
 
 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.
+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
 
@@ -226,9 +231,9 @@ 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. For an entirely optional set of filters, omit the whole `WHERE` clause when the list
-is empty:
+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 + '%'}`);

package/docs/mutations.md

@@ -51,8 +51,8 @@ Annotations, `satisfies`, or helper generic arguments apply generated input type
 the file does not check writes. Use `Pick` to narrow accepted fields and retain runtime validation.
 Generated inputs describe defaults and driver representations, not authorization or constraints.
 
-Selected columns choose and order fields, ignoring unlisted keys. They can discard a required
-field even when the original object is valid:
+Selected columns choose and order fields, ignoring unlisted keys. They can discard a required field
+even when the original object is valid:
 
 ```ts
 const input: Rows.Insert['profiles'] = { name: 'Ada' };
@@ -97,21 +97,24 @@ if (bio !== undefined) {
 }
 ```
 
-The second query preserves an existing bio. Omitting an insert value uses its database default;
-that alone does not decide which fields a conflict update overwrites.
+The second query preserves an existing bio. Omitting an insert value uses its database default; that
+alone does not decide which fields a conflict update overwrites.
 
 ## JSON and PostgreSQL arrays
 
-For a table with `payload jsonb` and `tags text[]`, native arrays work in either context:
+For a table with `payload jsonb` and `tags text[]`, encode JSON separately from the PostgreSQL
+array:
 
 ```ts
 const tags = ['ada', 'lin'];
-await db.query(sql`INSERT INTO deliveries ${sql.insertValues({ payload: tags, tags })}`);
+await db.query(
+  sql`INSERT INTO deliveries ${sql.insertValues({ payload: JSON.stringify(tags), tags })}`,
+);
 ```
 
-PostgreSQL establishes the target types and the driver serializes values. Pass native JSON rather
-than `JSON.stringify` output, which would store a JSON string. Generated JSON writes accept Tenon's
-`JSONValue` type, excluding SQL null for nonnullable columns. Use `'null'::jsonb` for JSON null.
+Generated JSON writes accept encoded JSON strings. Use `JSON.stringify(value)` for objects, arrays,
+strings, and JSON null; a bound JavaScript null means SQL null. Arrays passed directly are
+PostgreSQL arrays. Tenon leaves serialization to pg.
 
 ## Batches in one transaction
 
@@ -127,5 +130,5 @@ await db.transaction(async (tx) => {
 ```
 
 A failure rolls back all batches. Empty input makes no insert calls. Choose a batch size below the
-query-wide 65,533-parameter limit, including surrounding parameters; default cells consume none.
+query-wide 65,535-parameter limit, including surrounding parameters; default cells consume none.
 Tenon does not split batches or choose transaction boundaries for you.

package/docs/query-inspection.md

@@ -34,20 +34,22 @@ const description = await describeQuery({
 });
 ```
 
-Reuse the runtime URI and session settings. Optional `session.role` uses SET ROLE when permitted;
-it does not load that role's login defaults. Omitted settings use the inspection connection's
-defaults. Explicit undefined behaves like omission. Unknown keys and invalid settings fail.
+Reuse the runtime URI and session settings. Optional `session.role` uses SET ROLE when permitted; it
+does not load that role's login defaults. Omitted settings use the inspection connection's defaults.
+Explicit undefined behaves like omission. Unknown keys and invalid settings fail.
 
 `context` reports login/effective roles, configured/resolved search paths, timezone, database, and
-effective statement/lock timeouts. Its mode is `separate-session` and read mapping profile is
-`postgres`. Custom parsers, temporary tables, uncommitted changes, and transaction-local settings
-are not inherited. `PGOPTIONS` is not automatically copied; use URI startup options or session
-settings. Array mappings include Tenon's SQL NULL correction.
+effective statement/lock timeouts. Its mode is `separate-session` and read mapping profile is `pg`;
+reported read types assume pg's default parsers and do not infer application overrides. Temporary
+tables, uncommitted changes, and transaction-local settings are not inherited. pg reads its normal
+connection environment, including `PGOPTIONS` when URI options are absent. Use explicit URI/session
+settings for reproducibility.
 
 Defaults are a 3-second connection/authentication timeout, a 5-second limit per server statement,
-and a 1-second lock wait. Overrides are positive integer milliseconds, at most 2,147,483,647.
-URI settings cannot disable the statement/lock bounds. Cleanup uses a 1-second driver shutdown
-timeout. These are operation limits, not a single overall deadline.
+and a 1-second lock wait. Overrides are positive integer milliseconds, at most 2,147,483,647. URI
+settings cannot disable the statement/lock bounds. A URI `query_timeout` remains pg's separate
+client read timeout. The owned client closes after inspection. These are operation limits, not a
+single overall deadline.
 
 ## Result fields
 
@@ -113,10 +115,6 @@ rows/effects, JSON, permissions, and rollback in database tests, and run TypeScr
 meaningful query variants; one instance does not cover unexercised branches. Expect only reviewed
 findings and keep unexpected ones visible.
 
-A query builder is optional. When a test needs to retain executed statements, a test-only
-`QueryClient` wrapper can forward them and retain `{ text }` without parameter values. Production
-`onQuery` deliberately supplies neither SQL nor values.
-
 ## CLI
 
 Save SQL with PostgreSQL placeholders in `query.sql`: