letopis 1.4.2 → 3.0.0

package/dist/messages/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Каталог сообщений letopis (план 2.0, этап 3, п. 3): ключ → код ошибки, шаблон текста и, если нужно, своя подсказка
+ * «что делать». Здесь разделы сливаются в MESSAGES (префикс ключа — имя раздела, ключи не повторяются), а render()
+ * подставляет параметры; ошибки и тексты строит errors.ts — lerr, lmsg, lwarn.
+ *
+ * Как перевести место на ключ каталога — инструкция исполнителям (образцы: записи разделов api, query, access, sql-core, sql-write,
+ * sql-time и места, которые их бросают).
+ *
+ * 1. Раздел — по файлу, где брошена ошибка:
+ *      api — index, chain, typed, errors, internal;  write — write, tx, load;  query — sql, ops;
+ *      time — watch, admin, cache, signals;  access — auth, acl;  model — model, registry, sync, cli, validate,
+ *      jsonschema, uuid;  boot — up, pglite;  mcp — mcp, describe;  log — log (и тексты логирования из index, tx);
+ *      sql-core — sql/10, 15, 20, 30, 40;  sql-write — sql/60;  sql-access — sql/50, 80;
+ *      sql-time — sql/70, 90, 95, 99 и sql/migrate.
+ *    codes.ts — запись на каждый код: заголовок и подсказка. Новый код — ещё ErrorCode (types.ts), для кода базы —
+ *    LT_NAMES (errors.ts) и error_catalog(), и строка таблицы «Ошибки» README с якорем `<a id="код"></a>`.
+ * 2. Ключ — `<раздел>.<snake_case>`: что случилось, а не где (api.unknown_step, query.sort_field). Одно место — один
+ *    ключ; одинаковый текст в разных разделах — разные ключи (api.validation_failed и sql-write.invalid_data).
+ * 3. Запись — { code, ru, hint? }, поля в этом порядке:
+ *    code — код, с которым место бросало ошибку: код не меняется (коды сверяет check:semver);
+ *    ru — прежний текст буква в букву, без префикса «letopis: <код>: »; подстановка ${x} → параметр {имя};
+ *    hint — только если подсказка кода из codes.ts к месту не подходит (образцы: api.connect_schema, sql-time.last_owner).
+ *    Параметр печатается как `${x}` в шаблонной строке, поэтому прежний текст не меняется; лучше скаляры (строка,
+ *    число). Похожие имена — params.similar (массив из similar() в errors.ts): «— похожие: a, b» lerr допишет сам, в
+ *    шаблон их не пишут.
+ *    Текст с двумя формами (род, число) — две записи или параметр без грамматики, а не склейка слов в коде.
+ * 4. Вызов в TS:
+ *      throw lerr('api.unknown_step', { name, similar: similar(name, names) });
+ *      throw lerr('access.switch_not_root');
+ *      throw lerr('<раздел>.<ключ>', { cls }, { detail: { id }, cause: e });   // detail и cause — как раньше
+ *    Текст не для ошибки (сообщение нарушения, описание) — lmsg(ключ, параметры); предупреждение — lwarn(ключ,
+ *    параметры, { once }). Подкласс и помощник вида fail(текст) переходят на ключ так же (образец — ValidationError в
+ *    errors.ts). Старый конструктор new LetopisError(код, текст) из переведённого места уходит целиком.
+ * 5. Вызов в SQL — перегрузка lt_fail(p_key text, p_params jsonb default '{}', p_detail jsonb default null)
+ *    (lib/sql/15-errors.sql): код ошибки — из записи, текст база собирает из шаблона ru (его видит и сырой SQL), в
+ *    DETAIL — поля p_detail и ещё key, params; их fromDbError переносит в поля ошибки (key, params):
+ *      perform @SCHEMA@.lt_fail('sql-core.no_membership');
+ *      perform @SCHEMA@.lt_fail('sql-write.invalid_data', jsonb_build_object('cls', NEW.class), jsonb_build_object('issues', bad));
+ *    Параметры — jsonb_build_object со скалярами (список — array_to_string); без параметров — один аргумент, а не null
+ *    (литерал без типа выбрал бы прежнюю lt_fail(имя, текст)). detail ошибки — прежний: без p_detail — {}, а место, где
+ *    был raise без detail, — p_detail => 'null' (detail нет). Свой SQLSTATE не из каталога — lt_raise(p_code, p_key,
+ *    p_params, p_detail). В функциях, которые исполняет приложение (inc, links_patch: lt_fail ему не выдан), — raise
+ *    как прежде (errcode — SQLSTATE кода, message — префикс «letopis: <код>: » и текст), только текст — lt_text(ключ,
+ *    параметры) (она выдана приложению), а detail — jsonb_build_object('key', ключ, 'params', параметры)::text; без
+ *    своих полей — ещё 'nodetail', true (detail нет, как у raise без detail).
+ *    Разделы sql-* установщик кладёт в базу при каждом up() (@MESSAGES@): новой ревизии и миграции не нужно.
+ * 6. Готовый файл — убрать из PENDING_LITERALS в lib/scripts/check-docs.mjs (проверка «в LetopisError, fail и lt_fail не
+ *    осталось литеральных текстов»). Затем cd lib && npm run typecheck, npm run check:docs, npm run api:contract и тесты
+ *    модуля по одному файлу: тест, который сверял русский текст, остаётся зелёным без правки.
+ * 7. Особые места. Разделы каталога контракт API читает регэкспами: код — из поля code: в кавычках, текст ошибки — из
+ *    строки с префиксом letopis и двоеточием; в комментариях их в таком виде не пишут. up.ts и pglite.ts бросают обычный Error('letopis.up: ' + lmsg(…)) — подходящего кода нет. Сообщения нарушений
+ *    (issues[].message: validate.ts, 30-validate.sql) — lmsg и lt_text с кодом invalid_data. Описания инструментов MCP и
+ *    instructions — строки в mcp.ts рядом со схемами, тексты ответов — раздел mcp.
+ */
+import { access } from './access.js';
+import { api } from './api.js';
+import { boot } from './boot.js';
+import { codes } from './codes.js';
+import { log } from './log.js';
+import { mcp } from './mcp.js';
+import { model } from './model.js';
+import { query } from './query.js';
+import { sqlAccess } from './sql-access.js';
+import { sqlCore } from './sql-core.js';
+import { sqlTime } from './sql-time.js';
+import { sqlWrite } from './sql-write.js';
+import { time } from './time.js';
+import { write } from './write.js';
+import type { ErrorCode, Msg, Params } from './types.js';
+export type { ErrorCode, Msg, Params, Section } from './types.js';
+/** Каталог событий логирования (не сообщения об ошибках — в MESSAGES не входит). */
+export { LOG_EVENTS, type LogEventInfo, type LogEventLevel, type LogEventName } from './log.js';
+/** Разделы, которые установщик кладёт в базу (message_catalog() в lib/sql/15-errors.sql). */
+export declare const SQL_SECTIONS: readonly ["sql-core", "sql-write", "sql-access", "sql-time"];
+type All = typeof codes & typeof api & typeof write & typeof query & typeof time & typeof access & typeof model & typeof boot & typeof mcp & typeof log & typeof sqlCore & typeof sqlWrite & typeof sqlAccess & typeof sqlTime;
+/** Ключ каталога: опечатку в lerr('…') ловит проверка типов. */
+export type MsgKey = keyof All;
+/** Все записи каталога по ключу. */
+export declare const MESSAGES: Readonly<Record<MsgKey, Msg>>;
+/** Запись по ключу из любого источника (DETAIL базы, вызов из JS); нет такой — undefined. */
+export declare function msgOf(key: string): Msg | undefined;
+/** Подпись кода: заголовок и подсказка «что делать» (codes.ts). */
+export declare function codeOf(code: string): (Msg & {
+    hint: string;
+}) | undefined;
+/** Суффикс похожих имён (params.similar) — его дописывает lerr. */
+export declare const SIMILAR = " \u2014 \u043F\u043E\u0445\u043E\u0436\u0438\u0435: {similar}";
+/**
+ * Шаблон с параметрами: `{имя}` → значение, напечатанное как в шаблонной строке JS (`${x}`), поэтому перенос текста
+ * `…${x}…` в шаблон `…{x}…` его не меняет. `{имя}` без такого параметра остаётся как есть; так же — lt_text() в базе
+ * (там null — пусто, как у format('%s')).
+ */
+export declare function render(template: string, params?: Params): string;
+/** Разделы sql-* для базы: ключ → имя ошибки и русский шаблон (установщик подставляет в @MESSAGES@). */
+export declare function sqlCatalog(): Record<string, {
+    name: ErrorCode;
+    ru: string;
+}>;

