@kequtech/tenon-orm 0.4.0 → 0.4.3

package/docs/adoption-guide.md

@@ -1,190 +1,131 @@
 # 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).
-
-## 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.
+You can replace application queries without changing migration ownership. Tenon queries and type
+generation work with an existing schema and any migration runner. For a Tenon upgrade, read the
+[shipped changelog](../CHANGELOG.md) from your resolved version through the target version.
 
 ## Preserve connections and behavior
 
-Keep the existing database URI, credentials, TLS requirements, schema, and data. Tenon can add
-driver settings through pgclear configuration:
+Reuse the existing database URI, credentials, schema, TLS requirements, and data. Pool configuration
+uses pgclear options; timeout names include `Ms`. Configure runtime names with
+`startupParameters: { search_path: 'app,public' }`, or qualify tables in SQL. Tooling `namespace`
+does not configure runtime queries.
 
-```ts
-import { createTenon } from '@kequtech/tenon-orm';
+Before replacing an ORM, identify behavior it currently supplies: IDs/defaults, timestamps,
+validation, hooks, serialization, relationship loading, and transaction boundaries. Preserve needed
+behavior in application code, constraints, or SQL. Tenon has no model lifecycle or implicit loading.
 
-const db = createTenon({
-  connection: {
-    connectionString: existingUri,
-    connectTimeoutMs: 5000,
-  },
-});
-```
-
-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,
-hooks, serialization, relationships, and transaction boundaries. Preserve it explicitly in
-application code or SQL where required.
+Use [shared configuration](configuration.md) to reuse connection settings and codecs across runtime,
+generation, checking, inspection, and migrations. Keep credentials supplied by the deployment.
 
 ## Replace queries
 
-1. Optionally generate persistence types from the existing schema:
-
-   ```sh
-   npx tenon generate --namespace public --out src/generated-schema.d.ts
-   ```
-
-   This needs no Tenon migration history. Use the application's namespace and commit exact output.
-
-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).
-   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.
-
-Check cardinality when replacing a first-row accessor. `oneOrNone` rejects multiple rows and `one`
-also rejects zero rows. Use deterministic `ORDER BY` plus `LIMIT 1` when choosing one of several
-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 `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.
-For driver features, preserve resource ownership and recovery policy under the
-[native access contract](reference.md#native-driver-access).
+1. Optionally run `tenon generate` with the application's shared configuration.
+   Use the application's schema and codec registry; no Tenon migration history is required.
+2. Replace one workflow at a time with parameterized SQL in ordinary functions. Accept
+   `QueryClient` when callers may use either `db` or `tx`. Preserve selected columns, ordering,
+   null handling, authorization predicates, and transaction boundaries.
+3. Review input/output mappings and validate domain values at the persistence boundary. Generated
+   types do not validate JSON members or application constraints.
+4. Test actual rows, writes, permissions, and rollback. Use source checking and inspection where
+   useful. See [choosing a validation tool](reference.md#choosing-a-validation-tool).
+5. Remove unused dependencies/generated code once all their callers are gone.
+
+When replacing a first-row accessor, decide whether multiple matches should be an error.
+`oneOrNone` rejects multiple rows and `one` also rejects absence. To choose one match deliberately,
+author deterministic `ORDER BY ... LIMIT 1`; result modes do not add a limit.
+
+For object-to-SQL utilities, review omission, defaults, null, and empty patches against
+[the write guide](mutations.md). Use `tx.query` for every operation that must commit together;
+native pool calls do not join Tenon transactions.
 
 ## Transfer migration ownership
 
-Choose one final checkpoint for the old runner. Bring existing databases to it and disable that
-runner before handover; the runners do not share locks. Capture from a trusted reference database,
-preferably a disposable replay of the legacy migrations.
+Choose the old runner's final schema checkpoint. Bring every existing database to it and disable
+that runner before handover; the runners do not share locks. Capture one baseline from a trusted
+reference database, preferably a disposable replay of the old migrations.
 
 ### Capture a baseline
 
 For an application owning `app` in a shared database:
 
 ```sh
