letopis 2.0.0 → 3.0.1

package/dist/cli.js

@@ -13,6 +13,8 @@
  *   letopis maintain --dsn … --schema v2.x [--token … | --api-key …]
  *   letopis mcp --dsn … --schema v2.x --token … [--write]   — сервер MCP по stdio (план 1.1, §2.5); dsn, schema и
  *     token — ещё из LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; только токен пользователя: --api-key — отказ
+ *   --log[=уровень] — у любой команды (логирование 3.0): события JSON-строками в stderr, уровень debug|info|warn|error|off,
+ *     без значения — info; без флага действует LETOPIS_LOG
  *   справка — USAGE (её же читает справочник сайта, guide/scripts/gen-api.ts)
  */
 import { parseArgs } from 'node:util';
@@ -23,13 +25,16 @@ import { resolve } from 'node:path';
 import { connect } from './index.js';
 import { syncModels, generateTypes } from './sync.js';
 import { lerr, lmsg } from './errors.js';
-const USAGE = `letopis sync <модуль> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--apply | --check]
-letopis types --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--out <файл>] [--system]
-letopis load <файлы…> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--class <Класс>]
+import { stderrLog } from './log.js';
+const USAGE = `letopis sync <модуль> --dsn <строка> --schema <схема> (--token <токен> | --api-key <ключ>) [--apply | --check]
+letopis types --dsn <строка> --schema <схема> (--token <токен> | --api-key <ключ>) [--out <файл>] [--system]
+letopis load <файлы…> --dsn <строка> --schema <схема> (--token <токен> | --api-key <ключ>) [--class <Класс>]
   [--duplicates error|first|last] [--existing error|skip|update] [--commit-every <N>] [--initial]
-letopis maintain --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>]
-letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пользователя> [--write]
-  (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)`;
+letopis maintain --dsn <строка> --schema <схема> [--token <токен> | --api-key <ключ>]
+letopis mcp --dsn <строка> --schema <схема> --token <токен пользователя> [--write]
+  (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)
+у любой команды: --log[=debug|info|warn|error|off] — события JSON-строками в stderr (без значения — info)
+(<схема> — v2.<имя> или просто <имя>: shop — это v2.shop)`;
 /** Команды CLI: остальное — USAGE с кодом 2 ещё до подключения. */
 const COMMANDS = new Set(['sync', 'types', 'load', 'maintain', 'mcp']);
 const isModel = (v) => typeof v === 'object' && v !== null && typeof v.describe === 'function' && typeof v.name === 'string';
@@ -38,17 +43,64 @@ async function loadModels(path) {
     const mod = await import(pathToFileURL(resolve(path)).href);
     return [...new Set(Object.values(mod).flatMap((v) => (Array.isArray(v) ? v : [v])).filter(isModel))];
 }
