letopis 1.2.0 → 1.4.0

package/AGENT-CHEATSHEET.en.md

@@ -1,4 +1,4 @@
-# letopis 1.2 — 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:
@@ -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
@@ -263,7 +266,7 @@ const canDelete = await olga.acl.checkData('Wallet', 'DELETE')    // { allow: fa
 
 <!-- run -->
 ```ts
-const sub = db.watch({ from: 'start', classes: ['Wallet'] })  // from: 'now' (default) | 'start' | a cursor; pollMs
+const sub = db.watch({ from: 'start', classes: ['Wallet'] })  // from: 'now' (default) | 'start' | a cursor; pollMs; leaving classes — op 'delete'
 const lagMs = await sub.lag()                                  // lag, ms
 await db.Wallet(w).update({ balance: inc(1) }).rows()
 let cursor = ''
@@ -325,8 +328,8 @@ npx letopis import --from "$ADMIN" --from-schema v1.fixture --dsn "$ADMIN" --sch
 
 A projector builds rows of derived classes from the journal: summaries, cards, anything that may be computed with a
 lag. A derived class is marked with `derivedBy: 'projector-name'`, and only this projector writes its rows. The
-derived class itself (own or inherited) is created, edited and deleted only by an administrator: `syncModels` on an
-admin connection holding a tenant session (`connect({ dsn: ADMIN, schema, token, allowBypassRls: true })`) or an
+derived class itself (own or inherited) and its ancestors are created, edited and deleted only by an administrator:
+`syncModels` on an admin connection holding a tenant session (`connect({ dsn: ADMIN, schema, token, allowBypassRls: true })`) or an
 account with the System permission `letopis.projector`; for an application session it is `acl_denied`. Everyone whom
 the rules give `READ` on a derived class sees its totals, even without permissions on the source rows.
 ```ts
@@ -348,7 +351,7 @@ have no such field, so subtract `before` only after checking it for `null`. A cl
 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
