@kequtech/tenon-orm 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.4.6
+
+- Add `inspectSchema` and `tenon schema` for versioned, codec-independent catalog snapshots and
+  SHA-256 fingerprints. Version 1 includes scoped relation/type/sequence definitions and PostgreSQL
+  major version; functions, security policy, data and other excluded objects still need independent
+  checks. Existing adoption guards are unchanged. See [schema snapshots](docs/schema-inspection.md).
+- Check bounded optional insert/update mutation shapes, including omission, DEFAULT and nullable
+  values. Empty runtime-rejected combinations remain explicit notes; unresolved SQL and queries
+  beyond the 16-variant budget still fail. Reports include recognized-site coverage counts.
+  Constrained generic fields retain their undefined/DEFAULT branches; zero-variant sites remain
+  unchecked and fail the report.
+- Inspect default-decoded enum outputs as catalog label unions, including with unrelated codec
+  overrides. Source checking proves matching enum output unions while retaining narrower/custom
+  refinements and unknown nullability as unproven.
+- Require pgclear `^0.3.4`, adding `builtin.uuidArray`, safe decode-error column/type context, and
+  a complete shared-listener ownership example. See [connections](docs/connections.md).
+
 ## 0.4.5
 
 - Preserve generated enum and enum-domain label unions when unrelated codecs change, including

package/README.md

