letopis 2.0.0 → 3.0.1

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';
@@ -35,8 +36,7 @@ export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has,
 /**
  * Хотя бы один из фильтров: `db.Product(or({ sku: 'K-1' }, { price: lt(500) }))` — товар K-1 или дешевле 500. Ставится
  * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и». В шаге подключения
- * с моделями (`TypedDb`) фильтры внутри — поля и роли класса шага: тип им даёт шаг (план 2.0, этап 4, п. 1). Та же
- * фабрика, что в реестре операторов (ops.ts), — другой у неё только тип.
+ * с моделями (`TypedDb`) фильтры внутри — поля и роли класса шага: тип им даёт шаг.
  */
 export const or = orFilters;
 export { cursorOf } from './sql.js';
@@ -44,30 +44,58 @@ 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)[имя]()`. Объект тот же: проверки во время выполнения (неизвестное имя или поле, переход, слот) не меняются.
+ * `loose(db)[имя]()`. Объект тот же: проверки во время выполнения (неизвестное имя или поле, переход, шаг роли) не меняются.
  */
 export function loose(db) {
     return db;
 }
 const quote = (name) => `"${name.replace(/"/g, '""')}"`;
+/** Методы фасада, которые отвечают сразу, а не обещанием: после close() они бросают api.closed синхронно. */
+const SYNC_MEMBERS = new Set(['idOf', 'entity', 'watch', 'batch']);
+/** Свойства фасада, которые после close() читаются как прежде: не обращаются к базе. */
+const PASSIVE_MEMBERS = new Set(['close', 'schema', 'token', 'tenant', 'registry', 'cache']);
+/** Исполнитель, который после close() корня отказывает api.closed: postgres.js reserve() открыл бы закрытый пул заново. */
+function openOnly(sh, exec) {
+    return {
+        explicit: exec.explicit,
+        run: (fn, opts) => (sh.closed ? Promise.reject(lerr('api.closed')) : exec.run(fn, opts)),
+    };
+}
+/** Служебный объект фасада (auth, acl) после close(): каждый метод — отказ api.closed. */
+function closedApi(api) {
+    return new Proxy(api, {
+        get(t, prop, r) {
+            const v = Reflect.get(t, prop, r);
+            return typeof v === 'function' ? () => Promise.reject(lerr('api.closed')) : v;
+        },
+    });
+}
 /** Фасад db: пул (exec — исполнитель пула) или явная транзакция (tx). */
