letopis 0.5.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,275 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [0.16.0] — 2026-07-12
+
+### Changed — BREAKING: глаголы записи create/update, слот unset, id считает Schema
+
+- **`set()` разбит на `create()` / `update()`** — мина «`Класс()` → INSERT,
+  `Класс({})` → UPDATE всех» мертва, намерение всегда явное:
+  - **`create(data?)`** — INSERT; известный id (шаг `Класс(id)`, `data.id` или
+    вычисленный v5) уже существует → новая версия (идемпотентный create,
+    REST-PUT семантика). Фильтр-объект перед create — ошибка ПОСТРОЕНИЯ
+    (`create() takes no filter`); create на pivot-шаге — ошибка.
+  - **`update(data?)`** — новая версия КАЖДОГО найденного путём;
+    `Класс()` ≡ `Класс({})` — «все в границах контекста»; не найдено → `[]`,
+    update НИКОГДА не создаёт.
+  - `set()` бросает подсказку `set() split into create()/update() (0.16.0)`.
+- **Слот-снятие переименовано: `.Класс.delete()` → `.Класс.unset()`** — развели
+  «удалить сущность» (`delete()`) и «снять конец связи» (`unset()`); старое имя
+  бросает подсказку. Слот теперь требует глагол записи ПЕРЕД собой:
+  `…create(…).Класс.set(x)` / `…update(…).Класс.unset()`; слот без операции —
+  ошибка `link slot needs a write` (раньше слот молча создавал `set({})`).
+- **Генерация id по Schema** — `attributes.id`:
+  - `"uuid"` / `{type:'uuid'}` → **v4** (random, как раньше — дефолт);
+  - `{type:'uuid', generate: 7}` → **v7** (unix-время в старших битах — вставки
+    ложатся в хвост btree-индекса);
+  - `{type:'uuid', generate: 5, from:[…]}` → **v5, детерминированный**:
+    `uuidv5("pgSchema:partition:класс:значения from")`; `from` — имена
+    ОБЯЗАТЕЛЬНЫХ концов `Schema.links` (класс или полное имя союза
+    `'Service|Complex'`; значение — id конца) и/или скалярных полей `data`.
+    Явный id у v5-класса запрещён (`computes id`). Свойства: **create
+    идемпотентен** (та же комбинация → та же сущность, дубль невозможен даже в
+    гонке — двойная бронь мертва на уровне схемы) и **id известен ДО создания**
+    (формула открыта; namespace letopis `c7a2f9d4-3b61-4e8a-9f05-8d2c1e6b7a90`).
+  - Батч: multi-VALUES-склейка для v5-классов отключена (id нужны концы) —
+    такие планы исполняются поштучно, семантика та же.
+- **Наследование attributes по иерархии Schema**: при загрузке реестра attributes
+  класса собираются по цепочке `ancestor` — потомок ПОВЕРХ предка, переопределение
+  поля = замена правила целиком (не слияние). Правило `id` (генерация) наследуется
+  так же; `links` НЕ наследуются (концы объявляются каждым классом). Валидатор и
+  fieldTypes компилируются из слитых attributes.
+- **Демо-схема booking целиком на generate** — с наследованием: `Entity` и `link`
+  объявляют дефолт `{generate: 7}`, v7-классы (Org/Staff/Folder/Customer/Schedule/
+  Booking/item) наследуют его без собственного правила; v5-классы переопределяют:
+  `busy ← v5(Slot, Staff)`; `skill ← v5(Staff, Service|Complex)`;
+  `shift ← v5(Schedule, Staff)`; `compo ← v5(Complex, Service)`;
+  `Slot ← v5(Schedule, data.start)`; `Service`/`Complex` ← `v5(Org, data.name)`
+  (имя уникально в организации). Полигоны `v1.salondemo`/`v1.article` обновлены
+  на месте (UPDATE Schema; данные нетронуты).
+- Тесты мигрированы (все `set`→`create`/`update`, слот `.delete`→`.unset`,
+  фикс-id v5-классов → вычисляемые); новый **`test/idgen.test.ts`** — генерация
+  id на боевых классах Schema (v4/v7/v5 из поля и концов, гонка без локов,
+  наследование attributes/id-правила, схема-гарды). SALON.md и демо-полигон
+  перегнаны на 0.16.0. Итого **165 тестов**.
+
+## [0.15.0] — 2026-07-12
+
+### Changed — BREAKING: единый закон пути, слоты связей, pivot, entity()
+- **Один закон навигации для чтения И записи**: цепочка всегда подчиняется переходам
+  `Schema.links`; недопустимый переход — ошибка СИНХРОННО при построении (не в терминале).
+  Мультиродительский «контекст-сбор» через невалидные HUB→HUB прыжки удалён.
+- **Слоты связей** вместо `.link()`: конец связки задаётся `.Класс.set(target)` ПОСЛЕ
+  `.set(данные)` — свойство-класс БЕЗ вызова. Владелец создаваемой связки — из валидного
+  пути, прочие концы — слотами. `target` = id | Row | **вложенная цепочка** (исполняется в
+  той же транзакции, обязана дать ровно одну сущность класса конца — «создать И привязать»).
+  `.Класс.delete()` снимает optional-конец; союз-конец `[A|B]` замещается слотом целиком.
+  **`.link()` УДАЛЁН** (бросает подсказку).
+- **pivot**: повтор LINK-класса в пути — возврат к тому же узлу (ветвление к другому концу
+  + дофильтровка AND). `db.Запись(з).позиция().Услуга(у).позиция().Сотрудник(вася)` —
+  «позиции записи з с услугой у у мастера вася» одной цепочкой.
+- **`entity(x)`** (Chain и db): вставить узел-переменную/паттерн (`db.позиция()`) или Row в
+  путь; та же переменная повторно — явный pivot; `db.entity(row).…` — старт с готовой строки.
+- Тесты мигрированы на слоты; **`test/salon.test.ts`** — тест-план «работа салона»
+  (21 акт), покрывающий ВСЕ 145 публичных точек API + матрица покрытия. Итого 153 теста.
+
+## [0.14.0] — 2026-07-12
+
+### Changed — Schema.links v2: концы связей объектами
+- **Конец связи — объект**: `{"class":"Org","cardinality":1}` /
+  `{"classes":["Service","Complex"],"cardinality":1}` (союз ролей) /
+  `{"class":"Staff","optional":true,…}`. `'Entity'`-полиморф в новых схемах не
+  используется — классы концов называются явно. **Колонка `Schema.links` — `jsonb`**
+  (настоящий массив объектов; в новых схемах). Старые схемы с `text[]` читаются тем же
+  кодом по прежним правилам (legacy-строки `'Org'`, `'Entity'`-полиморф).
+- **Валидация строгая на двух уровнях** (либа `write.ts` + БД-триггер
+  `entity_check`): жадный матчинг ключей `Entity.links` по порядку объявления
+  концов; обязательный конец без ключа → `requires end "Service|Complex"`;
+  связь вне концов → `has stray link(s)` (раньше лишние молчали). Голый SQL
+  мимо либы ловится триггером так же.
+- **Демо-домен уточнён**: `позиция = [Запись, {Услуга|Комплекс}, Сотрудник?]` —
+  три конца, владелец строго Запись; состав комплекса — новый LINK-класс
+  **`compo`/«состав» = [Комплекс, Услуга]** (раньше ездил на позиции);
+  `навык = [Сотрудник, {Услуга|Комплекс}]`; `занятость = [Сотрудник, Окно, Запись?]`
+  (третий конец легализован — раньше жил контрабандой); `Запись = [Клиент?]`
+  (ручная бронь без клиента). `cardinality` — зарезервировано, пока не проверяется.
+- Полигон `v1.article` мигрирован НА МЕСТЕ (ALTER links → jsonb + apply поверх):
+  данные Entity нетронуты (1 112 952), схема идентична booking.
+- `lib/scripts/gen-seed.mjs` — сид Schema теперь реально генерится из
+  `schema.booking.v2.json` (комментарий «файл сгенерирован» стал правдой);
+  `schema-sync` сравнивает концы канонически (объект ⇔ JSON-текст в text[]).
+
+## [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