letopis 0.19.0 → 0.20.1

package/scripts/gen-types.mjs

@@ -3,16 +3,21 @@
  * Генерация 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>[]>
+ * Результат: интерфейсы data-полей каждого класса (с УЧЁТОМ наследования attributes),
+ * типизированные цепочки на класс, слоты связей из Schema.links и два фасада:
+ *
+ *   import type { TypedDb, TypedFullDb } from './entity-types';
+ *   const t = db as unknown as TypedDb;       // строго: только шаги по классам, опечатка = ошибка tsc
+ *   const t = db as unknown as TypedFullDb;   // удобно: + begin/batch/auth/acl/tables (опечатки НЕ ловятся)
+ *   await t.Мастер(и).навык().Услуга().rows()          // data типизирована по классу шага
+ *   await t.Мастер(и).запись().create({ notes: 'x' }).Услуга.set(s).rows()
  */
 //
 // FILE: lib/scripts/gen-types.mjs
-// VERSION: 1.0.0
+// VERSION: 1.1.0
 // START_MODULE_CONTRACT
-//   PURPOSE: CLI-кодген — читает таблицу Schema и печатает типизированный .d.ts-фасад (Data-интерфейсы классов + TypedRow/TypedChain/TypedDb).
-//   SCOPE: парсинг аргументов, чтение Schema, конвертация fastest-validator DSL → TS (ts), эмиссия .d.ts.
+//   PURPOSE: CLI-кодген — читает таблицу Schema и печатает типизированный .d.ts-фасад (Data-интерфейсы классов с наследованием + ChainOps/Steps/слоты + TypedDb/TypedFullDb).
+//   SCOPE: парсинг аргументов, чтение Schema, слияние attributes по ancestors, конвертация fastest-validator DSL → TS (ts), разбор Schema.links в слоты, эмиссия .d.ts.
 //   DEPENDS: none
 //   LINKS: M-GEN-TYPES, V-M-GEN-TYPES
 //   ROLE: SCRIPT
@@ -20,14 +25,21 @@
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
+//   RESERVED - имена, которые chain/db-Proxy перехватывает ДО резолва класса (шаг недостижим под этим именем)
 //   ts - fastest-validator DSL → TS-тип ({ t, opt })
 //   ident - безопасный идентификатор либо строковый ключ
+//   typeName - имя генерируемого типа из id класса (без коллизий со служебными)
+//   mergedAttrs - attributes класса со слиянием по ancestors (предок → потомок поверх)
+//   endsOf - Schema.links → список концов { classes, optional }
 //   sql/rows - чтение классов из таблицы Schema
-//   lines/facade - аккумуляторы генерируемого .d.ts
+//   lines/steps - аккумуляторы генерируемого .d.ts
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+//   LAST_CHANGE: [v1.1.0 - Фасад приведён к текущему API: убраны снесённые execute()/set(data) и глушащая
+//     индекс-сигнатура; добавлены run/create/update/delete/purge/withDeleted/deep/агрегации и слоты
+//     .Класс.set()/.unset() из Schema.links; attributes теперь наследуются по ancestors; шаги по классам
+//     типизированы (опечатка = ошибка компиляции); зарезервированные имена исключены из шагов]
 // END_CHANGE_SUMMARY
 import { writeFile } from 'node:fs/promises';
 import postgres from 'postgres';
@@ -40,6 +52,30 @@ 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_BLOCK_RESERVED_NAMES
+/**
+ * Proxy проверяет эти имена ДО ctx.registry.has(prop) (см. lib/src/chain.ts: switch в
+ * makeChain-handler и в makeDb-handler), поэтому класс с таким id/alias недостижим как шаг
+ * под этим именем. Здесь они ИСКЛЮЧАЮТСЯ из типизированных шагов — иначе типы обещали бы
+ * вызов, который в рантайме уходит в модификатор/терминал или в migration-ошибку.
+ * Список сверяется с case-метками chain.ts в scripts/check-docs.mjs.
+ */
+const RESERVED = new Set([
+  // все три handler'а
+  'then',
+  // chain-уровень
+  'entity', 'run', 'execute', 'rows', 'first', 'ids', 'count', 'limit', 'offset', 'sort',
+  'asOf', 'withDeleted', 'deep', 'exact', 'sum', 'avg', 'min', 'max', 'countBy', 'after', 'versions',
+  'create', 'update', 'set', 'delete', 'anonymize', 'purge', 'alias', 'tags', 'account',
+  'owner',
+  // batch-уровень
+  'discard', 'size',
+  // db-уровень: switch + фасады, разбираемые if'ами до switch
+  'as', 'begin', 'commit', 'rollback', 'lock', 'batch', 'watch', 'close', 'reloadSchema',
+  'registry', 'sql', 'accounts', 'credentials', 'resources', 'rules', 'schema', 'auth', 'acl',
+]);
+
+// END_BLOCK_RESERVED_NAMES
 // START_CONTRACT: ts
 //   PURPOSE: Свести attribute-спеку fastest-validator (строка/массив/объект) к TS-типу и признаку optional.
 //   INPUTS: { attr: unknown - правило поля }
