letopis 0.20.3 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [0.21.0] — 2026-08-23
+
+### Added — no-history классы: `meta.history: false` (DDL_REVISION 2)
+
+Класс, помеченный в `Schema.meta` флагом `history: false`, хранит **одну актуальную строку
+на id**: новый AFTER INSERT триггер `entity_collapse` после каждой вставки физически удаляет
+более старые версии этого id. Дефолт (`history` отсутствует или `true`) — прежнее поведение,
+все версии копятся; фича строго opt-in, существующие схемы и сервисы не затронуты.
+
+Зачем: у мутабельных статус-сущностей (очереди, outbox — статус живёт в `data`) история
+версий делает jsonb-фильтры неселективными: GIN по `data` матчит каждую версию, что
+когда-либо была в искомом статусе, и сканы растут O(вся история). Под `history:false`
+фильтр матчит только актуальные строки — скан остаётся O(активных) при любом росте данных.
+
+Механика:
+- `entity_collapse` — AFTER INSERT (как `entity_notify`; collapse по алфавиту раньше —
+  один NOTIFY на выжившую строку). In-place UPDATE не годится: Entity — гипертаблица по
+  `updated` (перенос между чанками), а `entity_notify` слушает только INSERT.
+- DELETE старых версий идёт под `letopis.purge='on'` (save+restore флага):
+  `entity_delete` пропущен — без tombstone и каскада. Advisory-lock тем же ключом,
+  что `entity_delete`/`purge`, сериализует конкурентные вставки одного id.
+- `.delete()` под no-history оставляет один tombstone (его `updated` строго больше),
+  `purge()` работает как прежде.
+- Новая серверная функция `compact(partition, class) → bigint` — разовая чистка УЖЕ
+  накопленной истории при переводе класса на `history:false` (оставить последнюю версию
+  каждого id, вернуть число удалённых). Идемпотентна. После вызова — `ANALYZE "Entity"`.
+- `ClassDef.history` в реестре; `.versions()`/`.asOf()` по no-history классу предупреждают
+  в console.warn (один раз на класс+метод за процесс) — результат не отражает историю.
+
+Накат на существующие схемы: `up({ upgrade: true })` или `node db/apply.mjs --upgrade`
+(файл идемпотентен, данные целы); до наката `connect()` предупредит о ревизии (1 → 2).
+
+- `test/no-history.test.ts` — 7 сцен: реестр, схлопывание, соседний history-класс,
+  NOTIFY, tombstone, `compact()`, warning; суммарно 205 тестов.
+
 ## [0.20.3] — 2026-07-31
 
 ### Fixed — релиз доезжает до npm

package/README.md

@@ -3838,6 +3838,9 @@ cd lib && npm test    # весь набор против живого docker (ti
             # idgen         — генерация id по Schema (§ 3.2): v4/v7/v5 из концов и полей,
             #                 гонка без локов, наследование attributes и правила id, гарды
             # integration   — E2E-барбершоп (8 сцен)
+            # no-history    — meta.history=false: одна строка на id (entity_collapse),
+            #                 NOTIFY один на вставку, tombstone цел, compact() идемпотентна,
+            #                 warning на .versions()/.asOf()
             # real-life     — 16 сцен «дня салона»: 4 руки, гонки ×3, переносы, no-show
             # tables        — auth/ACL-таблицы
             # up            — up(): docker-argv, probe-ветка, идемпотентность, fresh,

package/dist/chain.js

@@ -23,6 +23,21 @@ function normalizeFilter(f) {
     return f;
 }
 const clsOf = (steps) => steps.map((s) => s.cls.id);
