@kequtech/tenon-orm 0.3.1 → 0.4.2

package/docs/mutations.md

@@ -1,11 +1,14 @@
-# Mutation cookbook
+# Writing data
 
-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:
+Write `INSERT`, `UPDATE`, `DELETE`, and `ON CONFLICT` in SQL. Use `sql.insertValues` and
+`sql.assignments` when you have an object of field values; they return fragments for the column/value
+parts of your statement. The [API reference](reference.md#object-based-mutation-fragments) defines
+edge cases and validation rules.
+
+Examples use an existing `db`, import `sql` from Tenon, and assume this table:
 
 ```sql
-CREATE TABLE profiles (
+CREATE TABLE public.profiles (
   id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
   name text NOT NULL UNIQUE,
   bio text DEFAULT 'unwritten',
@@ -14,121 +17,168 @@ CREATE TABLE profiles (
 );
 ```
 
-## Defaults, undefined, and null in batches
+## Insert and return a row
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+
+const profile = await db.query(
+  sql<{ id: number; name: string }>`INSERT INTO public.profiles
+    ${sql.insertValues({ name: 'Ada' })} RETURNING id, name`,
+  { returns: 'one' },
+);
+```
+
+The helper emits `("name") VALUES ($1)` and binds `'Ada'`. PostgreSQL fills defaults. You choose
+`RETURNING` and the result mode explicitly.
+
+## Defaults, undefined, and null
 
 ```ts
 await db.query(
-  sql`INSERT INTO profiles ${sql.insertValues([
-    { name: 'Ada', bio: null },
-    { name: 'Lin', score: 4, bio: undefined },
-  ])} RETURNING id`,
-  { returns: 'many' },
+  sql`INSERT INTO public.profiles ${sql.insertValues([
+    { name: 'Lin', bio: null },
+    { name: 'Jo', score: 4, bio: undefined },
+  ])}`,
 );
 ```
 
-Ada gets the score default and SQL null for bio. Lin gets score 4 and the bio default. Columns stay
-aligned across heterogeneous rows. Empty batches fail; a single default-only object emits
-`DEFAULT VALUES` and still depends on the table's required-column rules.
+Lin gets score 0 and SQL null for bio. Jo gets score 4 and the bio default. Heterogeneous rows stay
+aligned. Missing/undefined insert cells use `DEFAULT`; explicit null remains SQL NULL.
+
+A single default-only object emits `DEFAULT VALUES`, which still fails if the table has an unmet
+required column. Empty batches fail. Multiple default-only rows need an explicit column list.
+
+## Type and select accepted fields
 
-## Input types and runtime validation
+Generate `Database` from the same schema, then narrow the fields the application accepts:
 
 ```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(
-    sql<{ id: number }>`INSERT INTO profiles
-    ${sql.insertValues(input, ['name', 'score'])} RETURNING id`,
+    sql<{ id: number }>`INSERT INTO public.profiles
+      ${sql.insertValues(input, ['name', 'score'])} RETURNING id`,
     { returns: 'one' },
   );
 }
 ```
 
-Annotations, `satisfies`, or helper generic arguments apply generated input types; merely generating
-the file does not check writes. Use `Pick` to narrow accepted fields and retain runtime validation.
-Generated inputs describe defaults and driver representations, not authorization or constraints.
+The explicit column list selects and orders fields and ignores unlisted keys. Keep required insert
+fields in that list: a well-typed object can still produce an invalid insert if selection discards
+its required `name`. Helpers have no schema metadata; PostgreSQL enforces constraints.
 
-Selected columns choose and order fields, ignoring unlisted keys. They can discard a required field
-even when the original object is valid:
+Types apply through annotations, `satisfies`, or helper generic arguments. They do not validate
+external data, authorization, JSON contents, or CHECK constraints. See
+[generated inputs](schema-types.md#insert-and-update-inputs).
 
-```ts
-const input: Rows.Insert['profiles'] = { name: 'Ada' };
-const query = sql`INSERT INTO profiles ${sql.insertValues(input, ['bio', 'score'])}`;
-// Executing this fails: name was discarded and has no default.
-```
+## Patch fields and use expressions
 
-## Patches mixed with expressions
+For a validated `id` and patch:
 
 ```ts
