letopis 0.16.0 → 0.18.1

package/dist/sessions.js

@@ -3,16 +3,56 @@
  * Клиент НЕ входит в зависимости — инжектируется пользователем (интерфейс ioredis-совместим).
  * В store лежит только sha256-хэш токена: дамп Redis не раскрывает действующие токены.
  */
+//
+// FILE: lib/src/sessions.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Жизненный цикл сессий поверх инжектируемого Redis-совместимого хранилища (start/check/revoke/revokeAll).
+//   SCOPE: интерфейсы SessionStore/Session/Sessions + фабрика makeSessions с операциями старта, проверки и отзыва сессий; токены хранятся как sha256 под ключами sess:* / sess:acc:* с TTL.
+//   DEPENDS: none
+//   LINKS: M-SESSIONS, V-M-SESSIONS
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   SessionStore - минимальный срез Redis-клиента (set/get/del/sadd/srem/smembers/expire).
+//   Session - полезная нагрузка сессии: account, meta, created.
+//   Sessions - контракт сервиса сессий: start/check/revoke/revokeAll.
+//   sha256 - (локальный) hex-хэш строки по sha256.
+//   accId - (локальный) нормализует account: string | { id } → id.
+//   DEFAULT_TTL - (локальный) TTL по умолчанию: 7 суток в секундах.
+//   makeSessions - фабрика: связывает store и возвращает объект Sessions.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import { createHash, randomBytes } from 'node:crypto';
 const sha256 = (s) => createHash('sha256').update(s).digest('hex');
 const accId = (a) => (typeof a === 'object' ? a.id : a);
 const DEFAULT_TTL = 7 * 24 * 3600;
