letopis 0.19.0 → 0.20.0

package/README.md

@@ -6,14 +6,15 @@ Dot-цепочки над append-only Entity-хранилищем (TimescaleDB).
 ```ts
 import { connect } from 'letopis'
 
-const db = await connect({ dsn: 'postgres://…', schema: 'v1.booking' })
+const db = await connect({ dsn: 'postgres://…', schema: 'v1.booking' })  // пул, безличный
+const t  = await db.as(accountId)   // арендатор ВЫЗОВА: кто именно делает эти запросы (§10.6)
 
 // чтение: пути по графу
-const пути = await db.Мастер({ name: 'Вася' }).навык().Услуга().run()
+const пути = await t.Мастер({ name: 'Вася' }).навык().Услуга().run()
 // [ { Мастер: Row, навык: Row, Услуга: Row }, … ]
 
 // запись: операции — звенья, исполняет терминал
-await db.Организация(org).Мастер().create({ name: 'Вася', phone: '+7 900 …' }).rows()
+await t.Организация(org).Мастер().create({ name: 'Вася', phone: '+7 900 …' }).rows()
 ```
 
 ## Возможности
@@ -52,7 +53,7 @@ await db.Организация(org).Мастер().create({ name: 'Вася', p
 - Пароли (scrypt), api-ключи, key-secret, external identity (oauth/sso/telegram), TOTP, одноразовые коды (§9.1).
 - Сессии во внешнем Redis (клиент инжектируется, §9.1).
 - ACL: `Resource` / `Rule`, `enforceAcl` — предикаты строк вливаются в SQL до сортировки/лимита; наследование прав по классам (§9.2).
-- Изоляция арендатора `enforceAccount` (§10.6).
+- Изоляция арендатора `enforceAccount` **включена по умолчанию**; арендатора называет `db.as(account)` — свойство ВЫЗОВА, не подключения (§10.6).
 
 **Эксплуатация**
 - `up()` — dev-bootstrap одной функцией: Docker (TimescaleDB pg17 + Redis) + схема + сиды + connect (§1, §1.1).
@@ -82,6 +83,19 @@ await db.Организация(org).Мастер().create({ name: 'Вася', p
 
 ## 1. Быстрый старт
 
+```bash
+npm install letopis          # ESM-only, Node 20+; рантайм-зависимости: postgres + fastest-validator
+```
+
+Нужен PostgreSQL 17 с расширением TimescaleDB (`Entity` — hypertable). Локально его
+поднимает сам `up()` через Docker; Redis нужен только для сессий (`db.auth.sessions`),
+клиент инжектируется.
+
+> **Две разные «версии», не путать.** Semver пакета живёт в `package.json` /
+> `CHANGELOG.md`. Везде в этом руководстве `version` / `opts.version` — **версия
+> DDL-схемы**: целое ≥ 1, из него строится имя PG-схемы `v<version>.<schema>`,
+> бампается руками при breaking-изменении `ddl.sql`.
+
 Одна функция — весь путь от нуля: dev-контейнер (TimescaleDB + Redis), готовность,
 версионная схема с сидами, подключение:
 
@@ -96,9 +110,14 @@ const db = await up({ schema: 'booking', version: 1 })   // → PG-схема "v
 // [letopis.up] schema "v1.booking" applied (3 files)
 // [letopis.up] connected (schema "v1.booking")
 
-const [org]  = await db.Организация().create({ name: 'BarberPro' }).rows()
-const [вася] = await db.Организация(org).Мастер().create({ name: 'Вася', phone: '+7 900 …' }).rows()
-await db.close()
+// db — безличный пул: изоляция арендатора включена по умолчанию, поэтому цепочки идут
+// от ИМЕНИ аккаунта (§10.6). На старте единственный аккаунт — System из сида.
+const [sys] = await db.accounts.find({ category: 'System' })
+const t = await db.as(sys.id)
+
+const [org]  = await t.Организация().create({ name: 'BarberPro' }).rows()
+const [вася] = await t.Организация(org).Мастер().create({ name: 'Вася', phone: '+7 900 …' }).rows()
+await db.close()   // scope'ы делят пул с корнем — закрывать один раз
 ```
 
 Идемпотентно: живой postgres на `dsn` → docker пропускается; существующая схема не трогается.
@@ -122,6 +141,13 @@ const db = await connect({ dsn: 'postgres://postgres:test@localhost:15432/clockz
 
 ### 1.1 Своя схема с нуля + всё в контейнере одной командой
 
+> **⚠ `seeds` ОБЯЗАТЕЛЕН для своего домена.** Без него (`seeds` не передан) `up()` заливает
+> **демо-домен booking** — в любую схему, как бы она ни называлась: `up({schema:'myapp', version:1})`
+> даст `v1.myapp` с классами `Организация`/`Мастер`/`запись`, а не с вашими.
+> Передавайте `seeds: ['./myapp.sql']`, либо `seeds: false` — голая структура без классов
+> (тогда классы добавляйте через `db.schema.define()`, иначе `connect` упадёт `has no classes`).
+> Схема применяется ОДИН раз: если `v1.myapp` уже есть, накат пропускается (`fresh: true` — дропнуть и перелить).
+
 Три шага: **(1)** сид своей схемы → **(2)** `up()` поднимает контейнер и накатывает → **(3)** пишешь данные. Таблицы (`Schema`, `Account`, `Entity`, …) создаёт `ddl.sql` — своему сиду нужны только INSERT-ы; маркер `<SCHEMA-NAME>` подставит `up()`.
 
 **1. Сид `myapp.sql`** — классы в таблицу `Schema` + System-аккаунт:
@@ -184,13 +210,17 @@ const db = await up({
 })
 ```
 
-**3. Данные — работают сразу** (System-аккаунт из сида закрывает `account`/`owner`):
+**3. Данные — работают сразу.** Цепочки идут от имени аккаунта (`db.as`, §10.6); System-аккаунт
+из сида — валидное «имя» для дев-скриптов и он же дефолт колонок `account`/`owner`:
 
 ```ts
-const [n] = await db.Заметка().create({ title: 'Купить хлеб' }).rows()
-const [t] = await db.Тег().create({ name: 'дом' }).rows()
-await db.Заметка(n).помечена().create().Тег.set(t).rows()   // связь Note ↔ Tag (§6.1)
-const активные = await db.Заметка({ done: false }).rows()
+const [sys] = await db.accounts.find({ category: 'System' })
+const s = await db.as(sys.id)
+
+const [n] = await s.Заметка().create({ title: 'Купить хлеб' }).rows()
+const [t] = await s.Тег().create({ name: 'дом' }).rows()
+await s.Заметка(n).помечена().create().Тег.set(t).rows()   // связь Note ↔ Tag (§6.1)
+const активные = await s.Заметка({ done: false }).rows()
 await db.close()
 ```
 
@@ -278,6 +308,35 @@ GIN-кандидатам, затем перепроверка условий н
 | `links` | концы связей класса, формат v2 — массив объектов (см. ниже); legacy-строка `'Org'` = `{class:'Org'}`, `'Entity'` = старый полиморф |
 | `meta` | `{ abstract?, description? }` |
 
+#### Зарезервированные имена классов
+
+Шаг цепочки — это свойство Proxy, а терминалы/модификаторы/глаголы записи разбираются
+**до** резолва класса. Значит класс, чей `id` или `alias` совпал с таким именем, как шаг
+под этим именем **недостижим**: например класс с id `count` не получится пройти как
+`db.X(id).count()` — вызовется терминал подсчёта.
+
+| Уровень | Занятые имена |
+|---|---|
+| цепочка | `account` `after` `alias` `anonymize` `asOf` `avg` `count` `countBy` `create` `deep` `delete` `entity` `exact` `execute` `first` `ids` `limit` `max` `min` `offset` `owner` `purge` `rows` `run` `set` `sort` `sum` `tags` `then` `update` `versions` `withDeleted` |
+| батч `db.batch(n)` | `discard` `size` (+ `run` / `execute` из строки выше) |
+| корень `db` | `accounts` `acl` `as` `auth` `batch` `begin` `close` `commit` `credentials` `lock` `registry` `reloadSchema` `resources` `rollback` `rules` `schema` `sql` `watch` |
+
+Всего 52 имени. `then` занят во всех трёх Proxy — иначе цепочка выглядела бы thenable и
+ломала `await`. Фасады `accounts`/`credentials`/`resources`/`rules`/`schema`/`auth`/`acl`
+разбираются на корне `db` до резолва класса.
+
+- Гварды: `db.schema.define()` **отказывает** на таком имени; `connect()`/`up()` печатают
+  предупреждение (один раз на процесс) вида
+  `letopis: class name "count" is reserved by the chain API — use "Счётчик" for chain steps`.
+- Хватает **одного** свободного имени из пары `id`/`alias`: если занят `id`, класс ходится
+  по алиасу, и наоборот. Если заняты оба — класс недостижим как шаг, `gen-types` его в типы
+  не выдаст, а предупреждение скажет «rename it».
+- В демо-домене конфликтов нет: охранник на `.link()` снят в 0.20.0, поэтому класс
+  `link`/`связь` (абстрактный корень связок) ходится под любым из двух имён.
+- Список — константа `RESERVED_CLASS_NAMES`; её совпадение с реальными точками перехвата
+  в `chain.ts` (и `case`-метки, и ранние `if (prop === …)`) проверяет
+  `scripts/check-docs.mjs`, а `gen-types` не выдаёт таких шагов в типы.
+
 ### 3.1 Концы связей — Schema.links v2
 
 Каждый конец — объект (`Schema.links jsonb` — массив объектов):
@@ -358,6 +417,32 @@ v7-классы (Org/Staff/Customer/Location/Schedule/Folder) наследуют
 наследуется так же — дефолт объявляется один раз на корне иерархии; `links` НЕ наследуются:
 концы объявляет каждый класс сам. Валидатор и типы полей компилируются из слитых attributes.
 
+**Чтение ПОЛИМОРФНО: шаг по родителю отдаёт объединение с потомками любой глубины** —
+как и права ACL наследуются по иерархии (§ 9.2). Абстрактные классы благодаря этому
+перестают быть пустыми: `db.Контрагент()` → `Мастер` + `Клиент`, `db.связь()` → все
+классы-связки, `db.Сущность()` → всё дерево. Уникальность сущности в таких выборках —
+пара `(class, id)`; `Row.class` показывает конкретный класс строки.
+
+**`.exact()` — только свой класс, без потомков.** Нужен, когда наследование в домене
+использовано для переиспользования `attributes`, а не как «is-a» для выборки: в демо
+`запись` наследует `окно` (интервал и правило v5-id), но смена ≠ бронь, поэтому
+«смены мастера» — `db.Мастер(id).окно().exact()`, иначе в выдачу попадут и записи.
+
+```ts
+await db.Контрагент().count()            // Мастера + Клиенты
+await db.Контрагент().exact().count()    // 0 — abstract-класс своих строк не имеет
+await db.Мастер(id).окно().exact().rows()  // именно смены, без броней
+```
+
+**Запись полиморфной НЕ бывает**: `create()` пишет строго в свой класс, в abstract —
+ошибка `class "X" is abstract`. `update()`/`delete()`/`purge()` версионируют/сносят
+то, что нашёл путь, — каждую строку в её собственном классе.
+
+Права ACL проверяются **по конкретному классу каждой строки**: запрещённый потомок
+выпадает из выборки по родителю (deny на `Customer` не обходится шагом `db.Контрагент()`),
+у каждого разрешённого класса действует его собственный row-предикат. Если запрещено
+всё семейство — отказ шага целиком.
+
 ### 3.4 Примеры схем из таблицы `Schema`
 
 Демо-домен booking — **20 классов** в `lib/sql/seed.booking.sql` (**источник правды**:
@@ -644,7 +729,7 @@ import { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends,
 ### Модификаторы цепочки
 
 ```ts
-db.окно().sort('data.start_datetime').limit(10).offset(20).rows()   // выборка
+db.окно().exact().sort('data.start_datetime').limit(10).offset(20).rows()   // выборка (exact: смены без броней)
 db.запись().sort('updated', 'desc').limit(50).rows()
 
 db.Клиент().tags('vip')                     // фильтр: tags ⊇ ['vip']
@@ -661,8 +746,9 @@ db.Мастер({…}).alias('Исполнитель')         // ключ ша
 | `asOf(t)` | вся цепочка | «как было на T» (§ 10.1) | — |
 | `after(cursor)` | вся цепочка | keyset-пагинация, требует `sort` (§ 10.2) | — |
 | `deep(max?)` | текущий шаг (self-hop) | рекурсивные дети, `$depth` (§ 10.4) | — |
+| `exact()` | текущий шаг | снять полиморфизм: только свой класс, без потомков (§ 3.3) | — (запись и так строго по своему классу) |
 | `tags(v)` | текущий шаг | фильтр по колонке | **значение** тегов при `create()` (string \| string[]) |
-| `account(v)` / `owner(v)` | текущий шаг | фильтр по колонке | **значение** при `create()` |
+| `account(v)` / `owner(v)` | текущий шаг | фильтр по колонке | **значение** при `create()`; арендатор всей цепочки — не здесь, а `db.as()` (§ 10.6) |
 | `.Класс.set(x)` / `.Класс.unset()` | слот связи — после глагола записи | — | записать / снять конец связи БЕЗ участия в фильтре целей (§ 6.1) |
 | `alias(name)` | текущий шаг | ключ в путях | — |
 
@@ -789,6 +875,10 @@ await db.Клиент(cid).purge().rows()                    // превью з
 await db.Клиент(cid).purge({ confirm: true }).rows()   // 2) физически: tombstone + всё поддерево (все версии)
 ```
 
+> **⚠ На живой сущности `.purge()` возвращает `[]` — БЕЗ ошибки.** Гейт двухфазный: пустой
+> результат значит «нечего стирать, сначала `.delete({confirm:true})`», а НЕ «стёрто».
+> Не считайте `[]` подтверждением: проверяйте `.withDeleted().first()` → `null`.
+
 **Двухфазно:** `.purge()` работает ТОЛЬКО по уже логически удалённому (tombstone) — живую сущность
 не трогает (сначала `.delete()`). Историю, в отличие от `.delete()`, НЕ сохраняет. Внутри — серверная
 `purge(partition,class,id)`: `SET LOCAL letopis.purge='on'` отключает append-only-триггер (через `WHEN`)
@@ -878,7 +968,8 @@ await db.rules.set({ account: 'authenticated:ACCOUNT', resource: 'shop:API', per
 ```
 
 Связка с Entity: `account`/`owner` NOT NULL, default — System-аккаунт; фильтры и значения —
-модификаторы `.account()/.owner()`; профиль владельца — `db.accounts.get(row.owner)`.
+хендл `db.as(account, { owner })` (§ 10.6) либо точечные модификаторы `.account()/.owner()`;
+профиль владельца — `db.accounts.get(row.owner)`.
 Сид `lib/sql/seed.auth.sql`: System + 16 Resource + 12 Rule.
 
 ### 9.1 Вход: `db.auth` — много кредов на аккаунт
@@ -996,13 +1087,15 @@ await db.acl.checkData(user, 'Org', 'READ')
 db.acl.reload()                                     // сброс кэша Resource/Rule фасада
 ```
 
-**`connect({ account, enforceAcl: true })`** — те же решения в цепочках: каждый шаг —
+**`connect({ enforceAcl: true })` + `db.as(субъект)`** — те же решения в цепочках: каждый шаг —
 `READ`, `create()`/`update()`/anonymize/батчи — `WRITE`, `delete()` — `DELETE` **по всем классам каскада**
 (deny в замыкании откатывает транзакцию); `watch()` отдаёт события только безусловных
-allow-классов (payload нечем проверить предикат). Правила фиксируются на connect.
+allow-классов (payload нечем проверить предикат). Субъекта даёт `db.as()`: правила снимаются
+и компилятся в memo-резолвер **на каждый scope** (у своего аккаунта — свой резолвер, ключ memo
+субъекта не содержит); правки `Resource`/`Rule` подхватывает `db.reloadSchema()` (§ 11.10).
 
 ```ts
-const u = await connect({ dsn, schema, account: user.id, enforceAcl: true })
+const u = await (await connect({ dsn, schema, enforceAcl: true })).as(user.id)
 await u.запись().rows()      // [7.6 ms] только owner = user.id — предикат в WHERE заранее
 await u.запись().count()     // честный count по суженному множеству
 await u.Организация().rows() // Error: letopis: acl denies READ on Org — no matching rule
@@ -1012,22 +1105,27 @@ await u.запись(чужаяId).update({ notes: '…' }).rows()     // → []
 // create той же v5-пары (id чужой записи) тоже НЕ перехватывает: → [] вместо новой версии
 ```
 
-Оверхед (полигон `v1.salondemo` ~980k, booking 440k×2; p50 из 20; `bench/acl.bench.mjs`):
+Оверхед (полигон `v1.salondemo` ~980k, booking 440k×2; p50 из 20; `bench/acl.bench.mjs`;
+все три хендла с `enforceAccount: false` — мерится цена **авторизации**, изоляция арендатора
+считается отдельно в § 10.6; полигон **проанализирован**, см. § 14.1):
 
 | Сцена | без ACL | allow (класс целиком) | allow с предикатом* |
 |---|---|---|---|
-| точечный `first(id)` | 2.9 ms | 4.2 ms | 6.1 ms |
-| фильтр `rows` limit 100 | 1394 ms | 1454 ms | 1362 ms |
-| keyset-страница всего класса 440k | 5495 ms | 5576 ms | 5364 ms |
-| `count()` класса 440k | 3196 ms | 3049 ms | 2874 ms |
-| цепочка `запись(id).Услуга()` | 5.5 ms | 6.6 ms | 5.1 ms |
-
-Безусловное правило — бесплатно (решение из кэша, SQL тот же). *Предикат здесь на
-селективности 100% (все строки booking — System-аккаунт, предикат никого не отсекает) —
-на тяжёлых сценах ACL в пределах шума с базой; в реальности предикат СУЖАЕТ выборку,
-и такие сцены становятся ДЕШЕВЛЕ, чем без ACL.
-`db.acl.checkData` — справочный (1.0 ms: SQL за категориями аккаунта на каждый вызов);
-горячий путь цепочек использует резолвер, скомпилированный на connect (микросекунды, memo).
+| точечный `first(id)` | 4.5 ms | 4.7 ms | 4.6 ms |
+| фильтр `rows` limit 100 | 10.9 ms | 11.1 ms | 11.4 ms |
+| keyset-страница всего класса 440k | 5425 ms | 5146 ms | 5305 ms |
+| `count()` класса 440k | 1373 ms | 1262 ms | 1392 ms |
+| цепочка `запись(id).Услуга()` | 6.0 ms | 6.4 ms | 5.8 ms |
+
+**ACL бесплатен на всех сценах** — отличия в пределах шума измерения (местами колонка с ACL
+даже «быстрее» базы). Решение берётся из memo, SQL безусловного правила совпадает с базовым.
+*Предикат здесь на селективности 100% (все строки booking — System-аккаунт, предикат никого
+не отсекает); в реальности он СУЖАЕТ выборку, и такие сцены становятся ДЕШЕВЛЕ, чем без ACL.
+`db.acl.checkData` — справочный (1.7 ms: SQL за категориями аккаунта на каждый вызов);
+горячий путь цепочек использует резолвер, скомпилированный при `db.as()` (микросекунды, memo).
+Цена самого `db.as()` под `enforceAcl` — один параллельный запрос за аккаунт + Resource/Rule
+(≈ те же 50 ms, что раньше платил `connect`), поэтому scope стоит держать на запрос, а не на
+цепочку. Без `enforceAcl` `db.as()` бесплатен: клон контекста, без SQL и без нового соединения.
 
 `enforceAccount` (§ 10.6) остаётся простым флагом-изоляцией без таблиц правил.
 
@@ -1080,7 +1178,7 @@ const стр2 = await db.запись().sort('updated', 'desc') //  можно
   .after(кур).limit(50).rows()
 
 // по data-пути ЛЮБОЙ глубины — field тот же, что в sort
-const дальше = await db.окно().sort('data.start_datetime')
+const дальше = await db.окно().exact().sort('data.start_datetime')
   .after(cursorOf(окно, 'data.start_datetime')).limit(20).rows()
 
 // бесконечная лента: .after(undefined) не добавляет условия — один код для всех страниц
@@ -1106,7 +1204,7 @@ do {
 await db.цена().sum('data.amounts.RUB')      // сумма всех прайсов (record-лист): number | null
 await db.Услуга().avg('data.duration')       // среднее
 await db.Услуга().countBy('data.duration')   // { '30': 2, '60': 1 } ({} на пустом)
-await db.окно().min('data.start_datetime')   // min/max — каст по типу поля из Schema
+await db.окно().exact().min('data.start_datetime')   // min/max — каст по типу поля из Schema
 ```
 
 Один проход в БД вместо перекачки строк в JS. Путь — `'data.<поле>'` или вложенный лист
@@ -1147,18 +1245,54 @@ const stop = await db.watch('запись', onEvent, {
 })
 ```
 
-### 10.6 Изоляция арендатора: `enforceAccount`
+### 10.6 Изоляция арендатора: `db.as()` + `enforceAccount`
+
+**Арендатор — свойство ВЫЗОВА, а не подключения.** Один пул обслуживает разных арендаторов,
+поэтому в `connect()` опции `account` нет: подключение безличное, а имя даёт `db.as(account)` —
+хендл того же пула, работающий от имени этого аккаунта.
 
 ```ts
-const db = await connect({ dsn, schema, account: tenantId, enforceAccount: true })
-await db.запись().rows()                 // ТОЛЬКО строки этого account (фильтр на каждом шаге)
-await db.Клиент().create({ name: 'X', phone: '+7…' })  // запись пришпилена к account
-db.запись().account(чужой).rows()        // ошибка: reads are pinned to account …
+const db = await connect({ dsn, schema })          // пул; enforceAccount по умолчанию TRUE
+const t  = await db.as(tenantId)                   // идентичность вызова (в вебе — на запрос)
+
+await t.запись().rows()                  // ТОЛЬКО строки этого account (фильтр на каждом шаге)
+await t.Клиент().create({ name: 'X', phone: '+7…' })  // запись пришпилена к account
+await t.запись().account(чужой).rows()   // ошибка: reads are pinned to account …
+
+await db.запись().rows()                 // ошибка: enforceAccount is on — call db.as(account) …
 ```
 
 Изоляцию гарантирует либа, а не дисциплина: забытый `.account()` в одном запросе
-больше не утечка данных соседнего салона. Это простой флаг «всё по одному арендатору»;
-гранулярные права (по классам, операциям, со срезами строк правилами) — ACL § 9.2.
+больше не утечка данных соседнего салона, а забытый `db.as()` — не тихая выдача всего, а
+внятная ошибка. Это простой флаг «всё по одному арендатору»; гранулярные права (по классам,
+операциям, со срезами строк правилами) — ACL § 9.2 (субъекта ему даёт тот же `db.as()`).
+
+`db.as()` дешёв: клон контекста на том же пуле, без нового соединения и без SQL (под
+`enforceAcl` — плюс компиляция правил под этого субъекта, § 9.2). Хендлы можно держать
+сколько нужно, `close()` зовётся один раз на пул. Второй аргумент задаёт `owner` новых
+строк: `db.as(account, { owner })` (по умолчанию `owner` = `account`).
+
+**Цена изоляции — отрицательная в реальной многоарендаторной базе.** Предикат `account`
+попадает не только в перепроверку, но и в подзапрос кандидатов, то есть **сужает выборку по
+индексу до основного скана**. Замерено на полигоне из 10 арендаторов (1 млн версий, класс
+`Customer`, `count()` — с сужением против без него):
+
+| Доля арендатора в классе | с сужением | без сужения |
+|---|---|---|
+| 50 % | 936 ms | 800 ms |
+| 10 % | 314 ms | 785 ms |
+| 1 % | 87 ms | 800 ms |
+| 0.3 % | 28 ms | 773 ms |
+
+Чем мельче арендатор, тем больше выигрыш: на 0.3 % класса изоляция ускоряет чтение в **27 раз**.
+Проигрывает она только в вырожденном случае, когда один арендатор владеет почти всем классом
+(на `v1.salondemo` System владеет 100 %, и там `count()` под изоляцией — 2.6 с против 1.3 с).
+Вывод практический: чем больше у вас арендаторов, тем выгоднее держать изоляцию включённой.
+Оба замера сняты на проанализированной базе — без `ANALYZE` эта же сцена давала 54 с (§ 14.1).
+
+Административный доступ (миграции, дев-скрипты, отчёты по всем арендаторам) — явным
+`connect({ …, enforceAccount: false })`: там `db` читает и пишет без scope, а колонку
+`account` закрывает System-аккаунт схемы.
 
 ### 10.7 Анонимизация (GDPR): `.anonymize()`
 
@@ -1276,7 +1410,7 @@ deadlock detected — letopis: transaction is aborted, retry the whole db.begin(
 **живой прогон** на едином полигоне `v1.salondemo` ~980 000 строк Entity (год окон-смен и
 записей: 440 000 записей-наследников окон ×2 версии, каталог из 600 услуг, 360 мастеров,
 40 000 клиентов, 1026 цен, 1260 навыков); воспроизводитель — `bench/api-reference-demo.mjs` (только
-читает полигон salon-seed, мутирует лишь свои сущности). Тот же полигон — под статьёй SALON.md.
+читает полигон salon-seed, мутирует лишь свои сущности).
 id сокращены: `…0911` = `00000000-0000-4000-8000-000000000911`; повторяющиеся
 `account`/`owner`/`partition` в ответах опущены.
 
@@ -1297,21 +1431,23 @@ id сокращены: `…0911` = `00000000-0000-4000-8000-000000000911`; по
 | `opts.dsn` | `string` | — | строка подключения `postgres://user:pass@host:port/db` |
 | `opts.schema` | `string` | — | ПОЛНОЕ имя PG-схемы с версией движка: `'v1.booking'` (создаёт `up({schema: 'booking', version: 1})` либо `db/apply.mjs --schema=booking --version=1`; либа префикс не достраивает) |
 | `opts.partition` | `string?` | `'entity'` | партиция данных: все чтения/записи этого подключения живут в ней |
-| `opts.account` | `uuid?` | System-аккаунт схемы | default-`account` (арендатор) новых строк |
-| `opts.owner` | `uuid?` | = `account` | default-`owner` (владелец) новых строк |
 | `opts.max` | `number?` | `10` | размер пула соединений postgres.js |
-| `opts.enforceAccount` | `boolean?` | `false` | жёсткая изоляция арендатора (§ 10.6): каждый шаг чтения фильтруется `account = opts.account`, записи пришпилены; явный чужой `.account()` — ошибка |
-| `opts.enforceAcl` | `boolean?` | `false` | ACL по Resource/Rule (§ 9.2): READ на каждый шаг, WRITE/DELETE на записи, предикаты строк в SQL заранее; **требует `account`**; deny-by-default |
+| `opts.enforceAccount` | `boolean?` | **`true`** | жёсткая изоляция арендатора (§ 10.6): каждый шаг чтения фильтруется по `account` scope-хендла, записи пришпилены; явный чужой `.account()` — ошибка; чтение/запись **с безличного корня — ошибка** с подсказкой на `db.as()` |
+| `opts.enforceAcl` | `boolean?` | `false` | ACL по Resource/Rule (§ 9.2): READ на каждый шаг, WRITE/DELETE на записи, предикаты строк в SQL заранее; субъект — аккаунт `db.as()`; deny-by-default. Выключенный печатает предупреждение один раз на процесс |
 | `opts.onQuery` | `((e: QueryEvent) => void)?` | — | хук на каждый запрос цепочки: `{mode, classes, ms, rows, slow}` (§ 10.10) |
 | `opts.slowMs` | `number?` | — | порог медленного запроса: `ms > slowMs` → `e.slow = true`; если `onQuery` не задан — `console.warn` |
 
 **Назначение и алгоритм.** Открывает пул postgres.js (timestamptz парсится **строкой**,
 чтобы не терять микросекунды в `asOf`/курсорах), одним SELECT загружает реестр классов из
 `Schema` (компилируя fastest-validator на класс), резолвит System-аккаунт как fallback для
-NOT NULL `Entity.account`. При `enforceAcl: true` дополнительно параллельно читает аккаунт,
-все Resource и включённые Rule и **компилирует синхронный резолвер решений** (класс,
-операция) → `AclDecision` с memo — правила фиксируются на весь срок жизни подключения.
-Реестр классов тоже фиксируется: новый класс в `Schema` увидит только новый `connect()`.
+NOT NULL `Entity.account`. Подключение **безличное**: арендатора и субъекта ACL называет
+`db.as(account)` (§ 10.6) — опций `account`/`owner` в `ConnectOpts` нет. При `enforceAcl: true`
+каждый `db.as()` параллельно читает свой аккаунт, все Resource и включённые Rule и
+**компилирует синхронный резолвер решений** (класс, операция) → `AclDecision` с memo.
+Реестр классов снимается один раз на `connect()` — но НЕ до конца жизни подключения: правки
+в `Schema` / `Resource` / `Rule` подхватываются `db.reloadSchema()` без реконнекта (со
+scope-хендла пересобирает и реестр, и его ACL-резолвер — [§11.2](#112-entitydb--корень)).
+Реконнект нужен только для смены `dsn`/`schema`/`partition` и флагов `enforce*`.
 
 **Примеры**
 
@@ -1325,26 +1461,62 @@ await dbSlow.запись().count()   // ~440k сущностей — дольш
 // {"mode":"count","classes":["booking"],"ms":3191.0,"rows":1,"slow":true}
 ```
 
-**Кейс: три подключения — обычное, изолированное, под ACL**
+**Кейс: три хендла — админский, изолированный, под ACL**
 
 ```ts
-const db  = await connect({ dsn, schema })                                        // [33.6 ms]
-const iso = await connect({ dsn, schema, account: acc.id, enforceAccount: true }) // [40.2 ms]
-const uc  = await connect({ dsn, schema, account: acc.id, enforceAcl: true })     // [54.7 ms]
-await db.Организация().count()    // → 30   — видит всех
+const db  = await connect({ dsn, schema, enforceAccount: false })                    // [32.6 ms]
+const iso = await (await connect({ dsn, schema })).as(acc.id)                        // [55.3 ms]
+const uc  = await (await connect({ dsn, schema, enforceAcl: true })).as(acc.id)      // [58.1 ms]
+await db.Организация().count()    // → 30   — админский видит всех
 await iso.Организация().count()   // [5.1 ms] → 1 — только свой арендатор
 await uc.Организация().rows()
 // Error: letopis: acl denies READ on Org — no matching rule (deny by default)
 await iso.close(); await uc.close()
 ```
 
+#### `uuidv5(name: string, ns = LETOPIS_NS): string` · `uuidv7(): string` · `LETOPIS_NS`
+
+| Экспорт | Тип | Описание |
+|---|---|---|
+| `uuidv5` | `(name: string, ns?: string) => string` | детерминированный (sha1) id из имени в пространстве `ns` |
+| `uuidv7` | `() => string` | time-ordered: старшие биты — метка времени (мс), дальше random |
+| `LETOPIS_NS` | `string` | пространство имён либы: `c7a2f9d4-3b61-4e8a-9f05-8d2c1e6b7a90` |
+
+**Назначение и алгоритм.** Это не хелперы «на всякий случай», а **публичный контракт**:
+для класса с `attributes.id = {type:'uuid', generate:5, from:[…]}` id считает схема, и
+формула открыта — тот же id можно получить на клиенте **до** записи (идемпотентный
+`create()`, проверка «занято ли» точечным `first()`, advisory-lock по будущему id).
+Строка-имя собирается так (`from` — в порядке объявления; конец связи → id цели,
+скалярное поле → его значение):
+
+```
+uuidv5(`${pgSchema}:${partition}:${class}:${from₁}:${from₂}:…`, LETOPIS_NS)
+```
+
+**Любое** изменение имени PG-схемы, партиции, id класса или ПОРЯДКА `from` даёт другой id —
+это часть контракта данных, менять как breaking-change (бамп `version` схемы).
+
+**Примеры**
+
+```ts
+import { uuidv5, uuidv7, LETOPIS_NS } from 'letopis'
+
+// id записи известен ДО создания: v5(Мастер, старт) — двойная бронь мертва самим id (§ 3.2)
+const bId = uuidv5(`v1.booking:entity:booking:${иван.id}:2026-08-01T07:00:00Z`)
+await db.запись(bId).first()          // «занято?» — точечно, без обхода
+uuidv5('x') === uuidv5('x', LETOPIS_NS)   // → true: ns по умолчанию
+uuidv7()                                   // → '0199f3c1-…' — сортируемый по времени
+```
+
+Полный разбор правил генерации (v4 / v7 / v5, наследование правила) — [§ 3.2](#32-id-считает-схема-attributesid).
+
 ### 11.1a up(opts)
 
 #### `up(opts: UpOpts): Promise<EntityDb>`
 
 | Параметр | Тип | Default | Описание |
 |---|---|---|---|
-| `opts.dsn` | `string?` | `postgres://postgres:test@localhost:15432/letopis` | строка подключения; хост не `localhost` → docker-шаги пропускаются (только ожидание готовности) |
+| `opts.dsn` | `string?` | `postgres://postgres:test@localhost:15432/letopis` | строка подключения. Docker-шаги решает **живая проба**, не имя хоста: postgres по `dsn` уже отвечает → контейнер не поднимается (`postgres is up … — docker skipped`), базы нет → создаётся. Контейнер создаётся только если проба не прошла И хост локальный; для нелокального хоста — только ожидание готовности |
 | `opts.schema` | `string` | — | **базовое** имя схемы БЕЗ версии и точек (`'booking'`) |
 | `opts.version` | `number` | — | версия движка, целое ≥ 1: итоговая PG-схема `"v<N>.<schema>"`; бамп руками при breaking-изменении DDL |
 | `opts.container` | `string?` | `'letopis-timescale'` | имя dev-контейнера |
@@ -1355,7 +1527,7 @@ await iso.close(); await uc.close()
 | `opts.fresh` | `boolean?` | `false` | дропнуть схему и накатить заново — **данные схемы теряются** |
 | `opts.quiet` | `boolean?` | `false` | без `[letopis.up]`-прогресса в консоли |
 | `opts.waitTimeoutMs` | `number?` | `120 000` | максимум ожидания готовности (первый запуск: pull образа + initdb) |
-| …остальные | `ConnectOpts` | — | `partition`/`account`/`enforceAcl`/`onQuery` и все опции `connect()` прокидываются насквозь |
+| …остальные | `ConnectOpts` | — | `partition`/`enforceAccount`/`enforceAcl`/`onQuery` и все опции `connect()` прокидываются насквозь; возвращённый `db` — такой же безличный корень (арендатора даёт `db.as()`, § 10.6) |
 
 **Назначение и алгоритм.** Одна точка входа: от пустой машины до готового `db`.
 (1) **Probe**: одна попытка `SELECT 1` по `dsn` — живой postgres (свой контейнер, CI-сервис,
@@ -1439,9 +1611,40 @@ import type {
 ### 11.2 EntityDb — корень
 
 `EntityDb` — Proxy: любое имя класса из `Schema` (id или алиас) — метод старта цепочки;
-плюс фиксированные члены `begin/commit/rollback/batch/watch/close/registry/sql` и фасады
+плюс фиксированные члены `as/begin/commit/rollback/batch/watch/close/registry/sql` и фасады
 `accounts/credentials/resources/rules` (§ 11.8), `auth` (§ 11.9), `acl` (§ 11.10).
 
+#### `db.as(account: uuid | { id }, opts?: { owner? }): Promise<EntityDb>`
+
+| Параметр | Тип | Default | Описание |
+|---|---|---|---|
+| `account` | `uuid \| { id }` | — | арендатор/субъект ЭТОГО вызова; пустое значение — ошибка `db.as(account) requires an account id` |
+| `opts.owner` | `uuid?` | = `account` | значение колонки `owner` для новых строк этого scope |
+
+**Назначение и алгоритм.** Возвращает хендл **того же пула**, работающий от имени `account`:
+арендатор — свойство вызова, не подключения (в `connect()` опции `account` нет). Клонирует
+контекст (как `db.begin()`), нового соединения не открывает; под `enforceAcl` дополнительно
+читает аккаунт + Resource/Rule и компилирует резолвер **под этого субъекта** — у каждого scope
+свой, решения между арендаторами не переиспользуются. Батчи со корня не наследуются: очередь
+планов, общая для разных арендаторов, была бы утечкой записи. `close()` закрывает пул, поэтому
+зовётся один раз — и с корня, и с любого scope (это одно и то же соединение).
+
+Под `enforceAccount` (default `true`) чтение/запись возможны **только** с такого хендла:
+с безличного корня — ошибка с подсказкой (§ 10.6). В вебе scope живёт на запрос:
+`const t = await db.as(req.accountId)`.
+
+**Примеры**
+
+```ts
+const db = await connect({ dsn, schema })
+const t1 = await db.as(salon1)
+const t2 = await db.as(salon2, { owner: managerId })
+await t1.Клиент().count()      // только клиенты salon1
+await t2.Клиент().create({ name: 'X', phone: '+7…' }).rows()  // account = salon2, owner = managerId
+await db.Клиент().count()      // Error: enforceAccount is on — call db.as(account) …
+await db.close()               // один раз на пул
+```
+
 #### `db.<Класс>(filter?: Filter): Chain`
 
 | Параметр | Тип | Описание |
@@ -1873,6 +2076,33 @@ for (;;) {
 }
 ```
 
+#### `.exact(): Chain`
+
+Параметров нет.
+
+**Назначение и алгоритм.** Снимает полиморфизм ТЕКУЩЕГО шага: в SQL уходит
+`class = '<свой>'` вместо `class = ANY('<свой>' + descendants)`. Нужен, когда наследование
+в домене — переиспользование `attributes`, а не «is-a» для выборки (§ 3.3). На классе без
+потомков — no-op. На запись не влияет: `create()` всегда пишет строго в свой класс.
+
+**Примеры**
+
+```ts
+await db.Контрагент().count()             // → 40367  Мастера + Клиенты (полиморфно)
+await db.Контрагент().exact().count()     // → 0      abstract-класс своих строк не имеет
+await db.окно().count()                   // → 494008 смены + записи-наследники
+await db.окно().exact().count()           // → 54005  именно смены
+await db.Мастер(и).окно().exact().rows()  // смены мастера, без его броней
+```
+
+**Кейс: «занят ли мастер»** — смены и брони живут в одной иерархии, поэтому проверка
+доступности всегда берёт `.exact()` на окне и отдельный шаг на записи:
+
+```ts
+const смены = await db.Мастер(и).окно().exact().rows()   // интервалы доступности
+const брони = await db.Мастер(и).запись().rows()         // что уже занято
+```
+
 #### `.deep(max = 32): Chain`
 
 | Параметр | Тип | Описание |
@@ -1995,9 +2225,11 @@ await db.Клиент().tags(hasAny(['vip', 'telegram'])).count()  // [48.4 ms]
 |---|---|---|
 | `v` | `uuid \| { id }` | чтение: фильтр колонки `account`/`owner`; при `create()` — значение колонки |
 
-**Назначение и алгоритм.** Прямое равенство по uuid-колонке (btree). Под `enforceAccount`
-чужой `.account()` — ошибка; под `enforceAcl` конфликт с пришпиленной правилом колонкой —
-ошибка `acl pins` (§ 11.10).
+**Назначение и алгоритм.** Прямое равенство по uuid-колонке (btree). Модификатор патчит
+**только свой шаг** — арендатор всей цепочки задаётся не им, а хендлом `db.as()` (§ 10.6):
+под `enforceAccount` он фильтрует каждый шаг сам, а чужой `.account()` — ошибка `pinned`.
+Под `enforceAcl` конфликт с пришпиленной правилом колонкой — ошибка `acl pins` (§ 11.10).
+Смысл `.account()` остаётся прежним: точечный фильтр/значение на админском хендле.
 
 ```ts
 await db.Организация().account(SYS).count()   // [5.1 ms] → 30
@@ -2577,9 +2809,13 @@ await db.accounts.delete(SYS)      // [6.0 ms]
 Предохранители (до сноса): вызывать может лишь **Owner/System**; нельзя снести **последний enabled Owner**
 (лок-аут тенанта) и **свой** аккаунт сессии.
 
+Вызывать нужно **со scoped-хендла** — предохранители смотрят, кто именно зовёт:
+
 ```ts
-const dbSys = await connect({ dsn, schema: 'v1.notify', account: SYS })
+const dbSys = await (await connect({ dsn, schema: 'v1.notify' })).as(SYS)
 await dbSys.accounts.purge(tenantId)   // → true: Entity + Account + Credential снесены, место освобождено
+// с безличного корня: Error: accounts.purge requires an authenticated caller — call it from
+//                     a scoped handle: (await db.as(caller)).accounts.purge(id)
 ```
 
 #### `db.schema.define(def)` / `db.reloadSchema()` — живой подхват правок схемы
@@ -3151,7 +3387,7 @@ app.use(async (req, res, next) => {
 `booking` действует на `VipBooking`). Победа — как в `check`. У победившего allow остальные
 ключи pattern (реальные колонки Entity, `"$account"` → id субъекта) возвращаются как
 `filter` — готовый предикат строк. Справочный метод (SQL за категориями аккаунта на каждый
-вызов ~1–2 ms); горячий путь цепочек использует резолвер, скомпилированный на connect
+вызов ~1–2 ms); горячий путь цепочек использует резолвер, скомпилированный при `db.as()`
 (микросекунды, memo).
 
 **Примеры**
@@ -3172,33 +3408,44 @@ await db.acl.checkData(acc, 'VipBooking', 'READ')   // [23.4 ms — свежий
 **Кейс: enforceAcl — те же решения в SQL цепочек (реальный прогон)**
 
 ```ts
-const uc = await connect({ dsn, schema, account: acc.id, enforceAcl: true })   // [66.9 ms] правила фиксируются
-await uc.запись().rows()    // [17.2 ms] → 3 Row — предикат owner=$account в WHERE ДО сортировки/лимита
-await uc.запись().count()   // [17.6 ms] → 3 — честный count по суженному множеству
-await uc.Услуга().count()   // [15.1 ms] → 602 — безусловный allow, класс целиком
+// enforceAccount: false — показаны ACL-предикаты, а не изоляция арендатора (§ 10.6)
+const uc = await (await connect({ dsn, schema, enforceAcl: true, enforceAccount: false })).as(acc.id)
+// [58.1 ms] снимок правил под ЭТОГО субъекта (обновить — reloadSchema)
+await uc.запись().rows()    // [12.6 ms] → 3 Row — предикат owner=$account в WHERE ДО сортировки/лимита
+await uc.запись().count()   // [12.5 ms] → 3 — честный count по суженному множеству
+await uc.Услуга().count()   // [11.4 ms] → 605 — безусловный allow, класс целиком
 await uc.Организация().rows()
 // Error: letopis: acl denies READ on Org — no matching rule (deny by default)   [0.3 ms]
 const [z] = await uc.запись().create({ start_datetime: t, end_datetime: e })
-  .Мастер.set(м).Локация.set(л).Расписание.set(р).Услуга.set(у).rows()   // [20.9 ms]
+  .Мастер.set(м).Локация.set(л).Расписание.set(р).Услуга.set(у).rows()   // [16.2 ms]
 z.owner === acc.id   // → true — owner пришпилен правилом
 await uc.запись().owner(SYS).create({ … }).rows()
-// Error: letopis: acl pins booking writes to owner 06d3bbfe-… — на терминале   [2.6 ms]
-await uc.запись('чужой-id').create({ … }).rows()   // [2.0 ms] — перехват чужого id мёртв: v5-класс id не принимает
+// Error: letopis: acl pins booking writes to owner 06d3bbfe-… — на терминале   [1.8 ms]
+await uc.запись('чужой-id').create({ … }).rows()   // [1.6 ms] — перехват чужого id мёртв: v5-класс id не принимает
 // Error: letopis: class "booking" computes id (uuid v5 from Staff, start_datetime) — remove the explicit id
-await uc.запись(свойId).delete({ confirm: true }).rows()   // [30.3 ms] → [{ id: 'ee65244b-…', $deleted: true }]
+await uc.запись(свойId).delete({ confirm: true }).rows()   // [27.8 ms] → [{ id: 'ee65244b-…', $deleted: true }]
 // watch: события только безусловных allow-классов —
 // uc.watch(cb) поймал ['Service']; booking скрыт (предикат не проверить по payload)
 ```
 
 #### `db.acl.reload(): void`
 
-Параметров нет. Сбрасывает кэш Resource/Rule фасада `db.acl` (следующий `check`/`checkData`
-перечитает словарь). На **enforceAcl-цепочки не влияет** — их резолвер скомпилирован на
-connect; подхватить новые правила = новый `connect()`. Реестр классов тоже фиксирован на
-connect — новый класс в lineage-проверках увидит только новое подключение.
+Параметров нет. Сбрасывает кэш Resource/Rule **фасада `db.acl`** (следующий `check`/`checkData`
+перечитает словарь). На **enforceAcl-цепочки не влияет** — это отдельная подсистема.
+
+**Два «reload», разные подсистемы — не путать:**
+
+| Вызов | Что пересобирает | На что НЕ влияет |
+|---|---|---|
+| `db.acl.reload()` | кэш Resource/Rule фасада `db.acl` (`check`/`checkData`) | энфорсер `enforceAcl`-цепочек, реестр классов |
+| `await db.reloadSchema()` | реестр классов из `Schema`; со scope-хендла (`db.as`) — **и** его энфорсер `enforceAcl` (§ 11.2) | кэш фасада `db.acl` (сбрасывать отдельно); энфорсеры ДРУГИХ scope |
+
+Реконнект нужен только для смены `dsn`/`schema`/`partition` и самих флагов `enforce*`
+(сменить арендатора реконнект НЕ требует — это новый `db.as()`).
 
 ```ts
-db.acl.reload()   // [187 µs]
+db.acl.reload()          // [187 µs] — словарь фасада
+await db.reloadSchema()  // классы + энфорсер цепочек, без реконнекта
 ```
 
 **Кейс:** админка сохранила правило → `reload()` в том же процессе, чтобы `check` следующего
@@ -3317,14 +3564,19 @@ AclDecision = { allow, rule?, filter?, code?, message? }         // filter —
 | `duplicate link slot "X"` | один конец задан слотом дважды в одной записи |
 | `set() split into create()/update() (0.16.0)` | старый глагол записи — create() вставляет, update() версионирует найденное |
 | `slot .delete() renamed to .unset() (0.16.0)` | старое имя слот-снятия |
-| `.link() removed (0.15.0)` | снесённый `.link()` — теперь слот `.Класс.set()` |
 | `execute() renamed to run() (0.11.0)` | старое имя терминала путей (и `batch.execute()`) |
 | `plan is queued in the batch — call batch.run()` | терминал на батч-цепочке с операциями |
 | `no path X → Y` / `LINK → LINK …` | недопустимый переход (синхронно при построении цепочки) |
-| `Entity.account is NOT NULL…` | нет account и System-аккаунта |
+| `enforceAccount is on — call db.as(account) to name the tenant of this call…` | чтение/запись с безличного корня при включённой изоляции: назвать арендатора вызова `db.as()` либо взять админский `connect({ enforceAccount: false })` (§ 10.6) |
+| `enforceAccount is on — reads are pinned to account X` / `writes are pinned to…` | `.account(чужой)` на scope-хендле — подменить арендатора нельзя (§ 10.6) |
+| `db.as(account) requires an account id (uuid or { id })` | `db.as()` без аккаунта (пустая строка / объект без `id`) |
+| `enforceAcl is on — call db.as(account) to name the subject` | цепочка под `enforceAcl` без субъекта (§ 9.2) |
+| `Entity.account is NOT NULL…` | нет ни `.account()`, ни scope `db.as()`, ни System-аккаунта в схеме |
 | `violates foreign key constraint "entity_*_fk"` | несуществующий класс/аккаунт; удаление класса с данными |
 | `lock() works only inside db.begin()` | лок вне транзакции |
 | `commit() needs a transaction` | commit на корневом db |
+| `schema "X" has no "Schema" table …` | `connect()` получил БАЗОВОЕ имя (`'booking'`) вместо полного `'v1.booking'` — либа префикс не достраивает; в тексте ошибки перечислены схемы letopis этой БД |
+| `schema "X" has no classes for partition "Y"` | схема есть, но таблица `Schema` пуста для партиции — нужен сид хотя бы одного класса (§ 1.1) |
 | `letopis.up: bad schema name "X"` / `bad version` | `up()`: имя с точкой/версией либо version не целое ≥ 1 |
 | `letopis.up: docker CLI not found…` | `up()`: docker не установлен, а postgres на dsn не отвечает |
 | `letopis.up: postgres not ready in N s…` / `redis not ready` | `up()`: контейнер не поднялся за `waitTimeoutMs` (подсказка: `docker logs`) |
@@ -3345,29 +3597,63 @@ AclDecision = { allow, rule?, filter?, code?, message? }         // filter —
 ## 14. Производительность
 
 Тайминги — живые прогоны демо на ЕДИНОМ полигоне `v1.salondemo` (`bench/salon-seed.mjs`,
-~980 000 строк: 440 000 записей ×2 версии, 600 услуг, 1026 цен, 1260 навыков). Статья
-(`bench/salon-article-demo.mjs`), API Reference (`bench/api-reference-demo.mjs`) и бенчи
-читают один и тот же полигон, мутируя лишь свои демо-сущности:
+980 328 строк: 440 006 записей ×2 версии, 600 услуг, 1026 цен, 1260 навыков; 13 чанков
+гипертаблицы, диапазон `updated` — год). Статья (`bench/salon-article-demo.mjs`), API Reference
+(`bench/api-reference-demo.mjs`) и бенчи читают один и тот же полигон, мутируя лишь свои
+демо-сущности.
+
+> **Цифры привязаны к размеру полигона — при его смене строки надо перемерять.** Тяжёлые сцены
+> линейны по числу строк, а обход графа — ещё и по числу чанков (см. ниже). Пример дрейфа:
+> строка про обход `запись→Мастер` показывала ≈6 с с версии 0.17.0, когда полигон был
+> 250 000 записей / 613 тыс. строк, и переезд на 440 006 записей / 980 328 строк её не обновил —
+> настоящее значение оказалось ≈30 с. Полигон обязан быть проанализирован (§ 14.1).
 
 | Операция | Время |
 |---|---|
-| фильтр/`count()` по каталогу (`ne`/`gt`/`between`/`like`) | 5–8 ms |
-| агрегация каталога `avg`/`min`/`max` | 5–15 ms |
-| `sum('data.amounts.RUB')` (класс цена, 1026 вариантов) | ≈13 ms |
-| `count()`/`rows()` каталога услуг (600) | 7–13 ms |
-| цена `sort('data.amounts.RUB')` + keyset-страница `after(cursor)` | 19–31 ms |
-| цепочка `навык→Услуга`, `count()` путей (1260) | ≈65 ms |
-| `countBy('data.notes')` по 440k записям | ≈3.3 s |
-| `sort('updated','desc').limit` по всему классу записей БЕЗ фильтра | ≈6 s |
-| `count()` всех 440 000 записей БЕЗ фильтра | ≈3.4 s |
-| обход `запись→Мастер` по всему классу записей | ≈6 s |
-| запись новой версии (`create`/`update`), в т.ч. со слотами | 8–21 ms |
-
-Слабое место — выборка/обход **всего класса записей без фильтра** (`DISTINCT ON` по всем
-440 000 сущностям: секунды); лечится селективным фильтром, контекст-шагом или курсором
-(keyset — миллисекунды даже на 440k). Каталог, агрегации и цепочки с фильтром — единицы—десятки ms.
-TOAST-порог (data > 2KB): 0 строк.
-
+| фильтр/`count()` по каталогу (`ne`/`gt`/`between`/`like`) | 4–7 ms |
+| агрегация каталога `avg`/`min`/`max` | 4–8 ms |
+| `sum('data.amounts.RUB')` (класс цена, 1026 вариантов) | ≈9 ms |
+| `count()`/`rows()` каталога услуг (600) | 6–21 ms |
+| цена `sort('data.amounts.RUB')` + keyset-страница `after(cursor)` | ≈17 ms |
+| фильтр `rows` limit 100 по 440k записям (`{notes: …}`) | ≈11 ms |
+| цепочка `навык→Услуга`, `count()` путей (1260) | ≈93 ms |
+| `countBy('data.notes')` по 440k записям | ≈1.9 s |
+| `count()` всех 440 000 записей БЕЗ фильтра | ≈1.4 s |
+| `sort('updated','desc').limit` по всему классу записей БЕЗ фильтра | ≈5.4 s |
+| обход `запись→Мастер` по всему классу записей | ≈30 s |
+| запись новой версии (`create`/`update`), в т.ч. со слотами | 8–25 ms |
+
+Слабое место — выборка/обход **всего класса записей без фильтра**; лечится селективным
+фильтром, контекст-шагом или курсором. Причины у двух худших строк разные:
+
+- `sort(…).limit` по классу (≈5.4 с) — `DISTINCT ON` обязан посчитать актуальную версию для
+  всех 440 000 сущностей прежде, чем сортировать. Упирается в объём, планировщику тут нечего
+  улучшать.
+- обход `запись→Мастер` (≈30 с) — forward-hop идёт коррелированным `JOIN LATERAL`: **одна
+  индексная проба на каждую строку внешнего шага**, и каждая проба обходит ВСЕ чанки
+  гипертаблицы (исключение по времени невозможно — ищем по `id`, не по `updated`). Отсюда
+  модель стоимости: `строки внешнего шага × чанки`. Замерено: одна проба обоих шагов — 0.924 мс
+  и 80 буферов (13 чанков × ~3 страницы × 2 шага), 440k проб → 17.7 млн обращений к буферам.
+
+  Форма запроса при этом **оптимальна**, а не «недоделана» — проверено замерами:
+  PostgreSQL не может её ни раскоррелировать, ни мемоизировать (корреляция сидит внутри
+  подзапроса с `DISTINCT ON`), и дело не в оценке кардинальности: подстановка класса литералом
+  вместо параметра и `SET enable_nestloop = off` план не меняют — `Nested Loop` без `Memoize`,
+  те же 17.7 млн буферов. Некоррелированный join обеих сторон по ключу измерен и оказался
+  **хуже в 18 раз** (561 с, 48.1 млн буферов).
+
+  Лечится не переписыванием запроса, а стороной, с которой начата цепочка:
+  `db.запись(id).Мастер()` — **7.5 мс**, `db.Мастер(id).запись()` — **11.7 мс** против 30 с
+  у `db.запись().Мастер()`. (В самой БД проба ещё дешевле, 0.9 мс; остальное — сборка SQL и
+  разбор ответа в клиенте.)
+
+Каталог, агрегации и цепочки с фильтром — единицы—десятки ms. TOAST-порог (data > 2KB): 0 строк.
+
+- **Цена полиморфизма.** Шаг по родителю сканирует всё семейство, поэтому дороже листа:
+  на том же полигоне `db.окно().exact().count()` ≈ 82 мс (54 008), `db.окно().count()` ≈ 1.6 с
+  (494 018), `db.Контрагент().count()` ≈ 0.23 с (40 371). Класс без потомков идёт быстрым
+  путём (равенство вместо `ANY`) и не дорожает вовсе: `db.Услуга().count()` ≈ 6 мс.
+  Тайминги в таблице выше сняты на классах-листьях и полиморфизмом не затронуты.
 - Containment и обход графа — GIN; операторы — на уже суженном наборе.
 - Начинайте цепочку с самого селективного шага (Организация/Мастер/Клиент, не `запись()`).
 - `count()` считает пути; число сущностей дешевле берётся `ids().length`.
@@ -3379,6 +3665,39 @@ TOAST-порог (data > 2KB): 0 строк.
   `node bench/history.bench.mjs --entities=10000 --versions=100`, оверхед ACL —
   `npx tsx bench/acl.bench.mjs` (таблица в § 9.2).
 
+### 14.1 `ANALYZE` обязателен после массовой заливки
+
+**Все тайминги выше верны только на проанализированной базе.** Без статистики те же запросы
+медленнее на порядок, и это самая дорогая ошибка эксплуатации из всех, что есть в этом
+руководстве.
+
+`Entity` — гипертаблица: строки живут в чанках, у родительской таблицы своих строк нет. Пока
+`ANALYZE` по ней не прошёл, планировщик подставляет дефолт «200 уникальных `id`». Ядро всех
+чтений либы — semi-join с подзапросом кандидатов (`e.id IN (SELECT c.id FROM Entity c WHERE …)`),
+и на оценке 200 вместо сотен тысяч он выбирает `Nested Loop` там, где нужен `Merge Semi Join`.
+
+Замерено на `v1.salondemo` (980k строк), один и тот же запрос:
+
+| Сцена | без статистики | после `ANALYZE` | |
+|---|---|---|---|
+| `count()` класса под изоляцией арендатора | 57.6 s | **3.2 s** | ×18 |
+| фильтр `rows` limit 100 по 440k | 1371 ms | **11 ms** | ×126 |
+| `count()` класса без фильтра | 2981 ms | **1373 ms** | ×2.2 |
+| keyset-страница по классу | 5610 ms | 5425 ms | без изменений |
+
+Выигрывают запросы **с предикатом** — там, где строится подзапрос кандидатов. Полные проходы
+по классу не меняются: они упираются в объём, а не в план.
+
+Статистику `n_distinct` PostgreSQL считает корректно сам (на этом полигоне `-0.35`, то есть
+уникальных `id` ≈ 35% строк — сущность живёт в среднем в трёх версиях). Никаких подсказок
+(`ALTER COLUMN … SET (n_distinct = …)`) добавлять не нужно — нужен сам факт запуска.
+
+- `up()` и `db/apply.mjs` делают `ANALYZE` при накате схемы сами.
+- **Своя массовая вставка — на вас**: после `COPY`, миграции или генератора данных вызовите
+  `ANALYZE "v1.myapp"."Entity"` (на 1 млн строк ≈ 9 с). Автовакуум доберётся сам, но не сразу,
+  и до этого приложение будет работать в разы медленнее без видимой причины.
+- Полезно и после массового `delete`/`purge`: доля живых строк меняется скачком.
+
 ---
 
 ## 15. E2E-пример: барбершоп
@@ -3437,12 +3756,20 @@ await db.запись(bId).delete({ confirm: true }).rows()           // отм
 ## 16. Тесты
 
 ```bash
-cd lib && npm test    # 167/167 тестов против живого docker (timescale + redis), по файлам:
+cd lib && npm test    # весь набор против живого docker (timescale + redis); счёт кейсов — в CHANGELOG
+            #                 актуального релиза. По файлам:
             # acl           — Resource/Rule: маски/weight/deny-by-default, шаблоны строк
-            #                 с $account, enforceAcl (предикаты в SQL, каскад, watch)
+            #                 с $account, enforceAcl (предикаты в SQL, каскад, watch);
+            #                 полиморфное чтение по иерархии + .exact(); deny на потомке
+            #                 не обходится шагом по родителю (проверка на утечку)
             # api-full      — сквозной чек-лист ВСЕХ публичных методов API (15 групп)
             # auth          — db.auth: пароль/api-key/key-secret/TOTP/OTP/link+lookup,
             #                 глобальная идентичность, сессии на живом Redis (expire/revoke)
+            # parity        — паритет клиент ↔ триггер БД: один и тот же кейс исполняется
+            #                 через либу и голым INSERT, оба обязаны решить одинаково
+            #                 (abstract, неизвестный класс, обязательные/optional/союзные
+            #                 концы, посторонняя связь) + закреплена известная асимметрия:
+            #                 валидацию data делает только либа
             # plan          — план-модель: несколько операций, fan-out, self-update,
             #                 превью/confirm delete, ОТКАТ плана, слот-перевес, батч-гард
             # resilience    — ретраи 40P01/40001, реальный deadlock двух транзакций,
@@ -3459,9 +3786,12 @@ cd lib && npm test    # 167/167 тестов против живого docker (t
             #                 свои сиды/seeds:false, автосоздание базы, валидация
             # salon         — ТЕСТ-ПЛАН: имитация салона, ВСЕ 145 публичных API
             #                 (21 акт + матрица покрытия); слоты/pivot/entity
-            # wave2         — asOf/versions, keyset-курсор, gen-types, enforceAccount, anonymize
+            # wave2         — asOf/versions, keyset-курсор, enforceAccount, anonymize; gen-types:
+            #                 форма фасада, слоты, отсутствие снесённых имён + compile-гейт (tsc)
             # wave3         — or/not, агрегации, deep, watch
             # wave4         — compression-политики (чтение сжатого чанка), schema-sync, onQuery
+            # wave5         — физический purge (двухфазность, замыкание, accounts.purge),
+            #                 withDeleted, живой подхват схемы (schema.define/reloadSchema)
 npm run bench   # производительность на 105k строк (§ 14)
 ```