letopis 1.4.0 → 1.4.2

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export { syncModels, generateTypes, schemaToTs, type SyncResult } from './sync.j
 export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, isOp } from './ops.js';
 export { cursorOf } from './sql.js';
 export { inc, isInc, type IncMarker, type WriteRow } from './write.js';
-export { totpCode, hashPassword, verifyHash, type AuthApi, type LoginResult, type Credential } from './auth.js';
+export { totpCode, hashPassword, verifyHash, type AuthApi, type LoginResult, type Credential, type SessionInfo } from './auth.js';
 export type { AclApi, AclDecision, AclDataDecision, AclOp } from './acl.js';
 export type { LoadOptions, LoadReport, LoadIssue, LoadInput } from './load.js';
 export type { Chain, ChainCore, StepFn, BatchEntry } from './chain.js';
@@ -54,36 +54,41 @@ export interface ConnectOptions {
     sql?: postgres.Sql;
     /** Схема установки, например `v2.salon`. */
     schema: string;
-    /** Токен сессии; либо ключ APIKEY в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
+    /** Токен сессии; либо ключ `APIKEY` в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
     token?: string;
     apiKey?: string;
     service?: string;
     /** Продлевать сессию раз в минуту работы (по умолчанию да, §2.9). */
     refreshSession?: boolean;
-    /** Разрешить роль, которая обходит RLS (суперпользователь, BYPASSRLS, член роли-владельца), — администраторское подключение (§2.9). */
+    /** Разрешить роль, которая обходит RLS (суперпользователь, `BYPASSRLS`, член роли-владельца), — администраторское подключение (§2.9). */
     allowBypassRls?: boolean;
-    /** Имя роли-владельца (по умолчанию letopis_owner). */
+    /** Имя роли-владельца (по умолчанию `letopis_owner`). */
     owner?: string;
     /** Интервал отправки отложенного сигнала, мс (по умолчанию 100; решение 9 точки А). */
     notifyIntervalMs?: number;
-    /** Размер пула, если подключение создаёт сам connect(). */
+    /** Размер пула, если подключение создаёт сам `connect()`. */
     max?: number;
     /** Хук на каждый запрос цепочки (метрики, лог). */
     onQuery?: (e: QueryEvent) => void;
-    /** Порог медленного запроса, мс: событие получает slow; без onQuery — console.warn. */
+    /** Порог медленного запроса, мс: событие получает `slow`; без `onQuery` — `console.warn`. */
     slowMs?: number;
-    /** Модели letopis/model — только для типов цепочек (TypedDb); описания классов берутся из базы. */
+    /** Модели `letopis/model` — только для типов цепочек (`TypedDb`); описания классов берутся из базы. */
     models?: readonly AnyModelLike[];
     /**
-     * Слушать сигналы базы (LISTEN, по умолчанию да). false — пул в режиме транзакций (PgBouncer):
-     * реестр перечитывается через db.refresh(), подписка опрашивает журнал, кэш результатов выключен
-     * (с cache: { ttlOnly: true } — работает только по сроку). В установке с up({ signals: 'none' })
-     * слушателя нет всегда, а реестр раз в 5 с сверяет отпечаток классов.
+     * Слушать сигналы базы (`LISTEN`). `false` — для пула в режиме транзакций (PgBouncer): тогда реестр классов сам не
+     * обновляется (новые и изменённые классы подключение увидит после `db.refresh()`), подписка `watch()` только опрашивает
+     * журнал, а кэш результатов работает лишь с `cache: { ttlOnly: true }` — по сроку. В установке с
+     * `up({ signals: 'none' })` так всегда, только изменения классов подключение раз в 5 секунд проверяет само.
      */
     listen?: boolean;
-    /** Кэш результатов (§2.12): срок по умолчанию, размер, ttlOnly; false — выключен. */
+    /** Кэш результатов (§2.12): срок по умолчанию, размер, `ttlOnly`; `false` — выключен. */
     cache?: CacheOptions | false;
-    /** Запускать maintain() по расписанию ('1h', '15m', мс) под блокировкой обслуживания: работает один процесс. */
+    /**
+     * Запускать `maintain()` по расписанию: интервал — число миллисекунд или строка вроде `'15m'`, `'1h'`, от 1 мс до
+     * 2³¹−1 мс (около 24 суток); иначе `connect()` отказывает с `invalid_data`, не открывая соединений. Если обслуживание в
+     * этот момент уже ведёт другой процесс или ещё идёт прошлый запуск, запуск пропускается. `close()` ждёт, пока идущий
+     * запуск доделает текущую пачку.
+     */
     maintain?: string | number;
 }
 export interface DbCore {
@@ -92,50 +97,72 @@ export interface DbCore {
     /** Арендатор сессии. */
     readonly tenant: string | null;
     readonly registry: Registry;
-    /** Креды, вход и сессии (этап 5). */
+    /**
+     * Вход и сессии: способы входа (креды) — пароль, ключ API, TOTP, одноразовый код из письма или СМС, привязка внешней
+     * учётной записи; вход по ним, выпуск и гашение сессий, выбор арендатора сессии.
+     */
     readonly auth: AuthApi;
-    /** Решения прав: check(endpoint), checkData(class, op) (этап 5). */
+    /**
+     * Права того, от чьего имени идёт запрос, — заранее, для интерфейса и проверок в приложении: `check(endpoint)` — можно
+     * ли обратиться к ресурсу приложения, `checkData(класс, операция)` — можно ли читать, менять или удалять объекты
+     * класса. Сами права база применяет при каждом запросе.
+     */
     readonly acl: AclApi;
-    /** Сырой SQL под сессией и RLS, одной транзакцией (в db.begin() — в ней): db.sql`select …`. */
+    /** Сырой SQL под сессией и RLS, одной транзакцией (в `db.begin()` — в ней): `` db.sql`select …` ``. */
     sql(strings: TemplateStringsArray, ...values: unknown[]): Promise<postgres.Row[]>;
-    /** Транзакция под сессией: fn получает соединение postgres.js (в db.begin() — ту же транзакцию). */
+    /** Транзакция под сессией: `fn` получает соединение postgres.js (в `db.begin()` — ту же транзакцию). */
     transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
-    /** id объекта класса с ключом в арендаторе сессии. */
+    /** id объекта по классу и значениям ключа — такой же, какой вычислит база в арендаторе сессии. */
     idOf(cls: string, key: Readonly<Record<string, unknown>>): string;
     /** Перечитать описания классов. */
     refresh(): Promise<void>;
     /** Отправить накопленные сигналы сейчас. */
     flushSignals(): Promise<void>;
     /**
-     * Проверка цепочек хэшей и якорь (хэш всех голов); { data: true } — ещё данные, концы, арендаторы,
-     * владельцы и id всех строк. Только системный администратор или администраторское подключение.
+     * Проверяет целостность журнала всей установки: сходится ли хэш каждой версии с хэшем предыдущей и текущая строка
+     * объекта — с его последней версией; с `{ data: true }` проверяет ещё каждую строку. Якорь в ответе — один хэш текущих
+     * версий всех объектов: храните его вне базы, тогда заметна и подмена самых свежих версий. Нужно право `letopis.verify`
+     * (по умолчанию оно у системного администратора) или администраторское подключение.
      */
     verify(opts?: {
         data?: boolean;
     }): Promise<VerifyResult>;
     /** Обслуживание: истёкшие сессии и коды, прореживание журнала по политике хранения, очередь сигналов. */
     maintain(opts?: MaintainOptions): Promise<MaintainReport>;
-    /** Сброс sessions | tenant | all (allowReset установки, право letopis.reset, confirm — имя схемы). */
+    /**
+     * Сбрасывает тестовую установку: сессии, данные одного арендатора или всё — смотря по `level`. Работает, только если
+     * установка поставлена с `up({ allowReset: true })`, у вызывающего есть право `letopis.reset` (или подключение
+     * администраторское), а `confirm` совпадает с именем схемы.
+     */
     reset(opts: ResetOptions): Promise<ResetResult>;
-    /** Обрезка истории до момента: класса (с потомками), id, списка id или строк; версия 1 → запись trim. */
+    /**
+     * Стирает версии, сделанные раньше момента `before`; текущая версия остаётся всегда. Вместо стёртого начала истории
+     * остаётся служебная запись `trim` со временем появления объекта.
+     */
     trimHistory(target: string | string[] | Row | Row[], before: string | Date): Promise<number>;
-    /** Новый ключ класса: строки семейства переносятся на новые id, ссылки переводятся. */
+    /**
+     * Меняет ключ класса. Объекты его семейства (сам класс и потомки), у которых по новому ключу выходит другой id,
+     * переезжают на новый id, а ссылки на них переводятся.
+     */
     rekeyClass(cls: string, key: string[]): Promise<number>;
-    /** Машинное описание модели с метаданными классов (describeText — то же текстом, llms.txt). */
+    /**
+     * Описание модели для программ и языковых моделей: классы арендатора сессии и общие классы System с полями, ключом,
+     * ссылками и метаданными `meta`. `describeText(db.describe())` превращает его в текст.
+     */
     describe(): ModelDescription;
-    /** Подписка по курсору: for await (const ev of db.watch({ from })) …; ev.cursor — откуда продолжить. */
+    /** Подписка по курсору: `for await (const ev of db.watch({ from })) …`; `sub.cursor` — откуда продолжить. */
     watch(opts?: WatchOptions): Subscription;
     /** Кэш результатов подключения. */
     readonly cache: {
         clear(): void;
         stats(): CacheStats;
     };
-    /** Начать путь с готового узла: db.entity(row | цепочка). */
+    /** Начать путь с готового узла: `db.entity(row | цепочка)`. */
     entity(x: Chain | Row): Chain;
     /**
-     * Тот же пул от имени аккаунта (letopis.account: имперсонацию проверяет база — право сервиса
-     * auth.impersonate), в арендаторе tenant (собственный аккаунта или по членству) и с явным владельцем
-     * новых строк: await db.as(account, { tenant, owner }). account = null — тот же актор.
+     * Подключение на том же пуле от имени другого аккаунта: запросы идут с его правами и в его арендаторе. Журнал
+     * записывает автором версий этот аккаунт, а исполнителем (`agent`) — аккаунт сессии, например сервис. Нужно право
+     * `auth.impersonate`.
      */
     as(account: string | {
         id: string;
@@ -143,50 +170,51 @@ export interface DbCore {
         owner?: string;
         tenant?: string;
     }): Promise<Db>;
-    /** Явная транзакция read committed: те же цепочки, commit(), rollback(), lock(), forUpdate(). */
-    /** Явная транзакция; reason — причина изменения для всех операций блока (план 1.1). */
+    /** Явная транзакция `read committed`: те же цепочки, `commit()`, `rollback()`, `lock()`, `forUpdate()`; `reason` — причина изменения для всех операций блока (план 1.1). */
     begin(opts?: {
         reason?: string;
     }): Promise<DbTx>;
     /**
-     * Загрузчик (§2.6): строки любых классов — проверки в коде, COPY от роли владельца, один запрос по
-     * целям вне загрузки. Только на администраторском подключении (иначе admin_required).
+     * Массовая загрузка строк любых классов одной транзакцией (или порциями `commitEvery`) — быстрее записи цепочками.
+     * Строки проверяются по тому же описанию класса, что и при обычной записи (данные, ссылки, ключ), уходят в базу
+     * командой `COPY`, а ссылки на объекты вне загрузки сверяет один запрос в конце; права проверяются только при загрузке
+     * от имени пользователя (опция `as`). Работает только на администраторском подключении, иначе `admin_required`.
      */
     load(input: LoadInput, opts?: LoadOptions): Promise<LoadReport>;
     /**
-     * Проектор из журнала (план 1.1, §2.4): строит строки производных классов (derivedBy: имя) из изменений
-     * классов from; run() — догнать журнал и следовать за ним, rebuild() — перестроить с текущего состояния.
-     * Только на администраторском подключении (иначе admin_required).
+     * Проектор из журнала (план 1.1, §2.4): строит строки производных классов (`derivedBy: имя`) из изменений
+     * классов `from`; `run()` — догнать журнал и следовать за ним, `rebuild()` — перестроить с текущего состояния.
+     * Только на администраторском подключении (иначе `admin_required`).
      */
     projector(name: string, opts: ProjectorOptions): Projector;
     /**
      * Ремонт агрегатов в базе (план 1.1, §2.4): поля класса (с потомками) во всех арендаторах — заново из живых строк
      * источников, под исключительными блокировками; версия — только у исправленных. Возвращает их число. Только на
-     * администраторском подключении (иначе admin_required).
+     * администраторском подключении (иначе `admin_required`).
      */
     rebuildAggregates(cls: string): Promise<number>;
     /**
-     * Именованная очередь планов фасада: batch.Класс(…).create(…); batch.run() — одной транзакцией. У корня,
-     * у каждого db.as() и у каждой db.begin() очереди свои: план исполняется от имени фасада, который его поставил.
+     * Именованная очередь планов фасада: `batch.Класс(…).create(…)`; `batch.run()` — одной транзакцией. У корня,
+     * у каждого `db.as()` и у каждой `db.begin()` очереди свои: план исполняется от имени фасада, который его поставил.
      */
     batch(name: string, opts?: {
         reason?: string;
     }): Batch;
-    /** Advisory-блокировка до конца транзакции — только в db.begin() (иначе tx_required). */
+    /** Advisory-блокировка до конца транзакции — только в `db.begin()` (иначе `tx_required`). */
     lock(...keys: (string | number)[]): Promise<void>;
-    /** Зафиксировать транзакцию tr (то же, что tr.commit()). */
+    /** Зафиксировать транзакцию `tr` (то же, что `tr.commit()`). */
     commit(tr?: DbTx): Promise<void>;
-    /** Откатить транзакцию tr (то же, что tr.rollback()). */
+    /** Откатить транзакцию `tr` (то же, что `tr.rollback()`). */
     rollback(tr?: DbTx): Promise<void>;
     close(): Promise<void>;
 }
-/** Подключение: служебные методы и классы как стартовые шаги цепочек — db.Класс(фильтр). */
+/** Подключение: служебные методы и классы как стартовые шаги цепочек — `db.Класс(фильтр)`. */
 export type Db = DbCore & {
     [className: string]: StepFn;
 };
-/** Явная транзакция db.begin(): тот же API; ошибка любого запроса её ломает (§2.5). */
+/** Явная транзакция `db.begin()`: тот же API; ошибка любого запроса её ломает (§2.5). */
 export type DbTx = Db;
-/** Подключение с типами шагов, строк и фильтров по моделям: connect({ models }). */
+/** Подключение с типами шагов, строк и фильтров по моделям: `connect({ models })`. */
 export type TypedDb<M extends readonly AnyModelLike[]> = DbCore & StepsOf<M> & {
     [className: string]: StepFn;
 };

package/dist/index.js

@@ -12,7 +12,7 @@ import { LetopisError, fromDbError, removed } from './errors.js';
 import { Registry } from './registry.js';
 import { AclPasses, ExplicitTx, Notifier, poolExecutor, runTx } from './tx.js';
 import { checkReason } from './write.js';
-import { registerDb } from './internal.js';
+import { limits, registerDb } from './internal.js';
 import { makeAuth } from './auth.js';
 import { makeAcl } from './acl.js';
 import { idOf as idOfClass } from './uuid.js';
@@ -23,7 +23,7 @@ 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, scheduleMaintain, trimHistory as runTrim, verify as runVerify, } from './admin.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';
 export { DDL_REVISION } from './types.js';
 export { uuidv5, v5Name, v5Id, idOf } from './uuid.js';
@@ -120,13 +120,23 @@ function makeDb(sh, scope, exec, owner, tx) {
                 throw removed('watch(cb) и watch(класс, cb)', 'watch({ from }) — подписка по курсору');
             const reg = scope.registry();
             const classes = o.classes ? [...new Set(o.classes.flatMap((c) => reg.family(c).map((x) => x.name)))] : null;
-            return new Subscription({
-                S: sh.S, exec: poolExecutor(txc), classes,
+            return sh.track(new Subscription({
+                S: sh.S, exec: poolExecutor(txc), classes, onClose: (s) => void sh.subs.delete(s),
+                // не бросает: класс удалили — список, снятый при watch(); иначе ошибка в общем разборе сигналов остановила бы
+                // доставку другим подписчикам
+                ...(o.classes ? { classesOf: () => {
+                        try {
+                            return [...new Set(o.classes.flatMap((c) => scope.registry().family(c).map((x) => x.name)))];
+                        }
+                        catch {
+                            return classes;
+                        }
+                    } } : {}),
                 ...(sh.listen ? {
                     onSignal: (fn) => { sh.signals.add(fn); return () => void sh.signals.delete(fn); },
                     tenant: () => (sh.allTenants ? null : sh.sig.tenantToken(scope.tenant())),
                 } : {}),
-            }, o);
+            }, o));
         },
         cache: {
             clear: () => sh.cache?.clear(),
@@ -152,7 +162,7 @@ function makeDb(sh, scope, exec, owner, tx) {
                 const tenant = r.tenant;
                 const registry = await sh.registryFor(tenant, scoped);
                 if (registry)
-                    return makeDb(sh, { txc: scoped, tenant: () => tenant, registry: () => registry, root: false }, poolExecutor(scoped), nextOwner);
+                    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(): контекст сессии меняется — реестр арендатора не загружен');
                 [r] = await runTx(scoped, (q) => q.unsafe(`select account, tenant from ${sh.S}.ctx()`), { read: true });
@@ -233,6 +243,8 @@ export async function connect(opts) {
     for (const k of Object.keys(opts))
         if (k in REMOVED_OPTIONS)
             throw removed(`опция connect({ ${k} })`, REMOVED_OPTIONS[k]);
+    // интервал обслуживания — до пула и таймеров: неверный не оставляет за собой открытых соединений
+    const maintainEvery = opts.maintain === undefined ? undefined : parseInterval(opts.maintain);
     const own = !opts.sql;
     // timestamptz — строкой: Date в JS режет микросекунды, а на них держатся asOf и курсоры по времени
     const sql = (opts.sql ?? postgres(opts.dsn, {
@@ -244,6 +256,10 @@ export async function connect(opts) {
     const owner = opts.owner ?? 'letopis_owner';
     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)`);
         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`;
@@ -268,7 +284,11 @@ export async function connect(opts) {
             throw new LetopisError('invalid_data', `connect: схемы ${opts.schema} нет — установите её: up({ schema })`);
         if (rev < DDL_REVISION)
             console.warn(`letopis: движок схемы ${opts.schema} ревизии ${rev}, библиотека ждёт ${DDL_REVISION} — обновите: up({ schema: '${opts.schema}', upgrade: true })`);
-        else if (rev === DDL_REVISION) {
+        // схему обновил более новый пакет (во время раскатки старые экземпляры ещё работают): подключаемся, но предупреждаем —
+        // этот пакет может не знать функций и колонок новой ревизии; up() такую схему не трогает и отказывает
+        else if (rev > DDL_REVISION)
+            console.warn(`letopis: движок схемы ${opts.schema} ревизии ${rev} новее библиотеки (она знает ${DDL_REVISION}) — обновите пакет letopis`);
+        else {
             // ревизия та же, а функции схемы ставила другая версия движка — штамп в комментарии схемы (99-revision.sql)
             const drift = await stampDrift(opts.schema, String(rv.c ?? ''));
             if (drift)
@@ -310,8 +330,18 @@ export async function connect(opts) {
                 return null;
             return q.unsafe(`select tenant, rev, data from ${S}.entity where class = 'Class' and tenant in (${S}.ctx_tenant(), '${SYSTEM_ID}')`);
         }, { read: true });
-        // реестры db.as() — общие на арендатора; txc — контекст последнего успешного as() этого арендатора
+        // реестры db.as() — общие на арендатора; txc — контекст последнего успешного as() этого арендатора. Порядок карты —
+        // давность обращения: сверх limits.asRegistries вытесняется самый давний (план 2.0, 7.4 №8 — иначе процесс,
+        // который ходит от имени многих арендаторов, копил бы реестры и перечитывал их все на каждый сигнал классов)
         const others = new Map();
+        let latest = null;
+        const keep = (tenant, entry) => {
+            latest = tenant;
+            others.delete(tenant);
+            others.set(tenant, entry);
+            while (others.size > Math.max(1, limits.asRegistries))
+                others.delete(others.keys().next().value);
+        };
         const loading = new Map();
         // токены классов (режим opaque) — по именам всех реестров подключения
         const tokens = () => sig.setClasses([root.registry, ...[...others.values()].map((o) => o.registry)].flatMap((r) => r.all().map((c) => c.name)));
@@ -337,7 +367,7 @@ export async function connect(opts) {
         const registryFor = async (tenant, txc) => {
             const known = others.get(tenant);
             if (known) {
-                known.txc = txc;
+                keep(tenant, { registry: known.registry, txc });
                 return known.registry;
             }
             // одновременные as() нового арендатора получают один реестр
@@ -349,7 +379,7 @@ export async function connect(opts) {
                         return null;
                     const registry = new Registry();
                     registry.load(rows);
-                    others.set(tenant, { registry, txc });
+                    keep(tenant, { registry, txc });
                     tokens();
                     return registry;
                 })().finally(() => loading.delete(tenant));
@@ -357,6 +387,20 @@ export async function connect(opts) {
             }
             return pending;
         };
+        // фасад db.as() берёт реестр через карту: свежий реестр арендатора, если его перечитал другой as(); вытесненный —
+        // обратно в карту (его снова обновляют сигналы) и перечитать фоном: пока он был вне карты, сигналы его не трогали
+        const registryOf = (tenant, registry, txc) => {
+            const cur = others.get(tenant);
+            if (cur) {
+                if (latest !== tenant)
+                    keep(tenant, cur);
+                return cur.registry;
+            }
+            keep(tenant, { registry, txc });
+            void loadClasses(txc, tenant).then((rows) => { if (rows)
+                registry.load(rows); }).catch(() => { }).finally(tokens);
+            return registry;
+        };
         // ключ сигналов (режимы tenant и opaque) — сессии с правом letopis.signals; без права процесс
         // работает без ключа: арендатора (а в opaque — и класса) в сигнале не различает
         const fetchKey = async () => {
@@ -462,8 +506,9 @@ export async function connect(opts) {
             stamper.unref?.();
         }
         let stopMaintain = null;
+        const subs = new Set();
         const shared = {
-            sql, schema: opts.schema, S, notifier, passes, root, registryFor, refresh, onQuery: opts.onQuery, slowMs: opts.slowMs,
+            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,
             cache,
@@ -471,8 +516,18 @@ export async function connect(opts) {
             allTenants: Boolean(bypass),
             signals,
             listen,
+            subs,
+            track: (s) => {
+                subs.add(s);
+                return s;
+            },
             async close() {
-                stopMaintain?.();
+                // живые подписки закрываются: иначе с чужим пулом (connect({ sql })) они опрашивали бы журнал и после close()
+                // (план 2.0, 7.4 №8)
+                for (const s of [...subs])
+                    s.close();
+                // идущий maintain() по расписанию доделывает пачку: пул закрывается после неё, а не посреди транзакции
+                await stopMaintain?.();
                 resync.stop();
                 startReload.stop();
                 if (stamper)
@@ -484,8 +539,8 @@ export async function connect(opts) {
             },
         };
         const db = makeDb(shared, { txc: ctx, tenant: () => root.tenant, registry: () => root.registry, root: true }, poolExecutor(ctx));
-        if (opts.maintain !== undefined)
-            stopMaintain = scheduleMaintain(() => db.maintain(), opts.maintain);
+        if (maintainEvery !== undefined)
+            stopMaintain = scheduleMaintain((stopped) => db.maintain({ [MAINTAIN_STOP]: stopped }), maintainEvery);
         return db;
     }
     catch (e) {

package/dist/internal.d.ts

@@ -10,6 +10,13 @@ export interface DbInternals {
     /** Фасад явной транзакции db.begin(). */
     readonly explicit: boolean;
 }
+/**
+ * Пределы подключения, которых нет в опциях: реестров классов db.as() — не больше asRegistries арендаторов (план 2.0,
+ * 7.4 №8). Тест меняет предел, чтобы проверить вытеснение без тысячи арендаторов.
+ */
+export declare const limits: {
+    asRegistries: number;
+};
 /** Запомнить фасад (зовёт makeDb для каждого фасада, который отдаёт наружу). */
 export declare function registerDb(db: object, info: DbInternals): void;
 /** Свойства фасада; undefined — объект не фасад connect() этого пакета. */

package/dist/internal.js

@@ -4,6 +4,11 @@
  * фасад db обходит RLS, не полагаясь на то, что сообщает о себе сам вызывающий.
  */
 const facades = new WeakMap();
+/**
+ * Пределы подключения, которых нет в опциях: реестров классов db.as() — не больше asRegistries арендаторов (план 2.0,
+ * 7.4 №8). Тест меняет предел, чтобы проверить вытеснение без тысячи арендаторов.
+ */
+export const limits = { asRegistries: 1000 };
 /** Запомнить фасад (зовёт makeDb для каждого фасада, который отдаёт наружу). */
 export function registerDb(db, info) {
     facades.set(db, info);

package/dist/load.d.ts

@@ -12,7 +12,10 @@ export interface LoadOptions {
     batch?: number;
     /** Фиксировать порциями примерно по N строк (порция — классы в порядке зависимостей, цикл — целиком). */
     commitEvery?: number;
-    /** Режим истории (импорт): строки — версии с $rev, $at и $op; пишутся волнами. */
+    /**
+     * Режим истории (импорт): каждая строка — версия объекта с номером `$rev`, временем `$at` и видом операции `$op`; так
+     * переносят историю объектов из другой системы.
+     */
     withHistory?: boolean;
     /** В конце перепроверить загруженные строки проверкой базы. */
     verify?: boolean;
@@ -20,7 +23,10 @@ export interface LoadOptions {
     class?: string;
     /** Арендатор строк (по умолчанию — арендатор сессии). */
     tenant?: string;
-    /** Агент версий (по умолчанию «letopis load»; импорт — «letopis import»). */
+    /**
+     * Исполнитель записи — строка, которую журнал сохранит в поле `agent` загруженных версий рядом с автором (по умолчанию
+     * «letopis load»; импорт — «letopis import»).
+     */
     agent?: string;
     /**
      * Загрузка от имени пользователя (§2.6, п. 10): автор версий — он; арендатор (по умолчанию —
@@ -128,7 +134,8 @@ export declare function load(env: LoadEnv, input: LoadInput, opts?: LoadOptions)
  * Первая заливка (план 1.1, §2.3): загрузки fn — одной транзакцией в пустую схему. Блокировка таблиц до
  * проверки; в схеме только строки системных классов и записи reset (иначе not_empty); они (с seq и tx
  * журнала) и определения ограничений, индексов и триггеров из каталога (с режимом включения tgenabled:
- * pg_get_triggerdef его не передаёт) сохраняются в памяти; TRUNCATE; триггеры, ограничения и индексы
+ * pg_get_triggerdef его не передаёт) сохраняются в памяти; внешний ключ secret.account снимается до TRUNCATE и
+ * возвращается после первичного ключа entity; TRUNCATE; триггеры, ограничения и индексы
  * снимаются — BEFORE ROW делает COPY построчным одним своим наличием, триггеры после оператора копят
  * переходные таблицы; системные строки возвращаются (seq журнала — generated always: overriding system
  * value); загрузки пишут COPY FREEZE. В конце — ограничения (дубликат найдёт сортировка), индексы,