letopis 1.3.0 → 1.4.1

package/README.md

@@ -1,4 +1,4 @@
-# letopis 1.3
+# letopis 1.4
 
 **letopis** — библиотека для Node.js, хранилище версионированных сущностей на PostgreSQL 18. Каждое изменение
 сохраняется версией в журнале. Поэтому у любого объекта есть история, состояние на любую дату и подписка на
@@ -129,7 +129,7 @@ await svc.close()
   уменьшил цену внутри оператора `UPDATE`, без предварительного чтения. `versions()` прочитал историю из журнала.
 
 Повторный вызов `up()` безопасен: он повторно накатывает ту же ревизию и данные не трогает, а ключ сервиса снова не
-выдаёт, пока в установке есть действующий ключ API. Дальше раздел 2 объясняет устройство, а разделы 3–13 разбирают задачи по порядку.
+выдаёт, пока в установке есть хоть один ключ API, кроме отозванных. Дальше раздел 2 объясняет устройство, а разделы 3–13 разбирают задачи по порядку.
 
 ## 2. Как устроен letopis
 
@@ -239,11 +239,16 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 | `owner`, `app` | имена ролей владельца и приложения (по умолчанию `letopis_owner`, `letopis_app`) |
 
 Результат: `schema` (полное имя), `serviceKey` (при первой установке и при накате, когда в установке не осталось ни
-одного действующего ключа API; иначе `null`), `created`,
+одного ключа API, кроме отозванных: истёкший или выключенный ключ тоже в счёт; иначе `null`), `created`,
 `upgraded`, `revision`, `migrations`, `analyzed`, `owner`, `app`, `signals` (режим сигналов установки), `warnings`
 (предупреждения, без `quiet` они печатаются), а также `tenant` и `pglite`, если их просили. На PostgreSQL ниже 18.2
 `up()` предупреждает: такой сервер мог усечь CLOG, который ещё нужен непрочитанным сигналам, — обновите его.
 
+Несколько экземпляров сервиса могут звать `up()` одной схемы одновременно: накат идёт под блокировкой схемы. Первый
+`up()` ставит или обновляет её, остальные ждут и делают повторный накат по готовой (`created: false`,
+`upgraded: false`); первого арендатора `tenant` заводит один из них, остальные находят его по имени. `up()` разных
+схем одной базы друг друга не ждут.
+
 Скрыть из сигналов имена классов — режим `opaque` (или `tenant`, если имена не секрет, а нужна точность кэша по
 арендатору); после смены режима перезапустите процессы приложения — режим читается при подключении:
 
@@ -285,7 +290,9 @@ const ANNA = r.tenant!.user!       // его первый пользовател
 Повтор с теми же именем и логином ничего не дублирует и пароль не меняет, только выдаёт новую сессию. Логин входит в
 id как есть: `Anna@shop.ru` и `anna@shop.ru` дали бы два аккаунта, и у второго не было бы пароля, — пишите логин в
 одном регистре. Поле `created` в ответе — создан ли арендатор этим вызовом: для существующего арендатора с новым
