letopis 2.0.0 → 3.0.1

package/dist/mcp.js

@@ -27,9 +27,11 @@ import { createRequire } from 'node:module';
 import { describeModel } from './describe.js';
 import { LetopisError, checkOptions, lerr, lmsg, similar } from './errors.js';
 import { internalsOf } from './internal.js';
+import { NOLOG } from './log.js';
 import { OPERATORS, opHint, or } from './ops.js';
 import { cursorOf } from './sql.js';
 import { ACL_CLASS_NAMES, RESERVED_CLASS_NAMES } from './types.js';
+import { UUID_RE } from './uuid.js';
 /** Все опции createMcpServer: неизвестная — invalid_data с похожими именами (checkOptions; план 2.0, 7.10 №4). */
 const MCP_OPTIONS = {
     write: true, maxRows: true, maxBytes: true, allowAclWrite: true, allowSystemAdmin: true,
@@ -43,7 +45,7 @@ const STATE_KEY = randomBytes(32);
 const CONFIRM_TTL_MS = 10 * 60_000;
 const RESERVED = new Set(RESERVED_CLASS_NAMES);
 const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID = UUID_RE;
 const TERMINALS = ['rows', 'first', 'ids', 'count', 'sum', 'avg', 'min', 'max', 'countBy'];
 const PAGED = new Set(['rows', 'first', 'ids']);
 /** Шагов цепочки и условий $or в одном фильтре не больше (ревью безопасности №2): запрос растёт с каждым. */
@@ -375,6 +377,8 @@ function stepFilter(a, where) {
     return undefined;
 }
 const step = (x, name) => x[name];
+/** Шаг с фильтром или без: без фильтра — вызов без аргумента (X(undefined) цепочка отмечает предупреждением, A13). */
+const stepWith = (fn, f) => (f === undefined ? fn() : fn(f));
 const encodeCursor = (c) => Buffer.from(JSON.stringify(c)).toString('base64url');
 function decodeCursor(s) {
     let c;
@@ -425,7 +429,7 @@ async function query(db, a, o) {
     if (typeof terminal !== 'string' || !TERMINALS.includes(terminal)) {
         throw lerr('mcp.unknown_terminal', { terminal: String(terminal), similar: similar(String(terminal), TERMINALS) });
     }
-    let chain = step(db, stepName(reg, a.class, 'letopis_query.class'))(stepFilter(a, 'letopis_query'));
+    let chain = stepWith(step(db, stepName(reg, a.class, 'letopis_query.class')), stepFilter(a, 'letopis_query'));
     if (a.steps !== undefined) {
         if (!Array.isArray(a.steps))
             throw lerr('mcp.steps_not_list');
@@ -436,7 +440,7 @@ async function query(db, a, o) {
             if (!isObj(s))
                 throw lerr('mcp.step_not_object', { where });
             checkKeys(s, ['step', 'id', 'ids', 'filter'], where);
-            chain = step(chain, stepName(reg, s.step, `${where}.step`))(stepFilter(s, where));
+            chain = stepWith(step(chain, stepName(reg, s.step, `${where}.step`)), stepFilter(s, where));
         });
     }
     if (a.asOf !== undefined) {
@@ -541,7 +545,7 @@ function withLinks(db, cls, c, links) {
 }
 /** Хэш операции удаления: схема, арендатор, класс, цели и превью каскада — подтверждение человека привязано к нему. */
 function operationOf(db, cls, targets, preview) {
-    const rows = preview.map((r) => [r.id, r.class, r.rev, r.$action ?? null, r.$depth ?? null]).sort((x, y) => (String(x[0]) < String(y[0]) ? -1 : 1));
+    const rows = preview.map((r) => [r.id, r.class, r.rev, r.$action ?? null, r.$depth ?? null, r.$count ?? null]).sort((x, y) => (String(x[0]) < String(y[0]) ? -1 : 1));
     return createHash('sha256').update(JSON.stringify({ schema: db.schema, tenant: db.tenant, cls, targets: [...targets].sort(), rows })).digest('hex');
 }
 const hmacOf = (who, exp, op) => createHmac('sha256', STATE_KEY).update(`letopis:mcp:delete:${who.account}:${who.tenant}:${exp}:${op}`).digest('hex');
@@ -658,15 +662,18 @@ async function write(db, a, ctx, sdk, server, o, who) {
         throw lerr('mcp.delete_operation_changed', undefined, { detail: { operation: op } });
     if (!preview.some((r) => (r.$depth ?? 0) === 0))
         throw lerr('mcp.delete_nothing');
-    if (preview.some((r) => r.$action === 'restrict'))
+    // мешают и скрытые правами строки: сводка $hidden 'restrict' (3.0.1)
+    if (preview.some((r) => r.$action === 'restrict' || r.$hidden === 'restrict'))
         throw lerr('mcp.delete_restricted', undefined, { detail: { preview } });
-    const count = (act) => preview.filter((r) => r.$action === act).length;
+    // сводка скрытых строк считается их числом ($count)
+    const count = (act) => preview.filter((r) => act === undefined || r.$action === act || r.$hidden === act)
+        .reduce((n, r) => n + (r.$action === 'hidden' ? r.$count ?? 0 : 1), 0);
     // окно видит человек: каноническое имя класса (имя — идентификатор по метасхеме) и id целей; алиас и meta — текст
     // арендатора, в окно они не попадают (ревью безопасности №2)
     const first = targets.slice(0, CONFIRM_IDS).join(', ');
     const shown = targets.length > CONFIRM_IDS ? lmsg('mcp.delete_ids_more', { ids: first, more: targets.length - CONFIRM_IDS }) : first;
     const message = lmsg('mcp.delete_message', {
-        count: targets.length, cls: db.registry.resolve(cls).name, ids: shown, rows: preview.length,
+        count: targets.length, cls: db.registry.resolve(cls).name, ids: shown, rows: count(),
         deleted: count('delete'), unset: count('unset'), operation: op.slice(0, 12),
     });
     const c = await confirmDelete(sdk, server, ctx, op, message, who);
@@ -674,13 +681,14 @@ async function write(db, a, ctx, sdk, server, o, who) {
         return c.ask;
     if (!c.granted)
         throw lerr(c.reason);
-    // превью и удаление — одной транзакцией: подтверждено ровно то, что удаляется
+    // превью и удаление — одной транзакцией: подтверждено ровно то, что удаляется; delete сверяет превью сам (expect,
+    // 3.0) — под блокировкой замыкания каскада
     const tx = await db.begin();
     try {
         const again = await step(tx, cls)(targets).delete(opts).rows();
         if (operationOf(db, cls, targets, again) !== op)
             throw lerr('mcp.delete_data_changed');
-        const rows = await step(tx, cls)(targets).delete({ confirm: true, ...opts }).rows();
+        const rows = await step(tx, cls)(targets).delete({ confirm: true, expect: again, ...opts }).rows();
         await tx.commit();
         return ok({ deleted: rows, operation: op });
     }
@@ -733,7 +741,7 @@ async function checkCredentials(db, o) {
 }
 /**
  * Сервер MCP для одного пользователя letopis: инструменты `letopis_model`, `letopis_query`, `letopis_history`, а с
- * `{ write: true }` — ещё `letopis_write`. Подключение — сессия пользователя (`connect({ token })`) или фасад
+ * `{ write: true }` — ещё `letopis_write`. Подключение — сессия пользователя (`connect({ token })`) или подключение
  * `db.as(пользователь)`. Транспорт выбирает приложение: `server.connect(транспорт)`, `serveStdio(() => createMcpServer(db))`
  * или обработчик HTTP `createMcpHandler(() => createMcpServer(db))` из SDK; токен запроса HTTP проверяет приложение.
  */
@@ -748,19 +756,29 @@ async function serve(db, opts) {
     const who = await checkCredentials(db, o);
     const sdk = await loadSdk();
     const server = new sdk.McpServer({ name: 'letopis', version: VERSION }, { instructions: instructions(o), capabilities: { tools: {} } });
-    const guard = (fn) => async (args, ctx) => {
+    // логирование 3.0: вызов инструмента — mcp.call (имя, время, исход), отказ — ещё error; логгер — фасада db
+    const log = internalsOf(db)?.log ?? NOLOG;
+    const guard = (tool, fn) => async (args, ctx) => {
+        const t0 = performance.now();
         try {
-            return await fn(isObj(args) ? args : {}, ctx);
+            const r = await fn(isObj(args) ? args : {}, ctx);
+            if (log.wants('mcp.call')) {
+                log.emit('mcp.call', { op: tool, ms: performance.now() - t0, detail: { ok: !r.isError } });
+            }
+            return r;
         }
         catch (e) {
+            log.error(e, { op: tool, ms: performance.now() - t0 });
+            if (log.wants('mcp.call'))
+                log.emit('mcp.call', { op: tool, ms: performance.now() - t0, detail: { ok: false } });
             return failure(e);
         }
     };
-    server.registerTool('letopis_model', { title: 'Модель letopis', description: DESCRIBE_MODEL, inputSchema: sdk.fromJsonSchema(MODEL_SCHEMA), annotations: READ_ONLY }, guard((a) => model(db, a, o)));
-    server.registerTool('letopis_query', { title: 'Чтение letopis', description: describeQuery(o), inputSchema: sdk.fromJsonSchema(QUERY_SCHEMA), annotations: READ_ONLY }, guard((a) => query(db, a, o)));
-    server.registerTool('letopis_history', { title: 'История letopis', description: describeHistory(o), inputSchema: sdk.fromJsonSchema(HISTORY_SCHEMA), annotations: READ_ONLY }, guard((a) => history(db, a, o)));
+    server.registerTool('letopis_model', { title: 'Модель letopis', description: DESCRIBE_MODEL, inputSchema: sdk.fromJsonSchema(MODEL_SCHEMA), annotations: READ_ONLY }, guard('letopis_model', (a) => model(db, a, o)));
+    server.registerTool('letopis_query', { title: 'Чтение letopis', description: describeQuery(o), inputSchema: sdk.fromJsonSchema(QUERY_SCHEMA), annotations: READ_ONLY }, guard('letopis_query', (a) => query(db, a, o)));
+    server.registerTool('letopis_history', { title: 'История letopis', description: describeHistory(o), inputSchema: sdk.fromJsonSchema(HISTORY_SCHEMA), annotations: READ_ONLY }, guard('letopis_history', (a) => history(db, a, o)));
     if (o.write) {
-        server.registerTool('letopis_write', { title: 'Запись letopis', description: describeWrite(o), inputSchema: sdk.fromJsonSchema(WRITE_SCHEMA), annotations: DESTRUCTIVE }, guard((a, ctx) => write(db, a, ctx, sdk, server, o, who)));
+        server.registerTool('letopis_write', { title: 'Запись letopis', description: describeWrite(o), inputSchema: sdk.fromJsonSchema(WRITE_SCHEMA), annotations: DESTRUCTIVE }, guard('letopis_write', (a, ctx) => write(db, a, ctx, sdk, server, o, who)));
     }
     return server;
 }

package/dist/messages/access.d.ts

@@ -87,4 +87,14 @@ export declare const access: {
         ru: string;
         hint: string;
     };
+    'access.bad_max_attempts': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
+    'access.bad_ttl': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
 };

package/dist/messages/access.js

@@ -110,4 +110,17 @@ export const access = {
         ru: 'секрет TOTP — не base32',
         hint: 'передать секрет из auth.enrollTotp() — строку base32 (A–Z, 2–7)',
     },
+    // auth.ts, issueOtp (3.0.1): maxAttempts не целое или вне 1–10 (раньше база молча приводила к пределу); value — как передан
+    'access.bad_max_attempts': {
+        code: 'invalid_data',
+        ru: 'issueOtp: maxAttempts {value} — целое от 1 до 10',
+        hint: 'maxAttempts — число неверных попыток до того, как код сгорит: целое от 1 до 10 (по умолчанию 5)',
+    },
+    // auth.ts, ttlOf (3.0.1): срок ttl (sessionFor, issueOtp, issueApiKey, verifyPassword, lookup, refresh, createTenant) — не
+    // число секунд, не короткая форма и не интервал PostgreSQL; where — вызов, value — как передан
+    'access.bad_ttl': {
+        code: 'invalid_data',
+        ru: "{where}: ttl {value} — нужно число секунд, '15m' или интервал PostgreSQL '15 minutes'",
+        hint: "срок ttl больше нуля: число секунд (600), короткая форма '30s', '15m', '2h', '1d' или интервал PostgreSQL '15 minutes'",
+    },
 };

package/dist/messages/api.d.ts

@@ -6,6 +6,56 @@ export declare const api: {
     'api.unknown_step': {
         code: "invalid_class";
         ru: string;
+        hint: string;
+    };
+    'api.token_not_active': {
+        code: "no_session";
+        ru: string;
+        hint: string;
+    };
+    'api.unknown_step_no_classes': {
+        code: "invalid_class";
+        ru: string;
+        hint: string;
+    };
+    'api.unknown_step_empty_tenant': {
+        code: "invalid_class";
+        ru: string;
+        hint: string;
+    };
+    'api.chain_not_rows': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
+    'api.step_undefined_filter': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'api.sort_not_last': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'api.with_deleted_step': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'api.db_bad_value': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
+    'api.validation_issue': {
+        code: "invalid_data";
+        ru: string;
+    };
+    'api.validation_root': {
+        code: "invalid_data";
+        ru: string;
+    };
+    'api.validation_more': {
+        code: "invalid_data";
+        ru: string;
     };
     'api.connect_schema': {
         code: "invalid_data";
@@ -49,6 +99,7 @@ export declare const api: {
     'api.for_update_unsupported': {
         code: "lock_unsupported";
         ru: string;
+        hint: string;
     };
     'api.lock_denied': {
         code: "acl_denied";
@@ -119,6 +170,16 @@ export declare const api: {
         ru: string;
         hint: string;
     };
+    'api.begin_arg': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
+    'api.closed': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
     'api.nested_begin': {
         code: "invalid_query";
         ru: string;
@@ -132,6 +193,11 @@ export declare const api: {
         ru: string;
         hint: string;
     };
+    'api.connect_empty_credential': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
     'api.connect_admin_type': {
         code: "invalid_data";
         ru: string;
@@ -168,4 +234,14 @@ export declare const api: {
         code: "invalid_data";
         ru: string;
     };
+    'api.create_tenant_admin': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
+    'api.versions_terminal': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
 };

package/dist/messages/api.js

@@ -8,6 +8,74 @@ export const api = {
     'api.unknown_step': {
         code: 'invalid_class',
         ru: 'класс или роль {name} не найдены',
+        hint: 'классы арендатора видны только в его сессии: арендаторы пользователя — db.auth.tenants(), переход — db.auth.switch(tenant) или db.as(аккаунт, { tenant }); имя — как в модели (классы записывает syncModels)',
+    },
+    // chain.ts: шаг не найден, а в реестре сессии нет ни одного класса, кроме классов System — сессия, похоже, в
+    // личном арендаторе (вход без switch); похожие имена — params.similar
+    // index.ts: connect({ token }) — токен не даёт сессии (погашен, истёк, неверен); chain.ts: шаг корня без сессии
+    // (сессия погасла после connect) — отказ терминала, а не синхронный
+    'api.token_not_active': {
+        code: 'no_session',
+        ru: 'нет действующей сессии: токен погашен, истёк или неверен',
+        hint: 'войти заново и подключиться с новым токеном; веб-сервису — одно подключение сервиса и svc.as(account, { tenant }) на запрос, а не connect({ token }) на каждый вход',
+    },
+    'api.unknown_step_no_classes': {
+        code: 'invalid_class',
+        ru: 'класс или роль {name} не найдены: в реестре сессии нет ни одного класса арендатора — сессия, похоже, в личном арендаторе',
+        hint: 'после входа сессия работает в личном арендаторе пользователя: найти нужного — db.auth.tenants(), перейти — db.auth.switch(tenant) или db.as(аккаунт, { tenant }); классы в арендатор записывает syncModels',
+    },
+    // chain.ts (3.0.1): шаг не найден, в реестре сессии только классы System, а арендатор сессии не личный — в нём просто
+    // нет классов; похожие имена — params.similar
+    'api.unknown_step_empty_tenant': {
+        code: 'invalid_class',
+        ru: 'класс или роль {name} не найдены: в этом арендаторе нет классов — вызовите syncModels в нём',
+        hint: 'классы в арендатор записывает syncModels — в сессии этого арендатора (подключение арендатора или db.as(аккаунт, { tenant })); имя — как в модели',
+    },
+    // chain.ts: у цепочки спросили свойство массива (length, map, filter, 0 …) или перебрали её — она не массив строк
+    'api.chain_not_rows': {
+        code: 'invalid_query',
+        ru: 'цепочка — не массив: {name} есть у строк ответа, а не у цепочки',
+        hint: 'получить строки терминалом с await: const rows = await db.Класс(…).rows(), одну строку — await ….first()',
+    },
+    // chain.ts, A13: шаг вызван с аргументом undefined — фильтра нет, шаг находит все строки класса (как без аргумента);
+    // предупреждение (lwarn), один раз на имя шага
+    'api.step_undefined_filter': {
+        code: 'invalid_query',
+        ru: '{name}(undefined) — фильтра нет: шаг находит все строки, как {name}(). Проверьте переменную с id',
+    },
+    // chain.ts, A13: шаг после sort() — сортировка относится к последнему шагу цепочки, а не к тому, после которого
+    // стоит; предупреждение (lwarn), один раз на пару
+    'api.sort_not_last': {
+        code: 'invalid_query',
+        ru: "sort('{field}') перед шагом {step} сортирует строки последнего шага ({step}), а не прежнего: ставьте sort() в конец цепочки",
+    },
+    // chain.ts, A9: withDeleted() не у последнего шага, а у последнего — нет; предупреждение (lwarn), один раз на пару:
+    // с 2.1 withDeleted() — модификатор своего шага
+    'api.with_deleted_step': {
+        code: 'invalid_query',
+        ru: 'withDeleted() у шага {step} относится к нему, а не к последнему шагу {last}: удалённые {last} — .{last}().withDeleted()',
+    },
+    // errors.ts, fromDbError: подстраховка — значение не того типа (SQLSTATE 22P02), которое не поймала проверка до
+    // запроса; text — текст сервера
+    'api.db_bad_value': {
+        code: 'invalid_query',
+        ru: 'база не приняла значение: оно не того типа, что поле или параметр запроса (ответ PostgreSQL: {text})',
+        hint: 'передавайте id строкой uuid, числа — числами, даты — строками ISO 8601; проверьте значения фильтра, курсора, опций и параметров db.sql и повторите запрос',
+    },
+    // errors.ts, ValidationError: первое нарушение в тексте ошибки — путь и сообщение; текст не для ошибки (lmsg)
+    'api.validation_issue': {
+        code: 'invalid_data',
+        ru: '{path} — {issue}',
+    },
+    // errors.ts, ValidationError: путь нарушения на верхнем уровне данных (пустой путь); текст не для ошибки (lmsg)
+    'api.validation_root': {
+        code: 'invalid_data',
+        ru: 'данные',
+    },
+    // errors.ts, ValidationError: число нарушений, если их больше одного; текст не для ошибки (lmsg)
+    'api.validation_more': {
+        code: 'invalid_data',
+        ru: ' (всего нарушений: {n}, все — err.issues)',
     },
     // index.ts: connect({ schema })
     'api.connect_schema': {
@@ -61,9 +129,11 @@ export const api = {
         ru: 'forUpdate() — только внутри db.begin(): вне явной транзакции блокировка снялась бы сразу',
     },
     // chain.ts, lockedRead: forUpdate() с другим терминалом, агрегатом, срезом, глаголом
+    // chain.ts, lockedRead: what — что мешает блокировке (терминал, asOf(), withDeleted(), deep(), глагол)
     'api.for_update_unsupported': {
         code: 'lock_unsupported',
-        ru: 'forUpdate() — с терминалами rows, first, ids, без агрегатов, asOf, versions, withDeleted, deep и глаголов',
+        ru: 'forUpdate() нельзя с {what}: блокировка — только у чтения rows(), first(), ids()',
+        hint: 'forUpdate() — в db.begin(), перед rows(), first() или ids(); без asOf(), versions(), withDeleted(), deep(), count(), paths(), агрегатов и глаголов. Правка — отдельной цепочкой после чтения: await tr.X(id).forUpdate().first(); await tr.X(id).update(…).rows()',
     },
     // chain.ts, lockedRead: строки видны, но политика правки не даёт их заблокировать; ids — через запятую (detail.ids — списком)
     'api.lock_denied': {
@@ -73,27 +143,27 @@ export const api = {
     // chain.ts, slotValue: значение .Роль.set(…), .add(…), .remove(…)
     'api.slot_value': {
         code: 'invalid_query',
-        ru: 'значение слота — id, список id, строка ответа или цепочка',
+        ru: 'значение шага роли (.Роль.set(), .add(), .remove()) — id, список id, строка ответа или цепочка',
     },
     // chain.ts: слот не сразу после create(), update() или upsert(); name — роль, как вызвана, op — set, unset, add, remove
     'api.slot_without_write': {
         code: 'invalid_query',
-        ru: 'слот .{name}.{op}() — после create(), update() или upsert(): db.Класс(…).update(…).{name}.{op}(…)',
+        ru: 'шаг роли .{name}.{op}() — после create(), update() или upsert(): db.Класс(…).update(…).{name}.{op}(…)',
     },
     // chain.ts: add() или remove() у одиночного конца
     'api.slot_single': {
         code: 'invalid_query',
-        ru: 'слот .{name}.{op}(): конец {role} одиночный — set() или unset()',
+        ru: 'шаг роли .{name}.{op}(): конец {role} одиночный — set() или unset()',
     },
     // chain.ts: unset() у обязательного конца
     'api.slot_required': {
         code: 'invalid_query',
-        ru: 'слот .{name}.unset(): конец {role} обязателен',
+        ru: 'шаг роли .{name}.unset(): конец {role} обязателен',
     },
     // chain.ts: set() или unset() одного конца дважды в одной записи
     'api.slot_twice': {
         code: 'invalid_query',
-        ru: 'слот {role} задан дважды в одной записи',
+        ru: 'конец {role} задан дважды в одной записи',
     },
     // chain.ts, withLast: deep(), exact(), alias(), tags(), owner() сразу после глагола; verb — глагол
     'api.step_mod_after_verb': {
@@ -118,7 +188,7 @@ export const api = {
     // chain.ts: set, unset, add, remove у цепочки, а не у слота роли; method — имя метода
     'api.slot_method': {
         code: 'invalid_query',
-        ru: '{method}() — метод слота: db.Класс(…).update(…).Роль.{method}(…)',
+        ru: '{method}() — метод шага роли после глагола: db.Класс(…).update(…).Роль.{method}(…)',
     },
     // chain.ts: cache({ ttl })
     'api.cache_ttl': {
@@ -152,6 +222,19 @@ export const api = {
         hint: 'повторить вызов: между запросами db.as() сессия сменила арендатора или кончилась',
     },
     // index.ts: db.begin() внутри db.begin()
+    // index.ts: db.begin(аргумент) — не объект опций (функция, строка, число); функцию begin() не вызывает; type — typeof
+    // аргумента (array — массив)
+    'api.begin_arg': {
+        code: 'invalid_query',
+        ru: 'db.begin() принимает только объект опций с полем reason или ничего; передано значение типа {type}. Функцию begin() не вызывает: транзакцию открывает begin(), закрывают commit() и rollback()',
+        hint: 'откройте транзакцию без функции и закройте её сами: const tr = await db.begin(); try { …запросы через tr…; await tr.commit() } catch (e) { await tr.rollback(); throw e }',
+    },
+    // index.ts: вызов цепочки или метода подключения после db.close() корня (и у db.as(), db.begin() этого подключения)
+    'api.closed': {
+        code: 'invalid_query',
+        ru: 'подключение закрыто (db.close()) — откройте новое connect()',
+        hint: 'db.close() — в конце работы процесса; цепочки, db.as() и db.begin() закрытого подключения не работают — для новой работы const db = await connect({ … })',
+    },
     'api.nested_begin': {
         code: 'invalid_query',
         ru: 'вложенных транзакций нет: db.begin() внутри db.begin()',
@@ -167,6 +250,12 @@ export const api = {
         ru: 'connect: нужен dsn или sql',
         hint: 'передать dsn — строку подключения — или sql — готовый пул postgres.js',
     },
+    // index.ts: connect({ apiKey | service | token }) передан, но пуст (null, '', не строка) — опция есть, а значения нет
+    'api.connect_empty_credential': {
+        code: 'invalid_data',
+        ru: 'connect: {name} передан, но пуст ({value}) — подключение без сессии не открывается',
+        hint: 'передать ключ сервиса или токен строкой (process.env.SERVICE_KEY не задана?) — либо убрать опцию, если сессия не нужна; ключ сервиса up() выдаёт один раз — храните его сами',
+    },
     // index.ts: connect({ admin }) — не строка и не пул
     'api.connect_admin_type': {
         code: 'invalid_data',
@@ -212,4 +301,17 @@ export const api = {
         code: 'invalid_data',
         ru: 'движок схемы {schema} ревизии {rev} новее библиотеки (она знает {known}) — обновите пакет letopis',
     },
+    // up.ts, createTenant(): первый аргумент — не пул postgres() (строка DSN, подключение connect(), объект без begin и
+    // unsafe); type — typeof значения или null
+    'api.create_tenant_admin': {
+        code: 'invalid_query',
+        ru: 'createTenant(admin, …): admin — пул postgres() с правами администратора, а не {type}',
+        hint: "const admin = postgres(dsnАдминистратора); await createTenant(admin, 'salon', { name }); await admin.end(). DSN-строку и подключение connect() letopis createTenant не принимает",
+    },
+    // chain.ts, versions(): у результата versions() вызвали метод цепочки (rows, first, sort…); method — его имя
+    'api.versions_terminal': {
+        code: 'invalid_query',
+        ru: 'versions() — терминал: отдаёт строки версий, у результата нет .{method}()',
+        hint: "const v = await db.Класс(id).versions(); модификаторы — до versions(): db.Класс(id).sort('at', 'desc').limit(10).versions()",
+    },
 };

package/dist/messages/boot.d.ts

@@ -64,6 +64,11 @@ export declare const boot: {
         ru: string;
         hint: string;
     };
+    'boot.login_grant_denied': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
     'boot.tenant_name_required': {
         code: "invalid_data";
         ru: string;

package/dist/messages/boot.js

@@ -3,7 +3,7 @@ const LOGIN = 'передать login: { user, password } — имя обычн
 /** Подсказка отказов user.roles в createTenant() и up({ tenant }). */
 const ROLES = "передать user.roles — список разных имён ролей членства, например ['staff'], или не передавать: по умолчанию ['owner']";
 /** Подсказка отказов createTenant() об удалённой строке. */
-const GONE = 'вернуть удалённое restore() (текст называет, кто это может) или выбрать другое имя или логин: id вычисляется из них';
+const GONE = 'вернуть удалённое restore({ expect }) — надгробие из withDeleted().rows() (текст называет, кто это может) или выбрать другое имя или логин: id вычисляется из них';
 export const boot = {
     // up.ts, substitute(): в тексте SQL (ядро, миграция, свой сид) маркер, которого установщик не знает
     'boot.unknown_marker': {
@@ -83,6 +83,13 @@ export const boot = {
         ru: 'up({ login }): роль {user} — привилегированная (суперпользователь, CREATEROLE, CREATEDB, REPLICATION, BYPASSRLS, роль-владелец или её член) или сама роль приложения: роль приложения — обычная роль входа, привилегированную up() не трогает',
         hint: 'выбрать для login другое имя — роль без этих атрибутов и без членства в роли владельца',
     },
+    // up.ts, ensureLogin (3.0.1): установщик не может выдать роль приложения (PostgreSQL 16+: нужен ADMIN OPTION, SQLSTATE
+    // 42501 «permission denied to grant role»); app — роль приложения, installer — роль установщика (current_user)
+    'boot.login_grant_denied': {
+        code: 'invalid_data',
+        ru: 'up({ login }): роль {installer} не может выдать роль {app} роли {user} — нужен ADMIN OPTION на роль {app} (grant {app} to {installer} with admin option) или суперпользователь',
+        hint: 'выполнить от суперпользователя grant <роль приложения> to <установщик> with admin option (имена — в тексте ошибки) и повторить up({ login }) — или ставить от суперпользователя',
+    },
     // up.ts, createTenant() и up({ tenant }): нет имени арендатора
     'boot.tenant_name_required': {
         code: 'invalid_data',
@@ -123,19 +130,19 @@ export const boot = {
     // up.ts, createTenant(): строки арендатора нет, а его история в журнале есть
     'boot.tenant_deleted': {
         code: 'invalid_data',
-        ru: 'createTenant: арендатор «{name}» ({id}) удалён, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.Account(id).restore() от имени системного администратора или выберите другое имя',
+        ru: 'createTenant: арендатор «{name}» ({id}) удалён, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.Account(id).restore({ expect: await db.Account(id).withDeleted().rows() }) от имени системного администратора или выберите другое имя',
         hint: GONE,
     },
     // up.ts, createTenant(): строки аккаунта пользователя нет, а его история в журнале есть
     'boot.tenant_user_deleted': {
         code: 'invalid_data',
-        ru: 'createTenant: аккаунт пользователя {login} ({id}) удалён, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.Account(id).restore() от имени системного администратора или выберите другой логин',
+        ru: 'createTenant: аккаунт пользователя {login} ({id}) удалён, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.Account(id).restore({ expect: await db.Account(id).withDeleted().rows() }) от имени системного администратора или выберите другой логин',
         hint: GONE,
     },
     // up.ts, createTenant(): строки членства нет, а его история в журнале есть
     'boot.tenant_member_deleted': {
         code: 'invalid_data',
-        ru: 'createTenant: членство {login} в арендаторе «{name}» ({id}) удалено, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.member(id).restore() в этом арендаторе или выберите другой логин',
+        ru: 'createTenant: членство {login} в арендаторе «{name}» ({id}) удалено, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.member(id).restore({ expect: await db.member(id).withDeleted().rows() }) в этом арендаторе или выберите другой логин',
         hint: GONE,
     },
     // up.ts, refuse1x(): схема letopis 1.x — ревизия из комментария схемы ниже первой ревизии 2.0 (FIRST_REVISION) или

package/dist/messages/codes.js

@@ -27,7 +27,7 @@ export const codes = {
     'codes.acl_denied': {
         code: 'acl_denied',
         ru: 'правила доступа запрещают это действие',
-        hint: 'добавить правило доступа (`Rule`) или выполнить действие от пользователя, которому оно разрешено; проверить заранее — `db.acl.checkData`, `db.acl.check`',
+        hint: 'выдать право `db.acl.grant` (правила — класс `rule`) или выполнить действие от пользователя, которому оно разрешено; проверить заранее — `db.acl.checkData`, `db.acl.check`',
     },
     'codes.id_mismatch': {
         code: 'id_mismatch',
@@ -72,7 +72,7 @@ export const codes = {
     'codes.not_deleted': {
         code: 'not_deleted',
         ru: '`restore` работает только для удалённых объектов',
-        hint: 'сначала `delete()`, потом `restore()`',
+        hint: 'сначала `delete({ confirm: true, expect })`, потом `restore({ expect })` с надгробиями из ответа `delete()` или `withDeleted().rows()`',
     },
     'codes.exists': {
         code: 'exists',
@@ -91,8 +91,8 @@ export const codes = {
     },
     'codes.conflict': {
         code: 'conflict',
-        ru: '`update` с `{ rev }`: строку уже изменили после того, как вы её прочли',
-        hint: 'перечитать строку и повторить правку с новым `rev`; для чисел — `inc` вместо записи итога',
+        ru: 'то, что вы видели, уже изменилось — ничего не записано: `update` с `{ rev }` (строку изменили после чтения, `write.rev_conflict`), `delete({ confirm: true, expect })` (предпросмотр изменился, `write.preview_changed`; в том числе цели уже удалены или не найдены — `detail.preview: []`), `restore({ expect })` (объект меняли после удаления, `write.restore_stale`)',
+        hint: 'перечитать и повторить с новыми данными: `update` — с новым `rev` (для чисел — `inc` вместо записи итога); `delete` — показать новый предпросмотр `err.detail.preview` и удалить с ним; `restore` — сообщить пользователю (вещь уже у другого) или `restore({ expect, partial: true })`',
     },
     'codes.rev_ambiguous': {
         code: 'rev_ambiguous',

package/dist/messages/index.d.ts

@@ -9,7 +9,7 @@
  * 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;
+ *      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), для кода базы —
@@ -56,6 +56,7 @@ 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';
@@ -67,9 +68,11 @@ 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 sqlCore & typeof sqlWrite & typeof sqlAccess & typeof sqlTime;
+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;
 /** Все записи каталога по ключу. */

package/dist/messages/index.js

@@ -9,7 +9,7 @@
  * 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;
+ *      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), для кода базы —
@@ -56,6 +56,7 @@ 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';
@@ -65,9 +66,11 @@ 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,
+    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). */