@@ -74,7 +74,8 @@ version. For work in an existing project, start with the [agent guide](docs/agen
 - **SQL defines the operation.** Use PostgreSQL joins, aggregates, constraints, and upserts directly.
   Reuse queries with ordinary functions; use fragments when parts of the SQL need to vary.
 - **TypeScript describes the values.** Declare query projections with `sql<Row>`. Optionally generate
-  table read/insert/update types with `tenon generate`.
+  table read/insert/update types with `tenon generate`. Capture a versioned
+  [schema fingerprint](docs/schema-inspection.md) with `tenon schema` for application-owned guards.
 - **Transactions define what commits together.** Use `db.transaction(async (tx) => { ... })` and run
   every participating query through `tx`.
 - **Write guards check affected rows.** `{ affectedRows: { exact: 1 } }` rolls back a write unless

package/dist/check/contracts.js

@@ -144,13 +144,17 @@ export function compareContracts(project, query, variant, description, readTypes
                 continue; // Structural result types may omit additional selected columns.
             const representation = readTypes[column.oid] ?? column.readType;
             const actual = project.types.get(representation);
+            const actualTypes = column.enumLabels?.map((label) => checker.getStringLiteralType(label)) ??
+                (actual && !(actual.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any))
+                    ? [actual]
+                    : undefined);
             const common = {
                 ...at,
                 resultColumn: column.name,
                 expected: checker.typeToString(expected),
                 observed: representation,
             };
-            if (!actual || actual.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any)) {
+            if (!actualTypes) {
                 findings.push({
                     ...common,
                     kind: 'unproven',
@@ -168,8 +172,8 @@ export function compareContracts(project, query, variant, description, readTypes
                     message: `Column ${JSON.stringify(column.name)} is declared as any.`,
                 });
             }
-            else if (!checker.isTypeAssignableTo(actual, nonnull)) {
-                const mismatch = disjoint(project, actual, nonnull);
+            else if (!actualTypes.every((type) => checker.isTypeAssignableTo(type, nonnull))) {
+                const mismatch = actualTypes.every((type) => disjoint(project, type, nonnull));
                 findings.push({
                     ...common,
                     kind: mismatch ? 'mismatch' : 'unproven',

package/dist/check/source.d.ts

@@ -40,7 +40,6 @@ export declare class SourceAnalysis {
     private conditional;
     private template;
     private mutation;
-    private containsUndefined;
     private expression;
     private codecOid;
     private encoderOid;

package/dist/check/source.js

@@ -300,50 +300,94 @@ export class SourceAnalysis {
             if (!property)
                 return this.fail(node, 'expansion-columns', `Column ${name} is absent from the expansion shape.`);
             const type = this.project.checker.getTypeOfSymbolAtLocation(property, shapeNode);
-            if (property.flags & ts.SymbolFlags.Optional || this.containsUndefined(type)) {
-                return this.fail(shapeNode, 'optional-expansion', `Expansion field ${name} may be absent or undefined, changing the SQL. Select required, defined fields for checking.`);
-            }
-            return { name, binding: { node: input, type, field: name } };
+            // Presence follows the same constrained value type used to derive bind hints.
+            const valueType = this.project.checker.getBaseConstraintOfType(type) ?? type;
+            const members = valueType.isUnion() ? valueType.types : [valueType];
+            return {
+                name,
+                type,
+                optional: !!(property.flags & ts.SymbolFlags.Optional) ||
+                    members.some((member) => !!(member.flags & ts.TypeFlags.Undefined)),
+                defined: members.some((member) => !(member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Never))),
+            };
         });
-        const parts = [];
-        if (helper === 'sql.assignments') {
-            if (!fields.length)
-                return this.fail(node, 'empty-expansion', 'An assignment needs at least one field.');
-            for (const [index, field] of fields.entries()) {
-                if (index)
-                    parts.push(', ');
-                parts.push(`${quote(field.name)} = `, field.binding);
+        const inputType = this.project.checker.getTypeAtLocation(input);
+        const rows = helper === 'sql.insertValues' &&
+            (this.project.checker.isArrayType(inputType) || this.project.checker.isTupleType(inputType))
+            ? this.array(input)
+            : [input];
+        if (!rows.length)
+            return this.fail(node, 'empty-expansion', 'Expansion requires a nonempty batch.');
+        let variants = [[]];
+        for (const row of rows) {
+            let choices = [[]];
+            for (const field of fields) {
+                const values = [];
+                if (field.defined)
+                    values.push({ node: row, type: field.type, field: field.name });
+                if (field.optional || !field.defined)
+                    values.push(undefined);
+                choices = choices.flatMap((choice) => values.map((value) => [...choice, value]));
+                if (choices.length * variants.length > variantLimit)
+                    return this.fail(node, 'variant-limit', `Mutation expansion exceeds the ${variantLimit}-variant budget.`);
             }
+            variants = variants.flatMap((variant) => choices.map((choice) => [...variant, choice]));
         }
-        else {
-            const inputType = this.project.checker.getTypeAtLocation(input);
-            const rows = this.project.checker.isArrayType(inputType) || this.project.checker.isTupleType(inputType)
-                ? this.array(input)
-                : [input];
-            if (!rows.length || (!fields.length && rows.length > 1))
-                return this.fail(node, 'empty-expansion', 'Expansion requires a nonempty batch; a default-only insert requires one row.');
-            if (!fields.length)
+        const result = [];
+        let rejected = false;
+        for (const variant of variants) {
+            const selected = node.arguments[1]
+                ? columns.map((_, index) => index)
+                : [
+                    ...new Set(variant.flatMap((row) => row.flatMap((cell, index) => (cell ? [index] : [])))),
+                ];
+            const parts = [];
+            if (helper === 'sql.assignments') {
+                for (const [index, cell] of variant[0].entries()) {
+                    if (!cell)
+                        continue;
+                    if (parts.length)
+                        parts.push(', ');
+                    parts.push(`${quote(columns[index])} = `, cell);
+                }
+                if (!parts.length) {
+                    rejected = true;
+                    continue;
+                }
+            }
+            else if (!selected.length) {
+                if (rows.length > 1) {
+                    rejected = true;
+                    continue;
+                }
                 parts.push('DEFAULT VALUES');
+            }
             else {
-                parts.push(`(${columns.map(quote).join(', ')}) VALUES `);
-                for (const [index, row] of rows.entries()) {
+                parts.push(`(${selected.map((index) => quote(columns[index])).join(', ')}) VALUES `);
+                for (const [index, row] of variant.entries()) {
                     if (index)
                         parts.push(', ');
                     parts.push('(');
-                    for (const [position, field] of fields.entries()) {
+                    for (const [position, column] of selected.entries()) {
                         if (position)
                             parts.push(', ');
-                        parts.push({ ...field.binding, node: row });
+                        parts.push(row[column] ?? 'DEFAULT');
                     }
                     parts.push(')');
                 }
             }
+            result.push({ parts, choices: new Map() });
         }
-        return [{ parts, choices: new Map() }];
-    }
-    containsUndefined(type) {
-        return (!!(type.flags & ts.TypeFlags.Undefined) ||
-            (!!type.isUnion() && type.types.some((part) => this.containsUndefined(part))));
+        if (!result.length)
+            return this.fail(node, 'empty-expansion', 'Every expansion is rejected by the runtime helper: assignments need a defined field and default-only inserts need one row.');
+        if (rejected)
+            this.issues.push({
+                ...location(node),
+                kind: 'unproven',
+                code: 'empty-expansion-rejected',
+                message: 'The runtime helper rejects empty assignments or default-only batches before SQL is sent. Only SQL-producing variants are analysed; validate inputs if rejection is not intended.',
+            });
+        return result;
     }
     expression(input, depth) {
         if (depth > 32)
@@ -461,6 +505,8 @@ export class SourceAnalysis {
         const hints = new Set();
         let uncertain = false;
         const visit = (type) => {
+            if (binding.field !== undefined && type.flags & ts.TypeFlags.Undefined)
+                return;
             if (type.isUnion()) {
                 type.types.forEach(visit);
                 return;

package/dist/check/types.d.ts

@@ -32,5 +32,12 @@ export interface CheckReport {
     readonly ok: boolean;
     readonly queries: readonly CheckedQuery[];
     readonly diagnostics: readonly CheckDiagnostic[];
+    /** Recognized query sites in the selected scope; analysed does not mean mismatch-free. */
+    readonly coverage: CheckCoverage;
     readonly context?: InspectionContext;
 }
+export interface CheckCoverage {
+    readonly total: number;
+    readonly analysed: number;
+    readonly unchecked: number;
+}

package/dist/check.d.ts

@@ -1,4 +1,4 @@
 import type { CheckOptions, CheckReport } from './check/types.js';
-export type { CheckOptions, CheckReport, CheckDiagnostic, CheckedQuery, SourceLocation, } from './check/types.js';
+export type { CheckOptions, CheckReport, CheckCoverage, CheckDiagnostic, CheckedQuery, SourceLocation, } from './check/types.js';
 /** Analyse authored source without importing the application, binding values or executing its SQL. */
 export declare function checkQueries(options: CheckOptions): Promise<CheckReport>;

package/dist/check.js

@@ -47,11 +47,25 @@ export async function checkQueries(options) {
                 ? 'Several queries occupy this line. Put their SQL tags on distinct lines.'
                 : 'No recognized complete Tenon query was found at the selected target.',
         });
-        return { project: project.project, ok: false, queries: [], diagnostics };
+        return {
+            project: project.project,
+            ok: false,
+            queries: [],
+            diagnostics,
+            coverage: { total: selected.length, analysed: 0, unchecked: selected.length },
+        };
     }
     const recovered = selected.map((query) => {
         const analysis = new SourceAnalysis(project, libraries);
         const variants = analysis.recover(query);
+        if (!variants.length && !analysis.issues.some((issue) => issue.kind === 'unchecked')) {
+            analysis.issues.push({
+                ...location(query),
+                kind: 'unchecked',
+                code: 'no-query-variants',
+                message: 'No complete SQL variant could be recovered for this query.',
+            });
+        }
         return { query, variants, diagnostics: analysis.issues };
     });
     const reports = [];
@@ -62,11 +76,15 @@ export async function checkQueries(options) {
     }
     const finish = () => {
         const all = distinct([...diagnostics, ...reports.flatMap((report) => report.diagnostics)]);
+        const analysed = reports.filter((report) => report.status === 'analysed').length;
         return {
             project: project.project,
-            ok: reports.length > 0 && !all.some((diagnostic) => diagnostic.kind !== 'unproven'),
+            ok: analysed > 0 &&
+                analysed === selected.length &&
+                !all.some((diagnostic) => diagnostic.kind !== 'unproven'),
             queries: reports,
             diagnostics: all,
+            coverage: { total: selected.length, analysed, unchecked: selected.length - analysed },
         };
     };
     if (!recovered.some(({ variants }) => variants.length)) {

package/dist/cli.js

@@ -9,6 +9,7 @@ import { loadConfig } from './config/load.js';
 import { initConfig } from './config/init.js';
 import { configConnection } from './config/connection.js';
 import { generateDefinitions } from './generate.js';
+import { inspectSchema } from './schema.js';
 import { writeDefinitions } from './generation/output.js';
 import { validatePath } from './validation.js';
 import { describeQuery } from './describe.js';
@@ -20,9 +21,10 @@ tenon baseline capture|adopt [--directory migrations] [--namespace public]
 baseline capture: [--schema name ...] [--connection native-uri] (default: whole database schema)
 tenon new <name> [--directory migrations] (no database required)
 tenon generate [--out path] [--namespace public] [--check] [--config path]
+tenon schema [--namespace public] (versioned catalog snapshot and fingerprint as JSON)
 tenon describe <query.sql> [--role name] [--search-path schemas] [--time-zone zone]
 tenon check [file.ts[:line]] [--project tsconfig.json] [--json]
-generate/check/describe require tenon.config.ts, .mts, .js or .mjs, or --config path.
+generate/schema/check/describe require tenon.config.ts, .mts, .js or .mjs, or --config path.
 describe: [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
 describe emits JSON metadata; it does not execute the query or verify result annotations.
 check compares source contracts; mismatches, unchecked sites and no sites fail. Unproven types are notes.
@@ -84,7 +86,7 @@ async function main() {
     // Validate explicitly supplied flags, not defaults. Silently ignoring --check
     // on migrate, for example, would turn an intended dry run into a schema change.
     const allowed = new Set(['help']);
-    if (!['describe', 'check', 'generate', 'init'].includes(command ?? ''))
+    if (!['describe', 'check', 'generate', 'schema', 'init'].includes(command ?? ''))
         allowed.add('directory');
     if (!['new', 'describe', 'check', 'init'].includes(command ?? '')) {
         allowed.add('namespace');
@@ -141,12 +143,26 @@ async function main() {
         : baseline || command === 'describe'
             ? positionals.length === 2
             : positionals.length === 1 &&
-                ['migrate', 'generate', 'status', 'rollback'].includes(command ?? '');
+                ['migrate', 'generate', 'schema', 'status', 'rollback'].includes(command ?? '');
     if (!valid) {
-        throw new Error('Choose init, new, baseline capture|adopt, migrate, generate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
+        throw new Error('Choose init, new, baseline capture|adopt, migrate, generate, schema, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
     }
-    if (command === 'generate' || command === 'check' || command === 'describe') {
+    if (command === 'generate' ||
+        command === 'schema' ||
+        command === 'check' ||
+        command === 'describe') {
         const config = await loadConfig(values.config, values.database);
+        if (command === 'schema') {
+            const snapshot = await inspectSchema({
+                connection: configConnection(config.connection),
+                namespace: values.namespace ??
+                    config.generate?.namespace ??
+                    config.migrations?.namespace ??
+                    'public',
+            });
+            process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+            return;
+        }
         if (command === 'generate') {
             const out = values.out === undefined ? config.generate?.out : resolve(values.out);
             if (out === undefined)
@@ -184,7 +200,7 @@ async function main() {
         else {
             for (const diagnostic of report.diagnostics)
                 process.stdout.write(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.kind}] ${diagnostic.code}: ${diagnostic.message}\n`);
-            process.stdout.write(`${report.queries.length} queries, ${report.queries.filter((query) => query.status === 'analysed').length} analysed, ${report.queries.filter((query) => query.status === 'unchecked').length} unchecked, ${report.queries.reduce((count, query) => count + query.variants, 0)} variants described; ${report.diagnostics.filter((diagnostic) => diagnostic.kind === 'mismatch').length} mismatches, ${report.diagnostics.filter((diagnostic) => diagnostic.kind === 'unproven').length} unproven findings.\n`);
+            process.stdout.write(`${report.coverage.total} queries, ${report.coverage.analysed} analysed, ${report.coverage.unchecked} unchecked, ${report.queries.reduce((count, query) => count + query.variants, 0)} variants described; ${report.diagnostics.filter((diagnostic) => diagnostic.kind === 'mismatch').length} mismatches, ${report.diagnostics.filter((diagnostic) => diagnostic.kind === 'unproven').length} unproven findings.\n`);
         }
         if (!report.ok)
             process.exitCode = 1;

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { adoptBaseline, captureBaseline } from './baseline.js';
 export type { CaptureBaselineOptions, CapturedBaseline } from './baseline.js';
 export { generateDefinitions } from './generate.js';
 export type { GenerateOptions } from './generate.js';
+export { inspectSchema } from './schema.js';
+export type { SchemaOptions, SchemaMetadata, SchemaSnapshot, SchemaTable, SchemaColumn, SchemaEnum, SchemaDomain, SchemaSequence, SchemaDefinition, } from './schema.js';
 export { migrate, migrationStatus, rollback } from './migrations.js';
 export type { MigrationStatus } from './migrations.js';
 export type { DatabaseToolOptions } from './migrations/connection.js';

package/dist/index.js

@@ -6,5 +6,6 @@ export { identifier, sql, unsafeSql } from './query.js';
 export { describeQuery } from './describe.js';
 export { adoptBaseline, captureBaseline } from './baseline.js';
 export { generateDefinitions } from './generate.js';
+export { inspectSchema } from './schema.js';
 export { migrate, migrationStatus, rollback } from './migrations.js';
 export { createMigration, readMigrations } from './migrations/files.js';

package/dist/inspection/catalog.d.ts

@@ -4,6 +4,7 @@ interface CatalogType {
     oid: number;
     schema: string;
     name: string;
+    enumLabels: readonly string[] | null;
 }
 interface ColumnSource {
     oid: number;

package/dist/inspection/catalog.js

@@ -5,7 +5,11 @@ export async function readStatementMetadata(client, query) {
         ...new Set([...statement.parameterTypes, ...statement.fields.map((c) => c.dataTypeOid)]),
     ];
     const types = (await client.queryClassic(`
-    SELECT t.oid, n.nspname AS schema, t.typname AS name
+    SELECT t.oid, n.nspname AS schema, t.typname AS name,
+      CASE WHEN t.typtype = 'e' THEN ARRAY(
+        SELECT e.enumlabel::text FROM pg_catalog.pg_enum e
+        WHERE e.enumtypid = t.oid ORDER BY e.enumsortorder
+      ) END AS "enumLabels"
     FROM pg_catalog.pg_type t
       JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
     WHERE t.oid = ANY(pg_catalog.string_to_array($1, ',')::pg_catalog.oid[])

package/dist/inspection/result.js

@@ -7,7 +7,12 @@ export function queryDescription({ statement, types, sources }, context, codecs)
         if (!type)
             throw new Error(`PostgreSQL type OID ${oid} was not found.`);
         const representation = codecs.typescript(oid);
-        const readType = representation ?? 'unknown';
+        const enumLabels = type.enumLabels !== null && representation === 'string' && codecs.isDefaultDecoder(oid)
+            ? type.enumLabels
+            : undefined;
+        const readType = enumLabels === undefined
+            ? (representation ?? 'unknown')
+            : enumLabels.map((label) => JSON.stringify(label)).join(' | ') || 'never';
         if (representation === undefined) {
             issues.set(`type:${oid}`, {
                 code: 'unmapped-type',
@@ -16,7 +21,12 @@ export function queryDescription({ statement, types, sources }, context, codecs)
                 message: `The selected pgclear registry cannot identify the decoder representation for ${type.schema}.${type.name} (OID ${oid}). Supply an application type for this custom decoder.`,
             });
         }
-        return { oid, postgres: `${type.schema}.${type.name}`, readType };
+        return {
+            oid,
+            postgres: `${type.schema}.${type.name}`,
+            readType,
+            ...(enumLabels === undefined ? {} : { enumLabels }),
+        };
     }
     const sourceMap = new Map(sources.map((s) => [`${s.oid}:${s.number}`, s]));
     const names = new Set();

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,6 +62,11 @@ 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. Result nullability remains unproven.
+
 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
@@ -83,8 +88,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,8 +100,9 @@ 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
@@ -132,7 +138,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
@@ -145,11 +151,25 @@ column list so runtime and checking select the same keys/order. Without one, the
 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.
+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 +186,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.
@@ -325,6 +325,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 +345,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).

package/docs/schema-types.md

@@ -272,3 +272,27 @@ It does not check query annotations, pending migrations, functions, privileges,
 object. A driver or generator update can change output without schema drift. Review generated diffs
 after upgrades. Generated text and schema-summary formatting are not version-stable schema
 fingerprints; see [baseline verification](adoption-guide.md#check-and-adopt-an-existing-database).
+
+### UUID array parameters
+
+`builtin.uuidArray` encodes a UUID array parameter with PostgreSQL's UUID-array OID. For a UUID
+`id` column:
+
+```ts
+import { builtin, param, sql } from '@kequtech/tenon-orm';
+
+const ids = ['123e4567-e89b-42d3-a456-426614174000'];
+const query = sql`SELECT id FROM public.users WHERE id = ANY(${param(ids, builtin.uuidArray)})`;
+```
+
+PostgreSQL validates UUID syntax; the codec uses the existing recursive string-array encoding rules,
+including empty arrays and SQL NULL elements. This additive helper does not change default decoding.
+The existing `param(ids, builtin.textArray)::uuid[]` form remains valid.
+
+### Decode error context
+
+`PGCLEAR_DECODE` errors expose `column` and `dataTypeOid` when the failing output field is known.
+These identify the field without adding row values, SQL, or parameters to the error context. The
+original decoder error remains available through `cause`; application-defined causes retain their
+own content. Date/infinity failures still propagate and should retain the application's existing
+fail-closed expiry checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",
@@ -71,7 +71,7 @@
     "printWidth": 100
   },
   "dependencies": {
-    "@kequtech/pgclear": "^0.3.3",
+    "@kequtech/pgclear": "^0.3.4",
     "typescript": "~6.0.2"
   }
 }