+// START_CONTRACT: makeSessions
+//   PURPOSE: Фабрика сервиса сессий: связывает инжектируемый store и возвращает объект Sessions.
+//   INPUTS: { store: SessionStore - Redis-совместимое хранилище (инжектируется пользователем) }
+//   OUTPUTS: { Sessions - объект с методами start/check/revoke/revokeAll }
+//   SIDE_EFFECTS: none при создании; возвращённые методы читают/пишут store (ключи sess:* / sess:acc:*)
+//   LINKS: M-SESSIONS, V-M-SESSIONS
+// END_CONTRACT: makeSessions
 export function makeSessions(store) {
     const kTok = (h) => `sess:${h}`;
     // индекс аккаунта без TTL: протухшие хэши безвредны, полная чистка — revokeAll
     const kAcc = (id) => `sess:acc:${id}`;
     return {
+        // START_CONTRACT: start
+        //   PURPOSE: Создать новую сессию и вернуть одноразовый токен (в store — только его sha256).
+        //   INPUTS: { account: string | { id: string } - аккаунт, opts?: { ttlSec?: number; meta?: Record<string, unknown> } - TTL (default 7 суток) и метаданные }
+        //   OUTPUTS: { Promise<string> - секретный токен (32 байта hex, отдаётся один раз) }
+        //   SIDE_EFFECTS: store.set(sess:<h>, payload, EX ttl) + store.sadd(sess:acc:<id>, h)
+        //   LINKS: M-SESSIONS, V-M-SESSIONS
+        // END_CONTRACT: start
         async start(account, opts = {}) {
+            // START_BLOCK_START_MINT_AND_PERSIST
             const id = accId(account);
             const token = randomBytes(32).toString('hex');
             const h = sha256(token);
@@ -20,13 +60,29 @@ export function makeSessions(store) {
             const payload = { account: id, meta: opts.meta ?? {}, created: new Date().toISOString() };
             await store.set(kTok(h), JSON.stringify(payload), 'EX', ttl);
             await store.sadd(kAcc(id), h);
+            // END_BLOCK_START_MINT_AND_PERSIST
             return token;
         },
+        // START_CONTRACT: check
+        //   PURPOSE: Проверить токен и вернуть данные сессии либо null.
+        //   INPUTS: { token: string - секретный токен }
+        //   OUTPUTS: { Promise<Session | null> - null = нет / просрочена / отозвана }
+        //   SIDE_EFFECTS: store.get(sess:<sha256(token)>) (только чтение)
+        //   LINKS: M-SESSIONS, V-M-SESSIONS
+        // END_CONTRACT: check
         async check(token) {
             const raw = await store.get(kTok(sha256(token)));
             return raw ? JSON.parse(raw) : null;
         },
+        // START_CONTRACT: revoke
+        //   PURPOSE: Отозвать одну сессию по токену.
+        //   INPUTS: { token: string - секретный токен }
+        //   OUTPUTS: { Promise<boolean> - true если сессия была и удалена, false если её нет }
+        //   SIDE_EFFECTS: store.del(sess:<h>) + store.srem(sess:acc:<account>, h)
+        //   LINKS: M-SESSIONS, V-M-SESSIONS
+        // END_CONTRACT: revoke
         async revoke(token) {
+            // START_BLOCK_REVOKE_LOOKUP_AND_DELETE
             const h = sha256(token);
             const raw = await store.get(kTok(h));
             if (!raw)
@@ -35,14 +91,24 @@ export function makeSessions(store) {
             await store.del(kTok(h));
             await store.srem(kAcc(account), h);
             return true;
+            // END_BLOCK_REVOKE_LOOKUP_AND_DELETE
         },
+        // START_CONTRACT: revokeAll
+        //   PURPOSE: Погасить все сессии аккаунта и очистить его индекс.
+        //   INPUTS: { account: string | { id: string } - аккаунт }
+        //   OUTPUTS: { Promise<number> - сколько хэшей было в индексе аккаунта }
+        //   SIDE_EFFECTS: store.del(все sess:<h>) + store.del(sess:acc:<id>)
+        //   LINKS: M-SESSIONS, V-M-SESSIONS
+        // END_CONTRACT: revokeAll
         async revokeAll(account) {
+            // START_BLOCK_REVOKE_ALL_PURGE
             const id = accId(account);
             const hs = await store.smembers(kAcc(id));
             if (hs.length)
                 await store.del(...hs.map(kTok));
             await store.del(kAcc(id));
             return hs.length;
+            // END_BLOCK_REVOKE_ALL_PURGE
         },
     };
 }

package/dist/sql.js

@@ -1,6 +1,13 @@
 import { OP } from './types.js';
 import { isOp } from './ops.js';
 import { aclDenied } from './acl.js';
+// START_CONTRACT: isTransient
+//   PURPOSE: Признак транзиентной ошибки PG (deadlock 40P01 / serialization failure 40001) — снимается повтором.
+//   INPUTS: { e: unknown - пойманная ошибка }
+//   OUTPUTS: { boolean }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SQL, V-M-SQL
+// END_CONTRACT: isTransient
 /** Транзиентные ошибки PG — гонка, снимаемая повтором: deadlock / serialization failure. */
 export function isTransient(e) {
     const code = e.code;
@@ -25,7 +32,15 @@ const READ_MODES = new Set([
  * повтор запрещён семантикой PG — ошибка уходит наружу с подсказкой.
  * Служебные запросы (loadRegistry, tables, listen) через неё не идут.
  */
+// START_CONTRACT: runQuery
+//   PURPOSE: Единая точка исполнения запросов цепочек: sql.unsafe + событие onQuery/slow-warn + ретрай transient в автокоммите.
+//   INPUTS: { ctx: Ctx; text: string; params: unknown[]; mode: QueryEvent['mode']; classes: string[] }
+//   OUTPUTS: { Promise<T[]> - строки результата }
+//   SIDE_EFFECTS: выполняет SQL; вызывает onQuery-хук; console.warn при slowMs; ретрай до RETRIES вне транзакции
+//   LINKS: M-SQL, V-M-SQL
+// END_CONTRACT: runQuery
 export async function runQuery(ctx, text, params, mode, classes) {
+    // START_BLOCK_RUN_QUERY_RETRY
     for (let attempt = 1;; attempt++) {
         const t0 = performance.now();
         try {
@@ -54,6 +69,7 @@ export async function runQuery(ctx, text, params, mode, classes) {
             throw e;
         }
     }
+    // END_BLOCK_RUN_QUERY_RETRY
 }
 let nodeSeq = 0;
 /** Уникальная метка узла пути (для pivot-возвратов; переживает нарезку плана). */
@@ -123,6 +139,13 @@ function accessor(path) {
     return (a) => `${jsonbAt(head)(a)}->>'${escLit(last)}'`;
 }
 /** Тип листа data-пути по Schema: спуск через record (значение) и object (props). */
+// START_CONTRACT: leafType
+//   PURPOSE: Тип листа data-пути по Schema (спуск через record/object) — для SQL-каста.
+//   INPUTS: { cls: ClassDef; path: string[] - сегменты data-пути }
+//   OUTPUTS: { FieldType | undefined }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SQL, V-M-SQL, type-FieldType
+// END_CONTRACT: leafType
 export function leafType(cls, path) {
     let ft = cls.fieldTypes.get(path[0]);
     for (let i = 1; i < path.length && ft; i++) {
@@ -130,7 +153,16 @@ export function leafType(cls, path) {
     }
     return ft;
 }
+// START_CONTRACT: compileOp
+//   PURPOSE: Скомпилировать оператор фильтра (ne/gt/between/in/like/has*/exists/isNull/not) в SQL-фраг с кастом по типу листа.
+//   INPUTS: { path: string[]; ft?: FieldType; o: Op; p: Params }
+//   OUTPUTS: { Frag - (alias) => SQL-предикат }
+//   SIDE_EFFECTS: пушит значения в Params
+//   ERRORS: unknown operator "<name>"
+//   LINKS: M-SQL, V-M-SQL, M-OPS
+// END_CONTRACT: compileOp
 function compileOp(path, ft, o, p) {
+    // START_BLOCK_COMPILE_OP
     const lhs = accessor(path);
     const cast = castOf(ft);
     // скобки обязательны: '::' сильнее '->>' (data->>'f'::ts кастил бы литерал 'f')
@@ -192,6 +224,7 @@ function compileOp(path, ft, o, p) {
         default:
             throw new Error(`letopis: unknown operator "${name}"`);
     }
+    // END_BLOCK_COMPILE_OP
 }
 /** Операторы на колонку tags (text[]): строка | string[] (все) | has/hasAny/hasAll. */
 function compileTags(v, p) {
@@ -215,6 +248,14 @@ function compileTags(v, p) {
     }
     throw new Error('letopis: $tags accepts a string or has/hasAny/hasAll');
 }
+// START_CONTRACT: compileFilter
+//   PURPOSE: Разобрать фильтр (id | string[] | or(...) | объект любой глубины) в idConds / candFrags(GIN) / finalFrags(перепроверка на latest).
+//   INPUTS: { cls: ClassDef; filter?: Filter; p: Params }
+//   OUTPUTS: { CompiledFilter }
+//   SIDE_EFFECTS: пушит значения в Params
+//   ERRORS: filter.id accepts string | string[]
+//   LINKS: M-SQL, V-M-SQL
+// END_CONTRACT: compileFilter
 function compileFilter(cls, filter, p) {
     const out = { idConds: [], candFrags: [], finalFrags: [] };
     if (filter === undefined)
@@ -241,6 +282,7 @@ function compileFilter(cls, filter, p) {
             out.idConds.push((a) => `${a}.id IN (${filter.map((x) => p.push(x)).join(', ')})`);
         return out;
     }
+    // START_BLOCK_COMPILE_FILTER_WALK
     const eqData = {};
     const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !isOp(v);
     /**
@@ -306,12 +348,21 @@ function compileFilter(cls, filter, p) {
         out.candFrags.push(frag);
         out.finalFrags.push(frag);
     }
+    // END_BLOCK_COMPILE_FILTER_WALK
     return out;
 }
 /** Класс target входит в какой-нибудь конец def (союзы учитываются). */
 export function linksTo(def, target) {
     return def.links.some((end) => end.classes.includes(target));
 }
+// START_CONTRACT: resolveHop
+//   PURPOSE: Определить направление обхода между классами (forward/reverse) по Schema.links.
+//   INPUTS: { prev: ClassDef; next: ClassDef }
+//   OUTPUTS: { HopMode - 'forward' | 'reverse' }
+//   SIDE_EFFECTS: none
+//   ERRORS: no path A→B (neither embeds the other); LINK → LINK traversal is not supported
+//   LINKS: M-SQL, V-M-SQL
+// END_CONTRACT: resolveHop
 /** Правило обхода между шагами (по реестру Schema). */
 export function resolveHop(prev, next) {
     if (prev.category === 'HUB' && next.category === 'LINK')
@@ -343,7 +394,10 @@ function sortField(alias, cls, order) {
 function orderExpr(alias, cls, mods) {
     if (!mods.order)
         return '';
-    return ` ORDER BY ${sortField(alias, cls, mods.order)}${mods.desc ? ' DESC' : ''}`;
+    const dir = mods.desc ? ' DESC' : '';
+    // id — стабильный tiebreaker ТЕМ ЖЕ направлением: ORDER BY совпадает с кортежом afterExpr
+    // (sortExpr, id), поэтому keyset не даёт пересечения страниц при неуникальном sort-поле.
+    return ` ORDER BY ${sortField(alias, cls, mods.order)}${dir}, ${alias}.id${dir}`;
 }
 /** Keyset-пагинация: (поле сортировки, id) строго после курсора. Требует .sort(). Выражение без WHERE. */
 function afterExpr(alias, cls, mods, p) {
@@ -360,6 +414,14 @@ const whereOf = (conds) => {
     const list = conds.filter((c) => !!c);
     return list.length ? ` WHERE ${list.join(' AND ')}` : '';
 };
+// START_CONTRACT: buildRead
+//   PURPOSE: Скомпилировать цепочку шагов+модов в один параметризованный read-запрос (латеральный обход путей, latest-версии, asOf/versions/agg, keyset).
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; mode: ReadMode }
+//   OUTPUTS: { BuiltQuery - { text, params, keys } }
+//   SIDE_EFFECTS: none (строит SQL; ACL-проверка READ может бросить)
+//   ERRORS: pivot node not in path; enforceAccount pin; acl denies READ; deep on non-self hop; agg needs data.<path>
+//   LINKS: M-SQL, V-M-SQL, M-ACL, M-DDL
+// END_CONTRACT: buildRead
 /** Построить читающий запрос по цепочке. */
 export function buildRead(ctx, steps, mods, mode) {
     const p = new Params();
@@ -367,6 +429,7 @@ export function buildRead(ctx, steps, mods, mode) {
     const pPart = p.push(ctx.partition);
     // pivot: карта эффективных блоков. real[i] — индекс блока-узла шага i
     // (pivot-шаг блока не строит, ссылается на узел по pivotKey).
+    // START_BLOCK_BUILD_PIVOT_MAP
     const real = [];
     const byNodeKey = new Map();
     const tailConds = []; // дофильтры pivot-шагов (alias подставлен) — в хвостовой WHERE
@@ -384,6 +447,8 @@ export function buildRead(ctx, steps, mods, mode) {
                 byNodeKey.set(s.nodeKey, i);
         }
     }
+    // END_BLOCK_BUILD_PIVOT_MAP
+    // START_BLOCK_BUILD_STEP_LOOP
     const blocks = [];
     for (let i = 0; i < steps.length; i++) {
         const step = steps[i];
@@ -506,6 +571,7 @@ export function buildRead(ctx, steps, mods, mode) {
         }
         blocks.push(i === 0 ? `FROM ${block}` : `JOIN LATERAL ${block} ON true`);
     }
+    // END_BLOCK_BUILD_STEP_LOOP
     const fromClause = blocks.join('\n');
     const last = real[steps.length - 1]; // pivot в конце → терминал на его узле
     const lastCls = steps[steps.length - 1].cls;
@@ -524,6 +590,7 @@ export function buildRead(ctx, steps, mods, mode) {
     const keys = keyed.map((k) => k.key);
     const limitOffset = (mods.limit !== undefined ? ` LIMIT ${p.push(mods.limit)}` : '') +
         (mods.offset !== undefined ? ` OFFSET ${p.push(mods.offset)}` : '');
+    // START_BLOCK_BUILD_MODE_SQL
     let text;
     switch (mode) {
         case 'paths': {
@@ -578,8 +645,16 @@ export function buildRead(ctx, steps, mods, mode) {
             break;
         }
     }
+    // END_BLOCK_BUILD_MODE_SQL
     return { text, params: p.list, keys };
 }
+// START_CONTRACT: insertSql
+//   PURPOSE: SQL одиночного INSERT новой версии/tombstone ($9 = updated прошлой версии, $10 = deleted).
+//   INPUTS: { pgSchema: string }
+//   OUTPUTS: { string - INSERT ... RETURNING * }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SQL, V-M-SQL, M-DDL
+// END_CONTRACT: insertSql
 /** INSERT новой версии/tombstone. $9 = updated прошлой версии (или null), $10 = deleted. */
 export function insertSql(pgSchema) {
     return (`INSERT INTO ${entityTable(pgSchema)} ` +
@@ -605,6 +680,13 @@ export function multiInsertSql(pgSchema, n) {
  * tombstone актуальной живой версии + рекурсивный каскад по links, всё в БД.
  * $1 partition, $2 class, дальше — id-шники.
  */
+// START_CONTRACT: deleteSql
+//   PURPOSE: SQL серверного удаления n сущностей — триггер entity_delete делает tombstone + рекурсивный каскад.
+//   INPUTS: { pgSchema: string; n: number }
+//   OUTPUTS: { string - DELETE ... WHERE id IN (...) }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SQL, V-M-SQL, M-DDL
+// END_CONTRACT: deleteSql
 export function deleteSql(pgSchema, n) {
     const ids = Array.from({ length: n }, (_, i) => `$${i + 3}`).join(', ');
     return `DELETE FROM ${entityTable(pgSchema)} WHERE partition = $1 AND class = $2 AND id IN (${ids})`;
@@ -613,6 +695,13 @@ export function deleteSql(pgSchema, n) {
  * Замыкание удаления: цели + все живые зависимые рекурсивно (то, что каскад затомбстоунит).
  * Рекурсивный CTE; каждый узел — актуальная живая версия. $1 partition, $2 class, $3+ — ids.
  */
+// START_CONTRACT: closureSql
+//   PURPOSE: Рекурсивный CTE: цели + все живые зависимые (то, что затомбстоунит каскад entity_delete).
+//   INPUTS: { pgSchema: string; n: number }
+//   OUTPUTS: { string - WITH RECURSIVE ... }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SQL, V-M-SQL, M-DDL
+// END_CONTRACT: closureSql
 export function closureSql(pgSchema, n) {
     const ent = entityTable(pgSchema);
     const ids = Array.from({ length: n }, (_, i) => `$${i + 3}`).join(', ');

package/dist/tables.js

@@ -1,4 +1,11 @@
 const T = (ctx, name) => `"${ctx.pgSchema.replace(/"/g, '""')}"."${name}"`;
+// START_CONTRACT: where
+//   PURPOSE: Собрать SQL WHERE из простых equality-условий, добавляя значения в params.
+//   INPUTS: { conds: Cond[] - условия с генераторами текста; params: unknown[] - аккумулятор значений }
+//   OUTPUTS: { string - " WHERE ..." или пустая строка }
+//   SIDE_EFFECTS: пушит значения в params (мутация массива)
+//   LINKS: M-TABLES, V-M-TABLES
+// END_CONTRACT: where
 /** WHERE из простых equality-условий (+спец-обработчики). */
 function where(conds, params) {
     if (!conds.length)
@@ -11,8 +18,16 @@ function where(conds, params) {
 }
 const eq = (col) => (n) => `"${col}" = $${n}`;
 // ---------------------------------------------------------------------------
+// START_CONTRACT: makeTables
+//   PURPOSE: Построить фасад Tables (accounts/credentials/resources/rules) поверх Ctx.
+//   INPUTS: { ctx: Ctx - runtime-контекст с sql и pgSchema }
+//   OUTPUTS: { Tables - четыре API с find/get/set/delete }
+//   SIDE_EFFECTS: каждый метод выполняет SELECT/INSERT/UPDATE/DELETE через ctx.sql
+//   LINKS: M-TABLES, V-M-TABLES, M-DDL
+// END_CONTRACT: makeTables
 export function makeTables(ctx) {
     const run = (text, params) => ctx.sql.unsafe(text, params);
+    // START_BLOCK_ACCOUNTS_API
     const accounts = {
         async find(f = {}) {
             const conds = [];
@@ -28,6 +43,14 @@ export function makeTables(ctx) {
         async get(id) {
             return (await run(`SELECT * FROM ${T(ctx, 'Account')} WHERE id = $1`, [id]))[0] ?? null;
         },
+        // START_CONTRACT: accounts.set
+        //   PURPOSE: INSERT (без id) либо UPDATE по id аккаунта; вернуть строку Account.
+        //   INPUTS: { a: Partial<Account> - поля categories/data/meta/avatar/enabled (+id для update) }
+        //   OUTPUTS: { Promise<Account> - созданная/обновлённая строка }
+        //   SIDE_EFFECTS: INSERT или UPDATE в таблице Account
+        //   ERRORS: account "<id>" not found (UPDATE не нашёл строку)
+        //   LINKS: M-TABLES, V-M-TABLES
+        // END_CONTRACT: accounts.set
         async set(a) {
             if (a.id) {
                 const sets = ['updated = now()'];
@@ -63,6 +86,8 @@ export function makeTables(ctx) {
             return rows.length > 0;
         },
     };
+    // END_BLOCK_ACCOUNTS_API
+    // START_BLOCK_CREDENTIALS_API
     const credentials = {
         async find(f = {}) {
             const conds = [];
@@ -82,6 +107,13 @@ export function makeTables(ctx) {
                 sql += conds.length ? ' AND deleted IS NULL' : ' WHERE deleted IS NULL';
             return run(sql + ' ORDER BY created', params);
         },
+        // START_CONTRACT: credentials.set
+        //   PURPOSE: upsert креденшела по UNIQUE (account, category, identifier); повторный set воскрешает (deleted → NULL).
+        //   INPUTS: { c: { account, category, identifier, meta?, confirmed? } }
+        //   OUTPUTS: { Promise<Credential> - upsert-нутая строка }
+        //   SIDE_EFFECTS: INSERT ... ON CONFLICT DO UPDATE в таблице Credential
+        //   LINKS: M-TABLES, V-M-TABLES
+        // END_CONTRACT: credentials.set
         async set(c) {
             const rows = await run(`INSERT INTO ${T(ctx, 'Credential')} (account, category, identifier, meta, confirmed)
          VALUES ($1, $2, $3, $4, $5)
@@ -95,6 +127,8 @@ export function makeTables(ctx) {
             return rows.length > 0;
         },
     };
+    // END_BLOCK_CREDENTIALS_API
+    // START_BLOCK_RESOURCES_API
     const resources = {
         async find(f = {}) {
             const conds = [];
@@ -117,6 +151,8 @@ export function makeTables(ctx) {
             return rows.length > 0;
         },
     };
+    // END_BLOCK_RESOURCES_API
+    // START_BLOCK_RULES_API
     const rules = {
         async find(f = {}) {
             const conds = [];
@@ -144,5 +180,6 @@ export function makeTables(ctx) {
             return rows.length > 0;
         },
     };
+    // END_BLOCK_RULES_API
     return { accounts, credentials, resources, rules };
 }

package/dist/tx.js

@@ -3,7 +3,34 @@
  * db.commit(tr) / db.rollback(tr) / tr.commit() / tr.rollback().
  * tr.lock(...) — pg_advisory_xact_lock (сериализация гонок, напр. двойная бронь).
  */
+// FILE: lib/src/tx.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Ручные транзакции и advisory-локи поверх зарезервированного pg-соединения.
+//   SCOPE: beginTx, lock
+//   DEPENDS: M-SQL
+//   LINKS: M-TX, V-M-TX
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   TxCtx - Ctx транзакции с методами commit()/rollback()
+//   beginTx - резервирует соединение, шлёт BEGIN, возвращает TxCtx
+//   lock - pg_advisory_xact_lock на составной ключ (только внутри транзакции)
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import { hintTxRetry, isTransient } from './sql.js';
+// START_CONTRACT: beginTx
+//   PURPOSE: Начать ручную транзакцию на зарезервированном соединении и вернуть TxCtx.
+//   INPUTS: { ctx: Ctx - базовый контекст с пулом sql }
+//   OUTPUTS: { Promise<TxCtx> - контекст с sql на резерве + commit()/rollback() }
+//   SIDE_EFFECTS: reserve() соединения из пула и BEGIN; commit/rollback шлют COMMIT/ROLLBACK и release() (идемпотентно через флаг done)
+//   LINKS: M-TX, V-M-TX, M-SQL
+// END_CONTRACT: beginTx
 export async function beginTx(ctx) {
     const reserved = await ctx.sql.reserve();
     const r = reserved;
@@ -30,10 +57,18 @@ export async function beginTx(ctx) {
     };
 }
 /** Advisory-lock на составной ключ; живёт до конца транзакции. */
+// START_CONTRACT: lock
+//   PURPOSE: Взять pg_advisory_xact_lock на составной ключ (сериализация гонок; живёт до конца транзакции).
+//   INPUTS: { ctx: Ctx - контекст (должен быть inTx); keys: (string|number)[] - части составного ключа }
+//   OUTPUTS: { Promise<void> }
+//   SIDE_EFFECTS: SELECT pg_advisory_xact_lock(hashtextextended(...)); вне транзакции бросает 'letopis: lock() works only inside db.begin() transaction'; на transient-ошибке (напр. deadlock 40P01) вызывает hintTxRetry и пробрасывает
+//   LINKS: M-TX, V-M-TX, M-SQL
+// END_CONTRACT: lock
 export async function lock(ctx, ...keys) {
     if (!ctx.inTx) {
         throw new Error('letopis: lock() works only inside db.begin() transaction (pg_advisory_xact_lock)');
     }
+    // START_BLOCK_ADVISORY_LOCK
     try {
         await ctx.sql.unsafe('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]);
     }
@@ -43,4 +78,5 @@ export async function lock(ctx, ...keys) {
             hintTxRetry(e);
         throw e;
     }
+    // END_BLOCK_ADVISORY_LOCK
 }

package/dist/types.js

@@ -1,5 +1,51 @@
 /**
  * letopis: типы.
  */
+//
+// FILE: lib/src/types.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Общий словарь типов всей библиотеки letopis.
+//   SCOPE: сущности, пути, определения классов, типы полей, фильтры и операторы, курсоры/план записи/модификаторы цепочки, записи auth/ACL, событие запроса и опции connect + символ OP.
+//   DEPENDS: none
+//   LINKS: M-TYPES, V-M-TYPES
+//   ROLE: TYPES
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   Row - строка Entity (актуальная версия): id/class/data/links/tags/account/owner/updated + служебные $deleted/$depth.
+//   Path - вариант пути run(): по одному узлу Row на каждый шаг цепочки.
+//   LinkEnd - конец связи класса (Schema.links v2): допустимые классы, optional, cardinality.
+//   IdGen - способ генерации id класса (версия 4/5/7) + источники from для v5.
+//   ClassDef - класс из таблицы Schema: категория, наследование, атрибуты, концы связей, idGen, валидатор, fieldTypes.
+//   FieldType - тип поля attributes для SQL-кастов (number/date/boolean/string/array/record/object/any).
+//   OP - символьная метка операторов фильтра (Symbol — не конфликтует с данными).
+//   Op - узел оператора фильтра: { [OP]: имя, args }.
+//   Scalar - скалярное значение фильтра: string | number | boolean | null.
+//   FieldFilter - значение фильтра по полю: скаляр (eq) / массив / оператор Op / вложенный record.
+//   Filter - фильтр шага: id-строка/массив, Op (or) или объект полей data.
+//   Cursor - курсор keyset-пагинации: значение поля сортировки + id последней строки.
+//   PlanOp - операция записи шага (create/update/delete/anonymize) + снапшот модификаторов.
+//   ChainMods - модификаторы выборки цепочки (limit/offset/order/desc/asOf/after + внутренняя агрегация).
+//   Account - запись аккаунта служебной таблицы auth.
+//   Credential - учётные данные аккаунта (identifier/category/confirmed/…).
+//   Resource - ресурс ACL: alias/category/pattern/meta.
+//   Rule - правило ACL: account/resource/permission/weight/enabled.
+//   AclOp - операция над данными = категория Resource: 'READ' | 'WRITE' | 'DELETE'.
+//   AclDecision - решение ACL: allow + победившее правило + остаточный filter + code/message.
+//   QueryEvent - событие хука onQuery: режим, классы, ms, rows, slow.
+//   ConnectOpts - опции connect(): dsn/schema/partition/account/owner/max/enforceAccount/enforceAcl/onQuery/slowMs.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
+//
+// START_BLOCK_ENTITY_TYPES
+// END_BLOCK_ENTITY_TYPES
+//
+// START_BLOCK_FILTER_TYPES
 /** Метка операторов фильтра (Symbol — не конфликтует с данными). */
 export const OP = Symbol('letopis.op');
+// END_BLOCK_CONNECT_TYPES