letopis 1.2.0 → 1.4.0

package/README.md

@@ -1,4 +1,4 @@
-# letopis 1.2
+# letopis 1.4
 
 **letopis** — библиотека для Node.js, хранилище версионированных сущностей на PostgreSQL 18. Каждое изменение
 сохраняется версией в журнале. Поэтому у любого объекта есть история, состояние на любую дату и подписка на
@@ -362,12 +362,23 @@ const adm = await connect({ dsn: ADMIN, schema: r.schema, token: r.tenant!.token
 получит `upgrade: true`. `up({ dsn, schema, upgrade: true })` применяет миграции из `sql/migrate/` и повторно
 накатывает функции; данные сохраняются.
 
+Ревизия меняется не с каждой версией: у 1.1–1.4 она одна, а функции разные. Поэтому `up()` пишет в комментарий схемы
+ещё и штамп движка: версию пакета и хэш его файлов SQL. Если штамп не совпадает с файлами пакета, `connect()`
+предупреждает. Когда схему накатила более старая версия (или версия до 1.4, у которой штампа нет), он советует
+`up({ schema })`. Когда схему уже обновила более новая версия, он советует обновить пакет: `up()` старой версией вернул
+бы прежние функции. Новая версия пакета без правок SQL штамп не меняет, и предупреждения нет.
+
 Первый `up()` после перехода на 1.2 строит индекс журнала `log_class_tenant_at (class, tenant, at)` вместо
 `log_class_at`: срез `asOf` и `withDeleted` по классу больше не читает журнал других арендаторов с тем же именем
 класса. Пока индекс строится, запись в журнал ждёт. На большой установке постройте его заранее, не останавливая
 записи: `create index concurrently log_class_tenant_at on "v2.<схема>".log (class, tenant, at)` от роли владельца, —
 тогда `up()` только снимет прежний.
 
+Обновление схем 1.1.0 и 1.0.1 проверяет тест `upgrade`. Схему ставит прежний пакет, данные пишет прежний движок, затем
+вызывается `up()` текущей версии. После него версии и хэши прежнего движка на месте, `verify({ data: true })` чист, а
+каталог схемы совпадает с чистой установкой. Схема 1.1.0 обновляется простым `up()`: ревизия у неё та же. Схема 1.0.1
+обновляется через `up({ upgrade: true })`.
+
 ### Разработка без PostgreSQL: PGlite
 
 `up({ pglite: true })` поднимает PGlite (PostgreSQL 18 на WebAssembly) с pgcrypto и сокетом на свободном порту.
@@ -544,11 +555,19 @@ const Movement = link('Movement', { amount: z.number().int() }, { ends: { Wallet
   достаточно права на запись в источник.
 - Описание проверяет база (`invalid_class`): поле есть в схеме, оно числовое и не входит в ключ; конец `via` —
   одиночный и принимает класс цели; поле `sum` — число; агрегаты не образуют цикл; цель и источник — не системные и
-  не производные классы. Источник, описанный позже цели, сверяется при появлении.
+  не производные классы. Класс-источник описывают раньше агрегата: агрегат над классом, которого ещё нет, отклоняется.
+  У класса арендатора источник ищут среди классов арендатора. `syncModels` сам описывает источники раньше целей, а
+  модели по кругу (агрегат над собственным потомком, цикл агрегатов) отклоняет до записи (`invalid_class` с кругом).
+  Класс `of` не удаляется, пока его называет агрегат класса того же арендатора: сначала агрегат убирают из описания цели.
 - Строки попадают в агрегат только с ведома того, кто читает их все: поле считает и строки, которые автору не видны.
   Описать или изменить агрегат может только тот, кто без условий читает все строки источника и его потомков. Сделать
-  класс источником (новый класс, смена `parent`, источник после цели) может только тот, кто без условий читает все
+  класс источником (новый потомок источника, смена `parent`) может только тот, кто без условий читает все
   строки этого класса и его потомков — и до правки, и после. Иначе `acl_denied`.
+- Новый источник проверяется и по тому, кто описал агрегат: он тоже должен без условий читать все строки класса.
+  Описавший — автор версии строки `Class` цели, с которой описание агрегата стало нынешним. Если он их не читает, класс
+  источником не станет (`acl_denied`), пока агрегат не опишет заново тот, кто читает. У агрегата класса System
+  описавший проверяется по классам System, как и при описании. Класс арендатора под агрегатом System проверяется
+  только у того, кто его заводит.
 - Опция наследуется, потомок заменяет её целиком. Добавить или изменить агрегат — ужесточение: запись в цель и в
   источники ждёт, пока поле пересчитывается у всех строк.
 - `db.rebuildAggregates(класс)` пересчитывает поле из текущих строк — для ремонта. Версия пишется только там, где
@@ -955,7 +974,8 @@ await db.Customer(temp).purge({ confirm: true }).rows()        // история
 версии 1 остаётся запись `purge` с числом стёртых версий. История системных классов не стирается. Пока проектор,
 чьи источники `from` включают класс объекта ([«Проекторы»](#проекторы)), не прочёл удаление, `purge` отказывает
 (`projector_pending`): стёртое надгробие проектор не увидел бы, и вклад объекта остался бы в итогах. Удаление и
-`purge` одной транзакцией в таком классе поэтому не проходят. Удалить аккаунт — `db.auth.purgeAccount`
+`purge` одной транзакцией в таком классе поэтому не проходят. Так же `db.trimHistory` отказывает, пока проектор не
+прочёл первую оставшуюся версию: прошлую версию для `before` он бы уже не нашёл. Удалить аккаунт — `db.auth.purgeAccount`
 ([раздел 10](#10-пользователи-вход-и-права)).
 
 ## 8. Транзакции, батчи и деньги
@@ -1423,15 +1443,21 @@ await anna.auth.switch(SHOP)               // арендатор сессии
 для одного класса, действовало бы и на строки другого. Нарушение — `invalid_class`.
 
 По тем же именам правила находят и старые версии строк в журнале. Поэтому класс удаляется, только когда у него нет
-строк, потомков и истории строк: историю удалённых строк сначала стирает `purge()`. Класс, удалённый с историей
-раньше, создаётся заново только с прежними `parent`, `alias` и `derivedBy` — иначе `invalid_class`: старые версии его
-строк попали бы под чужие правила. Если журнал хранит строки класса с этим именем, но не его надгробие (например,
-строки класса System, удалённого в 1.1), класс с этим именем не создаётся, пока историю не сотрёт `purge()`.
+строк, потомков и истории строк: историю удалённых строк сначала стирает `purge()`. Для класса System не в счёт
+строки, потомки и история арендатора, у которого есть свой класс с тем же именем: они относятся к его классу. Класс,
+удалённый с историей раньше, создаётся заново только с прежними `parent`, `alias`, `derivedBy` и `history` — иначе
+`invalid_class`: старые версии его строк попали бы под чужие правила или другое прореживание. Правила находят старые
+версии и по алиасам предков. Поэтому, пока удалённые потомки класса хранят историю строк, класс не меняет алиас
+(`invalid_class`), а удалённым создаётся заново только с прежним описанием. Если журнал хранит строки класса с этим
+именем, но не его надгробие (например, строки класса System, удалённого в 1.1), класс с этим именем не создаётся, пока
+историю не сотрёт `purge()`.
 
 Производный класс (`derivedBy`) заводит, меняет и удаляет только администратор: администраторское подключение или
 аккаунт с правом System `letopis.projector` (у системного администратора оно есть по маске `letopis.*`). Проектор
 пишет в такой класс итоги по всем строкам источников арендатора, без прав чтения, поэтому пользователь, заведя его
-сам, читал бы итоги по строкам, которые ему читать запрещено.
+сам, читал бы итоги по строкам, которые ему читать запрещено. Класс, у которого есть производные потомки, тоже
+правит только администратор: правка предка меняет описание потомка (поля, ключ, `history`). Пометку `aggregatedBy`
+(класс стал источником агрегата) база ставит и производному классу сама: полей и ключа она не меняет.
 
 ### Выдать право
 
@@ -1656,7 +1682,9 @@ for await (const ev of sub) {             // ev: { cursor, row, id, class, op, r
   запись после него в поток придёт. Пример выше читает с `'start'`.
 - Вызовы `sub.next()` идут по очереди: параллельные получают разные события. Вызов, брошенный по таймауту
   (`Promise.race`), всё равно получит своё событие — держите его обещание и ждите его снова.
-- `classes` — только эти классы с потомками; `pollMs` — запасной опрос (1000 мс).
+- `classes` — только эти классы с потомками; `pollMs` — запасной опрос (1000 мс). Строка, ушедшая из этих классов
+  сменой класса без смены id, приходит событием удаления в прежнем классе (`op: 'delete'`, `row` — прежняя версия с
+  `$deleted`), даже если новый класс подписчику не виден. Событие приходит, если прежнюю версию подписчик видел.
 - События идут без потерь и повторов, под правами читателя, в порядке номеров транзакций, а внутри транзакции — в
   порядке записи. Это не порядок фиксации: версии одного объекта сверяйте по `rev`.
 - Долгая пишущая транзакция в любой базе кластера задерживает поток: `await sub.lag()` показывает отставание в мс.
@@ -1772,7 +1800,8 @@ sales.close()                                    // stop() после текущ
   пачками, каждая своей транзакцией со своим снимком, пока хвост журнала идёт для всех: изменения арендатора выше
   последней пачки хвост пропускает (их прочтёт пачка), в пройденной — если транзакция видна в её снимке. Производные
   строки арендатора удаляются сразу и до конца перестройки неполны (`status().rebuildingTenants`); блокировку,
-  занятую `run()` другого процесса, перестройка пережидает.
+  занятую `run()` другого процесса, перестройка пережидает. Прерванную перестройку (процесс остановился) продолжает
+  `run()` любого процесса — с `onExpired` и без него.
 - `status().state` описывает проекцию в базе, а не процесс: `'new'` — проекции ещё нет, её построит первый `run()`
   или `rebuild()`; `'running'` — проекция построена и ведётся по журналу (это не значит, что какой-то процесс сейчас
   выполняет `run()`); `'rebuilding'` — идёт или прервана перестройка пачками.
@@ -1798,6 +1827,15 @@ sales.close()                                    // stop() после текущ
   его производных строк проектор не строит. Включите журнал класса и перестройте арендатора `rebuild({ tenant })`.
 - `batch` — сколько изменений в пачке (500), `pollMs` — запасной опрос (1000 мс): сигналы источников будят
   проектор раньше.
+- `lockTimeout` — сколько транзакция проектора ждёт чужую блокировку строки (5000 мс; 0 — без предела). Транзакция
+  любого арендатора, которая держит строку итога или цель конца, иначе держала бы пачку всех арендаторов. Дольше —
+  пачка откатывается, курсор остаётся, `run()` не отклоняется, а пропускает проход (`skipped`) и повторяет его. Отчёт
+  называет арендатора, на чьей строке встала пачка (`locked`). `rebuild({ tenant, chunked: true })` такую блокировку
+  пережидает.
+- `lockRetries` — сколько проходов подряд запись одного арендатора может упираться в `lockTimeout`, прежде чем он
+  выбудет (по умолчанию 0 — не выбывает). Выбывший получает код `55P03`, и пачка идёт для остальных; его изменения
+  пропускаются до `rebuild({ tenant })`. Счёт ведёт процесс, удачная запись арендатора его сбрасывает. Учтите: долгая
+  исключительная блокировка семейства класса System (ужесточение описания) упрётся в каждого арендатора по очереди.
 - Каждая правка, которую `out` отправляет в базу, — отдельная правка строки, и скорость проектора задаёт число
   правок, а не число изменений. Свёртка `inc` сводит правки строки к одной за пачку, поэтому handle из примера выше
   (`out.inc` на каждое изменение) на машине замеров догонял 6 тысяч изменений в секунду при `batch` 500 и 33 тысячи
@@ -2238,12 +2276,12 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 
 | Член | Что делает |
 |---|---|
-| опции `ProjectorOptions` | `from`, `into` — классы с потомками; `version` — целое от 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` — пачками); `batch` — изменений в пачке (500, от 1 до 10 000); `pollMs` — запасной опрос (1000 мс); `tenants` — id арендаторов-участников |
+| опции `ProjectorOptions` | `from`, `into` — классы с потомками; `version` — целое от 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` — пачками); `batch` — изменений в пачке (500, от 1 до 10 000); `pollMs` — запасной опрос (1000 мс); `lockTimeout` — ожидание чужой блокировки строки (5000 мс, 0 — без предела); `lockRetries` — проходов подряд до выбывания арендатора с чужой блокировкой (0 — не выбывает); `tenants` — id арендаторов-участников |
 | `run({ once })` | догнать журнал (`once`) или следовать за ним до `stop()` → `ProjectorReport` |
 | `rebuild({ chunked, tenant })` | перестроить с текущего состояния: атомарно, пачками или одного арендатора → `ProjectorReport` |
 | `status()` | → `ProjectorStatus`: `{ name, state, version, cursor, at, lag, failed, rebuildingTenants }`; `failed` — `{ [id арендатора]: ProjectorFailure }`, где `ProjectorFailure` — `{ cursor, code, message }` |
 | `stop()`, `close()` | остановить `run()` после текущей пачки; то же и отписаться от сигналов |
-| `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds }` |
+| `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds, locked }` |
 | `ProjectorChange` | `{ cursor, id, class, tenant, op, rev, at, author, row }` и, если есть, `agent`, `reason`, `moved`, `before`, `rebuild` |
 | `ProjectorOut` | `upsert(класс, строка, { tenant })`, `inc(класс, строка, приращения, { tenant })`, `delete(класс, ключ или id, { tenant })`, `get(класс, ключ или id, { tenant })` → `Row \| null`; строка — `ProjectorRow` в формате загрузчика |
 
@@ -2304,7 +2342,7 @@ npx letopis import --from postgres://…/old --from-schema v1.salon --dsn postgr
 | `confirm_mismatch` | LT020 | подтверждение сброса не совпадает с именем схемы |
 | `derived_class` | LT021 | строку производного класса (`derivedBy`) пишет, правит или удаляет не его проектор; конец ведёт на такую строку или на производный класс; проектор пишет в класс вне своих `into` или не нашёл ни одного арендатора, у которого все классы `into` помечены его `derivedBy` |
 | `aggregate_field` | LT022 | приложение передало или изменило агрегатное поле (`aggregate`): его считает база |
-| `projector_pending` | LT023 | `purge` удалённого объекта, чьё удаление ещё не прочёл проектор его класса: сначала `run()` проектора |
+| `projector_pending` | LT023 | `purge` удалённого объекта, чьё удаление ещё не прочёл проектор его класса, или `trimHistory`, чью первую оставшуюся версию он ещё не прочёл: сначала `run()` проектора |
 
 Коды библиотеки:
 
@@ -2388,7 +2426,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 
 ## 18. Ограничения
 
-Здесь собрано то, что letopis 1.2 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
+Здесь собрано то, что letopis 1.4 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
 
 **Платформа**
 
@@ -2468,8 +2506,9 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 - Счётчики попыток OTP и TOTP откатываются вместе с транзакцией вызывающего: частоту попыток ограничивает сервис.
 - Самостоятельная привязка занятого идентификатора отвечает `acl_denied` — пользователь с недавним входом так
   узнаёт, что идентификатор занят. Изменения прав во всех арендаторах упорядочены одной строкой счётчика.
-- Число невидимых строк, мешающих удалению или смене класса (`reclass_denied`), и существование аккаунта по id (как
-  цели ссылки) не скрываются.
+- Тексты отказов называют класс, роль и id ссылающейся строки, только если актор её видит: каскад удаления, снятие
+  конца, перевод ссылок при смене класса и ключа, конфликт смены `parent` (`tightening_conflict`). Число невидимых строк, мешающих удалению или смене класса
+  (`reclass_denied`), и существование аккаунта по id (как цели ссылки) не скрываются.
 - Ужесточение описания класса и `rekeyClass` проверяют все строки семейства, поэтому требуют права `READ` без условий
   на все строки класса и его потомков: иначе пробное ужесточение (`maximum`, `enum`, `pattern`) отвечало бы числом
   невидимых строк, которые ему не соответствуют. Системный администратор, ужесточая класс System, получает число
@@ -2547,6 +2586,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 - `purge()` ждёт проекторов: пока проектор, чьи источники включают класс объекта, а у арендатора объекта есть его
   производный класс, не прочёл удаление, `purge` отвечает `projector_pending`. Проектор, который больше не запускают,
   держит `purge` своих источников, пока у арендатора есть его производные классы: запустите его или удалите их.
+  Так же ждёт `trimHistory`: пока проектор не прочёл первую оставшуюся версию, обрезка отвечает `projector_pending`.
 
 **Агрегаты в базе**
 
@@ -2613,7 +2653,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 # hash — цепочка хэшей версий, подмена и разрыв журнала, verify() (этап 1)
 # harness — тестовая обвязка: подъём базы, схема на файл, две строки подключения (этап 0)
 # jsonschema — компиляция JSON Schema в jsonpath и проверка данных в базе (этап 1)
-# impersonation — имперсонация: letopis.account только для сервиса с правом, запреты целей, author и agent в журнале, sessionFor; реестр db.as() — один на арендатора, не пустеет, перечитывается по сигналу своего арендатора (этап 5; доработки после точки Б)
+# impersonation — имперсонация: letopis.account только для сервиса с правом, запреты целей, author и agent в журнале, sessionFor; реестр db.as() — один на арендатора, не пустеет, перечитывается по сигналу своего арендатора (этап 5; доработки после точки Б); реестр фасада не общий с корнем, пустой реестр не кэшируется (хвост ревью безопасности №3)
 # install — установщик и роли: повторная установка, две установки в базе, три таблицы (этап 1)
 # member — членство: работа в арендаторе по ролям, auth.switch, выход с переходом владения, системные строки, роли арендатора без прав System (этап 5)
 # model — модели на Zod, нормализатор JSON Schema, перевод шаблонов, совпадение с метасхемой базы (этап 2)
@@ -2637,6 +2677,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 # cache — кэш результатов: попадание, свои и чужие записи, ключ с пользователем, права, погашенные сессии, обрыв слушателя, ttl, пометка класса, без LISTEN, гонка, db.sql, предел счётчиков сигналов (этап 6; план 1.1, точка А)
 # maintain — обслуживание: истёкшие сессии и коды, права, один процесс под блокировкой, расписание (этап 6)
 # up — полный установщик: свежая установка, повторный накат, свои сиды, автосоздание базы, UTF8, версия 17, upgrade с миграциями, PGlite, первый арендатор и пользователь (up({ tenant }), createTenant) (этапы 6, 8)
+# upgrade — обновление схемы с 1.1.0 (повторный накат) и с 1.0.1 (upgrade: true, миграция 0006) пакетами letopis-11 и letopis-1: версии и хэши прежнего движка, verify(), каталог против чистой установки, строки-замки, приложение, подписка и проектор по старым данным, повторный up() (доработки после 1.2.0, этап 1)
 # scenario-salon — сквозной сценарий салона: 21 акт 0.21 (salon) с матрицей покрытия API 1.0 (этап 6)
 # telemetry — onQuery и slowMs, describe() и метаданные классов с наследованием, describeText (этап 6)
 # history — diff и blame по журналу, причина изменения у глаголов, db.begin() и батча; версия, скрытая условием ACL, колонка changed, пропуск версии, row_changes на 20 тыс. целей (план 1.1, этап 1 и точка А)

package/dist/index.js

@@ -24,6 +24,7 @@ import { Subscription } from './watch.js';
 import { Projector } from './project.js';
 import { SIGNAL_MODES, Signals, bucket, throttle } from './signals.js';
 import { describe as describeModel, maintain as runMaintain, rebuildAggregates as runRebuildAggregates, rekeyClass as runRekeyClass, reset as runReset, scheduleMaintain, trimHistory as runTrim, verify as runVerify, } from './admin.js';
+import { stampDrift } from './up.js';
 export { DDL_REVISION } from './types.js';
 export { uuidv5, v5Name, v5Id, idOf } from './uuid.js';
 export { LetopisError, ValidationError, fromDbError } from './errors.js';
@@ -142,12 +143,22 @@ function makeDb(sh, scope, exec, owner, tx) {
             }
             // имперсонация и арендатор проверяются базой сразу: ошибка — здесь, а не на первой цепочке
             const scoped = { ...txc, account: id ?? txc.account, tenant: o?.tenant ?? (id === undefined ? txc.tenant : undefined) };
-            const [r] = await runTx(scoped, (q) => q.unsafe(`select account, tenant from ${sh.S}.ctx()`), { read: true });
+            let [r] = await runTx(scoped, (q) => q.unsafe(`select account, tenant from ${sh.S}.ctx()`), { read: true });
             if (!r?.account)
                 throw new LetopisError('no_session', 'db.as(): нет действующей сессии');
-            const tenant = r.tenant;
-            const registry = await sh.registryFor(tenant, scoped);
-            return makeDb(sh, { txc: scoped, tenant: () => tenant, registry: () => registry, root: false }, poolExecutor(scoped), nextOwner);
+            // контекст сессии между запросами ушёл из арендатора (сменился или кончился): реестр не загружен и не
+            // кэширован (хвост ревью безопасности №3) — контекст читается заново, не больше трёх раз
+            for (let attempt = 1;; attempt++) {
+                const tenant = r.tenant;
+                const registry = await sh.registryFor(tenant, scoped);
+                if (registry)
+                    return makeDb(sh, { txc: scoped, tenant: () => tenant, registry: () => registry, root: false }, poolExecutor(scoped), nextOwner);
+                if (attempt === 3)
+                    throw new LetopisError('no_session', 'db.as(): контекст сессии меняется — реестр арендатора не загружен');
+                [r] = await runTx(scoped, (q) => q.unsafe(`select account, tenant from ${sh.S}.ctx()`), { read: true });
+                if (!r?.account)
+                    throw new LetopisError('no_session', 'db.as(): нет действующей сессии');
+            }
         },
         begin: async (o) => {
             if (tx)
@@ -257,6 +268,12 @@ export async function connect(opts) {
             throw new LetopisError('invalid_data', `connect: схемы ${opts.schema} нет — установите её: up({ schema })`);
         if (rev < DDL_REVISION)
             console.warn(`letopis: движок схемы ${opts.schema} ревизии ${rev}, библиотека ждёт ${DDL_REVISION} — обновите: up({ schema: '${opts.schema}', upgrade: true })`);
+        else if (rev === DDL_REVISION) {
+            // ревизия та же, а функции схемы ставила другая версия движка — штамп в комментарии схемы (99-revision.sql)
+            const drift = await stampDrift(opts.schema, String(rv.c ?? ''));
+            if (drift)
+                console.warn(drift);
+        }
         // режим сигналов установки (план 1.1, §2.2); схема, накатанная до него (нет signal_mode()), — class
         const [sm] = await sql.unsafe(`select ${S}.signal_mode() as m`).catch((e) => {
             if (e.code === '42883')
@@ -315,9 +332,9 @@ export async function connect(opts) {
             }
             tokens();
         };
+        // фасад db.as() не делит реестр с корнем, даже в том же арендаторе: корень после auth.switch() перечитывает свой
+        // реестр классами нового арендатора (хвост ревью безопасности №3)
         const registryFor = async (tenant, txc) => {
-            if (tenant === root.tenant)
-                return root.registry;
             const known = others.get(tenant);
             if (known) {
                 known.txc = txc;
@@ -327,8 +344,11 @@ export async function connect(opts) {
             let pending = loading.get(tenant);
             if (!pending) {
                 pending = (async () => {
+                    const rows = await loadClasses(txc, tenant);
+                    if (!rows)
+                        return null;
                     const registry = new Registry();
-                    registry.load(((await loadClasses(txc, tenant)) ?? []));
+                    registry.load(rows);
                     others.set(tenant, { registry, txc });
                     tokens();
                     return registry;

package/dist/project.d.ts

@@ -98,6 +98,17 @@ export interface ProjectorOptions {
     batch?: number;
     /** Запасной опрос журнала, мс (по умолчанию 1000; сигналы источников будят раньше). */
     pollMs?: number;
+    /**
+     * Сколько транзакция проектора ждёт чужую блокировку строки, мс (по умолчанию 5000; 0 — без предела). Дольше —
+     * пачка откатывается, курсор остаётся, run() не отклоняется, а пропускает проход и повторяет его.
+     */
+    lockTimeout?: number;
+    /**
+     * Сколько проходов подряд запись одного арендатора может упираться в lockTimeout, прежде чем он выбудет (код 55P03,
+     * дальше — rebuild({ tenant })), а пачка пойдёт для остальных; по умолчанию 0 — не выбывает, проход повторяется для всех.
+     * Счёт — в процессе, удачная запись арендатора его сбрасывает.
+     */
+    lockRetries?: number;
     /**
      * Явный список арендаторов проектора: участники — только они (и только те, у кого каждый класс into помечен
      * derivedBy). Без списка участник — любой арендатор с такими классами.
@@ -113,10 +124,12 @@ export interface ProjectorReport {
     updated: number;
     deleted: number;
     unchanged: number;
-    /** Пачек, пропущенных из-за блокировки: проектор работает в другом процессе. */
+    /** Пачек, пропущенных из-за блокировки: проектор работает в другом процессе или строку держит чужая транзакция. */
     skipped: number;
     /** Перестроек. */
     rebuilds: number;
+    /** Арендаторы, чья запись упиралась в чужую блокировку строки дольше lockTimeout (по порядку, без повторов). */
+    locked: string[];
 }
 /** Выбывший арендатор: база отклонила запись его результатов. */
 export interface ProjectorFailure {
@@ -168,12 +181,18 @@ export declare class Projector {
     /** Источники арендатора без журнала (history: false): их изменений проектор не увидит — арендатор выбывает. */
     private blind;
     private stale;
+    /** В чекпоинте есть начатая перестройка арендатора пачками (по последней пачке; до первой — проверить). */
+    private tenantsPending;
     private running;
     private stopped;
     private wake;
     private off;
     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);
     /**
@@ -299,10 +318,13 @@ export declare class Projector {
      */
     private tenantChunk;
     /**
-     * Автоматическая перестройка выбывших по cursor_expired (onExpired: 'rebuild') — проход run(): начинает перестройку
-     * пачками у каждого такого арендатора и продвигает начатые на пачку. true — работа ещё осталась.
+     * Перестройка арендаторов пачками — проход run(): с start (onExpired: 'rebuild') начинает её у каждого выбывшего по
+     * cursor_expired, затем продвигает на пачку каждую начатую — автоматическую и прерванную rebuild({ tenant, chunked:
+     * true }). true — работа ещё осталась.
      */
     private tenantWork;
+    /** Повторять fn, пока строку держит чужая транзакция дольше lockTimeout (55P03): пауза 20 мс, проход — в skipped. */
+    private untilFree;
     /** Ждать сигнал источников, остановку или запасной опрос. */
     private sleep;
 }