letopis 0.13.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,206 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [0.18.0] — 2026-07-13
+
+### Added — генератор id берёт default поля из Schema
+
+- **`v5Id` подставляет default необязательного from-поля** (`lib/src/write.ts`): если
+  поле из `attributes.id.from` не передано в `create`, id считается из его `default`
+  (объект-правило `{default}` или DSL `'…|default:X'`). Раньше отсутствие from-поля
+  роняло `needs scalar data field`. Теперь необязательное поле участвует в
+  детерминированном id прозрачно — единственная правка ядра библиотеки в этом релизе.
+
+### Changed — цена каталога: отдельный класс `цена` (варианты + мультивалюта)
+
+Демо-домен booking: у `Элемент` (Услуга/Товар/Комплекс) убрано скалярное поле `price`;
+цена вынесена в новый LINK-класс.
+
+- **`price·цена` (LINK)** `[ {Услуга|Товар|Комплекс} ]`: `note` (string, default
+  `'базовая'`) + `amounts` (record<валюта, число>, валюта — enum RUB/USD/EUR/AED).
+  `id = v5(элемент, note)`. У элемента несколько вариантов цены «по пожеланиям
+  клиента» (базовая / с дизайном / …), каждый — своя строка.
+- **Зачем не поле-массив:** массив в `data` при `update` заменяется целиком (точечно
+  не поправить, гонки теряют правки, по цене не искать). Отдельные строки-варианты +
+  record внутри дают точечную правку одной валюты (record мержится по ключам), поиск
+  (`db.цена({amounts:{RUB:lte(2000)}}).Услуга()`), историю и версии каждого варианта.
+- **v5-default в деле:** `db.Услуга(s).цена().create({amounts:{RUB:1500}})` без `note`
+  → `note='базовая'`, id детерминирован; повтор без note → та же строка (идемпотентно),
+  `amounts` домерживается точечно.
+- Тесты/бенчи/полигоны/доки переведены на класс `цена`; `idgen.test.ts` — новый кейс
+  «v5 берёт default из Schema».
+- **Единый демо-полигон `v1.salondemo`** (`bench/salon-seed.mjs`): тесты быстродействия,
+  API Reference (`bench/api-reference-demo.mjs`) и статья (`bench/salon-article-demo.mjs`,
+  `bench/article-demo.mjs`) читают ОДИН полигон (~980k строк), мутируя лишь свои демо-сущности
+  (непересекающиеся префиксы `00000900`/`00000000-09xx`/`00000902`); `v1.article` упразднён.
+
+### Fixed — keyset-пагинация стабильна при неуникальном sort-поле
+
+- **`orderExpr` добавляет `id` вторым ключом `ORDER BY`** (`lib/src/sql.ts`) тем же
+  направлением, что кортеж `(sortExpr, id)` в `.after()`. Раньше внешний `ORDER BY`
+  сортировал только по sort-полю: при неуникальных значениях (тысячи записей с одним
+  `updated`) страницы keyset перекрывались. Теперь `.sort()+.after()` даёт непересекающиеся
+  страницы на любом поле (id — стабильный tiebreaker); подтверждено на 440k записей с
+  совпадающим `updated`. Вторая (и последняя) правка ядра в релизе.
+
+### Changed — полигон-витрина: выразительный `salon-seed`
+
+- **`bench/salon-seed.mjs` обогащён** ради наглядности API Reference/статьи: папки —
+  дерево 3 уровней (Каталог→Мужской/Женский зал→Борода и усы→Уход) вместо плоского
+  списка; навыки — каждый мастер умеет 2–5 РАЗНЫХ услуг (~1260 осмысленных вместо ~3000
+  вырожденных на одну услугу); цены комплексов с разбросом по оргу (топ прайса различим);
+  клиентам розданы теги `vip`/`telegram` (`has/hasAny/hasAll` = 400/800/100); части услуг
+  дан явный `description: null` (`isNull()` ≠ `exists(false)`).
+- **§11 API Reference и SALON.md перегнаны построчно** под обогащённый полигон: имена
+  сущностей, числа-результаты и тайминги сняты живым прогоном воспроизводителей; keyset-
+  пример показывает пересечение страниц 0.
+
+## [0.17.0] — 2026-07-12
+
+### Changed — BREAKING: демо-домен booking переделан (позитивная доступность)
+
+Библиотека не изменилась — переделан демо-домен booking (19 классов вместо 16;
+источник правды — сид `lib/sql/seed.booking.sql`) и всё, что на нём стоит:
+тесты, бенчи, полигоны, доки. Промежуточные дизайн-файлы `schema.booking.v2.*`
+удалены из корня; `gen-seed.mjs` упразднён (сид редактируется напрямую).
+
+- **Новые HUB**: `Person·Контрагент` (абстракт: `name`+`phone`, наследуют
+  Мастер/Клиент), `Location·Локация`, `Element·Элемент` (абстрактная каталожная
+  единица: `name`/`price` + правило `id = v5(Org, name)` объявлены ОДИН раз,
+  наследуются Услугой/Товаром/Комплексом), `Product·Товар`.
+- **Смена категории**: Окно и Запись из HUB стали LINK:
+  - `slot·окно [Staff, Location, Schedule] {start_datetime, end_datetime}` —
+    интервал доступности мастера (смена), `id = v5(Staff, start_datetime)`;
+  - `booking·запись` — **наследник окна** (`ancestor: slot`): интервал и
+    v5-правило id приходят по наследству, свои концы — предмет-союз
+    `Service|Product|Complex` + `Customer?`. Двойная бронь мертва самим id
+    записи; окно и запись на одно время сосуществуют (classId в формуле).
+- **Инверсия модели доступности**: негативная (Slot-сетка + busy off/hold/booking
+  + shift-ростер) → **позитивная** (окно есть = мастер доступен; свободно =
+  внутри окна и нет пересекающейся записи). Классы `busy`, `shift`, `item`,
+  HUB `Slot`/`Booking` — удалены.
+- **Запись самодостаточна**: сама несёт интервал (длинная услуга = один интервал,
+  мульти-окна не нужны), предмет и клиента. «4 руки» = две записи. Перенос =
+  пересоздание (id жёстко держит пару мастер+старт). Отмена = tombstone-delete;
+  повторная бронь пары воскрешает id с историей. Статусы
+  (created/…/no_show), source, total, qty и снимок цены — удалены: история —
+  версии, цена — из предмета (`asOf` для задним числом).
+- **Каталог**: принадлежность папке — LINK `content·содержимое [Folder, союз]`
+  (M:N + order) вместо Folder-конца; состав комплекса `compo·состав` принимает
+  союз `Service|Product`; вложенность папок осталась HUB-концом `Folder⤴`.
+  `skill·навык` сужен до `[Staff, Service]` (+`level`) — умение комплекса
+  вычислимо по составу. Новый `address·адрес [Staff, Location]`.
+- **Упрощения атрибутов**: `price` — число (record по валютам удалён),
+  `Schedule {name, year, month}` (месячная модель), у Мастера/Клиента общие
+  поля уехали в Контрагента; `Complex` переопределяет унаследованный `price`
+  в `optional` (демонстрация «замена правила целиком»).
+- Тесты переписаны под модель (**167 тестов**, было 165): `idgen.test.ts` —
+  наследование v5-правила через два уровня (booking→slot→link, DeluxeBooking),
+  v5 из пары концов (адрес) и конца+поля (запись); `real-life.test.ts` — сцены
+  переноса-пересоздания, воскрешения id, no-show пометкой; `salon.test.ts` —
+  21 акт на новой модели; has/hasAny/hasAll переехали на колонку tags
+  (массивов в data демо-схемы больше нет).
+- Полигон `v1.salondemo` (~1M строк) пересеян генератором
+  новой модели; SALON.md, README §3, TESTPLAN.md — перегнаны с живых прогонов.
+
+## [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` обновлён
+  на месте (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` — зарезервировано, пока не проверяется.
+- Демо-полигон мигрирован НА МЕСТЕ (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()`: одна точка входа
@@ -22,8 +222,8 @@
 
 ### Changed
 - Dev-контейнер переименован: образ `clockz-db` → **`letopis-db`**, контейнер
-  `clockz-timescale` → **`letopis-timescale`** (данные перенесены дампом, полигон
-  `v1.article` 1 112 952 строк цел).
+  `clockz-timescale` → **`letopis-timescale`** (данные перенесены дампом, демо-полигон
+  1 112 952 строк цел).
 - Шаблоны переехали `db/*.sql` → `lib/sql/`, докер-файлы `db/docker/` → `lib/docker/`;
   `db/apply.mjs` остался CLI-обёрткой и читает шаблоны из `lib/sql/`.
 
@@ -42,7 +242,7 @@
   достраивает и о версиях не знает. Канал `pg_notify`/LISTEN = полное имя схемы
   (`pg_notify('v1.booking', …)` — строковый литерал; LISTEN-идентификатор postgres.js
   кавычит сам).
-- Все тестовые/бенч-схемы переехали: `v1.booking`, `v1.article`, `v1.acl`, `v1.depth`,
+- Все тестовые/бенч-схемы переехали: `v1.booking`, `v1.acl`, `v1.depth`,
   `v1.plan`, `v1.wave4`, `v1.bench`; безверсионные дропнуты.
 
 ## [0.11.0] — 2026-07-11