letopis 0.20.3 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,354 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [1.0.0] — 2026-10-09
+
+letopis 1.0 — новая реализация хранилища по плану `reports/PLAN-LETOPIS-1.0.md` (редакция 8), основанному на
+предложении «Свод» (`reports/PROPOSAL-SVOD.md`). Целостность, история, изоляция арендаторов и права проверяет
+сама база — и для библиотеки, и для сырого SQL. Переход с 0.21 — [MIGRATION.md](MIGRATION.md): импорт данных
+командой `letopis import` и таблица замен API. Подробная запись по этапам — ниже, в `[1.0.0-alpha.0]`.
+
+### BREAKING — платформа и хранение
+- PostgreSQL 18 и новее, Node 22 и новее. TimescaleDB, Redis и Docker не нужны; рантайм-зависимость одна —
+  `postgres`; fastest-validator заменён JSON Schema, модели на Zod 4 — необязательная peer-зависимость
+  (подпуть `letopis/model`).
+- Три таблицы: `entity` (текущие версии), `log` (журнал) и приватная `secret` (креды и сессии) вместо `Schema`,
+  `Entity`, `Account`, `Credential`, `Resource`, `Rule`. Классы, аккаунты, ресурсы и правила — строки системных
+  классов. Колонки `partition` нет: отдельные пространства — отдельные схемы `v2.<имя>`. Схема 0.21 на месте не
+  обновляется — данные переносит `letopis import`.
+- Журнал без партиций и политик TimescaleDB; хранение истории — политика «все версии — по дню — по неделе — по
+  месяцу — по году» (`history: { all, daily, weekly, monthly, yearly, tz }`), прореживает `maintain()`.
+  `compact()` снят: обрезка — `db.trimHistory()`, отказ от истории — `history: false`, который теперь отключает
+  и `versions`, `asOf`, `restore`, события подписки.
+- `up()` без Docker и без сидов по умолчанию: демо-домен — только `seeds: ['booking']`; схема — `v2.<имя>`.
+
+### BREAKING — идентификаторы и уникальность
+- Только v5: id объекта класса с ключом — v5 от имени класса и значений ключа как есть в пространстве арендатора
+  (`idOf`); у класса без ключа id выдаёт база. v4 и v7, `generate` и `from` ушли; `uuidv7()` и `LETOPIS_NS` —
+  охранники `removed`. Переданный id должен совпасть с вычисленным (`id_mismatch`); класс без ключа id не
+  принимает (`id_from_db`).
+- Уникальность — только ключ, правил `unique` нет; неявного ключа связи по её концам нет.
+- Ключевые поля, id, арендатор и владелец обычной правкой не меняются (`immutable_key`): новый ключ — `rekey()`
+  или `db.rekeyClass()`, оба выдают новые id и переводят ссылки. В 0.21 правка ключа проходила, но id переставал
+  ему соответствовать.
+- Смена класса — глагол `reclass()`: у класса без ключа id сохраняется, у класса с ключом вычисляется заново,
+  ссылки переводятся; правка класса обычной записью — `use_reclass`.
+
+### BREAKING — запись и транзакции
+- `create` — обычная вставка: занятый ключ — `exists` (`detail.id`), а не идемпотентный PUT. Замена целиком —
+  отдельный глагол `upsert`, только для класса с ключом (`no_key`) и только целым объектом.
+- `update` по-прежнему не создаёт; затронуто меньше строк, чем нашёл шаг, — откат плана с `target_not_found`,
+  `conflict` или `acl_denied`.
+- Ошибка любого запроса в `db.begin()` ломает транзакцию (в том числе `exists` и `conflict`): следующие вызовы и
+  `commit()` бросают исходную ошибку, `rollback()` проходит; обрыв связи во время `COMMIT` — `commit_unknown`.
+  В 0.21 повторный `commit` после ошибки молча проходил.
+- Каскад удаления — в триггере после оператора; удаление и создание одного id одним оператором —
+  `recreated_in_statement`; удаление, смена класса и ключа — только в `read committed` (`isolation_level`).
+- `db.as()` асинхронный и принимает арендатора: `await db.as(аккаунт, { tenant, owner })`.
+- `batch.execute()` — охранник с заменой `batch.run()`.
+
+### BREAKING — чтение
+- `count()` и агрегаты считают сущности последнего шага, а не пути; пути — `count({ paths: true })`; `run()` и
+  `execute()` сняты — пути отдаёт `paths()`.
+- `account()` снят: арендатор — свойство сессии (`connect({ token | apiKey })`, `db.as(…, { tenant })`,
+  `db.auth.switch()`).
+- Строка ответа: `tenant` вместо `account`, `at` вместо `updated`; новые поля `rev`, `author`, `op`, `agent`,
+  `reason`, `moved`.
+
+### BREAKING — доступ
+- Изоляция арендаторов и права действуют всегда — политиками RLS, для библиотеки и сырого SQL; права по умолчанию
+  запрещают. Опции `connect()` `partition`, `enforceAccount`, `enforceAcl`, `container`, `image`, `dataDir`,
+  `redisPort`, `version` — охранники `removed`. Роль, обходящая RLS, подключается только с `allowBypassRls`
+  (иначе `bypass_rls`).
+- Сессии — в PostgreSQL: `db.auth.sessions(store)` снят (`sessionFor`, `refresh`, `revoke`, `revokeAll`);
+  `enabled: false` гасит и живые сессии.
+- Фасады `db.accounts`, `db.credentials`, `db.resources`, `db.rules` сняты — системные классы `Account`,
+  `Resource`, `rule`, `member` и `db.auth`; `accounts.purge` — `db.auth.purgeAccount()`. `db.reloadSchema()` и
+  `db.acl.reload()` сняты: реестр и права обновляются сами по сигналу базы (принудительно — `db.refresh()`).
+- Системный сид — только общие группы и системные права; ресурсы продуктов (`chrono`, `payment`, `billing`,
+  `geo`, `shop`) в библиотеку не входят.
+
+### BREAKING — события, классы, ошибки
+- `watch(cb)` и `watch(класс, cb)` сняты: `db.watch({ from, classes })` — асинхронный итератор с курсором, без
+  потерь и повторов.
+- Классы описываются моделями на Zod (`hub`, `link`, `one`, `many`) или строками `Class` с JSON Schema;
+  `db.schema.define()` и CLI `schema-sync`, `gen-types` заменены `letopis sync` и `letopis types`; `db.schema` —
+  имя схемы.
+- Зарезервированы только имена методов цепочки и корня (`RESERVED_CLASS_NAMES`), а не 52 имени 0.21.
+- Ошибки — `LetopisError`, текст `letopis: <код>: <сообщение>`, строчный код в `err.code`; ошибки базы —
+  SQLSTATE `LT001`–`LT020` (`error_catalog()`).
+
+### Отличия от предложения «Свод» (§3 плана)
+PostgreSQL 18 вместо 15; одна приватная таблица `secret` вместо `credential` и `session`; журнал без партиций с
+политикой хранения; v5 — класс и значения ключа как есть, без канонизации и неявного ключа связи; только ключ
+вместо правил `unique`; `create` и `upsert` — разные глаголы; `rekey` для ключевых полей; приращение `inc`;
+`{ rev }` с кодом `conflict` и правилом одной цели; сломанная транзакция и `commit_unknown`; `forUpdate()`;
+загрузчик через `COPY` от роли владельца; индексы под RLS и срезы `asOf` через функции владельца `find_ids()`;
+план прав вместо таблицы-снимка; журнал защищён правами, а не триггерами; каскад после оператора; хэш —
+генерируемая колонка; проверка данных компиляцией JSON Schema в jsonpath; `NOTIFY` с именем класса; кэш плана и
+результатов; свободный объект `meta`; имперсонация через `letopis.account`; продление сессии отдельным вызовом;
+выпуск — letopis 1.0.0, а не новый пакет.
+
+### Added
+- Ядро в базе (этап 1): триггеры проверок, ссылок, ключей, умолчаний и журнала; `merge`, `inc`, каскад
+  `cascade`/`unset`/`restrict`, `reclass()`, `verify()` с якорем; роли `letopis_owner` и `letopis_app`; установка
+  без суперпользователя.
+- Модели и реестр (этап 2): `letopis/model`, нормализатор JSON Schema, v5 в TypeScript (`uuidv5`, `idOf`),
+  валидатор на TypeScript с теми же нарушениями, что в базе, `connect()` под сессией, `letopis sync` и `types`.
+- Чтение (этап 3): шаги-роли, полиморфные и множественные концы, 18 операторов, keyset, агрегаты, `deep`,
+  `asOf`, `withDeleted`; функции владельца `find_ids()`, `find_hop()`, `find_deep()` — индексы под RLS.
+- Запись (этап 4): `upsert`, `inc(n, { start })`, `update(patch, { rev })`, `forUpdate()`, слоты `add`/`remove`
+  множественных концов, батч со склейкой вставок, загрузчик `db.load()` и `letopis load`.
+- Доступ (этап 5): правила `Resource` и `rule` в базе, членство `member`, имперсонация, креды и сессии в
+  `secret`, подписанный пропуск прав, `db.acl.check()` и `checkData()`.
+- Время и эксплуатация (этап 6): `versions({ follow })`, `restore()`, `purge({ confirm })`, `trimHistory`,
+  `rekey`, `rekeyClass`, политика хранения, `maintain()`, `reset()`, подписка по курсору, кэш результатов, `up()`
+  без Docker и PGlite для разработки, `describe()` и `describeText()`.
+- Импорт из 0.21 (этап 7): `letopis import` с проверками до первой записи и отчётом; бенч против 0.21.
+- Руководство по переходу `MIGRATION.md` (входит в пакет) и шпаргалка агента 1.0.
+
+### Changed
+- Доводка контрольной точки Б (ревизия движка 5): индекс журнала `log_ends` ускорил срез `asOf` по переходу в
+  16 раз; чтение `letopis.changed` и `COMMIT` — одним конвейером.
+- Второе ревью безопасности (этап 5): креды привилегированных аккаунтов, недавний вход, лимиты OTP и TOTP,
+  потолок веса правил арендатора.
+
+### Added — после этапа 8 (решение владельца на точке В)
+- `up({ tenant })` и `createTenant(sql, schema, { name, grantAll, user })`: первый арендатор (аккаунт в System, правило «аутентифицированным можно всё») и его пользователь (членство с ролью `owner`, пароль, сессия в арендаторе) без своего сида; повтор ничего не дублирует (id — v5 от имени и логина).
+- `user.roles` в `up({ tenant })` и `createTenant`: роли членства пользователя, по умолчанию `['owner']`; непустой список имён (не масок), иначе `invalid_data`. Роли уже существующего членства повтор не меняет.
+- `verifyPassword({ …, totp })` и `lookup({ …, totp })`: вход со вторым фактором. После верного пароля или найденной учётной записи база проверяет код той же функцией, что `verifyTotp` (`auth_verify_totp`: право `auth.totp`, окно — шаг в каждую сторону, повтор шага отклоняется, счётчик неудач и блокировка общие), и выдаёт сессию со способами `[вид, 'TOTP']` — по ней пользователь с TOTP меняет свои креды сам. Неверный или повторный код и код у аккаунта без TOTP — `null`; удачный код включает ещё не подтверждённый фактор. Без `totp` — как раньше.
+
+### Documentation — после этапа 8 (решение владельца)
+- `README.md` пакета переписан как руководство по задачам: оглавление, сквозная нумерация разделов, один пример (магазин) от установки до эксплуатации, рецепт кошелька, справочник API, ошибки с SQLSTATE, ограничения.
+- Английские версии: `README.en.md`, `AGENT-CHEATSHEET.en.md` и корневой `README.en.md`.
+- В пакет входят шпаргалка агента `AGENT-CHEATSHEET.md` (перенесена из корня репозитория в `lib/`) и `llms.txt` — указатель для языковых моделей.
+- Тест `docs`: помеченные примеры README, шпаргалки и корневого README (обе версии) исполняются против PostgreSQL 18, а результаты, обещанные в комментариях примеров, сверяются.
+- `check-docs` ищет разделы README по заголовку, проверяет якоря оглавления, отсутствие управляющих символов и то, что английские версии повторяют структуру русских; `check-package` требует в архиве шпаргалку и `llms.txt`.
+
+### Fixed — после этапа 8 (код)
+- Подмена актора в `db.batch()`: очередь была общей для всех фасадов подключения, и `run()` одного фасада исполнял от своего имени планы, поставленные другим (`db.as()`, `db.begin()`). Теперь очередь своя у каждого фасада, и план исполняется от имени поставившего.
+- Курсор `after()` проверяется по типу поля `sort` до запроса: значение не того типа, курсор без `v` или `id` не uuid — `invalid_query`. Раньше курсор без `v` вешал соединение, а логический курсор по полю без описания давал ошибку сервера.
+- Ошибка загрузчика называет точное число нарушений («и ещё N»; «не меньше N» с причинами, если проверены не все строки), а в `detail` к первым 100 нарушениям в `rows` добавлены `total`, `truncated`, `limit` и `complete`.
+- Маска шаблона `Resource` не строкой (`categories`, `roles`, `endpoint`, `class`) совпадала со всеми, как в 0.21: группа `{ roles: ['staff'] }` с разрешающим правилом давала право любому аккаунту, маска `class` не строкой — на все классы. Теперь описание класса `Resource` требует строки, и маску не строкой отклоняет `invalid_data` — при записи библиотекой, сырым SQL и загрузчиком, в том числе при импорте. Строка, записанная в обход проверки, разрешений не даёт, а запрет по ней действует на всех: `acl_set_ok` и `acl_class_ok` на не строку отвечают null, `acl_rules` и `acl_plan_for` отбрасывают по ней разрешение. Новое описание попадает в свежую установку и после `reset({ all })`; в существующей схеме исправленное сопоставление действует после повторного `up()`.
+- Ключи сервиса: по сессии своего ключа сервис не мог ни выпустить себе новый ключ, ни отозвать старый (только системный администратор), а отзыв любого креда гасил все сессии аккаунта — ротация без простоя не получалась. Теперь свои `APIKEY` и `KEYSECRET` сервис выпускает и отзывает сам по сессии своего ключа (`auth_service_self`); сессия по ключу помнит его id (`meta.cred`), и отзыв ключа гасит только его сессии и старые сессии того же вида без отметки (`auth_kill_cred`), `keepCurrent` — как у прочих кредов. Последний действующий ключ сервиса не отзывается никем — `acl_denied` «последний действующий ключ сервиса не отзывается: сначала выпустите новый»; отключить сервис — `enabled: false`.
+- TOTP: пользователю с включённым TOTP свои креды было не сменить — база требует сессию с пройденным TOTP, а библиотека такую не выдавала. Теперь её выдают `verifyPassword` и `lookup` с `totp` (см. «Added — после этапа 8»).
+- `maintain()` за пулом в режиме транзакций (PgBouncer) молча вставал: сеансовая advisory-блокировка оставалась на серверном соединении, которое пул отдаёт другим клиентам, — `skipped` у всех. Теперь каждая пачка в своей транзакции первым делом берёт транзакционную блокировку (`pg_try_advisory_xact_lock`), её снимает фиксация пачки; блокировка занята до первой пачки — `skipped`, между пачками — остановка с `more: true`.
+- `after()` по полю данных терял строки с `null` или без поля: сравнение с `null` не проходило, а после строки с `null` следующая страница была пустой. Теперь `null` — после всех значений при возрастании и перед ними при убывании, как в `order by`; курсор `null` работает.
+- `letopis import`: ошибка загрузчика в данных арендатора теряла `total`, `truncated`, `limit` и `complete` отчёта загрузчика — теперь они доходят вместе со строками 0.21 в `rows` и `notes`.
+- `createTenant` и `up({ tenant })` после удаления арендатора, аккаунта пользователя или членства падали с `23505` (`log_id_rev`): `sys_create` пишет версию 1, а её занимает история. Теперь — `invalid_data` с объяснением и советом вернуть строку `restore()`, транзакция откатывается целиком; повтор удалённое не воскрешает.
+
+### Fixed — документация
+- В `README.md` стоял байт NUL: grep и поисковые инструменты считали файл двоичным и пропускали его.
+- Примеры шпаргалки, которые в прежнем виде падали: строгий режим `{ rev }` с устаревшим номером версии, создание уже существующего членства (теперь — правка ролей), подписка без условия выхода и неопределённые переменные.
+- Утверждения прежних README и шпаргалки, которые расходились с кодом (ревизия против кода и тестов): имперсонация не проверяет видимость пользователя по правилам доступа; `deep()` по умолчанию — 32 уровня; `refresh()` возвращает новое время истечения, а не токен; `verifyPassword` по умолчанию пускает только по подтверждённому креду; подписка отдаёт события в порядке номеров транзакций, а не фиксации; подключение к PGlite требует `allowBypassRls`; `update`, не нашедший целей, отвечает пустым списком, а не `target_not_found`; вес правила арендатора больше 999 урезается, а не отклоняется.
+- Маска группы (`Resource` категории `ACCOUNT`) задаётся только строкой; маску не строкой теперь отклоняет база (см. «Fixed — после этапа 8 (код)»).
+
+### Security — итоговое ревью безопасности (этап 8)
+- Блокировка семейства классов (`family_lock`) — по арендатору корневого класса: ужесточение класса или `rekeyClass` в одном арендаторе больше не останавливает запись в одноимённый класс других арендаторов.
+- `account_purge` проверяет право до поиска аккаунта: без права ответ всегда `acl_denied` — существование аккаунта не раскрывается.
+- `restore` и `purge` блокируют запись журнала только своего арендатора: чужой id нельзя ни заблокировать, ни заметить по ожиданию.
+- Маска `Resource` не строкой больше не открывает права всем: такую строку база не записывает (`invalid_data`), а записанная в обход проверки разрешений не даёт (см. «Fixed — после этапа 8 (код)»).
+- Тест `security-final`.
+
+## [1.0.0-alpha.0] — 2026-10-07
+
+Начало переписывания letopis 1.0 по плану `reports/PLAN-LETOPIS-1.0.md` (редакция 7).
+Версия не публиковалась; итоговая запись с разделом BREAKING — `[1.0.0]` выше.
+
+### Changed — этап 0 (подготовка)
+- Код 0.21 удалён из `lib/`: `src`, `sql`, `test`, `bench`, `docker`, `gen-types.mjs`,
+  `schema-sync.mjs`, а также `db/apply.mjs` и `db/policies.mjs`. Он доступен по тегу `v0.21.0`.
+- Копии `deepMerge`, `decide`, `matchCategories`, `matchMask` и наследования из `buildDef`
+  лежат в `lib/test/oracle/` — эталоны дифференциальных тестов; в пакет не входят.
+- Пакет: Node 22 и новее, единственная рантайм-зависимость `postgres`, Zod 4 — необязательная
+  peer-зависимость, подпуть `letopis/model`; `fastest-validator`, Redis и Docker уходят.
+- CI проверяет каждый пуш в `dev` на `postgres:18`; проверка пакета `scripts/check-package.mjs`
+  общая для CI и `release.yml`; версии с дефисом публикуются под dist-tag `next`.
+- `check-docs` и генератор контракта API переведены на новую раскладку.
+
+### Added — этап 1 (ядро в базе)
+- Три таблицы `entity`, `log`, `secret`; хэш версии — генерируемая колонка; права приложения только
+  на пользовательские колонки; RLS по арендатору; роли `letopis_owner` и `letopis_app`.
+- Установщик `install()` (`lib/src/up.ts`): членство `with inherit false, set true`, работает от роли
+  с `CREATEROLE` без суперпользователя; сиды по опции `seeds`.
+- Проверка данных: JSON Schema компилируется в jsonpath (колонка `validator` строки `Class`).
+- Конвейер записи в триггерах: id v5 по ключу, умолчания, концы с `for key share`, воскрешение,
+  монотонное время, журнал; `merge`, `inc` со `start`; удаление триггером после оператора
+  (`cascade`, `unset`, `restrict` по итогу); `reclass()`; `verify()` с якорем.
+- Классы — строки `Class`: метасхема, `resolved` с наследованием, пересчёт потомков, ужесточение
+  под исключительной блокировкой семейства, метаданные `meta`, политика хранения истории.
+- Коды ошибок `LT001`–`LT017` (`error_catalog()`).
+- Сигналы: сырой SQL шлёт `NOTIFY` из триггера; транзакции библиотеки (`letopis.notify = 'deferred'`)
+  копят классы в `letopis.changed` — решение 9 контрольной точки А.
+
+### Added — этап 2 (модели, реестр, контекст, валидатор)
+- `letopis/model`: `hub`, `link`, `one`, `many`, `Infer`, `InferLinks`, `ClassMeta`; нормализатор
+  JSON Schema (`$ref`/`$defs`, рекурсия — ошибка, ключи `.meta()` → `x-meta`, шаблоны в явные
+  классы символов, шаблон Zod у `format` сохраняется).
+- v5 в TypeScript: `uuidv5`, `v5Name`, `v5Id`, `idOf()` — общий файл векторов с базой.
+- Валидатор на TypeScript `compileValidator`, `applyDefaults` — те же нарушения, что в базе.
+- `connect()`: отказ ролям в обход RLS без `allowBypassRls`; транзакция на операцию с токеном
+  сессии и повторами; нотификатор отложенного сигнала (интервал по умолчанию 100 мс);
+  реестр классов с обновлением по сигналу; `db.sql`, `db.transaction`, `db.idOf`.
+- Ошибки: `LetopisError`, `ValidationError` с `issues` одного формата, `fromDbError`.
+- Демо-домен booking на Zod (18 классов 0.21 без корней `Entity` и `link`), `seed.booking.sql`
+  генерируется из моделей (`npm run seed:booking`).
+- CLI `letopis sync` (сухой прогон, применение, потерянные `refine`) и `letopis types`.
+
+### Added — этап 3 (цепочки: чтение)
+- Цепочки чтения `db.Класс(фильтр).Связь().Класс()`: шаг — имя класса, алиас или роль конца
+  (`db.Folder(f).Parent()`); переходы концами всех классов обоих семейств (шаг по базовому
+  классу, полиморфные и множественные концы); повтор связи — возврат к её узлу; `entity()`.
+- Фильтры: id, список id, строка ответа, `or(…)`, объект любой глубины с 18 операторами 0.21 и
+  приведением по типу листа из JSON Schema, роли концов (`{ Customer: id }`, `{ Customer: null }`).
+- Модификаторы `limit`, `offset`, `sort`, `after` и `cursorOf`, `asOf` (по журналу, в том числе с
+  `deep`), `withDeleted`, `deep(max)` с `$depth` (фильтр, теги и владелец — на каждом уровне),
+  `exact`, `alias`, `tags`, `owner`; терминалы `rows`, `first`, `ids`, `count`, `paths`,
+  `versions`, `sum`, `avg`, `min`, `max`, `countBy`; строки ответа несут `rev`.
+- Функции владельца `find_ids()`, `find_hop()`, `find_deep()` (`lib/sql/70-read.sql`): поиск id по
+  индексам GIN без RLS с тем же условием видимости, что у политик (`row_visible()`); строки
+  читаются по первичному ключу под RLS. Три шага с фильтрами на 2,2 млн строк
+  (`bench/chain-read.mjs`): узкий запрос — 23,6 мс против 18,8 мс у владельца без RLS, широкий
+  (14 285 строк) — 3,09 с против 2,93 с; на точке А прототип давал 21,7 с (решение 5).
+- Типы по моделям: `connect({ models })` → `TypedDb` (шаги по именам и алиасам, `RowOf`, `FilterOf`).
+- `onQuery` и `slowMs` в `connect()`; охранники снесённого API (`run`, `account`, `reloadSchema`,
+  фасады таблиц, `watch(cb)`, `db.auth.sessions`, `db.acl.reload`, `compact`, `uuidv7`,
+  `LETOPIS_NS`, опции `partition`, `enforceAccount`, `enforceAcl`, `container`, `image`,
+  `dataDir`, `redisPort`, `version`) — ошибка `removed` с версией и заменой.
+- Список методов цепочки `RESERVED_CLASS_NAMES` — единственный источник: установщик подставляет его
+  в `reserved_names()`, `check-docs` сверяет с Proxy и README §3.
+
+### Changed — этап 3
+- `count()` и агрегаты считают сущности последнего шага, а не пути; число путей — `count({ paths: true })`;
+  `run()` → `paths()`.
+- Строки `Class` других арендаторов больше не видны (политика: только системные и свои).
+- Надгробие строки, перенесённой `reclass()`, записывается видом `delete` (`moved` — новый id):
+  по нему срез `asOf` отличает удалённый id.
+- Транзакции библиотеки выставляют `TimeZone = UTC`: время в строках ответа не зависит от сервера;
+  пул, который создаёт сам `connect()`, разбирает `timestamptz` строкой (микросекунды), как в 0.21.
+- `db.schema` — имя схемы установки (в 0.21 — фасад таблицы `Schema`).
+
+### Added — этап 4 (цепочки: запись и загрузчик)
+- Глаголы записи — звенья плана одной транзакцией: `create`, `update(patch, { rev })`, `upsert` (`$upsert`),
+  `delete()` (превью `$action`) и `delete({ confirm })`, `anonymize`, `reclass`; продолжение от результата, fan-out,
+  self-update; слоты `.Роль.set/unset/add/remove` (функция базы `links_patch`).
+- Приращение `inc(n, { start })` — маркер `Symbol.for('letopis.inc')`; строгий режим `{ rev }`; правило числа
+  затронутых строк (`target_not_found`, `conflict`, `acl_denied`); коды `exists`, `no_key`, `rev_ambiguous`.
+- `db.begin()` — явная транзакция: сломанная транзакция, проверка ответа на `COMMIT` (`tx_rolled_back`), `lock()`,
+  `commit_unknown`; `forUpdate()` (`tx_required`, `lock_unsupported`); `db.batch()` со склейкой вставок и upsert;
+  `db.as(аккаунт, { owner })`.
+- Загрузчик `db.load()` и `letopis load`: проверки в коде, `COPY` от владельца, запрос по целям вне загрузки,
+  `duplicates`, `existing` (воскрешение удалённых), `commitEvery`, режим истории, `verify`; коды `admin_required`,
+  `class_not_loadable`, в отчёте — `duplicate`, `exists`, `deleted`.
+- Метасхема `Class`: `fields.anyOf` и `fields.oneOf` — условия по нескольким полям (потомок заменяет целиком).
+- Превью удаления `delete_preview()` — то же правило `ref_action()`, что у триггера удаления.
+- Тесты `chain-write`, `tx`, `load`, `balance` (обрыв связи — TCP-прокси `test/_proxy.ts`).
+
+### Changed — этап 4
+- Решение 2 точки А: строковые триггеры только разбирают концы (`links_shape`); цели проверяет и блокирует
+  `targets_bad()` в триггере после оператора — один раз на цель; журнал пишут триггеры после оператора
+  `entity_ai`/`entity_au` одной вставкой; надгробия каскада — одной вставкой на уровень; `class_row` — по индексу
+  `entity_class_name` без v5. Вставка пачкой: 776 → 328 мкс на строку (цель ≤ 400), каскад: 230 → 98 мкс на
+  строку; загрузчик не замедлился. Ревизия движка 2.
+- `runTx` — на зарезервированном соединении со своими `begin`/`commit`: после гибели серверного процесса
+  postgres.js 3.4 ронял процесс необработанным `TypeError` (rollback и возврат в пул закрытого соединения).
+- Поток `COPY` загрузчика перехватывает ошибку сервера, которую postgres.js 3.4 терял после конца потока.
+
+### Added — этап 5 (доступ)
+- Права ACL в базе: правила-строки `Resource` (группа `ACCOUNT` по категориям аккаунта или ролям членства, эндпоинт `API`, объект строк `READ`/`WRITE`/`DELETE` с маской класса и условием на колонки) и `rule` (группа → объект, `allow`/`deny`, вес) — семантика `decide` 0.21; план прав `acl_plan()` один раз на запрос, политики RLS на `entity` (select, insert, update, delete) и `log`, та же видимость в `find_*()`, превью удаления, проверке целей.
+- Правила арендатора действуют на его строки, правила System — везде; роли членства — только в правилах своего арендатора; права `auth.*` и `letopis.*` — только по правилам System.
+- Подписанный пропуск прав `letopis.acl` (`acl_token()`): библиотека кэширует план прав актора и передаёт его в каждой транзакции; счётчик изменений прав `acl_bump()` делает устаревший пропуск недействительным.
+- Членство `member` (концы `User`, `Tenant`, ключ `[User, Tenant]`, роли), `auth.switch`, `letopis.tenant`, `db.as(аккаунт, { tenant, owner })`; выход из членства переводит владение строками арендатору.
+- Имперсонация в `ctx()`: `letopis.account` — только при праве `auth.impersonate`; в журнале `author` — пользователь, `agent` — сервис.
+- Креды и сессии в `secret` (`80-auth.sql`, `db.auth`): пароль (scrypt в Node, хэш — только сервису с правом), ключ API, ключ + секрет, OTP, TOTP (RFC 6238 на pgcrypto), внешние identity; недавний вход для своих кредов; гашение сессий со сигналом `session:<начало хэша>`; `sessionFor`, `refresh`, `revoke`, `revokeAll`, `tenants`; `totpCode`, `hashPassword`, `verifyHash`.
+- `db.acl.check(endpoint)`, `db.acl.checkData(class, op)`.
+- Системный сид: классы `member`, `Resource`, `rule`, общие группы, права сервиса и администратора; `sys_grant_all()` для обвязки и первичной настройки арендатора.
+- Загрузчик: `load({ as })` — права пользователя, условия ACL, видимость целей, владелец по `ownerDefault`.
+- Тесты: `acl`, `acl-parity` (1000 наборов против 0.21), `auth`, `impersonation`, `member`, `system-classes`, `access-rest`; бенч `acl-cost`.
+
+### Changed — этап 5
+- Права включены всегда и по умолчанию запрещают; тестовая обвязка выдаёт тестовым арендаторам «аутентифицированным можно всё».
+- Аккаунты лежат только в арендаторе System; их категории правит системный администратор (член System с ролью `admin`).
+- `db.as()` асинхронный: `await db.as(аккаунт, { tenant, owner })`.
+- Явный владелец строки — существующий аккаунт, разрешение — по условию ACL (нарушение — `acl_denied`); несуществующий — `target_not_found`.
+- Каскад удаления требует права `DELETE` на каждую удаляемую строку, снятие конца — `WRITE`; цель ссылки должна быть видна актору.
+- `issue_session(аккаунт, ttl, способы)`; ревизия движка 3 (индекс `entity_owner`).
+
+### Security — второе ревью безопасности (этап 5)
+- Креды System, сервисов и системных администраторов меняет только сам аккаунт или системный администратор (`auth_guard`): сервис больше не привяжет себе вход под ними.
+- Свой кред аккаунт не подтверждает; недавний вход — только интерактивный, при включённом TOTP — с пройденным TOTP.
+- Вход по одноразовому коду и проверка TOTP — только сервису с правом (счётчики попыток транзакционные); лимит попыток OTP задаёт выпуск (1–10); окно TOTP — не шире шага, пять неудач — блокировка на 5 минут; продление сессии — не дольше выданного срока.
+- Вес правила арендатора — не больше 999: административные запреты System (вес от 1000) он не перевесит.
+- Строки прав не получаются сменой класса; служебная строка ключа подписи исключена из функций кредов; хэш выдаётся только для видов «логин/пароль».
+
+### Changed — доводка контрольной точки Б
+- Ревизия движка 5: индекс журнала `log_ends` (GIN по целям ссылок); срез `asOf` и withDeleted по переходу, `deep` на дату и условие на концы ищут в журнале от версий, ссылавшихся на источник (`log_refs_at`), а не перебором всех версий класса — на полигоне salon срез записей мастера 3,37 с → 0,22 с. Обновление установки — `up({ upgrade: true })` (строит индекс).
+- Транзакция записи: чтение `letopis.changed` и `COMMIT` — одним конвейером (минус круг до базы на запись).
+
+### Added — этап 7 (импорт из 0.21 и бенч)
+- `letopis import --from <строка 0.21> --from-schema v1.x` (`src/import.ts`): Schema → строки `Class` в System (fastest-validator → JSON Schema, концы — роли по классу цели, союз потомков — полиморфный конец, корни `Entity` и `link` опущены, метаданные → `meta`), Entity → загрузчик в режиме истории (надгробия, воскрешение, теги, владелец), Account → строки `Account`, Credential → `secret` как есть, Resource и Rule → System; id — v5 от ключа или от старого id; `--tenant`, `--keyless`, `--rename`, `--update`, `--commit-every`; проверки до первой записи, отчёт со счётчиками и `verify()`.
+- Загрузчик: `$tags` и `$owner` строки (владелец сверяется запросом в конце); `existing: 'skip'` в режиме истории.
+- Фикстура настоящей 0.21 (`test/fixtures/v021.sql`, генератор `gen-v021.mjs`), тест `import`; `npm run test:import-salon` — полный импорт полигона salon; полигоны 1.0 загрузчиком (`bench/polygons.mjs`) и бенч против 0.21 (`bench/compare.bench.mjs`).
+
+### Added — этап 6 (время, хранение, события, кэш, эксплуатация)
+- История: `versions({ follow: true })` через смену id (`reclass`, `rekey`, колонка `moved`, индекс `log_moved`); глаголы `restore()` (последний снимок удалённого, перепроверка по текущему описанию, id прежний) и `purge({ confirm })` (только удалённые, запись `purge` под номером 1); `db.trimHistory(цель, момент)` — обрезка с записью `trim` (время версии 1, стык по хэшу).
+- Смена ключа: глагол `rekey(patch)` и `db.rekeyClass(класс, ключ)` — новые id, перевод ссылок, рекурсия по связям с концом в ключе.
+- Политика хранения истории (§2.11): `history: { all, daily, weekly, monthly, yearly, tz }` у класса и `up({ history })`; прореживание в `maintain()` пачками; законные пропуски в `verify()`.
+- `db.verify({ data })` и `letopis verify`: законные разрывы (`purge`, `trim`, `reset`, прореживание), проверка данных, концов, арендаторов, владельцев и id всех строк; якорь.
+- `db.maintain()` (сессии, коды, прореживание, очередь сигналов) под advisory-блокировкой, `connect({ maintain })`, `letopis maintain`.
+- `db.reset({ level: 'sessions' | 'tenant' | 'all', confirm, tenant })` с флагом `allowReset`, правом `letopis.reset`, подтверждением; `all` — сид и новый ключ сервиса.
+- `db.auth.purgeAccount()` — удаление аккаунта с предохранителями 0.21 и переходом владения.
+- Подписка `db.watch({ from, classes })` по курсору (tx, seq) ниже горизонта, `cursor_expired`, `lag()`.
+- Кэш результатов `.cache({ ttl })` и пометка класса `cache`; `db.cache.clear()`, `stats()`; `connect({ cache, listen })`.
+- `up()` — оркестратор без Docker: ожидание и создание базы, PostgreSQL 18+ и UTF8, `fresh`, `upgrade` с миграциями `sql/migrate/`, свои сиды и ключ сервиса, `ANALYZE` без статистики; `up({ pglite })` — PGlite для разработки (решение 6 точки А; необязательные peer-зависимости `@electric-sql/pglite`, `@electric-sql/pglite-socket`); `db/apply.mjs`.
+- `db.describe()`, `describeText()`, `letopis describe`; коды ошибок `not_deleted`, `reset_disabled`, `confirm_mismatch`; каталог ошибок в README §12.
+- Тесты: `time`, `rekey`, `reset`, `verify`, `retention`, `watch`, `cache`, `maintain`, `up`, `telemetry`, `scenario-salon`; строки этапа 6 в `hash`, `load`, `balance`.
+
+### Changed — этап 6
+- Ревизия движка 4. `verify(p_data)` перенесён в `90-time.sql`; системный сид — функция `seed_system()`.
+- Воскрешение, `restore`, `purge` и обрезка берут последнюю запись журнала id `for update`.
+- Загрузчик в режиме истории пишет волну одной вставкой `insert … returning hash` (4000 волн — 6 с вместо 400 с).
+- `acl_bump()` сохраняет остальные ключи служебной строки ключа (курсор прореживания).
+- `compact()` — охранник с заменой `db.trimHistory`; `watch(cb)` — охранник с заменой `watch({ from })`.
+
+### Removed
+- Режим доверия загрузчика (`trust: true`, `--trust`) — решение владельца на контрольной точке А; охранник `removed`.
+
+## [0.21.0] — 2026-08-23
+
+### Added — no-history классы: `meta.history: false` (DDL_REVISION 2)
+
+Класс, помеченный в `Schema.meta` флагом `history: false`, хранит **одну актуальную строку
+на id**: новый AFTER INSERT триггер `entity_collapse` после каждой вставки физически удаляет
+более старые версии этого id. Дефолт (`history` отсутствует или `true`) — прежнее поведение,
+все версии копятся; фича строго opt-in, существующие схемы и сервисы не затронуты.
+
+Зачем: у мутабельных статус-сущностей (очереди, outbox — статус живёт в `data`) история
+версий делает jsonb-фильтры неселективными: GIN по `data` матчит каждую версию, что
+когда-либо была в искомом статусе, и сканы растут O(вся история). Под `history:false`
+фильтр матчит только актуальные строки — скан остаётся O(активных) при любом росте данных.
+
+Механика:
+- `entity_collapse` — AFTER INSERT (как `entity_notify`; collapse по алфавиту раньше —
+  один NOTIFY на выжившую строку). In-place UPDATE не годится: Entity — гипертаблица по
+  `updated` (перенос между чанками), а `entity_notify` слушает только INSERT.
+- DELETE старых версий идёт под `letopis.purge='on'` (save+restore флага):
+  `entity_delete` пропущен — без tombstone и каскада. Advisory-lock тем же ключом,
+  что `entity_delete`/`purge`, сериализует конкурентные вставки одного id.
+- `.delete()` под no-history оставляет один tombstone (его `updated` строго больше),
+  `purge()` работает как прежде.
+- Новая серверная функция `compact(partition, class) → bigint` — разовая чистка УЖЕ
+  накопленной истории при переводе класса на `history:false` (оставить последнюю версию
+  каждого id, вернуть число удалённых). Идемпотентна. После вызова — `ANALYZE "Entity"`.
+- `ClassDef.history` в реестре; `.versions()`/`.asOf()` по no-history классу предупреждают
+  в console.warn (один раз на класс+метод за процесс) — результат не отражает историю.
+
+Накат на существующие схемы: `up({ upgrade: true })` или `node db/apply.mjs --upgrade`
+(файл идемпотентен, данные целы); до наката `connect()` предупредит о ревизии (1 → 2).
+
+- `test/no-history.test.ts` — 7 сцен: реестр, схлопывание, соседний history-класс,
+  NOTIFY, tombstone, `compact()`, warning; суммарно 205 тестов.
+
 ## [0.20.3] — 2026-07-31
 
 ### Fixed — релиз доезжает до npm

