letopis 1.2.0 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# letopis 1.2
+# letopis 1.3
 
 **letopis** — библиотека для Node.js, хранилище версионированных сущностей на PostgreSQL 18. Каждое изменение
 сохраняется версией в журнале. Поэтому у любого объекта есть история, состояние на любую дату и подписка на
@@ -368,6 +368,11 @@ const adm = await connect({ dsn: ADMIN, schema: r.schema, token: r.tenant!.token
 записи: `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,10 +549,12 @@ const Movement = link('Movement', { amount: z.number().int() }, { ends: { Wallet
   достаточно права на запись в источник.
 - Описание проверяет база (`invalid_class`): поле есть в схеме, оно числовое и не входит в ключ; конец `via` —
   одиночный и принимает класс цели; поле `sum` — число; агрегаты не образуют цикл; цель и источник — не системные и
-  не производные классы. Источник, описанный позже цели, сверяется при появлении.
+  не производные классы. Класс-источник описывают раньше агрегата: агрегат над классом, которого ещё нет, отклоняется.
+  У класса арендатора источник ищут среди классов арендатора. `syncModels` сам описывает источники раньше целей.
+  Класс `of` не удаляется, пока его называет агрегат класса того же арендатора: сначала агрегат убирают из описания цели.
 - Строки попадают в агрегат только с ведома того, кто читает их все: поле считает и строки, которые автору не видны.
   Описать или изменить агрегат может только тот, кто без условий читает все строки источника и его потомков. Сделать
-  класс источником (новый класс, смена `parent`, источник после цели) может только тот, кто без условий читает все
+  класс источником (новый потомок источника, смена `parent`) может только тот, кто без условий читает все
   строки этого класса и его потомков — и до правки, и после. Иначе `acl_denied`.
 - Опция наследуется, потомок заменяет её целиком. Добавить или изменить агрегат — ужесточение: запись в цель и в
   источники ждёт, пока поле пересчитывается у всех строк.
@@ -955,7 +962,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 +1431,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 +1670,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 +1788,8 @@ sales.close()                                    // stop() после текущ
   пачками, каждая своей транзакцией со своим снимком, пока хвост журнала идёт для всех: изменения арендатора выше
   последней пачки хвост пропускает (их прочтёт пачка), в пройденной — если транзакция видна в её снимке. Производные
   строки арендатора удаляются сразу и до конца перестройки неполны (`status().rebuildingTenants`); блокировку,
-  занятую `run()` другого процесса, перестройка пережидает.
+  занятую `run()` другого процесса, перестройка пережидает. Прерванную перестройку (процесс остановился) продолжает
+  `run()` любого процесса — с `onExpired` и без него.
 - `status().state` описывает проекцию в базе, а не процесс: `'new'` — проекции ещё нет, её построит первый `run()`
   или `rebuild()`; `'running'` — проекция построена и ведётся по журналу (это не значит, что какой-то процесс сейчас
   выполняет `run()`); `'rebuilding'` — идёт или прервана перестройка пачками.
@@ -1798,6 +1815,9 @@ sales.close()                                    // stop() после текущ
   его производных строк проектор не строит. Включите журнал класса и перестройте арендатора `rebuild({ tenant })`.
 - `batch` — сколько изменений в пачке (500), `pollMs` — запасной опрос (1000 мс): сигналы источников будят
   проектор раньше.
+- `lockTimeout` — сколько транзакция проектора ждёт чужую блокировку строки (5000 мс; 0 — без предела). Транзакция
+  любого арендатора, которая держит строку итога или цель конца, иначе держала бы пачку всех арендаторов. Дольше —
+  пачка откатывается, курсор остаётся, `run()` не отклоняется, а пропускает проход (`skipped`) и повторяет его.
 - Каждая правка, которую `out` отправляет в базу, — отдельная правка строки, и скорость проектора задаёт число
   правок, а не число изменений. Свёртка `inc` сводит правки строки к одной за пачку, поэтому handle из примера выше
   (`out.inc` на каждое изменение) на машине замеров догонял 6 тысяч изменений в секунду при `batch` 500 и 33 тысячи
@@ -2238,7 +2258,7 @@ 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 — без предела); `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 }` |
@@ -2304,7 +2324,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 +2408,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 
 ## 18. Ограничения
 
-Здесь собрано то, что letopis 1.2 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
+Здесь собрано то, что letopis 1.3 сознательно не делает или делает с оговорками, и где за поведением нужно следить.
 
 **Платформа**
 
@@ -2468,8 +2488,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 +2568,7 @@ p50 — от −0,28 до +0,21 мс. Бенч против 1.0.1 (`bench/vs-101
 - `purge()` ждёт проекторов: пока проектор, чьи источники включают класс объекта, а у арендатора объекта есть его
   производный класс, не прочёл удаление, `purge` отвечает `projector_pending`. Проектор, который больше не запускают,
   держит `purge` своих источников, пока у арендатора есть его производные классы: запустите его или удалите их.
+  Так же ждёт `trimHistory`: пока проектор не прочёл первую оставшуюся версию, обрезка отвечает `projector_pending`.
 
 **Агрегаты в базе**
 
@@ -2613,7 +2635,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 +2659,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

@@ -142,12 +142,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)
@@ -315,9 +325,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 +337,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,11 @@ export interface ProjectorOptions {
     batch?: number;
     /** Запасной опрос журнала, мс (по умолчанию 1000; сигналы источников будят раньше). */
     pollMs?: number;
+    /**
+     * Сколько транзакция проектора ждёт чужую блокировку строки, мс (по умолчанию 5000; 0 — без предела). Дольше —
+     * пачка откатывается, курсор остаётся, run() не отклоняется, а пропускает проход и повторяет его.
+     */
+    lockTimeout?: number;
     /**
      * Явный список арендаторов проектора: участники — только они (и только те, у кого каждый класс into помечен
      * derivedBy). Без списка участник — любой арендатор с такими классами.
@@ -168,12 +173,15 @@ 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 only;
     constructor(env: ProjectorEnv, name: string, def: ProjectorOptions);
     /**
@@ -299,8 +307,9 @@ 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;
     /** Ждать сигнал источников, остановку или запасной опрос. */

package/dist/project.js

@@ -67,6 +67,10 @@ function change(row, cursor, rebuild = false) {
  * значениями (22…) и пределами размера (54…). Сбой окружения (блокировки, отмена запроса, связь) — не причина
  * выводить арендатора: пачка откатывается целиком, повтор начнётся с того же курсора.
  */
+/** Ожидание чужой блокировки строки дольше lock_timeout (55P03): сбой окружения, проход повторяется. */
+function lockWait(e) {
+    return e?.code === '55P03';
+}
 function tenantFault(e) {
     if (e instanceof LetopisError)
         return true;
@@ -198,12 +202,15 @@ export class Projector {
     /** Источники арендатора без журнала (history: false): их изменений проектор не увидит — арендатор выбывает. */
     blind = new Map();
     stale = true;
+    /** В чекпоинте есть начатая перестройка арендатора пачками (по последней пачке; до первой — проверить). */
+    tenantsPending = true;
     running = false;
     stopped = false;
     wake = null;
     off = null;
     batch;
     pollMs;
+    lockMs;
     only;
     constructor(env, name, def) {
         this.env = env;
@@ -228,6 +235,9 @@ export class Projector {
         this.only = def.tenants ? new Set(def.tenants.map((x) => x.toLowerCase())) : null;
         this.batch = def.batch ?? 500;
         this.pollMs = def.pollMs ?? 1000;
+        this.lockMs = def.lockTimeout ?? 5000;
+        if (!Number.isInteger(this.lockMs) || this.lockMs < 0)
+            throw new LetopisError('invalid_data', `проектор ${name}: lockTimeout — целое число мс, 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) {
@@ -261,18 +271,37 @@ export class Projector {
                     r = await this.step(rep);
                 }
                 catch (e) {
-                    if (!(e instanceof LetopisError && e.code === 'cursor_expired' && this.def.onExpired === 'rebuild'))
+                    if (lockWait(e)) {
+                        rep.skipped++;
+                        r = 'busy';
+                    }
+                    else if (e instanceof LetopisError && e.code === 'cursor_expired' && this.def.onExpired === 'rebuild') {
+                        r = 'rebuild';
+                    }
+                    else
                         throw e;
-                    r = 'rebuild';
                 }
                 // курсор истёк у части арендаторов: с onExpired: 'rebuild' они перестраиваются сами, пачками (доработки после
                 // точки Б). Состояние — в чекпоинте, поэтому перестройку продолжает run() любого процесса, а занятая
-                // блокировка — только повтор на следующем проходе; ошибка данных выводит арендатора с её кодом, без повторов
-                if (this.def.onExpired === 'rebuild' && r !== 'rebuild' && (await this.tenantWork(rep)) && r !== 'busy')
-                    r = 'more';
-                // пачку перестройки держит другой процесс того же проектора — подождать и продолжить
-                if (r === 'rebuild')
-                    r = (await this.rebuildNow(rep, 'auto')) === 'busy' ? 'busy' : 'more';
+                // блокировка — только повтор на следующем проходе; ошибка данных выводит арендатора с её кодом, без повторов.
+                // Начатую перестройку арендатора пачками — и прерванную rebuild({ tenant, chunked: true }) — продвигает run()
+                // и без onExpired (ревью безопасности №3): иначе хвост бессрочно пропускал бы изменения арендатора с id выше
+                // последней пачки. Начинает перестройку выбывших по ярусу только onExpired: 'rebuild'. Блокировку проектора держит
+                // другой процесс (busy) — перестройку продвинет он: чтение чекпоинта ждало бы его пачку
+                const auto = this.def.onExpired === 'rebuild';
+                try {
+                    if (r !== 'rebuild' && r !== 'busy' && (auto || this.tenantsPending) && (await this.tenantWork(rep, auto)))
+                        r = 'more';
+                    // пачку перестройки держит другой процесс того же проектора — подождать и продолжить
+                    if (r === 'rebuild')
+                        r = (await this.rebuildNow(rep, 'auto')) === 'busy' ? 'busy' : 'more';
+                }
+                catch (e) {
+                    if (!lockWait(e))
+                        throw e;
+                    rep.skipped++;
+                    r = 'busy';
+                }
                 if (r === 'more')
                     continue;
                 if (opts.once)
@@ -306,8 +335,11 @@ export class Projector {
                 return rep;
             }
             await this.startTenant(rep, tenant, false);
+            const started = rep.rebuilds;
             for (;;) {
-                const r = await this.tenantChunk(rep, tenant);
+                // занятая строка (lockTimeout) — как занятая блокировка проектора: подождать и повторить пачку
+                const r = await this.tenantChunk(rep, tenant).catch((e) => { if (lockWait(e))
+                    return 'busy'; throw e; });
                 if (r === 'busy')
                     await new Promise((res) => setTimeout(res, 20));
                 if (r !== 'done')
@@ -316,6 +348,10 @@ export class Projector {
                 const f = (await this.tx(async (q) => this.state(q))).failed?.[tenant];
                 if (f)
                     throw new LetopisError(f.code, f.message);
+                // последнюю пачку мог записать run() другого процесса (он продвигает начатые перестройки): перестройка этого
+                // вызова всё равно завершена
+                if (rep.rebuilds === started)
+                    rep.rebuilds++;
                 return rep;
             }
         }
@@ -369,6 +405,10 @@ export class Projector {
             await q.unsafe('begin isolation level read committed');
             await q.unsafe(`set local role ${ident(this.env.ownerRole)}`);
             await q.unsafe(`set local timezone = 'UTC'`);
+            // чужая блокировка строки (транзакция любого арендатора держит итог или цель) не держит пачку всех арендаторов
+            // дольше lockTimeout (хвост ревью безопасности №3): 55P03 — проход пропускается, курсор остаётся
+            if (this.lockMs > 0)
+                await q.unsafe(`set local lock_timeout = ${this.lockMs}`);
             const out = await fn(q);
             await q.unsafe('commit');
             return out;
@@ -489,6 +529,7 @@ export class Projector {
                 return 'rebuild';
             if (meta.version !== this.def.version)
                 throw this.versionError(meta);
+            this.tenantsPending = Object.values(meta.retenant ?? {}).some((v) => !v.done);
             const cur = dec(meta.cursor);
             const rows = await q.unsafe(`select l.tx::text as tx, l.seq::text as seq, ${rowJson('l')} as row
         from ${this.env.S}.watch_read($1::text::xid8, $2::bigint, null, $3::text[], $4::int, $5::text::pg_snapshot, true) l`, [cur.tx, cur.seq, [...this.from, '#reset'], this.batch, cur.snap ?? null]);
@@ -1059,27 +1100,31 @@ export class Projector {
         });
     }
     /**
-     * Автоматическая перестройка выбывших по cursor_expired (onExpired: 'rebuild') — проход run(): начинает перестройку
-     * пачками у каждого такого арендатора и продвигает начатые на пачку. true — работа ещё осталась.
+     * Перестройка арендаторов пачками — проход run(): с start (onExpired: 'rebuild') начинает её у каждого выбывшего по
+     * cursor_expired, затем продвигает на пачку каждую начатую — автоматическую и прерванную rebuild({ tenant, chunked:
+     * true }). true — работа ещё осталась.
      */
-    async tenantWork(rep) {
+    async tenantWork(rep, start) {
         const meta = await this.tx(async (q) => this.state(q));
         if (!meta.cursor || meta.state === 'rebuilding' || meta.version !== this.def.version)
             return false;
         let more = false;
-        for (const [t, f] of Object.entries(meta.failed ?? {})) {
-            if (f.code !== 'cursor_expired' || this.blind.has(t) || !this.scopes.has(t))
-                continue;
-            if ((await this.startTenant(rep, t, true)) === 'ok')
-                more = true;
+        if (start) {
+            for (const [t, f] of Object.entries(meta.failed ?? {})) {
+                if (f.code !== 'cursor_expired' || this.blind.has(t) || !this.scopes.has(t))
+                    continue;
+                if ((await this.startTenant(rep, t, true)) === 'ok')
+                    more = true;
+            }
         }
-        const fresh = await this.tx(async (q) => this.state(q));
+        const fresh = start ? await this.tx(async (q) => this.state(q)) : meta;
         for (const [t, v] of Object.entries(fresh.retenant ?? {})) {
             if (v.done)
                 continue;
             if ((await this.tenantChunk(rep, t)) === 'more')
                 more = true;
         }
+        this.tenantsPending = more;
         return more;
     }
     /** Ждать сигнал источников, остановку или запасной опрос. */

package/dist/sync.js

@@ -11,13 +11,22 @@ function canon(v) {
 export async function syncModels(db, models, opts = {}) {
     const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
     const S = `"${db.schema.replace(/"/g, '""')}"`;
-    // предок раньше потомка
+    // предок раньше потомка; класс-источник агрегата раньше цели: агрегат над классом, которого ещё нет, база отклоняет.
+    // Цикл агрегатов база отклоняет сама — обход его только не зацикливает
     const ordered = [];
+    const visiting = new Set();
     const visit = (m) => {
-        if (ordered.includes(m))
+        if (ordered.includes(m) || visiting.has(m))
             return;
+        visiting.add(m);
         if (m.parent && models.includes(m.parent))
             visit(m.parent);
+        for (const a of Object.values(m.describe().aggregate ?? {})) {
+            const src = models.find((x) => x.name === a.of);
+            if (src)
+                visit(src);
+        }
+        visiting.delete(m);
         ordered.push(m);
     };
     models.forEach(visit);

package/dist/watch.js

@@ -116,10 +116,35 @@ export class Subscription {
         if (!this.pos)
             this.pos = await (this.start ?? this.head());
         const p = this.pos;
-        const rows = await this.ctx.exec.run((q) => q.unsafe(`select l.tx::text as tx, l.seq::text as seq, jsonb_build_object('id', l.id, 'rev', l.rev, 'class', l.class, 'tenant', l.tenant, `
+        const cols = `l.tx::text as tx, l.seq::text as seq, jsonb_build_object('id', l.id, 'rev', l.rev, 'class', l.class, 'tenant', l.tenant, `
             + `'owner', l.owner, 'links', l.links, 'data', l.data, 'tags', l.tags, 'at', l.at, 'author', l.author, 'agent', l.agent, `
-            + `'op', l.op, 'reason', l.reason, 'moved', l.moved) as row `
-            + `from ${this.ctx.S}.watch_read($1::text::xid8, $2::bigint, $3::text::timestamptz, $4::text[], $5::int, $6::text::pg_snapshot) l`, [p.tx, p.seq, p.at, this.ctx.classes, this.batch, p.snap ?? null]), { read: true });
+            + `'op', l.op, 'reason', l.reason, 'moved', l.moved) as row`;
+        // уход строки из классов подписки сменой класса без смены id (хвост ревью безопасности №3) — надгробием прежней
+        // версии в том же окне: полная пачка watch_read ограничивает окно своей последней строкой. Оба потока — одним
+        // оператором: общий снимок и горизонт, иначе курсор перескочил бы событие, зафиксированное между запросами
+        // (автоматическое ревью). Потоки сливаются по (tx, seq) до границы — последней строки потока, обрезанного лимитом
+        const S = this.ctx.S;
+        const both = await this.ctx.exec.run((q) => q.unsafe(`with r as (select l.* from ${S}.watch_read($1::text::xid8, $2::bigint, $3::text::timestamptz, $4::text[], $5::int, $6::text::pg_snapshot) l),
+            u as (select r.tx, r.seq from r where (select count(*) from r) = $5 order by r.tx desc, r.seq desc limit 1)
+       select 0 as src, ${cols} from r l
+       union all
+       select 1 as src, ${cols} from ${S}.watch_leaving($1::text::xid8, $2::bigint, $4::text[], $5::int, $6::text::pg_snapshot,
+         (select tx from u), (select seq from u)) l`, [p.tx, p.seq, p.at, this.ctx.classes, this.batch, p.snap ?? null]), { read: true });
+        const before = (a, b) => BigInt(a.tx) < BigInt(b.tx) || (a.tx === b.tx && BigInt(a.seq) < BigInt(b.seq));
+        const order = (a, b) => (before(a, b) ? -1 : before(b, a) ? 1 : 0);
+        const read = both.filter((r) => r.src === 0).sort(order);
+        const away = both.filter((r) => r.src === 1).sort(order);
+        let rows = read;
+        {
+            const upto = read.length === this.batch ? read[read.length - 1] : null;
+            if (away.length) {
+                let bound = upto;
+                const lastAway = away[away.length - 1];
+                if (away.length === this.batch && (!bound || before(lastAway, bound)))
+                    bound = lastAway;
+                rows = [...read, ...away].sort(order).filter((r) => !bound || !before(bound, r));
+            }
+        }
         for (const r of rows) {
             const row = toRow(r.row);
             const snap = keepSnap(p.snap, r.tx);

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Versioned entity store for Node.js on PostgreSQL 18. Every change is a version in a journal (history, reads as of a date, cursor subscriptions). Integrity, tenant isolation and access rules are enforced by the database itself (triggers and row-level security), so they hold for raw SQL too. Data is read and written with chains like `db.Shop(shop).Product().rows()`.
 
-Key facts for writing code with letopis 1.2:
+Key facts for writing code with letopis 1.3:
 
 - ESM package, Node 22+, PostgreSQL 18+ with pgcrypto, database encoding UTF8. Runtime dependency: `postgres`. Zod 4 is an optional peer dependency needed only by `letopis/model`; `@modelcontextprotocol/server`, only by `letopis/mcp`.
 - Install a schema with `up({ dsn, schema })` from an admin role; the schema is named `v2.<name>`. The application connects with a LOGIN role that is a member of `letopis_app`: `connect({ dsn, schema: 'v2.<name>', token | apiKey })`. A role that bypasses RLS is refused (`bypass_rls`) unless `allowBypassRls: true`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Letopis (летопись): versioned entity store on PostgreSQL 18 — integrity, history, tenants and access control enforced by the database itself, dot-notation chains on top",
   "keywords": [
     "postgres",
@@ -101,6 +101,7 @@
     "@types/node": "^22.20.5",
     "letopis-0": "npm:letopis@0.21.0",
     "letopis-1": "npm:letopis@1.0.1",
+    "letopis-11": "npm:letopis@1.1.0",
     "tsx": "^4.23.15",
     "typescript": "~5.9.3",
     "zod": "4.6.5"

package/sql/10-core.sql

@@ -6,7 +6,9 @@
 revoke all on schema @SCHEMA@ from public;
 grant usage on schema @SCHEMA@ to @APP@;
 
--- Все цели концов плоским списком: {роль: id} или {роль: [id, …]}.
+-- Все цели концов плоским списком: {роль: id} или {роль: [id, …]}. Тело — SQL-стандарта (return): имена связываются
+-- при создании и от search_path сеанса не зависят, а колонку ends вычисляет роль приложения. Вариант на plpgsql быстрее
+-- на 17 % (бенч gencols), но его имена разрешались бы при исполнении (ревью безопасности доработок после 1.2.0)
 create or replace function @SCHEMA@.link_ids(links jsonb) returns uuid[]
 language sql immutable parallel safe
 return (