-(`status().failed`: `{ id: { cursor, code, message } }`) until `rebuild({ tenant: id })` (`{ tenant, chunked: true }` — in batches while the tail goes on for all;
+(`status().failed`: `{ id: { cursor, code, message } }`) until `rebuild({ tenant: id })` (`{ tenant, chunked: true }` — in batches while the tail goes on for all, an interrupted one is continued by any `run()`;
 `status().rebuildingTenants`), and the others go on; with `onExpired: 'rebuild'` a tenant dropped by the tier rebuilds
 itself in batches, in any process;
 `tenants: [id, …]` is an explicit list of participants.
@@ -374,7 +377,9 @@ A trigger recalculates the field after every statement (the library, raw SQL, a
 `rekey`, the loader); going below `minimum` is `invalid_data`, every change is a version of the target. Live rows of
 the same tenant are counted (a System row is not). Repair: `adm.rebuildAggregates('Wallet')` on an admin connection;
 discrepancies: `verify({ data: true })`. Only someone who reads all rows of the source and its descendants without
-conditions can describe or change an aggregate, otherwise `acl_denied`. A hot counter (more than ~150 writes per
+conditions can describe or change an aggregate, otherwise `acl_denied`. The source is described before the aggregate:
+an aggregate over a class that does not exist yet is refused (`invalid_class`), and the `of` class is not deleted while an
+aggregate names it; `syncModels` puts sources before targets itself. A hot counter (more than ~150 writes per
 second per object) is a projector that folds a batch, not an aggregate.
 
 ### 14. Agents and MCP
@@ -422,7 +427,7 @@ await adm.close(); await db.close(); await svc.close()
    if the row was deleted between the lookup and the edit.
 3. **Verbs return a chain.** Without a terminal (`.rows()`, `.first()` …) nothing runs. `delete()` without
    `{ confirm: true }` is only a preview; `purge` works only on deleted entities (`not_deleted`) and once a projector
-   of the class has read the deletion (`projector_pending`).
+   of the class has read the deletion (`projector_pending`); `trimHistory`, once the projector has read the versions.
 4. **Money and counters**: `update({ balance: inc(n) })` — the database adds inside the statement, without a read and
    without lost updates; the `minimum` check in the schema catches a drop below zero. For a total computed from what
    you read, use `{ rev }` (re-read and retry on `conflict`) or `forUpdate()` in `db.begin()`. Idempotency comes from

package/AGENT-CHEATSHEET.md

@@ -1,4 +1,4 @@
-# letopis 1.2 — шпаргалка для агента
+# letopis 1.4 — шпаргалка для агента
 
 Одна страница вместо [README.md](README.md) — для ИИ-агента, который пишет код поверх пакета. Лежит в пакете рядом с
 README; английская версия — [AGENT-CHEATSHEET.en.md](AGENT-CHEATSHEET.en.md). Переход с 0.21 — [MIGRATION.md](MIGRATION.md);
@@ -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` и сессию в арендаторе. Повтор с тем же именем и логином ничего не дублирует и роли
@@ -254,7 +257,7 @@ const canDelete = await olga.acl.checkData('Wallet', 'DELETE')    // { allow: fa
 
 <!-- run -->
 ```ts
-const sub = db.watch({ from: 'start', classes: ['Wallet'] })  // from: 'now' (по умолчанию) | 'start' | курсор; pollMs
+const sub = db.watch({ from: 'start', classes: ['Wallet'] })  // from: 'now' (по умолчанию) | 'start' | курсор; pollMs; уход из classes — op 'delete'
 const lagMs = await sub.lag()                                  // отставание, мс
 await db.Wallet(w).update({ balance: inc(1) }).rows()
 let cursor = ''
@@ -316,8 +319,8 @@ npx letopis import --from "$ADMIN" --from-schema v1.fixture --dsn "$ADMIN" --sch
 
 Проектор строит строки производных классов из журнала: сводки, карточки, всё, что можно считать с отставанием.
 Производный класс помечен `derivedBy: 'имя-проектора'`, и его строки пишет только этот проектор. Сам производный
-класс (свой или унаследованный) заводит, меняет и удаляет только администратор: `syncModels` администраторским
-подключением с сессией арендатора (`connect({ dsn: ADMIN, schema, token, allowBypassRls: true })`) или аккаунт с
+класс (свой или унаследованный) и его предков заводит, меняет и удаляет только администратор: `syncModels`
+администраторским подключением с сессией арендатора (`connect({ dsn: ADMIN, schema, token, allowBypassRls: true })`) или аккаунт с
 правом System `letopis.projector`; у сессии приложения — `acl_denied`. Итоги производного класса видит каждый, кому
 правила дают `READ` на него, даже без прав на строки источников.
 ```ts
@@ -339,7 +342,7 @@ p.run().catch(report)         // run() без once — с catch: после ош
 `row` — последняя версия в семействе с `$deleted`). `handle` получает изменения
 одного арендатора. Ошибку его данных (база отклонила его результаты или `out` — его строку или приращение)
 откатывает только он: арендатор выбывает (`status().failed`: `{ id: { cursor, code, message } }`) до
-`rebuild({ tenant: id })` (`{ tenant, chunked: true }` — пачками, пока хвост идёт для всех; `status().rebuildingTenants`),
+`rebuild({ tenant: id })` (`{ tenant, chunked: true }` — пачками, пока хвост идёт для всех, прерванную продолжает любой `run()`; `status().rebuildingTenants`),
 остальные идут дальше; с `onExpired: 'rebuild'` выбывший по ярусу перестраивается пачками сам, в любом процессе; `tenants: [id, …]` — явный список участников. `status().state`: `'new'` —
 проекции ещё нет, `'running'` — проекция построена и ведётся (а не «процесс сейчас работает»), `'rebuilding'` — идёт
 или прервана перестройка пачками.
@@ -362,7 +365,9 @@ await db.Wallet(w).Payment().create({ opId: 'op-9', amount: 500 }).rows()   //
 загрузчик); уход ниже `minimum` — `invalid_data`, каждое изменение — версия цели. Считаются живые строки того же
 арендатора (строка System — нет). Ремонт — `adm.rebuildAggregates('Wallet')` на администраторском подключении,
 расхождения — `verify({ data: true })`. Описать или изменить агрегат может только тот, кто без условий читает все строки
-источника и его потомков, иначе `acl_denied`. Горячий счётчик (больше ~150 записей в секунду на объект) —
+источника и его потомков, иначе `acl_denied`. Источник описывают раньше агрегата: над классом, которого ещё нет,
+агрегат не описывается (`invalid_class`), а класс `of` не удаляется, пока агрегат его называет; `syncModels` сам ставит
+источники раньше целей. Горячий счётчик (больше ~150 записей в секунду на объект) —
 проектор со свёрткой пачкой, а не агрегат.
 
 ### 14. Агенты и MCP
@@ -407,7 +412,7 @@ await adm.close(); await db.close(); await svc.close()
    и правкой.
 3. **Глаголы возвращают цепочку.** Без терминала (`.rows()`, `.first()` …) ничего не исполнится. `delete()` без
    `{ confirm: true }` — только превью; `purge` — только для удалённых (`not_deleted`) и после того, как проектор
-   класса прочёл удаление (`projector_pending`).
+   класса прочёл удаление (`projector_pending`); `trimHistory` — после того, как проектор прочёл версии.
 4. **Деньги и счётчики** — `update({ balance: inc(n) })`: база прибавляет внутри оператора, без чтения и потерянных
    обновлений; проверка `minimum` в схеме ловит уход в минус. Итог, вычисленный из прочитанного, — `{ rev }`
    (перечитать и повторить при `conflict`) или `forUpdate()` в `db.begin()`. Идемпотентность — ключом операции

package/CHANGELOG.md

@@ -2,6 +2,219 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [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`). Вошли три направления:
+- хвост ревью безопасности №3, все 12 кандидатов, плюс находки автоматического ревью и ревью безопасности доработок;
+- автоматический тест обновления схемы с 1.1.0 и 1.0.1;
+- замер генерируемых колонок первой заливки.
+
+Версия `1.3.0` (во время работы — `1.3.0-alpha.0`, не публиковалась). Схема 1.2.0 обновляется повторным `up()`:
+ревизия движка прежняя (6), функции накатываются заново. Новое в API:
+- опция проектора `lockTimeout`;
+- события ухода строки из классов подписки (`op: 'delete'` в прежнем классе).
+
+Поведение, которое стоит проверить при обновлении:
+- агрегат над классом, которого ещё нет, отклоняется, поэтому источник описывают раньше цели — `syncModels` делает
+  это сам;
+- класс-источник не удаляется, пока его называет агрегат;
+- класс с производными потомками правит только администратор.
+
+### Added — тест обновления схемы
+- `lib/test/upgrade.test.ts`. Схему ставит прежний пакет: 1.1.0 (новая dev-зависимость `letopis-11` =
+  `npm:letopis@1.1.0`) или 1.0.1 (`letopis-1`). Данные в неё пишет прежний движок: правки, перенос по концу,
+  удаление, каскад, `purge`, обрезка истории и креденшал пользователя вида `LOCK`. Затем вызывается `up()` текущей
+  версии: для 1.1.0 простой, для 1.0.1 с `upgrade: true` и миграцией `0006`. Тест проверяет:
+  - версии и хэши прежнего движка и `verify({ data: true })`;
+  - совпадение каталога схемы с чистой установкой: функции с правами и текстом, колонки, индексы, ограничения,
+    триггеры и политики;
+  - строки-замки семейств и снятие строк `LOCK` чужих аккаунтов;
+  - работу приложения, подписки и проектора по старым данным;
+  - что повторный `up()` не меняет ни каталог, ни данные.
+
+  Раньше обновление 1.1.0 → 1.2 было проверено только разовым прогоном.
+
+### Security — хвост ревью безопасности №3
+- Тексты отказов не называют невидимый класс (кандидат 6 из 10). Класс ссылающейся строки называется, только если
+  актор её видит, иначе текст общий. Это касается трёх отказов:
+  - каскад удаления без права DELETE (`acl_denied`);
+  - снятие конца без права WRITE (`acl_denied`);
+  - перевод ссылок при `reclass` и `rekey` на строку производного класса (`derived_class`).
+
+  Класс выбирает новая функция владельца `visible_class(jsonb)`. Атака №47.
+- Класс System и одноимённые классы арендаторов (кандидат 6 из 10). Раньше `class_has_history` и проверка «есть строки
+  или потомки» при удалении класса System считали журнал, строки и потомков любого арендатора по имени. Поэтому
+  арендатор с собственным классом `Invoice` и историей его строк не давал администратору создать или удалить System
+  `Invoice`. Теперь строки, потомки и история арендатора со своим одноимённым классом не в счёт: так их резолвит
+  `class_row`. Строки класса System у арендатора без своего класса по-прежнему мешают. Атака №48.
+- Надгробие класса (кандидат 5 из 10). Класс, удалённый с историей строк, создаётся заново только с прежней
+  политикой хранения `history` вместе с прежними `parent`, `alias` и `derivedBy`. Иначе `maintain()` прореживал бы его
+  старые версии по другой политике.
+
+  Алиасы предков в надгробии не записаны, поэтому дыра закрыта со стороны предка. Пока удалённые потомки класса
+  хранят историю строк, класс не меняет алиас (`invalid_class`). Удалённый, он создаётся заново только с описанием из
+  своего надгробия, даже без собственной истории. Удалённых потомков находит новая функция владельца
+  `class_orphan_history(text, uuid)`. Атака №49.
+- Производный класс через непроизводного предка (кандидат 5 из 10). Правка предка пересчитывает описание потомка
+  (`class_evolve`): поля, ключ и `history`. Поэтому класс, у которого есть производные потомки, теперь тоже правит
+  только администратор, с правом `letopis.projector`. Потомки учитываются своего арендатора, у класса System — всех.
+  Иначе `acl_denied`. Атака №50.
+- `family_conflicts` (кандидат 4 из 10). Конфликт смены `parent` (`tightening_conflict`) раньше называл роль невидимой
+  ссылающейся строки. Теперь о ней в тексте нет ни роли, ни id. Видимые ссылающиеся строки идут первыми, затем по id:
+  раньше бралась первая попавшаяся. Атака №51.
+- Агрегат над ещё не созданным классом источника (`/security-review`, кандидат 5 из 10). Раньше `class_admit`
+  проверял право READ описывающего агрегат только по уже существующим классам `of`. Пока класса не было, проверять
+  было нечего. Когда источник потом заводил пользователь с полным READ, проверялись только его права, и описавший
+  агрегат читал в истории цели вклад каждой строки источника.
+
+  Теперь новый или изменённый агрегат, у которого нет ни класса `of`, ни его потомков, отклоняется
+  (`invalid_class`, «класс-источник описывают раньше агрегата»). У класса арендатора они ищутся среди классов
+  арендатора, у класса System — среди классов System. `syncModels` (`letopis sync`) теперь описывает класс-источник
+  раньше цели, в каком бы порядке ни пришли модели. Атака №52, тест `sync`.
+
+  Класс `of` проверяется только при описании агрегата. Поэтому класс-источник теперь не удаляется, пока его называет
+  агрегат класса того же арендатора (`invalid_class`): иначе пустой класс удалили бы, а класс с этим именем завёл бы
+  заново другой пользователь, например под другим `parent`. Это нашло автоматическое ревью коммита. Агрегаты
+  классов System описывает системный администратор, он и так читает всё. Атака №53.
+- Прерванная `rebuild({ tenant, chunked: true })` (кандидат 6 из 10). Раньше её продолжал только `run()` с
+  `onExpired: 'rebuild'`. Без этой опции хвост бессрочно пропускал изменения арендатора с id выше последней пачки.
+
+  Теперь начатую перестройку арендатора продвигает `run()` любого процесса. Запуск перестройки выбывших по ярусу
+  по-прежнему только с `onExpired`. Если блокировку проектора держит другой процесс (`busy`), `run()` перестройку
+  не трогает и чекпоинт не читает: иначе второй процесс ждал бы пачку первого. Тест `projector`.
+- Нет `lock_timeout` у транзакций проектора (кандидат 6 из 10). Пачка всех арендаторов ждала блокировку строки,
+  которую держит транзакция любого арендатора. Новая опция `ProjectorOptions.lockTimeout`: сколько ждать, по
+  умолчанию 5000 мс, 0 — без предела. Её ставит `set local lock_timeout` в каждой транзакции проектора.
+
+  На 55P03 пачка откатывается, курсор остаётся, арендатор не выбывает. `run()` не отклоняется, а считает проход
+  пропущенным (`skipped`) и повторяет его; `rebuild({ tenant, chunked: true })` повторяет пачку. Держащая
+  транзакция и так держит горизонт подписок, поэтому ждать имеет смысл только запись, зафиксированную раньше неё.
+  Тест `projector`.
+- `trimHistory` версий, которые проектор ещё не прочёл (кандидат 5 из 10). Первая оставшаяся версия пришла бы
+  проектору с `before` = `null`, и свёртка прибавила бы её, не вычитая прежнюю. Теперь `trim_history` отказывает
+  `projector_pending`, пока проектор источника не прочёл первую оставшуюся версию. Класс проверяется у обеих версий
+  стыка, потому что строка могла уйти из семейства источников сменой класса.
+
+  Проверку `purge` и обрезки делает общая функция владельца `projector_behind(uuid, text[], xid8, bigint)`.
+  `rebuild({ tenant, chunked: true })` засчитывает завершённую перестройку, даже если последнюю пачку записал `run()`
+  другого процесса. Тест `projector`.
+- `as()` арендатора корня (кандидат 5 из 10). Фасад `db.as()` того же арендатора, что и корень, получал сам реестр
+  корня. После `auth.switch()` корня он видел классы нового арендатора. Теперь у фасада свой реестр из кэша
+  арендатора. Тест `impersonation`.
+- Пустой реестр `as()` (кандидат 4 из 10). Если на первой загрузке контекст сессии уже ушёл из арендатора (сменился
+  или кончился), пустой реестр кэшировался и не перечитывался. Теперь он не кэшируется: `as()` читает контекст
+  заново, не больше трёх раз, затем отказывает `no_session`. Тест `impersonation`.
+- Подписка и смена класса без смены id. Раньше `db.watch()` по классам не видел ухода строки из класса: версия
+  пишется уже с новым классом. Теперь такой уход приходит событием удаления в прежнем классе (`op: 'delete'`, `row` —
+  прежняя версия с `$deleted`, автор и время — версии смены класса). Событие приходит, даже если новый класс
+  подписчику не виден, но только если прежнюю версию он видел.
+
+  Уход находит новая функция владельца `watch_leaving`, выданная приложению. Окно у неё то же, что у `watch_read`, и
+  ограничено полной пачкой, поэтому догонка с `'start'` не читает журнал заново на каждой пачке. Подписка сливает
+  оба потока по `(tx, seq)`. Тесты `watch` (уход в видимый и в невидимый класс, уход в чужом арендаторе, вход в
+  класс) и `roles`.
+
+  Ревью безопасности доработок нашло ошибку в подписке, исправлена до выпуска. `watch_read` и `watch_leaving` идут
+  одним оператором с общим снимком: двумя запросами с разными горизонтами курсор мог перескочить событие,
+  зафиксированное между ними. Если новую версию подписчик не видит, надгробие приходит при любых классах подписки и
+  без автора: иначе перебором классов он узнал бы новый класс.
+- Обрезка истории проверяет курсор проектора по самой поздней по `(tx, seq)` версии у стыка: у более поздней версии
+  бывает меньший xid.
+
+### Changed
+- Порядок описания агрегата: класс-источник — раньше цели (раньше источник можно было описать позже, и он
+  сверялся при появлении). Классы с концом на ещё не созданный класс по-прежнему описываются, поэтому пара «цель —
+  источник с концом на цель» описывается в порядке «источник, цель». Тесты `aggregate` и бенч `derived` описывают
+  классы в этом порядке.
+
 ## [1.2.0] — 2026-10-28
 
 letopis 1.2 по плану `reports/PLAN-LETOPIS-1.1.md` (редакция 5, этапы 4–6 и контрольная точка Б) и плану доработок

package/README.en.md

@@ -1,4 +1,4 @@
-# letopis 1.2
+# letopis 1.4
 
 **letopis** is a Node.js library: a store of versioned entities on PostgreSQL 18. Every change is saved as a version
 in a journal. So every object has a history, a state as of any date and a change subscription. The database itself
@@ -369,12 +369,24 @@ package. So a startup script that calls `up()` on every start will stop after a
 `upgrade: true`. `up({ dsn, schema, upgrade: true })` applies the migrations from `sql/migrate/` and re-applies the
 functions; the data is kept.
 
+The revision does not change with every version: 1.1–1.4 share one, while their functions differ. So `up()` also writes
+an engine stamp into the schema comment: the package version and a hash of its SQL files. If the stamp does not match
+the package files, `connect()` warns. When the schema was applied by an older version (or by a version before 1.4,
+which has no stamp), it suggests `up({ schema })`. When a newer version has already upgraded the schema, it suggests
+updating the package: `up()` from the older version would bring the old functions back. A new package version without
+SQL changes keeps the stamp, and there is no warning.
+
 The first `up()` after moving to 1.2 builds the journal index `log_class_tenant_at (class, tenant, at)` instead of
 `log_class_at`: an `asOf` and `withDeleted` slice by class no longer reads the journal of other tenants with the same
 class name. While the index is being built, writes to the journal wait. On a large installation, build it in advance
 without stopping writes: `create index concurrently log_class_tenant_at on "v2.<schema>".log (class, tenant, at)` as
 the owner role — then `up()` only drops the old one.
 
+The `upgrade` test checks upgrading 1.1.0 and 1.0.1 schemas. The old package installs the schema and the old engine
+writes the data, then the current version's `up()` runs. After it, the versions and hashes written by the old engine
+are in place, `verify({ data: true })` is clean, and the schema catalog matches a clean installation. A 1.1.0 schema is
+upgraded with a plain `up()`, since its revision is the same. A 1.0.1 schema is upgraded with `up({ upgrade: true })`.
+
 ### Development without PostgreSQL: PGlite
 
 `up({ pglite: true })` starts PGlite (PostgreSQL 18 on WebAssembly) with pgcrypto and a socket on a free port. It needs
@@ -560,13 +572,23 @@ const Movement = link('Movement', { amount: z.number().int() }, { ends: { Wallet
   the target is needed: the permission to write the source is enough.
 - The database checks the description (`invalid_class`): the field is in the schema, it is numeric and not part of the
   key; the `via` end is single and accepts the target class; the `sum` field is a number; aggregates do not form a
-  cycle; the target and the source are not system or derived classes. A source described after the target is checked
-  when it appears.
+  cycle; the target and the source are not system or derived classes. A source class is described before the
+  aggregate: an aggregate over a class that does not exist yet is refused. For a tenant class, the source is looked up
+  among the tenant's classes. `syncModels` describes sources before targets itself, and models in a circle (an
+  aggregate over the class's own descendant, a cycle of aggregates) it refuses before writing (`invalid_class` naming
+  the circle). The `of` class is not deleted while an aggregate of a class of the same tenant names it: first the
+  aggregate is removed from the target's description.
 - Rows get into an aggregate only with the knowledge of someone who reads them all: the field also counts rows that
   the author cannot see. Only someone who reads all rows of the source and its descendants without conditions can
   describe or change an aggregate. Only someone who reads all rows of a class and its descendants without conditions,
-  both before the change and after it, can make the class a source (a new class, a `parent` change, a source described
-  after the target). Otherwise `acl_denied`.
+  both before the change and after it, can make the class a source (a new descendant of a source, a `parent` change).
+  Otherwise `acl_denied`.
+- A new source is also checked against whoever described the aggregate: they too must read all rows of the class
+  without conditions. The describer is the author of the version of the target's `Class` row from which the aggregate
+  description became the current one. If they cannot read those rows, the class does not become a source
+  (`acl_denied`) until someone who can read them describes the aggregate again. For an aggregate of a System class, the
+  describer is checked against System classes, as at description time. A tenant class under a System aggregate is
+  checked only for whoever creates it.
 - The option is inherited, and a descendant replaces it as a whole. Adding or changing an aggregate is a tightening:
   writes to the target and to the sources wait while the field is recalculated for all rows.
 - `db.rebuildAggregates(class)` recalculates the field from the current rows, for repair. A version is written only
@@ -981,7 +1003,8 @@ version 1, a `purge` record stays with the number of erased versions. The histor
 While a projector whose `from` sources include the class of the object ([“Projectors”](#projectors)) has not read
 the deletion, `purge` refuses (`projector_pending`): the projector would never see an erased tombstone, and the
 object's contribution would stay in the totals. So a deletion and a `purge` in one transaction do not go through in
-such a class. To delete an account, use `db.auth.purgeAccount` ([section 10](#10-users-sign-in-and-permissions)).
+such a class. Likewise, `db.trimHistory` refuses while the projector has not read the first remaining version: it
+would no longer find the previous version for `before`. To delete an account, use `db.auth.purgeAccount` ([section 10](#10-users-sign-in-and-permissions)).
 
 ## 8. Transactions, batches and money
 
@@ -1462,16 +1485,23 @@ alias in the tenant and System, and the name of a new class does not match anoth
 written for one class would act on the rows of another too. A violation gives `invalid_class`.
 
 By the same names, the rules also find the old versions of rows in the journal. So a class is deleted only when it has
-no rows, no descendants and no history of rows: `purge()` erases the history of deleted rows first. A class deleted
-with history before is created again only with the same `parent`, `alias` and `derivedBy` — otherwise `invalid_class`:
-the old versions of its rows would fall under other rules. If the journal holds rows of a class with this name but not
-its tombstone (for example, rows of a System class deleted in 1.1), a class with this name is not created until
-`purge()` erases the history.
+no rows, no descendants and no history of rows: `purge()` erases the history of deleted rows first. For a System class,
+the rows, descendants and history of a tenant that has its own class with the same name do not count: they belong to
+that tenant's class. A class deleted with history before is created again only with the same `parent`, `alias`,
+`derivedBy` and `history` — otherwise `invalid_class`: the old versions of its rows would fall under other rules or a
+different thinning. The rules also find old versions by the aliases of ancestors. So while deleted descendants of a
+class keep row history, the class does not change its alias (`invalid_class`), and once deleted it is created again
+only with the same description. If the journal holds rows of a class with this name but not its tombstone (for
+example, rows of a System class deleted in 1.1), a class with this name is not created until `purge()` erases the
+history.
 
 A derived class (`derivedBy`) is created, edited and deleted only by an administrator: an admin connection or an
 account with the System permission `letopis.projector` (the system administrator has it through the `letopis.*`
 mask). The projector writes totals over all source rows of the tenant into such a class, without read permissions,
-so a user who created it on their own would read totals over rows they may not read.
+so a user who created it on their own would read totals over rows they may not read. A class that has derived
+descendants is also edited only by an administrator: editing an ancestor changes the description of the descendant
+(fields, key, `history`). The database itself sets the `aggregatedBy` mark (the class became an aggregate source) on a
+derived class too: it does not change its fields or key.
 
 ### Granting a permission
 
@@ -1708,7 +1738,10 @@ for await (const ev of sub) {             // ev: { cursor, row, id, class, op, r
   moment: a write after it comes to the stream. The example above reads from `'start'`.
 - Calls of `sub.next()` go in turn: parallel calls get different events. A call abandoned by a timeout
   (`Promise.race`) still gets its event — keep its promise and wait for it again.
-- `classes`: only these classes with their descendants; `pollMs`: fallback polling (1000 ms).
+- `classes`: only these classes with their descendants; `pollMs`: fallback polling (1000 ms). A row that left these
+  classes through a class change without an id change arrives as a deletion event in the previous class (`op:
+  'delete'`, `row` is the previous version with `$deleted`), even if the subscriber cannot see the new class. The
+  event comes if the subscriber could see the previous version.
 - Events come without losses or repeats, under the reader's permissions, in the order of transaction numbers, and
   within a transaction in the order of writing. This is not the commit order: compare versions of one object by `rev`.
 - A long write transaction in any database of the cluster delays the stream: `await sub.lag()` shows the lag in ms.
@@ -1832,7 +1865,8 @@ sales.close()                                    // stop() after the current bat
   on for all: the tail skips the tenant's changes above the last batch (a batch will read them) and, in a passed batch,
   those whose transaction is visible in its snapshot. The tenant's derived rows are deleted at once and are incomplete
   until the end of the rebuild (`status().rebuildingTenants`); the rebuild waits out a lock held by `run()` of another
-  process.
+  process. An interrupted rebuild (the process stopped) is continued by `run()` of any process, with or without
+  `onExpired`.
 - `status().state` describes the projection in the database, not a process: `'new'` means there is no projection yet,
   and the first `run()` or `rebuild()` builds it; `'running'` means the projection is built and kept up with the
   journal (it does not mean that some process is executing `run()` right now); `'rebuilding'` means a batch rebuild
@@ -1861,6 +1895,16 @@ sales.close()                                    // stop() after the current bat
   tenant with `rebuild({ tenant })`.
 - `batch` is how many changes go into a batch (500), `pollMs` is fallback polling (1000 ms): source signals wake the
   projector earlier.
+- `lockTimeout` is how long a projector transaction waits for another transaction's row lock (5000 ms; 0 — no limit).
+  Otherwise a transaction of any tenant holding a total row or an end target would hold the batch of all tenants.
+  Longer than that, the batch rolls back, the cursor stays, and `run()` does not reject but skips the pass
+  (`skipped`) and repeats it. The report names the tenant whose row stopped the batch (`locked`).
+  `rebuild({ tenant, chunked: true })` waits such a lock out.
+- `lockRetries` is how many passes in a row the writes of one tenant may run into `lockTimeout` before it drops out
+  (0 by default — it never drops out). The dropped tenant gets the code `55P03`, and the batch goes on for the others;
+  its changes are skipped until `rebuild({ tenant })`. The process keeps the count, and a successful write of the
+  tenant resets it. Note: a long exclusive lock on the family of a System class (a tightening of its description) will
+  hit every tenant in turn.
 - Every edit that `out` sends to the database is a separate edit of a row, and the speed of a projector is set by the
   number of edits, not by the number of changes. The folding of `inc` brings the edits of a row down to one per batch,
   so the handle from the example above (`out.inc` for every change) caught up with 6 thousand changes per second with
@@ -2317,12 +2361,12 @@ give `invalid_data`.
 
 | Member | What it does |
 |---|---|
-| options `ProjectorOptions` | `from`, `into`: classes with descendants; `version`: an integer from 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` rebuilds in batches); `batch`: changes in a batch (500, from 1 to 10,000); `pollMs`: fallback polling (1000 ms); `tenants`: ids of the participant tenants |
+| options `ProjectorOptions` | `from`, `into`: classes with descendants; `version`: an integer from 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` rebuilds in batches); `batch`: changes in a batch (500, from 1 to 10,000); `pollMs`: fallback polling (1000 ms); `lockTimeout`: waiting for another transaction's row lock (5000 ms, 0 — no limit); `lockRetries`: passes in a row before a tenant with another transaction's lock drops out (0 — never); `tenants`: ids of the participant tenants |
 | `run({ once })` | catch up with the journal (`once`) or follow it until `stop()` → `ProjectorReport` |
 | `rebuild({ chunked, tenant })` | rebuild from the current state: atomically, in batches or for one tenant → `ProjectorReport` |
 | `status()` | → `ProjectorStatus`: `{ name, state, version, cursor, at, lag, failed, rebuildingTenants }`; `failed` is `{ [tenant id]: ProjectorFailure }`, where `ProjectorFailure` is `{ cursor, code, message }` |
 | `stop()`, `close()` | stop `run()` after the current batch; the same plus unsubscribing from signals |
-| `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds }` |
+| `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds, locked }` |
 | `ProjectorChange` | `{ cursor, id, class, tenant, op, rev, at, author, row }` and, when present, `agent`, `reason`, `moved`, `before`, `rebuild` |
 | `ProjectorOut` | `upsert(class, row, { tenant })`, `inc(class, row, deltas, { tenant })`, `delete(class, key or id, { tenant })`, `get(class, key or id, { tenant })` → `Row \| null`; a row is a `ProjectorRow` in the loader format |
 
@@ -2384,7 +2428,7 @@ Database codes. Raw SQL gets them too: SQLSTATE class `LT`, the details are JSON
 | `confirm_mismatch` | LT020 | the reset confirmation does not match the schema name |
 | `derived_class` | LT021 | a row of a derived class (`derivedBy`) is written, edited or deleted by someone other than its projector; an end leads to such a row or to a derived class; a projector writes to a class outside its `into` or has found no tenant in which every `into` class is marked with its `derivedBy` |
 | `aggregate_field` | LT022 | the application passed or changed an aggregate field (`aggregate`): the database calculates it |
-| `projector_pending` | LT023 | `purge` of a deleted object whose deletion a projector of its class has not read yet: run the projector first |
+| `projector_pending` | LT023 | `purge` of a deleted object whose deletion a projector of its class has not read yet, or `trimHistory` whose first remaining version it has not read yet: run the projector first |
 
 Library codes:
 
@@ -2470,7 +2514,7 @@ runs) showed no write or read regressions against 1.1: two outliers did not repe
 
 ## 18. Limitations
 
-This section lists what letopis 1.2 deliberately does not do or does with caveats, and where you need to watch the
+This section lists what letopis 1.4 deliberately does not do or does with caveats, and where you need to watch the
 behavior.
 
 **Platform**
@@ -2556,8 +2600,10 @@ behavior.
   attempts.
 - When users link a taken identifier themselves, the answer is `acl_denied`, so a user with a recent sign-in learns
   this way that the identifier is taken. Permission changes in all tenants are serialized through one counter row.
-- The number of invisible rows that block a deletion or a class change (`reclass_denied`), and the existence of an
-  account by id (as a reference target), are not hidden.
+- Refusal texts name the class, role and id of a referencing row only if the actor can see it: a cascade delete,
+  unsetting an end, rewriting references on a class or key change, and a `parent` change conflict
+  (`tightening_conflict`). The number of invisible rows that block a deletion or a
+  class change (`reclass_denied`), and the existence of an account by id (as a reference target), are not hidden.
 - Tightening a class description and `rekeyClass` check all rows of the family, so they need the `READ` permission
   without conditions on all rows of the class and its descendants: otherwise a trial tightening (`maximum`, `enum`,
   `pattern`) would answer with the number of invisible rows that do not match it. A system administrator who tightens
@@ -2640,6 +2686,8 @@ behavior.
 - `purge()` waits for projectors: while a projector whose sources include the class of the object, and which has a
   derived class in the object's tenant, has not read the deletion, `purge` answers `projector_pending`. A projector
   that is no longer run holds `purge` of its sources while the tenant has its derived classes: run it or delete them.
+  `trimHistory` waits the same way: while the projector has not read the first remaining version, trimming answers
+  `projector_pending`.
 
 **Aggregates in the database**
 
@@ -2707,7 +2755,7 @@ This section is for those who develop letopis itself. Run: `cd lib && npm test`.
 # hash — the version hash chain, journal tampering and gaps, verify() (stage 1)
 # harness — the test harness: starting the database, a schema per file, two connection strings (stage 0)
 # jsonschema — compiling JSON Schema to jsonpath and checking data in the database (stage 1)
-# impersonation — impersonation: letopis.account only for a service with the permission, target restrictions, author and agent in the journal, sessionFor; the db.as() registry is one per tenant, does not empty, is re-read on a signal of its tenant (stage 5; the work after checkpoint B)
+# impersonation — impersonation: letopis.account only for a service with the permission, target restrictions, author and agent in the journal, sessionFor; the db.as() registry is one per tenant, does not empty, is re-read on a signal of its tenant (stage 5; the work after checkpoint B); the facade registry is not shared with the root, an empty registry is not cached (security review No. 3 leftovers)
 # install — the installer and roles: a repeated installation, two installations in one database, three tables (stage 1)
 # member — memberships: working in a tenant by roles, auth.switch, leaving with ownership transfer, system rows, tenant roles without System permissions (stage 5)
 # model — Zod models, the JSON Schema normalizer, pattern translation, agreement with the database metaschema (stage 2)
@@ -2731,6 +2779,7 @@ This section is for those who develop letopis itself. Run: `cd lib && npm test`.
 # cache — result cache: hits, own and others' writes, the key with the user, permissions, revoked sessions, listener drop, ttl, class marking, without LISTEN, a race, db.sql, the limit of signal counters (stage 6; plan 1.1, checkpoint A)
 # maintain — maintenance: expired sessions and codes, permissions, one process under a lock, schedule (stage 6)
 # up — the full installer: fresh installation, re-apply, custom seeds, automatic database creation, UTF8, version 17, upgrade with migrations, PGlite, the first tenant and user (up({ tenant }), createTenant) (stages 6, 8)
+# upgrade — schema upgrade from 1.1.0 (re-apply) and from 1.0.1 (upgrade: true, migration 0006) with the letopis-11 and letopis-1 packages: versions and hashes written by the old engine, verify(), the catalog against a clean installation, lock rows, the application, a subscription and a projector over old data, a repeated up() (work after 1.2.0, stage 1)
 # scenario-salon — end-to-end salon scenario: 21 acts from 0.21 (salon) with a coverage matrix of the 1.0 API (stage 6)
 # telemetry — onQuery and slowMs, describe() and class metadata with inheritance, describeText (stage 6)
 # history — diff and blame over the log, the reason of a change for verbs, db.begin() and batches; a version hidden by an ACL condition, the changed column, a missing version, row_changes over 20 thousand targets (plan 1.1, stage 1 and checkpoint A)