@kequtech/tenon-orm 0.3.1 → 0.4.0

package/dist/transaction.js

@@ -1,81 +1,25 @@
-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 client = await pool.connect();
-    const connection = watchClient(client);
-    let active = true;
-    let began = false;
-    let releaseError;
-    let savepointId = 0;
-    let pending = Promise.resolve();
-    let recoveryFailure;
-    const query = async (text, input, readResult, guarded) => {
-        if (!active)
-            throw new Error('The transaction has finished.');
-        // Queue whole operations, including savepoint cleanup. Otherwise concurrent
-        // calls could place another write inside a savepoint that gets rolled back.
-        const operation = pending.then(async () => {
-            connection.check();
-            if (recoveryFailure)
-                throw recoveryFailure;
-            if (!guarded)
-                return readResult(await executeSql(client, text, input));
-            const savepoint = `tenon_affected_rows_${++savepointId}`;
-            await client.query(`SAVEPOINT ${savepoint}`);
-            try {
-                const result = readResult(await executeSql(client, text, input));
-                await client.query(`RELEASE SAVEPOINT ${savepoint}`);
-                return result;
-            }
-            catch (error) {
-                try {
-                    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
-                    // must not commit when the rejected write could still be present.
-                    recoveryFailure = new AggregateError([error, rollbackError], 'Operation and savepoint recovery failed.');
-                    throw recoveryFailure;
-                }
-                throw error;
-            }
-        });
-        pending = operation.then(() => { }, () => { });
-        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.query('COMMIT');
-        if (committed.command !== 'COMMIT') {
-            throw new Error('PostgreSQL rolled back the aborted transaction.');
-        }
-        return result;
-    }
-    catch (error) {
-        active = false;
-        await pending;
-        if (!began) {
-            releaseError = error instanceof Error ? error : new Error('BEGIN failed.');
-            throw error;
-        }
+import { executeSql } from './connection.js';
+/** Serialize whole Tenon policies; pgclear owns transaction, savepoint and transport recovery. */
+export function withTransaction(pool, work) {
+    return pool.transaction(async (transaction) => {
+        let active = true;
+        let pending = Promise.resolve();
+        const query = (text, input, readResult, guarded) => {
+            if (!active)
+                return Promise.reject(new Error('The transaction has finished.'));
+            const operation = pending.then(() => {
+                const execute = async (scope) => readResult(await executeSql(scope, text, input));
+                return guarded ? transaction.savepoint(execute) : execute(transaction);
+            });
+            pending = operation.then(() => { }, () => { });
+            return operation;
+        };
         try {
-            await client.query('ROLLBACK');
+            return await work(query);
         }
-        catch (rollbackError) {
-            releaseError = rollbackError instanceof Error ? rollbackError : new Error('Rollback failed.');
-            throw new AggregateError([error, rollbackError], 'Transaction and rollback failed.');
+        finally {
+            active = false;
+            await pending;
         }
-        throw error;
-    }
-    finally {
-        connection.release(releaseError);
-    }
+    });
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { Pool } from 'pg';
+import type { Pool } from '@kequtech/pgclear';
 import type { QueryResult } from './connection.js';
 import type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 import type { SqlQuery } from './query.js';

package/docs/adoption-guide.md

@@ -4,10 +4,49 @@ Replace application queries independently of migration ownership. Tenon can quer
 and generate types while the current migration runner stays in place. For a Tenon version upgrade,
 read the [Changelog](../CHANGELOG.md).
 
+## Upgrade from Tenon 0.3.x
+
+Tenon 0.4 uses pgclear 0.3.x in place of pg. Keep the existing database, credentials,
+migration history, and application query functions. Pgclear is included as a runtime dependency.
+With npm, update Tenon:
+
+```sh
+npm install @kequtech/tenon-orm@^0.4.0
+```
+
+Use the project's existing package manager and then review these boundaries:
+
+1. Translate pg `PoolConfig` fields to pgclear `PoolOptions`, or replace a borrowed pg Pool with a
+   pgclear Pool. A URI remains supported. Supply connection credentials explicitly; the driver does
+   not read PG environment variables, pgpass, service files, or pg-specific URI options.
+2. Keep Tenon `sql`, `QueryClient`, result modes, and callback transactions. Update native calls to
+   pgclear APIs: use `queryClassic(text, values?)` for finished SQL, release acquired sessions, and
+   close dedicated listeners separately. Import `sql`, `json`, `param`, and codec helpers from
+   `@kequtech/tenon-orm`. If native driver code also uses Pgclear's tag, alias it as `pgSql`; its query
+   objects belong in native `query`, while Tenon's query objects belong in `db.query`.
+3. Review temporal strings, readonly result arrays, Uint8Array bytes, exact string integer/numeric
+   arrays, and JSON/array inputs. Use `json(value)`, `param(value, codec)`, or encoded text for JSON
+   and arrays. Plain Date, bigint, and supported Temporal inputs are accepted with server inference;
+   Date encodes in UTC. They do not change output types. Command rowCount remains a number or null.
+   See [value mappings](reference.md#generated-types-and-checking).
+4. Regenerate database declarations against the intended development/test schema. Replace former
+   `Rows['users']`, `Rows.Insert['users']`, and `Rows.Update['users']` accesses with
+   `Database['users']['row']`, `Database['users']['insert']`, and `Database['users']['update']`.
+   Tenon owns generation and uses the configured driver's codec representations. If code imports
+   `generateDefinitions` from pgclear, import it from Tenon and use Tenon's options instead. Review
+   the generated diff and exclude exact generator output from formatting. Generated helper types
+   now import from Tenon; applications do not need a separate Pgclear dependency for them.
+5. Run the project's typecheck and database tests for queries, transactions, JSON/arrays, and native
+   integrations. Add optional source checking where composition is recoverable; optional patches
+   and runtime-dependent SQL may remain unchecked. See [validation tools](reference.md#choosing-a-validation-tool).
+
+If other code still uses pg directly, retain it until those callers are migrated. Updating Tenon
+does not require transferring migration ownership or adopting a new baseline.
+
 ## Preserve connections and behavior
 
 Keep the existing database URI, credentials, TLS requirements, schema, and data. Tenon can add
-driver settings through pg configuration:
+driver settings through pgclear configuration:
 
 ```ts
 import { createTenon } from '@kequtech/tenon-orm';
@@ -15,15 +54,15 @@ import { createTenon } from '@kequtech/tenon-orm';
 const db = createTenon({
   connection: {
     connectionString: existingUri,
-    connectionTimeoutMillis: 5000,
+    connectTimeoutMs: 5000,
   },
 });
 ```
 
-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
+Translate old driver configuration into pgclear `PoolOptions`. Pool timeouts use milliseconds.
+Set `startupParameters: { search_path: 'app,public' }` for runtime names. pgclear does not read
+PG environment variables, pgpass, or service files; supply connection settings explicitly. Preserve
+credentials and verified TLS requirements. 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,
@@ -42,11 +81,14 @@ 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):
-   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).
+3. Review value conversions against [Tenon's mappings](reference.md#generated-types-and-checking).
+   Pgclear defaults read int8/bigserial and SQL count(*) as exact strings; command rowCount is a
+   number. Bigint, Date, and supported Temporal inputs use server inference. Numeric values,
+   dates, arrays, and JSON serialization may also differ from the previous driver. Regenerate
+   declarations when mappings change; they do not replace domain validation.
+4. Run the optional [source-aware checker](query-checking.md) for recoverable queries, inspect
+   meaningful completed query variants, and run database assertions for actual rows, permissions,
+   write effects, and rollback. See [query inspection](query-inspection.md).
 5. Remove unused runtime dependencies and generated code after their callers are gone. Dependencies
    retained by other application code or installed transitively may still be needed.
 
@@ -55,7 +97,7 @@ also rejects zero rows. Use deterministic `ORDER BY` plus `LIMIT 1` when choosin
 matches is intended; modes do not add a limit.
 
 Use `sql.insertValues` and `sql.assignments` to replace object-to-SQL utilities, checking omission,
-default, null, and empty-input semantics. Generated `Rows.Insert`/`Rows.Update` types can replace
+default, null, and empty-input semantics. Generated `Database[table]['insert']`/`Database[table]['update']` types can replace
 handwritten persistence inputs. See the [mutation cookbook](mutations.md).
 
 Use `tx.query` for work that must commit together. Native pool calls do not join Tenon transactions.

package/docs/agent-guide.md

@@ -1,16 +1,24 @@
 # Tenon agent guide
 
-Tenon executes explicit PostgreSQL SQL through pg. Use ordinary functions for reusable queries. This
+Tenon executes explicit PostgreSQL SQL through pgclear. 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
 
+Read this guide after the README; consult the [reference](reference.md) for specific contracts.
+For a first setup, follow the [human guide](human-guide.md). Prefer documentation from the installed
+package when the repository's main branch describes a newer release.
+
 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.
 
+Start from the existing database module and a nearby query function. Reuse their connection,
+generated-schema imports, namespace, and `QueryClient` convention. Check both resolved Tenon and
+pgclear versions before changing driver calls or value representations.
+
 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
@@ -21,7 +29,9 @@ when mappings change, and run the project's typechecks and relevant database tes
 
 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.
+configuration. Tenon includes pgclear 0.3.x as a runtime dependency. Import `sql`, `json`, `param`,
+and codec helpers from Tenon. See [driver updates](reference.md#driver-updates) for independent
+compatible updates; regenerate changed types and rerun database checks.
 
 ```ts
 import { createTenon } from '@kequtech/tenon-orm';
@@ -31,8 +41,8 @@ if (!connection) throw new Error('DATABASE_URL is required');
 export const db = createTenon({ connection });
 ```
 
-`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
+`connection` accepts a URI string, pgclear `PoolOptions` (including `connectionString`), or an existing
+pgclear `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
@@ -43,9 +53,9 @@ work before closing. Tenon loads no environment files. Qualify table names or se
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { Rows } from './generated-schema.js';
+import type { Database } from './generated-schema.js';
 
-type Summary = Pick<Rows['users'], 'id' | 'email'>;
+type Summary = Pick<Database['users']['row'], 'id' | 'email'>;
 
 function userById(client: QueryClient, { id }: { id: number }) {
   return client.query(sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`, {
@@ -62,7 +72,7 @@ aggregates need types for their actual output.
 | `returns`          | Result                                             | Required returned rows |
 | ------------------ | -------------------------------------------------- | ---------------------- |
 | `native` (default) | Driver object with `.rows`, `.rowCount`, `.fields` | Any                    |
-| `many`             | Plain `Row[]`                                      | Any                    |
+| `many`             | `readonly Row[]`                                   | Any                    |
 | `oneOrNone`        | `Row \| undefined`                                 | Zero or one            |
 | `one`              | `Row`                                              | Exactly one            |
 
@@ -72,9 +82,10 @@ Options are `{ returns?, affectedRows?, label? }`; unknown keys fail. Modes do n
 
 ## Parameters and composition
 
-- 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
+- Interpolate values without quotes. Do not author `$n` placeholders inside templates. `null` binds
+  SQL NULL. Plain bigint, Date, and supported native/polyfilled Temporal values encode as text with
+  server inference; Date uses UTC. Undefined, plain objects, and arrays require omission or explicit encoding.
+- Use pgclear `param(ids, builtin.int4Array)` with `ANY` 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.
@@ -95,17 +106,20 @@ Selected columns ignore unlisted fields and can discard required inputs. Put exp
 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
+Use generated `Database['users']['insert']` and `Database['users']['update']` inputs; narrow editable fields with
 `Pick`. These types account for defaults, writable columns, domains, and driver representations.
 They do not validate constraints or JSON contents. See [mutation examples](mutations.md).
 
-Use `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
+Use pgclear `json(value)` or encoded text for JSON, and `param(value, codec)` for arrays and
+custom encodings. Bigint scalars and SQL `count(*)` read as exact strings; command `rowCount` uses
+numbers. Plain bigint, Date, and supported Temporal inputs do not change those output defaults.
+Choose explicit codecs for bigint, Date, or Temporal outputs. Decimals and temporal values otherwise
+read as strings. Numeric and bigint arrays preserve exact strings. Bytes use Uint8Array.
+SQL NULL array elements remain null. Tenon generates declarations from the schema and selected
+registry; a custom decoder can declare `text.typescript` so generation and checking agree without
+duplicating its type in `readTypes`. 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.
+[JSON/temporal projection](reference.md#persistence-and-domain-values).
 
 ## Transactions and native access
 
@@ -128,7 +142,7 @@ provided. Transactions belong to one database instance.
 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
+and CTE effects. pgclear owns savepoint recovery. A lost commit
 acknowledgment can leave the outcome unknown.
 
 `db.native` exposes the existing pool for driver features. Native calls bypass Tenon's guards and
@@ -139,16 +153,30 @@ not establish that the outer transaction committed.
 
 ## Inspect and validate
 
-Use `describeQuery({ connection, query })` on completed SQL or `tenon describe query.sql` on a file.
-Inspection owns a separate connection. Match the runtime role, search path, and timezone. Temporary
-tables and transaction-local state are not inherited; reported mappings assume pg's default parsers.
-Result nullability is unknown and JSON structure is unchecked. A successful description does not
-verify `sql<Row>`, bound values, execution permission, or effects.
-
-Pair inspection with database assertions for complete relevant rows, meaningful query variants, and
-rollback. A small query-building function can share the same statement with inspection and
-execution; keep simple queries inline when that is sufficient. See
-[query inspection](query-inspection.md).
+Choose the tool for the task: `tenon check` compares source contracts, `tenon describe` reports
+finished SQL metadata, and `tenon generate --check` checks generated-file freshness. None replaces
+TypeScript or database tests. See [validation tools](reference.md#choosing-a-validation-tool).
+
+Run tenon check on the TypeScript project, a file, or file:line. It recovers authored SQL and types
+without importing application code, then uses pgclear Describe. Mismatches, unchecked queries and
+zero query sites fail; unproven properties do not. Trust declared types when metadata is inconclusive.
+
+For checking, object expansions need an explicit finite shape type and required, defined selected
+properties. Prefer explicit column lists. Fixed fragments, const aliases, fixed joins and finite
+ternaries are supported within 16 variants per query. Dynamic fragments, optional-field SQL
+expansion and unknown batch lengths remain unchecked. See [query checking](query-checking.md).
+
+A generated update type usually has optional properties. Even with an explicit column list, those
+properties can change the SQL by omission, so the checker may report an ordinary patch as unchecked.
+Keep that runtime behavior when intended. If selected fields are always supplied, validate/narrow
+the input into an explicit required shape. Do not use casts just to suppress a finding. See
+[responding to findings](query-checking.md#responding-to-findings) and
+[troubleshooting](reference.md#troubleshooting).
+
+For metadata alone, use describeQuery or tenon describe query.sql. Match role, search path, timezone,
+and custom codecs. Temporary tables and transaction-local state are not inherited. Retain tests for
+complete rows, meaningful query variants, authorization, effects, and rollback. Describe does not
+prove bound values, JSON members, nullability, cardinality or runtime execution permission.
 
 ## Schema changes
 

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 pg. This guide follows a small application from its first table to reusable
+executes it through pgclear. 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
@@ -17,8 +17,10 @@ npm install @kequtech/tenon-orm
 ```
 
 Use PostgreSQL 16+ and TypeScript 6+. Keep your existing strict TypeScript configuration and Node
-typings. Supply `DATABASE_URL` through your application's environment setup; Tenon does not load
-`.env` files.
+typings. Tenon includes pgclear 0.3.x. Supply `DATABASE_URL` through your application's
+environment setup; Tenon does not load `.env` files. Import `sql`, `json`, `param`, and codec helpers
+from `@kequtech/tenon-orm` for application queries. See [driver updates](reference.md#driver-updates)
+when updating Pgclear independently.
 
 ```ts
 // src/db.ts
@@ -30,7 +32,7 @@ export const db = createTenon({ connection });
 ```
 
 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.
+supply an existing pgclear `Pool`; your application then owns its shutdown.
 
 ## Create a table
 
@@ -102,13 +104,22 @@ throws if the query returns more than one row. Use `'one'` when absence should a
 `'many'` for an array, or omit `returns` for the native result object with `.rows`, `.rowCount`, and
 `.fields`. These options do not change your SQL.
 
+`rowCount` is a number or null when the command has no count. SQL `count(*)` and bigint/bigserial
+column values are exact strings, including values beyond JavaScript's safe integer range. Use
+strings, bigint, or pgclear `param(text, builtin.int8)` for int8 parameters. Plain Date and supported
+Temporal inputs also work; they do not change the default string outputs. Date inputs encode in UTC.
+Opt-in codecs can return Date, bigint, or Temporal values when the application needs them.
+
 Generated table types can help describe projections without repeating every field:
 
 ```ts
-import type { Rows } from './generated-schema.js';
-type UserSummary = Pick<Rows['users'], 'id' | 'email'>;
+import type { Database } from './generated-schema.js';
+type UserSummary = Pick<Database['users']['row'], 'id' | 'email'>;
 ```
 
+For frequently used types, define [application aliases](reference.md#application-aliases) such as
+`UserRow`, `UserInsert`, and `UserUpdate` in a handwritten module.
+
 You can then write `sql<UserSummary>`. A table type describes the full table; a join or aggregate
 needs a type for what that particular query selects. An annotation is a declaration, not proof that
 the SQL matches. Without one, result fields are `unknown`. Use the inspection and database-test
@@ -116,7 +127,7 @@ 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.
+writes and reads, temporal strings, and an SQL predicate that rejects infinite session expiry.
 
 ## Reuse a query with a function
 
@@ -125,9 +136,9 @@ supplied values easy to read:
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { Rows } from './generated-schema.js';
+import type { Database } from './generated-schema.js';
 
-type UserSummary = Pick<Rows['users'], 'id' | 'email'>;
+type UserSummary = Pick<Database['users']['row'], 'id' | 'email'>;
 
 export function userByEmail(client: QueryClient, { email }: { email: string }) {
   return client.query(sql<UserSummary>`SELECT id, email FROM public.users WHERE email = ${email}`, {
@@ -171,12 +182,12 @@ Explicit `null` stays null. Empty batches and updates throw. Heterogeneous inser
 aligned, with `DEFAULT` for missing cells.
 
 ```ts
-import type { Rows } from './generated-schema.js';
+import type { Database } from './generated-schema.js';
 
-const input: Rows.Insert['users'] = { email: 'another@example.test' };
+const input: Database['users']['insert'] = { email: 'another@example.test' };
 await db.query(sql`INSERT INTO public.users ${sql.insertValues(input, ['email'])}`);
 
-const patch: Pick<Rows.Update['users'], 'active'> = { active: false };
+const patch: Pick<Database['users']['update'], 'active'> = { active: false };
 await db.query(sql`UPDATE public.users SET ${sql.assignments(patch, ['active'])}
   WHERE email = ${input.email}`);
 ```
@@ -188,14 +199,31 @@ Use `Pick` to limit editable fields. Keep expressions, predicates, conflict hand
 
 ## 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.
+The three database tools answer different questions: `tenon check` compares authored queries with
+their TypeScript contracts, `tenon describe` reports metadata for finished SQL, and
+`tenon generate --check` checks whether saved database declarations are current. See
+[validation tools](reference.md#choosing-a-validation-tool) for their limits.
+
+After migrating a development/test database, run the optional source-aware checker:
+
+```sh
+npx tenon check src/queries.ts
+npx tenon check src/queries.ts:23
+```
+
+A line selects one complete query. Omit the file to check the TypeScript project. The checker reads
+source and types without importing the application or executing SQL. It reports definite
+contradictions and unsupported composition; nullability, JSON members, and other inconclusive
+contracts receive the benefit of the declared type and remain unproven. See
+[query checking](query-checking.md) for supported fragments and explicit object expansion shapes.
 
-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.
+Use describeQuery on finished SQL, or tenon describe query.sql, when you only need metadata and a
+conservative row declaration. Match runtime role/session settings. Retain TypeScript and database
+tests for actual rows, effects, permissions, and rollback. The checker does not replace those tests.
+Generated patch types contain optional fields and can therefore be unchecked even when execution is
+valid. Keep optional patches when needed; see [responding to findings](query-checking.md#responding-to-findings).
+For rejected values, result-count errors, and other common failures, see
+[troubleshooting](reference.md#troubleshooting).
 
 ## Reuse or assemble parts of SQL when needed
 
@@ -215,6 +243,7 @@ const count = sql<{ count: string }>`SELECT count(*) AS count FROM public.users
 
 Execute each query with `db.query`. Validate application-supplied patterns and page sizes before
 building queries. The complete query supplies the result type.
+The SQL aggregate's `count` is a string; the native result's `rowCount` counts returned rows.
 
 Use `sql.join` when the number of fragments varies, such as one search condition per word or a set
 of optional filters. It combines fragments with `'AND'`, `'OR'`, or `','` and preserves their bound
@@ -248,3 +277,5 @@ when mixing `AND` and `OR`. See the [composition reference](reference.md#sql-fra
 
 Use fixed SQL when composition is unnecessary. See the [reference](reference.md) for arrays,
 identifiers, value mappings, CLI options, and error behavior.
+Runtime loops and dynamic fragment lists work during execution but remain unchecked by `tenon check`;
+use database tests for those queries.

package/docs/mutations.md

@@ -2,7 +2,7 @@
 
 Use `sql.insertValues` and `sql.assignments` for object fields while keeping SQL structure visible.
 The [reference](reference.md#object-based-mutation-fragments) defines the complete contract.
-Examples assume an existing `db` and this table, with generated `Rows` from the same schema:
+Examples assume an existing `db` and this table, with generated `Database` from the same schema:
 
 ```sql
 CREATE TABLE profiles (
@@ -34,9 +34,9 @@ aligned across heterogeneous rows. Empty batches fail; a single default-only obj
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { Rows } from './generated-schema.js';
+import type { Database } from './generated-schema.js';
 
-type ProfileInput = Pick<Rows.Insert['profiles'], 'name' | 'score'>;
+type ProfileInput = Pick<Database['profiles']['insert'], 'name' | 'score'>;
 
 function createProfile(client: QueryClient, input: ProfileInput) {
   return client.query(
@@ -55,7 +55,7 @@ Selected columns choose and order fields, ignoring unlisted keys. They can disca
 even when the original object is valid:
 
 ```ts
-const input: Rows.Insert['profiles'] = { name: 'Ada' };
+const input: Database['profiles']['insert'] = { name: 'Ada' };
 const query = sql`INSERT INTO profiles ${sql.insertValues(input, ['bio', 'score'])}`;
 // Executing this fails: name was discarded and has no default.
 ```
@@ -63,7 +63,7 @@ const query = sql`INSERT INTO profiles ${sql.insertValues(input, ['bio', 'score'
 ## Patches mixed with expressions
 
 ```ts
-const patch: Pick<Rows.Update['profiles'], 'name' | 'bio'> = { bio: null };
+const patch: Pick<Database['profiles']['update'], 'name' | 'bio'> = { bio: null };
 await db.query(sql`UPDATE profiles SET ${sql.assignments(patch)}, revision = revision + 1
   WHERE id = ${id}`);
 ```
@@ -106,15 +106,28 @@ For a table with `payload jsonb` and `tags text[]`, encode JSON separately from
 array:
 
 ```ts
+import { builtin, json, param } from '@kequtech/tenon-orm';
+
 const tags = ['ada', 'lin'];
 await db.query(
-  sql`INSERT INTO deliveries ${sql.insertValues({ payload: JSON.stringify(tags), tags })}`,
+  sql`INSERT INTO deliveries ${sql.insertValues({ payload: json(tags), tags: param(tags, builtin.textArray) })}`,
 );
 ```
 
-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.
+Generated JSON writes accept pgclear parameters or encoded strings. `json(value)` encodes objects,
+arrays, strings, and JSON null; plain `null` means SQL NULL. Arrays need `param(value, codec)` or
+encoded PostgreSQL text. Plain arrays, objects, and undefined reject as bound values. Tenon passes
+explicit parameters unchanged to pgclear. `json()` still rejects bigint values, including bigint
+nested inside objects; bigint support for ordinary SQL parameters does not change JSON encoding.
+
+For bigint/bigserial fields, generated writes accept exact strings, bigint, or explicit parameters;
+reads remain strings by default. Use `param('9007199254740993', builtin.int8)` for an explicit int8
+parameter and `param(['9007199254740993', null], builtin.int8Array)` for an int8 array. The bigint
+output codec and matching array encoder are separate opt-in choices.
+
+Date and supported Temporal values can be ordinary scalar inputs, including mutation fields. Date
+encodes in UTC; Temporal calendar dates, wall times, and instants retain their distinct meanings.
+Choose the value appropriate to the PostgreSQL column and retain application validation.
 
 ## Batches in one transaction