letopis 1.3.0 → 1.4.1

package/AGENT-CHEATSHEET.en.md

@@ -1,4 +1,4 @@
-# letopis 1.3 — agent cheatsheet
+# letopis 1.4 — agent cheatsheet
 
 One page instead of [README.en.md](README.en.md), for an AI agent that writes code on top of the package. It ships in
 the package next to the README; in Russian: [Русская версия](AGENT-CHEATSHEET.md). Migration from 0.21:
@@ -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`
@@ -49,6 +49,9 @@ const r = await up({ dsn: ADMIN, schema: 'myapp',                  // schema 'v2
   schema: `up()` without the option keeps it; after a change, restart the processes. The signal key (precise cache
   clearing) goes to services — the `letopis.signals` permission. The `up()` result also has `signals` and `warnings`
   (PostgreSQL below 18.2 — upgrade).
+- After a package update, call `up()`: only it re-applies the schema functions. `connect()` warns if the engine stamp
+  in the schema comment (package version and a hash of its SQL) does not match the package: an older schema — `up()`,
+  a newer one — update the package.
 - `tenant` — the first tenant and user without a seed of your own: the tenant gets the rule "authenticated users may
   do everything" (`grantAll`, on by default, weight 10); the user gets a membership with the roles `user.roles`
   (`['owner']` by default), a password for signing in with the login `login`, and a session in the tenant. Repeating
@@ -79,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
@@ -96,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

package/AGENT-CHEATSHEET.md

@@ -1,4 +1,4 @@
-# letopis 1.3 — шпаргалка для агента
+# letopis 1.4 — шпаргалка для агента
 
 Одна страница вместо [README.md](README.md) — для ИИ-агента, который пишет код поверх пакета. Лежит в пакете рядом с
 README; английская версия — [AGENT-CHEATSHEET.en.md](AGENT-CHEATSHEET.en.md). Переход с 0.21 — [MIGRATION.md](MIGRATION.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`.
