letopis 1.3.0 → 1.4.1

package/dist/ops.d.ts

@@ -5,39 +5,79 @@
  */
 import { type Op, type Scalar } from './types.js';
 export declare const isOp: (v: unknown) => v is Op;
-/** ≠ (IS DISTINCT FROM) */
+/**
+ * Не равно: `db.Order({ status: ne('cancelled') })`. Подходят и строки, где поля нет или в нём `null`, а `ne(null)` —
+ * строки, где у поля есть значение.
+ */
 export declare const ne: (v: Scalar) => Op;
-/** > */
+/**
+ * Больше: `db.Product({ price: gt(1000) })`. Сравнение — по типу поля из описания класса (числа — как числа, даты — как
+ * даты), поле без описания сравнивается как текст; строки без поля не подходят.
+ */
 export declare const gt: (v: Scalar) => Op;
-/** ≥ */
+/** Больше или равно: `db.Product({ price: gte(500) })`. Сравнение — как у `gt()`. */
 export declare const gte: (v: Scalar) => Op;
-/** < */
+/** Меньше: `db.Product({ price: lt(1000) })`. Сравнение — как у `gt()`. */
 export declare const lt: (v: Scalar) => Op;
-/** ≤ */
+/** Меньше или равно: `db.Product({ price: lte(900) })`. Сравнение — как у `gt()`. */
 export declare const lte: (v: Scalar) => Op;
-/** a ≤ x ≤ b */
+/**
+ * От `a` до `b` включительно: `db.Product({ price: between(500, 3000) })`. Сравнение — как у `gt()`; если `a` больше
+ * `b`, не подходит ни одна строка.
+ */
 export declare const between: (a: Scalar, b: Scalar) => Op;
-/** значение из списка */
+/**
+ * Одно из значений списка: `db.Product({ sku: inList(['K-1', 'M-1']) })`. Сравнение — по типу поля, как у `gt()`;
+ * пустой список не находит ничего, а `null` в списке не находит строк без значения — для них есть `isNull()`.
+ */
 export declare const inList: (vs: Scalar[]) => Op;
-/** LIKE (шаблон с % и _) */
+/**
+ * Текст по шаблону с учётом регистра: `%` — любые символы, в том числе ни одного, `_` — ровно один символ;
+ * `db.Product({ title: like('%чай%') })`. Поле берётся как текст; буквальные `%` и `_` пишут с обратной косой чертой:
+ * `like('100\\%')`.
+ */
 export declare const like: (s: string) => Op;
-/** ILIKE (без регистра) */
+/** Как `like()`, но без учёта регистра: `db.Product({ title: ilike('%чай%') })`. */
 export declare const ilike: (s: string) => Op;
-/** начинается с */
+/**
+ * Текст начинается с `s`, с учётом регистра: `db.Product({ sku: starts('T-') })`. Это `like(s + '%')`: `%`, `_` и
+ * обратная косая черта внутри `s` не экранируются и работают как в шаблоне `like()`.
+ */
 export declare const starts: (s: string) => Op;
-/** заканчивается на */
+/**
+ * Текст заканчивается на `s`, с учётом регистра: `db.Product({ sku: ends('-1') })`. Это `like('%' + s)`: `%`, `_` и
+ * обратная косая черта внутри `s` не экранируются и работают как в шаблоне `like()`.
+ */
 export declare const ends: (s: string) => Op;
-/** массив-поле содержит значение */
+/**
+ * Поле-массив содержит элемент `v`: `db.Product({ labels: has('хит') })`. Тип важен: `has(5)` найдёт число 5, но не
+ * строку `'5'`.
+ */
 export declare const has: (v: Scalar) => Op;
-/** массив-поле содержит хотя бы одно из */
+/**
+ * Поле-массив содержит хотя бы один элемент из списка: `db.Product({ labels: hasAny(['хит', 'акция']) })`. Находит
+ * только строковые элементы; пустой список не находит ничего.
+ */
 export declare const hasAny: (vs: Scalar[]) => Op;
-/** массив-поле содержит все */
+/**
+ * Поле-массив содержит все элементы списка, в любом порядке: `db.Product({ labels: hasAll(['хит', 'стекло']) })`. Тип
+ * элементов важен, как у `has()`; пустой список подходит любой строке, даже без этого поля.
+ */
 export declare const hasAll: (vs: Scalar[]) => Op;
