letopis 0.5.0 → 0.16.0

package/dist/sql.js

@@ -1,22 +1,63 @@
 import { OP } from './types.js';
 import { isOp } from './ops.js';
+import { aclDenied } from './acl.js';
+/** Транзиентные ошибки PG — гонка, снимаемая повтором: deadlock / serialization failure. */
+export function isTransient(e) {
+    const code = e.code;
+    return code === '40P01' || code === '40001';
+}
+/** Внутри db.begin() повтор невозможен (вся транзакция aborted) — дописываем подсказку. */
+export function hintTxRetry(e) {
+    const err = e;
+    if (err.letopisHinted || typeof err.message !== 'string')
+        return;
+    err.letopisHinted = true;
+    err.message += ' — letopis: transaction is aborted, retry the whole db.begin() block';
+}
+export const RETRIES = 3;
+export const retryDelay = (attempt) => new Promise((r) => setTimeout(r, 40 * attempt + Math.random() * 40));
+const READ_MODES = new Set([
+    'paths', 'rows', 'ids', 'count', 'versions', 'agg',
+]);
 /**
  * Единая точка исполнения запросов цепочек: sql.unsafe + событие onQuery/slowMs.
+ * Чтения в автокоммите ретраят transient-ошибки (40P01/40001); внутри db.begin()
+ * повтор запрещён семантикой PG — ошибка уходит наружу с подсказкой.
  * Служебные запросы (loadRegistry, tables, listen) через неё не идут.
  */
 export async function runQuery(ctx, text, params, mode, classes) {
-    const t0 = performance.now();
-    const res = (await ctx.sql.unsafe(text, params));
-    if (ctx.onQuery || ctx.slowMs !== undefined) {
-        const ms = performance.now() - t0;
-        const slow = ctx.slowMs !== undefined && ms > ctx.slowMs;
-        if (ctx.onQuery)
-            ctx.onQuery({ mode, classes, ms, rows: res.length, slow });
-        else if (slow)
-            console.warn(`letopis: slow query ${ms.toFixed(0)}ms — ${mode} ${classes.join('→')}`);
+    for (let attempt = 1;; attempt++) {
+        const t0 = performance.now();
+        try {
+            const res = (await ctx.sql.unsafe(text, params));
+            if (ctx.onQuery || ctx.slowMs !== undefined) {
+                const ms = performance.now() - t0;
+                const slow = ctx.slowMs !== undefined && ms > ctx.slowMs;
+                if (ctx.onQuery)
+                    ctx.onQuery({ mode, classes, ms, rows: res.length, slow });
+                else if (slow)
+                    console.warn(`letopis: slow query ${ms.toFixed(0)}ms — ${mode} ${classes.join('→')}`);
+            }
+            return res;
+        }
+        catch (e) {
+            if (isTransient(e)) {
+                if (ctx.inTx) {
+                    if (ctx.userTx)
+                        hintTxRetry(e);
+                }
+                else if (READ_MODES.has(mode) && attempt < RETRIES) {
+                    await retryDelay(attempt);
+                    continue;
+                }
+            }
+            throw e;
+        }
     }
-    return res;
 }
+let nodeSeq = 0;
+/** Уникальная метка узла пути (для pivot-возвратов; переживает нарезку плана). */
+export const nextNodeKey = () => ++nodeSeq;
 /** Накопитель позиционных параметров. */
 class Params {
     list = [];
@@ -28,6 +69,35 @@ class Params {
 const escId = (s) => `"${s.replace(/"/g, '""')}"`;
 const escLit = (s) => s.replace(/'/g, "''");
 export const entityTable = (pgSchema) => `${escId(pgSchema)}.${escId('Entity')}`;
+/**
+ * ACL-шаблон строки Entity → WHERE-фраги: колонки равенством, jsonb/tags — containment.
+ * Вливается и в кандидаты (GIN), и в перепроверку — ДО сортировки/лимита (пагинация цела).
+ */
+function rowTemplateFrags(tpl, p) {
+    const frags = [];
+    for (const [k, v] of Object.entries(tpl)) {
+        if (k === 'data' || k === 'links') {
+            const ph = p.push(v);
+            frags.push((a) => `${a}.${k} @> ${ph}::jsonb`);
+        }
+        else if (k === 'tags') {
+            const ph = p.push(Array.isArray(v) ? v : [v]);
+            frags.push((a) => `${a}.tags @> ${ph}`);
+        }
+        else if (k === 'owner' || k === 'account') {
+            const ph = p.push(v);
+            frags.push((a) => `${a}.${k} = ${ph}::uuid`);
+        }
+        else if (k === 'id' || k === 'partition') {
+            const ph = p.push(v);
+            frags.push((a) => `${a}.${k} = ${ph}`);
+        }
+        else {
+            throw new Error(`letopis: acl pattern key "${k}" is not an Entity column`);
+        }
+    }
+    return frags;
+}
 function castOf(ft) {
     switch (ft?.kind) {
         case 'number':
@@ -42,11 +112,23 @@ function castOf(ft) {
 }
 /** Каст параметра по JS-типу (для jsonb_build_array). */
 const jsCast = (v) => typeof v === 'number' ? '::numeric' : typeof v === 'boolean' ? '::boolean' : '::text';
-/** Доступ к полю data: 1 уровень — data->>'f'; 2 (record) — data->'f'->>'k'. */
+/** jsonb-выражение до пути (без извлечения текста): data->'a'->'b'. */
+function jsonbAt(path) {
+    return (a) => `${a}.data${path.map((k) => `->'${escLit(k)}'`).join('')}`;
+}
+/** Текст листа по data-пути ЛЮБОЙ глубины: data->'a'->'b'->>'c'. */
 function accessor(path) {
-    if (path.length === 1)
-        return (a) => `${a}.data->>'${escLit(path[0])}'`;
-    return (a) => `${a}.data->'${escLit(path[0])}'->>'${escLit(path[1])}'`;
+    const head = path.slice(0, -1);
+    const last = path[path.length - 1];
+    return (a) => `${jsonbAt(head)(a)}->>'${escLit(last)}'`;
+}
+/** Тип листа data-пути по Schema: спуск через record (значение) и object (props). */
+export function leafType(cls, path) {
+    let ft = cls.fieldTypes.get(path[0]);
+    for (let i = 1; i < path.length && ft; i++) {
+        ft = ft.kind === 'record' ? ft.value : ft.kind === 'object' ? ft.props.get(path[i]) : undefined;
+    }
+    return ft;
 }
 function compileOp(path, ft, o, p) {
     const lhs = accessor(path);
@@ -79,23 +161,26 @@ function compileOp(path, ft, o, p) {
             return (a) => `${lhs(a)} ILIKE ${p.push(args[0])}`;
         case 'has':
             // jsonb_build_array с кастом по JS-типу — JS-массив postgres.js слал бы как PG-array
-            return (a) => `${a}.data->'${escLit(path[0])}' @> jsonb_build_array(${p.push(args[0])}${jsCast(args[0])})`;
+            return (a) => `${jsonbAt(path)(a)} @> jsonb_build_array(${p.push(args[0])}${jsCast(args[0])})`;
         case 'hasAll': {
             const vs = args[0];
             if (!vs.length)
                 return () => 'TRUE';
-            return (a) => `${a}.data->'${escLit(path[0])}' @> jsonb_build_array(${vs.map((x) => p.push(x) + jsCast(x)).join(', ')})`;
+            return (a) => `${jsonbAt(path)(a)} @> jsonb_build_array(${vs.map((x) => p.push(x) + jsCast(x)).join(', ')})`;
         }
         case 'hasAny': {
             const vs = args[0];
             if (!vs.length)
                 return () => 'FALSE';
-            return (a) => `${a}.data->'${escLit(path[0])}' ?| ARRAY[${vs.map((x) => p.push(String(x))).join(', ')}]::text[]`;
+            return (a) => `${jsonbAt(path)(a)} ?| ARRAY[${vs.map((x) => p.push(String(x))).join(', ')}]::text[]`;
         }
-        case 'exists':
+        case 'exists': {
+            const holder = jsonbAt(path.slice(0, -1));
+            const last = escLit(path[path.length - 1]);
             return args[0]
-                ? (a) => `${a}.data ? '${escLit(path[0])}'`
-                : (a) => `NOT (${a}.data ? '${escLit(path[0])}')`;
+                ? (a) => `${holder(a)} ? '${last}'`
+                : (a) => `NOT (${holder(a)} ? '${last}')`;
+        }
         case 'isNull':
             return (a) => `${lhs(a)} IS NULL`;
         case 'not': {
@@ -157,6 +242,39 @@ function compileFilter(cls, filter, p) {
         return out;
     }
     const eqData = {};
+    const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !isOp(v);
+    /**
+     * Рекурсивный разбор объекта фильтра на ЛЮБУЮ глубину:
+     * операторы уходят в finalFrags по своему пути (каст по типу листа из Schema),
+     * скаляры/массивы собираются в containment-поддерево (GIN).
+     * Возврат: поддерево для eqData; undefined — внутри были только операторы.
+     */
+    const walk = (path, obj) => {
+        const eq = {};
+        let hadOps = false;
+        for (const [k, v] of Object.entries(obj)) {
+            if (v === undefined)
+                continue;
+            const sub = [...path, k];
+            if (isOp(v)) {
+                out.finalFrags.push(compileOp(sub, leafType(cls, sub), v, p));
+                hadOps = true;
+            }
+            else if (isPlain(v)) {
+                const nested = walk(sub, v);
+                if (nested !== undefined)
+                    eq[k] = nested;
+                else
+                    hadOps = true;
+            }
+            else {
+                eq[k] = v;
+            }
+        }
+        if (Object.keys(eq).length)
+            return eq;
+        return hadOps ? undefined : {}; // пустой объект без операторов → containment {}
+    };
     for (const [key, value] of Object.entries(filter)) {
         if (value === undefined)
             continue;
@@ -169,29 +287,14 @@ function compileFilter(cls, filter, p) {
                 throw new Error('letopis: filter.id accepts string | string[]');
             continue;
         }
-        const ft = cls.fieldTypes.get(key);
         if (isOp(value)) {
-            out.finalFrags.push(compileOp([key], ft, value, p));
+            out.finalFrags.push(compileOp([key], cls.fieldTypes.get(key), value, p));
             continue;
         }
-        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-            // объект: операторы по вложенным путям (record) и/или containment-скаляры
-            const nestedEq = {};
-            let hasNested = false;
-            for (const [sub, sv] of Object.entries(value)) {
-                if (isOp(sv)) {
-                    const vt = ft?.kind === 'record' ? ft.value : undefined;
-                    out.finalFrags.push(compileOp([key, sub], vt, sv, p));
-                    hasNested = true;
-                }
-                else {
-                    nestedEq[sub] = sv;
-                }
-            }
-            if (Object.keys(nestedEq).length)
-                eqData[key] = nestedEq;
-            else if (!hasNested)
-                eqData[key] = value;
+        if (isPlain(value)) {
+            const nested = walk([key], value);
+            if (nested !== undefined)
+                eqData[key] = nested;
             continue;
         }
         // скаляр / массив — точное совпадение через containment (GIN)
@@ -205,6 +308,10 @@ function compileFilter(cls, filter, p) {
     }
     return out;
 }
+/** Класс target входит в какой-нибудь конец def (союзы учитываются). */
+export function linksTo(def, target) {
+    return def.links.some((end) => end.classes.includes(target));
+}
 /** Правило обхода между шагами (по реестру Schema). */
 export function resolveHop(prev, next) {
     if (prev.category === 'HUB' && next.category === 'LINK')
@@ -215,52 +322,83 @@ 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)`);
     }
     throw new Error(`letopis: LINK → LINK traversal is not supported (${prev.id} → ${next.id})`);
 }
-/** Тип листа data-пути (для каста агрегаций): 1 уровень или record-значение. */
-function cls0Field(cls, path) {
-    const ft = cls.fieldTypes.get(path[0]);
-    return path.length === 1 ? ft : ft?.kind === 'record' ? ft.value : undefined;
-}
 function sortField(alias, cls, order) {
     if (order === 'updated')
         return `${alias}.updated`;
     if (order.startsWith('data.')) {
-        const field = order.slice(5);
-        return `(${alias}.data->>'${escLit(field)}')${castOf(cls.fieldTypes.get(field))}`;
+        // data-путь любой глубины ('data.settings.booking.deposit.amount') + каст по типу листа
+        const path = order.slice(5).split('.');
+        return `(${accessor(path)(alias)})${castOf(leafType(cls, path))}`;
     }
-    throw new Error(`letopis: order must be 'updated' or 'data.<field>'`);
+    throw new Error(`letopis: order must be 'updated' or 'data.<path>'`);
 }
 function orderExpr(alias, cls, mods) {
     if (!mods.order)
         return '';
     return ` ORDER BY ${sortField(alias, cls, mods.order)}${mods.desc ? ' DESC' : ''}`;
 }
-/** 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(cls.fieldTypes.get(mods.order.slice(5)));
+    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 ')}` : '';
+};
 /** Построить читающий запрос по цепочке. */
 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).
+    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);
+        }
+    }
     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()
@@ -292,6 +430,25 @@ export function buildRead(ctx, steps, mods, mode) {
             f.candFrags.push(frag);
             f.finalFrags.push(frag);
         }
+        // enforceAcl: READ-право на КАЖДЫЙ шаг; предикат победившего правила — в WHERE заранее
+        if (ctx.aclDecide) {
+            const d = ctx.aclDecide(step.cls, 'READ');
+            if (!d.allow)
+                throw aclDenied('READ', step.cls.id, d);
+            if (d.filter) {
+                for (const fr of rowTemplateFrags(d.filter, p)) {
+                    f.candFrags.push(fr);
+                    f.finalFrags.push(fr);
+                }
+            }
+        }
+        // предикат WRITE/DELETE-правила (поиск целей записи): только свои строки
+        if (step.aclFilter) {
+            for (const fr of rowTemplateFrags(step.aclFilter, p)) {
+                f.candFrags.push(fr);
+                f.finalFrags.push(fr);
+            }
+        }
         const innerWhere = [`e.partition = ${pPart}`, `e.class = ${pCls}`];
         if (mods.asOf !== undefined)
             innerWhere.push(`e.updated <= ${p.push(mods.asOf)}::timestamptz`); // «как было на T»
@@ -305,16 +462,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) {
@@ -341,7 +499,7 @@ 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}`;
@@ -349,45 +507,49 @@ export function buildRead(ctx, steps, mods, mode) {
         blocks.push(i === 0 ? `FROM ${block}` : `JOIN LATERAL ${block} ON true`);
     }
     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)}` : '');
     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 ` +
@@ -396,7 +558,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;
@@ -404,17 +566,14 @@ export function buildRead(ctx, steps, mods, mode) {
                 throw new Error("letopis: aggregation needs field 'data.<путь>'");
             }
             const path = aggField.slice(5).split('.');
-            const acc = path.length === 1
-                ? `h${last}.data->>'${escLit(path[0])}'`
-                : `h${last}.data->'${escLit(path[0])}'->>'${escLit(path[1])}'`;
+            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 ft = cls0Field(lastCls, path);
-                const cast = aggFn === 'sum' || aggFn === 'avg' ? '::numeric' : castOf(ft);
-                text = `SELECT ${aggFn}((${acc})${cast}) AS v\n${fromClause}`;
+                // 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}${whereOf(tailConds)}`;
             }
             break;
         }