package/dist/messages/index.js

@@ -0,0 +1,121 @@
+/**
+ * Каталог сообщений letopis (план 2.0, этап 3, п. 3): ключ → код ошибки, шаблон текста и, если нужно, своя подсказка
+ * «что делать». Здесь разделы сливаются в MESSAGES (префикс ключа — имя раздела, ключи не повторяются), а render()
+ * подставляет параметры; ошибки и тексты строит errors.ts — lerr, lmsg, lwarn.
+ *
+ * Как перевести место на ключ каталога — инструкция исполнителям (образцы: записи разделов api, query, access, sql-core, sql-write,
+ * sql-time и места, которые их бросают).
+ *
+ * 1. Раздел — по файлу, где брошена ошибка:
+ *      api — index, chain, typed, errors, internal;  write — write, tx, load;  query — sql, ops;
+ *      time — watch, admin, cache, signals;  access — auth, acl;  model — model, registry, sync, cli, validate,
+ *      jsonschema, uuid;  boot — up, pglite;  mcp — mcp, describe;  log — log (и тексты логирования из index, tx);
+ *      sql-core — sql/10, 15, 20, 30, 40;  sql-write — sql/60;  sql-access — sql/50, 80;
+ *      sql-time — sql/70, 90, 95, 99 и sql/migrate.
+ *    codes.ts — запись на каждый код: заголовок и подсказка. Новый код — ещё ErrorCode (types.ts), для кода базы —
+ *    LT_NAMES (errors.ts) и error_catalog(), и строка таблицы «Ошибки» README с якорем `<a id="код"></a>`.
+ * 2. Ключ — `<раздел>.<snake_case>`: что случилось, а не где (api.unknown_step, query.sort_field). Одно место — один
+ *    ключ; одинаковый текст в разных разделах — разные ключи (api.validation_failed и sql-write.invalid_data).
+ * 3. Запись — { code, ru, hint? }, поля в этом порядке:
+ *    code — код, с которым место бросало ошибку: код не меняется (коды сверяет check:semver);
+ *    ru — прежний текст буква в букву, без префикса «letopis: <код>: »; подстановка ${x} → параметр {имя};
+ *    hint — только если подсказка кода из codes.ts к месту не подходит (образцы: api.connect_schema, sql-time.last_owner).
+ *    Параметр печатается как `${x}` в шаблонной строке, поэтому прежний текст не меняется; лучше скаляры (строка,
+ *    число). Похожие имена — params.similar (массив из similar() в errors.ts): «— похожие: a, b» lerr допишет сам, в
+ *    шаблон их не пишут.
+ *    Текст с двумя формами (род, число) — две записи или параметр без грамматики, а не склейка слов в коде.
+ * 4. Вызов в TS:
+ *      throw lerr('api.unknown_step', { name, similar: similar(name, names) });
+ *      throw lerr('access.switch_not_root');
+ *      throw lerr('<раздел>.<ключ>', { cls }, { detail: { id }, cause: e });   // detail и cause — как раньше
+ *    Текст не для ошибки (сообщение нарушения, описание) — lmsg(ключ, параметры); предупреждение — lwarn(ключ,
+ *    параметры, { once }). Подкласс и помощник вида fail(текст) переходят на ключ так же (образец — ValidationError в
+ *    errors.ts). Старый конструктор new LetopisError(код, текст) из переведённого места уходит целиком.
+ * 5. Вызов в SQL — перегрузка lt_fail(p_key text, p_params jsonb default '{}', p_detail jsonb default null)
+ *    (lib/sql/15-errors.sql): код ошибки — из записи, текст база собирает из шаблона ru (его видит и сырой SQL), в
+ *    DETAIL — поля p_detail и ещё key, params; их fromDbError переносит в поля ошибки (key, params):
+ *      perform @SCHEMA@.lt_fail('sql-core.no_membership');
+ *      perform @SCHEMA@.lt_fail('sql-write.invalid_data', jsonb_build_object('cls', NEW.class), jsonb_build_object('issues', bad));
+ *    Параметры — jsonb_build_object со скалярами (список — array_to_string); без параметров — один аргумент, а не null
+ *    (литерал без типа выбрал бы прежнюю lt_fail(имя, текст)). detail ошибки — прежний: без p_detail — {}, а место, где
+ *    был raise без detail, — p_detail => 'null' (detail нет). Свой SQLSTATE не из каталога — lt_raise(p_code, p_key,
+ *    p_params, p_detail). В функциях, которые исполняет приложение (inc, links_patch: lt_fail ему не выдан), — raise
+ *    как прежде (errcode — SQLSTATE кода, message — префикс «letopis: <код>: » и текст), только текст — lt_text(ключ,
+ *    параметры) (она выдана приложению), а detail — jsonb_build_object('key', ключ, 'params', параметры)::text; без
+ *    своих полей — ещё 'nodetail', true (detail нет, как у raise без detail).
+ *    Разделы sql-* установщик кладёт в базу при каждом up() (@MESSAGES@): новой ревизии и миграции не нужно.
+ * 6. Готовый файл — убрать из PENDING_LITERALS в lib/scripts/check-docs.mjs (проверка «в LetopisError, fail и lt_fail не
+ *    осталось литеральных текстов»). Затем cd lib && npm run typecheck, npm run check:docs, npm run api:contract и тесты
+ *    модуля по одному файлу: тест, который сверял русский текст, остаётся зелёным без правки.
+ * 7. Особые места. Разделы каталога контракт API читает регэкспами: код — из поля code: в кавычках, текст ошибки — из
+ *    строки с префиксом letopis и двоеточием; в комментариях их в таком виде не пишут. up.ts и pglite.ts бросают обычный Error('letopis.up: ' + lmsg(…)) — подходящего кода нет. Сообщения нарушений
+ *    (issues[].message: validate.ts, 30-validate.sql) — lmsg и lt_text с кодом invalid_data. Описания инструментов MCP и
+ *    instructions — строки в mcp.ts рядом со схемами, тексты ответов — раздел mcp.
+ */
+import { access } from './access.js';
+import { api } from './api.js';
+import { boot } from './boot.js';
+import { codes } from './codes.js';
+import { log } from './log.js';
+import { mcp } from './mcp.js';
+import { model } from './model.js';
+import { query } from './query.js';
+import { sqlAccess } from './sql-access.js';
+import { sqlCore } from './sql-core.js';
+import { sqlTime } from './sql-time.js';
+import { sqlWrite } from './sql-write.js';
+import { time } from './time.js';
+import { write } from './write.js';
+/** Каталог событий логирования (не сообщения об ошибках — в MESSAGES не входит). */
+export { LOG_EVENTS } from './log.js';
+/** Разделы каталога: имя — префикс ключа и имя файла. */
+const SECTIONS = {
+    codes, api, write, query, time, access, model, boot, mcp, log,
+    'sql-core': sqlCore, 'sql-write': sqlWrite, 'sql-access': sqlAccess, 'sql-time': sqlTime,
+};
+/** Разделы, которые установщик кладёт в базу (message_catalog() в lib/sql/15-errors.sql). */
+export const SQL_SECTIONS = ['sql-core', 'sql-write', 'sql-access', 'sql-time'];
+function merge(sections) {
+    const out = {};
+    for (const [name, section] of Object.entries(sections)) {
+        for (const [key, m] of Object.entries(section)) {
+            if (!key.startsWith(`${name}.`))
+                throw new Error(`letopis: ключ каталога ${key} — не из раздела ${name}`);
+            if (Object.hasOwn(out, key))
+                throw new Error(`letopis: ключ каталога ${key} повторяется`);
+            out[key] = m;
+        }
+    }
+    return out;
+}
+/** Все записи каталога по ключу. */
+export const MESSAGES = merge(SECTIONS);
+/** Запись по ключу из любого источника (DETAIL базы, вызов из JS); нет такой — undefined. */
+export function msgOf(key) {
+    return Object.hasOwn(MESSAGES, key) ? MESSAGES[key] : undefined;
+}
+/** Подпись кода: заголовок и подсказка «что делать» (codes.ts). */
+export function codeOf(code) {
+    return msgOf(`codes.${code}`);
+}
+/** Суффикс похожих имён (params.similar) — его дописывает lerr. */
+export const SIMILAR = ' — похожие: {similar}';
+/**
+ * Шаблон с параметрами: `{имя}` → значение, напечатанное как в шаблонной строке JS (`${x}`), поэтому перенос текста
+ * `…${x}…` в шаблон `…{x}…` его не меняет. `{имя}` без такого параметра остаётся как есть; так же — lt_text() в базе
+ * (там null — пусто, как у format('%s')).
+ */
+export function render(template, params) {
+    if (!params)
+        return template;
+    return template.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (m, k) => (Object.hasOwn(params, k) ? String(params[k]) : m));
+}
+/** Разделы sql-* для базы: ключ → имя ошибки и русский шаблон (установщик подставляет в @MESSAGES@). */
+export function sqlCatalog() {
+    const out = {};
+    for (const s of SQL_SECTIONS) {
+        for (const [key, m] of Object.entries(SECTIONS[s]))
+            out[key] = { name: m.code, ru: m.ru };
+    }
+    return out;
+}

