@kequtech/tenon-orm 0.1.3 → 0.2.0

package/dist/transaction.js

@@ -1,10 +1,11 @@
-import { executeSql, watchClient } from './connection.js';
+import { reserveConnection } from './driver/session.js';
+import { executeSql } from './connection.js';
 /** The callback owns one connection and expires before commit or rollback begins. */
 export async function withTransaction(pool, work) {
-    const client = await pool.connect();
-    const connection = watchClient(client);
+    const connection = await reserveConnection(pool, 'BEGIN');
+    const client = connection.sql;
     let active = true;
-    let releaseError;
+    let discard = false;
     let savepointId = 0;
     let pending = Promise.resolve();
     let recoveryFailure;
@@ -20,16 +21,16 @@ export async function withTransaction(pool, work) {
             if (!guarded)
                 return readResult(await executeSql(client, text, input));
             const savepoint = `tenon_affected_rows_${++savepointId}`;
-            await client.query(`SAVEPOINT ${savepoint}`);
+            await client.unsafe(`SAVEPOINT ${savepoint}`);
             try {
                 const result = readResult(await executeSql(client, text, input));
-                await client.query(`RELEASE SAVEPOINT ${savepoint}`);
+                await client.unsafe(`RELEASE SAVEPOINT ${savepoint}`);
                 return result;
             }
             catch (error) {
                 try {
-                    await client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
-                    await client.query(`RELEASE SAVEPOINT ${savepoint}`);
+                    await client.unsafe(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+                    await client.unsafe(`RELEASE SAVEPOINT ${savepoint}`);
                 }
                 catch (rollbackError) {
                     // Even if application code catches this error, the outer transaction
@@ -44,14 +45,13 @@ export async function withTransaction(pool, work) {
         return operation;
     };
     try {
-        await client.query('BEGIN');
         const result = await work(query);
         active = false;
         await pending;
         connection.check();
         if (recoveryFailure)
             throw recoveryFailure;
-        const committed = await client.query('COMMIT');
+        const committed = await client.unsafe('COMMIT');
         if (committed.command !== 'COMMIT') {
             throw new Error('PostgreSQL rolled back the aborted transaction.');
         }
@@ -61,15 +61,16 @@ export async function withTransaction(pool, work) {
         active = false;
         await pending;
         try {
-            await client.query('ROLLBACK');
+            connection.check();
+            await client.unsafe('ROLLBACK');
         }
         catch (rollbackError) {
-            releaseError = rollbackError instanceof Error ? rollbackError : new Error('Rollback failed.');
+            discard = true;
             throw new AggregateError([error, rollbackError], 'Transaction and rollback failed.');
         }
         throw error;
     }
     finally {
-        connection.release(releaseError);
+        await connection.release(discard);
     }
 }

package/dist/types.d.ts

@@ -1,14 +1,14 @@
-import type { QueryResult, QueryResultRow } from 'pg';
+import type { QueryResult } from './connection.js';
 import type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 import type { SqlQuery } from './query.js';
 export interface QueryClient {
-    query<Row extends QueryResultRow>(query: SqlQuery<Row>, options?: QueryOptions & {
+    query<Row extends object>(query: SqlQuery<Row>, options?: QueryOptions & {
         readonly returns?: 'native';
     }): NoInfer<Promise<QueryResult<Row>>>;
-    query<Row extends QueryResultRow, Mode extends QueryReturnMode>(query: SqlQuery<Row>, options: QueryOptions & {
+    query<Row extends object, Mode extends QueryReturnMode>(query: SqlQuery<Row>, options: QueryOptions & {
         readonly returns: Mode;
     }): NoInfer<Promise<QueryOutput<Row, Mode>>>;
-    query<Row extends QueryResultRow>(query: SqlQuery<Row>, options: QueryOptions | undefined): NoInfer<Promise<QueryOutput<Row, QueryReturnMode>>>;
+    query<Row extends object>(query: SqlQuery<Row>, options: QueryOptions | undefined): NoInfer<Promise<QueryOutput<Row, QueryReturnMode>>>;
 }
 export type Transaction = QueryClient;
 export type Database = Transaction & {

package/docs/adoption-guide.md

@@ -22,12 +22,11 @@ queries or generate types; keep the existing migration runner if that is the int
 
 3. Replace queries with parameterized SQL in ordinary functions with named object inputs where
    useful. Preserve each caller's projection, null handling, ordering, and transaction behavior.
-   Generated types describe pg values: check bigint/numeric strings, dates, JSON, and arrays when
+   Generated types describe Postgres.js values: check bigint/numeric strings, dates, JSON, and arrays when
    the old ORM transformed them.
-4. If using optional SQL checking, configure the
-   [SafeQL integration](reference.md#sql-checking-with-safeql) and follow the
-   [incremental audit workflow](#adopt-sql-checking-incrementally) below before accepting generated
-   annotations. Run tests against a dedicated test database. Verify
+4. Inspect completed queries and test their behavior using the
+   [inspection workflow](#inspect-queries-during-adoption) below. Declare result types explicitly
+   and run tests against a dedicated test database. Verify
    writes and rollback, relationships, validation, and any hooks you moved into application code or
    SQL. A schema-preserving first release makes application rollback easier.
 5. Remove the old runtime dependency and unused generated code after its callers are gone. Keep the
@@ -50,81 +49,25 @@ in SQL and remove the local utilities after their callers move. Generated `Rows.
 `Rows.Update` types can replace handwritten table inputs; retain application-specific refinements
 and validation. Run the existing write and rollback workflows. See the [mutation cookbook](mutations.md).
 
-## Adopt SQL checking incrementally
-
-For an existing application, including Next.js, SQL checking can run as a separate audit while the
-normal lint/build commands keep their existing database requirements. Extend the existing flat
-ESLint configuration rather than replacing it. After installing the
-[checking dependencies](reference.md#install-and-configure), a single-database setup can use:
-
-```js
-// eslint.sql.config.mjs
-import { defineConfig } from 'eslint/config';
-import baseConfig from './eslint.config.mjs';
-import safeql from '@ts-safeql/eslint-plugin/config';
-import tseslint from 'typescript-eslint';
-import { safeqlPlugin, eslintPlugin } from '@kequtech/tenon-orm/safeql';
-
-const databaseUrl = process.env.DATABASE_URL;
-if (!databaseUrl) throw new Error('DATABASE_URL is required for SQL checking');
-
-export default defineConfig(baseConfig, {
-  files: ['src/**/*.ts', 'src/**/*.tsx'],
-  languageOptions: {
-    parser: tseslint.parser,
-    parserOptions: { projectService: true },
-  },
-  plugins: { tenon: eslintPlugin },
-  rules: { 'tenon/check-composition': 'error' },
-  extends: [
-    safeql.configs.connections({
-      databaseUrl,
-      plugins: [safeqlPlugin],
-      targets: [{ tag: { regex: '.*' } }],
-    }),
-  ],
-});
-```
-
-Preserve existing type-aware parser settings where configured. The broad target above lets Tenon
-recognize aliases; use distinct targets for [multiple databases](reference.md#configuration-choices-and-multiple-databases).
-The example does not load environment files. Use the application's existing environment loader
-and URL selection to supply its migrated development/test database through `DATABASE_URL`.
-
-```json
-{
-  "scripts": {
-    "lint:sql": "eslint --config eslint.sql.config.mjs \"src/**/*.{ts,tsx}\""
-  }
-}
-```
-
-Start with `npm run lint:sql`. Keep both checking rules enabled and distinguish the findings:
+## Inspect queries during adoption
 
-- SQL errors identify problems in reconstructed SQL; review them before accepting inferred types.
-- Missing/mismatched annotations may reflect an outdated type, a deliberate application refinement,
-  or a checker limitation. They are not all demonstrated application bugs.
-- `tenon/check-composition` means SQL analysis was skipped. Add inline selected columns for opaque
-  mutation inputs where useful. Keep reusable authorization policy centralized when its fragments
-  remain unsupported, with database tests for runtime variants.
+Use `describeQuery` from `@kequtech/tenon-orm` on the completed query object, or
+`npx tenon describe query.sql` on a SQL file. Inspection is available with the normal Tenon
+installation and uses no TypeScript compiler API. It works with helpers and runtime-built
+fragments because it receives the final SQL. See [query inspection](query-inspection.md).
 
-Preview fixes on a small module first, without writing source. Invoke ESLint directly to select
-one file, since the script above already supplies a source glob:
+Reuse the application's connection URI and session configuration; compare the reported role,
+search path, and timezone with execution. Inspection uses a separate connection and Postgres.js
+read mappings. Custom parsers and transaction-local state remain application responsibilities.
 
-```sh
-npx eslint --config eslint.sql.config.mjs src/database/profiles.ts --fix-dry-run --format json
-```
+Pair descriptions with durable database tests of actual rows and effects. For each converted
+query, cover the meaningful filter/ownership branches, null relationships, JSON structure, empty
+results, ordering/cursors, and transaction failure/replay behavior as applicable. Describe's success
+does not verify a TypeScript annotation or prove that execution is permitted or succeeds. Preserve
+existing authorization policy and transaction boundaries while making queries available to tests.
 
-Review the proposed annotations, apply selected changes deliberately, and run TypeScript and
-database tests. Broader inferred types may require validation where raw database values enter the
-application. For example, require a finite `Date` before calling `.getTime()`, validate structured
-JSON from `unknown`, and justify CHECK-constrained string refinements with matching schema checks
-or a reviewed column override. Do not globally map timestamps to `Date`: pg can return numeric
-infinities. See [checker mappings](reference.md#supported-sql-and-limitations).
-
-Unsupported queries have not had their SQL verified. Keep database tests for their runtime variants
-and use explained suppressions only where appropriate. Once the intended scope passes, make SQL
-checking a required CI step. Fix commands can also apply other enabled ESLint rules.
+Keep these tests in routine validation. A described query instance does not cover untested source
+queries or detect stale annotations elsewhere.
 
 ## Move migration ownership to Tenon
 
@@ -144,6 +87,26 @@ server's major. Default scope is the whole database schema. Repeat `--schema nam
 explicitly, accounting for dependencies, extensions, and required roles. Tenon's selected history
 table is excluded; old ORM metadata is preserved for deliberate cleanup later.
 
+The baseline recreates application schema, not a complete deployment environment. It omits
+ownership, grants/revokes, and default privileges. PostgreSQL creates replayed objects under the
+migration role. Role definitions and memberships also remain outside the dump. Functions,
+policies, or other object definitions can still refer to roles; provision any referenced roles
+before replay. See the [PostgreSQL pg_dump reference](https://www.postgresql.org/docs/16/app-pgdump.html).
+
+For `SECURITY DEFINER` functions, the owner determines execution authority, and newly created
+functions ordinarily permit `PUBLIC` execution. A captured function body alone does not preserve
+its original security boundary. Keep fixed application policy, such as revoking `PUBLIC` execution,
+in reviewed SQL in the baseline before its first adoption or in a subsequent application migration.
+Deployment provisioning assigns the intended owners, schema access, and grants to runtime roles.
+Keeping all security setup in provisioning is also supported, provided it runs before application access.
+
+On fresh environments, provision required roles, apply migrations, then apply the deployment's
+ownership/grant policy before starting the application. Verify both allowed and denied operations,
+including execution of sensitive functions and access to their underlying tables. For a shared
+database, apply only the selected application's policy. On existing environments, confirm the same
+provisioning procedure is repeatable. After adoption, use subsequent migrations rather than editing
+checksummed history.
+
 Capture changes no source data, migration history, or sequence positions. Review and commit the SQL.
 Keep the capture header: it identifies native dump SQL that bypasses the authored-migration scanner.
 It is a convention, not proof of provenance; do not use it on handwritten migrations. Normal

package/docs/agent-guide.md

@@ -1,6 +1,6 @@
 # Tenon agent guide
 
-Tenon executes PostgreSQL SQL through `pg`, with parameter binding, transactions, optional write
+Tenon executes PostgreSQL SQL through Postgres.js, with parameter binding, transactions, optional write
 limits, SQL migrations, and generated row and mutation input types. Use ordinary functions for reusable queries.
 This guide contains the setup and contracts needed for routine implementation; the
 [reference](reference.md) covers additional options.
@@ -9,13 +9,16 @@ This guide contains the setup and contracts needed for routine implementation; t
 
 1. Inspect the application's connection setup, migrations, generated types, query modules, and check
    commands. Reuse them. Do not replace a working migration runner just to use Tenon queries.
+   For new schemas, prefer plural `snake_case` table names and `snake_case` column names; preserve
+   existing schemas' names.
 2. Write straightforward SQL with explicit selected columns. Use separate complete queries when
    variants return different shapes. Introduce fragments only for actual reuse or variable
    composition.
 3. Put reusable queries in functions. Accept a `QueryClient` and named object inputs when useful;
    keep SQL and query options together. Call the same function with `db` or `tx`.
-4. After SQL changes, run the configured checker, typechecking, and relevant database tests.
-   Generate/repair annotations deliberately and inspect the diff.
+4. After SQL changes, inspect the completed queries and run typechecking and relevant database
+   assertions. Cover meaningful runtime variants and verify declared result contracts against
+   complete relevant rows.
 5. Keep validation, authorization, retries, and parser configuration in the application. A quoted
    identifier or correct row count does not prove authorization.
 
@@ -25,8 +28,7 @@ Requires Node.js 24+, PostgreSQL 16+, ESM, TypeScript 6+, and Node development t
 application's strict TypeScript configuration.
 
 ```sh
-npm install @kequtech/tenon-orm pg
-npm install --save-dev @types/pg
+npm install @kequtech/tenon-orm
 ```
 
 ```ts
@@ -37,9 +39,9 @@ if (!connection) throw new Error('DATABASE_URL is required');
 export const db = createTenon({ connection });
 ```
 
-`connection` accepts a URL, `pg.PoolConfig`, or existing `pg.Pool`. An explicit `{}` selects pg's
+`connection` accepts a URL, Postgres.js options, or an existing Postgres.js client. An explicit `{}` selects the driver's
 environment defaults. Reuse one instance per database connection. `close()` closes owned pools;
-supplied pools remain application-owned and need the application's idle-error handler. Await
+supplied clients remain application-owned. The driver retains its native connection callbacks. Await
 outstanding work before closing. Environment files are not loaded automatically. Qualify SQL names
 or configure `search_path`; CLI `--namespace` does not change runtime query names.
 
@@ -47,14 +49,16 @@ or configure `search_path`; CLI `--namespace` does not change runtime query name
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { User } from './generated-schema.js';
+import type { Rows } from './generated-schema.js';
 
-type Summary = Pick<User, 'id' | 'email'>;
+type Summary = Pick<Rows['users'], 'id' | 'email'>;
 
-function userById(client: QueryClient, { id }: { id: number }) {
-  return client.query(sql<Summary>`SELECT id, email FROM public."User" WHERE id = ${id}`, {
-    returns: 'oneOrNone',
-  });
+function userByIdQuery({ id }: { id: number }) {
+  return sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`;
+}
+
+function userById(client: QueryClient, input: { id: number }) {
+  return client.query(userByIdQuery(input), { returns: 'oneOrNone' });
 }
 
 const user = await userById(db, { id: 42 });
@@ -65,23 +69,29 @@ const user = await userById(db, { id: 42 });
 Unannotated fields stay `unknown`. Generated types describe full table rows; joins, aliases,
 aggregates, and expressions need projection-specific types.
 
-| `returns`          | Result                | Row-count contract |
-| ------------------ | --------------------- | ------------------ |
-| `native` (default) | pg `QueryResult<Row>` | Any                |
-| `many`             | `Row[]`               | Any                |
-| `oneOrNone`        | `Row \| undefined`    | At most one        |
-| `one`              | `Row`                 | Exactly one        |
+| `returns`          | Result                               | Row-count contract |
+| ------------------ | ------------------------------------ | ------------------ |
+| `native` (default) | Postgres.js `QueryResult<Row>` array | Any                |
+| `many`             | `Row[]`                              | Any                |
+| `oneOrNone`        | `Row \| undefined`                   | At most one        |
+| `one`              | `Row`                                | Exactly one        |
 
 `query` options are `{ returns?, affectedRows?, label? }`; unknown options fail. Return modes never
 insert `LIMIT` or `RETURNING`. Returned-row checks alone do not undo autocommitted writes. `label`
-is an optional nonempty diagnostic string.
+is an optional nonempty diagnostic string. Native results are row arrays with `.count`, `.command`,
+and `.columns`; `many` returns a plain row array.
+
+The Postgres.js driver is included. Undefined bound parameters fail. Pass JSON values directly,
+including arrays, rather than calling `JSON.stringify`. Numeric and bigint scalars and arrays read
+as strings. Dates read as `Date`, including invalid dates for timestamp infinities; check validity
+before using them. SQL NULL array elements read as JavaScript null.
 
 ## Parameters and composition
 
 - Ordinary interpolations bind values. Do not quote them or author manual `$n` placeholders inside
-  templates. `undefined` binds SQL null.
+  templates. `undefined` is rejected; use `null` for SQL null.
 - PostgreSQL infers parameter types from SQL. Cast standalone projections, e.g.
-  `SELECT ${value}::float8 AS value`; without a cast, a standalone parameter returns text.
+  `SELECT ${value}::float8 AS value`, so inspection and execution use the same type.
 - Use `id = ANY(${ids}::integer[])` for an array of IDs. Do not build a comma-separated string of
   values.
 - `identifier(schema, table)` quotes separate application-approved components. Ordinary strings such
@@ -98,9 +108,9 @@ For example, share a search condition between a page and count query:
 
 ```ts
 const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
-const page = sql<Summary>`SELECT id, email FROM public."User"
+const page = sql<Summary>`SELECT id, email FROM public.users
   WHERE ${search} ORDER BY id LIMIT ${limit}`;
-const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
+const count = sql<{ count: string }>`SELECT count(*) AS count FROM public.users
   WHERE ${search}`;
 ```
 
@@ -114,115 +124,74 @@ instead of application helpers that enumerate object keys. Keep tables, authoriz
 expressions, conflict behavior and `RETURNING` visible in SQL. Insert missing/undefined fields use
 PostgreSQL defaults; update missing/undefined fields are omitted. Explicit null stays null. Empty
 batches/updates throw; a single default-only insert works. Omit generated columns and batch large
-writes explicitly below the query-wide limit of 65,535 parameters. Expressions and queries are
+writes explicitly below the query-wide limit of 65,533 parameters. Expressions and queries are
 rejected as cell values; write arithmetic, `DEFAULT`, and `excluded.column` in the surrounding SQL.
 
 Use generated `Rows.Insert['table']` and `Rows.Update['table']` for mutation inputs when available;
 narrow editable fields with `Pick`. They account for defaults, nullability, domains, and generated
 columns. Write mappings differ from returned rows: timestamps use `Date | string`, bigint uses
-`string | bigint`, and JSON uses serialized text. See the [input types](reference.md#insert-and-update-inputs).
+`string | bigint`, and JSON accepts native JavaScript values through Tenon's exported `JSONValue` type. See the [input types](reference.md#insert-and-update-inputs).
 
 Selected columns choose and order fields, e.g. `sql.insertValues(rows, ['name', 'score'])`. Unlisted
 fields are ignored. See the [mutation contract](reference.md#object-based-mutation-fragments) and
 [cookbook](mutations.md).
 
-## Configure and run SQL checking
-
-SafeQL checks SQL against the development/test schema and generates or verifies result annotations.
-Configure it normally and add both exports from `@kequtech/tenon-orm/safeql`:
-
-- `safeqlPlugin` goes in each SafeQL connection's `plugins`. It translates Tenon SQL and constant
-  fragments and supplies pg type mappings. SafeQL performs result inference.
-- `eslintPlugin` goes in ESLint's `plugins`, with `tenon/check-composition` enabled. It reports
-  unsupported forms that the adapter skips. It does not wrap SafeQL's rule.
+## Inspect and test completed queries
 
-These tools run during development and CI. Reuse the application's TypeScript parser settings and
-use a TypeScript version supported by the lint toolchain. Generated table types are optional.
+Inspection ships with Tenon and needs no additional setup:
 
-Reuse existing configuration and scripts. For a new setup:
-
-```sh
-npm install --save-dev eslint typescript-eslint @ts-safeql/eslint-plugin
-```
+```ts
+import { describeQuery } from '@kequtech/tenon-orm';
 
-```js
-// eslint.config.mjs
-import { defineConfig } from 'eslint/config';
-import safeql from '@ts-safeql/eslint-plugin/config';
-import tseslint from 'typescript-eslint';
-import { safeqlPlugin, eslintPlugin } from '@kequtech/tenon-orm/safeql';
-
-const databaseUrl = process.env.DATABASE_URL;
-if (!databaseUrl) throw new Error('DATABASE_URL is required for SQL checking');
-
-export default defineConfig({
-  files: ['src/**/*.ts'],
-  languageOptions: {
-    parser: tseslint.parser,
-    parserOptions: { projectService: true },
-  },
-  plugins: { tenon: eslintPlugin },
-  rules: { 'tenon/check-composition': 'error' },
-  extends: [
-    safeql.configs.connections({
-      databaseUrl,
-      plugins: [safeqlPlugin],
-      targets: [{ tag: 'sql' }],
-    }),
-  ],
-});
+const query = userByIdQuery({ id: 42 });
+const description = await describeQuery({ connection, query });
 ```
 
-Point the URL at the intended development/test database with migrations applied. Supply environment
-variables through the application; no `.env` file is loaded here. `projectService` uses each file's
-nearest TypeScript project. Preserve existing type-aware parser settings if already configured.
+Pass the actual query object that will go to `db.query`, including fragments and conditional
+predicates. A small ordinary query-building function can make the same statement available to
+inspection and execution tests. Keep authorization policy inside the builder or shared fragments.
 
-`targets` matches the tag spelling. Add aliases to the target list when using them. For a single
-database, `{ tag: { regex: '.*' } }` includes all Tenon aliases and typed object properties; the
-adapter excludes unrelated tags. The composition rule checks every Tenon query in its ESLint file
-scope, independently of SafeQL's targets.
+For a SQL file with PostgreSQL `$n` placeholders:
 
-Reuse existing lint scripts or add:
-
-```json
-{
-  "scripts": {
-    "lint": "eslint \"src/**/*.ts\"",
-    "lint:fix": "eslint \"src/**/*.ts\" --fix"
-  }
-}
+```sh
+npx tenon describe query.sql
 ```
 
-SQL and annotation errors come from `@ts-safeql/check-sql`; unsupported composition errors come from
-`tenon/check-composition`. Keep both rules enabled.
+Supply `DATABASE_URL` through the application's existing environment setup. Match its role,
+`search_path`, and timezone through the connection URI or optional `session` settings. Review
+the returned `context`; this is a separate connection with Postgres.js read mappings. It does not
+inherit custom parsers, temporary tables, or transaction-local state.
 
-The checker supports constant fragments and `sql.join` with inline nonempty arrays and literal or
-const-string separators. It does not follow runtime-built lists or fragment-returning functions.
-For tested runtime variants, keep an explicit result type and suppress `tenon/check-composition`
-only on the particular query with a reason.
+The report contains parameter/column types and findings with stable issue codes. Result nullability
+is unknown, source `NOT NULL` is informational, and JSON remains unknown. CLI success means the
+statement was described, not that `sql<Row>`, values, permissions, or business behavior were verified.
 
-Mutation helpers accept inline object literals for checking. Runtime inputs, spreads, and
-data-builder results need inline selected columns, e.g. `sql.insertValues(rows, ['name', 'score'])`.
-The check uses all selected columns; it does not validate runtime input values or omission decisions.
+With a test fixture containing user 42, check the database projection and the actual value separately:
 
-For existing applications, use the [incremental audit workflow](adoption-guide.md#adopt-sql-checking-incrementally)
-to preview fixes and review database types versus application refinements.
+```ts
+import assert from 'node:assert/strict';
 
-1. Run the development `db:migrate` script below against the intended development/test database.
-2. Run `npm run lint`. Fix SQL mistakes before accepting generated types.
-3. Run `npm run lint:fix` for missing/stale annotations. It can add
-   `sql<{ id: number; email: string }>` to a query selecting those columns. Review the diff; other
-   enabled ESLint rules may also fix files.
-4. Run the application's typecheck and database tests. CI runs `lint` without `--fix`.
+assert.deepEqual(
+  description.columns.map(({ name, readType }) => [name, readType]),
+  [
+    ['id', 'number'],
+    ['email', 'string'],
+  ],
+);
+const expected = { id: 42, email: 'reader@example.test' } satisfies Summary;
+assert.deepEqual(await userById(db, { id: expected.id }), expected);
+```
 
-For multiple databases, give each connection distinct tag targets or ESLint file scopes. Qualify
-same-named tables with their schemas. See the [connection reference](reference.md#configuration-choices-and-multiple-databases).
+The builder keeps inspection and application SQL together; the query function keeps execution options
+and its `db`/`tx` contract together. Keep simple queries inline when they do not need a shared builder.
+The typed fixture checks the declared shape, the description checks PostgreSQL's projection, and
+execution checks the actual row. None of these proves coverage of other inputs or authorization rules.
 
-Checking verifies SQL and result annotations. Input validation, authorization, JSON contents, and
-runtime query variants still need application checks and database tests. Keep shared policy in
-ordinary functions even when its fragments cannot be checked statically. Use literal newlines in
-SQL templates and bind string values. The [reference](reference.md#supported-sql-and-limitations)
-covers supported composition and parser overrides.
+Run the same query through the real application connection against its test database. Assert full
+relevant rows/effects and exercise meaningful branches: ownership, optional filters, absent joins,
+empty aggregates, pagination ties, JSON validation, and failed/replayed/rolled-back writes as
+applicable. Keep these tests alongside the query; describing a single instance covers only that
+instance. See [query inspection](query-inspection.md) for session options, limits, and issue codes.
 
 ## Transactions and writes
 
@@ -239,7 +208,7 @@ savepoint names beginning with `tenon_affected_rows_`.
 
 Affected counts cover the final command, not extra trigger/cascade/CTE effects. They cannot detect
 the wrong single row. Sequence advances and external effects are not reversible. A lost commit
-acknowledgment may leave the outcome unknown; retry only according to application policy. Native pg
+acknowledgment may leave the outcome unknown; retry only according to application policy. Native Postgres.js
 errors retain their details; `AffectedRowsError` has codes `TENON_AFFECTED_ROWS_MISMATCH` and
 `TENON_AFFECTED_ROWS_UNSUPPORTED`. Cleanup failures can produce `AggregateError`.
 
@@ -288,5 +257,7 @@ partitioned roots; views/foreign tables need authored query types.
 When replacing another ORM, preserve its schema and behavior. If transferring migration ownership,
 capture one reviewed baseline with `tenon baseline capture`, record it only on matching existing
 databases with `tenon baseline adopt`, and use `tenon migrate` on fresh databases. Adoption does not
-compare schemas or run baseline SQL. See [adoption](adoption-guide.md) for the full transition
-procedure. A down migration or schema-only baseline is not a data backup.
+compare schemas or run baseline SQL. Fresh replay omits ownership and grants; apply deployment
+security provisioning before application access, especially for `SECURITY DEFINER` functions.
+See [adoption](adoption-guide.md) for the full transition procedure. A down migration or schema-only
+baseline is not a data backup.