@@ -90,65 +126,225 @@ function ts(attr) {
 
 const ident = (s) => (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s) ? s : JSON.stringify(s));
 
+// служебные имена генерируемого файла — класс с таким id получит суффикс, чтобы не затенять
+const OWN_TYPES = new Set(['TypedRow', 'ChainOps', 'Steps', 'AnyChain', 'TypedDb', 'TypedFullDb', 'SlotTarget']);
+// START_CONTRACT: typeName
+//   PURPOSE: Построить безопасное имя генерируемого типа из id класса.
+//   INPUTS: { id: string - id класса; suffix: string - 'Data' | 'Chain' | 'Slots' }
+//   OUTPUTS: { string - имя типа, не конфликтующее со служебными }
+//   SIDE_EFFECTS: none
+//   LINKS: M-GEN-TYPES, V-M-GEN-TYPES
+// END_CONTRACT: typeName
+function typeName(id, suffix) {
+  const base = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(id) ? id : id.replace(/[^A-Za-z0-9_$]/g, '_');
+  const name = `${base}${suffix}`;
+  return OWN_TYPES.has(name) ? `${name}_` : name;
+}
+
 // 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"`,
+  `SELECT id, alias, category, ancestor, ancestors, attributes, links, meta FROM "${schema.replaceAll('"', '""')}"."Schema" WHERE partition = 'entity' ORDER BY category, "order"`,
 );
 await sql.end();
+const byId = new Map(rows.map((r) => [r.id, r]));
 
 // END_BLOCK_READ_SCHEMA
