@kequtech/tenon-orm 0.4.0 → 0.4.3

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 `Database` 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,23 +17,41 @@ 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';
@@ -40,108 +61,124 @@ 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: Database['profiles']['insert'] = { name: 'Ada' };
-const query = sql`INSERT INTO profiles ${sql.insertValues(input, ['bio', 'score'])}`;
-// Executing this fails: name was discarded and has no default.
-```
+## Patch fields and use expressions
 
-## Patches mixed with expressions
+For a validated `id` and patch:
 
 ```ts
 const patch: Pick<Database['profiles']['update'], 'name' | 'bio'> = { bio: null };
-await db.query(sql`UPDATE profiles SET ${sql.assignments(patch)}, revision = revision + 1
-  WHERE id = ${id}`);
+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(tags), tags: param(tags, builtin.textArray) })}`,
-);
+await db.query(sql`INSERT INTO public.deliveries
+  ${sql.insertValues({ payload: json(tags), tags: param(tags, builtin.textArray) })}`);
 ```
 
-Generated JSON writes accept pgclear parameters or encoded strings. `json(value)` encodes objects,
-arrays, strings, and JSON null; plain `null` means SQL NULL. Arrays need `param(value, codec)` or
-encoded PostgreSQL text. Plain arrays, objects, and undefined reject as bound values. Tenon passes
-explicit parameters unchanged to pgclear. `json()` still rejects bigint values, including bigint
-nested inside objects; bigint support for ordinary SQL parameters does not change JSON encoding.
-
-For bigint/bigserial fields, generated writes accept exact strings, bigint, or explicit parameters;
-reads remain strings by default. Use `param('9007199254740993', builtin.int8)` for an explicit int8
-parameter and `param(['9007199254740993', null], builtin.int8Array)` for an int8 array. The bigint
-output codec and matching array encoder are separate opt-in choices.
+`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.
 
-Date and supported Temporal values can be ordinary scalar inputs, including mutation fields. Date
-encodes in UTC; Temporal calendar dates, wall times, and instants retain their distinct meanings.
-Choose the value appropriate to the PostgreSQL column and retain application validation.
+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

@@ -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 CLI imports the selected configuration module; the checker then reads query source without
+importing those modules, 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
+
+Create [shared configuration](configuration.md), then select a project, file, or one query:
 
 ```sh
 npx tenon check
@@ -12,18 +19,22 @@ 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 CLI uses `check.project`, defaulting to `tsconfig.json` beside the shared config. Use `--project`
+for another TypeScript config or project directory; targets must belong to that project. Configured
+paths resolve from the shared config; CLI targets and path flags resolve from the working directory.
+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 inherit the shared connection
+and codec registry. Inspection-only session settings and flags override runtime startup settings.
 
-## Contracts and findings
+## What gets checked
 
 ```ts
 import { sql } from '@kequtech/tenon-orm';
@@ -35,53 +46,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 +95,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 +114,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 +140,40 @@ 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 or pool-option
+values; its `codecs` are inherited unless the explicit inspection `codecs` argument is supplied.
+The programmatic API does not discover shared configuration.
+
+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 +184,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.
+
+The CLI loads the shared configuration for custom codecs; no checking script is required. An
+application-owned script may still call the programmatic API with explicit options. Generated-file
+freshness remains a separate `tenon generate --check` operation. For behavior tests, see
+[query inspection and testing](query-inspection.md).