-function makeDb(sh, scope, exec, owner, tx) {
+function makeDb(sh, scope, raw, owner, tx) {
     const txc = scope.txc;
+    // после close() корня цепочки (и созданные до него), auth, acl, db.sql — отказ api.closed; raw — у maintain(), который
+    // идёт по расписанию: close() его дожидается
+    const exec = openOnly(sh, raw);
+    // логгер фасада: арендатор и аккаунт — в момент события (корень меняет их 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, account: () => txc.account ?? sh.root.account, 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,13 +106,13 @@ 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 adm = { S: sh.S, txc, exec };
+    const acl = instrument(makeAcl(sh.S, exec, () => facade), log, 'acl', ACL_LOG);
+    const adm = { S: sh.S, txc, exec: raw };
     // один процесс (план 2.0, 7.9 №3): у корня с connect({ admin }) администраторские вызовы идут вторым пулом с той же
     // сессией, а цепочки и db.sql — пулом приложения под RLS; db.as() и db.begin() администраторский пул не берут
     const viaAdmin = scope.root && !tx && sh.adminSql ? sh.adminSql : null;
@@ -100,19 +128,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 +176,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 +210,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,25 +239,45 @@ 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() и close() у db.as() или db.begin() закрытого подключения — без ошибки
+        close: () => traced(log, !tx && scope.root ? 'close' : null, { op: 'close', detail: { schema: sh.schema } }, () => (tx ? (sh.closed ? Promise.resolve() : tx.rollback()) : scope.root ? sh.close() : Promise.resolve())),
     };
     /** Свойство фасада: служебное — из core, иначе шаг класса, алиаса или роли. */
     const member = (t, prop, r) => {
+        if (sh.closed && typeof prop === 'string' && prop !== 'then' && !PASSIVE_MEMBERS.has(prop))
+            return closedMember(t, prop, r);
         if (typeof prop === 'symbol' || prop in t)
             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);
+    };
+    /** Свойство фасада после close(): методы и шаги — отказ api.closed (обещанием, у шагов и синхронных методов — сразу). */
+    const closedMember = (t, prop, r) => {
+        if (prop in t) {
+            const v = Reflect.get(t, prop, r);
+            if (prop === 'auth' || prop === 'acl')
+                return closedApi(v);
+            if (typeof v !== 'function')
+                return v;
+            if (!SYNC_MEMBERS.has(prop))
+                return () => Promise.reject(lerr('api.closed'));
+        }
+        return () => {
+            throw lerr('api.closed');
+        };
     };
     const facade = new Proxy(core, {
         get(t, prop, r) {
@@ -211,7 +286,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 +294,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 +324,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 +359,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 +368,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 +393,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 +418,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 +448,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 +513,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 +588,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 +642,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 +657,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;
@@ -568,9 +690,10 @@ export async function connect(opts) {
             stamper.unref?.();
         }
         let stopMaintain = null;
+        let closing = 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 } : {}),
@@ -584,28 +707,46 @@ export async function connect(opts) {
                 subs.add(s);
                 return s;
             },
-            async close() {
-                // живые подписки закрываются: иначе с чужим пулом (connect({ sql })) они опрашивали бы журнал и после close()
-                // (план 2.0, 7.4 №8)
-                for (const s of [...subs])
-                    s.close();
-                // идущий maintain() по расписанию доделывается: пул закрывается после него, а не посреди транзакции
-                await stopMaintain?.();
-                resync.stop();
-                startReload.stop();
-                if (stamper)
-                    clearInterval(stamper);
-                await notifier.close();
-                await listener?.unlisten();
-                if (own)
-                    await sql.end({ timeout: 5 });
-                if (ownAdmin)
-                    await adminSql.end({ timeout: 5 });
+            closed: false,
+            close() {
+                // повторный close() ждёт первого; флаг — сразу: вызовы после close() отказывают api.closed, а не открывают пул
+                // заново (postgres.js reserve() после end() соединяется снова)
+                if (closing)
+                    return closing;
+                shared.closed = true;
+                closing = (async () => {
+                    // живые подписки закрываются: иначе с чужим пулом (connect({ sql })) они опрашивали бы журнал и после close()
+                    // (план 2.0, 7.4 №8)
+                    for (const s of [...subs])
+                        s.close();
+                    // идущий maintain() по расписанию доделывается: пул закрывается после него, а не посреди транзакции
+                    await stopMaintain?.();
+                    resync.stop();
+                    startReload.stop();
+                    if (stamper)
+                        clearInterval(stamper);
+                    cache?.clear();
+                    await notifier.close();
+                    await listener?.unlisten();
+                    if (own)
+                        await sql.end({ timeout: 5 });
+                    if (ownAdmin)
+                        await adminSql.end({ timeout: 5 });
+                })();
+                return closing;
             },
         };
         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';
@@ -29,7 +37,7 @@ export interface LoadOptions {
     /**
      * Загрузка от имени пользователя (§2.6, п. 10): автор версий — он; арендатор (по умолчанию —
      * собственный аккаунта) доступен ему; право WRITE на каждый класс и условия ACL на новые (и в
-     * existing: 'update' — прежние) значения строк; цели ссылок ему видны; владелец — по ownerDefault.
+     * existing: 'update' — прежние) значения строк; цели концов ему видны; владелец — по ownerDefault.
      */
     as?: string;
     /**
@@ -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>;
 }
 /** Состояние сессии первой заливки. */