letopis 0.16.0 → 0.18.1

package/scripts/gen-types.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * Генерация TS-типов из таблицы Schema:
+ *   npx tsx scripts/gen-types.mjs --dsn=postgres://… --schema=v1.booking [--out=entity-types.d.ts]
+ *
+ * Результат: интерфейсы data-полей каждого класса + фасад TypedDb.
+ *   import type { TypedDb } from './entity-types';
+ *   const t = db as unknown as TypedDb;   // t.Сотрудник(...).rows(): Promise<TypedRow<StaffData>[]>
+ */
+//
+// FILE: lib/scripts/gen-types.mjs
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: CLI-кодген — читает таблицу Schema и печатает типизированный .d.ts-фасад (Data-интерфейсы классов + TypedRow/TypedChain/TypedDb).
+//   SCOPE: парсинг аргументов, чтение Schema, конвертация fastest-validator DSL → TS (ts), эмиссия .d.ts.
+//   DEPENDS: none
+//   LINKS: M-GEN-TYPES, V-M-GEN-TYPES
+//   ROLE: SCRIPT
+//   MAP_MODE: LOCALS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   ts - fastest-validator DSL → TS-тип ({ t, opt })
+//   ident - безопасный идентификатор либо строковый ключ
+//   sql/rows - чтение классов из таблицы Schema
+//   lines/facade - аккумуляторы генерируемого .d.ts
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
+import { writeFile } from 'node:fs/promises';
+import postgres from 'postgres';
+
+// START_BLOCK_PARSE_ARGS
+const args = Object.fromEntries(process.argv.slice(2).map((a) => a.replace(/^--/, '').split('=')));
+const dsn = args.dsn ?? process.env.ENTITY_DSN;
+const schema = args.schema ?? 'booking';
+const out = args.out ?? 'entity-types.d.ts';
+if (!dsn) { console.error('usage: tsx scripts/gen-types.mjs --dsn=… --schema=v1.booking [--out=…]'); process.exit(1); }
+
+// END_BLOCK_PARSE_ARGS
+// START_CONTRACT: ts
+//   PURPOSE: Свести attribute-спеку fastest-validator (строка/массив/объект) к TS-типу и признаку optional.
+//   INPUTS: { attr: unknown - правило поля }
+//   OUTPUTS: { { t: string; opt: boolean } }
+//   SIDE_EFFECTS: none (рекурсивно по вложенным props/items)
+//   LINKS: M-GEN-TYPES, V-M-GEN-TYPES
+// END_CONTRACT: ts
+// fastest-validator DSL → TS-тип
+function ts(attr) {
+  if (typeof attr === 'string') {
+    const parts = attr.split('|').map((s) => s.trim());
+    const opt = parts.includes('optional');
+    const base = { number: 'number', boolean: 'boolean', date: 'string', string: 'string', uuid: 'string', email: 'string', url: 'string', any: 'unknown' }[parts[0]] ?? 'unknown';
+    return { t: base, opt };
+  }
+  if (Array.isArray(attr)) { const first = ts(attr[0] ?? 'any'); return { t: first.t, opt: true }; }
+  if (typeof attr === 'object' && attr !== null) {
+    const opt = attr.optional === true;
+    switch (attr.type) {
+      case 'enum': return { t: (attr.values ?? []).map((v) => JSON.stringify(v)).join(' | ') || 'string', opt };
+      case 'record': {
+        const key = attr.key?.type === 'enum' ? (attr.key.values ?? []).map((v) => JSON.stringify(v)).join(' | ') : 'string';
+        return { t: `Partial<Record<${key || 'string'}, number>>`, opt };
+      }
+      case 'array': {
+        const item = ts(attr.items ?? 'any');
+        return { t: `(${item.t})[]`, opt };
+      }
+      case 'number': return { t: 'number', opt };
+      case 'boolean': return { t: 'boolean', opt };
+      case 'date': return { t: 'string', opt };
+      case 'string': case 'uuid': case 'email': case 'url': return { t: 'string', opt };
+      case 'object': {
+        const props = attr.props ?? attr.properties;
+        if (props && typeof props === 'object') {
+          const fields = Object.entries(props)
+            .map(([k, v]) => { const f = ts(v); return `${ident(k)}${f.opt ? '?' : ''}: ${f.t}`; })
+            .join('; ');
+          return { t: `{ ${fields} }`, opt };
+        }
+        return { t: 'Record<string, unknown>', opt };
+      }
+      default: return { t: 'unknown', opt };
+    }
+  }
+  return { t: 'unknown', opt: true };
+}
+
+const ident = (s) => (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s) ? s : JSON.stringify(s));
+
+// START_BLOCK_READ_SCHEMA
+const sql = postgres(dsn, { max: 1 });
+const rows = await sql.unsafe(
+  `SELECT id, alias, category, attributes, meta FROM "${schema.replaceAll('"', '""')}"."Schema" WHERE partition = 'entity' ORDER BY category, "order"`,
+);
+await sql.end();
+
+// END_BLOCK_READ_SCHEMA
+// START_BLOCK_EMIT_TYPES
+const lines = [
+  '/* Сгенерировано scripts/gen-types.mjs — не редактировать вручную. */',
+  `import type { Row, Filter, Path, Cursor } from 'letopis';`,
+  '',
+  'export interface TypedRow<D> extends Omit<Row, \'data\'> { data: D }',
+  '',
+];
+const facade = [];
+for (const r of rows) {
+  if (r.meta?.abstract === true || r.meta?.abstract === 'true') continue;
+  const name = `${r.id}Data`;
+  lines.push(`/** ${r.category} ${r.id} · ${r.alias} */`, `export interface ${name} {`);
+  for (const [f, attr] of Object.entries(r.attributes)) {
+    if (f === 'id') continue;
+    const { t, opt } = ts(attr);
+    lines.push(`  ${ident(f)}${opt ? '?' : ''}: ${t};`);
+  }
+  lines.push('}', '');
+  for (const key of [r.id, r.alias]) {
+    facade.push(`  ${ident(key)}: (filter?: Filter) => TypedChain<${name}>;`);
+  }
+}
+lines.push(
+  'export interface TypedChain<D> {',
+  '  execute(): Promise<Path[]>;',
+  '  rows(): Promise<TypedRow<D>[]>;',
+  '  first(): Promise<TypedRow<D> | null>;',
+  '  ids(): Promise<string[]>;',
+  '  count(): Promise<number>;',
+  '  versions(): Promise<TypedRow<D>[]>;',
+  '  set(data?: Partial<D> & { id?: string }): PromiseLike<TypedRow<D>[]> & Record<string, (t: string | { id: string }) => unknown>;',
+  '  delete(): Promise<TypedRow<D>[]>;',
+  '  anonymize(fields: (keyof D & string)[]): Promise<TypedRow<D>[]>;',
+  '  limit(n: number): TypedChain<D>;',
+  '  offset(n: number): TypedChain<D>;',
+  '  sort(field: string, dir?: \'asc\' | \'desc\' | boolean): TypedChain<D>;',
+  '  asOf(t: string | Date): TypedChain<D>;',
+  '  after(c: Cursor): TypedChain<D>;',
+  '  alias(name: string): TypedChain<D>;',
+  '  tags(v: string | string[] | object): TypedChain<D>;',
+  '  account(v: string | { id: string }): TypedChain<D>;',
+  '  owner(v: string | { id: string }): TypedChain<D>;',
+  '  [className: string]: unknown;',
+  '}',
+  '',
+  'export interface TypedDb {',
+  ...facade,
+  '}',
+  '',
+);
+// END_BLOCK_EMIT_TYPES
+await writeFile(out, lines.join('\n'), 'utf8');
+console.log(`written ${out}: ${rows.length} classes`);

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

