letopis 0.18.1 → 0.20.0

package/scripts/gen-api-contract.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Машиночитаемый контракт публичного API → docs/api-contract.json:
+ *   node scripts/gen-api-contract.mjs [--out=../docs/api-contract.json] [--check]
+ *
+ * Всё ВЫВОДИТСЯ из исходников (src/index.ts, src/chain.ts, src/types.ts) — файл не
+ * набивается руками, иначе он стал бы очередным источником дрейфа. --check не пишет,
+ * а сравнивает с закоммиченным и выходит с кодом 1 при расхождении (используется в CI).
+ *
+ * Назначение: дать ИИ-агенту разбираемый список того, ЧТО есть и чего УЖЕ НЕТ,
+ * не заставляя читать 3500 строк README.
+ */
+//
+// FILE: lib/scripts/gen-api-contract.mjs
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Сгенерировать docs/api-contract.json из исходников — экспорты, поверхность цепочки, снесённые имена, зарезервированные имена классов, каталог ошибок.
+//   SCOPE: парсинг src/index.ts (barrel), src/chain.ts (case-метки Proxy + ChainCore), src/types.ts (RESERVED_CLASS_NAMES), сбор throw-сообщений; запись/сверка JSON.
+//   DEPENDS: none
+//   LINKS: M-GEN-API-CONTRACT, V-M-GEN-API-CONTRACT
+//   ROLE: SCRIPT
+//   MAP_MODE: LOCALS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   read - прочитать файл пакета относительно lib/
+//   exportsOf - публичные значения и типы из barrel src/index.ts
+//   chainSurface - case-метки Proxy цепочки/db + сигнатуры ChainCore
+//   removedNames - снесённые имена с версией и заменой (из migration-охранников)
+//   errorCatalog - все throw-сообщения letopis: с указанием файла
+//   main - сборка контракта, запись либо --check
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Новый модуль: генерируемый машиночитаемый контракт API для агентов]
+// END_CHANGE_SUMMARY
+import { readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+const LIB = fileURLToPath(new URL('..', import.meta.url));
+const args = Object.fromEntries(process.argv.slice(2).map((a) => a.replace(/^--/, '').split('=')));
+const out = args.out ?? join(LIB, '..', 'docs', 'api-contract.json');
+const check = 'check' in args;
+
+const read = (p) => readFile(join(LIB, p), 'utf8');
+
+// START_CONTRACT: exportsOf
+//   PURPOSE: Собрать публичную поверхность из barrel src/index.ts (значения и типы).
+//   INPUTS: { src: string - текст src/index.ts }
+//   OUTPUTS: { { values: string[]; types: string[] } }
+//   SIDE_EFFECTS: none
+//   LINKS: M-GEN-API-CONTRACT, M-CONNECT
+// END_CONTRACT: exportsOf
+function exportsOf(src) {
+  const values = new Set();
+  const types = new Set();
+  // export function foo / export const foo / export class Foo
+  for (const m of src.matchAll(/^export\s+(?:async\s+)?(?:function|const|class)\s+([A-Za-z_$][\w$]*)/gm)) {
+    values.add(m[1]);
+  }
+  // export { a, b } from '…'  /  export type { A, B } from '…'
+  for (const m of src.matchAll(/^export\s+(type\s+)?\{([^}]+)\}/gm)) {
+    const bucket = m[1] ? types : values;
+    for (const raw of m[2].split(',')) {
+      const name = raw.trim().split(/\s+as\s+/).pop().trim();
+      if (name) bucket.add(name);
+    }
+  }
+  return { values: [...values].sort(), types: [...types].sort() };
+}
+
+// START_CONTRACT: chainSurface
+//   PURPOSE: Извлечь имена, которые Proxy разбирает до резолва класса, и сигнатуры ChainCore.
+//   INPUTS: { chain: string - текст src/chain.ts }
+//   OUTPUTS: { { chainNames: string[]; dbNames: string[]; chainCore: {name,signature}[] } }
+//   SIDE_EFFECTS: none
+//   LINKS: M-GEN-API-CONTRACT, M-CHAIN
+// END_CONTRACT: chainSurface
+function chainSurface(chain) {
+  // ТРИ handler-switch'а, каждый разбирает имена до ctx.registry.has(prop):
+  // makeChain (цепочка) → makeBatch (батч) → makeDb (корень)
+  const batchAt = chain.indexOf('function makeBatch');
+  const dbAt = chain.indexOf('export function makeDb');
+  // перехват бывает ДВУХ форм: case-метка switch'а И ранний `if (prop === '…')`
+  // (так разбираются фасады db.accounts/auth/acl и гашение 'then') — ловим обе
+  const names = (text) =>
+    [
+      ...new Set([
+        ...[...text.matchAll(/case '([A-Za-z_$][\w$]*)':/g)].map((m) => m[1]),
+        ...[...text.matchAll(/(?<!typeof )prop === '([A-Za-z_$][\w$]*)'/g)].map((m) => m[1]),
+      ]),
+    ].sort();
+  const chainNames = names(chain.slice(0, batchAt));
+  const batchNames = names(chain.slice(batchAt, dbAt)).filter((n) => !chainNames.includes(n));
+  const dbNames = names(chain.slice(dbAt)).filter((n) => !chainNames.includes(n) && !batchNames.includes(n));
+
+  // ChainCore — источник истины поверхности цепочки для типов и кодогена
+  const body = chain.slice(chain.indexOf('export interface ChainCore {'));
+  const end = body.indexOf('\n}');
+  const chainCore = [...body.slice(0, end).matchAll(/^\s{2}([A-Za-z_$][\w$]*)\((.*?)\):\s*(.+?);$/gm)]
+    .map((m) => ({ name: m[1], signature: `${m[1]}(${m[2]}): ${m[3]}` }));
+  return { chainNames, batchNames, dbNames, chainCore };
+}
+
+// START_CONTRACT: removedNames
+//   PURPOSE: Собрать снесённые имена API с версией удаления и заменой (из migration-охранников chain.ts).
+//   INPUTS: { chain: string - текст src/chain.ts }
+//   OUTPUTS: { { name, removedIn, message }[] }
+//   SIDE_EFFECTS: none
+//   LINKS: M-GEN-API-CONTRACT, M-CHAIN
+// END_CONTRACT: removedNames
+function removedNames(chain) {
+  const byMsg = new Map();
+  // все migration-охранники: renamed / removed / split into — с версией в скобках
+  for (const m of chain.matchAll(/letopis: ([^'`\n]*?(?:renamed to|removed|split into)[^'`\n]*)/g)) {
+    const text = m[1].replace(/\$\{[^}]*\}/g, '<…>').replace(/\s+/g, ' ').trim();
+    const ver = text.match(/\((\d+\.\d+\.\d+)\)/);
+    // что именно снесено: 'batch.execute()' / '.link()' / 'slot .delete()' / 'set()'
+    const what = text.match(/^((?:[A-Za-z_$][\w$]*\s+)?\.?[\w$.]*\(\))/);
+    const key = text.slice(0, 60);
+    if (byMsg.has(key)) continue;
+    byMsg.set(key, {
+      removed: what ? what[1] : null,
+      removedIn: ver ? ver[1] : null,
+      replacement: text.includes('—') ? text.split('—').slice(1).join('—').trim() : null,
+      message: `letopis: ${text}`,
+    });
+  }
+  return [...byMsg.values()].sort((a, b) => String(a.removed).localeCompare(String(b.removed)));
+}
+
+// START_CONTRACT: errorCatalog
+//   PURPOSE: Собрать все throw-сообщения letopis по модулям — greppable каталог для агента.
+//   INPUTS: { files: Map<string,string> - имя модуля → текст }
+//   OUTPUTS: { { module, message }[] - шаблоны сообщений с ${…} как <…> }
+//   SIDE_EFFECTS: none
+//   LINKS: M-GEN-API-CONTRACT
+// END_CONTRACT: errorCatalog
+function errorCatalog(files) {
+  const rows = [];
+  for (const [mod, text] of files) {
+    for (const m of text.matchAll(/letopis(?:\.up|\.purge)?:\s?([^'`\n]{4,160})/g)) {
+      const msg = m[0].replace(/\$\{[^}]*\}/g, '<…>').replace(/\s+/g, ' ').trim();
+      if (!rows.some((r) => r.message === msg)) rows.push({ module: mod, message: msg });
+    }
+  }
+  return rows.sort((a, b) => a.message.localeCompare(b.message));
+}
+
+// START_BLOCK_MAIN
+const index = await read('src/index.ts');
+const chain = await read('src/chain.ts');
+const types = await read('src/types.ts');
+const pkg = JSON.parse(await read('package.json'));
+
+const { chainNames, batchNames, dbNames, chainCore } = chainSurface(chain);
+// начинаем ПОСЛЕ '= [' — иначе первый '[' попадёт на 'readonly string[]'
+const RES_MARK = 'RESERVED_CLASS_NAMES: readonly string[] = [';
+const resStart = types.indexOf(RES_MARK) + RES_MARK.length;
+// комментарии выбрасываем ДО извлечения строк: апостроф или пример в кавычках внутри
+// комментария иначе попадёт в список
+const reserved = [
+  ...types
+    .slice(resStart, types.indexOf('];', resStart))
+    .replace(/\/\/[^\n]*/g, '')
+    .matchAll(/'([^']+)'/g),
+].map((m) => m[1]);
+if (!reserved.length) throw new Error('gen-api-contract: не разобрал RESERVED_CLASS_NAMES из src/types.ts');
+
+const files = new Map([
+  ['chain', chain], ['sql', await read('src/sql.ts')], ['write', await read('src/write.ts')],
+  ['schema', types && (await read('src/schema.ts'))], ['tables', await read('src/tables.ts')],
+  ['auth', await read('src/auth.ts')], ['acl', await read('src/acl.ts')],
+  ['tx', await read('src/tx.ts')], ['up', await read('src/up.ts')], ['index', index],
+]);
+
+const contract = {
+  $comment:
+    'СГЕНЕРИРОВАНО lib/scripts/gen-api-contract.mjs из исходников — не редактировать руками. ' +
+    'Регенерация: cd lib && npm run api:contract. CI сверяет через npm run check:docs.',
+  package: { name: pkg.name, type: pkg.type, engines: pkg.engines, entry: pkg.main, types: pkg.types },
+  note: {
+    versionSource: 'lib/package.json + верхняя запись lib/CHANGELOG.md',
+    schemaOption:
+      'connect({schema}) требует ПОЛНОГО имени PG-схемы С версией движка ("v1.booking"); ' +
+      'up({schema,version}) берёт БАЗОВОЕ имя без точек и строит "v<version>.<schema>"',
+    classStep: 'шаг цепочки принимает id ИЛИ alias класса из таблицы Schema (db.Org ≡ db.Организация)',
+    writeVerbs: 'create/update/delete/purge/anonymize возвращают ЦЕПОЧКУ (звено плана); исполняет терминал',
+  },
+  exports: exportsOf(index),
+  chain: {
+    core: chainCore,
+    interceptedByChainProxy: chainNames,
+    interceptedByBatchProxy: batchNames,
+    interceptedByDbProxy: dbNames,
+    reservedClassNames: reserved,
+    reservedClassNamesNote:
+      'класс с таким id/alias недостижим как шаг ПОД ЭТИМ именем; schema.define() отказывает, loadRegistry предупреждает',
+  },
+  removed: removedNames(chain),
+  errors: errorCatalog(files),
+};
+
+const json = `${JSON.stringify(contract, null, 2)}\n`;
+if (check) {
+  let current = null;
+  try { current = await readFile(out, 'utf8'); } catch { /* нет файла — расхождение */ }
+  if (current !== json) {
+    console.error(`api-contract: ${out} устарел — перегенерируйте: cd lib && npm run api:contract`);
+    process.exit(1);
+  }
+  console.log('api-contract: актуален');
+} else {
+  await writeFile(out, json, 'utf8');
+  console.log(
+    `written ${out}: ${contract.exports.values.length} values, ${contract.exports.types.length} types, ` +
+      `${chainCore.length} chain methods, ${contract.removed.length} removed, ${contract.errors.length} errors`,
+  );
+}
+// END_BLOCK_MAIN

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(', ')} — имена зарезервированы цепочкой`);