letopis 0.5.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,177 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [0.13.0] — 2026-07-11
+
+### Added — `up()`: одна точка входа
+- **`up(opts): Promise<EntityDb>`** — от пустой машины до готового `db` одной функцией:
+  probe `dsn` (живой postgres — docker пропускается: CI-сервисы, внешние БД) → docker
+  ensure через CLI (`inspect`/`build` из пакованного Dockerfile/`run`/`start`) → ожидание
+  готовности PG + Redis → автосоздание базы из `dsn` (3D000) → версионная схема
+  `"v<version>.<schema>"` из шаблонов пакета (маркер `"<SCHEMA-NAME>"`) → сквозной
+  `connect()`. Идемпотентно на каждом шаге; `fresh: true` — дроп схемы и накат заново;
+  `seeds: string[] | false` — свои сиды вместо демо. Живые тайминги: с нуля
+  (build+initdb+apply) 7.4 s, `docker start` 1.2 s, всё готово ~110 ms.
+- **Данные PG — на хосте**: контейнер поднимается с named volume **`letopis-pgdata`**
+  (кроссплатформенно, переживает пересоздание контейнера; физически — внутри
+  docker-диска WSL2/ext4), `dataDir: '/path'` — bind mount папки (на Windows/NTFS —
+  на свой риск). Redis без персиста — сессии эфемерны.
+- SQL-шаблоны и Dockerfile теперь **пакуются в npm** (`lib/sql/`, `lib/docker/`,
+  `files += sql, docker`) — `up()` работает у любого потребителя пакета из коробки.
+
+### Changed
+- Dev-контейнер переименован: образ `clockz-db` → **`letopis-db`**, контейнер
+  `clockz-timescale` → **`letopis-timescale`** (данные перенесены дампом, полигон
+  `v1.article` 1 112 952 строк цел).
+- Шаблоны переехали `db/*.sql` → `lib/sql/`, докер-файлы `db/docker/` → `lib/docker/`;
+  `db/apply.mjs` остался CLI-обёрткой и читает шаблоны из `lib/sql/`.
+
+## [0.12.0] — 2026-07-11
+
+### Changed — BREAKING: шаблон SQL + версия движка в имени схемы
+- **SQL-шаблоны (`db/ddl.sql`, сиды) держат маркер `"<SCHEMA-NAME>"`** вместо реального
+  имени: подстановка тотальная и безопасна by construction — jsonb-литералы (`'booking'`
+  в enum, ключи settings) совпасть с маркером не могут (старый text-replace по живому
+  имени уже кусался).
+- **`db/apply.mjs`: обязательный `--version=N`** (целое ≥ 1, версия ДВИЖКА — бамп руками
+  при breaking-изменении DDL); итоговая PG-схема — **`vN.<имя>`**: `--schema=booking
+  --version=1` → `"v1.booking"` (точка в имени — валидный идентификатор в кавычках;
+  v1 и v2 живут в БД рядом). `--schema` принимает базовое имя без точек.
+- **`connect({ schema })` принимает ПОЛНОЕ имя** (`'v1.booking'`) — либа префикс не
+  достраивает и о версиях не знает. Канал `pg_notify`/LISTEN = полное имя схемы
+  (`pg_notify('v1.booking', …)` — строковый литерал; LISTEN-идентификатор postgres.js
+  кавычит сам).
+- Все тестовые/бенч-схемы переехали: `v1.booking`, `v1.article`, `v1.acl`, `v1.depth`,
+  `v1.plan`, `v1.wave4`, `v1.bench`; безверсионные дропнуты.
+
+## [0.11.0] — 2026-07-11
+
+### Changed — BREAKING: цепочка = план, операции = звенья
+- **`.set(data?)` / `.delete(opts?)` / `.anonymize(fields)` возвращают ЦЕПОЧКУ** (Chain),
+  а не исполняются сами: операция применяется к шагу, к которому приклеена точкой;
+  **исполняет терминал** (`rows/first/ids/count/run/versions/агрегации`) — весь план
+  **одной транзакцией** (deny/валидация любого сегмента откатывает всё). Голый
+  `await …set(…)` без терминала больше НЕ пишет (цепочка не thenable). Миграция:
+  `await db.X(id).set({…})` → `await db.X(id).set({…}).rows()`.
+- **Продолжение цепочки — от результата операции** (fan-out по строкам):
+  `db.Клиент({vip: true}).set({bonus: 500}).Запись().delete({confirm: true}).rows()` —
+  обновить всех vip и снести записи каждого. Повторная операция без шага — к тем же
+  строкам: `X(id).set({a}).set({b}).rows()` — две версии подряд.
+- **`execute()` → `run()`** (пути; то же у батча: `batch.execute()` → `batch.run()`);
+  старые имена бросают понятную ошибку.
+- **`delete({ confirm: true })` — удалить; БЕЗ confirm — превью**: терминал возвращает
+  кандидатов (цели + каскад), БД не тронута.
+- **Пост-довесы связей удалены** (`set({}).Окно(w)`, z-форма, тип `SetChain`): имя класса
+  после операции — переход-шаг. Связи — контекст-шагами до операции; для значения связи
+  БЕЗ участия в фильтре целей — новый модификатор **`.link(Класс, target)`**:
+  `tr.Запись(b).позиция({}).link('Сотрудник', новый).set({}).rows()`.
+- Ошибки записи (ValidationError, abstract, context step, acl) летят из терминала (async).
+- В батче `await …set(…)` больше не возвращает номер очереди (план в очереди; Chain).
+- Модификатор шага сразу после операции — ошибка `step modifier after set()`.
+
+## [0.10.0] — 2026-07-11
+
+### Added
+- **ACL по Resource/Rule** (формат согласован повторно, закрыт последний гэп RESEARCH.md):
+  - `db.acl.check(account, endpoint)` — legacy-семантика 1:1: субъект-группы по
+    `Account.categories` (`{A,B}` / `!{A,B}` / NULL), маски эндпоинтов (`*`, `{a,b}`),
+    победа ровно одного правила (max weight, при равенстве deny), без правил — deny.
+  - **Операции над данными = категории ресурсов `READ`/`WRITE`/`DELETE`**; pattern —
+    **шаблон строки Entity**: реальные колонки (`class`, `owner`, `account`, `tags`,
+    `data`, `links`…) с литералами или `"$account"` (подставляется динамически);
+    `class`-маска действует на потомков (lineage). Никаких выдуманных полей.
+  - `db.acl.checkData(account, class, op)` → `{allow, filter?}` — filter = остаточный
+    шаблон строк победившего правила с подставленным `$account`.
+  - **`connect({ account, enforceAcl: true })`**: READ на каждый шаг цепочки, WRITE на
+    `set()`/anonymize/батчи, DELETE на цели и все классы каскадного замыкания (deny
+    откатывает транзакцию). **Предикат вливается в SQL до сортировки/лимита** — пагинация,
+    count, keyset честные. INSERT пришпиливает `$account`-колонки; upsert по явному id
+    НЕ перехватывает существующую недоступную сущность. `watch()` отдаёт события только
+    безусловных allow-классов. Deny-by-default; правила фиксируются на connect.
+  - `bench/acl.bench.mjs` (1.1M): безусловное правило — бесплатно; предикат в worst-case
+    (100% строк) +33–99% на full-scan; в реальности предикат сужает выборку — дешевле базы.
+  - `test/acl.test.ts` — 9 сцен; суммарно 114 тестов. Сид не менялся.
+
+## [0.9.0] — 2026-07-11
+
+### Added
+- **OTP** в `db.auth` (node:crypto, без зависимостей):
+  - **TOTP** (RFC 6238, authenticator-приложения): `enrollTotp` (секрет base32 + otpauth-URI
+    для QR; re-enroll сбрасывает), `verifyTotp` (окно ±1 шаг, replay принятого шага отбит
+    через `meta.lastStep`, первая успешная проверка активирует фактор), `totpEnabled`;
+    хелпер `totpCode(secret, atMs?)` экспортирован (тесты/серверная генерация).
+  - **Одноразовые коды** (email/SMS/сброс — доставка на приложении): `issueOtp` (в БД
+    только sha256 + expires + attempts; повторный выпуск затирает старый код),
+    `verifyOtp` (успех сжигает код; 5 неудач сжигают; истёкший TTL сжигает).
+- `test/auth.test.ts`: +2 сцены (TOTP: enroll/verify/replay/окно/re-enroll; OTP:
+  одноразовость/лимит/TTL/перевыпуск); суммарно 105 тестов.
+
+## [0.8.0] — 2026-07-11
+
+### Added
+- **Устойчивость к сбоям** (§ 10.12 README):
+  - transient-ошибки PG (deadlock `40P01`, serialization `40001`) ретраятся там, где
+    повтор безопасен: чтения в автокоммите (до 3 попыток, backoff 40–160 ms), `insertOne`
+    (плюс прежний 23505), внутренние транзакции delete-каскада и батчей — повтор целиком;
+  - внутри `db.begin()` повтор невозможен (транзакция aborted) — ошибка уходит сразу
+    с подсказкой `retry the whole db.begin() block`; `tr.lock()` при deadlock — та же подсказка;
+  - ретрай 23505/transient в `insertOne` больше не срабатывает внутри транзакции
+    (раньше повтор в aborted-транзакции маскировал исходную ошибку кодом 25P02).
+- **`watch(…, { onReconnect })`** — LISTEN-соединение и так переживает обрывы
+  (postgres.js: reconnect + повторный LISTEN), но NOTIFY за время разрыва потеряны;
+  `onReconnect` зовётся после каждого восстановления — точка дочитать пропущенное.
+  Типы `WatchEvent`/`WatchOpts` экспортированы.
+- `test/resilience.test.ts` — юнит-ретраи, настоящий deadlock двух транзакций
+  (встречные `lock()`), обрыв LISTEN через `pg_terminate_backend` (reconnect ~0.4 s);
+  суммарно 103 теста.
+
+## [0.7.0] — 2026-07-10
+
+### Added
+- **`db.auth`** — вход по таблице Credential, на аккаунт много способов:
+  - пароль (`setPassword`/`verifyPassword`) — scrypt из node:crypto (без зависимостей),
+    формат `scrypt$N$r$p$salt$hash`; время ответа выровнено dummy-verify;
+  - api-ключ (`issueApiKey`/`verifyApiKey`) — `lts_<48hex>` показывается один раз,
+    в БД только sha256 (legacy хранил открыто — исправлено);
+  - ключ-секрет (`issueKeySecret`/`verifyKeySecret`) — key открытый id, secret хэшем;
+  - внешние identity (`link`/`lookup`) — oauth/sso/telegram: токен проверяет приложение;
+  - все verify: кред жив + `confirmed` (отключаемо `requireConfirmed:false`) + аккаунт `enabled`.
+- **Сессии в Redis**: `db.auth.sessions(store)` → `start/check/revoke/revokeAll`;
+  клиент инжектируется (интерфейс `SessionStore`, ioredis подходит как есть; в prod-зависимости
+  не входит); в Redis — sha256 токена, не сам токен.
+- `credential_identity_udx` — один живой кред на `(category, identifier)` во всей схеме:
+  вход по identifier однозначен; мягко удалённый identifier освобождается.
+- Dev-контейнер `db/docker/Dockerfile`: TimescaleDB + Redis в одном контейнере
+  (порты 15432/16379); CI — сервис redis:7.
+- `test/auth.test.ts` — 7 сцен, включая живой Redis (expire/revoke); суммарно 98 тестов.
+
+### Fixed
+- CI: артефакт пакета собирался по паттерну `entity-chain-*.tgz` и был пуст после
+  переименования пакета — теперь `letopis-*.tgz`.
+- `bench/article-demo.mjs`: битый относительный импорт `./src/index.js` → `../src/index.js`.
+
+## [0.6.0] — 2026-07-10
+
+### Added
+- **data-пути любой глубины** во всём API: containment-фильтры, операторы (включая
+  `exists`/`has*` на вложенных ключах), `.sort()`, `.after()`/`cursorOf()`,
+  `.sum/.avg/.min/.max/.countBy`. Тип листа (и SQL-каст) берётся из вложенных
+  `{type:'object', props:{…}}` схемы — новый `FieldType 'object'`.
+- Пример в booking-схеме: `Org.settings.booking.deposit.{amount,currency}` (лист глубины 4),
+  строгая валидация и default-ы на каждом уровне; deep-merge обновляет один вложенный лист,
+  не трогая соседей (покрыто тестом).
+- Наследование классов 3+ уровней покрыто тестом lineage (`Vehicle → Car → SportsCar`).
+- `gen-types`: `{type:'object', props}` → вложенные TS-литералы.
+- `test/depth.test.ts` — 5 сцен глубины; суммарно 91 тест.
+
+## [0.5.1] — 2026-07-10
+
+### Fixed
+- `.sort('data.price.RUB')` — сортировка по вложенному record-пути молча давала ORDER BY NULL
+  (ключ с точкой вместо пути); теперь строится `data->'price'->>'RUB'` с кастом по типу листа.
+  Тот же путь понимают `.after()` и `cursorOf()`. Дефект пойман живым прогоном примеров статьи.
+- `.min()/.max()` возвращали numeric строкой (`"800"`); для number-полей по Schema — число.
+
 ## [0.5.0] — 2026-07-10
 
 ### Changed