letopis 1.4.2 → 3.0.0

package/README.md

@@ -1,4 +1,8 @@
-# letopis 1.4
+# letopis 3.0
+
+> ИИ-агенту — сначала [AGENT-CHEATSHEET.md](AGENT-CHEATSHEET.md): памятка лежит в пакете рядом с этим файлом
+> (`node_modules/letopis/AGENT-CHEATSHEET.md`), в ней общие правила для любой задачи, рабочий цикл и грабли на одной
+> странице.
 
 **letopis** — библиотека для Node.js, хранилище версионированных сущностей на PostgreSQL 18. Каждое изменение
 сохраняется версией в журнале. Поэтому у любого объекта есть история, состояние на любую дату и подписка на
@@ -6,25 +10,24 @@
 RLS. Правила одинаково действуют и для библиотеки, и для сырого SQL. Данные читают и пишут цепочками:
 `db.Shop(shop).Product({ price: lt(1000) }).rows()`.
 
-[English version](README.en.md) · [Шпаргалка для ИИ-агента](AGENT-CHEATSHEET.md) · [Переход с 0.21](MIGRATION.md) ·
-[Изменения по версиям](CHANGELOG.md) · [llms.txt](llms.txt)
+[Памятка для ИИ-агента](AGENT-CHEATSHEET.md) · [Изменения по версиям](CHANGELOG.md) · [llms.txt](llms.txt) ·
+[Лицензия](#19-лицензия): некоммерческое использование бесплатно, коммерческое — по разрешению
 
 Что умеет letopis:
 
 - **Модели на Zod** хранятся в базе как классы: хабы (объекты) и связи (отношения со своими данными) — [раздел 4](#4-модель-данных).
-- **Запись цепочками**: `create`, `update` со слиянием, `upsert`, удаление с превью и каскадом, приращение `inc`
-  для денег и счётчиков — [разделы 5](#5-запись), [7](#7-удаление-и-восстановление) и [8](#8-транзакции-батчи-и-деньги).
+- **Запись цепочками**: `create`, `update` со слиянием, `upsert`, удаление только по показанному превью и с каскадом,
+  приращение `inc` для счётчиков — [разделы 5](#5-запись), [7](#7-удаление-и-восстановление) и [8](#8-транзакции-и-батчи).
 - **Чтение цепочками**: переходы по связям, фильтры, деревья, агрегаты, постраничный вывод — [раздел 6](#6-чтение).
-- **История**: версии, срез на дату, что изменилось и кто (`diff`, `blame`), восстановление удалённого, политика
-  хранения, проверка цепочки хэшей — [раздел 11](#11-история-и-срезы-на-дату).
+- **История**: версии с автором и причиной, срез на дату, восстановление удалённого — [раздел 11](#11-история-и-срезы-на-дату).
 - **Арендаторы, вход и права** — в самой базе: пароли, ключи API, одноразовые коды, TOTP, сессии, имперсонация,
   правила доступа — [раздел 10](#10-пользователи-вход-и-права).
 - **Подписка на изменения** по курсору без потерь и **кэш результатов** — [раздел 12](#12-подписка-на-изменения-и-кэш).
-- **Производные данные**: агрегаты в базе — суммы и счётчики, которые держит сама база, — и проекторы, которые строят
-  сводки из журнала, — [разделы 4](#агрегаты-в-базе) и [12](#проекторы).
 - **Агенты и MCP**: сервер MCP даёт ИИ-агенту модель, чтение, историю и, если разрешено, запись — с правами одного
   пользователя — [раздел 13](#агенты-и-mcp).
-- **Массовая загрузка** миллионов строк и **импорт из 0.21** — [разделы 9](#9-массовая-загрузка) и [14](#14-переход-с-021).
+- **Массовая загрузка** миллионов строк — [раздел 9](#9-массовая-загрузка).
+- **Журнал событий** приложения: удаления, восстановления, ошибки, вход, запросы — с маскировкой секретов —
+  [«Логирование»](#логирование).
 
 Требования:
 
@@ -44,38 +47,42 @@ RLS. Правила одинаково действуют и для библио
 5. [Запись](#5-запись)
 6. [Чтение](#6-чтение)
 7. [Удаление и восстановление](#7-удаление-и-восстановление)
-8. [Транзакции, батчи и деньги](#8-транзакции-батчи-и-деньги)
+8. [Транзакции и батчи](#8-транзакции-и-батчи)
 9. [Массовая загрузка](#9-массовая-загрузка)
 10. [Пользователи, вход и права](#10-пользователи-вход-и-права)
 11. [История и срезы на дату](#11-история-и-срезы-на-дату)
 12. [Подписка на изменения и кэш](#12-подписка-на-изменения-и-кэш)
-13. [Эксплуатация](#13-эксплуатация)
-14. [Переход с 0.21](#14-переход-с-021)
-15. [Справочник API](#15-справочник-api)
-16. [Ошибки](#16-ошибки)
-17. [Производительность](#17-производительность)
-18. [Ограничения](#18-ограничения)
-19. [Тесты](#19-тесты)
+13. [Эксплуатация](#13-эксплуатация): обслуживание, MCP, [логирование](#логирование), командная строка
+14. [Справочник API](#14-справочник-api)
+15. [Ошибки](#15-ошибки)
+16. [Производительность](#16-производительность)
+17. [Ограничения](#17-ограничения)
+18. [Тесты](#18-тесты)
+19. [Лицензия](#19-лицензия)
 
 Разделы 3–13 построены на одном примере — магазине: установка, модель, запись, чтение и так далее. Блоки кода этих
-разделов идут по порядку и вместе образуют одну программу. Её, как и пример быстрого старта, тест `docs` исполняет
-против настоящей базы, поэтому примеры не расходятся с кодом.
+разделов идут по порядку и вместе образуют одну программу. Автоматически её сейчас не сверяет ни один тест: тест
+`docs` отстал от текста. Если пример разошёлся с поведением пакета, верен код.
 
 ## 1. Быстрый старт
 
-Нужен PostgreSQL 18 и роль администратора: суперпользователь или роль с правом `CREATEROLE`. Установите пакет:
+Нужен PostgreSQL 18 и роль администратора: суперпользователь или роль с `CREATEROLE`, правом `CREATE` в базе (схема
+и расширение pgcrypto) и `CREATEDB`, если базы ещё нет. Установите пакет:
 
 ```sh
-npm install letopis zod postgres    # postgres — для createTenant и своих SQL-запросов
+npm pkg set type=module             # код приложения — ESM: "type": "module" или файлы .mjs
+npm install letopis zod postgres@3  # postgres@3 — для createTenant и своих SQL-запросов
+npm install -D tsx                  # запуск примеров на TypeScript: npx tsx app.ts
 ```
 
-Приложение подключается к базе отдельной ролью, которая состоит в `letopis_app`. Роль `letopis_app` создаёт установка.
-Поэтому после первой установки один раз создайте роль приложения:
+`postgres` — зависимость letopis версии 3. Ставьте ту же мажорную версию: `npm i postgres` без версии поставит 4.x,
+и код будет работать, но `createTenant(admin, …)` не пройдёт проверку типов — типы двух копий `postgres` несовместимы.
 
-```sql
-create role shop_app login password 'app-secret';
-grant letopis_app to shop_app;
-```
+Пакет — модуль ES, и примеры написаны на `import`: без `"type": "module"` в `package.json` приложения (или без
+расширения `.mjs`) Node ответит `SyntaxError: Cannot use import statement outside a module`.
+
+Приложение подключается к базе отдельной ролью, которая состоит в `letopis_app`. Её заводит сама установка: опция
+`login` у `up()` создаёт роль с паролем (повтор только обновит пароль) и выдаёт ей `letopis_app`.
 
 Пример ставит схему, заводит магазин с первым пользователем, описывает два класса и работает с ними:
 
@@ -88,8 +95,8 @@ import { z } from 'zod'
 const ADMIN = 'postgres://postgres:secret@localhost:5432/shop'    // администратор: ставит схему
 const APP = 'postgres://shop_app:app-secret@localhost:5432/shop'  // приложение: член letopis_app
 
-// 1. Установка схемы v2.shop. tenant — первый арендатор (магазин) и его пользователь Анна.
-const r = await up({ dsn: ADMIN, schema: 'shop',
+// 1. Установка схемы v2.shop. login — роль приложения shop_app, tenant — первый арендатор (магазин) и его пользователь Анна.
+const r = await up({ dsn: ADMIN, schema: 'shop', login: { user: 'shop_app', password: 'app-secret' },
   tenant: { name: 'Ромашка', user: { name: 'Анна', login: 'anna@shop.ru', password: 'Ромашка-2026!' } } })
 // r.serviceKey — ключ сервиса приложения: выдаётся при первой установке, сохраните его
 
@@ -121,7 +128,10 @@ await svc.close()
   `owner` в нём.
 - `connect({ apiKey })` обменял ключ сервиса на сессию. `verifyPassword` вернул `{ account, token }` (или `null`,
   если пароль неверный). `svc.as(account, { tenant })` — тот же пул соединений, но от имени Анны в магазине;
-  право сервиса на это проверяет база.
+  право сервиса на это проверяет база. Сессия входа и `svc.as(account)` без `tenant` работают в **личном**
+  арендаторе Анны (id её аккаунта): классов магазина там нет, и шаг `db.Product()` дал бы `invalid_class`. Своё
+  подключение по токену (`connect({ token })`) переходит в магазин через `auth.switch()`
+  ([«Работа в другом арендаторе»](#работа-в-другом-арендаторе)).
 - `hub('Product', поля, опции)` описал класс-объект. `ends: { Shop }` — обязательная ссылка на магазин.
   `key: ['Shop', 'sku']` — ключ: id товара вычисляется из магазина и артикула, а второй товар с тем же ключом база
   не примет.
@@ -129,7 +139,9 @@ await svc.close()
   уменьшил цену внутри оператора `UPDATE`, без предварительного чтения. `versions()` прочитал историю из журнала.
 
 Повторный вызов `up()` безопасен: он повторно накатывает ту же ревизию и данные не трогает, а ключ сервиса снова не
-выдаёт, пока в установке есть хоть один ключ API, кроме отозванных. Дальше раздел 2 объясняет устройство, а разделы 3–13 разбирают задачи по порядку.
+выдаёт, пока в установке есть хоть один ключ API, кроме отозванных. Поэтому код, который запускают не один раз,
+передаёт свой ключ — `up({ …, serviceKey: process.env.SERVICE_KEY })` — и подключается с ним
+(`apiKey: r.serviceKey ?? process.env.SERVICE_KEY`); повторный `create()` того же магазина даст `exists`. Дальше раздел 2 объясняет устройство, а разделы 3–13 разбирают задачи по порядку.
 
 ## 2. Как устроен letopis
 
@@ -148,21 +160,20 @@ await svc.close()
 | арендатор | аккаунт, в чьих данных идёт работа. Данные разных арендаторов изолированы |
 | членство | связь `member` «пользователь — арендатор» с ролями; даёт работать в чужом арендаторе |
 | сессия | токен, по которому база узнаёт аккаунт и арендатора. Сервис получает её по ключу API, пользователь — входом |
-| версия, журнал | каждое изменение строки — версия в журнале `log` с автором, временем и хэшем |
+| версия, журнал | каждое изменение строки — версия в журнале `log` с автором и временем |
 | надгробие | версия «удалено» с последним снимком объекта |
 | цепочка | запрос вида `db.Shop(shop).Product().rows()`: шаги, модификаторы, глаголы записи и терминал |
-| терминал | метод, который исполняет цепочку: `rows`, `first`, `ids`, `count`, `paths`, агрегаты |
+| терминал | метод, который исполняет цепочку: `rows`, `first`, `ids`, `count`, `paths`, `versions`, агрегаты |
 
 ### Что хранится в базе
 
 Таблиц три. `entity` — текущее состояние: одна строка на каждую живую сущность, включая строки системных классов
 (`Class`, `Account`, `Resource`, `member`, `rule`). `log` — журнал: полный снимок каждой версии с автором,
-временем, видом операции и хэшем. `secret` — креды, сессии и чекпоинты проекторов: приложение не видит в ней ни
-одной строки, с ней работают только функции входа и проекторов.
+временем, видом операции и причиной. `secret` — креды, сессии и служебные строки-замки: приложение не видит в ней ни
+одной строки, с ней работают только функции входа и блокировок движка.
 
 Классы — тоже сущности. Описание класса лежит в строке `Class`; там же база хранит развёрнутое описание с учётом
-предков и скомпилированную проверку данных. Хэш версии — генерируемая колонка: sha256 от хэша прошлой версии и
-снимка строки. Поэтому подмену версии выдаёт следующая версия, а у последней — якорь вне базы ([раздел 11](#11-история-и-срезы-на-дату)).
+предков и скомпилированную проверку данных.
 
 ### Кто проверяет данные
 
@@ -185,6 +196,28 @@ LOGIN-роль состоит только в ней. Всё, что выпол
   которая обходит RLS (суперпользователь, `BYPASSRLS`, член `letopis_owner`), если не указано
   `allowBypassRls: true`.
 
+### Безопасность по умолчанию
+
+Опасное действие нельзя совершить случайно — без сверки с тем, что видел человек, оно отклоняется до записи:
+
+- **Удаление — только по превью.** `delete()` — превью; удаляет `delete({ confirm: true, expect: превью })`, ровно
+  показанное. `delete({ confirm: true })` без `expect` — `invalid_query` (`write.confirm_without_expect`).
+- **Восстановление — только по надгробиям.** `restore({ expect })` с ответом `delete()` или строками `withDeleted()`;
+  `restore()` без `expect`, в том числе по явному id, — `invalid_query` (`write.restore_without_expect`).
+- **Массовое — только явно.** Правка и удаление без фильтра — `invalid_query`, пока нет `{ all: true }`; удаление и
+  восстановление без сверки — тоже только с `{ all: true }`.
+- **Арендатор и права — в базе.** Права по умолчанию запрещают, строки чужого арендатора не видны; роль в обход RLS
+  `connect()` отклоняет (`bypass_rls`), пока не передано `allowBypassRls: true`. Арендатора берут только из серверной
+  сессии ([«Веб-сервис: одно подключение и безопасность»](#веб-сервис-одно-подключение-и-безопасность)).
+- **Администраторский пул — явно.** `createTenant(admin, …)` принимает только пул `postgres()` (`api.create_tenant_admin`).
+- **Секреты в журнале событий маскируются**: поля с паролями, токенами, ключами и кредами, учётные данные в строке
+  подключения; значения параметров SQL и тексты ошибок PostgreSQL не пишутся вовсе. Значения фильтров чтения журнал
+  пишет как есть — персональные поля добавьте в `redact` ([«Логирование»](#логирование)).
+
+Общие правила для любой задачи на letopis — одна открытая запись на объект через ключ связи, удаление и возврат по
+превью, гонки, перевод ошибок в текст для человека — собраны в [памятке](AGENT-CHEATSHEET.md), «Правила для любой
+задачи».
+
 ### Как идёт чтение
 
 Под RLS индексы по `data` и по обратным ссылкам политике напрямую недоступны. Поэтому id для шагов цепочки
@@ -208,9 +241,8 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 | `none` | сигналов нет | ничего |
 
 Токен — 24 шестнадцатеричных знака ключевого HMAC: сопоставить псевдоним с именем может только процесс с ключом
-сигналов, а ключ выдаётся сервисам (право `letopis.signals`). Кроме сигналов записи, есть служебные: погашенная
-сессия шлёт `session:<16 hex>` (первые 16 шестнадцатеричных знаков sha256 её токена), сброс сессий — `session:*`,
-сброс арендатора или всей установки — `*` (сброс всей установки шлёт ещё и `session:*`). В режиме `none` нет и их.
+сигналов, а ключ выдаётся сервисам (право `letopis.signals`). Кроме сигналов записи, есть служебный: погашенная
+сессия шлёт `session:<16 hex>` (первые 16 шестнадцатеричных знаков sha256 её токена). В режиме `none` нет и его.
 Ни id, ни данных в сигналах нет. По сигналам перечитывается реестр классов, сбрасывается кэш результатов и будится
 подписка; что меняет режим для кэша и подписки — в [разделе 12](#12-подписка-на-изменения-и-кэш).
 
@@ -228,21 +260,28 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 | `schema` | имя установки: `'shop'` даёт схему `v2.shop`; можно сразу `'v2.shop'` |
 | `tenant` | первый арендатор и его пользователь (см. ниже) |
 | `seeds` | сиды после ядра: `'booking'` — демо-домен салона, или пути к своим файлам `.sql` |
-| `history` | политика хранения истории для классов без своей ([раздел 11](#11-история-и-срезы-на-дату)) |
-| `serviceKey` | свой ключ сервиса вместо случайного: `lts_` и 32–128 шестнадцатеричных знаков |
-| `allowReset` | разрешить `db.reset()` ([раздел 13](#13-эксплуатация)); по умолчанию выключено |
+| `serviceKey` | свой ключ сервиса вместо случайного: `lts_` и 32–128 шестнадцатеричных знаков в нижнем регистре (`/^lts_[0-9a-f]{32,128}$/`), иначе `invalid_data` ([«Сервис и ключи API»](#сервис-и-ключи-api)) |
 | `signals` | режим сигналов: `'class'` (по умолчанию), `'tenant'`, `'opaque'` или `'none'` ([«Сигналы»](#сигналы)); режим хранится в схеме — `up()` без опции его не меняет |
 | `fresh` | удалить схему и поставить заново — **данные схемы теряются** |
-| `upgrade` | обновить схему старой ревизии: миграции и повторный накат |
+| `upgrade` | обновить схему отставшей ревизии: миграции и повторный накат ([«Обновление пакета и схемы»](#обновление-пакета-и-схемы)) |
 | `pglite` | база для разработки без PostgreSQL (см. ниже) |
 | `quiet`, `waitTimeoutMs` | без сообщений в консоль; сколько ждать базу (по умолчанию 60 000 мс) |
 | `owner`, `app` | имена ролей владельца и приложения (по умолчанию `letopis_owner`, `letopis_app`) |
+| `login` | роль приложения `{ user, password }`: заводится или получает новый пароль и членство в `letopis_app`; строка подключения — `r.login.dsn` ([«Роль приложения»](#роль-приложения)) |
+| `migrationsDir` | свой каталог миграций для `upgrade` (по умолчанию `sql/migrate/` пакета) |
+| `log`, `logLevel`, `redact` | журнал событий установки (`up`, `migrate`), как у `connect()` ([«Логирование»](#логирование)) |
 
 Результат: `schema` (полное имя), `serviceKey` (при первой установке и при накате, когда в установке не осталось ни
 одного ключа API, кроме отозванных: истёкший или выключенный ключ тоже в счёт; иначе `null`), `created`,
-`upgraded`, `revision`, `migrations`, `analyzed`, `owner`, `app`, `signals` (режим сигналов установки), `warnings`
-(предупреждения, без `quiet` они печатаются), а также `tenant` и `pglite`, если их просили. На PostgreSQL ниже 18.2
-`up()` предупреждает: такой сервер мог усечь CLOG, который ещё нужен непрочитанным сигналам, — обновите его.
+`upgraded`, `revision`, `migrations`, `analyzed` (таблицы без статистики, у которых её собрал `ANALYZE` от роли
+владельца; оставшиеся без неё — в `warnings`), `owner`, `app`, `signals` (режим сигналов установки), `warnings`
+(предупреждения, без `quiet` они печатаются), а также `tenant`, `pglite` и `login` (`{ user, created, dsn }`), если
+их просили. На PostgreSQL ниже 18.2 `up()` предупреждает: такой сервер мог усечь CLOG, который ещё нужен непрочитанным сигналам, — обновите его.
+
+Ключ сервиса храните сами: повторный `up()` его не отдаёт (`serviceKey: null`). `up({ fresh: true })` ставит схему
+заново — вместе с данными пропадают сессии и ключи, и выдаётся новый ключ сервиса. Процесс со старым ключом получит
+`no_session: неверный ключ`: перезапустите его с новым. Чтобы ключ не менялся между установками (разработка,
+стенды), передавайте свой: `up({ …, serviceKey: process.env.SERVICE_KEY })` — он регистрируется и в новой схеме.
 
 Несколько экземпляров сервиса могут звать `up()` одной схемы одновременно: накат идёт под блокировкой схемы. Первый
 `up()` ставит или обновляет её, остальные ждут и делают повторный накат по готовой (`created: false`,
@@ -271,45 +310,56 @@ const ANNA = r.tenant!.user!       // его первый пользовател
 
 ### Роль приложения
 
-Приложение работает от LOGIN-роли, которая состоит только в `letopis_app`:
-`create role shop_app login password '…'; grant letopis_app to shop_app;`. Тогда на него действуют RLS и
+Приложение работает от LOGIN-роли, которая состоит только в `letopis_app`. Её заводит `up({ login: { user, password } })`:
+имя и пароль квотирует база, повтор обновляет пароль, а привилегированную роль (суперпользователя, с `CREATEROLE`,
+`CREATEDB`, `REPLICATION` или `BYPASSRLS`, роль-владельца или её члена) `up()` не трогает — `invalid_data`; строка подключения роли — `r.login.dsn`.
+Вручную — `create role shop_app login password '…'; grant letopis_app to shop_app;`. На роль приложения действуют RLS и
 триггеры, как и на любой сырой SQL от этой роли. Роль, которая обходит RLS, `connect()` отклоняет с ошибкой
-`bypass_rls`. Администраторское подключение (`allowBypassRls: true`) нужно только загрузчику, проекторам, ремонту
-агрегатов (`rebuildAggregates`), проверке и обслуживанию; держите его в отдельном процессе, а не в веб-приложении.
+`bypass_rls`. Администраторское подключение (`allowBypassRls: true`) нужно только загрузчику, обслуживанию
+и первой настройке прав арендатора ([«Права только по ролям»](#права-только-по-ролям)); держите его в отдельном процессе, а не в веб-приложении.
+Малому приложению хватит одного процесса — [ниже](#один-процесс).
 
 ### Первый арендатор и пользователь
 
 Права в letopis включены всегда и по умолчанию запрещают всё. Поэтому новому арендатору нужны правила. Опция
-`up({ tenant })` и функция `createTenant(sql, schema, opts)` делают это одной транзакцией:
+`up({ tenant })` и функция `createTenant(admin, schema, opts)` делают это одной транзакцией:
 
 - арендатор — аккаунт в System с id из имени («tenant:<имя>»);
-- правило «аутентифицированным можно всё» в этом арендаторе (`grantAll`, по умолчанию да, вес 10);
+- правило «аутентифицированным можно всё» в этом арендаторе — чтение, запись и удаление строк всех классов, но не
+  эндпоинты `api` (`grantAll`, по умолчанию да, `grantAll: false` — без него; вес 10; права только по
+  ролям — [ниже](#права-только-по-ролям));
 - пользователь (id из логина) с членством в арендаторе с ролями `user.roles` (по умолчанию `['owner']`), паролем и
   сессией в арендаторе.
 
-Повтор с теми же именем и логином ничего не дублирует и пароль не меняет, только выдаёт новую сессию. Логин входит в
-id как есть: `Anna@shop.ru` и `anna@shop.ru` дали бы два аккаунта, и у второго не было бы пароля, — пишите логин в
-одном регистре. Поле `created` в ответе — создан ли арендатор этим вызовом: для существующего арендатора с новым
+Повтор с теми же именем и логином ничего не дублирует и пароль не меняет, только выдаёт новую сессию. Крайние пробелы
+логина отбрасываются (` anna@shop.ru ` и `anna@shop.ru` — один пользователь), а регистр входит в id как есть:
+`Anna@shop.ru` и `anna@shop.ru` дали бы два аккаунта, и у второго не было бы пароля, — пишите логин в одном регистре. Поле `created` в ответе — создан ли арендатор этим вызовом: для существующего арендатора с новым
 пользователем оно `false`. Роли задаёт `user.roles` — непустой список имён (не масок), иначе `invalid_data`. Вид
 пароля `user.kind` (по умолчанию `PASSWORD`) подчиняется правилу вида креда, как у `auth.setPassword`
 ([«Справочник API»](#dbauth)), иначе — тоже `invalid_data`. Роли
 уже существующего членства повтор не меняет: их меняет правка членства ([«Выдать право»](#выдать-право)).
 Удалённое повтор не воскрешает: если арендатор, аккаунт пользователя или членство удалены (строки нет, а история в
 журнале есть), `createTenant` отвечает `invalid_data` и не записывает ничего. Текст ошибки называет удалённое и
-советует вернуть его `restore()`: аккаунт — `db.Account(id).restore()` от имени системного администратора,
-членство — `db.member(id).restore()` в этом арендаторе; другой выход — другое имя или логин. Сессия
+советует вернуть его `restore({ expect })` с надгробием из `withDeleted().rows()`: аккаунт —
+`db.Account(id).restore({ expect: await db.Account(id).withDeleted().rows() })` от имени системного администратора,
+членство — так же `db.member(id)` в этом арендаторе; другой выход — другое имя или логин. Сессия
 из `createTenant` — без способа входа, поэтому свой пароль по ней не сменить: для этого пользователь входит по
-паролю. `createTenant` нужен администраторский пул postgres.js:
+паролю.
+
+`admin` — **пул `postgres()`** администраторской роли (функция с методами `begin` и `unsafe`), а не строка
+подключения и не подключение `connect()` letopis: другое значение `createTenant` отклоняет до запросов — `invalid_query`
+(`api.create_tenant_admin`, текст называет, что передали). `schema` — как у `connect()` и `up()`: `'shop'` даёт
+`v2.shop`, можно сразу `'v2.shop'` или `r.schema`. Пул закрывает вызывающий:
 
 <!-- run: guide -->
 ```ts
 import postgres from 'postgres'
 import { createTenant } from 'letopis'
 
-const pg = postgres(ADMIN)
-const lutik = await createTenant(pg, r.schema, {
+const admin = postgres(ADMIN)                     // пул postgres(), не строка DSN
+const lutik = await createTenant(admin, r.schema, {
   name: 'Лютик', user: { name: 'Борис', login: 'boris@lutik.ru', password: 'Лютик-2026!' } })
-await pg.end()
+await admin.end()
 const BORIS = lutik.user!          // lutik: { tenant, user, token, created: true }
 ```
 
@@ -332,7 +382,7 @@ const anna = await connect({ dsn: APP, schema: r.schema, token: r.tenant!.token!
 | Опция `connect()` | Что делает |
 |---|---|
 | `dsn` или `sql` | строка подключения или готовый пул postgres.js |
-| `schema` | полное имя установки: `'v2.shop'` (удобно брать `r.schema`) |
+| `schema` | имя установки: `'v2.shop'` (удобно брать `r.schema`) или, как у `up()`, `'shop'` — то же `v2.shop` |
 | `token`, `apiKey` | токен сессии или ключ API (`service` — синоним `apiKey`) |
 | `models` | модели `letopis/model` — только для типов цепочек ([раздел 4](#4-модель-данных)) |
 | `max` | размер пула (по умолчанию 10) |
@@ -340,18 +390,23 @@ const anna = await connect({ dsn: APP, schema: r.schema, token: r.tenant!.token!
 | `cache` | кэш результатов: `{ ttl, max, ttlOnly }` или `false` ([раздел 12](#12-подписка-на-изменения-и-кэш)) |
 | `maintain` | запускать `maintain()` по расписанию: `'1h'`, `'15m'` или миллисекунды |
 | `onQuery`, `slowMs` | хук на каждый запрос цепочки и порог медленного запроса |
+| `log`, `logLevel`, `redact` | журнал событий: функция или объект-логгер (`console`, pino), порог (`'info'` по умолчанию) и ещё имена полей для маскировки ([«Логирование»](#логирование)) |
 | `refreshSession` | продлевать сессию раз в минуту работы (по умолчанию да) |
 | `notifyIntervalMs` | интервал отправки отложенных сигналов (100 мс) |
 | `allowBypassRls`, `owner` | разрешить роль в обход RLS (администраторское подключение); имя роли-владельца |
+| `admin` | строка подключения администратора или пул postgres.js: второй пул для `load`, `maintain` и `syncModels` с той же сессией ([«Один процесс»](#один-процесс)) |
+
+Неизвестная опция — ошибка `invalid_data` до подключения: похожие имена — в тексте и в `err.params.similar`. Так же
+проверяют опции `up()`, `db.load()`, `db.watch()` и `createMcpServer()` ([«Строгий режим»](#строгий-режим)).
 
 У подключения есть `db.schema`, `db.token`, `db.tenant` (арендатор сессии) и `db.close()`. Подключения,
-полученные через `as()`, делят пул с исходным: закрывать нужно исходное.
+полученные через `as()`, делят пул с исходным: закрывать нужно исходное, один раз — оно закрывает пул, подписки и все
+фасады. `close()` у подключения из `as()` ничего не делает: пул общий, и фасад после такого вызова работает дальше.
 
 ### Администраторское подключение
 
-Загрузчику, проекторам и `rebuildAggregates` нужно подключение роли, которая может стать владельцем, с
-`allowBypassRls: true`. `verify()` и
-`maintain()` работают и на нём, и у системного администратора по обычному подключению. Администраторское
+Загрузчику нужно подключение роли, которая может стать владельцем, с `allowBypassRls: true`. `maintain()` работает и
+на нём, и у системного администратора по обычному подключению. Администраторское
 подключение печатает предупреждение «RLS не действует» — так и должно быть. Сессия задаёт арендатора, с которым
 оно работает. Отдельному процессу загрузки удобнее ключ сервиса: `connect({ dsn: ADMIN, schema, apiKey,
 allowBypassRls: true })`, а арендатора строк задаёт опция `load(…, { tenant })`. В примере — сессия из `up()`:
@@ -361,54 +416,61 @@ allowBypassRls: true })`, а арендатора строк задаёт опц
 const adm = await connect({ dsn: ADMIN, schema: r.schema, token: r.tenant!.token!, allowBypassRls: true })
 ```
 
+### Один процесс
+
+Малому приложению не обязательно держать два процесса. `up({ login })` заводит роль приложения и отдаёт её строку
+подключения (`r.login.dsn`), а `connect({ dsn, admin, token })` при первом администраторском вызове открывает второй
+пул — не больше двух соединений — строкой администратора. Через него идут только `load`, `maintain` и `syncModels`,
+с той же сессией; цепочки и `db.sql` остаются в пуле приложения под RLS. Роль строки `admin` —
+суперпользователь или роль с `SET` на роль-владельца, иначе `admin_required`.
+Пароль администратора в процессе приложения — только для малых приложений: взломанный процесс получит и его.
+
+<!-- run: guide -->
+```ts
+const soloUp = await up({ dsn: ADMIN, schema: r.schema, login: { user: 'shop_app', password: 'app-secret' } })
+const solo = await connect({ dsn: soloUp.login!.dsn!, admin: ADMIN, schema: r.schema, token: r.tenant!.token! })
+const soloCheck = await solo.maintain()      // администраторским пулом, с сессией Анны: { skipped: false, … }
+const soloMembers = await solo.member().count()  // пулом приложения, под RLS: только своего арендатора
+await solo.close()                           // закрывает оба пула
+```
+
 ### Обновление пакета и схемы
 
-У схемы есть ревизия движка (сейчас 7). Если новая версия пакета принесла новую ревизию, `connect()` только
+У схемы есть ревизия движка (сейчас 10). Если новая версия пакета принесёт новую ревизию, `connect()` только
 предупредит и назовёт команду. Отказывает `up()`: на отставшую схему без `upgrade: true` и на схему новее пакета.
 К схеме новее пакета (её уже обновил более новый пакет, а старые экземпляры приложения ещё работают) `connect()`
-подключается с предупреждением «движок схемы … ревизии N новее библиотеки (она знает M) — обновите пакет letopis».
-Поэтому скрипт запуска, который вызывает `up()` при каждом старте, после обновления пакета остановится, пока не
-получит `upgrade: true`. `up({ dsn, schema, upgrade: true })` применяет миграции из `sql/migrate/` и повторно
-накатывает функции; данные сохраняются. Ревизия 7 (1.4.1) добавляет внешний ключ `secret.account`: миграция `0007`
-сначала стирает строки `secret`, чьих аккаунтов уже нет (креды удалённых раньше аккаунтов хранились с пометкой
-`deleted_at`), и ставит ключ.
-
-Ревизия меняется не с каждой версией: у 1.1–1.4.0 она одна (6), а функции разные. Поэтому `up()` пишет в комментарий
-схемы ещё и штамп движка: версию пакета и хэш его файлов SQL. Если штамп не совпадает с файлами пакета, `connect()`
-предупреждает. Когда схему накатила более старая версия (или версия до 1.4, у которой штампа нет), он советует
-`up({ schema })`. Когда схему уже обновила более новая версия, он советует обновить пакет: `up()` старой версией вернул
-бы прежние функции. Новая версия пакета без правок SQL штамп не меняет, и предупреждения нет.
-
-Первый `up()` после перехода на 1.2 строит индекс журнала `log_class_tenant_at (class, tenant, at)` вместо
-`log_class_at`: срез `asOf` и `withDeleted` по классу больше не читает журнал других арендаторов с тем же именем
-класса. Пока индекс строится, запись в журнал ждёт. На большой установке постройте его заранее, не останавливая
-записи: `create index concurrently log_class_tenant_at on "v2.<схема>".log (class, tenant, at)` от роли владельца, —
-тогда `up()` только снимет прежний.
-
-Обновление схем 1.4.1, 1.1.0 и 1.0.1 проверяет тест `upgrade`; каждый выпуск проверяет обновление с предыдущего
-выпуска. Схему ставит прежний пакет, данные пишет прежний движок, затем
-вызывается `up()` текущей версии. После него версии и хэши прежнего движка на месте, `verify({ data: true })` чист, а
-каталог схемы совпадает с чистой установкой. Схема 1.4.1 той же ревизии 7 обновляется обычным `up()`, без миграций;
-1.1.0 (ревизия 6) и 1.0.1 (ревизия 5) — через `up({ upgrade: true })`: миграцией `0007` и миграциями `0006` и `0007`.
+подключается с предупреждением
+«движок схемы … ревизии N новее библиотеки (она знает M) — обновите пакет letopis». Поэтому скрипт запуска, который
+вызывает `up()` при каждом старте, после такого обновления пакета остановится, пока не получит `upgrade: true`.
+`up({ dsn, schema, upgrade: true })` применяет миграции из `sql/migrate/` и повторно накатывает функции; данные
+сохраняются. Пока схема не обновлена, `connect()` предупреждает, а функции новой ревизии в ней не работают.
+
+Ревизия меняется не с каждой версией: у версий одной ревизии функции могут быть разные. Поэтому `up()` пишет в
+комментарий схемы ещё и штамп движка: версию пакета и хэш его файлов SQL. Если штамп не совпадает с файлами пакета,
+`connect()` предупреждает. Когда схему накатила более старая версия, он советует `up({ schema })`. Когда схему уже
+обновила более новая версия, он советует обновить пакет: `up()` старой версией вернул бы прежние функции. Новая версия
+пакета без правок SQL штамп не меняет, и предупреждения нет.
 
 ### Версии и совместимость
 
 Версии letopis следуют semver. Что обещает каждый шаг версии:
 
-- **Патч** (1.4.1 → 1.4.2) — только исправления. Ревизия движка та же: исправленные функции накатывает обычный
+- **Патч** (3.0.0 → 3.0.1) — только исправления. Ревизия движка та же: исправленные функции накатывает обычный
   `up({ schema })`, миграций нет; до наката `connect()` предупреждает о расхождении штампа. Работающий код не получает
   новых отказов, методы, опции, экспорты и коды ошибок не исчезают.
-- **Минор** (1.4 → 1.5) — новые возможности: методы, опции, коды ошибок; изменения поведения, которые не ломают
+- **Минор** (3.0 → 3.1) — новые возможности: методы, опции, коды ошибок; изменения поведения, которые не ломают
   работающий код; новая ревизия движка. Новую ревизию накатывает `up({ schema, upgrade: true })`. Удалённого и
   переименованного нет.
-- **Мажор** (1.x → 2.0) — удаление и переименование методов, опций, экспортов и кодов ошибок, смена сигнатур и типов,
-  новые отказы для всех. Что менять в коде, описывает `MIGRATION.md`.
+- **Мажор** (3.x → 4.0) — удаление и переименование методов, опций, экспортов и кодов ошибок, смена сигнатур и типов,
+  новые отказы для всех. Что снято и чем его заменить, перечисляет запись версии в [CHANGELOG.md](CHANGELOG.md). Схему
+  прошлого мажора новый мажор может не обновлять.
 
 Текст сообщения об ошибке в API не входит: в патче он может стать точнее. Полагайтесь на `err.code`.
 
-Шаг версии перед каждым выпуском сверяет сценарий `check:semver`: он сравнивает контракт API (`docs/api-contract.json`)
-и ревизию движка с прошлым выпуском и требует шаг не меньше нужного. Каждый выпуск проверяет обновление схемы с
-предыдущего выпуска (тест `upgrade`).
+Шаг версии перед каждым выпуском сверяет сценарий `check:semver`: он сравнивает контракт API (`lib/api-contract.json`)
+и ревизию движка с прошлым выпуском и требует шаг не меньше нужного. Каждый выпуск проверяет
+обновление схемы с предыдущего выпуска. Что изменилось при переходе на 3.0 и чем заменить снятое — запись
+версии в [CHANGELOG.md](CHANGELOG.md).
 
 ### Разработка без PostgreSQL: PGlite
 
@@ -469,13 +531,8 @@ const line = link('line', { qty: z.number().int().min(1), price: z.number().int(
   ends: { Order: one(Order).onDelete('cascade'), Product },
   key: ['Order', 'Product'],
 })
-const Wallet = hub('Wallet', { number: z.string(), balance: z.number().int().min(0).default(0) },
-  { ends: { Customer }, key: ['number'] })
-const Movement = link('Movement', {
-  opId: z.string(), kind: z.enum(['topup', 'debit', 'adjust']), amount: z.number().int(), target: z.number().int().optional(),
-}, { ends: { Wallet }, key: ['Wallet', 'opId'] })
 
-const models = [Shop, Category, Product, Customer, Vip, Order, line, Wallet, Movement]
+const models = [Shop, Category, Product, Customer, Vip, Order, line]
 const plan = await syncModels(db, models)                     // сухой прогон: что будет создано и изменено
 const applied = await syncModels(db, models, { apply: true }) // { applied: true, created: ['Shop', …], … }
 ```
@@ -487,10 +544,18 @@ const applied = await syncModels(db, models, { apply: true }) // { applied: true
 поле необязательным, `.default(…)` — задаёт умолчание, которое база подставит при вставке. Пометки `.meta()` у поля
 (`title`, `description`, свои ключи) база хранит, но на проверку данных они не влияют.
 
-Правила `refine`, `superRefine` и `transform` в JSON Schema не выражаются, и база их не исполняет. `syncModels`
-возвращает их в `lost`: проверяйте такие правила в приложении. Описание с ключевым словом JSON Schema, которого
+Правила `refine` и `superRefine` в JSON Schema не выражаются, и база их не исполняет. `syncModels` возвращает их в
+`lost`: проверяйте такие правила в приложении. Преобразования Zod — `.trim()`, `.toLowerCase()`, `.toUpperCase()`,
+`.normalize()`, `.transform()`, `z.preprocess()`, `.pipe()` — меняют значение, а не проверяют его: ни база, ни
+валидатор их не исполняют, и данные записались бы как есть. Поэтому модель с ними `syncModels` (и `letopis sync`)
+отклоняет до записи, в том числе в сухом прогоне: `invalid_class` (`model.transform_unsupported`, пути и виды — в
+`err.detail.rules`). Значение приводят в коде сервиса до записи (`value.trim()`), а в модели оставляют проверку:
+`.regex()`, `.min()`, `.refine()`. Описание с ключевым словом JSON Schema, которого
 база не знает, отклоняется — ни одно правило не пропадёт молча. Шаблоны `pattern` — ограниченное подмножество
-регулярных выражений, общее для Zod, валидатора и базы.
+регулярных выражений, общее для Zod, валидатора и базы. Исполняет шаблон на данных только база: шаблон задаёт
+арендатор, и шаблон с катастрофическим перебором повесил бы процесс приложения. Поэтому валидатор на TypeScript
+(`compileValidator`, проверка до записи) `pattern` и `anyOf`/`oneOf` с ним в ветке лишь разбирает, а нарушение
+`pattern` приходит от базы при записи — тот же `ValidationError`.
 
 ### Концы
 
@@ -516,10 +581,13 @@ const applied = await syncModels(db, models, { apply: true }) // { applied: true
 Нужный формат ключевого поля задайте в модели, и база будет его проверять.
 
 - id не передают: база вычисляет его сама. Чужой id — `id_mismatch`, id для класса без ключа — `id_from_db`.
-- Заранее id вычисляет `db.idOf(класс, ключ)`, например `db.idOf('Shop', { name: 'Ромашка' })`.
+- Заранее id вычисляет `db.idOf(класс, ключ)`, например `db.idOf('Shop', { name: 'Ромашка' })`. Часть ключа — конец
+  связи: имя роли и id цели строкой, `db.idOf('Product', { Shop: shop.id, sku: 'K-1' })` (не строка ответа). Часть
+  ключа не строкой — `invalid_data` (`model.key_part_not_string`), конец не uuid — `invalid_data`
+  (`model.key_end_not_uuid`).
 - Класс без ключа (`Customer` выше) получает id от случайной части; узнать его можно из ответа записи.
-- Ключевое поле обычной правкой не меняется (`immutable_key`): новый ключ — новый id, это `rekey`
-  ([раздел 5](#5-запись)).
+- Ключ и класс объекта неизменны: правка ключевого поля или класса — `immutable_key`. Объект с другим ключом или
+  классом — новый объект ([раздел 5](#5-запись), «Ключ и класс неизменны»).
 
 Если уникальным должно быть что-то кроме ключа, сделайте это отдельным классом. Например, email — ключ хаба
 `Email`, а связь человека с ним — ключ `['Email']`. Персональные данные лучше не делать ключом самого человека:
@@ -534,78 +602,15 @@ id из email подбирается перебором и остаётся в
 
 ### Настройки класса
 
-- `history: false` — журнал для класса не ведётся: нет версий, среза на дату, восстановления и событий подписки.
-  Политика хранения — `history: { all: '1 day', daily: '3 months', … }` ([раздел 11](#11-история-и-срезы-на-дату)).
-  Сменить `history` у существующего класса может только тот, у кого есть право `READ` и `DELETE` без условий на все
-  строки класса и его потомков: по политике `maintain()` прореживает журнал, а `false` его выключает.
+- `history: false` — журнал для класса не ведётся: нет версий, среза на дату, восстановления и событий подписки (по
+  умолчанию `true` — журнал хранит каждую версию). Сменить `history` у существующего класса может только тот, у кого
+  есть право `READ` и `DELETE` без условий на все строки класса и его потомков: `false` выключает журнал — аудит этих
+  строк.
 - `ownerDefault: 'actor'` — владелец новых строк — сам пользователь, а не арендатор (по умолчанию `'tenant'`).
   Пригодится для правила «каждый видит свои записи».
 - `cache: { ttl }` — чтения только этого класса кэшируются без `.cache()` ([раздел 12](#12-подписка-на-изменения-и-кэш)).
 - `meta` — свободные метаданные для приложения: название, иконка, цвет, порядок в меню. До 64 КБ, наследуются по
   ключам (`null` убирает унаследованное значение), видны всем, у кого есть сессия. У конца — `.meta()`.
-- `derivedBy: 'имя-проектора'` — производный класс: его строки пишет только этот проектор ([«Проекторы»](#проекторы)).
-  Имя — строчные латинские буквы, цифры и `_.:-` (первый знак — буква или цифра), до 64 символов. Опция
-  наследуется, потомок её не меняет. Концы производного класса — только `onDelete: 'cascade'` или `'unset'`:
-  производная строка не мешает удалять цель. На строки производного класса не ссылаются. Приложение, сырой SQL и
-  загрузчик в такой класс не пишут: запись, правка и удаление его строк — `derived_class`. Сам производный класс
-  (свой или унаследованный) заводит, меняет и удаляет только администратор — администраторское подключение или
-  аккаунт с правом System `letopis.projector`; у сессии приложения это `acl_denied` ([«Проекторы»](#проекторы)).
-- `aggregate: { поле: { sum | count, of, via, where } }` — агрегат в базе: сумму или счётчик строк источника держит
-  сама база ([«Агрегаты в базе»](#агрегаты-в-базе)).
-
-### Агрегаты в базе
-
-Агрегат — поле, которое держит сама база: сумма поля или число живых строк класса-источника, чей конец ведёт на
-строку. Он нужен там, где итог обязан совпадать с источником и для сырого SQL: баланс кошелька, число позиций заказа.
-
-```ts
-const Wallet = hub('Wallet', { number: z.string(), balance: z.number().int().min(0), deposits: z.number().int().optional() }, {
-  key: ['number'],
-  aggregate: {
-    balance: { sum: 'amount', of: 'Movement', via: 'Wallet' },                                        // сумма операций
-    deposits: { count: true, of: 'Movement', via: 'Wallet', where: { properties: { amount: { minimum: 1 } } } },  // число пополнений
-  },
-})
-const Movement = link('Movement', { amount: z.number().int() }, { ends: { Wallet } })
-```
-
-- `sum: 'поле'` — сумма числового поля источника, `count: true` — число строк. `of` — класс-источник (имя или
-  модель) вместе с потомками, `via` — его одиночный конец, который ведёт на строку-цель. `where` — JSON Schema над
-  данными источника: строки, которые её не проходят, в агрегат не входят.
-- Считаются только живые строки того же арендатора, что и цель. Ссылка на строку System в агрегат не входит: общий
-  справочник не считает данные всех арендаторов. Агрегат класса арендатора, в том числе унаследованный от класса
-  System, считает только классы своего арендатора: класс System с именем `of` в него не входит, а свой потомок класса
-  System входит. Агрегат класса System считает классы System и классы арендатора строки-цели.
-- Поле пересчитывает триггер после каждого оператора: запись библиотеки, сырой SQL, каскад удаления, `restore`,
-  `reclass`, `rekey`, загрузчик, удаление аккаунта. Операции одного оператора складываются в одно приращение цели, а
-  правило класса (`min(0)`) проверяется над итогом: операция, которая увела бы баланс в минус, отклоняется с
-  `invalid_data`. Каждое изменение цели — её новая версия с автором и причиной операции.
-- Поле пишет только база. Значение в `create`, `update`, `upsert`, `rekey`, `reclass` или в сыром SQL — ошибка
-  `aggregate_field`. Новая строка получает итог уже существующих источников, обычно 0. Замена данных целиком без
-  поля сохраняет прежнее значение. Загрузчик переданное значение не пишет. Права на запись в цель не нужно:
-  достаточно права на запись в источник.
-- Описание проверяет база (`invalid_class`): поле есть в схеме, оно числовое и не входит в ключ; конец `via` —
-  одиночный и принимает класс цели; поле `sum` — число; агрегаты не образуют цикл; цель и источник — не системные и
-  не производные классы. Класс-источник описывают раньше агрегата: агрегат над классом, которого ещё нет, отклоняется.
-  У класса арендатора источник ищут среди классов арендатора. `syncModels` сам описывает источники раньше целей, а
-  модели по кругу (агрегат над собственным потомком, цикл агрегатов) отклоняет до записи (`invalid_class` с кругом).
-  Класс `of` не удаляется, пока его называет агрегат класса того же арендатора: сначала агрегат убирают из описания цели.
-- Строки попадают в агрегат только с ведома того, кто читает их все: поле считает и строки, которые автору не видны.
-  Описать или изменить агрегат может только тот, кто без условий читает все строки источника и его потомков. Сделать
-  класс источником (новый потомок источника, смена `parent`) может только тот, кто без условий читает все
-  строки этого класса и его потомков — и до правки, и после. Иначе `acl_denied`.
-- Новый источник проверяется и по тому, кто описал агрегат: он тоже должен без условий читать все строки класса.
-  Описавший — автор версии строки `Class` цели, с которой описание агрегата стало нынешним. Если он их не читает, класс
-  источником не станет (`acl_denied`), пока агрегат не опишет заново тот, кто читает. У агрегата класса System
-  описавший проверяется по классам System, как и при описании. Класс арендатора под агрегатом System проверяется
-  только у того, кто его заводит.
-- Опция наследуется, потомок заменяет её целиком. Добавить или изменить агрегат — ужесточение: запись в цель и в
-  источники ждёт, пока поле пересчитывается у всех строк.
-- `db.rebuildAggregates(класс)` пересчитывает поле из текущих строк — для ремонта. Версия пишется только там, где
-  значение изменилось. Расхождения показывает `db.verify({ data: true })`. Нужно администраторское подключение.
-- Сырой `INSERT … ON CONFLICT DO UPDATE SET data = excluded.data` для цели отклоняется: поле в `excluded.data` уже
-  поставил триггер вставки. Пишите `excluded.data - array['balance']`, и поле останется прежним; `upsert` библиотеки
-  делает так сам.
 
 ### Записать модель в базу
 
@@ -614,7 +619,21 @@ const Movement = link('Movement', { amount: z.number().int() }, { ends: { Wallet
 `syncModels` трогает только переданные классы и ничего не удаляет. Безопасные изменения — новое необязательное поле или
 конец, метаданные, алиас — применяются сразу. Всё остальное, в том числе любая правка условий `anyOf` и `oneOf`, —
 ужесточение: оно проверяет все строки семейства, и если им мешают строки, приходит `tightening_conflict` со списком. Классы пишутся в арендатора сессии, и другие арендаторы их не видят.
-Классы, общие для всех, лежат в System: их ставит сид установки или импорт.
+Классы, общие для всех, лежат в System: их ставит сид установки. Модель с преобразованиями Zod `syncModels`
+отклоняет ([«Поля»](#поля)).
+
+Одна модель в нескольких арендаторах — `syncModels` в сессии каждого: сервис действует от имени пользователя, которому
+в этом арендаторе можно писать классы (по правилу «можно всё» — его члену):
+
+```ts
+for (const [user, tenant] of [[ANNA, SHOP], [BORIS, lutik.tenant]]) {
+  await syncModels(await svc.as(user, { tenant }), models, { apply: true })   // классы — в каждом арендаторе свои
+}
+```
+
+Из командной строки — тот же `letopis sync` с токеном сессии каждого арендатора. Повтор по арендатору, где модель уже
+записана, ничего не меняет (`unchanged`). Администраторское подключение для этого не нужно: через фасад `svc.as()`
+классы пишет сессия пользователя в пуле приложения, под RLS.
 
 То же из командной строки:
 
@@ -624,25 +643,88 @@ npx letopis sync ./models.js --dsn "$APP" --schema v2.shop --token "$TOKEN" --ap
 npx letopis types --dsn "$APP" --schema v2.shop --token "$TOKEN" --out types.ts       # типы классов из базы
 ```
 
-### Типы цепочек
+### Строгий режим
+
+Строгий режим ловит ошибки раньше записи: опечатку в имени класса, роли или поля — при компиляции, а без строгих
+типов — до обращения к базе; правку и удаление всех строк без условия, неизвестную опцию и курсор у счёта — тоже до
+обращения к базе.
+
+**Строгие типы.** `connect({ …, models })` с моделями `letopis/model` или `connect<Models>({ … })` с объявлениями
+`letopis types` дают подключение со строгими типами (`TypedDb`). Описания классов библиотека всё равно берёт из базы:
+модели и объявления нужны только TypeScript.
+
+- Шаг от корня — только класс или алиас из моделей и системные классы `Class`, `Account`, `member`, `Resource`,
+  `rule` (встроенный набор `SystemModels`; своя модель с тем же именем заменяет встроенную).
+- Переход — только по концам: от класса — его роли и классы, связанные с ним концом в любую сторону.
+- Слот — только роль записываемого класса: `set(id | строка | цепочка)`, `add()` и `remove()` — у множественного
+  конца, `unset()` — у необязательного.
+- Поля фильтра и `or()` — поля и роли класса шага; поле `sum()` и `avg()` — числовое `'data.<путь>'` класса, `min()`,
+  `max()` и `countBy()` — любое его поле.
+- Строки ответа типизированы данными и концами класса: тип данных — `Infer<typeof Product>`, концов —
+  `InferLinks<typeof Product>`. Своё описание `meta` типизируется расширением интерфейса `ClassMeta`.
 
-`connect({ …, models })` даёт типы шагов, строк и фильтров по моделям. Описания классов библиотека всё равно берёт
-из базы, модели нужны только TypeScript. Тип данных строки — `Infer<typeof Product>`, концов —
-`InferLinks<typeof Product>`. Своё описание `meta` типизируется расширением интерфейса `ClassMeta`.
+```ts
+import { connect, gte, loose } from 'letopis'
+
+const typed = await connect({ dsn: APP, schema: r.schema, token: r.tenant!.token!, models })
+const pricey = await typed.Shop({ name: 'Ромашка' }).Product({ price: gte(1000) }).rows()   // data.price — number
+// @ts-expect-error — класса Prodcut нет
+typed.Prodcut()
+// @ts-expect-error — Shop и Category не связаны концом
+typed.Shop({ name: 'Ромашка' }).Category()
+const name: string = 'Product'                                      // имя, известное только во время выполнения
+const n = await loose(typed)[name]().count()
+```
+
+`letopis types` выдаёт для каждого класса `<Класс>Data`, `<Класс>Links` и `<Класс>Model` — имя, алиас, концы с
+классами целей и предков, — а в конце список `Models`: строгие типы работают и без моделей Zod. Имя, известное только
+во время выполнения, — `loose(db)[имя]()`: то же подключение без строгих типов, проверки во время выполнения те же.
+Модели без литеральных имён (список типа `AnyModel[]`) строгих типов не дают — тогда подключение без них (`Db`).
+Чего строгие типы не знают: возврат к узлу связи от класса, с которым она не связана концом, и роль чужого класса
+шагом; `db.as()`, `db.begin()`, `db.batch()` и `entity()` отдают цепочки без строгих типов.
+
+**Отказы во время выполнения** — с моделями и без них:
+
+| Что | Ответ |
+|---|---|
+| `delete({ confirm: true })` без `expect` (и без `all: true`) | `invalid_query` (`write.confirm_without_expect`) до записи, в батче — при `run()`: удаление не сверено с превью, которое видел пользователь ([раздел 7](#превью-и-удаление)) |
+| `restore()` без `expect` (и без `all: true`), в том числе по явному id | `invalid_query` (`write.restore_without_expect`) до записи ([«Восстановить: `restore`»](#восстановить-restore)) |
+| `update()` или `delete({ confirm: true, expect })`, а ни у шага глагола, ни у шагов до него нет фильтра, id, непустого `tags()`, `owner()` или `limit()` и раньше в цепочке нет `create()` или `upsert()` (цель `update()` задаёт и `data.id` патча) | `invalid_query` (`write.no_filter`) до записи, в батче — при `run()`; все строки шага — `{ all: true }` ([раздел 5](#изменить-update), [раздел 7](#превью-и-удаление)) |
+| неизвестная опция `connect()`, `up()`, `db.load()`, `db.watch()`, `createMcpServer()` | `invalid_data` с похожими именами |
+| шаг — не класс, не алиас и не роль реестра | `invalid_class` с похожими именами (системные классы в похожие не идут) — при вызове шага; подсказка — классы арендатора видны только в его сессии. В реестре сессии нет ни одного класса арендатора — свой ключ `api.unknown_step_no_classes`: сессия, похоже, в личном арендаторе ([«Работа в другом арендаторе»](#работа-в-другом-арендаторе)) |
+| у цепочки спросили свойство массива — `.length`, `.map()`, `.filter()`, `.forEach()`, `[0]` и т. п. — или перебрали её (`for…of`, `[...цепочка]`) | `invalid_query` (`api.chain_not_rows`): цепочка — не массив, строки даёт терминал — `await ….rows()` |
+| id шага, фильтра `{ id }` или значения конца — не uuid, `null` вместо id | `invalid_query` (`query.bad_uuid`) до запроса; id в любом виде, который принимает PostgreSQL (без дефисов, в фигурных скобках), проходит |
+| модель с преобразованием Zod (`.trim()`, `.transform()` …) | `invalid_class` (`model.transform_unsupported`) от `syncModels` до записи ([«Поля»](#поля)) |
+| `db.begin(аргумент)` — функция, строка, число, массив вместо опций `{ reason }` | `invalid_query` (`api.begin_arg`): `begin()` функцию не вызывает; неизвестная опция `begin()` — `invalid_data` с похожими |
+| `restore({ partial: true })` без `expect`, в том числе с `all: true` | `invalid_query` (`write.partial_without_expect`) |
+| `createTenant(admin, …)`, где `admin` — не пул `postgres()`: строка DSN, подключение `connect()`, `undefined` | `invalid_query` (`api.create_tenant_admin`) до запросов ([«Первый арендатор и пользователь»](#первый-арендатор-и-пользователь)) |
+| метод цепочки у результата `versions()`: `versions().rows()`, `.sort()`, `.limit()` | `invalid_query` (`api.versions_terminal`): `versions()` — терминал, модификаторы — до него |
+| `forUpdate()` с тем, что блокировать нельзя: `count()`, `paths()`, `versions()`, агрегат, `asOf()`, `withDeleted()`, `deep()`, глагол | `lock_unsupported` (`api.for_update_unsupported`): текст называет помеху |
+
+**Предупреждения** — не отказы: цепочка исполняется, а в консоль один раз на место (`console.warn`, текст начинается с
+`letopis:`) выводится строка:
+
+| Что | Ключ | Почему |
+|---|---|---|
+| шаг с аргументом `undefined`: `db.Product(undefined)` | `api.step_undefined_filter` | фильтра нет — шаг находит все строки, как `db.Product()`; чаще всего это пустая переменная с id |
+| шаг после `sort()`: `db.Shop(shop).sort('data.name').Product()` | `api.sort_not_last` | `sort()` относится к последнему шагу цепочки — ставьте его в конец |
+| `withDeleted()` не у последнего шага, а у последнего его нет: `db.Order(o).withDeleted().line()` | `api.with_deleted_step` | `withDeleted()` — модификатор своего шага: здесь удалённые заказы и живые строки; удалённые строки — `.line().withDeleted()` ([«Удалённые»](#удалённые)) |
+| поле фильтра (и внутри `or()`), `sort('data.…')` или агрегата, которого нет в описании ни одного класса шага (с потомками, если шаг не `exact()`; у роли — её целей); в фильтре годится и роль конца | `invalid_query` с похожими именами до запроса, у плана записи — до записи. Сверяется только первый ключ пути: путь внутрь поля-объекта не проверяется. У строк `Class` поля — свойства описания класса (`kind`, `alias`, `parent` и другие) |
+| `after()` перед `count()`, `sum()`, `avg()`, `min()`, `max()` или `countBy()` | `invalid_query`: курсор листает строки, а счёт идёт по всем объектам шага |
+| класс с зарезервированным именем | `invalid_class`: хаб — от `hub()`, `syncModels` и базы, связь — от базы ([«Имена классов»](#имена-классов)) |
 
 ### Имена классов
 
 Шаг цепочки называется именем класса, его алиасом или именем роли. Имена методов цепочки и корня (`count`, `sort`,
-`set`, `sql`, `auth` и другие) там, где такой метод есть, библиотека разбирает раньше классов: класс `count` доступен
-первым шагом `db.count(…)`, но не после другого шага. Связь с таким именем база не примет. Не давайте классам эти
-имена; полный список — в разделе
-[«Зарезервированные имена»](#зарезервированные-имена).
+`set`, `sql`, `auth` и другие) там, где такой метод есть, библиотека разбирает раньше классов, поэтому класс с таким
+именем не создать: хаб отклоняют `hub()`, `syncModels` и база, связь — база (`invalid_class`). Хаб, заведённый мимо
+проверки базы (например, от роли владельца), `up()` оставляет и называет в предупреждении, правку его описания база
+отклоняет. Полный список имён — в разделе [«Зарезервированные имена»](#зарезервированные-имена).
 
 ## 5. Запись
 
-Глаголы записи — `create`, `update`, `upsert`, `delete`, `anonymize`, `reclass`, `rekey`, `restore`, `purge` —
-звенья плана. Сам по себе глагол ничего не делает: план исполняет терминал (`rows`, `first`, `ids`, `count`), и весь
-план — одна транзакция.
+Глаголы записи — `create`, `update`, `upsert`, `delete`, `restore` — звенья плана. Сам по себе глагол ничего не
+делает: план исполняет любой терминал (`rows`, `first`, `ids`, `count` и другие), и весь план — одна транзакция.
 
 ### Создать: `create`
 
@@ -656,7 +738,9 @@ const [green] = await db.Category().create({ name: 'Зелёный чай' }).Pa
 const [kettle] = await db.Shop(shop).Product().create({ sku: 'K-1', title: 'Чайник', price: 2500 }).rows()
 const [sencha] = await db.Shop(shop).Product()
   .create({ sku: 'T-7', title: 'Сенча', price: 900 }).Category.add(green).rows()
+await db.Shop(shop).Product().create({ sku: 'M-1', title: 'Кружка', price: 400 }).rows()
 const [olga] = await db.Customer().create({ name: 'Ольга', email: 'olga@mail.ru' }).rows()
+await db.Vip().create({ name: 'Вера', email: 'vera@mail.ru', discount: 10 }).rows()   // Vip — потомок Customer
 
 try {
   await db.Shop().create({ name: 'Ромашка' }).rows()
@@ -670,8 +754,19 @@ try {
   защищён: повтор создаст второй объект.
 - Теги новой строки задаёт `.tags([…])` перед глаголом, владельца — `.owner(id)`; явного владельца должны разрешать
   права.
-- Удалённый объект можно создать снова тем же ключом: история продолжится.
-- Ответ — строки созданных объектов со всеми колонками ([раздел 15](#15-справочник-api), «Строка ответа»).
+- Удалённый объект можно создать снова тем же ключом: новый объект **занимает id удалённого** (id — v5 от ключа), и
+  история id продолжится. Восстановить прежний после этого нельзя: `restore({ expect })` по его надгробию — `not_deleted`
+  (`write.restore_id_taken`). Если удалённое ещё могут вернуть, перед `create()` проверьте
+  ключ вместе с удалёнными: `db.Shop({ name: 'Ромашка' }).withDeleted().first()` — строка с `$deleted: true` значит,
+  что ключ принадлежит удалённому объекту, и решать, восстановить его или занять ключ, должно приложение.
+- Ответ — строки созданных объектов со всеми колонками ([раздел 14](#14-справочник-api), «Строка ответа»).
+- Ключи со значением `undefined` (`{ phone: undefined }`) `create`, `upsert` и `update` отбрасывают. У `update` поле
+  поэтому не меняется, а `upsert` заменяет данные целиком — поле с `undefined` у него **пропадает**, как не
+  переданное. `null` — значение: оно проходит, только если схема поля его допускает (`.nullable()`).
+- Концы — не поля данных: ключ с именем роли (`{ Shop: shop.id }`) в данных `create` — ошибка `invalid_data` с ключом
+  `write.link_in_data` до записи: текст называет ключ и класс («… — связь, а не поле данных») и сразу форму слота —
+  `.Shop.set(id)`; конец берётся из пути или задаётся слотом ([«Концы: из пути и слоты»](#концы-из-пути-и-слоты)). То
+  же у `upsert` и `update`.
 
 ### Изменить: `update`
 
@@ -685,28 +780,41 @@ await db.Shop(shop).Product({ price: gte(2000) }).update({ title: 'Чайник
 
 `update` правит каждую цель шага и никогда не создаёт. Патч сливается с данными внутри оператора: вложенные
 объекты — рекурсивно, а массивы, скаляры и `null` заменяются. Поэтому параллельные правки разных полей не теряются.
-Если у шага нет своего фильтра, цель берётся из `data.id` патча, а без `data.id` правятся все сущности шага:
-`db.Product().update(…)` правит все товары арендатора. Шаг ничего не нашёл — ответ пустой и ошибки нет, поэтому
-проверяйте длину ответа. Если `update` затронул меньше строк, чем нашёл шаг, весь план откатывается: строку успели
-удалить — `target_not_found`, строка видна, но править её нельзя — `acl_denied`. Модификатор `.tags(…)` перед
-`update` отбирает строки; строка или список ещё и заменяют их теги целиком, а оператор (`has`, `hasAny`, `hasAll`)
-только отбирает — теги не меняются.
+Если у шага нет своего фильтра, цель берётся из `data.id` патча. Цели сужают фильтр, id, `tags()`, `owner()` или
+`limit()` у шага глагола или шагов до него (или `create()` и `upsert()` раньше в цепочке; пустой `tags([])` не
+сужает); без них — `invalid_query` до записи
+([«Строгий режим»](#строгий-режим)). Править все строки шага — явно: `db.Product().update({ views: 0 }, { all: true })`
+правит все товары арендатора. Шаг ничего не нашёл — ответ пустой и ошибки нет, поэтому проверяйте длину ответа.
+
+Фильтр, который сужает цели не только по id (по данным, концам, `tags()`, `owner()`), `update` перепроверяет: цели
+блокируются (`for no key update`, по порядку id) и читаются заново тем же запросом, а правятся только строки, которые
+и после ожидания блокировки подходят. Так `db.Product({ price: gte(2000) }).update(…)` не тронет товар, который
+параллельная транзакция успела удешевить, а из двух одновременных `db.Order({ id, status: 'new' }).update({ status:
+'paid' })` проходит один — второй отвечает `[]`. Фильтр родительского шага перепроверяется так же. Без гонки цели те
+же. Фильтр только по id перепроверять нечего: две одновременные правки одного id пройдут обе, вторая поверх первой. Перепроверка защищает только условие самого фильтра:
+новое значение, вычисленное из прочитанного, защищают `{ rev }` и `forUpdate()` в `db.begin()`, а правило «не больше
+одной открытой записи на объект» — ключ связи ([«Восстановить: `restore`»](#восстановить-restore)).
+Если `update` затронул меньше строк, чем нашёл шаг, весь план откатывается: строку успели удалить —
+`target_not_found`, строка видна, но править её нельзя — `acl_denied`. Модификатор `.tags(…)` перед `update`
+отбирает строки; строка или список ещё и заменяют их теги целиком, а оператор (`has`, `hasAny`, `hasAll`) только
+отбирает — теги не меняются.
 
 ### Создать или заменить: `upsert`
 
 <!-- run: guide -->
 ```ts
 const [kept] = await db.Shop().upsert({ name: 'Ромашка', city: 'Казань' }).rows()    // kept.$upsert: 'unchanged'
-const [moved] = await db.Shop().upsert({ name: 'Ромашка', city: 'Уфа' }).rows()      // moved.$upsert: 'updated'
+const [replaced] = await db.Shop().upsert({ name: 'Ромашка', city: 'Уфа' }).rows()   // replaced.$upsert: 'updated'
 ```
 
 `upsert` создаёт объект, а если объект с этим ключом уже есть — заменяет его данные, концы и теги целиком. Это
 один оператор `INSERT … ON CONFLICT`, поэтому гонки «проверил, что нет, — создал» не бывает. Правила:
 
 - только класс с ключом, иначе `no_key` без обращения к базе;
-- объект передаётся целиком: поля, которых нет в переданном объекте, пропадают;
+- объект передаётся целиком: поля, которых нет в переданном объекте или которые равны `undefined`, пропадают;
+  сохранить прежнее значение поля — `update`, а не `upsert`;
 - ответ несёт `$upsert`: `created`, `updated` или `unchanged`;
-- приращать `upsert` не умеет и затирает параллельные приращения — для денег он не годится;
+- приращать `upsert` не умеет и затирает параллельные приращения — для счётчиков он не годится;
 - для синхронизации больших справочников дешевле загрузчик с `existing: 'update'` ([раздел 9](#9-массовая-загрузка)).
 
 ### Концы: из пути и слоты
@@ -725,6 +833,16 @@ await db.Category(green).update({}).Parent.unset().rows()         // катег
 await db.Category(green).update({}).Parent.set(tea).rows()        // и снова внутри «Чая»
 ```
 
+У связи с двумя концами один конец обычно приходит из пути, второй — слотом; можно и оба слотом. Строка заказа
+`line` с концами `Order` и `Product` (пример целиком — в [«Как исполняется план»](#как-исполняется-план)):
+
+```ts
+await db.Order(order).line().create({ qty: 1, price: 900 }).Product.set(sencha).rows()      // Order — из пути
+// или так — оба конца слотом (вместо строки выше: ключ [Order, Product] второй такой строки не даст)
+await db.line().create({ qty: 1, price: 900 }).Order.set(order).Product.set(sencha).rows()
+// db.line().create({ qty: 1, price: 900, Order: order, Product: sencha.id }) — invalid_data: концы не поля данных
+```
+
 ### Числа и счётчики: `inc`
 
 <!-- run: guide -->
@@ -743,14 +861,10 @@ await db.Product(kettle).update({ views: inc(1, { start: 0 }) }).rows()    // п
 - поле должно уже быть числом; если его нет — `invalid_data` или `start`. `null` и нечисло — ошибка даже со `start`;
 - путь идёт только через существующие объекты;
 - маркер `inc` нельзя получить из JSON: `{ "$inc": 5 }`, пришедший из сети, остаётся данными;
-- деньги храните целым числом мелких единиц (копеек) не больше 2^53 − 1.
+- суммы храните целым числом мелких единиц (копеек) не больше 2^53 − 1.
 
-Счётчик, который обязан совпадать с источником и для сырого SQL, удобнее держать агрегатом
-([«Агрегаты в базе»](#агрегаты-в-базе)): его пересчитывает сама база, и забыть `inc` нельзя. Цена у агрегата и `inc`
-одна: операции одного объекта идут друг за другом под блокировкой его строки, и каждая пишет его версию. На машине
-замеров один объект так принимал 150–190 операций в секунду, сколько бы писателей его ни ждало
-([раздел 17](#17-производительность)). Для более горячих счётчиков берите проектор со свёрткой пачкой
-([«Проекторы»](#проекторы)): итог отстаёт от источника, зато писатели не ждут друг друга.
+Операции `inc` одного объекта идут друг за другом под блокировкой его строки, и каждая пишет его версию: писатели
+одного горячего счётчика ждут друг друга.
 
 ### Защита от параллельной правки: `{ rev }`
 
@@ -765,44 +879,16 @@ try {
 }
 ```
 
-Строгий режим нужен, когда новое значение вычислено из прочитанного: если строку успели изменить, приходит
-`conflict`, и ничего не записывается. Режим работает при одной цели шага (иначе `rev_ambiguous`). `conflict`
+Правка с `{ rev }` нужна, когда новое значение вычислено из прочитанного: если строку успели изменить, приходит
+`conflict`, и ничего не записывается. `{ rev }` работает при одной цели шага (иначе `rev_ambiguous`). `conflict`
 библиотека сама не повторяет: что делать с изменившимися данными, решает приложение. Другой способ — чтение с
-блокировкой `forUpdate()` ([раздел 8](#8-транзакции-батчи-и-деньги)).
-
-### Сменить ключ или класс
-
-<!-- run: guide -->
-```ts
-const [mug] = await db.Shop(shop).Product().create({ sku: 'M-1', title: 'Кружка', price: 400 }).rows()
-const [mug2] = await db.Product(mug).rekey({ sku: 'M-100' }).rows()     // новый ключ — новый id, ссылки переведены
-const [vip] = await db.Customer(olga).reclass('Vip', { name: 'Ольга', email: 'olga@mail.ru', discount: 10 }).rows()
-```
+блокировкой `forUpdate()` ([раздел 8](#8-транзакции-и-батчи)).
 
-- `rekey(патч)` — новое значение ключа: строка с новым id, все ссылки переведены, старая строка удалена. Если
-  ссылающаяся строка включает этот конец в свой ключ, её id тоже меняется, и перевод идёт дальше. Журнал связывает
-  старый и новый id (`moved`).
-- `db.rekeyClass(класс, ключ)` — новый ключ для всех строк семейства, одной транзакцией. У производного класса и
-  у класса с производным потомком — `derived_class`: строки производного класса пишет только проектор.
-- `reclass(класс, данные)` — смена класса; данные необязательны, а если переданы — задаются целиком. Строка уходит из
-  прежнего класса, поэтому нужно право `DELETE` на неё, `WRITE` — на новый класс и на каждую строку, чьи ссылки
-  переписывает перевод, на любой глубине. Если у нового класса нет ключа, id сохраняется (как у `vip` выше); если
-  есть — id вычисляется заново, а ссылки переводятся.
-  Роли ссылающихся строк должны принимать новый класс, иначе `reclass_denied`. Сырой `UPDATE … SET class`
-  проходит, только если ключа нет ни у старого, ни у нового класса (иначе `use_reclass`).
-- Удаление, смена класса и смена ключа работают только в `read committed`: транзакции библиотеки всегда открываются
-  на этом уровне.
+### Ключ и класс неизменны
 
-### Обезличить: `anonymize`
-
-<!-- run: guide -->
-```ts
-await db.Customer(olga).anonymize(['email']).rows()     // email → '[erased]', тег anonymized
-```
-
-`anonymize(поля)` затирает строковые поля новой версией и помечает строку тегом `anonymized`. Прежние версии
-остаются в журнале. Для полного забвения дальше идут обрезка истории ([раздел 11](#11-история-и-срезы-на-дату)),
-затем удаление и `purge` ([раздел 7](#7-удаление-и-восстановление)).
+Ключевые поля, класс, id, арендатор и владелец строки правкой не меняются — `immutable_key`, в том числе у сырого
+`UPDATE … SET class`. Объект с другим ключом или классом — новый объект: создайте его (`create`), переведите на него
+ссылки правкой ссылающихся строк и удалите прежний.
 
 ### Как исполняется план
 
@@ -823,10 +909,11 @@ await db.Order(order).line().create({ qty: 1, price: 900 }).Product.set(sencha).
   (`40001`) и конфликте журнала библиотека повторяет план целиком, до трёх раз.
 - Ошибка любого звена откатывает весь план. `exists` и `conflict` не повторяются: это ответы для приложения.
 - Модификаторы до глагола (`limit`, `offset`, `sort`) сужают его цели.
-- Модификатор после глагола относится к тому, что идёт за ним: к шагу класса, к `versions()`, `diff()`, `blame()` и
-  агрегатам или к целям следующего глагола. Если за ним сразу терминал `rows`, `first`, `ids`, `count` или `paths`,
-  сужать уже нечего — глагол прошёл по всем целям шага, — поэтому `db.Product().update(…).limit(1).rows()` даёт
-  `invalid_query` и ничего не пишет. В батче так же отказывает `run()`.
+- Модификатор после глагола относится к тому, что идёт за ним: к шагу класса, к `versions()` и агрегатам или к
+  целям следующего глагола. Если за ним сразу терминал `rows`, `first`, `ids`, `count` или `paths`,
+  сужать уже нечего — глагол прошёл по всем целям шага, — поэтому
+  `db.Shop(shop).Product().update(…).limit(1).rows()` даёт `invalid_query` и ничего не пишет. В батче так же
+  отказывает `run()`.
 - Глагол сразу после глагола пишет в те же сущности.
 - Строки ответа глагола идут в порядке его целей: по `sort()` до глагола, без него — по id; `first()` после глагола —
   первая по этому порядку.
@@ -856,6 +943,13 @@ const onlyCustomer = await db.Customer().exact().rows()        // только
 ценой `"900"`. Список как значение поля — «массив содержит все элементы». Операторы приводят своё значение к типу
 поля из JSON Schema. Роль конца в фильтре — id цели или `null`.
 
+Тип поля для сравнения — по классу шага. Шаг по родителю отдаёт и потомков, и в таком семействе поле может быть
+описано разными типами (потомок переопределил тип, в одном из классов поле не описано). Тогда значение, которое к
+типу класса шага не приводится, в операторах сравнения, `sort()`, `after()` и агрегатах `min`, `max`, `sum`, `avg`
+считается `null`: при сортировке по возрастанию оно идёт после прочих (по убыванию — первым), ни одному оператору
+сравнения не отвечает, агрегат его пропускает, а курсор такой строки — как курсор `null`. Значение, которое
+приводится (`'7'` у числового поля), сравнивается как число. В семействе с одним типом поля всё как обычно.
+
 <!-- run: guide -->
 ```ts
 import { lt, ilike, between, or, not } from 'letopis'
@@ -868,18 +962,45 @@ const ofShop = await db.Product({ Shop: shop.id }).rows()
 const roots = await db.Category({ Parent: null }).rows()       // корневые категории
 ```
 
-| Оператор | Условие |
-|---|---|
-| `ne(v)`, `gt(v)`, `gte(v)`, `lt(v)`, `lte(v)` | ≠ (с учётом `null`), >, ≥, <, ≤ |
-| `between(a, b)`, `inList([…])` | a ≤ x ≤ b; значение из списка |
-| `like(s)`, `ilike(s)`, `starts(s)`, `ends(s)` | шаблон с `%` и `_`; без учёта регистра; начинается с; заканчивается на |
-| `has(v)`, `hasAny([…])`, `hasAll([…])` | поле-массив содержит значение; хотя бы одно; все (`hasAll([])` подходит любой строке, `hasAny([])` — никакой) |
-| `exists(true \| false)`, `isNull()` | поле есть или нет; поле `null` или отсутствует |
-| `not(v)` | отрицание оператора; скаляр — «не равно» |
-| `or(f1, f2, …)` | любой из фильтров шага |
+Операторы и их ключи в JSON-фильтре MCP (инструмент `letopis_query`, [раздел 13](#агенты-и-mcp)):
+
+<!-- ops -->
+| TypeScript | MCP | Смысл |
+|---|---|---|
+| `ne(v)` | `{ "$ne": v }` | Не равно. Подходят и строки без поля или с `null`; `ne(null)` — строки, где у поля есть значение |
+| `gt(v)` | `{ "$gt": v }` | Больше. Сравнение — по типу поля из описания класса (числа — как числа, даты — как даты), поле без описания — как текст; строки без поля не подходят |
+| `gte(v)` | `{ "$gte": v }` | Больше или равно; сравнение — как у `gt` |
+| `lt(v)` | `{ "$lt": v }` | Меньше; сравнение — как у `gt` |
+| `lte(v)` | `{ "$lte": v }` | Меньше или равно; сравнение — как у `gt` |
+| `between(a, b)` | `{ "$between": [a, b] }` | От `a` до `b` включительно; сравнение — как у `gt`. Если `a` больше `b`, не подходит ничего |
+| `inList([v, …])` | `{ "$in": [v, …] }` | Одно из значений списка. Пустой список не находит ничего; `null` в списке не находит строк без значения — для них `isNull` |
+| `like(s)` | `{ "$like": "s" }` | Текст по шаблону с учётом регистра: `%` — любые символы, в том числе ни одного, `_` — ровно один; буквальные `%` и `_` — с обратной косой чертой |
+| `ilike(s)` | `{ "$ilike": "s" }` | Как `like`, но без учёта регистра |
+| `starts(s)` | `{ "$starts": "s" }` | Текст начинается с `s`, с учётом регистра. Это `like(s + '%')`: `%` и `_` внутри `s` не экранируются и работают как в шаблоне |
+| `ends(s)` | `{ "$ends": "s" }` | Текст заканчивается на `s`, с учётом регистра. Это `like('%' + s)`: `%` и `_` внутри `s` не экранируются и работают как в шаблоне |
+| `has(v)` | `{ "$has": v }` | Поле-массив содержит элемент `v`. Тип важен: `has(5)` найдёт число 5, но не строку `'5'` |
+| `hasAny([v, …])` | `{ "$hasAny": [v, …] }` | Поле-массив содержит хотя бы один элемент списка. Находит только строковые элементы; пустой список не находит ничего |
+| `hasAll([v, …])` | `{ "$hasAll": [v, …] }` | Поле-массив содержит все элементы списка, в любом порядке. Тип важен, как у `has`; пустой список подходит любой строке, даже без поля |
+| `exists(b = true)` | `{ "$exists": b }` | Поле есть в данных (`true`, по умолчанию) или его нет (`false`); значение не важно — поле с `null` тоже есть |
+| `isNull()` | `{ "$isNull": true }` | В поле `null` или поля нет совсем; отличить одно от другого помогает `exists` |
+| `not(x)` | `{ "$not": x }` | Отрицание: `x` — оператор (`not(gte(1000))` — меньше 1000 или поля нет) или простое значение — тогда это «не равно», как `ne` |
+| `or(f1, f2, …)` | `{ "$or": [f1, f2, …] }` | Хотя бы один из фильтров. Ставится вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и» |
+<!-- /ops -->
 
 Теги и владелец строки — модификаторы `.tags(…)` и `.owner(…)`.
 
+Пустые значения в фильтре:
+
+- `{ поле: null }` — вхождение в `data`: находит только строки, где в поле явно записан `null`. Строки, где поля нет
+  совсем, находят `isNull()` (и `null`, и нет поля) и `exists(false)` (только нет поля).
+- Фильтр `undefined` — шаг без фильтра: `db.Product(undefined).first()` вернёт любой товар и выведет предупреждение
+  `api.step_undefined_filter` ([«Строгий режим»](#строгий-режим)). Ключ со значением `undefined` в объекте фильтра
+  (`{ id: undefined }`, `{ Shop: undefined }`) отбрасывается. `update()` без сужения откажет сам (`invalid_query`), а
+  чтение — нет: обязательные id из запроса проверяйте до цепочки.
+- id в фильтре — uuid. Строка другого вида (`db.Product('42')`), а также `null` вместо id — `invalid_query`
+  (`query.bad_uuid`) до запроса: `Product(…): "42" — не uuid`. Так же проверяются `{ id }` и значение конца
+  (`{ Shop: '42' }`). Подходит любой вид, который принимает PostgreSQL: с дефисами, без них, в фигурных скобках.
+
 ### Терминалы и строка ответа
 
 | Терминал | Что отдаёт |
@@ -893,8 +1014,8 @@ const roots = await db.Category({ Parent: null }).rows()       // корневы
 | `sum`, `avg`, `min`, `max`, `countBy` | агрегаты по полю `'data.<путь>'`; на пустом множестве — `null`, у `countBy` — `{}` |
 
 Строка ответа: `id`, `class`, `rev` (номер версии), `tenant`, `owner`, `links` (концы), `data` (поля), `tags`,
-`at` (время версии), `author`, `op` (вид операции) и, если есть, `agent`, `reason`, `moved`. Служебные поля
-начинаются с `$`: `$deleted`, `$depth`, `$upsert`, `$action`, `$versions`, `$purged`.
+`at` (время версии), `author`, `op` (вид операции) и, если есть, `agent`, `reason`. Служебные поля начинаются с
+`$`: `$deleted`, `$depth`, `$upsert`, `$action`.
 
 ### Сортировка и постраничный вывод
 
@@ -907,6 +1028,13 @@ const page2 = await db.Product().sort('data.price', 'desc')
   .after(cursorOf(page1.at(-1)!, 'data.price')).limit(2).rows()   // строго после последней строки страницы
 ```
 
+Модификаторы выборки не привязаны к шагу, после которого стоят. `sort`, `limit`, `offset`, `after` и `forUpdate`
+относятся к последнему шагу цепочки (а перед глаголом — к его целям), `asOf` — ко всей цепочке:
+`db.Shop(shop).sort('data.price').Product().rows()` сортирует товары, а поле `sort()` сверяется с классом последнего
+шага — иначе `invalid_query` с именем этого класса. Шаг после `sort()` выводит предупреждение `api.sort_not_last`:
+ставьте `sort()` в конец цепочки. `withDeleted()` — модификатор своего шага, как `exact()`
+([«Удалённые»](#удалённые)).
+
 `sort(поле, 'asc' | 'desc')` — по `'at'`, `'rev'`, `'id'` или `'data.<путь>'`. `after(cursorOf(строка, поле))` —
 постраничный вывод «после такой-то строки»; он требует `sort()`. Такой вывод устойчив к вставкам и удалениям между
 страницами, но строка, у которой изменилось поле сортировки, может выпасть или повториться. Курсор — объект
@@ -920,7 +1048,8 @@ const page2 = await db.Product().sort('data.price', 'desc')
 `after()` листает и `versions()`: курсор версии несёт её `rev`, поэтому версии одного объекта с равным полем
 сортировки не теряются. В `paths()` курсор даёт `cursorOf(путь, поле)`: поле и id — последнего узла пути, а в `path`
 — id всех узлов, поэтому не теряются пути к одному узлу. Курсор `cursorOf(путь.Узел, поле)` с одного узла пропустит
-остальные пути к этому узлу. `count()`, агрегаты, `diff()` и `blame()` курсор не учитывают.
+остальные пути к этому узлу. `after()` перед `count()` и агрегатами — `invalid_query`: они считают по всем объектам
+шага, страницы у них нет.
 
 Поле данных бывает `null` или отсутствует. Такие строки `sort` ставит, как `order by` в PostgreSQL: при
 возрастании — в конце, при убывании — в начале, а `after()` считает `null` значением после всех прочих (по
@@ -960,7 +1089,8 @@ const orderPaths = await db.Order(order).line().Product().paths()   // [{ Order:
 ```
 
 `paths()` отдаёт узлы каждого варианта пути; ключ узла — имя шага или имя из `.alias(имя)`. Ключи идут в порядке
-шагов; если цепочка кончается возвратом к прежнему узлу, этот узел — последний. Повтор связи в
+шагов; если цепочка кончается возвратом к прежнему узлу, этот узел — последний. Совпавшие имена получают первый
+свободный ключ: `x`, `x_2`, `x_3` и так далее, ни один узел не теряется. Повтор связи в
 цепочке возвращает к её узлу: так из одной связи можно пройти в несколько сторон. `db.entity(строка | цепочка)`
 вставляет готовый узел в путь.
 
@@ -971,22 +1101,35 @@ const orderPaths = await db.Order(order).line().Product().paths()   // [{ Order:
 <!-- run: guide -->
 ```ts
 const preview = await db.Order(order).delete().rows()     // ничего не удаляет: заказ и его строки, $action каждой
-await db.Order(order).delete({ confirm: true }).rows()    // удалено: надгробия с $deleted: true
+const goneOrder = await db.Order(order).delete({ confirm: true, expect: preview }).rows()   // надгробия, $deleted: true
 
-const blockers = (await db.Shop(shop).delete().rows()).filter((x) => x.$action === 'restrict')
+const shopPreview = await db.Shop(shop).delete().rows()
+const blockers = shopPreview.filter((x) => x.$action === 'restrict')
 try {
-  await db.Shop(shop).delete({ confirm: true }).rows()   // магазину мешают товары: конец Shop — restrict
+  await db.Shop(shop).delete({ confirm: true, expect: shopPreview }).rows()   // магазину мешают товары: restrict
 } catch (e) {
   if (!(e instanceof LetopisError) || e.code !== 'delete_restricted') throw e
 }
 ```
 
-`delete()` без `{ confirm: true }` — только превью: всё замыкание каскада. В каждой строке превью `$action`:
-`delete`, `unset` или `restrict`, и `$depth` — уровень каскада (0 — сама цель; у строк `unset` и `restrict` его
-нет). С подтверждением удаляются все цели шага одним оператором, а каскад применяет правила концов. Итог —
-надгробия по уровням каскада, внутри уровня по id (в таком порядке они и в журнале); цели классов без журнала
-(`history: false`) — в конце. Превью не учитывает права: строка с `$action: 'delete'` может не удалиться у
-пользователя без права (`acl_denied`), поэтому интерфейсу стоит спросить `acl.checkData(класс, 'DELETE')`.
+Удаляют в два шага: `delete()` — превью, его показывают человеку; `delete({ confirm: true, expect: превью })` —
+удаление ровно показанного. `delete()` без `{ confirm: true }` ничего не удаляет и отдаёт всё замыкание каскада. В
+каждой строке превью `$action`: `delete`, `unset` или `restrict`, и `$depth` — уровень каскада (0 — сама цель; у
+строк `unset` и `restrict` его нет). С подтверждением удаляются все цели шага одним оператором, а каскад применяет
+правила концов. Итог — надгробия по уровням каскада, внутри уровня по id (в таком порядке они и в журнале); цели
+классов без журнала (`history: false`) — в конце. Превью не учитывает права: строка с `$action: 'delete'` может не
+удалиться у пользователя без права (`acl_denied`), поэтому интерфейсу стоит спросить `acl.checkData(класс, 'DELETE')`.
+
+- `delete({ confirm: true })` без `expect` — `invalid_query` (`write.confirm_without_expect`) до записи, ничего не
+  удалено: удаление не сверено с тем, что видел пользователь. Подсказка ошибки — та же форма в два шага.
+- Цели, как у `update`, сужают фильтр, id, `tags()`, `owner()` или `limit()` у шага глагола или шагов до него (или
+  `create()` и `upsert()` раньше в цепочке), иначе `invalid_query` (`write.no_filter`) до записи; превью — без условий.
+- Осознанно удалить текущий состав целей без сверки с превью — `delete({ confirm: true, all: true })`: с фильтром —
+  текущие цели фильтра, без фильтра — все строки класса. `all` вместе с `expect` снимает только требование фильтра:
+  превью сверяется. Без сверки — только для скриптов обслуживания, не в ответ на действие пользователя.
+- Чужой, невидимый или несуществующий id — превью пустое, и удаление с `expect: []` отвечает пустым ответом без
+  ошибки, как `update`: проверяйте длину ответа.
+
 Правила концов:
 
 - `restrict` — удаление запрещено, пока на цель ссылаются (`delete_restricted` со списком видимых строк и числом
@@ -997,36 +1140,172 @@ try {
 Каскад требует права на удаление каждой удаляемой строки, снятие ссылки — права на запись. Сырой
 `DELETE … WHERE id IN (…)` любого набора связанных строк работает так же.
 
+**Сверка с превью.** Между превью и подтверждением данные могут измениться: к заказу добавили строку, строку
+поправили. С `expect: превью` удаление в своей транзакции строит превью заново и сравнивает его с показанным — по `id`,
+`rev` и `$action` (строки без `$action` сравниваются по `id` и `rev`). Совпало — удаляет. Не совпало — `conflict` с
+ключом `write.preview_changed`, ничего не удалено, новое превью — в `err.detail.preview`: его показывают пользователю и
+удаляют уже с ним. `expect` без `confirm: true` — `invalid_query` (`write.expect_without_confirm`), `expect` не
+списком строк `{ id, rev }` — `invalid_query` (`write.bad_expect`).
+
+`expect` — строки превью как есть (тип `Expected`: `{ id, rev, $action? }`), порядок не важен. `err.detail.preview` —
+`Row[]` той же формы, что превью: строки с `$action` и, у строк `delete`, `$depth`. Сверка атомарна и под гонкой: всё
+замыкание каскада (строки превью с `$action: 'delete'`) блокируется в порядке id, и превью строится ещё раз уже под
+блокировкой. Связь к удаляемой строке, добавленная до этого, попадает в новое превью (`preview_changed`); добавленная
+позже ждёт удаления и получает `target_not_found` (`sql-write.end_target_missing`) — непоказанное каскадом не уходит.
+Взаимную блокировку двух таких удалений операция из пула повторяет сама (`40P01`), в `db.begin()` — повторяет
+вызывающий. Пустые цели: `expect: []` и целей нет — пустой ответ; `expect` непуст, а целей уже нет (удалены, не
+видны) — `conflict` с пустым `err.detail.preview`.
+
+```ts
+const shown = await db.Order(id).delete().rows()                      // превью — пользователю
+// … пользователь подтвердил
+try {
+  const gone = await db.Order(id).delete({ confirm: true, expect: shown }).rows()   // удалено ровно показанное
+  // gone — надгробия: сохраните, по ним возвращают ровно ушедшее
+} catch (e) {
+  if (!(e instanceof LetopisError) || e.code !== 'conflict') throw e
+  const fresh = (e.detail as { preview: Row[] }).preview             // данные изменились: показать заново
+}
+```
+
 ### Восстановить: `restore`
 
 <!-- run: guide -->
 ```ts
-await db.Order(order).restore().rows()                       // заказ — последним снимком, id прежний
-await db.Order(order).line().withDeleted().restore().rows()  // и его строки, удалённые каскадом
+const back = await db.begin({ reason: 'возврат A-1' })   // заказ и его строки — одной транзакцией
+try {
+  await back.Order(order).restore({ expect: goneOrder }).rows()                      // заказ — тем снимком, что ушёл
+  await back.Order(order).line().withDeleted().restore({ expect: goneOrder }).rows() // и строки этого каскада
+  await back.commit()
+} catch (e) {
+  await back.rollback()                  // ошибка второго шага не оставит заказ без строк
+  throw e
+}
 ```
 
-`restore()` возвращает последний снимок удалённого объекта новой версией и перепроверяет его по текущему описанию
-класса. Восстанавливаются только цели шага, а не весь каскад. Живой объект — `not_deleted`.
+`restore({ expect })` возвращает удалённый объект его последним снимком новой версией и перепроверяет его по текущему
+описанию класса; id прежний. `expect` — надгробия `{ id, rev }`: ответ `delete({ confirm: true, expect })` или строки
+`withDeleted()` с `$deleted: true` (`db.Order(id).withDeleted().rows()`). Восстанавливаются только цели шага, чьи id
+есть в `expect`, а не весь каскад. Живой объект — `not_deleted`.
+
+- `restore()` без `expect` — `invalid_query` (`write.restore_without_expect`) до записи, и по явному id тоже: без
+  `expect` поднялось бы **последнее** надгробие id, а id удалённого может достаться другому — `create()` по ключу
+  удалённого занимает его id ([«Создать: `create`»](#создать-create)), а новый объект потом тоже удаляют.
+- Осознанно вернуть все удалённые цели шага без сверки версий — `restore({ all: true })`: с фильтром — удалённые цели
+  фильтра, без фильтра — всё удалённое класса; `all` вместе с `expect` — сверка по `expect`.
+- Цели — удалённые объекты последнего шага: шаг глагола `restore()` сам читает с удалёнными, `withDeleted()` перед
+  ним не обязателен. Чужой, невидимый или несуществующий id, id не из `expect` — пустой ответ без ошибки, как у
+  `update`: проверяйте длину ответа.
+- Шаги до глагола идут по живым строкам, если у них нет своего `withDeleted()`. Поэтому каскад возвращают после цели —
+  `db.Order(order).line().restore({ expect })` находит строки восстановленного заказа, — а строки ещё удалённого
+  заказа находит `db.Order(order).withDeleted().line().restore({ expect })`.
+
+**Сверка с надгробиями.** Восстанавливаются только цели, у которых последняя версия — это самое надгробие из
+`expect`. Иначе ничего не восстановлено, а отказ называет причину по записи журнала, которая идёт за надгробием цели:
+
+| Что с id после удаления | `why` | Ключ | Код |
+|---|---|---|---|
+| объект уже восстановлен (другим запросом) | `restored` | `write.restore_already` | `not_deleted` |
+| id занял новый живой объект с тем же ключом (`create()` по ключу удалённого) | `reissued` | `write.restore_id_taken` | `not_deleted` |
+| прочее: id пересоздан и удалён снова, объект удалён снова с другим номером версии, гонка | `changed` | `write.restore_stale` | `conflict` |
+
+У всех трёх `err.detail.ids` — id этого вида, а `err.detail.stale` — все цели, которые не восстановить:
+`[{ id, rev, expected, after, deleted, live, why }]`. `rev` — номер последней версии сейчас, `expected` — из
+`expect`, `after` — вид записи журнала сразу за `expected` (`create`, `update`, `delete`, `restore`; `null` — её нет),
+`deleted` — последняя версия — надгробие, `live` — объект живёт, `why` — из таблицы. Цели разного вида в одном вызове
+дают `restore_stale`, если среди них есть `changed`, иначе `restore_id_taken`, если есть `reissued`. Номер версии база
+сверяет ещё раз под блокировкой записи журнала и перечитывает последнюю запись после ожидания, поэтому гонку
+«прочитали надгробие — другой процесс пересоздал id — восстановили» ловит она, а проигравший гонку двух `restore()`
+получает `write.restore_already`. id из `expect`, которых нет среди целей шага, пропускаются: весь ответ `delete()` можно
+передавать каждому шагу. Поэтому шаг глагола задавайте id из `expect`: объект, который по пути уже не найти (связь
+пересоздана с другим концом), по пути молча пропустится, а по id даст `conflict`. Цель и её каскад возвращают одной
+`db.begin()`, цель конца — первой: отказ на любом шаге откатывает всё.
 
-### Стереть историю: `purge`
+```ts
+const gone = await db.Order(order).delete({ confirm: true, expect: shown, reason: 'отмена A-1 #7f3a' }).rows()
+const ids = (cls: string) => gone.filter((x) => x.class === cls).map((x) => x.id)
+// … позже: вернуть ровно это — заказ и строки этого каскада, одной транзакцией
+const tr = await db.begin()
+try {
+  await tr.Order(ids('Order')).restore({ expect: gone }).rows()   // заказ — если это всё ещё его надгробие
+  await tr.line(ids('line')).restore({ expect: gone }).rows()     // строки этого каскада, удалённые раньше — нет
+  await tr.commit()
+} catch (e) {
+  await tr.rollback()
+  if (!(e instanceof LetopisError) || (e.code !== 'conflict' && e.code !== 'not_deleted')) throw e
+  // e.key — write.restore_stale, write.restore_id_taken или write.restore_already; причины по целям —
+  // e.detail.stale[].why — пользователю: «id занят новой записью», «после удаления меняли», «уже вернули»
+}
+```
+
+**Вернуть, что можно: `restore({ expect, partial: true })`.** Без `partial` отказ одной цели отменяет всё. С
+`partial` восстанавливаются цели, у которых совпал номер версии, а остальные не роняют операцию и приходят в том же
+ответе строками-пропусками: последняя строка цели (живая или надгробие с `$deleted`) с `$action: 'skip'` и `$why` —
+`'restored'`, `'reissued'` или `'changed'`, как `why` в таблице выше. Ответ — в порядке целей (`sort()` до глагола,
+иначе по id). Каждая цель восстанавливается под своей точкой сохранения, поэтому проигранная гонка с другим
+`restore()` тоже становится пропуском. Ошибки другого рода — `target_not_found`, `invalid_data`, права — роняют
+операцию, как без `partial`. `partial` без `expect` — `invalid_query` (`write.partial_without_expect`), и с
+`all: true` тоже. Продолжение цепочки после такого `restore()` идёт только от восстановленных; `count()` и `ids()`
+сразу после него считают и пропуски — это строки ответа глагола.
+
+```ts
+const tr = await db.begin()
+try {
+  await tr.Order(ids('Order')).restore({ expect: gone }).rows()                    // заказ — целиком или отказ
+  const lines = await tr.line(ids('line')).restore({ expect: gone, partial: true }).rows()
+  await tr.commit()
+  const skipped = lines.filter((x) => x.$action === 'skip').map((x) => ({ id: x.id, why: x.$why }))
+  // skipped — пользователю: что не вернулось и почему
+} catch (e) {
+  await tr.rollback()
+  throw e
+}
+```
+
+Ответ `delete()` не сохранили — надгробия по id: `db.line(id).withDeleted().rows()` (строки с `$deleted: true`) — и
+их в `expect`. Ни ответа, ни id — надгробия по пути и причине удаления: каскад получает `reason` глагола. Причину
+делайте **своей у каждого удаления** (с номером операции, как `#7f3a` выше): у пересозданного и снова удалённого
+объекта последнее надгробие несёт причину того, второго удаления, и под ваш отбор не попадёт. Путь теряет и другое:
+объект, чей id занял новый живой объект, по пути от прежнего конца уже не находится (последняя версия ведёт к другому),
+и пропуска `reissued` по нему не будет — человек не узнает, что он не вернулся. Срез `asOf()` на момент до удаления
+показывает, что было живо, но его строки — живые версии: их `rev` для `expect` не годится.
 
-<!-- run: guide -->
 ```ts
-const [temp] = await db.Customer().create({ name: 'Тест', email: 'test@example.com' }).rows()
-await db.Customer(temp).delete({ confirm: true }).rows()
-const before = await db.Customer(temp).purge().rows()          // превью: $versions — сколько версий в журнале
-await db.Customer(temp).purge({ confirm: true }).rows()        // история стёрта; в журнале — запись purge
+const ours = (await db.Order(order).withDeleted().line().withDeleted().rows())
+  .filter((x) => x.$deleted && x.reason === 'отмена A-1 #7f3a')   // строки удалённого заказа с причиной этого удаления
 ```
 
-`purge` работает только для удалённых объектов (живой — `not_deleted`) и стирает их историю целиком; на месте
-версии 1 остаётся запись `purge` с числом стёртых версий. История системных классов не стирается. Пока проектор,
-чьи источники `from` включают класс объекта ([«Проекторы»](#проекторы)), не прочёл удаление, `purge` отказывает
-(`projector_pending`): стёртое надгробие проектор не увидел бы, и вклад объекта остался бы в итогах. Удаление и
-`purge` одной транзакцией в таком классе поэтому не проходят. Так же `db.trimHistory` отказывает, пока проектор не
-прочёл первую оставшуюся версию: прошлую версию для `before` он бы уже не нашёл. Удалить аккаунт — `db.auth.purgeAccount`
-([раздел 10](#10-пользователи-вход-и-права)).
+Штатные ответы `restore()` — их показывают пользователю, а не превращают в 500:
 
-## 8. Транзакции, батчи и деньги
+| Ответ | Когда | Пользователю |
+|---|---|---|
+| пустой | id чужой, невидимый, не существует или не среди целей шага | «не найдено» |
+| `invalid_query`, ключ `write.restore_without_expect` | нет `expect` (и нет `all: true`) | — (ошибка в коде) |
+| `not_deleted`, ключ `write.not_deleted` | объект жив и не удалялся | «не удалён» |
+| `not_deleted`, ключ `write.restore_already` | объект уже восстановлен (в том числе проигранная гонка двух `restore()`); id — `err.detail.ids` | «уже восстановлено» |
+| `not_deleted`, ключ `write.restore_id_taken` | id занял новый живой объект с тем же ключом (`create()` по ключу удалённого); id — `err.detail.ids` | «место занято новой записью» |
+| `conflict`, ключ `write.restore_stale` | после этого удаления id меняли — пересоздан и удалён снова, удалён снова; причины — `err.detail.stale` | «после удаления запись меняли» |
+| строки `$action: 'skip'` | с `partial: true` вместо трёх отказов выше; причина — `$why` | что не вернулось и почему |
+| `target_not_found` | цель конца снимка удалена или не видна | сначала восстановить цель |
+| `invalid_data` | снимок не проходит нынешнее описание класса | — |
+
+- `restore()` перепроверяет описание класса, концы (цель конца жива и видна, иначе `target_not_found`), ключ и права,
+  но не бизнес-правила приложения: восстановленная связь вернёт занятость прежнему концу, даже если объект уже занят
+  другим. Гарантию даёт только ключ связи: занятость держит ключ, а не поле и не проверка. Проверка в коде перед
+  `restore()` держит правило, лишь если **все** пути создания и возврата таких связей берут в `db.begin()` одну и ту же
+  блокировку (`forUpdate()` объекта или `tr.lock(…)`) и делают ту же проверку: один путь без неё — обычный `create()`
+  связи — гарантию ломает, потому что `create()` и `restore()` берут на объекте совместимую блокировку и друг друга не
+  ждут. Связь с ключом только из одного конца (`key: ['Obj']`) база второй для того же
+  объекта не создаст (`exists`). Удалённую каскадом такую связь новая на тот же объект создаёт заново с тем же id
+  (v5 от ключа), и восстановить прежнюю уже нельзя: пока новая связь жива, `restore({ expect })` —
+  `not_deleted` (`write.restore_id_taken`); когда удалена и она — `conflict` (`write.restore_stale`); с
+  `partial: true` вместо отказа — строка-пропуск. Общие правила — «одна открытая запись на объект» и возврат по ответу
+  `delete()` — в [памятке](AGENT-CHEATSHEET.md), «Правила для любой задачи».
+
+Историю удалённого объекта журнал хранит: стереть версии одного объекта нельзя. Удаление аккаунта
+(`db.auth.purgeAccount`, [раздел 10](#10-пользователи-вход-и-права)) стирает данные и журнал его арендатора.
+
+## 8. Транзакции и батчи
 
 ### Каждая операция — транзакция
 
@@ -1057,6 +1336,9 @@ try {
   библиотека о ней не знает, PostgreSQL молча отвечает `ROLLBACK` на `COMMIT`, а библиотека превращает это в ошибку
   `tx_rolled_back`.
 - Повторов внутри `db.begin()` нет: на `40P01` повторите весь блок.
+- `db.begin()` принимает только опции `{ reason }`. Функцию она не принимает и не вызывает: `db.begin(async (tr) => …)`,
+  строка, число или массив — отклонённый промис `invalid_query` (`api.begin_arg`) с подсказкой — формой выше;
+  неизвестная опция — `invalid_data` с похожими именами.
 - `lock(...ключи)` — advisory-блокировка до конца транзакции. Она защищает, только если её берут все, кто правит
   эти данные.
 
@@ -1077,74 +1359,23 @@ const results = await b.run()       // Row[][] — по массиву стро
 который поставил его в очередь (актор, арендатор, владелец, транзакция), и чужих планов `run()` не исполняет.
 Копите планы через один и тот же объект фасада.
 
-### Рецепт: кошелёк
-
-Баланс — поле `balance` хаба `Wallet` (целые копейки, `min(0)`), операции — связь `Movement` с ключом
-`[Wallet, opId]` ([раздел 4](#4-модель-данных)). Операцию не правят и не удаляют, а отменяют встречной операцией с
-новым `opId`. Ключ делает операцию идемпотентной: повтор после потери ответа получает `exists`, и рецепт сверяет,
-тот ли это запрос.
-
-<!-- run: guide -->
-```ts
-import { inc, type Db } from 'letopis'
-
-type Kind = 'topup' | 'debit' | 'adjust'
-
-/** Операция: запись Movement и приращение баланса — один план, одна транзакция. */
-async function operate(db: Db, wallet: string, opId: string, kind: 'topup' | 'debit', amount: number) {
-  try {
-    await db.Wallet(wallet).Movement().create({ opId, kind, amount })
-      .Wallet().update({ balance: inc(kind === 'topup' ? amount : -amount) }).rows()
-    return 'done'
-  } catch (e) {
-    if (e instanceof LetopisError && e.code === 'exists') return same(db, wallet, opId, kind, amount)   // повтор
-    throw e                                        // invalid_data — не хватает средств (min(0))
-  }
-}
-
-/** Отпечаток повтора: тот ли запрос уже записан под этим opId. */
-async function same(db: Db, wallet: string, opId: string, kind: Kind, value: number) {
-  const m = await db.Movement(db.idOf('Movement', { Wallet: wallet, opId })).first()
-  if (!m || m.data.kind !== kind || (kind === 'adjust' ? m.data.target : m.data.amount) !== value)
-    throw new Error(`ключ операции ${opId} уже использован другим запросом`)
-  return 'repeat'
-}
-
-/** Корректировка «баланс = target»: операция adjust на разницу, итог — под { rev }. */
-async function adjust(db: Db, wallet: string, opId: string, target: number) {
-  for (;;) {
-    if (await db.Movement(db.idOf('Movement', { Wallet: wallet, opId })).first()) return same(db, wallet, opId, 'adjust', target)
-    const cur = (await db.Wallet(wallet).first())!
-    try {
-      await db.Wallet(wallet).Movement().create({ opId, kind: 'adjust', amount: target - (cur.data.balance as number), target })
-        .Wallet().update({ balance: target }, { rev: cur.rev }).rows()
-      return 'done'
-    } catch (e) {
-      if (e instanceof LetopisError && e.code === 'conflict') continue     // кошелёк изменился — перечитать
-      if (e instanceof LetopisError && e.code === 'exists') return same(db, wallet, opId, 'adjust', target)
-      throw e
-    }
-  }
-}
+### Значение из прочитанного и повтор операции
 
-const [wallet] = await db.Customer(olga).Wallet().create({ number: 'W-1' }).rows()
-await operate(db, wallet.id, 'op-1', 'topup', 10_000)    // 'done': баланс 10 000
-await operate(db, wallet.id, 'op-1', 'topup', 10_000)    // 'repeat': повтор после потери ответа, баланс тот же
-await operate(db, wallet.id, 'op-2', 'debit', 3_000)     // баланс 7 000
-await adjust(db, wallet.id, 'op-3', 5_000)               // корректировка: adjust на −2 000, баланс 5 000
-```
+Новое значение, вычисленное из прочитанного, теряет параллельные правки, если его записать просто `update()`.
+Способов защиты три, и для одного объекта выбирают один:
 
-Тот же итог можно записать под чтением с блокировкой — без повторов при `conflict`:
+- **Приращение** — `update({ поле: inc(n) })`: база прибавляет внутри оператора, чтение не нужно, а `min(0)` в модели
+  отклоняет уход в минус (`invalid_data`, по `e.issues` — поле и правило `minimum`).
+- **Сверка версии** — `update(патч, { rev })`: строку успели изменить — `conflict`, перечитать и решить заново
+  ([«Защита от параллельной правки»](#защита-от-параллельной-правки--rev-)).
+- **Чтение с блокировкой** — `forUpdate()` внутри `db.begin()`: строка заблокирована до `commit()`, повторов нет.
 
 <!-- run: guide -->
 ```ts
-const [wallet2] = await db.Customer(olga).Wallet().create({ number: 'W-2' }).rows()
 const tx = await db.begin()
 try {
-  const w = (await tx.Wallet(wallet2).forUpdate().first())!     // строка кошелька заблокирована до commit
-  await tx.Wallet(wallet2).Movement()
-    .create({ opId: 'op-1', kind: 'adjust', amount: 6_000 - (w.data.balance as number), target: 6_000 })
-    .Wallet().update({ balance: 6_000 }).rows()
+  const locked = (await tx.Product(kettle).forUpdate().first())!          // строка заблокирована до commit
+  await tx.Product(kettle).update({ views: (locked.data.views as number) + 1 }).rows()
   await tx.commit()
 } catch (e) {
   await tx.rollback()
@@ -1152,87 +1383,30 @@ try {
 }
 ```
 
-- `inc` прибавляет внутри оператора над заблокированной строкой: параллельные списания не теряются, а `min(0)`
-  отклоняет списание сверх баланса.
-- Обычный `update({ balance: 700 })` записывает значение, а не прибавляет. Итог, вычисленный из прочитанного,
-  без `{ rev }` или `forUpdate()` теряет параллельные списания. Advisory `lock()` не спасает, если его берут не все
-  писатели. `upsert` затирает приращения.
 - `forUpdate()` — только внутри `db.begin()` (иначе `tx_required`) и только с `rows`, `first`, `ids` (иначе
   `lock_unsupported`). Строки блокируются в порядке id; строка, которая перестала подходить под условия шага, в ответ
   не попадает.
-- Для одного кошелька выберите один путь: под `{ rev }` и под `forUpdate()` кошелёк и ключ операции блокируются в
-  разном порядке, и смешение в параллельных запросах даёт `40P01`. Внутри блока с `forUpdate()` не ждите внешних
-  вызовов: кошелёк ждут все писатели (помогут `lock_timeout` и `idle_in_transaction_session_timeout`).
-- Перевод — две операции в одной `db.begin()`, кошельки правятся в порядке id: тогда взаимных блокировок нет.
-- Нехватку средств отличают от других ошибок данных по `e.issues`: поле `balance`, правило `minimum`.
-
-### Рецепт: баланс агрегатом
-
-Тот же кошелёк, только баланс держит сама база: `balance` — агрегат, сумма `amount` живых операций
-([«Агрегаты в базе»](#агрегаты-в-базе)). Операция — одна запись `Movement`, приращения `inc` в коде нет, и забыть его
-нельзя. Баланс остаётся верным, даже когда операции пишет сырой SQL или загрузчик, а удаляет каскад.
-
-```ts
-const Wallet = hub('Wallet', { number: z.string(), balance: z.number().int().min(0) }, {
-  ends: { Customer }, key: ['number'],
-  aggregate: { balance: { sum: 'amount', of: 'Movement', via: 'Wallet' } },   // баланс — сумма живых операций
-})
-const Movement = link('Movement', { opId: z.string(), amount: z.number().int() },
-  { ends: { Wallet }, key: ['Wallet', 'opId'] })                             // ключ операции — идемпотентность
-
-/** Операция: amount больше нуля — пополнение, меньше — списание. База пересчитает баланс в той же транзакции. */
-async function operate(db: Db, wallet: string, opId: string, amount: number) {
-  try {
-    await db.Wallet(wallet).Movement().create({ opId, amount }).rows()
-    return 'done'
-  } catch (e) {
-    if (e instanceof LetopisError && e.code === 'exists') return 'repeat'   // повтор после потери ответа
-    throw e                                        // invalid_data — баланс ушёл бы в минус (min(0))
-  }
-}
-
-/** Корректировка «баланс = target»: операция на разницу, кошелёк заблокирован до commit. */
-async function adjust(db: Db, wallet: string, opId: string, target: number) {
-  const tx = await db.begin()
-  try {
-    const w = (await tx.Wallet(wallet).forUpdate().first())!
-    await tx.Wallet(wallet).Movement().create({ opId, amount: target - (w.data.balance as number) }).rows()
-    await tx.commit()
-    return 'done'
-  } catch (e) {
-    await tx.rollback()
-    if (e instanceof LetopisError && e.code === 'exists') return 'repeat'   // корректировка с этим opId уже записана
-    throw e
-  }
-}
-
-const [wallet] = await db.Customer(olga).Wallet().create({ number: 'W-1' }).rows()   // balance — 0: его ставит база
-await operate(db, wallet.id, 'op-1', 10_000)    // баланс 10 000
-await operate(db, wallet.id, 'op-2', -3_000)    // баланс 7 000
-await adjust(db, wallet.id, 'op-3', 5_000)      // операция на −2 000, баланс 5 000
-```
-
-- Модель здесь своя, и блок в программу примера не входит: там баланс растёт через `inc`, а агрегатное поле так не
-  меняется.
-- `balance` не передают ни в `create`, ни в `update` (`aggregate_field`), поэтому корректировка — тоже операция, а не
-  `update` под `{ rev }`. Чтобы записать операцию, право на запись в кошелёк не нужно: хватает права на запись в
-  `Movement`.
-- Нехватка средств — `invalid_data`, как и с `inc`: в `e.issues` поле `balance` и правило `minimum`. Повтор сверяйте,
-  как `same()` в рецепте выше: `exists` говорит только о том, что операция с этим `opId` уже есть.
-- Правка и удаление операции тоже меняют баланс: база вычтет прежнее значение. Отменять операцию всё равно лучше
-  встречной операцией, тогда история кошелька остаётся полной.
-- Каждая операция блокирует строку кошелька и пишет его версию, поэтому операции одного кошелька идут друг за другом,
-  как и с `inc`: на машине замеров — около 150 в секунду ([раздел 17](#17-производительность)). Если один объект
-  получает больше, итог лучше считать проектором ([«Рецепт: дневная выручка»](#рецепт-дневная-выручка)).
+- Под `{ rev }` и под `forUpdate()` объект и ключи блокируются в разном порядке: смешение двух путей в параллельных
+  запросах одного объекта даёт `40P01`. Внутри блока с `forUpdate()` не ждите внешних вызовов: строку ждут все
+  писатели (помогут `lock_timeout` и `idle_in_transaction_session_timeout`).
+- Несколько объектов в одной `db.begin()` правьте в порядке id: тогда взаимных блокировок нет.
+- Обычный `update({ поле: значение })` записывает значение, а не прибавляет; `upsert` затирает приращения; advisory
+  `lock()` не спасает, если его берут не все писатели.
+- **Повтор операции.** Операцию, которую нельзя выполнить дважды, записывайте связью с ключом из объекта и номера
+  операции (`key: ['Объект', 'opId']`) вместе с приращением одним планом: повтор после потери ответа (`commit_unknown`,
+  обрыв связи) получает `exists` и ничего не меняет. Отменяют такую операцию встречной операцией с новым номером, а не
+  правкой и не удалением.
 
 ## 9. Массовая загрузка
 
 ### Когда нужен загрузчик
 
 Загрузчик — путь для импорта, засевки и синхронизации больших справочников. Он проверяет строки в коде библиотеки
-тем же валидатором, что и база, и пишет их командой `COPY` от роли владельца, без триггеров и RLS. На бенче это
-около 6 400 строк в секунду против 130 у построчного `create` ([раздел 17](#17-производительность)). Работает
-только на администраторском подключении (`allowBypassRls` и право стать владельцем), иначе — `admin_required`.
+тем же валидатором, что и база (шаблоны `pattern` — запросом к базе на пачку), и пишет их командой `COPY` от роли
+владельца, без триггеров и RLS. На замере `COPY` без триггеров писал около 14 000 строк в секунду, а
+построчная вставка через триггеры — около 170 ([раздел 16](#16-производительность)); проверки строк в коде библиотеки
+к этому добавляются. Работает только на администраторском подключении (`allowBypassRls` и право стать владельцем),
+иначе — `admin_required`.
 
 ### `db.load()`
 
@@ -1269,15 +1443,14 @@ const changed = await adm.load({ Shop: [{ name: 'Василёк', city: 'Сам
 | Опция | Значения |
 |---|---|
 | `duplicates` — повтор id внутри загрузки | `'error'` (по умолчанию) — отменить; `'first'` или `'last'` — оставить первую или последнюю строку |
-| `existing` — объект уже есть в базе | `'error'` (по умолчанию) — отменить; `'skip'` — пропустить, удалённые не воскрешать; `'update'` — новая версия, если содержимое отличается (неизменённые считаются в `skipped`), удалённые — создать заново; объект другого класса с тем же id (класс без ключа после `reclass`) — `exists` |
+| `existing` — объект уже есть в базе | `'error'` (по умолчанию) — отменить; `'skip'` — пропустить, удалённые не воскрешать; `'update'` — новая версия, если содержимое отличается (неизменённые считаются в `skipped`), удалённые — создать заново; объект другого класса с тем же id — `exists` |
 
-### Порции, история и проверка
+### Порции и история
 
 - `commitEvery: N` — фиксировать порциями примерно по N строк. Порции идут по классам в порядке зависимостей,
   классы из одного цикла — в одной порции. Ошибка отменяет только текущую порцию, а повтор с `existing: 'skip'`
   дописывает остальное.
-- `withHistory: true` — строки — это версии с `$rev`, `$at` и `$op`; так импорт переносит историю.
-- `verify: true` — в конце перепроверить загруженные строки проверкой базы.
+- `withHistory: true` — строки — это версии с `$rev`, `$at` и `$op`; так переносят историю из другой системы.
 - `batch` (строк в пачке `COPY`, 10 000), `class` (класс строк без `$class`), `tenant`, `agent` (агент версий).
 
 ### Загрузка от имени пользователя
@@ -1299,20 +1472,18 @@ const r = await adm.load(rows, { initial: true })   // пустая схема:
 ```
 
 `db.load(rows, { initial: true })` (`letopis load --initial`) заливает данные в пустую схему быстрее обычного
-загрузчика — на миллионе объектов примерно в 2,2 раза: всё идёт одной транзакцией, на время загрузки таблицы закрыты
+загрузчика — на миллионе объектов примерно в 2,2 раза (замер `lib/bench/initial-load.mjs`): всё идёт одной транзакцией, на время загрузки таблицы закрыты
 для чтения и записи, индексы, ограничения и триггеры сняты и строятся заново в конце, строки пишутся `COPY … FREEZE`.
-Пустая — значит, кроме строк системных классов (описания классов, аккаунты, членства, ресурсы, правила) и записей
-`reset`, в схеме ничего нет; иначе — `not_empty` до любых изменений. Режим несовместим с `commitEvery`, `existing`
-(кроме `'error'`) и `{ as }`; ошибка любой строки откатывает всё, вместе с индексами и триггерами.
-`letopis import --initial` проводит так весь импорт: одной транзакцией, без `--update` и `--commit-every`. WAL пишется
-и здесь (без него — только при `wal_level = minimal`), но индексы строятся один раз, и его почти втрое меньше; после
+Пустая — значит, кроме строк системных классов (описания классов, аккаунты, членства, ресурсы, правила), в схеме
+ничего нет; иначе — `not_empty` до любых изменений. Режим несовместим с `commitEvery`, `existing` (кроме `'error'`) и
+`{ as }`; ошибка любой строки откатывает всё, вместе с индексами и триггерами. WAL пишется и здесь (без него — только при `wal_level = minimal`), но индексы строятся один раз, и его почти втрое меньше; после
 `FREEZE` первое чтение и первая очистка таблицу не переписывают.
 
 ### Командная строка
 
 ```sh
 npx letopis load shops.ndjson products.ndjson --dsn "$ADMIN" --schema v2.shop --token "$TOKEN" \
-  [--class Product] [--duplicates first] [--existing skip] [--commit-every 100000] [--verify]
+  [--class Product] [--duplicates first] [--existing skip] [--commit-every 100000]
 # shops.ndjson:    {"$class":"Shop","name":"Юг"}
 # products.ndjson: {"$class":"Product","sku":"Y-1","title":"Ваза","price":800,"Shop":{"$key":["Юг"]}}
 ```
@@ -1327,8 +1498,7 @@ npx letopis load shops.ndjson products.ndjson --dsn "$ADMIN" --schema v2.shop --
 `issues`), `total` — сколько нарушений найдено, `truncated` — список обрезан, `limit` — предел списка (100),
 `complete` — проверки, нашедшие нарушения, прошли все строки. Коды строк: коды проверок базы, а также `duplicate`
 (повтор id), `exists` (объект уже есть), `deleted` (объект с этим id жил раньше) и `class_not_loadable` (строки
-`Class` загрузчик не принимает: классы задаёт `syncModels`). Строки производных классов и ссылки на них загрузчик
-отклоняет с кодом `derived_class`: такие строки пишет только проектор.
+`Class` загрузчик не принимает: классы задаёт `syncModels`).
 
 Нарушения ищутся поэтапно: разбор строк (классы, id, повторы), права на классы (`load({ as })`), данные и концы
 пачками, в конце порции — цели вне загрузки, владельцы и арендатор. Загрузка отменяется после первого этапа,
@@ -1336,7 +1506,7 @@ npx letopis load shops.ndjson products.ndjson --dsn "$ADMIN" --schema v2.shop --
 первая, что на неё ссылается). «(и ещё N)» в тексте ошибки — точное число остальных нарушений. Если проверены не все
 строки, `complete` — `false`, а текст говорит «(и ещё не меньше N: причины)» или, если найдено одно нарушение,
 «(возможно, не единственная: причины)». Причины: следующие порции `commitEvery` не проверялись; условия ACL
-следующих пачек не проверялись (`load({ as })`); проверка базы (`verify: true`) называет не больше 100 строк.
+следующих пачек не проверялись (`load({ as })`); проверка базы (шаблоны `pattern`) называет не больше 100 строк.
 
 ## 10. Пользователи, вход и права
 
@@ -1359,6 +1529,15 @@ npx letopis load shops.ndjson products.ndjson --dsn "$ADMIN" --schema v2.shop --
 ключи других сервисов, System и системных администраторов выпускает и отзывает только системный администратор;
 новый ключ сервиса регистрирует и `up({ serviceKey })`.
 
+Ключ установки `up()` выпускает сам: `lts_` и 64 шестнадцатеричных знака в нижнем регистре. Отдаёт он его в
+`r.serviceKey` один раз — при первой установке или на накате, когда в схеме не осталось ни одного неотозванного ключа
+API; иначе `r.serviceKey` — `null`. База хранит только sha256 ключа, поэтому показать его снова нельзя: сохраните ключ
+в хранилище секретов. Чтобы ключ был известен заранее (например, из переменной окружения), передайте свой:
+`up({ serviceKey: process.env.LETOPIS_SERVICE_KEY })`. Формат — `lts_` и 32–128 шестнадцатеричных знаков в нижнем
+регистре, `/^lts_[0-9a-f]{32,128}$/`, иначе `invalid_data`; подходит `'lts_' + randomBytes(32).toString('hex')` из
+`node:crypto`. Если такого неотозванного ключа ещё нет, `up()` регистрирует его за сервисом установки и возвращает в
+`r.serviceKey`, иначе там `null`. Сервис входит по ключу: `connect({ dsn: APP, schema, apiKey })`.
+
 Ключей может быть несколько. Сессия, открытая ключом, помнит его, и отзыв ключа гасит только его сессии: подключения
 по другим ключам работают дальше. Поэтому ротация идёт без простоя: сервис выпускает себе новый ключ
 (`issueApiKey({ account: <id сервиса> })`), переводит процессы на него и отзывает старый (`revokeCredential(id)`).
@@ -1385,7 +1564,7 @@ const failed = await svc.auth.verifyPassword({ identifier: 'boris@lutik.ru', pas
 
 - Пароль хранится хэшем scrypt; проверяет его сервис, время ответа для несуществующего логина выровнено.
 - Идентификатор сравнивается без учёта регистра: `Anna@Shop.ru` и `anna@shop.ru` — один вход.
-- Смена пароля гасит остальные сессии аккаунта (`keepCurrent` — оставить текущую).
+- Смена пароля гасит остальные сессии аккаунта; текущая остаётся, `keepCurrent: false` гасит и её.
 - По умолчанию вход — только по подтверждённому креду, иначе `null`; `requireConfirmed: false` пускает и по
   неподтверждённому. Подтверждает кред сервис: `confirmed: true` в `setPassword` или `setFlags`.
 - Второй фактор — опция `totp`: `verifyPassword({ identifier, password, totp })` после верного пароля проверяет код
@@ -1430,7 +1609,7 @@ const viaTelegram = await svc.auth.lookup({ kind: 'TELEGRAM', identifier: '10050
 сессия от сервиса не в счёт) и не подтверждает их сам. При включённом TOTP база требует сессию с пройденным TOTP:
 её выдают `verifyPassword` и `lookup` с опцией `totp`. Если идентификатор занят, привязка отвечает тем же
 `acl_denied`, что и без недавнего входа. Но пользователь с недавним входом по такому отказу поймёт, что
-идентификатор занят ([раздел 18](#18-ограничения)).
+идентификатор занят ([раздел 17](#17-ограничения)).
 
 ### Сессии
 
@@ -1447,12 +1626,36 @@ await boris.close()
 Токен — 256 случайных бит; база хранит только его sha256. Срок по умолчанию — 7 суток. `refresh()` продлевает
 текущую сессию: новый срок отсчитывается от текущего момента, но не больше срока, выданного при входе; возвращает
 он новое время истечения. `connect()` продлевает сессию сам раз в минуту работы (`refreshSession`), поэтому сессия,
-которой пользуются, не истекает: срок — это время простоя. `revoke()` — выход, `revokeAll()` — выход везде.
+которой пользуются, не истекает: срок — это время простоя. `revoke()` — выход: гасит сессию этого подключения;
+`revoke(token)` — выход пользователя по токену его сессии (ниже); `revokeAll(account?)` — выход везде, то есть все
+сессии **одного** аккаунта. Общего вызова «погасить все сессии установки» нет: при утечке или после восстановления
+копии на чужом стенде — остановить процессы приложения и от суперпользователя или роли-владельца выполнить
+`update "v2.имя".secret set deleted_at = clock_timestamp() where kind = 'SESSION' and deleted_at is null` (ключи API —
+`kind in ('APIKEY', 'KEYSECRET')` или `revokeCredential(id)`); сигнала этот запрос не шлёт, поэтому процессы
+перезапускают.
 Сессии гаснут при отключении аккаунта, смене пароля, удалении креда и удалении аккаунта. Удаление креда гасит
 остальные сессии аккаунта, а отзыв ключа API или пары «ключ + секрет» — только сессии, открытые этим ключом (и
 старые сессии того же вида входа без отметки ключа); текущая сессия остаётся, если не передать
 `keepCurrent: false`.
 
+`apiKey`, `service` или `token`, переданные со значением `null`, пустой строкой или не строкой, `connect()` отклоняет
+сразу — `invalid_data` (`api.connect_empty_credential`); `undefined` значит «опции нет» — подключение без сессии, и
+отказ `no_session` придёт на первом вызове. Поэтому ключ из переменной окружения проверяйте до `connect()`.
+
+`connect({ token })` с токеном, который уже не даёт сессии (погашен `revoke`, истёк, неверен), подключения не создаёт:
+его промис отклоняется с `no_session` (`api.token_not_active`, «нет действующей сессии: токен погашен, истёк или
+неверен»), пул закрывается. Пользователь входит заново.
+
+Подключение с постоянным токеном (`connect({ token })`), которым не пользовались дольше срока сессии, остаётся без
+сессии: истёкшую сессию продление не возвращает, а новый токен подключение само не берёт. После простоя дольше минуты
+подключение до операции продлевает сессию и узнаёт, жива ли она: истёкшая — `no_session` на любую операцию, и
+чтение не идёт как анонимное с пустым ответом (с `refreshSession: false` проверки нет). Токен выдают заново —
+повтором `createTenant()` (для существующих арендатора и пользователя повтор только выдаёт новую сессию) или
+`svc.auth.sessionFor()` — и открывают с ним новое подключение. Подключение по ключу (`connect({ apiKey })`, ключ
+сервиса) так не застревает: истёкшую сессию оно заменяет само — обменивает ключ заново, с тем же рабочим арендатором,
+что выбрал `auth.switch()`, и повторяет операцию. Процессу, которому сессия пользователя нужна для редких операций,
+проще брать её на одну операцию: `sessionFor()`, подключение с её токеном, работа, `revoke()` и `close()`.
+
 Сервис, у которого есть токен пользователя (например, в cookie), узнаёт о сессии через `svc.auth.session(token)`:
 подключение по этому токену не открывается, срок сессии не продлевается. Ответ — чья сессия (`account`), в каком
 арендаторе она работает (`tenant`: выбранный `auth.switch()` или собственный арендатор аккаунта), цело ли там членство
@@ -1462,6 +1665,18 @@ await boris.close()
 чтение по погашенной сессии ошибки не даёт, ответы просто пустые. Вызывает метод сервис или системный администратор
 (право `auth.session`); пользователю отвечают `acl_denied`.
 
+Выход в веб-сервисе — `svc.auth.revoke(token)` с токеном из cookie: сервис гасит сессию пользователя, не подключаясь
+по ней. Ответ — `true`, если сессия погашена, и `false`, если токен неверный, сессия уже погашена или истекла (причина
+не различается). Право то же — `auth.session`, без него `acl_denied`. Погашенная сессия шлёт сигнал `session:…`, и
+процессы сбрасывают кэш её ответов. `svc.auth.revoke()` без аргумента погасил бы сессию самого сервиса:
+
+```ts
+// POST /logout — токен пользователя в cookie
+const token = req.cookies.session
+if (token) await svc.auth.revoke(token)   // true — вышел; false — сессии уже не было
+res.clearCookie('session')
+```
+
 ### Работа в другом арендаторе
 
 Сервис действует от имени пользователя через `svc.as(account, { tenant, owner })`. База проверяет право сервиса
@@ -1474,10 +1689,69 @@ await boris.close()
 
 <!-- run: guide -->
 ```ts
-const mine = await anna.auth.tenants()     // [{ tenant, roles }]: собственный арендатор и магазин по членству
+const mine = await anna.auth.tenants()     // [{ tenant, roles, name, personal }]: собственный арендатор и магазин
 await anna.auth.switch(SHOP)               // арендатор сессии — магазин
 ```
 
+`auth.tenants()` отдаёт арендаторов аккаунта сессии: `{ tenant, roles, name, personal }`. Первым идёт собственный
+арендатор пользователя — `tenant` равен id его аккаунта, `roles: ['owner']`, `personal: true`, `name` — имя
+пользователя. За ним — арендаторы по членству (`personal: false`) с ролями членства, по id. `name` — имя аккаунта
+арендатора: то, что передали в `createTenant({ name })` или `up({ tenant: { name } })`; у аккаунта без имени — `null`.
+Нужны только арендаторы по членству — `filter((t) => !t.personal)`.
+
+Сервис узнаёт арендаторов пользователя, не открывая подключения по его токену: от имени пользователя без `tenant`
+(`svc.as(account)` работает в его личном арендаторе) — тот же `auth.tenants()`. Так после входа выбирают, куда
+пустить пользователя:
+
+```ts
+const ok = await svc.auth.verifyPassword({ identifier, password })
+if (!ok) return 'неверный логин или пароль'
+const shops = (await (await svc.as(ok.account)).auth.tenants()).filter((t) => !t.personal)
+if (!shops.length) return 'вы не состоите ни в одном магазине'
+// несколько — список shops.map((t) => t.name) пользователю на выбор; выбранный — в его сессии:
+const work = await svc.as(ok.account, { tenant: shops[0].tenant })
+```
+
+Сессия, открытая входом (`verifyPassword`, `sessionFor`), `svc.as(account)` без `tenant` и
+`connect({ token })` до `auth.switch()` работают в **собственном** арендаторе пользователя. Классы, которые
+`syncModels` записал в арендатор магазина, там не видны: шаг по такому классу — `invalid_class: класс или роль …
+не найдены`. Поэтому член арендатора работает так: сервис — `svc.as(login.account, { tenant: SHOP })`, своё
+подключение по токену — `auth.switch(SHOP)`; `db.tenant` показывает, где сессия. `auth.switch()` меняет арендатора
+самой сессии: токен и дальше работает в выбранном арендаторе. Нет членства — `tenant_denied`.
+
+Название арендатора пользователь получает из `auth.tenants()` (`name`); саму строку `Account` арендатора он не
+видит — видна только своя (`db.Account(SHOP).first()` у члена магазина — `null`). Название, которое меняется в
+интерфейсе приложения, храните в данных арендатора — например, хабом `Shop` с полем `name`.
+
+### Веб-сервис: одно подключение и безопасность
+
+- **Одно подключение сервиса на процесс.** Сервис держит одно подключение по ключу (`connect({ apiKey })`) и на каждый
+  запрос берёт фасад `svc.as(account, { tenant })` — тот же пул. `connect({ token })` на каждый вход открывает
+  отдельный пул (`max`, по умолчанию 10 соединений) на пользователя: несколько десятков входов исчерпают соединения
+  PostgreSQL. `close()` у фасада `as()` ничего не делает; закрывают `svc` при остановке процесса.
+- **Арендатор — только из серверной сессии.** В начале запроса — `svc.auth.session(token)` по токену из cookie
+  (`null` — не вошёл: 401, никаких данных); арендатор — из конфигурации сервера или из выбора, сохранённого на сервере
+  при входе, и никогда из параметра запроса (`?club=`, тело, заголовок). Нет членства — `svc.as()` отвечает
+  `tenant_denied` (403).
+- **Экранирование.** Данные из базы, вставленные в HTML, экранируют все пять символов `& < > " '` (или пишут через
+  `textContent`), а обработчики событий (`onclick="…"`) из данных не строят: id — в атрибуте `data-*`, обработчик —
+  `addEventListener`.
+- **Ключ сервиса** выдаётся один раз ([«Сервис и ключи API»](#сервис-и-ключи-api)): храните его в файле с правами
+  только владельца (`chmod 600`) или в хранилище секретов, файл — в `.gitignore`; в репозиторий и клиенту он не
+  попадает. Свой ключ заранее — `up({ serviceKey })`.
+
+```ts
+const svc = await connect({ dsn: APP, schema: 'v2.shop',
+  apiKey: readFileSync('/etc/shop/service.key', 'utf8').trim() })   // один раз на процесс
+async function userDb(token: string | undefined) {                   // в начале каждого запроса
+  const s = token ? await svc.auth.session(token) : null
+  if (!s) return null                                                 // 401
+  return svc.as(s.account, { tenant: SHOP })                          // арендатор — с сервера; нет членства — tenant_denied
+}
+const esc = (v: string) => v.replace(/[&<>"']/g, (c) =>
+  ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!)
+```
+
 ### Права
 
 Права включены всегда и по умолчанию запрещают. Правило связывает группу с объектом:
@@ -1496,28 +1770,21 @@ await anna.auth.switch(SHOP)               // арендатор сессии
 видны, правка — пусто или `acl_denied`.
 
 Маска класса в объекте `READ`, `WRITE` или `DELETE` совпадает и с потомками класса — по именам предков и их алиасам.
-Поэтому правка класса, которая меняет `parent`, `alias` или `derivedBy`, требует права `READ`, `WRITE` и `DELETE` без
+Поэтому правка класса, которая меняет `parent` или `alias`, требует права `READ`, `WRITE` и `DELETE` без
 условий на все строки класса и каждого его потомка, иначе `acl_denied`: одного права `WRITE` на `Class` мало, чтобы
 подставить строки класса под чужие правила. Алиас не совпадает с именем другого класса (в том числе `Class` и
 системных) и с чужим алиасом арендатора и System, а имя нового класса — с чужим алиасом: иначе правило, написанное
 для одного класса, действовало бы и на строки другого. Нарушение — `invalid_class`.
 
 По тем же именам правила находят и старые версии строк в журнале. Поэтому класс удаляется, только когда у него нет
-строк, потомков и истории строк: историю удалённых строк сначала стирает `purge()`. Для класса System не в счёт
-строки, потомки и история арендатора, у которого есть свой класс с тем же именем: они относятся к его классу. Класс,
-удалённый с историей раньше, создаётся заново только с прежними `parent`, `alias`, `derivedBy` и `history` — иначе
-`invalid_class`: старые версии его строк попали бы под чужие правила или другое прореживание. Правила находят старые
-версии и по алиасам предков. Поэтому, пока удалённые потомки класса хранят историю строк, класс не меняет алиас
-(`invalid_class`), а удалённым создаётся заново только с прежним описанием. Если журнал хранит строки класса с этим
-именем, но не его надгробие (например, строки класса System, удалённого в 1.1), класс с этим именем не создаётся, пока
-историю не сотрёт `purge()`.
-
-Производный класс (`derivedBy`) заводит, меняет и удаляет только администратор: администраторское подключение или
-аккаунт с правом System `letopis.projector` (у системного администратора оно есть по маске `letopis.*`). Проектор
-пишет в такой класс итоги по всем строкам источников арендатора, без прав чтения, поэтому пользователь, заведя его
-сам, читал бы итоги по строкам, которые ему читать запрещено. Класс, у которого есть производные потомки, тоже
-правит только администратор: правка предка меняет описание потомка (поля, ключ, `history`). Пометку `aggregatedBy`
-(класс стал источником агрегата) база ставит и производному классу сама: полей и ключа она не меняет.
+строк, потомков и истории строк; историю строк не стереть, и класс, который придётся удалять, заводят с
+`history: false`. Для класса System не в счёт строки, потомки и история арендатора, у которого есть свой класс с тем
+же именем: они относятся к его классу. Класс, удалённый с историей раньше, создаётся заново только с прежними
+`parent`, `alias` и `history` — иначе `invalid_class`: старые версии его строк попали бы под чужие правила. Правила
+находят старые версии и по алиасам предков. Поэтому, пока удалённые потомки класса хранят историю строк, класс не
+меняет алиас (`invalid_class`), а удалённым создаётся заново только с прежним описанием. Если журнал хранит строки
+класса с этим именем, но не его надгробие (например, строку класса удалили мимо триггеров от роли владельца), класс с этим именем не
+создаётся.
 
 ### Выдать право
 
@@ -1525,17 +1792,14 @@ await anna.auth.switch(SHOP)               // арендатор сессии
 
 <!-- run: guide -->
 ```ts
-const pg2 = postgres(ADMIN)
-const OLEG = (await createTenant(pg2, r.schema, {          // тот же магазин: создаётся только пользователь
+const admin2 = postgres(ADMIN)
+const OLEG = (await createTenant(admin2, r.schema, {          // тот же магазин: создаётся только пользователь
   name: 'Ромашка', user: { name: 'Олег', login: 'oleg@shop.ru', password: 'Олег-2026!' } })).user!
-await pg2.end()
-await db.member(db.idOf('member', { User: OLEG, Tenant: SHOP })).update({ roles: ['staff'] }).rows()
+await admin2.end()
+await db.acl.roles(OLEG, ['staff'])                         // роли Олега в текущем арендаторе (строка member)
 
-const [staff] = await db.Resource().create({ alias: 'staff:ACCOUNT', category: 'ACCOUNT', pattern: { roles: '{staff}' } }).rows()
-const [delProduct] = await db.Resource().create({ alias: 'product:DELETE', category: 'DELETE', pattern: { class: 'Product' } }).rows()
-await db.rule().create({ permission: 'deny', weight: 50 }).Group.set(staff).Object.set(delProduct).rows()   // сильнее «можно всё» (10)
-const [reports] = await db.Resource().create({ alias: 'reports:API', category: 'API', pattern: { endpoint: 'shop.reports.*' } }).rows()
-await db.rule().create({ permission: 'allow', weight: 50 }).Group.set(staff).Object.set(reports).rows()
+await db.acl.deny({ role: 'staff', delete: 'Product' })     // вес 50 — сильнее «можно всё» (10)
+await db.acl.grant({ role: 'staff', api: 'shop.reports.*' })
 
 const asOleg = await svc.as(OLEG, { tenant: SHOP })
 const canDelete = await asOleg.acl.checkData('Product', 'DELETE')   // { allow: false }
@@ -1543,10 +1807,28 @@ const canRead = await asOleg.acl.checkData('Product', 'READ')       // { allow:
 const canReport = await asOleg.acl.check('shop.reports.daily')      // { allow: true, rule: { weight: 50, … } }
 ```
 
+- `db.acl.grant` и `db.acl.deny` принимают, кому правило, — роль (`role`) или все аккаунты арендатора, кроме анонимных
+  и теневых (`everyone: true`; ровно одно из двух), — и цели: `read`, `write`, `delete` — класс (с потомками), `'*'` —
+  все классы или класс с условием на строки (`{ class: 'Ticket', owner: '$actor' }`); `api` — маска эндпоинта;
+  списком — несколько. На каждую операцию и цель — одно правило с весом `weight` (по умолчанию 50, от 1 до 999). Под
+  капотом — те же строки `Resource` (`role:staff:ACCOUNT`, `everyone:ACCOUNT`, `class:Product:DELETE`,
+  `api:shop.reports.*:API`) и `rule` текущего
+  арендатора, ключ правила — пара группа и объект: повтор ничего не меняет, а `grant` после `deny` той же роли и цели
+  заменяет запрет разрешением. Внутри `db.begin()` — в её транзакции. Писать правила может тот, у кого есть `WRITE` на
+  `Resource` и `rule` (после `createTenant` — любой участник по правилу «можно всё»; закрыть — `deny` с
+  `write: ['Resource', 'rule', 'member']`). Неверный вызов — `invalid_data` до записи.
+- `db.acl.revoke({ role, … })` и `db.acl.revoke({ everyone: true, … })` снимают правила роли или всех аккаунтов —
+  разрешения и запреты — для этих целей и отвечают числом снятых; для всех аккаунтов — и «можно всё» от
+  `createTenant` ([Права только по ролям](#права-только-по-ролям)).
+  `db.acl.roles(аккаунт)` — роли в текущем арендаторе (`null` — не член), `db.acl.roles(аккаунт, ['staff'])` — заменить
+  их (членство заводится), `db.acl.roles(аккаунт, null)` — снять членство. `db.acl.list()` — правила арендатора
+  `{ id, role, everyone, group, op, target, condition, permission, weight, enabled }`, свои и «можно всё» от
+  `createTenant` (`everyone: true`, `role: null`); `enabled: false` — правило выключено полем `enabled` строки `rule`,
+  база его не применяет. На администраторском подключении — тоже только правила арендатора сессии.
 - `acl.check(эндпоинт)` → `{ allow, rule, code, message }`: свой отказ эндпоинта задают поля `code` и `message`
   запрещающего правила.
 - `acl.checkData(класс, 'READ' | 'WRITE' | 'DELETE')` → `{ allow, filter }`: `filter` — условие на строки.
-- Права пересчитываются базой сами. Убрать право — удалить правило: `db.rule(id).delete({ confirm: true })`.
+- Права пересчитываются базой сами. Правила можно писать и цепочками `Resource` и `rule` напрямую — поля ниже.
 - Библиотека один раз берёт у базы подписанный план прав актора — пропуск прав — и передаёт его в каждой
   транзакции, поэтому проверка прав стоит десятки микросекунд. Сырой SQL без пропуска платит 0,3–1,3 мс на запрос.
 - На вопрос «у кого был доступ на дату» отвечает срез `asOf` по классам `rule`, `member` и `Resource`.
@@ -1558,14 +1840,57 @@ const canReport = await asOleg.acl.check('shop.reports.daily')      // { allow:
   `READ`, `WRITE`, `DELETE`) и `pattern` — маска. У группы маска `categories` или `roles` — только строка: `'{staff}'`,
   `'{a,b}'`, отрицание — `'!{a}'`. У объекта — `endpoint` или `class` (тоже только строки) и условия на колонки.
   **Маску не строкой (например, массив `['staff']`, число или `null`) база отклоняет** с `invalid_data` — при записи
-  библиотекой, сырым SQL и загрузчиком. Старые строки с такой маской (записанные до этой проверки или в обход
-  неё) разрешений не дают, а запрет по ним действует на всех: по группе — на все аккаунты, по маске `class` — на все
-  классы (маска `endpoint` не строкой, как и прежде, не совпадает ни с одним эндпоинтом). Проверку при записи несёт
-  описание класса `Resource`: оно приходит со свежей установкой и после `reset({ all })`; в существующей схеме
-  исправленное сопоставление действует после повторного `up()`;
+  библиотекой, сырым SQL и загрузчиком; проверку несёт описание класса `Resource`. Строка с такой маской, записанная
+  в обход проверки (от роли владельца), разрешений не даёт, а запрет по ней действует на всех: по группе — на все
+  аккаунты, по маске `class` — на все классы (маска `endpoint` не строкой не совпадает ни с одним эндпоинтом);
 - `rule` — концы `Group` и `Object` (строки `Resource`), поля `permission` (`allow` или `deny`), `weight`, а для
   своего отказа эндпоинта — `code` и `message`.
 
+### Права только по ролям
+
+`createTenant` и `up({ tenant })` дают арендатору правило «аутентифицированным можно всё» (вес 10). Запреты ролей с
+весом больше сужают права, но всё, что запретами не закрыто, остаётся разрешено любому участнику. Чтобы права решали
+только роли, снимите это правило после настройки или не заводите его вовсе.
+
+Снять после настройки. «Можно всё» — три правила `READ`, `WRITE` и `DELETE` для всех аккаунтов арендатора (группа
+System `authenticated:ACCOUNT`) на все классы; `db.acl.list()` показывает их с `everyone: true`, `role: null` и
+`target: '*'`, а снимает их `db.acl.revoke({ everyone: true, read: '*', write: '*', delete: '*' })`. Права ролям
+выдайте раньше, пока правило действует: после снятия у участника остаются только права его ролей. Если права и
+дальше правит приложение, дайте какой-то роли права и на строки прав (`Resource`, `rule`, `member`), иначе их запишет
+только администраторское подключение.
+
+```ts
+await db.acl.grant({ role: 'manager', read: 'Product', write: 'Product', delete: 'Product' })
+await db.acl.grant({ role: 'staff', read: 'Product' })
+await db.acl.grant({ role: 'manager', read: ['Resource', 'rule', 'member'],      // правит права и дальше
+  write: ['Resource', 'rule', 'member'], delete: ['rule', 'member'] })
+await db.acl.revoke({ everyone: true, read: '*', write: '*', delete: '*' })     // «можно всё» снято: 3
+```
+
+Вернуть его — `db.acl.grant({ everyone: true, read: '*', write: '*', delete: '*', weight: 10 })`: правила для всех
+аккаунтов обёртка пишет своей группой `everyone:ACCOUNT`. Так же — право всем аккаунтам на отдельный класс:
+`db.acl.grant({ everyone: true, read: 'Catalog' })`.
+
+Не заводить. `createTenant(admin, schema, { name, grantAll: false, user })` и `up({ tenant: { name, grantAll: false, user
+} })` заводят арендатора без правил. У его участников, в том числе у первого пользователя, прав нет — ни на данные, ни
+на запись правил. Классы и правила такого арендатора пишет администраторское подключение с сессией его пользователя:
+RLS на нём не действует, а строки идут в арендатор сессии.
+
+```ts
+const admin = postgres(ADMIN)
+const t = await createTenant(admin, r.schema, { name: 'Склад', grantAll: false,
+  user: { name: 'Ирина', login: 'irina@stock.ru', password: 'Склад-2026!', roles: ['manager'] } })
+await admin.end()
+const adm = await connect({ dsn: ADMIN, schema: r.schema, token: t.token, allowBypassRls: true })
+await syncModels(adm, [Product], { apply: true })
+await adm.acl.grant({ role: 'manager', read: 'Product', write: 'Product', delete: 'Product' })
+await adm.close()
+```
+
+Читать администраторское подключение может строки всех арендаторов, но `adm.acl.list()` и там показывает правила
+арендатора сессии. Видимость целей правила актору сессии база на таком подключении не проверяет (существование,
+арендатор и класс цели — проверяет), поэтому правило пишется и тогда, когда прав у актора ещё нет.
+
 ### Удалить аккаунт
 
 `db.auth.purgeAccount(аккаунт)` удаляет аккаунт и данные его арендатора. Вызывать может системный администратор или
@@ -1573,10 +1898,10 @@ const canReport = await asOleg.acl.check('shop.reports.daily')      // { allow:
 арендаторах переходит этим арендаторам, сессии гаснут, креды удаляются. Владелец может стереть и арендатора, в
 котором сейчас работает: его сессия вернётся в личный арендатор.
 
-Системный администратор может удалить и саму строку аккаунта — `db.Account(id).delete({ confirm: true })` в
-арендаторе System; данные арендатора аккаунта при этом остаются. Любой путь сразу стирает строки аккаунта в `secret`:
-сессии, хэши паролей и ключей, секреты TOTP, внешние учётные записи (внешний ключ `secret.account` с каскадом,
-ревизия 7). Сессии гаснут до этого с сигналом, и процессы сбрасывают кэш ответов этих сессий. Аккаунт System
+Системный администратор может удалить и саму строку аккаунта — по превью, `db.Account(id).delete({ confirm: true,
+expect: превью })`, в арендаторе System; данные арендатора аккаунта при этом остаются. Любой путь сразу стирает строки аккаунта в `secret`:
+сессии, хэши паролей и ключей, секреты TOTP, внешние учётные записи (внешний ключ `secret.account` с каскадом).
+Сессии гаснут до этого с сигналом, и процессы сбрасывают кэш ответов этих сессий. Аккаунт System
 не удаляется (`acl_denied`): ему принадлежат служебные строки установки в `secret`.
 
 ## 11. История и срезы на дату
@@ -1586,22 +1911,32 @@ const canReport = await asOleg.acl.check('shop.reports.daily')      // { allow:
 <!-- run: guide -->
 ```ts
 const versions = await db.Product(kettle).versions()              // все версии: op, rev, author, at, data
-const followed = await db.Product(mug2).versions({ follow: true }) // и через смену id (rekey, reclass)
 ```
 
-У каждой версии — автор, агент, время, номер, вид операции (`create`, `update`, `delete`, `reclass`, `rekey`,
-`restore`, `purge`, `trim`, `reset`) и причина (`reason`). Причину задаёт опция `reason` глагола (`update(patch, { reason })`, `create(data, { reason })`,
+У каждой версии — автор, агент, время, номер, вид операции (`create`, `update`, `delete`, `restore`) и причина
+(`reason`). Причину задаёт опция `reason` глагола (`update(patch, { reason })`, `create(data, { reason })`,
 `delete({ confirm, reason })` и других), для всех операций блока — `db.begin({ reason })` и
 `db.batch(имя, { reason })`; сырой SQL — настройка `letopis.reason` транзакции. Версия удаления — с `$deleted`.
 
-Без `sort()` версии идут по id и номеру версии (с `follow` — по времени). `sort()` задаёт порядок и версиям, а
-`limit()` ограничивает их в самом запросе: `db.Product(kettle).sort('at', 'desc').limit(5).versions()` — пять
+Версия — строка той же формы, что строка ответа ([«Строка ответа»](#строка-ответа)), но со снимком на свою версию:
+`rev` — номер версии, `op` — вид операции, `links` и `data` — концы и поля после этой операции (у версии удаления —
+последний снимок объекта), `at`, `author`, а если есть — `agent` и `reason`; у версии удаления ещё `$deleted: true`.
+Без `sort()` версии идут по id и номеру версии (по возрастанию: первой — `create`). `sort()` задаёт порядок и версиям,
+а `limit()` ограничивает их в самом запросе: `db.Product(kettle).sort('at', 'desc').limit(5).versions()` — пять
 последних версий, новые первыми.
 
-`follow: true` отдаёт историю объекта на всех его id: до переноса — версии прежнего id, после — нового. Объект,
-который потом завели на прежнем id (тот же ключ после `rekey`), — другой, и его версий в этой истории нет; его
-собственная история с `follow` начинается с его создания. Так же идут `diff({ follow: true })` и `blame()`. Без
-`follow` `versions()` отдаёт все версии id, чьи бы они ни были.
+Шаг с явными id находит и удалённые объекты: `db.Product(id).versions()` отдаёт историю удалённого товара вместе с
+версией удаления, `withDeleted()` для этого не нужен. Шаг без id (`db.Product().versions()`, переход по пути) отдаёт
+версии **только живых** объектов, с удалёнными — `withDeleted()` этого шага. Так, строки удалённого заказа ушли
+каскадом, и `db.Product(p).line().versions()` их не покажет, а `db.Product(p).line().withDeleted().versions()` или
+`versions()` по id строки — покажут: концы — `links` версии, удаление — версия удаления, причина — `reason`.
+
+`versions()` — терминал: отдаёт промис строк версий. Модификаторы ставят до него
+(`db.Product(kettle).sort('at', 'desc').limit(5).versions()`), а метод цепочки у его результата —
+`versions().rows()`, `.sort()`, `.limit()` — `invalid_query` (`api.versions_terminal`).
+
+Журнал хранит каждую версию: прореживания и обрезки истории нет. Классу, чья история не нужна, — `history: false`
+([«Настройки класса»](#настройки-класса)).
 
 ### Срез на дату
 
@@ -1624,115 +1959,27 @@ const assortment = await db.Shop(shop).Product().asOf(createdAt).rows()
 const withGone = await db.Customer().withDeleted().rows()   // живые и удалённые; у удалённых $deleted: true
 ```
 
-### Политика хранения
-
-Без политики журнал хранит каждую версию. Политика задаёт, сколько хранить старые версии и с какой подробностью:
-
-```ts
-history: { all: '1 day', daily: '1 week', weekly: '1 month', monthly: '1 year', yearly: 'forever', tz: 'Europe/Moscow' }
-```
-
-Это значит: все версии за последние сутки; за неделю — по одной на день; за месяц — по одной на неделю; за год —
-по одной на месяц; старше — по одной на год, бессрочно. От периода остаётся его последняя версия. Неделя
-начинается с понедельника, границы периодов — в поясе `tz` (по умолчанию UTC).
-
-- Политику задают у класса (потомки наследуют) или для всех классов без своей — `up({ history })`.
-- Если у последнего яруса задан срок, а не `'forever'`, история старше срока удаляется: `{ all: '30 days' }`.
-- Пока история объекта жива, не удаляются текущая версия, версия 1 и версии особых видов (`create`, `delete`,
-  `reclass`, `rekey`, `restore`, `purge`, `reset`, `trim`). Если надгробие удалённого объекта старше последнего яруса
-  со сроком, его история стирается целиком. История системных классов не прореживается.
-- Прореживает `maintain()` пачками по 10 000 версий ([раздел 13](#13-эксплуатация)).
-- В прореженной части срез показывает последнюю сохранённую версию до момента, то есть его точность равна
-  периоду яруса. Подписчик, отставший дольше яруса `all`, получает `cursor_expired`.
-
-### Что изменилось и кто: `diff` и `blame`
-
-```ts
-const [d] = await db.Order(id).diff()                       // предыдущая версия → последняя
-await db.Order(id).diff({ from: 3, to: 7 })                 // по номерам версий
-await db.Order(id).diff({ from: '2026-10-01' })             // состояние на момент → последнее
-await db.Order(id).diff({ follow: true })                   // через смену id (reclass, rekey)
-const [b] = await db.Order(id).blame()                      // каждое поле последней версии
-await db.Order(id).blame({ at: '2026-10-01', limit: 200 })  // версия на момент; просмотреть 200 версий
-```
-
-Оба терминала отдают массив — по элементу на объект шага. Так выглядят ответы для чайника, которому снизили цену с
-причиной:
-
-```ts
-import type { BlameResult, DiffResult } from 'letopis'
-
-// db.Product(kettle).blame(): цену изменила версия 2, остальные листья — с создания (версия 1)
-const blamed: BlameResult = {
-  id: '6f1c…', class: 'Product', rev: 2, complete: true,
-  fields: [                                     // по порядку пути
-    { path: ['class'], rev: 1, at: '2026-10-27T09:15:02.118204+00:00', author: '<id Анны>', agent: '<id сервиса>',
-      op: 'create', exact: true },
-    { path: ['data', 'price'], rev: 2, at: '2026-10-27T09:20:41.502617+00:00', author: '<id Анны>', agent: '<id сервиса>',
-      op: 'update', reason: 'скидка к акции', exact: true },
-    // ['data', 'sku'], ['data', 'title'], ['links', 'Shop'], ['owner'] — тоже версия 1, как ['class']
-  ],
-}
-// db.Product(kettle).diff(): предыдущая версия → последняя
-const diffed: DiffResult = {
-  id: '6f1c…', class: 'Product',
-  from: { rev: 1, at: '2026-10-27T09:15:02.118204+00:00' },
-  to: { rev: 2, at: '2026-10-27T09:20:41.502617+00:00' },
-  changes: [{ path: ['data', 'price'], kind: 'changed', before: 2500, after: 2000 }],
-}
-```
-
-`agent` здесь — сервис, который пишет от имени Анны (`db = await svc.as(…)`); у записи без имперсонации его нет.
-
-- `diff()` — массив `DiffResult`: `{ id, class, from, to, changes }`. `from` и `to` — сравниваемые версии
-  `{ rev, at }`. В них есть `id`, если версия принадлежит другому id (`follow: true` через `reclass` или `rekey`), а у
-  `to` — `deleted: true`, если на этот момент объект удалён; тогда `changes` пуст. `from` равен `null`, если объекта
-  тогда ещё не было: все пути — `added`. Если версии нет вовсе, `class` и `to` тоже `null`.
-- Изменение `DiffChange` — `{ path, kind, before, after }`. `path` — массив сегментов, а не строка с точками; первый
-  сегмент — раздел строки: `data`, `links`, `tags`, `owner`, `class`. `kind` — `added` (значения не было), `removed`
-  (не стало) или `changed`. Пустое значение опускается: у `added` нет `before`, у `removed` — `after`. Объекты данных
-  сравниваются по ключам, массивы — целиком. Множественный конец и теги — множества: по изменению на каждый id или
-  тег, путь — `['links', роль]` или `['tags']`, а сам id или тег — в `before` или `after`.
-- `blame()` — массив `BlameResult`: `{ id, class, rev, complete, fields }` и `deleted: true`, если эта версия —
-  надгробие. Объект без версий на этот момент элемента не даёт. `fields` — массив `BlameField`, по элементу на лист
-  версии, упорядоченный по пути: `{ path, rev, at, author, op, exact }` и, если есть, `agent`, `reason`, `id`. Лист —
-  скаляр или массив в данных, пустой объект, роль одиночного конца, каждый id множественного конца
-  (`['links', роль, id]`), каждый тег (`['tags', тег]`), `owner` и `class`. `rev`, `at`, `author`, `agent`, `op` и
-  `reason` — от версии, которая последней изменила лист. Пустые `agent` и `reason` опускаются; `id` есть, только если
-  это версия прежнего id (история прошла через `reclass` или `rekey`). Версии другого объекта на том же id — того,
-  что жил там до переноса или заведён после, — `blame()` не смотрит.
-- `exact: false` — между текущей версией и найденной есть пропуски (история прорежена, обрезана или часть версий не
-  видна): лист мог менять и выпавшая версия. `complete: true` — история просмотрена целиком и без пропусков; по
-  умолчанию просматривается не больше 1000 последних версий.
-- Считает база с правами вызывающего: сырой SQL получает то же — `select "v2.shop".blame('<id>')`,
-  `select "v2.shop".diff_versions('<id>')`.
-- Колонка журнала `changed` (пути изменения версии, по ним `blame` работает быстро) приложению не выдана: пути
-  описывают разницу с предыдущей версией, а её читатель может не видеть. Поэтому `select * from log` от приложения
-  не работает — колонки перечисляются явно; `blame` берёт пути функцией базы, только когда видны обе версии.
-
-### Обрезка истории
-
-<!-- run: guide -->
-```ts
-const trimmed = await db.trimHistory(kettle, new Date())     // стереть версии чайника до этого момента
-```
-
-`db.trimHistory(цель, момент)` сразу стирает историю до момента: класса с потомками (по имени), id, списка id или
-строк. Это средний шаг «права на забвение»: `anonymize` → обрезка истории → удаление и `purge`. На месте версии 1
-остаётся запись `trim` с её временем, поэтому срез знает, когда объект появился.
+`withDeleted()` — модификатор своего шага, как `exact()`: удалённые находит шаг, после которого он стоит, а шаги без
+него идут по живым строкам. Удалённый объект приходит надгробием — своей последней версией, версией удаления, — с
+`$deleted: true`.
 
-### Проверка целостности
-
-<!-- run: guide -->
-```ts
-const audit = await adm.verify({ data: true })     // { ok, issues, anchor }
-```
-
-`verify()` пересчитывает цепочки хэшей всех версий и возвращает якорь — хэш всех голов цепочек. Храните якорь вне
-базы: подмену последних версий выдаст его расхождение. `{ data: true }` вдобавок перепроверяет данные, концы,
-арендаторов, владельцев и id всех строк. Вызывать может системный администратор или администраторское подключение;
-из командной строки — `letopis verify [--data]` (код выхода 1 при находках). Законные разрывы — записи `trim` и
-`purge`, прореживание и `reset` — ошибкой не считаются.
+| Цепочка | Что находит |
+|---|---|
+| `db.Order(o).line().withDeleted()` | живые и удалённые строки живого заказа |
+| `db.Order(o).withDeleted().line().withDeleted()` | живые и удалённые строки заказа, даже если сам заказ удалён |
+| `db.Order(o).withDeleted().line()` | только **живые** строки (заказ — с удалёнными); выводит предупреждение `api.with_deleted_step` |
+| `db.Order(o).line().Product().withDeleted()` | товары, в том числе удалённые, живых строк живого заказа |
+
+Путь через удалённый узел читают одной цепочкой — `withDeleted()` у каждого шага, который может быть удалён:
+`db.Customer(c).Order().withDeleted().line().withDeleted()` — строки всех заказов клиента, в том числе удалённых. В
+цепочке записи `withDeleted()` — только перед `restore()`: у других глаголов — `invalid_query`. В инструменте MCP
+`letopis_query` опция `withDeleted` относится к последнему шагу.
+
+`withDeleted()` отдаёт по каждому id его последнюю версию. Если id надгробия занял новый объект (`create()` по ключу
+удалённого), шаг находит живой новый объект без `$deleted`, а прежнего надгробия среди строк нет; путь от прежнего
+владельца (`db.Customer(c).withDeleted().Order().withDeleted()`) такой объект не находит, если его последняя версия
+ведёт к другому. Прежнее надгробие видно только в версиях — `db.Order(id).versions()`; вернуть его нельзя: пока
+новый объект жив, `restore({ expect })` — `not_deleted` (`write.restore_id_taken`) ([«Восстановить: `restore`»](#восстановить-restore)).
 
 ## 12. Подписка на изменения и кэш
 
@@ -1755,228 +2002,15 @@ for await (const ev of sub) {             // ev: { cursor, row, id, class, op, r
   запись после него в поток придёт. Пример выше читает с `'start'`.
 - Вызовы `sub.next()` идут по очереди: параллельные получают разные события. Вызов, брошенный по таймауту
   (`Promise.race`), всё равно получит своё событие — держите его обещание и ждите его снова.
-- `classes` — только эти классы с потомками; `pollMs` — запасной опрос (1000 мс). Строка, ушедшая из этих классов
-  сменой класса без смены id, приходит событием удаления в прежнем классе (`op: 'delete'`, `row` — прежняя версия с
-  `$deleted`), даже если новый класс подписчику не виден. Событие приходит, если прежнюю версию подписчик видел.
+- `classes` — только эти классы с потомками; `batch` — событий за один запрос к журналу (500); `pollMs` — запасной
+  опрос (1000 мс).
 - События идут без потерь и повторов, под правами читателя, в порядке номеров транзакций, а внутри транзакции — в
   порядке записи. Это не порядок фиксации: версии одного объекта сверяйте по `rev`.
 - Долгая пишущая транзакция в любой базе кластера задерживает поток: `await sub.lag()` показывает отставание в мс.
-- Курсор старше яруса `all` политики хранения — `cursor_expired`: перечитайте текущее состояние и подпишитесь
-  с `'now'`. Время в курсоре подписки `sub.cursor` — время последнего события, а когда подписка догнала журнал, —
-  время опроса, поэтому подписка, к которой сутки не было событий, не устаревает. Курсор события `ev.cursor` хранит
-  время самого события.
 - Без `LISTEN` (`connect({ listen: false })`) подписка опрашивает журнал.
 - Подписка без потерь — это сохранённый курсор: обработав событие, храните `sub.cursor` (позиция после последнего
-  выданного события) и продолжайте с него после перезапуска. С `ev.cursor` поток тоже продолжится, но после затишья
-  дольше яруса `all` такой курсор старше яруса, и продолжение с него — `cursor_expired`.
-
-### Проекторы
-
-Проектор строит строки производных классов из журнала: сводки, денормализованные карточки и всё, что можно считать
-с отставанием от записи. Классы-источники (`from`) пишет приложение, а строки классов `into` — только проектор.
-Каждый класс `into` помечен опцией `derivedBy` с именем проектора ([«Настройки класса»](#настройки-класса)).
-Производные классы заводит только администратор: синхронизируйте их администраторским подключением с сессией
-арендатора — `adm` из раздела 3 (`connect({ dsn: ADMIN, schema, token, allowBypassRls: true })`) или `as()` сервиса
-на таком подключении, в CLI — `letopis sync` с `--dsn` роли администратора. У сессии приложения это `acl_denied`. В примере ниже проектор
-считает продажи товаров по строкам заказов `line`.
-
-```ts
-const ProductSales = hub('ProductSales', { qty: z.number().int(), revenue: z.number().int() }, {
-  ends: { Product: one(Product).onDelete('cascade') }, key: ['Product'], derivedBy: 'product-sales', history: false,
-})                                               // производный класс — в модели; syncModels — администраторским подключением
-
-const sales = adm.projector('product-sales', {   // adm — администраторское подключение
-  from: ['line'],                                // классы-источники с потомками; у них должен быть журнал
-  into: ['ProductSales'],                        // производные классы этого проектора
-  version: 1,                                    // логика handle изменилась — новая версия и перестройка
-  withBefore: true,                              // c.before — прошлая версия объекта или null
-  handle(changes, out) {
-    for (const c of changes) {
-      if (c.op === 'purge' || c.op === 'trim' || c.op === 'reset') continue   // служебные изменения, не версии
-      const was = c.before                       // прошлая версия строки заказа — вычесть
-      const now = c.row.$deleted ? null : c.row  // новая версия — прибавить; у удаления её нет
-      if (was) out.inc('ProductSales', { Product: was.links.Product },
-        { qty: -Number(was.data.qty), revenue: -Number(was.data.qty) * Number(was.data.price) }, { tenant: c.tenant })
-      if (now) out.inc('ProductSales', { Product: now.links.Product },
-        { qty: Number(now.data.qty), revenue: Number(now.data.qty) * Number(now.data.price) }, { tenant: c.tenant })
-    }
-  },
-})
-const report = await sales.run({ once: true })  // догнать журнал: { batches, changes, created, updated, … }
-const state = await sales.status()               // { name, state, version, cursor, at, lag, failed, rebuildingTenants }
-await sales.rebuild()                            // перестроить с текущего состояния; { chunked: true } — пачками
-await sales.rebuild({ tenant: tenantId })        // перестроить одного арендатора — например, выбывшего (failed)
-await sales.rebuild({ tenant: tenantId, chunked: true })   // его же пачками: хвост журнала тем временем идёт для всех
-sales.run().catch((err) => console.error('проектор остановлен', err))   // следовать за журналом до stop()
-sales.close()                                    // stop() после текущей пачки и отписка от сигналов
-```
-
-- Проектору нужно администраторское подключение: `connect({ allowBypassRls: true })` роли, которая может стать
-  владельцем схемы. Иначе — `admin_required`, внутри `db.begin()` — `invalid_query`. Проектор читает журнал всех
-  арендаторов.
-- Первый запуск `run()` перестраивает проекцию с текущего состояния: журнал прорежен политикой хранения и обрезан
-  `purge`, поэтому собрать проекцию с начала журнала нельзя.
-- Каждая пачка — одна транзакция: изменения журнала, `handle`, запись результатов и сдвиг курсора фиксируются
-  вместе. Обрыв посреди пачки откатывает её целиком, а повтор начинается с того же курсора, поэтому каждое
-  изменение применяется ровно один раз. Писатель у проектора один: второй процесс того же проектора пропускает пачку
-  (счётчик `skipped` в отчёте), а `rebuild()`, начатая, пока другой процесс пишет пачку, — `projector_busy`.
-- Пачка делится по арендаторам: `handle` получает изменения одного арендатора, и запись его результатов идёт под
-  своей точкой сохранения. Если база отклоняет запись результатов арендатора (данные не проходят описание его
-  производного класса, цель конца не найдена и т. п.) или `out` отклоняет строку или приращение, построенные по его
-  данным (приращение — не число), откатываются только его изменения: арендатор выбывает, а остальные записываются в
-  той же пачке. Выбывший попадает в `status().failed` — `{ [id арендатора]: { cursor, code, message } }`, `message`
-  называет арендатора и id строки, — и его изменения пропускаются, пока его не перестроят. Производные строки
-  выбывшего больше не меняются: выбывший в `run()` сохраняет их такими, какими они были до пачки с ошибкой, а выбывший
-  посреди перестройки остаётся без них — частично построенные строки удаляются. Исключение из `handle`, нарушение
-  границ `out` и сбой окружения (взаимная блокировка, отмена запроса, обрыв связи) откатывают пачку целиком, а
-  `run()` отклоняется. Поэтому `run()` без `once` ловите (`catch`): после ошибки он остановлен.
-- Изменение (`ProjectorChange`) — это `cursor`, `id`, `class`, `tenant`, `op`, `rev`, `at`, `author`, `agent`,
-  `reason`, `moved` и `row` — версия из журнала (у удаления — надгробие с `$deleted`). При перестройке изменения —
-  строки текущего состояния: `rebuild: true`, `op` — `create`, `cursor` пустой.
-- Смена класса без смены id (у классов без ключа: сырой `UPDATE … SET class` и `reclass()`) журнал пишет версией уже
-  нового класса. Если она уводит строку из семейства `from`, проектор получает удаление: `op` — `delete`, `row` —
-  последняя версия строки в семействе с `$deleted`, `rev`, `at` и автор — смены класса. Строка, вошедшая так в
-  семейство, приходит изменением `reclass` с `before` = `null`.
-- С `withBefore` у изменения есть `before` — прошлая версия того же id. `before` равен `null`, если прошлой версии нет
-  (создание и первая версия нового id после `reclass` и `rekey`), если прошлая версия — удаление (так бывает после
-  `restore`) или вне семейства `from`, и у всех изменений перестройки. При `reclass` и `rekey` прежние данные
-  вычитает надгробие прежнего id: оно приходит изменением с `$deleted`, его `before` — последняя версия прежнего id,
-  а `moved` обоих изменений указывает на другой id. Поэтому свёртка из примера после `rekey` даёт ту же сумму. У
-  служебных изменений `purge`, `trim` и `reset` поля `before` нет совсем. Поэтому вычитайте `before`, только проверив
-  его на `null`, как в примере выше.
-- Служебные записи журнала `purge`, `trim` и `reset` тоже приходят изменениями, и у них `rev` равен 1. Поэтому
-  сначала разберите `op`, а уже потом сравнивайте `rev`.
-- `out.upsert(класс, строка, { tenant })` создаёт строку или заменяет её целиком по ключу класса.
-  `out.inc(класс, строка, приращения, { tenant })` создаёт строку или дополняет её и прибавляет числа, не читая
-  строку (поля, которых нет, считаются от 0). `out.delete(класс, ключ или id, { tenant })` удаляет строку, а если её
-  нет, ничего не делает. `await out.get(класс, ключ или id, { tenant })` читает текущую строку вместе с записями
-  пачки. Строку класса с ключом `delete` и `get` находят по полям ключа (`{ day: '2026-10-29' }`), а по id (строкой
-  или `{ $id }`) — только строку класса без ключа; один id у класса с ключом — `invalid_data`, и пачка откатывается.
-  `out` пишет только в классы `into` и только в арендатора изменений, переданных в `handle`; иначе —
-  `derived_class` или `tenant_denied`, и пачка откатывается.
-- Приращения строки, заданной одними полями ключа (или одним `$id`), `out` складывает до отправки в базу, пока между
-  ними нет `upsert`, `delete` или `get`: на строку — одна правка за пачку, а правило класса проверяется над итогом её
-  приращений. Строку с другими полями (данными, `$tags`, `$owner`) `inc` не складывает: её поля правят строку, и
-  порядок таких правок сохраняется.
-- Строка для `out` — в формате загрузчика: поля и роли концов на верхнем уровне, служебные `$tags`, `$owner` и
-  `$id` (`$id` нужен только классу без ключа). Значение роли — id цели. Правка, которая ничего не меняет, версии не
-  даёт. Версии производных строк пишутся от System с агентом `letopis projector <имя>`; журнал ведётся по
-  `history` класса, а сигнал об изменении уходит всегда.
-- `rebuild()` перестраивает проекцию атомарно, одной транзакцией: до её фиксации читатели видят прежние строки, но
-  горизонт подписок стоит. `rebuild({ chunked: true })` идёт пачками: производные строки удаляются сразу, и до
-  конца перестройки данные неполные, а `status().state` — `'rebuilding'`. Прерванную перестройку пачками
-  продолжает следующий запуск. Сам `run()` — первый запуск новой проекции и `onExpired: 'rebuild'` — перестраивает
-  пачками: горизонт подписок кластера стоит не дольше пачки. Второй процесс того же проектора тем временем ждёт или
-  продолжает ту же перестройку, а не начинает её заново. Перестройка удаляет строки только участников и только
-  классов их семейств `into` и начинает всех участников заново: отметки выбывших снимаются, а арендатор, чьи данные
-  снова не проходят, выбывает снова.
-- `rebuild({ tenant: id })` перестраивает одного арендатора одной транзакцией: удаляет его производные строки, строит
-  их из его текущих строк источников и снимает отметку в `status().failed`; изменения, уже учтённые перестройкой,
-  проектор потом не применяет второй раз. Исправьте данные или описание класса арендатора, затем перестройте его. Если
-  база снова отклоняет запись, перестройка откатывается с этой ошибкой, и арендатор остаётся выбывшим. Проекции ещё
-  нет или идёт перестройка пачками — `rebuild_required`; арендатор не участник — `tenant_denied`. С `chunked: true` —
-  пачками, каждая своей транзакцией со своим снимком, пока хвост журнала идёт для всех: изменения арендатора выше
-  последней пачки хвост пропускает (их прочтёт пачка), в пройденной — если транзакция видна в её снимке. Производные
-  строки арендатора удаляются сразу и до конца перестройки неполны (`status().rebuildingTenants`); блокировку,
-  занятую `run()` другого процесса, перестройка пережидает. Прерванную перестройку (процесс остановился) продолжает
-  `run()` любого процесса — с `onExpired` и без него.
-- `status().state` описывает проекцию в базе, а не процесс: `'new'` — проекции ещё нет, её построит первый `run()`
-  или `rebuild()`; `'running'` — проекция построена и ведётся по журналу (это не значит, что какой-то процесс сейчас
-  выполняет `run()`); `'rebuilding'` — идёт или прервана перестройка пачками.
-- `version` — версия логики `handle`. Если проекция построена другой версией, `run()` бросает `rebuild_required`, и
-  нужна перестройка `rebuild()`.
-- Если курсор старше яруса `all` политики хранения источников и после него есть изменения, часть изменений могла
-  проредиться. Ярус у каждого арендатора свой — это описание его классов. Курсор старше яруса у всех участников —
-  `run()` бросает `cursor_expired`, а с `onExpired: 'rebuild'` проектор перестраивается целиком, пачками. Старше
-  яруса только у части — выбывают они (`status().failed`, код `cursor_expired`), остальные идут дальше, а с
-  `onExpired: 'rebuild'` выбывшие перестраиваются сами, пачками: состояние перестройки лежит в чекпоинте, и её
-  продолжает `run()` любого процесса; блокировка, занятая другим процессом, — только повтор на следующем проходе, а
-  ошибка данных выводит арендатора с её кодом, без повторов. Ярус перестроенного арендатора отсчитывается от начала
-  его перестройки, пока курсор её не догнал: отстающий проектор не выводит его снова. Проектор без новых изменений не
-  истекает. `status().lag` — возраст самого старого необработанного изменения в мс.
-- Проектор работает с арендаторами, у которых каждый класс `into` помечен его `derivedBy`; изменения остальных
-  арендаторов он пропускает, поэтому одноимённый класс без пометки у другого арендатора ему не мешает. Нет ни одного
-  такого арендатора — `derived_class`. Пометить классы арендатора может только администратор, поэтому участников
-  выбирает он: пользователь арендатора сам к проектору не подключится. Опция
-  `tenants: [id, …]` — явный список участников: проектор работает только с этими арендаторами (их классы `into` тоже
-  должны быть помечены), а пометку у остальных не учитывает. Источники — семейства `from` у этих арендаторов; класс
-  из `into` источником не бывает, даже если попадает в `from`: свои результаты проектор не читает. Изменений класса
-  с `history: false` проектор не видит: журнала у него нет. Поэтому арендатор, у которого такой класс среди
-  источников, выбывает с кодом `invalid_class`, и его производных строк проектор не строит. Включите журнал класса и перестройте арендатора `rebuild({ tenant })`.
-- Арендатор, который стал участником после первой проекции (администратор пометил его классы позже), получает
-  начальную перестройку пачками: в проекцию попадают и строки, заведённые до вступления. Состав участников проектор
-  перечитывает по сигналу классов, а на подключении без LISTEN (`listen: false`) — в начале `run()` и не реже раза
-  в 5 секунд.
-- `batch` — сколько изменений в пачке (500), `pollMs` — запасной опрос (1000 мс): сигналы источников будят
-  проектор раньше.
-- `lockTimeout` — сколько транзакция проектора ждёт чужую блокировку строки (5000 мс; 0 — без предела). Транзакция
-  любого арендатора, которая держит строку итога или цель конца, иначе держала бы пачку всех арендаторов. Дольше —
-  пачка откатывается, курсор остаётся, `run()` не отклоняется, а пропускает проход (`skipped`) и повторяет его. Отчёт
-  называет арендатора, на чьей строке встала пачка (`locked`). `rebuild({ tenant, chunked: true })` такую блокировку
-  пережидает.
-- `lockRetries` — сколько проходов подряд запись одного арендатора может упираться в `lockTimeout`, прежде чем он
-  выбудет (по умолчанию 0 — не выбывает). Выбывший получает код `55P03`, и пачка идёт для остальных; его изменения
-  пропускаются до `rebuild({ tenant })`. Счёт ведёт процесс, удачная запись арендатора его сбрасывает. Учтите: долгая
-  исключительная блокировка семейства класса System (ужесточение описания) упрётся в каждого арендатора по очереди.
-- Каждая правка, которую `out` отправляет в базу, — отдельная правка строки, и скорость проектора задаёт число
-  правок, а не число изменений. Свёртка `inc` сводит правки строки к одной за пачку, поэтому handle из примера выше
-  (`out.inc` на каждое изменение) на машине замеров догонял 6 тысяч изменений в секунду при `batch` 500 и 33 тысячи
-  при `batch` 2000 ([раздел 17](#17-производительность)): чем больше пачка, тем больше приращений одной строки
-  складывается в одну правку.
-
-### Рецепт: дневная выручка
-
-Агрегат в базе и проектор решают похожие задачи по-разному:
-
-| | Агрегат в базе | Проектор |
-|---|---|---|
-| когда считается | в той же транзакции, что и запись источника | после фиксации, с отставанием (`status().lag`) |
-| что считает | сумму поля или число строк источника для одной строки-цели | что угодно: сводки по дням и группам, денормализованные карточки |
-| совпадает с источником | всегда, в том числе для сырого SQL | когда проектор догнал журнал |
-| цена записи | каждая операция блокирует строку цели и пишет её версию, поэтому писатели одной цели идут по очереди | писатели не ждут друг друга: проектор применяет изменения пачками после фиксации |
-| правило над итогом | `min(0)` отклоняет операцию, которая увела бы итог за правило | итог не мешает записи: ошибка данных выводит арендатора из проекции |
-| что запустить | ничего: поле держит база | процесс на администраторском подключении |
-
-Баланс кошелька, который не должен уйти в минус, — агрегат ([«Рецепт: баланс агрегатом»](#рецепт-баланс-агрегатом)).
-Выручка магазина по дням — итог по многим продажам, которому можно немного отставать, — работа для проектора:
-
-```ts
-const Sale = hub('Sale', { day: z.iso.date(), amount: z.number().int().min(0) }, { ends: { Shop } })   // продажа: день и сумма
-const DayRevenue = hub('DayRevenue', { day: z.iso.date(), revenue: z.number().int(), sales: z.number().int() }, {
-  ends: { Shop: one(Shop).onDelete('cascade') }, key: ['Shop', 'day'], derivedBy: 'day-revenue', history: false,
-})
-await syncModels(db, [Sale], { apply: true })
-await syncModels(adm, [DayRevenue], { apply: true })   // производный класс заводит администратор: adm — с сессией арендатора
-
-const revenue = adm.projector('day-revenue', {
-  from: ['Sale'], into: ['DayRevenue'], version: 1, withBefore: true,
-  handle(changes, out) {
-    for (const c of changes) {
-      if (c.op === 'purge' || c.op === 'trim' || c.op === 'reset') continue   // служебные изменения
-      const was = c.before                          // прошлая версия продажи — вычесть из её дня
-      const now = c.row.$deleted ? null : c.row     // новая — прибавить к её дню; у удаления её нет
-      if (was) out.inc('DayRevenue', { Shop: was.links.Shop, day: was.data.day },
-        { revenue: -Number(was.data.amount), sales: -1 }, { tenant: c.tenant })
-      if (now) out.inc('DayRevenue', { Shop: now.links.Shop, day: now.data.day },
-        { revenue: Number(now.data.amount), sales: 1 }, { tenant: c.tenant })
-    }
-  },
-})
-revenue.run().catch((err) => console.error('проектор выручки остановлен', err))   // следует за журналом до stop()
-const week = await db.Shop(shop).DayRevenue().sort('data.day', 'desc').limit(7).rows()   // семь последних дней
-```
-
-- День — поле продажи, а не время версии `at`: со временем версии правка, `restore` или `rekey` переносили бы сумму
-  продажи в свой день.
-- `out.inc` прибавляет, не читая строку, поэтому итог не зависит от порядка изменений: журнал отдаёт транзакции в
-  порядке первой записи, а не фиксации. Правка продажи вычитает прежнюю сумму из прежнего дня и прибавляет новую к
-  новому, удаление только вычитает. День, в котором продаж не осталось, остаётся строкой с нулями. Приращения одного
-  дня в пачке `out` складывает в одну правку.
-- У `DayRevenue` — `history: false`: производные строки не удваивают журнал, а перестройка соберёт их и без истории.
-  У `Sale` журнал нужен: изменений класса с `history: false` проектор не видит.
-- Строки `DayRevenue` приложение читает, как любой класс, а пишет их только проектор: `create` или `update` такой
-  строки — `derived_class`. Итог отстаёт от продаж до следующей пачки: проектор будят сигналы записи, а без них —
-  опрос раз в `pollMs`.
+  выданного события) и продолжайте с него после перезапуска. С `ev.cursor` поток тоже продолжится — после этого
+  события.
 
 ### Кэш результатов
 
@@ -1998,10 +2032,10 @@ const stats = db.cache.stats()                                 // { size, hits,
 - срок по умолчанию — 60 секунд; внутри `db.begin()` кэш не работает;
 - без `LISTEN` и в режиме `none` кэш выключен, а `connect({ cache: { ttlOnly: true } })` включает его: ответ живёт до
   конца срока, если его не сбросит запись этого подключения;
-- `db.load()`, проектор и `db.rebuildAggregates()` сбрасывают кэш, даже этого подключения, только сигналом базы.
+- `db.load()` сбрасывает кэш, даже этого подключения, только сигналом базы.
 
 Реестр классов процесс перечитывает по сигналу об изменении классов сразу (одно перечитывание за раз), а реестр и
-ключ сигналов по `*`, по незнакомому токену и по нагрузке не своего режима (а без ключа в режиме `opaque` — по любому
+ключ сигналов после переподключения слушателя, по незнакомому токену и по нагрузке не своего режима (а без ключа в режиме `opaque` — по любому
 сигналу) — не чаще раза в 5 секунд: поток сигналов, в том числе поддельных, не превращается в поток запросов. В режиме `none` реестр раз в 5 секунд сверяет отпечаток классов, а подписка
 опрашивает журнал. Подписка просыпается только от своих классов и своего арендатора, а без ключа — от любого
 сигнала; события она в любом случае читает из журнала, поэтому ничего не теряет.
@@ -2015,50 +2049,23 @@ const stats = db.cache.stats()                                 // { size, hits,
 
 <!-- run: guide -->
 ```ts
-const report = await adm.maintain()     // { sessions, codes, thinned, batches, more, queue, skipped }
+const report = await adm.maintain()     // { sessions, codes, queue, skipped }
 ```
 
 `maintain()` удаляет из таблицы `secret` сессии и одноразовые коды всех видов (`OTP` и свои `OTP_<ИМЯ>` из
 `issueOtp({ kind })`) — истёкшие, а также погашенные сессии и коды, которые уже использованы, заменены новым или
 исчерпали попытки, — и строки-замки удалённых классов (по две на класс; строку, которую держит транзакция, — следующим
-вызовом), прореживает журнал по политике хранения
-и проверяет очередь сигналов PostgreSQL: заполнение больше половины — предупреждение. Строки удалённого аккаунта
-`maintain()` ждать не нужно: их стирает само удаление ([«Удалить аккаунт»](#удалить-аккаунт)). Вызывать может системный
-администратор, роль с правом `letopis.maintain` или администраторское подключение. Запускает его внешний
-планировщик (`letopis maintain`) или сама библиотека: `connect({ maintain: '1h' })`. Интервал — число миллисекунд или
-строка (`'500ms'`, `'30s'`, `'15m'`, `'1h'`, `'1d'`) от 1 мс до 2³¹−1 мс (около 24 суток): другое значение, в том
-числе ноль, отрицательное или `NaN`, `connect()` отклоняет с `invalid_data`, не открывая соединений. `close()` ждёт
-идущий по расписанию запуск: он доделывает текущую пачку и следующую не начинает. Из нескольких процессов работает один:
-каждая пачка — своя транзакция, и первым делом она берёт блокировку обслуживания — строку таблицы `secret`, которую
-ни прикладная, ни посторонняя роль базы не займёт; блокировка снимается с фиксацией пачки. Если блокировку держит
-другой процесс, вызов до первой пачки отвечает `skipped: true`, а между пачками останавливается (продолжит тот
-процесс) и отчитывается о сделанном с `more: true`. Сеансовой блокировки нет, поэтому `maintain()` работает за любым
-пулом, в том числе за PgBouncer в режиме транзакций.
-
-### Сброс: `reset()`
-
-```ts
-await adm.reset({ level: 'tenant', confirm: 'v2.shop', tenant: SHOP })   // sessions | tenant | all
-```
-
-Сброс нужен тестам и стендам. Он работает, только если установка поставлена с `up({ allowReset: true })` (иначе
-`reset_disabled` даже для System), у вызывающего есть право `letopis.reset`, а `confirm` совпадает с именем схемы
-(`confirm_mismatch`). Уровни: `sessions` — все сессии, кроме текущей; `tenant` — данные арендатора; `all` — всё, с заново
-положенным системным сидом и новым ключом сервиса. Первая запись журнала после сброса — `reset`.
-
-### Описание модели для людей и ИИ
-
-<!-- run: guide -->
-```ts
-import { describeText } from 'letopis'
-
-const model = db.describe()           // { schema, tenant, classes: [...], methods }
-const modelText = describeText(model) // то же текстом — для llms.txt приложения или подсказки ИИ-агенту
-```
-
-`db.describe()` отдаёт описание классов, доступных сессии: поля, концы, ключи, политики и метаданные, а также
-условия по нескольким полям `anyOf` и `oneOf` с учётом наследования, признак производного класса `derivedBy` и
-агрегаты `aggregate`, если они заданы. Из командной строки — `letopis describe --format text --out llms.txt`.
+вызовом), а ещё проверяет очередь сигналов PostgreSQL: заполнение больше половины — предупреждение. Журнал
+`maintain()` не трогает. Строки удалённого аккаунта ждать не нужно: их стирает само удаление ([«Удалить
+аккаунт»](#удалить-аккаунт)). Вызывать может системный администратор, роль с правом `letopis.maintain` или
+администраторское подключение; остальным — `acl_denied` (`sql-time.maintain_denied`), в том числе сервису по ключу. Запускает его внешний планировщик (`letopis maintain`) или сама библиотека:
+`connect({ maintain: '1h' })`. Интервал — число миллисекунд или строка (`'500ms'`, `'30s'`, `'15m'`, `'1h'`, `'1d'`)
+от 1 мс до 2³¹−1 мс (около 24 суток): другое значение, в том числе ноль, отрицательное или `NaN`, `connect()`
+отклоняет с `invalid_data`, не открывая соединений. `close()` ждёт идущий по расписанию запуск. Из нескольких
+процессов работает один: обслуживание — одна транзакция, и первым делом она берёт блокировку обслуживания — строку
+таблицы `secret`, которую ни прикладная, ни посторонняя роль базы не займёт; блокировка снимается с фиксацией. Если
+блокировку держит другой процесс, вызов отвечает `skipped: true`. Сеансовой блокировки нет, поэтому `maintain()`
+работает за любым пулом, в том числе за PgBouncer в режиме транзакций.
 
 ### Агенты и MCP
 
@@ -2068,9 +2075,9 @@ const modelText = describeText(model) // то же текстом — для llm
 
 | Инструмент | Что делает |
 |---|---|
-| `letopis_model` | модель: классы, поля (JSON Schema), условия `anyOf` и `oneOf`, концы, ключи, алиасы, метаданные; с `class` — подробно один класс |
+| `letopis_model` | модель: классы, поля (JSON Schema), условия `anyOf` и `oneOf`, концы, ключи, алиасы, метаданные и рабочие цепочки `examples`; с `class` — подробно один класс |
 | `letopis_query` | чтение JSON-цепочкой: старт `class` и `filter`, `id` или `ids`; `steps` — переходы по ролям и классам; `asOf`, `withDeleted`, `sort`, `limit`, `cursor`; терминал `rows`, `first`, `ids`, `count`, `sum`, `avg`, `min`, `max`, `countBy` |
-| `letopis_history` | `versions`, `diff` или `blame` одного объекта |
+| `letopis_history` | версии одного объекта |
 | `letopis_write` | `create`, `update` (только с `rev`), `upsert`, `delete` — только при `write: true` (`letopis mcp --write`) |
 
 Запрос `letopis_query` — та же цепочка, что `db.Product({ price: lt(1000) }).Shop().sort('data.name').rows()`, только записанная JSON:
@@ -2079,9 +2086,9 @@ const modelText = describeText(model) // то же текстом — для llm
 { "class": "Product", "filter": { "price": { "$lt": 1000 } }, "steps": [{ "step": "Shop" }], "sort": { "field": "data.name" } }
 ```
 
-Значение фильтра — равенство, вложенный объект — поля вложенных объектов, `{ "Роль": id }` — конец. Операторы:
-`$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between`, `$in`, `$like`, `$ilike`, `$starts`, `$ends`, `$has`, `$hasAny`,
-`$hasAll`, `$exists`, `$isNull`, `$not`; ИЛИ — `{ "$or": [фильтр, …] }`. Неизвестный класс, роль, параметр или
+Значение фильтра — равенство, вложенный объект — поля вложенных объектов, `{ "Роль": id }` — конец. Операторы — ключи
+колонки MCP в таблице раздела [«Фильтры»](#фильтры): `{ "price": { "$gt": 5 } }`; ИЛИ — `{ "$or": [фильтр, …] }`
+вместо всего фильтра. Неизвестный класс, роль, поле, параметр или
 оператор — ответ `isError` с подсказкой похожих имён. Шагов `steps` — не больше 16, условий в `$or` одного фильтра —
 не больше 64; иначе `invalid_query`. Время запроса эти пределы не ограничивают: задайте `statement_timeout` роли базы,
 под которой подключается сервер MCP (`alter role … set statement_timeout = '5s'`).
@@ -2108,15 +2115,25 @@ const modelText = describeText(model) // то же текстом — для llm
 `'asc'` (по умолчанию) или `'desc'`; без `sort` строки идут по `id`. `sort`, `limit` и `cursor` — только у `rows`,
 `first` и `ids`.
 
-`letopis_model` без `class` отвечает (в `data`) `{ schema, tenant, classes }` — классы те же, что в `db.describe()`. Если такая
-модель больше `maxBytes`, приходит краткая: `brief: true`, а у классов — только имена полей и концов; подробно каждый
-класс отдаёт `letopis_model` с `class`. `letopis_history` принимает `class`, `id` и `kind`. `versions` отвечает
-`{ versions, more }` — последние версии в пределах ответа, от старой к новой; `diff` с `from` и `to` (номер версии или
-момент) — `{ diff }`; `blame` с `at` и `limit` — `{ blame }`. Если изменения или листья не поместились, ответ
-обрезан, и в нём есть `truncated: true` и `total`. `follow` работает у `versions` и `diff`.
-
-Отказ инструмента — `isError: true` и `structuredContent` вида `{ notice, error }`, где `error` — `{ code, message }`, а также `similar` (похожие
-имена), `detail` (подробности) и `sqlstate` (код PostgreSQL у ошибки не из letopis), если они есть. Параметр не по
+`letopis_model` без `class` отвечает (в `data`) `{ schema, tenant, classes }` — классы, доступные сессии: свои классы
+арендатора и общие классы System с полями, концами, ключами, настройками (`history`, `ownerDefault`, `cache`) и метаданными, а также условия по нескольким
+полям `anyOf` и `oneOf` с учётом наследования, если они заданы. У каждого класса есть `examples` — рабочие цепочки, собранные из реестра: `create` — создать, `find` — найти,
+`neighbors` — перейти к соседям. `create` передаёт поля ключа и обязательные поля без умолчания, а обязательные концы и
+концы ключа ставит слотами; у абстрактного и системного класса его нет. Образец значения — `examples`
+из JSON Schema поля (в Zod — `.meta({ examples: […] })`), иначе `const`, `default`, первое из `enum`, иначе по типу и
+формату. Поле с `pattern` без `examples` может получить образец, который проверку не пройдёт. `find` ищет по ключу
+(`first()`), а без ключа — по обязательному полю (`rows()`). `neighbors` идёт по каждому концу класса и к классам, чьи
+концы ведут на него. `'<id Org>'` — место для id объекта класса или его потомка; `'<id Service|Product>'` — любого из
+классов; у множественного конца с `min` — `'<id Класс #1>'`, `'<id Класс #2>'`. Если модель больше `maxBytes`, она
+приходит сначала без `examples`, затем краткой: `brief: true`, а у классов — только имена полей и концов; подробно
+каждый класс отдаёт `letopis_model` с `class`.
+
+`letopis_history` принимает `class`, `id` и необязательный `kind` (только `versions`). Ответ — `{ versions, more }`:
+последние версии в пределах ответа, от старой к новой; `more: true` — есть и более ранние.
+
+Отказ инструмента — `isError: true` и `structuredContent` вида `{ notice, error }`, где `error` — `{ code, message }`, а также `hint` (что
+делать), `similar` (похожие имена классов, ролей, полей, параметров или операторов), `detail` (подробности) и `sqlstate` (код
+PostgreSQL у ошибки не из letopis), если они есть. Параметр не по
 входной схеме инструмента (не тот тип, значение не из перечня, нет обязательного) отклоняет SDK ещё до letopis: тогда
 `isError: true` и только текст, без `structuredContent`.
 
@@ -2131,12 +2148,13 @@ const modelText = describeText(model) // то же текстом — для llm
 `rev` прочитанной версии: чужая версия — `conflict`, потерянной правки нет. `delete` без `confirm` возвращает превью
 каскада и код операции: `{ preview, operation }`. С `confirm: true` удаление подтверждает человек в клиенте через
 elicitation (в ревизии протокола 2025 — запросом клиенту, в 2026-07-28 — ответом `input_required`), подтверждение
-привязано к хэшу операции, а ответ — `{ deleted, operation }`. В ревизии 2026-07-28 подпись `requestState`, с которой
+привязано к хэшу операции, а ответ — `{ deleted, operation }`. Удаляет инструмент ровно показанное: превью, построенное
+до подтверждения, идёт в `expect`, и если данные изменились — `conflict` (`write.preview_changed`), ничего не удалено. В ревизии 2026-07-28 подпись `requestState`, с которой
 клиент повторяет вызов, привязана ещё к пользователю сервера и действует 10 минут: подпись сервера другого
 пользователя и устаревшая — отказ `confirmation_required`. Окно подтверждения показывает каноническое имя класса и
 id целей (первые 10, дальше — «и ещё K»); алиас и `meta` класса пишет арендатор, поэтому в окно они не попадают. Код
 операции, присланный агентом, подтверждением не считается; клиент без elicitation получает отказ
-`confirmation_required`. Причина каждой записи — `mcp: letopis_write`, её показывает `blame()`. Классы прав — `rule`,
+`confirmation_required`. Причина каждой записи — `mcp: letopis_write`, её показывают версии. Классы прав — `rule`,
 `Resource`, `member`, `Account`, `Class` и их потомков (правила, членства, описания классов) — `letopis_write` по
 умолчанию не пишет, не правит и не удаляет: отказ `acl_denied`. Агент под инъекцией в данных выдал бы постороннему
 членство или правило без подтверждения человека. Разрешает это только опция `allowAclWrite: true`.
@@ -2169,7 +2187,9 @@ id целей (первые 10, дальше — «и ещё K»); алиас и
 **HTTP.** Встроенного HTTP-сервера нет. `createMcpServer(db, { write, maxRows, maxBytes })` из `letopis/mcp` отдаёт
 сервер MCP, а приложение подключает его к своему обработчику `createMcpHandler` из SDK со своей авторизацией
 OAuth 2.1: токен запроса проверяет приложение и находит по нему пользователя letopis. Подключение — сессия
-пользователя (`connect({ token })`) или фасад `svc.as(пользователь)`: ключ сервиса остаётся в процессе приложения.
+пользователя в арендаторе приложения (`connect({ token })` после `auth.switch(tenant)`) или фасад
+`svc.as(пользователь, { tenant })`: ключ сервиса остаётся в процессе приложения. Без `{ tenant }` фасад работает в
+личном арендаторе пользователя, и классов приложения агент не увидит.
 Подключение в обход RLS получает отказ `bypass_rls`, корень сервиса без `as()` и подключение без сессии —
 `user_session_required`, фасад явной транзакции `db.begin()` — `invalid_query`. Сессию в арендаторе System — так
 работает системный администратор: его роль `admin` даёт права на аккаунты, членства и правила установки — сервер тоже
@@ -2214,39 +2234,157 @@ const [{ n }] = await db.sql`select count(*)::int as n from "v2.shop".entity whe
 сериализации запрос и `fn` повторяются до трёх раз, поэтому `fn` должна выдерживать повтор. Писать сырым SQL тоже
 можно — те же триггеры проверят данные, а функции базы `merge` и `inc` доступны приложению.
 
+Ошибки базы `db.sql`, `db.transaction(fn)` и `tr.sql` в `db.begin()` приходят так же, как у цепочек: с кодом letopis
+(`LT…` — по таблице [«Ошибки»](#15-ошибки)), а прочие — как ошибка postgres.js с SQLSTATE в `err.code`. Исключение —
+значение не того типа, SQLSTATE `22P02` (`'42'::uuid`, `'abc'::int`): оно приходит `LetopisError` с кодом
+`invalid_query` (ключ `api.db_bad_value`), текст называет значение — `letopis: invalid_query: значение не того типа:
+invalid input syntax for type uuid: "42"`, а исходная ошибка PostgreSQL — в `err.cause` (`err.cause.code === '22P02'`).
+Ловите её по `err.code === 'invalid_query'`, а не по SQLSTATE:
+
+```ts
+try {
+  await db.sql`select * from "v2.shop".entity where id = ${input}::uuid`
+} catch (e) {
+  if (!(e instanceof LetopisError) || e.code !== 'invalid_query') throw e
+  // e.key === 'api.db_bad_value'; (e.cause as { code: string }).code === '22P02'
+}
+```
+
 ### Командная строка
 
 ```sh
-letopis sync <модуль> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--apply]
-letopis types --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--out <файл>]
+letopis sync <модуль> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--apply | --check]
+letopis types --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--out <файл>] [--system]
 letopis load <файлы…> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--class <Класс>]
-  [--duplicates error|first|last] [--existing error|skip|update] [--commit-every <N>] [--verify] [--initial]
-letopis verify --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>] [--data]
-letopis maintain --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>] [--batches <N>]
-letopis describe --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--format json|text] [--out <файл>]
-letopis import --from <строка 0.21> --from-schema <v1.имя> --dsn <строка> --schema <v2.имя> [--tenant <имя>] [--keyless <Класс>]…
-  [--rename <Старое>=<Новое>]… [--update] [--commit-every <N>] [--partition <имя>] [--initial]
+  [--duplicates error|first|last] [--existing error|skip|update] [--commit-every <N>] [--initial]
+letopis maintain --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>]
 letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пользователя> [--write]
   (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)
+# у любой команды: --log[=debug|info|warn|error] — события JSON-строками в stderr (без флага — LETOPIS_LOG)
 ```
 
-`letopis types` и `letopis describe` строят результат по классам сессии, поэтому без действующей сессии (токен истёк,
-погашен, неверен или не задан, ключ API неверен) выходят с кодом 1 и ошибкой `no_session`, а файл `--out` не трогают.
+`letopis types` строит результат по классам сессии, поэтому без действующей сессии (токен истёк, погашен, неверен или
+не задан, ключ API неверен) выходит с кодом 1 и ошибкой `no_session`, а файл `--out` не трогает.
+Классы арендатора System — системные и классы сидов пакета (например, `booking`) — `letopis types` выдаёт только с
+`--system`.
+
+`letopis sync --check` — тот же сухой прогон, но с кодом 1, если модели расходятся с базой (есть что создать или
+изменить): шаг CI перед `--apply`. Вместе с `--apply` — справка и код 2.
 
 ### Наблюдение
 
+- Журнал событий — `connect({ log })` или `LETOPIS_LOG` ([«Логирование»](#логирование)).
 - `connect({ onQuery, slowMs })`: хук получает на каждый запрос цепочки режим, классы, длительность, число строк и
   признак медленного запроса; без хука медленный запрос печатает предупреждение.
 - `sub.lag()` — отставание подписки; отчёт `maintain()` — заполнение очереди сигналов.
 - Горячие цели ссылок (организация, на которую ссылается почти всё) копят блокировки `for key share` и MultiXact,
   как при обычных внешних ключах. Это стоит мониторить.
 
+### Логирование
+
+letopis пишет журнал событий приложения: что прочитано и записано, что удалено и восстановлено, какие были ошибки,
+кто вошёл. По нему видно, что удаление прошло по показанному превью, а восстановление вернуло то, что ушло. Журнал
+выключен, пока его не включили опцией или переменной окружения.
+
+**Опции.** `connect()` и `up()` принимают одни и те же:
+
+| Опция | Что делает |
+|---|---|
+| `log` | куда писать: функция `(event) => void` или объект с методами `debug`, `info`, `warn`, `error` (`console`, pino и подобные) — вызывается `logger[level](event, event.event)`; нет метода уровня — `logger.log`, нет и его — событие пропускается |
+| `logLevel` | порог: `'debug'`, `'info'` (по умолчанию), `'warn'`, `'error'` или `'off'`; событие ниже порога не собирается |
+| `redact` | ещё имена полей (`string[]`, без учёта регистра), значения которых заменяются на `'***'` в любом месте `detail` |
+
+```ts
+import pino from 'pino'
+const svc = await connect({ dsn: APP, schema: 'v2.shop', apiKey: SERVICE_KEY,
+  log: pino(), logLevel: 'info', redact: ['phone', 'email'] })
+const solo = await connect({ dsn: APP, schema: 'v2.shop', token, log: (e) => audit.push(e) })   // своя функция
+```
+
+Подключения из `db.as()` и `svc.as()`, `db.begin()`, `db.transaction()`, батч и `auth.switch()` пишут тем же журналом
+с тем же порогом и `redact`; в их событиях свои `tenant`, `account` и `tx`. Исключение внутри логгера проглатывается:
+операция из-за журнала не ломается. Хук `onQuery` работает как прежде, а каждый запрос SQL — ещё и событие `sql`.
+
+**Переменная окружения и командная строка.** `LETOPIS_LOG=<уровень>` (`debug`, `info`, `warn`, `error`, `off`;
+`1` и `true` — то же, что `info`): если `log` не передан, события пишутся в stderr JSON-строками, одна строка — одно
+событие. Если `log` передан без `logLevel`, порог берётся из `LETOPIS_LOG`, а без неё — `info`. Без `log` и без
+`LETOPIS_LOG` журнала нет. Команды CLI принимают `--log[=уровень]` (`--log` без значения — `info`), события — в stderr;
+без флага действует `LETOPIS_LOG`.
+
+```sh
+LETOPIS_LOG=info node app.js 2>> letopis.log
+npx letopis maintain --dsn "$ADMIN" --schema v2.shop --api-key "$KEY" --log=debug
+```
+
+**Событие** — объект:
+
+| Поле | Что значит |
+|---|---|
+| `ts`, `level`, `event` | время ISO, уровень (`debug`, `info`, `warn`, `error`), имя события |
+| `op`, `ms` | операция (`rows`, `first`, `create`, `delete`, `login` …) и длительность в миллисекундах |
+| `tenant`, `account`, `tx` | арендатор и аккаунт сессии; метка транзакции, если операция в `db.begin()`, `transaction()` или батче |
+| `chain`, `rows` | цепочка в читаемом виде (`Shop({"name":"Ромашка"}).Product.rows()`) и число строк результата или затронутых |
+| `code`, `key`, `msg` | код и ключ каталога ошибки или предупреждения, текст |
+| `detail` | подробности события (секреты замаскированы) |
+| `cause` | у события `error` — исходная ошибка: `{ name, message, code }` |
+
+**Маскировка.** Без настройки заменяются на `'***'` на любой глубине `detail`: значения полей с паролями, токенами,
+ключами, секретами и кредами — в том числе `password`, `pass`, `passwd`, `pwd`, `passphrase`, `secret`, `token`,
+`serviceKey`, `apiKey`, `api_key`, `credential`, `authorization`, `cookie`, `hash`, `material`, `totp`, `otp`;
+учётные данные в строке подключения (`postgres://***@host/db` — скрыт и пользователь); пароль в тексте SQL
+(`password '…'`). `redact` добавляет свои имена полей (персональные данные и т. п.).
+
+Не пишутся никогда: значения параметров SQL (у событий `sql` и `raw` — только их число); текст, `DETAIL`, `WHERE`,
+`HINT` и внутренний запрос ошибки PostgreSQL — в событии только SQLSTATE и имена ограничения, таблицы, колонки, схемы,
+типа и функции, а вместо текста — фраза «ошибка PostgreSQL <SQLSTATE>»; поле `data` строк в `detail` ошибки (превью,
+снимки отказа `restore`) — `'***'`; значение аргумента в тексте ошибки letopis (`query.bad_uuid`, `api.db_bad_value`
+и подобные) — `'***'`.
+
+Пишутся как есть — учитывайте это: значения фильтров в `chain` (`Shop({"name":"Ромашка"})`; у записи данные —
+только именами полей), поэтому фильтр по персональным полям — `redact: ['email', …]`; тексты исключений кода
+приложения (с маскировкой паролей). Объект ошибки, который получает приложение (`err.message`, `err.cause`), журнал
+не меняет: что из него логировать самому, решает приложение.
+
+**Транзакции и фиксация.** Событие записи вне `db.begin()` пишется после фиксации своей транзакции и само доказывает
+её. Внутри `db.begin()` события несут `tx` и пишутся, когда оператор выполнен, до `COMMIT`: `begin → delete →
+rollback` оставит событие `delete`, а строки — на месте. Фиксацию такой записи доказывает только `tx.commit` с тем же
+`tx`; `tx.rollback` с ним — запись отменена; `commit_unknown` — исход неизвестен (повтор с тем же ключом).
+
+**Основные события.** Полный каталог с уровнями и описаниями — `lib/src/messages/log.ts` (`LOG_EVENTS`).
+
+| Событие | Уровень | Когда | Главное в событии |
+|---|---|---|---|
+| `connect`, `close` | info | подключение готово, закрыто | `ms`; `detail.schema` |
+| `up`, `migrate` | info | `up()` завершён; `up()` обновил ревизию схемы | `detail`: `schema`, `created`, `revision`; `from`, `to` |
+| `sync` | info | `syncModels()` | итог: созданные и изменённые классы |
+| `read` | debug | терминал чтения | `op`, `chain`, `rows`, `ms`, `tx` |
+| `cache.hit`, `cache.miss` | debug | ответ из кэша результатов; промах | `chain`, `rows` |
+| `write` | info | глагол записи, план батча, загрузка | `op`, `chain`, `rows`, `ms`, `tx` |
+| `delete.preview` | debug | `delete()` без `confirm` | `rows`; `detail`: сколько `delete`, `unset`, `restrict` |
+| `delete` | info | удаление выполнено | `chain`, `rows`; `detail.expect` — сколько строк превью сверено (`false` — без сверки, `all: true`) |
+| `restore` | info | восстановление выполнено | `chain`, `rows`; `detail`: `expect`, `partial`, `skipped: [{ id, why }]` |
+| `tx.begin` | debug | открыта транзакция | `tx` |
+| `tx.commit` | info, если в транзакции была запись, иначе debug | зафиксирована транзакция | `tx`, `ms`; `detail.writes` — число операций записи |
+| `tx.rollback` | info | откат | `detail`: `reason` (`explicit` или `error`), `writes` |
+| `tx.retry` | warn | повтор после `40001`, `40P01` или конфликта журнала | `detail`: `attempt`, `code` |
+| `auth.login`, `auth.logout`, `auth.revoke`, `auth.switch` | info | вход, выход, отзыв сессии, смена арендатора | `account`, `tenant` |
+| `watch.start`, `watch.stop` | info | подписка открыта, закрыта | `detail.classes` |
+| `signal` | debug | получен сигнал базы | `detail.channel` |
+| `maintain` | info | `maintain()` | итог обслуживания |
+| `warning` | warn | любое предупреждение letopis (`api.step_undefined_filter` и другие) | `key`, `msg` |
+| `error` | warn — штатный отказ (`exists`, `conflict`, `target_not_found`, `not_deleted`, `delete_restricted`, `acl_denied`, `tenant_denied`, `no_session`, `invalid_data` с `err.issues` и другие); error — прочее | каждая ошибка при выходе из операции | `op`, `chain`, `code`, `key`, `msg`, `detail`, `cause` |
+| `sql` | debug | каждый запрос SQL | `ms`, `rows`, `tx`; `detail`: текст (до 2000 знаков), число параметров |
+
+Ещё есть, среди прочих: `auth.as` (debug, `as()`), `auth.fail` (warn, неудачный вход), `acl.change` (правка прав
+`db.acl`), `tenant.create`, `account.purge`, `load` (итог загрузчика), `lock` (debug, `db.lock()`), `mcp.call` (вызов
+инструмента MCP).
+
 ### Пулы соединений и PgBouncer
 
 С PgBouncer в режиме транзакций `LISTEN` недоступен: `connect({ listen: false })`. Тогда реестр перечитывается через
 `db.refresh()`, подписка опрашивает журнал, а кэш результатов выключен или работает по сроку. Подготовленные
 операторы работают с PgBouncer 1.21 и новее; со старыми передайте свой пул postgres.js с `prepare: false` в
-`connect({ sql })`. `maintain()` берёт транзакционную блокировку в каждой пачке и работает за таким пулом.
+`connect({ sql })`. `maintain()` берёт транзакционную блокировку и работает за таким пулом.
 
 <!-- run: guide -->
 ```ts
@@ -2255,55 +2393,18 @@ await anna.close()
 await svc.close()      // и подключения, полученные через svc.as()
 ```
 
-## 14. Переход с 0.21
+## 14. Справочник API
 
-1.0 — новая реализация, а не продолжение 0.21: схема 0.21 не обновляется на месте. 1.0 ставится в новую схему,
-данные переносит команда `letopis import`, а код переводится по таблице замен из [MIGRATION.md](MIGRATION.md).
-Главные отличия в поведении: `create` не перезаписывает (занятый ключ — `exists`), `count()` считает сущности,
-пути — `paths()`, права и изоляция арендаторов включены всегда.
-
-```sh
-npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgres://…/new --schema v2.salon \
-  --tenant salon [--keyless booking] [--rename link=link_] [--update] [--commit-every 100000]
-```
-
-- Схема 1.0 ставится заранее (`up()`), оба подключения — администраторские. Источник — таблицы 0.21 (`Schema`,
-  `Entity`, `Account`, `Credential`, `Resource`, `Rule`) любой базы: PostgreSQL 17 с TimescaleDB или дамп обычных
-  таблиц. Пишут загрузчик (режим истории, `existing: 'skip'`, агент `letopis import`) и функции владельца.
-- Классы становятся строками `Class` в System. Правила fastest-validator переводятся в JSON Schema (`optional`
-  пропускает `null`, `$$strict` → `additionalProperties: false`, `record` → `propertyNames`). Концы — роли по
-  имени класса цели, союз всех потомков класса — полиморфный конец. Корни `Entity` и `link` опускаются;
-  `description`, `appearance`, `order` переходят в `meta`. Имена, занятые методами 1.0, — `--rename` (по умолчанию
-  имя с `_`).
-- id: у класса с ключом (правило v5 из 0.21) — v5 от ключа, у класса без ключа — v5 от старого id. Данные System
-  переходят в арендатора `--tenant`, аккаунты — в строки `Account`, креды — в `secret` как есть (scrypt, ключи);
-  одноразовые коды не переносятся. Ресурсы и правила — в System.
-- До первой записи импорт останавливается, если два объекта 0.21 дают один id 1.0 (данные нарушают ключ —
-  `--keyless <Класс>`), если ключ менялся между версиями или ссылается на отсутствующий объект. Висячая ссылка
-  живой строки — `target_not_found` с объектом 0.21.
-- Если загрузчик отклонил данные, ошибка начинается с `import: арендатор …`, а её `detail` — как у загрузчика
-  ([«Отчёт и ошибки»](#отчёт-и-ошибки)), только строки названы объектами 0.21: `rows` — нарушения с `class`, `id`
-  и `rev` объекта 0.21, `code` и `message`; `total`, `truncated`, `limit` и `complete` — как в отчёте загрузчика;
-  `notes` — непереведённые правила.
-- Повтор дописывает недостающее без дублей, `--update` — ещё и новые версии изменившихся объектов. Отчёт — JSON в
-  конце вывода: объекты и версии по классам в 0.21 и в 1.0, `verify()`, непереведённые правила, классы без ключа и
-  uuid в `data`, совпадающие со старыми id (их импорт не переписывает). Код выхода 1, если `verify()` нашёл
-  расхождения.
-
-## 15. Справочник API
-
-Полный машинный список экспортов, методов и текстов ошибок — `docs/api-contract.json` в репозитории.
+Полный машинный список экспортов, методов и текстов ошибок — `lib/api-contract.json` в репозитории.
 
 ### Экспорты пакета
 
 | Точка входа | Что экспортирует |
 |---|---|
-| `letopis` | `connect`, `up`, `createTenant`; операторы `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `inList`, `like`, `ilike`, `starts`, `ends`, `has`, `hasAny`, `hasAll`, `exists`, `isNull`, `not`, `or`, `isOp`; `inc`, `isInc`, `cursorOf`; `idOf`, `uuidv5`, `v5Name`, `v5Id`; `LetopisError`, `ValidationError`, `fromDbError`; `syncModels`, `generateTypes`, `schemaToTs`; `compileValidator`, `applyDefaults`, `Registry`; `totpCode`, `hashPassword`, `verifyHash`; `describeText`; константы `DDL_REVISION`, `RESERVED_CLASS_NAMES`, `CHAIN_METHODS`, `DB_METHODS`; типы `Db`, `DbTx`, `TypedDb`, `Chain`, `Row`, `Filter`, `Cursor`, `ConnectOptions`, `UpOptions`, `LoadOptions`, `LoadReport`, `WatchOptions`, `WatchEvent`, `AuthApi`, `AclApi`, `DiffResult`, `DiffChange`, `BlameResult`, `BlameField`, `Projector`, `ProjectorOptions`, `ProjectorChange`, `ProjectorOut`, `ProjectorRow`, `ProjectorReport`, `ProjectorStatus`, `ProjectorFailure` ([«Проектор»](#проектор)), `AggregateInfo` и другие |
-| `letopis/model` | `hub`, `link`, `one`, `many`, `End`, типы `Infer`, `InferLinks`, `Model`, `ClassDef`, `ClassMeta`, `HistoryPolicy`, `AggregateDef`; `normalizeSchema`, `translatePattern`, тип `JsonSchema` |
+| `letopis` | `connect`, `loose`, `up`, `createTenant`; операторы `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `inList`, `like`, `ilike`, `starts`, `ends`, `has`, `hasAny`, `hasAll`, `exists`, `isNull`, `not`, `or`, `isOp`; `inc`, `isInc`, `cursorOf`; `idOf`, `uuidv5`, `v5Name`, `v5Id`; `LetopisError`, `ValidationError`, `fromDbError`; `syncModels`, `generateTypes`, `schemaToTs`; `compileValidator`, `applyDefaults`, `Registry`; `totpCode`, `hashPassword`, `verifyHash`; константы `DDL_REVISION`, `RESERVED_CLASS_NAMES`, `CHAIN_METHODS`, `DB_METHODS`; типы `Db`, `DbTx`, `TypedDb`, `SystemModels`, `Chain`, `Row`, `Expected` (строка `expect`: `{ id, rev, $action? }`), `DeleteOptions`, `RestoreOptions`, `Filter`, `Cursor`, `ConnectOptions`, `UpOptions`, `LoadOptions`, `LoadReport`, `WatchOptions`, `WatchEvent`, `AuthApi`, `AclApi`, `MaintainReport` и другие |
+| `letopis/model` | `hub`, `link`, `one`, `many`, `End`, типы `Infer`, `InferLinks`, `Model`, `ClassDef`, `ClassMeta`; `normalizeSchema`, `translatePattern`, тип `JsonSchema` |
 | `letopis/mcp` | `createMcpServer(db, опции)` — сервер MCP SDK с инструментами letopis; тип `McpOptions`: `write` — инструмент `letopis_write` (по умолчанию его нет), `maxRows` — строк в ответе (100, от 1 до 10 000), `maxBytes` — байт в ответе (50 000, от 1 000 до 50 000 000); `allowAclWrite` — `letopis_write` пишет и классы прав (по умолчанию — `acl_denied`); `allowSystemAdmin` — сессия в арендаторе System (по умолчанию — `user_session_required`); значение вне пределов — `invalid_data`. Нужен пакет `@modelcontextprotocol/server` ([раздел 13](#агенты-и-mcp)) |
-| CLI `letopis` | `sync`, `types`, `load`, `verify`, `maintain`, `describe`, `import`, `mcp` ([раздел 13](#13-эксплуатация)); у `mcp` — `--dsn`, `--schema`, `--token` (или `LETOPIS_DSN`, `LETOPIS_SCHEMA`, `LETOPIS_TOKEN`) и `--write` |
-
-Снятые имена 0.21 (`uuidv7`, `LETOPIS_NS` и методы, перечисленные ниже) бросают `removed` с заменой.
+| CLI `letopis` | `sync`, `types`, `load`, `maintain`, `mcp` ([раздел 13](#13-эксплуатация)); у всех — `--log[=уровень]` ([«Логирование»](#логирование)); у `mcp` — `--dsn`, `--schema`, `--token` (или `LETOPIS_DSN`, `LETOPIS_SCHEMA`, `LETOPIS_TOKEN`) и `--write` |
 
 ### Корень `db`
 
@@ -2313,29 +2414,25 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `schema`, `token`, `tenant`, `registry` | имя установки, токен, арендатор сессии, реестр классов (`resolve`, `find`, `has`, `all`, `family`) |
 | `auth`, `acl` | вход, креды и сессии; решения прав ([раздел 10](#10-пользователи-вход-и-права)) |
 | `as(аккаунт, { tenant, owner })` | тот же пул от имени аккаунта (асинхронный) |
-| `begin()`, `commit(tr)`, `rollback(tr)`, `lock(…ключи)` | явная транзакция ([раздел 8](#8-транзакции-батчи-и-деньги)) |
+| `begin()`, `commit(tr)`, `rollback(tr)`, `lock(…ключи)` | явная транзакция ([раздел 8](#8-транзакции-и-батчи)) |
 | `batch(имя)` | очередь планов: `run()`, `discard()`, `size()` |
 | `load(вход, опции)` | загрузчик ([раздел 9](#9-массовая-загрузка)) |
-| `projector(имя, опции)` | проектор из журнала: `run()`, `rebuild({ chunked, tenant })`, `status()`, `stop()`, `close()` ([«Проекторы»](#проекторы)) |
-| `rebuildAggregates(класс)` | ремонт агрегатов класса и его потомков во всех арендаторах: поле заново из живых источников, версия — только у исправленных; → их число ([«Агрегаты в базе»](#агрегаты-в-базе)) |
 | `watch(опции)`, `cache` | подписка; кэш результатов (`clear()`, `stats()`) |
 | `` sql`…` ``, `transaction(fn)` | сырой SQL под сессией и RLS |
 | `idOf(класс, ключ)` | id объекта класса с ключом в арендаторе сессии |
 | `entity(строка \| цепочка)` | начать путь с готового узла |
-| `describe()` | машинное описание модели |
-| `verify(опции)`, `maintain(опции)`, `reset(опции)` | проверка, обслуживание, сброс ([разделы 11](#11-история-и-срезы-на-дату) и [13](#13-эксплуатация)) |
-| `trimHistory(цель, момент)`, `rekeyClass(класс, ключ)` | обрезка истории; новый ключ класса |
-| `refresh()`, `flushSignals()`, `close()` | перечитать классы; отправить сигналы сейчас; закрыть |
+| `maintain()` | обслуживание ([раздел 13](#13-эксплуатация)) |
+| `refresh()`, `flushSignals()`, `close()` | перечитать классы; отправить сигналы сейчас; закрыть пул и подписки (у фасада `as()` — ничего не делает, в `db.begin()` — откат) |
 
 ### Цепочка
 
 | Группа | Методы |
 |---|---|
 | шаги | `.Класс(фильтр)`, `.алиас(фильтр)`, `.Роль(фильтр)` |
-| модификаторы | `limit(n)`, `offset(n)`, `sort(поле, 'asc' \| 'desc')`, `after(курсор)`, `asOf(момент)`, `withDeleted()`, `deep(max)`, `exact()`, `alias(имя)`, `tags(…)`, `owner(…)`, `entity(…)`, `forUpdate()`, `cache({ ttl })` |
-| глаголы | `create(данные)`, `update(патч, { rev })`, `upsert(данные)`, `delete({ confirm })`, `anonymize(поля)`, `reclass(класс, данные)`, `rekey(патч)`, `restore()`, `purge({ confirm })` |
+| модификаторы | `limit(n)`, `offset(n)`, `sort(поле, 'asc' \| 'desc')`, `after(курсор)`, `asOf(момент)`, `withDeleted()`, `deep(max)`, `exact()`, `alias(имя)`, `tags(…)`, `owner(…)`, `entity(…)`, `forUpdate()`, `cache({ ttl })`; модификаторы выборки `limit`, `offset`, `sort`, `after`, `forUpdate` — последнему шагу цепочки (перед глаголом — его целям), где бы ни стояли; `asOf` и `cache` — всей цепочке; `withDeleted`, `deep`, `exact`, `alias`, `tags`, `owner` — своему шагу |
+| глаголы | `create(данные)`, `update(патч, { rev, all })`, `upsert(данные)`, `delete({ confirm, expect, all })`, `restore({ expect, partial, all })` (у всех — ещё `reason`; `expect` — строки `{ id, rev }` превью или надгробий, [раздел 7](#7-удаление-и-восстановление)); `delete({ confirm: true })` — только с `expect` или `all: true`, `restore()` — только с `expect` или `all: true` (тип `DeleteOptions` и `RestoreOptions` отклоняет иное ещё при компиляции); `update` и `delete({ confirm: true, expect })` без фильтра, id, `tags()`, `owner()` и `limit()` у шага глагола и шагов до него (и без `create()` или `upsert()` раньше в цепочке) — только с `{ all: true }` |
 | слоты | после глагола: `.Роль.set(значение)`, `.Роль.unset()`, `.Роль.add(значение)`, `.Роль.remove(значение)` |
-| терминалы | `rows()`, `first()`, `ids()`, `count({ paths })`, `paths()`, `versions({ follow })`, `diff({ from, to, follow })`, `blame({ at, limit })`, `sum(поле)`, `avg(поле)`, `min(поле)`, `max(поле)`, `countBy(поле)` |
+| терминалы | `rows()`, `first()`, `ids()`, `count({ paths })`, `paths()`, `versions()`, `sum(поле)`, `avg(поле)`, `min(поле)`, `max(поле)`, `countBy(поле)` |
 
 ### `db.auth`
 
@@ -2349,9 +2446,9 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `issueOtp`, `verifyOtp` | `{ account, identifier, kind?, ttl?, digits?, maxAttempts? }` → `{ code }`; `{ identifier, code, kind? }` → вход или `null` |
 | `link`, `lookup` | `{ account, kind, identifier, meta?, confirmed? }` → id; `{ kind, identifier, requireConfirmed?, ttl?, totp? }` → вход или `null` |
 | `credentials`, `revokeCredential`, `setFlags` | `(account)` → креды без секретов; `(id, { keepCurrent? })`; `(id, { confirmed?, enabled? })` |
-| `sessionFor`, `refresh`, `revoke`, `revokeAll` | `(account, { ttl? })` → токен; `({ ttl? })` → новое время истечения (токен прежний); `()`; `(account?)` → число сессий |
+| `sessionFor`, `refresh`, `revoke`, `revokeAll` | `(account, { ttl? })` → токен; `({ ttl? })` → новое время истечения (токен прежний); `()` — выход подключения, `(token)` — выход пользователя по токену его сессии (право `auth.session`) → `boolean`; `(account?)` → число сессий |
 | `session` | `(token)` → `{ account, tenant, member, expiresAt, loginAt, methods }` или `null` |
-| `tenants`, `switch` | `()` → `[{ tenant, roles }]`; `(tenant)` |
+| `tenants`, `switch` | `()` → `[{ tenant, roles, name, personal }]` (первым — собственный, `personal: true`); `(tenant)` |
 | `purgeAccount` | `(account)` → `{ account, rows, versions, memberships, owned }` |
 
 Проверку паролей, кодов и TOTP, выпуск сессий, сведения о сессии по токену и подтверждение кредов вызывает сервис
@@ -2361,26 +2458,9 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 креды — нет; последний действующий ключ сервиса не отзывается никем (`acl_denied`). С `totp` вход `verifyPassword` и
 `lookup` проверяет ещё и код TOTP (право `auth.totp`) и выдаёт сессию со способом `TOTP`.
 Вид креда `kind` — `^[A-Z][A-Z0-9_]{1,31}$` (`PASSWORD`, `EMAIL`, `TELEGRAM` …); `SESSION`, `APIKEY`, `KEYSECRET`,
-`OTP`, `TOTP`, `KEY`, `PROJECTOR` и `LOCK` заняты. То же правило — у вида пароля `user.kind` в `createTenant` и
+`OTP`, `TOTP`, `KEY` и `LOCK` заняты. То же правило — у вида пароля `user.kind` в `createTenant` и
 `up({ tenant })`.
 
-### Проектор
-
-`db.projector(имя, опции)` работает только на администраторском подключении ([«Проекторы»](#проекторы)). Имя —
-строчные латинские буквы, цифры и `_.:-`, до 64 символов; оно же — `derivedBy` производных классов. Неверные опции —
-`invalid_data`.
-
-| Член | Что делает |
-|---|---|
-| опции `ProjectorOptions` | `from`, `into` — классы с потомками; `version` — целое от 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` — пачками); `batch` — изменений в пачке (500, от 1 до 10 000); `pollMs` — запасной опрос (1000 мс); `lockTimeout` — ожидание чужой блокировки строки (5000 мс, 0 — без предела); `lockRetries` — проходов подряд до выбывания арендатора с чужой блокировкой (0 — не выбывает); `tenants` — id арендаторов-участников |
-| `run({ once })` | догнать журнал (`once`) или следовать за ним до `stop()` → `ProjectorReport` |
-| `rebuild({ chunked, tenant })` | перестроить с текущего состояния: атомарно, пачками или одного арендатора → `ProjectorReport` |
-| `status()` | → `ProjectorStatus`: `{ name, state, version, cursor, at, lag, failed, rebuildingTenants }`; `failed` — `{ [id арендатора]: ProjectorFailure }`, где `ProjectorFailure` — `{ cursor, code, message }` |
-| `stop()`, `close()` | остановить `run()` после текущей пачки; то же и отписаться от сигналов |
-| `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds, locked }` |
-| `ProjectorChange` | `{ cursor, id, class, tenant, op, rev, at, author, row }` и, если есть, `agent`, `reason`, `moved`, `before`, `rebuild` |
-| `ProjectorOut` | `upsert(класс, строка, { tenant })`, `inc(класс, строка, приращения, { tenant })`, `delete(класс, ключ или id, { tenant })`, `get(класс, ключ или id, { tenant })` → `Row \| null`; строка — `ProjectorRow` в формате загрузчика; у класса с ключом `delete` и `get` — по ключу, id — только у класса без ключа |
-
 ### Строка ответа
 
 | Поле | Что значит |
@@ -2389,142 +2469,211 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `tenant`, `owner` | арендатор и владелец строки |
 | `links`, `data`, `tags` | концы, поля, теги |
 | `at`, `author`, `agent`, `op`, `reason` | время версии (ISO, UTC, микросекунды), автор, агент (сервис при имперсонации), вид операции, причина |
-| `moved` | связь со старым или новым id после `reclass` и `rekey` |
 | `$deleted` | надгробие: удалённая сущность или версия удаления |
 | `$depth` | глубина узла в `deep()`; уровень каскада в превью удаления |
-| `$upsert`, `$action`, `$versions`, `$purged` | что сделал `upsert`; что сделает удаление; число версий в `purge`; история стёрта |
+| `$upsert`, `$action` | что сделал `upsert`; что сделает удаление (`delete`, `unset`, `restrict`); `skip` — цель `restore({ expect, partial: true })`, которую не восстановить |
+| `$why` | у строки `$action: 'skip'` — почему: `restored`, `reissued`, `changed` ([«Восстановить: `restore`»](#восстановить-restore)) |
 
 ### Зарезервированные имена
 
-Имя метода закрывает класс только там, где этот метод есть: после шага — методы цепочки, у корня `db` — его методы,
-у батча — его. Поэтому хаб с именем метода только цепочки (например, `count`) доступен первым шагом `db.count(…)`, а
-после другого шага недостижим; хаб с именем метода корня первым шагом не вызвать. Связь с любым из этих имён база не
-примет (`reserved_names()`; список подставляет установщик из `RESERVED_CLASS_NAMES`). Не давайте классам эти имена.
+Имя метода закрывает класс там, где этот метод есть: после шага — методы цепочки, у корня `db` — его методы, у
+батча — его. Поэтому класс с любым из этих имён не создать: хаб отклоняют `hub()`, `syncModels` и база, связь — база
+(`invalid_class`; `reserved_names()`, список подставляет установщик из `RESERVED_CLASS_NAMES`). Хаб, заведённый мимо
+проверки базы, `up()` оставляет и называет в предупреждении: с именем метода только цепочки (например, `count`) он
+доступен первым шагом `db.count(…)`, а после другого шага недостижим.
 
 - методы цепочки: `then`, `entity`, `paths`, `rows`, `first`, `ids`, `count`, `limit`, `offset`, `sort`, `asOf`,
   `withDeleted`, `deep`, `exact`, `sum`, `avg`, `min`, `max`, `countBy`, `after`, `versions`, `create`, `update`,
-  `upsert`, `set`, `unset`, `add`, `remove`, `delete`, `anonymize`, `reclass`, `restore`, `purge`, `alias`, `tags`,
-  `owner`, `forUpdate`, `cache`, `rekey`, `diff`, `blame`; охранники снесённого API — `run`, `execute`, `account`;
+  `upsert`, `set`, `unset`, `add`, `remove`, `delete`, `restore`, `alias`, `tags`, `owner`, `forUpdate`, `cache`;
 - корень `db`: `as`, `begin`, `commit`, `rollback`, `lock`, `batch`, `watch`, `close`, `registry`, `sql`, `load`,
-  `verify`, `maintain`, `reset`, `describe`, `auth`, `acl`, `idOf`, `refresh`, `transaction`, `flushSignals`,
-  `schema`, `token`, `tenant`, `trimHistory`, `rekeyClass`, `cache`, `projector`, `rebuildAggregates`; охранники — `reloadSchema`,
-  `accounts`, `credentials`, `resources`, `rules`, `compact`;
-- батч: `discard`, `size`.
+  `maintain`, `auth`, `acl`, `idOf`, `refresh`, `transaction`, `flushSignals`, `schema`, `token`, `tenant`, `cache`;
+- батч: `run`, `discard`, `size`.
 
-## 16. Ошибки
+Имя роли конца одно на арендатора — это имя шага цепочки: во всех классах арендатора и System роль с одним именем
+ведёт на одни и те же классы. Поэтому заняты роли концов системных классов: `Group` и `Object` (класс `rule`) ведут на
+`Resource`, `User` и `Tenant` (класс `member`) — на `Account`. Конец с таким именем, который ведёт на другой класс,
+`syncModels` отклоняет до записи — `invalid_class` (`model.end_role_system`; роль другого своего класса —
+`model.end_role_taken`), а класс, заведённый мимо него, — база (`sql-write.end_other_class`). Имена классов `Group` и
+другие не заняты — заняты имена ролей: называйте роли иначе (`Team`, `Org`, `Holder`).
+
+## 15. Ошибки
 
 Текст ошибки — `letopis: <код>: <сообщение>`. Код — в `err.code`, подробности — в `err.detail`. Ошибки — объекты
-`LetopisError`, у ошибок данных — `ValidationError` с `err.issues: [{ path, keyword, message }]`.
+`LetopisError`, у ошибок данных — `ValidationError` с `err.issues: [{ path, keyword, message }]`. Ещё у ошибки есть:
+
+- `err.hint` — что делать: подсказка из каталога сообщений библиотеки, своя у места или общая у кода;
+- `err.docs` — ссылка на строку кода в этом разделе README на GitHub, по тегу версии пакета;
+- `err.key` и `err.params` — ключ каталога сообщений и параметры текста. Они есть у ошибок, собранных по ключу каталога:
+  у мест библиотеки и у ошибок базы, которая прислала ключ в `DETAIL`.
+
+Тексты ошибок — только на русском. Ошибку базы с ключом библиотека отдаёт с тем же текстом, что получает и сырой SQL
+мимо библиотеки, а ключ и параметры из `DETAIL` переносит в `err.key` и `err.params`. У ошибки данных (`invalid_data`)
+текст ещё называет первое нарушение и их число: `letopis: invalid_data: данные не проходят описание класса Order:
+status — значение не из перечисления: допустимо "new", "paid", "cancelled" (всего нарушений: 2, все — err.issues)`.
+Сообщение нарушения перечисления называет допустимые значения, лишнего ключа — сам ключ (`лишний ключ colour`).
+
+```ts
+const db = await connect({ dsn, schema: 'v2.shop', token })
+try {
+  await db.Shpo().rows()
+} catch (e) {
+  // e.code — 'invalid_class', e.params.similar — ['Shop']
+  // e.message — 'letopis: invalid_class: класс или роль Shpo не найдены — похожие: Shop'
+  // e.hint — что делать; e.docs — https://github.com/alepri51/letopis/blob/v<версия>/lib/README.md#invalid_class
+}
+```
+
+Похожие имена. Неизвестный класс или роль в цепочке — ошибка `invalid_class`, неизвестное поле в фильтре, `sort()` или
+агрегате — ошибка `invalid_query`, неизвестная опция `connect()`, `up()`, `db.load()`, `db.watch()` и
+`createMcpServer()` — ошибка `invalid_data`: похожие имена — в тексте и в `err.params.similar`.
+
+```ts
+try {
+  await db.Shop({ ctiy: 'Юг' }).rows()
+} catch (e) {
+  // e.code — 'invalid_query', e.key — 'query.unknown_field', e.params.similar — ['city']
+  // e.message — 'letopis: invalid_query: Shop({ ctiy }): поле ctiy не описано в классе Shop — похожие: city'
+}
+```
 
 Коды базы. Их получает и сырой SQL: SQLSTATE класса `LT`, подробности — JSON в `DETAIL`.
 
 | Код | SQLSTATE | Когда |
 |---|---|---|
-| `no_session` | LT001 | нет действующей сессии |
-| `target_not_found` | LT002 | цель не найдена — одинаково для несуществующей, чужой и невидимой |
-| `invalid_data` | LT003 | данные не проходят описание класса; `err.issues` — путь, ключевое слово, сообщение |
-| `undeclared_end` | LT004 | конец не объявлен в классе |
-| `tenant_denied` | LT005 | чужой арендатор или нет членства |
-| `acl_denied` | LT006 | отказ по правилам доступа |
-| `id_mismatch`, `id_from_db` | LT007, LT008 | id не равен v5 от ключа; id класса без ключа выдаёт база |
-| `immutable_key` | LT009 | ключевое поле, id, арендатор и владелец не меняются (новый ключ — `rekey`) |
-| `invalid_class` | LT010 | описание класса отклонено, класс не найден или абстрактный; класс со строками, потомками или историей строк не удаляется |
-| `use_reclass`, `reclass_denied` | LT011, LT012 | смена класса через `update`, когда у старого или нового класса есть ключ: id меняется, нужен `reclass()`; роли ссылающихся строк не принимают новый класс |
-| `tightening_conflict` | LT013 | ужесточению описания мешают строки |
-| `isolation_level` | LT014 | удаление, смена класса и ключа — только в `read committed` |
-| `recreated_in_statement` | LT015 | id удалён и создан заново одним оператором |
-| `cursor_expired` | LT016 | курсор подписки или проектора старше яруса `all` политики хранения |
-| `delete_restricted` | LT017 | удалению мешают ссылающиеся строки (`onDelete: 'restrict'`) |
-| `not_deleted` | LT018 | `restore` и `purge` — только для удалённых |
-| `reset_disabled` | LT019 | сброс выключен в установке (`allowReset`) |
-| `confirm_mismatch` | LT020 | подтверждение сброса не совпадает с именем схемы |
-| `derived_class` | LT021 | строку производного класса (`derivedBy`) пишет, правит или удаляет не его проектор; конец ведёт на такую строку или на производный класс; проектор пишет в класс вне своих `into` или не нашёл ни одного арендатора, у которого все классы `into` помечены его `derivedBy` |
-| `aggregate_field` | LT022 | приложение передало или изменило агрегатное поле (`aggregate`): его считает база |
-| `projector_pending` | LT023 | `purge` удалённого объекта, чьё удаление ещё не прочёл проектор его класса, или `trimHistory`, чью первую оставшуюся версию он ещё не прочёл: сначала `run()` проектора |
+| `no_session`<a id="no_session"></a> | LT001 | нет действующей сессии. У библиотеки ещё — `connect({ token })` с погашенным, истёкшим или неверным токеном: отклонённый промис, подключение не создаётся (`api.token_not_active`); то же — промисом терминала у шага, не найденного в реестре подключения по токену без арендатора сессии |
+| `target_not_found`<a id="target_not_found"></a> | LT002 | цель не найдена — одинаково для несуществующей, чужой и невидимой. `svc.as(id)` с id аккаунта, которого нет (не заводили или удалён), — ключ `sql-core.impersonation_no_account`: «аккаунт … не найден»; аккаунт есть, но действовать от его имени нельзя (System, сервис, системный администратор, выключен) — `acl_denied` (`sql-core.impersonation_denied`) |
+| `invalid_data`<a id="invalid_data"></a> | LT003 | данные не проходят описание класса; текст называет первое нарушение и их число, `err.issues` — все: путь, ключевое слово, сообщение. Ключ с именем конца в данных `create`, `upsert`, `update` — `write.link_in_data`: текст называет ключ и форму слота `.Роль.set(id)`. У библиотеки ещё — неизвестная опция `connect()`, `up()`, `db.load()`, `db.watch()` и `createMcpServer()` (похожие — в `err.params.similar`) и неверное значение опции |
+| `undeclared_end`<a id="undeclared_end"></a> | LT004 | конец не объявлен в классе |
+| `tenant_denied`<a id="tenant_denied"></a> | LT005 | чужой арендатор или нет членства |
+| `acl_denied`<a id="acl_denied"></a> | LT006 | отказ по правилам доступа |
+| `id_mismatch`, `id_from_db`<a id="id_mismatch"></a><a id="id_from_db"></a> | LT007, LT008 | id не равен v5 от ключа; id класса без ключа выдаёт база |
+| `immutable_key`<a id="immutable_key"></a> | LT009 | ключевое поле, класс, id, арендатор и владелец не меняются: другой ключ или класс — новый объект |
+| `invalid_class`<a id="invalid_class"></a> | LT010 | описание класса отклонено, класс не найден или абстрактный; класс со строками, потомками или историей строк не удаляется; хаб или связь с зарезервированным именем (хаб отклоняют ещё `hub()` и `syncModels`). Класс, который точно записан `syncModels`, «не найден» — сессия в другом арендаторе, и классы арендатора ей не видны: чаще всего пользователь после входа остался в личном арендаторе — проверьте `db.tenant`, нужен `svc.as(account, { tenant })` или `auth.switch(tenant)` ([«Работа в другом арендаторе»](#работа-в-другом-арендаторе)). Если в реестре сессии нет ни одного класса арендатора — ключ `api.unknown_step_no_classes`. Системные классы в похожие имена не идут. Ещё — модель с преобразованием Zod у `syncModels` (`model.transform_unsupported`, [«Поля»](#поля)) |
+| `tightening_conflict`<a id="tightening_conflict"></a> | LT013 | ужесточению описания мешают строки |
+| `isolation_level`<a id="isolation_level"></a> | LT014 | удаление — только в `read committed` |
+| `recreated_in_statement`<a id="recreated_in_statement"></a> | LT015 | id удалён и создан заново одним оператором |
+| `delete_restricted`<a id="delete_restricted"></a> | LT017 | удалению мешают ссылающиеся строки (`onDelete: 'restrict'`) |
+| `not_deleted`<a id="not_deleted"></a> | LT018 | `restore` — только для удалённых: объект жив и не удалялся (`write.not_deleted`), уже восстановлен — в том числе проигравшим гонку двух `restore()` (`write.restore_already`), или его id занял новый живой объект с тем же ключом — `create()` по ключу удалённого (`write.restore_id_taken`): место занято новым объектом, восстанавливать нечего. id — `err.detail.ids`, с `expect` причины по целям — `err.detail.stale` ([«Восстановить: `restore`»](#восстановить-restore)) |
 
 Коды библиотеки:
 
 | Код | Когда |
 |---|---|
-| `exists` | объект уже существует: `create` (`detail.id` — его id), `rekey` (новый id занят) или загрузчик |
-| `duplicate`, `deleted` | загрузчик: повтор id в загрузке; объект с этим id жил раньше. Загрузчик бросает код первой проблемной строки, первые 100 — в `detail.rows`, всего — `detail.total` |
-| `conflict` | `update(патч, { rev })`: строку успели изменить (`detail`: `id`, `rev`, `expected`) |
-| `rev_ambiguous` | `{ rev }` у шага, у которого не одна цель |
-| `tx_required` | `forUpdate()`, `lock()`, `commit()` или `rollback()` вне действующей `db.begin()` |
-| `lock_unsupported` | `forUpdate()` с агрегатом, `asOf`, `versions`, `withDeleted`, `deep` или глаголом |
-| `commit_unknown` | связь оборвалась во время `COMMIT`: исход неизвестен |
-| `tx_rolled_back` | PostgreSQL ответил `ROLLBACK` на `COMMIT`: ошибку перехватили внутри `tr.transaction(fn)` |
-| `no_key` | `upsert`, `rekey` или `idOf` у класса без ключа |
-| `no_path` | между классами соседних шагов нет перехода |
-| `invalid_query` | цепочку или API используют неверно (модификатор шага `deep`, `exact`, `alias`, `tags` или `owner` после глагола, модификатор выборки между глаголом и терминалом `rows`, `first`, `ids`, `count` или `paths`, слот не после глагола, курсор `after()` со значением не того типа, что поле `sort`, без `v` или с `id` не uuid и т. п.) |
-| `admin_required` | загрузчику, проектору и `rebuildAggregates` нужно администраторское подключение |
-| `rebuild_required` | проекция построена другой версией проектора (`version`): нужна перестройка `rebuild()`; `rebuild({ tenant })`, пока проекции нет или идёт перестройка пачками |
-| `projector_busy` | перестройку не начать: проектор сейчас работает в другом процессе |
-| `not_empty` | первая заливка (`initial`) — только в пустую схему |
-| `class_not_loadable` | строки `Class` загрузчик не принимает |
-| `bypass_rls` | `connect()` с ролью, которая обходит RLS, без `allowBypassRls`; `createMcpServer` с подключением в обход RLS |
-| `user_session_required` | `createMcpServer` и `letopis mcp`: нужна сессия пользователя — у подключения нет сессии, это корень сервиса без `as()`, сессия в арендаторе System без `allowSystemAdmin`, в командной строке ключ сервиса или нет токена |
-| `confirmation_required` | `letopis_write` (MCP): удаление без подтверждения человека — клиент без elicitation, человек отказал, ответ не к этой операции или данные изменились после превью |
-| `removed` | снесённое API 0.21; в тексте — замена |
+| `exists`<a id="exists"></a> | объект уже существует: `create` (`detail.id` — его id) или загрузчик |
+| `duplicate`, `deleted`<a id="duplicate"></a><a id="deleted"></a> | загрузчик: повтор id в загрузке; объект с этим id жил раньше. Загрузчик бросает код первой проблемной строки, первые 100 — в `detail.rows`, всего — `detail.total` |
+| `conflict`<a id="conflict"></a> | `update(патч, { rev })`: строку успели изменить (`detail`: `id`, `rev`, `expected`); `restore({ expect })`: после этого удаления id меняли — пересоздан и удалён снова, удалён снова (`write.restore_stale`, `detail`: `{ ids, stale: [{ id, rev, expected, after, deleted, live, why }] }`), ничего не восстановлено; `delete({ confirm: true, expect })`: превью изменилось (`write.preview_changed`, новое превью — `detail.preview`; цели уже удалены или не найдены при непустом `expect` — `detail.preview: []`), ничего не удалено |
+| `rev_ambiguous`<a id="rev_ambiguous"></a> | `{ rev }` у шага, у которого не одна цель |
+| `tx_required`<a id="tx_required"></a> | `forUpdate()`, `lock()`, `commit()` или `rollback()` вне действующей `db.begin()` |
+| `lock_unsupported`<a id="lock_unsupported"></a> | `forUpdate()` с агрегатом, `count()`, `paths()`, `versions()`, `asOf()`, `withDeleted()`, `deep()` или глаголом (`api.for_update_unsupported`): текст называет помеху — «forUpdate() нельзя с withDeleted(): блокировка — только у чтения rows(), first(), ids()», подсказка — допустимое и форма «прочитать `forUpdate().first()`, затем `update()` отдельной цепочкой» |
+| `commit_unknown`<a id="commit_unknown"></a> | связь оборвалась во время `COMMIT`: исход неизвестен |
+| `tx_rolled_back`<a id="tx_rolled_back"></a> | PostgreSQL ответил `ROLLBACK` на `COMMIT`: ошибку перехватили внутри `tr.transaction(fn)` |
+| `no_key`<a id="no_key"></a> | `upsert` или `idOf` у класса без ключа |
+| `no_path`<a id="no_path"></a> | между классами соседних шагов нет перехода |
+| `invalid_query`<a id="invalid_query"></a> | цепочку или API используют неверно (поле фильтра, `sort()` или агрегата не описано ни в одном классе шага — похожие в `err.params.similar`; `delete({ confirm: true })` без `expect` и без `all: true` (`write.confirm_without_expect`); `restore()` без `expect` и без `all: true`, в том числе по явному id (`write.restore_without_expect`); `update()` или `delete({ confirm: true, expect })` без фильтра, id, `tags()`, `owner()` и `limit()` у шагов и без `{ all: true }` (`write.no_filter`); `createTenant(admin, …)` с `admin` не пулом `postgres()` (`api.create_tenant_admin`); метод цепочки у результата `versions()` (`api.versions_terminal`), `after()` перед `count()` и агрегатами, модификатор шага `deep`, `exact`, `alias`, `tags` или `owner` после глагола, модификатор выборки между глаголом и терминалом `rows`, `first`, `ids`, `count` или `paths`, слот не после глагола, курсор `after()` со значением не того типа, что поле `sort`, без `v` или с `id` не uuid; id шага, `{ id }` или конца — не uuid (`query.bad_uuid`); свойство массива у цепочки — `.length`, `.map()`, `[0]`, перебор (`api.chain_not_rows`); `expect` без `confirm: true` или не списком строк `{ id, rev }`; `restore({ partial: true })` без `expect`, и с `all: true` тоже (`write.partial_without_expect`); `db.begin(аргумент)` — не объект опций `{ reason }`: функция, строка, число, массив (`api.begin_arg`); `withDeleted()` в цепочке записи, кроме `restore()`; значение не того типа в запросе — SQLSTATE `22P02` из базы, в том числе у `db.sql` (`api.db_bad_value`, исходная ошибка — `err.cause`) и т. п.) |
+| `admin_required`<a id="admin_required"></a> | загрузчику нужно администраторское подключение; роль строки `connect({ admin })` не может стать владельцем схемы; `up()` от роли без ADMIN OPTION на уже существующую роль владельца |
+| `not_empty`<a id="not_empty"></a> | первая заливка (`initial`) — только в пустую схему |
+| `class_not_loadable`<a id="class_not_loadable"></a> | строки `Class` загрузчик не принимает |
+| `bypass_rls`<a id="bypass_rls"></a> | `connect()` с ролью, которая обходит RLS, без `allowBypassRls`; `createMcpServer` с подключением в обход RLS |
+| `user_session_required`<a id="user_session_required"></a> | `createMcpServer` и `letopis mcp`: нужна сессия пользователя — у подключения нет сессии, это корень сервиса без `as()`, сессия в арендаторе System без `allowSystemAdmin`, в командной строке ключ сервиса или нет токена |
+| `confirmation_required`<a id="confirmation_required"></a> | `letopis_write` (MCP): удаление без подтверждения человека — клиент без elicitation, человек отказал, ответ не к этой операции или данные изменились после превью |
+| `internal`<a id="internal"></a> | внутренняя ошибка letopis: база не создала или не нашла свою строку-замок (из базы — SQLSTATE `XX000`, ключ в `DETAIL`); сообщите о ней с текстом, кодом и версией пакета |
 
 Отказ PostgreSQL в праве (`42501`) приходит, например, при `upsert` поверх чужой строки, которую нельзя править.
 
-## 17. Производительность
-
-Бенч 1.0 против 0.21 на одних полигонах (`cd lib && npx tsx bench/compare.bench.mjs`, 2026-10-09, PostgreSQL 18
-и 0.21 на PostgreSQL 17 с TimescaleDB, одна машина): salon — ~980 тыс. строк (в 0.21 — у System без изоляции,
-в 1.0 — в арендаторе под RLS и правами), tenants — 500 тыс. клиентов по 2 версии у десяти арендаторов.
-Цифры зависят от машины; важно соотношение.
-
-| Замер | 1.0 | 0.21 | Единица | Примечание |
-|---|---|---|---|---|
-| загрузка полигона salon | 6359 | 3609 | строк/с | 1.0 — загрузчик в режиме истории с проверками; 0.21 — сырые INSERT в Entity |
-| загрузка полигона tenants | 8566 | 35186 | строк/с | 0.21 — INSERT … SELECT с выключенными триггерами |
-| построчный create | 128 | 156 | строк/с |  |
-| чтение по ключу | 2.2 | 3.81 | мс (p50) |  |
-| цепочка из трёх шагов (count) | 222.79 | 1233.83 | мс (p50) | организация → мастера → записи |
-| запрос на дату (asOf) | 202.77 | 327.98 | мс (p50) | записи мастера на середину года |
-| 20 параллельных писателей | 982 | 522 | строк/с |  |
-| смена класса (reclass) | 9.5 | — | мс (p50) | в 0.21 глагола нет |
-| count() записей: арендатор под RLS и правами | 272.25 | 890.73 | мс (p50) | 0.21 — без изоляции и прав (enforceAccount: false); 1.0 без RLS (администратор): 18.59 мс |
-| count() клиентов арендатора 1 (50.0%) | 114.09 | 667.19 | мс (p50) |  |
-| count() клиентов арендатора 3 (10.0%) | 23.8 | 229.94 | мс (p50) |  |
-| count() клиентов арендатора 8 (1.0%) | 5.3 | 88.02 | мс (p50) |  |
-| count() клиентов арендатора 10 (0.3%) | 3.54 | 26.08 | мс (p50) |  |
-
-Полный импорт полигона salon из 0.21 (`npm run test:import-salon`): 539 580 объектов и 980 180 версий за 193 с
-(5 084 строки/с), счётчики по классам совпали, `verify()` чист. Доводка точки Б (ревизия 5): индекс журнала
-по целям ссылок `log_ends` ускорил срез `asOf` по переходу в 16 раз (3,37 с → 0,20 с) и стоит загрузчику
-15–17 % скорости; чтение `letopis.changed` и `COMMIT` одним конвейером сняло круг до базы с каждой записи (построчная
-запись: 119 → 128–147 строк/с в разных прогонах). Построчный `create` остаётся медленнее 0.21 на 12–18 % (замеры
-колеблются): основное время — триггеры проверок в базе и фиксация с записью на диск.
-
-Первая заливка (`cd lib && npx tsx bench/initial-load.mjs`, 2026-10-11, медиана трёх кругов): 1,07 млн объектов
-полигона salon без истории обычный загрузчик пишет за 169 с (6 351 строка/с, WAL 4,0 ГБ), первая заливка — за 77 с
-(13 902 строки/с, WAL 1,4 ГБ). Главную разницу дают индексы GIN: поддерживать их во время загрузки стоит 36 с, построить
-в конце — около 5 с. Подготовка строк в самом загрузчике (проверки, концы, id) идёт одновременно с `COPY` предыдущей
-пачки и теперь задаёт скорость: около 60 с из 77.
-
-Производные данные 1.2 (`cd lib && npx tsx bench/derived.bench.mjs`, 2026-10-27, PostgreSQL 18.6, одна машина; у
-агрегатов — медиана трёх кругов; строки проектора — повтор серий 2 и 3 после свёртки `inc` в `out`,
-`BENCH_SERIES=2,3`):
-
-| Замер | 1.2 | Для сравнения |
+**Отказы безопасности по умолчанию и неверного использования.** Ключи, которые приходят до записи и до запроса — их
+исправляют в коде, а не показывают пользователю:
+
+| Ключ | Код | Когда | Что делать |
+|---|---|---|---|
+| `write.confirm_without_expect` | `invalid_query` | `delete({ confirm: true })` без `expect` и без `all: true` | показать превью `delete()` и удалить с ним: `delete({ confirm: true, expect: превью })`; без сверки — осознанно `{ confirm: true, all: true }` |
+| `write.restore_without_expect` | `invalid_query` | `restore()` без `expect` и без `all: true`, в том числе по явному id | `restore({ expect })` с ответом `delete()` или строками `withDeleted().rows()`; что можно — `restore({ expect, partial: true })`; всё без сверки — осознанно `restore({ all: true })` |
+| `api.create_tenant_admin` | `invalid_query` | `createTenant(admin, …)`: `admin` — строка DSN, подключение `connect()`, `undefined` или другой не пул | `const admin = postgres(ADMIN); await createTenant(admin, schema, opts); await admin.end()` |
+| `api.versions_terminal` | `invalid_query` | метод цепочки у результата `versions()`: `versions().rows()`, `.sort()`, `.limit()` | `await db.X(id).versions()`; модификаторы — до `versions()` |
+| `write.link_in_data` | `invalid_data` | имя конца (связи) в данных `create()`, `upsert()`, `update()` | конец — из пути или слотом после глагола: `.Роль.set(id)`, у списка — `.add(id)` / `.remove(id)`, снять — `.unset()` |
+| `sql-core.impersonation_no_account` | `target_not_found` | `svc.as(id)`: аккаунта нет — не заводили или удалён | id аккаунта — из входа, `createTenant()` или `auth.tenants()` |
+
+**Текст для человека.** Штатные отказы — ответ пользователю, а не 500. Фразу выбирают по `err.key`, если он есть, иначе
+по `err.code`; `err.message` и `err.hint` — для разработчика и журнала:
+
+| Код (ключ) | Пользователю |
+|---|---|
+| `exists` | «уже существует» / «уже занято» |
+| `conflict` | «данные изменил другой — обновите и повторите»; `write.preview_changed` — показать новое превью; `write.restore_stale` — «после удаления запись меняли» |
+| `not_deleted` | `write.restore_already` — «уже возвращено»; `write.restore_id_taken` — «место занято новой записью»; `write.not_deleted` — «не удалено» |
+| `target_not_found` | «не найдено: удалено или недоступно» |
+| `delete_restricted` | «нельзя удалить: на запись ссылаются» (строки — превью с `$action: 'restrict'`) |
+| `acl_denied`, `tenant_denied` | «недостаточно прав», «нет доступа к организации» |
+| `no_session` | «сессия истекла — войдите снова» |
+| `invalid_data` | по `err.issues`: своё название поля по `path`, фраза по `keyword` (ниже) |
+
+**Значение не того типа (SQLSTATE `22P02`).** Неверный id в цепочке библиотека ловит сама, до запроса:
+`invalid_query`, ключ `query.bad_uuid`. Что дошло до базы — `'42'::uuid` в `db.sql`, `db.transaction(fn)` или
+`tr.sql`, — приходит `LetopisError` с кодом `invalid_query` и ключом `api.db_bad_value`; текст называет, какое
+значение не подошло, исходная ошибка PostgreSQL — в `err.cause`:
+
+```ts
+try {
+  await db.sql`select ${'42'}::uuid`
+} catch (e) {
+  // e instanceof LetopisError, e.code === 'invalid_query', e.key === 'api.db_bad_value'
+  // e.message — 'letopis: invalid_query: значение не того типа: invalid input syntax for type uuid: "42"'
+  // (e.cause as { code: string }).code === '22P02' — исходная ошибка PostgreSQL
+}
+```
+
+SQLSTATE, если он нужен, берут из `err.cause.code`.
+
+**Текст для пользователя из `err.issues`.** У `ValidationError` каждое нарушение — `{ path, keyword, message }`:
+`path` — путь к полю (`[]` — данные целиком), `keyword` — правило JSON Schema (`type`, `required`, `minimum`, `enum`,
+`pattern`, `additionalProperties` …), `message` — русский текст для разработчика: у перечисления он называет
+допустимые значения, у лишнего ключа — сам ключ, у `minLength` и `maxLength` — предел («длина строки меньше 3», «длина
+строки больше 40»), у прочих правил бывает общим («нарушено правило minimum»). Пользователю
+показывают свои названия полей и свои фразы по `keyword`, а `message` — запасной текст:
+
+```ts
+import { ValidationError } from 'letopis'
+
+const LABELS: Record<string, string> = { price: 'Цена', title: 'Название', sku: 'Артикул' }
+const RULES: Record<string, string> = { required: 'обязательно', minimum: 'слишком мало', type: 'неверный формат' }
+function explain(e: ValidationError): string[] {
+  return e.issues.map((i) => {
+    const field = i.path.length ? (LABELS[String(i.path[0])] ?? i.path.join('.')) : 'Данные'
+    return `${field}: ${RULES[i.keyword] ?? i.message}`   // «Цена: слишком мало»
+  })
+}
+```
+
+**Предупреждения.** Часть ошибок использования — не отказ, а предупреждение в консоли: шаг с `undefined`, шаг после
+`sort()`, `withDeleted()` не у того шага ([«Строгий режим»](#строгий-режим)). При включённом журнале каждое
+предупреждение — ещё и событие `warning`, а каждая ошибка — событие `error` с кодом, ключом и цепочкой
+([«Логирование»](#логирование)).
+
+## 16. Производительность
+
+Замеры — сценарии `lib/bench/` (как запускать, написано в шапке каждого файла), итоги — `lib/bench/results/`. Ниже —
+серии `core-*` (замеры 8 октября 2026 года: PostgreSQL 18.6 в Docker, `shared_buffers` 128 МБ, Node.js 24) и
+чтение цепочкой `chain-read` на тех же данных, что у `core-read`. Цифры зависят от машины; важно соотношение.
+
+| Что меряли | Серия | Итог |
 |---|---|---|
-| операция с агрегатом, один писатель | 94 операции/с, p50 10,7 мс | без агрегата — 137 и 6,9 мс; рецепт с `inc` — 69 |
-| операции одного кошелька с агрегатом, 20 писателей | 152 операции/с, p95 0,47 с | без агрегата — 1 987; рецепт с `inc` — 190 |
-| операции 20 кошельков с агрегатом, 20 писателей | 1 379 операций/с | без агрегата — 2 023 |
-| догонка проектора, `out.inc` на каждое изменение | 6 076 и 33 395 изменений/с (`batch` 500 и 2000) | до свёртки `inc` в `out` — 992 и 1 203 |
-| перестройка 75 тыс. строк | атомарная — 13,3–13,5 с, пачками — 13,0–13,2 с | до свёртки `inc` в `out` — 101 с и 58–63 с |
-| задержка события подписки во время перестройки | атомарной — до 13,4 с, пачками — до 0,21 с | без перестройки — до 0,12 с |
+| Вставка через триггеры по строке, транзакция на строку | `core-write`, 10 000 строк | около 170 строк в секунду; без ожидания записи на диск при фиксации (`synchronous_commit = off`) — около 470 |
+| Та же вставка пачками по 1 000 строк в одном операторе (так склеивает подряд идущие `create` батч) | `core-write`, 10 000 строк | около 1 350 строк в секунду: 731 мкс на строку, из них проверка концов — около 330, журнал — 150, сигнал — 90, проверка данных — 45, RLS — меньше 10; та же вставка без триггеров — 99 мкс |
+| `COPY` от роли владельца и проверка концов одним запросом в конце (прототип загрузчика) | `core-write`, `core-load` | 10 000 строк — около 14 000 в секунду; миллион — за 92 с (около 10 800 в секунду) против 75 с у `COPY` в таблицы без триггеров; запрос по целям в конце — 0,1 с при 1 000 целей и 1,2 с при 100 000 |
+| Горячая строка: операция и `inc` итога одной транзакцией | `core-concurrency`, замер 11 | одно соединение — около 150 операций в секунду, 5 — 325, 20 — 230 (95-й процентиль — 290 мс), 50 — 154 (около 1 с); итог через `{ rev }` с повторами при 20 соединениях — 72 (23 тыс. повторов), через блокировку строки — 144 |
+| Двадцать писателей строк со ссылкой на одну цель | `core-concurrency`, замер 2; `core-notify` | с `NOTIFY` в транзакции записи — около 580 строк в секунду, без него — 2 900: фиксации с `NOTIFY` идут по одной. Сигналы отдельной транзакцией (так их шлёт библиотека, [«Сигналы»](#сигналы)) — 2 800 |
+| Чтение цепочкой из трёх шагов с фильтром по `data` под RLS: два арендатора, у каждого 1 000 организаций, 100 тыс. мастеров и миллион смен | `chain-read` | узкий запрос (143 строки) — 24 мс, владелец без RLS — 19 мс; широкий (14 285 строк) — 3,1 с против 2,9 с |
+| Срез `asOf` по журналу | `core-read`, замер 7 | 51 мс под RLS, 50 мс у владельца |
+| Каскадное удаление организации с мастерами одним `delete` | `core-delete` | 100 тыс. строк — 23 с, миллион — 247 с (около 240 мкс на строку); временные файлы — 80 и 800 МБ |
+| id v5 против последовательных | `core-ids`, 10 млн строк | v5 ложатся в индекс вразброс: вставка в 3,4 раза медленнее (135 тыс. строк в секунду против 465 тыс.), индекс на 27 % и WAL на 39 % больше; вычисление v5 в базе — 11 мкс |
+| Проверка данных в базе (jsonpath) | `core-validate`, 100 тыс. строк | 35 мкс на строку у плоского описания из пяти полей, 113 мкс — у вложенного глубины 4; у модели, где регулярных выражений больше 32, — 1,6 мс (PostgreSQL держит в памяти процесса 32 скомпилированных выражения) |
 
-Триггеры агрегатов срабатывают на каждом операторе записи, но у классов без агрегатов их цены замер не видит: разница
-p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101.bench.mjs`, четыре прогона) регрессий записи и чтения
-против 1.1 не показал: два выброса не повторились в отдельных проверках.
+Построчная запись дороже простой вставки: основное время — проверки в базе и фиксация с записью на диск. Поэтому
+подряд идущие `create` склеивает батч ([раздел 8](#батч)), массовую запись ведёт загрузчик, а первая заливка в пустую
+схему строит индексы, ограничения и триггеры разом в конце ([раздел 9](#9-массовая-загрузка)).
 
-## 18. Ограничения
+## 17. Ограничения
 
-Здесь собрано то, что letopis 1.4 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
+Здесь собрано то, что letopis 3.0 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
 
 **Платформа**
 
@@ -2545,50 +2694,60 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 
 **Запись и целостность**
 
-- Построчная запись дороже простой вставки: каждую строку проверяют триггеры (данные, концы, id, журнал, хэш, RLS).
-  Построчный `create` медленнее 0.21 на 12–18 % ([раздел 17](#17-производительность)); для массовой записи есть
-  загрузчик.
-- Удаление, смена класса и смена ключа работают только в `read committed` (`isolation_level`); транзакции
-  библиотеки всегда открываются на этом уровне.
+- Построчная запись дороже простой вставки: каждую строку проверяют триггеры (данные, концы, id, журнал, RLS).
+  Построчная вставка через триггеры, транзакция на строку, — около 170 строк в секунду
+  ([раздел 16](#16-производительность)); подряд идущие `create` склеивает батч, для массовой записи есть загрузчик.
+- Удаление работает только в `read committed` (`isolation_level`); транзакции библиотеки всегда открываются на этом
+  уровне.
 - `COPY` в таблицы под RLS PostgreSQL не выполняет; массовая загрузка — только загрузчиком на администраторском
   подключении.
 - Первая заливка закрывает таблицы схемы на всё время загрузки — и для записи, и для чтения: она для пустой схемы
-  (засевка, перенос, импорт), а не для работающей системы. Выигрыш у неё — в базе (индексы и ограничения строятся
+  (засевка, перенос данных), а не для работающей системы. Выигрыш у неё — в базе (индексы и ограничения строятся
   один раз); подготовку строк в загрузчике она не ускоряет, а только ведёт одновременно с `COPY`, поэтому на миллионе
   объектов она быстрее обычной загрузки примерно в 2,2 раза.
 - Загрузчику база доверяет: данные, концы и id загруженных строк проверяет код библиотеки (валидатор на TypeScript),
-  а не триггеры; база сверяет только цели вне загрузки, арендаторов и владельцев одним запросом в конце.
-  Защита — загрузчик только у администратора, дифференциальные тесты валидатора против базы, `load({ verify: true })`
-  и `db.verify({ data: true })`. Администраторское подключение держит отдельный процесс загрузки, а не
-  веб-приложение: SQL-инъекция в нём получила бы права владельца.
-- Владелец схемы и суперпользователь могут отключить триггеры и изменить что угодно. letopis это не предотвращает,
-  а обнаруживает: `verify()` пересчитывает цепочки хэшей, `verify({ data: true })` перепроверяет строки, а якорь
-  (хэш всех голов цепочек) стоит хранить вне базы.
-- В базе проверяется подмножество JSON Schema: `refine`, `superRefine` и `transform` Zod работают только
-  в библиотеке, описание с неизвестным ключевым словом база не примет; `pattern` — ограниченное подмножество
+  а не триггеры; база сверяет только шаблоны `pattern` — запросом на пачку до записи — и цели вне загрузки,
+  арендаторов и владельцев одним запросом в конце.
+  Защита — загрузчик только у администратора и дифференциальные тесты валидатора против базы. Администраторское
+  подключение держит отдельный процесс загрузки, а не веб-приложение: SQL-инъекция в нём получила бы права владельца.
+- Владелец схемы и суперпользователь могут отключить триггеры и изменить что угодно, в том числе журнал: letopis
+  этого не предотвращает и не обнаруживает. Журналу можно верить, пока роль владельца и суперпользователь — вне
+  приложения.
+- В базе проверяется подмножество JSON Schema: `refine` и `superRefine` Zod база не исполняет (они в `lost` у
+  `syncModels`), преобразования Zod (`.trim()`, `.transform()` …) `syncModels` отклоняет, описание с неизвестным
+  ключевым словом база не примет; `pattern` — ограниченное подмножество
   регулярных выражений, общее для Zod, валидатора и базы. Вывод `z.toJSONSchema()` меняется между версиями Zod:
   в базе хранится уже нормализованная схема, а сухой прогон `syncModels` показывает разницу до применения.
 - Ключ — единственный способ уникальности: id вычисляется из значений ключа без нормализации, поэтому одно
   значение в разной записи (email в разном регистре, время с миллисекундами и без) даёт разные id. Формат
   ключевого поля задаёт модель, и база его проверяет.
-- Частая смена значения ключа (email, телефон) требует `rekey`. Изменчивые и персональные значения лучше выносить
-  в отдельный хаб со связью: id из email подбирается перебором и остаётся в ссылках и журнале даже после
-  `anonymize`, а отдельный хаб удаляется вместе со связью через `purge`.
+- Ключ и класс объекта неизменны: смена значения ключа (email, телефон) — новый объект. Изменчивые и персональные
+  значения лучше выносить в отдельный хаб со связью: id из email подбирается перебором и остаётся в ссылках и
+  журнале, а версии журнала не стираются (кроме удаления аккаунта вместе с его арендатором).
+- `create()` по ключу удалённого объекта занимает его id: прежний объект после этого не восстановить
+  (`restore({ expect })` — `not_deleted`, `write.restore_id_taken`, пока новый объект жив; когда удалён и он, —
+  `conflict`, `write.restore_stale`). Что ключ принадлежит удалённому, показывает `withDeleted()` перед `create()`.
+- `restore()` не проверяет бизнес-правила приложения, только описание класса, концы, ключ и права.
 - `create` занятого ключа отвечает `exists` с id, `upsert` без права на существующую строку — отказом `42501`:
   так раскрывается, что ключ занят, но только внутри своего арендатора — у других арендаторов те же ключи дают
   другие id.
-- Смена класса и ключа переписывает все входящие ссылки (и рекурсивно — связи, в ключ которых входит этот конец),
-  поэтому её цена пропорциональна числу ссылок. Ужесточение описания класса и `rekeyClass` на время проверки или
-  переноса приостанавливают запись в семейство.
-- `rekeyClass` переносит строки одной транзакцией под исключительной блокировкой семейства, а не пачками:
-  между пачками строки со старыми id нарушали бы правило «id — v5 от ключа».
+- Ужесточение описания класса на время проверки строк приостанавливает запись в семейство.
 - id v5 ложатся в индекс первичного ключа вразброс; на очень больших таблицах с интенсивной вставкой это заметнее,
   чем с последовательными id.
 - Горячие цели ссылок (организация, на которую ссылается почти всё) копят блокировки `for key share` и MultiXact,
-  как при обычных внешних ключах; это нужно мониторить. Операции одного кошелька идут друг за другом под
-  блокировкой его строки ([раздел 8](#8-транзакции-батчи-и-деньги), «Рецепт: кошелёк»).
-- Связь не может называться зарезервированным именем, а хаб с таким именем доступен не везде: например, `count` —
-  только первым шагом ([«Зарезервированные имена»](#зарезервированные-имена)).
+  как при обычных внешних ключах; это нужно мониторить. Приращения и правки одного объекта идут друг за другом под
+  блокировкой его строки ([раздел 8](#8-транзакции-и-батчи), «Значение из прочитанного и повтор операции»).
+- Класс не может называться зарезервированным именем ([«Зарезервированные имена»](#зарезервированные-имена)): хаб
+  отклоняют `hub()`, `syncModels` и база, связь — база. Хаб, заведённый мимо проверки базы, доступен не везде:
+  например, `count` — только первым шагом.
+- Строгие типы есть только у подключения с моделями (`TypedDb`): `db.as()`, `db.begin()`, `db.batch()`, `entity()` и
+  `loose(db)` отдают цепочки без них. Неизвестное поле в фильтре, `sort()` или агрегате у них ловит проверка во время
+  выполнения — `invalid_query` до запроса ([«Строгий режим»](#строгий-режим)), но только по первому ключу пути: опечатку
+  внутри поля-объекта (`{ address: { ctiy } }`) не ловит ничто, условие просто ничего не найдёт.
+- Поля сверяются с описаниями классов в реестре подключения. Поле, которое другой процесс только что добавил в
+  описание, до обновления реестра (сигнал изменения класса или `db.refresh()`) — тоже `invalid_query`, как и новый
+  класс. Срезы `asOf()`, `withDeleted()` и `versions()` сверяются с нынешним описанием: поле, которое из описания
+  убрали, в фильтре старых версий — отказ.
 
 **Доступ**
 
@@ -2605,9 +2764,9 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 - Самостоятельная привязка занятого идентификатора отвечает `acl_denied` — пользователь с недавним входом так
   узнаёт, что идентификатор занят. Изменения прав во всех арендаторах упорядочены одной строкой счётчика.
 - Тексты отказов называют класс, роль и id ссылающейся строки, только если актор её видит: каскад удаления, снятие
-  конца, перевод ссылок при смене класса и ключа, конфликт смены `parent` (`tightening_conflict`). Число невидимых строк, мешающих удалению или смене класса
-  (`reclass_denied`), и существование аккаунта по id (как цели ссылки) не скрываются.
-- Ужесточение описания класса и `rekeyClass` проверяют все строки семейства, поэтому требуют права `READ` без условий
+  конца, конфликт смены `parent` (`tightening_conflict`). Число невидимых строк, мешающих удалению, и существование
+  аккаунта по id (как цели ссылки) не скрываются.
+- Ужесточение описания класса проверяет все строки семейства, поэтому требует права `READ` без условий
   на все строки класса и его потомков: иначе пробное ужесточение (`maximum`, `enum`, `pattern`) отвечало бы числом
   невидимых строк, которые ему не соответствуют. Системный администратор, ужесточая класс System, получает число
   нарушающих строк других арендаторов (`others`): это уровень установки.
@@ -2615,26 +2774,24 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 - Прикладная роль может замедлить установку для всех: `LOCK TABLE entity`, advisory-блокировки с ключами `lock()`
   приложения, поддельные сигналы `NOTIFY` (лишь сбрасывают кэш), частая смена прав (одна строка счётчика на
   установку). По глобальному номеру журнала видна общая активность записи. Внутренние блокировки — семейства
-  классов, проектора и обслуживания — строки таблицы `secret`, а не advisory: ни прикладная, ни посторонняя роль базы
+  классов и обслуживания — строки таблицы `secret`, а не advisory: ни прикладная, ни посторонняя роль базы
   их не займёт. Писатель семейства проходит шлюз ужесточения в подтранзакции — одной на первую запись в семейство за
   транзакцию.
 
 **История, сигналы, кэш**
 
-- Срез `asOf` восстанавливается из журнала; дёшево только текущее состояние. В прореженной части журнала срез
-  показывает последнюю сохранённую версию до момента: его точность там равна периоду яруса — дню, неделе, месяцу
-  или году. Импорт истории в класс с политикой прореживается сразу, и подписчик может не увидеть старые версии.
-- Прореженная часть журнала не доказывает ни полноты истории, ни подлинности старых версий: подмену версии
-  старше яруса `all` у класса с политикой `verify()` не отличит от прореживания.
-- Журнал без партиций: прореживание удаляет версии пачками, файл таблицы сам не уменьшается (место занимают новые
-  версии после autovacuum); вернуть место системе — `VACUUM FULL` или `pg_repack` в окно обслуживания.
+- Срез `asOf` восстанавливается из журнала; дёшево только текущее состояние.
+- Журнал без партиций и хранит каждую версию: прореживания, обрезки и стирания истории объекта нет, версии стирает
+  только удаление аккаунта вместе с его арендатором. Классу, чья история не нужна, — `history: false`.
+  Место удалённых версий файл таблицы сам не отдаёт (его занимают новые версии после autovacuum); вернуть место
+  системе — `VACUUM FULL` или `pg_repack` в окно обслуживания.
 - Сигналы раскрывают активность: слушать канал PostgreSQL разрешает любой роли. В режиме `class` видно, когда и в
   какие классы пишут; `tenant` добавляет псевдонимы арендаторов; `opaque` прячет, что записано, но не когда: время и
   частоту записи по псевдониму видно, а детерминированный токен — основа частотных атак. Время записи видно и без
   сигналов: `pg_stat_all_tables` и `pg_locks` открыты для PUBLIC. Режим `none` убирает сигналы, но тогда отзыв
   сессии действует в кэше других процессов только по сроку, а новый класс появляется в их реестре в течение
   5 секунд. Настоящая защита от посторонних ролей — отдельная база. Поддельный сигнал лишь сбросит кэш лишний раз:
-  по `*` и незнакомым токенам реестр перечитывается не чаще раза в 5 секунд, а поддельный сигнал изменения классов
+  по незнакомым токенам и нагрузке не своего режима реестр перечитывается не чаще раза в 5 секунд, а поддельный сигнал изменения классов
   перечитывает его, как настоящий, но не больше одного перечитывания одновременно.
 - Режим сигналов меняется `up({ signals })`, и после этого нужно перезапустить процессы: режим и ключ сигналов
   процесс читает при подключении (нагрузку другого режима он считает чужой и сбрасывает весь кэш).
@@ -2656,47 +2813,6 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 - Курсор подписки «с этого момента» несёт снимок момента подписки, пока не пройдёт его границу: такой
   курсор длиннее обычного.
 
-**Проекторы**
-
-- Проектор — процесс администратора: он работает только на администраторском подключении, читает журнал всех
-  арендаторов в обход RLS и пишет результаты от роли владельца. Держите его в отдельном процессе, как загрузчик.
-  Участник проектора — арендатор, у которого все классы `into` помечены его `derivedBy`; пометить класс может только
-  администратор (право `letopis.projector`).
-- Итоги производного класса видит каждый, кому правила арендатора дают `READ` на него, — даже тот, кто не читает
-  строки источников: решайте, кому его читать, правилами на сам производный класс. С `history: true` его журнал
-  показывает изменение каждой пачки, то есть и вклад отдельных строк источников.
-- Строки производных классов пишет только их проектор: приложение, сырой SQL и загрузчик получают `derived_class`, а
-  ссылаться на такие строки концами нельзя.
-- Атомарная перестройка — одна долгая пишущая транзакция: пока она идёт, горизонт подписок стоит, и события
-  задерживаются у подписчиков и проекторов всех процессов. На машине замеров перестройка 75 тысяч строк шла 13 с, и
-  до её конца подписчик не получил ни одного события. Поэтому сам `run()` перестраивает пачками, а атомарную
-  перестройку запускает только явный `rebuild()`.
-- Перестройка пачками держит горизонт только на время пачки (в тех же замерах события задерживались до 0,2 с), но
-  до её конца производные данные неполные: строки удалены сразу и появляются по мере перестройки.
-- Проектор видит только изменения из журнала, поэтому класс с `history: false` источником быть не может: арендатор
-  с таким источником выбывает из проектора (`invalid_class`), пока журнал класса не включат и арендатора не
-  перестроят.
-- Прореживание журнала старше яруса `all` ведёт к перестройке: проектор, отставший больше чем на этот ярус,
-  получает `cursor_expired` или, с `onExpired: 'rebuild'`, перестраивается сам. Ярус — по арендатору: истёк только у
-  части участников — выбывают и перестраиваются только они.
-- Проектор работает только на схеме той ревизии движка, которую ждёт библиотека; на схеме другой ревизии он
-  отвечает `invalid_data`.
-- `purge()` ждёт проекторов: пока проектор, чьи источники включают класс объекта, а у арендатора объекта есть его
-  производный класс, не прочёл удаление, `purge` отвечает `projector_pending`. Проектор, который больше не запускают,
-  держит `purge` своих источников, пока у арендатора есть его производные классы: запустите его или удалите их.
-  Так же ждёт `trimHistory`: пока проектор не прочёл первую оставшуюся версию, обрезка отвечает `projector_pending`.
-
-**Агрегаты в базе**
-
-- Агрегат выстраивает писателей одного объекта в очередь: каждая операция блокирует строку цели и пишет её версию.
-  На машине замеров 20 писателей одного кошелька с агрегатом делали 152 операции в секунду (p95 — 0,47 с), без
-  агрегата — 1 987. Для горячих счётчиков берите проектор со свёрткой пачкой.
-- `reclass` и `rekey` копят вклады до конца переноса, а каскад удаления и загрузчик применяют их по операторам:
-  правило класса проверяется на итоге каждого оператора каскада и каждой пачки загрузчика. Поэтому загрузка, где
-  списания идут пачкой раньше пополнений, получит `invalid_data`, хотя итог всей загрузки допустим. Каждая пачка,
-  задевшая цель, пишет её версию.
-- Агрегат арендатора не считает строки класса System, а поле строки System считает только источники System.
-
 **Агенты и MCP**
 
 - Обёртка `<untrusted-data-…>` — смягчение, а не защита: модель может последовать тексту внутри неё. Защищают права
@@ -2710,19 +2826,11 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
   удаление по нему отклоняется (`confirmation_required`). Удаляйте по stdio или в ревизии 2026-07-28.
 - Подтверждение в ревизии 2026-07-28 подписано ключом процесса: повтор вызова, попавший в другой процесс приложения
   (несколько экземпляров за балансировщиком), получает отказ `confirmation_required`.
-- `versions` отдаёт последние версии в пределах `maxRows` и `maxBytes` (из базы — не больше `maxRows` + 1 версий) и
-  `more`; более ранние — `diff` и `blame` с `from`, `to`, `at`. Режим, в котором агент пишет код против API (code
-  mode), в пакет не входит.
-
-**Импорт из 0.21**
+- `letopis_history` отдаёт последние версии в пределах `maxRows` и `maxBytes` (из базы — не больше `maxRows` + 1
+  версий) и `more`; состояние на более ранний момент — `letopis_query` с `asOf`. Режим, в котором агент пишет код
+  против API (code mode), в пакет не входит.
 
-- 1.0 — новая major-версия, а не продолжение 0.21: `count()`, `paths()`, `create`, роли, множественные концы
-  и `reclass` ведут себя по-новому, данные переносятся импортом ([MIGRATION.md](MIGRATION.md)).
-- Импорт: шаги (классы, аккаунты, креды, права, данные каждого арендатора) — отдельные транзакции, источник
-  читается в память целиком; владелец строки, не найденный среди аккаунтов, становится арендатором; правила доступа
-  0.21 переносятся в System и действуют во всех арендаторах; `onDelete` концов — `cascade`, как удаляла 0.21.
-
-## 19. Тесты
+## 18. Тесты
 
 Раздел — для тех, кто развивает сам letopis. Запуск: `cd lib && npm test`. Обвязка сама поднимает контейнер `letopis-pg18` (`postgres:18`,
 порт 15433), если база не отвечает; каждый тестовый файл работает в своей схеме `v2.t_<имя>`.
@@ -2734,67 +2842,81 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 исправления называется пунктом тест-плана («план 2.0, 7.3 №1») и без исправления падает.
 
 ```
-# connect — подключение под сессией, отказ ролям в обход RLS, реестр, отложенный сигнал, перевод ошибок (этап 2)
+# connect — подключение под сессией, отказ ролям в обход RLS, реестр, отложенный сигнал, перевод ошибок (этап 2); сессия, истёкшая по простою: по ключу — обмен заново с прежним арендатором, по токену — no_session вместо пустого чтения (ревью сервисов)
 # context — сессии, вход сервиса по ключу, политики RLS этапа 1 (этап 1)
 # access-rest — оставшиеся строки этапа 5: загрузка от имени пользователя, баланс №20, 22, 29, upsert и { rev } под ACL, встраивание acl_ok (этап 5)
-# aggregate — агрегаты в базе: 20 писателей одного кошелька, сырой SQL, каскад, reclass, restore, загрузчик, удаление аккаунта, restore и rekey цели, смена описания под записью и гонка №18, aggregate_field, ремонт и verify, строка System (план 1.1, этап 4б)
-# acl — права ACL: перенос набора 0.21, условия на строки, вес и запрет по умолчанию, каскад, запрет на потомке, deep, невидимая цель, сырой SQL против библиотеки; смена parent и alias класса — только с правами на все его строки, алиас — не имя другого класса, имя — не чужой алиас (этап 5; ревью безопасности №2)
-# acl-parity — 1000 случайных наборов правил: план прав и решения по эндпоинтам базы против decide 0.21 (этап 5)
+# acl — права ACL: решение одним правилом, условия на строки, вес и запрет по умолчанию, каскад, запрет на потомке, deep, невидимая цель, сырой SQL против библиотеки; смена parent и alias класса — только с правами на все его строки, алиас — не имя другого класса, имя — не чужой алиас (этап 5; ревью безопасности №2)
+# acl-grant — обёртка прав db.acl: grant, deny, revoke, roles и list идемпотентны, их соблюдает база поверх «можно всё», при равном весе запрет сильнее, условие $actor, api, транзакция db.begin(), invalid_data до записи (план 2.0, 7.9 №1); everyone — правила для всех аккаунтов, revoke({ everyone: true, … }) снимает «можно всё»; list() на администраторском подключении — только арендатор сессии, enabled; администраторское подключение пишет правила арендатора без «можно всё» — без target_not_found (агентский прогон, этап 3, п. 9); check() — отказ правила сида «запрет по умолчанию»
+# acl-parity — 1000 случайных наборов правил: план прав и решения по эндпоинтам базы против эталона decide из lib/test/oracle (этап 5)
 # auth — креды (пароль, ключ, ключ + секрет, OTP, TOTP, identity), выравнивание времени, регистр, гашение сессий, недавний вход (этап 5)
 # balance — пополнение и списание: идемпотентность по opId, гонки, взаимная блокировка, обрыв связи (TCP-прокси), корректировка под { rev } и forUpdate (этап 4)
-# chain-api — охранники снесённого API, зарезервированные имена, ошибки построения, кэш плана, onQuery (этап 3)
+# chain-api — зарезервированные имена, ошибки построения, кэш плана, onQuery (этап 3)
 # chain-read — цепочки чтения на демо-домене: переходы, роли, множественные концы, 18 операторов, keyset, агрегаты, deep, asOf, withDeleted, pivot (этап 3)
-# chain-types — типы шагов, строк и фильтров по моделям: connect({ models }) (этапы 3, 4)
-# chain-write — запись цепочками: create, update, upsert, delete с превью, anonymize, reclass, слоты, inc, { rev }, fan-out, откат плана (этап 4)
+# chain-types — строгие типы цепочек по моделям: connect({ models }) и connect<Models>() (этапы 3, 4); шаг — только класс или алиас моделей и системных классов, переходы по концам, слоты ролей класса, поля фильтров, or() и агрегатов, loose(db) (план 2.0, 7.10 №1); строгие типы из файла letopis types (7.10 №6)
+# chain-write — запись цепочками: create, update, upsert, delete с превью, слоты, inc, { rev }, fan-out, откат плана (этап 4); update() и delete({ confirm: true }) без фильтра — invalid_query до записи, с { all: true }, фильтром, id, tags(), owner() или limit() — проходят: цепочка, батч, db.begin() (план 2.0, 7.10 №2)
 # demo — демо-домен booking на Zod: сид из моделей, запись данных, id по ключу, согласие Zod и базы (этап 2)
-# docs — примеры документации исполняются: помеченные блоки README и шпаргалки (русские и английские) — сценариями против PostgreSQL 18 (этап 8)
-# engine-attacks — атаки сырым SQL от прикладной роли: строки §7.3.1 этапов 1 и 3 с конкретными исходами; ключ сигналов без права, заливка поддельными сигналами, в том числе Class; запись в производный класс и ссылка на него, чекпоинт проектора через функции кредов; агент через MCP без --write и без подтверждения человека; смена parent, alias и derivedBy класса с одним правом WRITE на Class, удаление и пересоздание класса с историей строк, пробное ужесточение как оракул, reclass без DELETE и перевод ссылок глубже первого уровня, политика хранения истории с одним правом WRITE на Class; агент через MCP выдаёт членство или правило, сессия системного администратора; пользователь арендатора сам заводит производный класс, `rekeyClass` предка производного класса; перенос строки, который переписал бы ссылки строк производного класса; прикладная роль держит advisory-блокировки с прежними ключами внутренних блокировок, а строки-замки ей недоступны; подделанная справка о взятых блокировках семейства (этапы 1, 3; план 1.1, этапы 2, 4а, 5, точка А, ревью безопасности №2, точка Б и доработки после неё, ревью безопасности №3)
-# engine-class — классы как сущности: метасхема, наследование, пересчёт потомков, ужесточение, метаданные; класс с историей строк удаляется только после purge() (этап 1; доработки после точки Б)
-# engine-write — конвейер записи сырым SQL: id v5, умолчания, merge, inc, удаление, воскрешение, журнал, сигналы (этап 1)
+# docs — примеры документации исполняются: помеченные блоки README, шпаргалки и корневого README — сценариями против PostgreSQL 18 (этап 8)
+# engine-attacks — атаки сырым SQL от прикладной роли: строки §7.3.1 этапов 1 и 3 с конкретными исходами; ключ сигналов без права, заливка поддельными сигналами, в том числе Class; агент через MCP без --write и без подтверждения человека; смена parent и alias класса с одним правом WRITE на Class, удаление и пересоздание класса с историей строк, пробное ужесточение как оракул, выключение журнала класса (history) с одним правом WRITE на Class; смена класса — immutable_key; агент через MCP выдаёт членство или правило, сессия системного администратора; прикладная роль держит advisory-блокировки с прежними ключами внутренних блокировок, а строки-замки ей недоступны; подделанная справка о взятых блокировках семейства (этапы 1, 3; план 1.1, этапы 2, 5, точка А, ревью безопасности №2, точка Б и доработки после неё, ревью безопасности №3)
+# engine-class — классы как сущности: метасхема, наследование, пересчёт потомков, ужесточение, метаданные; класс с историей строк не удаляется, класс без журнала — удаляется (этап 1; доработки после точки Б)
+# engine-write — конвейер записи сырым SQL: id v5, умолчания, merge, inc, удаление, воскрешение, журнал без пропусков номеров версий, сигналы; класс строки неизменен — immutable_key (этап 1; план 2.0)
 # engine-races — гонки на двух соединениях в обоих порядках без пауз по времени; ужесточение во время непрерывной записи семейства не голодает; блокировка семейств, чьи корни отличаются только регистром, и подложенная строка вида LOCK (этап 1; ревью безопасности №3)
 # explain — индексы цепочек от роли приложения: снаружи первичный ключ и (class, tenant), внутри find_*() — GIN; срез asOf по классу не читает журнал другого арендатора (этап 3; доработки после точки Б)
 # find-ids-parity — 30 цепочек через find_*() и прямым чтением под RLS дают одинаковые ответы; свои членства в других арендаторах и строки Class System — сейчас, asOf и withDeleted (этап 3; доработки после точки Б)
-# hash — цепочка хэшей версий, подмена и разрыв журнала, verify() (этап 1)
 # harness — тестовая обвязка: подъём базы, схема на файл, две строки подключения (этап 0)
 # jsonschema — компиляция JSON Schema в jsonpath и проверка данных в базе (этап 1)
-# impersonation — имперсонация: letopis.account только для сервиса с правом, запреты целей, author и agent в журнале, sessionFor; реестр db.as() — один на арендатора, не пустеет, перечитывается по сигналу своего арендатора (этап 5; доработки после точки Б); реестр фасада не общий с корнем, пустой реестр не кэшируется (хвост ревью безопасности №3)
+# impersonation — имперсонация: letopis.account только для сервиса с правом, запреты целей, author и agent в журнале, sessionFor; реестр db.as() — один на арендатора, не пустеет, перечитывается по сигналу своего арендатора (этап 5; доработки после точки Б); реестр фасада не общий с корнем, пустой реестр не кэшируется (хвост ревью безопасности №3); auth.switch при имперсонации — LetopisError acl_denied из каталога, а не сырая ошибка LT000 (план 2.0, 7.5 №3)
 # install — установщик и роли: повторная установка, две установки в базе, три таблицы (этап 1)
 # member — членство: работа в арендаторе по ролям, auth.switch, выход с переходом владения, системные строки, роли арендатора без прав System (этап 5)
-# model — модели на Zod, нормализатор JSON Schema, перевод шаблонов, совпадение с метасхемой базы (этап 2)
+# model — модели на Zod, нормализатор JSON Schema, перевод шаблонов, совпадение с метасхемой базы (этап 2); format email длиннее 254 символов — нарушение без шаблона (ревью)
 # load — загрузчик: несколько классов, циклы, $key и $ext, повторы, existing, порции, режим истории, запрос по целям вне загрузки, CLI (этап 4)
-# roles — роли и права: установка без суперпользователя, функции владельца, триггеры по каталогу, журнал без колонки changed (этап 1; план 1.1, точка А)
+# roles — роли и права: установка без суперпользователя, функции владельца, триггеры по каталогу, журнал на чтение всеми колонками; up() от такого установщика — ANALYZE и fresh от роли владельца (этап 1; план 1.1, точка А; ревью)
 # write-races — гонки записи: 20 параллельных правок разных полей без потерь и строгий rev, параллельные add/remove множественного конца, загрузчик против ужесточения класса и против параллельной правки (existing: update) в обоих порядках (этап 4)
-# validator-parity — валидатор на TypeScript против проверки в базе: официальный набор, 10 000 случайных документов, умолчания (этап 2)
-# scenario-barbershop — сквозной сценарий барбершопа: 9 сцен 0.21 (integration) на цепочках 1.0 — каталог, окна батчем, брони под lock, мульти-слот и мульти-мастер, версии, отмена и бронь заново на тот же id, закрытие месяца при restrict (этап 4)
-# scenario-real-life — «реальная жизнь» салона: 16 сцен 0.21 (real-life) — сервис записи поверх цепочек, гонки двойной брони, переноса и отмены, walk-in, отказы, отчёты и инварианты дня (этап 4)
-# system-classes — системные классы вместо фасадов 0.21: сид System, аккаунты, креды, ресурсы и правила, транзакции (этап 5)
-# sync — letopis sync (сухой прогон, применение, ужесточение, потерянные refine) и letopis types (этап 2)
+# validator-parity — валидатор на TypeScript против проверки в базе: официальный набор, 10 000 случайных документов, умолчания (этап 2); нарушение базы — ключ каталога и параметры, шаблон с ними — текст базы (план 2.0, этап 3, п. 3)
+# scenario-barbershop — сквозной сценарий барбершопа: 9 сцен на цепочках — каталог, окна батчем, брони под lock, мульти-слот и мульти-мастер, версии, отмена и бронь заново на тот же id, закрытие месяца при restrict (этап 4)
+# scenario-real-life — «реальная жизнь» салона: 16 сцен — сервис записи поверх цепочек, гонки двойной брони, переноса и отмены, walk-in, отказы, отчёты и инварианты дня (этап 4)
+# system-classes — системные классы: сид System, аккаунты, креды, ресурсы и правила, транзакции (этап 5)
+# sync — letopis sync (сухой прогон, применение, ужесточение, потерянные refine) и letopis types (этап 2); зарезервированное имя хаба — отказ hub(), syncModels и базы (план 2.0, 7.10 №3)
+# cli — команды CLI (план 2.0, 7.9 №10, ред. 2): коды выхода letopis sync --check; справка, отчёт sync и letopis types, letopis types --system
 # tx — явные транзакции db.begin(): сломанная транзакция, lock(), 40P01; forUpdate(); батч и его склейка, очередь батча — своя у фасада; db.as(…, { owner }) (этап 4)
 # v5 — идентификаторы v5 на стороне SQL против векторов независимой реализации (этап 1)
 # zod-output — снимок вывода z.toJSONSchema() по видам полей демо-домена против эталона (этап 0)
-# time — история: versions({ follow }) через reclass и rekey, withDeleted, restore, purge, обрезка истории, удаление аккаунта (этап 6)
-# rekey — новое значение ключа объекта и новый ключ класса: новые id, перевод ссылок, рекурсия по связям с концом в ключе (этап 6)
-# reset — сброс sessions, tenant, all: флаг allowReset, право letopis.reset, подтверждение именем схемы, запись reset, новый ключ сервиса (этап 6)
-# verify — законные разрывы и подмены, verify({ data: true }): данные, концы, арендаторы, id по ключу; права и CLI (этап 6)
-# retention — политика хранения: ярусы, конечный срок, особые версии, удалённые, asOf, cursor_expired, часовой пояс, догоняющий запуск, наследование и умолчание — против эталона на TypeScript (этап 6)
+# time — история: versions, withDeleted, restore, удаление аккаунта (этап 6)
 # watch — подписка по курсору: порядок фиксации, долгая транзакция, возобновление, обрыв слушателя, два арендатора (этап 6)
-# cache — кэш результатов: попадание, свои и чужие записи, ключ с пользователем, права, погашенные сессии, обрыв слушателя, ttl, пометка класса, без LISTEN, гонка, db.sql, предел счётчиков сигналов (этап 6; план 1.1, точка А)
+# cache — кэш результатов: попадание, свои и чужие записи, ключ с пользователем, права, погашенные сессии, обрыв слушателя, ttl, пометка класса, без LISTEN, гонка, db.sql, предел счётчиков сигналов, гашения чужих сессий не растят счётчики (этап 6; план 1.1, точка А; план 2.0, 7.7)
 # maintain — обслуживание: истёкшие сессии и коды, права, один процесс под блокировкой, расписание (этап 6), строки-замки удалённых классов
-# up — полный установщик: свежая установка, повторный накат, свои сиды, автосоздание базы, UTF8, версия 17, upgrade с миграциями, PGlite, первый арендатор и пользователь (up({ tenant }), createTenant) (этапы 6, 8)
-# upgrade — обновление схемы с 1.4.1 (обычный up() без миграций, план 2.0, 7.8 №2), с 1.1.0 (upgrade: true, миграция 0007) и с 1.0.1 (upgrade: true, миграции 0006 и 0007) пакетами letopis-141, letopis-11 и letopis-1: версии и хэши прежнего движка, verify(), каталог против чистой установки, строки-замки, строки secret без аккаунта стёрты, приложение, подписка и проектор по старым данным, повторный up() (доработки после 1.2.0, этап 1; ревизия 7)
-# scenario-salon — сквозной сценарий салона: 21 акт 0.21 (salon) с матрицей покрытия API 1.0 (этап 6)
-# telemetry — onQuery и slowMs, describe() и метаданные классов с наследованием, describeText (этап 6)
-# history — diff и blame по журналу, причина изменения у глаголов, db.begin() и батча; версия, скрытая условием ACL, колонка changed, пропуск версии, row_changes на 20 тыс. целей (план 1.1, этап 1 и точка А)
-# signals — режимы сигналов: нагрузка у посторонней роли, точность кэша до арендатора, System, классы прав, процесс без ключа, загрузчик, подписка, ключ, none, склейка, версия сервера, смена класса, повтор отправки, режим после up() и reset({ all }) (план 1.1, этап 2)
-# initial-load — первая заливка: равенство с обычным загрузчиком, структура и режимы триггеров, системные строки, непустая схема, вставка во время запуска, откат, MULTI_INSERT в WAL, commitEvery, import --initial, агрегаты (agg_fill) (план 1.1, этапы 3 и 4б)
-# projector — проекторы из журнала: догонка, ровно один раз при обрыве, один писатель, долгая транзакция, транзакция на границе снимка перестройки, запрет записи в производные классы и ссылок на них, границы out, перестройка атомарная и пачками во время записи, purge источника, отставание и cursor_expired, функции кредов; версия, имя, администраторское подключение; гонка двух процессов; ошибка данных одного арендатора — выбывает только он (failed, rebuild({ tenant }), опция tenants), чекпоинт — только строка System, перестройка — только строки участников и семейств into, before после rekey, ярус all и журнал источников — по арендатору; свёртка out.inc по ключу в пачке, перестройка пачками в автоматических путях run() и второй процесс во время неё; перестройка одного арендатора пачками, пока идёт хвост; onExpired пачками в другом процессе, ошибка данных без повторов, ярус от начала перестройки; пустой последний проход перестройки пачками, выбывший посреди своей перестройки — без частичных строк, смена класса без смены id из семейства источников и в него, purge непрочитанного надгробия (план 1.1, этап 4а; ревью безопасности №2; точка Б и доработки после неё; ревью безопасности №3)
-# mcp — инструменты MCP: модель и meta только в результатах, права арендатора, JSON-цепочка и подсказки похожих имён, предел строк и байт с курсором, обёртка недоверенных данных, запись только с write, update только с rev, удаление с подтверждением человека (elicitation в ревизиях 2025 и 2026-07-28), причина в blame, учётные данные, схемы инструментов, letopis без SDK; letopis mcp по stdio, обработчик HTTP; окно подтверждения без алиаса и meta, countBy и versions с пределом в самом запросе, предел шагов и условий $or; классы прав — только с allowAclWrite, сессия в арендаторе System — только с allowSystemAdmin; structuredContent с пояснением, подпись requestState пользователя сервера со сроком (план 1.1, этап 5; ревью безопасности №2; точка Б и доработки после неё)
-# import — импорт из 0.21 по фикстуре настоящей 0.21: нарушение ключа, --keyless, счётчики по классам, verify, самоссылка, повтор, id без ключа, висячая ссылка, $$strict и поля на $, update, креды, CLI (этап 7)
-# security-final — итоговое ревью безопасности (этап 8, §7.10 №8.4): блокировка семейства по арендатору корня, account_purge без права и restore/purge чужого id не дают ни утечки, ни блокировки; функции этапа 6, log_refs_at, срезы find_* по журналу и watch_read не выходят за свой арендатор; NOTIFY несёт только имена или токены режима; ключ кэша различает токен, актора и арендатора (этап 8)
+# up — полный установщик: свежая установка, повторный накат, свои сиды, автосоздание базы, UTF8, версия 17, накат миграций, PGlite, первый арендатор и пользователь (up({ tenant }), createTenant); ошибки, ход установки и предупреждение штампа — тексты каталога (раздел boot); установка без ADMIN OPTION на готовую роль владельца — admin_required (7.5 №3); схема ревизии ниже 8 или без штампа — отказ up() и connect() до любых изменений с подсказкой up({ fresh: true }), fresh проходит (план 2.0, 7.10 №5); хаб с зарезервированным именем, заведённый мимо проверки базы, переживает up() с предупреждением, правку его описания база отклоняет (7.10 №3) (этапы 6, 8)
+# scenario-salon — сквозной сценарий салона: 20 актов с матрицей покрытия API (этап 6)
+# telemetry — onQuery и slowMs (этап 6)
+# history — причина изменения в версиях журнала: у глаголов, db.begin() и батча, причина батча — с фасада, поставившего глагол (план 1.1, этап 1)
+# signals — режимы сигналов: нагрузка у посторонней роли, точность кэша до арендатора, System, классы прав, процесс без ключа, загрузчик, подписка, ключ, none, склейка, версия сервера, повтор отправки, режим после повторного up() (план 1.1, этап 2)
+# initial-load — первая заливка: равенство с обычным загрузчиком, структура и режимы триггеров, системные строки, непустая схема, вставка во время запуска, откат, MULTI_INSERT в WAL, commitEvery (план 1.1, этап 3)
+# mcp — инструменты MCP: модель и meta только в результатах, права арендатора, JSON-цепочка и подсказки похожих имён, предел строк и байт с курсором, обёртка недоверенных данных, запись только с write, update только с rev, удаление с подтверждением человека (elicitation в ревизиях 2025 и 2026-07-28), причина в версиях, учётные данные, схемы инструментов, letopis без SDK; letopis mcp по stdio, обработчик HTTP; окно подтверждения без алиаса и meta, countBy и versions с пределом в самом запросе, предел шагов и условий $or; классы прав — только с allowAclWrite, сессия в арендаторе System — только с allowSystemAdmin; structuredContent с пояснением, подпись requestState пользователя сервера со сроком; описания инструментов, их параметров и instructions — у каждого есть, по-русски (план 1.1, этап 5; ревью безопасности №2; точка Б и доработки после неё)
+# security-final — итоговое ревью безопасности (этап 8, §7.10 №8.4): блокировка семейства по арендатору корня, account_purge без права и restore чужого id не дают ни утечки, ни блокировки; функции этапа 6, log_refs_at, срезы find_* по журналу и watch_read не выходят за свой арендатор; NOTIFY несёт только имена или токены режима; ключ кэша различает токен, актора и арендатора (этап 8)
 # semver — правила версий: check:semver требует шаг версии не меньше нужного — мажор за исчезнувший метод или код ошибки, минор за новый метод и новую ревизию движка, патча хватает на тексты (план 2.0, 7.8 №1)
-# prerelease — проверка перед выпуском: шаги идут строго по очереди, первый красный останавливает прогон, следующие не запускаются (план 2.0, 7.8 №3)
-# write-contract — обещания README о записи (план 2.0, 7.2): повтор ключа в батче — exists и откат, порядок строк ответа reclass, restore и rekey, цепочка с глаголом в значении слота, загрузчик с existing: update не правит строку другого класса, ответ из кэша не портится правкой прошлого ответа
-# watch-contract — обещания README о подписке и подключении (план 2.0, 7.4): молчащая подписка опрашивает журнал раз в pollMs, close() подключения закрывает живые подписки, reclass без ключа сбрасывает кэш прежнего класса, новый участник проектора получает начальную перестройку, проектор без LISTEN перечитывает состав, реестров db.as() не больше предела
+# one-process — один процесс: up({ login }) квотирует имя и пароль роли приложения, повтор обновляет пароль, привилегированную роль не трогает; connect({ admin }) — второй пул при первой надобности для load, syncModels, maintain с той же сессией, цепочки под RLS, без admin — admin_required (план 2.0, 7.9 №3, №4)
+# prerelease — проверка перед выпуском: шаги идут строго по очереди, первый красный останавливает прогон, следующие не запускаются; тест-файл, процесс которого упал до первого теста, перезапускается один раз, красный тест — нет; при --only и --skip таблица итогов копится — строки прочих шагов остаются из прежних прогонов (план 2.0, 7.8 №3)
+# write-contract — обещания README о записи (план 2.0, 7.2): повтор ключа в батче — exists и откат, порядок строк ответа restore, цепочка с глаголом в значении слота, загрузчик с existing: update не правит строку другого класса, ответ из кэша не портится правкой прошлого ответа
+# watch-contract — обещания README о подписке и подключении (план 2.0, 7.4): молчащая подписка опрашивает журнал раз в pollMs, close() подключения закрывает живые подписки, подписка на класс получает события потомка, заведённого после watch(), реестров db.as() не больше предела
 # model-contract — обещания README о моделях, типах, CLI и ошибках (план 2.0, 7.5): letopis types — верный TypeScript для кириллицы, класса без полей и anyOf, полная форма hub() с z.object, понятные ошибки вместо сырых, коды выхода CLI
-# read-contract — обещания README о чтении и истории (план 2.0, 7.1): срез asOf по классу и по концам после смены класса без смены id, versions, diff и blame с follow после rekey, курсор after() в versions() и paths(), имя поля с @S@
-```
+# read-contract — обещания README о чтении и истории (план 2.0, 7.1): курсор after() в versions() и paths(), имя поля с @S@
+# messages — каталог сообщений (план 2.0, этап 3, п. 3; 7.9 №6): у каждого кода заголовок и подсказка, hint и docs у каждой ошибки, docs ведёт на якорь кода в README; места библиотеки и ошибки базы — по ключу каталога, key и params, текст как у сырого SQL; нарушения данных из базы (запись, ужесточение класса, загрузчик), внутренняя ошибка internal, повторяемый конфликт с ключом; похожие имена для неизвестного класса, роли, поля и опции; неизвестная опция connect(), up(), load(), watch() и createMcpServer() — invalid_data с похожими (7.10 №4)
+# mcp-model — описание модели в letopis_model: каждая цепочка examples («создать», «найти», «перейти к соседям») исполняется на демо-схеме booking, letopis_model { class } отдаёт те же примеры, большая модель сначала теряет только их (план 2.0, 7.9 №9); метаданные и наследование, условия anyOf и oneOf (этап 6; план 1.1)
+# llms — один словарь фильтров (план 2.0, 7.9 №8): реестр операторов совпадает с фабриками пакета, с ключами letopis_query (тот же ответ, что у цепочки) и с таблицами README, шпаргалки и главы «Чтение» сайта
+# disconnect — обрыв соединения (план 2.0, 7.4 №7): загрузчик и первая заливка, открытие db.begin() — обрыв TCP до и после COMMIT и на открытии транзакции, pg_terminate_backend процесса, ждущего блокировку: промис отклонён ошибкой связи, необработанных ошибок в процессе нет, следующая операция пула проходит
+```
+
+## 19. Лицензия
+
+letopis распространяется под лицензией **PolyForm Noncommercial License 1.0.0** (SPDX `PolyForm-Noncommercial-1.0.0`):
+исходный код открыт, некоммерческое использование бесплатно, коммерческое — только по отдельной лицензии от
+владельца. Это не лицензия open source в смысле OSI. Полный текст — [LICENSE](LICENSE) (юридическую силу имеет он).
+
+- **Без разрешения** — любые некоммерческие цели: личное использование для исследований, экспериментов, учёбы, хобби
+  без коммерческого применения; использование благотворительными и некоммерческими организациями, учебными
+  заведениями, государственными исследовательскими организациями и учреждениями. Код можно менять и распространять —
+  с текстом лицензии и строкой `Required Notice: Copyright 2026 alepri51 (https://github.com/alepri51)`.
+- **По разрешению владельца** — коммерческое использование: платный продукт или сервис, внутренние системы
+  коммерческой компании, разработка на заказ, встраивание в коммерческий продукт.
+- **Как получить разрешение** — issue в репозитории <https://github.com/alepri51/letopis/issues> с заголовком
+  «Коммерческая лицензия»; владелец — <https://github.com/alepri51>. Подробнее — [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md).
+- Версии до 2.0.0 включительно выпущены под MIT и остаются под ней; PolyForm Noncommercial действует с 2.1.0.