letopis 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,260 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [0.20.0] — 2026-07-29
+
+### Fixed — `ANALYZE` при накате схемы: чтения были медленнее на порядок
+
+`up()` и `db/apply.mjs` теперь вызывают `ANALYZE "<схема>"."Entity"` после наката DDL и сидов.
+
+`Entity` — гипертаблица: строки лежат в чанках, у родительской таблицы своих строк нет. Пока
+`ANALYZE` по ней не прошёл, планировщик берёт дефолт «200 уникальных `id`». Ядро всех чтений
+либы — semi-join с подзапросом кандидатов (`e.id IN (SELECT c.id FROM Entity c WHERE …)`), и на
+такой оценке он выбирает `Nested Loop` вместо `Merge Semi Join`, с уходом хеша и сортировки на
+диск. Замерено на полигоне 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 |
+
+Тайминги README §14 и §9.2 перемерены на проанализированной базе. Своя массовая вставка
+(`COPY`, миграция, генератор) требует `ANALYZE` вручную — это отдельная грабля в
+`AGENT-CHEATSHEET.md` (#17) и новая секция README §14.1.
+
+Заодно вычищен доковый дрейф в §14: строка «обход `запись→Мастер` по всему классу» показывала
+≈6 с с версии 0.17.0, где полигон был 250 000 записей / 613 тыс. строк, и переезд на
+440 006 / 980 328 её не обновил — настоящее значение ≈30 с. Стоимость этой сцены = `строки
+внешнего шага × чанки` (одна проба — 0.924 мс / 80 буферов при 13 чанках), потому что
+forward-hop идёт коррелированным `JOIN LATERAL` с пробой по всем чанкам. Первое объяснение
+в §14 («планировщик недооценивает внешнюю сторону и не ставит `Memoize`») **снято как
+неверное**: подстановка класса литералом и `SET enable_nestloop = off` план не меняют, дело в
+самой форме — корреляция внутри подзапроса с `DISTINCT ON` не раскоррелируется и не
+мемоизируется. Некоррелированный join измерен и хуже в 18 раз (561 с), так что форма
+оставлена как есть; лечится стороной старта цепочки — `db.запись(id).Мастер()` 7.5 мс и
+`db.Мастер(id).запись()` 11.7 мс против 30 с у обхода всего класса.
+
+Попутно исправлен `bench/acl.bench.mjs`: его колонки были несравнимы — `base` шёл без изоляции
+арендатора, а ACL-хендлы с ней, из-за чего бенч приписывал авторизации до 18× чужой цены.
+Теперь все три режима с `enforceAccount: false`, и видно настоящее: **ACL бесплатен на всех
+сценах** (отличия в пределах шума). Цена изоляции измеряется отдельно и зависит от доли
+арендатора в классе — на 10-арендаторном полигоне она ускоряет чтение до 27× (README §10.6).
+
+### BREAKING — арендатор стал свойством ВЫЗОВА: `db.as(account)`, опции `connect({ account })` больше нет
+
+Из `ConnectOpts` **удалены `account` и `owner`**. Аккаунт на подключении — это модель
+«одно соединение = один тенант», а для веб-приложения она неверна: пул общий, арендатор
+меняется от запроса к запросу. Теперь подключение безличное, а идентичность даёт хендл:
+
+```ts
+const db = await connect({ dsn, schema })     // было: connect({ …, account: X })
+const t  = await db.as(accountId)             // стало: имя вызова, хендл того же пула
+await t.Клиент().rows()
+```
+
+`db.as(account, { owner? })` клонирует контекст на **том же пуле** (нового соединения не
+открывает, SQL не шлёт), поэтому его нормально создавать на каждый HTTP-запрос. `close()`
+по-прежнему один на пул. Батчи с корня в scope не наследуются: очередь планов, общая для
+разных арендаторов, была бы утечкой записи.
+
+Под `enforceAcl` **правила компилятся под субъекта scope** — у каждого `db.as()` свой
+энфорсер. Это не оптимизация, а требование корректности: ключ memo в `acl.ts` — «класс +
+операция», без аккаунта, так что переиспользование одного энфорсера двумя арендаторами
+отдало бы второму решения первого. Закреплено тестом (`acl.test.ts`, «memo энфорсера не
+течёт между scope одного пула»); проверено негативно — с общим энфорсером тест падает.
+
+`enforceAccount` — **`true`** по умолчанию: чтения фильтруются по `account` scope-хендла,
+записи к нему пришпилены. Забыть флаг было слишком легко, а цена забывчивости — чужие
+строки в выдаче без всякой ошибки. Теперь и забыть `db.as()` нельзя: с безличного корня
+чтение/запись бросают
+
+```
+letopis: enforceAccount is on — call db.as(account) to name the tenant of this call,
+or connect({ enforceAccount: false }) for admin access
+```
+
+Админским и сервисным подключениям (миграции, отчёты по всем арендаторам, дев-скрипты)
+нужен явный `connect({ …, enforceAccount: false })` — там колонку `account` закрывает
+System-аккаунт схемы, как раньше.
+
+Смысл модификатора `.account()` не изменился: это точечный фильтр/значение одного шага;
+на scope-хендле чужое значение — ошибка `pinned`.
+
+`enforceAcl` остаётся **`false`** (opt-in): включённый по умолчанию deny-by-default без
+настроенных `Resource`/`Rule` давал бы пустые выборки. Вместо смены дефолта `connect()`
+печатает предупреждение один раз на процесс: авторизация не проверяется — это должно быть
+шумно, а не молча.
+
+**Миграция.** `connect({ …, account: X })` → `(await connect({ … })).as(X)`;
+`connect({ …, account: X, owner: Y })` → `.as(X, { owner: Y })`; подключения, которые
+работали без `account` и должны видеть всё, — `connect({ …, enforceAccount: false })`.
+`accounts.purge(id)` требует scoped-хендла: `(await db.as(caller)).accounts.purge(id)`.
+
+### BREAKING — снят охранник `.link()`
+
+`case 'link'` в цепочке удалён. Он затенял **реальный класс схемы**: в демо-домене `link`
+(алиас `связь`) — абстрактный корень всех связок, и `db.Клиент(c).link()` падал
+migration-ошибкой вместо обхода, хотя `db.link()` с корня работал. Теперь имя `link`
+резолвится как класс на всех уровнях; зарезервированных имён 52 (`link` ушло, `as` пришло).
+Совместимость со снесённым в 0.15.0 методом `.link()` принесена в жертву достижимости
+класса — при обращении к нему теперь будет обычная ошибка пути, а не подсказка миграции.
+Остальные migration-охранники (`execute()`, `set(data)`, слот `.delete()`,
+`batch.execute()`) не тронуты: они не затеняют классов.
+
+### Added — тест паритета клиент ↔ триггер БД
+
+`test/parity.test.ts`: правило концов связей реализовано дважды — в plpgsql
+(`entity_check`) и в TypeScript (`write.validate`), и до сих пор ничто не проверяло, что
+реализации не разошлись. Теперь каждый кейс исполняется двумя путями (через либу и голым
+`INSERT` в `Entity`), и утверждается одинаковое решение: abstract-класс, неизвестный
+класс, отсутствующий обязательный конец, посторонняя связь, ключ `links` не-класс,
+союз ролей, отсутствие optional-конца. Тест не привязан к схеме потребителя — проверяется
+само правило, одно для всех схем.
+
+Отдельным кейсом закреплена **известная асимметрия**: валидация данных по `attributes`
+живёт только в либе (fastest-validator нельзя запустить в plpgsql), поэтому голый SQL
+структурный мусор в `data` принимает. Если это изменится — тест упадёт и потребует
+поправить README §2.
+
+### BREAKING — чтение стало полиморфным по иерархии классов
+
+Шаг цепочки по родительскому классу теперь отдаёт **объединение с потомками любой глубины**
+(как и права ACL наследуются по иерархии). Раньше фильтр шёл по точной колонке `class`,
+поэтому abstract-классы молча возвращали пусто, а родитель не видел потомков:
+
+- `db.Контрагент()` (`Person`, abstract): было `0` → стало `Мастер` + `Клиент`;
+- `db.связь()` (`link`, abstract): было `0` → стало все классы-связки;
+- `db.окно()` (`slot`, конкретный, потомок `booking`): в демо-полигоне было `54 005` →
+  стало `494 008`.
+
+**Что нужно проверить в своём коде.** Если наследование у вас — переиспользование
+`attributes`, а не «is-a» для выборки, добавьте **`.exact()`** на шаг: он возвращает
+одиночный класс. Ровно этот случай в демо-домене — `запись` наследует `окно` (интервал и
+правило v5-id), но смена ≠ бронь, поэтому «смены мастера» теперь
+`db.Мастер(id).окно().exact()`. На классе без потомков `.exact()` — no-op.
+
+- **Идентичность сущности в полиморфной выборке — пара `(class, id)`**: `DISTINCT ON`,
+  подзапрос кандидатов и join истории в `versions()` переведены на неё; `Row.class`
+  показывает конкретный класс строки.
+- **Ключи `Entity.links` конкретны**, поэтому обходы (forward/reverse/`deep`) берут ключ
+  из колонки `class` строки, а не из литерала родителя.
+- **ACL решается по конкретному классу каждой строки.** `deny` на потомке больше не
+  обходится шагом по родителю: запрещённые классы выпадают из выборки, у каждого
+  разрешённого действует его собственный row-предикат; отказ шага целиком — только если
+  запрещено всё семейство. Покрыто `test/acl.test.ts` (2 новых теста).
+- **Запись полиморфной не бывает**: `create()` пишет строго в свой класс (в abstract —
+  `class "X" is abstract`); `update()`/`delete()`/`purge()` работают со строками в их
+  собственных классах.
+- `exact` добавлено в зарезервированные имена классов (52).
+
+Ревизия документации на пригодность для ИИ-агента: устранён дрейф между доками и кодом,
+добавлен агентский слой и автопроверки, чтобы дрейф не возвращался.
+
+### Fixed — кодоген `scripts/gen-types.mjs` выдавал мёртвый API
+
+- Фасад `TypedChain` содержал **`execute()`** (снесён в 0.11.0) и **старый глагол записи
+  `set(data)`** (снесён в 0.16.0) — оба бросают в рантайме; не было `run`/`create`/`update`/
+  `purge`/`withDeleted`/`deep`/агрегаций/слотов. Индекс-сигнатура `[className: string]: unknown`
+  глушила любую ошибку компилятора. Слот-сеттер `.Класс.set(target)` — жив, он ни при чём.
+- `attributes` **не наследовались** по `ancestors`: `StaffData` шёл без `name`/`phone`
+  от `Person`, т.е. сгенерированные типы отвергали код из README §15.
+- Теперь: полная поверхность `ChainCore`, шаги по классам типизированы (опечатка в имени
+  класса — ошибка компиляции), слоты выведены из `Schema.links` (`unset()` только у optional),
+  два фасада — `TypedDb` (строгий) и `TypedFullDb` (+ `begin`/`batch`/`auth`/`acl`/таблицы).
+- Гвард: `test/wave2.test.ts` проверяет форму фасада, отсутствие снесённых имён и
+  **компилирует** сгенерированный `.d.ts` (валидный код проходит, `set()`/`execute()`/
+  опечатки — ошибка `tsc`).
+
+### Added — зарезервированные имена классов
+
+- **52 имени** разбирается Proxy до резолва класса, причём в двух формах: `case`-метки
+  switch'ей (`count`, `sort`, `account`, `as`, `set`, `size`, …) **и** ранние `if (prop === …)`
+  — гашение `then` во всех трёх Proxy и фасады корня `db` (`schema`, `auth`, `acl`, `accounts`,
+  `credentials`, `resources`, `rules`). Класс с таким `id`/`alias` недостижим как шаг под этим
+  именем; раньше это нигде не было записано, хотя коллизия живёт в самом демо-сиде (класс `link`).
+- `RESERVED_CLASS_NAMES` / `reservedNamesOf()` в `types.ts`; `db.schema.define()` **отказывает**
+  на таком имени; `loadRegistry` предупреждает (один раз на схему+класс за процесс, не throw —
+  иначе демо-сид ронял бы `up()`); `gen-types` не выдаёт таких шагов; таблица в README §3.
+
+### Added — агентский слой и автопроверки
+
+- **`scripts/check-docs.mjs`** (`npm run check:docs`, шаг в CI после typecheck) — 8 проверок:
+  версия ↔ CHANGELOG, мёртвые ссылки, список тестов в README §16, счётчики классов в сидах,
+  codescribe-целостность (парность маркеров, `M-*` ↔ файл, `M-*` → `V-M-*`), актуальность
+  `docs/api-contract.json`, зарезервированные имена (код ↔ константа ↔ README), синтаксис и
+  импорты `bench/*.mjs`. БД не нужна.
+- **`scripts/gen-api-contract.mjs`** → `docs/api-contract.json`: машиночитаемый контракт
+  (экспорты, поверхность цепочки, снесённые имена с версией и заменой, каталог ошибок,
+  зарезервированные имена). Генерируется из исходников, `--check` падает при устаревании.
+- Корневой `README.md`, `AGENT-CHEATSHEET.md` (рабочий цикл + 18 граблей), `LICENSE` (MIT),
+  `engines: node >= 20`, таблица статусов корневых доков в `AGENTS.md`.
+- Шпаргалка проверена двумя приёмочными прогонами «агент видит только её»: первый дал
+  3 падения рантайма и 4 пробела, после правок второй прошёл сценарий с первого раза без
+  ошибок и догадок. Закрыто по итогам: шаблон сида с маркером `<SCHEMA-NAME>` и точными
+  колонками (`Account.categories text[]`, а не `category` — было написано неверно), форма
+  `Row` (атрибуты в `row.data`, иначе молчаливый `undefined`), определение LINK-класса и его
+  концов, таблица фасадов `db`, `fastest-validator` как язык `attributes`, партиция
+  по умолчанию, идемпотентность `up()` по docker-пробе и по схеме, радиус `fresh: true`
+  (только `DROP SCHEMA` целевой схемы), `versions()` сам включает tombstone, ключи `Path`
+  (имя как в цепочке; порядок не совпадает с обходом), форма `ClassDef` в `db.registry`,
+  замыкание в результате `delete`/`purge`.
+- `lib/README.md` §11.1a: `opts.dsn` — docker-шаги решает живая проба postgres, а не имя
+  хоста (прежняя формулировка «хост не localhost» была неточной).
+
+### Fixed — противоречия и устаревшие факты в документации
+
+- Утверждение «реестр классов фиксируется до нового `connect()`» противоречило
+  `db.reloadSchema()` — исправлено в README (§11.1, §11.10, §9.2), `acl.ts`, `types.ts`;
+  добавлена таблица «`db.reloadSchema()` vs `db.acl.reload()` — разные подсистемы».
+- JSDoc точки входа `index.ts` показывал `schema: 'booking'` (нужно полное `'v1.booking'`)
+  и несуществующий алиас `Сотрудник`.
+- `AGENTS.md` / `requirements.xml` / `verification-plan.xml` заявляли отсутствие юнит-теста
+  M-ACL — `test/acl.test.ts` существовал раньше, чем эти доки.
+- Формат имени схемы `<schema>.v<version>` → `v<version>.<schema>`; 5 живых ссылок на
+  снесённый `SALON.md`; `wave5` в списке тестов; «19 классов» в заголовке сида при 20 INSERT-ах;
+  устаревшие LOC и дублированный semver убраны (нечему дрейфовать); `RESEARCH.md` помечен
+  HISTORICAL; ранние дизайн-файлы `schema.booking.md` / `.json` удалены — они описывали
+  13 HUB + 11 LINK и класс `Contragent`, которых в реальном сиде нет, и могли быть приняты
+  за схему проекта (истина — `lib/sql/seed.booking.sql`).
+- README: `npm install letopis`, разведены semver пакета и `opts.version` (версия DDL-схемы),
+  `####`-блоки для `uuidv5`/`uuidv7`/`LETOPIS_NS` с формулой v5-id как публичным контрактом,
+  предупреждения про `seeds` по умолчанию и про `.purge()` на живой сущности (`[]`, не ошибка).
+
+### Changed
+
+- `connect()` на схему без таблицы `Schema` даёт адресную ошибку со списком схем letopis
+  этой БД вместо сырой `42P01` (типовая ошибка — базовое имя вместо `vN.имя`).
+- `prepublishOnly` = `typecheck && check:docs && build`; `LICENSE` включён в `files`.
+
+## [0.19.0] — 2026-07-14
+
+### Added — физический purge (hard-erase) + живой подхват правок схемы
+
+- **`.purge({ confirm })`** — необратимый физический снос уже логически удалённой (tombstone)
+  сущности + всего поддерева по `links` (все версии). Двухфазно: живую не трогает (сначала
+  `.delete()`); без `confirm` — dry-превью замыкания. Внутри — серверная `purge()`:
+  `SET LOCAL letopis.purge='on'` отключает append-only-триггер через `WHEN`-условие → плоский
+  `DELETE` (детерминированно, без `TM_SelfModified`).
+- **`.withDeleted()`** — включить удалённые (tombstone) в выдачу последнего шага; снимает ТОЛЬКО
+  фильтр `deleted`, изоляция арендатора (`enforceAccount`) и ACL (`enforceAcl`) действуют.
+- **`db.accounts.purge(id)`** — полный офбординг тенанта: физ. снос всех Entity (`account|owner`)
+  + сам Account (Credential — FK-каскад). Гарды: только Owner/System, не последний Owner, не свой аккаунт.
+- **`db.reloadSchema()` / `db.schema.define(def)`** — правка определений классов простым SQL в
+  таблице `Schema` подхватывается без реконнекта (пересборка registry + ACL-резолвера).
+
+### Changed — DDL (требует наката `ddl.sql` на существующие схемы)
+
+- `entity_delete` получил `WHEN (current_setting('letopis.purge', true) IS DISTINCT FROM 'on')` —
+  обычный путь (tombstone + каскад) неизменен; под флагом триггер пропускается для физ-сноса.
+- Новые серверные функции: `purge_closure(partition,class,ids[])`,
+  `purge(partition,class,id[,dry]) RETURNS SETOF Entity`, `purge_account(id)`.
+
+### Notes
+
+- Голый повторный `DELETE` надгробия БЕЗ флага остаётся no-op (safety-инвариант жив).
+- Тесты: новый `test/wave5.test.ts` (13 кейсов P1/P2) — весь набор 181/181 зелёный.
+
 ## [0.18.1] — 2026-07-13
 
 ### Fixed — упаковка: CLI-скрипты в npm-пакете

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alepri51
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.