letopis 1.2.0 → 1.3.0

package/AGENT-CHEATSHEET.en.md

@@ -1,4 +1,4 @@
-# letopis 1.2 — agent cheatsheet
+# letopis 1.3 — 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:
@@ -263,7 +263,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 +325,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 +348,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 +374,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 +424,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.3 — шпаргалка для агента
 
 Одна страница вместо [README.md](README.md) — для ИИ-агента, который пишет код поверх пакета. Лежит в пакете рядом с
 README; английская версия — [AGENT-CHEATSHEET.en.md](AGENT-CHEATSHEET.en.md). Переход с 0.21 — [MIGRATION.md](MIGRATION.md);
@@ -254,7 +254,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 +316,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 +339,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 +362,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 +409,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,131 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [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.3
 
 **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
@@ -375,6 +375,11 @@ class name. While the index is being built, writes to the journal wait. On a lar
 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 +565,15 @@ 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. 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`.
 - 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 +988,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 +1470,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 +1723,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 +1850,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 +1880,10 @@ 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.
 - 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,7 +2340,7 @@ 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); `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 }` |
@@ -2384,7 +2407,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 +2493,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.3 deliberately does not do or does with caveats, and where you need to watch the
 behavior.
 
 **Platform**
@@ -2556,8 +2579,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 +2665,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 +2734,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 +2758,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)