-/** поле присутствует (true) или отсутствует (false) */
+/**
+ * Поле есть в данных (`true`, по умолчанию) или его нет (`false`); значение не важно — поле с `null` тоже есть:
+ * `db.Product({ labels: exists(false) })` — товары без поля `labels`.
+ */
 export declare const exists: (yes?: boolean) => Op;
-/** поле null или отсутствует */
+/** В поле `null` или поля нет совсем: `db.Product({ specs: isNull() })`. Отличить одно от другого помогает `exists()`. */
 export declare const isNull: () => Op;
-/** НЕ-условие по полю: not(ilike('%тест%')); скаляр — «не равно» */
+/**
+ * Отрицание оператора: `db.Product({ price: not(gte(1000)) })` — цена меньше 1000 или поля нет. Простое значение вместо
+ * оператора значит «не равно», как `ne()`: `db.Order({ status: not('cancelled') })`.
+ */
 export declare const not: (v: Scalar | Op) => Op;
-/** ИЛИ на уровне фильтра шага: t.booking(or({ notes: 'a' }, { notes: 'b' })) */
+/**
+ * Хотя бы один из фильтров: `db.Product(or({ sku: 'K-1' }, { price: lt(500) }))` — товар K-1 или дешевле 500. Ставится
+ * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и».
+ */
 export declare const or: (...filters: Record<string, unknown>[]) => Op;

package/dist/ops.js

@@ -6,39 +6,79 @@
 import { OP } from './types.js';
 const op = (name, ...args) => ({ [OP]: name, args });
 export const isOp = (v) => typeof v === 'object' && v !== null && OP in v;
-/** ≠ (IS DISTINCT FROM) */
+/**
+ * Не равно: `db.Order({ status: ne('cancelled') })`. Подходят и строки, где поля нет или в нём `null`, а `ne(null)` —
+ * строки, где у поля есть значение.
+ */
 export const ne = (v) => op('ne', v);
-/** > */
+/**
+ * Больше: `db.Product({ price: gt(1000) })`. Сравнение — по типу поля из описания класса (числа — как числа, даты — как
+ * даты), поле без описания сравнивается как текст; строки без поля не подходят.
+ */
 export const gt = (v) => op('gt', v);
-/** ≥ */
+/** Больше или равно: `db.Product({ price: gte(500) })`. Сравнение — как у `gt()`. */
 export const gte = (v) => op('gte', v);
-/** < */
+/** Меньше: `db.Product({ price: lt(1000) })`. Сравнение — как у `gt()`. */
 export const lt = (v) => op('lt', v);
-/** ≤ */
+/** Меньше или равно: `db.Product({ price: lte(900) })`. Сравнение — как у `gt()`. */
 export const lte = (v) => op('lte', v);
-/** a ≤ x ≤ b */
+/**
+ * От `a` до `b` включительно: `db.Product({ price: between(500, 3000) })`. Сравнение — как у `gt()`; если `a` больше
+ * `b`, не подходит ни одна строка.
+ */
 export const between = (a, b) => op('between', a, b);
-/** значение из списка */
+/**
+ * Одно из значений списка: `db.Product({ sku: inList(['K-1', 'M-1']) })`. Сравнение — по типу поля, как у `gt()`;
+ * пустой список не находит ничего, а `null` в списке не находит строк без значения — для них есть `isNull()`.
+ */
 export const inList = (vs) => op('in', vs);
-/** LIKE (шаблон с % и _) */
+/**
+ * Текст по шаблону с учётом регистра: `%` — любые символы, в том числе ни одного, `_` — ровно один символ;
+ * `db.Product({ title: like('%чай%') })`. Поле берётся как текст; буквальные `%` и `_` пишут с обратной косой чертой:
+ * `like('100\\%')`.
+ */
 export const like = (s) => op('like', s);
-/** ILIKE (без регистра) */
+/** Как `like()`, но без учёта регистра: `db.Product({ title: ilike('%чай%') })`. */
 export const ilike = (s) => op('ilike', s);
