letopis 0.16.0 → 0.18.1

package/dist/chain.js

@@ -5,6 +5,13 @@ import { makeTables } from './tables.js';
 import { makeAuth } from './auth.js';
 import { makeAcl } from './acl.js';
 /** Фильтр-аргумент принимает и Row/Account-объект — берётся его id. */
+// START_CONTRACT: normalizeFilter
+//   PURPOSE: Нормализует фильтр-аргумент — Row/Account-объект сворачивается в свой id.
+//   INPUTS: { f: Filter | undefined - id-строка, объект-предикат, массив либо Row/Account }
+//   OUTPUTS: { Filter | undefined - id-строка для Row/Account, иначе исходный фильтр }
+//   SIDE_EFFECTS: none
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: normalizeFilter
 function normalizeFilter(f) {
     if (f !== undefined &&
         typeof f === 'object' &&
@@ -20,10 +27,24 @@ const clsOf = (steps) => steps.map((s) => s.cls.id);
 export const PLAN = Symbol('letopis.plan');
 const peekPlan = (x) => x !== null && typeof x === 'object' ? x[PLAN] : undefined;
 /** Конец схемы владельца, принимающий класс слота (legacy: 'Entity'-конец берёт любой HUB). */
+// START_CONTRACT: findEnd
+//   PURPOSE: Находит конец Schema.links владельца, принимающий класс слота (legacy: конец 'Entity' берёт любой HUB при нестрогих концах).
+//   INPUTS: { owner: ClassDef - класс-владелец связей; slot: ClassDef - класс устанавливаемого конца }
+//   OUTPUTS: { LinkEnd | undefined - подходящий конец связи или undefined }
+//   SIDE_EFFECTS: none
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: findEnd
 function findEnd(owner, slot) {
     return owner.links.find((e) => e.classes.includes(slot.id) || (!owner.strictEnds && e.classes.includes('Entity') && slot.category === 'HUB'));
 }
 /** Значение слота: id-строка | Row | цепочка (одношаговый адрес сворачивается в id). */
+// START_CONTRACT: slotValue
+//   PURPOSE: Приводит значение слота к SlotValue — id-строка, Row (берётся id) или ленивая цепочка (одношаговый адрес db.Класс(id) сворачивается в id, иначе вложенный план).
+//   INPUTS: { slotCls: ClassDef - класс конца связи; v: unknown - id | Row | Chain }
+//   OUTPUTS: { SlotValue - id-строка либо { plan, mods } вложенной цепочки }
+//   SIDE_EFFECTS: бросает при цепочке чужого класса или неподдержанном значении
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: slotValue
 function slotValue(slotCls, v) {
     if (typeof v === 'string')
         return v;
@@ -44,6 +65,13 @@ function slotValue(slotCls, v) {
     throw new Error(`letopis: slot "${slotCls.id}" accepts an id, a Row or a chain`);
 }
 /** Узел для pivot: последний реальный шаг класса cls в ТЕКУЩЕМ читающем сегменте (до op). */
+// START_CONTRACT: pivotNodeOf
+//   PURPOSE: Ищет последний реальный шаг класса cls в текущем читающем сегменте (до первой операции) — узел для pivot-возврата.
+//   INPUTS: { steps: Step[] - шаги цепочки; cls: ClassDef - искомый класс }
+//   OUTPUTS: { Step | undefined - шаг-узел, либо undefined если операция закрыла паттерн }
+//   SIDE_EFFECTS: none
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: pivotNodeOf
 function pivotNodeOf(steps, cls) {
     for (let i = steps.length - 1; i >= 0; i--) {
         const s = steps[i];
@@ -54,7 +82,15 @@ function pivotNodeOf(steps, cls) {
     }
     return undefined;
 }
+// START_CONTRACT: runPaths
+//   PURPOSE: Исполняет читающий план в режиме путей — строит SQL через buildRead и мапит строки в Path (узлы каждого варианта).
+//   INPUTS: { ctx: Ctx - контекст соединения/схемы; steps: Step[] - шаги; mods: ChainMods - модификаторы }
+//   OUTPUTS: { Promise<Path[]> - массив путей вида { ключ_шага: Row } }
+//   SIDE_EFFECTS: читает БД через M-SQL.buildRead/runQuery
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: runPaths
 async function runPaths(ctx, steps, mods) {
+    // START_BLOCK_RUN_PATHS
     const q = buildRead(ctx, steps, mods, 'paths');
     const res = await runQuery(ctx, q.text, q.params, 'paths', clsOf(steps));
     return res.map((r) => {
@@ -63,8 +99,17 @@ async function runPaths(ctx, steps, mods) {
             out[k] = toRow(v);
         return out;
     });
+    // END_BLOCK_RUN_PATHS
 }
+// START_CONTRACT: runRows
+//   PURPOSE: Исполняет читающий план в режиме строк — уникальные сущности последнего шага, с $depth при рекурсивном обходе.
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods }
+//   OUTPUTS: { Promise<Row[]> - строки последнего шага (с $depth при deep) }
+//   SIDE_EFFECTS: читает БД через M-SQL.buildRead/runQuery
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: runRows
 async function runRows(ctx, steps, mods) {
+    // START_BLOCK_RUN_ROWS
     const q = buildRead(ctx, steps, mods, 'rows');
     const res = await runQuery(ctx, q.text, q.params, 'rows', clsOf(steps));
     return res.map((r) => {
@@ -72,13 +117,22 @@ async function runRows(ctx, steps, mods) {
         const d = r.row.depth;
         return d != null ? { ...row, $depth: d } : row;
     });
+    // END_BLOCK_RUN_ROWS
 }
 const NO_NODES = new Map();
 /**
  * Свойство-класс (вызов = шаг/pivot; без скобок = слот). ownerSteps undefined — корень
  * (db/batch): слот без владельца — ошибка.
  */
+// START_CONTRACT: classProp
+//   PURPOSE: Строит StepProp для класса — вызов даёт шаг-навигацию или pivot-возврат, обращение без скобок — слот связи (set/unset) записываемой версии.
+//   INPUTS: { ctx: Ctx; name: string - имя/alias класса; cls: ClassDef; ownerSteps: Step[] | undefined - шаги владельца (undefined = корень db/batch); mods: ChainMods; batch: BatchRef | undefined; nodes: NodeMap - карта entity-идентичности; applySlot?: (slotCls, value) => Chain }
+//   OUTPUTS: { StepProp - вызываемый (шаг) Proxy с методами set/unset }
+//   SIDE_EFFECTS: возвращает новые Chain; бросает подсказки при слоте без владельца / не-конце / обращении без вызова
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: classProp
 function classProp(ctx, name, cls, ownerSteps, mods, batch, nodes, applySlot) {
+    // START_BLOCK_CLASS_STEP
     const step = (filter) => {
         const prev = ownerSteps?.[ownerSteps.length - 1];
         // повтор LINK-класса в текущем паттерне — возврат к узлу (pivot)
@@ -92,6 +146,8 @@ function classProp(ctx, name, cls, ownerSteps, mods, batch, nodes, applySlot) {
         const next = { name, cls, filter: normalizeFilter(filter), nodeKey: nextNodeKey() };
         return makeChain(ctx, [...(ownerSteps ?? []), next], ownerSteps ? mods : {}, batch, nodes);
     };
+    // END_BLOCK_CLASS_STEP
+    // START_BLOCK_LINK_SLOT
     const slotGuard = () => {
         if (!ownerSteps?.length || !applySlot) {
             throw new Error(`letopis: slot "${name}" needs an owner step — start with a class call: db.Класс(…).${name}.set(…)`);
@@ -132,9 +188,18 @@ function classProp(ctx, name, cls, ownerSteps, mods, batch, nodes, applySlot) {
             throw new Error(`letopis: "${name}" without call is a link slot (set/unset); for navigation call ${name}(…)`);
         },
     });
+    // END_BLOCK_LINK_SLOT
 }
+// START_CONTRACT: makeChain
+//   PURPOSE: Собирает Proxy-цепочку над списком шагов — модификаторы и слоты порождают новые цепочки, терминалы делегируют чтение (M-SQL) или исполнение плана (M-WRITE.runPlan).
+//   INPUTS: { ctx: Ctx; steps: Step[] - накопленные шаги; mods: ChainMods; batch?: BatchRef - контекст батча; nodes?: NodeMap - entity-идентичность }
+//   OUTPUTS: { Chain - Proxy с терминалами/модификаторами и свойствами-классами }
+//   SIDE_EFFECTS: терминалы читают/пишут БД (runPaths/runRows/runQuery, runPlan); в батче мутирует очередь через syncBatch
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: makeChain
 function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
     const hasOps = steps.some((s) => s.op);
+    // START_BLOCK_STEP_MUTATORS
     const withLast = (patch) => {
         const last = steps[steps.length - 1];
         if (last.op) {
@@ -145,6 +210,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
         return makeChain(ctx, next, mods, batch, nodes);
     };
     const withMods = (patch) => makeChain(ctx, steps, { ...mods, ...patch }, batch, nodes);
+    // END_BLOCK_STEP_MUTATORS
+    // START_BLOCK_WRITE_DISPATCH
     /** Обновить план в батче (регистрируется на первой операции, дальше мутируется). */
     const syncBatch = (next) => {
         if (!batch)
@@ -188,6 +255,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
         syncBatch(next);
         return makeChain(ctx, next, mods, batch, nodes);
     };
+    // END_BLOCK_WRITE_DISPATCH
+    // START_BLOCK_ENTITY_EMBED
     /** entity(x): вклейка узла/паттерна; та же переменная повторно — возврат к её узлу. */
     const entityStep = (x) => {
         const plan = peekPlan(x);
@@ -220,6 +289,7 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
         }
         throw new Error('letopis: entity() accepts a lazy chain or a Row');
     };
+    // END_BLOCK_ENTITY_EMBED
     /** Терминал: план (есть операции) — runPlan одной транзакцией; иначе прямое чтение. */
     const guardBatch = () => {
         if (batch && hasOps) {
@@ -233,6 +303,7 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
             switch (prop) {
+                // START_BLOCK_READ_TERMINALS
                 case 'entity':
                     return entityStep;
                 case 'run':
@@ -273,6 +344,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                         const res = await runQuery(ctx, q.text, q.params, 'count', clsOf(steps));
                         return res[0].n;
                     };
+                // END_BLOCK_READ_TERMINALS
+                // START_BLOCK_READ_MODIFIERS
                 case 'limit':
                     return (n) => withMods({ limit: n });
                 case 'offset':
@@ -283,6 +356,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                     return (t) => withMods({ asOf: t instanceof Date ? t.toISOString() : t });
                 case 'deep':
                     return (max = 32) => withLast({ deepMax: max });
+                // END_BLOCK_READ_MODIFIERS
+                // START_BLOCK_AGGREGATIONS
                 case 'sum':
                 case 'avg':
                 case 'min':
@@ -319,6 +394,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                             })();
                         return Object.fromEntries(res.map((r) => [r.k ?? 'null', r.n]));
                     };
+                // END_BLOCK_AGGREGATIONS
+                // START_BLOCK_VERSIONS_CURSOR
                 case 'after':
                     return (cursor) => withMods({ after: cursor });
                 case 'versions':
@@ -334,6 +411,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                             return raw.deleted ? { ...row, $deleted: true } : row;
                         });
                     };
+                // END_BLOCK_VERSIONS_CURSOR
+                // START_BLOCK_WRITE_TERMINALS
                 case 'create':
                     return (data = {}) => {
                         const last = steps[steps.length - 1];
@@ -355,6 +434,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                     return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true, mods });
                 case 'anonymize':
                     return (fields) => withOp({ kind: 'anonymize', fields, mods });
+                // END_BLOCK_WRITE_TERMINALS
+                // START_BLOCK_COLUMN_MODS
                 case 'alias':
                     return (name) => withLast({ aliasKey: name });
                 case 'tags':
@@ -365,22 +446,33 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                     return (v) => withLast({ ownerFilter: typeof v === 'object' ? v.id : v });
                 case 'link':
                     throw new Error('letopis: .link() removed (0.15.0) — use the link slot: .Класс.set(target)');
+                // END_BLOCK_COLUMN_MODS
             }