@@ -6,14 +6,41 @@
 -- "<SCHEMA-NAME>" — маркер: letopis.up() / db/apply.mjs подставляет полное имя схемы vN.<имя>.
 -- =============================================================================
 
+-- FILE: lib/sql/ddl.sql
+-- VERSION: 1.0.0
+-- 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.
+--   DEPENDS: none
+--   LINKS: M-DDL, V-M-DDL
+--   ROLE: RUNTIME
+--   MAP_MODE: SUMMARY
+-- END_MODULE_CONTRACT
+--
+-- START_MODULE_MAP
+--   Schema - определения классов (HUB/LINK), наследование, attributes/links
+--   Entity - append-only hypertable версий сущностей и связей
+--   Account/Credential/Resource/Rule - служебные таблицы auth/ACL
+--   schema_lineage - пересчёт ancestors/descendants (statement-level)
+--   entity_check - валидация класса и концов LINK при INSERT
+--   entity_update - UPDATE → вставка новой версии
+--   entity_delete - DELETE → tombstone + рекурсивный каскад (advisory-lock)
+--   entity_notify - pg_notify о новой версии (канал = имя схемы)
+-- END_MODULE_MAP
+--
+-- START_CHANGE_SUMMARY
+--   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+-- END_CHANGE_SUMMARY
+
 CREATE EXTENSION IF NOT EXISTS timescaledb;
 
 CREATE SCHEMA IF NOT EXISTS "<SCHEMA-NAME>";
 
 -- -----------------------------------------------------------------------------
 -- Schema: классы предметной области (HUB — сущности, LINK — связи).
