letopis 2.0.0 → 3.0.0

package/dist/index.js

@@ -8,18 +8,19 @@
  * Этап 6: история (versions, asOf, restore), maintain, watch, кэш результатов.
  */
 import postgres from 'postgres';
-import { LetopisError, checkOptions, fromDbError, lerr, lwarn } from './errors.js';
+import { LetopisError, checkOptions, fromDbError, lerr, lwarn, warnText } from './errors.js';
+import { guarded, instrument, makeLog, maskDsn, nextTx, safeErrorText, sqlText, traceSql, traced } from './log.js';
 import { Registry } from './registry.js';
 import { AclPasses, ExplicitTx, Notifier, poolExecutor, runTx } from './tx.js';
 import { checkReason } from './write.js';
 import { limits, registerDb } from './internal.js';
-import { makeAuth } from './auth.js';
-import { makeAcl } from './acl.js';
+import { AUTH_LOG, makeAuth } from './auth.js';
+import { ACL_LOG, makeAcl } from './acl.js';
 import { idOf as idOfClass } from './uuid.js';
 import { load, LOAD_OPTIONS } from './load.js';
 import { makeBatch, startEntity, startStep } from './chain.js';
 import { or as orFilters } from './ops.js';
-import { DDL_REVISION } from './types.js';
+import { DDL_REVISION, SCHEMA_VERSION } from './types.js';
 import { ACL_CLASSES, ResultCache } from './cache.js';
 import { Subscription } from './watch.js';
 import { SIGNAL_MODES, Signals, bucket, throttle } from './signals.js';
@@ -44,16 +45,19 @@ export { inc, isInc } from './write.js';
 export { totpCode, hashPassword, verifyHash } from './auth.js';
 export { up, createTenant } from './up.js';
 export { RESERVED_CLASS_NAMES, CHAIN_METHODS, DB_METHODS } from './types.js';
+export { LOG_EVENTS } from './messages/index.js';
 const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
 const SCHEMA_NAME = /^v\d+\.[a-z_][a-z0-9_]{0,40}$/;
 /** Все опции connect(): неизвестная — invalid_data с похожими именами (checkOptions; план 2.0, 7.10 №4). */
 const CONNECT_OPTIONS = {
     dsn: true, sql: true, schema: true, token: true, apiKey: true, service: true, refreshSession: true, allowBypassRls: true,
     admin: true, owner: true, notifyIntervalMs: true, max: true, onQuery: true, slowMs: true, models: true, listen: true,
-    cache: true, maintain: true,
+    cache: true, maintain: true, log: true, logLevel: true, redact: true,
 };
 /** Опции watch() (WatchOptions). */
 const WATCH_OPTIONS = { from: true, classes: true, batch: true, pollMs: true };
+/** Опции db.begin() (второй раунд 2.1, A4). */
+const BEGIN_OPTIONS = { reason: true };
 /**
  * То же подключение без строгих типов: шагом может быть любое имя, в том числе известное только во время выполнения, —
  * `loose(db)[имя]()`. Объект тот же: проверки во время выполнения (неизвестное имя или поле, переход, слот) не меняются.
@@ -65,9 +69,11 @@ const quote = (name) => `"${name.replace(/"/g, '""')}"`;
 /** Фасад db: пул (exec — исполнитель пула) или явная транзакция (tx). */
 function makeDb(sh, scope, exec, owner, tx) {
     const txc = scope.txc;
+    // логгер фасада: арендатор и аккаунт — в момент события (корень меняет их auth.switch), метка транзакции — от db.begin()
+    const log = (txc.log ?? sh.log).child({ who: () => ({ tenant: scope.tenant(), account: txc.account ?? sh.root.account }) });
     const chainCtx = {
-        reg: scope.registry(), schema: sh.schema, exec, tenant: scope.tenant, owner, onQuery: sh.onQuery, slowMs: sh.slowMs,
-        reason: txc.reason ?? '', txReason: txc.reason ?? '',
+        reg: scope.registry(), schema: sh.schema, exec, tenant: scope.tenant, hasToken: () => Boolean(txc.token), owner, onQuery: sh.onQuery, slowMs: sh.slowMs,
+        reason: txc.reason ?? '', txReason: txc.reason ?? '', log,
         ...(sh.cache ? { cache: { store: sh.cache, who: () => ({ token: txc.token, account: txc.account, tenant: scope.tenant() }) } } : {}),
     };
     // реестр корня меняется после auth.switch — цепочки берут действующий
@@ -78,12 +84,12 @@ function makeDb(sh, scope, exec, owner, tx) {
     const noTx = (what) => {
         throw lerr('api.tx_only', { what });
     };
-    const auth = makeAuth(sh.S, exec, async () => {
+    const auth = instrument(makeAuth(sh.S, exec, async () => {
         sh.passes.clear();
         await sh.refresh();
-    }, scope.root && !tx);
+    }, scope.root && !tx), log, 'auth', AUTH_LOG, { switch: () => scope.tenant() });
     // запись правил (grant, deny, revoke, roles) идёт цепочками самого фасада — он объявлен ниже, берётся при вызове
-    const acl = makeAcl(sh.S, exec, () => facade);
+    const acl = instrument(makeAcl(sh.S, exec, () => facade), log, 'acl', ACL_LOG);
     const adm = { S: sh.S, txc, exec };
     // один процесс (план 2.0, 7.9 №3): у корня с connect({ admin }) администраторские вызовы идут вторым пулом с той же
     // сессией, а цепочки и db.sql — пулом приложения под RLS; db.as() и db.begin() администраторский пул не берут
@@ -100,19 +106,35 @@ function makeDb(sh, scope, exec, owner, tx) {
         get registry() { return scope.registry(); },
         auth,
         acl,
-        sql: (strings, ...values) => exec.run((q) => q(strings, ...values), { raw: true }),
-        transaction: (fn) => exec.run(fn),
-        idOf: (cls, key) => {
+        sql: (strings, ...values) => traced(log, 'raw', { op: 'sql' }, () => exec.run((q) => q(strings, ...values), { raw: true }), (r) => ({ rows: r.length, detail: { text: sqlText(strings.reduce((a, x, i) => (i ? `${a}$${i}${x}` : x), '')), params: values.length } })),
+        transaction: (fn) => {
+            // в db.begin() — та же транзакция: своих событий tx.* нет
+            if (exec.explicit || !log.enabled)
+                return traced(log, null, { op: 'transaction' }, () => exec.run(fn));
+            const tl = log.child({ tx: nextTx('t') });
+            tl.emit('tx.begin', { op: 'transaction', detail: { isolation: 'read committed' } });
+            const t0 = performance.now();
+            return exec.run(fn).then((r) => {
+                // сырой SQL: была ли запись, не знаем — фиксация такой транзакции всегда info (доказательство фиксации)
+                tl.emit('tx.commit', { op: 'transaction', ms: performance.now() - t0, level: 'info', detail: { raw: true } });
+                return r;
+            }, (e) => {
+                tl.error(e, { op: 'transaction', ms: performance.now() - t0 });
+                tl.emit('tx.rollback', { op: 'transaction', ms: performance.now() - t0, detail: { reason: 'error' } });
+                throw e;
+            });
+        },
+        idOf: (cls, key) => guarded(log, { op: 'idOf' }, () => {
             const tenant = scope.tenant();
             if (!tenant)
                 throw lerr('api.id_of_no_tenant');
             const c = scope.registry().resolve(cls);
             return idOfClass({ name: c.name, key: c.key, ends: Object.keys(c.ends) }, key, { tenant });
-        },
-        refresh: sh.refresh,
+        }),
+        refresh: () => traced(log, null, { op: 'refresh' }, sh.refresh),
         flushSignals: () => sh.notifier.flush(),
-        maintain: () => (viaAdmin ? adminReady().then(() => runMaintain(admCtx())) : runMaintain(adm)),
-        watch: (o = {}) => {
+        maintain: () => traced(log, 'maintain', { op: 'maintain' }, () => (viaAdmin ? adminReady().then(() => runMaintain(admCtx())) : runMaintain(adm)), (r) => ({ detail: { ...r } })),
+        watch: (o = {}) => guarded(log, { op: 'watch' }, () => {
             checkOptions('watch', o, WATCH_OPTIONS);
             const reg = scope.registry();
             const classes = o.classes ? [...new Set(o.classes.flatMap((c) => reg.family(c).map((x) => x.name)))] : null;
@@ -132,14 +154,15 @@ function makeDb(sh, scope, exec, owner, tx) {
                     onSignal: (fn) => { sh.signals.add(fn); return () => void sh.signals.delete(fn); },
                     tenant: () => (sh.allTenants ? null : sh.sig.tenantToken(scope.tenant())),
                 } : {}),
+                ...(log.enabled ? { log } : {}),
             }, o));
-        },
+        }),
         cache: {
             clear: () => sh.cache?.clear(),
             stats: () => sh.cache?.stats() ?? { size: 0, hits: 0, misses: 0, stores: 0, raced: 0, signals: 0, listens: 0, enabled: false },
         },
