letopis 2.0.0 → 3.0.0

package/README.md

@@ -1,4 +1,8 @@
-# letopis 2.0
+# letopis 3.0
+
+> ИИ-агенту — сначала [AGENT-CHEATSHEET.md](AGENT-CHEATSHEET.md): памятка лежит в пакете рядом с этим файлом
+> (`node_modules/letopis/AGENT-CHEATSHEET.md`), в ней общие правила для любой задачи, рабочий цикл и грабли на одной
+> странице.
 
 **letopis** — библиотека для Node.js, хранилище версионированных сущностей на PostgreSQL 18. Каждое изменение
 сохраняется версией в журнале. Поэтому у любого объекта есть история, состояние на любую дату и подписка на
@@ -6,13 +10,14 @@
 RLS. Правила одинаково действуют и для библиотеки, и для сырого SQL. Данные читают и пишут цепочками:
 `db.Shop(shop).Product({ price: lt(1000) }).rows()`.
 
-[Шпаргалка для ИИ-агента](AGENT-CHEATSHEET.md) · [Изменения по версиям](CHANGELOG.md) · [llms.txt](llms.txt)
+[Памятка для ИИ-агента](AGENT-CHEATSHEET.md) · [Изменения по версиям](CHANGELOG.md) · [llms.txt](llms.txt) ·
+[Лицензия](#19-лицензия): некоммерческое использование бесплатно, коммерческое — по разрешению
 
 Что умеет letopis:
 
 - **Модели на Zod** хранятся в базе как классы: хабы (объекты) и связи (отношения со своими данными) — [раздел 4](#4-модель-данных).
-- **Запись цепочками**: `create`, `update` со слиянием, `upsert`, удаление с превью и каскадом, приращение `inc`
-  для денег и счётчиков — [разделы 5](#5-запись), [7](#7-удаление-и-восстановление) и [8](#8-транзакции-батчи-и-деньги).
+- **Запись цепочками**: `create`, `update` со слиянием, `upsert`, удаление только по показанному превью и с каскадом,
+  приращение `inc` для счётчиков — [разделы 5](#5-запись), [7](#7-удаление-и-восстановление) и [8](#8-транзакции-и-батчи).
 - **Чтение цепочками**: переходы по связям, фильтры, деревья, агрегаты, постраничный вывод — [раздел 6](#6-чтение).
 - **История**: версии с автором и причиной, срез на дату, восстановление удалённого — [раздел 11](#11-история-и-срезы-на-дату).
 - **Арендаторы, вход и права** — в самой базе: пароли, ключи API, одноразовые коды, TOTP, сессии, имперсонация,
@@ -21,6 +26,8 @@ RLS. Правила одинаково действуют и для библио
 - **Агенты и MCP**: сервер MCP даёт ИИ-агенту модель, чтение, историю и, если разрешено, запись — с правами одного
   пользователя — [раздел 13](#агенты-и-mcp).
 - **Массовая загрузка** миллионов строк — [раздел 9](#9-массовая-загрузка).
+- **Журнал событий** приложения: удаления, восстановления, ошибки, вход, запросы — с маскировкой секретов —
+  [«Логирование»](#логирование).
 
 Требования:
 
@@ -40,30 +47,40 @@ RLS. Правила одинаково действуют и для библио
 5. [Запись](#5-запись)
 6. [Чтение](#6-чтение)
 7. [Удаление и восстановление](#7-удаление-и-восстановление)
-8. [Транзакции, батчи и деньги](#8-транзакции-батчи-и-деньги)
+8. [Транзакции и батчи](#8-транзакции-и-батчи)
 9. [Массовая загрузка](#9-массовая-загрузка)
 10. [Пользователи, вход и права](#10-пользователи-вход-и-права)
 11. [История и срезы на дату](#11-история-и-срезы-на-дату)
 12. [Подписка на изменения и кэш](#12-подписка-на-изменения-и-кэш)
-13. [Эксплуатация](#13-эксплуатация)
+13. [Эксплуатация](#13-эксплуатация): обслуживание, MCP, [логирование](#логирование), командная строка
 14. [Справочник API](#14-справочник-api)
 15. [Ошибки](#15-ошибки)
 16. [Производительность](#16-производительность)
 17. [Ограничения](#17-ограничения)
 18. [Тесты](#18-тесты)
+19. [Лицензия](#19-лицензия)
 
 Разделы 3–13 построены на одном примере — магазине: установка, модель, запись, чтение и так далее. Блоки кода этих
-разделов идут по порядку и вместе образуют одну программу. Её, как и пример быстрого старта, тест `docs` исполняет
-против настоящей базы, поэтому примеры не расходятся с кодом.
+разделов идут по порядку и вместе образуют одну программу. Автоматически её сейчас не сверяет ни один тест: тест
+`docs` отстал от текста. Если пример разошёлся с поведением пакета, верен код.
 
 ## 1. Быстрый старт
 
-Нужен PostgreSQL 18 и роль администратора: суперпользователь или роль с правом `CREATEROLE`. Установите пакет:
+Нужен PostgreSQL 18 и роль администратора: суперпользователь или роль с `CREATEROLE`, правом `CREATE` в базе (схема
+и расширение pgcrypto) и `CREATEDB`, если базы ещё нет. Установите пакет:
 
 ```sh
-npm install letopis zod postgres    # postgres — для createTenant и своих SQL-запросов
+npm pkg set type=module             # код приложения — ESM: "type": "module" или файлы .mjs
+npm install letopis zod postgres@3  # postgres@3 — для createTenant и своих SQL-запросов
+npm install -D tsx                  # запуск примеров на TypeScript: npx tsx app.ts
 ```
 
+`postgres` — зависимость letopis версии 3. Ставьте ту же мажорную версию: `npm i postgres` без версии поставит 4.x,
+и код будет работать, но `createTenant(admin, …)` не пройдёт проверку типов — типы двух копий `postgres` несовместимы.
+
+Пакет — модуль ES, и примеры написаны на `import`: без `"type": "module"` в `package.json` приложения (или без
+расширения `.mjs`) Node ответит `SyntaxError: Cannot use import statement outside a module`.
+
 Приложение подключается к базе отдельной ролью, которая состоит в `letopis_app`. Её заводит сама установка: опция
 `login` у `up()` создаёт роль с паролем (повтор только обновит пароль) и выдаёт ей `letopis_app`.
 
@@ -111,7 +128,10 @@ await svc.close()
   `owner` в нём.
 - `connect({ apiKey })` обменял ключ сервиса на сессию. `verifyPassword` вернул `{ account, token }` (или `null`,
   если пароль неверный). `svc.as(account, { tenant })` — тот же пул соединений, но от имени Анны в магазине;
-  право сервиса на это проверяет база.
+  право сервиса на это проверяет база. Сессия входа и `svc.as(account)` без `tenant` работают в **личном**
+  арендаторе Анны (id её аккаунта): классов магазина там нет, и шаг `db.Product()` дал бы `invalid_class`. Своё
+  подключение по токену (`connect({ token })`) переходит в магазин через `auth.switch()`
+  ([«Работа в другом арендаторе»](#работа-в-другом-арендаторе)).
 - `hub('Product', поля, опции)` описал класс-объект. `ends: { Shop }` — обязательная ссылка на магазин.
   `key: ['Shop', 'sku']` — ключ: id товара вычисляется из магазина и артикула, а второй товар с тем же ключом база
   не примет.
@@ -119,7 +139,9 @@ await svc.close()
   уменьшил цену внутри оператора `UPDATE`, без предварительного чтения. `versions()` прочитал историю из журнала.
 
 Повторный вызов `up()` безопасен: он повторно накатывает ту же ревизию и данные не трогает, а ключ сервиса снова не
-выдаёт, пока в установке есть хоть один ключ API, кроме отозванных. Дальше раздел 2 объясняет устройство, а разделы 3–13 разбирают задачи по порядку.
+выдаёт, пока в установке есть хоть один ключ API, кроме отозванных. Поэтому код, который запускают не один раз,
+передаёт свой ключ — `up({ …, serviceKey: process.env.SERVICE_KEY })` — и подключается с ним
+(`apiKey: r.serviceKey ?? process.env.SERVICE_KEY`); повторный `create()` того же магазина даст `exists`. Дальше раздел 2 объясняет устройство, а разделы 3–13 разбирают задачи по порядку.
 
 ## 2. Как устроен letopis
 
@@ -174,6 +196,28 @@ LOGIN-роль состоит только в ней. Всё, что выпол
   которая обходит RLS (суперпользователь, `BYPASSRLS`, член `letopis_owner`), если не указано
   `allowBypassRls: true`.
 
+### Безопасность по умолчанию
+
+Опасное действие нельзя совершить случайно — без сверки с тем, что видел человек, оно отклоняется до записи:
+
+- **Удаление — только по превью.** `delete()` — превью; удаляет `delete({ confirm: true, expect: превью })`, ровно
+  показанное. `delete({ confirm: true })` без `expect` — `invalid_query` (`write.confirm_without_expect`).
+- **Восстановление — только по надгробиям.** `restore({ expect })` с ответом `delete()` или строками `withDeleted()`;
+  `restore()` без `expect`, в том числе по явному id, — `invalid_query` (`write.restore_without_expect`).
+- **Массовое — только явно.** Правка и удаление без фильтра — `invalid_query`, пока нет `{ all: true }`; удаление и
+  восстановление без сверки — тоже только с `{ all: true }`.
+- **Арендатор и права — в базе.** Права по умолчанию запрещают, строки чужого арендатора не видны; роль в обход RLS
+  `connect()` отклоняет (`bypass_rls`), пока не передано `allowBypassRls: true`. Арендатора берут только из серверной
+  сессии ([«Веб-сервис: одно подключение и безопасность»](#веб-сервис-одно-подключение-и-безопасность)).
+- **Администраторский пул — явно.** `createTenant(admin, …)` принимает только пул `postgres()` (`api.create_tenant_admin`).
+- **Секреты в журнале событий маскируются**: поля с паролями, токенами, ключами и кредами, учётные данные в строке
+  подключения; значения параметров SQL и тексты ошибок PostgreSQL не пишутся вовсе. Значения фильтров чтения журнал
+  пишет как есть — персональные поля добавьте в `redact` ([«Логирование»](#логирование)).
+
+Общие правила для любой задачи на letopis — одна открытая запись на объект через ключ связи, удаление и возврат по
+превью, гонки, перевод ошибок в текст для человека — собраны в [памятке](AGENT-CHEATSHEET.md), «Правила для любой
+задачи».
+
 ### Как идёт чтение
 
 Под RLS индексы по `data` и по обратным ссылкам политике напрямую недоступны. Поэтому id для шагов цепочки
@@ -225,6 +269,7 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 | `owner`, `app` | имена ролей владельца и приложения (по умолчанию `letopis_owner`, `letopis_app`) |
 | `login` | роль приложения `{ user, password }`: заводится или получает новый пароль и членство в `letopis_app`; строка подключения — `r.login.dsn` ([«Роль приложения»](#роль-приложения)) |
 | `migrationsDir` | свой каталог миграций для `upgrade` (по умолчанию `sql/migrate/` пакета) |
+| `log`, `logLevel`, `redact` | журнал событий установки (`up`, `migrate`), как у `connect()` ([«Логирование»](#логирование)) |
 
 Результат: `schema` (полное имя), `serviceKey` (при первой установке и при накате, когда в установке не осталось ни
 одного ключа API, кроме отозванных: истёкший или выключенный ключ тоже в счёт; иначе `null`), `created`,
@@ -233,6 +278,11 @@ LOGIN-роль состоит только в ней. Всё, что выпол
 (предупреждения, без `quiet` они печатаются), а также `tenant`, `pglite` и `login` (`{ user, created, dsn }`), если
 их просили. На PostgreSQL ниже 18.2 `up()` предупреждает: такой сервер мог усечь CLOG, который ещё нужен непрочитанным сигналам, — обновите его.
 
+Ключ сервиса храните сами: повторный `up()` его не отдаёт (`serviceKey: null`). `up({ fresh: true })` ставит схему
+заново — вместе с данными пропадают сессии и ключи, и выдаётся новый ключ сервиса. Процесс со старым ключом получит
+`no_session: неверный ключ`: перезапустите его с новым. Чтобы ключ не менялся между установками (разработка,
+стенды), передавайте свой: `up({ …, serviceKey: process.env.SERVICE_KEY })` — он регистрируется и в новой схеме.
+
 Несколько экземпляров сервиса могут звать `up()` одной схемы одновременно: накат идёт под блокировкой схемы. Первый
 `up()` ставит или обновляет её, остальные ждут и делают повторный накат по готовой (`created: false`,
 `upgraded: false`); первого арендатора `tenant` заводит один из них, остальные находят его по имени. `up()` разных
@@ -272,37 +322,44 @@ const ANNA = r.tenant!.user!       // его первый пользовател
 ### Первый арендатор и пользователь
 
 Права в letopis включены всегда и по умолчанию запрещают всё. Поэтому новому арендатору нужны правила. Опция
-`up({ tenant })` и функция `createTenant(sql, schema, opts)` делают это одной транзакцией:
+`up({ tenant })` и функция `createTenant(admin, schema, opts)` делают это одной транзакцией:
 
 - арендатор — аккаунт в System с id из имени («tenant:<имя>»);
-- правило «аутентифицированным можно всё» в этом арендаторе (`grantAll`, по умолчанию да, вес 10; права только по
+- правило «аутентифицированным можно всё» в этом арендаторе — чтение, запись и удаление строк всех классов, но не
+  эндпоинты `api` (`grantAll`, по умолчанию да, `grantAll: false` — без него; вес 10; права только по
   ролям — [ниже](#права-только-по-ролям));
 - пользователь (id из логина) с членством в арендаторе с ролями `user.roles` (по умолчанию `['owner']`), паролем и
   сессией в арендаторе.
 
-Повтор с теми же именем и логином ничего не дублирует и пароль не меняет, только выдаёт новую сессию. Логин входит в
-id как есть: `Anna@shop.ru` и `anna@shop.ru` дали бы два аккаунта, и у второго не было бы пароля, — пишите логин в
-одном регистре. Поле `created` в ответе — создан ли арендатор этим вызовом: для существующего арендатора с новым
+Повтор с теми же именем и логином ничего не дублирует и пароль не меняет, только выдаёт новую сессию. Крайние пробелы
+логина отбрасываются (` anna@shop.ru ` и `anna@shop.ru` — один пользователь), а регистр входит в id как есть:
+`Anna@shop.ru` и `anna@shop.ru` дали бы два аккаунта, и у второго не было бы пароля, — пишите логин в одном регистре. Поле `created` в ответе — создан ли арендатор этим вызовом: для существующего арендатора с новым
 пользователем оно `false`. Роли задаёт `user.roles` — непустой список имён (не масок), иначе `invalid_data`. Вид
 пароля `user.kind` (по умолчанию `PASSWORD`) подчиняется правилу вида креда, как у `auth.setPassword`
 ([«Справочник API»](#dbauth)), иначе — тоже `invalid_data`. Роли
 уже существующего членства повтор не меняет: их меняет правка членства ([«Выдать право»](#выдать-право)).
 Удалённое повтор не воскрешает: если арендатор, аккаунт пользователя или членство удалены (строки нет, а история в
 журнале есть), `createTenant` отвечает `invalid_data` и не записывает ничего. Текст ошибки называет удалённое и
-советует вернуть его `restore()`: аккаунт — `db.Account(id).restore()` от имени системного администратора,
-членство — `db.member(id).restore()` в этом арендаторе; другой выход — другое имя или логин. Сессия
+советует вернуть его `restore({ expect })` с надгробием из `withDeleted().rows()`: аккаунт —
+`db.Account(id).restore({ expect: await db.Account(id).withDeleted().rows() })` от имени системного администратора,
+членство — так же `db.member(id)` в этом арендаторе; другой выход — другое имя или логин. Сессия
 из `createTenant` — без способа входа, поэтому свой пароль по ней не сменить: для этого пользователь входит по
-паролю. `createTenant` нужен администраторский пул postgres.js:
+паролю.
+
+`admin` — **пул `postgres()`** администраторской роли (функция с методами `begin` и `unsafe`), а не строка
+подключения и не подключение `connect()` letopis: другое значение `createTenant` отклоняет до запросов — `invalid_query`
+(`api.create_tenant_admin`, текст называет, что передали). `schema` — как у `connect()` и `up()`: `'shop'` даёт
+`v2.shop`, можно сразу `'v2.shop'` или `r.schema`. Пул закрывает вызывающий:
 
 <!-- run: guide -->
 ```ts
 import postgres from 'postgres'
 import { createTenant } from 'letopis'
 
-const pg = postgres(ADMIN)
-const lutik = await createTenant(pg, r.schema, {
+const admin = postgres(ADMIN)                     // пул postgres(), не строка DSN
+const lutik = await createTenant(admin, r.schema, {
   name: 'Лютик', user: { name: 'Борис', login: 'boris@lutik.ru', password: 'Лютик-2026!' } })
-await pg.end()
+await admin.end()
 const BORIS = lutik.user!          // lutik: { tenant, user, token, created: true }
 ```
 
@@ -325,7 +382,7 @@ const anna = await connect({ dsn: APP, schema: r.schema, token: r.tenant!.token!
 | Опция `connect()` | Что делает |
 |---|---|
 | `dsn` или `sql` | строка подключения или готовый пул postgres.js |
-| `schema` | полное имя установки: `'v2.shop'` (удобно брать `r.schema`) |
+| `schema` | имя установки: `'v2.shop'` (удобно брать `r.schema`) или, как у `up()`, `'shop'` — то же `v2.shop` |
 | `token`, `apiKey` | токен сессии или ключ API (`service` — синоним `apiKey`) |
 | `models` | модели `letopis/model` — только для типов цепочек ([раздел 4](#4-модель-данных)) |
 | `max` | размер пула (по умолчанию 10) |
@@ -333,6 +390,7 @@ const anna = await connect({ dsn: APP, schema: r.schema, token: r.tenant!.token!
 | `cache` | кэш результатов: `{ ttl, max, ttlOnly }` или `false` ([раздел 12](#12-подписка-на-изменения-и-кэш)) |
 | `maintain` | запускать `maintain()` по расписанию: `'1h'`, `'15m'` или миллисекунды |
 | `onQuery`, `slowMs` | хук на каждый запрос цепочки и порог медленного запроса |
+| `log`, `logLevel`, `redact` | журнал событий: функция или объект-логгер (`console`, pino), порог (`'info'` по умолчанию) и ещё имена полей для маскировки ([«Логирование»](#логирование)) |
 | `refreshSession` | продлевать сессию раз в минуту работы (по умолчанию да) |
 | `notifyIntervalMs` | интервал отправки отложенных сигналов (100 мс) |
 | `allowBypassRls`, `owner` | разрешить роль в обход RLS (администраторское подключение); имя роли-владельца |
@@ -342,7 +400,8 @@ const anna = await connect({ dsn: APP, schema: r.schema, token: r.tenant!.token!
 проверяют опции `up()`, `db.load()`, `db.watch()` и `createMcpServer()` ([«Строгий режим»](#строгий-режим)).
 
 У подключения есть `db.schema`, `db.token`, `db.tenant` (арендатор сессии) и `db.close()`. Подключения,
-полученные через `as()`, делят пул с исходным: закрывать нужно исходное.
+полученные через `as()`, делят пул с исходным: закрывать нужно исходное, один раз — оно закрывает пул, подписки и все
+фасады. `close()` у подключения из `as()` ничего не делает: пул общий, и фасад после такого вызова работает дальше.
 
 ### Администраторское подключение
 
@@ -377,14 +436,14 @@ await solo.close()                           // закрывает оба пул
 
 ### Обновление пакета и схемы
 
-У схемы есть ревизия движка (сейчас 8). Если новая версия пакета принесёт новую ревизию, `connect()` только
+У схемы есть ревизия движка (сейчас 10). Если новая версия пакета принесёт новую ревизию, `connect()` только
 предупредит и назовёт команду. Отказывает `up()`: на отставшую схему без `upgrade: true` и на схему новее пакета.
 К схеме новее пакета (её уже обновил более новый пакет, а старые экземпляры приложения ещё работают) `connect()`
 подключается с предупреждением
 «движок схемы … ревизии N новее библиотеки (она знает M) — обновите пакет letopis». Поэтому скрипт запуска, который
 вызывает `up()` при каждом старте, после такого обновления пакета остановится, пока не получит `upgrade: true`.
 `up({ dsn, schema, upgrade: true })` применяет миграции из `sql/migrate/` и повторно накатывает функции; данные
-сохраняются. У 2.0 миграций нет.
+сохраняются. Пока схема не обновлена, `connect()` предупреждает, а функции новой ревизии в ней не работают.
 
 Ревизия меняется не с каждой версией: у версий одной ревизии функции могут быть разные. Поэтому `up()` пишет в
 комментарий схемы ещё и штамп движка: версию пакета и хэш его файлов SQL. Если штамп не совпадает с файлами пакета,
@@ -396,21 +455,22 @@ await solo.close()                           // закрывает оба пул
 
 Версии letopis следуют semver. Что обещает каждый шаг версии:
 
-- **Патч** (2.0.0 → 2.0.1) — только исправления. Ревизия движка та же: исправленные функции накатывает обычный
+- **Патч** (3.0.0 → 3.0.1) — только исправления. Ревизия движка та же: исправленные функции накатывает обычный
   `up({ schema })`, миграций нет; до наката `connect()` предупреждает о расхождении штампа. Работающий код не получает
   новых отказов, методы, опции, экспорты и коды ошибок не исчезают.
-- **Минор** (2.0 → 2.1) — новые возможности: методы, опции, коды ошибок; изменения поведения, которые не ломают
+- **Минор** (3.0 → 3.1) — новые возможности: методы, опции, коды ошибок; изменения поведения, которые не ломают
   работающий код; новая ревизия движка. Новую ревизию накатывает `up({ schema, upgrade: true })`. Удалённого и
   переименованного нет.
-- **Мажор** (2.x → 3.0) — удаление и переименование методов, опций, экспортов и кодов ошибок, смена сигнатур и типов,
+- **Мажор** (3.x → 4.0) — удаление и переименование методов, опций, экспортов и кодов ошибок, смена сигнатур и типов,
   новые отказы для всех. Что снято и чем его заменить, перечисляет запись версии в [CHANGELOG.md](CHANGELOG.md). Схему
   прошлого мажора новый мажор может не обновлять.
 
 Текст сообщения об ошибке в API не входит: в патче он может стать точнее. Полагайтесь на `err.code`.
 
-Шаг версии перед каждым выпуском сверяет сценарий `check:semver`: он сравнивает контракт API (`docs/api-contract.json`)
-и ревизию движка с прошлым выпуском и требует шаг не меньше нужного. Каждый следующий выпуск 2.x проверяет
-обновление схемы с предыдущего выпуска.
+Шаг версии перед каждым выпуском сверяет сценарий `check:semver`: он сравнивает контракт API (`lib/api-contract.json`)
+и ревизию движка с прошлым выпуском и требует шаг не меньше нужного. Каждый выпуск проверяет
+обновление схемы с предыдущего выпуска. Что изменилось при переходе на 3.0 и чем заменить снятое — запись
+версии в [CHANGELOG.md](CHANGELOG.md).
 
 ### Разработка без PostgreSQL: PGlite
 
@@ -471,13 +531,8 @@ const line = link('line', { qty: z.number().int().min(1), price: z.number().int(
   ends: { Order: one(Order).onDelete('cascade'), Product },
   key: ['Order', 'Product'],
 })
-const Wallet = hub('Wallet', { number: z.string(), balance: z.number().int().min(0).default(0) },
-  { ends: { Customer }, key: ['number'] })
-const Movement = link('Movement', {
-  opId: z.string(), kind: z.enum(['topup', 'debit', 'adjust']), amount: z.number().int(), target: z.number().int().optional(),
-}, { ends: { Wallet }, key: ['Wallet', 'opId'] })
 
-const models = [Shop, Category, Product, Customer, Vip, Order, line, Wallet, Movement]
+const models = [Shop, Category, Product, Customer, Vip, Order, line]
 const plan = await syncModels(db, models)                     // сухой прогон: что будет создано и изменено
 const applied = await syncModels(db, models, { apply: true }) // { applied: true, created: ['Shop', …], … }
 ```
@@ -489,8 +544,13 @@ const applied = await syncModels(db, models, { apply: true }) // { applied: true
 поле необязательным, `.default(…)` — задаёт умолчание, которое база подставит при вставке. Пометки `.meta()` у поля
 (`title`, `description`, свои ключи) база хранит, но на проверку данных они не влияют.
 
-Правила `refine`, `superRefine` и `transform` в JSON Schema не выражаются, и база их не исполняет. `syncModels`
-возвращает их в `lost`: проверяйте такие правила в приложении. Описание с ключевым словом JSON Schema, которого
+Правила `refine` и `superRefine` в JSON Schema не выражаются, и база их не исполняет. `syncModels` возвращает их в
+`lost`: проверяйте такие правила в приложении. Преобразования Zod — `.trim()`, `.toLowerCase()`, `.toUpperCase()`,
+`.normalize()`, `.transform()`, `z.preprocess()`, `.pipe()` — меняют значение, а не проверяют его: ни база, ни
+валидатор их не исполняют, и данные записались бы как есть. Поэтому модель с ними `syncModels` (и `letopis sync`)
+отклоняет до записи, в том числе в сухом прогоне: `invalid_class` (`model.transform_unsupported`, пути и виды — в
+`err.detail.rules`). Значение приводят в коде сервиса до записи (`value.trim()`), а в модели оставляют проверку:
+`.regex()`, `.min()`, `.refine()`. Описание с ключевым словом JSON Schema, которого
 база не знает, отклоняется — ни одно правило не пропадёт молча. Шаблоны `pattern` — ограниченное подмножество
 регулярных выражений, общее для Zod, валидатора и базы. Исполняет шаблон на данных только база: шаблон задаёт
 арендатор, и шаблон с катастрофическим перебором повесил бы процесс приложения. Поэтому валидатор на TypeScript
@@ -521,7 +581,10 @@ const applied = await syncModels(db, models, { apply: true }) // { applied: true
 Нужный формат ключевого поля задайте в модели, и база будет его проверять.
 
 - id не передают: база вычисляет его сама. Чужой id — `id_mismatch`, id для класса без ключа — `id_from_db`.
-- Заранее id вычисляет `db.idOf(класс, ключ)`, например `db.idOf('Shop', { name: 'Ромашка' })`.
+- Заранее id вычисляет `db.idOf(класс, ключ)`, например `db.idOf('Shop', { name: 'Ромашка' })`. Часть ключа — конец
+  связи: имя роли и id цели строкой, `db.idOf('Product', { Shop: shop.id, sku: 'K-1' })` (не строка ответа). Часть
+  ключа не строкой — `invalid_data` (`model.key_part_not_string`), конец не uuid — `invalid_data`
+  (`model.key_end_not_uuid`).
 - Класс без ключа (`Customer` выше) получает id от случайной части; узнать его можно из ответа записи.
 - Ключ и класс объекта неизменны: правка ключевого поля или класса — `immutable_key`. Объект с другим ключом или
   классом — новый объект ([раздел 5](#5-запись), «Ключ и класс неизменны»).
@@ -556,7 +619,21 @@ id из email подбирается перебором и остаётся в
 `syncModels` трогает только переданные классы и ничего не удаляет. Безопасные изменения — новое необязательное поле или
 конец, метаданные, алиас — применяются сразу. Всё остальное, в том числе любая правка условий `anyOf` и `oneOf`, —
 ужесточение: оно проверяет все строки семейства, и если им мешают строки, приходит `tightening_conflict` со списком. Классы пишутся в арендатора сессии, и другие арендаторы их не видят.
-Классы, общие для всех, лежат в System: их ставит сид установки.
+Классы, общие для всех, лежат в System: их ставит сид установки. Модель с преобразованиями Zod `syncModels`
+отклоняет ([«Поля»](#поля)).
+
+Одна модель в нескольких арендаторах — `syncModels` в сессии каждого: сервис действует от имени пользователя, которому
+в этом арендаторе можно писать классы (по правилу «можно всё» — его члену):
+
+```ts
+for (const [user, tenant] of [[ANNA, SHOP], [BORIS, lutik.tenant]]) {
+  await syncModels(await svc.as(user, { tenant }), models, { apply: true })   // классы — в каждом арендаторе свои
+}
+```
+
+Из командной строки — тот же `letopis sync` с токеном сессии каждого арендатора. Повтор по арендатору, где модель уже
+записана, ничего не меняет (`unchanged`). Администраторское подключение для этого не нужно: через фасад `svc.as()`
+классы пишет сессия пользователя в пуле приложения, под RLS.
 
 То же из командной строки:
 
@@ -610,9 +687,28 @@ const n = await loose(typed)[name]().count()
 
 | Что | Ответ |
 |---|---|
-| `update()` или `delete({ confirm: true })`, а ни у шага глагола, ни у шагов до него нет фильтра, id, непустого `tags()`, `owner()` или `limit()` и раньше в цепочке нет `create()` или `upsert()` (цель `update()` задаёт и `data.id` патча) | `invalid_query` до записи, в батче — при `run()`; все строки шага — `{ all: true }` ([раздел 5](#изменить-update), [раздел 7](#превью-и-удаление)) |
+| `delete({ confirm: true })` без `expect` (и без `all: true`) | `invalid_query` (`write.confirm_without_expect`) до записи, в батче — при `run()`: удаление не сверено с превью, которое видел пользователь ([раздел 7](#превью-и-удаление)) |
+| `restore()` без `expect` (и без `all: true`), в том числе по явному id | `invalid_query` (`write.restore_without_expect`) до записи ([«Восстановить: `restore`»](#восстановить-restore)) |
+| `update()` или `delete({ confirm: true, expect })`, а ни у шага глагола, ни у шагов до него нет фильтра, id, непустого `tags()`, `owner()` или `limit()` и раньше в цепочке нет `create()` или `upsert()` (цель `update()` задаёт и `data.id` патча) | `invalid_query` (`write.no_filter`) до записи, в батче — при `run()`; все строки шага — `{ all: true }` ([раздел 5](#изменить-update), [раздел 7](#превью-и-удаление)) |
 | неизвестная опция `connect()`, `up()`, `db.load()`, `db.watch()`, `createMcpServer()` | `invalid_data` с похожими именами |
-| шаг — не класс, не алиас и не роль реестра | `invalid_class` с похожими именами — при вызове шага |
+| шаг — не класс, не алиас и не роль реестра | `invalid_class` с похожими именами (системные классы в похожие не идут) — при вызове шага; подсказка — классы арендатора видны только в его сессии. В реестре сессии нет ни одного класса арендатора — свой ключ `api.unknown_step_no_classes`: сессия, похоже, в личном арендаторе ([«Работа в другом арендаторе»](#работа-в-другом-арендаторе)) |
+| у цепочки спросили свойство массива — `.length`, `.map()`, `.filter()`, `.forEach()`, `[0]` и т. п. — или перебрали её (`for…of`, `[...цепочка]`) | `invalid_query` (`api.chain_not_rows`): цепочка — не массив, строки даёт терминал — `await ….rows()` |
+| id шага, фильтра `{ id }` или значения конца — не uuid, `null` вместо id | `invalid_query` (`query.bad_uuid`) до запроса; id в любом виде, который принимает PostgreSQL (без дефисов, в фигурных скобках), проходит |
+| модель с преобразованием Zod (`.trim()`, `.transform()` …) | `invalid_class` (`model.transform_unsupported`) от `syncModels` до записи ([«Поля»](#поля)) |
+| `db.begin(аргумент)` — функция, строка, число, массив вместо опций `{ reason }` | `invalid_query` (`api.begin_arg`): `begin()` функцию не вызывает; неизвестная опция `begin()` — `invalid_data` с похожими |
+| `restore({ partial: true })` без `expect`, в том числе с `all: true` | `invalid_query` (`write.partial_without_expect`) |
+| `createTenant(admin, …)`, где `admin` — не пул `postgres()`: строка DSN, подключение `connect()`, `undefined` | `invalid_query` (`api.create_tenant_admin`) до запросов ([«Первый арендатор и пользователь»](#первый-арендатор-и-пользователь)) |
+| метод цепочки у результата `versions()`: `versions().rows()`, `.sort()`, `.limit()` | `invalid_query` (`api.versions_terminal`): `versions()` — терминал, модификаторы — до него |
+| `forUpdate()` с тем, что блокировать нельзя: `count()`, `paths()`, `versions()`, агрегат, `asOf()`, `withDeleted()`, `deep()`, глагол | `lock_unsupported` (`api.for_update_unsupported`): текст называет помеху |
+
+**Предупреждения** — не отказы: цепочка исполняется, а в консоль один раз на место (`console.warn`, текст начинается с
+`letopis:`) выводится строка:
+
+| Что | Ключ | Почему |
+|---|---|---|
+| шаг с аргументом `undefined`: `db.Product(undefined)` | `api.step_undefined_filter` | фильтра нет — шаг находит все строки, как `db.Product()`; чаще всего это пустая переменная с id |
+| шаг после `sort()`: `db.Shop(shop).sort('data.name').Product()` | `api.sort_not_last` | `sort()` относится к последнему шагу цепочки — ставьте его в конец |
+| `withDeleted()` не у последнего шага, а у последнего его нет: `db.Order(o).withDeleted().line()` | `api.with_deleted_step` | `withDeleted()` — модификатор своего шага: здесь удалённые заказы и живые строки; удалённые строки — `.line().withDeleted()` ([«Удалённые»](#удалённые)) |
 | поле фильтра (и внутри `or()`), `sort('data.…')` или агрегата, которого нет в описании ни одного класса шага (с потомками, если шаг не `exact()`; у роли — её целей); в фильтре годится и роль конца | `invalid_query` с похожими именами до запроса, у плана записи — до записи. Сверяется только первый ключ пути: путь внутрь поля-объекта не проверяется. У строк `Class` поля — свойства описания класса (`kind`, `alias`, `parent` и другие) |
 | `after()` перед `count()`, `sum()`, `avg()`, `min()`, `max()` или `countBy()` | `invalid_query`: курсор листает строки, а счёт идёт по всем объектам шага |
 | класс с зарезервированным именем | `invalid_class`: хаб — от `hub()`, `syncModels` и базы, связь — от базы ([«Имена классов»](#имена-классов)) |
@@ -658,8 +754,19 @@ try {
   защищён: повтор создаст второй объект.
 - Теги новой строки задаёт `.tags([…])` перед глаголом, владельца — `.owner(id)`; явного владельца должны разрешать
   права.
-- Удалённый объект можно создать снова тем же ключом: история продолжится.
+- Удалённый объект можно создать снова тем же ключом: новый объект **занимает id удалённого** (id — v5 от ключа), и
+  история id продолжится. Восстановить прежний после этого нельзя: `restore({ expect })` по его надгробию — `not_deleted`
+  (`write.restore_id_taken`). Если удалённое ещё могут вернуть, перед `create()` проверьте
+  ключ вместе с удалёнными: `db.Shop({ name: 'Ромашка' }).withDeleted().first()` — строка с `$deleted: true` значит,
+  что ключ принадлежит удалённому объекту, и решать, восстановить его или занять ключ, должно приложение.
 - Ответ — строки созданных объектов со всеми колонками ([раздел 14](#14-справочник-api), «Строка ответа»).
+- Ключи со значением `undefined` (`{ phone: undefined }`) `create`, `upsert` и `update` отбрасывают. У `update` поле
+  поэтому не меняется, а `upsert` заменяет данные целиком — поле с `undefined` у него **пропадает**, как не
+  переданное. `null` — значение: оно проходит, только если схема поля его допускает (`.nullable()`).
+- Концы — не поля данных: ключ с именем роли (`{ Shop: shop.id }`) в данных `create` — ошибка `invalid_data` с ключом
+  `write.link_in_data` до записи: текст называет ключ и класс («… — связь, а не поле данных») и сразу форму слота —
+  `.Shop.set(id)`; конец берётся из пути или задаётся слотом ([«Концы: из пути и слоты»](#концы-из-пути-и-слоты)). То
+  же у `upsert` и `update`.
 
 ### Изменить: `update`
 
@@ -678,6 +785,15 @@ await db.Shop(shop).Product({ price: gte(2000) }).update({ title: 'Чайник
 сужает); без них — `invalid_query` до записи
 ([«Строгий режим»](#строгий-режим)). Править все строки шага — явно: `db.Product().update({ views: 0 }, { all: true })`
 правит все товары арендатора. Шаг ничего не нашёл — ответ пустой и ошибки нет, поэтому проверяйте длину ответа.
+
+Фильтр, который сужает цели не только по id (по данным, концам, `tags()`, `owner()`), `update` перепроверяет: цели
+блокируются (`for no key update`, по порядку id) и читаются заново тем же запросом, а правятся только строки, которые
+и после ожидания блокировки подходят. Так `db.Product({ price: gte(2000) }).update(…)` не тронет товар, который
+параллельная транзакция успела удешевить, а из двух одновременных `db.Order({ id, status: 'new' }).update({ status:
+'paid' })` проходит один — второй отвечает `[]`. Фильтр родительского шага перепроверяется так же. Без гонки цели те
+же. Фильтр только по id перепроверять нечего: две одновременные правки одного id пройдут обе, вторая поверх первой. Перепроверка защищает только условие самого фильтра:
+новое значение, вычисленное из прочитанного, защищают `{ rev }` и `forUpdate()` в `db.begin()`, а правило «не больше
+одной открытой записи на объект» — ключ связи ([«Восстановить: `restore`»](#восстановить-restore)).
 Если `update` затронул меньше строк, чем нашёл шаг, весь план откатывается: строку успели удалить —
 `target_not_found`, строка видна, но править её нельзя — `acl_denied`. Модификатор `.tags(…)` перед `update`
 отбирает строки; строка или список ещё и заменяют их теги целиком, а оператор (`has`, `hasAny`, `hasAll`) только
@@ -695,9 +811,10 @@ const [replaced] = await db.Shop().upsert({ name: 'Ромашка', city: 'Уф
 один оператор `INSERT … ON CONFLICT`, поэтому гонки «проверил, что нет, — создал» не бывает. Правила:
 
 - только класс с ключом, иначе `no_key` без обращения к базе;
-- объект передаётся целиком: поля, которых нет в переданном объекте, пропадают;
+- объект передаётся целиком: поля, которых нет в переданном объекте или которые равны `undefined`, пропадают;
+  сохранить прежнее значение поля — `update`, а не `upsert`;
 - ответ несёт `$upsert`: `created`, `updated` или `unchanged`;
-- приращать `upsert` не умеет и затирает параллельные приращения — для денег он не годится;
+- приращать `upsert` не умеет и затирает параллельные приращения — для счётчиков он не годится;
 - для синхронизации больших справочников дешевле загрузчик с `existing: 'update'` ([раздел 9](#9-массовая-загрузка)).
 
 ### Концы: из пути и слоты
@@ -716,6 +833,16 @@ await db.Category(green).update({}).Parent.unset().rows()         // катег
 await db.Category(green).update({}).Parent.set(tea).rows()        // и снова внутри «Чая»
 ```
 
+У связи с двумя концами один конец обычно приходит из пути, второй — слотом; можно и оба слотом. Строка заказа
+`line` с концами `Order` и `Product` (пример целиком — в [«Как исполняется план»](#как-исполняется-план)):
+
+```ts
+await db.Order(order).line().create({ qty: 1, price: 900 }).Product.set(sencha).rows()      // Order — из пути
+// или так — оба конца слотом (вместо строки выше: ключ [Order, Product] второй такой строки не даст)
+await db.line().create({ qty: 1, price: 900 }).Order.set(order).Product.set(sencha).rows()
+// db.line().create({ qty: 1, price: 900, Order: order, Product: sencha.id }) — invalid_data: концы не поля данных
+```
+
 ### Числа и счётчики: `inc`
 
 <!-- run: guide -->
@@ -734,7 +861,7 @@ await db.Product(kettle).update({ views: inc(1, { start: 0 }) }).rows()    // п
 - поле должно уже быть числом; если его нет — `invalid_data` или `start`. `null` и нечисло — ошибка даже со `start`;
 - путь идёт только через существующие объекты;
 - маркер `inc` нельзя получить из JSON: `{ "$inc": 5 }`, пришедший из сети, остаётся данными;
-- деньги храните целым числом мелких единиц (копеек) не больше 2^53 − 1.
+- суммы храните целым числом мелких единиц (копеек) не больше 2^53 − 1.
 
 Операции `inc` одного объекта идут друг за другом под блокировкой его строки, и каждая пишет его версию: писатели
 одного горячего счётчика ждут друг друга.
@@ -755,7 +882,7 @@ try {
 Правка с `{ rev }` нужна, когда новое значение вычислено из прочитанного: если строку успели изменить, приходит
 `conflict`, и ничего не записывается. `{ rev }` работает при одной цели шага (иначе `rev_ambiguous`). `conflict`
 библиотека сама не повторяет: что делать с изменившимися данными, решает приложение. Другой способ — чтение с
-блокировкой `forUpdate()` ([раздел 8](#8-транзакции-батчи-и-деньги)).
+блокировкой `forUpdate()` ([раздел 8](#8-транзакции-и-батчи)).
 
 ### Ключ и класс неизменны
 
@@ -816,6 +943,13 @@ const onlyCustomer = await db.Customer().exact().rows()        // только
 ценой `"900"`. Список как значение поля — «массив содержит все элементы». Операторы приводят своё значение к типу
 поля из JSON Schema. Роль конца в фильтре — id цели или `null`.
 
+Тип поля для сравнения — по классу шага. Шаг по родителю отдаёт и потомков, и в таком семействе поле может быть
+описано разными типами (потомок переопределил тип, в одном из классов поле не описано). Тогда значение, которое к
+типу класса шага не приводится, в операторах сравнения, `sort()`, `after()` и агрегатах `min`, `max`, `sum`, `avg`
+считается `null`: при сортировке по возрастанию оно идёт после прочих (по убыванию — первым), ни одному оператору
+сравнения не отвечает, агрегат его пропускает, а курсор такой строки — как курсор `null`. Значение, которое
+приводится (`'7'` у числового поля), сравнивается как число. В семействе с одним типом поля всё как обычно.
+
 <!-- run: guide -->
 ```ts
 import { lt, ilike, between, or, not } from 'letopis'
@@ -855,6 +989,18 @@ const roots = await db.Category({ Parent: null }).rows()       // корневы
 
 Теги и владелец строки — модификаторы `.tags(…)` и `.owner(…)`.
 
+Пустые значения в фильтре:
+
+- `{ поле: null }` — вхождение в `data`: находит только строки, где в поле явно записан `null`. Строки, где поля нет
+  совсем, находят `isNull()` (и `null`, и нет поля) и `exists(false)` (только нет поля).
+- Фильтр `undefined` — шаг без фильтра: `db.Product(undefined).first()` вернёт любой товар и выведет предупреждение
+  `api.step_undefined_filter` ([«Строгий режим»](#строгий-режим)). Ключ со значением `undefined` в объекте фильтра
+  (`{ id: undefined }`, `{ Shop: undefined }`) отбрасывается. `update()` без сужения откажет сам (`invalid_query`), а
+  чтение — нет: обязательные id из запроса проверяйте до цепочки.
+- id в фильтре — uuid. Строка другого вида (`db.Product('42')`), а также `null` вместо id — `invalid_query`
+  (`query.bad_uuid`) до запроса: `Product(…): "42" — не uuid`. Так же проверяются `{ id }` и значение конца
+  (`{ Shop: '42' }`). Подходит любой вид, который принимает PostgreSQL: с дефисами, без них, в фигурных скобках.
+
 ### Терминалы и строка ответа
 
 | Терминал | Что отдаёт |
@@ -882,6 +1028,13 @@ const page2 = await db.Product().sort('data.price', 'desc')
   .after(cursorOf(page1.at(-1)!, 'data.price')).limit(2).rows()   // строго после последней строки страницы
 ```
 
+Модификаторы выборки не привязаны к шагу, после которого стоят. `sort`, `limit`, `offset`, `after` и `forUpdate`
+относятся к последнему шагу цепочки (а перед глаголом — к его целям), `asOf` — ко всей цепочке:
+`db.Shop(shop).sort('data.price').Product().rows()` сортирует товары, а поле `sort()` сверяется с классом последнего
+шага — иначе `invalid_query` с именем этого класса. Шаг после `sort()` выводит предупреждение `api.sort_not_last`:
+ставьте `sort()` в конец цепочки. `withDeleted()` — модификатор своего шага, как `exact()`
+([«Удалённые»](#удалённые)).
+
 `sort(поле, 'asc' | 'desc')` — по `'at'`, `'rev'`, `'id'` или `'data.<путь>'`. `after(cursorOf(строка, поле))` —
 постраничный вывод «после такой-то строки»; он требует `sort()`. Такой вывод устойчив к вставкам и удалениям между
 страницами, но строка, у которой изменилось поле сортировки, может выпасть или повториться. Курсор — объект
@@ -936,7 +1089,8 @@ const orderPaths = await db.Order(order).line().Product().paths()   // [{ Order:
 ```
 
 `paths()` отдаёт узлы каждого варианта пути; ключ узла — имя шага или имя из `.alias(имя)`. Ключи идут в порядке
-шагов; если цепочка кончается возвратом к прежнему узлу, этот узел — последний. Повтор связи в
+шагов; если цепочка кончается возвратом к прежнему узлу, этот узел — последний. Совпавшие имена получают первый
+свободный ключ: `x`, `x_2`, `x_3` и так далее, ни один узел не теряется. Повтор связи в
 цепочке возвращает к её узлу: так из одной связи можно пройти в несколько сторон. `db.entity(строка | цепочка)`
 вставляет готовый узел в путь.
 
@@ -947,25 +1101,35 @@ const orderPaths = await db.Order(order).line().Product().paths()   // [{ Order:
 <!-- run: guide -->
 ```ts
 const preview = await db.Order(order).delete().rows()     // ничего не удаляет: заказ и его строки, $action каждой
-await db.Order(order).delete({ confirm: true }).rows()    // удалено: надгробия с $deleted: true
+const goneOrder = await db.Order(order).delete({ confirm: true, expect: preview }).rows()   // надгробия, $deleted: true
 
-const blockers = (await db.Shop(shop).delete().rows()).filter((x) => x.$action === 'restrict')
+const shopPreview = await db.Shop(shop).delete().rows()
+const blockers = shopPreview.filter((x) => x.$action === 'restrict')
 try {
-  await db.Shop(shop).delete({ confirm: true }).rows()   // магазину мешают товары: конец Shop — restrict
+  await db.Shop(shop).delete({ confirm: true, expect: shopPreview }).rows()   // магазину мешают товары: restrict
 } catch (e) {
   if (!(e instanceof LetopisError) || e.code !== 'delete_restricted') throw e
 }
 ```
 
-`delete()` без `{ confirm: true }` — только превью: всё замыкание каскада. В каждой строке превью `$action`:
-`delete`, `unset` или `restrict`, и `$depth` — уровень каскада (0 — сама цель; у строк `unset` и `restrict` его
-нет). С подтверждением удаляются все цели шага одним оператором, а каскад применяет правила концов. Цели, как у
-`update`, сужают фильтр, id, `tags()`, `owner()` или `limit()` у шага глагола или шагов до него (или `create()` и
-`upsert()` раньше в цепочке), иначе `invalid_query` до записи;
-удалить все строки шага — `delete({ confirm: true, all: true })`, превью — без условий. Итог —
-надгробия по уровням каскада, внутри уровня по id (в таком порядке они и в журнале); цели классов без журнала
-(`history: false`) — в конце. Превью не учитывает права: строка с `$action: 'delete'` может не удалиться у
-пользователя без права (`acl_denied`), поэтому интерфейсу стоит спросить `acl.checkData(класс, 'DELETE')`.
+Удаляют в два шага: `delete()` — превью, его показывают человеку; `delete({ confirm: true, expect: превью })` —
+удаление ровно показанного. `delete()` без `{ confirm: true }` ничего не удаляет и отдаёт всё замыкание каскада. В
+каждой строке превью `$action`: `delete`, `unset` или `restrict`, и `$depth` — уровень каскада (0 — сама цель; у
+строк `unset` и `restrict` его нет). С подтверждением удаляются все цели шага одним оператором, а каскад применяет
+правила концов. Итог — надгробия по уровням каскада, внутри уровня по id (в таком порядке они и в журнале); цели
+классов без журнала (`history: false`) — в конце. Превью не учитывает права: строка с `$action: 'delete'` может не
+удалиться у пользователя без права (`acl_denied`), поэтому интерфейсу стоит спросить `acl.checkData(класс, 'DELETE')`.
+
+- `delete({ confirm: true })` без `expect` — `invalid_query` (`write.confirm_without_expect`) до записи, ничего не
+  удалено: удаление не сверено с тем, что видел пользователь. Подсказка ошибки — та же форма в два шага.
+- Цели, как у `update`, сужают фильтр, id, `tags()`, `owner()` или `limit()` у шага глагола или шагов до него (или
+  `create()` и `upsert()` раньше в цепочке), иначе `invalid_query` (`write.no_filter`) до записи; превью — без условий.
+- Осознанно удалить текущий состав целей без сверки с превью — `delete({ confirm: true, all: true })`: с фильтром —
+  текущие цели фильтра, без фильтра — все строки класса. `all` вместе с `expect` снимает только требование фильтра:
+  превью сверяется. Без сверки — только для скриптов обслуживания, не в ответ на действие пользователя.
+- Чужой, невидимый или несуществующий id — превью пустое, и удаление с `expect: []` отвечает пустым ответом без
+  ошибки, как `update`: проверяйте длину ответа.
+
 Правила концов:
 
 - `restrict` — удаление запрещено, пока на цель ссылаются (`delete_restricted` со списком видимых строк и числом
@@ -976,21 +1140,172 @@ try {
 Каскад требует права на удаление каждой удаляемой строки, снятие ссылки — права на запись. Сырой
 `DELETE … WHERE id IN (…)` любого набора связанных строк работает так же.
 
+**Сверка с превью.** Между превью и подтверждением данные могут измениться: к заказу добавили строку, строку
+поправили. С `expect: превью` удаление в своей транзакции строит превью заново и сравнивает его с показанным — по `id`,
+`rev` и `$action` (строки без `$action` сравниваются по `id` и `rev`). Совпало — удаляет. Не совпало — `conflict` с
+ключом `write.preview_changed`, ничего не удалено, новое превью — в `err.detail.preview`: его показывают пользователю и
+удаляют уже с ним. `expect` без `confirm: true` — `invalid_query` (`write.expect_without_confirm`), `expect` не
+списком строк `{ id, rev }` — `invalid_query` (`write.bad_expect`).
+
+`expect` — строки превью как есть (тип `Expected`: `{ id, rev, $action? }`), порядок не важен. `err.detail.preview` —
+`Row[]` той же формы, что превью: строки с `$action` и, у строк `delete`, `$depth`. Сверка атомарна и под гонкой: всё
+замыкание каскада (строки превью с `$action: 'delete'`) блокируется в порядке id, и превью строится ещё раз уже под
+блокировкой. Связь к удаляемой строке, добавленная до этого, попадает в новое превью (`preview_changed`); добавленная
+позже ждёт удаления и получает `target_not_found` (`sql-write.end_target_missing`) — непоказанное каскадом не уходит.
+Взаимную блокировку двух таких удалений операция из пула повторяет сама (`40P01`), в `db.begin()` — повторяет
+вызывающий. Пустые цели: `expect: []` и целей нет — пустой ответ; `expect` непуст, а целей уже нет (удалены, не
+видны) — `conflict` с пустым `err.detail.preview`.
+
+```ts
+const shown = await db.Order(id).delete().rows()                      // превью — пользователю
+// … пользователь подтвердил
+try {
+  const gone = await db.Order(id).delete({ confirm: true, expect: shown }).rows()   // удалено ровно показанное
+  // gone — надгробия: сохраните, по ним возвращают ровно ушедшее
+} catch (e) {
+  if (!(e instanceof LetopisError) || e.code !== 'conflict') throw e
+  const fresh = (e.detail as { preview: Row[] }).preview             // данные изменились: показать заново
+}
+```
+
 ### Восстановить: `restore`
 
 <!-- run: guide -->
 ```ts
-await db.Order(order).restore().rows()                       // заказ — последним снимком, id прежний
-await db.Order(order).line().withDeleted().restore().rows()  // и его строки, удалённые каскадом
+const back = await db.begin({ reason: 'возврат A-1' })   // заказ и его строки — одной транзакцией
+try {
+  await back.Order(order).restore({ expect: goneOrder }).rows()                      // заказ — тем снимком, что ушёл
+  await back.Order(order).line().withDeleted().restore({ expect: goneOrder }).rows() // и строки этого каскада
+  await back.commit()
+} catch (e) {
+  await back.rollback()                  // ошибка второго шага не оставит заказ без строк
+  throw e
+}
+```
+
+`restore({ expect })` возвращает удалённый объект его последним снимком новой версией и перепроверяет его по текущему
+описанию класса; id прежний. `expect` — надгробия `{ id, rev }`: ответ `delete({ confirm: true, expect })` или строки
+`withDeleted()` с `$deleted: true` (`db.Order(id).withDeleted().rows()`). Восстанавливаются только цели шага, чьи id
+есть в `expect`, а не весь каскад. Живой объект — `not_deleted`.
+
+- `restore()` без `expect` — `invalid_query` (`write.restore_without_expect`) до записи, и по явному id тоже: без
+  `expect` поднялось бы **последнее** надгробие id, а id удалённого может достаться другому — `create()` по ключу
+  удалённого занимает его id ([«Создать: `create`»](#создать-create)), а новый объект потом тоже удаляют.
+- Осознанно вернуть все удалённые цели шага без сверки версий — `restore({ all: true })`: с фильтром — удалённые цели
+  фильтра, без фильтра — всё удалённое класса; `all` вместе с `expect` — сверка по `expect`.
+- Цели — удалённые объекты последнего шага: шаг глагола `restore()` сам читает с удалёнными, `withDeleted()` перед
+  ним не обязателен. Чужой, невидимый или несуществующий id, id не из `expect` — пустой ответ без ошибки, как у
+  `update`: проверяйте длину ответа.
+- Шаги до глагола идут по живым строкам, если у них нет своего `withDeleted()`. Поэтому каскад возвращают после цели —
+  `db.Order(order).line().restore({ expect })` находит строки восстановленного заказа, — а строки ещё удалённого
+  заказа находит `db.Order(order).withDeleted().line().restore({ expect })`.
+
+**Сверка с надгробиями.** Восстанавливаются только цели, у которых последняя версия — это самое надгробие из
+`expect`. Иначе ничего не восстановлено, а отказ называет причину по записи журнала, которая идёт за надгробием цели:
+
+| Что с id после удаления | `why` | Ключ | Код |
+|---|---|---|---|
+| объект уже восстановлен (другим запросом) | `restored` | `write.restore_already` | `not_deleted` |
+| id занял новый живой объект с тем же ключом (`create()` по ключу удалённого) | `reissued` | `write.restore_id_taken` | `not_deleted` |
+| прочее: id пересоздан и удалён снова, объект удалён снова с другим номером версии, гонка | `changed` | `write.restore_stale` | `conflict` |
+
+У всех трёх `err.detail.ids` — id этого вида, а `err.detail.stale` — все цели, которые не восстановить:
+`[{ id, rev, expected, after, deleted, live, why }]`. `rev` — номер последней версии сейчас, `expected` — из
+`expect`, `after` — вид записи журнала сразу за `expected` (`create`, `update`, `delete`, `restore`; `null` — её нет),
+`deleted` — последняя версия — надгробие, `live` — объект живёт, `why` — из таблицы. Цели разного вида в одном вызове
+дают `restore_stale`, если среди них есть `changed`, иначе `restore_id_taken`, если есть `reissued`. Номер версии база
+сверяет ещё раз под блокировкой записи журнала и перечитывает последнюю запись после ожидания, поэтому гонку
+«прочитали надгробие — другой процесс пересоздал id — восстановили» ловит она, а проигравший гонку двух `restore()`
+получает `write.restore_already`. id из `expect`, которых нет среди целей шага, пропускаются: весь ответ `delete()` можно
+передавать каждому шагу. Поэтому шаг глагола задавайте id из `expect`: объект, который по пути уже не найти (связь
+пересоздана с другим концом), по пути молча пропустится, а по id даст `conflict`. Цель и её каскад возвращают одной
+`db.begin()`, цель конца — первой: отказ на любом шаге откатывает всё.
+
+```ts
+const gone = await db.Order(order).delete({ confirm: true, expect: shown, reason: 'отмена A-1 #7f3a' }).rows()
+const ids = (cls: string) => gone.filter((x) => x.class === cls).map((x) => x.id)
+// … позже: вернуть ровно это — заказ и строки этого каскада, одной транзакцией
+const tr = await db.begin()
+try {
+  await tr.Order(ids('Order')).restore({ expect: gone }).rows()   // заказ — если это всё ещё его надгробие
+  await tr.line(ids('line')).restore({ expect: gone }).rows()     // строки этого каскада, удалённые раньше — нет
+  await tr.commit()
+} catch (e) {
+  await tr.rollback()
+  if (!(e instanceof LetopisError) || (e.code !== 'conflict' && e.code !== 'not_deleted')) throw e
+  // e.key — write.restore_stale, write.restore_id_taken или write.restore_already; причины по целям —
+  // e.detail.stale[].why — пользователю: «id занят новой записью», «после удаления меняли», «уже вернули»
+}
+```
+
+**Вернуть, что можно: `restore({ expect, partial: true })`.** Без `partial` отказ одной цели отменяет всё. С
+`partial` восстанавливаются цели, у которых совпал номер версии, а остальные не роняют операцию и приходят в том же
+ответе строками-пропусками: последняя строка цели (живая или надгробие с `$deleted`) с `$action: 'skip'` и `$why` —
+`'restored'`, `'reissued'` или `'changed'`, как `why` в таблице выше. Ответ — в порядке целей (`sort()` до глагола,
+иначе по id). Каждая цель восстанавливается под своей точкой сохранения, поэтому проигранная гонка с другим
+`restore()` тоже становится пропуском. Ошибки другого рода — `target_not_found`, `invalid_data`, права — роняют
+операцию, как без `partial`. `partial` без `expect` — `invalid_query` (`write.partial_without_expect`), и с
+`all: true` тоже. Продолжение цепочки после такого `restore()` идёт только от восстановленных; `count()` и `ids()`
+сразу после него считают и пропуски — это строки ответа глагола.
+
+```ts
+const tr = await db.begin()
+try {
+  await tr.Order(ids('Order')).restore({ expect: gone }).rows()                    // заказ — целиком или отказ
+  const lines = await tr.line(ids('line')).restore({ expect: gone, partial: true }).rows()
+  await tr.commit()
+  const skipped = lines.filter((x) => x.$action === 'skip').map((x) => ({ id: x.id, why: x.$why }))
+  // skipped — пользователю: что не вернулось и почему
+} catch (e) {
+  await tr.rollback()
+  throw e
+}
+```
+
+Ответ `delete()` не сохранили — надгробия по id: `db.line(id).withDeleted().rows()` (строки с `$deleted: true`) — и
+их в `expect`. Ни ответа, ни id — надгробия по пути и причине удаления: каскад получает `reason` глагола. Причину
+делайте **своей у каждого удаления** (с номером операции, как `#7f3a` выше): у пересозданного и снова удалённого
+объекта последнее надгробие несёт причину того, второго удаления, и под ваш отбор не попадёт. Путь теряет и другое:
+объект, чей id занял новый живой объект, по пути от прежнего конца уже не находится (последняя версия ведёт к другому),
+и пропуска `reissued` по нему не будет — человек не узнает, что он не вернулся. Срез `asOf()` на момент до удаления
+показывает, что было живо, но его строки — живые версии: их `rev` для `expect` не годится.
+
+```ts
+const ours = (await db.Order(order).withDeleted().line().withDeleted().rows())
+  .filter((x) => x.$deleted && x.reason === 'отмена A-1 #7f3a')   // строки удалённого заказа с причиной этого удаления
 ```
 
-`restore()` возвращает последний снимок удалённого объекта новой версией и перепроверяет его по текущему описанию
-класса. Восстанавливаются только цели шага, а не весь каскад. Живой объект — `not_deleted`.
+Штатные ответы `restore()` — их показывают пользователю, а не превращают в 500:
+
+| Ответ | Когда | Пользователю |
+|---|---|---|
+| пустой | id чужой, невидимый, не существует или не среди целей шага | «не найдено» |
+| `invalid_query`, ключ `write.restore_without_expect` | нет `expect` (и нет `all: true`) | — (ошибка в коде) |
+| `not_deleted`, ключ `write.not_deleted` | объект жив и не удалялся | «не удалён» |
+| `not_deleted`, ключ `write.restore_already` | объект уже восстановлен (в том числе проигранная гонка двух `restore()`); id — `err.detail.ids` | «уже восстановлено» |
+| `not_deleted`, ключ `write.restore_id_taken` | id занял новый живой объект с тем же ключом (`create()` по ключу удалённого); id — `err.detail.ids` | «место занято новой записью» |
+| `conflict`, ключ `write.restore_stale` | после этого удаления id меняли — пересоздан и удалён снова, удалён снова; причины — `err.detail.stale` | «после удаления запись меняли» |
+| строки `$action: 'skip'` | с `partial: true` вместо трёх отказов выше; причина — `$why` | что не вернулось и почему |
+| `target_not_found` | цель конца снимка удалена или не видна | сначала восстановить цель |
+| `invalid_data` | снимок не проходит нынешнее описание класса | — |
+
+- `restore()` перепроверяет описание класса, концы (цель конца жива и видна, иначе `target_not_found`), ключ и права,
+  но не бизнес-правила приложения: восстановленная связь вернёт занятость прежнему концу, даже если объект уже занят
+  другим. Гарантию даёт только ключ связи: занятость держит ключ, а не поле и не проверка. Проверка в коде перед
+  `restore()` держит правило, лишь если **все** пути создания и возврата таких связей берут в `db.begin()` одну и ту же
+  блокировку (`forUpdate()` объекта или `tr.lock(…)`) и делают ту же проверку: один путь без неё — обычный `create()`
+  связи — гарантию ломает, потому что `create()` и `restore()` берут на объекте совместимую блокировку и друг друга не
+  ждут. Связь с ключом только из одного конца (`key: ['Obj']`) база второй для того же
+  объекта не создаст (`exists`). Удалённую каскадом такую связь новая на тот же объект создаёт заново с тем же id
+  (v5 от ключа), и восстановить прежнюю уже нельзя: пока новая связь жива, `restore({ expect })` —
+  `not_deleted` (`write.restore_id_taken`); когда удалена и она — `conflict` (`write.restore_stale`); с
+  `partial: true` вместо отказа — строка-пропуск. Общие правила — «одна открытая запись на объект» и возврат по ответу
+  `delete()` — в [памятке](AGENT-CHEATSHEET.md), «Правила для любой задачи».
 
 Историю удалённого объекта журнал хранит: стереть версии одного объекта нельзя. Удаление аккаунта
 (`db.auth.purgeAccount`, [раздел 10](#10-пользователи-вход-и-права)) стирает данные и журнал его арендатора.
 
-## 8. Транзакции, батчи и деньги
+## 8. Транзакции и батчи
 
 ### Каждая операция — транзакция
 
@@ -1021,6 +1336,9 @@ try {
   библиотека о ней не знает, PostgreSQL молча отвечает `ROLLBACK` на `COMMIT`, а библиотека превращает это в ошибку
   `tx_rolled_back`.
 - Повторов внутри `db.begin()` нет: на `40P01` повторите весь блок.
+- `db.begin()` принимает только опции `{ reason }`. Функцию она не принимает и не вызывает: `db.begin(async (tr) => …)`,
+  строка, число или массив — отклонённый промис `invalid_query` (`api.begin_arg`) с подсказкой — формой выше;
+  неизвестная опция — `invalid_data` с похожими именами.
 - `lock(...ключи)` — advisory-блокировка до конца транзакции. Она защищает, только если её берут все, кто правит
   эти данные.
 
@@ -1041,74 +1359,23 @@ const results = await b.run()       // Row[][] — по массиву стро
 который поставил его в очередь (актор, арендатор, владелец, транзакция), и чужих планов `run()` не исполняет.
 Копите планы через один и тот же объект фасада.
 
-### Рецепт: кошелёк
-
-Баланс — поле `balance` хаба `Wallet` (целые копейки, `min(0)`), операции — связь `Movement` с ключом
-`[Wallet, opId]` ([раздел 4](#4-модель-данных)). Операцию не правят и не удаляют, а отменяют встречной операцией с
-новым `opId`. Ключ делает операцию идемпотентной: повтор после потери ответа получает `exists`, и рецепт сверяет,
-тот ли это запрос.
-
-<!-- run: guide -->
-```ts
-import { inc, type Db } from 'letopis'
-
-type Kind = 'topup' | 'debit' | 'adjust'
-
-/** Операция: запись Movement и приращение баланса — один план, одна транзакция. */
-async function operate(db: Db, wallet: string, opId: string, kind: 'topup' | 'debit', amount: number) {
-  try {
-    await db.Wallet(wallet).Movement().create({ opId, kind, amount })
-      .Wallet().update({ balance: inc(kind === 'topup' ? amount : -amount) }).rows()
-    return 'done'
-  } catch (e) {
-    if (e instanceof LetopisError && e.code === 'exists') return same(db, wallet, opId, kind, amount)   // повтор
-    throw e                                        // invalid_data — не хватает средств (min(0))
-  }
-}
-
-/** Отпечаток повтора: тот ли запрос уже записан под этим opId. */
-async function same(db: Db, wallet: string, opId: string, kind: Kind, value: number) {
-  const m = await db.Movement(db.idOf('Movement', { Wallet: wallet, opId })).first()
-  if (!m || m.data.kind !== kind || (kind === 'adjust' ? m.data.target : m.data.amount) !== value)
-    throw new Error(`ключ операции ${opId} уже использован другим запросом`)
-  return 'repeat'
-}
+### Значение из прочитанного и повтор операции
 
-/** Корректировка «баланс = target»: операция adjust на разницу, итог — под { rev }. */
-async function adjust(db: Db, wallet: string, opId: string, target: number) {
-  for (;;) {
-    if (await db.Movement(db.idOf('Movement', { Wallet: wallet, opId })).first()) return same(db, wallet, opId, 'adjust', target)
-    const cur = (await db.Wallet(wallet).first())!
-    try {
-      await db.Wallet(wallet).Movement().create({ opId, kind: 'adjust', amount: target - (cur.data.balance as number), target })
-        .Wallet().update({ balance: target }, { rev: cur.rev }).rows()
-      return 'done'
-    } catch (e) {
-      if (e instanceof LetopisError && e.code === 'conflict') continue     // кошелёк изменился — перечитать
-      if (e instanceof LetopisError && e.code === 'exists') return same(db, wallet, opId, 'adjust', target)
-      throw e
-    }
-  }
-}
+Новое значение, вычисленное из прочитанного, теряет параллельные правки, если его записать просто `update()`.
+Способов защиты три, и для одного объекта выбирают один:
 
-const [wallet] = await db.Customer(olga).Wallet().create({ number: 'W-1' }).rows()
-await operate(db, wallet.id, 'op-1', 'topup', 10_000)    // 'done': баланс 10 000
-await operate(db, wallet.id, 'op-1', 'topup', 10_000)    // 'repeat': повтор после потери ответа, баланс тот же
-await operate(db, wallet.id, 'op-2', 'debit', 3_000)     // баланс 7 000
-await adjust(db, wallet.id, 'op-3', 5_000)               // корректировка: adjust на −2 000, баланс 5 000
-```
-
-Тот же итог можно записать под чтением с блокировкой — без повторов при `conflict`:
+- **Приращение** — `update({ поле: inc(n) })`: база прибавляет внутри оператора, чтение не нужно, а `min(0)` в модели
+  отклоняет уход в минус (`invalid_data`, по `e.issues` — поле и правило `minimum`).
+- **Сверка версии** — `update(патч, { rev })`: строку успели изменить — `conflict`, перечитать и решить заново
+  ([«Защита от параллельной правки»](#защита-от-параллельной-правки--rev-)).
+- **Чтение с блокировкой** — `forUpdate()` внутри `db.begin()`: строка заблокирована до `commit()`, повторов нет.
 
 <!-- run: guide -->
 ```ts
-const [wallet2] = await db.Customer(olga).Wallet().create({ number: 'W-2' }).rows()
 const tx = await db.begin()
 try {
-  const w = (await tx.Wallet(wallet2).forUpdate().first())!     // строка кошелька заблокирована до commit
-  await tx.Wallet(wallet2).Movement()
-    .create({ opId: 'op-1', kind: 'adjust', amount: 6_000 - (w.data.balance as number), target: 6_000 })
-    .Wallet().update({ balance: 6_000 }).rows()
+  const locked = (await tx.Product(kettle).forUpdate().first())!          // строка заблокирована до commit
+  await tx.Product(kettle).update({ views: (locked.data.views as number) + 1 }).rows()
   await tx.commit()
 } catch (e) {
   await tx.rollback()
@@ -1116,19 +1383,19 @@ try {
 }
 ```
 
-- `inc` прибавляет внутри оператора над заблокированной строкой: параллельные списания не теряются, а `min(0)`
-  отклоняет списание сверх баланса.
-- Обычный `update({ balance: 700 })` записывает значение, а не прибавляет. Итог, вычисленный из прочитанного,
-  без `{ rev }` или `forUpdate()` теряет параллельные списания. Advisory `lock()` не спасает, если его берут не все
-  писатели. `upsert` затирает приращения.
 - `forUpdate()` — только внутри `db.begin()` (иначе `tx_required`) и только с `rows`, `first`, `ids` (иначе
   `lock_unsupported`). Строки блокируются в порядке id; строка, которая перестала подходить под условия шага, в ответ
   не попадает.
-- Для одного кошелька выберите один путь: под `{ rev }` и под `forUpdate()` кошелёк и ключ операции блокируются в
-  разном порядке, и смешение в параллельных запросах даёт `40P01`. Внутри блока с `forUpdate()` не ждите внешних
-  вызовов: кошелёк ждут все писатели (помогут `lock_timeout` и `idle_in_transaction_session_timeout`).
-- Перевод — две операции в одной `db.begin()`, кошельки правятся в порядке id: тогда взаимных блокировок нет.
-- Нехватку средств отличают от других ошибок данных по `e.issues`: поле `balance`, правило `minimum`.
+- Под `{ rev }` и под `forUpdate()` объект и ключи блокируются в разном порядке: смешение двух путей в параллельных
+  запросах одного объекта даёт `40P01`. Внутри блока с `forUpdate()` не ждите внешних вызовов: строку ждут все
+  писатели (помогут `lock_timeout` и `idle_in_transaction_session_timeout`).
+- Несколько объектов в одной `db.begin()` правьте в порядке id: тогда взаимных блокировок нет.
+- Обычный `update({ поле: значение })` записывает значение, а не прибавляет; `upsert` затирает приращения; advisory
+  `lock()` не спасает, если его берут не все писатели.
+- **Повтор операции.** Операцию, которую нельзя выполнить дважды, записывайте связью с ключом из объекта и номера
+  операции (`key: ['Объект', 'opId']`) вместе с приращением одним планом: повтор после потери ответа (`commit_unknown`,
+  обрыв связи) получает `exists` и ничего не меняет. Отменяют такую операцию встречной операцией с новым номером, а не
+  правкой и не удалением.
 
 ## 9. Массовая загрузка
 
@@ -1297,7 +1564,7 @@ const failed = await svc.auth.verifyPassword({ identifier: 'boris@lutik.ru', pas
 
 - Пароль хранится хэшем scrypt; проверяет его сервис, время ответа для несуществующего логина выровнено.
 - Идентификатор сравнивается без учёта регистра: `Anna@Shop.ru` и `anna@shop.ru` — один вход.
-- Смена пароля гасит остальные сессии аккаунта (`keepCurrent` — оставить текущую).
+- Смена пароля гасит остальные сессии аккаунта; текущая остаётся, `keepCurrent: false` гасит и её.
 - По умолчанию вход — только по подтверждённому креду, иначе `null`; `requireConfirmed: false` пускает и по
   неподтверждённому. Подтверждает кред сервис: `confirmed: true` в `setPassword` или `setFlags`.
 - Второй фактор — опция `totp`: `verifyPassword({ identifier, password, totp })` после верного пароля проверяет код
@@ -1359,12 +1626,26 @@ await boris.close()
 Токен — 256 случайных бит; база хранит только его sha256. Срок по умолчанию — 7 суток. `refresh()` продлевает
 текущую сессию: новый срок отсчитывается от текущего момента, но не больше срока, выданного при входе; возвращает
 он новое время истечения. `connect()` продлевает сессию сам раз в минуту работы (`refreshSession`), поэтому сессия,
-которой пользуются, не истекает: срок — это время простоя. `revoke()` — выход, `revokeAll()` — выход везде.
+которой пользуются, не истекает: срок — это время простоя. `revoke()` — выход: гасит сессию этого подключения;
+`revoke(token)` — выход пользователя по токену его сессии (ниже); `revokeAll(account?)` — выход везде, то есть все
+сессии **одного** аккаунта. Общего вызова «погасить все сессии установки» нет: при утечке или после восстановления
+копии на чужом стенде — остановить процессы приложения и от суперпользователя или роли-владельца выполнить
+`update "v2.имя".secret set deleted_at = clock_timestamp() where kind = 'SESSION' and deleted_at is null` (ключи API —
+`kind in ('APIKEY', 'KEYSECRET')` или `revokeCredential(id)`); сигнала этот запрос не шлёт, поэтому процессы
+перезапускают.
 Сессии гаснут при отключении аккаунта, смене пароля, удалении креда и удалении аккаунта. Удаление креда гасит
 остальные сессии аккаунта, а отзыв ключа API или пары «ключ + секрет» — только сессии, открытые этим ключом (и
 старые сессии того же вида входа без отметки ключа); текущая сессия остаётся, если не передать
 `keepCurrent: false`.
 
+`apiKey`, `service` или `token`, переданные со значением `null`, пустой строкой или не строкой, `connect()` отклоняет
+сразу — `invalid_data` (`api.connect_empty_credential`); `undefined` значит «опции нет» — подключение без сессии, и
+отказ `no_session` придёт на первом вызове. Поэтому ключ из переменной окружения проверяйте до `connect()`.
+
+`connect({ token })` с токеном, который уже не даёт сессии (погашен `revoke`, истёк, неверен), подключения не создаёт:
+его промис отклоняется с `no_session` (`api.token_not_active`, «нет действующей сессии: токен погашен, истёк или
+неверен»), пул закрывается. Пользователь входит заново.
+
 Подключение с постоянным токеном (`connect({ token })`), которым не пользовались дольше срока сессии, остаётся без
 сессии: истёкшую сессию продление не возвращает, а новый токен подключение само не берёт. После простоя дольше минуты
 подключение до операции продлевает сессию и узнаёт, жива ли она: истёкшая — `no_session` на любую операцию, и
@@ -1384,6 +1665,18 @@ await boris.close()
 чтение по погашенной сессии ошибки не даёт, ответы просто пустые. Вызывает метод сервис или системный администратор
 (право `auth.session`); пользователю отвечают `acl_denied`.
 
+Выход в веб-сервисе — `svc.auth.revoke(token)` с токеном из cookie: сервис гасит сессию пользователя, не подключаясь
+по ней. Ответ — `true`, если сессия погашена, и `false`, если токен неверный, сессия уже погашена или истекла (причина
+не различается). Право то же — `auth.session`, без него `acl_denied`. Погашенная сессия шлёт сигнал `session:…`, и
+процессы сбрасывают кэш её ответов. `svc.auth.revoke()` без аргумента погасил бы сессию самого сервиса:
+
+```ts
+// POST /logout — токен пользователя в cookie
+const token = req.cookies.session
+if (token) await svc.auth.revoke(token)   // true — вышел; false — сессии уже не было
+res.clearCookie('session')
+```
+
 ### Работа в другом арендаторе
 
 Сервис действует от имени пользователя через `svc.as(account, { tenant, owner })`. База проверяет право сервиса
@@ -1396,13 +1689,68 @@ await boris.close()
 
 <!-- run: guide -->
 ```ts
-const mine = await anna.auth.tenants()     // [{ tenant, roles }]: собственный арендатор и магазин по членству
+const mine = await anna.auth.tenants()     // [{ tenant, roles, name, personal }]: собственный арендатор и магазин
 await anna.auth.switch(SHOP)               // арендатор сессии — магазин
 ```
 
-`auth.tenants()` отдаёт и собственный арендатор пользователя: первым элементом, с `tenant`, равным id его аккаунта, и
-`roles: ['owner']`. За ним идут арендаторы по членству с ролями членства. Нужны только арендаторы по членству —
-отбросьте элемент с id аккаунта (`login.account` у `verifyPassword`, `user` у `createTenant`).
+`auth.tenants()` отдаёт арендаторов аккаунта сессии: `{ tenant, roles, name, personal }`. Первым идёт собственный
+арендатор пользователя — `tenant` равен id его аккаунта, `roles: ['owner']`, `personal: true`, `name` — имя
+пользователя. За ним — арендаторы по членству (`personal: false`) с ролями членства, по id. `name` — имя аккаунта
+арендатора: то, что передали в `createTenant({ name })` или `up({ tenant: { name } })`; у аккаунта без имени — `null`.
+Нужны только арендаторы по членству — `filter((t) => !t.personal)`.
+
+Сервис узнаёт арендаторов пользователя, не открывая подключения по его токену: от имени пользователя без `tenant`
+(`svc.as(account)` работает в его личном арендаторе) — тот же `auth.tenants()`. Так после входа выбирают, куда
+пустить пользователя:
+
+```ts
+const ok = await svc.auth.verifyPassword({ identifier, password })
+if (!ok) return 'неверный логин или пароль'
+const shops = (await (await svc.as(ok.account)).auth.tenants()).filter((t) => !t.personal)
+if (!shops.length) return 'вы не состоите ни в одном магазине'
+// несколько — список shops.map((t) => t.name) пользователю на выбор; выбранный — в его сессии:
+const work = await svc.as(ok.account, { tenant: shops[0].tenant })
+```
+
+Сессия, открытая входом (`verifyPassword`, `sessionFor`), `svc.as(account)` без `tenant` и
+`connect({ token })` до `auth.switch()` работают в **собственном** арендаторе пользователя. Классы, которые
+`syncModels` записал в арендатор магазина, там не видны: шаг по такому классу — `invalid_class: класс или роль …
+не найдены`. Поэтому член арендатора работает так: сервис — `svc.as(login.account, { tenant: SHOP })`, своё
+подключение по токену — `auth.switch(SHOP)`; `db.tenant` показывает, где сессия. `auth.switch()` меняет арендатора
+самой сессии: токен и дальше работает в выбранном арендаторе. Нет членства — `tenant_denied`.
+
+Название арендатора пользователь получает из `auth.tenants()` (`name`); саму строку `Account` арендатора он не
+видит — видна только своя (`db.Account(SHOP).first()` у члена магазина — `null`). Название, которое меняется в
+интерфейсе приложения, храните в данных арендатора — например, хабом `Shop` с полем `name`.
+
+### Веб-сервис: одно подключение и безопасность
+
+- **Одно подключение сервиса на процесс.** Сервис держит одно подключение по ключу (`connect({ apiKey })`) и на каждый
+  запрос берёт фасад `svc.as(account, { tenant })` — тот же пул. `connect({ token })` на каждый вход открывает
+  отдельный пул (`max`, по умолчанию 10 соединений) на пользователя: несколько десятков входов исчерпают соединения
+  PostgreSQL. `close()` у фасада `as()` ничего не делает; закрывают `svc` при остановке процесса.
+- **Арендатор — только из серверной сессии.** В начале запроса — `svc.auth.session(token)` по токену из cookie
+  (`null` — не вошёл: 401, никаких данных); арендатор — из конфигурации сервера или из выбора, сохранённого на сервере
+  при входе, и никогда из параметра запроса (`?club=`, тело, заголовок). Нет членства — `svc.as()` отвечает
+  `tenant_denied` (403).
+- **Экранирование.** Данные из базы, вставленные в HTML, экранируют все пять символов `& < > " '` (или пишут через
+  `textContent`), а обработчики событий (`onclick="…"`) из данных не строят: id — в атрибуте `data-*`, обработчик —
+  `addEventListener`.
+- **Ключ сервиса** выдаётся один раз ([«Сервис и ключи API»](#сервис-и-ключи-api)): храните его в файле с правами
+  только владельца (`chmod 600`) или в хранилище секретов, файл — в `.gitignore`; в репозиторий и клиенту он не
+  попадает. Свой ключ заранее — `up({ serviceKey })`.
+
+```ts
+const svc = await connect({ dsn: APP, schema: 'v2.shop',
+  apiKey: readFileSync('/etc/shop/service.key', 'utf8').trim() })   // один раз на процесс
+async function userDb(token: string | undefined) {                   // в начале каждого запроса
+  const s = token ? await svc.auth.session(token) : null
+  if (!s) return null                                                 // 401
+  return svc.as(s.account, { tenant: SHOP })                          // арендатор — с сервера; нет членства — tenant_denied
+}
+const esc = (v: string) => v.replace(/[&<>"']/g, (c) =>
+  ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!)
+```
 
 ### Права
 
@@ -1444,10 +1792,10 @@ await anna.auth.switch(SHOP)               // арендатор сессии
 
 <!-- run: guide -->
 ```ts
-const pg2 = postgres(ADMIN)
-const OLEG = (await createTenant(pg2, r.schema, {          // тот же магазин: создаётся только пользователь
+const admin2 = postgres(ADMIN)
+const OLEG = (await createTenant(admin2, r.schema, {          // тот же магазин: создаётся только пользователь
   name: 'Ромашка', user: { name: 'Олег', login: 'oleg@shop.ru', password: 'Олег-2026!' } })).user!
-await pg2.end()
+await admin2.end()
 await db.acl.roles(OLEG, ['staff'])                         // роли Олега в текущем арендаторе (строка member)
 
 await db.acl.deny({ role: 'staff', delete: 'Product' })     // вес 50 — сильнее «можно всё» (10)
@@ -1523,16 +1871,16 @@ await db.acl.revoke({ everyone: true, read: '*', write: '*', delete: '*' })
 аккаунтов обёртка пишет своей группой `everyone:ACCOUNT`. Так же — право всем аккаунтам на отдельный класс:
 `db.acl.grant({ everyone: true, read: 'Catalog' })`.
 
-Не заводить. `createTenant(sql, schema, { name, grantAll: false, user })` и `up({ tenant: { name, grantAll: false, user
+Не заводить. `createTenant(admin, schema, { name, grantAll: false, user })` и `up({ tenant: { name, grantAll: false, user
 } })` заводят арендатора без правил. У его участников, в том числе у первого пользователя, прав нет — ни на данные, ни
 на запись правил. Классы и правила такого арендатора пишет администраторское подключение с сессией его пользователя:
 RLS на нём не действует, а строки идут в арендатор сессии.
 
 ```ts
-const pg = postgres(ADMIN)
-const t = await createTenant(pg, r.schema, { name: 'Склад', grantAll: false,
+const admin = postgres(ADMIN)
+const t = await createTenant(admin, r.schema, { name: 'Склад', grantAll: false,
   user: { name: 'Ирина', login: 'irina@stock.ru', password: 'Склад-2026!', roles: ['manager'] } })
-await pg.end()
+await admin.end()
 const adm = await connect({ dsn: ADMIN, schema: r.schema, token: t.token, allowBypassRls: true })
 await syncModels(adm, [Product], { apply: true })
 await adm.acl.grant({ role: 'manager', read: 'Product', write: 'Product', delete: 'Product' })
@@ -1550,8 +1898,8 @@ await adm.close()
 арендаторах переходит этим арендаторам, сессии гаснут, креды удаляются. Владелец может стереть и арендатора, в
 котором сейчас работает: его сессия вернётся в личный арендатор.
 
-Системный администратор может удалить и саму строку аккаунта — `db.Account(id).delete({ confirm: true })` в
-арендаторе System; данные арендатора аккаунта при этом остаются. Любой путь сразу стирает строки аккаунта в `secret`:
+Системный администратор может удалить и саму строку аккаунта — по превью, `db.Account(id).delete({ confirm: true,
+expect: превью })`, в арендаторе System; данные арендатора аккаунта при этом остаются. Любой путь сразу стирает строки аккаунта в `secret`:
 сессии, хэши паролей и ключей, секреты TOTP, внешние учётные записи (внешний ключ `secret.account` с каскадом).
 Сессии гаснут до этого с сигналом, и процессы сбрасывают кэш ответов этих сессий. Аккаунт System
 не удаляется (`acl_denied`): ему принадлежат служебные строки установки в `secret`.
@@ -1570,10 +1918,23 @@ const versions = await db.Product(kettle).versions()              // все ве
 `delete({ confirm, reason })` и других), для всех операций блока — `db.begin({ reason })` и
 `db.batch(имя, { reason })`; сырой SQL — настройка `letopis.reason` транзакции. Версия удаления — с `$deleted`.
 
-Без `sort()` версии идут по id и номеру версии. `sort()` задаёт порядок и версиям, а
-`limit()` ограничивает их в самом запросе: `db.Product(kettle).sort('at', 'desc').limit(5).versions()` — пять
+Версия — строка той же формы, что строка ответа ([«Строка ответа»](#строка-ответа)), но со снимком на свою версию:
+`rev` — номер версии, `op` — вид операции, `links` и `data` — концы и поля после этой операции (у версии удаления —
+последний снимок объекта), `at`, `author`, а если есть — `agent` и `reason`; у версии удаления ещё `$deleted: true`.
+Без `sort()` версии идут по id и номеру версии (по возрастанию: первой — `create`). `sort()` задаёт порядок и версиям,
+а `limit()` ограничивает их в самом запросе: `db.Product(kettle).sort('at', 'desc').limit(5).versions()` — пять
 последних версий, новые первыми.
 
+Шаг с явными id находит и удалённые объекты: `db.Product(id).versions()` отдаёт историю удалённого товара вместе с
+версией удаления, `withDeleted()` для этого не нужен. Шаг без id (`db.Product().versions()`, переход по пути) отдаёт
+версии **только живых** объектов, с удалёнными — `withDeleted()` этого шага. Так, строки удалённого заказа ушли
+каскадом, и `db.Product(p).line().versions()` их не покажет, а `db.Product(p).line().withDeleted().versions()` или
+`versions()` по id строки — покажут: концы — `links` версии, удаление — версия удаления, причина — `reason`.
+
+`versions()` — терминал: отдаёт промис строк версий. Модификаторы ставят до него
+(`db.Product(kettle).sort('at', 'desc').limit(5).versions()`), а метод цепочки у его результата —
+`versions().rows()`, `.sort()`, `.limit()` — `invalid_query` (`api.versions_terminal`).
+
 Журнал хранит каждую версию: прореживания и обрезки истории нет. Классу, чья история не нужна, — `history: false`
 ([«Настройки класса»](#настройки-класса)).
 
@@ -1598,6 +1959,28 @@ const assortment = await db.Shop(shop).Product().asOf(createdAt).rows()
 const withGone = await db.Customer().withDeleted().rows()   // живые и удалённые; у удалённых $deleted: true
 ```
 
+`withDeleted()` — модификатор своего шага, как `exact()`: удалённые находит шаг, после которого он стоит, а шаги без
+него идут по живым строкам. Удалённый объект приходит надгробием — своей последней версией, версией удаления, — с
+`$deleted: true`.
+
+| Цепочка | Что находит |
+|---|---|
+| `db.Order(o).line().withDeleted()` | живые и удалённые строки живого заказа |
+| `db.Order(o).withDeleted().line().withDeleted()` | живые и удалённые строки заказа, даже если сам заказ удалён |
+| `db.Order(o).withDeleted().line()` | только **живые** строки (заказ — с удалёнными); выводит предупреждение `api.with_deleted_step` |
+| `db.Order(o).line().Product().withDeleted()` | товары, в том числе удалённые, живых строк живого заказа |
+
+Путь через удалённый узел читают одной цепочкой — `withDeleted()` у каждого шага, который может быть удалён:
+`db.Customer(c).Order().withDeleted().line().withDeleted()` — строки всех заказов клиента, в том числе удалённых. В
+цепочке записи `withDeleted()` — только перед `restore()`: у других глаголов — `invalid_query`. В инструменте MCP
+`letopis_query` опция `withDeleted` относится к последнему шагу.
+
+`withDeleted()` отдаёт по каждому id его последнюю версию. Если id надгробия занял новый объект (`create()` по ключу
+удалённого), шаг находит живой новый объект без `$deleted`, а прежнего надгробия среди строк нет; путь от прежнего
+владельца (`db.Customer(c).withDeleted().Order().withDeleted()`) такой объект не находит, если его последняя версия
+ведёт к другому. Прежнее надгробие видно только в версиях — `db.Order(id).versions()`; вернуть его нельзя: пока
+новый объект жив, `restore({ expect })` — `not_deleted` (`write.restore_id_taken`) ([«Восстановить: `restore`»](#восстановить-restore)).
+
 ## 12. Подписка на изменения и кэш
 
 ### Подписка
@@ -1675,7 +2058,7 @@ const report = await adm.maintain()     // { sessions, codes, queue, skipped }
 вызовом), а ещё проверяет очередь сигналов PostgreSQL: заполнение больше половины — предупреждение. Журнал
 `maintain()` не трогает. Строки удалённого аккаунта ждать не нужно: их стирает само удаление ([«Удалить
 аккаунт»](#удалить-аккаунт)). Вызывать может системный администратор, роль с правом `letopis.maintain` или
-администраторское подключение. Запускает его внешний планировщик (`letopis maintain`) или сама библиотека:
+администраторское подключение; остальным — `acl_denied` (`sql-time.maintain_denied`), в том числе сервису по ключу. Запускает его внешний планировщик (`letopis maintain`) или сама библиотека:
 `connect({ maintain: '1h' })`. Интервал — число миллисекунд или строка (`'500ms'`, `'30s'`, `'15m'`, `'1h'`, `'1d'`)
 от 1 мс до 2³¹−1 мс (около 24 суток): другое значение, в том числе ноль, отрицательное или `NaN`, `connect()`
 отклоняет с `invalid_data`, не открывая соединений. `close()` ждёт идущий по расписанию запуск. Из нескольких
@@ -1765,7 +2148,8 @@ PostgreSQL у ошибки не из letopis), если они есть. Пар
 `rev` прочитанной версии: чужая версия — `conflict`, потерянной правки нет. `delete` без `confirm` возвращает превью
 каскада и код операции: `{ preview, operation }`. С `confirm: true` удаление подтверждает человек в клиенте через
 elicitation (в ревизии протокола 2025 — запросом клиенту, в 2026-07-28 — ответом `input_required`), подтверждение
-привязано к хэшу операции, а ответ — `{ deleted, operation }`. В ревизии 2026-07-28 подпись `requestState`, с которой
+привязано к хэшу операции, а ответ — `{ deleted, operation }`. Удаляет инструмент ровно показанное: превью, построенное
+до подтверждения, идёт в `expect`, и если данные изменились — `conflict` (`write.preview_changed`), ничего не удалено. В ревизии 2026-07-28 подпись `requestState`, с которой
 клиент повторяет вызов, привязана ещё к пользователю сервера и действует 10 минут: подпись сервера другого
 пользователя и устаревшая — отказ `confirmation_required`. Окно подтверждения показывает каноническое имя класса и
 id целей (первые 10, дальше — «и ещё K»); алиас и `meta` класса пишет арендатор, поэтому в окно они не попадают. Код
@@ -1803,7 +2187,9 @@ id целей (первые 10, дальше — «и ещё K»); алиас и
 **HTTP.** Встроенного HTTP-сервера нет. `createMcpServer(db, { write, maxRows, maxBytes })` из `letopis/mcp` отдаёт
 сервер MCP, а приложение подключает его к своему обработчику `createMcpHandler` из SDK со своей авторизацией
 OAuth 2.1: токен запроса проверяет приложение и находит по нему пользователя letopis. Подключение — сессия
-пользователя (`connect({ token })`) или фасад `svc.as(пользователь)`: ключ сервиса остаётся в процессе приложения.
+пользователя в арендаторе приложения (`connect({ token })` после `auth.switch(tenant)`) или фасад
+`svc.as(пользователь, { tenant })`: ключ сервиса остаётся в процессе приложения. Без `{ tenant }` фасад работает в
+личном арендаторе пользователя, и классов приложения агент не увидит.
 Подключение в обход RLS получает отказ `bypass_rls`, корень сервиса без `as()` и подключение без сессии —
 `user_session_required`, фасад явной транзакции `db.begin()` — `invalid_query`. Сессию в арендаторе System — так
 работает системный администратор: его роль `admin` даёт права на аккаунты, членства и правила установки — сервер тоже
@@ -1848,6 +2234,22 @@ const [{ n }] = await db.sql`select count(*)::int as n from "v2.shop".entity whe
 сериализации запрос и `fn` повторяются до трёх раз, поэтому `fn` должна выдерживать повтор. Писать сырым SQL тоже
 можно — те же триггеры проверят данные, а функции базы `merge` и `inc` доступны приложению.
 
+Ошибки базы `db.sql`, `db.transaction(fn)` и `tr.sql` в `db.begin()` приходят так же, как у цепочек: с кодом letopis
+(`LT…` — по таблице [«Ошибки»](#15-ошибки)), а прочие — как ошибка postgres.js с SQLSTATE в `err.code`. Исключение —
+значение не того типа, SQLSTATE `22P02` (`'42'::uuid`, `'abc'::int`): оно приходит `LetopisError` с кодом
+`invalid_query` (ключ `api.db_bad_value`), текст называет значение — `letopis: invalid_query: значение не того типа:
+invalid input syntax for type uuid: "42"`, а исходная ошибка PostgreSQL — в `err.cause` (`err.cause.code === '22P02'`).
+Ловите её по `err.code === 'invalid_query'`, а не по SQLSTATE:
+
+```ts
+try {
+  await db.sql`select * from "v2.shop".entity where id = ${input}::uuid`
+} catch (e) {
+  if (!(e instanceof LetopisError) || e.code !== 'invalid_query') throw e
+  // e.key === 'api.db_bad_value'; (e.cause as { code: string }).code === '22P02'
+}
+```
+
 ### Командная строка
 
 ```sh
@@ -1858,6 +2260,7 @@ letopis load <файлы…> --dsn <строка> --schema <v2.имя> (--token
 letopis maintain --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>]
 letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пользователя> [--write]
   (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)
+# у любой команды: --log[=debug|info|warn|error] — события JSON-строками в stderr (без флага — LETOPIS_LOG)
 ```
 
 `letopis types` строит результат по классам сессии, поэтому без действующей сессии (токен истёк, погашен, неверен или
@@ -1870,12 +2273,112 @@ letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пол
 
 ### Наблюдение
 
+- Журнал событий — `connect({ log })` или `LETOPIS_LOG` ([«Логирование»](#логирование)).
 - `connect({ onQuery, slowMs })`: хук получает на каждый запрос цепочки режим, классы, длительность, число строк и
   признак медленного запроса; без хука медленный запрос печатает предупреждение.
 - `sub.lag()` — отставание подписки; отчёт `maintain()` — заполнение очереди сигналов.
 - Горячие цели ссылок (организация, на которую ссылается почти всё) копят блокировки `for key share` и MultiXact,
   как при обычных внешних ключах. Это стоит мониторить.
 
+### Логирование
+
+letopis пишет журнал событий приложения: что прочитано и записано, что удалено и восстановлено, какие были ошибки,
+кто вошёл. По нему видно, что удаление прошло по показанному превью, а восстановление вернуло то, что ушло. Журнал
+выключен, пока его не включили опцией или переменной окружения.
+
+**Опции.** `connect()` и `up()` принимают одни и те же:
+
+| Опция | Что делает |
+|---|---|
+| `log` | куда писать: функция `(event) => void` или объект с методами `debug`, `info`, `warn`, `error` (`console`, pino и подобные) — вызывается `logger[level](event, event.event)`; нет метода уровня — `logger.log`, нет и его — событие пропускается |
+| `logLevel` | порог: `'debug'`, `'info'` (по умолчанию), `'warn'`, `'error'` или `'off'`; событие ниже порога не собирается |
+| `redact` | ещё имена полей (`string[]`, без учёта регистра), значения которых заменяются на `'***'` в любом месте `detail` |
+
+```ts
+import pino from 'pino'
+const svc = await connect({ dsn: APP, schema: 'v2.shop', apiKey: SERVICE_KEY,
+  log: pino(), logLevel: 'info', redact: ['phone', 'email'] })
+const solo = await connect({ dsn: APP, schema: 'v2.shop', token, log: (e) => audit.push(e) })   // своя функция
+```
+
+Подключения из `db.as()` и `svc.as()`, `db.begin()`, `db.transaction()`, батч и `auth.switch()` пишут тем же журналом
+с тем же порогом и `redact`; в их событиях свои `tenant`, `account` и `tx`. Исключение внутри логгера проглатывается:
+операция из-за журнала не ломается. Хук `onQuery` работает как прежде, а каждый запрос SQL — ещё и событие `sql`.
+
+**Переменная окружения и командная строка.** `LETOPIS_LOG=<уровень>` (`debug`, `info`, `warn`, `error`, `off`;
+`1` и `true` — то же, что `info`): если `log` не передан, события пишутся в stderr JSON-строками, одна строка — одно
+событие. Если `log` передан без `logLevel`, порог берётся из `LETOPIS_LOG`, а без неё — `info`. Без `log` и без
+`LETOPIS_LOG` журнала нет. Команды CLI принимают `--log[=уровень]` (`--log` без значения — `info`), события — в stderr;
+без флага действует `LETOPIS_LOG`.
+
+```sh
+LETOPIS_LOG=info node app.js 2>> letopis.log
+npx letopis maintain --dsn "$ADMIN" --schema v2.shop --api-key "$KEY" --log=debug
+```
+
+**Событие** — объект:
+
+| Поле | Что значит |
+|---|---|
+| `ts`, `level`, `event` | время ISO, уровень (`debug`, `info`, `warn`, `error`), имя события |
+| `op`, `ms` | операция (`rows`, `first`, `create`, `delete`, `login` …) и длительность в миллисекундах |
+| `tenant`, `account`, `tx` | арендатор и аккаунт сессии; метка транзакции, если операция в `db.begin()`, `transaction()` или батче |
+| `chain`, `rows` | цепочка в читаемом виде (`Shop({"name":"Ромашка"}).Product.rows()`) и число строк результата или затронутых |
+| `code`, `key`, `msg` | код и ключ каталога ошибки или предупреждения, текст |
+| `detail` | подробности события (секреты замаскированы) |
+| `cause` | у события `error` — исходная ошибка: `{ name, message, code }` |
+
+**Маскировка.** Без настройки заменяются на `'***'` на любой глубине `detail`: значения полей с паролями, токенами,
+ключами, секретами и кредами — в том числе `password`, `pass`, `passwd`, `pwd`, `passphrase`, `secret`, `token`,
+`serviceKey`, `apiKey`, `api_key`, `credential`, `authorization`, `cookie`, `hash`, `material`, `totp`, `otp`;
+учётные данные в строке подключения (`postgres://***@host/db` — скрыт и пользователь); пароль в тексте SQL
+(`password '…'`). `redact` добавляет свои имена полей (персональные данные и т. п.).
+
+Не пишутся никогда: значения параметров SQL (у событий `sql` и `raw` — только их число); текст, `DETAIL`, `WHERE`,
+`HINT` и внутренний запрос ошибки PostgreSQL — в событии только SQLSTATE и имена ограничения, таблицы, колонки, схемы,
+типа и функции, а вместо текста — фраза «ошибка PostgreSQL <SQLSTATE>»; поле `data` строк в `detail` ошибки (превью,
+снимки отказа `restore`) — `'***'`; значение аргумента в тексте ошибки letopis (`query.bad_uuid`, `api.db_bad_value`
+и подобные) — `'***'`.
+
+Пишутся как есть — учитывайте это: значения фильтров в `chain` (`Shop({"name":"Ромашка"})`; у записи данные —
+только именами полей), поэтому фильтр по персональным полям — `redact: ['email', …]`; тексты исключений кода
+приложения (с маскировкой паролей). Объект ошибки, который получает приложение (`err.message`, `err.cause`), журнал
+не меняет: что из него логировать самому, решает приложение.
+
+**Транзакции и фиксация.** Событие записи вне `db.begin()` пишется после фиксации своей транзакции и само доказывает
+её. Внутри `db.begin()` события несут `tx` и пишутся, когда оператор выполнен, до `COMMIT`: `begin → delete →
+rollback` оставит событие `delete`, а строки — на месте. Фиксацию такой записи доказывает только `tx.commit` с тем же
+`tx`; `tx.rollback` с ним — запись отменена; `commit_unknown` — исход неизвестен (повтор с тем же ключом).
+
+**Основные события.** Полный каталог с уровнями и описаниями — `lib/src/messages/log.ts` (`LOG_EVENTS`).
+
+| Событие | Уровень | Когда | Главное в событии |
+|---|---|---|---|
+| `connect`, `close` | info | подключение готово, закрыто | `ms`; `detail.schema` |
+| `up`, `migrate` | info | `up()` завершён; `up()` обновил ревизию схемы | `detail`: `schema`, `created`, `revision`; `from`, `to` |
+| `sync` | info | `syncModels()` | итог: созданные и изменённые классы |
+| `read` | debug | терминал чтения | `op`, `chain`, `rows`, `ms`, `tx` |
+| `cache.hit`, `cache.miss` | debug | ответ из кэша результатов; промах | `chain`, `rows` |
+| `write` | info | глагол записи, план батча, загрузка | `op`, `chain`, `rows`, `ms`, `tx` |
+| `delete.preview` | debug | `delete()` без `confirm` | `rows`; `detail`: сколько `delete`, `unset`, `restrict` |
+| `delete` | info | удаление выполнено | `chain`, `rows`; `detail.expect` — сколько строк превью сверено (`false` — без сверки, `all: true`) |
+| `restore` | info | восстановление выполнено | `chain`, `rows`; `detail`: `expect`, `partial`, `skipped: [{ id, why }]` |
+| `tx.begin` | debug | открыта транзакция | `tx` |
+| `tx.commit` | info, если в транзакции была запись, иначе debug | зафиксирована транзакция | `tx`, `ms`; `detail.writes` — число операций записи |
+| `tx.rollback` | info | откат | `detail`: `reason` (`explicit` или `error`), `writes` |
+| `tx.retry` | warn | повтор после `40001`, `40P01` или конфликта журнала | `detail`: `attempt`, `code` |
+| `auth.login`, `auth.logout`, `auth.revoke`, `auth.switch` | info | вход, выход, отзыв сессии, смена арендатора | `account`, `tenant` |
+| `watch.start`, `watch.stop` | info | подписка открыта, закрыта | `detail.classes` |
+| `signal` | debug | получен сигнал базы | `detail.channel` |
+| `maintain` | info | `maintain()` | итог обслуживания |
+| `warning` | warn | любое предупреждение letopis (`api.step_undefined_filter` и другие) | `key`, `msg` |
+| `error` | warn — штатный отказ (`exists`, `conflict`, `target_not_found`, `not_deleted`, `delete_restricted`, `acl_denied`, `tenant_denied`, `no_session`, `invalid_data` с `err.issues` и другие); error — прочее | каждая ошибка при выходе из операции | `op`, `chain`, `code`, `key`, `msg`, `detail`, `cause` |
+| `sql` | debug | каждый запрос SQL | `ms`, `rows`, `tx`; `detail`: текст (до 2000 знаков), число параметров |
+
+Ещё есть, среди прочих: `auth.as` (debug, `as()`), `auth.fail` (warn, неудачный вход), `acl.change` (правка прав
+`db.acl`), `tenant.create`, `account.purge`, `load` (итог загрузчика), `lock` (debug, `db.lock()`), `mcp.call` (вызов
+инструмента MCP).
+
 ### Пулы соединений и PgBouncer
 
 С PgBouncer в режиме транзакций `LISTEN` недоступен: `connect({ listen: false })`. Тогда реестр перечитывается через
@@ -1892,16 +2395,16 @@ await svc.close()      // и подключения, полученные чер
 
 ## 14. Справочник API
 
-Полный машинный список экспортов, методов и текстов ошибок — `docs/api-contract.json` в репозитории.
+Полный машинный список экспортов, методов и текстов ошибок — `lib/api-contract.json` в репозитории.
 
 ### Экспорты пакета
 
 | Точка входа | Что экспортирует |
 |---|---|
-| `letopis` | `connect`, `loose`, `up`, `createTenant`; операторы `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `inList`, `like`, `ilike`, `starts`, `ends`, `has`, `hasAny`, `hasAll`, `exists`, `isNull`, `not`, `or`, `isOp`; `inc`, `isInc`, `cursorOf`; `idOf`, `uuidv5`, `v5Name`, `v5Id`; `LetopisError`, `ValidationError`, `fromDbError`; `syncModels`, `generateTypes`, `schemaToTs`; `compileValidator`, `applyDefaults`, `Registry`; `totpCode`, `hashPassword`, `verifyHash`; константы `DDL_REVISION`, `RESERVED_CLASS_NAMES`, `CHAIN_METHODS`, `DB_METHODS`; типы `Db`, `DbTx`, `TypedDb`, `SystemModels`, `Chain`, `Row`, `Filter`, `Cursor`, `ConnectOptions`, `UpOptions`, `LoadOptions`, `LoadReport`, `WatchOptions`, `WatchEvent`, `AuthApi`, `AclApi`, `MaintainReport` и другие |
+| `letopis` | `connect`, `loose`, `up`, `createTenant`; операторы `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `inList`, `like`, `ilike`, `starts`, `ends`, `has`, `hasAny`, `hasAll`, `exists`, `isNull`, `not`, `or`, `isOp`; `inc`, `isInc`, `cursorOf`; `idOf`, `uuidv5`, `v5Name`, `v5Id`; `LetopisError`, `ValidationError`, `fromDbError`; `syncModels`, `generateTypes`, `schemaToTs`; `compileValidator`, `applyDefaults`, `Registry`; `totpCode`, `hashPassword`, `verifyHash`; константы `DDL_REVISION`, `RESERVED_CLASS_NAMES`, `CHAIN_METHODS`, `DB_METHODS`; типы `Db`, `DbTx`, `TypedDb`, `SystemModels`, `Chain`, `Row`, `Expected` (строка `expect`: `{ id, rev, $action? }`), `DeleteOptions`, `RestoreOptions`, `Filter`, `Cursor`, `ConnectOptions`, `UpOptions`, `LoadOptions`, `LoadReport`, `WatchOptions`, `WatchEvent`, `AuthApi`, `AclApi`, `MaintainReport` и другие |
 | `letopis/model` | `hub`, `link`, `one`, `many`, `End`, типы `Infer`, `InferLinks`, `Model`, `ClassDef`, `ClassMeta`; `normalizeSchema`, `translatePattern`, тип `JsonSchema` |
 | `letopis/mcp` | `createMcpServer(db, опции)` — сервер MCP SDK с инструментами letopis; тип `McpOptions`: `write` — инструмент `letopis_write` (по умолчанию его нет), `maxRows` — строк в ответе (100, от 1 до 10 000), `maxBytes` — байт в ответе (50 000, от 1 000 до 50 000 000); `allowAclWrite` — `letopis_write` пишет и классы прав (по умолчанию — `acl_denied`); `allowSystemAdmin` — сессия в арендаторе System (по умолчанию — `user_session_required`); значение вне пределов — `invalid_data`. Нужен пакет `@modelcontextprotocol/server` ([раздел 13](#агенты-и-mcp)) |
-| CLI `letopis` | `sync`, `types`, `load`, `maintain`, `mcp` ([раздел 13](#13-эксплуатация)); у `mcp` — `--dsn`, `--schema`, `--token` (или `LETOPIS_DSN`, `LETOPIS_SCHEMA`, `LETOPIS_TOKEN`) и `--write` |
+| CLI `letopis` | `sync`, `types`, `load`, `maintain`, `mcp` ([раздел 13](#13-эксплуатация)); у всех — `--log[=уровень]` ([«Логирование»](#логирование)); у `mcp` — `--dsn`, `--schema`, `--token` (или `LETOPIS_DSN`, `LETOPIS_SCHEMA`, `LETOPIS_TOKEN`) и `--write` |
 
 ### Корень `db`
 
@@ -1911,7 +2414,7 @@ await svc.close()      // и подключения, полученные чер
 | `schema`, `token`, `tenant`, `registry` | имя установки, токен, арендатор сессии, реестр классов (`resolve`, `find`, `has`, `all`, `family`) |
 | `auth`, `acl` | вход, креды и сессии; решения прав ([раздел 10](#10-пользователи-вход-и-права)) |
 | `as(аккаунт, { tenant, owner })` | тот же пул от имени аккаунта (асинхронный) |
-| `begin()`, `commit(tr)`, `rollback(tr)`, `lock(…ключи)` | явная транзакция ([раздел 8](#8-транзакции-батчи-и-деньги)) |
+| `begin()`, `commit(tr)`, `rollback(tr)`, `lock(…ключи)` | явная транзакция ([раздел 8](#8-транзакции-и-батчи)) |
 | `batch(имя)` | очередь планов: `run()`, `discard()`, `size()` |
 | `load(вход, опции)` | загрузчик ([раздел 9](#9-массовая-загрузка)) |
 | `watch(опции)`, `cache` | подписка; кэш результатов (`clear()`, `stats()`) |
@@ -1919,15 +2422,15 @@ await svc.close()      // и подключения, полученные чер
 | `idOf(класс, ключ)` | id объекта класса с ключом в арендаторе сессии |
 | `entity(строка \| цепочка)` | начать путь с готового узла |
 | `maintain()` | обслуживание ([раздел 13](#13-эксплуатация)) |
-| `refresh()`, `flushSignals()`, `close()` | перечитать классы; отправить сигналы сейчас; закрыть |
+| `refresh()`, `flushSignals()`, `close()` | перечитать классы; отправить сигналы сейчас; закрыть пул и подписки (у фасада `as()` — ничего не делает, в `db.begin()` — откат) |
 
 ### Цепочка
 
 | Группа | Методы |
 |---|---|
 | шаги | `.Класс(фильтр)`, `.алиас(фильтр)`, `.Роль(фильтр)` |
-| модификаторы | `limit(n)`, `offset(n)`, `sort(поле, 'asc' \| 'desc')`, `after(курсор)`, `asOf(момент)`, `withDeleted()`, `deep(max)`, `exact()`, `alias(имя)`, `tags(…)`, `owner(…)`, `entity(…)`, `forUpdate()`, `cache({ ttl })` |
-| глаголы | `create(данные)`, `update(патч, { rev, all })`, `upsert(данные)`, `delete({ confirm, all })`, `restore()`; `update` и `delete({ confirm: true })` без фильтра, id, `tags()`, `owner()` и `limit()` у шага глагола и шагов до него (и без `create()` или `upsert()` раньше в цепочке) — только с `{ all: true }` |
+| модификаторы | `limit(n)`, `offset(n)`, `sort(поле, 'asc' \| 'desc')`, `after(курсор)`, `asOf(момент)`, `withDeleted()`, `deep(max)`, `exact()`, `alias(имя)`, `tags(…)`, `owner(…)`, `entity(…)`, `forUpdate()`, `cache({ ttl })`; модификаторы выборки `limit`, `offset`, `sort`, `after`, `forUpdate` — последнему шагу цепочки (перед глаголом — его целям), где бы ни стояли; `asOf` и `cache` — всей цепочке; `withDeleted`, `deep`, `exact`, `alias`, `tags`, `owner` — своему шагу |
+| глаголы | `create(данные)`, `update(патч, { rev, all })`, `upsert(данные)`, `delete({ confirm, expect, all })`, `restore({ expect, partial, all })` (у всех — ещё `reason`; `expect` — строки `{ id, rev }` превью или надгробий, [раздел 7](#7-удаление-и-восстановление)); `delete({ confirm: true })` — только с `expect` или `all: true`, `restore()` — только с `expect` или `all: true` (тип `DeleteOptions` и `RestoreOptions` отклоняет иное ещё при компиляции); `update` и `delete({ confirm: true, expect })` без фильтра, id, `tags()`, `owner()` и `limit()` у шага глагола и шагов до него (и без `create()` или `upsert()` раньше в цепочке) — только с `{ all: true }` |
 | слоты | после глагола: `.Роль.set(значение)`, `.Роль.unset()`, `.Роль.add(значение)`, `.Роль.remove(значение)` |
 | терминалы | `rows()`, `first()`, `ids()`, `count({ paths })`, `paths()`, `versions()`, `sum(поле)`, `avg(поле)`, `min(поле)`, `max(поле)`, `countBy(поле)` |
 
@@ -1943,9 +2446,9 @@ await svc.close()      // и подключения, полученные чер
 | `issueOtp`, `verifyOtp` | `{ account, identifier, kind?, ttl?, digits?, maxAttempts? }` → `{ code }`; `{ identifier, code, kind? }` → вход или `null` |
 | `link`, `lookup` | `{ account, kind, identifier, meta?, confirmed? }` → id; `{ kind, identifier, requireConfirmed?, ttl?, totp? }` → вход или `null` |
 | `credentials`, `revokeCredential`, `setFlags` | `(account)` → креды без секретов; `(id, { keepCurrent? })`; `(id, { confirmed?, enabled? })` |
-| `sessionFor`, `refresh`, `revoke`, `revokeAll` | `(account, { ttl? })` → токен; `({ ttl? })` → новое время истечения (токен прежний); `()`; `(account?)` → число сессий |
+| `sessionFor`, `refresh`, `revoke`, `revokeAll` | `(account, { ttl? })` → токен; `({ ttl? })` → новое время истечения (токен прежний); `()` — выход подключения, `(token)` — выход пользователя по токену его сессии (право `auth.session`) → `boolean`; `(account?)` → число сессий |
 | `session` | `(token)` → `{ account, tenant, member, expiresAt, loginAt, methods }` или `null` |
-| `tenants`, `switch` | `()` → `[{ tenant, roles }]`; `(tenant)` |
+| `tenants`, `switch` | `()` → `[{ tenant, roles, name, personal }]` (первым — собственный, `personal: true`); `(tenant)` |
 | `purgeAccount` | `(account)` → `{ account, rows, versions, memberships, owned }` |
 
 Проверку паролей, кодов и TOTP, выпуск сессий, сведения о сессии по токену и подтверждение кредов вызывает сервис
@@ -1968,7 +2471,8 @@ await svc.close()      // и подключения, полученные чер
 | `at`, `author`, `agent`, `op`, `reason` | время версии (ISO, UTC, микросекунды), автор, агент (сервис при имперсонации), вид операции, причина |
 | `$deleted` | надгробие: удалённая сущность или версия удаления |
 | `$depth` | глубина узла в `deep()`; уровень каскада в превью удаления |
-| `$upsert`, `$action` | что сделал `upsert`; что сделает удаление |
+| `$upsert`, `$action` | что сделал `upsert`; что сделает удаление (`delete`, `unset`, `restrict`); `skip` — цель `restore({ expect, partial: true })`, которую не восстановить |
+| `$why` | у строки `$action: 'skip'` — почему: `restored`, `reissued`, `changed` ([«Восстановить: `restore`»](#восстановить-restore)) |
 
 ### Зарезервированные имена
 
@@ -1985,6 +2489,13 @@ await svc.close()      // и подключения, полученные чер
   `maintain`, `auth`, `acl`, `idOf`, `refresh`, `transaction`, `flushSignals`, `schema`, `token`, `tenant`, `cache`;
 - батч: `run`, `discard`, `size`.
 
+Имя роли конца одно на арендатора — это имя шага цепочки: во всех классах арендатора и System роль с одним именем
+ведёт на одни и те же классы. Поэтому заняты роли концов системных классов: `Group` и `Object` (класс `rule`) ведут на
+`Resource`, `User` и `Tenant` (класс `member`) — на `Account`. Конец с таким именем, который ведёт на другой класс,
+`syncModels` отклоняет до записи — `invalid_class` (`model.end_role_system`; роль другого своего класса —
+`model.end_role_taken`), а класс, заведённый мимо него, — база (`sql-write.end_other_class`). Имена классов `Group` и
+другие не заняты — заняты имена ролей: называйте роли иначе (`Team`, `Org`, `Holder`).
+
 ## 15. Ошибки
 
 Текст ошибки — `letopis: <код>: <сообщение>`. Код — в `err.code`, подробности — в `err.detail`. Ошибки — объекты
@@ -1996,7 +2507,10 @@ await svc.close()      // и подключения, полученные чер
   у мест библиотеки и у ошибок базы, которая прислала ключ в `DETAIL`.
 
 Тексты ошибок — только на русском. Ошибку базы с ключом библиотека отдаёт с тем же текстом, что получает и сырой SQL
-мимо библиотеки, а ключ и параметры из `DETAIL` переносит в `err.key` и `err.params`.
+мимо библиотеки, а ключ и параметры из `DETAIL` переносит в `err.key` и `err.params`. У ошибки данных (`invalid_data`)
+текст ещё называет первое нарушение и их число: `letopis: invalid_data: данные не проходят описание класса Order:
+status — значение не из перечисления: допустимо "new", "paid", "cancelled" (всего нарушений: 2, все — err.issues)`.
+Сообщение нарушения перечисления называет допустимые значения, лишнего ключа — сам ключ (`лишний ключ colour`).
 
 ```ts
 const db = await connect({ dsn, schema: 'v2.shop', token })
@@ -2026,20 +2540,20 @@ try {
 
 | Код | SQLSTATE | Когда |
 |---|---|---|
-| `no_session`<a id="no_session"></a> | LT001 | нет действующей сессии |
-| `target_not_found`<a id="target_not_found"></a> | LT002 | цель не найдена — одинаково для несуществующей, чужой и невидимой |
-| `invalid_data`<a id="invalid_data"></a> | LT003 | данные не проходят описание класса; `err.issues` — путь, ключевое слово, сообщение. У библиотеки ещё — неизвестная опция `connect()`, `up()`, `db.load()`, `db.watch()` и `createMcpServer()` (похожие — в `err.params.similar`) и неверное значение опции |
+| `no_session`<a id="no_session"></a> | LT001 | нет действующей сессии. У библиотеки ещё — `connect({ token })` с погашенным, истёкшим или неверным токеном: отклонённый промис, подключение не создаётся (`api.token_not_active`); то же — промисом терминала у шага, не найденного в реестре подключения по токену без арендатора сессии |
+| `target_not_found`<a id="target_not_found"></a> | LT002 | цель не найдена — одинаково для несуществующей, чужой и невидимой. `svc.as(id)` с id аккаунта, которого нет (не заводили или удалён), — ключ `sql-core.impersonation_no_account`: «аккаунт … не найден»; аккаунт есть, но действовать от его имени нельзя (System, сервис, системный администратор, выключен) — `acl_denied` (`sql-core.impersonation_denied`) |
+| `invalid_data`<a id="invalid_data"></a> | LT003 | данные не проходят описание класса; текст называет первое нарушение и их число, `err.issues` — все: путь, ключевое слово, сообщение. Ключ с именем конца в данных `create`, `upsert`, `update` — `write.link_in_data`: текст называет ключ и форму слота `.Роль.set(id)`. У библиотеки ещё — неизвестная опция `connect()`, `up()`, `db.load()`, `db.watch()` и `createMcpServer()` (похожие — в `err.params.similar`) и неверное значение опции |
 | `undeclared_end`<a id="undeclared_end"></a> | LT004 | конец не объявлен в классе |
 | `tenant_denied`<a id="tenant_denied"></a> | LT005 | чужой арендатор или нет членства |
 | `acl_denied`<a id="acl_denied"></a> | LT006 | отказ по правилам доступа |
 | `id_mismatch`, `id_from_db`<a id="id_mismatch"></a><a id="id_from_db"></a> | LT007, LT008 | id не равен v5 от ключа; id класса без ключа выдаёт база |
 | `immutable_key`<a id="immutable_key"></a> | LT009 | ключевое поле, класс, id, арендатор и владелец не меняются: другой ключ или класс — новый объект |
-| `invalid_class`<a id="invalid_class"></a> | LT010 | описание класса отклонено, класс не найден или абстрактный; класс со строками, потомками или историей строк не удаляется; хаб или связь с зарезервированным именем (хаб отклоняют ещё `hub()` и `syncModels`) |
+| `invalid_class`<a id="invalid_class"></a> | LT010 | описание класса отклонено, класс не найден или абстрактный; класс со строками, потомками или историей строк не удаляется; хаб или связь с зарезервированным именем (хаб отклоняют ещё `hub()` и `syncModels`). Класс, который точно записан `syncModels`, «не найден» — сессия в другом арендаторе, и классы арендатора ей не видны: чаще всего пользователь после входа остался в личном арендаторе — проверьте `db.tenant`, нужен `svc.as(account, { tenant })` или `auth.switch(tenant)` ([«Работа в другом арендаторе»](#работа-в-другом-арендаторе)). Если в реестре сессии нет ни одного класса арендатора — ключ `api.unknown_step_no_classes`. Системные классы в похожие имена не идут. Ещё — модель с преобразованием Zod у `syncModels` (`model.transform_unsupported`, [«Поля»](#поля)) |
 | `tightening_conflict`<a id="tightening_conflict"></a> | LT013 | ужесточению описания мешают строки |
 | `isolation_level`<a id="isolation_level"></a> | LT014 | удаление — только в `read committed` |
 | `recreated_in_statement`<a id="recreated_in_statement"></a> | LT015 | id удалён и создан заново одним оператором |
 | `delete_restricted`<a id="delete_restricted"></a> | LT017 | удалению мешают ссылающиеся строки (`onDelete: 'restrict'`) |
-| `not_deleted`<a id="not_deleted"></a> | LT018 | `restore` — только для удалённых |
+| `not_deleted`<a id="not_deleted"></a> | LT018 | `restore` — только для удалённых: объект жив и не удалялся (`write.not_deleted`), уже восстановлен — в том числе проигравшим гонку двух `restore()` (`write.restore_already`), или его id занял новый живой объект с тем же ключом — `create()` по ключу удалённого (`write.restore_id_taken`): место занято новым объектом, восстанавливать нечего. id — `err.detail.ids`, с `expect` причины по целям — `err.detail.stale` ([«Восстановить: `restore`»](#восстановить-restore)) |
 
 Коды библиотеки:
 
@@ -2047,15 +2561,15 @@ try {
 |---|---|
 | `exists`<a id="exists"></a> | объект уже существует: `create` (`detail.id` — его id) или загрузчик |
 | `duplicate`, `deleted`<a id="duplicate"></a><a id="deleted"></a> | загрузчик: повтор id в загрузке; объект с этим id жил раньше. Загрузчик бросает код первой проблемной строки, первые 100 — в `detail.rows`, всего — `detail.total` |
-| `conflict`<a id="conflict"></a> | `update(патч, { rev })`: строку успели изменить (`detail`: `id`, `rev`, `expected`) |
+| `conflict`<a id="conflict"></a> | `update(патч, { rev })`: строку успели изменить (`detail`: `id`, `rev`, `expected`); `restore({ expect })`: после этого удаления id меняли — пересоздан и удалён снова, удалён снова (`write.restore_stale`, `detail`: `{ ids, stale: [{ id, rev, expected, after, deleted, live, why }] }`), ничего не восстановлено; `delete({ confirm: true, expect })`: превью изменилось (`write.preview_changed`, новое превью — `detail.preview`; цели уже удалены или не найдены при непустом `expect` — `detail.preview: []`), ничего не удалено |
 | `rev_ambiguous`<a id="rev_ambiguous"></a> | `{ rev }` у шага, у которого не одна цель |
 | `tx_required`<a id="tx_required"></a> | `forUpdate()`, `lock()`, `commit()` или `rollback()` вне действующей `db.begin()` |
-| `lock_unsupported`<a id="lock_unsupported"></a> | `forUpdate()` с агрегатом, `asOf`, `versions`, `withDeleted`, `deep` или глаголом |
+| `lock_unsupported`<a id="lock_unsupported"></a> | `forUpdate()` с агрегатом, `count()`, `paths()`, `versions()`, `asOf()`, `withDeleted()`, `deep()` или глаголом (`api.for_update_unsupported`): текст называет помеху — «forUpdate() нельзя с withDeleted(): блокировка — только у чтения rows(), first(), ids()», подсказка — допустимое и форма «прочитать `forUpdate().first()`, затем `update()` отдельной цепочкой» |
 | `commit_unknown`<a id="commit_unknown"></a> | связь оборвалась во время `COMMIT`: исход неизвестен |
 | `tx_rolled_back`<a id="tx_rolled_back"></a> | PostgreSQL ответил `ROLLBACK` на `COMMIT`: ошибку перехватили внутри `tr.transaction(fn)` |
 | `no_key`<a id="no_key"></a> | `upsert` или `idOf` у класса без ключа |
 | `no_path`<a id="no_path"></a> | между классами соседних шагов нет перехода |
-| `invalid_query`<a id="invalid_query"></a> | цепочку или API используют неверно (поле фильтра, `sort()` или агрегата не описано ни в одном классе шага — похожие в `err.params.similar`; `update()` или `delete({ confirm: true })` без фильтра, id, `tags()`, `owner()` и `limit()` у шагов и без `{ all: true }`, `after()` перед `count()` и агрегатами, модификатор шага `deep`, `exact`, `alias`, `tags` или `owner` после глагола, модификатор выборки между глаголом и терминалом `rows`, `first`, `ids`, `count` или `paths`, слот не после глагола, курсор `after()` со значением не того типа, что поле `sort`, без `v` или с `id` не uuid и т. п.) |
+| `invalid_query`<a id="invalid_query"></a> | цепочку или API используют неверно (поле фильтра, `sort()` или агрегата не описано ни в одном классе шага — похожие в `err.params.similar`; `delete({ confirm: true })` без `expect` и без `all: true` (`write.confirm_without_expect`); `restore()` без `expect` и без `all: true`, в том числе по явному id (`write.restore_without_expect`); `update()` или `delete({ confirm: true, expect })` без фильтра, id, `tags()`, `owner()` и `limit()` у шагов и без `{ all: true }` (`write.no_filter`); `createTenant(admin, …)` с `admin` не пулом `postgres()` (`api.create_tenant_admin`); метод цепочки у результата `versions()` (`api.versions_terminal`), `after()` перед `count()` и агрегатами, модификатор шага `deep`, `exact`, `alias`, `tags` или `owner` после глагола, модификатор выборки между глаголом и терминалом `rows`, `first`, `ids`, `count` или `paths`, слот не после глагола, курсор `after()` со значением не того типа, что поле `sort`, без `v` или с `id` не uuid; id шага, `{ id }` или конца — не uuid (`query.bad_uuid`); свойство массива у цепочки — `.length`, `.map()`, `[0]`, перебор (`api.chain_not_rows`); `expect` без `confirm: true` или не списком строк `{ id, rev }`; `restore({ partial: true })` без `expect`, и с `all: true` тоже (`write.partial_without_expect`); `db.begin(аргумент)` — не объект опций `{ reason }`: функция, строка, число, массив (`api.begin_arg`); `withDeleted()` в цепочке записи, кроме `restore()`; значение не того типа в запросе — SQLSTATE `22P02` из базы, в том числе у `db.sql` (`api.db_bad_value`, исходная ошибка — `err.cause`) и т. п.) |
 | `admin_required`<a id="admin_required"></a> | загрузчику нужно администраторское подключение; роль строки `connect({ admin })` не может стать владельцем схемы; `up()` от роли без ADMIN OPTION на уже существующую роль владельца |
 | `not_empty`<a id="not_empty"></a> | первая заливка (`initial`) — только в пустую схему |
 | `class_not_loadable`<a id="class_not_loadable"></a> | строки `Class` загрузчик не принимает |
@@ -2066,6 +2580,74 @@ try {
 
 Отказ PostgreSQL в праве (`42501`) приходит, например, при `upsert` поверх чужой строки, которую нельзя править.
 
+**Отказы безопасности по умолчанию и неверного использования.** Ключи, которые приходят до записи и до запроса — их
+исправляют в коде, а не показывают пользователю:
+
+| Ключ | Код | Когда | Что делать |
+|---|---|---|---|
+| `write.confirm_without_expect` | `invalid_query` | `delete({ confirm: true })` без `expect` и без `all: true` | показать превью `delete()` и удалить с ним: `delete({ confirm: true, expect: превью })`; без сверки — осознанно `{ confirm: true, all: true }` |
+| `write.restore_without_expect` | `invalid_query` | `restore()` без `expect` и без `all: true`, в том числе по явному id | `restore({ expect })` с ответом `delete()` или строками `withDeleted().rows()`; что можно — `restore({ expect, partial: true })`; всё без сверки — осознанно `restore({ all: true })` |
+| `api.create_tenant_admin` | `invalid_query` | `createTenant(admin, …)`: `admin` — строка DSN, подключение `connect()`, `undefined` или другой не пул | `const admin = postgres(ADMIN); await createTenant(admin, schema, opts); await admin.end()` |
+| `api.versions_terminal` | `invalid_query` | метод цепочки у результата `versions()`: `versions().rows()`, `.sort()`, `.limit()` | `await db.X(id).versions()`; модификаторы — до `versions()` |
+| `write.link_in_data` | `invalid_data` | имя конца (связи) в данных `create()`, `upsert()`, `update()` | конец — из пути или слотом после глагола: `.Роль.set(id)`, у списка — `.add(id)` / `.remove(id)`, снять — `.unset()` |
+| `sql-core.impersonation_no_account` | `target_not_found` | `svc.as(id)`: аккаунта нет — не заводили или удалён | id аккаунта — из входа, `createTenant()` или `auth.tenants()` |
+
+**Текст для человека.** Штатные отказы — ответ пользователю, а не 500. Фразу выбирают по `err.key`, если он есть, иначе
+по `err.code`; `err.message` и `err.hint` — для разработчика и журнала:
+
+| Код (ключ) | Пользователю |
+|---|---|
+| `exists` | «уже существует» / «уже занято» |
+| `conflict` | «данные изменил другой — обновите и повторите»; `write.preview_changed` — показать новое превью; `write.restore_stale` — «после удаления запись меняли» |
+| `not_deleted` | `write.restore_already` — «уже возвращено»; `write.restore_id_taken` — «место занято новой записью»; `write.not_deleted` — «не удалено» |
+| `target_not_found` | «не найдено: удалено или недоступно» |
+| `delete_restricted` | «нельзя удалить: на запись ссылаются» (строки — превью с `$action: 'restrict'`) |
+| `acl_denied`, `tenant_denied` | «недостаточно прав», «нет доступа к организации» |
+| `no_session` | «сессия истекла — войдите снова» |
+| `invalid_data` | по `err.issues`: своё название поля по `path`, фраза по `keyword` (ниже) |
+
+**Значение не того типа (SQLSTATE `22P02`).** Неверный id в цепочке библиотека ловит сама, до запроса:
+`invalid_query`, ключ `query.bad_uuid`. Что дошло до базы — `'42'::uuid` в `db.sql`, `db.transaction(fn)` или
+`tr.sql`, — приходит `LetopisError` с кодом `invalid_query` и ключом `api.db_bad_value`; текст называет, какое
+значение не подошло, исходная ошибка PostgreSQL — в `err.cause`:
+
+```ts
+try {
+  await db.sql`select ${'42'}::uuid`
+} catch (e) {
+  // e instanceof LetopisError, e.code === 'invalid_query', e.key === 'api.db_bad_value'
+  // e.message — 'letopis: invalid_query: значение не того типа: invalid input syntax for type uuid: "42"'
+  // (e.cause as { code: string }).code === '22P02' — исходная ошибка PostgreSQL
+}
+```
+
+SQLSTATE, если он нужен, берут из `err.cause.code`.
+
+**Текст для пользователя из `err.issues`.** У `ValidationError` каждое нарушение — `{ path, keyword, message }`:
+`path` — путь к полю (`[]` — данные целиком), `keyword` — правило JSON Schema (`type`, `required`, `minimum`, `enum`,
+`pattern`, `additionalProperties` …), `message` — русский текст для разработчика: у перечисления он называет
+допустимые значения, у лишнего ключа — сам ключ, у `minLength` и `maxLength` — предел («длина строки меньше 3», «длина
+строки больше 40»), у прочих правил бывает общим («нарушено правило minimum»). Пользователю
+показывают свои названия полей и свои фразы по `keyword`, а `message` — запасной текст:
+
+```ts
+import { ValidationError } from 'letopis'
+
+const LABELS: Record<string, string> = { price: 'Цена', title: 'Название', sku: 'Артикул' }
+const RULES: Record<string, string> = { required: 'обязательно', minimum: 'слишком мало', type: 'неверный формат' }
+function explain(e: ValidationError): string[] {
+  return e.issues.map((i) => {
+    const field = i.path.length ? (LABELS[String(i.path[0])] ?? i.path.join('.')) : 'Данные'
+    return `${field}: ${RULES[i.keyword] ?? i.message}`   // «Цена: слишком мало»
+  })
+}
+```
+
+**Предупреждения.** Часть ошибок использования — не отказ, а предупреждение в консоли: шаг с `undefined`, шаг после
+`sort()`, `withDeleted()` не у того шага ([«Строгий режим»](#строгий-режим)). При включённом журнале каждое
+предупреждение — ещё и событие `warning`, а каждая ошибка — событие `error` с кодом, ключом и цепочкой
+([«Логирование»](#логирование)).
+
 ## 16. Производительность
 
 Замеры — сценарии `lib/bench/` (как запускать, написано в шапке каждого файла), итоги — `lib/bench/results/`. Ниже —
@@ -2091,7 +2673,7 @@ try {
 
 ## 17. Ограничения
 
-Здесь собрано то, что letopis 2.0 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
+Здесь собрано то, что letopis 3.0 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
 
 **Платформа**
 
@@ -2131,8 +2713,9 @@ try {
 - Владелец схемы и суперпользователь могут отключить триггеры и изменить что угодно, в том числе журнал: letopis
   этого не предотвращает и не обнаруживает. Журналу можно верить, пока роль владельца и суперпользователь — вне
   приложения.
-- В базе проверяется подмножество JSON Schema: `refine`, `superRefine` и `transform` Zod работают только
-  в библиотеке, описание с неизвестным ключевым словом база не примет; `pattern` — ограниченное подмножество
+- В базе проверяется подмножество JSON Schema: `refine` и `superRefine` Zod база не исполняет (они в `lost` у
+  `syncModels`), преобразования Zod (`.trim()`, `.transform()` …) `syncModels` отклоняет, описание с неизвестным
+  ключевым словом база не примет; `pattern` — ограниченное подмножество
   регулярных выражений, общее для Zod, валидатора и базы. Вывод `z.toJSONSchema()` меняется между версиями Zod:
   в базе хранится уже нормализованная схема, а сухой прогон `syncModels` показывает разницу до применения.
 - Ключ — единственный способ уникальности: id вычисляется из значений ключа без нормализации, поэтому одно
@@ -2141,6 +2724,10 @@ try {
 - Ключ и класс объекта неизменны: смена значения ключа (email, телефон) — новый объект. Изменчивые и персональные
   значения лучше выносить в отдельный хаб со связью: id из email подбирается перебором и остаётся в ссылках и
   журнале, а версии журнала не стираются (кроме удаления аккаунта вместе с его арендатором).
+- `create()` по ключу удалённого объекта занимает его id: прежний объект после этого не восстановить
+  (`restore({ expect })` — `not_deleted`, `write.restore_id_taken`, пока новый объект жив; когда удалён и он, —
+  `conflict`, `write.restore_stale`). Что ключ принадлежит удалённому, показывает `withDeleted()` перед `create()`.
+- `restore()` не проверяет бизнес-правила приложения, только описание класса, концы, ключ и права.
 - `create` занятого ключа отвечает `exists` с id, `upsert` без права на существующую строку — отказом `42501`:
   так раскрывается, что ключ занят, но только внутри своего арендатора — у других арендаторов те же ключи дают
   другие id.
@@ -2148,8 +2735,8 @@ try {
 - id v5 ложатся в индекс первичного ключа вразброс; на очень больших таблицах с интенсивной вставкой это заметнее,
   чем с последовательными id.
 - Горячие цели ссылок (организация, на которую ссылается почти всё) копят блокировки `for key share` и MultiXact,
-  как при обычных внешних ключах; это нужно мониторить. Операции одного кошелька идут друг за другом под
-  блокировкой его строки ([раздел 8](#8-транзакции-батчи-и-деньги), «Рецепт: кошелёк»).
+  как при обычных внешних ключах; это нужно мониторить. Приращения и правки одного объекта идут друг за другом под
+  блокировкой его строки ([раздел 8](#8-транзакции-и-батчи), «Значение из прочитанного и повтор операции»).
 - Класс не может называться зарезервированным именем ([«Зарезервированные имена»](#зарезервированные-имена)): хаб
   отклоняют `hub()`, `syncModels` и база, связь — база. Хаб, заведённый мимо проверки базы, доступен не везде:
   например, `count` — только первым шагом.
@@ -2317,3 +2904,19 @@ try {
 # llms — один словарь фильтров (план 2.0, 7.9 №8): реестр операторов совпадает с фабриками пакета, с ключами letopis_query (тот же ответ, что у цепочки) и с таблицами README, шпаргалки и главы «Чтение» сайта
 # disconnect — обрыв соединения (план 2.0, 7.4 №7): загрузчик и первая заливка, открытие db.begin() — обрыв TCP до и после COMMIT и на открытии транзакции, pg_terminate_backend процесса, ждущего блокировку: промис отклонён ошибкой связи, необработанных ошибок в процессе нет, следующая операция пула проходит
 ```
+
+## 19. Лицензия
+
+letopis распространяется под лицензией **PolyForm Noncommercial License 1.0.0** (SPDX `PolyForm-Noncommercial-1.0.0`):
+исходный код открыт, некоммерческое использование бесплатно, коммерческое — только по отдельной лицензии от
+владельца. Это не лицензия open source в смысле OSI. Полный текст — [LICENSE](LICENSE) (юридическую силу имеет он).
+
+- **Без разрешения** — любые некоммерческие цели: личное использование для исследований, экспериментов, учёбы, хобби
+  без коммерческого применения; использование благотворительными и некоммерческими организациями, учебными
+  заведениями, государственными исследовательскими организациями и учреждениями. Код можно менять и распространять —
+  с текстом лицензии и строкой `Required Notice: Copyright 2026 alepri51 (https://github.com/alepri51)`.
+- **По разрешению владельца** — коммерческое использование: платный продукт или сервис, внутренние системы
+  коммерческой компании, разработка на заказ, встраивание в коммерческий продукт.
+- **Как получить разрешение** — issue в репозитории <https://github.com/alepri51/letopis/issues> с заголовком
+  «Коммерческая лицензия»; владелец — <https://github.com/alepri51>. Подробнее — [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md).
+- Версии до 2.0.0 включительно выпущены под MIT и остаются под ней; PolyForm Noncommercial действует с 2.1.0.