@kequtech/tenon-orm 0.4.0 → 0.4.2

package/docs/query-checking.md

@@ -1,9 +1,16 @@
-# Check authored queries
+# Checking query types
 
-`tenon check` compares recoverable Tenon SQL with declared TypeScript contracts and the selected
-PostgreSQL database. It reads source and types without importing the application, evaluating parameter
-expressions, binding values, or executing application SQL. Normal query execution continues to trust
-annotations and performs no additional runtime validation.
+`tenon check` compares Tenon SQL in TypeScript source with declared input/result types and PostgreSQL
+metadata. It can catch a missing result property, an int8 result declared as number, or an unsupported
+bound input. It is optional; normal execution still trusts `sql<Row>` annotations.
+
+The checker reads source without importing the application, evaluating input expressions, binding
+values, or executing application SQL. PostgreSQL still parses/analyzes each recovered statement,
+which can take locks. Use a representative migrated development/test database.
+
+## Run a check
+
+Set `DATABASE_URL`, then select a project, file, or one query:
 
 ```sh
 npx tenon check
@@ -12,18 +19,21 @@ npx tenon check src/users.ts:23
 npx tenon check src/users.ts:23 --project tsconfig.json --json
 ```
 
-Omit the target to inspect the TypeScript project's source files. A file target checks all recognized
-queries in that file. A one-based line selects the complete query containing that line, including a
-multiline SQL template or its variable declaration. A line with no query or several queries fails
-explicitly. A fragment alone is not a complete query target.
+A one-based line selects the complete query containing it, including multiline templates and their
+variable declaration line. A line with no query or multiple queries fails. A fragment alone is not
+a complete query target.
+
+The checker discovers `tsconfig.json` from the target's directory or current working directory.
+Use `--project` for another config or project directory; targets must belong to that project.
+It uses the bundled TypeScript 6 compiler and the project's imports, aliases, indexed access,
+`Pick`, unions, and path mappings. `strictNullChecks` is required. Invalid configuration and compiler
+errors in selected files fail the report.
 
