letopis 1.4.0 → 1.4.2

package/README.md

@@ -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,14 +363,18 @@ 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 она одна, а функции разные. Поэтому `up()` пишет в комментарий схемы
-ещё и штамп движка: версию пакета и хэш его файлов SQL. Если штамп не совпадает с файлами пакета, `connect()`
+Ревизия меняется не с каждой версией: у 1.1–1.4.0 она одна (6), а функции разные. Поэтому `up()` пишет в комментарий
+схемы ещё и штамп движка: версию пакета и хэш его файлов SQL. Если штамп не совпадает с файлами пакета, `connect()`
 предупреждает. Когда схему накатила более старая версия (или версия до 1.4, у которой штампа нет), он советует
 `up({ schema })`. Когда схему уже обновила более новая версия, он советует обновить пакет: `up()` старой версией вернул
 бы прежние функции. Новая версия пакета без правок SQL штамп не меняет, и предупреждения нет.
@@ -374,10 +385,30 @@ const adm = await connect({ dsn: ADMIN, schema: r.schema, token: r.tenant!.token
 записи: `create index concurrently log_class_tenant_at on "v2.<схема>".log (class, tenant, at)` от роли владельца, —
 тогда `up()` только снимет прежний.
 
-Обновление схем 1.1.0 и 1.0.1 проверяет тест `upgrade`. Схему ставит прежний пакет, данные пишет прежний движок, затем
+Обновление схем 1.4.1, 1.1.0 и 1.0.1 проверяет тест `upgrade`; каждый выпуск проверяет обновление с предыдущего
+выпуска. Схему ставит прежний пакет, данные пишет прежний движок, затем
 вызывается `up()` текущей версии. После него версии и хэши прежнего движка на месте, `verify({ data: true })` чист, а
-каталог схемы совпадает с чистой установкой. Схема 1.1.0 обновляется простым `up()`: ревизия у неё та же. Схема 1.0.1
-обновляется через `up({ upgrade: true })`.
+каталог схемы совпадает с чистой установкой. Схема 1.4.1 той же ревизии 7 обновляется обычным `up()`, без миграций;
+1.1.0 (ревизия 6) и 1.0.1 (ревизия 5) — через `up({ upgrade: true })`: миграцией `0007` и миграциями `0006` и `0007`.
+
+### Версии и совместимость
+
+Версии letopis следуют semver. Что обещает каждый шаг версии:
+
+- **Патч** (1.4.1 → 1.4.2) — только исправления. Ревизия движка та же: исправленные функции накатывает обычный
+  `up({ schema })`, миграций нет; до наката `connect()` предупреждает о расхождении штампа. Работающий код не получает
+  новых отказов, методы, опции, экспорты и коды ошибок не исчезают.
+- **Минор** (1.4 → 1.5) — новые возможности: методы, опции, коды ошибок; изменения поведения, которые не ломают
+  работающий код; новая ревизия движка. Новую ревизию накатывает `up({ schema, upgrade: true })`. Удалённого и
+  переименованного нет.
+- **Мажор** (1.x → 2.0) — удаление и переименование методов, опций, экспортов и кодов ошибок, смена сигнатур и типов,
+  новые отказы для всех. Что менять в коде, описывает `MIGRATION.md`.
+
+Текст сообщения об ошибке в API не входит: в патче он может стать точнее. Полагайтесь на `err.code`.
+
+Шаг версии перед каждым выпуском сверяет сценарий `check:semver`: он сравнивает контракт API (`docs/api-contract.json`)
+и ревизию движка с прошлым выпуском и требует шаг не меньше нужного. Каждый выпуск проверяет обновление схемы с
+предыдущего выпуска (тест `upgrade`).
 
 ### Разработка без PostgreSQL: PGlite
 
@@ -602,8 +633,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. Запись
@@ -657,7 +689,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`
 
@@ -789,8 +822,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. Чтение
 
@@ -834,7 +873,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, …)` | любой из фильтров шага |
@@ -871,13 +910,18 @@ const page2 = await db.Product().sort('data.price', 'desc')
 `sort(поле, 'asc' | 'desc')` — по `'at'`, `'rev'`, `'id'` или `'data.<путь>'`. `after(cursorOf(строка, поле))` —
 постраничный вывод «после такой-то строки»; он требует `sort()`. Такой вывод устойчив к вставкам и удалениям между
 страницами, но строка, у которой изменилось поле сортировки, может выпасть или повториться. Курсор — объект
-`{ v, id }` (значение поля и id строки): он переживает JSON, и его можно отдать клиенту. Поле в `cursorOf` должно
+`{ v, id, rev }` (значение поля, id и номер версии строки): он переживает JSON, и его можно отдать клиенту. Поле в `cursorOf` должно
 совпадать с полем `sort`. Значение курсора проверяется по типу поля `sort` до запроса, неверное — `invalid_query`:
 числовому полю нужно конечное число, `rev` — целое, логическому — `true` или `false`, текстовому — строка, uuid и
 `id` — uuid, времени и `at` — строка ISO с поясом, дате — `ГГГГ-ММ-ДД`, полю без описания — строка, число или
 `true`/`false`. `null` подходит только полям данных, `id` курсора — всегда uuid. Курсор того же типа, снятый
 с другого поля, проверка не отличит. `limit` и `offset` тоже есть.
 
+`after()` листает и `versions()`: курсор версии несёт её `rev`, поэтому версии одного объекта с равным полем
+сортировки не теряются. В `paths()` курсор даёт `cursorOf(путь, поле)`: поле и id — последнего узла пути, а в `path`
+— id всех узлов, поэтому не теряются пути к одному узлу. Курсор `cursorOf(путь.Узел, поле)` с одного узла пропустит
+остальные пути к этому узлу. `count()`, агрегаты, `diff()` и `blame()` курсор не учитывают.
+
 Поле данных бывает `null` или отсутствует. Такие строки `sort` ставит, как `order by` в PostgreSQL: при
 возрастании — в конце, при убывании — в начале, а `after()` считает `null` значением после всех прочих (по
 возрастанию) или перед ними (по убыванию). Поэтому страницы проходят такие строки без пропусков и повторов, а
@@ -904,7 +948,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 отвечает ошибкой.
 
 ### Пути
 
@@ -913,7 +959,8 @@ const byStatus = await db.Order().countBy('data.status')          // { new: 1 }
 const orderPaths = await db.Order(order).line().Product().paths()   // [{ Order: Row, line: Row, Product: Row }, …]
 ```
 
-`paths()` отдаёт узлы каждого варианта пути; ключ узла — имя шага или имя из `.alias(имя)`. Повтор связи в
+`paths()` отдаёт узлы каждого варианта пути; ключ узла — имя шага или имя из `.alias(имя)`. Ключи идут в порядке
+шагов; если цепочка кончается возвратом к прежнему узлу, этот узел — последний. Повтор связи в
 цепочке возвращает к её узлу: так из одной связи можно пройти в несколько сторон. `db.entity(строка | цепочка)`
 вставляет готовый узел в путь.
 
@@ -936,10 +983,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` со списком видимых строк и числом
   остальных);
@@ -1221,7 +1269,7 @@ const changed = await adm.load({ Shop: [{ name: 'Василёк', city: 'Сам
 | Опция | Значения |
 |---|---|
 | `duplicates` — повтор id внутри загрузки | `'error'` (по умолчанию) — отменить; `'first'` или `'last'` — оставить первую или последнюю строку |
-| `existing` — объект уже есть в базе | `'error'` (по умолчанию) — отменить; `'skip'` — пропустить, удалённые не воскрешать; `'update'` — новая версия, если содержимое отличается (неизменённые считаются в `skipped`), удалённые — создать заново |
+| `existing` — объект уже есть в базе | `'error'` (по умолчанию) — отменить; `'skip'` — пропустить, удалённые не воскрешать; `'update'` — новая версия, если содержимое отличается (неизменённые считаются в `skipped`), удалённые — создать заново; объект другого класса с тем же id (класс без ключа после `reclass`) — `exists` |
 
 ### Порции, история и проверка
 
@@ -1389,8 +1437,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()
 ```
 
@@ -1403,13 +1453,23 @@ 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 })`. База проверяет право сервиса
 `auth.impersonate` (по правилам System), что пользователь существует и включён и что арендатор ему доступен —
 собственный или по членству. От имени System, сервисов, системных администраторов и отключённых аккаунтов
 действовать нельзя. Видимость пользователя по правилам доступа не проверяется. В журнале `author` — пользователь,
-`agent` — сервис. Подключение
+`agent` — сервис. Реестр классов `db.as()` — один на арендатора, подключение держит их не больше 1000: давно не
+нужный вытесняется, а фасад, чей реестр вытеснен, продолжает работать — реестр перечитывается. Подключение
 пользователя по своему токену переключается между арендаторами так:
 
 <!-- run: guide -->
@@ -1510,7 +1570,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. История и срезы на дату
 
@@ -1531,6 +1598,11 @@ const followed = await db.Product(mug2).versions({ follow: true }) // и чер
 `limit()` ограничивает их в самом запросе: `db.Product(kettle).sort('at', 'desc').limit(5).versions()` — пять
 последних версий, новые первыми.
 
+`follow: true` отдаёт историю объекта на всех его id: до переноса — версии прежнего id, после — нового. Объект,
+который потом завели на прежнем id (тот же ключ после `rekey`), — другой, и его версий в этой истории нет; его
+собственная история с `follow` начинается с его создания. Так же идут `diff({ follow: true })` и `blame()`. Без
+`follow` `versions()` отдаёт все версии id, чьи бы они ни были.
+
 ### Срез на дату
 
 <!-- run: guide -->
@@ -1627,7 +1699,8 @@ const diffed: DiffResult = {
   скаляр или массив в данных, пустой объект, роль одиночного конца, каждый id множественного конца
   (`['links', роль, id]`), каждый тег (`['tags', тег]`), `owner` и `class`. `rev`, `at`, `author`, `agent`, `op` и
   `reason` — от версии, которая последней изменила лист. Пустые `agent` и `reason` опускаются; `id` есть, только если
-  это версия прежнего id (история прошла через `reclass` или `rekey`).
+  это версия прежнего id (история прошла через `reclass` или `rekey`). Версии другого объекта на том же id — того,
+  что жил там до переноса или заведён после, — `blame()` не смотрит.
 - `exact: false` — между текущей версией и найденной есть пропуски (история прорежена, обрезана или часть версий не
   видна): лист мог менять и выпавшая версия. `complete: true` — история просмотрена целиком и без пропусков; по
   умолчанию просматривается не больше 1000 последних версий.
@@ -1671,7 +1744,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()) — остановить
 }
 ```
@@ -1689,10 +1762,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`.
 
 ### Проекторы
 
@@ -1774,7 +1850,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`: на строку — одна правка за пачку, а правило класса проверяется над итогом её
@@ -1822,9 +1900,13 @@ sales.close()                                    // stop() после текущ
   выбирает он: пользователь арендатора сам к проектору не подключится. Опция
   `tenants: [id, …]` — явный список участников: проектор работает только с этими арендаторами (их классы `into` тоже
   должны быть помечены), а пометку у остальных не учитывает. Источники — семейства `from` у этих арендаторов; класс
-  не может быть одновременно источником и результатом. Изменений класса с `history: false` проектор не видит:
-  журнала у него нет. Поэтому арендатор, у которого такой класс среди источников, выбывает с кодом `invalid_class`, и
-  его производных строк проектор не строит. Включите журнал класса и перестройте арендатора `rebuild({ tenant })`.
+  из `into` источником не бывает, даже если попадает в `from`: свои результаты проектор не читает. Изменений класса
+  с `history: false` проектор не видит: журнала у него нет. Поэтому арендатор, у которого такой класс среди
+  источников, выбывает с кодом `invalid_class`, и его производных строк проектор не строит. Включите журнал класса и перестройте арендатора `rebuild({ tenant })`.
+- Арендатор, который стал участником после первой проекции (администратор пометил его классы позже), получает
+  начальную перестройку пачками: в проекцию попадают и строки, заведённые до вступления. Состав участников проектор
+  перечитывает по сигналу классов, а на подключении без LISTEN (`listen: false`) — в начале `run()` и не реже раза
+  в 5 секунд.
 - `batch` — сколько изменений в пачке (500), `pollMs` — запасной опрос (1000 мс): сигналы источников будят
   проектор раньше.
 - `lockTimeout` — сколько транзакция проектора ждёт чужую блокировку строки (5000 мс; 0 — без предела). Транзакция
@@ -1914,7 +1996,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` — по любому
@@ -1934,10 +2018,17 @@ 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`, а между пачками останавливается (продолжит тот
@@ -2139,6 +2230,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 })`: хук получает на каждый запрос цепочки режим, классы, длительность, число строк и
@@ -2256,17 +2350,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 })`.
 
 ### Проектор
 
@@ -2283,7 +2379,7 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `stop()`, `close()` | остановить `run()` после текущей пачки; то же и отписаться от сигналов |
 | `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 — только у класса без ключа |
 
 ### Строка ответа
 
@@ -2300,8 +2396,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`,
@@ -2358,7 +2456,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` | перестройку не начать: проектор сейчас работает в другом процессе |
@@ -2431,7 +2529,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 **Платформа**
 
 - Нужен PostgreSQL 18 или новее; обходных путей для 15–17 нет. AWS RDS, Google Cloud SQL, Azure Flexible Server
-  и Neon поддерживают 18, а Supabase на октябрь 2026 года — только 15 и 17, поэтому там 1.0 не заработает.
+  и Neon поддерживают 18, а Supabase на октябрь 2026 года — только 15 и 17, поэтому там letopis не заработает.
 - База — в кодировке UTF8 (`casefold()` и коллация `pg_unicode_fast`). Если новая основная версия PostgreSQL
   обновит таблицы Unicode, уникальный индекс идентификаторов кредов перестраивается командой `reindex`.
 - PGlite — одно соединение суперпользователя: без параллельных писателей и `LISTEN`, RLS не действует
@@ -2489,8 +2587,8 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 - Горячие цели ссылок (организация, на которую ссылается почти всё) копят блокировки `for key share` и MultiXact,
   как при обычных внешних ключах; это нужно мониторить. Операции одного кошелька идут друг за другом под
   блокировкой его строки ([раздел 8](#8-транзакции-батчи-и-деньги), «Рецепт: кошелёк»).
-- Связь не может называться зарезервированным именем, а хаб с таким именем недостижим как шаг
-  ([«Зарезервированные имена»](#зарезервированные-имена)).
+- Связь не может называться зарезервированным именем, а хаб с таким именем доступен не везде: например, `count` —
+  только первым шагом ([«Зарезервированные имена»](#зарезервированные-имена)).
 
 **Доступ**
 
@@ -2629,6 +2727,12 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 Раздел — для тех, кто развивает сам letopis. Запуск: `cd lib && npm test`. Обвязка сама поднимает контейнер `letopis-pg18` (`postgres:18`,
 порт 15433), если база не отвечает; каждый тестовый файл работает в своей схеме `v2.t_<имя>`.
 
+В CI тестов нет: перед пушем и выпуском всё, что проверяет поведение, идёт одной командой `cd lib && npm run prerelease` —
+по очереди typecheck, сверка документов, все тесты, примеры сайта со снимками, песочница, сценарии сервисов, быстрый
+долгий прогон (15 минут смешанной нагрузки) и проверка пакета с живым прогоном; первый красный шаг останавливает
+прогон. Та же нагрузка на сутки — `cd lib && npm run soak` (длительность — `SOAK_HOURS`, по умолчанию 24 часа). Тест
+исправления называется пунктом тест-плана («план 2.0, 7.3 №1») и без исправления падает.
+
 ```
 # connect — подключение под сессией, отказ ролям в обход RLS, реестр, отложенный сигнал, перевод ошибок (этап 2)
 # context — сессии, вход сервиса по ключу, политики RLS этапа 1 (этап 1)
@@ -2675,9 +2779,9 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 # retention — политика хранения: ярусы, конечный срок, особые версии, удалённые, asOf, cursor_expired, часовой пояс, догоняющий запуск, наследование и умолчание — против эталона на TypeScript (этап 6)
 # watch — подписка по курсору: порядок фиксации, долгая транзакция, возобновление, обрыв слушателя, два арендатора (этап 6)
 # cache — кэш результатов: попадание, свои и чужие записи, ключ с пользователем, права, погашенные сессии, обрыв слушателя, ttl, пометка класса, без LISTEN, гонка, db.sql, предел счётчиков сигналов (этап 6; план 1.1, точка А)
-# maintain — обслуживание: истёкшие сессии и коды, права, один процесс под блокировкой, расписание (этап 6)
+# 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.4.1 (обычный up() без миграций, план 2.0, 7.8 №2), с 1.1.0 (upgrade: true, миграция 0007) и с 1.0.1 (upgrade: true, миграции 0006 и 0007) пакетами letopis-141, 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 и точка А)
@@ -2687,4 +2791,10 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 # mcp — инструменты MCP: модель и meta только в результатах, права арендатора, JSON-цепочка и подсказки похожих имён, предел строк и байт с курсором, обёртка недоверенных данных, запись только с write, update только с rev, удаление с подтверждением человека (elicitation в ревизиях 2025 и 2026-07-28), причина в blame, учётные данные, схемы инструментов, letopis без SDK; letopis mcp по stdio, обработчик HTTP; окно подтверждения без алиаса и meta, countBy и versions с пределом в самом запросе, предел шагов и условий $or; классы прав — только с allowAclWrite, сессия в арендаторе System — только с allowSystemAdmin; structuredContent с пояснением, подпись requestState пользователя сервера со сроком (план 1.1, этап 5; ревью безопасности №2; точка Б и доработки после неё)
 # import — импорт из 0.21 по фикстуре настоящей 0.21: нарушение ключа, --keyless, счётчики по классам, verify, самоссылка, повтор, id без ключа, висячая ссылка, $$strict и поля на $, update, креды, CLI (этап 7)
 # security-final — итоговое ревью безопасности (этап 8, §7.10 №8.4): блокировка семейства по арендатору корня, account_purge без права и restore/purge чужого id не дают ни утечки, ни блокировки; функции этапа 6, log_refs_at, срезы find_* по журналу и watch_read не выходят за свой арендатор; NOTIFY несёт только имена или токены режима; ключ кэша различает токен, актора и арендатора (этап 8)
+# semver — правила версий: check:semver требует шаг версии не меньше нужного — мажор за исчезнувший метод или код ошибки, минор за новый метод и новую ревизию движка, патча хватает на тексты (план 2.0, 7.8 №1)
+# prerelease — проверка перед выпуском: шаги идут строго по очереди, первый красный останавливает прогон, следующие не запускаются (план 2.0, 7.8 №3)
+# write-contract — обещания README о записи (план 2.0, 7.2): повтор ключа в батче — exists и откат, порядок строк ответа reclass, restore и rekey, цепочка с глаголом в значении слота, загрузчик с existing: update не правит строку другого класса, ответ из кэша не портится правкой прошлого ответа
+# watch-contract — обещания README о подписке и подключении (план 2.0, 7.4): молчащая подписка опрашивает журнал раз в pollMs, close() подключения закрывает живые подписки, reclass без ключа сбрасывает кэш прежнего класса, новый участник проектора получает начальную перестройку, проектор без LISTEN перечитывает состав, реестров db.as() не больше предела
+# model-contract — обещания README о моделях, типах, CLI и ошибках (план 2.0, 7.5): letopis types — верный TypeScript для кириллицы, класса без полей и anyOf, полная форма hub() с z.object, понятные ошибки вместо сырых, коды выхода CLI
+# read-contract — обещания README о чтении и истории (план 2.0, 7.1): срез asOf по классу и по концам после смены класса без смены id, versions, diff и blame с follow после rekey, курсор after() в versions() и paths(), имя поля с @S@
 ```

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;