-// START_BLOCK_EMIT_TYPES
+// START_CONTRACT: mergedAttrs
+//   PURPOSE: Слить attributes класса по цепочке ancestors (предок → потомок поверх), как это делает M-SCHEMA.buildDef.
+//   INPUTS: { r: object - строка Schema }
+//   OUTPUTS: { Record<string, unknown> - слитые attributes }
+//   SIDE_EFFECTS: none
+//   LINKS: M-GEN-TYPES, M-SCHEMA, V-M-GEN-TYPES
+// END_CONTRACT: mergedAttrs
+function mergedAttrs(r) {
+  // attributes НАСЛЕДУЮТСЯ (lib/src/schema.ts: buildDef); links — НЕТ
+  let chain = Array.isArray(r.ancestors) && r.ancestors.length ? r.ancestors : null;
+  if (!chain) {
+    chain = [r.id];
+    let cur = r.ancestor;
+    const seen = new Set([r.id]);
+    while (cur && !seen.has(cur)) { chain.push(cur); seen.add(cur); cur = byId.get(cur)?.ancestor ?? null; }
+  }
+  const merged = {};
+  for (let i = chain.length - 1; i >= 0; i--) Object.assign(merged, byId.get(chain[i])?.attributes ?? {});
+  return merged;
+}
+
+// START_CONTRACT: endsOf
+//   PURPOSE: Разобрать Schema.links класса в список концов (как M-SCHEMA.parseEnd, без валидации).
+//   INPUTS: { r: object - строка Schema }
+//   OUTPUTS: { { classes: string[]; optional: boolean }[] }
+//   SIDE_EFFECTS: none
+//   LINKS: M-GEN-TYPES, M-SCHEMA, V-M-GEN-TYPES
+// END_CONTRACT: endsOf
+function endsOf(r) {
+  let raw = r.links ?? [];
+  if (typeof raw === 'string') { try { raw = JSON.parse(raw); } catch { return []; } }
+  if (!Array.isArray(raw)) return [];
+  return raw.map((e) => {
+    if (typeof e === 'string') {
+      if (!e.trimStart().startsWith('{')) return { classes: [e], optional: false };
+      try { e = JSON.parse(e); } catch { return null; }
+    }
+    const classes = e.classes ?? (e.class ? [e.class] : []);
+    return classes.length ? { classes, optional: e.optional === true } : null;
+  }).filter(Boolean);
+}
+
+// START_BLOCK_EMIT_HEADER
 const lines = [
   '/* Сгенерировано scripts/gen-types.mjs — не редактировать вручную. */',
-  `import type { Row, Filter, Path, Cursor } from 'letopis';`,
+  `/* Схема: ${schema} · классов: ${rows.length} */`,
+  '',
+  `import type { Row, Path, Filter, Cursor, Chain, EntityDb } from 'letopis';`,
   '',
   'export interface TypedRow<D> extends Omit<Row, \'data\'> { data: D }',
   '',
+  '/** Цель слота связи: id | Row/сущность с id | вложенная цепочка (та же транзакция). */',
+  'export type SlotTarget = string | { id: string } | Chain;',
+  '',
+  '/**',
+  ' * Терминалы, модификаторы и глаголы записи цепочки. Self — тип конкретной цепочки-класса,',
+  ' * поэтому модификаторы и глаголы записи сохраняют типизацию data.',
+  ' * ВНИМАНИЕ: create/update/delete/purge/anonymize возвращают ЦЕПОЧКУ (звено плана),',
+  ' * исполняет её терминал (.rows()/.run()/…), а не сам глагол.',
+  ' */',
+  'export interface ChainOps<D, Self> {',
+  '  /** Пути: [{шаг1: Row, шаг2: Row, …}, …]. */',
+  '  run(): Promise<Path[]>;',
+  '  /** Уникальные сущности последнего шага. */',
+  '  rows(): Promise<TypedRow<D>[]>;',
+  '  first(): Promise<TypedRow<D> | null>;',
+  '  ids(): Promise<string[]>;',
+  '  /** Число ПУТЕЙ. */',
+  '  count(): Promise<number>;',
+  '  /** ВСЕ версии сущностей последнего шага, по возрастанию updated. */',
+  '  versions(): Promise<TypedRow<D>[]>;',
+  '  sum(field: string): Promise<number | null>;',
+  '  avg(field: string): Promise<number | null>;',
+  '  min(field: string): Promise<unknown>;',
+  '  max(field: string): Promise<unknown>;',
+  '  countBy(field: string): Promise<Record<string, number>>;',
+  '  limit(n: number): Self;',
+  '  offset(n: number): Self;',
+  '  sort(field: string, dir?: \'asc\' | \'desc\' | boolean): Self;',
+  '  /** Чтение «как было на момент T». */',
+  '  asOf(t: string | Date): Self;',
+  '  /** Keyset-пагинация; требует .sort(). */',
+  '  after(cursor: Cursor): Self;',
+  '  /** Включить удалённые (tombstone) в выдачу последнего шага. */',
+  '  withDeleted(): Self;',
+  '  /** Рекурсивный self-обход: дети любой глубины (тот же класс). */',
+  '  deep(max?: number): Self;',
+  '  /** Снять полиморфизм шага: только свой класс, без классов-потомков. */',
+  '  exact(): Self;',
+  '  alias(name: string): Self;',
+  '  tags(v: string | string[] | object): Self;',
+  '  account(v: string | { id: string }): Self;',
+  '  owner(v: string | { id: string }): Self;',
+  '  /** Вклейка узла/паттерна — тип шага не выводится, отсюда AnyChain. */',
+  '  entity(x: Chain | Row): AnyChain;',
+  '  /** Звено: вставить сущность. id — по Schema (v4/v7/v5); фильтр-объект перед create() — ошибка. */',
+  '  create(data?: Partial<D> & { id?: string }): Self;',
+  '  /** Звено: новая версия каждой найденной путём (deep-merge листьев data). */',
+  '  update(data?: Partial<D>): Self;',
+  '  /** Звено: без confirm — превью (БД не тронута); { confirm: true } — tombstone + каскад. */',
+  '  delete(opts?: { confirm?: boolean }): Self;',
+  '  /** Звено: ФИЗИЧЕСКИЙ hard-erase уже удалённых (tombstone). Живую сущность не трогает — вернёт пусто. */',
+  '  purge(opts?: { confirm?: boolean }): Self;',
+  '  /** Звено: затереть string-поля + тег anonymized. */',
+  '  anonymize(fields: (keyof D & string)[]): Self;',
+  '}',
+  '',
 ];
