letopis 2.0.0 → 3.0.0

package/dist/tx.js

@@ -1,4 +1,5 @@
 import { LetopisError, fromDbError, lerr, lmsg } from './errors.js';
+import { NOLOG } from './log.js';
 /** Транзиентные ошибки PG, которые снимает повтор: взаимная блокировка, сериализация. */
 export function isTransient(e) {
     const code = e.code;
@@ -56,15 +57,17 @@ export class Notifier {
     channel;
     intervalMs;
     onError;
+    log;
     queue = new Set();
     timer = null;
     stopped = false;
     flushing = Promise.resolve();
-    constructor(sql, channel, intervalMs, onError = () => { }) {
+    constructor(sql, channel, intervalMs, onError = () => { }, log = NOLOG) {
         this.sql = sql;
         this.channel = channel;
         this.intervalMs = intervalMs;
         this.onError = onError;
+        this.log = log;
     }
     /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed) {
@@ -89,7 +92,10 @@ export class Notifier {
             return this.flushing;
         const payloads = [...this.queue];
         this.queue.clear();
-        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${payloads}::text[]) as c`.then(() => undefined, (e) => {
+        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${payloads}::text[]) as c`.then(() => {
+            if (this.log.wants('signal.send'))
+                this.log.emit('signal.send', { rows: payloads.length });
+        }, (e) => {
             // не отправлено (обрыв связи, отказ базы) — обратно в очередь: уйдёт следующим интервалом
             // (в 1.0.1 такие сигналы терялись, и кэш других процессов устаревал до срока)
             for (const c of payloads)
@@ -204,6 +210,11 @@ export async function runTx(ctx, fn, opts = {}) {
             if (bodyDone && !opts.read && dead)
                 throw commitUnknown(e);
             if (attempt <= retries && (isTransient(e) || isLogConflict(e))) {
+                const log = ctx.log ?? NOLOG;
+                if (log.wants('tx.retry')) {
+                    log.emit('tx.retry', { detail: { attempt, of: retries, sqlstate: e.code,
+                            ...(isLogConflict(e) ? { conflict: 'log_id_rev' } : {}) } });
+                }
                 await retryDelay(attempt);
                 continue;
             }
@@ -243,10 +254,15 @@ export class ExplicitTx {
     failure = null;
     /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
     raw = false;
+    /** Время открытия — для ms у tx.commit и tx.rollback. */
+    t0 = performance.now();
     constructor(ctx, conn) {
         this.ctx = ctx;
         this.conn = conn;
     }
+    get log() {
+        return this.ctx.log ?? NOLOG;
+    }
     static async open(ctx, renewed = false) {
         if (!renewed && ctx.before)
             await ctx.before(ctx);
@@ -267,6 +283,9 @@ export class ExplicitTx {
                 return ExplicitTx.open(ctx, true);
             throw le;
         }
+        const log = ctx.log ?? NOLOG;
+        if (log.wants('tx.begin'))
+            log.emit('tx.begin', { op: 'begin', detail: { isolation: 'read committed', ...(ctx.reason ? { reason: ctx.reason } : {}) } });
         return new ExplicitTx(ctx, conn);
     }
     /** Транзакция ещё открыта (не зафиксирована и не откачена). */
@@ -307,6 +326,7 @@ export class ExplicitTx {
                 await this.conn.unsafe('rollback').catch(() => { });
             release(this.conn, this.broken);
             this.failure = this.broken;
+            this.rolledBack('error', this.broken);
             throw this.broken;
         }
         let changed = null;
@@ -331,18 +351,40 @@ export class ExplicitTx {
         catch (e) {
             this.failure ??= isConnectionError(e) ? commitUnknown(e) : fromDbError(e);
             release(this.conn, e);
+            this.rolledBack('error', this.failure);
             throw this.failure;
         }
         this.conn.release();
+        // транзакция с записью (write, delete, restore, db.sql, права, креды) — tx.commit уровня info: это и есть
+        // доказательство фиксации её событий записи (у них то же поле tx); без записи — debug, как прежде
+        const writes = this.log.writes ?? 0;
+        const level = writes > 0 ? 'info' : 'debug';
+        if (this.log.level(level)) {
+            this.log.emit('tx.commit', { op: 'commit', level, ms: performance.now() - this.t0,
+                detail: { writes, ...(changed ? { signals: changed.split(',').filter(Boolean).length } : {}) } });
+        }
         this.ctx.notifier?.add(changed);
         if (changed)
             this.ctx.onChanged?.(changedList(changed), this.raw);
         this.ctx.after?.();
     }
+    /** Событие отката (tx.rollback) и ошибка, которой он вызван. */
+    rolledBack(reason, err) {
+        const log = this.log;
+        if (!log.enabled)
+            return;
+        if (err !== undefined)
+            log.error(err, { op: 'commit', ms: performance.now() - this.t0 });
+        if (log.wants('tx.rollback')) {
+            log.emit('tx.rollback', { op: reason === 'error' ? 'commit' : 'rollback', ms: performance.now() - this.t0,
+                detail: { reason, writes: log.writes ?? 0, ...(this.broken ? { broken: true } : {}) } });
+        }
+    }
     async rollback() {
         if (this.done)
             return;
         this.done = true;
+        this.rolledBack('explicit');
         try {
             // соединение, оборванное ошибкой, не трогаем: postgres.js уронил бы процесс записью в закрытый сокет
             if (!isConnectionError(this.broken))

package/dist/typed.d.ts

@@ -16,7 +16,7 @@
  */
 import type { ChainCore, ChainRef } from './chain.js';
 import type { Cursor, Op, OP, Path, Row, Scalar } from './types.js';
-import type { IncMarker } from './write.js';
+import type { DeleteOptions, IncMarker, RestoreOptions } from './write.js';
 /**
  * То, что цепочкам нужно от модели: имя, алиас и типы для вывода — данные строки, концы строки, концы класса (роль →
  * `{ targets: имена классов целей; many; required }`) и имена класса и его предков. Модели letopis/model и объявления
@@ -290,16 +290,20 @@ export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, R
     upsert(data: Partial<DataOf<C>>, opts?: {
         reason?: string;
     }): TypedChain<C, M>;
-    /** С `{ confirm: true }` без фильтра, id, `tags()`, `owner()` и `limit()` у шагов — `invalid_query`; всех — `{ all: true }`. */
-    delete(opts?: {
-        confirm?: boolean;
-        all?: boolean;
-        reason?: string;
-    }): TypedChain<C, M>;
+    /**
+     * Без опций — превью. `{ confirm: true, expect: превью }` — удалить ровно показанное (цели сужены фильтром, id, `tags()`,
+     * `owner()` или `limit()`); `{ confirm: true }` без `expect` — `invalid_query` (`write.confirm_without_expect`);
+     * осознанно удалить текущий состав без сверки — `{ confirm: true, all: true }`.
+     */
+    delete(opts?: DeleteOptions): TypedChain<C, M>;
     forUpdate(): TypedChain<C, M>;
-    restore(opts?: {
-        reason?: string;
-    }): TypedChain<C, M>;
+    /**
+     * `{ expect }` — надгробия `{ id, rev }`: восстановить ровно то, что ушло удалением; расхождение — отказ по смыслу
+     * (`write.restore_already`, `write.restore_id_taken`, `write.restore_stale`). `{ expect, partial: true }` — что можно, а
+     * остальное — строки `$action: 'skip'` с причиной `$why`. Без `expect` — `invalid_query` (`write.restore_without_expect`);
+     * осознанно вернуть все удалённые цели шага без сверки — `{ all: true }`.
+     */
+    restore(opts: RestoreOptions): TypedChain<C, M>;
     cache(opts?: {
         ttl?: number;
     }): TypedChain<C, M>;

package/dist/types.d.ts

@@ -6,7 +6,12 @@
  * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии 2.x `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).
@@ -52,8 +57,16 @@ export interface Row<D = Record<string, unknown>, L = Record<string, string | st
     $depth?: number;
     /** Что сделал upsert. */
     $upsert?: 'created' | 'updated' | 'unchanged';
-    /** Превью удаления (delete() без confirm): удалится, снимется конец или помешает (restrict). */
-    $action?: 'delete' | 'unset' | 'restrict';
+    /**
+     * Превью удаления (delete() без confirm): удалится, снимется конец или помешает (restrict). В ответе
+     * `restore({ expect, partial: true })` — `skip`: цель не восстановлена, причина — `$why`.
+     */
+    $action?: 'delete' | 'unset' | 'restrict' | 'skip';
+    /**
+     * Почему цель `restore({ expect, partial: true })` не восстановлена: `restored` — её уже восстановили, `reissued` — id
+     * занял новый объект с тем же ключом, `changed` — после показанного удаления её меняли (удалили снова и т. п.).
+     */
+    $why?: 'restored' | 'reissued' | 'changed';
 }
 /** Путь paths(): узел на каждый шаг цепочки. */
 export type Path = Record<string, Row>;
@@ -102,7 +115,10 @@ export interface ChainMods {
     /** Срез «как было на момент T» (ISO). */
     asOf?: string;
     after?: Cursor;
-    /** Последний шаг включает удалённые. */
+    /**
+     * Не действует: с 2.1 `withDeleted()` — модификатор своего шага (флаг шага цепочки), а не всей выборки. Поле оставлено,
+     * чтобы тип не менялся.
+     */
     withDeleted?: boolean;
     /** Чтение с блокировкой строк последнего шага (только в db.begin()). */
     forUpdate?: boolean;
@@ -121,3 +137,65 @@ export interface QueryEvent {
     /** ms > slowMs. */
     slow: boolean;
 }
+/** Порог логирования: события этого уровня и выше; `'off'` — ничего. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';
+/** Событие логирования (каталог событий — lib/src/messages/log.ts). Поля без значения в событии отсутствуют. */
+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;
+    /** Арендатор сессии фасада. */
+    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

@@ -6,7 +6,12 @@
  * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии 2.x `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).

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 (база уже существует). */
@@ -221,4 +222,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,7 +16,8 @@ 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 { checkOptions, lerr, lmsg } from './errors.js';
@@ -24,7 +25,7 @@ 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 }));
@@ -597,11 +626,22 @@ 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 hash = u ? await hashPassword(u.password) : null;
     return sql.begin(async (tx) => {
         // под блокировкой схемы, как накат: up({ tenant }) нескольких экземпляров сервиса разом заводит арендатора один
@@ -624,18 +664,18 @@ 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]);
+        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, u.ttl ?? '7 days', { tenant }]))[0].t;
         }
         return { tenant, user, token, created };

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;