package/dist/tx.d.ts

@@ -3,7 +3,7 @@
  * db.commit(tr) / db.rollback(tr) / tr.commit() / tr.rollback().
  * tr.lock(...) — pg_advisory_xact_lock (сериализация гонок, напр. двойная бронь).
  */
-import type { Ctx } from './sql.js';
+import { type Ctx } from './sql.js';
 export interface TxCtx extends Ctx {
     commit(): Promise<void>;
     rollback(): Promise<void>;

package/dist/tx.js

@@ -1,3 +1,9 @@
+/**
+ * Транзакции: db.begin() → tr (тот же API на выделенном соединении),
+ * db.commit(tr) / db.rollback(tr) / tr.commit() / tr.rollback().
+ * tr.lock(...) — pg_advisory_xact_lock (сериализация гонок, напр. двойная бронь).
+ */
+import { hintTxRetry, isTransient } from './sql.js';
 export async function beginTx(ctx) {
     const reserved = await ctx.sql.reserve();
     const r = reserved;
@@ -18,6 +24,7 @@ export async function beginTx(ctx) {
         ...ctx,
         sql: reserved,
         inTx: true,
+        userTx: true,
         commit: () => finish('COMMIT'),
         rollback: () => finish('ROLLBACK'),
     };
@@ -27,5 +34,13 @@ export async function lock(ctx, ...keys) {
     if (!ctx.inTx) {
         throw new Error('letopis: lock() works only inside db.begin() transaction (pg_advisory_xact_lock)');
     }
-    await ctx.sql.unsafe('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]);
+    try {
+        await ctx.sql.unsafe('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]);
+    }
+    catch (e) {
+        // встречный порядок lock() двух транзакций → deadlock 40P01 (PG убивает одну)
+        if (isTransient(e))
+            hintTxRetry(e);
+        throw e;
+    }
 }