letopis 0.20.0 → 0.20.1

package/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [0.20.1] — 2026-07-31
+
+### Fixed — движок схемы больше не отстаёт молча
+
+`ddl.sql` растёт аддитивно внутри одной версии движка (в 0.19.0 так появились
+`purge`/`purge_closure`/`purge_account`), а существующая схема этих правок **не получала**:
+приложение обновляло пакет и падало сырым
+`PostgresError: function "v1.booking".purge(...) does not exist`. Обнаружено смоук-тестом
+опубликованного пакета на схеме, накатанной до 0.19.0.
+
+- Последняя строка `ddl.sql` штампует метку `COMMENT ON SCHEMA … IS 'letopis ddl_revision=N'`
+  (последней — чтобы метка не встала при частично применённом файле). `connect()` сверяет её
+  с новой константой `DDL_REVISION` и **один раз на схему за процесс** предупреждает, называя
+  команду апгрейда. Предупреждение, а не отказ: правки аддитивны.
+- Апгрейд движка на месте: `up({ upgrade: true })` и `node db/apply.mjs … --upgrade`
+  перекатывают **только** `ddl.sql` (сиды не трогаются). Безопасно, потому что файл
+  идемпотентен — `CREATE OR REPLACE` у функций, `DROP IF EXISTS` + `CREATE` у триггеров,
+  `IF NOT EXISTS` у таблиц/индексов. Механизм существовал, но был недостижим: `applySchema`
+  при существующей схеме молча выходил.
+- Ревизия ≠ версия схемы: несовместимая правка структуры таблиц по-прежнему означает смену
+  `version` в имени схемы (`v1` → `v2`). README § 10.8a, грабля #18 в шпаргалке.
+
+### Fixed — под `enforceAcl` каждый `db.as()` делал три SELECT вместо одного
+
+Словарь `Resource`/`Rule` одинаков для всех субъектов, но снимался на каждый scope — то есть
+в вебе (scope на HTTP-запрос) два лишних запроса к БД на каждый запрос приложения. Теперь
+снимок берётся один раз на подключение и переиспользуется; per-scope остались чтение своего
+аккаунта и компиляция энфорсера (один энфорсер = один субъект — иначе memo отдаст чужое
+решение). Снимок сбрасывает `db.reloadSchema()`. Провал чтения не кэшируется.
+
+### Added — проверки и воспроизводимость
+
+- `check:docs` — десятая проверка: маркер `-- DDL_REVISION:` в `ddl.sql`, штамп `COMMENT` и
+  константа в `types.ts` обязаны совпадать, а штамп — быть последним выражением файла.
+- `release.yml` — смоук **артефакта** после публикации: пакет ставится из реестра в чистую
+  папку, проверяются ESM-импорт, ключевые экспорты и наличие `dist`/`sql`/`scripts` в тарболе.
+  Тесты гоняют `lib/src`, а в npm уезжает сборка — сломанные `exports`/`files` иначе
+  обнаружил бы первый пользователь.
+- `bench/tenants-seed.mjs` + `bench/isolation.bench.mjs` — многоарендаторный полигон
+  (10 аккаунтов, перекос 50 %…0.3 %, 1 млн строк) и цена изоляции. Таблица README § 10.6
+  была измерена временным скриптом; попутно из неё убрана колонка «без сужения» — это форма
+  SQL, которой в публичном API нет.
+- Тайминги README § 11 перенесены с проанализированного полигона точным сопоставлением по
+  коду вызова (151 из 208; остальные — иллюстративные фрагменты, у них добавлена оговорка).
+- Тесты: 198 (было 193 на 0.20.0). Новые — ревизия движка и апгрейд, `ANALYZE` при накате,
+  кэш словаря ACL. Каждый проверен негативно.
+
+### Changed — на каждое событие ровно одно действие в Actions
+
+Тесты гонялись трижды на одном и том же коммите: прогон от push в `dev`, второй от
+`pull_request` при открытии релизного PR и третий от push в `main` при merge. Причём на merge
+`ci` и `tag` стартовали **одновременно** — тег мог встать раньше, чем закончатся тесты.
+
+Контур приведён к одному действию на событие:
+
+```
+push dev            →  ci  (typecheck + check:docs + 198 тестов)
+merge dev→main      →  tag (аннотированный тег из lib/package.json)
+publish Release     →  release (заметки git-cliff + npm publish + смоук артефакта)
+```
+
+- `ci.yml` — только `push: dev`. Ни `pull_request`, ни `push: main`: релизный PR и сам merge
+  несут ТОТ ЖЕ коммит, что уже проверен на `dev` (ветка всегда пушится до PR). `concurrency` —
+  быстрые последовательные пуши в `dev` отменяют предыдущий прогон.
+- `tag.yml` — `push: main`, тегирует сразу: ждать нечего, тесты прошли на `dev`.
+- убраны шаги `npm run build` + `npm pack` с выгрузкой артефакта: тарбол никто не забирал —
+  `release.yml` публикует сам (`prepublishOnly` гоняет typecheck + build), а результат
+  проверяется смоуком уже из реестра; компиляция дублировала шаг Typecheck. CI — 7 шагов.
+
+**Остаётся настройкой репозитория:** branch protection на `main` с обязательной проверкой
+`test`. Без неё запрет «не мерджить на красном» держится на дисциплине: у PR своей проверки
+нет, гарантию даёт зелёный прогон того же SHA на `dev`.
+
+### Changed — флоу релиза по логике VP
+
+`tag.yml` ставит **аннотированный** тег: аннотация несёт changelog коммитов по Conventional
+Commits (`git-cliff`, конфиг `cliff.toml`), так что `git show <tag>` и GitHub → Tags
+показывают состав версии без GitHub Release.
+
+`release.yml` при публикации **сам собирает тело релиза**: тот же `git-cliff`, диапазон — от
+предыдущего **опубликованного** релиза до этого тега (черновики и pre-release не считаются,
+поэтому заметки не теряют коммиты между публикациями). Описание релиза писать руками не нужно.
+
+Источник версии — `lib/package.json` (тег обязан равняться тому, что уедет в npm); расчёт
+`git-cliff` печатается предупреждением, если бамп забыли.
+
 ## [0.20.0] — 2026-07-29
 
 ### Fixed — `ANALYZE` при накате схемы: чтения были медленнее на порядок