--- Сидится из schema.booking.v2.json (lib/sql/seed.booking.sql).
+-- Сидится демо-доменом booking: lib/sql/seed.booking.sql (источник правды).
 -- -----------------------------------------------------------------------------
+-- START_BLOCK_TABLE_SCHEMA
 CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Schema" (
     partition  text   NOT NULL DEFAULT 'entity',
     id         text   NOT NULL,                  -- англ. id класса: 'Staff', 'skill'
@@ -28,6 +55,7 @@ CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Schema" (
     descendants text[] NOT NULL DEFAULT '{}',    -- все потомки (транзитивно)  — считает триггер schema_lineage
     PRIMARY KEY (partition, id)
 );
+-- END_BLOCK_TABLE_SCHEMA
 
 -- -----------------------------------------------------------------------------
 -- Триггер lineage: ancestors + descendants пересчитываются автоматически
@@ -35,6 +63,13 @@ CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Schema" (
 -- Рекурсивные CTE вверх и вниз; защита от циклов (depth ≤ 32) и от
 -- саморекурсии триггера (pg_trigger_depth).
 -- -----------------------------------------------------------------------------
+-- START_CONTRACT: schema_lineage
+--   PURPOSE: Пересчитать ancestors + descendants всех классов при изменении Schema (statement-level; защита от циклов depth≤32 и саморекурсии).
+--   INPUTS: { trigger: AFTER INSERT/UPDATE(ancestor,id)/DELETE ON Schema }
+--   OUTPUTS: { NULL - обновляет колонки ancestors/descendants }
+--   SIDE_EFFECTS: UPDATE Schema.ancestors/descendants
+--   LINKS: M-DDL, V-M-DDL
+-- END_CONTRACT: schema_lineage
 CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".schema_lineage() RETURNS trigger
 LANGUAGE plpgsql AS $$
 BEGIN
@@ -86,6 +121,7 @@ CREATE TRIGGER schema_lineage
 -- Версия = строка; актуальная версия = max(updated); удаление = tombstone (deleted).
 -- links = {"Класс": "id", ...} — произвольное число ссылок в одной строке.
 -- -----------------------------------------------------------------------------
+-- START_BLOCK_ENTITY_STORAGE
 CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Entity" (
     partition text        NOT NULL,
     id        text        NOT NULL,
@@ -126,6 +162,7 @@ CREATE INDEX IF NOT EXISTS entity_data_idx    ON "<SCHEMA-NAME>"."Entity" USING
 CREATE INDEX IF NOT EXISTS entity_tags_idx    ON "<SCHEMA-NAME>"."Entity" USING gin (tags);
 CREATE INDEX IF NOT EXISTS entity_account_idx ON "<SCHEMA-NAME>"."Entity" (account);
 CREATE INDEX IF NOT EXISTS entity_owner_idx   ON "<SCHEMA-NAME>"."Entity" (owner);
+-- END_BLOCK_ENTITY_STORAGE
 
 -- -----------------------------------------------------------------------------
 -- Триггер 1: целостность при INSERT (только проверки, никакой логики приложения).
