letopis 0.13.0 → 0.18.0

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,7 +69,11 @@ export async function runQuery(ctx, text, params, mode, classes) {
             throw e;
         }
     }
+    // END_BLOCK_RUN_QUERY_RETRY
 }
+let nodeSeq = 0;
+/** Уникальная метка узла пути (для pivot-возвратов; переживает нарезку плана). */
+export const nextNodeKey = () => ++nodeSeq;
 /** Накопитель позиционных параметров. */
 class Params {
     list = [];
@@ -120,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++) {
@@ -127,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')
@@ -189,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) {
@@ -212,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)
@@ -238,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);
     /**
@@ -303,8 +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')
@@ -315,9 +373,9 @@ export function resolveHop(prev, next) {
         // self-переход (Папка→Папка) = reverse: дети; родитель и так лежит в row.links
         if (prev.id === next.id)
             return 'reverse';
-        if (prev.links.includes(next.id))
+        if (linksTo(prev, next.id))
             return 'forward';
-        if (next.links.includes(prev.id))
+        if (linksTo(next, prev.id))
             return 'reverse';
         throw new Error(`letopis: no path ${prev.id} → ${next.id}: neither embeds the other (Schema.links)`);
     }
@@ -336,27 +394,76 @@ 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(). */
-function afterCond(alias, cls, mods, p) {
+/** Keyset-пагинация: (поле сортировки, id) строго после курсора. Требует .sort(). Выражение без WHERE. */
+function afterExpr(alias, cls, mods, p) {
     if (!mods.after)
-        return '';
+        return undefined;
     if (!mods.order)
         throw new Error('letopis: .after(cursor) requires .sort(field)');
     const expr = sortField(alias, cls, mods.order);
     const cast = mods.order === 'updated' ? '::timestamptz' : castOf(leafType(cls, mods.order.slice(5).split('.')));
     const cmp = mods.desc ? '<' : '>';
-    return ` WHERE (${expr}, ${alias}.id) ${cmp} (${p.push(mods.after.v)}${cast}, ${p.push(mods.after.id)})`;
+    return `(${expr}, ${alias}.id) ${cmp} (${p.push(mods.after.v)}${cast}, ${p.push(mods.after.id)})`;
 }
+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();
     const ent = entityTable(ctx.pgSchema);
     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
+    for (let i = 0; i < steps.length; i++) {
+        const s = steps[i];
+        if (s.pivotKey !== undefined) {
+            const at = byNodeKey.get(s.pivotKey);
+            if (at === undefined)
+                throw new Error(`letopis: pivot "${s.name}" — node is not in this path`);
+            real[i] = at;
+        }
+        else {
+            real[i] = i;
+            if (s.nodeKey !== undefined)
+                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];
+        // pivot-шаг: узел уже есть — только дофильтры (AND на алиас узла)
+        if (step.pivotKey !== undefined) {
+            const a = `h${real[i]}`;
+            const f = compileFilter(step.cls, step.filter, p);
+            for (const c of f.idConds)
+                tailConds.push(c(a));
+            for (const fr of f.finalFrags)
+                tailConds.push(fr(a));
+            if (step.tagsFilter !== undefined)
+                tailConds.push(compileTags(step.tagsFilter, p)(a));
+            continue;
+        }
         const pCls = p.push(step.cls.id);
         const f = compileFilter(step.cls, step.filter, p);
         // модификаторы шага: .tags() / .account() / .owner()
@@ -420,16 +527,17 @@ export function buildRead(ctx, steps, mods, mode) {
         const isDeep = step.deepMax !== undefined;
         if (i > 0 && !isDeep) { // deep строит containment сам (recursive CTE)
             const prev = steps[i - 1];
+            const prevAlias = `h${real[i - 1]}`; // pivot: ветвление от узла-возврата
             const hop = resolveHop(prev.cls, step.cls);
             if (hop === 'forward') {
                 // id неизменен — условие сразу во внутренний WHERE, перепроверка не нужна
-                innerWhere.push(`e.id = h${i - 1}.links->>${p.push(step.cls.id)}`);
+                innerWhere.push(`e.id = ${prevAlias}.links->>${p.push(step.cls.id)}`);
             }
             else {
                 // reverse containment: кандидаты по GIN + перепроверка на latest
                 const pKey = p.push(prev.cls.id);
-                candWhere.push(`c.links @> jsonb_build_object(${pKey}::text, h${i - 1}.id)`);
-                outerWhere.push(`t.links @> jsonb_build_object(${pKey}::text, h${i - 1}.id)`);
+                candWhere.push(`c.links @> jsonb_build_object(${pKey}::text, ${prevAlias}.id)`);
+                outerWhere.push(`t.links @> jsonb_build_object(${pKey}::text, ${prevAlias}.id)`);
             }
         }
         if (candWhere.length) {
@@ -456,53 +564,59 @@ export function buildRead(ctx, steps, mods, mode) {
                 ` WHERE t.deleted IS NULL AND t.links @> jsonb_build_object(${p.push(step.cls.id)}::text, ${ref}))`;
             block =
                 `(WITH RECURSIVE d AS (` +
-                    `SELECT k.*, 1 AS depth FROM ${kids(`h${i - 1}.id`)} k` +
+                    `SELECT k.*, 1 AS depth FROM ${kids(`h${real[i - 1]}.id`)} k` +
                     ` UNION ALL ` +
                     `SELECT k.*, d.depth + 1 FROM d JOIN LATERAL ${kids('d.id')} k ON true WHERE d.depth < ${pMax}::int` +
                     `) SELECT * FROM d) h${i}`;
         }
         blocks.push(i === 0 ? `FROM ${block}` : `JOIN LATERAL ${block} ON true`);
     }
+    // END_BLOCK_BUILD_STEP_LOOP
     const fromClause = blocks.join('\n');
-    const last = steps.length - 1;
-    const lastCls = steps[last].cls;
-    // ключи шагов в путях: alias → имя вызова; дубликаты получают _2, _3…
-    const keys = [];
+    const last = real[steps.length - 1]; // pivot в конце → терминал на его узле
+    const lastCls = steps[steps.length - 1].cls;
+    // ключи шагов в путях: alias → имя вызова; pivot узла не добавляет; дубликаты — _2, _3…
+    const keyed = [];
     const seen = new Map();
-    for (const s of steps) {
+    for (let i = 0; i < steps.length; i++) {
+        const s = steps[i];
+        if (s.pivotKey !== undefined)
+            continue;
         const base = s.aliasKey ?? s.name;
         const n = (seen.get(base) ?? 0) + 1;
         seen.set(base, n);
-        keys.push(n === 1 ? base : `${base}_${n}`);
+        keyed.push({ key: n === 1 ? base : `${base}_${n}`, block: i });
     }
+    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': {
-            const obj = keys.map((k, i) => `${p.push(k)}::text, to_jsonb(h${i})`).join(', ');
+            const obj = keyed.map(({ key, block }) => `${p.push(key)}::text, to_jsonb(h${block})`).join(', ');
             text =
                 `SELECT jsonb_build_object(${obj}) AS path\n${fromClause}` +
-                    afterCond(`h${last}`, lastCls, mods, p) +
+                    whereOf([...tailConds, afterExpr(`h${last}`, lastCls, mods, p)]) +
                     orderExpr(`h${last}`, lastCls, mods) +
                     limitOffset;
             break;
         }
         case 'rows':
         case 'ids': {
-            const inner = `SELECT DISTINCT ON (h${last}.id) h${last}.* \n${fromClause}\n` +
+            const inner = `SELECT DISTINCT ON (h${last}.id) h${last}.* \n${fromClause}${whereOf(tailConds)}\n` +
                 `ORDER BY h${last}.id, h${last}.updated DESC`;
             const sel = mode === 'rows' ? 'to_jsonb(z) AS row' : 'z.id';
             text =
                 `SELECT ${sel} FROM (${inner}) z` +
-                    afterCond('z', lastCls, mods, p) +
+                    whereOf([afterExpr('z', lastCls, mods, p)]) +
                     orderExpr('z', lastCls, mods) +
                     limitOffset;
             break;
         }
         case 'versions': {
             // ВСЕ версии (включая tombstone) сущностей последнего шага, по возрастанию updated
-            const inner = `SELECT DISTINCT h${last}.id \n${fromClause}`;
+            const inner = `SELECT DISTINCT h${last}.id \n${fromClause}${whereOf(tailConds)}`;
             text =
                 `SELECT to_jsonb(v) AS row FROM (${inner}) z ` +
                     `JOIN ${ent} v ON v.partition = ${pPart} AND v.class = ${p.push(lastCls.id)} AND v.id = z.id ` +
@@ -511,7 +625,7 @@ export function buildRead(ctx, steps, mods, mode) {
             break;
         }
         case 'count':
-            text = `SELECT count(*)::int AS n\n${fromClause}`;
+            text = `SELECT count(*)::int AS n\n${fromClause}${whereOf(tailConds)}`;
             break;
         case 'agg': {
             const { aggFn, aggField } = mods;
@@ -521,18 +635,26 @@ export function buildRead(ctx, steps, mods, mode) {
             const path = aggField.slice(5).split('.');
             const acc = accessor(path)(`h${last}`); // data-путь любой глубины
             if (aggFn === 'countBy') {
-                text = `SELECT ${acc} AS k, count(*)::int AS n\n${fromClause}\nGROUP BY 1 ORDER BY 2 DESC`;
+                text = `SELECT ${acc} AS k, count(*)::int AS n\n${fromClause}${whereOf(tailConds)}\nGROUP BY 1 ORDER BY 2 DESC`;
             }
             else {
                 // sum/avg — всегда numeric; min/max — по типу листа
                 const cast = aggFn === 'sum' || aggFn === 'avg' ? '::numeric' : castOf(leafType(lastCls, path));
-                text = `SELECT ${aggFn}((${acc})${cast}) AS v\n${fromClause}`;
+                text = `SELECT ${aggFn}((${acc})${cast}) AS v\n${fromClause}${whereOf(tailConds)}`;
             }
             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)} ` +
@@ -558,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})`;
@@ -566,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.d.ts

@@ -18,6 +18,32 @@ export interface Row {
 }
 /** Результат run(): вариант пути — узел на каждый шаг цепочки. */
 export type Path = Record<string, Row>;
+/**
+ * Конец связи класса (Schema.links v2). В БД элемент text[]: JSON-объект
+ * `{"class":"Org","cardinality":1}` / `{"classes":["Service","Complex"],"cardinality":1}`
+ * (союз ролей); legacy-строка 'Org' — сахар для {classes:['Org']} (старые схемы).
+ */
+export interface LinkEnd {
+    /** Допустимые классы конца; ровно один из них присутствует в Entity.links. */
+    classes: string[];
+    /** Конец может отсутствовать. Default false. */
+    optional?: boolean;
+    /** ЗАРЕЗЕРВИРОВАНО (не имплементировано): 0 — безлимит, N — точное число. Default 1. */
+    cardinality?: number;
+}
+/**
+ * Генерация id класса — из attributes.id:
+ *   "uuid" | {type:'uuid'}                    → v4 (random, дефолт);
+ *   {type:'uuid', generate: 7}                → v7 (время в старших битах);
+ *   {type:'uuid', generate: 5, from: ['Slot','Staff']} → v5: детерминированный id из значений
+ *     from — имена ОБЯЗАТЕЛЬНЫХ концов Schema.links (класс или полное имя союза
+ *     'Service|Complex') и/или скалярных полей data.
+ */
+export interface IdGen {
+    version: 4 | 5 | 7;
+    /** Только v5: источники имени (порядок значим). */
+    from?: string[];
+}
 /** Класс из таблицы Schema. */
 export interface ClassDef {
     id: string;
@@ -27,11 +53,20 @@ export interface ClassDef {
     ancestors: string[];
     /** Все потомки (транзитивно) — считает триггер schema_lineage. */
     descendants: string[];
+    /** Поля data с НАСЛЕДОВАНИЕМ по ancestor-цепочке (потомок поверх предка). */
     attributes: Record<string, unknown>;
-    links: string[];
+    links: LinkEnd[];
+    /**
+     * true — хотя бы один конец объявлен объектом (схема v2): строгая валидация
+     * (жадный матчинг по порядку, союзы, optional, лишние связи — ошибка).
+     * false — все концы legacy-строками: старое поведение ('Entity' = полиморф, лишние молчат).
+     */
+    strictEnds: boolean;
     meta: Record<string, unknown>;
     abstract: boolean;
     order: number;
+    /** Как генерить id новой сущности (attributes.id). */
+    idGen: IdGen;
     /** Скомпилированный fastest-validator: true | ошибки. */
     check: (data: Record<string, unknown>) => true | {
         field: string;
@@ -85,12 +120,13 @@ export interface Cursor {
     id: string;
 }
 /**
- * Операция записи, привязанная к шагу цепочки: .set() / .delete() / .anonymize().
+ * Операция записи, привязанная к шагу цепочки:
+ * .create() / .update() / .delete() / .anonymize().
  * Терминал исполняет план (все операции + финальное чтение) одной транзакцией.
  */
 export interface PlanOp {
-    kind: 'set' | 'delete' | 'anonymize';
-    /** set: данные новой версии (deep-merge листьев). */
+    kind: 'create' | 'update' | 'delete' | 'anonymize';
+    /** create/update: данные новой версии (deep-merge листьев). */
     data?: Record<string, unknown>;
     /** anonymize: string-поля под '[erased]'. */
     fields?: string[];

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