+/**
+ * Флаг --log[=уровень] (логирование 3.0): вынимается из аргументов до parseArgs — у строкового флага parseArgs требует
+ * значение, а --log без него значит info.
+ */
+function logFlag(argv) {
+    let level;
+    const args = [];
+    for (const a of argv) {
+        if (a === '--log')
+            level = 'info';
+        else if (a.startsWith('--log='))
+            level = (a.slice('--log='.length) || 'info');
+        else
+            args.push(a);
+    }
+    return { args, log: level === undefined ? {} : { log: stderrLog, logLevel: level } };
+}
+/** Флаги CLI для parseArgs. */
+const OPTIONS = {
+    dsn: { type: 'string' }, schema: { type: 'string' }, token: { type: 'string' }, 'api-key': { type: 'string' },
+    apply: { type: 'boolean' }, out: { type: 'string' }, help: { type: 'boolean' },
+    class: { type: 'string' }, duplicates: { type: 'string' }, existing: { type: 'string' }, 'commit-every': { type: 'string' },
+    initial: { type: 'boolean' }, write: { type: 'boolean' }, system: { type: 'boolean' }, check: { type: 'boolean' },
+};
+/**
+ * Ошибка разбора аргументов parseArgs — русский текст каталога (английский текст Node — только для прочих ошибок);
+ * null — не ошибка разбора.
+ */
+function parseError(e) {
+    const code = e?.code;
+    const message = String(e?.message ?? '');
+    // имя флага или аргумент — первое в кавычках: «Unknown option '--aply'…», «Option '--dsn <value>' argument missing»
+    const quoted = (/'([^']*)'/.exec(message)?.[1] ?? '').split(' ')[0] ?? '';
+    if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION')
+        return lmsg('model.cli_unknown_flag', { flag: quoted });
+    if (code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE') {
+        // строковому флагу не дали значения или булевому дали
+        return lmsg(/does not take/i.test(message) ? 'model.cli_flag_no_value' : 'model.cli_flag_needs_value', { flag: quoted });
+    }
+    if (code === 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL')
+        return lmsg('model.cli_unexpected_arg', { arg: quoted });
+    return null;
+}
 export async function main(argv) {
-    const { values, positionals } = parseArgs({
-        args: argv,
-        allowPositionals: true,
-        options: {
-            dsn: { type: 'string' }, schema: { type: 'string' }, token: { type: 'string' }, 'api-key': { type: 'string' },
-            apply: { type: 'boolean' }, out: { type: 'string' }, help: { type: 'boolean' },
-            class: { type: 'string' }, duplicates: { type: 'string' }, existing: { type: 'string' }, 'commit-every': { type: 'string' },
-            initial: { type: 'boolean' }, write: { type: 'boolean' }, system: { type: 'boolean' }, check: { type: 'boolean' },
-        },
-    });
+    const { args, log } = logFlag(argv);
+    let parsed;
+    try {
+        parsed = parseArgs({ args, allowPositionals: true, options: OPTIONS });
+    }
+    catch (e) {
+        const text = parseError(e);
+        if (text === null)
+            throw e;
+        // код выхода 1 — как у прочих ошибок до подключения (прежде — необработанное исключение parseArgs)
+        console.error(`letopis: ${text}`);
+        return 1;
+    }
+    const { values, positionals } = parsed;
     const [cmd, arg] = positionals;
     // клиенты MCP передают строку подключения и токен окружением (план 1.1, §2.5) — только для этой команды
     if (cmd === 'mcp') {
@@ -67,9 +119,9 @@ export async function main(argv) {
         return cmd ? 2 : 0;
     }
     if (cmd === 'mcp')
-        return mcp(values);
+        return mcp(values, log);
     // загрузчику нужно администраторское подключение (§2.6, п. 1)
-    const db = await connect({ dsn: values.dsn, schema: values.schema, token: values.token, apiKey: values['api-key'], max: 2,
+    const db = await connect({ dsn: values.dsn, schema: values.schema, token: values.token, apiKey: values['api-key'], max: 2, ...log,
         // maintain работает и на администраторском подключении без сессии; классы со строками синхронизирует
         // администраторское подключение с сессией арендатора
         ...(cmd === 'load' || cmd === 'maintain' || cmd === 'sync' ? { allowBypassRls: true } : {}) });
@@ -145,7 +197,7 @@ export async function main(argv) {
  * грузятся только здесь: letopis --help и прочие команды работают без SDK. В stdout — только протокол (предупреждения
  * connect() идут в stderr); процесс живёт, пока клиент не закроет stdin.
  */
-async function mcp(v) {
+async function mcp(v, log = {}) {
     if (v['api-key'] !== undefined) {
         console.error(lerr('model.mcp_api_key_refused').message);
         return 2;
@@ -155,7 +207,7 @@ async function mcp(v) {
         return 2;
     }
     const { createMcpServer } = await import('./mcp.js');
-    const db = await connect({ dsn: v.dsn, schema: v.schema, token: v.token, max: 4 });
+    const db = await connect({ dsn: v.dsn, schema: v.schema, token: v.token, max: 4, ...log });
     try {
         const opts = { write: v.write === true };
         // учётные данные — до начала протокола: отказ виден кодом выхода и текстом в stderr

package/dist/errors.d.ts

@@ -8,13 +8,26 @@ export interface Issue {
 }
 /** Текст записи каталога с параметрами (params.similar — «— похожие: …»): сообщения нарушений, описания, отчёты CLI. */
 export declare function lmsg(key: MsgKey, params?: Params): string;
+/** Логгер, в который уходит предупреждение (lib/src/log.ts, Log): только то, что нужно lwarn. */
+interface WarnSink {
+    readonly active: boolean;
+    warning(key: string | undefined, msg: string, detail?: Record<string, unknown>): void;
+}
+export declare function setEnvWarnSink(fn: () => WarnSink): void;
 /**
  * Предупреждение по записи каталога — «letopis: <текст>» в console.warn; once — ключ «один раз на процесс». Неизвестное
  * поле фильтра, sort() и агрегата с 2.0 — уже не предупреждение, а отказ query.unknown_field (sql.ts, checkField).
+ * Логирование 3.0: задан логгер (opts.log подключения или LETOPIS_LOG) — событие warning в него вместо console.warn.
  */
 export declare function lwarn(key: MsgKey, params?: Params, opts?: {
     once?: string;
+    log?: WarnSink;
 }): void;
+/**
+ * Готовый текст предупреждения: в логгер (событие warning с ключом и параметрами), если он задан, иначе console.warn.
+ * Ошибка логгера предупреждение не теряет и операцию не прерывает.
+ */
+export declare function warnText(text: string, key?: string, log?: WarnSink, params?: Params): void;
 export declare class LetopisError extends Error {
     readonly code: string;
     readonly detail: unknown;
@@ -46,7 +59,12 @@ export declare function similar(name: string, candidates: Iterable<string>, n?:
  * 7.9 №6). known — все ключи опций: объект `satisfies Record<keyof Опции, true>`, пропуск ключа — ошибка типов.
  */
 export declare function checkOptions(where: string, opts: unknown, known: Readonly<Record<string, true>>): void;
-/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed). */
+/**
+ * Первое нарушение для текста ошибки (план 2.1, A8): «: <путь> — <сообщение>», при нескольких — ещё их число. Полный
+ * список — err.issues.
+ */
+export declare function issuesSuffix(issues: readonly Issue[]): string;
+/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed) и первое нарушение. */
 export declare class ValidationError extends LetopisError {
     readonly issues: Issue[];
     constructor(cls: string, issues: Issue[], msg?: {
@@ -66,10 +84,9 @@ export declare function issuesFromDb(issues: unknown): Issue[];
  */
 export declare function findingsFromDb<T>(rows: readonly T[]): T[];
 /**
- * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL (JSON) переносятся в
- * detail; ключ каталога и параметры из DETAIL (lt_fail(ключ, …)) — в key и params, текст — тот, что база собрала по ним
- * из русского шаблона; без ключа — текст базы. У нарушений (issues) и строк отказа (detail.rows) key и params наружу не
- * идут. Внутренняя ошибка базы (XX000) с ключом в DETAIL — код internal. Повторяемый конфликт (40001, 40P01) и прочие
- * ошибки возвращаются как есть: на SQLSTATE конфликта держатся повторы (tx.ts).
+ * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями) — для ошибок сырого SQL (`db.sql`,
+ * `db.transaction()`): тот же код, ключ и подробности, что у цепочек. Подробности ошибки базы переходят в `detail`, ключ
+ * каталога и параметры — в `key` и `params`, текст — русский; без ключа — текст базы. Значение не того типа (22P02) —
+ * `invalid_query`. Повторяемый конфликт (40001, 40P01) и прочие ошибки возвращаются как есть.
  */
 export declare function fromDbError(e: unknown): unknown;

package/dist/errors.js

@@ -2,10 +2,10 @@
  * Ошибки letopis 1.0 (план, §7.1, этап 2, п. 10). Текст — «letopis: <код>: <сообщение>», как у ошибок
  * базы; код — имя из каталога (`error_catalog()` в lib/sql/15-errors.sql) или код самой библиотеки.
  *
- * Каталог сообщений (план 2.0, этап 3, п. 3; lib/src/messages): ошибка по ключу — `lerr(ключ, параметры)`, текст —
+ * Каталог сообщений: ошибка по ключу — `lerr(ключ, параметры)`, текст —
  * шаблон записи с параметрами. У каждой ошибки — подсказка «что делать» (`hint`) и ссылка на строку её кода в разделе
  * «Ошибки» README на GitHub по тегу версии (`docs`). База собирает текст по ключу и параметрам из того же шаблона и
- * кладёт их в DETAIL (`lt_fail(ключ, …)`), а fromDbError переносит их в поля ошибки (`key`, `params`); без ключа —
+ * передаёт ключ и параметры вместе с ошибкой, а fromDbError переносит их в поля ошибки (`key`, `params`); без ключа —
  * текст базы как есть. У нарушений (validate_data) и строк отказа ужесточения key и params наружу не идут: issuesFromDb,
  * findingsFromDb.
  */
@@ -30,9 +30,15 @@ export function lmsg(key, params) {
     return textOf(key, params);
 }
 const warned = new Set();
+/** Логгер по LETOPIS_LOG для предупреждений без подключения — ставит log.ts (без цикла импорта значений). */
+let envSink = null;
+export function setEnvWarnSink(fn) {
+    envSink = fn;
+}
 /**
  * Предупреждение по записи каталога — «letopis: <текст>» в console.warn; once — ключ «один раз на процесс». Неизвестное
  * поле фильтра, sort() и агрегата с 2.0 — уже не предупреждение, а отказ query.unknown_field (sql.ts, checkField).
+ * Логирование 3.0: задан логгер (opts.log подключения или LETOPIS_LOG) — событие warning в него вместо console.warn.
  */
 export function lwarn(key, params, opts = {}) {
     if (opts.once !== undefined) {
@@ -42,7 +48,24 @@ export function lwarn(key, params, opts = {}) {
             warned.clear();
         warned.add(opts.once);
     }
-    console.warn(`letopis: ${textOf(key, params)}`);
+    warnText(`letopis: ${textOf(key, params)}`, key, opts.log, params);
+}
+/**
+ * Готовый текст предупреждения: в логгер (событие warning с ключом и параметрами), если он задан, иначе console.warn.
+ * Ошибка логгера предупреждение не теряет и операцию не прерывает.
+ */
+export function warnText(text, key, log, params) {
+    const sink = log?.active ? log : envSink?.();
+    if (sink?.active) {
+        try {
+            sink.warning(key, text, params && Object.keys(params).length ? { ...params } : undefined);
+            return;
+        }
+        catch {
+            // логгер не принял — как без него
+        }
+    }
+    console.warn(text);
 }
 export class LetopisError extends Error {
     code;
@@ -120,12 +143,24 @@ export function checkOptions(where, opts, known) {
             throw lerr('api.unknown_option', { where, name: k, similar: similar(k, Object.keys(known)) });
     }
 }
-/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed). */
+/**
+ * Первое нарушение для текста ошибки (план 2.1, A8): «: <путь> — <сообщение>», при нескольких — ещё их число. Полный
+ * список — err.issues.
+ */
+export function issuesSuffix(issues) {
+    const first = issues[0];
+    if (!first)
+        return '';
+    const path = Array.isArray(first.path) && first.path.length ? first.path.join('.') : textOf('api.validation_root', undefined);
+    const more = issues.length > 1 ? textOf('api.validation_more', { n: issues.length }) : '';
+    return `: ${textOf('api.validation_issue', { path, issue: first.message })}${more}`;
+}
+/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed) и первое нарушение. */
 export class ValidationError extends LetopisError {
     issues;
     constructor(cls, issues, msg) {
         const m = msg ?? { key: 'api.validation_failed', params: { cls } };
-        super('invalid_data', textOf(m.key, m.params), { issues }, m);
+        super('invalid_data', textOf(m.key, m.params) + issuesSuffix(issues), { issues }, m);
         this.name = 'ValidationError';
         this.issues = issues;
     }
@@ -178,11 +213,10 @@ function parseDetail(detail) {
     }
 }
 /**
- * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL (JSON) переносятся в
- * detail; ключ каталога и параметры из DETAIL (lt_fail(ключ, …)) — в key и params, текст — тот, что база собрала по ним
- * из русского шаблона; без ключа — текст базы. У нарушений (issues) и строк отказа (detail.rows) key и params наружу не
- * идут. Внутренняя ошибка базы (XX000) с ключом в DETAIL — код internal. Повторяемый конфликт (40001, 40P01) и прочие
- * ошибки возвращаются как есть: на SQLSTATE конфликта держатся повторы (tx.ts).
+ * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями) — для ошибок сырого SQL (`db.sql`,
+ * `db.transaction()`): тот же код, ключ и подробности, что у цепочек. Подробности ошибки базы переходят в `detail`, ключ
+ * каталога и параметры — в `key` и `params`, текст — русский; без ключа — текст базы. Значение не того типа (22P02) —
+ * `invalid_query`. Повторяемый конфликт (40001, 40P01) и прочие ошибки возвращаются как есть.
  */
 export function fromDbError(e) {
     const err = e;
@@ -192,6 +226,10 @@ export function fromDbError(e) {
     if (err.code === '42501' && err.routine === 'ExecWithCheckOptions' && !/USING/.test(err.message ?? '')) {
         return lerr('api.row_check_denied', undefined, { cause: e });
     }
+    // значение не того типа (22P02: «invalid input syntax for type uuid» и т. п.), которое не поймала проверка до запроса,
+    // — ошибка letopis, а не сырая ошибка PostgreSQL (план 2.1, A7); 40001 и 40P01 остаются как есть — на них держатся повторы
+    if (err.code === '22P02')
+        return lerr('api.db_bad_value', { text: err.message ?? '' }, { cause: e });
     let name;
     let detail;
     if (err.code === 'XX000') {
@@ -225,9 +263,10 @@ export function fromDbError(e) {
     const issues = detail?.issues;
     if (name === 'invalid_data' && Array.isArray(issues)) {
         const cls = msg ? String(msg.params.cls ?? '?') : /класса (\S+)/.exec(text)?.[1] ?? '?';
-        const v = new ValidationError(cls, issuesFromDb(issues), msg);
-        // текст целиком — тот, что собрала база по шаблону записи
-        return Object.assign(v, { cause: e, ...(text ? { message: `letopis: invalid_data: ${text}` } : {}) });
+        const list = issuesFromDb(issues);
+        const v = new ValidationError(cls, list, msg);
+        // текст — тот, что собрала база по шаблону записи, и первое нарушение (план 2.1, A8)
+        return Object.assign(v, { cause: e, ...(text ? { message: `letopis: invalid_data: ${text}${issuesSuffix(list)}` } : {}) });
     }
     return Object.assign(new LetopisError(name, text, detail, msg), { cause: e });
 }

package/dist/index.d.ts

@@ -14,7 +14,7 @@ import { type AuthApi } from './auth.js';
 import { type AclApi } from './acl.js';
 import { type LoadInput, type LoadOptions, type LoadReport } from './load.js';
 import { type Batch, type Chain, type ChainRef, type StepFn } from './chain.js';
-import type { QueryEvent, Row } from './types.js';
+import type { LogOptions, QueryEvent, Row } from './types.js';
 import { type CacheOptions, type CacheStats } from './cache.js';
 import { Subscription, type WatchOptions } from './watch.js';
 import { type MaintainReport } from './admin.js';
@@ -29,12 +29,11 @@ export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has,
 /**
  * Хотя бы один из фильтров: `db.Product(or({ sku: 'K-1' }, { price: lt(500) }))` — товар K-1 или дешевле 500. Ставится
  * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и». В шаге подключения
- * с моделями (`TypedDb`) фильтры внутри — поля и роли класса шага: тип им даёт шаг (план 2.0, этап 4, п. 1). Та же
- * фабрика, что в реестре операторов (ops.ts), — другой у неё только тип.
+ * с моделями (`TypedDb`) фильтры внутри — поля и роли класса шага: тип им даёт шаг.
  */
 export declare const or: <F extends object>(...filters: NoInfer<F>[]) => OrOp<F>;
 export { cursorOf } from './sql.js';
-export { inc, isInc, type IncMarker, type WriteRow } from './write.js';
+export { inc, isInc, type DeleteOptions, type Expected, type IncMarker, type RestoreOptions, type WriteRow } from './write.js';
 export { totpCode, hashPassword, verifyHash, type AuthApi, type LoginResult, type Credential, type SessionInfo } from './auth.js';
 export type { AclApi, AclDecision, AclDataDecision, AclOp, AclRule, AclRuleSpec, AclTarget } from './acl.js';
 export type { LoadOptions, LoadReport, LoadIssue, LoadInput } from './load.js';
@@ -47,13 +46,15 @@ export type { WatchOptions, WatchEvent, Subscription } from './watch.js';
 export type { MaintainReport } from './admin.js';
 export { up, createTenant, type UpOptions, type UpResult, type TenantOptions, type TenantResult, type LoginOptions } from './up.js';
 export { RESERVED_CLASS_NAMES, CHAIN_METHODS, DB_METHODS } from './types.js';
-export interface ConnectOptions {
+export type { LogEvent, LogFn, LogLevel, LogObject, LogOptions, Logger } from './types.js';
+export { LOG_EVENTS, type LogEventName } from './messages/index.js';
+export interface ConnectOptions extends LogOptions {
     /** Строка подключения; либо готовый пул postgres.js в `sql`. */
     dsn?: string;
     sql?: postgres.Sql;
-    /** Схема установки, например `v2.salon`. */
+    /** Схема установки, например `v2.salon`; имя без точки (`salon`) — как у `up()`: `v2.salon`. */
     schema: string;
-    /** Токен сессии; либо ключ `APIKEY` в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
+    /** Токен сессии; либо ключ API в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
     token?: string;
     apiKey?: string;
     service?: string;
@@ -119,7 +120,15 @@ export interface DbCore {
      * класса. Сами права база применяет при каждом запросе.
      */
     readonly acl: AclApi;
-    /** Сырой SQL под сессией и RLS, одной транзакцией (в `db.begin()` — в ней): `` db.sql`select …` ``. */
+    /**
+     * Сырой SQL под сессией и RLS, одной транзакцией (в `db.begin()` — в ней); права те же, что у цепочек. Путь поиска
+     * схем у запроса — по умолчанию PostgreSQL, поэтому таблицы `entity`, `log`, `secret` пишутся со схемой установки в
+     * двойных кавычках, значения — параметрами шаблона:
+     * ```ts
+     * const rows = await db.sql`select id, data->>'name' as name from "v2.shop".entity where class = ${'Shop'}`;
+     * ```
+     * Без схемы (`from entity`) — ошибка PostgreSQL 42P01 «relation does not exist».
+     */
     sql(strings: TemplateStringsArray, ...values: unknown[]): Promise<postgres.Row[]>;
     /** Транзакция под сессией: `fn` получает соединение postgres.js (в `db.begin()` — ту же транзакцию). */
     transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
@@ -160,14 +169,15 @@ export interface DbCore {
     }): Promise<DbTx>;
     /**
      * Массовая загрузка строк любых классов одной транзакцией (или порциями `commitEvery`) — быстрее записи цепочками.
-     * Строки проверяются по тому же описанию класса, что и при обычной записи (данные, ссылки, ключ), уходят в базу
-     * командой `COPY`, а ссылки на объекты вне загрузки сверяет один запрос в конце; права проверяются только при загрузке
+     * Строки проверяются по тому же описанию класса, что и при обычной записи (данные, концы, ключ), уходят в базу
+     * командой `COPY`, а концы к объектам вне загрузки сверяет один запрос в конце; права проверяются только при загрузке
      * от имени пользователя (опция `as`). Работает только на администраторском подключении, иначе `admin_required`.
      */
     load(input: LoadInput, opts?: LoadOptions): Promise<LoadReport>;
     /**
-     * Именованная очередь планов фасада: `batch.Класс(…).create(…)`; `batch.run()` — одной транзакцией. У корня,
-     * у каждого `db.as()` и у каждой `db.begin()` очереди свои: план исполняется от имени фасада, который его поставил.
+     * Именованная очередь планов подключения (db, db.as(), db.begin()): `batch.Класс(…).create(…)`; `batch.run()` — одной
+     * транзакцией. У корня, у каждого `db.as()` и у каждой `db.begin()` очереди свои: план исполняется от имени того
+     * подключения, которое его поставило.
      */
     batch(name: string, opts?: {
         reason?: string;
@@ -178,6 +188,13 @@ export interface DbCore {
     commit(tr?: DbTx): Promise<void>;
     /** Откатить транзакцию `tr` (то же, что `tr.rollback()`). */
     rollback(tr?: DbTx): Promise<void>;
+    /**
+     * Закрыть подключение: у корня — пул, подписки и обслуживание по расписанию (идущий запуск `maintain()` close() ждёт),
+     * в `db.begin()` — откат транзакции; у `db.as()` ничего не делает (пул общий с корнем). После `close()` корня любой
+     * вызов этого подключения и производных от него (`db.as()`, `db.begin()`, цепочки, созданные раньше) — `invalid_query`
+     * «подключение закрыто (db.close()) — откройте новое connect()»; пул заново не открывается, процесс может завершиться.
+     * Повторный `close()` — без ошибки.
+     */
     close(): Promise<void>;
 }
 /** Подключение: служебные методы и классы как стартовые шаги цепочек — `db.Класс(фильтр)`. */
@@ -188,15 +205,15 @@ export type Db = DbCore & {
 export type DbTx = Db;
 /**
  * Подключение со строгими типами по моделям: `connect({ models })` или `connect<Models>()` с объявлениями
- * `letopis types`. Шаг — только известный класс или алиас (модели и системные классы), переходы — по концам, слоты — роли
- * класса; имена, известные только во время выполнения, — `loose(db)` (план 2.0, этап 4, п. 1). Модели без литеральных
+ * `letopis types`. Шаг — только известный класс или алиас (модели и системные классы), переходы — по концам, шаги ролей
+ * после глагола — роли класса; имена, известные только во время выполнения, — `loose(db)`. Модели без литеральных
  * имён (`AnyModel[]` вместо списка `as const`) строгим типам не помогут — тогда это `Db`.
  */
 export type TypedDb<M extends readonly AnyModelLike[]> = string extends M[number]['name'] ? Db : DbCore & StepsOf<M>;
 export type { Batch };
 /**
  * То же подключение без строгих типов: шагом может быть любое имя, в том числе известное только во время выполнения, —
- * `loose(db)[имя]()`. Объект тот же: проверки во время выполнения (неизвестное имя или поле, переход, слот) не меняются.
+ * `loose(db)[имя]()`. Объект тот же: проверки во время выполнения (неизвестное имя или поле, переход, шаг роли) не меняются.
  */
 export declare function loose(db: DbCore): Db;
 export declare function connect<const M extends readonly AnyModelLike[]>(opts: ConnectOptions & {