letopis 2.0.0 → 3.0.1

package/dist/types.d.ts

@@ -3,17 +3,22 @@
  */
 /**
  * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
- * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии 2.x `up()` обновляет только с
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии (того же поколения `v2`) `up()` обновляет только с
  * `upgrade: true`, а `connect()` о ней предупреждает.
  */
-export declare const DDL_REVISION = 8;
+export declare const DDL_REVISION = 11;
+/**
+ * Префикс версии в имени схемы `v<N>.<имя>`: `up({ schema: 'salon' })` и `connect({ schema: 'salon' })` дописывают его к
+ * имени без точки — `v2.salon`.
+ */
+export declare const SCHEMA_VERSION = "v2";
 /**
  * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
  * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
  */
 export declare const ACL_CLASS_NAMES: readonly string[];
 /**
- * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then`. После шага цепочки эти
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и шаги роли, а также `then`. После шага цепочки эти
  * имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
  */
 export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "restore", "alias", "tags", "owner", "forUpdate", "cache"];
@@ -46,14 +51,27 @@ export interface Row<D = Record<string, unknown>, L = Record<string, string | st
     /** Вид операции версии: create, update, delete, restore, … */
     op: string;
     reason?: string;
-    /** Надгробие: удалённая сущность (withDeleted) или версия удаления (versions). */
+    /** Надгробие: удалённый объект (withDeleted) или версия удаления (versions). */
     $deleted?: true;
-    /** Глубина узла при deep() (1 — прямой потомок); в превью удаления — уровень каскада (0 — цель). */
+    /** Глубина узла при deep() (1 — прямой потомок); в предпросмотре удаления — уровень каскада (0 — цель). */
     $depth?: number;
     /** Что сделал upsert. */
     $upsert?: 'created' | 'updated' | 'unchanged';
-    /** Превью удаления (delete() без confirm): удалится, снимется конец или помешает (restrict). */
-    $action?: 'delete' | 'unset' | 'restrict';
+    /**
+     * Превью удаления (delete() без confirm): удалится, снимется конец или помешает (restrict). В ответе
+     * `restore({ expect, partial: true })` — `skip`: цель не восстановлена, причина — `$why`. `hidden` — строка-сводка
+     * предпросмотра, а не объект: скрытые правами строки замыкания (что с ними будет — `$hidden`, сколько — `$count`).
+     */
+    $action?: 'delete' | 'unset' | 'restrict' | 'skip' | 'hidden';
+    /** Строка-сводка предпросмотра удаления (`$action: 'hidden'`): что будет со скрытыми правами строками. */
+    $hidden?: 'delete' | 'unset' | 'restrict';
+    /** Строка-сводка предпросмотра удаления (`$action: 'hidden'`): число скрытых правами строк. */
+    $count?: number;
+    /**
+     * Почему цель `restore({ expect, partial: true })` не восстановлена: `restored` — её уже восстановили, `reissued` — id
+     * занял новый объект с тем же ключом, `changed` — после показанного удаления её меняли (удалили снова и т. п.).
+     */
+    $why?: 'restored' | 'reissued' | 'changed';
 }
 /** Путь paths(): узел на каждый шаг цепочки. */
 export type Path = Record<string, Row>;