-The checker discovers tsconfig.json from the file's directory or current working directory. Use
-`--project` for another configuration or project directory. The target must belong to that project.
-The checker uses the bundled TypeScript 6 compiler with the project's context, imports, aliases,
-indexed access, Pick, unions, and path mappings. strictNullChecks is required. Compiler errors in
-selected source files and invalid compiler configuration fail the report.
+Match runtime role, search path, timezone, and codecs. Session/timeout flags are the same as
+[Describe](query-inspection.md#cli). CLI checks use default codecs; use the programmatic API for
+a custom registry.
 
-## Contracts and findings
+## What gets checked
 
 ```ts
 import { sql } from '@kequtech/tenon-orm';
@@ -35,53 +45,45 @@ export function userQuery(id: number) {
 }
 ```
 
-Recognition follows imported symbols, including aliases, namespaces, barrel re-exports, and const
-aliases. A different library's function named sql is not a Tenon query. Both sql templates and
-unsafeSql with fixed SQL and a fixed values list are supported.
-
-PostgreSQL Describe parses/analyzes each complete recovered variant and returns parameter OIDs and
-ordered result metadata. It can take analysis locks. Run against the intended schema, database role,
-and search path; a representative development/test database is appropriate. Session and timeout
-flags are the same as [Describe](query-inspection.md#cli): --role, --search-path, --time-zone,
---connect-timeout-ms, --statement-timeout-ms, and --lock-timeout-ms. DATABASE_URL is required by the CLI.
-
-Findings have three kinds:
-
-| Kind      | Meaning                                                                                                                                                                | Exit status   |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| mismatch  | Definite contradiction, such as a missing required result property, int8 declared as number, incompatible array elements, invalid SQL, or an invalid driver input type | Failure       |
-| unchecked | SQL structure cannot be recovered, a composition limit is exceeded, or inspection cannot complete                                                                      | Failure       |
-| unproven  | Available evidence cannot prove or disprove the declared type                                                                                                          | Does not fail |
-
-Declared types receive the benefit of the doubt when evidence is inconclusive. SQL result nullability,
-JSON members, branded/literal refinements, and unfamiliar custom decoder types remain unproven. A
-narrow declaration is not rejected merely because Describe supplies a broader representation. Each
-SQL variant must fit at least one member of a declared result union. Additional selected columns are
-allowed by structural result types; missing required properties fail.
-
-Input and read contracts are separate: int8 accepts exact text, bigint, or an explicit encoder and decodes
-as exact strings by default. Plain bigint, Date, and supported native/polyfilled Temporal inputs use
-OID 0 and server inference, just as strings and numbers do. Boolean, bytes, and recoverable pgclear
-json/param calls supply the same explicit OID hints as execution. Unions with different hints produce
-variants. Accepted input types do not prove server ranges, valid Date values, or textual formats.
-Plain objects, arrays, and undefined contradict pgclear's bind API; use explicit parameters or omission. A declared opaque pgclear Parameter is trusted, with its OID
-reported as unproven. Describe then uses server inference; dependent result comparisons and inference
-errors are unproven rather than contradictions. This is a stated limitation, not validation of the
-unknown encoder.
+Recognition follows Tenon's imported symbols through aliases, namespaces, barrel re-exports, and
+const aliases. Unrelated functions named `sql` are ignored. Fixed-text `unsafeSql` calls with fixed
+values lists are also supported. Each recoverable SQL variant goes through PostgreSQL Describe;
+parameter OIDs and result columns are compared with the declared contracts.
 
-## Responding to findings
+| Finding     | Meaning                                                                     | Fails the command? |
+| ----------- | --------------------------------------------------------------------------- | ------------------ |
+| `mismatch`  | A definite contradiction, invalid SQL, or invalid input type                | Yes                |
+| `unchecked` | SQL cannot be recovered, a limit is exceeded, or inspection cannot complete | Yes                |
+| `unproven`  | Metadata cannot prove or disprove the declaration                           | No                 |
+
+Missing required result properties fail; extra selected columns are allowed by structural types.
+Each variant must fit at least one member of a declared result union. Nullability, JSON members,
+literal/branded refinements, and unfamiliar decoder types may remain unproven. A broader metadata
+type alone does not reject a narrower application declaration.
 
-Read each diagnostic's kind and code, then check the selected SQL and input/result declarations:
+Input and output contracts are separate. For example, an int8 input accepts exact text, bigint, or
+an explicit encoder; its default output is a string. Strings, numbers, bigint, Date, and supported
+Temporal inputs use OID 0/server inference. Booleans, bytes, and recoverable `json`/`param` calls
+supply the same OID hints as execution. Unions with different hints create variants. Input types do
+not prove value ranges, valid Dates, or textual formats.
 
-| Finding     | Action                                                                                                                                                                                                                          |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mismatch`  | Correct the SQL or declared contract. For an int8 column, use a string result type; for an invalid bind, use the documented encoder. Recheck after the change.                                                                  |
-| `unchecked` | Inspect the reason. Recoverable SQL may need an explicit shape or fixed composition; runtime-dependent SQL needs database tests. The command fails until unchecked sites are removed from the selected scope or made checkable. |
-| `unproven`  | Retain the declared contract when appropriate, with application validation and tests for the property metadata cannot establish. This note alone does not fail the command.                                                     |
+A plain object, array, or undefined input contradicts the driver's bind API. An opaque `Parameter`
+is trusted, with its unknown OID reported as unproven. Describe uses server inference in that case;
+dependent result comparisons and inference errors remain unproven. This does not validate the encoder.
+
+## Responding to findings
 
-For example, a generated `Database['users']['update']` makes `active` optional. An assignments
-fragment can omit it, so checking that shape is unsupported even when a particular object currently
-contains `active`. If a function always receives a validated boolean, declare that required shape:
+- **Mismatch:** correct the SQL or declared contract, then recheck. For int8 output, use string under
+  default codecs; for arrays/objects as inputs, choose the documented encoder.
+- **Unchecked:** read the reason. An explicit shape or fixed composition may make it recoverable.
+  Runtime-dependent SQL needs database tests. The command fails while unchecked sites remain in
+  the selected scope; narrow the target to check supported sites separately and retain visibility
+  of the remaining coverage.
+- **Unproven:** retain the declaration when justified, with validation/tests for what metadata cannot
+  establish. A note alone does not fail the command.
+
+For example, generated update fields are optional and can disappear from SQL. If application
+validation always supplies a boolean, declare that required contract:
 
 ```ts
 type ActivePatch = { active: boolean };
@@ -92,19 +94,14 @@ function setActive(id: number, patch: ActivePatch) {
 }
 ```
 
-When omission is intentional, retain the optional input and test the resulting SQL and effects.
-An explicit column list does not make an optional property required. Avoid assertions that merely
-hide this difference. Narrow a CLI target to check supported sites independently; report the
-remaining unchecked sites in the project's validation workflow.
-
-Exit zero means no definite mismatch or unchecked site was reported in the selected scope. It does
-not mean JSON members, nullability, cardinality, or every runtime branch was verified. No query sites
-also fails, so an empty or incorrectly selected file cannot appear to pass.
+If omission is intended, keep optional fields and test the SQL/effects. An explicit column list does
+not make optional fields required. Avoid assertions that merely hide this distinction.
 
-The report includes source locations, parameter/column identifiers, expected and observed types, and
-variant numbers. An unsupported site does not stop independent sites. Recoverable branches can still
-expose mismatches when another branch is unchecked. The default output is readable diagnostics and
-counts; --json returns the structured report.
+Exit 0 means no mismatch or unchecked site in the selected scope. It does not establish JSON shape,
+nullability, cardinality, or every runtime branch. No query sites also fails. Independent queries
+continue after an unsupported site, and a recoverable branch can expose a mismatch even when another
+branch is unchecked. Diagnostics include locations, codes, parameter/column identifiers, expected
+and observed types, and variant numbers. `--json` returns the structured report.
 
 ## Supported composition
 
@@ -116,21 +113,22 @@ const query = sql<Summary>`SELECT id, email FROM public.users
 ```
 
 The checker follows inline fragments and const bindings with recoverable initializers, fixed
-identifier names, fixed join lists/separators, and ternaries with recoverable branches. It checks
-both branches without evaluating the condition. Reusing the same conditional fragment preserves
-its branch choice. Separate ternaries using a const condition or an unwritten function parameter also share that choice,
-including simple negation. Repeated mutable guards with unresolved correlation are unchecked. Branch
-reachability through general application control flow is not inferred.
-
-Each query has a fixed budget of 16 complete variants, including parameter OID alternatives, and a
-32-reference composition depth limit. The checker does not evaluate arbitrary fragment factories,
-walk function bodies to reconstruct returned SQL, execute loops, or accept lists that can be mutated
-or escape to arbitrary application code. A runtime fragment, identifier, mutable fragment binding,
-or dynamic join becomes unchecked. Unknown source is never replaced with invented SQL.
+identifiers, fixed join lists/separators, and ternaries with recoverable branches. Both branches are
+checked without evaluating the condition.
+
+Reusing a conditional fragment preserves its branch choice. Separate ternaries using the same const
+condition or an unwritten function parameter also share that choice, including simple negation.
+Repeated mutable guards with unresolved correlation are unchecked. General control-flow reachability
+is not inferred.
+
+Limits are 16 complete variants per query, including parameter OID alternatives, and 32 levels of
+composition references. Arbitrary fragment factories, function-body reconstruction, loops, dynamic
+identifiers, mutable/escaping fragment lists, and runtime joins are unsupported. These can be valid
+runtime SQL, but need database tests. Unknown source is never replaced with invented SQL.
 
 ## Object expansion
 
-For checking, insertValues and assignments require an explicit finite shape type:
+For checking, `insertValues` and `assignments` need an explicit finite shape type:
 
 ```ts
 type NewUser = { email: string; active: boolean };
@@ -141,24 +139,38 @@ function createUser(input: NewUser) {
 }
 ```
 
-The type is a trusted expansion contract; the checker does not read the object. Explicit column
-lists give runtime and checker the same selected keys and order. Without a list, the declared
-shape is assumed to describe exactly the expanded fields; TypeScript's structural typing does not
-prove the absence of extra own properties or their enumeration order. This assumption is reported
-as unproven. Prefer an explicit list when passing application objects.
+The shape is a trusted expansion contract; the checker does not read the object. Prefer an explicit
+column list so runtime and checking select the same keys/order. Without one, the declared shape is
+assumed to describe exactly the expanded fields. Structural typing cannot prove the absence of
+extra own keys or their order, so that assumption is unproven.
 
-Selected fields must be required and exclude undefined. Optional presence changes SQL through
-omission or DEFAULT, so it is unchecked in this version. Unselected optional properties are fine.
-Index signatures, unresolved generic key sets, unions of shapes, and unknown shapes are unchecked.
-Fixed literal batches are supported; unknown batch lengths are unchecked. Runtime helpers can still
-be used with inferred shapes and optional fields, but those query sites cannot be checked yet.
+Selected fields must be required and exclude undefined. Optional presence changes the SQL through
+omission or DEFAULT and is unchecked. Unselected optional properties are fine. Index signatures,
+unresolved generic key sets, shape unions, and unknown shapes are unsupported. Fixed literal batches
+are supported; unknown batch lengths are not. Runtime helpers still accept inferred shapes and
+optional fields.
 
 ## Programmatic use and custom codecs
 
-The checking API has its own entry point so ordinary execution does not load TypeScript:
+The checking API has a separate entry point, so ordinary queries do not load TypeScript:
 
 ```ts
 import { checkQueries } from '@kequtech/tenon-orm/check';
+
+const report = await checkQueries({
+  connection,
+  project: 'tsconfig.json',
+  target: 'src/users.ts',
+});
+if (!report.ok) process.exitCode = 1;
+```
+
+The report has `ok`, `project`, `queries`, `diagnostics`, and available inspection `context`. Options
+also accept `session`, `timeouts`, `codecs`, and `readTypes`. `connection` is a URI.
+
+For a custom codec, pass the same registry as runtime queries. A text codec may declare its output:
+
+```ts
 import { defaultCodecs } from '@kequtech/tenon-orm';
 
 const codecs = defaultCodecs.with({
@@ -169,32 +181,19 @@ const codecs = defaultCodecs.with({
     typescript: 'import("./src/types.js").DecodedInteger',
   },
 });
-const report = await checkQueries({
-  connection,
-  project: 'tsconfig.json',
-  target: 'src/users.ts:23',
-  codecs,
-});
-if (!report.ok) process.exitCode = 1;
+const report = await checkQueries({ connection, project: 'tsconfig.json', codecs });
 ```
 
-The example assumes `src/types.ts` exports `DecodedInteger = { raw: string }`. Pass the same
-registry used by execution. Its known non-NULL read expressions, including declared custom types and
-derived arrays, come from `codecs.typescript(oid)` and `codecs.typescriptTypes()`. Tenon compiles them
-in the application's TypeScript context without importing or executing application modules.
-
-Supply `readTypes: { 23: 'import("./src/types.js").DecodedInteger' }` only when that decoder has no
-known representation, for example when an existing codec cannot be annotated. A mapping cannot
-replace a known registry representation or claim a JSON member shape for default JSON decoding.
-Type expressions resolve from the tsconfig directory; referenced application types/dependencies must
-be available there. A decoder declaration describes what conversion returns, not a validation pass
-performed by the checker.
-
-The CLI uses default codecs. Custom registry configuration belongs in an application-owned checking
-script calling this API. The application chooses that script's configuration; the checker does not
-import configuration or an application entry point automatically.
-
-pgclear owns execution, Describe, value conversion, and codec representation metadata. Tenon owns
-schema queries and declaration rendering as well as source discovery, composition recovery,
-TypeScript comparison, diagnostics, and file output.
-`tenon generate --check` remains a separate generated-file freshness check.
+Here `src/types.ts` must export `DecodedInteger = { raw: string }`. Registry metadata describes
+non-NULL output, including derived arrays. Type expressions compile in the application's project
+without importing/executing its modules; referenced dependencies/types must be available.
+
+Use `readTypes: { 23: 'import("./src/types.js").DecodedInteger' }` only for a decoder with no known
+registry representation. It cannot replace known metadata or claim JSON members for default JSON
+decoding. Expressions resolve from the tsconfig directory. A codec declaration is trusted output
+metadata, not data validation.
+
+Custom configuration belongs in an application-owned checking script; the checker does not load
+application configuration automatically. Generated-file freshness remains a separate
+`db.generateTypes({ out, check: true })` operation. For behavior tests, see
+[query inspection and testing](query-inspection.md).

package/docs/query-inspection.md

@@ -1,8 +1,8 @@
-# Inspect and test queries
+# Inspecting and testing queries
 
-`describeQuery` asks PostgreSQL for a completed statement's parameter/result metadata without
-binding its values or executing it. Inspection is included with Tenon and opens a separate,
-short-lived connection. It works with SQL assembled from fragments and mutation helpers.
+`describeQuery` asks PostgreSQL for a finished statement's parameter and result metadata. It does
+not bind values or execute the statement. Use it to inspect SQL and to support database tests. To
+compare TypeScript source annotations instead, use [query checking](query-checking.md).
 
 ## Inspect completed SQL
 
@@ -18,16 +18,19 @@ const query = sql<{ id: number; total: string }>`
 const description = await describeQuery({ connection, query });
 ```
 
-`query` accepts SQL text or an object with `text`, including `SqlQuery`. Pass the same completed
-query to inspection and execution. Strings use PostgreSQL `$1` placeholders; templates use
-`${value}`. Cast standalone parameters so PostgreSQL can infer their types without runtime values.
-Inspection does not read `sql<Row>`, check `query.values`, or compare an annotation with SQL.
-For SQL with ambiguous parameters, pass `{ text, parameterTypes: [oid, ...] }`; these public
-pgclear Describe hints require no values. Describe still performs server parsing/analysis and may
-take locks.
+Pass the same completed query to inspection and execution. `query` accepts SQL text or an object
+with `text`, including a Tenon `SqlQuery`. Raw SQL uses `$1` placeholders; templates use `${value}`.
+Inspection checks neither `query.values` nor its `sql<Row>` annotation.
+
+Cast standalone parameters so PostgreSQL can infer their types without values. Alternatively pass
+`query: { text, parameterTypes: [oid, ...] }` for explicit Describe hints. PostgreSQL still parses
+and analyzes the statement, which can take locks.
 
 ## Session and timeouts
 
+Inspection opens and closes its own short-lived session. `connection` must be a PostgreSQL URI;
+it does not inherit a runtime pool or transaction:
+
 ```ts
 const description = await describeQuery({
   connection,
@@ -37,48 +40,50 @@ 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.
+Match runtime 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 reject.
 
 `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 `pgclear`. Read types use
-`codecs.typescript(oid)` from the registry passed as `codecs`, or `defaultCodecs` when omitted. Temporary
-tables, uncommitted changes, and transaction-local settings are not inherited. pgclear uses explicit connection configuration; it does not read PG environment variables, pgpass,
-or service files. 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. pg-specific `query_timeout` and `options`
-URI parameters are unsupported; use the documented timeout and session options. The owned client closes after inspection. These are operation limits, not a
-single overall deadline.
-
-## Result fields
-
-| Field                   | Meaning                                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------------------ |
-| `parameters`            | OIDs, qualified PostgreSQL names, and read representations; not JavaScript input contracts |
-| `columns`               | Ordered names, PostgreSQL types, read representations, and source metadata where available |
-| `columns[].nullability` | Always `"unknown"`; source `notNull` is informational                                      |
-| `rowType`               | Conservative `DescribedRow` declaration, or null for no columns/duplicate names            |
-| `issues`                | Findings with stable `code` fields and descriptive messages                                |
-| `context`               | Effective inspection-session settings                                                      |
-
-Known read types in `rowType` include null; unknown types already include it. Source constraints
-cannot establish result nullability through joins, expressions, or grouping. JSON structure stays
-unknown. Handle findings by code:
-
-| Code                  | Meaning                                                               |
-| --------------------- | --------------------------------------------------------------------- |
-| `nullability-unknown` | Result nullability is unresolved                                      |
-| `shape-unknown`       | Listed output columns have unknown shapes/read types                  |
-| `unmapped-type`       | The selected registry cannot identify a custom decoder representation |
-| `duplicate-column`    | Repeated result names reject during object-row execution              |
+effective statement/lock timeouts. Mode is `separate-session`, read mapping profile `pgclear`.
+Temporary tables, uncommitted changes, and transaction-local state are not inherited. PG environment
+variables, pgpass, service files, and `.env` are not loaded.
+
+| Timeout       | Default  | Scope                         |
+| ------------- | -------- | ----------------------------- |
+| `connectMs`   | 3,000 ms | Connection and authentication |
+| `statementMs` | 5,000 ms | Each server statement         |
+| `lockMs`      | 1,000 ms | Lock wait                     |
+
+Overrides are positive integer milliseconds up to 2,147,483,647. These are operation bounds, not a
+single overall deadline. URI settings cannot disable statement/lock bounds. pg-specific
+`query_timeout` and `options` URI parameters are unsupported; use the options above.
+
+## Read the report
+
+| Field                   | Meaning                                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
+| `parameters`            | OIDs, qualified PostgreSQL names, and read representations; these are not input contracts |
+| `columns`               | Ordered names, PostgreSQL types, read representations, and available source metadata      |
+| `columns[].nullability` | Always `"unknown"`; source `notNull` is informational                                     |
+| `rowType`               | Conservative `DescribedRow` declaration, or null for no columns/duplicate names           |
+| `issues`                | Findings with stable `code` and descriptive messages                                      |
+| `context`               | Effective inspection-session settings                                                     |
+
+Known read types in `rowType` include null; unknown already includes it. A source column's NOT NULL
+constraint cannot prove result nullability through outer joins, expressions, or grouping. JSON
+members remain unknown.
+
+| Finding code          | Meaning                                               |
+| --------------------- | ----------------------------------------------------- |
+| `nullability-unknown` | Result nullability is unresolved                      |
+| `shape-unknown`       | Listed columns have unknown shapes/read types         |
+| `unmapped-type`       | A custom decoder has no known representation          |
+| `duplicate-column`    | Repeated result names would fail object-row execution |
 
 ## Custom codecs
 
-Pass the runtime registry explicitly. Inspection decodes only its own catalog/context queries with
-default codecs; the selected registry determines the reported application read representations.
+Pass the runtime registry as `codecs` to report its read representations; omission uses defaults:
 
 ```ts
 import { builtin, defaultCodecs } from '@kequtech/tenon-orm';
@@ -87,21 +92,21 @@ const codecs = defaultCodecs.with(builtin.jsonbText);
 const description = await describeQuery({ connection, query, codecs });
 ```
 
-A raw JSON decoder reports string instead of unknown. Scalar overrides affect derived built-in
-arrays; explicit array overrides win. A custom decoder can declare `text.typescript` to expose its
-actual output expression, including an application type import. Describe includes that expression
-in its conservative row declaration; generation and source checking consume the same metadata.
-Without a known representation, an unfamiliar decoder reports `unknown` with an `unmapped-type`
-issue, even when its catalog type is a known scalar, enum, or domain. Supply an application
-representation when comparing such results with authored types. Catalog base types do
-not replace the wire OID's selected decoder contract. Parameter read representations are not input
-compatibility rules: text can be a valid int8 input while int8 results decode as exact strings.
+That registry reports JSONB output as string. Scalar overrides affect derived built-in arrays;
+explicit array overrides win. Custom `text.typescript` expressions appear in the conservative row
+declaration and are shared with generation/source checking. Without known metadata, a custom
+decoder remains unknown even for a familiar scalar/enum/domain OID. Catalog base types do not
+replace the wire OID's decoder contract.
+
+Inspection's own catalog/context queries use default decoding. Reported parameter read types are
+not encoding rules: exact text can be a valid int8 input while its output also uses text by default.
+See [schema mappings and codecs](schema-types.md#custom-codecs).
 
 ## Test the same statement
 
-For the `public.users` table from the [human guide](human-guide.md), assume a dedicated test fixture
-has rows `{ id: 1, email: 'ada@example.test', active: true }` and
-`{ id: 2, email: 'lin@example.test', active: false }`, and `db` is its runtime connection:
+Use a dedicated test database. For `public.users` from [Getting started](human-guide.md), assume a
+fixture contains `{ id: 1, email: 'ada@example.test', active: true }` and
+`{ id: 2, email: 'lin@example.test', active: false }`. Here `db` and `connection` select that database:
 
 ```ts
 import assert from 'node:assert/strict';
@@ -133,15 +138,15 @@ for (const activeOnly of [false, true]) {
 }
 ```
 
-Description and execution establish different facts. Describe can succeed for invalid bound values,
-a write that violates constraints, or an operation the runtime role cannot execute. Check actual
-rows/effects, JSON, permissions, and rollback in database tests, and run TypeScript. Inspect
-meaningful query variants; one instance does not cover unexercised branches. Expect only reviewed
-findings and keep unexpected ones visible.
+Describe establishes metadata; execution tests establish behavior. Describe may succeed even when
+bound values are invalid, constraints would reject a write, or the role lacks execution permission.
+Test actual rows, write effects, authorization, JSON validation, and rollback. Exercise meaningful
+composition variants and keep unexpected findings visible. Do not test query behavior by matching
+words in documentation or SQL strings.
 
 ## CLI
 
-Save SQL with PostgreSQL placeholders in `query.sql`:
+Save raw SQL in `query.sql`:
 
 ```sql
 SELECT $1::integer AS id, count(*) AS total FROM pg_catalog.pg_class;
@@ -152,12 +157,11 @@ npx tenon describe query.sql
 npx tenon describe query.sql --search-path app,public --time-zone UTC
 ```
 
-The CLI uses `DATABASE_URL` and prints JSON. Session flags are `--role`, `--search-path`, and
-`--time-zone`. Timeout flags are `--connect-timeout-ms`, `--statement-timeout-ms`, and
-`--lock-timeout-ms`. Migration/generation flags such as `--namespace` and `--check` are rejected.
-
-Exit 0 means description succeeded, including reports with unresolved findings. Exit 1 means input,
-connection, timeout, or PostgreSQL analysis failed. The inspected statement is never executed.
+The CLI reads `DATABASE_URL` and prints JSON using default codecs. Session flags are `--role`,
+`--search-path`, and `--time-zone`; timeout flags are `--connect-timeout-ms`,
+`--statement-timeout-ms`, and `--lock-timeout-ms`. Unsupported flags, including `--namespace` and
+`--check`, reject.
 
-See [source-aware checking](query-checking.md) for the separate TypeScript/SQL contract
-checking command. `tenon generate --check` only checks generated-file freshness.
+Exit 0 means inspection succeeded, even with unresolved findings. Input, connection, timeout, or
+PostgreSQL analysis failures exit 1. The inspected statement is never executed. Generated-file
+freshness uses `db.generateTypes({ out, check: true })`, a separate operation.