package/MIGRATION.md

@@ -0,0 +1,190 @@
+# Переход с letopis 0.21 на 1.0
+
+letopis 1.0 — новая реализация хранилища: PostgreSQL 18, три таблицы (`entity`, `log`, `secret`), проверки и
+права в самой базе. Схема 0.21 не обновляется на месте: 1.0 ставится в новую схему, данные переносит команда
+`letopis import`, а код приложения переводится по таблице замен ниже. Полный список несовместимостей — раздел
+BREAKING записи `[1.0.0]` в `CHANGELOG.md`; руководство по 1.0 — `README.md`, краткая шпаргалка — `AGENT-CHEATSHEET.md`
+(оба лежат в пакете рядом с этим файлом).
+
+## 1. Порядок перехода
+
+1. Поднимите PostgreSQL 18 (TimescaleDB, Redis и Docker больше не нужны) и Node 22+.
+2. Установите схему 1.0 без демо-сида: `await up({ dsn: ADMIN, schema: 'salon' })` — схема `v2.salon`. Сохраните
+   `serviceKey` из результата: ключ сервиса выдаётся один раз. В 0.21 `up()` без `seeds` заливал демо-домен; в
+   1.0 сиды ставятся только явно (`seeds: ['booking']` или путь к своему `.sql`).
+3. Создайте прикладную LOGIN-роль, которая состоит только в `letopis_app`
+   (`create role app login password '…'; grant letopis_app to app;`). Приложение подключается ею: роль, которая
+   обходит RLS, `connect()` отклоняет (`bypass_rls`), если не передать `allowBypassRls: true`.
+4. Перенесите данные: `letopis import` (раздел 2). Повтор безопасен — он дописывает недостающее.
+5. Переведите код по таблицам разделов 3–5 и проверьте установку: `letopis verify --data`.
+
+## 2. Импорт данных: `letopis import`
+
+```sh
+npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgres://…/new --schema v2.salon \
+  [--tenant <имя>] [--keyless <Класс>]… [--rename <Старое>=<Новое>]… [--update] [--commit-every <N>] [--partition <имя>]
+```
+
+| Опция | Что делает |
+|---|---|
+| `--from`, `--from-schema` | база и схема 0.21 (`v1.<имя>`): PostgreSQL 17 с TimescaleDB или дамп обычных таблиц |
+| `--dsn`, `--schema` | база и схема 1.0 (`v2.<имя>`), поставленная заранее `up()`; оба подключения — администраторские |
+| `--tenant <имя>` | арендатор, в которого переходят данные System 0.21 (в 1.0 у System своих данных нет) |
+| `--keyless <Класс>` | класс, чьи данные нарушают ключ: его объекты получают id от старого id, а не от ключа |
+| `--rename <Старое>=<Новое>` | новое имя класса, совпавшего с методом 1.0 (по умолчанию — имя с `_` на конце) |
+| `--update` | при повторе — новые версии объектов, изменившихся в 0.21 после прошлого импорта |
+| `--commit-every <N>` | размер порции загрузчика |
+| `--partition <имя>` | партиция 0.21 (по умолчанию `entity`) |
+
+Что переносится:
+- **Классы** (`Schema`) — строки `Class` арендатора System. Правила fastest-validator переводятся в JSON Schema
+  (`optional` пропускает `null`, `$$strict` — `additionalProperties: false`, `record` — `propertyNames`); концы
+  становятся ролями с именем класса цели, союз всех потомков класса — полиморфным концом; корни `Entity` и `link`
+  опускаются; `description`, `appearance`, `order` — в `meta`.
+- **id**: у класса с ключом (правило v5 из 0.21) — v5 от ключа в арендаторе, у класса без ключа — v5 от старого
+  id. uuid внутри `data`, совпадающие со старыми id, импорт не переписывает и перечисляет в отчёте.
+- **Объекты** (`Entity`) — загрузчиком в режиме истории: все версии, надгробия, воскрешения, теги, владелец; агент
+  в журнале — `letopis import`. Каждый аккаунт 0.21 становится арендатором своих строк; владелец, не найденный
+  среди аккаунтов, заменяется арендатором. `onDelete` концов — `cascade`, как удаляла 0.21.
+- **Аккаунты** — строки `Account` (в System); **креды** — в `secret` как есть (хэши scrypt, ключи);
+  одноразовые коды не переносятся.
+- **Ресурсы и правила** ACL — в System, поэтому действуют во всех арендаторах; непереведённые правила — в отчёте.
+  Ресурс с маской не строкой импорт не пропустит (`invalid_data`, см. [раздел 4](#4-изменения-поведения)).
+
+Проверки до первой записи: импорт останавливается, если два объекта 0.21 дают один id 1.0 (данные нарушают ключ —
+укажите `--keyless <Класс>`), если ключ объекта менялся между версиями или ссылается на отсутствующий объект.
+Висячая ссылка живой строки — `target_not_found` с объектом 0.21.
+
+Отчёт — JSON в конце вывода (перед ним — строки хода `letopis.import: …`): объекты и версии по классам в 0.21 и в 1.0, аккаунты, креды, ресурсы, правила, классы без
+ключа, результат `verify()`. Код выхода 1, если `verify()` нашёл расхождения. Шаги импорта (классы, аккаунты,
+креды, права, данные каждого арендатора) — отдельные транзакции; источник читается в память целиком.
+
+## 3. Таблица замен API
+
+Снятые имена не исчезли молча: вызов бросает `LetopisError` с кодом `removed` и текстом
+`letopis: removed: <имя> снят в 1.0.0 — <замена>`.
+
+| 0.21 | 1.0 (текст замены в ошибке) |
+|---|---|
+| `.run()` | `paths()` |
+| `.execute()` | `paths()` |
+| `.account(id)` | арендатор сессии и `auth.switch()` |
+| `batch.execute()` | `batch.run()` |
+| `uuidv7()` | `uuidv5()` и `idOf()`: id объекта вычисляется из ключа |
+| `LETOPIS_NS` | пространство имён v5 — id арендатора: `idOf(класс, ключ, { tenant })` |
+| `db.watch(cb)`, `db.watch(класс, cb)` | `watch({ from })` — подписка по курсору |
+| `db.reloadSchema()` | реестр обновляется сам по сигналу; принудительно — `db.refresh()` |
+| `db.accounts`, `db.credentials`, `db.resources`, `db.rules` | системные классы `Account`, `Resource`, `rule`, `member` и `db.auth` (`accounts.purge` — `db.auth.purgeAccount`) |
+| `db.compact()` | `db.trimHistory(цель, момент)`, политика хранения `history` и `history: false` |
+| `db.acl.reload()` | права обновляются сами: база применяет действующие правила |
+| `db.auth.sessions(store)` | сессии хранятся в базе: `sessionFor`, `refresh`, `revoke`, `revokeAll` |
+| `connect({ partition })` | отдельные схемы установки (`v2.<имя>`) |
+| `connect({ enforceAccount })` | изоляция арендаторов включена всегда (RLS) |
+| `connect({ enforceAcl })` | права включены всегда |
+| `connect({ container })`, `({ image })`, `({ dataDir })` | Docker в `up()` не нужен |
+| `connect({ redisPort })` | Redis не нужен: сессии в базе |
+| `connect({ version })` | версия схемы — константа движка |
+
+Замены без охранника — имя осталось, но значит другое, или API устроено иначе:
+
+| 0.21 | 1.0 |
+|---|---|
+| `db.schema.define(def)`, CLI `schema-sync` | модели `hub`/`link` из `letopis/model` и `letopis sync <модуль> [--apply]` (или `syncModels(db, модели, { apply })`); класс — строка `Class` с JSON Schema |
+| `db.schema` — фасад таблицы `Schema` | `db.schema` — имя схемы установки |
+| CLI `gen-types` | `letopis types`; типы цепочек — `connect({ models })` |
+| `attributes` на fastest-validator, `id: { generate, from }` | поля на Zod / JSON Schema, ключ класса `key: [...]`; id только v5 |
+| `db.as(account, { owner })` — синхронный | `await db.as(account, { tenant, owner })` — имперсонацию проверяет база (право `auth.impersonate`) |
+| `connect({ dsn, schema })` + `db.as(accountId)` | `connect({ dsn, schema, token })` или `connect({ …, apiKey })` — сессия в базе |
+| `row.account`, `row.updated` | `row.tenant`, `row.at` (в `sort` и `cursorOf` имя `updated` понимается как `at`); новые `rev`, `author`, `op`, `agent`, `reason`, `moved` |
+| `.count()` — число путей | `.count()` — число сущностей; путей — `.count({ paths: true })` |
+| `up({ schema: 'x', version: 1 })` → `v1.x` | `up({ schema: 'x' })` → `v2.x`; Docker-опций нет, есть `pglite: true` |
+| `db.sql` — голый клиент | `` db.sql`…` `` — под сессией и RLS, одной транзакцией; `db.transaction(fn)` |
+| коды ошибок 0.21 | `err.code` — строчный код каталога (`exists`, `conflict`, `invalid_data` …), ошибки базы — SQLSTATE `LT001`–`LT020` |
+| `tr.lock(...keys)` | остался: advisory-блокировка до конца `db.begin()`; для денег — раздел 5 |
+
+## 4. Изменения поведения
+
+- **`create` — не PUT.** Занятый ключ — ошибка `exists` с `detail.id`; в 0.21 повторный `create` перезаписывал
+  объект. Замена целиком — `upsert(data)` (только класс с ключом, иначе `no_key`; в строке ответа `$upsert`:
+  `created`, `updated` или `unchanged`). Частичная правка — `update`.
+- **`update` не создаёт** (как и в 0.21), но теперь строже: если глагол затронул меньше строк, чем нашёл шаг,
+  весь план откатывается с `target_not_found`, `conflict` или `acl_denied`.
+- **`count()` считает сущности** последнего шага, агрегаты — тоже; число путей — `count({ paths: true })`.
+- **Пути — `paths()`** вместо `run()`: `[{ Шаг: Row, … }]`, ключ — имя шага или `.alias(имя)`.
+- **Арендатор сессии вместо `account()`.** Строки принадлежат арендатору сессии подключения; чужие не видны и
+  неотличимы от несуществующих. Работа в другом арендаторе — по членству (`member`): `db.auth.switch(tenant)` или
+  `await db.as(account, { tenant })`. System-fallback 0.21 нет.
+- **Права включены всегда** и по умолчанию запрещают — для библиотеки и сырого SQL (политики RLS). После импорта
+  правила 0.21 лежат в System; новому арендатору нужны свои правила (`Resource` и `rule` цепочками).
+- **Маска `Resource` — только строка** (`categories`, `roles`, `endpoint`, `class`; например, `roles: '{staff}'`). В 0.21
+  маска не строкой (например, массив `roles: ['staff']`) совпадала со всеми аккаунтами, и разрешающее правило с такой
+  группой давало право каждому. В 1.0 такую строку `Resource` база отклоняет с `invalid_data` — при записи
+  библиотекой, сырым SQL и загрузчиком, в том числе при импорте: перепишите маску строкой в источнике.
+- **Ключ неизменен.** Правка ключевого поля — `immutable_key`; новый ключ — `rekey(patch)` или
+  `db.rekeyClass(класс, ключ)`, оба дают новые id и переводят ссылки. Смена класса — `reclass(класс, данные)`.
+- **Явный id** у класса с ключом должен совпасть с вычисленным (`id_mismatch`), класс без ключа id не принимает
+  (`id_from_db`). Вычислить id заранее — `db.idOf(класс, ключ)`.
+- **Ошибка ломает `db.begin()`**: следующие вызовы и `commit()` бросают исходную ошибку (`commit()` откатывает),
+  `rollback()` проходит. В 0.21 `commit()` после ошибки молча проходил. Обрыв связи во время `COMMIT` —
+  `commit_unknown`, без повтора.
+- **Каскад удаления** — по правилам концов `onDelete` (`restrict` по умолчанию, `cascade`, `unset`); превью
+  `delete()` показывает `$action` каждой строки. Удаление, `reclass` и `rekey` — только в `read committed`.
+- **`history: false`** отключает ещё и `versions`, `asOf`, `restore` и события подписки.
+- **Подписка** `db.watch({ from, classes })` — асинхронный итератор с курсором `ev.cursor`: без потерь и повторов,
+  продолжение — `watch({ from: курсор })`; `onReconnect` не нужен.
+
+## 5. Баланс и счётчики
+
+В 0.21 баланс правили так: явная транзакция, `tr.lock(...)`, перечитать строку, записать новое значение. Advisory-
+блокировка не останавливает тех, кто её не берёт (другой код, сырой SQL), а перечитывание и запись — два запроса.
+
+```ts
+// 0.21
+const tr = await db.begin()
+await tr.lock('wallet', id)
+const w = await tr.Wallet(id).first()
+await tr.Wallet(id).update({ balance: w.data.balance - 300 }).rows()
+await tr.commit()
+```
+
+В 1.0 — один из трёх способов.
+
+**1. Приращение `inc`** — для пополнения, списания, счётчиков. База прибавляет величину внутри оператора: без
+чтения, без блокировок в приложении, без потерянных обновлений. Нижнюю границу держит описание класса
+(`minimum: 0` → уход в минус — `invalid_data`). Идемпотентность — ключом операции:
+```ts
+import { inc } from 'letopis'
+// Movement: связь с ключом [Wallet, opId]; повтор той же операции — exists, баланс не меняется
+await db.Wallet(id).Movement().create({ opId, kind: 'debit', amount: 300 }).Wallet().update({ balance: inc(-300) }).rows()
+await db.Wallet(id).update({ visits: inc(1, { start: 0 }) }).first()   // start — если поля ещё нет
+```
+
+**2. Строгий режим `{ rev }`** — когда новое значение вычисляется из прочитанного (корректировка до целевого
+значения). Если строку успели изменить, приходит `conflict` — перечитать и повторить:
+```ts
+for (;;) {
+  const w = await db.Wallet(id).first()
+  try {
+    await db.Wallet(id).update({ balance: target(w!.data) }, { rev: w!.rev }).rows()
+    break
+  } catch (e) {
+    if ((e as { code?: string }).code !== 'conflict') throw e
+  }
+}
+```
+`{ rev }` действует при одной цели шага (иначе `rev_ambiguous`) и не повторяется автоматически.
+
+**3. Чтение с блокировкой `forUpdate()`** — когда нужно прочитать несколько строк и записать итог без повторов:
+```ts
+const tr = await db.begin()
+try {
+  const w = await tr.Wallet(id).forUpdate().first()      // for no key update, строки — в порядке id
+  await tr.Wallet(id).update({ balance: w!.data.balance - 300 }).rows()
+  await tr.commit()
+} catch (e) {
+  await tr.rollback()
+  throw e
+}
+```
+`forUpdate()` — только внутри `db.begin()` (`tx_required`) и только с `rows`, `first`, `ids` (`lock_unsupported`).
+Транзакция — `read committed`; на `40P01` повторите весь блок `db.begin()`.