@@ -45,6 +45,9 @@ const r = await up({ dsn: ADMIN, schema: 'myapp',                  // схема
   `session:<16 hex>` — погашенная сессия, `session:*` и `*` — сбросы (`reset`). Режим хранится в схеме: `up()` без
   опции его не меняет; после смены — перезапуск процессов. Ключ сигналов (точный сброс кэша) получают сервисы — право
   `letopis.signals`. Результат `up()`: ещё `signals` и `warnings` (PostgreSQL ниже 18.2 — обновить).
+- После обновления пакета вызывайте `up()`: функции схемы накатывает только он. `connect()` предупреждает, если штамп
+  движка в комментарии схемы (версия пакета и хэш его SQL) не совпадает с пакетом: схема старее — `up()`, новее —
+  обновить пакет.
 - `tenant` — первый арендатор и пользователь без своего сида: арендатор получает правило «аутентифицированным можно
   всё» (`grantAll`, по умолчанию да, вес 10), пользователь — членство с ролями `user.roles` (по умолчанию `['owner']`),
   пароль для входа по логину `login` и сессию в арендаторе. Повтор с тем же именем и логином ничего не дублирует и роли
@@ -74,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 меняет свои креды сам. Неверный или повторный код и код у
@@ -90,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` — пользователь,

package/CHANGELOG.md

@@ -2,6 +2,253 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [1.4.1] — 2026-11-01
+
+Исправления, найденные прогоном примеров документации для людей (`guide/`).
+
+### Добавлено
+- `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
+
+letopis 1.4 — доработки после выпуска 1.3.0. Вошли:
+- хвост ревью безопасности доработок после 1.2.0 — все девять замечаний, плюс находка автоматического ревью:
+  администратора база определяла по роли входа, а не по действующей роли сеанса;
+- штамп версии движка в схеме: `connect()` замечает схему, которую после обновления пакета не накатили;
+- опция проектора `lockRetries`.
+
+Версия `1.4.0` (во время работы — `1.4.0-alpha.0`, не публиковалась). Схема 1.3.0 обновляется повторным `up()`:
+ревизия движка прежняя (6), функции накатываются заново. До наката `connect()` новой версии предупреждает о схеме без
+штампа и советует `up({ schema })`. Новое в API:
+- опция проектора `lockRetries` и поле отчёта `ProjectorReport.locked`;
+- штамп движка в комментарии схемы и предупреждение `connect()` о схеме другой версии.
+
+Поведение, которое стоит проверить при обновлении:
+- на подключении, где роль приложения поставлена поверх привилегированной роли входа (`SET ROLE`, параметр запуска
+  `role`), пользователи больше не получают права `letopis.*`;
+- новый источник агрегата должен без условий читать и тот, кто описал агрегат, иначе `acl_denied`; агрегат можно
+  описать заново от того, кто читает;
+- предки и алиас класса System больше не дают прав на строки одноимённого класса арендатора;
+- запись, дождавшаяся удаления своего класса, получает `invalid_class` «класс … удалён».
+
+### Added — проектор: изоляция арендаторов при чужой блокировке
+- Опция проектора `lockRetries` (решение владельца, кандидат 6 из 10 «`lockTimeout` не изолирует арендаторов»). Задаёт,
+  сколько проходов подряд запись одного арендатора может упираться в `lockTimeout`. Дальше арендатор выбывает с кодом
+  `55P03`, и пачка идёт для остальных; его изменения пропускаются до `rebuild({ tenant })`. По умолчанию 0: арендатор
+  не выбывает, и проход повторяется для всех, как раньше. Счёт ведёт процесс, удачная запись арендатора его
+  сбрасывает.
+- Отчёт `run()` называет арендаторов, на чьей строке вставала пачка: новое поле `ProjectorReport.locked`.
+- `rebuild({ tenant, chunked: true })` пережидает чужую блокировку строки арендатора (кандидат 5 из 10). Раньше
+  `startTenant` отдавал вызывающему сырую ошибку 55P03, хотя состояние не портилось. Так же ведёт себя чтение
+  чекпоинта в конце перестройки, а пропущенные из-за блокировки проходы идут в `skipped`.
+
+### Added — штамп движка в схеме
+- `up()` пишет в комментарий схемы, кроме ревизии, штамп движка: версию пакета и 16 знаков sha256 исходного текста
+  файлов `sql/NN-*.sql` (`'letopis ddl_revision=6 engine=1.4.0 sql=…'`). Ревизия у 1.1–1.4 одна, а функции разные, и
+  `connect()` раньше не замечал схему, которую после обновления пакета не накатили (так было при 1.1 → 1.2).
+- `connect()` при той же ревизии сверяет штамп с файлами своего пакета и при расхождении предупреждает
+  (`console.warn`). Схема без штампа (до 1.4) или со штампом более старой версии — совет `up({ schema })`. Штамп более
+  новой версии — совет обновить пакет: `up()` старой версией вернул бы прежние функции. Новая версия пакета без правок
+  SQL штамп не меняет. Если файлов SQL рядом со сборкой нет, сверка молча пропускается.
+
+### Security — хвост ревью безопасности доработок после 1.2.0
+- `purge` и `trimHistory` проверяют, прочёл ли проектор источника каждую версию строки, а не одну (кандидат 5 из 10).
+  Раньше `purge` смотрел только надгробие, а обрезка — самую позднюю по `(tx, seq)` версию у стыка. Но у более поздней
+  версии бывает меньший xid, а снимок перестройки учитывает транзакции, зафиксированные до него. Поэтому непрочитанной
+  могла остаться версия, которую проверка пропускала, и `purge` или обрезка стирали её. Проверку делает функция
+  владельца `projector_unread(uuid, uuid, int)`, прежняя `projector_behind` удаляется при накате.
+- Удаление класса больше не расходится с параллельной записью (кандидат 5 из 10, «гонка смены алиаса и удаления
+  потомка»). Удаление проверяет, что у класса нет строк, потомков и истории, но раньше проверка не видела строку, которую
+  писатель ещё не зафиксировал: строка оставалась без класса, а вместе с ней появлялась история удалённого класса, от
+  которой зависит запрет смены алиаса предка. Теперь так:
+  - удаление класса берёт исключительную блокировку его семейства, поэтому ждёт писателей и видит их строки;
+  - создание класса и смена `parent` берут разделяемую блокировку семейства родителя, поэтому родитель не удаляется мимо
+    нового потомка;
+  - писатель, дождавшийся блокировки, проверяет, что класс ещё есть (`invalid_class`, «класс … удалён»). Так делают
+    вставка, правка, `reclass`, `restore`, `rekey` и запись проектора.
+- План прав берёт один класс на имя — тот, что находит `class_row`: свой класс арендатора, иначе класс System (замечание
+  `/security-review` ниже порога). Раньше в план попадали оба одноимённых класса, и побеждало разрешение любого из них.
+  Поэтому предки и алиас класса System, заведённого после класса арендатора, давали права на строки класса арендатора.
+- Правка класса System без права `letopis.projector` больше не упирается в производных потомков у арендаторов со своим
+  одноимённым классом (кандидат 5 из 10, лишняя строгость): их потомки наследуют класс арендатора, а не класс System.
+- Подписка подключения в обход RLS получает события ухода строки из классов подписки (кандидат 6 из 10). Раньше без
+  сессии `watch_leaving` их не отдавал (`acl_actor` — null), хотя `watch_read` такому подключению отдаёт журнал всех
+  арендаторов. Теперь роль сеанса (суперпользователь, `BYPASSRLS`, член роли-владельца) видит все события ухода, с
+  автором.
+- Администратором и подключением в обход RLS база считает действующую роль сеанса, а не роль входа (находка
+  автоматического ревью коммита). Внутри функции владельца `session_user` — роль входа, даже если поверх неё поставлена
+  роль приложения (`SET ROLE` или параметр запуска `role`). Так бывает у пула с одной привилегированной ролью входа: там
+  `connect()` видит роль приложения, а `admin_role()` с 1.0 видела суперпользователя. Поэтому любой пользователь
+  арендатора на таком подключении получал права `letopis.*` (`verify`, `reset`, `letopis.projector` и другие), а
+  подписка — события ухода чужих арендаторов. Новая функция владельца `session_role()` берёт роль `SET ROLE`, иначе роль
+  входа; через неё работают `admin_role()` и `watch_leaving`.
+- Новый источник агрегата проверяется и по тому, кто описал агрегат (кандидат 6 из 10, решение владельца). Раньше право
+  `READ` проверялось только у того, кто заводит потомка источника (или переносит класс под него сменой `parent`). Тот,
+  кто описал агрегат без права на строки будущего потомка, читал бы в истории цели вклад каждой из них. Теперь
+  описавший тоже должен без условий читать все строки нового источника, иначе `acl_denied`; агрегат можно описать
+  заново от того, кто их читает. Описавший — автор версии строки `Class` цели, с которой описание агрегата (своё или
+  унаследованное) стало нынешним; журнал строк `Class` не стирается. Объём проверки — как при описании: у агрегата
+  класса арендатора — классы арендатора, у агрегата класса System — классы System; класс арендатора под агрегатом System
+  проверяет только заводящий.
+
+### Fixed — хвост ревью безопасности доработок после 1.2.0
+- `syncModels` отклоняет модели по кругу до записи: `invalid_class` называет круг (кандидат 4 из 10). Пример — агрегат
+  над собственным потомком: потомок ждёт родителя, а цель ждёт источник агрегата. Раньше обход молча ставил потомка
+  раньше предка, и база отвечала «предок … не найден». В два шага такой агрегат отклоняет уже база: потомок наследует
+  агрегат над самим собой, и выходит «цикл агрегатов».
+
 ## [1.3.0] — 2026-10-28
 
 letopis 1.3 — доработки после выпуска 1.2.0 (`docs/checkpoint-1.3.md`). Вошли три направления: