letopis 1.4.0 → 1.4.2

package/AGENT-CHEATSHEET.en.md

@@ -32,7 +32,7 @@ const r = await up({ dsn: ADMIN, schema: 'myapp',                  // schema 'v2
   tenant: { name: 'Salon', user: { name: 'Olga', login: 'olga@salon.ru', password: 'Lilac-2026!' } } })
 // r: { schema, created, upgraded, revision, serviceKey, migrations, analyzed, tenant, … }
 // r.serviceKey ('lts_…') is the service key; it is issued at the first installation (again only if the installation has
-// no valid API keys left). Save it.
+// no API keys left except revoked ones). Save it.
 // r.tenant: { tenant, user, token, created } — the tenant "Salon" and its first user Olga
 ```
 - `up()` waits for the database, creates it, checks for PostgreSQL 18+ and UTF8, and installs the roles `letopis_owner`
@@ -82,10 +82,10 @@ db.tenant          // the session tenant: by default the account's own tenant (h
   allowBypassRls, models })`. `schema` is the **full** name with `v2.`.
 - `db.auth`: `setPassword`, `verifyPassword`, `issueApiKey`, `verifyApiKey`, `issueKeySecret`, `verifyKeySecret`,
   `enrollTotp`, `verifyTotp`, `totpEnabled`, `issueOtp`, `verifyOtp`, `link`, `lookup`, `credentials`, `revokeCredential`,
-  `setFlags`, `sessionFor(account, { ttl })`, `refresh`, `revoke`, `revokeAll`, `switch(tenant)`, `tenants()`,
-  `purgeAccount`. Password, OTP and TOTP checks, issuing sessions and confirming credentials are called by the
-  **service** (the `auth.*` permissions); a regular user gets `acl_denied`. Signatures:
-  `issueApiKey({ account, name?, ttl? })` → `{ key, id }`; `verifyApiKey(key)` → `{ token, account } | null`;
+  `setFlags`, `sessionFor(account, { ttl })`, `session(token)`, `refresh`, `revoke`, `revokeAll`, `switch(tenant)`,
+  `tenants()`, `purgeAccount`. Password, OTP and TOTP checks, issuing sessions, session details by token and
+  confirming credentials are called by the **service** (the `auth.*` permissions); a regular user gets `acl_denied`.
+  Signatures: `issueApiKey({ account, name?, ttl? })` → `{ key, id }`; `verifyApiKey(key)` → `{ token, account } | null`;
   `sessionFor(account, { ttl })` → a token string; then `connect({ dsn, schema, token })`, and to work in another
   tenant through a membership, `db.auth.switch(tenant)` (without it, the session is in the account's own tenant). The
   token for the CLI (`--token`) is the same `token` from `verifyPassword`/`verifyApiKey`/`sessionFor`. An admin
@@ -99,6 +99,11 @@ db.tenant          // the session tenant: by default the account's own tenant (h
   `issueKeySecret` with `account` set to the service id; `revokeCredential(id)`). Revoking a key revokes only the
   sessions of that key, so rotation has no downtime: new key → processes onto it → revoke the old one. The last active
   key of a service cannot be revoked (`acl_denied`); to disable a service, set `enabled: false` on its account.
+- Session by token: `svc.auth.session(token)` → `{ account, tenant, member, expiresAt, loginAt, methods } | null`.
+  The service (the `auth.session` permission) learns whose session it is, which tenant it works in and whether the
+  membership there is intact, without connecting with the token and without extending the session. A wrong, revoked
+  or expired token and a disabled account give `null`. This is how a web service checks the session from a cookie at
+  the start of every request: reading under a revoked session gives no error, the answers are simply empty.
 - Working in another tenant through a membership: `await user.auth.tenants()` → `[{ tenant, roles }]`, then
   `await user.auth.switch(tenant)` (only from the connection root). Impersonation by a service:
   `const u = await svc.as(account, { tenant, owner })` — the database checks it; in the journal, `author` is the user
@@ -189,6 +194,9 @@ await db.Wallet(or({ number: 'W-1' }, { number: 'W-200' })).ids()
   `{ Shop: id }`, `{ Shop: null }`. Fields are in `row.data`, not at the root of the row.
 - A step is a class name, an alias or an end role; a step by a parent class also returns descendants (`.exact()` —
   only its own class); `.deep(max)` — a tree (`$depth`); `.tags()`, `.owner()`, `.alias(name)`, `db.entity(row)`.
+- `after(cursorOf(row, field))` requires `sort()` by the same field; it pages `rows()`, `versions()` and `paths()` (the
+  cursor of a path is `cursorOf(path, field)`, the keys of a path follow the order of the steps). `count()`,
+  aggregates, `diff()`, `blame()` ignore the cursor.
 
 ### 6. Deletion with a preview
 
@@ -347,7 +355,7 @@ they drop out. A tenant with a source with `history: false` drops out (`invalid_
 `withBefore`) is the previous version of the same id or `null`: `null` for a creation, for the first version of a new
 id after `reclass` and `rekey` (the tombstone of the former id subtracts the former data), during a rebuild and when
 the previous version is a deletion (after `restore`) or lies outside the `from` family; `purge`, `trim` and `reset`
-have no such field, so subtract `before` only after checking it for `null`. A class change that keeps the id (a class
+have no such field (`undefined`), so subtract `before` only after checking that it is truthy: `if (c.before)`. A class change that keeps the id (a class
 without a key) and takes the row out of the `from` family comes as a deletion (`op` `delete`, `row` is the last
 version in the family with `$deleted`). `handle` gets the changes of one tenant. An error of its data (the
 database rejected its results, or `out` rejected its row or delta) rolls back only this tenant: it drops out
@@ -402,7 +410,7 @@ data, not instructions); `data` by terminal: `rows` — `{ rows, count, more, cu
 `{ ids, count, more, cursor? }` (`count` is the rows on the page), `first` — `{ row }`, `count` — `{ count }`,
 `countBy` — `{ counts, truncated? }`, `sum`, `avg`, `min`, `max` —
 `{ value }`. A refusal is `isError: true` with a `structuredContent` of the form `{ notice, error }` (`error` is
-`{ code, message, similar? }`). Writing only
+`{ code, message, detail?, sqlstate?, similar? }`). Writing only
 with `write: true` (without it `letopis_write` is not in the list, and a call is an SDK protocol error): `update` with
 `rev`; `delete` without `confirm` is a preview, with `confirm` a human confirms it (elicitation), and without that it
 is `confirmation_required`. Data from the database in an answer sits inside `<untrusted-data-…>`.

package/AGENT-CHEATSHEET.md

@@ -30,7 +30,7 @@ const r = await up({ dsn: ADMIN, schema: 'myapp',                  // схема
   tenant: { name: 'Салон', user: { name: 'Ольга', login: 'olga@salon.ru', password: 'Сирень-2026!' } } })
 // r: { schema, created, upgraded, revision, serviceKey, migrations, analyzed, tenant, … }
 // r.serviceKey ('lts_…') — ключ сервиса, выдаётся при первой установке (снова — только если в установке не осталось
-// действующих ключей API). Сохраните его.
+// ключей API, кроме отозванных). Сохраните его.
 // r.tenant: { tenant, user, token, created } — арендатор «Салон» и его первый пользователь Ольга
 ```
 - `up()` ждёт базу, создаёт её, проверяет PostgreSQL 18+ и UTF8, ставит роли `letopis_owner` и `letopis_app`.
@@ -77,14 +77,14 @@ db.tenant          // арендатор сессии: по умолчанию
   allowBypassRls, models })`. `schema` — **полное** имя с `v2.`.
 - `db.auth`: `setPassword`, `verifyPassword`, `issueApiKey`, `verifyApiKey`, `issueKeySecret`, `verifyKeySecret`,
   `enrollTotp`, `verifyTotp`, `totpEnabled`, `issueOtp`, `verifyOtp`, `link`, `lookup`, `credentials`, `revokeCredential`,
-  `setFlags`, `sessionFor(account, { ttl })`, `refresh`, `revoke`, `revokeAll`, `switch(tenant)`, `tenants()`,
-  `purgeAccount`. Проверку паролей, OTP и TOTP, выпуск сессий и подтверждение кредов вызывает **сервис** (права
-  `auth.*`); обычному пользователю — `acl_denied`. Сигнатуры: `issueApiKey({ account, name?, ttl? })` →
-  `{ key, id }`; `verifyApiKey(key)` → `{ token, account } | null`; `sessionFor(account, { ttl })` → строка-токен —
-  дальше `connect({ dsn, schema, token })`, а для работы в чужом арендаторе по членству — `db.auth.switch(арендатор)`
-  (без него сессия — в собственном арендаторе аккаунта). Токен для CLI (`--token`) — тот же `token` из
-  `verifyPassword`/`verifyApiKey`/`sessionFor`. Администраторское подключение (`allowBypassRls`) печатает
-  предупреждение «RLS не действует» — так и должно быть.
+  `setFlags`, `sessionFor(account, { ttl })`, `session(token)`, `refresh`, `revoke`, `revokeAll`, `switch(tenant)`,
+  `tenants()`, `purgeAccount`. Проверку паролей, OTP и TOTP, выпуск сессий, сведения о сессии по токену и
+  подтверждение кредов вызывает **сервис** (права `auth.*`); обычному пользователю — `acl_denied`. Сигнатуры:
+  `issueApiKey({ account, name?, ttl? })` → `{ key, id }`; `verifyApiKey(key)` → `{ token, account } | null`;
+  `sessionFor(account, { ttl })` → строка-токен — дальше `connect({ dsn, schema, token })`, а для работы в чужом
+  арендаторе по членству — `db.auth.switch(арендатор)` (без него сессия — в собственном арендаторе аккаунта). Токен для
+  CLI (`--token`) — тот же `token` из `verifyPassword`/`verifyApiKey`/`sessionFor`. Администраторское подключение
+  (`allowBypassRls`) печатает предупреждение «RLS не действует» — так и должно быть.
 - Второй фактор: `verifyPassword({ identifier, password, totp })` и `lookup({ kind, identifier, totp })` после первой
   проверки сверяют код TOTP (право `auth.totp`, счётчик неудач и блокировка — общие с `verifyTotp`) → сессия со
   способами `[вид, 'TOTP']`, по ней пользователь с TOTP меняет свои креды сам. Неверный или повторный код и код у
@@ -93,6 +93,11 @@ db.tenant          // арендатор сессии: по умолчанию
   `issueKeySecret` с `account` — id сервиса; `revokeCredential(id)`). Отзыв ключа гасит только сессии этого ключа —
   ротация без простоя: новый ключ → процессы на него → отзыв старого. Последний действующий ключ сервиса не
   отзывается (`acl_denied`); отключить сервис — `enabled: false` у его аккаунта.
+- Сессия по токену: `svc.auth.session(token)` → `{ account, tenant, member, expiresAt, loginAt, methods } | null`.
+  Сервис (право `auth.session`) узнаёт, чья сессия, в каком арендаторе она работает и цело ли там членство, не
+  подключаясь по токену и не продлевая сессию. Неверный, погашенный или истёкший токен и отключённый аккаунт —
+  `null`. Так веб-сервис проверяет сессию из cookie в начале каждого запроса: чтение по погашенной сессии ошибки не
+  даёт, ответы просто пустые.
 - Работа в чужом арендаторе по членству: `await user.auth.tenants()` → `[{ tenant, roles }]`, затем
   `await user.auth.switch(tenant)` (только от корня подключения). Имперсонация сервисом:
   `const u = await svc.as(account, { tenant, owner })` — проверяет база, в журнале `author` — пользователь,
