letopis 1.0.0 → 1.1.0

package/README.md

@@ -1,4 +1,4 @@
-# letopis 1.0
+# letopis 1.1
 
 **letopis** — библиотека для Node.js, хранилище версионированных сущностей на PostgreSQL 18. Каждое изменение
 сохраняется версией в журнале. Поэтому у любого объекта есть история, состояние на любую дату и подписка на
@@ -188,10 +188,22 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 
 ### Сигналы
 
-Запись сообщает об изменённых классах через `NOTIFY`. Сырой SQL шлёт сигнал из триггера, и PostgreSQL доставляет
+Запись сообщает об изменениях через `NOTIFY` в канал схемы. Сырой SQL шлёт сигнал из триггера, и PostgreSQL доставляет
 его при фиксации. Транзакции библиотеки шлют сигналы отложенно: нотификатор процесса отправляет их раз в 100 мс
-(`notifyIntervalMs`). В сигнале только имя класса или начало хэша токена погашенной сессии — ни id, ни данных.
-По сигналам перечитывается реестр классов, сбрасывается кэш результатов и будится подписка.
+(`notifyIntervalMs`), а неотправленные из-за ошибки — повторяет. Что несёт сигнал записи, задаёт режим установки
+`up({ signals })`:
+
+| Режим | Сигнал записи | Что видит любая роль, которая может подключиться к базе |
+|---|---|---|
+| `class` (по умолчанию) | имя класса: `Booking` | имена классов и время записи |
+| `tenant` | имя класса и токен арендатора: `Booking@3f9c…` | ещё и псевдонимы арендаторов |
+| `opaque` | токен класса и токен арендатора | только время и частоту записи по псевдонимам |
+| `none` | сигналов нет | ничего |
+
+Погашенная сессия шлёт `session:<начало хэша токена>`, сброс — `*`; ни id, ни данных в сигналах нет. Токен — ключевой
+HMAC: сопоставить псевдоним с именем может только процесс с ключом сигналов, а ключ выдаётся сервисам (право
+`letopis.signals`). По сигналам перечитывается реестр классов, сбрасывается кэш результатов и будится подписка;
+что меняет режим для кэша и подписки — в [разделе 12](#12-подписка-на-изменения-и-кэш).
 
 ## 3. Установка и подключение
 
@@ -210,6 +222,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 +231,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
@@ -467,8 +489,8 @@ id из email подбирается перебором и остаётся в
 `syncModels(db, модели)` без `apply` — сухой прогон, с `{ apply: true }` — применение. Результат:
 `{ applied, created, updated, unchanged, skipped, lost }`; в `skipped` — классы System, их меняет только установка.
 `syncModels` трогает только переданные классы и ничего не удаляет. Безопасные изменения — новое необязательное поле или
-конец, метаданные, алиас — применяются сразу. Ужесточение проверяет все строки семейства, и если им мешают строки,
-приходит `tightening_conflict` со списком. Классы пишутся в арендатора сессии, и другие арендаторы их не видят.
+конец, метаданные, алиас — применяются сразу. Всё остальное, в том числе любая правка условий `anyOf` и `oneOf`, —
+ужесточение: оно проверяет все строки семейства, и если им мешают строки, приходит `tightening_conflict` со списком. Классы пишутся в арендатора сессии, и другие арендаторы их не видят.
 Классы, общие для всех, лежат в System: их ставит сид установки или импорт.
 
 То же из командной строки:
@@ -1056,6 +1078,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
@@ -1294,8 +1332,9 @@ 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`.
 
 ### Срез на дату
 
@@ -1339,6 +1378,31 @@ 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 версий
+```
+
+- `diff()` — по объекту шага: `{ id, class, from, to, changes }`, где изменение — `{ path, kind, before, after }`,
+  `kind` — `added`, `removed` или `changed`, а путь начинается с раздела строки: `data`, `links`, `tags`, `owner`,
+  `class`. Объекты данных сравниваются по ключам, массивы — целиком; множественный конец и теги — по элементам.
+  Если на момент `from` объекта не было, все пути — `added`; если на момент `to` он удалён — `to.deleted: true`.
+- `blame()` — `{ id, class, rev, complete, fields }`: у каждого листа — версия, которая последней его изменила,
+  `author`, `agent`, `op`, `reason` и `exact`. `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 -->
@@ -1403,11 +1467,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()` очищает кэш.
@@ -1452,8 +1524,9 @@ 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` с учётом наследования, если они заданы. Из командной строки —
+`letopis describe --format text --out llms.txt`.
 
 ### Сырой SQL
 
@@ -1473,12 +1546,12 @@ 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]
 ```
 
 ### Наблюдение
@@ -1628,7 +1701,7 @@ 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`,
@@ -1679,6 +1752,7 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `no_path` | между классами соседних шагов нет перехода |
 | `invalid_query` | цепочку или API используют неверно (модификатор шага `deep`, `exact`, `alias`, `tags` или `owner` после глагола, слот не после глагола, курсор `after()` со значением не того типа, что поле `sort`, без `v` или с `id` не uuid и т. п.) |
 | `admin_required` | загрузчику нужно администраторское подключение |
+| `not_empty` | первая заливка (`initial`) — только в пустую схему |
 | `class_not_loadable` | строки `Class` загрузчик не принимает |
 | `bypass_rls` | `connect()` с ролью, которая обходит RLS, без `allowBypassRls` |
 | `removed` | снесённое API 0.21; в тексте — замена |
@@ -1715,9 +1789,15 @@ 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.
+
 ## 18. Ограничения
 
-Здесь собрано то, что letopis 1.0 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
+Здесь собрано то, что letopis 1.1 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
 
 **Платформа**
 
@@ -1732,6 +1812,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 +1825,10 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
   библиотеки всегда открываются на этом уровне.
 - `COPY` в таблицы под RLS PostgreSQL не выполняет; массовая загрузка — только загрузчиком на администраторском
   подключении.
+- Первая заливка закрывает таблицы схемы на всё время загрузки — и для записи, и для чтения: она для пустой схемы
+  (засевка, перенос, импорт), а не для работающей системы. Выигрыш у неё — в базе (индексы и ограничения строятся
+  один раз); подготовку строк в загрузчике она не ускоряет, а только ведёт одновременно с `COPY`, поэтому на миллионе
+  объектов она быстрее обычной загрузки примерно в 2,2 раза.
 - Загрузчику база доверяет: данные, концы и id загруженных строк проверяет код библиотеки (валидатор на TypeScript),
   а не триггеры; база сверяет только цели вне загрузки, арендаторов и владельцев одним запросом в конце.
   Защита — загрузчик только у администратора, дифференциальные тесты валидатора против базы, `load({ verify: true })`
@@ -1805,16 +1892,25 @@ 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()` предупреждает о заполнении больше чем
   наполовину.
 - Горизонт подписки общий для кластера: долгая пишущая транзакция задерживает события всех подписчиков
   (`sub.lag()`); длинные операции лучше вести пачками.
 - Кэш результатов между процессами устаревает на интервал отправки сигналов (100 мс) плюс доставку и на время
-  переподключения слушателя; срок `ttl` — предохранитель.
+  переподключения слушателя: обрыв соединения слушателя postgres.js не сообщает, поэтому до переподключения кэш
+  работает, а после — сбрасывается целиком. Срок `ttl` — предохранитель.
 - Курсор подписки «с этого момента» несёт снимок момента подписки, пока не пройдёт его границу: такой
   курсор длиннее обычного.
 
@@ -1845,7 +1941,7 @@ 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-attacks — атаки сырым SQL от прикладной роли: строки §7.3.1 этапов 1 и 3 с конкретными исходами; ключ сигналов без права, заливка поддельными сигналами, в том числе Class (этапы 1, 3; план 1.1, этап 2 и точка А)
 # engine-class — классы как сущности: метасхема, наследование, пересчёт потомков, ужесточение, метаданные (этап 1)
 # engine-write — конвейер записи сырым SQL: id v5, умолчания, merge, inc, удаление, воскрешение, журнал, сигналы (этап 1)
 # engine-races — гонки на двух соединениях в обоих порядках без пауз по времени (этап 1)
@@ -1859,7 +1955,7 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 # 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 +1971,14 @@ 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 (план 1.1, этап 3)
 # 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)
 ```

package/dist/admin.d.ts

@@ -72,6 +72,10 @@ export interface ModelDescription {
         system: boolean;
         fields: Record<string, unknown>;
         required: string[];
+        /** Условия по нескольким полям (`fields.anyOf` описания с учётом наследования): хотя бы одно должно выполняться. */
+        anyOf?: unknown[];
+        /** Условия по нескольким полям (`fields.oneOf`): ровно одно должно выполняться. */
+        oneOf?: unknown[];
         ends: Record<string, unknown>;
         key: string[];
         history: unknown;

package/dist/admin.js

@@ -134,6 +134,8 @@ export function describe(a) {
         system: SYSTEM_CLASSES.has(c.name),
         fields: (c.schema.properties ?? {}),
         required: (c.schema.required ?? []),
+        ...(Array.isArray(c.schema.anyOf) ? { anyOf: c.schema.anyOf } : {}),
+        ...(Array.isArray(c.schema.oneOf) ? { oneOf: c.schema.oneOf } : {}),
         ends: c.ends,
         key: c.key,
         history: c.history,
@@ -158,6 +160,10 @@ export function describeText(d) {
         });
         if (fields.length)
             out.push(`- поля: ${fields.join(', ')}`);
+        if (c.anyOf)
+            out.push(`- условия anyOf (хотя бы одно): ${JSON.stringify(c.anyOf)}`);
+        if (c.oneOf)
+            out.push(`- условия oneOf (ровно одно): ${JSON.stringify(c.oneOf)}`);
         const ends = Object.entries(c.ends).map(([k, v]) => {
             const e = v;
             return `${k}${e.required ? '*' : ''} → ${Array.isArray(e.class) ? e.class.join('|') : e.class}${e.many ? '[]' : ''}`;

package/dist/cache.d.ts

@@ -1,3 +1,4 @@
+import { Signals, type Signal } from './signals.js';
 /** Классы, строки которых меняют права и схему: их сигнал сбрасывает весь кэш. */
 export declare const ACL_CLASSES: ReadonlySet<string>;
 export interface CacheOptions {
@@ -25,14 +26,22 @@ export interface CacheStats {
 /** Снимок счётчиков до запроса: ответ кладётся, только если они не изменились. */
 export interface CacheToken {
     epoch: number;
-    classes: [string, number][];
+    /** Класс, его счётчик и счётчик пары «класс, арендатор» (без арендатора — сигналов класса в любом). */
+    classes: [string, number, number][];
     session: number;
+    /** Токен арендатора запроса; null — ответ сбрасывается сигналом класса из любого арендатора. */
+    tenant: string | null;
 }
 /** Начало sha256 токена — так база называет сессию в сигнале session:<16 hex>. */
 export declare const sessionTag: (token: string | null) => string;
 export declare class ResultCache {
+    private sig;
+    private allTenants;
     private map;
     private classEpoch;
+    /** Сигналы класса в арендаторе: по паре и по классу в любом арендаторе (для ответов без арендатора). */
+    private pairEpoch;
+    private anyEpoch;
     private sessionEpoch;
     private epoch;
     private listening;
@@ -40,7 +49,11 @@ export declare class ResultCache {
     readonly ttlMs: number;
     readonly ttlOnly: boolean;
     private max;
-    constructor(opts?: CacheOptions);
+    /**
+     * sig — режим сигналов и ключ подключения (разбор нагрузки, токены арендаторов); allTenants —
+     * подключение видит строки всех арендаторов (обходит RLS): ответ сбрасывается сигналом из любого.
+     */
+    constructor(opts?: CacheOptions, sig?: Signals, allTenants?: boolean);
     /** Кэш работает: слушатель на месте или режим только по сроку. */
     get enabled(): boolean;
     /** Ключ ответа: запрос, параметры и тот, кто спрашивает. */
@@ -49,24 +62,35 @@ export declare class ResultCache {
         account?: string;
         tenant?: string | null;
     }): string;
-    /** Снимок счётчиков классов и сессии — до запроса. */
-    token(classes: readonly string[], session: string): CacheToken;
+    /** Снимок счётчиков классов, пар с арендатором запроса (id) и сессии — до запроса. */
+    token(classes: readonly string[], session: string, tenantId?: string | null): CacheToken;
+    private pairCount;
     get(key: string): unknown[] | undefined;
     /** Положить ответ, если с момента снимка не было сигналов о его классах и сессии. */
     set(key: string, value: unknown[], classes: readonly string[], session: string, tok: CacheToken, ttlMs: number, sessionExpires: number | null): boolean;
-    /** Сбросить ответы, читавшие эти классы. */
+    /** Сбросить ответы, читавшие эти классы (во всех арендаторах). */
     invalidate(classes: Iterable<string>): void;
+    /** Сбросить ответы класса в арендаторе (токен) и ответы без арендатора; null — во всех. */
+    private invalidateIn;
     /** Сбросить ответы сессии (тег — начало sha256 токена). */
     invalidateSession(tag: string): void;
+    /**
+     * Счётчик сигналов по ключу (класс, пара «класс, арендатор», сессия). Ключи приходят в нагрузке сигнала, а её
+     * может прислать любая роль базы: при переполнении карта очищается, и снимки в полёте устаревают целиком
+     * (epoch), — иначе заливка разными именами копила бы счётчики без предела (ревью №1 точки А плана 1.1).
+     */
+    private bump;
     /** Весь кэш. */
     clear(): void;
+    /** Сброс по разобранному сигналу. */
+    apply(s: Signal): void;
     /**
-     * Имена из сигнала или из letopis.changed своей транзакции: классы, `*`, `session:<тег>`,
-     * `session:*`. raw — запись через db.sql: весь кэш.
+     * Нагрузки из letopis.changed своей транзакции (те же, что уйдут сигналом). raw — запись через db.sql:
+     * весь кэш.
      */
     changed(names: Iterable<string>, raw?: boolean): void;
-    /** Сигнал от базы. */
-    signal(name: string): void;
+    /** Сигнал от базы: нагрузка или уже разобранный. */
+    signal(s: string | Signal): void;
     /** Слушатель (пере)подключился: сигналы за время обрыва потеряны — весь кэш. */
     listen(): void;
     stats(): CacheStats;