letopis 1.4.2 → 2.0.0

package/dist/index.js

@@ -5,10 +5,10 @@
  * Этап 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 } from './errors.js';
 import { Registry } from './registry.js';
 import { AclPasses, ExplicitTx, Notifier, poolExecutor, runTx } from './tx.js';
 import { checkReason } from './write.js';
@@ -16,53 +16,51 @@ import { limits, registerDb } from './internal.js';
 import { makeAuth } from './auth.js';
 import { 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 { or as orFilters } from './ops.js';
 import { DDL_REVISION } 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 })');
-    },
-});
 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,
 };
+/** Опции watch() (WatchOptions). */
+const WATCH_OPTIONS = { from: true, classes: true, batch: true, pollMs: 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) {
@@ -78,14 +76,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 () => {
         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 };
+    // запись правил (grant, deny, revoke, roles) идёт цепочками самого фасада — он объявлен ниже, берётся при вызове
+    const acl = makeAcl(sh.S, exec, () => facade);
+    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; },
@@ -98,26 +105,15 @@ function makeDb(sh, scope, exec, owner, tx) {
         idOf: (cls, key) => {
             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,
         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),
+        maintain: () => (viaAdmin ? adminReady().then(() => runMaintain(admCtx())) : runMaintain(adm)),
         watch: (o = {}) => {
-            if (typeof o === 'function' || typeof o === 'string')
-                throw removed('watch(cb) и watch(класс, cb)', 'watch({ from }) — подписка по курсору');
+            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({
@@ -145,7 +141,7 @@ function makeDb(sh, scope, exec, owner, tx) {
         entity: (x) => startEntity(chainCtx, x),
         as: async (account, o) => {
             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 +151,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,42 +160,31 @@ 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) => {
             if (tx)
-                throw new LetopisError('invalid_query', 'вложенных транзакций нет: db.begin() внутри db.begin()');
+                throw lerr('api.nested_begin');
             // причина блока ставится в начале транзакции (setupSql) и действует на все её операции
             const btx = o?.reason !== undefined ? { ...txc, reason: checkReason(o.reason, 'db.begin()') } : txc;
             const t = await ExplicitTx.open(btx);
             return makeDb(sh, btx === txc ? scope : { ...scope, txc: btx }, t, owner, t);
         },
         load: async (input, o) => {
+            // опции — до всего прочего: неизвестная — отказ раньше 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);
-        },
         batch: (name, o) => {
             let q = batches.get(name);
             if (!q)
@@ -211,93 +196,104 @@ function makeDb(sh, scope, exec, owner, tx) {
         rollback: async (tr) => (tr ? tr.rollback() : tx ? tx.rollback() : noTx('rollback()')),
         close: () => (tx ? tx.rollback() : sh.close()),
     };
+    /** Свойство фасада: служебное — из core, иначе шаг класса, алиаса или роли. */
+    const member = (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);
+    };
     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),
+        ...(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);
     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');
     // интервал обслуживания — до пула и таймеров: неверный не оставляет за собой открытых соединений
     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 } };
+    const sql = (opts.sql ?? postgres(opts.dsn, { max: opts.max ?? 10, onnotice: () => { }, types }));
+    // один процесс (план 2.0, 7.9 №3): пул администратора postgres.js соединяется при первом запросе — до первого
+    // администраторского вызова соединений у него нет
+    const ownAdmin = typeof opts.admin === 'string';
+    const adminSql = (typeof opts.admin === 'string'
+        ? postgres(opts.admin, { max: 2, onnotice: () => { }, types, connection: { application_name: 'letopis admin' } })
+        : opts.admin);
     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');
+        // ревизия движка — до первого вызова функций схемы (вход по ключу): схема 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 });
         // схему обновил более новый пакет (во время раскатки старые экземпляры ещё работают): подключаемся, но предупреждаем —
         // этот пакет может не знать функций и колонок новой ревизии; 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 });
         else {
             // ревизия та же, а функции схемы ставила другая версия движка — штамп в комментарии схемы (99-revision.sql)
             const drift = await stampDrift(opts.schema, String(rv.c ?? ''));
             if (drift)
                 console.warn(drift);
         }
-        // режим сигналов установки (план 1.1, §2.2); схема, накатанная до него (нет signal_mode()), — class
+        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)
         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';
@@ -312,7 +308,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();
@@ -322,6 +321,69 @@ export async function connect(opts) {
         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() };
+        // подключение по ключу 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)
+                    return false;
+                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) => {
@@ -411,15 +473,15 @@ export async function connect(opts) {
                     return null;
                 throw e;
             });
-            // ключ сменился (reset({ all })): ответы с токенами старого ключа сигналы больше не узнают
+            // ключ сменился: ответы с токенами старого ключа сигналы больше не узнают
             if (sig.setKey(key))
                 cache?.clear();
         };
         await fetchKey();
         await refresh();
-        // ключ, реестр и пропуска прав — заново по *, незнакомому токену, нагрузке не по режиму, а у процесса
-        // без ключа в режиме opaque — по любому сигналу; не чаще раза в 5 с: заливка канала (в том числе
-        // поддельными сигналами) не становится потоком перечитываний
+        // ключ, реестр и пропуска прав — заново после переподключения слушателя, по незнакомому токену, нагрузке не по
+        // режиму, а у процесса без ключа в режиме opaque — по любому сигналу; не чаще раза в 5 с: заливка канала (в том
+        // числе поддельными сигналами) не становится потоком перечитываний
         const resync = throttle(() => {
             passes.clear();
             void fetchKey().then(() => refresh()).catch(() => { });
@@ -511,6 +573,7 @@ export async function connect(opts) {
             sql, schema: opts.schema, S, notifier, passes, root, registryFor, registryOf, refresh, onQuery: opts.onQuery, slowMs: opts.slowMs,
             admin: Boolean(bypass && (role.rolsuper || role.can_set)),
             ownerRole: owner,
+            ...(adminSql ? { adminSql, adminReady } : {}),
             cache,
             sig,
             allTenants: Boolean(bypass),
@@ -526,7 +589,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 +599,20 @@ 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);
         return db;
     }
     catch (e) {
         if (own)
             await sql.end({ timeout: 1 });
+        if (ownAdmin)
+            await adminSql.end({ timeout: 1 });
         throw e;
     }
 }

package/dist/internal.d.ts

@@ -9,6 +9,11 @@ export interface DbInternals {
     readonly allTenants: boolean;
     /** Фасад явной транзакции db.begin(). */
     readonly explicit: boolean;
+    /**
+     * Транзакция на администраторском пуле connect({ admin }) с сессией фасада (план 2.0, 7.9 №3): ею пишет syncModels.
+     * Только у корня подключения с опцией admin.
+     */
+    readonly adminTx?: <T>(fn: (tx: import('./tx.js').Tx) => Promise<T>) => Promise<T>;
 }
 /**
  * Пределы подключения, которых нет в опциях: реестров классов db.as() — не больше asRegistries арендаторов (план 2.0,