-const patch: Pick<Rows.Update['profiles'], 'name' | 'bio'> = { bio: null };
-await db.query(sql`UPDATE profiles SET ${sql.assignments(patch)}, revision = revision + 1
-  WHERE id = ${id}`);
+const patch: Pick<Database['profiles']['update'], 'name' | 'bio'> = { bio: null };
+await db.query(
+  sql`UPDATE public.profiles SET ${sql.assignments(patch)}, revision = revision + 1
+    WHERE id = ${id}`,
+  { affectedRows: { exact: 1 } },
+);
 ```
 
-Missing/undefined fields are omitted; null clears a nullable field. Put arithmetic and
-`column = DEFAULT` in SQL. Helpers accept values, not SQL expression objects.
+Assignments omit missing/undefined fields. Null clears a nullable field. Put arithmetic,
+`column = DEFAULT`, and other SQL expressions in the surrounding statement; helper cells accept
+bound values, not SQL fragments or expression objects.
 
-An empty patch fails even if the surrounding SQL has other assignments. Branch when an
-expression-only update is intended:
+`sql.assignments` throws if no defined fields remain, even if the surrounding query has another
+assignment. Skip an empty patch, or branch when an expression-only update is intended:
 
 ```ts
 if (patch.name !== undefined || patch.bio !== undefined) {
-  await db.query(sql`UPDATE profiles SET ${sql.assignments(patch)}, revision = revision + 1
-    WHERE id = ${id}`);
+  await db.query(
+    sql`UPDATE public.profiles SET ${sql.assignments(patch)}, revision = revision + 1
+    WHERE id = ${id}`,
+    { affectedRows: { exact: 1 } },
+  );
 } else {
-  await db.query(sql`UPDATE profiles SET revision = revision + 1 WHERE id = ${id}`);
+  await db.query(sql`UPDATE public.profiles SET revision = revision + 1 WHERE id = ${id}`, {
+    affectedRows: { exact: 1 },
+  });
 }
 ```
 
-## Preserve an omitted field during an upsert
+## Upsert without overwriting an omitted field
 
-Given validated `name`, `score`, and optional `bio`, choose conflict behavior explicitly:
+For validated `name`, `score`, and optional `bio`, choose conflict behavior explicitly:
 
 ```ts
 if (bio !== undefined) {
-  await db.query(sql`INSERT INTO profiles ${sql.insertValues({ name, score, bio })}
+  await db.query(sql`INSERT INTO public.profiles ${sql.insertValues({ name, score, bio })}
     ON CONFLICT (name) DO UPDATE SET score = excluded.score, bio = excluded.bio`);
 } else {
-  await db.query(sql`INSERT INTO profiles ${sql.insertValues({ name, score })}
+  await db.query(sql`INSERT INTO public.profiles ${sql.insertValues({ name, score })}
     ON CONFLICT (name) DO UPDATE SET score = excluded.score`);
 }
 ```
 
-The second query preserves an existing bio. Omitting an insert value uses its database default; that
-alone does not decide which fields a conflict update overwrites.
+The second branch preserves an existing bio. Omitting an insert field uses its database default;
+it does not decide whether an upsert overwrites that field.
+
+## Delete with a bound
+
+```ts
+await db.query(sql`DELETE FROM public.profiles WHERE id = ${id}`, {
+  affectedRows: { max: 1 },
+});
+```
+
+Zero or one deletion is allowed; more causes rollback. Use `exact: 1` when absence is also an error.
+Guards work without `RETURNING`. See [transactions and guards](reference.md#transactions-guarded-writes-and-errors).
 
 ## JSON and PostgreSQL arrays
 
-For a table with `payload jsonb` and `tags text[]`, encode JSON separately from the PostgreSQL
-array:
+For an additional table with `payload jsonb` and `tags text[]`:
 
 ```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 })}`,
-);
+await db.query(sql`INSERT INTO public.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.
+`json(value)` encodes a JSON document; `param(value, codec)` chooses a PostgreSQL type and encoder.
+A JSON array and a PostgreSQL array are separate formats. Generated writes accept encoded strings
+or explicit parameters; plain objects/arrays reject. `json(null)` means JSON null, while plain
+`null` means SQL NULL. `json('text')` encodes a JSON string, not an already-encoded document.
+JSON encoding rejects bigint, including nested bigint values.
+
+For int8, use exact strings, bigint, or `param('9007199254740993', builtin.int8)`. For an int8 array,
+use `param(['9007199254740993', null], builtin.int8Array)`. Reads remain strings by default. Plain
+Date and supported Temporal values work as scalar inputs; Date encodes in UTC. Neither input form
+changes the output decoder. See [value mappings](schema-types.md#value-mappings).
 
-## Batches in one transaction
+## Batch within one transaction
 
-For an array `rows` of generated profile inputs:
+For `rows` containing generated profile insert inputs:
 
 ```ts
 await db.transaction(async (tx) => {
   for (let offset = 0; offset < rows.length; offset += 300) {
     const batch = rows.slice(offset, offset + 300);
-    await tx.query(sql`INSERT INTO profiles ${sql.insertValues(batch, ['name', 'bio', 'score'])}`);
+    await tx.query(sql`INSERT INTO public.profiles
+      ${sql.insertValues(batch, ['name', 'bio', 'score'])}`);
   }
 });
 ```
 
-A failure rolls back all batches. Empty input makes no insert calls. Choose a batch size below the
-query-wide 65,535-parameter limit, including surrounding parameters; default cells consume none.
-Tenon does not split batches or choose transaction boundaries for you.
+A failure rolls back every batch; empty input makes no calls. Choose a batch size below the
+query-wide 65,535-parameter limit, counting surrounding interpolations too. Default cells consume
+no parameters. Tenon does not split batches or choose transaction boundaries.
+
+These helpers support optional fields at runtime. The optional source checker needs explicit shape
+types with required selected fields and fixed batch lengths; ordinary generated patch types can
+remain unchecked. See [object expansion checking](query-checking.md#object-expansion).

package/docs/query-checking.md

@@ -0,0 +1,199 @@
+# Checking query types
+
+`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
+npx tenon check src/users.ts
+npx tenon check src/users.ts:23
+npx tenon check src/users.ts:23 --project tsconfig.json --json
+```
+
+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.
+
+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.
+
+## What gets checked
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+import type { Database } from './generated-schema.js';
+
+type Summary = Pick<Database['users']['row'], 'id' | 'email'>;
+export function userQuery(id: number) {
+  return sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`;
+}
+```
+
+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.
+
+| 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.
+
+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.
+
+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
+
+- **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 };
+
+function setActive(id: number, patch: ActivePatch) {
+  return sql`UPDATE public.users SET ${sql.assignments<ActivePatch>(patch, ['active'])}
+    WHERE id = ${id}`;
+}
+```
+
+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.
+
+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
+
+```ts
+const direction = descending ? sql.fragment`DESC` : sql.fragment`ASC`;
+const predicates = [sql.fragment`active = ${true}`, sql.fragment`email <> ${''}`] as const;
+const query = sql<Summary>`SELECT id, email FROM public.users
+  WHERE ${sql.join(predicates, 'AND')} ORDER BY email ${direction}`;
+```
+
+The checker follows inline fragments and const bindings with recoverable initializers, fixed
+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` need an explicit finite shape type:
+
+```ts
+type NewUser = { email: string; active: boolean };
+
+function createUser(input: NewUser) {
+  return sql<{ id: number }>`INSERT INTO public.users
+    ${sql.insertValues<NewUser>(input, ['email', 'active'])} RETURNING id`;
+}
+```
+
+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 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 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({
+  oid: 23,
+  text: {
+    encode: (value: { raw: string }) => value.raw,
+    decode: (raw) => ({ raw }),
+    typescript: 'import("./src/types.js").DecodedInteger',
+  },
+});
+const report = await checkQueries({ connection, project: 'tsconfig.json', codecs });
+```
+
+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,13 +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.
+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,
@@ -34,50 +40,73 @@ 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 `pg`;
-reported read types assume pg's default parsers and do not infer application overrides. Temporary
-tables, uncommitted changes, and transaction-local settings are not inherited. pg reads its normal
-connection environment, including `PGOPTIONS` when URI options are absent. Use explicit URI/session
-settings for reproducibility.
-
-Defaults are a 3-second connection/authentication timeout, a 5-second limit per server statement,
-and a 1-second lock wait. Overrides are positive integer milliseconds, at most 2,147,483,647. URI
-settings cannot disable the statement/lock bounds. A URI `query_timeout` remains pg's separate
-client read timeout. The owned client closes after inspection. These are operation limits, not a
-single overall deadline.
-
-## Result fields
-
-| 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`       | A parameter or result type has no verified driver mapping       |
-| `duplicate-column`    | Repeated result names would overwrite earlier object properties |
+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 as `codecs` to report its read representations; omission uses defaults:
+
+```ts
+import { builtin, defaultCodecs } from '@kequtech/tenon-orm';
+
+const codecs = defaultCodecs.with(builtin.jsonbText);
+const description = await describeQuery({ connection, query, codecs });
+```
+
+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';
@@ -109,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;
@@ -128,9 +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.
+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.
 
-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.
+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.