-/** начинается с */
+/**
+ * Текст начинается с `s`, с учётом регистра: `db.Product({ sku: starts('T-') })`. Это `like(s + '%')`: `%`, `_` и
+ * обратная косая черта внутри `s` не экранируются и работают как в шаблоне `like()`.
+ */
 export const starts = (s) => op('like', s + '%');
-/** заканчивается на */
+/**
+ * Текст заканчивается на `s`, с учётом регистра: `db.Product({ sku: ends('-1') })`. Это `like('%' + s)`: `%`, `_` и
+ * обратная косая черта внутри `s` не экранируются и работают как в шаблоне `like()`.
+ */
 export const ends = (s) => op('like', '%' + s);
-/** массив-поле содержит значение */
+/**
+ * Поле-массив содержит элемент `v`: `db.Product({ labels: has('хит') })`. Тип важен: `has(5)` найдёт число 5, но не
+ * строку `'5'`.
+ */
 export const has = (v) => op('has', v);
-/** массив-поле содержит хотя бы одно из */
+/**
+ * Поле-массив содержит хотя бы один элемент из списка: `db.Product({ labels: hasAny(['хит', 'акция']) })`. Находит
+ * только строковые элементы; пустой список не находит ничего.
+ */
 export const hasAny = (vs) => op('hasAny', vs);
-/** массив-поле содержит все */
+/**
+ * Поле-массив содержит все элементы списка, в любом порядке: `db.Product({ labels: hasAll(['хит', 'стекло']) })`. Тип
+ * элементов важен, как у `has()`; пустой список подходит любой строке, даже без этого поля.
+ */
 export const hasAll = (vs) => op('hasAll', vs);
-/** поле присутствует (true) или отсутствует (false) */
+/**
+ * Поле есть в данных (`true`, по умолчанию) или его нет (`false`); значение не важно — поле с `null` тоже есть:
+ * `db.Product({ labels: exists(false) })` — товары без поля `labels`.
+ */
 export const exists = (yes = true) => op('exists', yes);
-/** поле null или отсутствует */
+/** В поле `null` или поля нет совсем: `db.Product({ specs: isNull() })`. Отличить одно от другого помогает `exists()`. */
 export const isNull = () => op('isNull');
-/** НЕ-условие по полю: not(ilike('%тест%')); скаляр — «не равно» */
+/**
+ * Отрицание оператора: `db.Product({ price: not(gte(1000)) })` — цена меньше 1000 или поля нет. Простое значение вместо
+ * оператора значит «не равно», как `ne()`: `db.Order({ status: not('cancelled') })`.
+ */
 export const not = (v) => op('not', v);
-/** ИЛИ на уровне фильтра шага: t.booking(or({ notes: 'a' }, { notes: 'b' })) */
+/**
+ * Хотя бы один из фильтров: `db.Product(or({ sku: 'K-1' }, { price: lt(500) }))` — товар K-1 или дешевле 500. Ставится
+ * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и».
+ */
 export const or = (...filters) => op('or', filters);

package/dist/project.d.ts

@@ -61,18 +61,25 @@ export interface ProjectorOut {
         tenant: string;
     }): void;
     /**
-     * Создать (поля без строки — от 0) или дополнить строку и прибавить числа: коммутативная свёртка без чтения.
-     * Приращения строки, заданной одними полями ключа (или одним $id), складываются до отправки в базу, пока между ними
-     * нет upsert, delete или get: одна правка строки на пачку.
+     * Прибавляет к полям строки числа из `deltas`: читать строку не нужно, и итог не зависит от порядка приращений. Поле
+     * приращения, которого в строке нет, считается от 0, а если нет самой строки, она создаётся; поля `row` дописываются в
+     * её данные. Приращения одной строки, заданной только полями ключа (или только `$id`), до отправки в базу складываются
+     * в одну правку, пока между ними нет `upsert`, `delete` или `get`.
      */
     inc(cls: string, row: ProjectorRow, deltas: Record<string, number>, opts: {
         tenant: string;
     }): void;
-    /** Удалить по ключу или id; строки нет — ничего. */
+    /**
+     * Удалить строку: у класса с ключом — по полям ключа, у класса без ключа — по id (строкой или { $id }); строки нет —
+     * ничего. Один id у класса с ключом — invalid_data.
+     */
     delete(cls: string, keyOrId: string | ProjectorRow, opts: {
         tenant: string;
     }): void;