+// no-history класс (meta.history=false): в БД одна актуальная строка на id — .versions()
+// вернёт её одну, .asOf() отдаст «текущее» вместо point-in-time. Предупреждаем (не бросаем:
+// вызовы могли жить до перевода класса), один раз на класс+метод за процесс.
+const noHistoryWarned = new Set();
+function warnNoHistory(steps, method) {
+    const cls = steps[steps.length - 1]?.cls;
+    if (!cls || cls.history)
+        return;
+    const key = `${cls.id}|${method}`;
+    if (noHistoryWarned.has(key))
+        return;
+    noHistoryWarned.add(key);
+    console.warn(`letopis: .${method}() on no-history class "${cls.id}" (meta.history=false) — ` +
+        `хранится одна актуальная версия на id, результат не отражает историю`);
+}
 /** Внутренний канал: план чужой ленивой цепочки (слот-значения, entity()). */
 export const PLAN = Symbol('letopis.plan');
 const peekPlan = (x) => x !== null && typeof x === 'object' ? x[PLAN] : undefined;
@@ -353,7 +368,10 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                 case 'sort':
                     return (field, dir) => withMods({ order: field, desc: dir === true || dir === 'desc' });
                 case 'asOf':
-                    return (t) => withMods({ asOf: t instanceof Date ? t.toISOString() : t });
+                    return (t) => {
+                        warnNoHistory(steps, 'asOf');
+                        return withMods({ asOf: t instanceof Date ? t.toISOString() : t });
+                    };
                 case 'withDeleted':
                     return () => withMods({ withDeleted: true });
                 case 'deep':