@@ -182,6 +187,9 @@ await db.Wallet(or({ number: 'W-1' }, { number: 'W-200' })).ids()
   `{ Shop: null }`. Поля — в `row.data`, не в корне строки.
 - Шаг — имя класса, алиас или роль конца; шаг по родителю отдаёт и потомков (`.exact()` — только свой класс);
   `.deep(max)` — дерево (`$depth`); `.tags()`, `.owner()`, `.alias(имя)`, `db.entity(row)`.
+- `after(cursorOf(строка, поле))` требует `sort()` по тому же полю; листает `rows()`, `versions()` и `paths()` (курсор
+  пути — `cursorOf(путь, поле)`, ключи пути — в порядке шагов). `count()`, агрегаты, `diff()`, `blame()` курсор не
+  учитывают.
 
 ### 6. Удаление с превью
 
@@ -337,7 +345,7 @@ p.run().catch(report)         // run() без once — с catch: после ош
 Арендатор с источником `history: false` выбывает (`invalid_class`). `c.before` (с `withBefore`) —
 прошлая версия того же id или `null`: `null` при создании, у первой версии нового id после `reclass` и `rekey`
 (прежние данные вычитает надгробие прежнего id), при перестройке и когда прошлая версия — удаление (после `restore`)
-или вне семейства `from`; у `purge`, `trim` и `reset` поля нет — вычитайте `before`, только проверив его на `null`.
+или вне семейства `from`; у `purge`, `trim` и `reset` поля нет (`undefined`) — вычитайте `before`, только проверив его истинность: `if (c.before)`.
 Смена класса без смены id (класс без ключа), уводящая строку из семейства `from`, приходит удалением (`op` `delete`,
 `row` — последняя версия в семействе с `$deleted`). `handle` получает изменения
 одного арендатора. Ошибку его данных (база отклонила его результаты или `out` — его строку или приращение)
@@ -387,7 +395,7 @@ const server = await createMcpServer(await svc.as(userId))   // letopis_model, l
 (`notice` — постоянное пояснение, что это данные, а не инструкции); `data` по терминалам: `rows` —
 `{ rows, count, more, cursor? }`, `ids` — `{ ids, count, more, cursor? }` (`count` — строк на странице), `first` —
 `{ row }`, `count` — `{ count }`, `countBy` — `{ counts, truncated? }`, `sum`, `avg`, `min`, `max` — `{ value }`.
-Отказ — `isError: true` и `structuredContent` вида `{ notice, error }` (`error` — `{ code, message, similar? }`). Запись — только `write: true`
+Отказ — `isError: true` и `structuredContent` вида `{ notice, error }` (`error` — `{ code, message, detail?, sqlstate?, similar? }`). Запись — только `write: true`
 (без него `letopis_write` нет в списке, а вызов — ошибка протокола SDK): `update` с `rev`; `delete` без `confirm` —
 превью, с `confirm` — подтверждение человека (elicitation), без него — `confirmation_required`. Данные из базы в
 ответе — внутри `<untrusted-data-…>`.

package/CHANGELOG.md

@@ -1,6 +1,304 @@
 # Changelog
 
-Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
+Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver. Что обещают патч, минор и мажор, — раздел
+«Версии и совместимость» в README; шаг версии сверяет `npm run check:semver`. С 1.4.2 у правки ядра (библиотеки и SQL)
+в конце пункта указан источник находки: «Источник: тест», «пример», «сервис», «ревью», «soak» или «внедрение».
+
+## [1.4.2] — 2026-11-01
+
+План 2.0 (`reports/PLAN-LETOPIS-2.0.md`): правила версий, проверка перед выпуском, исправления.
+
+### Добавлено
+- Правила версий — подраздел «Версии и совместимость» в README (обе версии): патч — только исправления без новой
+  ревизии движка и без новых отказов; минор — новые возможности и новая ревизия с `up({ upgrade: true })`; мажор —
+  удаление, переименование, смена сигнатур и новые отказы.
+- `npm run check:semver` (`scripts/check-semver.mjs`): контракт API и ревизия движка текущего дерева против тега
+  прошлого выпуска — исчезло → мажор, появилось или выросла ревизия → минор, тексты ошибок → патч; шаг версии обязан
+  быть не меньше. Входит в `check:docs` (в CI checkout с полной историей) и в `release.yml` до публикации. Сборка
+  контракта вынесена в `scripts/contract.mjs`; в `docs/api-contract.json` появилось поле `codes` — коды ошибок.
+- `npm run prerelease` (`scripts/prerelease.mjs`) — полная локальная проверка одной командой, строго по очереди:
+  typecheck, сверка документов, весь `npm test`, примеры сайта со снимками, ER-схемы, покрытие, сборка сайта,
+  песочница, сценарии четырёх сервисов, проверка пакета с живым прогоном. Первый красный шаг останавливает прогон;
+  итог — таблица в `docs/checkpoint-<x.y.z>.md`. Тесты в CI не гоняются (решение владельца 01.11.2026).
+- Долгий прогон `npm run soak` (`bench/soak.mjs`, план 2.0, этап 2): смешанная нагрузка одного процесса на часы —
+  писатели с агрегатом и `inc`, читатели, подписки, проектор, `maintain()` с прореживанием под записью, вход и выход,
+  `db.as()`, заведение и удаление классов; замер раз в 5 минут, в конце — критерии §7.7 и `verify({ data: true })`.
+  Быстрый режим на 15 минут — шаг `soak` в `npm run prerelease`.
+- Метрика стабилизации: у правки ядра в CHANGELOG — источник находки, `release-notes.mjs` считает их в теле релиза.
+- Тест `upgrade` №3: накат схемы 1.4.1 (dev-зависимость `letopis-141`) обычным `up()` без миграций; правило — каждый
+  выпуск проверяет накат с предыдущего. Тесты `semver` и `prerelease` проверяют сами сценарии (план 2.0, 7.8).
+- `CONTRIBUTING.md` (и английская версия), шаблон issue об ошибке, форма отчёта о внедрении
+  `docs/adoption/TEMPLATE.md`.
+
+### Исправлено
+- Строки-замки удалённых классов не убирались: запись строки `Class` заводит две строки `LOCK` в `secret` (замок
+  семейства и его шлюз), а удаление класса их оставляло — приложение, которое заводит и удаляет классы на лету, копило
+  их без предела. Теперь `maintain()` убирает строки-замки семейств, чей корневой класс удалён (или удалён его
+  арендатор); строку, которую держит транзакция, — следующим вызовом; класс с тем же именем заводит их заново
+  (7.7 №8). Источник: soak.
+- `maintain()` мог безвозвратно стереть историю: если класс System заводили позже одноимённого класса арендатора,
+  строки журнала арендатора попадали в отбор дважды, и промежуточные версии ярусов стирались. Теперь политику выбирают
+  прореживание, `verify` и срок курсора подписки так же, как класс строки: свой класс арендатора, иначе System
+  (план 2.0, 7.3 №1). Источник: ревью.
+- История удалённого объекта стирается целиком и тогда, когда до `reclass` он был в классе без политики: версии
+  прежнего класса больше не остаются и не показывают объект живым в срезе (7.3 №2). Источник: ревью.
+- Стирание истории удалённого ждёт `restore()`, начатый в другой транзакции, и после него историю не трогает: раньше
+  цепочка восстановленного объекта начиналась не с версии 1 (7.3 №3). Источник: ревью.
+- `maintain()` чистит истёкшие сессии и коды один раз за вызов, в первой пачке, а не в каждой из пачек (до 100):
+  у функции базы `maintain` третий аргумент `p_cleanup`; схема, которую ещё не обновил `up()`, получает прежний
+  вызов (7.3 №4). Источник: ревью.
+
+- Два `create` одного ключа в батче проходили молча: обе строки ответа были одной и той же строкой. Теперь повтор —
+  `exists`, и батч откатывается целиком (7.2 №1). Источник: ревью.
+- Строки ответа `reclass`, `restore` и `rekey` — в порядке целей (`sort()` до глагола, иначе id), как обещает README;
+  в 1.4.1 так стало только у `update` и `anonymize` (7.2 №2). Источник: ревью.
+- Цепочка с глаголом и читающим хвостом в значении слота (`.Cat.add(db.Cat().create(…).Parent())`) падала с
+  `TypeError`; вложенный план не проходил проверки до базы. Теперь работает, а модификатор сразу после её глагола —
+  `invalid_query`, как у терминала (7.2 №3). Источник: ревью.
+- Кэш результатов отдавал общие объекты: правка `rows[0].data` у ответа `.cache()` портила следующие ответы. Теперь
+  кэш хранит и отдаёт копии (7.2 №5). Источник: ревью.
+
+- Подписка без событий опрашивала журнал сериями по 40 коротких повторов на каждый тик таймера — около 4 запросов в
+  секунду вместо одного за `pollMs`. Теперь короткие повторы идут только после сигнала (7.4 №1). Источник: ревью.
+- `close()` подключения не закрывал живые подписки: с чужим пулом (`connect({ sql })`) они опрашивали журнал и после
+  `close()`. Теперь подписки закрываются, ожидающий `next()` получает `done: true` (7.4 №8). Источник: ревью.
+
+- `reclass` класса без ключа (id тот же) сигналил только новый класс: ответы кэша и подписки прежнего класса не
+  сбрасывались и отдавали строку, которая из него ушла. Теперь сигнал идёт по обоим классам, как у пути через
+  триггер (7.4 №4). Источник: ревью.
+
+- `letopis types` падал на кириллическом имени класса (`invalid_class`, хотя такой идентификатор в TypeScript допустим),
+  а для класса без полей, класса с `anyOf`/`oneOf` и открытой схемы выдавал неверный TypeScript
+  (`export interface XData Record<string, unknown>`). Теперь имена — буквы Unicode, не-объекты — `export type`, ветки
+  `anyOf` из одних `required` у класса с полями — условие, а не форма (7.5 №1). Источник: ревью.
+- `hub('X', { fields: z.object(…) })` без других ключей описания читался как короткая форма — класс с единственным
+  полем `fields`. Теперь это полная форма (7.5 №2). Источник: ревью.
+- Понятные ошибки вместо сырых: `connect({ owner })` с ролью, которой нет, — `invalid_data`; `anonymize(['опечатка'])` —
+  «поля нет в классе»; `up()` на готовой роли владельца без ADMIN OPTION — объяснение, что нужно; `auth.switch` при
+  имперсонации сырым SQL — `acl_denied` из каталога, а не неизвестный код; `--trust` — `LetopisError` (7.5 №3).
+  Источник: ревью.
+- CLI: `letopis <команда> --help` возвращает код 0, неизвестная команда — справку с кодом 2 ещё до подключения к базе
+  (7.5 №4). Источник: ревью.
+- Сравнение имени проектора в `88-derived.sql` — той же коллацией, что индекс `secret_kind_ident` (7.5 №5). Источник:
+  ревью.
+
+- Срез `asOf` по классу и по концам показывал объект в классе, из которого он уже ушёл (`reclass` класса без ключа
+  сохраняет id): последняя версия выбиралась среди версий классов шага. Теперь она выбирается среди всех версий id, и
+  класс проверяется у неё — как уже делала ветка по id; то же в `trimHistory` по классам (7.1 №1). Источник: ревью.
+- `after()` в `versions()` молча не действовал: страница «после курсора» повторяла первую. Теперь курсор листает версии
+  в порядке `sort()`. Курсор версии несёт её `rev` (`cursorOf` кладёт его сам), поэтому версии одного объекта с равным
+  полем сортировки не теряются. Без `sort()` — `invalid_query`, как у `rows()`. `count()`, агрегаты, `diff()` и
+  `blame()` курсор не учитывают, README теперь это описывает (7.1 №4). Источник: ревью.
+- `paths()` с `after()` терял пути с общим последним узлом: курсор помнил только этот узел, и следующая страница
+  начиналась после всех путей к нему. Теперь `cursorOf(путь, поле)` кладёт в курсор id всех узлов (`path`), а пути
+  упорядочены по ним после поля и последнего узла. Ключи объекта пути идут в порядке шагов, как в примере README;
+  прежде они шли в порядке jsonb — по длине имени (7.1 №3). Источник: ревью.
+- `versions({ follow: true })`, `diff({ follow: true })` и `blame()` после `rekey` смешивали историю перенесённого
+  объекта с объектом, которого потом завели на прежнем id (тот же ключ): брались все версии всех связанных id.
+  Теперь история идёт по отрезкам между переносами — надгробие переноса кончает отрезок, первая версия на новом id
+  начинает (функция базы `history_segments`, обычный `up()`); у нового объекта своя история с его создания (7.1 №2).
+  Источник: ревью.
+- `blame()` на каждом новом соединении первые пять вызовов шли с квадратичной сложностью: свой план функции базы
+  `version_paths` по фильтру видимости оценивал версии в 2 строки и искал предыдущую версию по одному id, проверяя
+  номер фильтром, — около 250 мс на 1000 версиях и секунды на 10 000. Теперь обе версии ищутся по `(id, rev)` на
+  каждую пару: 21 мс с первого вызова (`bench/results/history.json`; ошибку нашёл замер `bench/history.bench.mjs`
+  при проверке 7.1 №2). Источник: тест.
+- Проектор не строил данных арендатора, который стал участником после первой проекции: изменения шли только с
+  курсора, строки, заведённые до вступления, в проекцию не попадали. Теперь чекпоинт хранит состав участников
+  (`tenants`), и новый участник получает начальную перестройку пачками (7.4 №5). Источник: ревью.
+- Проектор на подключении без LISTEN не перечитывал состав участников: сигнала о новых классах нет, и арендатор,
+  вступивший после запуска, не участвовал вовсе. Теперь состав читается в начале `run()` и не реже раза в 5 с (7.4 №6).
+  Источник: ревью.
+- Реестры классов `db.as()` копились без предела: процесс, который ходит от имени многих арендаторов, держал реестр
+  каждого и перечитывал их все на каждый сигнал классов. Теперь их не больше 1000 на подключение, давно не нужный
+  вытесняется; фасад с вытесненным реестром работает — реестр возвращается и перечитывается (7.4 №8). Источник: ревью.
+- Загрузчик с `existing: 'update'` писал в строку другого класса, если у неё тот же id: объект класса без ключа после
+  `reclass` сохраняет id, и повторный импорт по `$ext` правил его данными, проверенными по схеме прежнего класса, мимо
+  триггеров. Теперь такая строка — `exists` с классом объекта в тексте (7.2 №4). Источник: ревью.
+
+- Имя поля, в котором есть `@S@` (например, `a@S@b`), портилось в запросе цепочки: построитель подставлял на это место
+  имя схемы, и фильтр, `sort()` или агрегат по такому полю ничего не находили (7.1 №5). Источник: ревью.
+
+- После обрыва соединения транзакция проектора, `db.begin()` при открытии и загрузчик слали `rollback` в мёртвое
+  соединение и возвращали его в пул — postgres.js 3.4 ронял процесс необработанным `TypeError`. Теперь, как в
+  `runTx`: после обрыва в соединение не пишут и в пул его не возвращают, промис отклоняется (7.4 №7). Источник: ревью.
+
+- `watch({ from: 'start' })` после первой полной пачки событий старше яруса `all` падал с `cursor_expired`, хотя
+  обещан весь журнал. Теперь, пока подписка не догнала журнал, свои чтения она шлёт без срока курсора; курсоры
+  событий и `sub.cursor` время хранят, и продолжение с них после прореживания — по-прежнему `cursor_expired` (7.4 №3).
+  Источник: ревью.
+
+- Подписка на класс не получала события его потомков, заведённых после `watch()`: список потомков фиксировался при
+  подписке, и курсор уходил за их события. Теперь классы с потомками берутся из текущего реестра (7.4 №2).
+  Источник: ревью.
+
+### Изменено
+- CI: у задания `test` нет сервиса PostgreSQL (живой прогон пакета в CI выключен, база не нужна), комментарии
+  `ci.yml` описывают то, что задания делают.
+
+## [1.4.1] — 2026-11-01
+
+Исправления, найденные прогоном примеров документации для людей (`guide/`).
+
+По правилам версий, введённым в 1.4.2, часть изменений этого выпуска требовала минора (ревизия движка 7 с миграцией
+`0007`, новый метод `auth.session`), а новые отказы (`invalid_query` для модификатора после глагола, `acl_denied` для
+удаления `Account` System, код 1 у `letopis types` и `letopis describe` без сессии) и убранный код `not_implemented` —
+мажора.
+
+### Добавлено
+- `db.auth.session(token)` — сведения о сессии по её токену для сервиса: чья сессия (`account`), в каком арендаторе
+  она работает (`tenant`), цело ли там членство (`member`; в собственном арендаторе — всегда `true`), когда она
+  истечёт (`expiresAt`), когда и как был вход (`loginAt`, `methods`). Подключение по этому токену не открывается,
+  срок сессии не продлевается. Неверный, погашенный или истёкший токен и отключённый аккаунт — `null`, причина не
+  различается. Вызывает сервис или системный администратор (право `auth.session`, как у `sessionFor`); пользователю
+  отвечают `acl_denied`, вызову без сессии — `no_session`. В базе — функция владельца `auth_session_info(text)`, в
+  пакете — новый тип `SessionInfo`; в схеме метод появляется после повторного `up()`. Пробел нашли сервисы-примеры
+  сайта (салон, helpdesk). Helpdesk теперь проверяет сессию в начале каждого запроса через `svc.auth.session(token)`,
+  а не вызовом `auth.tenants()` по подключению пользователя.
+
+### Исправлено
+- `db.auth.purgeAccount(арендатор)` из сессии, которая работает в этом же арендаторе, откатывался с
+  `tenant_denied` («нет членства в арендаторе»): функция стирала членство вызывающего вместе с данными, а
+  надгробия и передача владения дальше перечитывали контекст. Теперь после проверки прав остаток операции идёт в
+  личном арендаторе вызывающего, его сессия больше не указывает на стёртого арендатора, а корень подключения
+  перечитывает арендатора и реестр. Подтверждает пример `guide/examples/auth/02-sessions-tenants.ts` (шаг 8):
+  без исправления он падает.
+- `commit()` явной транзакции (`db.begin()`), в которой ошибку поймали и проглотили, бросал сырую ошибку
+  PostgreSQL `25P02` вместо обещанного README `tx_rolled_back`: чтение `letopis.changed` в одном конвейере с
+  COMMIT падало раньше, чем COMMIT отвечал ROLLBACK. Теперь на `25P02` библиотека дожидается ответа COMMIT и
+  бросает `tx_rolled_back`. Подтверждает пример `guide/examples/errors/01-api-errors.ts` (шаг 7): без исправления
+  он падает с `25P02`.
+- Порядок надгробий одного уровня каскада в журнале (`seq`, время `at`) и строк итога
+  `delete({ confirm: true })` зависел от плана запроса и менялся от прогона к прогону: триггер удаления писал
+  надгробия вставкой без `order by`, а превью при этом шло по id. Теперь надгробия каждого уровня пишутся в порядке
+  id, итог — по уровням каскада, внутри уровня по id (README, раздел 7); цели классов без журнала — в конце, тоже по
+  id. Подтверждают примеры `guide/examples/delete/01-delete-cascade.ts` и `02-restore-purge.ts`: без исправления их
+  снимки то и дело расходятся порядком строк заказа.
+
+- Порядок записей журнала у остальных массовых операций тоже определён, а не зависит от плана запроса: пакетная
+  вставка — в порядке входа, правка многих строк, перестройка проектора, загрузчик с `existing: 'update'` — по id;
+  смена владельца при выходе из членства и `purgeAccount` идут по арендаторам по порядку; глаголы по списку целей без
+  `sort` (`restore`, `purge`, `reclass`, `rekey`) обходят цели по id.
+- Подписка, к которой больше суток (яруса `all` политики хранения её классов) не было событий, получала ложный
+  `cursor_expired`, хотя ничего не пропустила: время курсора оставалось временем последнего события, а база проверяет
+  его на каждом опросе. Теперь подписка, догнав журнал, ставит в свой курсор время опроса — «сейчас», но не позже самой
+  старой записи её классов, которая уже зафиксирована, а горизонт ещё не прошла; курсор события `ev.cursor` по-прежнему
+  хранит время события. `sub.cursor` больше не обгоняет события, прочитанные в запас: он стоит после последнего
+  события, которое отдал `next()`, поэтому продолжать после перезапуска нужно с него (README, раздел 12 «Подписка»).
+  Подтверждает пример `guide/examples/watch/02-quiet-cursor.ts`: без исправления шаг 3 падает с `cursor_expired`.
+- `connect({ maintain })` не проверял интервал: ноль, отрицательное число, `NaN`, `Infinity` или интервал длиннее
+  2³¹−1 мс (`'25d'`, `'30d'`) таймер Node.js превращал в 1 мс, и обслуживание шло без перерыва, а `null` и `true`
+  давали `TypeError`. Теперь интервал — число или строка, конечный, от 1 мс до 2³¹−1 мс (около 24 суток), иначе
+  `invalid_data`; проверка идёт до открытия пула и таймеров. `close()` ждёт идущий по расписанию запуск: он доделывает
+  текущую пачку и следующую не начинает, а пул закрывается после него. Подтверждает пример
+  `guide/examples/install/03-connect-options.ts` (шаг 6): без исправления подключения с такими интервалами открывались.
+- `createTenant` и `up({ tenant })` принимали любой `user.kind`: вид в другом регистре (`password`), пустой или
+  служебный (`SESSION`, `TOTP` …). По такому паролю нельзя было войти, а служебным видом пароль выдавал себя за другой
+  кред: с видом `TOTP` аккаунт выглядел так, будто у него включён второй фактор (`totpEnabled: true`), с видом
+  `SESSION` пароль пропадал из `auth.credentials()`. Теперь вид проверяется по правилу функций кредов (`^[A-Z][A-Z0-9_]{1,31}$`, не `SESSION`, `APIKEY`,
+  `KEYSECRET`, `OTP`, `TOTP`, `KEY`, `PROJECTOR`, `LOCK`), иначе `invalid_data` до записи. Подтверждает пример
+  `guide/examples/install/01-up-and-connect.ts` (шаг 4): без исправления арендатор создавался.
+- Параллельные `up()` разных схем одной базы падали с `tuple concurrently updated` (`XX000`): общую часть
+  установки — роли `letopis_owner` и `letopis_app`, членство установщика, pgcrypto и право владельца на схему pgcrypto —
+  каждый `up()` менял одновременно с другими, а `grant usage on schema` переписывает строку схемы в каталоге, даже если
+  право уже выдано. На чистой базе так же столкнулись бы `create role` и `create extension`. Теперь общая часть — одна
+  транзакция под advisory-блокировкой: следующий `up()` ждёт, пока предыдущий её зафиксирует. Блокировка действует в
+  пределах базы, а роли общие для кластера, поэтому роль или членство, которые одновременно создал `up()` в другой
+  базе, считаются уже созданными. Нашёл стенд сайта (`services/compose.yaml`): helpdesk падал при одновременном
+  запуске четырёх сервисов; без исправления 4 из 8 параллельных `up()` падали в каждом круге.
+- Одновременные `up()` одной и той же схемы (несколько экземпляров сервиса при запуске) падали: второй
+  `create schema` — на уникальном индексе каталога (`23505`), второй `create or replace function` или `comment` —
+  `tuple concurrently updated` (`XX000`), а `up({ tenant })` дважды вставлял того же арендатора. Ревизию, от которой
+  считаются миграции, `up()` читал до наката, поэтому второй `upgrade` повторил бы миграции, уже накатанные первым.
+  Теперь накат схемы — `fresh`, чтение ревизии, `create schema`, миграции, ядро, сиды и ключ сервиса — одна транзакция
+  под advisory-блокировкой схемы (ключ — её имя), и `createTenant` берёт ту же блокировку. Следующий `up()` ждёт
+  предыдущий и делает повторный накат по готовой схеме: `created` и `upgraded` он считает по ревизии, которую увидел
+  под блокировкой. `up()` разных схем друг друга не ждут. Подтверждает пример
+  `guide/examples/install/02-up-options.ts` (шаг 6): без исправления он падал 5 раз из 5.
+- `out.delete` и `out.get` проектора у производного класса с ключом, получив один id (строкой или `{ $id }`), искали
+  строку с пустым ключом: `get` отвечал `null`, а `delete` выводил арендатора с `id_mismatch`. Теперь это сразу
+  `invalid_data` с перечнем полей ключа — ошибка кода `handle`, пачка откатывается целиком; строку класса с ключом
+  называют полями ключа, id — только у класса без ключа (README, раздел 12 «Проекторы»). Подтверждает пример
+  `guide/examples/derived/03-projector-options.ts` (шаги 3 и 4): без исправления `get` по id отвечал `null`, а
+  `run()` проходил без ошибки.
+- Строки `secret` удалённого аккаунта хранились вечно: удаление строки `Account` гасило сессии и ставило способам
+  входа `deleted_at`, а `maintain()` физически убирает только сессии и коды вида `OTP` — хэши паролей и ключей,
+  секреты TOTP и внешние учётные записи удалённого аккаунта оставались в базе. Теперь их уносит внешний ключ
+  `secret.account → entity(id) on delete cascade` в том же операторе удаления. Сессии гаснут с сигналом
+  `session:<хэш>` раньше каскада — в новом триггере `entity_bd_account` (до удаления, для всех ролей, в том числе
+  владельца: аккаунты удаляют и каскад `trg_entity_ad`, и `purgeAccount`), поэтому процессы по-прежнему сбрасывают кэш
+  ответов этих сессий; пометка `deleted_at` в триггере удаления снята. Первая заливка снимает внешний ключ до `TRUNCATE`
+  и возвращает его после первичного ключа `entity`; `letopis import` пропускает креды аккаунтов, которых нет в
+  `Account` версии 0.21 (считает их в `skipped`). Подтверждает пример `guide/examples/auth/03-delete-account.ts`: без
+  исправления шаг 3 находит в `secret` три строки удалённого аккаунта, а шаг 4 не получает `acl_denied`.
+- Описание `maintain()` в README расходилось с кодом и JSDoc: он удаляет не только истёкшие сессии и коды, но и
+  погашенные сессии и использованные, заменённые или исчерпавшие попытки коды вида `OTP`. В README перечислены и
+  занятые виды кредов `PROJECTOR` и `LOCK`.
+- `.tags(has(…))`, `.tags(hasAny(…))` и `.tags(hasAll(…))` перед `update()` падали сырой ошибкой Node.js
+  `ERR_INVALID_ARG_TYPE`: оператор отбора библиотека пыталась записать в колонку тегов. Теперь оператор перед
+  `update()` только отбирает строки, а их теги не меняются; строка или список, как и раньше, и отбирают строки, и
+  заменяют их теги целиком. Подтверждает пример `guide/examples/write/05-batch-tags-reason.ts` (шаг 6): без
+  исправления он падает.
+
+- Срез `asOf()` и надгробия `withDeleted()` на обратном переходе отдавали объект столько раз, на сколько объектов
+  прошлого шага он ссылается: товар в двух категориях на шаге `db.Category().Product().asOf(t)` приходил в `rows()`
+  дважды, `count()` и итоги его удваивали. Без среза повторы отбрасывались, а пары переходов среза журнала шли в узел
+  как есть. Теперь узел — одна строка на объект, `paths()` по-прежнему отдаёт путь на каждую ссылку. Подтверждает
+  пример `guide/examples/history/01-versions-asof-diff-blame.ts` (шаг 6): без исправления он падает.
+- Строки ответа `update()` и `anonymize()` шли в порядке обхода таблицы, а не целей, поэтому `first()` после глагола
+  отдавал случайную из исправленных строк. Теперь ответ — в порядке целей: по `sort()` до глагола, без него — по id.
+  Подтверждает пример `guide/examples/write/01-create-update-upsert.ts` (шаг 7): без исправления он падает.
+- `maintain()` удалял только одноразовые коды вида `OTP`, а использованные и истёкшие коды своих видов `OTP_<ИМЯ>`
+  (`auth.issueOtp({ kind })`) оставались в `secret` навсегда. Теперь он удаляет коды всех видов, которые выпускает
+  `issueOtp`. Подтверждает пример `guide/examples/auth/01-login-factors.ts` (шаг 6): без исправления он падает.
+- `min()` и `max()` по логическому полю падали сырой ошибкой PostgreSQL (у `boolean` нет `min` и `max`). Теперь
+  `false` меньше `true`: `min` — `false`, если есть хоть одно `false`, `max` — `true`, если есть хоть одно `true`.
+  Подтверждает пример `guide/examples/read/03-sort-pages-aggregates.ts` (шаг 7).
+- `verifyHash()` и вход `auth.verifyPassword()` по хэшу scrypt, которому нужно больше 64 МБ памяти или с
+  недопустимыми N, r, p, бросали сырую ошибку Node.js; теперь — `invalid_data` с объяснением. `compileValidator()` с
+  шаблоном `pattern`, неверным для JavaScript, бросал `SyntaxError`; теперь — `invalid_class` с путём поля.
+  Подтверждает пример `guide/examples/models/06-exports.ts` (шаги 3 и 5).
+
+### Изменено
+- `letopis types` и `letopis describe` без действующей сессии (токен истёк, погашен, неверен или не задан) выдавали
+  пустой результат с кодом 0, а с `--out` затирали им файл. Теперь они выходят с кодом 1 и ошибкой `no_session`, файл
+  не трогают. Подтверждает пример `guide/examples/ops/04-cli.ts` (шаг 5).
+- `connect()` на схеме, ревизия которой новее пакета (её обновил более новый пакет), молчал; теперь он подключается и
+  предупреждает «обновите пакет letopis», как предупреждает об отставшей схеме. Подтверждает пример
+  `guide/examples/install/05-engine-stamp.ts` (шаг 4).
+- Описания методов (JSDoc), которые справочник сайта показывал непонятными, переписаны простыми словами: цепочка и
+  операторы фильтра, `db.as`, `db.verify`, `db.reset`, `db.trimHistory`, способы входа, подписка, проектор, загрузчик,
+  кэш, `up()` и `createTenant`, MCP, валидатор, константы. Исправлено неверное описание `InstallResult.serviceKey`:
+  новый ключ сервиса выпускается на любом накате, где не осталось ни одного неотозванного ключа API.
+- README: ключ сервиса `up()` выдаёт, когда не осталось ни одного ключа API, кроме отозванных (истёкший или
+  выключенный ключ тоже в счёт), — было «действующего»; класс из `into` проектора источником не бывает, даже если
+  попадает в `from`, — было «не может быть одновременно источником и результатом», будто это запрет.
+- Модификатор выборки (`limit`, `offset`, `sort`, `after`, `asOf`, `withDeleted`, `cache`) сразу после глагола, за
+  которым идёт терминал `rows`, `first`, `ids`, `count` или `paths`, — теперь `invalid_query` до записи. Раньше
+  `db.Product().update(…).limit(1).rows()` правил все товары, а в ответе отдавал одну строку; `offset`, `sort` и
+  остальные молча пропускались, а у `ids` и `count` — и `limit`. Цели глагола сужают модификаторы до него. В батче
+  так же отказывает `run()`. После глагола модификатор по-прежнему действует на чтение за ним (шаг класса,
+  `versions()`, `diff()`, `blame()`, агрегаты) и на цели следующего глагола. Подтверждают примеры
+  `guide/examples/write/01-create-update-upsert.ts` (шаг 8) и `guide/examples/write/05-batch-tags-reason.ts`
+  (шаг 9): без изменения они падают.
+- Ревизия движка 7: внешний ключ `secret.account` (миграция `0007` сначала стирает строки `secret`, чьих аккаунтов уже
+  нет в `entity`, затем ставит ключ) и индекс `secret_account`. Схемы ревизии 6 (1.1–1.4.0) обновляются через
+  `up({ upgrade: true })`: без него `up()` отказывает, а `connect()` предупреждает об отставшей ревизии.
+- Строку `Account` аккаунта System удалить нельзя — `acl_denied` (как уже отказывал `purgeAccount`): ему принадлежат
+  служебные строки установки в `secret` (ключ прав и сигналов, строки-замки, чекпоинты проекторов), которые каскад
+  внешнего ключа стёр бы. `seed_system()` создаёт аккаунт System раньше строки ключа.
+- Убран код ошибки `not_implemented` (охранник `notYet`): в 1.4 его не бросал ни один метод.
+- Тексты для людей:
+  - ошибка снятой опции `connect()` согласована по роду: «опция connect({ … }) снята в 1.0.0»;
+  - предупреждение о схеме, которую не обновили после смены пакета, — «обновите схему — вызовите up(…)» вместо
+    «накатите up(…)»;
+  - ошибка `rev_ambiguous` — «проверить версию { rev } можно только у одной цели» вместо «строгий режим только
+    для одной»;
+  - причина выбывания арендатора проектора по `lockRetries` (`status().failed`, код `55P03`) — «держит чужая
+    транзакция — в течение 3 проходов подряд дольше lockTimeout» вместо «— 3 проходов подряд…»: число и слово не
+    согласовывались («1 проходов», «3 проходов»).
+- Тест `retention` «7.8.1 №7» больше не зависит от даты: 29–31 числа «сейчас» эталона уходило в прошлое, и проверка
+  разрыва свежей версии падала при исправной библиотеке.
 
 ## [1.4.0] — 2026-10-29