letopis 0.18.0 → 0.19.0

package/scripts/schema-sync.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * Миграция классов: diff JSON-файла схемы и таблицы Schema + отчёт совместимости.
+ * Ловит ломающие изменения ДО применения: новый валидатор прогоняется по живым
+ * latest-строкам каждого изменённого класса (строгая валидация, как в рантайме).
+ *
+ *   node scripts/schema-sync.mjs --file=my-schema.json --dsn=… --schema=v1.booking
+ *   node scripts/schema-sync.mjs --file=… --dsn=… --schema=v1.booking --apply
+ *
+ * Без --apply — только отчёт (exit 1, если есть несовместимые строки).
+ * Классы, отсутствующие в файле, НЕ удаляются (append-only дух; удаление — вручную).
+ * ancestors/descendants пересчитывает триггер schema_lineage.
+ */
+//
+// FILE: lib/scripts/schema-sync.mjs
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: CLI-миграция схемы — diff JSON-файла и таблицы Schema, ревалидация выборки живых строк, upsert классов при --apply.
+//   SCOPE: парсинг аргументов, канон-сериализация (stable/linkEnd), diff added/changed/removed, проверка совместимости, apply.
+//   DEPENDS: none
+//   LINKS: M-SCHEMA-SYNC, V-M-SCHEMA-SYNC
+//   ROLE: SCRIPT
+//   MAP_MODE: LOCALS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   stable - стабильная сериализация для сравнения
+//   linkEnd/linksCanon - канон элементов Schema.links
+//   FIELDS - поля класса для diff/upsert
+//   added/changed/removed - результат diff файла и БД
+//   breakingRows - живые строки, ломающиеся о новую валидацию
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import postgres from 'postgres';
+
+const Validator = createRequire(import.meta.url)('fastest-validator');
+const v = new Validator({ useNewCustomCheckerFunction: true });
+
+// START_BLOCK_PARSE_ARGS
+const args = Object.fromEntries(
+  process.argv.slice(2).map((a) => {
+    const m = a.match(/^--([^=]+)(?:=(.*))?$/);
+    return m ? [m[1], m[2] ?? true] : [a, true];
+  }),
+);
+const { file, schema } = args;
+const dsn = args.dsn ?? process.env.ENTITY_DSN;
+const partition = args.partition ?? 'entity';
+const sample = Number(args.sample ?? 200);
+if (!file || !dsn || !schema || typeof schema !== 'string') {
+  console.error('usage: node scripts/schema-sync.mjs --file=schema.json --dsn=… --schema=<pg_schema> [--partition=entity] [--sample=200] [--apply]');
+  process.exit(1);
+}
+
+// END_BLOCK_PARSE_ARGS
+const ident = `"${schema.replaceAll('"', '""')}"`;
+/** Поля класса, участвующие в diff и upsert (lineage-колонки считает триггер). */
+const FIELDS = ['alias', 'category', 'ancestor', 'attributes', 'links', 'meta', 'order'];
+
+// START_CONTRACT: stable
+//   PURPOSE: Стабильная сериализация значения (сортировка ключей на всех уровнях) для сравнения diff.
+//   INPUTS: { x: unknown }
+//   OUTPUTS: { string - канонический вид }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SCHEMA-SYNC, V-M-SCHEMA-SYNC
+// END_CONTRACT: stable
+/** Стабильная сериализация для сравнения (сортировка ключей на всех уровнях). */
+function stable(x) {
+  if (Array.isArray(x)) return `[${x.map(stable).join(',')}]`;
+  if (typeof x === 'object' && x !== null)
+    return `{${Object.keys(x).sort().map((k) => `${JSON.stringify(k)}:${stable(x[k])}`).join(',')}}`;
+  return JSON.stringify(x ?? null);
+}
+
+// START_CONTRACT: linkEnd
+//   PURPOSE: Привести элемент links к канону (конец v2: в БД JSON-текст в text[], в файле — объект).
+//   INPUTS: { e: string|object }
+//   OUTPUTS: { string }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SCHEMA-SYNC, V-M-SCHEMA-SYNC
+// END_CONTRACT: linkEnd
+/** Элемент links к канону: в БД конец v2 лежит JSON-текстом в text[], в файле — объектом. */
+function linkEnd(e) {
+  if (typeof e === 'string' && e.trimStart().startsWith('{')) return stable(JSON.parse(e));
+  return typeof e === 'string' ? JSON.stringify(e) : stable(e);
+}
+const linksCanon = (arr) => `[${(arr ?? []).map(linkEnd).join(',')}]`;
+
+const fileClasses = JSON.parse(await readFile(file, 'utf8'));
+const sql = postgres(dsn, { max: 1 });
+
+try {
+  // START_BLOCK_DIFF
+  const dbRows = await sql.unsafe(
+    `SELECT id, alias, category, ancestor, attributes, links, meta, "order" FROM ${ident}."Schema" WHERE partition = $1`,
+    [partition],
+  );
+  const inDb = new Map(dbRows.map((r) => [r.id, r]));
+  const inFile = new Map(fileClasses.map((c) => [c.id, c]));
+
+  const added = fileClasses.filter((c) => !inDb.has(c.id));
+  const removed = dbRows.filter((r) => !inFile.has(r.id));
+  const changed = [];
+  for (const c of fileClasses) {
+    const db = inDb.get(c.id);
+    if (!db) continue;
+    const diff = FIELDS.filter((f) =>
+      f === 'links'
+        ? linksCanon(c.links) !== linksCanon(db.links)
+        : stable(c[f] ?? (f === 'order' ? 0 : f === 'ancestor' ? null : {})) !== stable(db[f]));
+    if (diff.length) changed.push({ cls: c, fields: diff });
+  }
+
+  // END_BLOCK_DIFF
+  console.log(`schema-sync: ${file} ↔ ${schema}.Schema (partition ${partition})`);
+  for (const c of added) console.log(`  + ${c.id} (${c.category} · ${c.alias}) — новый класс`);
+  for (const { cls, fields } of changed) console.log(`  ~ ${cls.id} — изменены: ${fields.join(', ')}`);
+  for (const r of removed) console.log(`  - ${r.id} — в файле отсутствует (НЕ удаляется)`);
+  if (!added.length && !changed.length && !removed.length) console.log('  без изменений');
+
+  // совместимость: живые latest-строки изменённых классов против НОВОЙ строгой валидации
+  // START_BLOCK_COMPAT_CHECK
+  let breakingRows = 0;
+  for (const { cls, fields } of changed) {
+    if (!fields.includes('attributes')) continue;
+    const check = v.compile({ ...cls.attributes, $$strict: true });
+    const rows = await sql.unsafe(
+      `SELECT t.id, t.data FROM (
+         SELECT DISTINCT ON (e.id) e.id, e.data, e.deleted FROM ${ident}."Entity" e
+         WHERE e.partition = $1 AND e.class = $2
+         ORDER BY e.id, e.updated DESC
+       ) t WHERE t.deleted IS NULL LIMIT $3`,
+      [partition, cls.id, sample],
+    );
+    const bad = [];
+    for (const r of rows) {
+      const res = check({ ...r.data, id: r.id });
+      if (res !== true) bad.push({ id: r.id, issues: res });
+    }
+    if (bad.length) {
+      breakingRows += bad.length;
+      console.log(`  ! ${cls.id}: ${bad.length}/${rows.length} живых строк НЕ пройдут новую валидацию:`);
+      for (const b of bad.slice(0, 3)) {
+        console.log(`      id=${b.id} → ${b.issues.map((i) => `${i.field} — ${i.message ?? 'invalid'}`).join('; ')}`);
+      }
+      if (bad.length > 3) console.log(`      … и ещё ${bad.length - 3}`);
+    } else if (rows.length) {
+      console.log(`  ✓ ${cls.id}: ${rows.length} живых строк проходят новую валидацию`);
+    }
+  }
+
+  // END_BLOCK_COMPAT_CHECK
+  // START_BLOCK_APPLY
+  if (!args.apply) {
+    if (breakingRows) {
+      console.log(`ИТОГ: ломающие изменения (${breakingRows} строк). Применение (--apply) сломает запись этих сущностей.`);
+      process.exitCode = 1;
+    } else {
+      console.log(`ИТОГ: ${added.length} новых, ${changed.length} изменённых. Применить: --apply`);
+    }
+  } else {
+    if (breakingRows) console.warn(`ВНИМАНИЕ: применяю НЕсовместимую схему (${breakingRows} строк перестанут проходить валидацию при записи).`);
+    for (const c of [...added, ...changed.map((x) => x.cls)]) {
+      await sql.unsafe(
+        `INSERT INTO ${ident}."Schema" (partition, id, alias, category, ancestor, attributes, links, meta, "order")
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+         ON CONFLICT (partition, id) DO UPDATE SET
+           alias = EXCLUDED.alias, category = EXCLUDED.category, ancestor = EXCLUDED.ancestor,
+           attributes = EXCLUDED.attributes, links = EXCLUDED.links, meta = EXCLUDED.meta, "order" = EXCLUDED."order"`,
+        // links — jsonb-массив (объекты-концы v2 / legacy-строки); postgres.js сериализует сам
+        [partition, c.id, c.alias, c.category, c.ancestor ?? null, c.attributes ?? {},
+         c.links ?? [], c.meta ?? {}, c.order ?? 0],
+      );
+    }
+    console.log(`применено: ${added.length} новых, ${changed.length} изменённых классов`);
+  }
+  // END_BLOCK_APPLY
+} finally {
+  await sql.end();
+}