@@ -406,6 +424,7 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                 case 'versions':
                     return async () => {
                         guardBatch();
+                        warnNoHistory(steps, 'versions');
                         if (hasOps)
                             return runPlan(ctx, steps, mods, 'versions');
                         const q = buildRead(ctx, steps, mods, 'versions');

package/dist/schema.js

@@ -281,6 +281,7 @@ function buildDef(row, byId) {
         idGen,
         meta: row.meta ?? {},
         abstract: row.meta?.abstract === true || row.meta?.abstract === 'true',
+        history: row.meta?.history !== false && row.meta?.history !== 'false', // дефолт true; только явный false отключает историю
         order: row.order,
         check,
         fieldTypes,

package/dist/types.d.ts

@@ -64,6 +64,8 @@ export interface ClassDef {
     strictEnds: boolean;
     meta: Record<string, unknown>;
     abstract: boolean;
+    /** false — движок хранит одну актуальную строку на id (триггер entity_collapse), .versions()/.asOf() теряют смысл. */
+    history: boolean;
     order: number;
     /** Как генерить id новой сущности (attributes.id). */
     idGen: IdGen;
@@ -285,6 +287,6 @@ export declare function reservedNamesOf(def: {
  * Совпадение константы с маркером `-- DDL_REVISION:` в ddl.sql проверяет
  * `scripts/check-docs.mjs` — иначе одно уедет без другого.
  */
-export declare const DDL_REVISION = 1;
+export declare const DDL_REVISION = 2;
 /** Метка ревизии в комментарии схемы: 'letopis ddl_revision=N' → N; иначе null. */
 export declare function parseDdlRevision(comment: string | null | undefined): number | null;

package/dist/types.js

@@ -104,7 +104,7 @@ export function reservedNamesOf(def) {
  * Совпадение константы с маркером `-- DDL_REVISION:` в ddl.sql проверяет
  * `scripts/check-docs.mjs` — иначе одно уедет без другого.
  */
-export const DDL_REVISION = 1;
+export const DDL_REVISION = 2;
 /** Метка ревизии в комментарии схемы: 'letopis ddl_revision=N' → N; иначе null. */
 export function parseDdlRevision(comment) {
     const m = /letopis ddl_revision=(\d+)/.exec(comment ?? '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "Letopis (летопись): append-only versioned entity store on TimescaleDB with dot-notation chains — every change is a new row, history is first-class (asOf, versions, watch, cascade tombstones)",
   "keywords": [
     "timescaledb",

package/sql/ddl.sql

@@ -8,10 +8,10 @@
 
 -- FILE: lib/sql/ddl.sql
 -- VERSION: 1.1.0
--- DDL_REVISION: 1   (последняя строка файла штампует её в COMMENT ON SCHEMA; см. там же)
+-- DDL_REVISION: 2   (последняя строка файла штампует её в COMMENT ON SCHEMA; см. там же)
 -- START_MODULE_CONTRACT
 --   PURPOSE: Движок-хранилище PostgreSQL/TimescaleDB — таблицы, Entity-hypertable, индексы и триггеры целостности (валидация, версионирование, каскад-tombstone, lineage, notify).
---   SCOPE: таблицы Schema/Entity/Account/Credential/Resource/Rule + триггеры schema_lineage/entity_check/entity_update/entity_delete/entity_notify.
+--   SCOPE: таблицы Schema/Entity/Account/Credential/Resource/Rule + триггеры schema_lineage/entity_check/entity_update/entity_delete/entity_notify/entity_collapse + compact.
 --   DEPENDS: none
 --   LINKS: M-DDL, V-M-DDL
 --   ROLE: RUNTIME
@@ -571,6 +571,91 @@ CREATE TRIGGER entity_notify
     AFTER INSERT ON "<SCHEMA-NAME>"."Entity"
     FOR EACH ROW EXECUTE FUNCTION "<SCHEMA-NAME>".entity_notify();
 
+-- -----------------------------------------------------------------------------
+-- Триггер 5: no-history — класс с Schema.meta.history=false хранит ОДНУ актуальную
+-- строку на id: после вставки новой версии старые физически удаляются.
+-- Зачем: у мутабельных статус-сущностей (очереди, outbox) история версий делает
+-- jsonb-фильтры неселективными (GIN матчит каждую версию, что когда-либо была в
+-- статусе) — сканы растут O(вся история). Дефолт (meta.history отсутствует/true) —
+-- поведение прежнее, все версии копятся.
+-- Почему AFTER INSERT, а не in-place UPDATE: Entity — гипертаблица по updated
+-- (апдейт time-колонки = перенос между чанками), а entity_notify слушает только
+-- INSERT (in-place UPDATE потерял бы NOTIFY). Оба AFTER INSERT триггера идут по
+-- алфавиту: entity_collapse раньше entity_notify — один NOTIFY на выжившую строку.
+-- -----------------------------------------------------------------------------
+-- START_CONTRACT: entity_collapse
+--   PURPOSE: Для класса с meta.history=false удалить версии старее только что вставленной (одна актуальная строка на id).
+--   INPUTS: { trigger: AFTER INSERT ON Entity (NEW) }
+--   OUTPUTS: { NULL }
+--   SIDE_EFFECTS: DELETE старых версий под letopis.purge='on' (entity_delete пропущен: без tombstone/каскада); pg_advisory_xact_lock на partition|class|id
+--   LINKS: M-DDL, V-M-DDL
+-- END_CONTRACT: entity_collapse
+CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".entity_collapse() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE prev text;
+BEGIN
+    -- per-class флаг из Schema.meta (PK-lookup; зеркало чтения abstract в entity_check).
+    -- jsonb ->> отдаёт текст: boolean false -> 'false'.
+    IF NOT EXISTS (SELECT 1 FROM "<SCHEMA-NAME>"."Schema"
+                    WHERE partition = NEW.partition AND id = NEW.class
+                      AND meta->>'history' = 'false') THEN
+        RETURN NULL;                                   -- history-класс (дефолт): версии копятся
+    END IF;
+    -- сериализация конкурентных INSERT одного id: тот же ключ, что в entity_delete/purge.
+    -- Лок транзакционный и реентерабельный — tombstone-INSERT внутри entity_delete
+    -- (он уже держит этот лок) не дедлочится.
+    PERFORM pg_advisory_xact_lock(
+        hashtextextended(NEW.partition || '|' || NEW.class || '|' || NEW.id, 0));
+    -- purge-guard: entity_delete висит с WHEN (letopis.purge IS DISTINCT FROM 'on') —
+    -- DELETE ниже идёт физически, без tombstone и каскада. save+restore, чтобы не
+    -- затереть флаг, выставленный снаружи, до конца транзакции.
+    prev := current_setting('letopis.purge', true);
+    PERFORM set_config('letopis.purge', 'on', true);
+    DELETE FROM "<SCHEMA-NAME>"."Entity" e
+     WHERE e.partition = NEW.partition AND e.class = NEW.class AND e.id = NEW.id
+       AND e.updated < NEW.updated;                    -- выживает ровно вставленная версия
+    PERFORM set_config('letopis.purge', COALESCE(prev, ''), true);
+    RETURN NULL;
+END $$;
+
+DROP TRIGGER IF EXISTS entity_collapse ON "<SCHEMA-NAME>"."Entity";
+CREATE TRIGGER entity_collapse
+    AFTER INSERT ON "<SCHEMA-NAME>"."Entity"
+    FOR EACH ROW EXECUTE FUNCTION "<SCHEMA-NAME>".entity_collapse();
+
+-- -----------------------------------------------------------------------------
+-- compact(): разовая компакция класса — оставить по одной (последней) версии на id.
+-- Для перевода класса на meta.history=false с уже накопленной историей: триггер
+-- entity_collapse останавливает накопление ВПЕРЁД, старые версии убирает compact().
+-- Идемпотентна (повторный вызов вернёт 0). GROUP BY покрыт entity_latest_idx.
+-- Не по ctid: в гипертаблице он не уникален между чанками — только PK-условие.
+-- После вызова: ANALYZE "Entity" (статистика для планировщика гипертаблицы).
+-- -----------------------------------------------------------------------------
+-- START_CONTRACT: compact
+--   PURPOSE: Удалить все версии класса, кроме последней на каждый id; вернуть число удалённых строк.
+--   INPUTS: { p_partition: text; p_class: text }
+--   OUTPUTS: { bigint - удалено строк }
+--   SIDE_EFFECTS: физический DELETE под letopis.purge='on' (SET LOCAL, сброс в '' как в purge)
+--   LINKS: M-DDL, V-M-DDL
+-- END_CONTRACT: compact
+CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".compact(p_partition text, p_class text)
+RETURNS bigint LANGUAGE plpgsql AS $$
+DECLARE n bigint;
+BEGIN
+    PERFORM set_config('letopis.purge', 'on', true);   -- SET LOCAL: физический DELETE
+    WITH keep AS (
+        SELECT partition, class, id, max(updated) AS mx
+        FROM "<SCHEMA-NAME>"."Entity"
+        WHERE partition = p_partition AND class = p_class
+        GROUP BY partition, class, id)
+    DELETE FROM "<SCHEMA-NAME>"."Entity" e USING keep
+     WHERE e.partition = keep.partition AND e.class = keep.class AND e.id = keep.id
+       AND e.updated < keep.mx;
+    GET DIAGNOSTICS n = ROW_COUNT;
+    PERFORM set_config('letopis.purge', '', true);
+    RETURN n;
+END $$;
+
 -- -----------------------------------------------------------------------------
 -- Метка ревизии движка — ПОСЛЕДНЕЙ строкой: комментарий появляется только если весь
 -- файл применился. Её читает connect() и предупреждает, если схема отстала от либы
@@ -582,7 +667,7 @@ CREATE TRIGGER entity_notify
 -- Несовместимая правка СТРУКТУРЫ таблиц — это смена version в имени схемы (v1 → v2),
 -- а не ревизия.
 -- -----------------------------------------------------------------------------
-COMMENT ON SCHEMA "<SCHEMA-NAME>" IS 'letopis ddl_revision=1';
+COMMENT ON SCHEMA "<SCHEMA-NAME>" IS 'letopis ddl_revision=2';
 
 -- -----------------------------------------------------------------------------
 -- Опционально (включать по мере роста данных):