package/dist/messages/log.d.ts

@@ -0,0 +1,229 @@
+export declare const log: {
+    'log.bad_level': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
+    'log.bad_logger': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
+    'log.bad_redact': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
+    'log.db_error': {
+        code: "internal";
+        ru: string;
+    };
+    'log.logger_failed': {
+        code: "internal";
+        ru: string;
+    };
+    'log.notify_failed': {
+        code: "internal";
+        ru: string;
+    };
+    'log.renew_failed': {
+        code: "no_session";
+        ru: string;
+    };
+};
+/** Уровень события. */
+export type LogEventLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Запись каталога событий: уровень по умолчанию и что значит событие. */
+export interface LogEventInfo {
+    level: LogEventLevel;
+    ru: string;
+}
+/**
+ * Каталог событий логирования. Имена основных событий зафиксированы спецификацией 3.0 (connect, close, up, migrate,
+ * sync, read, cache.hit, cache.miss, write, delete.preview, delete, restore, tx.*, auth.login, auth.logout, auth.revoke,
+ * auth.switch, watch.start, watch.stop, signal, maintain, warning, error, sql); остальные — дополнительные.
+ */
+export declare const LOG_EVENTS: {
+    readonly connect: {
+        readonly level: "info";
+        readonly ru: "connect() готов: схема, режим сигналов, кэш, способ входа";
+    };
+    readonly close: {
+        readonly level: "info";
+        readonly ru: "db.close(): пул, подписки и таймеры закрыты";
+    };
+    readonly 'registry.refresh': {
+        readonly level: "debug";
+        readonly ru: "реестр классов перечитан";
+    };
+    readonly 'session.renew': {
+        readonly level: "info";
+        readonly ru: "сессия по ключу сервиса истекла — ключ обменян на новую";
+    };
+    readonly up: {
+        readonly level: "info";
+        readonly ru: "up() завершён: схема поставлена, обновлена или накатана повторно";
+    };
+    readonly 'up.step': {
+        readonly level: "info";
+        readonly ru: "шаг up(): то, что без логгера печатается в консоль";
+    };
+    readonly migrate: {
+        readonly level: "info";
+        readonly ru: "up() обновил ревизию схемы миграциями";
+    };
+    readonly 'tenant.create': {
+        readonly level: "info";
+        readonly ru: "арендатор (и его первый пользователь) заведён или найден";
+    };
+    readonly sync: {
+        readonly level: "info";
+        readonly ru: "syncModels(): классы созданы, изменены или сверены (сухой прогон)";
+    };
+    readonly read: {
+        readonly level: "debug";
+        readonly ru: "терминал чтения цепочки: rows, first, ids, count, paths, versions, агрегаты";
+    };
+    readonly 'cache.hit': {
+        readonly level: "debug";
+        readonly ru: "ответ взят из кэша результатов";
+    };
+    readonly 'cache.miss': {
+        readonly level: "debug";
+        readonly ru: "ответа нет в кэше результатов — запрос к базе";
+    };
+    readonly raw: {
+        readonly level: "debug";
+        readonly ru: "сырой SQL db.sql";
+    };
+    readonly write: {
+        readonly level: "info";
+        readonly ru: "запись цепочкой (create, update, upsert, слоты) или батч";
+    };
+    readonly 'delete.preview': {
+        readonly level: "debug";
+        readonly ru: "превью удаления: delete() без confirm, ничего не удалено";
+    };
+    readonly delete: {
+        readonly level: "info";
+        readonly ru: "удаление выполнено: состав каскада, сверка с expect";
+    };
+    readonly restore: {
+        readonly level: "info";
+        readonly ru: "восстановление выполнено: восстановленные и пропущенные цели";
+    };
+    readonly load: {
+        readonly level: "info";
+        readonly ru: "db.load(): массовая загрузка завершена";
+    };
+    readonly lock: {
+        readonly level: "debug";
+        readonly ru: "db.lock(): advisory-блокировка в транзакции";
+    };
+    readonly 'tx.begin': {
+        readonly level: "debug";
+        readonly ru: "открыта транзакция: db.begin() или db.transaction()";
+    };
+    readonly 'tx.commit': {
+        readonly level: "debug";
+        readonly ru: "транзакция зафиксирована; с записью (db.begin()) и у db.transaction() — уровень info и detail.writes: доказательство фиксации событий с тем же tx";
+    };
+    readonly 'tx.rollback': {
+        readonly level: "info";
+        readonly ru: "транзакция откачена: явно или из-за ошибки";
+    };
+    readonly 'tx.retry': {
+        readonly level: "warn";
+        readonly ru: "повтор операции после конфликта (взаимная блокировка, сериализация, журнал)";
+    };
+    readonly 'auth.login': {
+        readonly level: "info";
+        readonly ru: "успешный вход: пароль, ключ, код, привязка";
+    };
+    readonly 'auth.fail': {
+        readonly level: "warn";
+        readonly ru: "неудачный вход или неверный второй фактор";
+    };
+    readonly 'auth.logout': {
+        readonly level: "info";
+        readonly ru: "выход: гашение текущей сессии";
+    };
+    readonly 'auth.revoke': {
+        readonly level: "info";
+        readonly ru: "отзыв: сессии по токену, все сессии аккаунта или кред";
+    };
+    readonly 'auth.switch': {
+        readonly level: "info";
+        readonly ru: "auth.switch(): сменён рабочий арендатор сессии";
+    };
+    readonly 'auth.as': {
+        readonly level: "debug";
+        readonly ru: "db.as(): фасад от имени другого аккаунта или арендатора";
+    };
+    readonly 'auth.session': {
+        readonly level: "info";
+        readonly ru: "сервис выпустил сессию пользователю (sessionFor)";
+    };
+    readonly 'auth.credential': {
+        readonly level: "info";
+        readonly ru: "кред заведён или изменён: пароль, ключ, TOTP, код, привязка, флаги";
+    };
+    readonly 'auth.call': {
+        readonly level: "debug";
+        readonly ru: "прочие вызовы db.auth: сведения о сессии, кредах, арендаторах";
+    };
+    readonly 'account.purge': {
+        readonly level: "info";
+        readonly ru: "аккаунт удалён с данными своего арендатора";
+    };
+    readonly 'acl.change': {
+        readonly level: "info";
+        readonly ru: "права изменены: grant, deny, revoke, roles";
+    };
+    readonly 'acl.check': {
+        readonly level: "debug";
+        readonly ru: "проверка или список прав";
+    };
+    readonly 'watch.start': {
+        readonly level: "info";
+        readonly ru: "подписка watch() открыта";
+    };
+    readonly 'watch.fetch': {
+        readonly level: "debug";
+        readonly ru: "подписка прочитала пачку событий журнала";
+    };
+    readonly 'watch.stop': {
+        readonly level: "info";
+        readonly ru: "подписка закрыта";
+    };
+    readonly signal: {
+        readonly level: "debug";
+        readonly ru: "получен сигнал базы (NOTIFY) или слушатель переподключился";
+    };
+    readonly 'signal.send': {
+        readonly level: "debug";
+        readonly ru: "отправлены накопленные сигналы записи";
+    };
+    readonly maintain: {
+        readonly level: "info";
+        readonly ru: "maintain(): обслуживание выполнено или пропущено";
+    };
+    readonly 'mcp.call': {
+        readonly level: "info";
+        readonly ru: "вызов инструмента MCP";
+    };
+    readonly warning: {
+        readonly level: "warn";
+        readonly ru: "предупреждение letopis";
+    };
+    readonly error: {
+        readonly level: "error";
+        readonly ru: "ошибка операции letopis: код, ключ каталога, подробности, причина; штатный отказ (exists, conflict, target_not_found, нарушения данных и т. п.) — уровень warn; у ошибки PostgreSQL — только SQLSTATE и имена объектов схемы";
+    };
+    readonly sql: {
+        readonly level: "debug";
+        readonly ru: "SQL-запрос: текст без значений параметров, время, число строк";
+    };
+};
+/** Имя события логирования. */
+export type LogEventName = keyof typeof LOG_EVENTS;

