letopis 1.4.2 → 3.0.0

package/dist/index.js

@@ -5,71 +5,75 @@
  * Этап 2: connect() — подключение под сессией, реестр классов, отложенный сигнал, db.sql.
  * Этап 3: цепочки чтения t.Класс(…).Связь().rows(); этап 4 — запись цепочками и загрузчик.
  * Этап 5: db.auth (креды, вход, сессии), db.acl, db.as(аккаунт, { tenant }) — имперсонация.
- * Этап 6: история (restore, purge, rekey, trimHistory), verify, maintain, reset, watch, кэш результатов.
+ * Этап 6: история (versions, asOf, restore), maintain, watch, кэш результатов.
  */
 import postgres from 'postgres';
-import { LetopisError, fromDbError, removed } 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 } from './load.js';
+import { load, LOAD_OPTIONS } from './load.js';
 import { makeBatch, startEntity, startStep } from './chain.js';
-import { DDL_REVISION } from './types.js';
+import { or as orFilters } from './ops.js';
+import { DDL_REVISION, SCHEMA_VERSION } from './types.js';
 import { ACL_CLASSES, ResultCache } from './cache.js';
 import { Subscription } from './watch.js';
-import { Projector } from './project.js';
 import { SIGNAL_MODES, Signals, bucket, throttle } from './signals.js';
-import { describe as describeModel, maintain as runMaintain, rebuildAggregates as runRebuildAggregates, rekeyClass as runRekeyClass, reset as runReset, MAINTAIN_STOP, parseInterval, scheduleMaintain, trimHistory as runTrim, verify as runVerify, } from './admin.js';
-import { stampDrift } from './up.js';
+import { maintain as runMaintain, parseInterval, scheduleMaintain, } from './admin.js';
+import { refuse1x, stampDrift } from './up.js';
 export { DDL_REVISION } from './types.js';
 export { uuidv5, v5Name, v5Id, idOf } from './uuid.js';
 export { LetopisError, ValidationError, fromDbError } from './errors.js';
 export { Registry } from './registry.js';
 export { compileValidator, applyDefaults } from './validate.js';
 export { syncModels, generateTypes, schemaToTs } from './sync.js';
-export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, isOp } from './ops.js';
+export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, isOp } from './ops.js';
+/**
+ * Хотя бы один из фильтров: `db.Product(or({ sku: 'K-1' }, { price: lt(500) }))` — товар K-1 или дешевле 500. Ставится
+ * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и». В шаге подключения
+ * с моделями (`TypedDb`) фильтры внутри — поля и роли класса шага: тип им даёт шаг (план 2.0, этап 4, п. 1). Та же
+ * фабрика, что в реестре операторов (ops.ts), — другой у неё только тип.
+ */
+export const or = orFilters;
 export { cursorOf } from './sql.js';
 export { inc, isInc } from './write.js';
 export { totpCode, hashPassword, verifyHash } from './auth.js';
-export { describeText } from './admin.js';
 export { up, createTenant } from './up.js';
 export { RESERVED_CLASS_NAMES, CHAIN_METHODS, DB_METHODS } from './types.js';
