letopis 1.0.1 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# letopis 1.0
+# letopis 1.2
 
 **letopis** — библиотека для Node.js, хранилище версионированных сущностей на PostgreSQL 18. Каждое изменение
 сохраняется версией в журнале. Поэтому у любого объекта есть история, состояние на любую дату и подписка на
@@ -15,11 +15,15 @@ RLS. Правила одинаково действуют и для библио
 - **Запись цепочками**: `create`, `update` со слиянием, `upsert`, удаление с превью и каскадом, приращение `inc`
   для денег и счётчиков — [разделы 5](#5-запись), [7](#7-удаление-и-восстановление) и [8](#8-транзакции-батчи-и-деньги).
 - **Чтение цепочками**: переходы по связям, фильтры, деревья, агрегаты, постраничный вывод — [раздел 6](#6-чтение).
-- **История**: версии, срез на дату, восстановление удалённого, политика хранения, проверка цепочки хэшей —
-  [раздел 11](#11-история-и-срезы-на-дату).
+- **История**: версии, срез на дату, что изменилось и кто (`diff`, `blame`), восстановление удалённого, политика
+  хранения, проверка цепочки хэшей — [раздел 11](#11-история-и-срезы-на-дату).
 - **Арендаторы, вход и права** — в самой базе: пароли, ключи API, одноразовые коды, TOTP, сессии, имперсонация,
   правила доступа — [раздел 10](#10-пользователи-вход-и-права).
 - **Подписка на изменения** по курсору без потерь и **кэш результатов** — [раздел 12](#12-подписка-на-изменения-и-кэш).
+- **Производные данные**: агрегаты в базе — суммы и счётчики, которые держит сама база, — и проекторы, которые строят
+  сводки из журнала, — [разделы 4](#агрегаты-в-базе) и [12](#проекторы).
+- **Агенты и MCP**: сервер MCP даёт ИИ-агенту модель, чтение, историю и, если разрешено, запись — с правами одного
+  пользователя — [раздел 13](#агенты-и-mcp).
 - **Массовая загрузка** миллионов строк и **импорт из 0.21** — [разделы 9](#9-массовая-загрузка) и [14](#14-переход-с-021).
 
 Требования:
@@ -28,7 +32,8 @@ RLS. Правила одинаково действуют и для библио
 - Node.js 22 или новее; пакет — модуль ES.
 - Рантайм-зависимость одна — `postgres`. Zod 4 — необязательная peer-зависимость: он нужен только подпути
   `letopis/model`, а `import { connect } from 'letopis'` работает и без него. Для разработки без PostgreSQL —
-  необязательные `@electric-sql/pglite` и `@electric-sql/pglite-socket`.
+  необязательные `@electric-sql/pglite` и `@electric-sql/pglite-socket`. Серверу MCP (`letopis/mcp` и
+  `letopis mcp`) нужна необязательная `@modelcontextprotocol/server` версии 2.4 или новее в линейке 2.
 
 ## Оглавление
 
@@ -152,8 +157,8 @@ await svc.close()
 
 Таблиц три. `entity` — текущее состояние: одна строка на каждую живую сущность, включая строки системных классов
 (`Class`, `Account`, `Resource`, `member`, `rule`). `log` — журнал: полный снимок каждой версии с автором,
-временем, видом операции и хэшем. `secret` — креды и сессии: приложение не видит в ней ни одной строки, с ней
-работают только функции входа.
+временем, видом операции и хэшем. `secret` — креды, сессии и чекпоинты проекторов: приложение не видит в ней ни
+одной строки, с ней работают только функции входа и проекторов.
 
 Классы — тоже сущности. Описание класса лежит в строке `Class`; там же база хранит развёрнутое описание с учётом
 предков и скомпилированную проверку данных. Хэш версии — генерируемая колонка: sha256 от хэша прошлой версии и
@@ -188,10 +193,26 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 
 ### Сигналы
 
-Запись сообщает об изменённых классах через `NOTIFY`. Сырой SQL шлёт сигнал из триггера, и PostgreSQL доставляет
-его при фиксации. Транзакции библиотеки шлют сигналы отложенно: нотификатор процесса отправляет их раз в 100 мс
-(`notifyIntervalMs`). В сигнале только имя класса или начало хэша токена погашенной сессии — ни id, ни данных.
-По сигналам перечитывается реестр классов, сбрасывается кэш результатов и будится подписка.
+Запись сообщает об изменениях через `NOTIFY`. Канал — полное имя схемы установки вместе с версией, например
+`v2.shop`; из-за точки в SQL его имя берут в двойные кавычки: `LISTEN "v2.shop"`. Запись сырым SQL на своём
+соединении шлёт сигнал из триггера, и PostgreSQL доставляет его при фиксации. Транзакции библиотеки, в том числе
+`db.sql` и `db.transaction()`, шлют сигналы отложенно: нотификатор процесса отправляет их раз в 100 мс
+(`notifyIntervalMs`), а неотправленные из-за ошибки — повторяет. Что несёт сигнал записи (его нагрузка, payload),
+задаёт режим установки `up({ signals })`:
+
+| Режим | Нагрузка сигнала записи | Что видит любая роль, которая может подключиться к базе |
+|---|---|---|
+| `class` (по умолчанию) | имя класса: `Booking` | имена классов и время записи |
+| `tenant` | `Класс@токен арендатора`: `Booking@3f9c…` | ещё и псевдонимы арендаторов |
+| `opaque` | `токен класса@токен арендатора`: `9a1e…@3f9c…` | только время и частоту записи по псевдонимам |
+| `none` | сигналов нет | ничего |
+
+Токен — 24 шестнадцатеричных знака ключевого HMAC: сопоставить псевдоним с именем может только процесс с ключом
+сигналов, а ключ выдаётся сервисам (право `letopis.signals`). Кроме сигналов записи, есть служебные: погашенная
+сессия шлёт `session:<16 hex>` (первые 16 шестнадцатеричных знаков sha256 её токена), сброс сессий — `session:*`,
+сброс арендатора или всей установки — `*` (сброс всей установки шлёт ещё и `session:*`). В режиме `none` нет и их.
+Ни id, ни данных в сигналах нет. По сигналам перечитывается реестр классов, сбрасывается кэш результатов и будится
+подписка; что меняет режим для кэша и подписки — в [разделе 12](#12-подписка-на-изменения-и-кэш).
 
 ## 3. Установка и подключение
 
@@ -210,6 +231,7 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 | `history` | политика хранения истории для классов без своей ([раздел 11](#11-история-и-срезы-на-дату)) |
 | `serviceKey` | свой ключ сервиса вместо случайного: `lts_` и 32–128 шестнадцатеричных знаков |
 | `allowReset` | разрешить `db.reset()` ([раздел 13](#13-эксплуатация)); по умолчанию выключено |
+| `signals` | режим сигналов: `'class'` (по умолчанию), `'tenant'`, `'opaque'` или `'none'` ([«Сигналы»](#сигналы)); режим хранится в схеме — `up()` без опции его не меняет |
 | `fresh` | удалить схему и поставить заново — **данные схемы теряются** |
 | `upgrade` | обновить схему старой ревизии: миграции и повторный накат |
 | `pglite` | база для разработки без PostgreSQL (см. ниже) |
@@ -218,7 +240,16 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 
 Результат: `schema` (полное имя), `serviceKey` (при первой установке и при накате, когда в установке не осталось ни
 одного действующего ключа API; иначе `null`), `created`,
-`upgraded`, `revision`, `migrations`, `analyzed`, `owner`, `app`, а также `tenant` и `pglite`, если их просили.
+`upgraded`, `revision`, `migrations`, `analyzed`, `owner`, `app`, `signals` (режим сигналов установки), `warnings`
+(предупреждения, без `quiet` они печатаются), а также `tenant` и `pglite`, если их просили. На PostgreSQL ниже 18.2
+`up()` предупреждает: такой сервер мог усечь CLOG, который ещё нужен непрочитанным сигналам, — обновите его.
+
+Скрыть из сигналов имена классов — режим `opaque` (или `tenant`, если имена не секрет, а нужна точность кэша по
+арендатору); после смены режима перезапустите процессы приложения — режим читается при подключении:
+
+```ts
+await up({ dsn: ADMIN, schema: 'shop', signals: 'opaque' })   // дальше up({ dsn, schema }) режим не меняет
+```
 
 <!-- run: guide -->
 ```ts
@@ -238,8 +269,8 @@ const ANNA = r.tenant!.user!       // его первый пользовател
 Приложение работает от LOGIN-роли, которая состоит только в `letopis_app`:
 `create role shop_app login password '…'; grant letopis_app to shop_app;`. Тогда на него действуют RLS и
 триггеры, как и на любой сырой SQL от этой роли. Роль, которая обходит RLS, `connect()` отклоняет с ошибкой
-`bypass_rls`. Администраторское подключение (`allowBypassRls: true`) нужно только загрузчику, проверке и
-обслуживанию; держите его в отдельном процессе, а не в веб-приложении.
+`bypass_rls`. Администраторское подключение (`allowBypassRls: true`) нужно только загрузчику, проекторам, ремонту
+агрегатов (`rebuildAggregates`), проверке и обслуживанию; держите его в отдельном процессе, а не в веб-приложении.
 
 ### Первый арендатор и пользователь
 
@@ -311,7 +342,8 @@ const anna = await connect({ dsn: APP, schema: r.schema, token: r.tenant!.token!
 
 ### Администраторское подключение
 
-Загрузчику нужно подключение роли, которая может стать владельцем, с `allowBypassRls: true`. `verify()` и
+Загрузчику, проекторам и `rebuildAggregates` нужно подключение роли, которая может стать владельцем, с
+`allowBypassRls: true`. `verify()` и
 `maintain()` работают и на нём, и у системного администратора по обычному подключению. Администраторское
 подключение печатает предупреждение «RLS не действует» — так и должно быть. Сессия задаёт арендатора, с которым
 оно работает. Отдельному процессу загрузки удобнее ключ сервиса: `connect({ dsn: ADMIN, schema, apiKey,
@@ -324,12 +356,18 @@ const adm = await connect({ dsn: ADMIN, schema: r.schema, token: r.tenant!.token
 
 ### Обновление пакета и схемы
 
-У схемы есть ревизия движка (сейчас 5). Если новая версия пакета принесла новую ревизию, `connect()` только
+У схемы есть ревизия движка (сейчас 6). Если новая версия пакета принесла новую ревизию, `connect()` только
 предупредит и назовёт команду. Отказывает `up()`: на отставшую схему без `upgrade: true` и на схему новее пакета.
 Поэтому скрипт запуска, который вызывает `up()` при каждом старте, после обновления пакета остановится, пока не
 получит `upgrade: true`. `up({ dsn, schema, upgrade: true })` применяет миграции из `sql/migrate/` и повторно
 накатывает функции; данные сохраняются.
 
+Первый `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()` только снимет прежний.
+
 ### Разработка без PostgreSQL: PGlite
 
 `up({ pglite: true })` поднимает PGlite (PostgreSQL 18 на WebAssembly) с pgcrypto и сокетом на свободном порту.
@@ -456,11 +494,68 @@ id из email подбирается перебором и остаётся в
 
 - `history: false` — журнал для класса не ведётся: нет версий, среза на дату, восстановления и событий подписки.
   Политика хранения — `history: { all: '1 day', daily: '3 months', … }` ([раздел 11](#11-история-и-срезы-на-дату)).
+  Сменить `history` у существующего класса может только тот, у кого есть право `READ` и `DELETE` без условий на все
+  строки класса и его потомков: по политике `maintain()` прореживает журнал, а `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` — число; агрегаты не образуют цикл; цель и источник — не системные и
+  не производные классы. Источник, описанный позже цели, сверяется при появлении.
+- Строки попадают в агрегат только с ведома того, кто читает их все: поле считает и строки, которые автору не видны.
+  Описать или изменить агрегат может только тот, кто без условий читает все строки источника и его потомков. Сделать
+  класс источником (новый класс, смена `parent`, источник после цели) может только тот, кто без условий читает все
+  строки этого класса и его потомков — и до правки, и после. Иначе `acl_denied`.
+- Опция наследуется, потомок заменяет её целиком. Добавить или изменить агрегат — ужесточение: запись в цель и в
+  источники ждёт, пока поле пересчитывается у всех строк.
+- `db.rebuildAggregates(класс)` пересчитывает поле из текущих строк — для ремонта. Версия пишется только там, где
+  значение изменилось. Расхождения показывает `db.verify({ data: true })`. Нужно администраторское подключение.
+- Сырой `INSERT … ON CONFLICT DO UPDATE SET data = excluded.data` для цели отклоняется: поле в `excluded.data` уже
+  поставил триггер вставки. Пишите `excluded.data - array['balance']`, и поле останется прежним; `upsert` библиотеки
+  делает так сам.
 
 ### Записать модель в базу
 
@@ -598,6 +693,13 @@ await db.Product(kettle).update({ views: inc(1, { start: 0 }) }).rows()    // п
 - маркер `inc` нельзя получить из JSON: `{ "$inc": 5 }`, пришедший из сети, остаётся данными;
 - деньги храните целым числом мелких единиц (копеек) не больше 2^53 − 1.
 
+Счётчик, который обязан совпадать с источником и для сырого SQL, удобнее держать агрегатом
+([«Агрегаты в базе»](#агрегаты-в-базе)): его пересчитывает сама база, и забыть `inc` нельзя. Цена у агрегата и `inc`
+одна: операции одного объекта идут друг за другом под блокировкой его строки, и каждая пишет его версию. На машине
+замеров один объект так принимал 150–190 операций в секунду, сколько бы писателей его ни ждало
+([раздел 17](#17-производительность)). Для более горячих счётчиков берите проектор со свёрткой пачкой
+([«Проекторы»](#проекторы)): итог отстаёт от источника, зато писатели не ждут друг друга.
+
 ### Защита от параллельной правки: `{ rev }`
 
 <!-- run: guide -->
@@ -628,9 +730,12 @@ const [vip] = await db.Customer(olga).reclass('Vip', { name: 'Ольга', email
 - `rekey(патч)` — новое значение ключа: строка с новым id, все ссылки переведены, старая строка удалена. Если
   ссылающаяся строка включает этот конец в свой ключ, её id тоже меняется, и перевод идёт дальше. Журнал связывает
   старый и новый id (`moved`).
-- `db.rekeyClass(класс, ключ)` — новый ключ для всех строк семейства, одной транзакцией.
-- `reclass(класс, данные)` — смена класса; данные необязательны, а если переданы — задаются целиком. Если у нового
-  класса нет ключа, id сохраняется (как у `vip` выше); если есть — id вычисляется заново, а ссылки переводятся.
+- `db.rekeyClass(класс, ключ)` — новый ключ для всех строк семейства, одной транзакцией. У производного класса и
+  у класса с производным потомком — `derived_class`: строки производного класса пишет только проектор.
+- `reclass(класс, данные)` — смена класса; данные необязательны, а если переданы — задаются целиком. Строка уходит из
+  прежнего класса, поэтому нужно право `DELETE` на неё, `WRITE` — на новый класс и на каждую строку, чьи ссылки
+  переписывает перевод, на любой глубине. Если у нового класса нет ключа, id сохраняется (как у `vip` выше); если
+  есть — id вычисляется заново, а ссылки переводятся.
   Роли ссылающихся строк должны принимать новый класс, иначе `reclass_denied`. Сырой `UPDATE … SET class`
   проходит, только если ключа нет ни у старого, ни у нового класса (иначе `use_reclass`).
 - Удаление, смена класса и смена ключа работают только в `read committed`: транзакции библиотеки всегда открываются
@@ -779,7 +884,8 @@ const avgPrice = await db.Shop(shop).Product().avg('data.price')
 const byStatus = await db.Order().countBy('data.status')          // { new: 1 }
 ```
 
-Агрегаты считает база, по сущностям последнего шага.
+Агрегаты считает база, по сущностям последнего шага. `limit(n)` и `offset(n)` перед `countBy()` относятся к группам:
+`db.Order().limit(3).countBy('data.status')` — три самых частых значения.
 
 ### Пути
 
@@ -846,8 +952,11 @@ await db.Customer(temp).purge({ confirm: true }).rows()        // история
 ```
 
 `purge` работает только для удалённых объектов (живой — `not_deleted`) и стирает их историю целиком; на месте
-версии 1 остаётся запись `purge` с числом стёртых версий. История системных классов не стирается. Удалить аккаунт —
-`db.auth.purgeAccount` ([раздел 10](#10-пользователи-вход-и-права)).
+версии 1 остаётся запись `purge` с числом стёртых версий. История системных классов не стирается. Пока проектор,
+чьи источники `from` включают класс объекта ([«Проекторы»](#проекторы)), не прочёл удаление, `purge` отказывает
+(`projector_pending`): стёртое надгробие проектор не увидел бы, и вклад объекта остался бы в итогах. Удаление и
+`purge` одной транзакцией в таком классе поэтому не проходят. Удалить аккаунт — `db.auth.purgeAccount`
+([раздел 10](#10-пользователи-вход-и-права)).
 
 ## 8. Транзакции, батчи и деньги
 
@@ -989,6 +1098,65 @@ try {
 - Перевод — две операции в одной `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-производительность)). Если один объект
+  получает больше, итог лучше считать проектором ([«Рецепт: дневная выручка»](#рецепт-дневная-выручка)).
+
 ## 9. Массовая загрузка
 
 ### Когда нужен загрузчик
@@ -1056,6 +1224,22 @@ await adm.load({ Category: [{ name: 'Посуда' }] }, { as: ANNA, tenant: SHO
 `ownerDefault`. Без `tenant` строки идут в собственного арендатора пользователя. Так процесс загрузки принимает
 файлы, присланные пользователями.
 
+### Первая заливка
+
+```ts
+const r = await adm.load(rows, { initial: true })   // пустая схема: одна транзакция, индексы и триггеры — в конце
+```
+
+`db.load(rows, { initial: true })` (`letopis load --initial`) заливает данные в пустую схему быстрее обычного
+загрузчика — на миллионе объектов примерно в 2,2 раза: всё идёт одной транзакцией, на время загрузки таблицы закрыты
+для чтения и записи, индексы, ограничения и триггеры сняты и строятся заново в конце, строки пишутся `COPY … FREEZE`.
+Пустая — значит, кроме строк системных классов (описания классов, аккаунты, членства, ресурсы, правила) и записей
+`reset`, в схеме ничего нет; иначе — `not_empty` до любых изменений. Режим несовместим с `commitEvery`, `existing`
+(кроме `'error'`) и `{ as }`; ошибка любой строки откатывает всё, вместе с индексами и триггерами.
+`letopis import --initial` проводит так весь импорт: одной транзакцией, без `--update` и `--commit-every`. WAL пишется
+и здесь (без него — только при `wal_level = minimal`), но индексы строятся один раз, и его почти втрое меньше; после
+`FREEZE` первое чтение и первая очистка таблицу не переписывают.
+
 ### Командная строка
 
 ```sh
@@ -1075,7 +1259,8 @@ 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`).
+`Class` загрузчик не принимает: классы задаёт `syncModels`). Строки производных классов и ссылки на них загрузчик
+отклоняет с кодом `derived_class`: такие строки пишет только проектор.
 
 Нарушения ищутся поэтапно: разбор строк (классы, id, повторы), права на классы (`load({ as })`), данные и концы
 пачками, в конце порции — цели вне загрузки, владельцы и арендатор. Загрузка отменяется после первого этапа,
@@ -1230,6 +1415,24 @@ await anna.auth.switch(SHOP)               // арендатор сессии
 арендатора действуют на его строки, правила System — везде. Права действуют и на сырой SQL: строки без права не
 видны, правка — пусто или `acl_denied`.
 
+Маска класса в объекте `READ`, `WRITE` или `DELETE` совпадает и с потомками класса — по именам предков и их алиасам.
+Поэтому правка класса, которая меняет `parent`, `alias` или `derivedBy`, требует права `READ`, `WRITE` и `DELETE` без
+условий на все строки класса и каждого его потомка, иначе `acl_denied`: одного права `WRITE` на `Class` мало, чтобы
+подставить строки класса под чужие правила. Алиас не совпадает с именем другого класса (в том числе `Class` и
+системных) и с чужим алиасом арендатора и System, а имя нового класса — с чужим алиасом: иначе правило, написанное
+для одного класса, действовало бы и на строки другого. Нарушение — `invalid_class`.
+
+По тем же именам правила находят и старые версии строк в журнале. Поэтому класс удаляется, только когда у него нет
+строк, потомков и истории строк: историю удалённых строк сначала стирает `purge()`. Класс, удалённый с историей
+раньше, создаётся заново только с прежними `parent`, `alias` и `derivedBy` — иначе `invalid_class`: старые версии его
+строк попали бы под чужие правила. Если журнал хранит строки класса с этим именем, но не его надгробие (например,
+строки класса System, удалённого в 1.1), класс с этим именем не создаётся, пока историю не сотрёт `purge()`.
+
+Производный класс (`derivedBy`) заводит, меняет и удаляет только администратор: администраторское подключение или
+аккаунт с правом System `letopis.projector` (у системного администратора оно есть по маске `letopis.*`). Проектор
+пишет в такой класс итоги по всем строкам источников арендатора, без прав чтения, поэтому пользователь, заведя его
+сам, читал бы итоги по строкам, которые ему читать запрещено.
+
 ### Выдать право
 
 Пример: Олег — сотрудник магазина с ролью `staff`, и сотрудникам нельзя удалять товары.
@@ -1294,8 +1497,13 @@ const followed = await db.Product(mug2).versions({ follow: true }) // и чер
 ```
 
 У каждой версии — автор, агент, время, номер, вид операции (`create`, `update`, `delete`, `reclass`, `rekey`,
-`restore`, `purge`, `trim`, `reset`) и причина (`reason`) — если её задала настройка `letopis.reason` транзакции;
-отдельного API для причины нет. Версия удаления — с `$deleted`.
+`restore`, `purge`, `trim`, `reset`) и причина (`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()` — пять
+последних версий, новые первыми.
 
 ### Срез на дату
 
@@ -1339,6 +1547,70 @@ history: { all: '1 day', daily: '1 week', weekly: '1 month', monthly: '1 year',
 - В прореженной части срез показывает последнюю сохранённую версию до момента, то есть его точность равна
   периоду яруса. Подписчик, отставший дольше яруса `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`).
+- `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 -->
@@ -1380,7 +1652,10 @@ for await (const ev of sub) {             // ev: { cursor, row, id, class, op, r
 
 - `from` — `'now'` (по умолчанию: только изменения после подписки), `'start'` (весь журнал) или сохранённый курсор.
   `db.watch()` возвращается сразу, а момент «now» подписка берёт первым запросом к базе: запись, сделанная сразу
-  после `db.watch()`, может зафиксироваться раньше и в поток не попасть. Поэтому пример выше читает с `'start'`.
+  после `db.watch()`, может зафиксироваться раньше и в поток не попасть. `await sub.ready()` дожидается этого момента:
+  запись после него в поток придёт. Пример выше читает с `'start'`.
+- Вызовы `sub.next()` идут по очереди: параллельные получают разные события. Вызов, брошенный по таймауту
+  (`Promise.race`), всё равно получит своё событие — держите его обещание и ждите его снова.
 - `classes` — только эти классы с потомками; `pollMs` — запасной опрос (1000 мс).
 - События идут без потерь и повторов, под правами читателя, в порядке номеров транзакций, а внутри транзакции — в
   порядке записи. Это не порядок фиксации: версии одного объекта сверяйте по `rev`.
@@ -1391,6 +1666,198 @@ for await (const ev of sub) {             // ev: { cursor, row, id, class, op, r
 - Подписка без потерь — это сохранённый курсор: храните `ev.cursor` последнего обработанного события и продолжайте
   с него после перезапуска.
 
+### Проекторы
+
+Проектор строит строки производных классов из журнала: сводки, денормализованные карточки и всё, что можно считать
+с отставанием от записи. Классы-источники (`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 })` читает текущую строку вместе с записями
+  пачки. `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()` другого процесса, перестройка пережидает.
+- `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` у этих арендаторов; класс
+  не может быть одновременно источником и результатом. Изменений класса с `history: false` проектор не видит:
+  журнала у него нет. Поэтому арендатор, у которого такой класс среди источников, выбывает с кодом `invalid_class`, и
+  его производных строк проектор не строит. Включите журнал класса и перестройте арендатора `rebuild({ tenant })`.
+- `batch` — сколько изменений в пачке (500), `pollMs` — запасной опрос (1000 мс): сигналы источников будят
+  проектор раньше.
+- Каждая правка, которую `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`.
+
 ### Кэш результатов
 
 <!-- run: guide -->
@@ -1403,11 +1870,19 @@ const stats = db.cache.stats()                                 // { size, hits,
 
 - в ключе ответа — запрос, параметры, сессия, актор и арендатор, поэтому один пользователь не получит ответ другого;
 - свои записи сбрасывают ответы изменённых классов сразу после фиксации (с классами каскада), чужие — по сигналу
-  базы;
+  базы. В режимах `tenant` и `opaque` процесс с ключом сигналов сбрасывает класс только в арендаторе записи (строки
+  System — во всех); процесс без ключа — во всех арендаторах, а в режиме `opaque` любой сигнал сбрасывает у него
+  весь кэш;
 - изменение прав и классов, запись через `db.sql`, погашенная сессия и переподключение слушателя сбрасывают весь
   кэш или ответы сессии;
 - срок по умолчанию — 60 секунд; внутри `db.begin()` кэш не работает;
-- без `LISTEN` кэш выключен, а `connect({ cache: { ttlOnly: true } })` включает его только по сроку.
+- без `LISTEN` и в режиме `none` кэш выключен, а `connect({ cache: { ttlOnly: true } })` включает его только по сроку.
+
+Реестр классов процесс перечитывает по сигналу об изменении классов сразу (одно перечитывание за раз), а реестр и
+ключ сигналов по `*`, по незнакомому токену и по нагрузке не своего режима (а без ключа в режиме `opaque` — по любому
+сигналу) — не чаще раза в 5 секунд: поток сигналов, в том числе поддельных, не превращается в поток запросов. В режиме `none` реестр раз в 5 секунд сверяет отпечаток классов, а подписка
+опрашивает журнал. Подписка просыпается только от своих классов и своего арендатора, а без ключа — от любого
+сигнала; события она в любом случае читает из журнала, поэтому ничего не теряет.
 
 Между процессами кэш устаревает на интервал отправки сигналов (`notifyIntervalMs`, 100 мс) плюс доставку;
 `db.flushSignals()` отправляет накопленные сигналы сразу. `db.cache.clear()` очищает кэш.
@@ -1425,11 +1900,11 @@ const report = await adm.maintain()     // { sessions, codes, thinned, batches,
 очередь сигналов PostgreSQL: заполнение больше половины — предупреждение. Вызывать может системный администратор,
 роль с правом `letopis.maintain` или администраторское подключение. Запускает его внешний планировщик
 (`letopis maintain`) или сама библиотека: `connect({ maintain: '1h' })`. Из нескольких процессов работает один:
-каждая пачка — своя транзакция, и первым делом она берёт транзакционную advisory-блокировку
-(`pg_try_advisory_xact_lock`), которая снимается с фиксацией пачки. Если блокировку держит другой процесс, вызов до
-первой пачки отвечает `skipped: true`, а между пачками останавливается (продолжит тот процесс) и отчитывается о
-сделанном с `more: true`. Сеансовой блокировки нет, поэтому `maintain()` работает за любым пулом, в том числе за
-PgBouncer в режиме транзакций.
+каждая пачка — своя транзакция, и первым делом она берёт блокировку обслуживания — строку таблицы `secret`, которую
+ни прикладная, ни посторонняя роль базы не займёт; блокировка снимается с фиксацией пачки. Если блокировку держит
+другой процесс, вызов до первой пачки отвечает `skipped: true`, а между пачками останавливается (продолжит тот
+процесс) и отчитывается о сделанном с `more: true`. Сеансовой блокировки нет, поэтому `maintain()` работает за любым
+пулом, в том числе за PgBouncer в режиме транзакций.
 
 ### Сброс: `reset()`
 
@@ -1452,8 +1927,151 @@ const model = db.describe()           // { schema, tenant, classes: [...], metho
 const modelText = describeText(model) // то же текстом — для llms.txt приложения или подсказки ИИ-агенту
 ```
 
-`db.describe()` отдаёт описание классов, доступных сессии: поля, концы, ключи, политики и метаданные. Из
-командной строки — `letopis describe --format text --out llms.txt`.
+`db.describe()` отдаёт описание классов, доступных сессии: поля, концы, ключи, политики и метаданные, а также
+условия по нескольким полям `anyOf` и `oneOf` с учётом наследования, признак производного класса `derivedBy` и
+агрегаты `aggregate`, если они заданы. Из командной строки — `letopis describe --format text --out llms.txt`.
+
+### Агенты и MCP
+
+Агент — Claude, Cursor или свой — работает с данными через инструменты MCP: узнаёт модель, читает цепочкой, смотрит
+историю, а если разрешено — пишет. Сервер MCP действует от имени одного пользователя и только с его правами: каждый
+вызов — цепочка под его сессией, права и арендаторов проверяет база. Сырого SQL у агента нет.
+
+| Инструмент | Что делает |
+|---|---|
+| `letopis_model` | модель: классы, поля (JSON Schema), условия `anyOf` и `oneOf`, концы, ключи, алиасы, метаданные; с `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_write` | `create`, `update` (только с `rev`), `upsert`, `delete` — только при `write: true` (`letopis mcp --write`) |
+
+Запрос `letopis_query` — та же цепочка, что `db.Product({ price: lt(1000) }).Shop().sort('data.name').rows()`, только записанная JSON:
+
+```json
+{ "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": [фильтр, …] }`. Неизвестный класс, роль, параметр или
+оператор — ответ `isError` с подсказкой похожих имён. Шагов `steps` — не больше 16, условий в `$or` одного фильтра —
+не больше 64; иначе `invalid_query`. Время запроса эти пределы не ограничивают: задайте `statement_timeout` роли базы,
+под которой подключается сервер MCP (`alter role … set statement_timeout = '5s'`).
+
+Ответ — `structuredContent` и его текстовый дубль. `structuredContent` — `{ notice, data }`: `notice` — постоянный
+текст пакета о том, что в `data` данные базы, а не инструкции, `data` — сам ответ. Форма `data` у `letopis_query`
+зависит от терминала:
+
+| Терминал | `structuredContent.data` |
+|---|---|
+| `rows` (по умолчанию) | `{ rows, count, more, cursor? }` |
+| `ids` | `{ ids, count, more, cursor? }` |
+| `first` | `{ row }` — строка или `null` |
+| `count` | `{ count }` |
+| `countBy` | `{ counts, truncated? }` |
+| `sum`, `avg`, `min`, `max` | `{ value }` |
+
+У `rows` и `ids` `count` — число строк на этой странице, а не всего. Страница — не больше `limit`, `maxRows` строк
+(100) и `maxBytes` байт JSON строк (50 000); строка, которая сама больше `maxBytes`, приходит на странице одна.
+`more: true` — есть ещё строки, и тогда `cursor` с тем же запросом отдаёт следующую страницу. `counts` —
+`{ значение: число }`, самые частые значения; если группы не поместились в пределы, приходит `truncated: true`. Из
+базы `countBy` читает не больше `maxRows` + 1 групп. Поле агрегата и `countBy` —
+`field: 'data.<путь>'`. Сортировка — `sort: { field, dir }`: `field` — `at`, `rev`, `id` или `data.<путь>`, `dir` —
+`'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), если они есть. Параметр не по
+входной схеме инструмента (не тот тип, значение не из перечня, нет обязательного) отклоняет SDK ещё до letopis: тогда
+`isError: true` и только текст, без `structuredContent`.
+
+В тексте ответа всё, что пришло из базы, — строки, имена и описания классов, тексты ошибок, подсказки — стоит внутри
+`<untrusted-data-…>` со случайным суффиксом и пояснением, что это данные, а не инструкции. Описания инструментов и
+`instructions` сервера — постоянный текст пакета: `meta` классов пишут арендаторы, поэтому она попадает только в
+результаты.
+
+Запись. Без `write` инструмента `letopis_write` нет в списке инструментов, а его вызов — ошибка протокола SDK
+(`Tool letopis_write not found`), а не ответ инструмента с `isError`. Концы записи задаёт
+`links: { Роль: id | [id] | null }`, а `create`, `update` и `upsert` отвечают `{ rows }`. `update` принимает только
+`rev` прочитанной версии: чужая версия — `conflict`, потерянной правки нет. `delete` без `confirm` возвращает превью
+каскада и код операции: `{ preview, operation }`. С `confirm: true` удаление подтверждает человек в клиенте через
+elicitation (в ревизии протокола 2025 — запросом клиенту, в 2026-07-28 — ответом `input_required`), подтверждение
+привязано к хэшу операции, а ответ — `{ deleted, operation }`. В ревизии 2026-07-28 подпись `requestState`, с которой
+клиент повторяет вызов, привязана ещё к пользователю сервера и действует 10 минут: подпись сервера другого
+пользователя и устаревшая — отказ `confirmation_required`. Окно подтверждения показывает каноническое имя класса и
+id целей (первые 10, дальше — «и ещё K»); алиас и `meta` класса пишет арендатор, поэтому в окно они не попадают. Код
+операции, присланный агентом, подтверждением не считается; клиент без elicitation получает отказ
+`confirmation_required`. Причина каждой записи — `mcp: letopis_write`, её показывает `blame()`. Классы прав — `rule`,
+`Resource`, `member`, `Account`, `Class` и их потомков (правила, членства, описания классов) — `letopis_write` по
+умолчанию не пишет, не правит и не удаляет: отказ `acl_denied`. Агент под инъекцией в данных выдал бы постороннему
+членство или правило без подтверждения человека. Разрешает это только опция `allowAclWrite: true`.
+
+**stdio.** `letopis mcp` — сервер по stdio для клиентов MCP. Нужен пакет SDK: `npm i @modelcontextprotocol/server`
+(необязательная peer-зависимость). Строку подключения, схему и токен клиент передаёт флагами или переменными
+`LETOPIS_DSN`, `LETOPIS_SCHEMA`, `LETOPIS_TOKEN`; `--write` включает запись. Принимается только токен сессии
+пользователя — его выпускает приложение: `svc.auth.sessionFor(пользователь, { ttl })`, а рабочий арендатор сессии
+задаёт `auth.switch(арендатор)`. Ключ сервиса (`--api-key`) команда отклоняет: он даёт все права `auth.*` и лежал бы на
+машине агента. Без токена и с `--api-key` команда завершается с кодом 2 и пишет причину в stderr. Токен сессии в
+арендаторе System (так работает системный администратор) команда тоже отклоняет: опций `allowSystemAdmin` и
+`allowAclWrite` у неё нет. Конфигурация клиента (Claude Desktop, Claude Code, Cursor):
+
+```json
+{
+  "mcpServers": {
+    "letopis": {
+      "command": "npx",
+      "args": ["letopis", "mcp"],
+      "env": {
+        "LETOPIS_DSN": "postgres://shop_app:app-secret@localhost:5432/shop",
+        "LETOPIS_SCHEMA": "v2.shop",
+        "LETOPIS_TOKEN": "<токен сессии пользователя>"
+      }
+    }
+  }
+}
+```
+
+**HTTP.** Встроенного HTTP-сервера нет. `createMcpServer(db, { write, maxRows, maxBytes })` из `letopis/mcp` отдаёт
+сервер MCP, а приложение подключает его к своему обработчику `createMcpHandler` из SDK со своей авторизацией
+OAuth 2.1: токен запроса проверяет приложение и находит по нему пользователя letopis. Подключение — сессия
+пользователя (`connect({ token })`) или фасад `svc.as(пользователь)`: ключ сервиса остаётся в процессе приложения.
+Подключение в обход RLS получает отказ `bypass_rls`, корень сервиса без `as()` и подключение без сессии —
+`user_session_required`, фасад явной транзакции `db.begin()` — `invalid_query`. Сессию в арендаторе System — так
+работает системный администратор: его роль `admin` даёт права на аккаунты, членства и правила установки — сервер тоже
+отклоняет с `user_session_required`, если не передана опция `allowSystemAdmin: true`.
+
+<!-- run: mcp -->
+```ts
+import { up, connect } from 'letopis'
+import { createMcpServer } from 'letopis/mcp'
+import { createMcpHandler } from '@modelcontextprotocol/server'
+
+const ADMIN = 'postgres://postgres:secret@localhost:5432/shop'
+const APP = 'postgres://shop_app:app-secret@localhost:5432/shop'
+const r = await up({ dsn: ADMIN, schema: 'shop', quiet: true,
+  tenant: { name: 'Ромашка', user: { name: 'Анна', login: 'anna@shop.ru', password: 'Ромашка-2026!' } } })
+const svc = await connect({ dsn: APP, schema: r.schema, apiKey: r.serviceKey! })
+
+// authInfo — итог проверки токена запроса приложением; в extra оно кладёт id аккаунта letopis
+const mcp = createMcpHandler(async ({ authInfo }) =>
+  createMcpServer(await svc.as(String(authInfo?.extra?.account), { tenant: r.tenant!.tenant })))
+// в HTTP-обработчике приложения, после проверки токена: return mcp.fetch(request, { authInfo })
+```
+
+Фабрику обработчик вызывает на каждый запрос HTTP, поэтому `createMcpServer` проверяет подключение каждый раз (один
+запрос к базе).
+
+Проверить обработчик можно без сети: клиент SDK из пакета `@modelcontextprotocol/client` ходит в него через `fetch`
+приложения — `new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { fetch: (url, init) =>
+mcp.fetch(new Request(url, init), { authInfo }) })`. Так пример выше проверяет тест `docs` (сценарий `mcp` в
+`lib/test/docs.test.ts` репозитория): без `write` клиент видит три инструмента, а `letopis_model` отвечает от имени
+Анны в магазине.
 
 ### Сырой SQL
 
@@ -1473,12 +2091,14 @@ const [{ n }] = await db.sql`select count(*)::int as n from "v2.shop".entity whe
 letopis sync <модуль> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--apply]
 letopis types --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--out <файл>]
 letopis load <файлы…> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--class <Класс>]
-  [--duplicates error|first|last] [--existing error|skip|update] [--commit-every <N>] [--verify]
+  [--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 <имя>]
+  [--rename <Старое>=<Новое>]… [--update] [--commit-every <N>] [--partition <имя>] [--initial]
+letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пользователя> [--write]
+  (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)
 ```
 
 ### Наблюдение
@@ -1546,9 +2166,10 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 
 | Точка входа | Что экспортирует |
 |---|---|
-| `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` и другие |
-| `letopis/model` | `hub`, `link`, `one`, `many`, `End`, типы `Infer`, `InferLinks`, `Model`, `ClassDef`, `ClassMeta`, `HistoryPolicy`; `normalizeSchema`, `translatePattern`, тип `JsonSchema` |
-| CLI `letopis` | `sync`, `types`, `load`, `verify`, `maintain`, `describe`, `import` ([раздел 13](#13-эксплуатация)) |
+| `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/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` с заменой.
 
@@ -1563,6 +2184,8 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `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 объекта класса с ключом в арендаторе сессии |
@@ -1580,7 +2203,7 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | модификаторы | `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 })` |
 | слоты | после глагола: `.Роль.set(значение)`, `.Роль.unset()`, `.Роль.add(значение)`, `.Роль.remove(значение)` |
-| терминалы | `rows()`, `first()`, `ids()`, `count({ paths })`, `paths()`, `versions({ follow })`, `sum(поле)`, `avg(поле)`, `min(поле)`, `max(поле)`, `countBy(поле)` |
+| терминалы | `rows()`, `first()`, `ids()`, `count({ paths })`, `paths()`, `versions({ follow })`, `diff({ from, to, follow })`, `blame({ at, limit })`, `sum(поле)`, `avg(поле)`, `min(поле)`, `max(поле)`, `countBy(поле)` |
 
 ### `db.auth`
 
@@ -1607,6 +2230,23 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 Вид креда `kind` — `^[A-Z][A-Z0-9_]{1,31}$` (`PASSWORD`, `EMAIL`, `TELEGRAM` …); `SESSION`, `APIKEY`, `KEYSECRET`,
 `OTP`, `TOTP` и `KEY` заняты.
 
+### Проектор
+
+`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 мс); `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 }` |
+| `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` в формате загрузчика |
+
 ### Строка ответа
 
 | Поле | Что значит |
@@ -1628,11 +2268,11 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 - методы цепочки: `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`; охранники снесённого API — `run`, `execute`, `account`;
+  `owner`, `forUpdate`, `cache`, `rekey`, `diff`, `blame`; охранники снесённого API — `run`, `execute`, `account`;
 - корень `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`; охранники — `reloadSchema`, `accounts`,
-  `credentials`, `resources`, `rules`, `compact`;
+  `schema`, `token`, `tenant`, `trimHistory`, `rekeyClass`, `cache`, `projector`, `rebuildAggregates`; охранники — `reloadSchema`,
+  `accounts`, `credentials`, `resources`, `rules`, `compact`;
 - батч: `discard`, `size`.
 
 ## 16. Ошибки
@@ -1652,16 +2292,19 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `acl_denied` | LT006 | отказ по правилам доступа |
 | `id_mismatch`, `id_from_db` | LT007, LT008 | id не равен v5 от ключа; id класса без ключа выдаёт база |
 | `immutable_key` | LT009 | ключевое поле, id, арендатор и владелец не меняются (новый ключ — `rekey`) |
-| `invalid_class` | LT010 | описание класса отклонено, класс не найден или абстрактный |
+| `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` политики хранения |
+| `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` удалённого объекта, чьё удаление ещё не прочёл проектор его класса: сначала `run()` проектора |
 
 Коды библиотеки:
 
@@ -1678,9 +2321,14 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `no_key` | `upsert`, `rekey` или `idOf` у класса без ключа |
 | `no_path` | между классами соседних шагов нет перехода |
 | `invalid_query` | цепочку или API используют неверно (модификатор шага `deep`, `exact`, `alias`, `tags` или `owner` после глагола, слот не после глагола, курсор `after()` со значением не того типа, что поле `sort`, без `v` или с `id` не uuid и т. п.) |
-| `admin_required` | загрузчику нужно администраторское подключение |
+| `admin_required` | загрузчику, проектору и `rebuildAggregates` нужно администраторское подключение |
+| `rebuild_required` | проекция построена другой версией проектора (`version`): нужна перестройка `rebuild()`; `rebuild({ tenant })`, пока проекции нет или идёт перестройка пачками |
+| `projector_busy` | перестройку не начать: проектор сейчас работает в другом процессе |
+| `not_empty` | первая заливка (`initial`) — только в пустую схему |
 | `class_not_loadable` | строки `Class` загрузчик не принимает |
-| `bypass_rls` | `connect()` с ролью, которая обходит RLS, без `allowBypassRls` |
+| `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; в тексте — замена |
 
 Отказ PostgreSQL в праве (`42501`) приходит, например, при `upsert` поверх чужой строки, которую нельзя править.
@@ -1715,9 +2363,32 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 запись: 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 | Для сравнения |
+|---|---|---|
+| операция с агрегатом, один писатель | 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 с |
+
+Триггеры агрегатов срабатывают на каждом операторе записи, но у классов без агрегатов их цены замер не видит: разница
+p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101.bench.mjs`, четыре прогона) регрессий записи и чтения
+против 1.1 не показал: два выброса не повторились в отдельных проверках.
+
 ## 18. Ограничения
 
-Здесь собрано то, что letopis 1.0 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
+Здесь собрано то, что letopis 1.2 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
 
 **Платформа**
 
@@ -1732,6 +2403,9 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
   с `prepare: false` в `connect({ sql })`.
 - Символ NUL (`\u0000`) в строках данных невозможен: PostgreSQL не хранит его в `jsonb`; такие данные
   отклоняются ещё при разборе JSON (официальный набор JSON-Schema-Test-Suite, группы «nul characters», пропущены).
+- На PostgreSQL до 18.6 параллельная сборка индекса GIN могла записать в статистику таблицы (`pg_class.reltuples`)
+  неверное число строк, после чего автоочистка переставала её обрабатывать. Первая заливка поэтому всегда
+  заканчивается `ANALYZE`, но сервер лучше обновить до 18.6 или новее.
 
 **Запись и целостность**
 
@@ -1742,6 +2416,10 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
   библиотеки всегда открываются на этом уровне.
 - `COPY` в таблицы под RLS PostgreSQL не выполняет; массовая загрузка — только загрузчиком на администраторском
   подключении.
+- Первая заливка закрывает таблицы схемы на всё время загрузки — и для записи, и для чтения: она для пустой схемы
+  (засевка, перенос, импорт), а не для работающей системы. Выигрыш у неё — в базе (индексы и ограничения строятся
+  один раз); подготовку строк в загрузчике она не ускоряет, а только ведёт одновременно с `COPY`, поэтому на миллионе
+  объектов она быстрее обычной загрузки примерно в 2,2 раза.
 - Загрузчику база доверяет: данные, концы и id загруженных строк проверяет код библиотеки (валидатор на TypeScript),
   а не триггеры; база сверяет только цели вне загрузки, арендаторов и владельцев одним запросом в конце.
   Защита — загрузчик только у администратора, дифференциальные тесты валидатора против базы, `load({ verify: true })`
@@ -1790,11 +2468,19 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 - Счётчики попыток OTP и TOTP откатываются вместе с транзакцией вызывающего: частоту попыток ограничивает сервис.
 - Самостоятельная привязка занятого идентификатора отвечает `acl_denied` — пользователь с недавним входом так
   узнаёт, что идентификатор занят. Изменения прав во всех арендаторах упорядочены одной строкой счётчика.
-- Число невидимых строк, мешающих удалению, и существование аккаунта по id (как цели ссылки) не скрываются.
+- Число невидимых строк, мешающих удалению или смене класса (`reclass_denied`), и существование аккаунта по id (как
+  цели ссылки) не скрываются.
+- Ужесточение описания класса и `rekeyClass` проверяют все строки семейства, поэтому требуют права `READ` без условий
+  на все строки класса и его потомков: иначе пробное ужесточение (`maximum`, `enum`, `pattern`) отвечало бы числом
+  невидимых строк, которые ему не соответствуют. Системный администратор, ужесточая класс System, получает число
+  нарушающих строк других арендаторов (`others`): это уровень установки.
 - Метаданные классов (`meta`) видны всем, у кого есть сессия: строки `Class` читает любой. Секретам там не место.
-- Прикладная роль может замедлить установку для всех: `LOCK TABLE entity`, advisory-блокировки с предсказуемыми
-  ключами, поддельные сигналы `NOTIFY` (лишь сбрасывают кэш), частая смена прав (одна строка счётчика на
-  установку). По глобальному номеру журнала видна общая активность записи.
+- Прикладная роль может замедлить установку для всех: `LOCK TABLE entity`, advisory-блокировки с ключами `lock()`
+  приложения, поддельные сигналы `NOTIFY` (лишь сбрасывают кэш), частая смена прав (одна строка счётчика на
+  установку). По глобальному номеру журнала видна общая активность записи. Внутренние блокировки — семейства
+  классов, проектора и обслуживания — строки таблицы `secret`, а не advisory: ни прикладная, ни посторонняя роль базы
+  их не займёт. Писатель семейства проходит шлюз ужесточения в подтранзакции — одной на первую запись в семейство за
+  транзакцию.
 
 **История, сигналы, кэш**
 
@@ -1805,19 +2491,91 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
   старше яруса `all` у класса с политикой `verify()` не отличит от прореживания.
 - Журнал без партиций: прореживание удаляет версии пачками, файл таблицы сам не уменьшается (место занимают новые
   версии после autovacuum); вернуть место системе — `VACUUM FULL` или `pg_repack` в окно обслуживания.
-- Сигналы раскрывают активность: слушать канал PostgreSQL разрешает любой роли, и по именам классов в сигналах
-  видно, когда и в какие классы пишут (ни id, ни арендатора, ни данных в сигнале нет). Поддельный сигнал лишь
-  сбросит кэш лишний раз.
+- Сигналы раскрывают активность: слушать канал PostgreSQL разрешает любой роли. В режиме `class` видно, когда и в
+  какие классы пишут; `tenant` добавляет псевдонимы арендаторов; `opaque` прячет, что записано, но не когда: время и
+  частоту записи по псевдониму видно, а детерминированный токен — основа частотных атак. Время записи видно и без
+  сигналов: `pg_stat_all_tables` и `pg_locks` открыты для PUBLIC. Режим `none` убирает сигналы, но тогда отзыв
+  сессии действует в кэше других процессов только по сроку, а новый класс появляется в их реестре в течение
+  5 секунд. Настоящая защита от посторонних ролей — отдельная база. Поддельный сигнал лишь сбросит кэш лишний раз:
+  по `*` и незнакомым токенам реестр перечитывается не чаще раза в 5 секунд, а поддельный сигнал изменения классов
+  перечитывает его, как настоящий, но не больше одного перечитывания одновременно.
+- Режим сигналов меняется `up({ signals })`, и после этого нужно перезапустить процессы: режим и ключ сигналов
+  процесс читает при подключении (нагрузку другого режима он считает чужой и сбрасывает весь кэш).
+- PostgreSQL ниже 18.2 мог усечь CLOG, который ещё нужен непрочитанным сигналам: `up()` предупреждает об этом.
 - Очередь `NOTIFY` (8 ГБ) общая для кластера: зависший слушатель её переполняет, и тогда транзакции с `NOTIFY`
   падают при фиксации. Библиотека читает сигналы сразу, `maintain()` предупреждает о заполнении больше чем
   наполовину.
+- Транзакции с `NOTIFY` PostgreSQL фиксирует по одной: общую для кластера блокировку очереди сигналов фиксация держит
+  вместе с записью на диск. Запись сырым SQL на своём соединении шлёт сигнал из триггера в той же транзакции, поэтому
+  параллельные писатели сырым SQL фиксируются по очереди: на машине замеров 20 таких писателей делали около 520
+  вставок в секунду. Транзакции библиотеки, в том числе `db.sql` и `db.transaction()`, фиксируют данные без `NOTIFY` и
+  отправляют сигналы потом, отдельно, поэтому их писатели этой очереди не ждут: 20 писателей библиотеки делали около
+  2 000 операций в секунду.
 - Горизонт подписки общий для кластера: долгая пишущая транзакция задерживает события всех подписчиков
   (`sub.lag()`); длинные операции лучше вести пачками.
 - Кэш результатов между процессами устаревает на интервал отправки сигналов (100 мс) плюс доставку и на время
-  переподключения слушателя; срок `ttl` — предохранитель.
+  переподключения слушателя: обрыв соединения слушателя postgres.js не сообщает, поэтому до переподключения кэш
+  работает, а после — сбрасывается целиком. Срок `ttl` — предохранитель.
 - Курсор подписки «с этого момента» несёт снимок момента подписки, пока не пройдёт его границу: такой
   курсор длиннее обычного.
 
+**Проекторы**
+
+- Проектор — процесс администратора: он работает только на администраторском подключении, читает журнал всех
+  арендаторов в обход 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` своих источников, пока у арендатора есть его производные классы: запустите его или удалите их.
+
+**Агрегаты в базе**
+
+- Агрегат выстраивает писателей одного объекта в очередь: каждая операция блокирует строку цели и пишет её версию.
+  На машине замеров 20 писателей одного кошелька с агрегатом делали 152 операции в секунду (p95 — 0,47 с), без
+  агрегата — 1 987. Для горячих счётчиков берите проектор со свёрткой пачкой.
+- `reclass` и `rekey` копят вклады до конца переноса, а каскад удаления и загрузчик применяют их по операторам:
+  правило класса проверяется на итоге каждого оператора каскада и каждой пачки загрузчика. Поэтому загрузка, где
+  списания идут пачкой раньше пополнений, получит `invalid_data`, хотя итог всей загрузки допустим. Каждая пачка,
+  задевшая цель, пишет её версию.
+- Агрегат арендатора не считает строки класса System, а поле строки System считает только источники System.
+
+**Агенты и MCP**
+
+- Обёртка `<untrusted-data-…>` — смягчение, а не защита: модель может последовать тексту внутри неё. Защищают права
+  базы: агент читает и пишет только то, что разрешено его пользователю. В `structuredContent` данные базы лежат в
+  `data` и `error` рядом с пояснением `notice`, без меток: клиент, который отдаёт модели его, а не текст, передаёт
+  данные с пояснением, но без случайной метки.
+- По умолчанию сервер только читает; запись — `write: true` (`--write`); удаление — только с подтверждением человека.
+  Классы прав сервер пишет только с `allowAclWrite`, сессию в арендаторе System принимает только с
+  `allowSystemAdmin`; `create`, `update` и `upsert` остальных классов подтверждения человека не требуют.
+- Обработчик HTTP в ревизии 2025 работает без состояния: экземпляр на запрос не знает возможностей клиента, поэтому
+  удаление по нему отклоняется (`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**
 
 - 1.0 — новая major-версия, а не продолжение 0.21: `count()`, `paths()`, `create`, роли, множественные концы
@@ -1835,7 +2593,8 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 # connect — подключение под сессией, отказ ролям в обход RLS, реестр, отложенный сигнал, перевод ошибок (этап 2)
 # context — сессии, вход сервиса по ключу, политики RLS этапа 1 (этап 1)
 # access-rest — оставшиеся строки этапа 5: загрузка от имени пользователя, баланс №20, 22, 29, upsert и { rev } под ACL, встраивание acl_ok (этап 5)
-# acl — права ACL: перенос набора 0.21, условия на строки, вес и запрет по умолчанию, каскад, запрет на потомке, deep, невидимая цель, сырой SQL против библиотеки (этап 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)
 # auth — креды (пароль, ключ, ключ + секрет, OTP, TOTP, identity), выравнивание времени, регистр, гашение сессий, недавний вход (этап 5)
 # balance — пополнение и списание: идемпотентность по opId, гонки, взаимная блокировка, обрыв связи (TCP-прокси), корректировка под { rev } и forUpdate (этап 4)
@@ -1845,21 +2604,21 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 # chain-write — запись цепочками: create, update, upsert, delete с превью, anonymize, reclass, слоты, inc, { rev }, fan-out, откат плана (этап 4)
 # demo — демо-домен booking на Zod: сид из моделей, запись данных, id по ключу, согласие Zod и базы (этап 2)
 # docs — примеры документации исполняются: помеченные блоки README и шпаргалки (русские и английские) — сценариями против PostgreSQL 18 (этап 8)
-# engine-attacks — атаки сырым SQL от прикладной роли: строки §7.3.1 этапов 1 и 3 с конкретными исходами (этапы 1, 3)
-# engine-class — классы как сущности: метасхема, наследование, пересчёт потомков, ужесточение, метаданные (этап 1)
+# 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)
-# engine-races — гонки на двух соединениях в обоих порядках без пауз по времени (этап 1)
-# explain — индексы цепочек от роли приложения: снаружи первичный ключ и (class, tenant), внутри find_*() — GIN (этап 3)
-# find-ids-parity — 30 цепочек через find_*() и прямым чтением под RLS дают одинаковые ответы (этап 3)
+# 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 (этап 5)
+# impersonation — имперсонация: letopis.account только для сервиса с правом, запреты целей, author и agent в журнале, sessionFor; реестр db.as() — один на арендатора, не пустеет, перечитывается по сигналу своего арендатора (этап 5; доработки после точки Б)
 # install — установщик и роли: повторная установка, две установки в базе, три таблицы (этап 1)
 # member — членство: работа в арендаторе по ролям, auth.switch, выход с переходом владения, системные строки, роли арендатора без прав System (этап 5)
 # model — модели на Zod, нормализатор JSON Schema, перевод шаблонов, совпадение с метасхемой базы (этап 2)
 # load — загрузчик: несколько классов, циклы, $key и $ext, повторы, existing, порции, режим истории, запрос по целям вне загрузки, CLI (этап 4)
-# roles — роли и права: установка без суперпользователя, функции владельца, триггеры по каталогу (этап 1)
+# roles — роли и права: установка без суперпользователя, функции владельца, триггеры по каталогу, журнал без колонки changed (этап 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)
@@ -1875,11 +2634,16 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 # verify — законные разрывы и подмены, verify({ data: true }): данные, концы, арендаторы, id по ключу; права и CLI (этап 6)
 # retention — политика хранения: ярусы, конечный срок, особые версии, удалённые, asOf, cursor_expired, часовой пояс, догоняющий запуск, наследование и умолчание — против эталона на TypeScript (этап 6)
 # watch — подписка по курсору: порядок фиксации, долгая транзакция, возобновление, обрыв слушателя, два арендатора (этап 6)
-# cache — кэш результатов: попадание, свои и чужие записи, ключ с пользователем, права, погашенные сессии, обрыв слушателя, ttl, пометка класса, без LISTEN, гонка, db.sql (этап 6)
+# cache — кэш результатов: попадание, свои и чужие записи, ключ с пользователем, права, погашенные сессии, обрыв слушателя, ttl, пометка класса, без LISTEN, гонка, db.sql, предел счётчиков сигналов (этап 6; план 1.1, точка А)
 # maintain — обслуживание: истёкшие сессии и коды, права, один процесс под блокировкой, расписание (этап 6)
 # up — полный установщик: свежая установка, повторный накат, свои сиды, автосоздание базы, UTF8, версия 17, upgrade с миграциями, PGlite, первый арендатор и пользователь (up({ tenant }), createTenant) (этапы 6, 8)
 # 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)
+# security-final — итоговое ревью безопасности (этап 8, §7.10 №8.4): блокировка семейства по арендатору корня, account_purge без права и restore/purge чужого id не дают ни утечки, ни блокировки; функции этапа 6, log_refs_at, срезы find_* по журналу и watch_read не выходят за свой арендатор; NOTIFY несёт только имена или токены режима; ключ кэша различает токен, актора и арендатора (этап 8)
 ```