package/dist/messages/log.js

@@ -0,0 +1,102 @@
+export const log = {
+    // log.ts, makeLog: logLevel не из списка; value — как передан (строка — в кавычках)
+    'log.bad_level': {
+        code: 'invalid_data',
+        ru: "logLevel {value}: ожидается 'debug', 'info', 'warn', 'error' или 'off'",
+        hint: "передать logLevel одной из строк 'debug', 'info', 'warn', 'error', 'off' (по умолчанию 'info')",
+    },
+    // log.ts, makeLog: log — не функция и не объект с методами уровней
+    'log.bad_logger': {
+        code: 'invalid_data',
+        ru: 'log: ожидается функция (событие) => void или объект с методами debug, info, warn, error (pino, console)',
+        hint: 'передать в log функцию или объект логгера (pino, console)',
+    },
+    // log.ts, makeLog: redact — не массив строк
+    'log.bad_redact': {
+        code: 'invalid_data',
+        ru: 'redact: ожидается массив имён полей (строк)',
+        hint: "передать redact списком имён полей, например ['email', 'phone']",
+    },
+    // log.ts, errorFields и causeOf: ошибка PostgreSQL в событии — только SQLSTATE и имена объектов схемы; её текст,
+    // DETAIL, WHERE и HINT могут нести значения параметров и данных и в журнал не идут (полный текст — у самой ошибки)
+    'log.db_error': {
+        code: 'internal',
+        ru: 'ошибка PostgreSQL {sqlstate} (текст, DETAIL, WHERE и HINT базы в журнал не пишутся — они у самой ошибки)',
+    },
+    // log.ts, deliver: исключение в логгере приложения — один раз на процесс в stderr; операция не прерывается
+    'log.logger_failed': {
+        code: 'internal',
+        ru: 'логгер бросил исключение на событии {event}: {message} — событие пропущено, операции это не мешает',
+    },
+    // index.ts, Notifier: отправка сигналов не удалась — предупреждение (warning); повтор — следующим интервалом
+    'log.notify_failed': {
+        code: 'internal',
+        ru: 'сигналы не отправлены: {message} — повтор следующим интервалом',
+    },
+    // index.ts, ctx.renew: обмен ключа сервиса на новую сессию не удался — предупреждение (warning)
+    'log.renew_failed': {
+        code: 'no_session',
+        ru: 'сессия по ключу сервиса истекла, а обмен ключа на новую не удался',
+    },
+};
+/**
+ * Каталог событий логирования. Имена основных событий зафиксированы спецификацией 3.0 (connect, close, up, migrate,
+ * sync, read, cache.hit, cache.miss, write, delete.preview, delete, restore, tx.*, auth.login, auth.logout, auth.revoke,
+ * auth.switch, watch.start, watch.stop, signal, maintain, warning, error, sql); остальные — дополнительные.
+ */
+export const LOG_EVENTS = {
+    // подключение
+    'connect': { level: 'info', ru: 'connect() готов: схема, режим сигналов, кэш, способ входа' },
+    'close': { level: 'info', ru: 'db.close(): пул, подписки и таймеры закрыты' },
+    'registry.refresh': { level: 'debug', ru: 'реестр классов перечитан' },
+    'session.renew': { level: 'info', ru: 'сессия по ключу сервиса истекла — ключ обменян на новую' },
+    // установка
+    'up': { level: 'info', ru: 'up() завершён: схема поставлена, обновлена или накатана повторно' },
+    'up.step': { level: 'info', ru: 'шаг up(): то, что без логгера печатается в консоль' },
+    'migrate': { level: 'info', ru: 'up() обновил ревизию схемы миграциями' },
+    'tenant.create': { level: 'info', ru: 'арендатор (и его первый пользователь) заведён или найден' },
+    'sync': { level: 'info', ru: 'syncModels(): классы созданы, изменены или сверены (сухой прогон)' },
+    // чтение
+    'read': { level: 'debug', ru: 'терминал чтения цепочки: rows, first, ids, count, paths, versions, агрегаты' },
+    'cache.hit': { level: 'debug', ru: 'ответ взят из кэша результатов' },
+    'cache.miss': { level: 'debug', ru: 'ответа нет в кэше результатов — запрос к базе' },
+    'raw': { level: 'debug', ru: 'сырой SQL db.sql' },
+    // запись
+    'write': { level: 'info', ru: 'запись цепочкой (create, update, upsert, слоты) или батч' },
+    'delete.preview': { level: 'debug', ru: 'превью удаления: delete() без confirm, ничего не удалено' },
+    'delete': { level: 'info', ru: 'удаление выполнено: состав каскада, сверка с expect' },
+    'restore': { level: 'info', ru: 'восстановление выполнено: восстановленные и пропущенные цели' },
+    'load': { level: 'info', ru: 'db.load(): массовая загрузка завершена' },
+    'lock': { level: 'debug', ru: 'db.lock(): advisory-блокировка в транзакции' },
+    // транзакции
+    'tx.begin': { level: 'debug', ru: 'открыта транзакция: db.begin() или db.transaction()' },
+    'tx.commit': { level: 'debug', ru: 'транзакция зафиксирована; с записью (db.begin()) и у db.transaction() — уровень info и detail.writes: доказательство фиксации событий с тем же tx' },
+    'tx.rollback': { level: 'info', ru: 'транзакция откачена: явно или из-за ошибки' },
+    'tx.retry': { level: 'warn', ru: 'повтор операции после конфликта (взаимная блокировка, сериализация, журнал)' },
+    // вход и права
+    'auth.login': { level: 'info', ru: 'успешный вход: пароль, ключ, код, привязка' },
+    'auth.fail': { level: 'warn', ru: 'неудачный вход или неверный второй фактор' },
+    'auth.logout': { level: 'info', ru: 'выход: гашение текущей сессии' },
+    'auth.revoke': { level: 'info', ru: 'отзыв: сессии по токену, все сессии аккаунта или кред' },
+    'auth.switch': { level: 'info', ru: 'auth.switch(): сменён рабочий арендатор сессии' },
+    'auth.as': { level: 'debug', ru: 'db.as(): фасад от имени другого аккаунта или арендатора' },
+    'auth.session': { level: 'info', ru: 'сервис выпустил сессию пользователю (sessionFor)' },
+    'auth.credential': { level: 'info', ru: 'кред заведён или изменён: пароль, ключ, TOTP, код, привязка, флаги' },
+    'auth.call': { level: 'debug', ru: 'прочие вызовы db.auth: сведения о сессии, кредах, арендаторах' },
+    'account.purge': { level: 'info', ru: 'аккаунт удалён с данными своего арендатора' },
+    'acl.change': { level: 'info', ru: 'права изменены: grant, deny, revoke, roles' },
+    'acl.check': { level: 'debug', ru: 'проверка или список прав' },
+    // время
+    'watch.start': { level: 'info', ru: 'подписка watch() открыта' },
+    'watch.fetch': { level: 'debug', ru: 'подписка прочитала пачку событий журнала' },
+    'watch.stop': { level: 'info', ru: 'подписка закрыта' },
+    'signal': { level: 'debug', ru: 'получен сигнал базы (NOTIFY) или слушатель переподключился' },
+    'signal.send': { level: 'debug', ru: 'отправлены накопленные сигналы записи' },
+    'maintain': { level: 'info', ru: 'maintain(): обслуживание выполнено или пропущено' },
+    // MCP
+    'mcp.call': { level: 'info', ru: 'вызов инструмента MCP' },
+    // общее
+    'warning': { level: 'warn', ru: 'предупреждение letopis' },
+    'error': { level: 'error', ru: 'ошибка операции letopis: код, ключ каталога, подробности, причина; штатный отказ (exists, conflict, target_not_found, нарушения данных и т. п.) — уровень warn; у ошибки PostgreSQL — только SQLSTATE и имена объектов схемы' },
+    'sql': { level: 'debug', ru: 'SQL-запрос: текст без значений параметров, время, число строк' },
+};