-const facade = [];
+
+// END_BLOCK_EMIT_HEADER
+// START_BLOCK_EMIT_CLASSES
+const steps = [];
+const skipped = [];
 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 dataT = typeName(r.id, 'Data');
+  const chainT = typeName(r.id, 'Chain');
+  const slotsT = typeName(r.id, 'Slots');
+
+  lines.push(`/** ${r.category} ${r.id} · ${r.alias} */`, `export interface ${dataT} {`);
+  for (const [f, attr] of Object.entries(mergedAttrs(r))) {
+    if (f === 'id' || f.startsWith('$$')) 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}>;`);
+
+  // слоты: концы Schema.links владельца; союз задаётся ЛЮБЫМ своим классом; unset() — только optional
+  const ends = endsOf(r);
+  const slotKeys = [];
+  for (const end of ends) {
+    for (const c of end.classes) {
+      const target = byId.get(c);
+      for (const key of target ? [target.id, target.alias] : [c]) {
+        if (slotKeys.some((s) => s.key === key)) continue;
+        slotKeys.push({ key, optional: end.optional });
+      }
+    }
+  }
+  if (slotKeys.length) {
+    lines.push(`/** Концы связей ${r.id} (Schema.links): .Класс.set(target) / .unset(). */`, `export interface ${slotsT} {`);
+    for (const { key, optional } of slotKeys) {
+      const body = optional
+        ? `{ set(target: SlotTarget): ${chainT}; unset(): ${chainT} }`
+        : `{ set(target: SlotTarget): ${chainT} }`;
+      lines.push(`  ${ident(key)}: ${body};`);
+    }
+    lines.push('}', '');
+  }
+
+  lines.push(
+    `export type ${chainT} = ChainOps<${dataT}, ${chainT}> & Steps${slotKeys.length ? ` & ${slotsT}` : ''};`,
+    '',
+  );
+
+  const names = [r.id, r.alias].filter((n, i, a) => a.indexOf(n) === i);
+  const usable = names.filter((n) => !RESERVED.has(n));
+  if (!usable.length) { skipped.push(`${r.id}·${r.alias}`); continue; }
+  for (const n of names) {
+    if (RESERVED.has(n)) {
+      steps.push(`  /** ⚠ "${n}" зарезервировано цепочкой — шаг доступен как ${usable.map((u) => `\`${u}\``).join(' / ')}. */`);
+      continue;
+    }
+    steps.push(`  ${ident(n)}(filter?: Filter): ${chainT};`);
   }
 }
+
+// END_BLOCK_EMIT_CLASSES
+// START_BLOCK_EMIT_FACADE
 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;',
+  '/**',
+  ' * Шаги по классам — доступны с любой цепочки и с корня db. ЗАКОННОСТЬ перехода',
+  ' * (HUB↔LINK, pivot, «no path X → Y») проверяет letopis синхронно при построении цепочки;',
+  ' * типы этого не гарантируют — они ловят опечатки в именах и типизируют data шага.',
+  ' */',
+  'export interface Steps {',
+  ...steps,
   '}',
   '',
-  'export interface TypedDb {',
-  ...facade,
-  '}',
+  '/** Цепочка с невыведенным классом шага (результат entity()). */',
+  'export type AnyChain = ChainOps<Record<string, unknown>, AnyChain> & Steps;',
+  '',
+  '/** Строгий фасад: только шаги по классам — опечатка в имени класса = ошибка компиляции. */',
+  'export type TypedDb = Steps;',
+  '',
+  '/** Полный фасад: шаги + begin/batch/watch/auth/acl/служебные таблицы.',
+  '  * Индекс-сигнатура EntityDb означает, что опечатки здесь НЕ ловятся. */',
+  'export type TypedFullDb = Steps & EntityDb;',
   '',
 );
-// END_BLOCK_EMIT_TYPES
+if (skipped.length) {
+  lines.push(`/* Без типизированного шага (все имена зарезервированы цепочкой): ${skipped.join(', ')} */`, '');
+}
+
+// END_BLOCK_EMIT_FACADE
 await writeFile(out, lines.join('\n'), 'utf8');
 console.log(`written ${out}: ${rows.length} classes`);
+if (skipped.length) console.warn(`gen-types: пропущены шаги для ${skipped.join(', ')} — имена зарезервированы цепочкой`);

package/sql/ddl.sql

@@ -7,7 +7,8 @@
 -- =============================================================================
 
 -- FILE: lib/sql/ddl.sql
--- VERSION: 1.0.0
+-- VERSION: 1.1.0
+-- DDL_REVISION: 1   (последняя строка файла штампует её в 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.
@@ -570,6 +571,19 @@ CREATE TRIGGER entity_notify
     AFTER INSERT ON "<SCHEMA-NAME>"."Entity"
     FOR EACH ROW EXECUTE FUNCTION "<SCHEMA-NAME>".entity_notify();
 
+-- -----------------------------------------------------------------------------
+-- Метка ревизии движка — ПОСЛЕДНЕЙ строкой: комментарий появляется только если весь
+-- файл применился. Её читает connect() и предупреждает, если схема отстала от либы
+-- (DDL_REVISION в lib/src/types.ts; совпадение сверяет scripts/check-docs.mjs).
+--
+-- Ревизия — про АДДИТИВНЫЕ правки внутри одной версии движка (новые функции/триггеры/
+-- индексы): файл идемпотентен, поэтому такие правки доезжают повторным накатом
+-- (up({ upgrade: true }) / node db/apply.mjs --upgrade), данные при этом целы.
+-- Несовместимая правка СТРУКТУРЫ таблиц — это смена version в имени схемы (v1 → v2),
+-- а не ревизия.
+-- -----------------------------------------------------------------------------
+COMMENT ON SCHEMA "<SCHEMA-NAME>" IS 'letopis ddl_revision=1';
+
 -- -----------------------------------------------------------------------------
 -- Опционально (включать по мере роста данных):
 --

package/sql/seed.booking.sql

@@ -1,11 +1,11 @@
 -- =============================================================================
--- Сид таблицы Schema — ИСТОЧНИК ПРАВДЫ демо-домена booking (19 классов, 0.17).
+-- Сид таблицы Schema — ИСТОЧНИК ПРАВДЫ демо-домена booking (20 классов: 12 HUB + 8 LINK).
 -- Редактируется руками; накат: db/apply.mjs / up() (маркер <SCHEMA-NAME>).
 -- Идемпотентен (ON CONFLICT). Концы связей — Schema.links v2 (JSON-объекты в text[]).
 -- =============================================================================
 --
 -- FILE: lib/sql/seed.booking.sql
--- VERSION: 1.0.0
+-- VERSION: 1.0.1
 -- START_MODULE_CONTRACT
 --   PURPOSE: Идемпотентный сид таблицы Schema — источник правды демо-домена booking (классы HUB + LINK).
 --   SCOPE: 20 INSERT-ов классов (12 HUB: Entity/Org/Person/Staff/Customer/Location/Element/Service/Product/Complex/Schedule/Folder; 8 LINK: link/address/slot/booking/content/compo/skill/price).
@@ -18,11 +18,12 @@
 -- START_MODULE_MAP
 --   HUB-классы - сущности домена (наследование от Entity; id v5/v7)
 --   LINK-классы - связи (концы Schema.links v2; id v5 из концов)
---   NB: фактически 20 классов (12 HUB + 8 LINK); заголовок файла говорит «19» — расхождение
+--   NB: 20 классов (12 HUB + 8 LINK); число в заголовке файла сверяет scripts/check-docs.mjs
 -- END_MODULE_MAP
 --
 -- START_CHANGE_SUMMARY
---   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+--   LAST_CHANGE: [v1.0.1 - Docs-only: заголовок файла приведён к факту (20 классов: 12 HUB + 8 LINK);
+--     число теперь проверяется автоматически. INSERT-ы не менялись]
 -- END_CHANGE_SUMMARY
 --
 -- START_BLOCK_SEED_HUB_CLASSES