-/** Снесено в 1.0.0: id v7 больше не выдаются (§2.3). */
-export function uuidv7() {
-    throw removed('uuidv7()', 'uuidv5() и idOf(): id объекта вычисляется из ключа');
-}
-/** Снесено в 1.0.0: пространство имён v5 — id арендатора. Любое использование значения — ошибка. */
-export const LETOPIS_NS = new Proxy({}, {
-    get(_t, p) {
-        if (p === 'then')
-            return undefined;
-        throw removed('LETOPIS_NS', 'пространство имён v5 — id арендатора: idOf(класс, ключ, { tenant })');
-    },
-});
+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}$/;
-/** Опции 0.21, снятые в 1.0.0, и их замены (этап 3, п. 11). */
-const REMOVED_OPTIONS = {
-    partition: 'отдельные схемы установки (v2.<имя>)',
-    enforceAccount: 'изоляция арендаторов включена всегда (RLS)',
-    enforceAcl: 'права включены всегда (этап 5)',
-    container: 'Docker в up() не нужен',
-    image: 'Docker в up() не нужен',
-    dataDir: 'Docker в up() не нужен',
-    redisPort: 'Redis не нужен: сессии в базе',
-    version: 'версия схемы — константа движка',
+/** Все опции 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, 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)[имя]()`. Объект тот же: проверки во время выполнения (неизвестное имя или поле, переход, слот) не меняются.
+ */
+export function loose(db) {
+    return db;
+}
 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,14 +82,23 @@ function makeDb(sh, scope, exec, owner, tx) {
     // (актор, арендатор, владелец, транзакция), значит, в ней только планы, поставленные этим же фасадом
     const batches = new Map();
     const noTx = (what) => {
-        throw new LetopisError('tx_required', `${what} — только внутри db.begin()`);
+        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);
-    const acl = makeAcl(sh.S, exec);
-    const adm = { sql: sh.sql, schema: sh.schema, S: sh.S, txc, exec, registry: scope.registry, tenant: scope.tenant };
+    }, scope.root && !tx), log, 'auth', AUTH_LOG, { switch: () => scope.tenant() });
+    // запись правил (grant, deny, revoke, roles) идёт цепочками самого фасада — он объявлен ниже, берётся при вызове
+    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() администраторский пул не берут
+    const viaAdmin = scope.root && !tx && sh.adminSql ? sh.adminSql : null;
+    const adminReady = sh.adminReady ?? (async () => { });
+    const admCtx = () => {
+        const t = { ...txc, sql: viaAdmin };
+        return { ...adm, txc: t, exec: poolExecutor(t) };
+    };
     const core = {
         schema: sh.schema,
         get token() { return txc.token; },
@@ -93,31 +106,36 @@ 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 new LetopisError('no_session', 'idOf: нет арендатора сессии');
+                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(),
-        verify: (o) => runVerify(adm, o),
-        maintain: (o) => runMaintain(adm, o),
-        reset: async (o) => {
-            const r = await runReset(adm, o);
-            sh.passes.clear();
-            sh.cache?.clear();
-            return r;
-        },
-        trimHistory: (target, before) => runTrim(adm, target, before),
-        rekeyClass: (cls, key) => runRekeyClass(adm, cls, key),
-        describe: () => describeModel(adm),
-        watch: (o = {}) => {
-            if (typeof o === 'function' || typeof o === 'string')
-                throw removed('watch(cb) и watch(класс, cb)', 'watch({ from }) — подписка по курсору');
+        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;
             return sh.track(new Subscription({
@@ -136,16 +154,17 @@ 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 new LetopisError('invalid_query', 'db.as() — от корня подключения, а не внутри db.begin()');
+                throw lerr('api.as_in_tx');
             const id = account === null ? undefined : typeof account === 'object' ? account.id : account;
             const nextOwner = o?.owner ?? owner;
             if (id === undefined && o?.tenant === undefined) {
@@ -155,7 +174,7 @@ function makeDb(sh, scope, exec, owner, tx) {
             const scoped = { ...txc, account: id ?? txc.account, tenant: o?.tenant ?? (id === undefined ? txc.tenant : undefined) };
             let [r] = await runTx(scoped, (q) => q.unsafe(`select account, tenant from ${sh.S}.ctx()`), { read: true });
             if (!r?.account)
-                throw new LetopisError('no_session', 'db.as(): нет действующей сессии');
+                throw lerr('api.as_no_session');
             // контекст сессии между запросами ушёл из арендатора (сменился или кончился): реестр не загружен и не
             // кэширован (хвост ревью безопасности №3) — контекст читается заново, не больше трёх раз
             for (let attempt = 1;; attempt++) {
@@ -164,145 +183,181 @@ function makeDb(sh, scope, exec, owner, tx) {
                 if (registry)
                     return makeDb(sh, { txc: scoped, tenant: () => tenant, registry: () => sh.registryOf(tenant, registry, scoped), root: false }, poolExecutor(scoped), nextOwner);
                 if (attempt === 3)
-                    throw new LetopisError('no_session', 'db.as(): контекст сессии меняется — реестр арендатора не загружен');
+                    throw lerr('api.as_context_changing');
                 [r] = await runTx(scoped, (q) => q.unsafe(`select account, tenant from ${sh.S}.ctx()`), { read: true });
                 if (!r?.account)
-                    throw new LetopisError('no_session', 'db.as(): нет действующей сессии');
+                    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 new LetopisError('invalid_query', 'вложенных транзакций нет: db.begin() внутри db.begin()');
-            // причина блока ставится в начале транзакции (setupSql) и действует на все её операции
-            const btx = o?.reason !== undefined ? { ...txc, reason: checkReason(o.reason, 'db.begin()') } : txc;
+                throw lerr('api.nested_begin');
+            // причина блока ставится в начале транзакции (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)
-                throw new LetopisError('invalid_query', 'load() — своей транзакцией, не внутри db.begin()');
+                throw lerr('api.load_in_tx');
+            if (viaAdmin) {
+                await adminReady();
+                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);
-        },
-        projector: (name, o) => {
-            if (tx)
-                throw new LetopisError('invalid_query', 'projector() — от корня подключения, а не внутри db.begin()');
-            if (!sh.admin)
-                throw new LetopisError('admin_required', 'проектору нужно администраторское подключение (connect({ allowBypassRls: true }) роли, которая может стать владельцем схемы)');
-            return new Projector({
-                sql: sh.sql, schema: sh.schema, S: sh.S, ownerRole: sh.ownerRole,
-                ...(sh.listen ? { onSignal: (fn) => { sh.signals.add(fn); return () => void sh.signals.delete(fn); } } : {}),
-            }, name, o);
-        },
-        rebuildAggregates: async (cls) => {
-            if (tx)
-                throw new LetopisError('invalid_query', 'rebuildAggregates() — своей транзакцией, не внутри db.begin()');
-            if (!sh.admin)
-                throw new LetopisError('admin_required', 'ремонту агрегатов нужно администраторское подключение (connect({ allowBypassRls: true }) роли, которая может стать владельцем схемы)');
-            return runRebuildAggregates({ sql: sh.sql, S: sh.S, ownerRole: sh.ownerRole }, cls);
-        },
+        }, (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) => {
+        if (typeof prop === 'symbol' || prop in t)
+            return Reflect.get(t, prop, r);
+        if (prop === 'then')
+            return undefined;
+        // неизвестный класс или роль — событие 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) {
-            if (typeof prop === 'symbol' || prop in t)
-                return Reflect.get(t, prop, r);
-            switch (prop) {
-                case 'then':
-                    return undefined;
-                case 'reloadSchema':
-                    throw removed('reloadSchema()', 'реестр обновляется сам по сигналу; принудительно — db.refresh()');
-                case 'accounts':
-                case 'credentials':
-                case 'resources':
-                case 'rules':
-                    throw removed(`фасад db.${prop}`, 'системные классы Account, Resource, rule, member и db.auth (accounts.purge — db.auth.purgeAccount)');
-                case 'compact':
-                    throw removed('compact()', 'db.trimHistory(цель, момент), политика хранения history и history: false');
-            }
-            return startStep(chainCtx, prop);
+            return member(t, prop, r);
         },
     });
     // модули пакета (letopis/mcp) узнают обход RLS по самому подключению, а не со слов вызывающего (internal.ts)
-    registerDb(facade, { allTenants: sh.allTenants, explicit: Boolean(tx) });
+    registerDb(facade, {
+        allTenants: sh.allTenants, explicit: Boolean(tx), log,
+        ...(viaAdmin ? { adminTx: (fn) => adminReady().then(() => runTx({ ...txc, sql: viaAdmin }, fn)) } : {}),
+    });
     return facade;
 }
 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 new LetopisError('invalid_data', `connect: схема ${opts.schema} — нужно v<N>.<имя>`);
+        throw lerr('api.connect_schema', { schema: opts.schema });
     if (!opts.sql && !opts.dsn)
-        throw new LetopisError('invalid_data', 'connect: нужен dsn или sql');
-    for (const k of Object.keys(opts))
-        if (k in REMOVED_OPTIONS)
-            throw removed(`опция connect({ ${k} })`, REMOVED_OPTIONS[k]);
+        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') {
+        throw lerr('api.connect_admin_type');
+    }
     const own = !opts.sql;
     // timestamptz — строкой: Date в JS режет микросекунды, а на них держатся asOf и курсоры по времени
-    const sql = (opts.sql ?? postgres(opts.dsn, {
-        max: opts.max ?? 10,
-        onnotice: () => { },
-        types: { timestamptz: { to: 1184, from: [1184], serialize: (v) => (v instanceof Date ? v.toISOString() : v), parse: (v) => v } },
-    }));
+    const types = { timestamptz: { to: 1184, from: [1184], serialize: (v) => (v instanceof Date ? v.toISOString() : v), parse: (v) => v } };
+    // порог 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 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;
+    const adminReady = adminSql ? () => (adminChecked ??= (async () => {
+        const [a] = await adminSql `select r.rolsuper, pg_has_role(current_user, ${owner}, 'SET') as can_set from pg_roles r where r.rolname = current_user`;
+        if (!a?.rolsuper && !a?.can_set) {
+            throw lerr('api.connect_admin_role', { owner });
+        }
+    })().catch((e) => {
+        adminChecked = undefined;
+        throw e;
+    })) : undefined;
     try {
         // роль, которая обходит RLS, видела бы данные всех арендаторов (§2.9)
         // роли владельца нет (опечатка в owner) — понятная ошибка, а не сырая 42704 PostgreSQL (план 2.0, 7.5 №3)
         const [known] = await sql `select exists (select 1 from pg_roles where rolname = ${owner}) as ok`;
         if (!known.ok)
-            throw new LetopisError('invalid_data', `connect: роли владельца ${owner} в базе нет — проверьте опцию owner (по умолчанию letopis_owner)`);
+            throw lerr('api.connect_no_owner', { owner });
         const [role] = await sql `select r.rolsuper, r.rolbypassrls,
         pg_has_role(current_user, ${owner}, 'USAGE') as inherits, pg_has_role(current_user, ${owner}, 'SET') as can_set
       from pg_roles r where r.rolname = current_user`;
         const bypass = role.rolsuper || role.rolbypassrls || role.inherits || role.can_set;
         if (bypass && !opts.allowBypassRls) {
-            throw new LetopisError('bypass_rls', 'роль подключения обходит RLS (суперпользователь, BYPASSRLS или член роли-владельца); администраторское подключение — только с опцией allowBypassRls');
+            throw lerr('api.connect_bypass_rls');
         }
         if (bypass)
-            console.warn('letopis: администраторское подключение — RLS не действует, данные всех арендаторов видны');
-        let token = opts.token ?? null;
-        const apiKey = opts.apiKey ?? opts.service;
-        if (!token && apiKey) {
-            const [r] = await sql.unsafe(`select ${S}.login_apikey($1) as t`, [apiKey]).catch((e) => {
-                throw fromDbError(e);
-            });
-            token = r.t;
-        }
-        // ревизия движка: библиотека новее схемы — накат отстал (этап 6, п. 10)
+            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}`;
-        const rev = Number(/ddl_revision=(\d+)/.exec(String(rv?.c ?? ''))?.[1] ?? 0);
         if (!rv)
-            throw new LetopisError('invalid_data', `connect: схемы ${opts.schema} нет — установите её: up({ schema })`);
+            throw lerr('api.connect_no_schema', { schema: opts.schema });
+        const rev = Number(/ddl_revision=(\d+)/.exec(String(rv.c ?? ''))?.[1] ?? 0);
+        refuse1x(opts.schema, rev);
+        // библиотека новее схемы 2.x — накат отстал (этап 6, п. 10)
         if (rev < DDL_REVISION)
-            console.warn(`letopis: движок схемы ${opts.schema} ревизии ${rev}, библиотека ждёт ${DDL_REVISION} — обновите: up({ schema: '${opts.schema}', upgrade: true })`);
+            lwarn('api.schema_older', { schema: opts.schema, rev, want: DDL_REVISION }, { log: base });
         // схему обновил более новый пакет (во время раскатки старые экземпляры ещё работают): подключаемся, но предупреждаем —
         // этот пакет может не знать функций и колонок новой ревизии; up() такую схему не трогает и отказывает
         else if (rev > DDL_REVISION)
-            console.warn(`letopis: движок схемы ${opts.schema} ревизии ${rev} новее библиотеки (она знает ${DDL_REVISION}) — обновите пакет letopis`);
+            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;
+        if (!token && apiKey) {
+            const [r] = await sql.unsafe(`select ${S}.login_apikey($1) as t`, [apiKey]).catch((e) => {
+                throw fromDbError(e);
+            });
+            token = r.t;
         }
-        // режим сигналов установки (план 1.1, §2.2); схема, накатанная до него (нет signal_mode()), — class
+        // режим сигналов установки (план 1.1, §2.2)
         const [sm] = await sql.unsafe(`select ${S}.signal_mode() as m`).catch((e) => {
-            if (e.code === '42883')
-                return [{ m: 'class' }];
             throw fromDbError(e);
         });
         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';
@@ -312,7 +367,10 @@ export async function connect(opts) {
         // продление сессии (§2.9): отдельным вызовом не чаще раза в минуту; ошибка (реплика,
         // транзакции только для чтения) не мешает работе
         let refreshedAt = Date.now();
+        // время последней удачной операции: после простоя дольше минуты сессию проверяют до операции (ctx.before)
+        let lastOk = Date.now();
         const touch = () => {
+            lastOk = Date.now();
             if (!token || opts.refreshSession === false || Date.now() - refreshedAt < 60_000)
                 return;
             refreshedAt = Date.now();
@@ -320,8 +378,76 @@ 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)
+        if (apiKey && !opts.token) {
+            let renewing = null;
+            const exchange = async () => {
+                const [r] = await sql.unsafe(`select ${S}.login_apikey($1) as t`, [apiKey]);
+                const next = r?.t ? String(r.t) : null;
+                const want = root.tenant;
+                if (next && want) {
+                    await runTx({ sql, token: next, notifier: null }, async (q) => {
+                        const [t] = await q.unsafe(`select ${S}.ctx_tenant() as t`);
+                        if (String(t?.t ?? '').toLowerCase() !== want.toLowerCase())
+                            await q.unsafe(`select ${S}.auth_switch($1::uuid)`, [want]);
+                    }, { retries: 0 });
+                }
+                return next;
+            };
+            ctx.renew = async (failed) => {
+                // ключ уже обменян другим вызовом — достаточно нового токена
+                if (token && failed.token !== token) {
+                    failed.token = token;
+                    return true;
+                }
+                renewing ??= exchange().catch(() => null).finally(() => {
+                    renewing = null;
+                });
+                const next = await renewing;
+                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;
+                refreshedAt = Date.now();
+                return true;
+            };
+        }
+        // после простоя дольше минуты — продление до операции: сессия, истёкшая по простою, даёт no_session (подключение по
+        // ключу выдаёт новую), а не анонимное чтение с пустым ответом; ошибка продления другого рода (реплика, транзакция
+        // только для чтения) работе не мешает, как у touch
+        let checking = null;
+        const checkSession = async () => {
+            try {
+                await runTx({ sql, token, notifier: null }, (q) => q.unsafe(`select ${S}.auth_refresh()`), { retries: 0 });
+            }
+            catch (e) {
+                if (!(e instanceof LetopisError && e.code === 'no_session'))
+                    return;
+                if (!ctx.renew || !(await ctx.renew(ctx)))
+                    throw e;
+            }
+            refreshedAt = lastOk = Date.now();
+        };
+        ctx.before = async (c) => {
+            if (!token || opts.refreshSession === false || Date.now() - lastOk < 60_000)
+                return;
+            checking ??= checkSession().finally(() => {
+                checking = null;
+            });
+            await checking;
+            if (token && c.token !== token)
+                c.token = token;
+        };
         // классы арендатора tenant под контекстом txc; null — контекст уже не в этом арендаторе (сессия кончилась,
         // пользователь выбыл из арендатора): тогда прежний реестр остаётся, а не пустеет (доработки после точки Б)
         const loadClasses = (txc, tenant) => runTx(txc, async (q) => {
@@ -347,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;
@@ -411,15 +544,22 @@ export async function connect(opts) {
                     return null;
                 throw e;
             });
-            // ключ сменился (reset({ all })): ответы с токенами старого ключа сигналы больше не узнают
+            // ключ сменился: ответы с токенами старого ключа сигналы больше не узнают
             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();
-        // ключ, реестр и пропуска прав — заново по *, незнакомому токену, нагрузке не по режиму, а у процесса
-        // без ключа в режиме opaque — по любому сигналу; не чаще раза в 5 с: заливка канала (в том числе
-        // поддельными сигналами) не становится потоком перечитываний
+        // ключ, реестр и пропуска прав — заново после переподключения слушателя, по незнакомому токену, нагрузке не по
+        // режиму, а у процесса без ключа в режиме opaque — по любому сигналу; не чаще раза в 5 с: заливка канала (в том
+        // числе поддельными сигналами) не становится потоком перечитываний
         const resync = throttle(() => {
             passes.clear();
             void fetchKey().then(() => refresh()).catch(() => { });
@@ -462,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')
@@ -475,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;
@@ -508,9 +652,10 @@ 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 } : {}),
             cache,
             sig,
             allTenants: Boolean(bypass),
@@ -526,7 +671,7 @@ export async function connect(opts) {
                 // (план 2.0, 7.4 №8)
                 for (const s of [...subs])
                     s.close();
-                // идущий maintain() по расписанию доделывает пачку: пул закрывается после неё, а не посреди транзакции
+                // идущий maintain() по расписанию доделывается: пул закрывается после него, а не посреди транзакции
                 await stopMaintain?.();
                 resync.stop();
                 startReload.stop();
@@ -536,16 +681,28 @@ export async function connect(opts) {
                 await listener?.unlisten();
                 if (own)
                     await sql.end({ timeout: 5 });
+                if (ownAdmin)
+                    await adminSql.end({ timeout: 5 });
             },
         };
         const db = makeDb(shared, { txc: ctx, tenant: () => root.tenant, registry: () => root.registry, root: true }, poolExecutor(ctx));
         if (maintainEvery !== undefined)
-            stopMaintain = scheduleMaintain((stopped) => db.maintain({ [MAINTAIN_STOP]: stopped }), 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) {
         if (own)
             await sql.end({ timeout: 1 });
+        if (ownAdmin)
+            await adminSql.end({ timeout: 1 });
         throw e;
     }
 }