@@ -102,7 +120,10 @@ export interface ChainMods {
     /** Срез «как было на момент T» (ISO). */
     asOf?: string;
     after?: Cursor;
-    /** Последний шаг включает удалённые. */
+    /**
+     * Не действует: с 2.1 `withDeleted()` — модификатор своего шага (флаг шага цепочки), а не всей выборки. Поле оставлено,
+     * чтобы тип не менялся.
+     */
     withDeleted?: boolean;
     /** Чтение с блокировкой строк последнего шага (только в db.begin()). */
     forUpdate?: boolean;
@@ -121,3 +142,65 @@ export interface QueryEvent {
     /** ms > slowMs. */
     slow: boolean;
 }
+/** Порог логирования: события этого уровня и выше; `'off'` — ничего. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';
+/** Событие логирования (каталог событий — `LOG_EVENTS`). Поля без значения в событии отсутствуют. */
+export interface LogEvent {
+    /** Время события, ISO 8601 (UTC). */
+    ts: string;
+    level: Exclude<LogLevel, 'off'>;
+    /** Имя события: connect, read, write, delete, error, sql и др. */
+    event: string;
+    /** Операция: терминал или глагол цепочки, метод db, auth, acl, инструмент MCP. */
+    op?: string;
+    /** Длительность операции, мс (с точностью до 0,1). */
+    ms?: number;
+    /** Арендатор сессии подключения (db, db.as(), db.begin()). */
+    tenant?: string;
+    /** Аккаунт подключения: аккаунт сессии или тот, от чьего имени действует db.as(). */
+    account?: string;
+    /** Метка транзакции db.begin() или db.transaction(). */
+    tx?: string;
+    /** Цепочка в читаемом виде: `Shop({"name":"A"}).Product.limit(10).rows()`; данные записи — только именами полей. */
+    chain?: string;
+    /** Строк в ответе или затронуто. */
+    rows?: number;
+    /** Код ошибки letopis (или SQLSTATE ошибки базы) — у error. */
+    code?: string;
+    /** Ключ каталога сообщений — у error и warning. */
+    key?: string;
+    /** Текст ошибки или предупреждения. */
+    msg?: string;
+    /** Подробности события; секреты замаскированы. */
+    detail?: Record<string, unknown>;
+    /** Причина ошибки (исходная ошибка базы и т. п.) — у error. */
+    cause?: {
+        name?: string;
+        message: string;
+        code?: string;
+    };
+}
+/** Логгер-функция. */
+export type LogFn = (event: LogEvent) => unknown;
+/** Логгер-объект: pino, console и подобные — вызов `logger[уровень](событие, событие.event)`. */
+export interface LogObject {
+    debug?(event: LogEvent, msg: string): unknown;
+    info?(event: LogEvent, msg: string): unknown;
+    warn?(event: LogEvent, msg: string): unknown;
+    error?(event: LogEvent, msg: string): unknown;
+    log?(event: LogEvent, msg: string): unknown;
+}
+/** Логгер: функция или объект с методами уровней. */
+export type Logger = LogFn | LogObject;
+/** Опции логирования connect() и up(). */
+export interface LogOptions {
+    /**
+     * Логгер: функция `(событие) => void` или объект с методами `debug`, `info`, `warn`, `error` (pino, console). Без него
+     * и с переменной окружения `LETOPIS_LOG=<уровень>` события идут JSON-строками в stderr.
+     */
+    log?: Logger;
+    /** Порог: `'debug' | 'info' | 'warn' | 'error' | 'off'`, по умолчанию `'info'` (или уровень из `LETOPIS_LOG`). */
+    logLevel?: LogLevel;
+    /** Ещё имена полей, значения которых маскируются в событиях (пароли, токены и ключи маскируются всегда). */
+    redact?: readonly string[];
+}

package/dist/types.js

@@ -3,10 +3,15 @@
  */
 /**
  * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
- * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии 2.x `up()` обновляет только с
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии (того же поколения `v2`) `up()` обновляет только с
  * `upgrade: true`, а `connect()` о ней предупреждает.
  */
-export const DDL_REVISION = 8;
+export const DDL_REVISION = 11;
+/**
+ * Префикс версии в имени схемы `v<N>.<имя>`: `up({ schema: 'salon' })` и `connect({ schema: 'salon' })` дописывают его к
+ * имени без точки — `v2.salon`.
+ */
+export const SCHEMA_VERSION = 'v2';
 /**
  * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
  * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
@@ -16,7 +21,7 @@ export const ACL_CLASS_NAMES = ['rule', 'Resource', 'member', 'Account', 'Class'
 // Методы цепочки — единственный источник зарезервированных имён (план, §2.14, этап 3, п. 10)
 // ---------------------------------------------------------------------------
 /**
- * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then`. После шага цепочки эти
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и шаги роли, а также `then`. После шага цепочки эти
  * имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
  */
 export const CHAIN_METHODS = [

package/dist/up.d.ts

@@ -1,8 +1,9 @@
 import postgres from 'postgres';
+import { SCHEMA_VERSION, type LogOptions } from './types.js';
 import { type PgliteOptions, type PgliteServer } from './pglite.js';
 import { type SignalMode } from './signals.js';
 export declare const SYSTEM_ID = "2eba6d0a-1edd-4bb6-a85a-a703dab49035";
-export declare const SCHEMA_VERSION = "v2";
+export { SCHEMA_VERSION };
 /**
  * Первая ревизия движка 2.0 (план 2.0, редакция 2): схема ниже неё — letopis 1.x или схема без штампа ревизии. Её
  * `up()` не обновляет, а `connect()` к ней не подключается: 2.0 ставится только заново (`up({ fresh: true })`), данные
@@ -84,7 +85,7 @@ export declare function install(sql: postgres.Sql, opts: InstallOptions): Promis
 }>;
 /** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */
 export declare function migrationFiles(dir: string, from: number): Promise<string[]>;
-export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'migrateFrom'> {
+export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'migrateFrom'>, LogOptions {
     /** Администраторская строка подключения (роль-установщик). */
     dsn?: string;
     /** Готовый пул postgres.js вместо dsn (база уже существует). */
@@ -120,9 +121,11 @@ export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'mig
      */
     login?: LoginOptions;
 }
-/** Роль приложения up({ login }). */
+/** Роль приложения up({ login }): `{ user, password }` (поле — `user`, не `name`). */
 export interface LoginOptions {
+    /** Имя роли PostgreSQL для приложения, например `'shop_app'`: нет — up() её создаёт, есть — меняет пароль. */
     user: string;
+    /** Пароль роли: войдёт в строку подключения `r.login.dsn`. */
     password: string;
 }
 export interface UpResult extends InstallResult {
@@ -199,7 +202,8 @@ export interface TenantOptions {
          * APIKEY, KEYSECRET, OTP, TOTP, KEY, LOCK); иначе invalid_data.
          */
         kind?: string;
-        ttl?: string;
+        /** Срок сессии: как ttl у auth (число секунд, '15m', интервал PostgreSQL '15 minutes'); по умолчанию 7 суток. */
+        ttl?: string | number;
         /** Роли членства (по умолчанию ['owner']); роли уже существующего членства повтор не меняет. */
         roles?: string[];
     };
@@ -221,4 +225,3 @@ export interface TenantResult {
  * пользователь или членство были удалены, повтор их не воскрешает — отказ `invalid_data`.
  */
 export declare function createTenant(sql: postgres.Sql, schema: string, opts: TenantOptions, owner?: string): Promise<TenantResult>;
-export {};

package/dist/up.js

@@ -16,15 +16,16 @@ import { fileURLToPath } from 'node:url';
 import { join, resolve } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
 import postgres from 'postgres';
-import { DDL_REVISION, RESERVED_CLASS_NAMES } from './types.js';
+import { DDL_REVISION, RESERVED_CLASS_NAMES, SCHEMA_VERSION } from './types.js';
+import { makeLog, maskDsn, traceSql, traced } from './log.js';
 import { startPglite } from './pglite.js';
-import { hashPassword } from './auth.js';
+import { hashPassword, ttlGuard, ttlOf } from './auth.js';
 import { checkOptions, lerr, lmsg } from './errors.js';
 import { sqlCatalog } from './messages/index.js';
 import { v5Id } from './uuid.js';
 import { SIGNAL_MODES } from './signals.js';
 export const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
-export const SCHEMA_VERSION = 'v2';
+export { SCHEMA_VERSION };
 /**
  * Первая ревизия движка 2.0 (план 2.0, редакция 2): схема ниже неё — letopis 1.x или схема без штампа ревизии. Её
  * `up()` не обновляет, а `connect()` к ней не подключается: 2.0 ставится только заново (`up({ fresh: true })`), данные
@@ -321,7 +322,7 @@ export async function migrationFiles(dir, from) {
 const UP_OPTIONS = {
     dsn: true, sql: true, schema: true, fresh: true, upgrade: true, quiet: true, waitTimeoutMs: true, pglite: true, tenant: true,
     login: true, owner: true, app: true, seeds: true, migrationsDir: true, serviceKey: true,
-    signals: true,
+    signals: true, log: true, logLevel: true, redact: true,
 };
 /** Проба сервера: ok | нет сервера | нет базы | запускается | роковая ошибка (неверный пароль). */
 export async function pgPing(dsn) {
@@ -397,7 +398,30 @@ export async function schemaRevision(sql, schema) {
  */
 export async function up(opts) {
     checkOptions('up', opts, UP_OPTIONS);
-    const log = opts.quiet ? () => { } : (m) => console.log(`letopis.up: ${m}`);
+    // логирование 3.0: события up, migrate, up.step, tenant.create, warning, error, sql — в логгер opts.log (или LETOPIS_LOG)
+    const lg = makeLog({ log: opts.log, logLevel: opts.logLevel, redact: opts.redact });
+    return traced(lg, 'up', { op: 'up' }, () => upCore(opts, lg), (r) => ({
+        detail: {
+            // schema — фактическое имя (имя без точки получает префикс версии: 'salon' → 'v2.salon'); requested — как передано
+            schema: r.schema, ...(opts.schema !== r.schema ? { requested: opts.schema } : {}),
+            created: r.created, upgraded: r.upgraded, revision: r.revision, signals: r.signals,
+            ...(opts.dsn ? { dsn: maskDsn(opts.dsn) } : {}), ...(r.pglite ? { pglite: true } : {}), ...(opts.fresh ? { fresh: true } : {}),
+            analyzed: r.analyzed.length, warnings: r.warnings.length, ...(r.serviceKey ? { issuedKey: true } : {}),
+            ...(r.tenant ? { tenant: r.tenant.tenant } : {}), ...(r.login ? { login: r.login.user } : {}),
+        },
+    }));
+}
+/** up() после проверки опций; lg — логгер. */
+async function upCore(opts, lg) {
+    // сообщения шагов: при заданном логгере — событие up.step вместо console.log
+    const log = opts.quiet ? () => { } : lg.active ? (m) => lg.emit('up.step', { op: 'up', msg: m }) : (m) => console.log(`letopis.up: ${m}`);
+    /** Предупреждение: в логгер (warning), иначе console.warn без quiet. */
+    const warn = (w) => {
+        if (lg.active)
+            lg.warning(undefined, w);
+        else if (!opts.quiet)
+            console.warn(`letopis.up: ${w}`);
+    };
     const schema = opts.schema.includes('.') ? opts.schema : `${SCHEMA_VERSION}.${opts.schema}`;
     if (!SCHEMA_NAME.test(schema))
         throw lerr('boot.up_schema_name', { schema: opts.schema });
@@ -432,13 +456,14 @@ export async function up(opts) {
         }
         sql = postgres(opts.dsn, { max: 1, onnotice: () => { } });
     }
+    // порог debug — событие sql на каждый запрос установки (тексты create/alter role — без пароля)
+    sql = traceSql(sql, lg);
     try {
         const [srv] = await sql `select current_setting('server_version_num')::int as v, pg_encoding_to_char(encoding) as enc
       from pg_database where datname = current_database()`;
         const warnings = checkServer(srv.v, srv.enc);
-        if (!opts.quiet)
-            for (const w of warnings)
-                console.warn(`letopis.up: ${w}`);
+        for (const w of warnings)
+            warn(w);
         // ревизия до блокировки схемы — для ранних отказов; что накатывать, install() решает по ревизии под блокировкой
         const before = opts.fresh ? null : await schemaRevision(sql, schema);
         if (before !== null && before > DDL_REVISION) {
@@ -451,10 +476,14 @@ export async function up(opts) {
         if (before !== null && before < DDL_REVISION && !opts.upgrade) {
             throw new Error(`letopis.up: ${lmsg('boot.schema_older', { schema, rev: before, want: DDL_REVISION })}`);
         }
-        const { dsn: _d, sql: _s, schema: _sc, fresh: _f, upgrade: _u, quiet: _q, waitTimeoutMs: _w, pglite: _p, login: _l, ...rest } = opts;
+        const { dsn: _d, sql: _s, schema: _sc, fresh: _f, upgrade: _u, quiet: _q, waitTimeoutMs: _w, pglite: _p, login: _l, log: _lg, logLevel: _ll, redact: _rd, ...rest } = opts;
+        const t0 = performance.now();
         const { found, ...res } = await install(sql, {
             ...rest, schema, ...(opts.fresh ? { fresh: true } : {}), ...(before !== null && before < DDL_REVISION ? { migrateFrom: before } : {}),
         });
+        if (found !== null && found < DDL_REVISION && lg.wants('migrate')) {
+            lg.emit('migrate', { op: 'up', ms: performance.now() - t0, rows: res.migrations.length, detail: { schema, from: found, to: DDL_REVISION, files: res.migrations } });
+        }
         if (opts.fresh)
             log(lmsg('boot.log_fresh', { schema }));
         // ANALYZE — только там, где статистики ещё нет: на повторном накате это самая дорогая часть. От роли владельца, как у
@@ -476,8 +505,7 @@ export async function up(opts) {
         if (left.length) {
             const w = lmsg('boot.analyze_skipped', { owner: res.owner, tables: left.map((t) => `${schema}.${t}`).join(', ') });
             warnings.push(w);
-            if (!opts.quiet)
-                console.warn(`letopis.up: ${w}`);
+            warn(w);
         }
         // хабы с зарезервированными именами, заведённые мимо проверки базы (план 2.0, этап 4, п. 2; 7.10 №3): накат их
         // оставляет и называет, новых таких база не пишет. Строки Class — от роли владельца, как ANALYZE: у установщика без
@@ -491,12 +519,13 @@ export async function up(opts) {
         if (reserved.length) {
             const w = lmsg('boot.reserved_hubs', { hubs: reserved.map((h) => `${h.name} (${h.tenant})`).join(', ') });
             warnings.push(w);
-            if (!opts.quiet)
-                console.warn(`letopis.up: ${w}`);
+            warn(w);
         }
         const revision = (await schemaRevision(sql, schema)) ?? 0;
         log(lmsg(found === null ? 'boot.log_installed' : found < DDL_REVISION ? 'boot.log_upgraded' : 'boot.log_reapplied', { schema, revision, from: found }));
-        const tenant = opts.tenant ? await createTenant(sql, schema, opts.tenant, opts.owner) : undefined;
+        const tenant = opts.tenant
+            ? await traced(lg, 'tenant.create', { op: 'createTenant' }, () => createTenant(sql, schema, opts.tenant, opts.owner), (t) => ({ tenant: t.tenant, ...(t.user ? { account: t.user } : {}), detail: { name: opts.tenant.name, created: t.created, user: Boolean(t.user) } }))
+            : undefined;
         const login = opts.login ? await ensureLogin(sql, opts.login, res.owner, res.app, opts.dsn ?? lite?.dsn) : undefined;
         if (login)
             log(lmsg(login.created ? 'boot.log_login_created' : 'boot.log_login_updated', { user: login.user }));
@@ -543,8 +572,15 @@ async function ensureLogin(sql, login, owner, app, dsn) {
         const verb = r ? 'alter role %I login password %L' : 'create role %I login password %L';
         const [{ q }] = await tx `select format(${verb}::text, ${login.user}::text, ${login.password}::text) as q`;
         await tx.unsafe(q);
-        const [{ g }] = await tx `select format('grant %I to %I', ${app}::text, ${login.user}::text) as g`;
-        await tx.unsafe(g);
+        const [{ g, installer }] = await tx `select format('grant %I to %I', ${app}::text, ${login.user}::text) as g, current_user::text as installer`;
+        // PostgreSQL 16+: выдать роль может только тот, у кого на неё ADMIN OPTION (или суперпользователь) — понятный отказ
+        // вместо сырого 42501 «permission denied to grant role» (3.0.1)
+        await tx.unsafe(g).catch((e) => {
+            if (e?.code === '42501') {
+                throw lerr('boot.login_grant_denied', { installer, app, user: login.user }, { cause: e });
+            }
+            throw e;
+        });
         return !r;
     });
     let url;
@@ -597,13 +633,25 @@ function checkTenant(opts) {
  * пользователь или членство были удалены, повтор их не воскрешает — отказ `invalid_data`.
  */
 export async function createTenant(sql, schema, opts, owner = 'letopis_owner') {
+    // admin — пул postgres(): строка DSN, подключение connect() letopis или другой объект упали бы голым TypeError на
+    // sql.begin (3.0)
+    const pool = sql;
+    if (typeof pool !== 'function' || typeof pool.begin !== 'function' || typeof pool.unsafe !== 'function') {
+        throw lerr('api.create_tenant_admin', { type: pool === null ? 'null' : typeof pool });
+    }
+    // имя схемы — как у connect() и up(): без точки — с префиксом версии (v2.salon)
+    if (typeof schema === 'string' && !schema.includes('.'))
+        schema = `${SCHEMA_VERSION}.${schema}`;
     const roles = checkTenant(opts);
     const S = quoteIdent(schema);
     const tenant = v5Id(SYSTEM_ID, 'Account', [`tenant:${opts.name}`]);
     const u = opts.user;
-    const user = u ? v5Id(SYSTEM_ID, 'Account', [`user:${u.login}`]) : null;
+    // логин без крайних пробелов, как у auth.setPassword() и verifyPassword() (план 2.1, A12)
+    const login = u ? (typeof u.login === 'string' ? u.login.trim() : u.login) : '';
+    const user = u ? v5Id(SYSTEM_ID, 'Account', [`user:${login}`]) : null;
+    const ttl = u ? ttlOf(u.ttl, 'createTenant') : null;
     const hash = u ? await hashPassword(u.password) : null;
-    return sql.begin(async (tx) => {
+    return ttlGuard(sql.begin(async (tx) => {
         // под блокировкой схемы, как накат: up({ tenant }) нескольких экземпляров сервиса разом заводит арендатора один
         // раз, остальные находят его по имени (без неё оба вставили бы ту же строку и один упал бы на ключе)
         await lockSchema(tx, schema);
@@ -624,20 +672,20 @@ export async function createTenant(sql, schema, opts, owner = 'letopis_owner') {
         }
         let token = null;
         if (u && user) {
-            if (!(await exists(user, 'Account', 'boot.tenant_user_deleted', { login: u.login }))) {
+            if (!(await exists(user, 'Account', 'boot.tenant_user_deleted', { login }))) {
                 await tx.unsafe(`select ${S}.sys_create($1::uuid, 'Account', $2::uuid, '{}', $3::jsonb)`, [user, SYSTEM_ID, { name: u.name, categories: ['User'], enabled: true }]);
             }
             const member = (await tx.unsafe(`select ${S}.v5_id($1::uuid, 'member', array[$2::text, $1::text]) as id`, [tenant, user]))[0].id;
             // существующее членство не трогаем: повтор с другими ролями их не меняет (их правят правкой member)
-            if (!(await exists(member, 'member', 'boot.tenant_member_deleted', { login: u.login, name: opts.name }))) {
+            if (!(await exists(member, 'member', 'boot.tenant_member_deleted', { login, name: opts.name }))) {
                 await tx.unsafe(`select ${S}.sys_create($1::uuid, 'member', $2::uuid, $3::jsonb, $4::jsonb)`, [member, tenant, { User: user, Tenant: tenant }, { roles }]);
             }
             const kind = u.kind ?? 'PASSWORD';
             await tx.unsafe(`insert into ${S}.secret (account, kind, ident, material, meta)
         select $1::uuid, $2, $3, convert_to($4, 'UTF8'), '{"confirmed": true}'::jsonb
-        where not exists (select 1 from ${S}.secret where kind = $2 and casefold(ident) collate pg_unicode_fast = casefold($3) collate pg_unicode_fast and deleted_at is null)`, [user, kind, u.login, hash]);
-            token = (await tx.unsafe(`select ${S}.new_session($1::uuid, $2::interval, $3::jsonb) as t`, [user, u.ttl ?? '7 days', { tenant }]))[0].t;
+        where not exists (select 1 from ${S}.secret where kind = $2 and casefold(ident) collate pg_unicode_fast = casefold($3) collate pg_unicode_fast and deleted_at is null)`, [user, kind, login, hash]);
+            token = (await tx.unsafe(`select ${S}.new_session($1::uuid, $2::interval, $3::jsonb) as t`, [user, ttl ?? '7 days', { tenant }]))[0].t;
         }
         return { tenant, user, token, created };
-    });
+    }), u?.ttl, 'createTenant');
 }

package/dist/uuid.d.ts

@@ -1,3 +1,11 @@
+/** uuid в каноническом виде 8-4-4-4-12 (регистр любой) — общий для построителя, загрузчика и MCP. */
+export declare const UUID_RE: RegExp;
+/**
+ * Любой вид uuid, который принимает приведение PostgreSQL `::uuid`: 32 шестнадцатеричные цифры, дефис — после любой
+ * группы из четырёх (или без дефисов), весь в фигурных скобках или без них. Фильтр с таким id работал и до проверки,
+ * поэтому проверка до запроса (sql.ts, compileFilter) отказывает только тому, что отклонила бы база.
+ */
+export declare const PG_UUID_RE: RegExp;
 /** RFC 4122 v5: sha1(пространство + имя); одно имя в одном пространстве — один id. */
 export declare function uuidv5(name: string, ns: string): string;
 /** Имя v5: JSON-массив из имени класса и значений ключа — как `jsonb_build_array(…)::text` в базе. */

package/dist/uuid.js

@@ -7,7 +7,15 @@
  */
 import { hash } from 'node:crypto';
 import { lerr } from './errors.js';
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** uuid в каноническом виде 8-4-4-4-12 (регистр любой) — общий для построителя, загрузчика и MCP. */
+export const UUID_RE = /^[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;
+/**
+ * Любой вид uuid, который принимает приведение PostgreSQL `::uuid`: 32 шестнадцатеричные цифры, дефис — после любой
+ * группы из четырёх (или без дефисов), весь в фигурных скобках или без них. Фильтр с таким id работал и до проверки,
+ * поэтому проверка до запроса (sql.ts, compileFilter) отказывает только тому, что отклонила бы база.
+ */
+export const PG_UUID_RE = /^(?:[0-9a-f]{4}(?:-?[0-9a-f]{4}){7}|\{[0-9a-f]{4}(?:-?[0-9a-f]{4}){7}\})$/i;
 // байты пространств имён (арендаторов): в загрузке их единицы, а проверка и разбор шли на каждый id
 const NS = new Map();
 function nsBytes(ns) {

package/dist/validate.js

@@ -104,6 +104,11 @@ const prop = (sel, k) => (root) => sel(root).flatMap((n) => (isObj(n) && Object.
 const items = (sel) => (root) => sel(root).flatMap((n) => (Array.isArray(n) ? n : []));
 const others = (sel, known) => (root) => sel(root).flatMap((n) => (isObj(n) ? Object.keys(n).filter((k) => !known.includes(k)).map((k) => n[k]) : []));
 const keys = (sel) => (root) => sel(root).flatMap((n) => (isObj(n) ? Object.keys(n) : []));
+/** Допустимые значения перечисления для сообщения нарушения — как у базы (validate_data): JSON через запятую, до 20. */
+function enumValues(values) {
+    const shown = values.slice(0, 20).map((v) => JSON.stringify(v)).join(', ');
+    return values.length > 20 ? `${shown}, …` : shown;
+}
 /** Описание не компилируется (`invalid_class`): ключ каталога и параметры; путь узла — параметр node. */
 function fail(path, key, params) {
     throw lerr(key, { ...params, node: JSON.stringify(path) });
@@ -127,13 +132,15 @@ function compileNode(s, sel, path, inAny, out) {
     if (sch.enum !== undefined || sch.const !== undefined) {
         const keyword = sch.enum !== undefined ? 'enum' : 'const';
         const values = (sch.enum ?? [sch.const]);
+        // сообщение называет допустимые значения (план 2.1, A8)
+        const msg = lmsg('model.issue_enum', { values: enumValues(values) });
         if (values.some((v) => typeof v === 'object' && v !== null)) {
             if (inAny)
                 fail(path, 'model.validator_enum_objects_in_any_of');
-            out.push({ path, keyword, select: sel, test: () => true, extra: (v) => (values.some((x) => jsonEqual(x, v)) ? null : lmsg('model.issue_enum')) });
+            out.push({ path, keyword, select: sel, test: () => true, extra: (v) => (values.some((x) => jsonEqual(x, v)) ? null : msg) });
         }
         else {
-            out.push({ path, keyword, select: sel, test: (v) => values.some((x) => typeOf(x) === typeOf(v) && jsonEqual(x, v)) });
+            out.push({ path, keyword, select: sel, test: (v) => values.some((x) => typeOf(x) === typeOf(v) && jsonEqual(x, v)), explain: () => msg });
         }
     }
     const num = (f, b) => (v) => typeof v !== 'number' || f(v, b);
@@ -177,8 +184,13 @@ function compileNode(s, sel, path, inAny, out) {
         const min = sch.minLength ?? 0;
         const max = sch.maxLength ?? Infinity;
         out.push({ path, keyword: sch.minLength !== undefined ? 'minLength' : 'maxLength', select: sel, test: () => true,
-            extra: (v) => { if (typeof v !== 'string')
-                return null; const n = [...v].length; return n < min || n > max ? lmsg('model.issue_string_length') : null; } });
+            // текст называет границу (второй раунд 2.1, A6), как у базы (30-validate.sql, validate_data)
+            extra: (v) => {
+                if (typeof v !== 'string')
+                    return null;
+                const n = [...v].length;
+                return n < min ? lmsg('model.issue_string_too_short', { limit: min }) : n > max ? lmsg('model.issue_string_too_long', { limit: max }) : null;
+            } });
     }
     if (sch.minItems !== undefined)
         out.push({ path, keyword: 'minItems', select: sel, test: (v) => !Array.isArray(v) || v.length >= sch.minItems });
@@ -211,7 +223,9 @@ function compileNode(s, sel, path, inAny, out) {
             compileNode(v, prop(sel, k), [...path, k], inAny, out);
     }
     if (sch.additionalProperties === false) {
-        out.push({ path, keyword: 'additionalProperties', select: sel, test: (v) => !isObj(v) || Object.keys(v).every((k) => known.includes(k)) });
+        // сообщение называет лишние ключи (план 2.1, A8)
+        out.push({ path, keyword: 'additionalProperties', select: sel, test: (v) => !isObj(v) || Object.keys(v).every((k) => known.includes(k)),
+            explain: (v) => lmsg('model.issue_additional', { keys: Object.keys(v).filter((k) => !known.includes(k)).slice(0, 20).join(', ') }) });
     }
     else if (isObj(sch.additionalProperties)) {
         compileNode(sch.additionalProperties, others(sel, known), [...path, '*'], inAny, out);
@@ -258,8 +272,11 @@ export function compileValidator(schema) {
                         issues.push({ path: r.path, keyword: r.keyword, message: msg });
                 }
             }
-            else if (!nodes.every((n) => r.test(n))) {
-                issues.push({ path: r.path, keyword: r.keyword, message: lmsg('model.issue_rule', { keyword: r.keyword }) });
+            else {
+                const at = nodes.findIndex((n) => !r.test(n));
+                if (at >= 0) {
+                    issues.push({ path: r.path, keyword: r.keyword, message: r.explain ? r.explain(nodes[at]) : lmsg('model.issue_rule', { keyword: r.keyword }) });
+                }
             }
         }
         return issues;

package/dist/watch.d.ts

@@ -1,6 +1,7 @@
 import type { Executor } from './tx.js';
 import type { Row } from './types.js';
 import type { Signal } from './signals.js';
+import type { Log } from './log.js';
 export interface WatchOptions {
     /** Откуда: курсор (sub.cursor или курсор события), 'now' (по умолчанию — изменения после подписки) или 'start' (весь журнал). */
     from?: string;
@@ -39,6 +40,8 @@ export interface WatchCtx {
     tenant?: () => string | null;
     /** Подписка закрылась: подключение перестаёт её учитывать (план 2.0, 7.4 №8). */
     onClose?: (s: Subscription) => void;
+    /** Логгер фасада (lib/src/log.ts): watch.start, watch.fetch, watch.stop, error. */
+    log?: Log;
 }
 /**
  * Будит ли сигнал подписку: свои классы (watched; null — все) и свой арендатор (mine — токен; null —
@@ -67,6 +70,8 @@ export declare class Subscription implements AsyncIterable<WatchEvent> {
     private start;
     /** Вызовы next() — по очереди: параллельные получают разные события (доработки после точки Б). */
     private queue;
+    /** Выдано событий — для watch.stop. */
+    private delivered;
     constructor(ctx: WatchCtx, opts: WatchOptions);
     /** Курсор подписки: позиция после последнего выданного события (или начальная точка) — с неё продолжают после перезапуска. */
     get cursor(): string | null;

package/dist/watch.js

@@ -66,6 +66,8 @@ export class Subscription {
     start = null;
     /** Вызовы next() — по очереди: параллельные получают разные события (доработки после точки Б). */
     queue = Promise.resolve();
+    /** Выдано событий — для watch.stop. */
+    delivered = 0;
     constructor(ctx, opts) {
         this.ctx = ctx;
         this.opts = opts;
@@ -95,6 +97,10 @@ export class Subscription {
             this.wake?.();
         }, this.pollMs);
         this.timer.unref?.();
+        if (ctx.log?.wants('watch.start')) {
+            ctx.log.emit('watch.start', { op: 'watch', detail: { from: opts.from ?? 'now', classes: ctx.classes, batch: this.batch,
+                    pollMs: this.pollMs, signals: Boolean(ctx.onSignal) } });
+        }
     }
     /** Курсор подписки: позиция после последнего выданного события (или начальная точка) — с неё продолжают после перезапуска. */
     get cursor() {
@@ -128,6 +134,8 @@ export class Subscription {
         // пока события пачки не выданы, курсор подписки — позиция до пачки
         if (rows.length)
             this.given = encode(p);
+        if (rows.length && this.ctx.log?.wants('watch.fetch'))
+            this.ctx.log.emit('watch.fetch', { op: 'watch', rows: rows.length });
         for (const r of rows) {
             const row = toRow(r.row);
             const snap = keepSnap(p.snap, r.tx);
@@ -153,6 +161,7 @@ export class Subscription {
             if (this.buf.length) {
                 const ev = this.buf.shift();
                 this.given = ev.cursor;
+                this.delivered++;
                 return { value: ev, done: false };
             }
             if (this.closed)
@@ -167,6 +176,7 @@ export class Subscription {
                 }
                 catch (e) {
                     this.failure = e;
+                    this.ctx.log?.error(e, { op: 'watch' });
                     this.close();
                     throw e;
                 }
@@ -209,6 +219,9 @@ export class Subscription {
         if (this.closed)
             return;
         this.closed = true;
+        if (this.ctx.log?.wants('watch.stop')) {
+            this.ctx.log.emit('watch.stop', { op: 'watch', rows: this.delivered, detail: { cursor: this.cursor, ...(this.failure ? { failed: true } : {}) } });
+        }
         this.off?.();
         this.ctx.onClose?.(this);
         if (this.timer)