package/sql/ddl.sql

@@ -321,7 +321,8 @@ CREATE TRIGGER entity_update
 --   * бьёт только актуальную ЖИВУЮ строку (история и tombstone неприкосновенны);
 --   * advisory-lock сериализует параллельные удаления сущности;
 --   * каскад: DELETE живых зависимых (links ⊃ {класс: id}) → рекурсия этого же триггера;
---   * физического удаления не происходит никогда (очистка истории — retention-политики).
+--   * физического удаления не происходит никогда — КРОМЕ явного purge (см. ниже):
+--     при SET LOCAL letopis.purge='on' триггер целиком пропускается (WHEN) → физический DELETE.
 -- Работает и для голого SQL: DELETE FROM "<SCHEMA-NAME>"."Entity" WHERE partition=… AND class=… AND id=…
 -- -----------------------------------------------------------------------------
 -- START_CONTRACT: entity_delete
@@ -363,7 +364,94 @@ END $$;
 DROP TRIGGER IF EXISTS entity_delete ON "<SCHEMA-NAME>"."Entity";
 CREATE TRIGGER entity_delete
     BEFORE DELETE ON "<SCHEMA-NAME>"."Entity"
-    FOR EACH ROW EXECUTE FUNCTION "<SCHEMA-NAME>".entity_delete();
+    FOR EACH ROW
+    -- purge-режим: при SET LOCAL letopis.purge='on' триггер НЕ срабатывает → физический DELETE.
+    -- Обычный путь (флаг не выставлен) видит NULL → IS DISTINCT FROM 'on' = true → триггер работает (tombstone).
+    WHEN (current_setting('letopis.purge', true) IS DISTINCT FROM 'on')
+    EXECUTE FUNCTION "<SCHEMA-NAME>".entity_delete();
+
+-- -----------------------------------------------------------------------------
+-- Физический hard-erase (purge). Вся логика — в БД (две функции); либа лишь зовёт purge():
+--   * purge_closure(partition,class,ids[]) — (class,id) всего поддерева по links (вкл. tombstone);
+--     единый источник замыкания (UNION отсекает циклы/диаманты).
+--   * purge(partition,class,id[,dry]) RETURNS SETOF Entity — двухфазный снос корня + поддерева:
+--       - ДВУХФАЗНОСТЬ: только если сущность уже логически удалена (актуальная версия — tombstone);
+--         живую не трогает (0 строк);
+--       - dry=true  → превью (актуальные версии замыкания), БД не трогается;
+--       - dry=false → SET LOCAL letopis.purge='on' отключает entity_delete (см. WHEN выше) → плоский DELETE
+--         замыкания без вложенного DML (без TM_SelfModified, детерминированно), возвращает снесённое;
+--       - флаг транзакционный (is_local) + явный сброс → дальше в той же tx снова tombstone; привилегий не требует.
+-- Голый SQL:  SELECT * FROM "<SCHEMA-NAME>".purge('entity','Order','X');          -- снос
+--             SELECT * FROM "<SCHEMA-NAME>".purge('entity','Order','X', true);    -- превью
+-- -----------------------------------------------------------------------------
+-- START_CONTRACT: purge_closure
+--   PURPOSE: (class,id)-замыкание поддерева по links (вкл. tombstone) — что снесёт purge(); переиспользуется самой purge() (снос и dry-превью).
+--   INPUTS: { p_partition text; p_class text; p_ids text[] }
+--   OUTPUTS: { SETOF (class text, id text) - узлы замыкания }
+--   SIDE_EFFECTS: none (STABLE)
+--   LINKS: M-DDL, V-M-DDL, M-WRITE, M-SQL
+-- END_CONTRACT: purge_closure
+CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".purge_closure(p_partition text, p_class text, p_ids text[])
+RETURNS TABLE(class text, id text) LANGUAGE sql STABLE AS $$
+    WITH RECURSIVE closure(cls, cid) AS (
+        SELECT p_class, x FROM unnest(p_ids) AS x
+        UNION                                          -- не ALL → отсекает циклы/диаманты links
+        SELECT e.class, e.id
+          FROM "<SCHEMA-NAME>"."Entity" e
+          JOIN closure c ON e.links @> jsonb_build_object(c.cls, c.cid)
+         WHERE e.partition = p_partition
+    )
+    SELECT cls, cid FROM closure;
+$$;
+
+-- START_CONTRACT: purge
+--   PURPOSE: Двухфазно физически стереть логически удалённый корень и всё поддерево (по links, все версии); dry=превью.
+--   INPUTS: { p_partition text; p_class text; p_id text; p_dry boolean = false }
+--   OUTPUTS: { SETOF Entity - снесённые (по одному на сущность, latest) либо превью (dry); пусто если не tombstone }
+--   SIDE_EFFECTS: при dry=false — SET LOCAL letopis.purge (отключает entity_delete на tx) + физический DELETE; advisory-lock
+--   LINKS: M-DDL, V-M-DDL, M-WRITE, M-TABLES
+-- END_CONTRACT: purge
+CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".purge(
+    p_partition text, p_class text, p_id text, p_dry boolean DEFAULT false)
+RETURNS SETOF "<SCHEMA-NAME>"."Entity" LANGUAGE plpgsql AS $$
+BEGIN
+    PERFORM pg_advisory_xact_lock(
+        hashtextextended(p_partition || '|' || p_class || '|' || p_id, 0));
+
+    -- двухфазность: hard-purge только ПОСЛЕ логического удаления — актуальная версия обязана быть tombstone.
+    -- Живую (не удалённую) сущность purge НЕ трогает (возвращает 0 строк).
+    IF NOT EXISTS (
+        SELECT 1 FROM "<SCHEMA-NAME>"."Entity" e
+         WHERE e.partition = p_partition AND e.class = p_class AND e.id = p_id AND e.deleted IS NOT NULL
+           AND e.updated = (SELECT max(updated) FROM "<SCHEMA-NAME>"."Entity"
+                             WHERE partition = p_partition AND class = p_class AND id = p_id)
+    ) THEN
+        RETURN;
+    END IF;
+
+    IF p_dry THEN
+        -- превью: актуальная версия каждого члена замыкания, БД не трогаем
+        RETURN QUERY
+          SELECT DISTINCT ON (e.class, e.id) e.* FROM "<SCHEMA-NAME>"."Entity" e
+            JOIN "<SCHEMA-NAME>".purge_closure(p_partition, p_class, ARRAY[p_id]) c
+              ON e.class = c.class AND e.id = c.id
+           WHERE e.partition = p_partition
+           ORDER BY e.class, e.id, e.updated DESC;
+        RETURN;
+    END IF;
+
+    PERFORM set_config('letopis.purge', 'on', true);   -- SET LOCAL: entity_delete отключён на эту tx
+    RETURN QUERY
+      WITH del AS (
+        DELETE FROM "<SCHEMA-NAME>"."Entity" e
+         USING "<SCHEMA-NAME>".purge_closure(p_partition, p_class, ARRAY[p_id]) c
+         WHERE e.partition = p_partition AND e.class = c.class AND e.id = c.id  -- триггер пропущен (WHEN)
+        RETURNING e.*
+      )
+      SELECT DISTINCT ON (class, id) * FROM del ORDER BY class, id, updated DESC;
+    PERFORM set_config('letopis.purge', '', true);     -- сброс: дальше в той же tx снова tombstone
+    RETURN;
+END $$;
 
 -- =============================================================================
 -- Служебные таблицы (auth/ACL) — перенесены из legacy-дампа 1:1.