+            // START_BLOCK_CLASS_RESOLVE
             if (ctx.registry.has(prop)) {
                 return classProp(ctx, prop, ctx.registry.resolve(prop), steps, mods, batch, nodes, applySlot);
             }
             ctx.registry.resolve(prop); // неизвестный класс — понятная ошибка со списком
             return undefined;
+            // END_BLOCK_CLASS_RESOLVE
         },
     };
     return new Proxy({}, handler);
 }
+// START_CONTRACT: makeBatch
+//   PURPOSE: Собирает Proxy-батч над общей очередью планов — свойства-классы копят цепочки, run() исполняет всю очередь одной транзакцией.
+//   INPUTS: { ctx: Ctx; queue: BatchPlan[] - общая очередь планов батча }
+//   OUTPUTS: { Batch - Proxy с run/discard/size и свойствами-классами }
+//   SIDE_EFFECTS: run() исполняет и очищает очередь через M-WRITE.executeBatch; discard() очищает очередь
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: makeBatch
 function makeBatch(ctx, queue) {
     const handler = {
         get(_t, prop) {
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
             switch (prop) {
+                // START_BLOCK_BATCH_QUEUE
                 case 'run':
                     return async () => {
                         const plans = queue.splice(0, queue.length);
@@ -392,6 +484,7 @@ function makeBatch(ctx, queue) {
                     return () => void queue.splice(0, queue.length);
                 case 'size':
                     return () => queue.length;
+                // END_BLOCK_BATCH_QUEUE
             }
             if (ctx.registry.has(prop)) {
                 return classProp(ctx, String(prop), ctx.registry.resolve(prop), undefined, {}, { queue }, NO_NODES);
@@ -402,6 +495,13 @@ function makeBatch(ctx, queue) {
     };
     return new Proxy({}, handler);
 }
+// START_CONTRACT: makeDb
+//   PURPOSE: Фабрика корневого фасада EntityDb над Ctx — классы как стартовые шаги, транзакции (begin/commit/rollback/lock), батчи, watch, служебные таблицы/auth/acl, entity()-старт.
+//   INPUTS: { ctx: Ctx - контекст соединения/схемы (или TxCtx внутри begin()); root?: RootState - общее состояние батчей }
+//   OUTPUTS: { EntityDb - Proxy-фасад }
+//   SIDE_EFFECTS: begin() открывает транзакцию (M-TX.beginTx); watch() ставит LISTEN на канал = имя схемы (ctx.pgSchema); close() закрывает соединение; лениво поднимает M-TABLES/M-AUTH/M-ACL
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: makeDb
 export function makeDb(ctx, root) {
     const state = root ?? { batches: new Map() };
     let tables; // лениво, на ctx этого фасада (работает и в tr)
@@ -411,6 +511,7 @@ export function makeDb(ctx, root) {
         get(_t, prop) {
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
+            // START_BLOCK_TABLES_AUTH_ACL
             if (prop === 'accounts' || prop === 'credentials' || prop === 'resources' || prop === 'rules') {
                 tables ??= makeTables(ctx);
                 return tables[prop];
@@ -425,7 +526,9 @@ export function makeDb(ctx, root) {
                 acl ??= makeAcl(tables, ctx.registry);
                 return acl;
             }
+            // END_BLOCK_TABLES_AUTH_ACL
             switch (prop) {
+                // START_BLOCK_TX_LOCK
                 case 'begin':
                     return async () => makeDb(await beginTx(ctx), state);
                 case 'commit':
@@ -448,6 +551,8 @@ export function makeDb(ctx, root) {
                     };
                 case 'lock':
                     return (...keys) => lock(ctx, ...keys);
+                // END_BLOCK_TX_LOCK
+                // START_BLOCK_BATCH_OPEN
                 case 'batch':
                     return (name) => {
                         let q = state.batches.get(name);
@@ -457,6 +562,8 @@ export function makeDb(ctx, root) {
                         }
                         return makeBatch(ctx, q);
                     };
+                // END_BLOCK_BATCH_OPEN
+                // START_BLOCK_WATCH_LISTEN
                 case 'watch':
                     return async (a, b, c) => {
                         const cls = typeof a === 'string' ? ctx.registry.resolve(a).id : undefined;
@@ -496,13 +603,17 @@ export function makeDb(ctx, root) {
                         const { unlisten } = await ctx.sql.listen(ctx.pgSchema, listener, onlisten);
                         return unlisten;
                     };
+                // END_BLOCK_WATCH_LISTEN
+                // START_BLOCK_CLOSE_META
                 case 'close':
                     return () => ctx.sql.end();
                 case 'registry':
                     return ctx.registry;
                 case 'sql':
                     return ctx.sql;
+                // END_BLOCK_CLOSE_META
             }
+            // START_BLOCK_ENTITY_START
             if (prop === 'entity') {
                 // старт пути с готового паттерна/строки: db.entity(pos).…
                 return (x) => makeChain(ctx, [], {}, undefined, NO_NODES).entity(x);
@@ -512,6 +623,7 @@ export function makeDb(ctx, root) {
             }
             ctx.registry.resolve(prop);
             return undefined;
+            // END_BLOCK_ENTITY_START
         },
     };
     return new Proxy({}, handler);

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * letopis: dot-цепочки над append-only Entity-хранилищем (TimescaleDB).
+ *
+ *   const db = await connect({ dsn, schema: 'booking' })
+ *   await db.Сотрудник({ name: 'Вася' }).навык().Услуга().run()
+ */
 import { type EntityDb } from './chain.js';
 import type { ConnectOpts } from './types.js';
 export declare function connect(opts: ConnectOpts): Promise<EntityDb>;

package/dist/index.js

@@ -4,11 +4,38 @@
  *   const db = await connect({ dsn, schema: 'booking' })
  *   await db.Сотрудник({ name: 'Вася' }).навык().Услуга().run()
  */
+// FILE: lib/src/index.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Публичная точка входа пакета — открыть соединение (реестр, опциональный ACL, сборка db) и ре-экспорт публичной поверхности; хелпер курсора.
+//   SCOPE: connect, cursorOf + barrel-реэкспорты
+//   DEPENDS: M-SCHEMA, M-CHAIN, M-TABLES, M-ACL, M-SQL, M-TYPES, M-UP
+//   LINKS: M-CONNECT, V-M-CONNECT
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   connect - открывает pg-соединение, грузит реестр, опц. включает ACL, собирает EntityDb
+//   cursorOf - курсор keyset-пагинации из последней строки страницы
+//   NOTE (re-exports) - up/UpOpts←M-UP; uuidv5/uuidv7/LETOPIS_NS←M-UUID; ops←M-OPS; totpCode/AuthApi/AuthResult←M-AUTH; AclApi←M-ACL; ValidationError←M-WRITE; Registry←M-SCHEMA; Session-типы←M-SESSIONS; базовые типы←M-TYPES; типы chain/tables
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import postgres from 'postgres';
 import { loadRegistry } from './schema.js';
 import { makeDb } from './chain.js';
 import { makeTables } from './tables.js';
 import { compileEnforcer } from './acl.js';
+// START_CONTRACT: connect
+//   PURPOSE: Открыть соединение: postgres-пул, реестр схемы, System-аккаунт, опциональный ACL — и собрать EntityDb.
+//   INPUTS: { opts: ConnectOpts { dsn, schema, partition?='entity', max?=10, account?, owner?, enforceAcl?, enforceAccount?, onQuery?, slowMs? } }
+//   OUTPUTS: { Promise<EntityDb> - dot-цепочный db }
+//   SIDE_EFFECTS: открывает пул postgres (timestamptz строкой), читает реестр и System-аккаунт; при enforceAcl без account бросает 'letopis: enforceAcl requires connect({ account })', при ненайденном — 'letopis: enforceAcl — account "…" not found', иначе читает resources/rules и компилит aclDecide; NB: ESM-цикл M-CONNECT↔M-UP (up ре-экспортится здесь)
+//   LINKS: M-CONNECT, V-M-CONNECT, M-SCHEMA, M-CHAIN, M-TABLES, M-ACL, M-SQL
+// END_CONTRACT: connect
 export async function connect(opts) {
     // timestamptz — строкой (JS Date режет микросекунды → ломал бы asOf/cursorOf по updated)
     const sql = postgres(opts.dsn, {
@@ -32,6 +59,7 @@ export async function connect(opts) {
         onQuery: opts.onQuery,
         slowMs: opts.slowMs,
     };
+    // START_BLOCK_ENFORCE_ACL
     // enforceAcl: правила и категории субъекта фиксируются на connect (перечитка — новый connect)
     if (opts.enforceAcl) {
         if (!opts.account)
@@ -46,9 +74,17 @@ export async function connect(opts) {
             throw new Error(`letopis: enforceAcl — account "${opts.account}" not found`);
         ctx.aclDecide = compileEnforcer({ resources, rules }, account.id, account.categories, registry);
     }
+    // END_BLOCK_ENFORCE_ACL
     return makeDb(ctx);
 }
 /** Курсор keyset-пагинации из последней строки страницы (field как в .sort(), вложенные пути поддержаны). */
+// START_CONTRACT: cursorOf
+//   PURPOSE: Собрать курсор keyset-пагинации из последней строки страницы.
+//   INPUTS: { row: Row - строка результата; field?: string='updated' - поле сортировки как в .sort() (вложенные пути 'data.*' поддержаны) }
+//   OUTPUTS: { Cursor - { v, id } для следующей страницы }
+//   SIDE_EFFECTS: none
+//   LINKS: M-CONNECT, V-M-CONNECT, M-TYPES
+// END_CONTRACT: cursorOf
 export function cursorOf(row, field = 'updated') {
     const v = field === 'updated'
         ? row.updated

package/dist/ops.js

@@ -2,6 +2,44 @@
  * Операторы фильтров. Symbol-tagged объекты — не пересекаются с данными.
  * Касты по типам полей делает sql.ts на основе Schema.attributes.
  */
+//
+// FILE: lib/src/ops.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Билдеры операторов фильтра, создающие узлы Op для DSL фильтров.
+//   SCOPE: type guard isOp + конструкторы операторов сравнения / списков / строк / массивов / наличия / логики (ne…or) поверх локальной фабрики op().
+//   DEPENDS: M-TYPES
+//   LINKS: M-OPS, V-M-OPS
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   op - (локальный) фабрика узла Op: { [OP]: name, args }.
+//   isOp - type guard: значение является узлом Op (содержит символ OP).
+//   ne - ≠ (IS DISTINCT FROM).
+//   gt - >.
+//   gte - ≥.
+//   lt - <.
+//   lte - ≤.
+//   between - a ≤ x ≤ b.
+//   inList - значение из списка (IN).
+//   like - LIKE (шаблон с % и _).
+//   ilike - ILIKE (без регистра).
+//   starts - начинается с (LIKE s%).
+//   ends - заканчивается на (LIKE %s).
+//   has - массив-поле содержит значение.
+//   hasAny - массив-поле содержит хотя бы одно из.
+//   hasAll - массив-поле содержит все.
+//   exists - поле присутствует (true) / отсутствует (false) в data.
+//   isNull - поле NULL или отсутствует.
+//   not - НЕ-условие по полю (скаляр → «не равно»).
+//   or - ИЛИ на уровне фильтра шага.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import { OP } from './types.js';
 const op = (name, ...args) => ({ [OP]: name, args });
 export const isOp = (v) => typeof v === 'object' && v !== null && OP in v;
@@ -39,5 +77,12 @@ export const exists = (yes = true) => op('exists', yes);
 export const isNull = () => op('isNull');
 /** НЕ-условие по полю: not(ilike('%тест%')); скаляр → «не равно» */
 export const not = (v) => op('not', v);
+// START_CONTRACT: or
+//   PURPOSE: Логическое ИЛИ на уровне фильтра шага — объединяет несколько фильтров-объектов в один узел Op.
+//   INPUTS: { filters: Record<string, unknown>[] - варьируемое число фильтров-объектов (каждый — свой набор условий) }
+//   OUTPUTS: { Op - узел { [OP]: 'or', args: [filters] } }
+//   SIDE_EFFECTS: none (чистая фабрика через op())
+//   LINKS: M-OPS, V-M-OPS
+// END_CONTRACT: or
 /** ИЛИ на уровне фильтра шага: db.Запись(or({status:'created'}, {status:'confirmed'})) */
 export const or = (...filters) => op('or', filters);

package/dist/schema.js

@@ -7,6 +7,27 @@
  *  - скомпилированный fastest-validator per class;
  *  - карта типов полей (для SQL-кастов фильтров).
  */
+//
+// FILE: lib/src/schema.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Строит реестр классов из таблицы Schema — резолв наследования/link-ends, типы полей, компиляция валидаторов.
+//   SCOPE: Registry (add/find/resolve/has), loadRegistry, fieldTypeOf; локальные parseEnd/parseIdGen/buildDef.
+//   DEPENDS: M-TYPES
+//   LINKS: M-SCHEMA, V-M-SCHEMA
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   Registry - реестр классов (add/find/resolve/has, all)
+//   fieldTypeOf - attribute-спека fastest-validator → FieldType (для SQL-кастов)
+//   loadRegistry - загрузка Schema-строк партиции → Registry со скомпилированными check
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import { createRequire } from 'node:module';
 const Validator = createRequire(import.meta.url)('fastest-validator');
 const v = new Validator({ useNewCustomCheckerFunction: true });
@@ -22,6 +43,13 @@ export class Registry {
     find(name) {
         return this.byName.get(name);
     }
+    // START_CONTRACT: Registry.resolve
+    //   PURPOSE: Вернуть класс по id или alias, иначе бросить ошибку со списком известных.
+    //   INPUTS: { name: string - id или alias класса }
+    //   OUTPUTS: { ClassDef - найденный класс }
+    //   SIDE_EFFECTS: none
+    //   LINKS: M-SCHEMA, V-M-SCHEMA
+    // END_CONTRACT: Registry.resolve
     /** Класс по id или alias; иначе понятная ошибка со списком. */
     resolve(name) {
         const def = this.byName.get(name);
@@ -35,6 +63,13 @@ export class Registry {
         return this.byName.has(name);
     }
 }
+// START_CONTRACT: fieldTypeOf
+//   PURPOSE: Свести attribute-спеку fastest-validator (строка/массив/объект) к FieldType.
+//   INPUTS: { attr: unknown - правило поля из attributes }
+//   OUTPUTS: { FieldType - вид поля (number/date/boolean/string/array/record/object/any) }
+//   SIDE_EFFECTS: none (рекурсивно по вложенным props/value)
+//   LINKS: M-SCHEMA, V-M-SCHEMA, type-FieldType
+// END_CONTRACT: fieldTypeOf
 /** Тип поля из fastest-validator DSL — для каста в SQL. */
 export function fieldTypeOf(attr) {
     if (typeof attr === 'string') {
@@ -94,6 +129,14 @@ export function fieldTypeOf(attr) {
  * Элемент Schema.links: объект-конец v2 (jsonb) либо legacy-строка 'Org'
  * (включая JSON-текст в text[] у старых схем). Возвращает [конец, isV2].
  */
+// START_CONTRACT: parseEnd
+//   PURPOSE: Разобрать один элемент Schema.links в LinkEnd (объект-конец v2 или legacy-строка).
+//   INPUTS: { cls: string - id класса; raw: string|object - сырой конец из jsonb/text[] }
+//   OUTPUTS: { [LinkEnd, boolean] - конец и признак v2-формы (для strictEnds) }
+//   SIDE_EFFECTS: none
+//   ERRORS: malformed link end (bad JSON); link end without classes
+//   LINKS: M-SCHEMA, V-M-SCHEMA
+// END_CONTRACT: parseEnd
 function parseEnd(cls, raw) {
     let o;
     if (typeof raw === 'string') {
@@ -119,6 +162,14 @@ function parseEnd(cls, raw) {
  * attributes.id: правило валидации + (объектом) спецификация генерации.
  * generate/from — ключи letopis, вырезаются из правила перед компиляцией валидатора.
  */
+// START_CONTRACT: parseIdGen
+//   PURPOSE: Отделить спецификацию генерации id (generate/from) от правила валидации attributes.id.
+//   INPUTS: { cls: string - id класса; attributes: object - слитые attributes класса }
+//   OUTPUTS: { { idGen: IdGen; attrs: object } - версия генерации id и очищенное правило }
+//   SIDE_EFFECTS: none
+//   ERRORS: generate must be 4|5|7; generate:5 needs "from"; from is for generate:5 only
+//   LINKS: M-SCHEMA, V-M-SCHEMA
+// END_CONTRACT: parseIdGen
 function parseIdGen(cls, attributes) {
     const raw = attributes.id;
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
@@ -142,7 +193,16 @@ function parseIdGen(cls, attributes) {
     }
     return { idGen: { version: generate }, attrs };
 }
+// START_CONTRACT: buildDef
+//   PURPOSE: Собрать ClassDef из строки Schema — цепочка ancestors, наследование attributes, id-gen, компиляция check, типы полей, link-ends.
+//   INPUTS: { row: SchemaRow - строка класса; byId: Map<string,SchemaRow> - все классы партиции }
+//   OUTPUTS: { ClassDef - полностью разрешённое определение класса }
+//   SIDE_EFFECTS: none (компилирует fastest-validator)
+//   ERRORS: id v5 can't depend on optional end; id "from" source is neither end nor field
+//   LINKS: M-SCHEMA, V-M-SCHEMA, type-ClassDef
+// END_CONTRACT: buildDef
 function buildDef(row, byId) {
+    // START_BLOCK_INHERIT_ANCESTORS
     // цепочка наследования: из БД или walk по ancestor
     let ancestors = row.ancestors ?? [];
     if (!ancestors.length) {
@@ -161,6 +221,7 @@ function buildDef(row, byId) {
     for (let i = ancestors.length - 1; i >= 0; i--) {
         Object.assign(merged, byId.get(ancestors[i])?.attributes ?? {});
     }
+    // END_BLOCK_INHERIT_ANCESTORS
     // attributes.id: спецификация генерации (generate/from) отделяется от правила валидации
     const { idGen, attrs } = parseIdGen(row.id, merged);
     // fastest-validator: валидируем {id, ...data}; СТРОГО — лишние поля запрещены
@@ -187,6 +248,7 @@ function buildDef(row, byId) {
             strictEnds = true;
         return end;
     });
+    // START_BLOCK_ID_V5_VALIDATE
     // id v5: каждый источник from — обязательный конец links (класс или полное имя союза
     // 'Service|Complex') ЛИБО поле data
     if (idGen.version === 5) {
@@ -203,6 +265,7 @@ function buildDef(row, byId) {
             throw new Error(`letopis: class "${row.id}" — id "from" source "${f}" is neither a link end nor a data field`);
         }
     }
+    // END_BLOCK_ID_V5_VALIDATE
     return {
         id: row.id,
         alias: row.alias,
@@ -221,13 +284,23 @@ function buildDef(row, byId) {
         fieldTypes,
     };
 }
+// START_CONTRACT: loadRegistry
+//   PURPOSE: Прочитать классы партиции из таблицы Schema и построить Registry со скомпилированными check.
+//   INPUTS: { sql: postgres.Sql; pgSchema: string; partition: string }
+//   OUTPUTS: { Promise<Registry> - реестр всех классов партиции }
+//   SIDE_EFFECTS: SELECT из "<pgSchema>"."Schema"
+//   ERRORS: schema has no classes for partition
+//   LINKS: M-SCHEMA, V-M-SCHEMA, M-DDL
+// END_CONTRACT: loadRegistry
 export async function loadRegistry(sql, pgSchema, partition) {
+    // START_BLOCK_LOAD_QUERY
     const ident = `"${pgSchema.replace(/"/g, '""')}"`;
     const rows = (await sql.unsafe(`SELECT id, alias, category, ancestor, attributes, links, meta, "order", ancestors, descendants
        FROM ${ident}."Schema" WHERE partition = $1 ORDER BY category, "order"`, [partition]));
     if (!rows.length) {
         throw new Error(`letopis: schema "${pgSchema}" has no classes for partition "${partition}"`);
     }
+    // END_BLOCK_LOAD_QUERY
     const byId = new Map(rows.map((r) => [r.id, r]));
     const registry = new Registry();
     for (const row of rows)