-    /** Текущая строка внутри пачки (с записями пачки, сделанными до вызова); нет — null. */
+    /**
+     * Текущая строка внутри пачки (с записями пачки, сделанными до вызова); нет — null. Строку называют, как в delete: у
+     * класса с ключом — полями ключа, у класса без ключа — id; один id у класса с ключом — invalid_data.
+     */
     get(cls: string, keyOrId: string | ProjectorRow, opts: {
         tenant: string;
     }): Promise<Row | null>;
@@ -82,27 +89,40 @@ export interface ProjectorOptions {
     from: string[];
     /** Производные классы (с потомками): описание каждого — derivedBy: имя проектора. */
     into: string[];
-    /** Версия проектора: другая версия в чекпоинте — rebuild_required, нужна перестройка. */
+    /**
+     * Версия логики проектора — целое число от 1. Вместе с позицией в журнале проектор хранит в базе версию, которой
+     * построена проекция: если она другая, `run()` и `rebuild({ tenant })` отклоняются с `rebuild_required`, а полная
+     * перестройка `rebuild()` строит проекцию заново и запоминает новую версию.
+     */
     version: number;
-    /** Изменения одного арендатора (пачка делится по арендаторам) и запись его результатов. */
+    /**
+     * Функция `handle(changes, out)`: получает изменения одного арендатора и пишет его результаты через `out`. Пачку журнала
+     * проектор делит по арендаторам и вызывает `handle` для каждого по очереди.
+     */
     handle(changes: ProjectorChange[], out: ProjectorOut): void | Promise<void>;
     /** Подавать прошлую версию объекта (before). */
     withBefore?: boolean;
     /**
      * Курсор старше яруса all политики хранения источников (cursor_expired): 'rebuild' — перестроить самому, пачками.
-     * Ярус — по арендатору: истёк у части участников — выбывают они (с 'rebuild' — перестраиваются сами, каждый своей
-     * транзакцией), у всех — вся проекция.
+     * Ярус — по арендатору: истёк у части участников — выбывают они (с 'rebuild' — перестраиваются сами, по одному, пачками), у
+     * всех — вся проекция.
      */
     onExpired?: 'rebuild' | 'error';
     /** Изменений в пачке (по умолчанию 500). */
     batch?: number;
-    /** Запасной опрос журнала, мс (по умолчанию 1000; сигналы источников будят раньше). */
+    /** Как часто проектор сам проверяет журнал, если сигнал не пришёл, мс (по умолчанию 1000); сигналы источников будят его раньше. */
     pollMs?: number;
     /**
      * Сколько транзакция проектора ждёт чужую блокировку строки, мс (по умолчанию 5000; 0 — без предела). Дольше —
      * пачка откатывается, курсор остаётся, run() не отклоняется, а пропускает проход и повторяет его.
      */
     lockTimeout?: number;
+    /**
+     * Сколько проходов подряд запись одного арендатора может упираться в lockTimeout, прежде чем он выбудет (код 55P03,
+     * дальше — rebuild({ tenant })), а пачка пойдёт для остальных; по умолчанию 0 — не выбывает, проход повторяется для всех.
+     * Счёт — в процессе, удачная запись арендатора его сбрасывает.
+     */
+    lockRetries?: number;
     /**
      * Явный список арендаторов проектора: участники — только они (и только те, у кого каждый класс into помечен
      * derivedBy). Без списка участник — любой арендатор с такими классами.
@@ -118,10 +138,12 @@ export interface ProjectorReport {
     updated: number;
     deleted: number;
     unchanged: number;
-    /** Пачек, пропущенных из-за блокировки: проектор работает в другом процессе. */
+    /** Пачек, пропущенных из-за блокировки: проектор работает в другом процессе или строку держит чужая транзакция. */
     skipped: number;
     /** Перестроек. */
     rebuilds: number;
+    /** Арендаторы, чья запись упиралась в чужую блокировку строки дольше lockTimeout (по порядку, без повторов). */
+    locked: string[];
 }
 /** Выбывший арендатор: база отклонила запись его результатов. */
 export interface ProjectorFailure {
@@ -182,6 +204,9 @@ export declare class Projector {
     private readonly batch;
     private readonly pollMs;
     private readonly lockMs;
+    private readonly lockRetries;
+    /** Проходов подряд, в которых запись арендатора упиралась в lockTimeout (lockRetries). */
+    private readonly lockHits;
     private readonly only;
     constructor(env: ProjectorEnv, name: string, def: ProjectorOptions);
     /**
@@ -269,8 +294,13 @@ export declare class Projector {
     private ours;
     /** Смена класса без смены id, после которой строка вне семейства from арендатора, — возможно, уход из него (leaving). */
     private leaves;
-    /** Класс результата в арендаторе — из его семейства into. */
+    /**
+     * Входит ли класс `cls` в классы `into` проектора у арендатора `tenant` — сами эти классы или их потомки. Служебный
+     * метод: им `out` проверяет, что `handle` пишет только в эти классы.
+     */
     intoOf(tenant: string, cls: string): boolean;
+    /** Поля ключа класса into арендатора (пусто — класс без ключа). */
+    keyOf(tenant: string, cls: string): string[];
     /**
      * Ключ свёртки inc: класс и строка из одних полей ключа класса или одного $id; иначе null. Строку с другими полями
      * (данные, $tags, $owner) inc не складывает: её поля правят строку, и порядок таких правок важен.
@@ -312,6 +342,8 @@ export declare class Projector {
      * true }). true — работа ещё осталась.
      */
     private tenantWork;
+    /** Повторять fn, пока строку держит чужая транзакция дольше lockTimeout (55P03): пауза 20 мс, проход — в skipped. */
+    private untilFree;
     /** Ждать сигнал источников, остановку или запасной опрос. */
     private sleep;
 }

package/dist/project.js

@@ -50,7 +50,7 @@ function withFailed(meta, failed) {
         delete next.failed;
     return next;
 }
-const emptyReport = () => ({ batches: 0, changes: 0, created: 0, updated: 0, deleted: 0, unchanged: 0, skipped: 0, rebuilds: 0 });
+const emptyReport = () => ({ batches: 0, changes: 0, created: 0, updated: 0, deleted: 0, unchanged: 0, skipped: 0, rebuilds: 0, locked: [] });
 function change(row, cursor, rebuild = false) {
     return {
         cursor, id: row.id, class: row.class, tenant: row.tenant, op: rebuild ? 'create' : row.op, rev: row.rev, at: row.at,
@@ -67,6 +67,10 @@ function change(row, cursor, rebuild = false) {
  * значениями (22…) и пределами размера (54…). Сбой окружения (блокировки, отмена запроса, связь) — не причина
  * выводить арендатора: пачка откатывается целиком, повтор начнётся с того же курсора.
  */
+/** «1 прохода», «2 проходов», «21 прохода» — число проходов в родительном падеже («в течение …»). */
+function passesGen(n) {
+    return `${n} ${n % 10 === 1 && n % 100 !== 11 ? 'прохода' : 'проходов'}`;
+}
 /** Ожидание чужой блокировки строки дольше lock_timeout (55P03): сбой окружения, проход повторяется. */
 function lockWait(e) {
     return e?.code === '55P03';
@@ -161,17 +165,32 @@ class Out {
         if (key !== null)
             this.folds.set(key, d);
     }
+    /**
+     * Строка для delete и get. У класса с ключом её называют полями ключа: id такой строки — v5 от ключа, и по одному id
+     * (строкой или { $id }) база искала бы строку с пустым ключом — get отвечал бы null, а delete выводил арендатора с
+     * id_mismatch. Это ошибка кода handle, а не данных: invalid_data сразу, пачка откатывается целиком.
+     */
+    target(cls, tenant, keyOrId) {
+        const row = this.rowOf(keyOrId);
+        const key = this.p.keyOf(tenant, cls);
+        if (key.length && Object.keys(row).every((n) => n === '$id')) {
+            throw new LetopisError('invalid_data', `проектор ${this.p.name}: у класса ${cls} есть ключ (${key.join(', ')}) — строку называют полями ключа, например { ${key.map((k) => `${k}: …`).join(', ')} }, а не id`);
+        }
+        return row;
+    }
     delete(cls, keyOrId, opts) {
         const tenant = this.check(cls, opts?.tenant);
+        const row = this.target(cls, tenant, keyOrId);
         this.folds.clear();
-        this.ops.push({ op: 'delete', class: cls, tenant, row: this.rowOf(keyOrId) });
+        this.ops.push({ op: 'delete', class: cls, tenant, row });
     }
     async get(cls, keyOrId, opts) {
         const tenant = this.check(cls, opts?.tenant);
+        const row = this.target(cls, tenant, keyOrId);
         await this.flush();
         const S = this.p.env.S;
         const [r] = await this.db(() => this.q.unsafe(`select ${rowJson('e')} as row from ${S}.entity e
-      where e.id = ${S}.derived_id($1, $2::uuid, $3::text::jsonb) and e.class = $1 and e.tenant = $2::uuid`, [cls, tenant, JSON.stringify(this.rowOf(keyOrId))]));
+      where e.id = ${S}.derived_id($1, $2::uuid, $3::text::jsonb) and e.class = $1 and e.tenant = $2::uuid`, [cls, tenant, JSON.stringify(row)]));
         return r ? toRow(r.row) : null;
     }
     async flush() {
@@ -211,6 +230,9 @@ export class Projector {
     batch;
     pollMs;
     lockMs;
+    lockRetries;
+    /** Проходов подряд, в которых запись арендатора упиралась в lockTimeout (lockRetries). */
+    lockHits = new Map();
     only;
     constructor(env, name, def) {
         this.env = env;
@@ -238,6 +260,9 @@ export class Projector {
         this.lockMs = def.lockTimeout ?? 5000;
         if (!Number.isInteger(this.lockMs) || this.lockMs < 0)
             throw new LetopisError('invalid_data', `проектор ${name}: lockTimeout — целое число мс, 0 и больше`);
+        this.lockRetries = def.lockRetries ?? 0;
+        if (!Number.isInteger(this.lockRetries) || this.lockRetries < 0)
+            throw new LetopisError('invalid_data', `проектор ${name}: lockRetries — целое число, 0 и больше`);
         if (!Number.isInteger(this.batch) || this.batch < 1 || this.batch > 10_000)
             throw new LetopisError('invalid_data', `проектор ${name}: batch — от 1 до 10 000`);
         if (env.onSignal) {
@@ -338,14 +363,19 @@ export class Projector {
             const started = rep.rebuilds;
             for (;;) {
                 // занятая строка (lockTimeout) — как занятая блокировка проектора: подождать и повторить пачку
-                const r = await this.tenantChunk(rep, tenant).catch((e) => { if (lockWait(e))
-                    return 'busy'; throw e; });
+                const r = await this.tenantChunk(rep, tenant).catch((e) => {
+                    if (!lockWait(e))
+                        throw e;
+                    rep.skipped++;
+                    return 'busy';
+                });
                 if (r === 'busy')
                     await new Promise((res) => setTimeout(res, 20));
                 if (r !== 'done')
                     continue;
-                // ошибка данных арендатора — как у перестройки одной транзакцией: отказ, арендатор выбывший
-                const f = (await this.tx(async (q) => this.state(q))).failed?.[tenant];
+                // ошибка данных арендатора — как у перестройки одной транзакцией: отказ, арендатор выбывший; чекпоинт держит
+                // пачка run() другого процесса дольше lockTimeout — подождать
+                const f = (await this.untilFree(rep, () => this.tx(async (q) => this.state(q)))).failed?.[tenant];
                 if (f)
                     throw new LetopisError(f.code, f.message);
                 // последнюю пачку мог записать run() другого процесса (он продвигает начатые перестройки): перестройка этого
@@ -723,6 +753,27 @@ export class Projector {
             catch (e) {
                 // причина — первая ошибка базы группы (следом за ней база отвечает лишь «транзакция прервана»)
                 const cause = out.aborted ?? e;
+                // строку арендатора держит чужая транзакция дольше lockTimeout (хвост ревью доработок после 1.2.0): отчёт
+                // называет арендатора; с lockRetries после стольких проходов подряд он выбывает, и пачка идёт для остальных,
+                // иначе откатывается вся пачка и проход повторяется
+                if (failed && lockWait(cause)) {
+                    if (!rep.locked.includes(tenant))
+                        rep.locked.push(tenant);
+                    const hits = (this.lockHits.get(tenant) ?? 0) + 1;
+                    if (this.lockRetries === 0 || hits < this.lockRetries) {
+                        this.lockHits.set(tenant, hits);
+                        throw e;
+                    }
+                    this.lockHits.delete(tenant);
+                    await q.unsafe('rollback to savepoint letopis_projector');
+                    await q.unsafe('release savepoint letopis_projector');
+                    failed[tenant] = {
+                        cursor: list[0].cursor || start,
+                        code: '55P03',
+                        message: `проектор ${this.name}: строку арендатора ${tenant} держит чужая транзакция — в течение ${passesGen(hits)} подряд дольше lockTimeout`,
+                    };
+                    continue;
+                }
                 if (!failed || !out.owns(e) || !tenantFault(cause))
                     throw e;
                 await q.unsafe('rollback to savepoint letopis_projector');
@@ -737,6 +788,7 @@ export class Projector {
             }
             if (failed)
                 await q.unsafe('release savepoint letopis_projector');
+            this.lockHits.delete(tenant);
             rep.created += out.stats.created;
             rep.updated += out.stats.updated;
             rep.deleted += out.stats.deleted;
@@ -775,10 +827,17 @@ export class Projector {
         const sc = this.scopes.get(row.tenant);
         return sc !== undefined && !failed?.[row.tenant] && row.op === 'reclass' && !row.moved && !sc.from.has(row.class) && row.class !== '#reset';
     }
-    /** Класс результата в арендаторе — из его семейства into. */
+    /**
+     * Входит ли класс `cls` в классы `into` проектора у арендатора `tenant` — сами эти классы или их потомки. Служебный
+     * метод: им `out` проверяет, что `handle` пишет только в эти классы.
+     */
     intoOf(tenant, cls) {
         return this.scopes.get(tenant)?.into.has(cls) ?? false;
     }
+    /** Поля ключа класса into арендатора (пусто — класс без ключа). */
+    keyOf(tenant, cls) {
+        return this.scopes.get(tenant)?.keys.get(cls) ?? [];
+    }
     /**
      * Ключ свёртки inc: класс и строка из одних полей ключа класса или одного $id; иначе null. Строку с другими полями
      * (данные, $tags, $owner) inc не складывает: её поля правят строку, и порядок таких правок важен.
@@ -1002,6 +1061,9 @@ export class Projector {
      */
     async startTenant(rep, tenant, auto) {
         for (;;) {
+            // строку арендатора (его производные строки удаляются) держит чужая транзакция дольше lockTimeout — как занятая
+            // блокировка проектора: run() повторит на следующем проходе, rebuild() подождёт (хвост ревью доработок после 1.2.0:
+            // rebuild({ tenant, chunked: true }) отдавал сырую 55P03)
             const r = await this.tx(async (q) => {
                 if (!(await this.lock(q)))
                     return 'busy';
@@ -1033,6 +1095,12 @@ export class Projector {
                     delete next.resync;
                 await this.advance(q, meta.cursor, withFailed(next, failed));
                 return 'ok';
+            }).catch((e) => {
+                if (!lockWait(e))
+                    throw e;
+                if (!auto)
+                    rep.skipped++;
+                return 'busy';
             });
             if (r !== 'busy' || auto) {
                 if (r === 'busy')
@@ -1127,6 +1195,20 @@ export class Projector {
         this.tenantsPending = more;
         return more;
     }
+    /** Повторять fn, пока строку держит чужая транзакция дольше lockTimeout (55P03): пауза 20 мс, проход — в skipped. */
+    async untilFree(rep, fn) {
+        for (;;) {
+            try {
+                return await fn();
+            }
+            catch (e) {
+                if (!lockWait(e))
+                    throw e;
+                rep.skipped++;
+            }
+            await new Promise((res) => setTimeout(res, 20));
+        }
+    }
     /** Ждать сигнал источников, остановку или запасной опрос. */
     sleep() {
         return new Promise((resolve) => {

package/dist/registry.d.ts

@@ -68,7 +68,10 @@ export declare class Registry {
     all(): ClassInfo[];
     /** Класс и все его потомки (семейство). */
     family(name: string): ClassInfo[];
-    /** Тип листа по пути полей класса: по JSON Schema (type и format). */
+    /**
+     * Тип листа — поля в конце пути `path` — у класса `cls`, по его JSON Schema (`type` и `format`). По этому типу
+     * библиотека сравнивает значения поля в фильтрах, сортировке и итогах.
+     */
     leafType(cls: string, path: readonly string[]): LeafType;
 }
 export {};

package/dist/registry.js

@@ -70,7 +70,10 @@ export class Registry {
         const root = this.resolve(name).name;
         return this.all().filter((c) => c.ancestors.includes(root));
     }
-    /** Тип листа по пути полей класса: по JSON Schema (type и format). */
+    /**
+     * Тип листа — поля в конце пути `path` — у класса `cls`, по его JSON Schema (`type` и `format`). По этому типу
+     * библиотека сравнивает значения поля в фильтрах, сортировке и итогах.
+     */
     leafType(cls, path) {
         let node = this.resolve(cls).schema;
         for (const p of path) {

package/dist/sql.d.ts

@@ -62,7 +62,10 @@ export interface Hop {
  *    хаб → связь — назад; связь → хаб и хаб → хаб — вперёд; нет нужного — другое направление.
  */
 export declare function resolveHop(reg: Registry, prev: Step, next: Step): Hop;
-/** Курсор keyset-пагинации из последней строки страницы. */
+/**
+ * Курсор постраничного вывода для `after()`: `{ v, id }` — значение поля сортировки и id последней строки страницы.
+ * Поле — то же, что в `sort()`; если его нет в данных строки, `v` — `null`.
+ */
 export declare function cursorOf(row: Row, field: string): Cursor;
 export interface BuildOptions {
     /**

package/dist/sql.js

@@ -422,7 +422,10 @@ function cursorParams(c, sort) {
     }
     return { v: value, id };
 }
-/** Курсор keyset-пагинации из последней строки страницы. */
+/**
+ * Курсор постраничного вывода для `after()`: `{ v, id }` — значение поля сортировки и id последней строки страницы.
+ * Поле — то же, что в `sort()`; если его нет в данных строки, `v` — `null`.
+ */
 export function cursorOf(row, field) {
     const f = field === 'updated' ? 'at' : field;
     if (f === 'at' || f === 'rev' || f === 'id')
@@ -609,10 +612,13 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
                     + `where (v.op = 'delete') = ${isDead} and v.op not in ('purge', 'trim', 'reset')${dataCond('v')}${endsCond(`${S}.link_ids(v.links)`)}${rolesCond('v', 's.src')})`;
             };
             ctes.push(`p${i}a as (select q.src, q.id, q.rev from ${hopCall(atPh, false)} q)`);
-            parts.push(cur ? entityByIds(`select q.id from p${i}a q`) : logPart(`select q.id, q.rev from p${i}a q`));
+            // пары переходов — по одной на (источник, цель): объект, который ссылается на несколько объектов прошлого шага,
+            // встречается в них несколько раз; строка узла — одна на id, иначе rows(), count() и агрегаты его удваивали
+            // (entityByIds повторы отбрасывает сам, срез asOf() и надгробия withDeleted() — через distinct здесь)
+            parts.push(cur ? entityByIds(`select q.id from p${i}a q`) : logPart(`select distinct q.id, q.rev from p${i}a q`));
             if (dead) {
                 ctes.push(`p${i}d as (select q.src, q.id, q.rev from ${hopCall(atPh, true)} q)`);
-                parts.push(logPart(`select q.id, q.rev from p${i}d q`));
+                parts.push(logPart(`select distinct q.id, q.rev from p${i}d q`));
                 ctes.push(`p${i} as (select src, id from p${i}a union all select src, id from p${i}d)`);
             }
             else {
@@ -728,7 +734,9 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
             }
             else {
                 const cast = agg.fn === 'sum' || agg.fn === 'avg' ? '::numeric' : CAST[aggLeaf];
-                text = `${withClause}select ${agg.fn}((${acc})${cast}) as v from ${ents} z`;
+                // у boolean в PostgreSQL нет min и max; false меньше true: наименьшее — «все ли true», наибольшее — «есть ли true»
+                const fn = aggLeaf === 'boolean' && agg.fn === 'min' ? 'bool_and' : aggLeaf === 'boolean' && agg.fn === 'max' ? 'bool_or' : agg.fn;
+                text = `${withClause}select ${fn}((${acc})${cast}) as v from ${ents} z`;
             }
             break;
         }