@@ -431,6 +519,30 @@ CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Rule" (
 );
 -- END_BLOCK_AUTH_TABLES
 
+-- -----------------------------------------------------------------------------
+-- purge_account(): полный физический офбординг тенанта — все Entity (account|owner) + сам Account.
+--   Credential уходит FK-каскадом (ON DELETE CASCADE). Флаг letopis.purge отключает entity_delete на
+--   снос Entity (см. WHEN). Права/предохранители (Owner-only, последний Owner, не-себя) — в либе
+--   (accounts.purge, им нужен ctx/ACL). Возвращает id снесённого Account либо NULL.
+-- -----------------------------------------------------------------------------
+-- START_CONTRACT: purge_account
+--   PURPOSE: Физически стереть тенанта: все Entity с account|owner = id + сам Account (Credential — FK-каскад).
+--   INPUTS: { p_id uuid }
+--   OUTPUTS: { uuid - id снесённого Account, либо NULL если не найден }
+--   SIDE_EFFECTS: SET LOCAL letopis.purge (отключает entity_delete); физический DELETE Entity + Account
+--   LINKS: M-DDL, V-M-DDL, M-TABLES
+-- END_CONTRACT: purge_account
+CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".purge_account(p_id uuid)
+RETURNS uuid LANGUAGE plpgsql AS $$
+DECLARE gone uuid;
+BEGIN
+    PERFORM set_config('letopis.purge', 'on', true);   -- SET LOCAL: entity_delete отключён (см. WHEN)
+    DELETE FROM "<SCHEMA-NAME>"."Entity" WHERE account = p_id OR owner = p_id;  -- обе оси (иначе entity_owner_fk RESTRICT)
+    PERFORM set_config('letopis.purge', '', true);
+    DELETE FROM "<SCHEMA-NAME>"."Account" WHERE id = p_id RETURNING id INTO gone;  -- Credential — FK-каскад
+    RETURN gone;
+END $$;
+
 -- -----------------------------------------------------------------------------
 -- Триггер 4: realtime — факт каждой новой версии в pg_notify (канал = имя схемы).
 -- Payload лёгкий (без data): подписчик дочитывает нужное сам. Потребитель: db.watch().