-пользователем оно `false`. Роли задаёт `user.roles` — непустой список имён (не масок), иначе `invalid_data`. Роли
+пользователем оно `false`. Роли задаёт `user.roles` — непустой список имён (не масок), иначе `invalid_data`. Вид
+пароля `user.kind` (по умолчанию `PASSWORD`) подчиняется правилу вида креда, как у `auth.setPassword`
+([«Справочник API»](#dbauth)), иначе — тоже `invalid_data`. Роли
 уже существующего членства повтор не меняет: их меняет правка членства ([«Выдать право»](#выдать-право)).
 Удалённое повтор не воскрешает: если арендатор, аккаунт пользователя или членство удалены (строки нет, а история в
 журнале есть), `createTenant` отвечает `invalid_data` и не записывает ничего. Текст ошибки называет удалённое и
@@ -356,11 +363,21 @@ const adm = await connect({ dsn: ADMIN, schema: r.schema, token: r.tenant!.token
 
 ### Обновление пакета и схемы
 
-У схемы есть ревизия движка (сейчас 6). Если новая версия пакета принесла новую ревизию, `connect()` только
+У схемы есть ревизия движка (сейчас 7). Если новая версия пакета принесла новую ревизию, `connect()` только
 предупредит и назовёт команду. Отказывает `up()`: на отставшую схему без `upgrade: true` и на схему новее пакета.
+К схеме новее пакета (её уже обновил более новый пакет, а старые экземпляры приложения ещё работают) `connect()`
+подключается с предупреждением «движок схемы … ревизии N новее библиотеки (она знает M) — обновите пакет letopis».
 Поэтому скрипт запуска, который вызывает `up()` при каждом старте, после обновления пакета остановится, пока не
 получит `upgrade: true`. `up({ dsn, schema, upgrade: true })` применяет миграции из `sql/migrate/` и повторно
-накатывает функции; данные сохраняются.
+накатывает функции; данные сохраняются. Ревизия 7 (1.4.1) добавляет внешний ключ `secret.account`: миграция `0007`
+сначала стирает строки `secret`, чьих аккаунтов уже нет (креды удалённых раньше аккаунтов хранились с пометкой
+`deleted_at`), и ставит ключ.
+
+Ревизия меняется не с каждой версией: у 1.1–1.4.0 она одна (6), а функции разные. Поэтому `up()` пишет в комментарий
+схемы ещё и штамп движка: версию пакета и хэш его файлов SQL. Если штамп не совпадает с файлами пакета, `connect()`
+предупреждает. Когда схему накатила более старая версия (или версия до 1.4, у которой штампа нет), он советует
+`up({ schema })`. Когда схему уже обновила более новая версия, он советует обновить пакет: `up()` старой версией вернул
+бы прежние функции. Новая версия пакета без правок SQL штамп не меняет, и предупреждения нет.
 
 Первый `up()` после перехода на 1.2 строит индекс журнала `log_class_tenant_at (class, tenant, at)` вместо
 `log_class_at`: срез `asOf` и `withDeleted` по классу больше не читает журнал других арендаторов с тем же именем
@@ -370,8 +387,8 @@ const adm = await connect({ dsn: ADMIN, schema: r.schema, token: r.tenant!.token
 
 Обновление схем 1.1.0 и 1.0.1 проверяет тест `upgrade`. Схему ставит прежний пакет, данные пишет прежний движок, затем
 вызывается `up()` текущей версии. После него версии и хэши прежнего движка на месте, `verify({ data: true })` чист, а
-каталог схемы совпадает с чистой установкой. Схема 1.1.0 обновляется простым `up()`: ревизия у неё та же. Схема 1.0.1
-обновляется через `up({ upgrade: true })`.
+каталог схемы совпадает с чистой установкой. Обе схемы обновляются через `up({ upgrade: true })`: 1.1.0 (ревизия 6) —
+миграцией `0007`, 1.0.1 (ревизия 5) — миграциями `0006` и `0007`.
 
 ### Разработка без PostgreSQL: PGlite
 
@@ -550,12 +567,18 @@ const Movement = link('Movement', { amount: z.number().int() }, { ends: { Wallet
 - Описание проверяет база (`invalid_class`): поле есть в схеме, оно числовое и не входит в ключ; конец `via` —
   одиночный и принимает класс цели; поле `sum` — число; агрегаты не образуют цикл; цель и источник — не системные и
   не производные классы. Класс-источник описывают раньше агрегата: агрегат над классом, которого ещё нет, отклоняется.
-  У класса арендатора источник ищут среди классов арендатора. `syncModels` сам описывает источники раньше целей.
+  У класса арендатора источник ищут среди классов арендатора. `syncModels` сам описывает источники раньше целей, а
+  модели по кругу (агрегат над собственным потомком, цикл агрегатов) отклоняет до записи (`invalid_class` с кругом).
   Класс `of` не удаляется, пока его называет агрегат класса того же арендатора: сначала агрегат убирают из описания цели.
 - Строки попадают в агрегат только с ведома того, кто читает их все: поле считает и строки, которые автору не видны.
   Описать или изменить агрегат может только тот, кто без условий читает все строки источника и его потомков. Сделать
   класс источником (новый потомок источника, смена `parent`) может только тот, кто без условий читает все
   строки этого класса и его потомков — и до правки, и после. Иначе `acl_denied`.
+- Новый источник проверяется и по тому, кто описал агрегат: он тоже должен без условий читать все строки класса.
+  Описавший — автор версии строки `Class` цели, с которой описание агрегата стало нынешним. Если он их не читает, класс
+  источником не станет (`acl_denied`), пока агрегат не опишет заново тот, кто читает. У агрегата класса System
+  описавший проверяется по классам System, как и при описании. Класс арендатора под агрегатом System проверяется
+  только у того, кто его заводит.
 - Опция наследуется, потомок заменяет её целиком. Добавить или изменить агрегат — ужесточение: запись в цель и в
   источники ждёт, пока поле пересчитывается у всех строк.
 - `db.rebuildAggregates(класс)` пересчитывает поле из текущих строк — для ремонта. Версия пишется только там, где
@@ -590,8 +613,9 @@ npx letopis types --dsn "$APP" --schema v2.shop --token "$TOKEN" --out types.ts
 ### Имена классов
 
 Шаг цепочки называется именем класса, его алиасом или именем роли. Имена методов цепочки и корня (`count`, `sort`,
-`set`, `sql`, `auth` и другие) Proxy разбирает раньше классов. Поэтому класс с таким именем недостижим как шаг, а
-связь с таким именем база не примет. Полный список — в разделе
+`set`, `sql`, `auth` и другие) там, где такой метод есть, библиотека разбирает раньше классов: класс `count` доступен
+первым шагом `db.count(…)`, но не после другого шага. Связь с таким именем база не примет. Не давайте классам эти
+имена; полный список — в разделе
 [«Зарезервированные имена»](#зарезервированные-имена).
 
 ## 5. Запись
@@ -645,7 +669,8 @@ await db.Shop(shop).Product({ price: gte(2000) }).update({ title: 'Чайник
 `db.Product().update(…)` правит все товары арендатора. Шаг ничего не нашёл — ответ пустой и ошибки нет, поэтому
 проверяйте длину ответа. Если `update` затронул меньше строк, чем нашёл шаг, весь план откатывается: строку успели
 удалить — `target_not_found`, строка видна, но править её нельзя — `acl_denied`. Модификатор `.tags(…)` перед
-`update` и отбирает строки, и заменяет их теги целиком.
+`update` отбирает строки; строка или список ещё и заменяют их теги целиком, а оператор (`has`, `hasAny`, `hasAll`)
+только отбирает — теги не меняются.
 
 ### Создать или заменить: `upsert`
 
@@ -777,8 +802,14 @@ await db.Order(order).line().create({ qty: 1, price: 900 }).Product.set(sencha).
 - Весь план — одна транзакция уровня `read committed`. При взаимной блокировке (`40P01`), ошибке сериализации
   (`40001`) и конфликте журнала библиотека повторяет план целиком, до трёх раз.
 - Ошибка любого звена откатывает весь план. `exists` и `conflict` не повторяются: это ответы для приложения.
-- Модификаторы до глагола (`limit`, `sort`) сужают его цели.
+- Модификаторы до глагола (`limit`, `offset`, `sort`) сужают его цели.
+- Модификатор после глагола относится к тому, что идёт за ним: к шагу класса, к `versions()`, `diff()`, `blame()` и
+  агрегатам или к целям следующего глагола. Если за ним сразу терминал `rows`, `first`, `ids`, `count` или `paths`,
+  сужать уже нечего — глагол прошёл по всем целям шага, — поэтому `db.Product().update(…).limit(1).rows()` даёт
+  `invalid_query` и ничего не пишет. В батче так же отказывает `run()`.
 - Глагол сразу после глагола пишет в те же сущности.
+- Строки ответа глагола идут в порядке его целей: по `sort()` до глагола, без него — по id; `first()` после глагола —
+  первая по этому порядку.
 
 ## 6. Чтение
 
@@ -822,7 +853,7 @@ const roots = await db.Category({ Parent: null }).rows()       // корневы
 | `ne(v)`, `gt(v)`, `gte(v)`, `lt(v)`, `lte(v)` | ≠ (с учётом `null`), >, ≥, <, ≤ |
 | `between(a, b)`, `inList([…])` | a ≤ x ≤ b; значение из списка |
 | `like(s)`, `ilike(s)`, `starts(s)`, `ends(s)` | шаблон с `%` и `_`; без учёта регистра; начинается с; заканчивается на |
-| `has(v)`, `hasAny([…])`, `hasAll([…])` | поле-массив содержит значение; хотя бы одно; все |
+| `has(v)`, `hasAny([…])`, `hasAll([…])` | поле-массив содержит значение; хотя бы одно; все (`hasAll([])` подходит любой строке, `hasAny([])` — никакой) |
 | `exists(true \| false)`, `isNull()` | поле есть или нет; поле `null` или отсутствует |
 | `not(v)` | отрицание оператора; скаляр — «не равно» |
 | `or(f1, f2, …)` | любой из фильтров шага |
@@ -892,7 +923,9 @@ const byStatus = await db.Order().countBy('data.status')          // { new: 1 }
 ```
 
 Агрегаты считает база, по сущностям последнего шага. `limit(n)` и `offset(n)` перед `countBy()` относятся к группам:
-`db.Order().limit(3).countBy('data.status')` — три самых частых значения.
+`db.Order().limit(3).countBy('data.status')` — три самых частых значения. У логического поля `min()` — `false`, если
+есть хоть одно `false` (все ли значения `true`), а `max()` — `true`, если есть хоть одно `true`; `sum()` и `avg()`
+логическое поле не считают — PostgreSQL отвечает ошибкой.
 
 ### Пути
 
@@ -924,10 +957,11 @@ try {
 
 `delete()` без `{ confirm: true }` — только превью: всё замыкание каскада. В каждой строке превью `$action`:
 `delete`, `unset` или `restrict`, и `$depth` — уровень каскада (0 — сама цель; у строк `unset` и `restrict` его
-нет). С подтверждением удаляются все цели
-шага одним оператором, а каскад применяет правила концов. Превью не учитывает права: строка с `$action: 'delete'`
-может не удалиться у пользователя без права (`acl_denied`), поэтому интерфейсу стоит спросить
-`acl.checkData(класс, 'DELETE')`. Правила концов:
+нет). С подтверждением удаляются все цели шага одним оператором, а каскад применяет правила концов. Итог —
+надгробия по уровням каскада, внутри уровня по id (в таком порядке они и в журнале); цели классов без журнала
+(`history: false`) — в конце. Превью не учитывает права: строка с `$action: 'delete'` может не удалиться у
+пользователя без права (`acl_denied`), поэтому интерфейсу стоит спросить `acl.checkData(класс, 'DELETE')`.
+Правила концов:
 
 - `restrict` — удаление запрещено, пока на цель ссылаются (`delete_restricted` со списком видимых строк и числом
   остальных);
@@ -1377,8 +1411,10 @@ const viaTelegram = await svc.auth.lookup({ kind: 'TELEGRAM', identifier: '10050
 <!-- run: guide -->
 ```ts
 const shortToken = await svc.auth.sessionFor(BORIS, { ttl: 600 })   // сессия на 10 минут простоя — для другого процесса
+const whose = await svc.auth.session(shortToken)                     // { account, tenant, member, expiresAt, loginAt, methods }
 const boris = await connect({ dsn: APP, schema: r.schema, token: shortToken })
 await boris.auth.revoke()                                            // выход: сессия погашена
+const ended = await svc.auth.session(shortToken)                     // null
 await boris.close()
 ```
 
@@ -1391,6 +1427,15 @@ await boris.close()
 старые сессии того же вида входа без отметки ключа); текущая сессия остаётся, если не передать
 `keepCurrent: false`.
 
+Сервис, у которого есть токен пользователя (например, в cookie), узнаёт о сессии через `svc.auth.session(token)`:
+подключение по этому токену не открывается, срок сессии не продлевается. Ответ — чья сессия (`account`), в каком
+арендаторе она работает (`tenant`: выбранный `auth.switch()` или собственный арендатор аккаунта), цело ли там членство
+(`member`; в собственном арендаторе — всегда `true`), когда она истечёт (`expiresAt`), когда и как был вход
+(`loginAt`, `methods`: `PASSWORD`, `APIKEY`, `SERVICE`, `TOTP` …). Неверный, погашенный или истёкший токен и
+отключённый аккаунт — `null`, причина не различается. Так веб-сервис проверяет сессию в начале каждого запроса:
+чтение по погашенной сессии ошибки не даёт, ответы просто пустые. Вызывает метод сервис или системный администратор
+(право `auth.session`); пользователю отвечают `acl_denied`.
+
 ### Работа в другом арендаторе
 
 Сервис действует от имени пользователя через `svc.as(account, { tenant, owner })`. База проверяет право сервиса
@@ -1498,7 +1543,14 @@ const canReport = await asOleg.acl.check('shop.reports.daily')      // { allow:
 
 `db.auth.purgeAccount(аккаунт)` удаляет аккаунт и данные его арендатора. Вызывать может системный администратор или
 владелец его арендатора; себя и последнего владельца арендатора удалить нельзя. Владение строками в чужих
-арендаторах переходит этим арендаторам, сессии гаснут, креды удаляются.
+арендаторах переходит этим арендаторам, сессии гаснут, креды удаляются. Владелец может стереть и арендатора, в
+котором сейчас работает: его сессия вернётся в личный арендатор.
+
+Системный администратор может удалить и саму строку аккаунта — `db.Account(id).delete({ confirm: true })` в
+арендаторе System; данные арендатора аккаунта при этом остаются. Любой путь сразу стирает строки аккаунта в `secret`:
+сессии, хэши паролей и ключей, секреты TOTP, внешние учётные записи (внешний ключ `secret.account` с каскадом,
+ревизия 7). Сессии гаснут до этого с сигналом, и процессы сбрасывают кэш ответов этих сессий. Аккаунт System
+не удаляется (`acl_denied`): ему принадлежат служебные строки установки в `secret`.
 
 ## 11. История и срезы на дату
 
@@ -1659,7 +1711,7 @@ const sub = db.watch({ from: 'start', classes: ['Product'] })   // весь жу
 await db.Product(kettle).update({ price: 2100 }).rows()
 let cursor = ''
 for await (const ev of sub) {             // ev: { cursor, row, id, class, op, rev, at }
-  cursor = ev.cursor                      // сохраните курсор: watch({ from: cursor }) продолжит после него
+  cursor = sub.cursor!                    // курсор подписки: watch({ from: cursor }) продолжит после этого события
   if (ev.id === kettle.id && ev.row.data.price === 2100) break   // break (или sub.close()) — остановить
 }
 ```
@@ -1677,10 +1729,13 @@ for await (const ev of sub) {             // ev: { cursor, row, id, class, op, r
   порядке записи. Это не порядок фиксации: версии одного объекта сверяйте по `rev`.
 - Долгая пишущая транзакция в любой базе кластера задерживает поток: `await sub.lag()` показывает отставание в мс.
 - Курсор старше яруса `all` политики хранения — `cursor_expired`: перечитайте текущее состояние и подпишитесь
-  с `'now'`.
+  с `'now'`. Время в курсоре подписки `sub.cursor` — время последнего события, а когда подписка догнала журнал, —
+  время опроса, поэтому подписка, к которой сутки не было событий, не устаревает. Курсор события `ev.cursor` хранит
+  время самого события.
 - Без `LISTEN` (`connect({ listen: false })`) подписка опрашивает журнал.
-- Подписка без потерь — это сохранённый курсор: храните `ev.cursor` последнего обработанного события и продолжайте
-  с него после перезапуска.
+- Подписка без потерь — это сохранённый курсор: обработав событие, храните `sub.cursor` (позиция после последнего
+  выданного события) и продолжайте с него после перезапуска. С `ev.cursor` поток тоже продолжится, но после затишья
+  дольше яруса `all` такой курсор старше яруса, и продолжение с него — `cursor_expired`.
 
 ### Проекторы
 
@@ -1762,7 +1817,9 @@ sales.close()                                    // stop() после текущ
   `out.inc(класс, строка, приращения, { tenant })` создаёт строку или дополняет её и прибавляет числа, не читая
   строку (поля, которых нет, считаются от 0). `out.delete(класс, ключ или id, { tenant })` удаляет строку, а если её
   нет, ничего не делает. `await out.get(класс, ключ или id, { tenant })` читает текущую строку вместе с записями
-  пачки. `out` пишет только в классы `into` и только в арендатора изменений, переданных в `handle`; иначе —
+  пачки. Строку класса с ключом `delete` и `get` находят по полям ключа (`{ day: '2026-10-29' }`), а по id (строкой
+  или `{ $id }`) — только строку класса без ключа; один id у класса с ключом — `invalid_data`, и пачка откатывается.
+  `out` пишет только в классы `into` и только в арендатора изменений, переданных в `handle`; иначе —
   `derived_class` или `tenant_denied`, и пачка откатывается.
 - Приращения строки, заданной одними полями ключа (или одним `$id`), `out` складывает до отправки в базу, пока между
   ними нет `upsert`, `delete` или `get`: на строку — одна правка за пачку, а правило класса проверяется над итогом её
@@ -1810,14 +1867,20 @@ sales.close()                                    // stop() после текущ
   выбирает он: пользователь арендатора сам к проектору не подключится. Опция
   `tenants: [id, …]` — явный список участников: проектор работает только с этими арендаторами (их классы `into` тоже
   должны быть помечены), а пометку у остальных не учитывает. Источники — семейства `from` у этих арендаторов; класс
-  не может быть одновременно источником и результатом. Изменений класса с `history: false` проектор не видит:
-  журнала у него нет. Поэтому арендатор, у которого такой класс среди источников, выбывает с кодом `invalid_class`, и
-  его производных строк проектор не строит. Включите журнал класса и перестройте арендатора `rebuild({ tenant })`.
+  из `into` источником не бывает, даже если попадает в `from`: свои результаты проектор не читает. Изменений класса
+  с `history: false` проектор не видит: журнала у него нет. Поэтому арендатор, у которого такой класс среди
+  источников, выбывает с кодом `invalid_class`, и его производных строк проектор не строит. Включите журнал класса и перестройте арендатора `rebuild({ tenant })`.
 - `batch` — сколько изменений в пачке (500), `pollMs` — запасной опрос (1000 мс): сигналы источников будят
   проектор раньше.
 - `lockTimeout` — сколько транзакция проектора ждёт чужую блокировку строки (5000 мс; 0 — без предела). Транзакция
   любого арендатора, которая держит строку итога или цель конца, иначе держала бы пачку всех арендаторов. Дольше —
-  пачка откатывается, курсор остаётся, `run()` не отклоняется, а пропускает проход (`skipped`) и повторяет его.
+  пачка откатывается, курсор остаётся, `run()` не отклоняется, а пропускает проход (`skipped`) и повторяет его. Отчёт
+  называет арендатора, на чьей строке встала пачка (`locked`). `rebuild({ tenant, chunked: true })` такую блокировку
+  пережидает.
+- `lockRetries` — сколько проходов подряд запись одного арендатора может упираться в `lockTimeout`, прежде чем он
+  выбудет (по умолчанию 0 — не выбывает). Выбывший получает код `55P03`, и пачка идёт для остальных; его изменения
+  пропускаются до `rebuild({ tenant })`. Счёт ведёт процесс, удачная запись арендатора его сбрасывает. Учтите: долгая
+  исключительная блокировка семейства класса System (ужесточение описания) упрётся в каждого арендатора по очереди.
 - Каждая правка, которую `out` отправляет в базу, — отдельная правка строки, и скорость проектора задаёт число
   правок, а не число изменений. Свёртка `inc` сводит правки строки к одной за пачку, поэтому handle из примера выше
   (`out.inc` на каждое изменение) на машине замеров догонял 6 тысяч изменений в секунду при `batch` 500 и 33 тысячи
@@ -1896,7 +1959,9 @@ const stats = db.cache.stats()                                 // { size, hits,
 - изменение прав и классов, запись через `db.sql`, погашенная сессия и переподключение слушателя сбрасывают весь
   кэш или ответы сессии;
 - срок по умолчанию — 60 секунд; внутри `db.begin()` кэш не работает;
-- без `LISTEN` и в режиме `none` кэш выключен, а `connect({ cache: { ttlOnly: true } })` включает его только по сроку.
+- без `LISTEN` и в режиме `none` кэш выключен, а `connect({ cache: { ttlOnly: true } })` включает его: ответ живёт до
+  конца срока, если его не сбросит запись этого подключения;
+- `db.load()`, проектор и `db.rebuildAggregates()` сбрасывают кэш, даже этого подключения, только сигналом базы.
 
 Реестр классов процесс перечитывает по сигналу об изменении классов сразу (одно перечитывание за раз), а реестр и
 ключ сигналов по `*`, по незнакомому токену и по нагрузке не своего режима (а без ключа в режиме `opaque` — по любому
@@ -1916,10 +1981,16 @@ const stats = db.cache.stats()                                 // { size, hits,
 const report = await adm.maintain()     // { sessions, codes, thinned, batches, more, queue, skipped }
 ```
 
-`maintain()` удаляет истёкшие сессии и одноразовые коды, прореживает журнал по политике хранения и проверяет
-очередь сигналов PostgreSQL: заполнение больше половины — предупреждение. Вызывать может системный администратор,
-роль с правом `letopis.maintain` или администраторское подключение. Запускает его внешний планировщик
-(`letopis maintain`) или сама библиотека: `connect({ maintain: '1h' })`. Из нескольких процессов работает один:
+`maintain()` удаляет из таблицы `secret` сессии и одноразовые коды всех видов (`OTP` и свои `OTP_<ИМЯ>` из
+`issueOtp({ kind })`) — истёкшие, а также погашенные сессии и коды, которые уже использованы, заменены новым или
+исчерпали попытки, — прореживает журнал по политике хранения
+и проверяет очередь сигналов PostgreSQL: заполнение больше половины — предупреждение. Строки удалённого аккаунта
+`maintain()` ждать не нужно: их стирает само удаление ([«Удалить аккаунт»](#удалить-аккаунт)). Вызывать может системный
+администратор, роль с правом `letopis.maintain` или администраторское подключение. Запускает его внешний
+планировщик (`letopis maintain`) или сама библиотека: `connect({ maintain: '1h' })`. Интервал — число миллисекунд или
+строка (`'500ms'`, `'30s'`, `'15m'`, `'1h'`, `'1d'`) от 1 мс до 2³¹−1 мс (около 24 суток): другое значение, в том
+числе ноль, отрицательное или `NaN`, `connect()` отклоняет с `invalid_data`, не открывая соединений. `close()` ждёт
+идущий по расписанию запуск: он доделывает текущую пачку и следующую не начинает. Из нескольких процессов работает один:
 каждая пачка — своя транзакция, и первым делом она берёт блокировку обслуживания — строку таблицы `secret`, которую
 ни прикладная, ни посторонняя роль базы не займёт; блокировка снимается с фиксацией пачки. Если блокировку держит
 другой процесс, вызов до первой пачки отвечает `skipped: true`, а между пачками останавливается (продолжит тот
@@ -2121,6 +2192,9 @@ letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пол
   (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)
 ```
 
+`letopis types` и `letopis describe` строят результат по классам сессии, поэтому без действующей сессии (токен истёк,
+погашен, неверен или не задан, ключ API неверен) выходят с кодом 1 и ошибкой `no_session`, а файл `--out` не трогают.
+
 ### Наблюдение
 
 - `connect({ onQuery, slowMs })`: хук получает на каждый запрос цепочки режим, классы, длительность, число строк и
@@ -2238,17 +2312,19 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `link`, `lookup` | `{ account, kind, identifier, meta?, confirmed? }` → id; `{ kind, identifier, requireConfirmed?, ttl?, totp? }` → вход или `null` |
 | `credentials`, `revokeCredential`, `setFlags` | `(account)` → креды без секретов; `(id, { keepCurrent? })`; `(id, { confirmed?, enabled? })` |
 | `sessionFor`, `refresh`, `revoke`, `revokeAll` | `(account, { ttl? })` → токен; `({ ttl? })` → новое время истечения (токен прежний); `()`; `(account?)` → число сессий |
+| `session` | `(token)` → `{ account, tenant, member, expiresAt, loginAt, methods }` или `null` |
 | `tenants`, `switch` | `()` → `[{ tenant, roles }]`; `(tenant)` |
 | `purgeAccount` | `(account)` → `{ account, rows, versions, memberships, owned }` |
 
-Проверку паролей, кодов и TOTP, выпуск сессий и подтверждение кредов вызывает сервис (права `auth.*`); обычному
-пользователю отвечают `acl_denied`. Креды System, сервисов и системных администраторов меняет только сам аккаунт
-после недавнего интерактивного входа или системный администратор. Исключение — ключи сервиса: свои ключи API и
-пары «ключ + секрет» сервис выпускает и отзывает сам по сессии своего ключа, прочие свои креды — нет; последний
-действующий ключ сервиса не отзывается никем (`acl_denied`). С `totp` вход `verifyPassword` и `lookup` проверяет
-ещё и код TOTP (право `auth.totp`) и выдаёт сессию со способом `TOTP`.
+Проверку паролей, кодов и TOTP, выпуск сессий, сведения о сессии по токену и подтверждение кредов вызывает сервис
+(права `auth.*`); обычному пользователю отвечают `acl_denied`. Креды System, сервисов и системных администраторов
+меняет только сам аккаунт после недавнего интерактивного входа или системный администратор. Исключение — ключи
+сервиса: свои ключи API и пары «ключ + секрет» сервис выпускает и отзывает сам по сессии своего ключа, прочие свои
+креды — нет; последний действующий ключ сервиса не отзывается никем (`acl_denied`). С `totp` вход `verifyPassword` и
+`lookup` проверяет ещё и код TOTP (право `auth.totp`) и выдаёт сессию со способом `TOTP`.
 Вид креда `kind` — `^[A-Z][A-Z0-9_]{1,31}$` (`PASSWORD`, `EMAIL`, `TELEGRAM` …); `SESSION`, `APIKEY`, `KEYSECRET`,
-`OTP`, `TOTP` и `KEY` заняты.
+`OTP`, `TOTP`, `KEY`, `PROJECTOR` и `LOCK` заняты. То же правило — у вида пароля `user.kind` в `createTenant` и
+`up({ tenant })`.
 
 ### Проектор
 
@@ -2258,14 +2334,14 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 
 | Член | Что делает |
 |---|---|
-| опции `ProjectorOptions` | `from`, `into` — классы с потомками; `version` — целое от 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` — пачками); `batch` — изменений в пачке (500, от 1 до 10 000); `pollMs` — запасной опрос (1000 мс); `lockTimeout` — ожидание чужой блокировки строки (5000 мс, 0 — без предела); `tenants` — id арендаторов-участников |
+| опции `ProjectorOptions` | `from`, `into` — классы с потомками; `version` — целое от 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` — пачками); `batch` — изменений в пачке (500, от 1 до 10 000); `pollMs` — запасной опрос (1000 мс); `lockTimeout` — ожидание чужой блокировки строки (5000 мс, 0 — без предела); `lockRetries` — проходов подряд до выбывания арендатора с чужой блокировкой (0 — не выбывает); `tenants` — id арендаторов-участников |
 | `run({ once })` | догнать журнал (`once`) или следовать за ним до `stop()` → `ProjectorReport` |
 | `rebuild({ chunked, tenant })` | перестроить с текущего состояния: атомарно, пачками или одного арендатора → `ProjectorReport` |
 | `status()` | → `ProjectorStatus`: `{ name, state, version, cursor, at, lag, failed, rebuildingTenants }`; `failed` — `{ [id арендатора]: ProjectorFailure }`, где `ProjectorFailure` — `{ cursor, code, message }` |
 | `stop()`, `close()` | остановить `run()` после текущей пачки; то же и отписаться от сигналов |
-| `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds }` |
+| `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds, locked }` |
 | `ProjectorChange` | `{ cursor, id, class, tenant, op, rev, at, author, row }` и, если есть, `agent`, `reason`, `moved`, `before`, `rebuild` |
-| `ProjectorOut` | `upsert(класс, строка, { tenant })`, `inc(класс, строка, приращения, { tenant })`, `delete(класс, ключ или id, { tenant })`, `get(класс, ключ или id, { tenant })` → `Row \| null`; строка — `ProjectorRow` в формате загрузчика |
+| `ProjectorOut` | `upsert(класс, строка, { tenant })`, `inc(класс, строка, приращения, { tenant })`, `delete(класс, ключ или id, { tenant })`, `get(класс, ключ или id, { tenant })` → `Row \| null`; строка — `ProjectorRow` в формате загрузчика; у класса с ключом `delete` и `get` — по ключу, id — только у класса без ключа |
 
 ### Строка ответа
 
@@ -2282,8 +2358,10 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 
 ### Зарезервированные имена
 
-Имена ниже Proxy разбирает раньше классов, поэтому класс с таким именем недостижим как шаг, а связь с таким
-именем база не примет (`reserved_names()`; список подставляет установщик из `RESERVED_CLASS_NAMES`).
+Имя метода закрывает класс только там, где этот метод есть: после шага — методы цепочки, у корня `db` — его методы,
+у батча — его. Поэтому хаб с именем метода только цепочки (например, `count`) доступен первым шагом `db.count(…)`, а
+после другого шага недостижим; хаб с именем метода корня первым шагом не вызвать. Связь с любым из этих имён база не
+примет (`reserved_names()`; список подставляет установщик из `RESERVED_CLASS_NAMES`). Не давайте классам эти имена.
 
 - методы цепочки: `then`, `entity`, `paths`, `rows`, `first`, `ids`, `count`, `limit`, `offset`, `sort`, `asOf`,
   `withDeleted`, `deep`, `exact`, `sum`, `avg`, `min`, `max`, `countBy`, `after`, `versions`, `create`, `update`,
@@ -2340,7 +2418,7 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `tx_rolled_back` | PostgreSQL ответил `ROLLBACK` на `COMMIT`: ошибку перехватили внутри `tr.transaction(fn)` |
 | `no_key` | `upsert`, `rekey` или `idOf` у класса без ключа |
 | `no_path` | между классами соседних шагов нет перехода |
-| `invalid_query` | цепочку или API используют неверно (модификатор шага `deep`, `exact`, `alias`, `tags` или `owner` после глагола, слот не после глагола, курсор `after()` со значением не того типа, что поле `sort`, без `v` или с `id` не uuid и т. п.) |
+| `invalid_query` | цепочку или API используют неверно (модификатор шага `deep`, `exact`, `alias`, `tags` или `owner` после глагола, модификатор выборки между глаголом и терминалом `rows`, `first`, `ids`, `count` или `paths`, слот не после глагола, курсор `after()` со значением не того типа, что поле `sort`, без `v` или с `id` не uuid и т. п.) |
 | `admin_required` | загрузчику, проектору и `rebuildAggregates` нужно администраторское подключение |
 | `rebuild_required` | проекция построена другой версией проектора (`version`): нужна перестройка `rebuild()`; `rebuild({ tenant })`, пока проекции нет или идёт перестройка пачками |
 | `projector_busy` | перестройку не начать: проектор сейчас работает в другом процессе |
@@ -2408,7 +2486,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 
 ## 18. Ограничения
 
-Здесь собрано то, что letopis 1.3 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
+Здесь собрано то, что letopis 1.4 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
 
 **Платформа**
 
@@ -2471,8 +2549,8 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 - Горячие цели ссылок (организация, на которую ссылается почти всё) копят блокировки `for key share` и MultiXact,
   как при обычных внешних ключах; это нужно мониторить. Операции одного кошелька идут друг за другом под
   блокировкой его строки ([раздел 8](#8-транзакции-батчи-и-деньги), «Рецепт: кошелёк»).
-- Связь не может называться зарезервированным именем, а хаб с таким именем недостижим как шаг
-  ([«Зарезервированные имена»](#зарезервированные-имена)).
+- Связь не может называться зарезервированным именем, а хаб с таким именем доступен не везде: например, `count` —
+  только первым шагом ([«Зарезервированные имена»](#зарезервированные-имена)).
 
 **Доступ**
 
@@ -2659,7 +2737,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 # cache — кэш результатов: попадание, свои и чужие записи, ключ с пользователем, права, погашенные сессии, обрыв слушателя, ttl, пометка класса, без LISTEN, гонка, db.sql, предел счётчиков сигналов (этап 6; план 1.1, точка А)
 # maintain — обслуживание: истёкшие сессии и коды, права, один процесс под блокировкой, расписание (этап 6)
 # up — полный установщик: свежая установка, повторный накат, свои сиды, автосоздание базы, UTF8, версия 17, upgrade с миграциями, PGlite, первый арендатор и пользователь (up({ tenant }), createTenant) (этапы 6, 8)
-# upgrade — обновление схемы с 1.1.0 (повторный накат) и с 1.0.1 (upgrade: true, миграция 0006) пакетами letopis-11 и letopis-1: версии и хэши прежнего движка, verify(), каталог против чистой установки, строки-замки, приложение, подписка и проектор по старым данным, повторный up() (доработки после 1.2.0, этап 1)
+# upgrade — обновление схемы с 1.1.0 (upgrade: true, миграция 0007) и с 1.0.1 (upgrade: true, миграции 0006 и 0007) пакетами letopis-11 и letopis-1: версии и хэши прежнего движка, verify(), каталог против чистой установки, строки-замки, строки secret без аккаунта стёрты, приложение, подписка и проектор по старым данным, повторный up() (доработки после 1.2.0, этап 1; ревизия 7)
 # scenario-salon — сквозной сценарий салона: 21 акт 0.21 (salon) с матрицей покрытия API 1.0 (этап 6)
 # telemetry — onQuery и slowMs, describe() и метаданные классов с наследованием, describeText (этап 6)
 # history — diff и blame по журналу, причина изменения у глаголов, db.begin() и батча; версия, скрытая условием ACL, колонка changed, пропуск версии, row_changes на 20 тыс. целей (план 1.1, этап 1 и точка А)

package/dist/acl.d.ts

@@ -1,9 +1,9 @@
 import type { Executor } from './tx.js';
 export type AclOp = 'READ' | 'WRITE' | 'DELETE';
-/** Решение по эндпоинту API. */
+/** Решение по ресурсу приложения (эндпоинту): можно ли к нему обратиться. */
 export interface AclDecision {
     allow: boolean;
-    /** Победившее правило: id, группа и объект (alias ресурсов), вес, разрешение. */
+    /** Победившее правило: id, группа и объект (`alias` ресурсов), вес, разрешение. */
     rule?: {
         id: string;
         group: string;
@@ -11,7 +11,7 @@ export interface AclDecision {
         weight: number;
         permission: 'allow' | 'deny';
     };
-    /** Код и сообщение запрещающего правила (поля code, message строки rule). */
+    /** Код и сообщение запрещающего правила (поля `code`, `message` строки `rule`). */
     code?: number;
     message?: string;
 }
@@ -21,9 +21,15 @@ export interface AclDataDecision {
     filter?: Record<string, unknown>;
 }
 export interface AclApi {
-    /** Может ли актор вызвать эндпоинт (ресурсы категории API; правила System и арендатора). */
+    /**
+     * Можно ли тому, от чьего имени идёт запрос, обратиться к ресурсу приложения (эндпоинту). Решают правила доступа
+     * System и текущего арендатора.
+     */
     check(endpoint: string): Promise<AclDecision>;
-    /** Решение операции над классом для актора: allow и условие на строки (filter). */
+    /**
+     * Можно ли тому, от чьего имени идёт запрос, выполнять операцию `op` с объектами класса — со всеми или только с теми,
+     * что подходят под условие `filter` в ответе.
+     */
     checkData(className: string, op: AclOp): Promise<AclDataDecision>;
 }
 export declare function makeAcl(S: string, exec: Executor): AclApi;

package/dist/admin.d.ts

@@ -17,22 +17,28 @@ export interface VerifyIssue {
 export interface VerifyResult {
     ok: boolean;
     issues: VerifyIssue[];
-    /** Хэш всех голов цепочек — храните вне базы: подмену последних версий выдаст его расхождение. */
+    /** Один хэш текущих версий всех объектов — храните его вне базы: подмену самых свежих версий выдаст его расхождение. */
     anchor: string;
 }
 export interface MaintainOptions {
-    /** Момент «сейчас» для прореживания — только в установке с allowReset (тесты). */
+    /** Момент «сейчас» для прореживания — только в установке с `allowReset` (тесты). */
     now?: string | Date;
-    /** Пачек прореживания за вызов (по умолчанию 100); каждая — своя транзакция. */
+    /** Сколько пачек прореживания журнала самое большее сделать за один вызов; каждая пачка — своя транзакция. */
     batches?: number;
-    /** Версий в пачке (по умолчанию 10 000). */
+    /** Сколько версий самое большее удалить в одной пачке прореживания. */
     limit?: number;
 }
+/** Внутренняя опция maintain(): остановка запуска по расписанию — текущая пачка доделывается, следующая не начинается. */
+export declare const MAINTAIN_STOP: unique symbol;
 export interface MaintainReport {
     /** Другой процесс уже обслуживает установку (держит строку-замок обслуживания): этот вызов ничего не делал. */
     skipped: boolean;
-    /** Удалено истёкших и погашенных сессий и одноразовых кодов. */
+    /** Удалено сессий: истёкших и погашенных (выход, отзыв, смена пароля, отключение или удаление аккаунта). */
     sessions: number;
+    /**
+     * Удалено одноразовых кодов (вид `OTP` и свои виды `OTP_<ИМЯ>` из `issueOtp({ kind })`): истёкших, использованных,
+     * заменённых новым и исчерпавших попытки.
+     */
     codes: number;
     /** Прорежено версий журнала. */
     thinned: number;
@@ -46,7 +52,7 @@ export interface ResetOptions {
     level: 'sessions' | 'tenant' | 'all';
     /** Подтверждение — имя схемы установки. */
     confirm: string;
-    /** level: 'tenant' — арендатор (по умолчанию — арендатор сессии). */
+    /** Какого арендатора сбросить при `level: 'tenant'` — его id; на других уровнях не учитывается. */
     tenant?: string;
 }
 export interface ResetResult {
@@ -55,10 +61,10 @@ export interface ResetResult {
     tenant?: string;
     rows?: number;
     versions?: number;
-    /** level: 'all' — новый ключ сервиса: прежние сессии и ключи больше не действуют. */
+    /** `level: 'all'` — новый ключ сервиса: прежние сессии и ключи больше не действуют. */
     serviceKey?: string;
 }
-/** Машинное описание модели (db.describe()). */
+/** Машинное описание модели (`db.describe()`). */
 export interface ModelDescription {
     schema: string;
     tenant: string | null;
@@ -117,13 +123,23 @@ export declare function verify(a: AdminCtx, opts?: {
  * (skipped у всех). Блокировку держит другой процесс: до первой пачки — skipped; между пачками —
  * вызов останавливается (продолжит тот процесс), отчёт — о сделанном, more: true.
  */
-export declare function maintain(a: AdminCtx, opts?: MaintainOptions): Promise<MaintainReport>;
+export declare function maintain(a: AdminCtx, opts?: MaintainOptions & {
+    [MAINTAIN_STOP]?: () => boolean;
+}): Promise<MaintainReport>;
 /** Предупреждение о заполненной очереди сигналов (§2.12): больше половины — зависший слушатель. */
 export declare function queueWarning(queue: number): string | null;
-/** Интервал расписания: число мс или '30s', '15m', '1h', '1d'. */
-export declare function parseInterval(v: string | number): number;
-/** Запуск maintain() по расписанию (connect({ maintain: '1h' })): ошибки — предупреждением. */
-export declare function scheduleMaintain(run: () => Promise<unknown>, every: string | number): () => void;
+/**
+ * Интервал расписания: число мс или строка '500ms', '30s', '15m', '1h', '1d' — конечный, от 1 мс до 2³¹−1 мс (около 24
+ * суток); иначе invalid_data. Ноль, отрицательное, NaN и слишком длинный интервал таймер Node.js превращает в 1 мс —
+ * обслуживание шло бы без перерыва.
+ */
+export declare function parseInterval(v: unknown): number;
+/**
+ * Запуск maintain() по расписанию (connect({ maintain: '1h' }); ms — уже проверенный интервал): ошибки — предупреждением,
+ * следующий запуск не начинается, пока идёт прежний. Возвращает остановку: она снимает таймер, просит идущий запуск не
+ * начинать новых пачек и ждёт его конца — close() закрывает пул после неё, а не посреди пачки.
+ */
+export declare function scheduleMaintain(run: (stopped: () => boolean) => Promise<unknown>, ms: number): () => Promise<void>;
 /**
  * Сброс (этап 6, п. 6). Предохранители — в базе: флаг allowReset установки, право letopis.reset,
  * подтверждение именем схемы. tenant — пачками (длинная операция не держит горизонт подписок).
@@ -153,6 +169,6 @@ export declare function rebuildAggregates(env: {
 }, cls: string): Promise<number>;
 /** Машинное описание модели арендатора вместе с метаданными классов (этап 6, п. 12). */
 export declare function describe(a: AdminCtx): ModelDescription;
-/** Описание модели текстом для языковых моделей (llms.txt). */
+/** Описание модели текстом для языковых моделей. */
 export declare function describeText(d: ModelDescription): string;
 export {};