-        entity: (x) => startEntity(chainCtx, x),
-        as: async (account, o) => {
+        entity: (x) => guarded(log, { op: 'entity' }, () => startEntity(chainCtx, x)),
+        as: (account, o) => traced(log, 'auth.as', { op: 'as' }, async () => {
             if (tx)
                 throw lerr('api.as_in_tx');
             const id = account === null ? undefined : typeof account === 'object' ? account.id : account;
@@ -165,16 +188,26 @@ function makeDb(sh, scope, exec, owner, tx) {
                 if (!r?.account)
                     throw lerr('api.as_no_session');
             }
-        },
-        begin: async (o) => {
+        }, (d) => ({ tenant: d.tenant ?? undefined, account: typeof account === 'object' && account !== null ? account.id : account ?? undefined,
+            detail: { ...(o?.tenant !== undefined ? { tenant: o.tenant } : {}), ...(o?.owner !== undefined ? { owner: o.owner } : {}) } })),
+        begin: (o) => traced(log, null, { op: 'begin' }, async () => {
+            // аргумент — только опции (второй раунд 2.1, A4): begin(fn) функцию не вызывал, а транзакция оставалась открытой
+            if (o !== undefined && o !== null && (typeof o !== 'object' || Array.isArray(o))) {
+                throw lerr('api.begin_arg', { type: Array.isArray(o) ? 'array' : typeof o });
+            }
+            checkOptions('begin', o, BEGIN_OPTIONS);
             if (tx)
                 throw lerr('api.nested_begin');
-            // причина блока ставится в начале транзакции (setupSql) и действует на все её операции
-            const btx = o?.reason !== undefined ? { ...txc, reason: checkReason(o.reason, 'db.begin()') } : txc;
+            // причина блока ставится в начале транзакции (setupSql) и действует на все её операции; логгер — с меткой
+            // транзакции: её события (tx.*) и все операции фасада db.begin() несут поле tx
+            const tl = log.enabled ? (txc.log ?? sh.log).child({ tx: nextTx('b'), writes: { n: 0 } }) : undefined;
+            const btx = o?.reason !== undefined || tl
+                ? { ...txc, ...(o?.reason !== undefined ? { reason: checkReason(o.reason, 'db.begin()') } : {}), ...(tl ? { log: tl } : {}) }
+                : txc;
             const t = await ExplicitTx.open(btx);
             return makeDb(sh, btx === txc ? scope : { ...scope, txc: btx }, t, owner, t);
-        },
-        load: async (input, o) => {
+        }),
+        load: (input, o) => traced(log, 'load', { op: 'load' }, async () => {
             // опции — до всего прочего: неизвестная — отказ раньше admin_required пула администратора (план 2.0, 7.10 №4)
             checkOptions('load', o, LOAD_OPTIONS);
             if (tx)
@@ -184,17 +217,18 @@ function makeDb(sh, scope, exec, owner, tx) {
                 return load({ sql: viaAdmin, schema: sh.schema, tenant: scope.tenant(), admin: true, ownerRole: sh.ownerRole }, input, o);
             }
             return load({ sql: sh.sql, schema: sh.schema, tenant: scope.tenant(), admin: sh.admin, ownerRole: sh.ownerRole }, input, o);
-        },
+        }, (r) => ({ rows: r.loaded + r.updated, detail: { ...r } })),
         batch: (name, o) => {
             let q = batches.get(name);
             if (!q)
                 batches.set(name, (q = []));
             return makeBatch(o?.reason !== undefined ? { ...chainCtx, reason: checkReason(o.reason, 'db.batch()') } : chainCtx, q);
         },
