@kequtech/tenon-orm 0.4.5 → 0.4.7

package/dist/inspection/types.d.ts

@@ -55,6 +55,8 @@ export interface DescribedType {
     readonly postgres: string;
     /** pgclear read representation, before considering result nullability. */
     readonly readType: string;
+    /** Catalog labels when this enum's effective decoder preserves its default output. */
+    readonly enumLabels?: readonly string[];
 }
 export interface DescribedColumn extends DescribedType {
     readonly name: string;

package/dist/migrations/connection.js

@@ -15,7 +15,7 @@ export async function withMigrationLock(options, mode, work) {
     try {
         lease = await pool.acquire();
         const client = lease;
-        await client.queryClassic(`SELECT pg_advisory_lock${suffix}(hashtextextended($1, 0))`, [lockKey], { codecs: defaultCodecs });
+        await client.queryClassic(`SELECT pg_catalog.pg_advisory_lock${suffix}(pg_catalog.hashtextextended($1, 0))`, [lockKey], { codecs: defaultCodecs });
         locked = true;
         result = await work(client, namespace);
     }
@@ -29,7 +29,7 @@ export async function withMigrationLock(options, mode, work) {
                 if (lease.transactionStatus !== 'idle')
                     await client.queryClassic('ROLLBACK', []);
                 if (locked) {
-                    await client.queryClassic(`SELECT pg_advisory_unlock${suffix}(hashtextextended($1, 0))`, [lockKey], { codecs: defaultCodecs });
+                    await client.queryClassic(`SELECT pg_catalog.pg_advisory_unlock${suffix}(pg_catalog.hashtextextended($1, 0))`, [lockKey], { codecs: defaultCodecs });
                 }
             }
             catch (error) {

package/dist/schema/catalog.d.ts

@@ -0,0 +1,4 @@
+import type { CatalogClient } from '../generation/catalog.js';
+import type { SchemaMetadata } from './types.js';
+/** Versioned catalog contract: change formatVersion when changing fingerprint inputs. */
+export declare function readSchema(client: CatalogClient, namespace: string): Promise<SchemaMetadata>;

package/dist/schema/catalog.js

@@ -0,0 +1,69 @@
+import { migrationTable } from '../migrations/history.js';
+/** Versioned catalog contract: change formatVersion when changing fingerprint inputs. */
+export async function readSchema(client, namespace) {
+    const result = await client.query(`SELECT (pg_catalog.current_setting('server_version_num')::integer / 10000) AS "postgresMajor",
+    COALESCE((
+      SELECT jsonb_agg(jsonb_build_object(
+        'name', c.relname, 'kind', c.relkind, 'persistence', c.relpersistence,
+        'parents', COALESCE((SELECT jsonb_agg(i.inhparent::regclass::text ORDER BY i.inhseqno)
+          FROM pg_inherits i WHERE i.inhrelid = c.oid), '[]'::jsonb),
+        'partitionKey', pg_get_partkeydef(c.oid),
+        'partitionBound', pg_get_expr(c.relpartbound, c.oid, false),
+        'columns', COALESCE((SELECT jsonb_agg(jsonb_build_object(
+          'name', a.attname, 'type', format_type(a.atttypid, a.atttypmod),
+          'nullable', NOT a.attnotnull, 'expression', pg_get_expr(d.adbin, d.adrelid, false),
+          'identity', a.attidentity, 'generated', a.attgenerated,
+          'collation', CASE WHEN a.attcollation <> t.typcollation THEN a.attcollation::regcollation::text END
+        ) ORDER BY a.attnum)
+          FROM pg_attribute a JOIN pg_type t ON t.oid = a.atttypid
+          LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+          WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped), '[]'::jsonb),
+        'constraints', COALESCE((SELECT jsonb_agg(jsonb_build_object(
+          'name', x.conname, 'definition', pg_get_constraintdef(x.oid, false)
+        ) ORDER BY x.conname COLLATE "C") FROM pg_constraint x
+          WHERE x.conrelid = c.oid AND x.contype IN ('p','u','f','c','x')), '[]'::jsonb),
+        'indexes', COALESCE((SELECT jsonb_agg(jsonb_build_object(
+          'name', ic.relname, 'definition', pg_get_indexdef(i.indexrelid, 0, false),
+          'valid', i.indisvalid, 'ready', i.indisready
+        ) ORDER BY ic.relname COLLATE "C") FROM pg_index i
+          JOIN pg_class ic ON ic.oid = i.indexrelid WHERE i.indrelid = c.oid), '[]'::jsonb)
+      ) ORDER BY c.relname COLLATE "C")
+      FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = $1 AND c.relkind IN ('r','p') AND c.relname <> $2
+    ), '[]'::jsonb) AS tables,
+    COALESCE((
+      SELECT jsonb_agg(jsonb_build_object('name', t.typname, 'labels',
+        COALESCE((SELECT jsonb_agg(e.enumlabel ORDER BY e.enumsortorder)
+          FROM pg_enum e WHERE e.enumtypid = t.oid), '[]'::jsonb)
+      ) ORDER BY t.typname COLLATE "C") FROM pg_type t
+      JOIN pg_namespace n ON n.oid = t.typnamespace WHERE n.nspname = $1 AND t.typtype = 'e'
+    ), '[]'::jsonb) AS enums,
+    COALESCE((
+      SELECT jsonb_agg(jsonb_build_object(
+        'name', t.typname, 'type', format_type(t.typbasetype, t.typtypmod),
+        'nullable', NOT t.typnotnull, 'default', pg_get_expr(t.typdefaultbin, 0, false),
+        'collation', CASE WHEN t.typcollation <> b.typcollation THEN t.typcollation::regcollation::text END,
+        'constraints', COALESCE((SELECT jsonb_agg(jsonb_build_object(
+          'name', x.conname, 'definition', pg_get_constraintdef(x.oid, false)
+        ) ORDER BY x.conname COLLATE "C") FROM pg_constraint x WHERE x.contypid = t.oid), '[]'::jsonb)
+      ) ORDER BY t.typname COLLATE "C") FROM pg_type t
+      JOIN pg_type b ON b.oid = t.typbasetype JOIN pg_namespace n ON n.oid = t.typnamespace
+      WHERE n.nspname = $1 AND t.typtype = 'd'
+    ), '[]'::jsonb) AS domains,
+    COALESCE((
+      SELECT jsonb_agg(jsonb_build_object(
+        'name', c.relname, 'type', s.seqtypid::regtype::text,
+        'start', s.seqstart::text, 'increment', s.seqincrement::text,
+        'min', s.seqmin::text, 'max', s.seqmax::text, 'cache', s.seqcache::text, 'cycle', s.seqcycle,
+        'ownedBy', (SELECT jsonb_build_object('schema', rn.nspname, 'table', r.relname, 'column', a.attname)
+          FROM pg_depend d JOIN pg_class r ON r.oid = d.refobjid
+          JOIN pg_namespace rn ON rn.oid = r.relnamespace
+          JOIN pg_attribute a ON a.attrelid = r.oid AND a.attnum = d.refobjsubid
+          WHERE d.classid = 'pg_catalog.pg_class'::regclass AND d.objid = c.oid
+            AND d.refclassid = 'pg_catalog.pg_class'::regclass AND d.deptype IN ('a','i'))
+      ) ORDER BY c.relname COLLATE "C") FROM pg_sequence s
+      JOIN pg_class c ON c.oid = s.seqrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = $1
+    ), '[]'::jsonb) AS sequences`, [namespace, migrationTable]);
+    return { formatVersion: 1, namespace, ...result.rows[0] };
+}

package/dist/schema/types.d.ts

@@ -0,0 +1,70 @@
+import type { DatabaseToolOptions } from '../migrations/connection.js';
+export type SchemaOptions = Pick<DatabaseToolOptions, 'connection' | 'namespace'>;
+export interface SchemaDefinition {
+    readonly name: string;
+    readonly definition: string;
+}
+export interface SchemaColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+    /** Default or generated expression, distinguished by generated. */
+    readonly expression: string | null;
+    readonly identity: '' | 'a' | 'd';
+    readonly generated: '' | 's' | 'v';
+    readonly collation: string | null;
+}
+export interface SchemaTable {
+    readonly name: string;
+    readonly kind: 'r' | 'p';
+    readonly persistence: 'p' | 'u' | 't';
+    readonly parents: readonly string[];
+    readonly partitionKey: string | null;
+    readonly partitionBound: string | null;
+    readonly columns: readonly SchemaColumn[];
+    readonly constraints: readonly SchemaDefinition[];
+    readonly indexes: readonly (SchemaDefinition & {
+        readonly valid: boolean;
+        readonly ready: boolean;
+    })[];
+}
+export interface SchemaEnum {
+    readonly name: string;
+    readonly labels: readonly string[];
+}
+export interface SchemaDomain {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+    readonly default: string | null;
+    readonly collation: string | null;
+    readonly constraints: readonly SchemaDefinition[];
+}
+export interface SchemaSequence {
+    readonly name: string;
+    readonly type: string;
+    readonly start: string;
+    readonly increment: string;
+    readonly min: string;
+    readonly max: string;
+    readonly cache: string;
+    readonly cycle: boolean;
+    readonly ownedBy: {
+        readonly schema: string;
+        readonly table: string;
+        readonly column: string;
+    } | null;
+}
+/** Version 1 covers declared relation/type metadata, not data, functions or security policy. */
+export interface SchemaMetadata {
+    readonly formatVersion: 1;
+    readonly postgresMajor: number;
+    readonly namespace: string;
+    readonly tables: readonly SchemaTable[];
+    readonly enums: readonly SchemaEnum[];
+    readonly domains: readonly SchemaDomain[];
+    readonly sequences: readonly SchemaSequence[];
+}
+export interface SchemaSnapshot extends SchemaMetadata {
+    readonly fingerprint: string;
+}

package/dist/schema/types.js

@@ -0,0 +1 @@
+export {};

package/dist/schema.d.ts

@@ -0,0 +1,4 @@
+import type { SchemaOptions, SchemaSnapshot } from './schema/types.js';
+export type { SchemaOptions, SchemaMetadata, SchemaSnapshot, SchemaTable, SchemaColumn, SchemaEnum, SchemaDomain, SchemaSequence, SchemaDefinition, } from './schema/types.js';
+/** Read a versioned, codec-independent catalog snapshot without executing application SQL. */
+export declare function inspectSchema(options: SchemaOptions): Promise<SchemaSnapshot>;

package/dist/schema.js

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+import { defaultCodecs } from '@kequtech/pgclear';
+import { withMigrationLock } from './migrations/connection.js';
+import { quote } from './sql.js';
+import { plainObject } from './validation.js';
+import { readSchema } from './schema/catalog.js';
+/** Canonical JSON: object keys are sorted; ordered catalog arrays retain their semantic order. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value !== null && typeof value === 'object') {
+        const object = value;
+        return ('{' +
+            Object.keys(object)
+                .sort()
+                .map((key) => JSON.stringify(key) + ':' + canonical(object[key]))
+                .join(',') +
+            '}');
+    }
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new Error('Schema metadata is not JSON serializable.');
+    return json;
+}
+/** Read a versioned, codec-independent catalog snapshot without executing application SQL. */
+export async function inspectSchema(options) {
+    for (const name of Object.keys(plainObject(options, 'Schema options')))
+        if (!['connection', 'namespace'].includes(name))
+            throw new Error(`Unknown schema option: ${name}`);
+    return withMigrationLock(options, 'shared', (client, namespace) => client.transaction(async (transaction) => {
+        const catalog = {
+            query: (text, values = []) => transaction.queryClassic(text, values, { codecs: defaultCodecs }),
+        };
+        const exists = await catalog.query('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [namespace]);
+        if (!exists.rows.length)
+            throw new Error(`Schema ${quote(namespace)} does not exist.`);
+        await catalog.query(`SELECT pg_catalog.set_config(name, value, true) FROM (VALUES
+          ('search_path', 'pg_catalog'), ('quote_all_identifiers', 'on'),
+          ('standard_conforming_strings', 'on'), ('TimeZone', 'UTC'),
+          ('DateStyle', 'ISO, YMD'), ('IntervalStyle', 'postgres'),
+          ('bytea_output', 'hex'), ('extra_float_digits', '3'), ('lc_monetary', 'C')
+        ) AS settings(name, value)`);
+        const metadata = await readSchema(catalog, namespace);
+        const hash = createHash('sha256').update(canonical(metadata)).digest('hex');
+        return { ...metadata, fingerprint: `tenon-schema-v1:sha256:${hash}` };
+    }, { isolation: 'repeatable read', readOnly: true }));
+}

package/docs/adoption-guide.md

@@ -91,7 +91,10 @@ The namespace must already exist. Repeating adoption with matching history is ha
 after later migrations; conflicting history fails. Once adopted, leave the baseline unchanged and
 add forward migrations.
 
-For an application-owned schema guard, keep a frozen checkpoint reference. Generated relation types
+For an application-owned schema guard, keep a frozen checkpoint reference. The versioned
+[schema snapshot API](schema-inspection.md) provides codec- and generator-independent relation
+metadata for new guards; verify any transition against an immutable disposable baseline replay.
+Keep function, security, and migration-history checks independent. Generated relation types
 do not cover functions or privileges; check required objects separately. Neither generated text nor
 schema-summary formatting is a version-stable fingerprint. If a guard hashes that text, preserve
 its original reference and freeze a separate reviewed reference for each generator version, taken

package/docs/configuration.md

@@ -120,12 +120,13 @@ npx tenon new create_users
 npx tenon migrate
 npx tenon generate
 npx tenon generate --check
+npx tenon schema
 npx tenon check
 npx tenon check src/users.ts:23 --json
 npx tenon describe query.sql
 ```
 
-Generation, checking, and inspection require configuration and use its connection and codecs. A
+Generation, schema snapshots, checking, and inspection require configuration and use its connection and codecs. A
 missing or invalid config fails instead of falling back to `DATABASE_URL`. The config chooses which
 environment variables to read; Tenon does not load `.env` files.
 

package/docs/connections.md

@@ -203,7 +203,7 @@ for deadlines, cancellation, and changes queued during reconnect.
 
 ## Update the driver
 
-Tenon depends on `@kequtech/pgclear: ^0.3.3`, which permits compatible 0.3.x patch updates. With npm:
+Tenon depends on `@kequtech/pgclear: ^0.3.4`, which permits compatible 0.3.x patch updates. With npm:
 
 ```sh
 npm update @kequtech/pgclear
@@ -216,3 +216,47 @@ this range and requires an explicit Tenon compatibility update.
 
 If the application imports pgclear directly, declare it as a dependency with a compatible version
 so the package manager can share a copy. See the [changelog](../CHANGELOG.md) when updating Tenon.
+
+### Reuse configuration for a dedicated listener
+
+Keep session settings separate from pool limits when both a query pool and a listener use them:
+
+```ts
+import { builtin, defaultCodecs, type TenonConfig } from '@kequtech/tenon-orm';
+import { listen } from '@kequtech/pgclear';
+
+const session = {
+  codecs: defaultCodecs.with(builtin.timestamptzDate),
+  startupParameters: { search_path: 'app,public' },
+  connectTimeoutMs: 5000,
+};
+export const main = {
+  connection: { ...session, connectionString: process.env.DATABASE_URL, maxConnections: 10 },
+} satisfies TenonConfig;
+
+// Call during startup with the application's validated database URI.
+async function startNotifications(connectionString: string) {
+  return listen(
+    { ...session, connectionString },
+    {
+      channels: [],
+      timeoutMs: 5000,
+      reconnect: false,
+      onNotification: ({ channel, payload }) => console.log(channel, payload),
+    },
+  );
+}
+```
+
+The config remains safe to import without credentials. Pool-only settings (`maxConnections`,
+`maxWaiting`, `acquireTimeoutMs`, `idleTimeoutMs`, `maxLifetimeMs`) belong on the query pool; `listen`
+takes native connection settings and rejects pool limits. A supplied pool does not expose its
+credentials; retain the application-owned connection settings when using both resources.
+
+For multiple SSE/WebSocket consumers, use the complete
+[pgclear shared-listener example](https://github.com/kequtech/pgclear/blob/main/docs/notifications.md#shared-consumer-ownership).
+It demonstrates reference counts, shared readiness, ordered removal/replacement, bounded shutdown,
+and stale-generation guards. Those remain application responsibilities. If a table's actual schema
+must be discovered first, reuse the existing application pool before opening subscriptions; a
+separate listener query hook is unnecessary for that startup workflow. Keep reconciliation after a
+notification gap tied to authoritative application reads.

package/docs/query-checking.md

@@ -62,11 +62,19 @@ Each variant must fit at least one member of a declared result union. Nullabilit
 literal/branded refinements, and unfamiliar decoder types may remain unproven. A broader metadata
 type alone does not reject a narrower application declaration.
 
+For enum results with unchanged default decoding, catalog labels establish exact or superset string
+unions, including when unrelated Date/bigint codecs change. Narrower label subsets and branded
+strings remain unproven. Custom enum decoders keep their registry representations; catalog labels
+never narrow a decoder that transforms them. Disjoint string-literal declarations fail as definite
+mismatches; a declaration with some matching labels remains unproven. Result nullability is outside
+the check.
+
 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.
+not prove value ranges, valid Dates, or textual formats. These general limits are stated once in
+readable output, rather than repeated as diagnostics for ordinary queries.
 
 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;
@@ -83,8 +91,8 @@ dependent result comparisons and inference errors remain unproven. This does not
 - **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:
+Finite optional mutation shapes are supported within the variant budget. A required, narrower
+contract can reduce that budget when application validation always supplies a value:
 
 ```ts
 type ActivePatch = { active: boolean };
@@ -95,14 +103,18 @@ function setActive(id: number, patch: ActivePatch) {
 }
 ```
 
-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.
+If omission is intended, keep optional fields. An explicit column list fixes column selection and
+order; it does not make optional fields required. Empty assignments still reject at runtime, so
+validate the patch if that rejection is not intended. Keep execution tests for the actual effects.
 
 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.
+and observed types, and variant numbers. Readable output groups equivalent findings within each
+query and counts those groups, preserving distinct columns, parameters and types. `--json` retains
+the individual variant findings in the structured report. Ordinary scalar bindings and unknown
+result nullability do not generate per-query findings.
 
 ## Supported composition
 
@@ -132,7 +144,7 @@ runtime SQL, but need database tests. Unknown source is never replaced with inve
 For checking, `insertValues` and `assignments` need an explicit finite shape type:
 
 ```ts
-type NewUser = { email: string; active: boolean };
+type NewUser = { email: string; active?: boolean | undefined };
 
 function createUser(input: NewUser) {
   return sql<{ id: number }>`INSERT INTO public.users
@@ -140,16 +152,37 @@ function createUser(input: NewUser) {
 }
 ```
 
-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.
+For a direct object literal, the checker recovers its actual own fields and value expressions without
+evaluating them. This includes shorthand properties and literals within fixed batches. A broad
+generated shape therefore does not multiply variants for fields absent from the literal. An
+undefined-valued expression still creates defined/omitted branches when its type permits both.
+
+For other inputs, the shape is a trusted expansion contract. 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, unless the input is a recovered literal. Structural typing
+cannot prove the absence of extra own keys or their order, so that assumption is unproven. Object
+aliases, spreads, computed keys and accessors retain this conservative shape analysis; the checker
+does not reconstruct object mutation or evaluate getters.
+
+Optional or undefined-valued fields create bounded SQL variants. With explicit insert columns, an
+absent/undefined cell becomes `DEFAULT`; with inferred columns, a field absent from every row is
+omitted. Fixed batches use each row's defined fields and per-cell defaults. Assignments omit
+absent/undefined fields. SQL NULL stays a bound value and is separate from omission.
+
+The checker describes only variants that can produce SQL. Empty assignments and inferred multi-row batches
+with no defined fields are rejected by the runtime helper before dispatch; the report retains an
+`empty-expansion-rejected` unproven note when such an input is possible. A mutation whose every
+combination rejects is unchecked. These checks do not establish that application input validation
+avoids runtime rejection.
+
+The same 16-variant limit covers optional combinations, surrounding fragments, and parameter OID
+alternatives. Select fewer columns or a narrower validated shape when that limit is exceeded.
+Index signatures, unresolved generic key sets, shape unions, and unknown shapes remain unsupported.
+Fixed literal batches are supported; unknown batch lengths are not. Runtime helpers still accept
+inferred shapes and optional fields without source checking.
+
+For an otherwise finite shape, a constrained generic field uses its base constraint to determine
+defined and omitted variants. Open generic shapes and unconstrained field values remain unchecked.
 
 ## Programmatic use and custom codecs
 
@@ -166,8 +199,20 @@ const report = await checkQueries({
 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
+The report has `ok`, `project`, `queries`, `diagnostics`, `coverage`, and available inspection
+`context`. Coverage counts recognized Tenon query sites in the selected scope:
+
+- `total`: recognized complete query sites, including unsupported ones.
+- `analysed`: sites whose complete SQL variant set was recovered and inspected.
+- `unchecked`: sites with unsupported structure or incomplete inspection, including a site where only
+  some branches were recovered.
+
+An analysed site can still have mismatches or unproven findings; use `ok` and diagnostics for the
+result. Unrelated SQL tags are outside these counts. No recognized sites still fails with zero
+coverage. JSON reports expose the same counts, so focused CI checks can retain visibility of their
+scope without accepting unchecked sites as successes.
+
+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.
 

package/docs/query-inspection.md

@@ -75,6 +75,12 @@ Known read types in `rowType` include null; unknown already includes it. A sourc
 constraint cannot prove result nullability through outer joins, expressions, or grouping. JSON
 members remain unknown.
 
+An enum with its default decoder reports its catalog label union and `enumLabels`, including when
+unrelated Date or bigint codecs are configured. Source checking can verify an exact enum union or
+broader string result annotation against those labels. Narrower application refinements and
+nullability remain unproven. Enum arrays retain their actual wire representation rather than
+becoming arrays of label unions.
+
 | Finding code          | Meaning                                               |
 | --------------------- | ----------------------------------------------------- |
 | `nullability-unknown` | Result nullability is unresolved                      |
@@ -100,6 +106,9 @@ declaration and are shared with generation/source checking. Without known metada
 decoder remains unknown even for a familiar scalar/enum/domain OID. Catalog base types do not
 replace the wire OID's decoder contract.
 
+A custom enum decoder uses its declared output representation and does not receive catalog-label
+narrowing or `enumLabels`, even if it declares `string`: the decoder may transform those labels.
+
 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).

package/docs/reference.md

@@ -2,7 +2,7 @@
 
 For a complete first setup, follow [Getting started](human-guide.md). Task guides explain
 [queries](sql.md), [writes](mutations.md), [schema types](schema-types.md),
-[migrations](migrations.md), and [connections](connections.md).
+[migrations](migrations.md), [schema snapshots](schema-inspection.md), and [connections](connections.md).
 
 ## Installation and connection
 
@@ -44,7 +44,7 @@ handling, timeout bounds, and lifecycle examples. Runtime `search_path` is indep
 
 ### Driver updates
 
-The dependency range is `@kequtech/pgclear: ^0.3.3`. Compatible patches may be updated independently;
+The dependency range is `@kequtech/pgclear: ^0.3.4`. Compatible patches may be updated independently;
 see [driver updates](connections.md#update-the-driver). Tenon re-exports `builtin`, `json`, `param`,
 `defaultCodecs`, and `createTemporalCodecs`, with the driver's `Codec`, `CodecRegistry`, `Parameter`,
 `PgArray`, `TemporalConstructors`, and `TemporalInput` types.
@@ -265,6 +265,8 @@ The bundled TypeScript compiler loads only through that path or the check comman
 Options are `{ connection, target?, project?, session?, timeouts?, codecs?, readTypes? }`.
 Connection is a URI or pool-option values; connection codecs are inherited unless `codecs` is explicit. The report contains `ok`, `project`, `queries`, `diagnostics`, and available
 inspection `context`. Mismatches, unchecked sites, and no sites fail; unproven findings alone do not.
+Readable output groups equivalent findings per query; JSON retains their variant records. General
+limits on runtime values and result nullability do not generate individual diagnostics.
 See [query checking](query-checking.md) for selection, supported composition, and custom decoders.
 
 ## Query inspection
@@ -325,6 +327,7 @@ Unsupported command flags reject.
 ```text
 tenon init [--config path]
 tenon new <name> [--directory migrations]
+tenon schema [--namespace schema]
 tenon generate [--out path] [--namespace schema] [--check]
 tenon migrate [--directory migrations] [--namespace public]
 tenon status [--directory migrations] [--namespace public]
@@ -344,6 +347,7 @@ tenon describe <query.sql> [--role name] [--search-path value] [--time-zone valu
 | `new`                  | Paths of the new empty up/down pair; fill before applying                               |
 | `migrate` / `rollback` | Completed IDs or “nothing to do”; each file commits independently                       |
 | `status`               | JSON `{ applied, pending }`; validates history                                          |
+| `schema`               | Emits a versioned catalog snapshot and fingerprint; requires shared configuration       |
 | `baseline capture`     | Writes a reviewed schema-only baseline using native `pg_dump`                           |
 | `baseline adopt`       | Records baseline history without executing its SQL                                      |
 | `generate`             | Writes output atomically; `--check` rejects missing/stale output without writing        |

package/docs/schema-inspection.md

@@ -0,0 +1,94 @@
+# Schema snapshots and fingerprints
+
+`inspectSchema` reads a versioned catalog snapshot independently of generated TypeScript, codec
+choices, and generator comments. Use it as one part of an application-owned schema checkpoint guard.
+It does not adopt a baseline, execute migrations, or validate a whole database.
+
+With [shared configuration](configuration.md):
+
+```sh
+npx tenon schema
+npx tenon schema --namespace app --database main
+```
+
+The command requires configuration and emits JSON. Namespace selection matches generation:
+`--namespace`, then `generate.namespace`, then `migrations.namespace`, then `public`.
+It writes nothing to the database or filesystem. Save and review the JSON using your existing
+application tooling.
+
+The programmatic API takes an explicit connection and optional namespace, without discovering config:
+
+```ts
+import { inspectSchema } from '@kequtech/tenon-orm';
+
+const snapshot = await inspectSchema({ connection, namespace: 'app' });
+console.log(snapshot.formatVersion, snapshot.postgresMajor, snapshot.fingerprint);
+```
+
+A supplied pool remains application-owned. Catalog reads use default codecs on one borrowed session,
+a read-only repeatable-read transaction, and Tenon's shared migration advisory lock. Temporary
+search-path and deparser settings are restored before release. Snapshot reads pin UTC, ISO dates,
+PostgreSQL interval output, hex bytes, round-trip floats and the C monetary locale, so caller session
+formatting cannot change a fingerprint. Uncoordinated external DDL is outside
+Tenon's migration locking contract.
+
+## Version 1 scope
+
+`SchemaSnapshot` contains `formatVersion: 1`, `postgresMajor`, `namespace`, the collections below,
+and `fingerprint`. Names are sorted using PostgreSQL's C collation. Column, enum-label, and parent
+orders retain their catalog meaning. Public types are readonly.
+
+| Collection        | Included metadata                                                                                                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tables`          | Ordinary and partitioned tables, including attached partitions; persistence, inheritance parents, partition keys and bounds                                                     |
+| Table columns     | Ordered names, formatted PostgreSQL types, column-level nullability, `expression` for defaults/generated expressions, identity/generated kinds, explicit non-default collations |
+| Table constraints | Named primary, unique, foreign-key, check, and exclusion definitions                                                                                                            |
+| Table indexes     | Named definitions, including expressions/predicates, validity and readiness                                                                                                     |
+| `enums`           | All enums in the namespace, with ordered labels, including unused or empty enums                                                                                                |
+| `domains`         | All domains in the namespace, with base type, nullability, default, collation and named constraints                                                                             |
+| `sequences`       | All sequence declarations in the namespace: type, start/increment/min/max/cache/cycle and owned-column association                                                              |
+
+The catalog kind codes are `r` (ordinary table) and `p` (partitioned table); persistence is `p`
+(permanent), `u` (unlogged), or `t` (temporary). Column `identity` is empty, `a` (always), or `d`
+(by default); `generated` is empty, `s` (stored), or `v` (virtual).
+
+Sequence integers are exact strings. Sequence positions and table rows are excluded. The selected
+namespace's `__tenon_migrations` table is excluded; migration-file checksums and adoption history
+remain separate checks.
+
+Version 1 excludes functions and their bodies, privileges/owners, row-security settings and
+policies, triggers, rules, views/materialized views, foreign tables, extension/composite/range type
+definitions, collation definitions, table storage settings and external object definitions.
+Index storage clauses emitted by PostgreSQL's index definition (such as `WITH (fillfactor=...)`)
+are included in that definition and therefore affect the fingerprint.
+References to external objects remain qualified in PostgreSQL definitions. Verify excluded
+application contracts independently; this fingerprint is not proof of complete schema equivalence.
+
+## Fingerprint contract
+
+The fingerprint is `tenon-schema-v1:sha256:<hex>`. It hashes canonical JSON of the metadata, excluding
+the fingerprint itself: object keys are sorted, arrays preserve their order, and strings retain their
+exact content. Database object OIDs and connection values are absent. Schema names and the PostgreSQL
+major version are included. A fresh replay into the same namespace on the same PostgreSQL major
+reproduces the fingerprint despite different OIDs or sequence positions.
+
+Generator syntax, prose and codec changes do not affect this format. Changes to fingerprint inputs
+require a new format version. PostgreSQL owns SQL deparsing; inspect snapshot differences when
+upgrading PostgreSQL, including patch releases. Different major versions deliberately produce
+incomparable checkpoints. This avoids silently assuming that their catalog/deparser contracts match.
+
+## Adopt a reviewed checkpoint
+
+Keep any existing guard until the replacement is verified:
+
+1. Replay the immutable baseline into a disposable database using the intended namespace and
+   PostgreSQL major. Verify it against the existing frozen references and independent checks.
+2. Capture and review the versioned snapshot. Commit its expected fingerprint alongside the
+   application's fixed adoption policy, retaining the original references.
+3. Before adoption, inspect the target and compare it with that reviewed reference. Refuse on a
+   mismatch. Keep function/security/history checks and test matching adoption, preserved rows,
+   repeat adoption, and refusal after relevant drift.
+
+Do not establish the expected fingerprint from whichever live database happens to be configured.
+Tenon's baseline adoption does not automatically perform this comparison. See
+[adoption safety](adoption-guide.md#check-and-adopt-an-existing-database).