@@ -140,6 +177,14 @@ CREATE INDEX IF NOT EXISTS entity_owner_idx   ON "<SCHEMA-NAME>"."Entity" (owner
 --     полиморфный (его резолвит либа), лишние связи не проверяются.
 -- Tombstone-версии (deleted IS NOT NULL) не валидируются.
 -- -----------------------------------------------------------------------------
+-- START_CONTRACT: entity_check
+--   PURPOSE: Проверить при INSERT — класс существует и не абстрактный; ключи links — существующие классы со строковыми id; концы LINK (v2 жадный матчинг / legacy).
+--   INPUTS: { trigger: BEFORE INSERT ON Entity (NEW) }
+--   OUTPUTS: { NEW - либо EXCEPTION }
+--   SIDE_EFFECTS: none (валидация; tombstone-версии пропускаются)
+--   ERRORS: unknown class; class is abstract; links key not a class; link requires end; stray link
+--   LINKS: M-DDL, V-M-DDL, M-WRITE
+-- END_CONTRACT: entity_check
 CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".entity_check() RETURNS trigger
 LANGUAGE plpgsql AS $$
 DECLARE
@@ -184,6 +229,7 @@ BEGIN
 
     -- LINK: концы по Schema.links — jsonb-массив; элемент-объект = v2 (строгий жадный
     -- матчинг по порядку), элемент-строка = legacy-имя класса
+    -- START_BLOCK_ENTITY_CHECK_LINK
     IF s.category = 'LINK' THEN
         is_v2 := EXISTS (
             SELECT 1 FROM jsonb_array_elements(COALESCE(s.links, '[]'::jsonb)) le
@@ -223,6 +269,7 @@ BEGIN
         END IF;
     END IF;
 
+    -- END_BLOCK_ENTITY_CHECK_LINK
     RETURN NEW;
 END $$;
 
@@ -238,6 +285,13 @@ CREATE TRIGGER entity_check
 --   * вставка проходит entity_check (валидация класса/links).
 -- Работает и для голого SQL: UPDATE "<SCHEMA-NAME>"."Entity" SET data=… WHERE …
 -- -----------------------------------------------------------------------------
+-- START_CONTRACT: entity_update
+--   PURPOSE: Превратить UPDATE в INSERT новой версии — бьёт только актуальную строку, историю не трогает, updated монотонно растёт.
+--   INPUTS: { trigger: BEFORE UPDATE ON Entity (OLD/NEW) }
+--   OUTPUTS: { NULL - физический UPDATE отменён }
+--   SIDE_EFFECTS: INSERT новой версии (проходит entity_check)
+--   LINKS: M-DDL, V-M-DDL
+-- END_CONTRACT: entity_update
 CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".entity_update() RETURNS trigger
 LANGUAGE plpgsql AS $$
 DECLARE latest timestamptz;
@@ -270,6 +324,13 @@ CREATE TRIGGER entity_update
 --   * физического удаления не происходит никогда (очистка истории — retention-политики).
 -- Работает и для голого SQL: DELETE FROM "<SCHEMA-NAME>"."Entity" WHERE partition=… AND class=… AND id=…
 -- -----------------------------------------------------------------------------
+-- START_CONTRACT: entity_delete
+--   PURPOSE: Превратить DELETE в tombstone + рекурсивный каскад по links; advisory-lock сериализует параллельные удаления; физического удаления нет.
+--   INPUTS: { trigger: BEFORE DELETE ON Entity (OLD) }
+--   OUTPUTS: { NULL - физическое удаление отменено }
+--   SIDE_EFFECTS: INSERT tombstone; DELETE живых зависимых (рекурсия триггера); pg_advisory_xact_lock
+--   LINKS: M-DDL, V-M-DDL, M-WRITE
+-- END_CONTRACT: entity_delete
 CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".entity_delete() RETURNS trigger
 LANGUAGE plpgsql AS $$
 DECLARE latest timestamptz;
@@ -310,6 +371,7 @@ CREATE TRIGGER entity_delete
 -- =============================================================================
 
 -- Аккаунты: пользователи и сервисы. Категории: System | User | Anonymous | Shadow…
+-- START_BLOCK_AUTH_TABLES
 CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Account" (
     id         uuid                   DEFAULT gen_random_uuid() NOT NULL PRIMARY KEY,
     categories character varying[]    DEFAULT ARRAY['User'::text] NOT NULL,
@@ -367,11 +429,19 @@ CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Rule" (
     enabled    boolean DEFAULT true NOT NULL,
     PRIMARY KEY (account, resource)
 );
+-- END_BLOCK_AUTH_TABLES
 
 -- -----------------------------------------------------------------------------
 -- Триггер 4: realtime — факт каждой новой версии в pg_notify (канал = имя схемы).
 -- Payload лёгкий (без data): подписчик дочитывает нужное сам. Потребитель: db.watch().
 -- -----------------------------------------------------------------------------
+-- START_CONTRACT: entity_notify
+--   PURPOSE: Опубликовать факт новой версии в pg_notify (канал = имя схемы), лёгкий payload без data.
+--   INPUTS: { trigger: AFTER INSERT ON Entity (NEW) }
+--   OUTPUTS: { NULL }
+--   SIDE_EFFECTS: pg_notify(канал = имя схемы)
+--   LINKS: M-DDL, V-M-DDL, M-CHAIN
+-- END_CONTRACT: entity_notify
 CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".entity_notify() RETURNS trigger
 LANGUAGE plpgsql AS $$
 BEGIN

package/sql/seed.auth.sql

@@ -4,11 +4,35 @@
 -- Идемпотентен (ON CONFLICT).
 -- =============================================================================
 
+-- FILE: lib/sql/seed.auth.sql
+-- VERSION: 1.0.0
+-- START_MODULE_CONTRACT
+--   PURPOSE: Идемпотентный сид System-аккаунта и дефолтного набора ACL Resource/Rule для auth-эндпоинтов.
+--   SCOPE: 1 Account (System), 16 Resource (subjects+API), 12 Rule (allow/deny с весами).
+--   DEPENDS: none
+--   LINKS: M-SEED-AUTH, V-M-SEED-AUTH
+--   ROLE: CONFIG
+--   MAP_MODE: SUMMARY
+-- END_MODULE_CONTRACT
+--
+-- START_MODULE_MAP
+--   Account - один System-аккаунт (фикс. id 2eba6d0a-…)
+--   Resource - 16 ресурсов ACL (anonymous/authenticated/any, auth.*, payment/shop/billing/geo)
+--   Rule - 12 правил allow/deny, вес 0..105
+-- END_MODULE_MAP
+--
+-- START_CHANGE_SUMMARY
+--   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+-- END_CHANGE_SUMMARY
+
+-- START_BLOCK_SEED_ACCOUNT
 -- Системный аккаунт (фиксированный id из дампа)
 INSERT INTO "<SCHEMA-NAME>"."Account" (id, categories, data, meta, avatar, enabled) VALUES
   ('2eba6d0a-1edd-4bb6-a85a-a703dab49035', '{System}', '{"id": "System", "name": "System"}', '{}', 'https://i.pravatar.cc/128?img=28', true)
   ON CONFLICT (id) DO NOTHING;
 
+-- END_BLOCK_SEED_ACCOUNT
+-- START_BLOCK_SEED_RESOURCES
 -- Ресурсы: субъекты (категории аккаунтов) и объекты (API-эндпоинты)
 INSERT INTO "<SCHEMA-NAME>"."Resource" (alias, category, pattern, meta) VALUES
   ('anonymous:ACCOUNT',      'ACCOUNT', '{"categories": "{Anonymous,Shadow}"}',  '{"description": "Unauthenticated users (includes Anonymous and Shadow categories)"}'),
@@ -29,6 +53,8 @@ INSERT INTO "<SCHEMA-NAME>"."Resource" (alias, category, pattern, meta) VALUES
   ('geo:API',                'API', '{"endpoint": "v2.geo.*"}',                  NULL)
   ON CONFLICT (alias) DO UPDATE SET category = EXCLUDED.category, pattern = EXCLUDED.pattern, meta = EXCLUDED.meta;
 
+-- END_BLOCK_SEED_RESOURCES
+-- START_BLOCK_SEED_RULES
 -- Правила: субъект → объект → allow|deny (weight — приоритет)
 INSERT INTO "<SCHEMA-NAME>"."Rule" (account, resource, permission, weight, meta, enabled) VALUES
   ('authenticated:ACCOUNT', 'auth.user.password:API', 'allow',  90, '{"description": "Users can change their own password"}', true),
@@ -44,3 +70,4 @@ INSERT INTO "<SCHEMA-NAME>"."Rule" (account, resource, permission, weight, meta,
   ('authenticated:ACCOUNT', 'billing:API',            'allow',  90, '{"description": "Users can access billing (uses ctx.meta.$account.id)"}', true),
   ('authenticated:ACCOUNT', 'geo:API',                'allow',  90, '{"description": "Users can access geo (uses ctx.meta.$account.id)"}', true)
   ON CONFLICT (account, resource) DO UPDATE SET permission = EXCLUDED.permission, weight = EXCLUDED.weight, meta = EXCLUDED.meta, enabled = EXCLUDED.enabled;
+-- END_BLOCK_SEED_RULES