-        lock: async (...keys) => (tx ? tx.lock(...keys) : noTx('lock()')),
-        commit: async (tr) => (tr ? tr.commit() : tx ? tx.commit() : noTx('commit()')),
-        rollback: async (tr) => (tr ? tr.rollback() : tx ? tx.rollback() : noTx('rollback()')),
-        close: () => (tx ? tx.rollback() : sh.close()),
+        lock: (...keys) => traced(log, 'lock', { op: 'lock', detail: { keys } }, async () => (tx ? tx.lock(...keys) : noTx('lock()'))),
+        commit: (tr) => traced(log, null, { op: 'commit' }, async () => (tr ? tr.commit() : tx ? tx.commit() : noTx('commit()'))),
+        rollback: (tr) => traced(log, null, { op: 'rollback' }, async () => (tr ? tr.rollback() : tx ? tx.rollback() : noTx('rollback()'))),
+        // подключение из as() пул не закрывает: пул общий с корнем (план 2.1, A12) — закрывает его close() корня
+        close: () => traced(log, !tx && scope.root ? 'close' : null, { op: 'close', detail: { schema: sh.schema } }, () => (tx ? tx.rollback() : scope.root ? sh.close() : Promise.resolve())),
     };
     /** Свойство фасада: служебное — из core, иначе шаг класса, алиаса или роли. */
     const member = (t, prop, r) => {
@@ -202,7 +236,8 @@ function makeDb(sh, scope, exec, owner, tx) {
             return Reflect.get(t, prop, r);
         if (prop === 'then')
             return undefined;
-        return startStep(chainCtx, prop);
+        // неизвестный класс или роль — событие error с именем шага
+        return log.enabled ? guarded(log, { op: prop, chain: prop }, () => startStep(chainCtx, prop)) : startStep(chainCtx, prop);
     };
     const facade = new Proxy(core, {
         get(t, prop, r) {
@@ -211,7 +246,7 @@ function makeDb(sh, scope, exec, owner, tx) {
     });
     // модули пакета (letopis/mcp) узнают обход RLS по самому подключению, а не со слов вызывающего (internal.ts)
     registerDb(facade, {
-        allTenants: sh.allTenants, explicit: Boolean(tx),
+        allTenants: sh.allTenants, explicit: Boolean(tx), log,
         ...(viaAdmin ? { adminTx: (fn) => adminReady().then(() => runTx({ ...txc, sql: viaAdmin }, fn)) } : {}),
     });
     return facade;
@@ -219,10 +254,28 @@ function makeDb(sh, scope, exec, owner, tx) {
 export async function connect(opts) {
     // опции — первыми: неизвестная — invalid_data с похожими именами до прочих проверок (план 2.0, 7.10 №4)
     checkOptions('connect', opts, CONNECT_OPTIONS);
+    // логгер — до всего прочего: отказы connect() тоже идут событием error (логирование 3.0)
+    const base = makeLog({ log: opts.log, logLevel: opts.logLevel, redact: opts.redact });
+    const info = {};
+    return traced(base, 'connect', { op: 'connect' }, () => open(opts, base, info), (db) => ({ tenant: db.tenant ?? undefined, account: info.account ?? undefined, detail: info }));
+}
+/** connect() после проверки опций: base — логгер подключения, info — подробности события connect. */
+async function open(opts, base, info) {
+    // имя без точки — как у up(): v2.<имя> (план 2.1, A12); дальше всё, и канал LISTEN, — по полному имени
+    if (typeof opts.schema === 'string' && !opts.schema.includes('.'))
+        opts = { ...opts, schema: `${SCHEMA_VERSION}.${opts.schema}` };
     if (!SCHEMA_NAME.test(opts.schema))
         throw lerr('api.connect_schema', { schema: opts.schema });
     if (!opts.sql && !opts.dsn)
         throw lerr('api.connect_no_dsn');
+    // ключ сервиса или токен передан, но пуст (null, '', не строка — например, повторный up() вернул serviceKey: null):
+    // отказ сразу, а не подключение без сессии и no_session на первой записи. undefined — опции нет (CLI, необязательный токен)
+    for (const name of ['apiKey', 'service', 'token']) {
+        const v = opts[name];
+        if (v !== undefined && (typeof v !== 'string' || v.trim() === '')) {
+            throw lerr('api.connect_empty_credential', { name, value: v === null ? 'null' : typeof v === 'string' ? `'${v}'` : typeof v });
+        }
+    }
     // интервал обслуживания — до пула и таймеров: неверный не оставляет за собой открытых соединений
     const maintainEvery = opts.maintain === undefined ? undefined : parseInterval(opts.maintain);
     if (opts.admin !== undefined && typeof opts.admin !== 'string' && typeof opts.admin !== 'function') {
@@ -231,13 +284,15 @@ export async function connect(opts) {
     const own = !opts.sql;
     // timestamptz — строкой: Date в JS режет микросекунды, а на них держатся asOf и курсоры по времени
     const types = { timestamptz: { to: 1184, from: [1184], serialize: (v) => (v instanceof Date ? v.toISOString() : v), parse: (v) => v } };
-    const sql = (opts.sql ?? postgres(opts.dsn, { max: opts.max ?? 10, onnotice: () => { }, types }));
+    // порог debug — каждый запрос пула даёт событие sql (traceSql); иначе пул как есть
+    const sql = traceSql((opts.sql ?? postgres(opts.dsn, { max: opts.max ?? 10, onnotice: () => { }, types })), base);
     // один процесс (план 2.0, 7.9 №3): пул администратора postgres.js соединяется при первом запросе — до первого
     // администраторского вызова соединений у него нет
     const ownAdmin = typeof opts.admin === 'string';
-    const adminSql = (typeof opts.admin === 'string'
+    const adminRaw = (typeof opts.admin === 'string'
         ? postgres(opts.admin, { max: 2, onnotice: () => { }, types, connection: { application_name: 'letopis admin' } })
         : opts.admin);
+    const adminSql = adminRaw ? traceSql(adminRaw, base) : undefined;
     const S = quote(opts.schema);
     const owner = opts.owner ?? 'letopis_owner';
     let adminChecked;
@@ -264,7 +319,7 @@ export async function connect(opts) {
             throw lerr('api.connect_bypass_rls');
         }
         if (bypass)
-            lwarn('api.admin_connection');
+            lwarn('api.admin_connection', undefined, { log: base });
         // ревизия движка — до первого вызова функций схемы (вход по ключу): схема letopis 1.x — отказ (план 2.0, 7.10 №5)
         const [rv] = await sql `select obj_description(n.oid, 'pg_namespace') as c from pg_namespace n where n.nspname = ${opts.schema}`;
         if (!rv)
@@ -273,16 +328,16 @@ export async function connect(opts) {
         refuse1x(opts.schema, rev);
         // библиотека новее схемы 2.x — накат отстал (этап 6, п. 10)
         if (rev < DDL_REVISION)
-            lwarn('api.schema_older', { schema: opts.schema, rev, want: DDL_REVISION });
+            lwarn('api.schema_older', { schema: opts.schema, rev, want: DDL_REVISION }, { log: base });
         // схему обновил более новый пакет (во время раскатки старые экземпляры ещё работают): подключаемся, но предупреждаем —
         // этот пакет может не знать функций и колонок новой ревизии; up() такую схему не трогает и отказывает
         else if (rev > DDL_REVISION)
-            lwarn('api.schema_newer', { schema: opts.schema, rev, known: DDL_REVISION });
+            lwarn('api.schema_newer', { schema: opts.schema, rev, known: DDL_REVISION }, { log: base });
         else {
             // ревизия та же, а функции схемы ставила другая версия движка — штамп в комментарии схемы (99-revision.sql)
             const drift = await stampDrift(opts.schema, String(rv.c ?? ''));
             if (drift)
-                console.warn(drift);
+                warnText(drift, undefined, base);
         }
         let token = opts.token ?? null;
         const apiKey = opts.apiKey ?? opts.service;
@@ -298,7 +353,11 @@ export async function connect(opts) {
         });
         const mode = SIGNAL_MODES.includes(sm?.m) ? sm.m : 'class';
         const sig = new Signals(mode);
-        const notifier = new Notifier(sql, opts.schema, opts.notifyIntervalMs ?? 100);
+        // отправка сигналов не удалась — предупреждение только при заданном логгере (без него — молча, как прежде)
+        const notifier = new Notifier(sql, opts.schema, opts.notifyIntervalMs ?? 100, (e) => {
+            if (base.active)
+                lwarn('log.notify_failed', { message: safeErrorText(e) }, { log: base });
+        }, base);
         const passes = new AclPasses(S);
         // режим none: сигналов нет — без LISTEN, кэш только по сроку (ttlOnly), подписка опрашивает журнал
         const listen = opts.listen !== false && mode !== 'none';
@@ -319,8 +378,8 @@ export async function connect(opts) {
         };
         // в режиме none нотификатор не отправляет: letopis.changed своей транзакции сбрасывает только свой кэш
         const ctx = { sql, token, notifier: mode === 'none' ? null : notifier, passes, after: touch,
-            ...(cache ? { onChanged: (names, raw) => cache.changed(names, raw) } : {}) };
-        const root = { tenant: null, registry: new Registry() };
+            ...(cache ? { onChanged: (names, raw) => cache.changed(names, raw) } : {}), ...(base.active ? { log: base } : {}) };
+        const root = { tenant: null, registry: new Registry(), account: null };
         // подключение по ключу APIKEY: сессия истекает по простою (срок — 7 суток), и процесс, простоявший дольше, получал
         // бы no_session на каждый вызов. Ключ обменивается на новую сессию заново (один обмен на все ждущие вызовы), с тем
         // же рабочим арендатором, что выбрал auth.switch(); операция повторяется один раз (runTx, ExplicitTx.open)
@@ -349,8 +408,13 @@ export async function connect(opts) {
                     renewing = null;
                 });
                 const next = await renewing;
-                if (!next)
+                if (!next) {
+                    if (base.active)
+                        lwarn('log.renew_failed', undefined, { log: base });
                     return false;
+                }
+                if (base.wants('session.renew'))
+                    base.emit('session.renew', { tenant: root.tenant ?? undefined, account: root.account ?? undefined });
                 token = next;
                 ctx.token = next;
                 failed.token = next;
@@ -409,12 +473,19 @@ export async function connect(opts) {
         const tokens = () => sig.setClasses([root.registry, ...[...others.values()].map((o) => o.registry)].flatMap((r) => r.all().map((c) => c.name)));
         // only — токены арендаторов из сигналов Class (режимы tenant и opaque): реестры db.as() только этих арендаторов
         const refresh = async (only) => {
+            const t0 = performance.now();
             const rows = await runTx(ctx, async (q) => {
-                const [t] = await q.unsafe(`select ${S}.ctx_tenant() as t`);
+                // аккаунт сессии — для полей account событий лога корня
+                const [t] = await q.unsafe(`select ${S}.ctx_tenant() as t, ${S}.ctx_account() as a`);
                 root.tenant = t?.t ?? null;
+                root.account = t?.a ?? null;
                 return q.unsafe(`select tenant, rev, data from ${S}.entity where class = 'Class' and tenant in (${S}.ctx_tenant(), '${SYSTEM_ID}')`);
             });
             root.registry.load(rows);
+            if (base.wants('registry.refresh')) {
+                base.emit('registry.refresh', { op: 'refresh', ms: performance.now() - t0, rows: rows.length, tenant: root.tenant ?? undefined,
+                    account: root.account ?? undefined, ...(only ? { detail: { tenants: only.size } } : {}) });
+            }
             for (const [tenant, o] of others) {
                 if (only && !only.has(sig.tenantToken(tenant) ?? ''))
                     continue;
@@ -477,6 +548,13 @@ export async function connect(opts) {
             if (sig.setKey(key))
                 cache?.clear();
         };
+        // токен, который не даёт сессии (погашен, истёк, неверен), — отказ connect(), а не подключение без сессии, где первый
+        // же шаг дал бы invalid_class про личный арендатор (второй раунд 2.1, A5)
+        if (opts.token) {
+            const [s] = await runTx(ctx, (q) => q.unsafe(`select account from ${S}.ctx()`), { read: true, retries: 0 });
+            if (!s?.account)
+                throw lerr('api.token_not_active');
+        }
         await fetchKey();
         await refresh();
         // ключ, реестр и пропуска прав — заново после переподключения слушателя, по незнакомому токену, нагрузке не по
@@ -524,6 +602,8 @@ export async function connect(opts) {
         // (пере)подключение слушателя — кэш целиком, после обрыва — и ключ с реестром (сигналы потеряны)
         const onSignal = (payload) => {
             const s = sig.parse(payload);
+            if (base.wants('signal'))
+                base.emit('signal', { detail: { ...s } });
             if (s.kind === 'class' && ACL_CLASSES.has(s.cls))
                 passes.clear();
             if (s.kind === 'class' && s.cls === 'Class')
@@ -537,6 +617,8 @@ export async function connect(opts) {
         let listened = false;
         const listener = listen
             ? await sql.listen(opts.schema, onSignal, () => {
+                if (base.wants('signal'))
+                    base.emit('signal', { detail: { kind: 'listen', reconnect: listened } });
                 if (listened)
                     resync();
                 listened = true;
@@ -570,7 +652,7 @@ export async function connect(opts) {
         let stopMaintain = null;
         const subs = new Set();
         const shared = {
-            sql, schema: opts.schema, S, notifier, passes, root, registryFor, registryOf, refresh, onQuery: opts.onQuery, slowMs: opts.slowMs,
+            sql, schema: opts.schema, S, notifier, passes, root, registryFor, registryOf, refresh, onQuery: opts.onQuery, slowMs: opts.slowMs, log: base,
             admin: Boolean(bypass && (role.rolsuper || role.can_set)),
             ownerRole: owner,
             ...(adminSql ? { adminSql, adminReady } : {}),
@@ -605,7 +687,15 @@ export async function connect(opts) {
         };
         const db = makeDb(shared, { txc: ctx, tenant: () => root.tenant, registry: () => root.registry, root: true }, poolExecutor(ctx));
         if (maintainEvery !== undefined)
-            stopMaintain = scheduleMaintain(() => db.maintain(), maintainEvery);
+            stopMaintain = scheduleMaintain(() => db.maintain(), maintainEvery, base);
+        if (base.enabled) {
+            Object.assign(info, {
+                schema: opts.schema, ...(opts.dsn ? { dsn: maskDsn(opts.dsn) } : {}), pool: own ? 'own' : 'external', ...(own ? { max: opts.max ?? 10 } : {}),
+                ...(adminSql ? { adminPool: ownAdmin ? 'own' : 'external' } : {}), bypass: Boolean(bypass), revision: rev, signals: mode, listen,
+                cache: Boolean(cache), ...(maintainEvery !== undefined ? { maintain: maintainEvery } : {}),
+                session: opts.token ? 'token' : apiKey ? 'service' : 'none', account: root.account,
+            });
+        }
         return db;
     }
     catch (e) {

package/dist/internal.d.ts

@@ -14,6 +14,8 @@ export interface DbInternals {
      * Только у корня подключения с опцией admin.
      */
     readonly adminTx?: <T>(fn: (tx: import('./tx.js').Tx) => Promise<T>) => Promise<T>;
+    /** Логгер фасада (lib/src/log.ts): им пишут syncModels и инструменты MCP. */
+    readonly log?: import('./log.js').Log;
 }
 /**
  * Пределы подключения, которых нет в опциях: реестров классов db.as() — не больше asRegistries арендаторов (план 2.0,

package/dist/load.d.ts

@@ -3,6 +3,14 @@ import { type Issue } from './errors.js';
 import { Registry } from './registry.js';
 type Sql = postgres.Sql<Record<string, unknown>>;
 type Raw = Record<string, unknown>;
+/** Ссылка на цель вне загрузки: строка, роль и допустимые классы конца. */
+type ExtRef = {
+    line: number;
+    role: string;
+    allowed: string[];
+};
+/** Цели вне загрузки: id → первая ссылка с каждым набором допустимых классов (сверяется каждый набор). */
+type ExtRefs = Map<string, ExtRef[]>;
 export interface LoadOptions {
     /** Повтор id в загрузке: отменить загрузку (по умолчанию), оставить первую или последнюю строку. */
     duplicates?: 'error' | 'first' | 'last';
@@ -110,11 +118,7 @@ export interface InitialTuning {
 interface Pending {
     reg: Registry;
     tenant: string;
-    external: Map<string, {
-        line: number;
-        role: string;
-        allowed: string[];
-    }>;
+    external: ExtRefs;
     owners: Map<string, number>;
 }
 /** Состояние сессии первой заливки. */

package/dist/load.js

@@ -22,13 +22,16 @@ import { LetopisError, checkOptions, fromDbError, issuesFromDb, lerr, lmsg } fro
 import { isOp } from './ops.js';
 import { Registry } from './registry.js';
 import { accepts } from './sql.js';
-import { v5Id } from './uuid.js';
+import { UUID_RE, v5Id } from './uuid.js';
 import { applyDefaults, leavesToDb } from './validate.js';
 import { isInc } from './write.js';
 import { ACL_CLASS_NAMES } from './types.js';
 import { isConnectionError, release, rollbackAfter } from './tx.js';
 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;
+function sameList(a, b) {
+    return a.length === b.length && a.every((x, k) => x === b[k]);
+}
 /**
  * Все опции load(): неизвестная — invalid_data с похожими (checkOptions; план 2.0, 7.10 №4). Фасад db.load() сверяет их
  * до пула администратора (index.ts), load() — ещё раз до проверки прав.
@@ -523,6 +526,14 @@ export async function load(env, input, opts = {}) {
             for (const r of roots)
                 await conn.unsafe(`select ${S}.family_lock(${S}.class_row($1, $2::uuid), false)`, [r, tenant]);
             const reg = await readRegistry(conn);
+            // класс строки, удалённый между первым чтением реестра и блокировкой семейства, — отказ, а не прежнее описание
+            for (const i of portion) {
+                const n = p1[i].cls.name;
+                if (!reg.find(n))
+                    issues.add({ line: i + 1, code: 'invalid_class', message: lmsg('write.load_class_not_found', { name: n }), id: p1[i].id, class: n });
+            }
+            if (issues.any)
+                issues.fail();
             const [{ ts, xid }] = await conn.unsafe(`select clock_timestamp()::text as ts, pg_current_xact_id()::text as xid`);
             // от имени пользователя: арендатор доступен ему, планы прав READ и WRITE; класс без права — отказ
             if (asAcc) {
@@ -618,10 +629,11 @@ export async function load(env, input, opts = {}) {
                 const found = new Map((await conn.unsafe(`select e.id, e.tenant, e.class from ${S}.entity e where e.id = any ($1::uuid[]) order by e.id for key share`, [ext]))
                     .map((r) => [r.id, r]));
                 for (const id of ext) {
-                    const ref = external.get(id);
                     const f = found.get(id);
-                    if (!f || (f.tenant !== tenant && f.tenant !== SYSTEM_ID) || !accepts(reg, ref.allowed, f.class)) {
-                        issues.add({ line: ref.line, code: 'target_not_found', message: lmsg('write.load_target_not_found', { role: ref.role }), id });
+                    for (const ref of external.get(id)) {
+                        if (!f || (f.tenant !== tenant && f.tenant !== SYSTEM_ID) || !accepts(reg, ref.allowed, f.class)) {
+                            issues.add({ line: ref.line, code: 'target_not_found', message: lmsg('write.load_target_not_found', { role: ref.role }), id });
+                        }
                     }
                 }
             }
@@ -713,7 +725,7 @@ export async function load(env, input, opts = {}) {
     /** Проверки строки и ссылок; null — строка не пишется (нарушение уже в отчёте). */
     function check(reg, i, inLoad, external, lastVersion) {
         const raw = rows[i];
-        const cls = reg.find(p1[i].cls.name) ?? p1[i].cls;
+        const cls = reg.find(p1[i].cls.name); // наличие в свежем реестре проверено после блокировки (loadPortion)
         const sh = shape(reg, tenant, cls, raw, true);
         if (sh.error) {
             issues.add({ line: i + 1, code: sh.error.code, message: sh.error.message, id: p1[i].id, class: cls.name, ...(sh.error.issues ? { issues: sh.error.issues } : {}) });
@@ -758,8 +770,14 @@ export async function load(env, input, opts = {}) {
                     if (!t.alive || !accepts(reg, allowed, t.cls))
                         issues.add({ line: i + 1, code: 'target_not_found', message: lmsg('write.load_target_not_found', { role }), id: p1[i].id, class: cls.name });
                 }
-                else if (!external.has(id)) {
-                    external.set(id, { line: i + 1, role, allowed });
+                else {
+                    // первая ссылка на id с каждым набором допустимых классов: тот же id под другой ролью может требовать
+                    // другой класс (сверяются все наборы), повторы того же набора — не копятся
+                    const refs = external.get(id);
+                    if (!refs)
+                        external.set(id, [{ line: i + 1, role, allowed }]);
+                    else if (!refs.some((r) => sameList(r.allowed, allowed)))
+                        refs.push({ line: i + 1, role, allowed });
                 }
             }
         }
@@ -1181,10 +1199,11 @@ export async function initialSession(env, fn, tune = {}) {
                 const found = new Map((await q(`select e.id, e.tenant, e.class from ${S}.entity e where e.id = any ($1::uuid[])`, [ext]))
                     .map((r) => [r.id, r]));
                 for (const id of ext) {
-                    const ref = p.external.get(id);
                     const f = found.get(id);
-                    if (!f || (f.tenant !== p.tenant && f.tenant !== SYSTEM_ID) || !accepts(p.reg, ref.allowed, f.class)) {
-                        issues.add({ line: ref.line, code: 'target_not_found', message: lmsg('write.load_target_not_found', { role: ref.role }), id });
+                    for (const ref of p.external.get(id)) {
+                        if (!f || (f.tenant !== p.tenant && f.tenant !== SYSTEM_ID) || !accepts(p.reg, ref.allowed, f.class)) {
+                            issues.add({ line: ref.line, code: 'target_not_found', message: lmsg('write.load_target_not_found', { role: ref.role }), id });
+                        }
                     }
                 }
             }