@kequtech/tenon-orm 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.5
+
+- Preserve generated enum and enum-domain label unions when unrelated codecs change, including
+  Date and bigint decoding. Custom enum decoders retain their declared output types; unidentified
+  decoders still warn and generate `unknown`. Enum write inputs retain catalog choices.
+- Require pgclear `^0.3.3` for per-type default-decoder metadata and dynamic notification
+  subscriptions. Native listeners can add and remove channels on one dedicated connection; see
+  [notifications](docs/connections.md#listen-for-notifications) for ownership and recovery.
+
+## 0.4.4
+
+- Pass the shared `TenonConfig` directly to `createTenon`, including its connection, codecs, and
+  `onQuery` observer. `TenonConfig` replaces the `TenonOptions` type.
+- Defer pool creation and connection validation until the first query, transaction, or native-pool
+  access. Importing configuration and closing an unused instance need no credentials. Generated
+  configs use plain environment reads; remove eager credential checks from existing configs.
+- Support named config exports for multiple databases and CLI selection with `--database`. A sole
+  config is selected automatically; ambiguous or unknown names fail without fallback. `tenon init`
+  generates a named `main` export, and existing default exports remain supported.
+- Allow migration-file creation without database credentials while retaining each selected config's
+  migration, generation, and checking settings.
+
 ## 0.4.3
 
 - Add shared runtime/CLI configuration and offline `tenon init`. Restore `tenon generate`, share migration defaults, and require config for generation/checking/inspection.

package/README.md

@@ -15,14 +15,14 @@ typings. The PostgreSQL driver, [pgclear](https://github.com/kequtech/pgclear),
 
 ## Query with SQL
 
-This example assumes a `public.users` table with integer `id` and text `email` columns:
+This example assumes a `public.users` table with integer `id` and text `email` columns and a
+`main` export in your [shared configuration](docs/configuration.md):
 
 ```ts
 import { createTenon, sql } from '@kequtech/tenon-orm';
+import { main } from './tenon.config.ts';
 
-const connection = process.env.DATABASE_URL;
-if (!connection) throw new Error('DATABASE_URL is required');
-const db = createTenon({ connection });
+const db = createTenon(main);
 
 try {
   const email = 'reader@example.test';
@@ -97,10 +97,12 @@ choosing application types.
 
 ## Share configuration with the CLI
 
-Run `tenon init` to create `tenon.config.ts`, put connection settings and codecs there, and use its
-`connection` in `createTenon`.
-Then run `tenon generate`, `tenon generate --check`, `tenon check`, and `tenon describe query.sql`
-without custom scripts. Migration commands also use the shared connection and migration defaults.
+Run `tenon init` to create `tenon.config.ts`. Put connection settings and codecs in its `main` export,
+then reuse that object with `createTenon(main)`. Initialization stays lazy, so builds that only import
+the database instance need no credentials.
+
+The CLI uses the same config for migrations, `tenon generate`, freshness checks, `tenon check`, and
+`tenon describe query.sql`. For multiple databases, add named exports and select one with `--database`.
 See [shared configuration](docs/configuration.md) for the complete setup.
 
 ## Documentation

package/dist/cli.js

@@ -7,6 +7,7 @@ import { adoptBaseline, captureBaseline } from './baseline.js';
 import { describeFlags, inspectionSettings } from './inspection/cli.js';
 import { loadConfig } from './config/load.js';
 import { initConfig } from './config/init.js';
+import { configConnection } from './config/connection.js';
 import { generateDefinitions } from './generate.js';
 import { writeDefinitions } from './generation/output.js';
 import { validatePath } from './validation.js';
@@ -26,7 +27,8 @@ describe: [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-time
 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.
 rollback: --steps 1
-All commands accept --config path. Migration commands fall back to DATABASE_URL only without config.
+All commands accept --config path. Database commands accept --database <export> to select a named config.
+Multiple database exports require --database. Migration commands fall back to DATABASE_URL only without config.
 `;
 function warn(message) {
     process.stderr.write(`Warning: ${message}\n`);
@@ -59,6 +61,7 @@ async function main() {
             connection: { type: 'string' },
             namespace: { type: 'string' },
             config: { type: 'string' },
+            database: { type: 'string' },
             out: { type: 'string' },
             check: { type: 'boolean', default: false },
             schema: { type: 'string', multiple: true },
@@ -94,6 +97,8 @@ async function main() {
         allowed.add('check');
     }
     allowed.add('config');
+    if (command !== 'init')
+        allowed.add('database');
     if (command === 'baseline' && argument === 'capture') {
         allowed.add('schema');
         allowed.add('connection');
@@ -122,7 +127,7 @@ async function main() {
         if (positionals.length !== 2) {
             throw new Error('Use new <name> to create a migration pair.');
         }
-        const config = await loadConfig(values.config, false);
+        const config = await loadConfig(values.config, values.database, false);
         const files = await createMigration({
             name: argument,
             directory: values.directory ?? config?.migrations?.directory ?? 'migrations',
@@ -141,14 +146,14 @@ async function main() {
         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.');
     }
     if (command === 'generate' || command === 'check' || command === 'describe') {
-        const config = await loadConfig(values.config);
+        const config = await loadConfig(values.config, values.database);
         if (command === 'generate') {
             const out = values.out === undefined ? config.generate?.out : resolve(values.out);
             if (out === undefined)
                 throw new Error('Configure generate.out or pass --out.');
             const namespace = values.namespace ?? config.generate?.namespace ?? config.migrations?.namespace;
             const source = await generateDefinitions({
-                connection: config.connection,
+                connection: configConnection(config.connection),
                 onWarning: warn,
                 ...(namespace !== undefined && { namespace }),
             });
@@ -158,7 +163,7 @@ async function main() {
         }
         const flags = inspectionSettings(values);
         const settings = {
-            connection: config.connection,
+            connection: configConnection(config.connection),
             session: { ...config.session, ...flags.session },
             timeouts: { ...config.timeouts, ...flags.timeouts },
         };
@@ -185,11 +190,11 @@ async function main() {
             process.exitCode = 1;
         return;
     }
-    const config = await loadConfig(values.config, false);
+    const config = await loadConfig(values.config, values.database, false);
     const capture = command === 'baseline' && argument === 'capture';
     const connection = values.connection ??
         (capture ? config?.baseline?.connection : undefined) ??
-        config?.connection ??
+        (config === undefined ? undefined : configConnection(config.connection)) ??
         process.env.DATABASE_URL;
     if (!connection)
         throw new Error('DATABASE_URL is required.');

package/dist/config/connection.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectionOptions } from '../connection.js';
+/** Resolve only when a command or application actually needs its configured database. */
+export declare function configConnection(value: unknown): string | ConnectionOptions;

package/dist/config/connection.js

@@ -0,0 +1,22 @@
+import { plainObject } from '../validation.js';
+/** Resolve only when a command or application actually needs its configured database. */
+export function configConnection(value) {
+    if (value === undefined) {
+        throw new Error('Tenon config connection is required. Check its database environment variables.');
+    }
+    if (typeof value === 'string') {
+        if (!value.trim())
+            throw new Error('Tenon config connection string must be nonempty.');
+        return value;
+    }
+    if (value !== null && typeof value === 'object' && ('acquire' in value || 'close' in value)) {
+        throw new Error('Tenon config requires connection options, not an open pool.');
+    }
+    const connection = plainObject(value, 'Tenon config connection');
+    // An explicitly configured URI must never silently fall back to the driver's local defaults.
+    if ('connectionString' in connection &&
+        (typeof connection.connectionString !== 'string' || !connection.connectionString.trim())) {
+        throw new Error('Tenon config connectionString must be nonempty. Check its database environment variables.');
+    }
+    return connection;
+}

package/dist/config/init.js

@@ -18,11 +18,8 @@ export async function initConfig(filename) {
         }
     }
     const typed = extension === '.ts' || extension === '.mts';
-    const source = `${typed ? "import type { TenonConfig } from '@kequtech/tenon-orm';\n\n" : ''}const connectionString = process.env.DATABASE_URL;
-if (!connectionString) throw new Error('DATABASE_URL is required');
-
-export default {
-  connection: { connectionString },
+    const source = `${typed ? "import type { TenonConfig } from '@kequtech/tenon-orm';\n\n" : ''}export const main = {
+  connection: { connectionString: process.env.DATABASE_URL },
   migrations: { directory: 'migrations', namespace: 'public' },
   generate: { out: 'src/generated-schema.d.ts' },
   check: { project: 'tsconfig.json' },

package/dist/config/load.d.ts

@@ -3,5 +3,5 @@ export declare const configNames: string[];
 /** Find configuration without importing it, including for offline initialization. */
 export declare function findConfig(directory?: string): Promise<string | undefined>;
 /** Import only the selected trusted configuration module; never discover application entry points. */
-export declare function loadConfig(filename?: string): Promise<TenonConfig>;
-export declare function loadConfig(filename: string | undefined, required: false): Promise<TenonConfig | undefined>;
+export declare function loadConfig(filename?: string, database?: string): Promise<TenonConfig>;
+export declare function loadConfig(filename: string | undefined, database: string | undefined, required: false): Promise<TenonConfig | undefined>;

package/dist/config/load.js

@@ -4,6 +4,7 @@ import { pathToFileURL } from 'node:url';
 import { sessionOptions, timeoutOptions } from '../inspection/options.js';
 import { validateName } from '../sql.js';
 import { plainObject, validatePath } from '../validation.js';
+import { configObject, configSection } from './validate.js';
 export const configNames = [
     'tenon.config.ts',
     'tenon.config.mts',
@@ -20,13 +21,20 @@ async function exists(path) {
         throw error;
     }
 }
-function keys(value, label, allowed) {
-    const config = plainObject(value, label);
-    for (const key of Object.keys(config)) {
-        if (!allowed.includes(key))
-            throw new Error(`Unknown ${label} option: ${key}`);
+function selectDatabase(exports, database) {
+    const names = Object.keys(exports).filter((name) => {
+        const value = exports[name];
+        return (name === 'default' || (value !== null && typeof value === 'object' && 'connection' in value));
+    });
+    if (database !== undefined && !names.includes(database)) {
+        throw new Error(`Unknown database export: ${database}. Available: ${names.join(', ') || 'none'}.`);
     }
-    return config;
+    if (database === undefined && names.length !== 1) {
+        throw new Error(names.length
+            ? `Multiple databases exported: ${names.join(', ')}. Select one with --database.`
+            : 'No database configurations exported. Export a Tenon config with a connection field.');
+    }
+    return exports[database ?? names[0]];
 }
 /** Find configuration without importing it, including for offline initialization. */
 export async function findConfig(directory = process.cwd()) {
@@ -47,50 +55,35 @@ export async function findConfig(directory = process.cwd()) {
         directory = parent;
     }
 }
-export async function loadConfig(filename, required = true) {
+export async function loadConfig(filename, database, required = true) {
     if (filename !== undefined)
         validatePath(filename, 'Config filename');
+    if (database !== undefined && (!database.trim() || database.includes('\0'))) {
+        throw new Error('--database must be a nonempty export name without NUL.');
+    }
     const selected = filename === undefined ? await findConfig() : resolve(filename);
-    if (!selected && !required)
+    if (!selected && !required && database === undefined)
         return undefined;
     if (!selected)
         throw new Error('Tenon configuration is required. Run tenon init or pass --config.');
-    let value;
+    let exports;
     try {
-        value = (await import(pathToFileURL(selected).href)).default;
+        exports = await import(pathToFileURL(selected).href);
     }
     catch {
         // Import errors may contain credentials from environment validation or dependency messages.
         throw new Error(`Could not load Tenon configuration: ${selected}. Check the module and its imports.`);
     }
-    const config = keys(value, 'Tenon config', [
-        'connection',
-        'generate',
-        'migrations',
-        'baseline',
-        'check',
-        'session',
-        'timeouts',
-    ]);
-    if (typeof config.connection === 'string') {
-        if (!config.connection.trim())
-            throw new Error('Tenon config connection must be nonempty.');
-    }
-    else {
-        const connection = plainObject(config.connection, 'Tenon config connection');
-        if ('acquire' in connection || 'close' in connection) {
-            throw new Error('Tenon config requires connection options, not an open pool.');
-        }
-    }
+    const config = configObject(selectDatabase(exports, database));
     const root = dirname(selected);
-    const migrations = keys(config.migrations === undefined ? {} : config.migrations, 'migration config', ['directory', 'namespace']);
+    const migrations = configSection(config.migrations === undefined ? {} : config.migrations, 'migration config', ['directory', 'namespace']);
     if (migrations.directory !== undefined)
         validatePath(migrations.directory, 'Migration directory');
     if (migrations.namespace !== undefined)
         validateName(migrations.namespace);
     let generate;
     if (config.generate !== undefined) {
-        const options = keys(config.generate, 'generation config', ['out', 'namespace']);
+        const options = configSection(config.generate, 'generation config', ['out', 'namespace']);
         validatePath(options.out, 'Generation out');
         if (options.namespace !== undefined)
             validateName(options.namespace);
@@ -99,7 +92,7 @@ export async function loadConfig(filename, required = true) {
             ...(options.namespace !== undefined && { namespace: options.namespace }),
         };
     }
-    const check = keys(config.check === undefined ? {} : config.check, 'checking config', [
+    const check = configSection(config.check === undefined ? {} : config.check, 'checking config', [
         'project',
         'readTypes',
     ]);
@@ -116,10 +109,7 @@ export async function loadConfig(filename, required = true) {
             }
         }
     }
-    const baseline = keys(config.baseline === undefined ? {} : config.baseline, 'baseline config', [
-        'connection',
-        'schemas',
-    ]);
+    const baseline = configSection(config.baseline === undefined ? {} : config.baseline, 'baseline config', ['connection', 'schemas']);
     if (baseline.connection !== undefined &&
         (typeof baseline.connection !== 'string' ||
             !baseline.connection.trim() ||
@@ -136,6 +126,9 @@ export async function loadConfig(filename, required = true) {
     const timeouts = timeoutOptions(config.timeouts === undefined ? {} : config.timeouts);
     return {
         connection: config.connection,
+        ...(config.onQuery !== undefined && {
+            onQuery: config.onQuery,
+        }),
         migrations: {
             directory: resolve(root, migrations.directory ?? 'migrations'),
             ...(migrations.namespace !== undefined && { namespace: migrations.namespace }),

package/dist/config/validate.d.ts

@@ -0,0 +1,3 @@
+export declare function configSection(value: unknown, label: string, allowed: readonly string[]): Record<string, unknown>;
+/** Check the shared shape without resolving credentials or constructing a pool. */
+export declare function configObject(value: unknown): Record<string, unknown>;

package/dist/config/validate.js

@@ -0,0 +1,28 @@
+import { plainObject } from '../validation.js';
+export function configSection(value, label, allowed) {
+    const config = plainObject(value, label);
+    for (const key of Object.keys(config)) {
+        if (!allowed.includes(key))
+            throw new Error(`Unknown ${label} option: ${key}`);
+    }
+    return config;
+}
+/** Check the shared shape without resolving credentials or constructing a pool. */
+export function configObject(value) {
+    const config = configSection(value, 'Tenon config', [
+        'connection',
+        'onQuery',
+        'generate',
+        'migrations',
+        'baseline',
+        'check',
+        'session',
+        'timeouts',
+    ]);
+    if (!('connection' in config))
+        throw new Error('Tenon config must declare connection.');
+    if (config.onQuery !== undefined && typeof config.onQuery !== 'function') {
+        throw new Error('Tenon config onQuery must be a function.');
+    }
+    return config;
+}

package/dist/config.d.ts

@@ -1,8 +1,13 @@
+import type { Pool } from '@kequtech/pgclear';
 import type { ConnectionConfig } from './connection.js';
+import type { QueryEvent } from './types.js';
 import type { InspectionSession, InspectionTimeouts } from './inspection/types.js';
 /** Shared runtime connection values and CLI defaults. Export without opening a database. */
 export interface TenonConfig {
-    readonly connection: ConnectionConfig;
+    /** Environment values may be absent during builds; database use validates them. */
+    readonly connection: ConnectionConfig | Pool | undefined;
+    /** Observe runtime queries; native driver calls and CLI tooling do not invoke this callback. */
+    readonly onQuery?: (event: QueryEvent) => void | Promise<void>;
     readonly generate?: {
         readonly out: string;
         readonly namespace?: string;
@@ -13,7 +18,7 @@ export interface TenonConfig {
     };
     /** Native pg_dump connection/scope; defaults to the main connection only when it is a string. */
     readonly baseline?: {
-        readonly connection?: string;
+        readonly connection?: string | undefined;
         readonly schemas?: readonly string[];
     };
     readonly check?: {

package/dist/connection.d.ts

@@ -2,13 +2,16 @@ import { type Pool, type PoolOptions, type QueryResult as DriverResult, type Exe
 import type { UnknownRow } from './query.js';
 export type ConnectionOptions = PoolOptions;
 /** Connection settings and executable credentials/codecs, without a live pool. */
-export type ConnectionConfig = string | (ConnectionOptions & {
+export type ConnectionConfig = string | (Omit<ConnectionOptions, 'connectionString'> & {
+    /** May be absent during builds; operations reject an explicitly missing URI. */
+    readonly connectionString?: string | undefined;
     readonly acquire?: never;
     readonly close?: never;
 });
 export type Connection = string | ConnectionOptions | Pool;
 export type QueryResult<Row extends object = UnknownRow> = DriverResult<Row>;
 export type QueryExecutor = <T>(text: string, input: readonly unknown[], readResult: (result: QueryResult) => T, guarded: boolean) => Promise<T>;
+export declare function isPool(connection: unknown): connection is Pool;
 /** Constructed pools are owned; supplied public pgclear pools remain application-owned. */
 export declare function createConnection(connection: Connection): {
     pool: Pool;

package/dist/connection.js

@@ -1,6 +1,6 @@
 import { createPool, } from '@kequtech/pgclear';
 import { plainObject } from './validation.js';
-function isPool(connection) {
+export function isPool(connection) {
     return (connection !== null &&
         typeof connection === 'object' &&
         'acquire' in connection &&

package/dist/database.d.ts

@@ -1,7 +1,3 @@
-import type { Connection } from './connection.js';
-import type { Database, QueryEvent } from './types.js';
-export interface TenonOptions {
-    readonly connection: Connection;
-    readonly onQuery?: (event: QueryEvent) => void | Promise<void>;
-}
-export declare function createTenon(options: TenonOptions): Database;
+import type { TenonConfig } from './config.js';
+import type { Database } from './types.js';
+export declare function createTenon(config: TenonConfig): Database;

package/dist/database.js

@@ -1,5 +1,7 @@
 import { createClient } from './client.js';
-import { createConnection, executeSql } from './connection.js';
+import { createConnection, executeSql, isPool } from './connection.js';
+import { configConnection } from './config/connection.js';
+import { configObject } from './config/validate.js';
 import { withTransaction } from './transaction.js';
 import { plainObject } from './validation.js';
 function closeTimeout(options) {
@@ -17,34 +19,40 @@ function closeTimeout(options) {
     }
     return timeoutMs;
 }
-export function createTenon(options) {
-    for (const key of Object.keys(plainObject(options, 'Tenon options'))) {
-        if (key !== 'connection' && key !== 'onQuery') {
-            throw new Error(`Unknown Tenon option: ${key}`);
-        }
-    }
-    if (options.onQuery !== undefined && typeof options.onQuery !== 'function') {
-        throw new Error('onQuery must be a function.');
-    }
-    const { pool, close } = createConnection(options.connection);
+export function createTenon(config) {
+    configObject(config);
+    const onQuery = config.onQuery;
+    let connection;
     let closing;
     function checkOpen() {
         if (closing) {
             throw new Error('This database instance is closed.');
         }
     }
+    function currentConnection() {
+        if (!connection) {
+            checkOpen();
+            const value = config.connection;
+            connection = createConnection(isPool(value) ? value : configConnection(value));
+        }
+        return connection;
+    }
     const query = (text, input, readResult, guarded) => {
         checkOpen();
+        const { pool } = currentConnection();
         if (guarded)
             return withTransaction(pool, (query) => query(text, input, readResult, false));
         return executeSql(pool, text, input).then(readResult);
     };
     return {
-        ...createClient(query, options.onQuery),
-        native: pool,
+        ...createClient(query, onQuery),
+        get native() {
+            return currentConnection().pool;
+        },
         async transaction(callback) {
             checkOpen();
-            return withTransaction(pool, (query) => callback(createClient(query, options.onQuery)));
+            const { pool } = currentConnection();
+            return withTransaction(pool, (query) => callback(createClient(query, onQuery)));
         },
         close(options) {
             if (closing)
@@ -52,7 +60,7 @@ export function createTenon(options) {
             try {
                 const timeoutMs = closeTimeout(options);
                 // Cache before invoking driver callbacks, so reentrant/concurrent callers share shutdown.
-                closing = Promise.resolve().then(() => close(timeoutMs));
+                closing = Promise.resolve().then(() => connection?.close(timeoutMs));
                 return closing;
             }
             catch (error) {

package/dist/generation/render.js

@@ -6,12 +6,13 @@ function columnTypes(column, codecs, path, warn) {
         warn(`Column ${path} uses a custom decoder without a known TypeScript representation; generated as unknown.`);
         read = 'unknown';
     }
-    const choices = column.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
-    if (column.typeKind === 'e' && codecs === defaultCodecs && read === 'string')
-        read = choices;
     let write = defaultCodecs.typescript(oid);
-    if (column.typeKind === 'e')
+    if (column.typeKind === 'e') {
+        const choices = column.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
+        if (read === 'string' && codecs.isDefaultDecoder(oid))
+            read = choices;
         write = choices;
+    }
     if (write === 'unknown' || write.startsWith('PgArray<'))
         write = 'string';
     if ([20, 1700].includes(oid))

package/dist/index.d.ts

@@ -3,7 +3,6 @@ export type { Codec, CodecRegistry, Parameter, PgArray, TemporalConstructors, Te
 export type { Connection, ConnectionConfig, ConnectionOptions, QueryResult } from './connection.js';
 export type { AffectedRowsConstraint } from './affected-rows.js';
 export { createTenon } from './database.js';
-export type { TenonOptions } from './database.js';
 export type { TenonConfig } from './config.js';
 export { AffectedRowsError, CardinalityError } from './errors.js';
 export type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';

package/dist/inspection/options.js

@@ -1,4 +1,5 @@
 import { plainObject } from '../validation.js';
+import { configConnection } from '../config/connection.js';
 const defaults = { connectMs: 3000, statementMs: 5000, lockMs: 1000 };
 export function sessionOptions(value) {
     const input = plainObject(value, 'Inspection session');
@@ -31,19 +32,8 @@ export function timeoutOptions(value) {
 }
 /** Validate and capture caller-owned settings before opening a connection. */
 export function inspectionOptions(options) {
-    let connection;
-    if (typeof options.connection === 'string') {
-        if (!options.connection.trim())
-            throw new Error('Describe requires an explicit nonempty connection string.');
-        connection = { connectionString: options.connection };
-    }
-    else {
-        plainObject(options.connection, 'Inspection connection');
-        if ('acquire' in options.connection || 'close' in options.connection) {
-            throw new Error('Inspection requires connection options, not an open pool.');
-        }
-        connection = { ...options.connection };
-    }
+    const selected = configConnection(options.connection);
+    let connection = typeof selected === 'string' ? { connectionString: selected } : { ...selected };
     if (connection.startupParameters !== undefined) {
         plainObject(connection.startupParameters, 'Startup parameters');
     }

package/dist/inspection/types.d.ts

@@ -25,7 +25,7 @@ export interface InspectionContext {
 }
 export interface DescribeOptions {
     /** URI or pool configuration values. Inspection owns a separate, short-lived connection. */
-    readonly connection: ConnectionConfig;
+    readonly connection: ConnectionConfig | undefined;
     /** Finished SQL; query values are neither bound nor executed. */
     readonly query: string | DescribeStatement;
     /** Use the same registry as execution; custom decoder types can remain unresolved. */

package/dist/types.d.ts

@@ -17,7 +17,7 @@ export interface CloseOptions {
     readonly timeoutMs?: number | undefined;
 }
 export type Database = Transaction & {
-    /** The underlying pool-level driver client; native calls bypass Tenon's query and transaction guards. */
+    /** The underlying pool; access initializes shared config. Native calls bypass Tenon's guards. */
     readonly native: Pool;
     /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
     transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;

package/docs/agent-guide.md

@@ -104,9 +104,8 @@ establishes that contract; do not cast merely to silence a diagnostic. See
 [responding to findings](query-checking.md#responding-to-findings).
 
 Share runtime connection/codecs through `tenon.config.ts`; CLI generation, checking, inspection,
-and migrations read it. Use `--config` for another role/deployment. Match runtime role, search path,
-timezone, and codecs. Describe uses a separate session and
-cannot establish result nullability, JSON members, cardinality, or execution permissions. Native
+and migrations read it. Select a named export with `--database`, or another file with `--config`.
+Match runtime role, search path, timezone, and codecs. Describe uses a separate session and cannot establish result nullability, JSON members, cardinality, or execution permissions. Native
 calls bypass Tenon's guards/observations and need explicit resource ownership; see
 [connections and driver access](connections.md). For common failures, use
 [troubleshooting](reference.md#troubleshooting).