-npx tenon baseline capture --directory migrations --namespace app --schema app
+npx tenon baseline capture --directory migrations --namespace app --schema app --connection "$DATABASE_URL"
 ```
 
+This example supplies the native libpq URI for the same database through `DATABASE_URL`.
+The native connection can instead be stored in `baseline.connection`, and the captured schemas in
+`baseline.schemas`. A string main connection can be used directly. Preserve required native authentication and TLS settings.
+
 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.
+`pg_dump --schema-only --no-owner --no-privileges` and writes `0001_baseline.up.sql` without a down
+file. Install compatible PostgreSQL client tools on PATH, preferably matching the server's major
+version. Capture does not modify source data or history and does not preserve sequence positions.
 
-| Option                | Scope                                                                                |
-| --------------------- | ------------------------------------------------------------------------------------ |
-| `--namespace app`     | Tenon history table to exclude from capture; history/runner scope for later commands |
-| `--schema app`        | Objects selected by native `pg_dump`; repeat to select additional schemas            |
-| Runtime `search_path` | Configured independently on the application connection                               |
+| Setting               | What it selects                                                         |
+| --------------------- | ----------------------------------------------------------------------- |
+| `--namespace app`     | Tenon history table to exclude; history/runner scope for later commands |
+| `--schema app`        | Schema objects included by pg_dump; repeat for more schemas             |
+| Runtime `search_path` | Application name resolution, configured separately                      |
 
-Omitting `--schema` captures the whole database schema, even with a custom namespace. Capture does
-not modify source data/history or preserve sequence positions. It excludes Tenon's selected history
-table but can retain the old runner's metadata tables. Review and commit the SQL. Preserve the
-capture header, which opts this reviewed dump into native baseline parsing; do not add it to
-handwritten migrations.
+Omitting `--schema` captures the whole database schema, even with a custom namespace. The selected
+Tenon history table is excluded; old-runner metadata tables may remain. Review and commit the SQL.
+Preserve the capture header: it opts this reviewed dump into native baseline parsing. Do not add
+that header to handwritten migrations.
 
-A scoped dump can refer to objects it does not include. Provision external schemas, functions,
-extensions, and referenced roles before they are needed. A fresh replay must execute representative
-operations, not just reproduce generated relation types. Tenon requires no particular extension.
+A scoped dump may depend on objects outside its scope. Provision required external schemas,
+extensions, functions, and roles. Fresh replay must exercise representative application operations,
+not merely reproduce table types. Tenon itself requires no particular extension.
 
 ### Check and adopt an existing database
 
-Verify the final legacy checkpoint before adoption. If using schema comparisons, freeze separate
-reference definitions rather than comparing against types regenerated after later migrations.
-`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.
+Confirm that each existing database matches the reviewed final checkpoint. Tenon does not compare
+the live schema with the baseline. Adoption records its checksum without executing its SQL:
 
 ```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.
+The namespace must already exist. Repeating adoption with matching history is harmless, including
+after later migrations; conflicting history fails. Once adopted, leave the baseline unchanged and
+add forward migrations.
+
+For an application-owned schema guard, keep a frozen checkpoint reference. Generated relation types
+do not cover functions or privileges; check required objects separately. Neither generated text nor
+schema-summary formatting is a version-stable fingerprint. If a guard hashes that text, preserve
+its original reference and freeze a separate reviewed reference for each generator version, taken
+from a disposable replay of the immutable checkpoint. Verify that replay against the checkpoint
+before accepting the reference; do not derive it from whichever live database is configured.
+Test both matching adoption and refusal after drift. This is separate from migration checksums.
 
 ### 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.
-
-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,
-and new functions ordinarily permit `PUBLIC` execution. Keep fixed policy such as revoking public
-execution in reviewed baseline SQL before first adoption or in a forward migration. Deployment
-provisioning supplies named roles, owners, and grants. Verify permitted and denied operations on
-both adopted and fresh environments. See the
-[pg_dump contract](https://www.postgresql.org/docs/16/app-pgdump.html).
-
-For development, generate types after migrating; production runs migrations and consumes committed
-types. Test existing-row preservation, repeatable adoption, subsequent migrations, and fresh replay.
-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.
+```sh
+npx tenon migrate --directory migrations --namespace app
+```
+
+Do not adopt a fresh database. Migration executes the committed baseline and subsequent files.
+The dump omits ownership, grants/revokes, and default privileges; objects are recreated under the
+migration role. Deployment provisioning must supply required roles, owners, and grants.
+
+For `SECURITY DEFINER` functions, the recreated owner controls authority. PostgreSQL ordinarily grants
+`PUBLIC` execution on new functions. Put fixed policy such as revoking public execution in reviewed
+baseline SQL before first adoption, or in a forward migration. Supply deployment-specific role names
+and grants during provisioning. Verify permitted and denied operations on adopted and fresh databases.
+
+Test preserved existing rows, repeatable adoption, later migrations, and fresh replay. A schema-only
+baseline is not a backup; the missing down file prevents rollback across it. Use the application's
+backup/recovery procedure for that boundary.
+
+### Baseline API
+
+- `captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })` returns
+  `{ id, upPath }`. Connection is a native libpq connection string passed to pg_dump. Omitting
+  `schemas` captures the whole database schema; an empty list rejects. Warnings default to
+  `console.warn`.
+- `adoptBaseline({ connection, directory?, namespace? })` accepts Tenon's runtime connection forms
+  and returns newly recorded IDs. It requires `0001_baseline.up.sql` with no down file.
+
+Defaults are directory `migrations` and namespace `public`. See [migrations](migrations.md) for
+history validation, per-file transactions, and locking.

package/docs/agent-guide.md

@@ -1,55 +1,20 @@
-# Tenon agent guide
+# Agent guide
 
-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.
+Use this as a short workflow for changing an existing Tenon application. For first setup, follow
+[Getting started](human-guide.md). Exact contracts are in the [reference](reference.md).
 
-## Start with the existing project
+## Read the project first
 
-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 `tenon.config.ts` (or its JavaScript equivalent), the database module, nearby query
+functions, migration runner, generated types, and check commands. Reuse the application's package manager, connection configuration, namespace, and
+conventions. Read the docs shipped with the installed Tenon version.
 
-Inspect its connection configuration, migration runner, generated types, query functions, and check
-commands. Preserve those conventions. Tenon queries and type generation do not require Tenon
-migration history. Keep input validation, authorization, domain conversion, and retry policy in the
-application.
+For an upgrade, find the previous resolved version in the lockfile and read the
+[changelog](../CHANGELOG.md) through the target version and follow its API and driver upgrade
+instructions. Check both Tenon and pgclear versions before changing native
+calls or representations.
 
-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
-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. 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';
-
-const connection = process.env.DATABASE_URL;
-if (!connection) throw new Error('DATABASE_URL is required');
-export const db = createTenon({ connection });
-```
-
-`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
-`search_path`; CLI `--namespace` selects tooling scope, not runtime query names. See
-[connection options](reference.md#installation-and-connection).
-
-## Query and result contracts
+## Write a query function
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
@@ -57,139 +22,91 @@ import type { Database } from './generated-schema.js';
 
 type Summary = Pick<Database['users']['row'], 'id' | 'email'>;
 
-function userById(client: QueryClient, { id }: { id: number }) {
+export function userById(client: QueryClient, { id }: { id: number }) {
   return client.query(sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`, {
     returns: 'oneOrNone',
   });
 }
 ```
 
-`QueryClient` accepts either `db` or a transaction's `tx`. Keep SQL and execution options together.
-`sql<Row>` declares one selected row; it does not verify SQL or validate data. Unannotated fields
-are `unknown`. Generated table types can describe full rows or `Pick` projections; joins and
-aggregates need types for their actual output.
-
-| `returns`          | Result                                             | Required returned rows |
-| ------------------ | -------------------------------------------------- | ---------------------- |
-| `native` (default) | Driver object with `.rows`, `.rowCount`, `.fields` | Any                    |
-| `many`             | `readonly 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.
-
-## Parameters and composition
-
-- 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.
-- `sql.fragment` creates partial SQL with bound values; `sql.join(parts, 'AND' | 'OR' | ',')`
-  combines a nonempty list. Blank fragments fail. Group mixed conditions with parentheses.
-- Full `sql` or `unsafeSql` queries cannot be nested. `unsafeSql<Row>(text, values)` is for trusted
-  external SQL with an explicit values array. Each Tenon query executes one statement.
-
-Use fragments for actual reuse or variable composition. Keep fixed structure in SQL, and retain
-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,535-parameter limit.
-
-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 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/temporal projection](reference.md#persistence-and-domain-values).
-
-## Transactions and native access
-
-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}`, {
-    affectedRows: { exact: 1 },
-  });
-});
-```
-
-Use `tx` for every operation in the callback and await the work. Tenon commits on success and rolls
-back on an escaping error; the callback client expires when the callback finishes. Direct
-BEGIN/COMMIT/ROLLBACK boundaries, nested callback transactions, and automatic retries are not
-provided. Transactions belong to one database instance.
-
-`affectedRows: { exact: n }` or `{ max: n }` checks the final INSERT/UPDATE/DELETE/MERGE count.
-Bounds are nonnegative safe integers. A guarded `db.query` uses a transaction; a guarded `tx.query`
-uses a savepoint. Rejection rolls back that operation. A caught guarded failure permits continued
-work; an unguarded SQL error normally aborts the transaction. Counts exclude extra trigger/cascade
-and CTE effects. 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
-`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
-
-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
+Use a `QueryClient` parameter when callers may pass `db` or `tx`. Keep SQL and execution options
+together. Qualify table names or follow the configured runtime search path.
+
+- Bind values without quotes. Do not mix manual `$n` placeholders into templates.
+- Declare the actual projection with `sql<Row>`. Generated table rows do not describe arbitrary
+  joins/aggregates, and annotations do not validate runtime output.
+- Choose `many`, `oneOrNone`, `one`, or default `native` deliberately. Modes add no SQL limits.
+  A cardinality error alone does not undo an autocommitted write.
+- Use approved `identifier(...)` names and fixed fragments for SQL syntax. Keep mandatory
+  authorization predicates in every branch.
+- Use fragments for real reuse/composition. Runtime loops work but may remain unchecked by the
+  optional checker. See [writing queries](sql.md).
+
+## Preserve representations and validate inputs
+
+Bigint/bigserial and `count(*)` read as exact strings by default; command `rowCount` is a number or
+null. Decimals and temporal values default to strings, bytes to Uint8Array, and JSON to unknown.
+Built-in arrays preserve scalar representations and null elements.
+
+Plain bigint, valid Date, and supported Temporal inputs are accepted; inputs do not change output
+decoders. Plain arrays/objects require `json`, `param`, or encoded text. Direct undefined rejects.
+JSON encoding still rejects bigint. Import parameter/codec helpers from Tenon.
+
+Keep the registry in shared `connection.codecs` so queries and CLI tools agree. Programmatic
+inspection/checking inherit codecs from connection-option values; pass the registry explicitly
+when using a URI. Retain application validation, authorization, domain conversion, and retry
+policy. See [schema types and values](schema-types.md).
+
+## Change data deliberately
+
+Use `sql.insertValues` and `sql.assignments` for object fields while keeping table, predicates,
+expressions, conflicts, and `RETURNING` in SQL. Apply generated insert/update types and narrow
+editable fields with `Pick`.
+
+Missing/undefined insert fields use defaults; assignment fields are omitted; null remains null.
+Empty batches and assignments reject. Explicit column lists select/order fields and can discard
+required inputs. Batch below the complete query's 65,535-parameter limit. See [writing data](mutations.md).
+
+For work that commits together, use `db.transaction` and await every operation through `tx`. A
+callback client expires when it finishes; root/native pool queries do not join it. Tenon owns
+transaction boundaries and provides no automatic retries.
+
+Use `affectedRows: { exact: n }` or `{ max: n }` for write bounds. A root guard uses a transaction;
+a callback guard uses a savepoint. A rejected guarded operation rolls back before throwing, so a
+caught guard failure permits continued work. An unguarded server error normally aborts the
+transaction. Counts exclude additional trigger/cascade/CTE effects. A lost commit response can
+leave an unknown outcome. See [transactions](reference.md#transactions-guarded-writes-and-errors).
+
+## Make schema changes
+
+Keep an existing migration runner. With Tenon's runner, create a new numbered SQL pair, fill both
+files or omit an irreversible down file, and apply it. Never change applied SQL; checksums include
+both directions. Each file commits separately. Use direct or session pooling for tooling advisory
+locks. See [migrations](migrations.md).
+
+After migrations commit, run `tenon generate` with the project's
+[shared configuration](configuration.md). Review the diff and commit migrations with exact
+generated output. Keep handwritten aliases separate and generated files out of formatting. In CI,
+migrate the test database and run `tenon generate --check` without first regenerating. Production
+consumes committed declarations.
+
+## Verify the changed workflow
+
+Run the project's typecheck and database tests for actual rows, effects, permissions, and rollback.
+Use `tenon check` for source contracts and `tenon describe` for finished SQL metadata when useful.
+See [validation tools](reference.md#choosing-a-validation-tool).
+
+The checker fails on definite mismatches and unchecked sites; unproven properties remain notes.
+Fixed composition is supported within bounded variants. Object expansion needs an explicit finite
+shape with required, defined selected fields; optional generated patches may be unchecked. Keep
+intentional omission behavior and test it. Narrow to required fields only when application validation
+establishes that contract; do not cast merely to silence a diagnostic. See
+[responding to findings](query-checking.md#responding-to-findings).
+
+Share runtime connection/codecs through `tenon.config.ts`; CLI generation, checking, inspection,
+and migrations read it. Use `--config` for another role/deployment. Match runtime role, search path,
+timezone, and codecs. Describe uses a separate session and
+cannot establish result nullability, JSON members, cardinality, or execution permissions. Native
+calls bypass Tenon's guards/observations and need explicit resource ownership; see
+[connections and driver access](connections.md). For common failures, use
 [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
-
-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).