letopis 1.4.2 → 3.0.0

package/dist/project.js

@@ -1,1258 +0,0 @@
-import { LetopisError, fromDbError } from './errors.js';
-import { release, rollbackAfter } from './tx.js';
-import { toRow } from './sql.js';
-import { wakes } from './watch.js';
-import { schemaRevision, SYSTEM_ID } from './up.js';
-import { DDL_REVISION } from './types.js';
-/** Имя проектора — оно же derivedBy производных классов (метасхема `40-class.sql`). */
-const NAME = /^[a-z0-9][a-z0-9_.:-]{0,63}$/;
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/** Служебные записи журнала: не версии объекта. */
-const SPECIAL = new Set(['purge', 'trim', 'reset']);
-const ident = (n) => `"${n.replace(/"/g, '""')}"`;
-const rowJson = (a) => `jsonb_build_object('id', ${a}.id, 'rev', ${a}.rev, 'class', ${a}.class, 'tenant', ${a}.tenant, `
-    + `'owner', ${a}.owner, 'links', ${a}.links, 'data', ${a}.data, 'tags', ${a}.tags, 'at', ${a}.at, 'author', ${a}.author, `
-    + `'agent', ${a}.agent, 'op', ${a}.op, 'reason', ${a}.reason, 'moved', ${a}.moved)`;
-const enc = (p) => `${p.tx}:${p.seq}${p.snap ? `~${p.snap}` : ''}`;
-function dec(c) {
-    const [head, snap] = c.split('~');
-    const [tx, seq] = head.split(':');
-    return { tx, seq, ...(snap ? { snap } : {}) };
-}
-/** Снимок нужен, пока курсор не дошёл до его xmax. */
-const keepSnap = (snap, tx) => snap && BigInt(tx) < BigInt(snap.split(':')[1]) ? snap : undefined;
-/** Транзакция tx видна в снимке «xmin:xmax:xip,…» (как pg_visible_in_snapshot). */
-function visible(tx, snap) {
-    const [xmin, xmax, xip] = snap.split(':');
-    const t = BigInt(tx);
-    if (t < BigInt(xmin))
-        return true;
-    if (t >= BigInt(xmax))
-        return false;
-    return !(xip ? xip.split(',').some((x) => BigInt(x) === t) : false);
-}
-/**
- * Пустой последний проход перестройки пачками — тоже пачка: id выше последней прочитанной строки до конца диапазона.
- * Его снимок учёл, что таких строк нет, поэтому хвост не применяет изменения, видимые в нём (ревью безопасности №3:
- * без неё надгробие строки с наибольшим id вычиталось лишний раз).
- */
-const LAST_ID = 'ffffffff-ffff-ffff-ffff-ffffffffffff';
-/** Изменение уже учтено перестройкой пачками: id попал в пачку, в снимке которой транзакция видна. */
-function seen(chunks, id, tx) {
-    const c = chunks.find((x) => x.upto >= id);
-    return c !== undefined && visible(tx, c.snap);
-}
-/** Отметки выбывших в meta: пустой список — без ключа. */
-function withFailed(meta, failed) {
-    const next = { ...meta };
-    if (Object.keys(failed).length)
-        next.failed = failed;
-    else
-        delete next.failed;
-    return next;
-}
-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,
-        author: row.author,
-        ...(row.agent !== undefined ? { agent: row.agent } : {}),
-        ...(row.reason !== undefined ? { reason: row.reason } : {}),
-        ...(row.moved !== undefined ? { moved: row.moved } : {}),
-        row,
-        ...(rebuild ? { rebuild: true } : {}),
-    };
-}
-/**
- * Причина ошибки — данные арендатора: проверки строк и приращений out и ошибки базы с кодами letopis (LT…), неверными
- * значениями (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';
-}
-function tenantFault(e) {
-    if (e instanceof LetopisError)
-        return true;
-    return /^(LT|22|54)/.test(String(e?.code ?? ''));
-}
-/** Запись результатов группы одного арендатора: операции копятся и уходят одним вызовом derived_apply. */
-class Out {
-    p;
-    q;
-    tenant;
-    ops = [];
-    /**
-     * Приращения неотправленных inc по ключу свёртки (Projector.foldKey; решение точки Б): каждый вызов out — отдельная
-     * правка строки в базе, и свёртка сводит правки строки к одной на пачку. upsert, delete и get индекс сбрасывают:
-     * правки одной строки уходят в базу в своём порядке.
-     */
-    folds = new Map();
-    /** Итоги записи группы: в отчёт идут, только если группа записана. */
-    stats = { created: 0, updated: 0, deleted: 0, unchanged: 0 };
-    /** Ошибки базы при записи и чтении результатов группы и отказы out по строке и приращениям. */
-    errors = [];
-    /** Первая ошибка базы: транзакция группы прервана, даже если handle поймал ошибку и не бросил её. */
-    aborted = undefined;
-    constructor(p, q, tenant) {
-        this.p = p;
-        this.q = q;
-        this.tenant = tenant;
-    }
-    /** Ошибку дали база или проверки out, а не код handle. */
-    owns(e) {
-        return this.errors.includes(e);
-    }
-    /** Отказ out по строке или приращениям: его причина — данные, по которым handle их построил. */
-    fault(e) {
-        this.errors.push(e);
-        return e;
-    }
-    check(cls, tenant) {
-        if (tenant === this.tenant && !this.p.intoOf(tenant, cls)) {
-            throw new LetopisError('derived_class', `проектор ${this.p.name}: класс ${cls} не входит в into`);
-        }
-        if (typeof tenant !== 'string' || tenant !== this.tenant) {
-            throw new LetopisError('tenant_denied', `проектор ${this.p.name}: арендатор ${String(tenant)} — не арендатор изменений`);
-        }
-        return tenant;
-    }
-    rowOf(keyOrId) {
-        if (typeof keyOrId === 'string')
-            return { $id: keyOrId };
-        if (!keyOrId || typeof keyOrId !== 'object') {
-            throw this.fault(new LetopisError('invalid_data', `проектор ${this.p.name}: нужен ключ строки или id (арендатор ${this.tenant})`));
-        }
-        return keyOrId;
-    }
-    /** Запрос к базе: ошибка запоминается — по ней откатывается группа и выбывает арендатор. */
-    async db(fn) {
-        try {
-            return await fn();
-        }
-        catch (e) {
-            this.errors.push(e);
-            this.aborted ??= e;
-            throw e;
-        }
-    }
-    upsert(cls, row, opts) {
-        const tenant = this.check(cls, opts?.tenant);
-        this.folds.clear();
-        this.ops.push({ op: 'upsert', class: cls, tenant, row: this.rowOf(row) });
-    }
-    inc(cls, row, deltas, opts) {
-        const tenant = this.check(cls, opts?.tenant);
-        for (const [k, v] of Object.entries(deltas ?? {})) {
-            if (typeof v !== 'number' || !Number.isFinite(v)) {
-                throw this.fault(new LetopisError('invalid_data', `проектор ${this.p.name}: приращение поля ${k} — не число (арендатор ${tenant})`));
-            }
-        }
-        const r = this.rowOf(row);
-        const key = this.p.foldKey(tenant, cls, r);
-        const acc = key === null ? undefined : this.folds.get(key);
-        if (acc) {
-            for (const [k, v] of Object.entries(deltas ?? {}))
-                acc[k] = (acc[k] ?? 0) + v;
-            return;
-        }
-        const d = { ...(deltas ?? {}) };
-        this.ops.push({ op: 'inc', class: cls, tenant, row: r, deltas: d });
-        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 });
-    }
-    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(row)]));
-        return r ? toRow(r.row) : null;
-    }
-    async flush() {
-        if (!this.ops.length)
-            return;
-        const ops = this.ops;
-        this.ops = [];
-        this.folds.clear();
-        const [r] = await this.db(() => this.q.unsafe(`select ${this.p.env.S}.derived_apply($1, $2::text::jsonb) as r`, [this.p.name, JSON.stringify(ops)]));
-        const s = r.r;
-        this.stats.created += s.created;
-        this.stats.updated += s.updated;
-        this.stats.deleted += s.deleted;
-        this.stats.unchanged += s.unchanged;
-    }
-}
-export class Projector {
-    env;
-    def;
-    name;
-    /** Области арендаторов проектора: свои семейства from и into. */
-    scopes = new Map();
-    from = [];
-    /** Арендаторы проектора: каждый класс into у них помечен его derivedBy (и, с опцией tenants, они в списке). */
-    tenants = [];
-    /** Самый короткий ярус all политик хранения источников арендатора, мс (нет в карте — предела нет). */
-    lim = new Map();
-    /** Источники арендатора без журнала (history: false): их изменений проектор не увидит — арендатор выбывает. */
-    blind = new Map();
-    stale = true;
-    /** Когда состав читался в последний раз: без LISTEN сигнала о новых классах нет (план 2.0, 7.4 №6). */
-    resolvedAt = 0;
-    /** Участники, которых чекпоинт ещё не знает: им начальная перестройка пачками (tenantWork). */
-    newcomers = [];
-    /** В чекпоинте есть начатая перестройка арендатора пачками (по последней пачке; до первой — проверить). */
-    tenantsPending = true;
-    running = false;
-    stopped = false;
-    wake = null;
-    off = null;
-    batch;
-    pollMs;
-    lockMs;
-    lockRetries;
-    /** Проходов подряд, в которых запись арендатора упиралась в lockTimeout (lockRetries). */
-    lockHits = new Map();
-    only;
-    /**
-     * Перечитать состав: по сигналу классов, а без LISTEN (сигналов нет) — не реже раза в 5 с, как реестр подключения в
-     * режиме none, и в начале run() (план 2.0, 7.4 №6): иначе арендатор, вступивший после запуска, не участвовал бы.
-     */
-    due() {
-        return this.stale || (!this.env.onSignal && Date.now() - this.resolvedAt >= 5000);
-    }
-    constructor(env, name, def) {
-        this.env = env;
-        this.def = def;
-        if (typeof name !== 'string' || !NAME.test(name)) {
-            throw new LetopisError('invalid_data', `проектор: имя ${String(name)} — строчные латинские буквы, цифры и _.:- (до 64), оно же derivedBy классов`);
-        }
-        const names = (x) => Array.isArray(x) && x.length > 0 && x.every((n) => typeof n === 'string' && n.length > 0);
-        if (!def || !names(def.from) || !names(def.into))
-            throw new LetopisError('invalid_data', `проектор ${name}: from и into — непустые списки классов`);
-        if (!Number.isInteger(def.version) || def.version < 1)
-            throw new LetopisError('invalid_data', `проектор ${name}: version — целое число от 1`);
-        if (typeof def.handle !== 'function')
-            throw new LetopisError('invalid_data', `проектор ${name}: нужна функция handle(changes, out)`);
-        if (def.onExpired !== undefined && def.onExpired !== 'rebuild' && def.onExpired !== 'error') {
-            throw new LetopisError('invalid_data', `проектор ${name}: onExpired — 'rebuild' или 'error'`);
-        }
-        if (def.tenants !== undefined && !(Array.isArray(def.tenants) && def.tenants.length > 0 && def.tenants.every((x) => typeof x === 'string' && UUID.test(x)))) {
-            throw new LetopisError('invalid_data', `проектор ${name}: tenants — непустой список id арендаторов`);
-        }
-        this.name = name;
-        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 и больше`);
-        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) {
-            this.off = env.onSignal((s) => {
-                if (s.kind === 'class' && s.cls === 'Class')
-                    this.stale = true;
-                if (s.kind === 'all')
-                    this.stale = true;
-                if (wakes(s, this.from.length ? new Set([...this.from, '#reset']) : null, null))
-                    this.wake?.();
-            });
-        }
-    }
-    /**
-     * Догнать журнал и следовать за ним до stop(); { once: true } — только догнать. Первый запуск (проекции
-     * ещё нет) начинается с перестройки пачками, прерванная перестройка пачками продолжается; так же, пачками,
-     * перестраивает onExpired: 'rebuild' (решение точки Б: горизонт подписок кластера стоит не дольше пачки).
-     */
-    async run(opts = {}) {
-        if (this.running)
-            throw new LetopisError('invalid_query', `проектор ${this.name} уже запущен в этом процессе`);
-        this.running = true;
-        this.stopped = false;
-        if (!this.env.onSignal)
-            this.stale = true;
-        const rep = emptyReport();
-        try {
-            for (;;) {
-                if (this.stopped)
-                    return rep;
-                let r;
-                try {
-                    r = await this.step(rep);
-                }
-                catch (e) {
-                    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;
-                }
-                // курсор истёк у части арендаторов: с onExpired: 'rebuild' они перестраиваются сами, пачками (доработки после
-                // точки Б). Состояние — в чекпоинте, поэтому перестройку продолжает run() любого процесса, а занятая
-                // блокировка — только повтор на следующем проходе; ошибка данных выводит арендатора с её кодом, без повторов.
-                // Начатую перестройку арендатора пачками — и прерванную 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)
-                    return rep;
-                await this.sleep();
-            }
-        }
-        finally {
-            this.running = false;
-        }
-    }
-    /**
-     * Перестроить проекцию с текущего состояния: атомарно (одна транзакция: до фиксации читатели видят
-     * прежние строки, но горизонт подписок стоит) или { chunked: true } — пачками: производные строки
-     * удаляются сразу, до конца перестройки данные неполные (status() — rebuilding); прерванную перестройку
-     * продолжает следующий запуск. Полная перестройка начинает всех участников заново: отметки выбывших снимаются,
-     * а чьи данные снова не проходят — выбывают снова. { tenant: id } — только этот арендатор, одной транзакцией:
-     * его производные строки удаляются и строятся из его текущих строк источников, отметка выбывшего снимается.
-     * { tenant, chunked: true } — этот арендатор пачками, пока хвост журнала идёт для всех (доработки после точки Б):
-     * его производные строки удаляются сразу и до конца перестройки неполны; блокировку, занятую run() другого процесса,
-     * перестройка пережидает.
-     */
-    async rebuild(opts = {}) {
-        const rep = emptyReport();
-        if (opts.tenant !== undefined) {
-            if (typeof opts.tenant !== 'string' || !UUID.test(opts.tenant))
-                throw new LetopisError('invalid_data', `проектор ${this.name}: rebuild({ tenant }) — id арендатора`);
-            const tenant = opts.tenant.toLowerCase();
-            if (!opts.chunked) {
-                await this.rebuildTenant(rep, tenant);
-                return rep;
-            }
-            await this.startTenant(rep, tenant, false);
-            const started = rep.rebuilds;
-            for (;;) {
-                // занятая строка (lockTimeout) — как занятая блокировка проектора: подождать и повторить пачку
-                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;
-                // ошибка данных арендатора — как у перестройки одной транзакцией: отказ, арендатор выбывший; чекпоинт держит
-                // пачка 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() другого процесса (он продвигает начатые перестройки): перестройка этого
-                // вызова всё равно завершена
-                if (rep.rebuilds === started)
-                    rep.rebuilds++;
-                return rep;
-            }
-        }
-        await this.rebuildNow(rep, Boolean(opts.chunked));
-        return rep;
-    }
-    async status() {
-        return this.tx(async (q) => {
-            if (this.due())
-                await this.resolve(q);
-            const [r] = await q.unsafe(`select s.meta from ${this.env.S}.secret s
-        where s.kind = 'PROJECTOR' and s.ident = $1 and s.account = $2::uuid and s.deleted_at is null`, [this.name, SYSTEM_ID]);
-            const meta = (r?.meta ?? {});
-            const failed = meta.failed ?? {};
-            let lag = 0;
-            if (meta.cursor) {
-                const p = dec(meta.cursor);
-                const [l] = await q.unsafe(`select coalesce(extract(epoch from clock_timestamp() - min(l.at)) * 1000, 0)::float8 as ms
-          from ${this.env.S}.log l where (l.tx, l.seq) > ($1::text::xid8, $2::bigint) and l.class = any ($3::text[]) and l.tenant = any ($5::uuid[])
-            and ($4::text is null or not pg_visible_in_snapshot(l.tx, $4::text::pg_snapshot))`, [p.tx, p.seq, [...this.from, '#reset'], p.snap ?? null, this.tenants.filter((x) => !failed[x])]);
-                lag = Number(l?.ms ?? 0);
-            }
-            return {
-                name: this.name,
-                state: !meta.cursor ? 'new' : meta.state === 'rebuilding' ? 'rebuilding' : 'running',
-                version: meta.version ?? null,
-                cursor: meta.cursor ?? null,
-                at: meta.at ?? null,
-                lag,
-                failed,
-                rebuildingTenants: Object.entries(meta.retenant ?? {}).filter(([, v]) => !v.done).map(([t]) => t).sort(),
-            };
-        });
-    }
-    /** Остановить run() после текущей пачки. */
-    stop() {
-        this.stopped = true;
-        this.wake?.();
-    }
-    /** stop() и отписка от сигналов. */
-    close() {
-        this.stop();
-        this.off?.();
-        this.off = null;
-    }
-    // ---------------------------------------------------------------------------
-    /** Транзакция под ролью владельца на отдельном соединении пула. */
-    async tx(fn) {
-        const q = await this.env.sql.reserve();
-        let failure = null;
-        try {
-            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;
-        }
-        catch (e) {
-            // обрыв: rollback и возврат мёртвого соединения в пул роняли процесс (план 2.0, 7.4 №7)
-            failure = e;
-            await rollbackAfter(q, e);
-            throw fromDbError(e);
-        }
-        finally {
-            release(q, failure);
-        }
-    }
-    async lock(q) {
-        // строка-замок таблицы secret (lock_try, ревью безопасности №3, №2): посторонняя роль её не займёт
-        const [r] = await q.unsafe(`select ${this.env.S}.lock_try($1) as ok`, [`${this.env.schema}:projector:${this.name}`]);
-        return Boolean(r?.ok);
-    }
-    async state(q) {
-        const [r] = await q.unsafe(`select ${this.env.S}.projector_state($1) as m`, [this.name]);
-        return (r?.m ?? {});
-    }
-    async advance(q, expected, meta) {
-        // источники — для purge базы: надгробие, которое проектор ещё не прочёл, она не сотрёт (ревью безопасности №3, №5)
-        const [r] = await q.unsafe(`select ${this.env.S}.projector_advance($1, $2, $3::text::jsonb) as ok`, [this.name, expected ?? null, JSON.stringify({ ...meta, from: this.def.from })]);
-        if (!r?.ok)
-            throw new LetopisError('invalid_query', `проектор ${this.name}: чекпоинт изменился во время пачки`);
-    }
-    async now(q) {
-        // ISO, как время версий в строках (jsonb): Date.parse его понимает
-        const [r] = await q.unsafe(`select to_json(clock_timestamp()) #>> '{}' as t`);
-        return String(r.t);
-    }
-    /** Отметка выбывшего: источники арендатора не ведут журнал. */
-    blindFailure(tenant, cursor) {
-        return { cursor, code: 'invalid_class', message: this.blindError(tenant).message.replace(/^letopis: [a-z_]+: /, '') };
-    }
-    blindError(tenant) {
-        return new LetopisError('invalid_class', `проектор ${this.name}: у арендатора ${tenant} источники ${(this.blind.get(tenant) ?? []).join(', ')} не ведут журнал (history: false) — проектор не увидит их изменений`);
-    }
-    versionError(meta) {
-        return new LetopisError('rebuild_required', `проектор ${this.name}: проекция построена версией ${String(meta.version)}, а проектор — версии ${this.def.version}: нужна перестройка rebuild()`);
-    }
-    /**
-     * Арендаторы и классы по строкам Class всех арендаторов (реестр администраторского подключения без сессии
-     * видит только System). Проектор работает с арендаторами, у которых каждый класс into помечен его
-     * derivedBy (с опцией tenants — только из списка); изменения остальных арендаторов пропускаются — иначе
-     * любой арендатор, заведя одноимённый класс без пометки, остановил бы проектор для всех. Источники — семейства
-     * from у этих арендаторов, кроме собственных результатов.
-     */
-    async resolve(q) {
-        const S = this.env.S;
-        const rev = await schemaRevision(q, this.env.schema);
-        if (rev !== DDL_REVISION) {
-            throw new LetopisError('invalid_data', `проектор ${this.name}: движок схемы ревизии ${String(rev)}, библиотека — ${DDL_REVISION}: обновите схему up({ upgrade: true })`);
-        }
-        const wanted = [...new Set(this.def.into)];
-        const tenants = (await q.unsafe(`select x.tenant::text as t from ${S}.entity x
-      where x.class = 'Class' and x.data->>'name' = any ($1::text[]) and x.data->'resolved'->>'derivedBy' = $2
-      group by x.tenant having count(distinct x.data->>'name') = $3`, [wanted, this.name, wanted.length]))
-            .map((r) => r.t).filter((x) => !this.only || this.only.has(x));
-        if (!tenants.length) {
-            throw new LetopisError('derived_class', `проектор ${this.name}: ни у одного арендатора${this.only ? ' из списка tenants' : ''} классы ${wanted.join(', ')} не помечены derivedBy: '${this.name}'`);
-        }
-        // области — по арендатору: у каждого свои семейства from и into (имена классов у арендаторов свои)
-        const scopes = new Map(tenants.map((x) => [x, { from: new Set(), into: new Set(), keys: new Map() }]));
-        const rows = await q.unsafe(`select x.tenant::text as t, x.data->>'name' as n, x.data->'resolved'->'key' as key,
-        x.data->'resolved'->'ancestors' ?| $2::text[] as is_into, x.data->'resolved'->'ancestors' ?| $1::text[] as is_from
-      from ${S}.entity x
-      where x.class = 'Class' and x.tenant = any ($3::uuid[]) and x.data->'resolved'->'ancestors' ?| ($1::text[] || $2::text[])`, [this.def.from, this.def.into, tenants]);
-        for (const r of rows) {
-            const sc = scopes.get(r.t);
-            // результат проектора источником не бывает: свой вывод он не читает
-            if (r.is_into) {
-                sc.into.add(r.n);
-                sc.keys.set(r.n, Array.isArray(r.key) ? r.key : []);
-            }
-            else if (r.is_from)
-                sc.from.add(r.n);
-        }
-        const from = [...new Set([...scopes.values()].flatMap((s) => [...s.from]))];
-        if (!from.length)
-            throw new LetopisError('invalid_class', `проектор ${this.name}: классов ${this.def.from.join(', ')} нет у арендаторов проектора`);
-        // ярус all политики хранения и журнал источников — по арендатору (ревью безопасности №2): это описание его классов,
-        // и короткий ярус или выключенный журнал одного арендатора не касается остальных
-        const lim = new Map();
-        const blind = new Map();
-        const pol = await q.unsafe(`select x.tenant::text as t, x.data->>'name' as n, x.data->'resolved'->>'history' = 'false' as off,
-        (extract(epoch from ${S}.history_iv(${S}.history_policy(x.data->'resolved')->>'all')) * 1000)::float8 as ms
-      from ${S}.entity x
-      where x.class = 'Class' and x.data->>'name' = any ($1::text[]) and x.tenant = any ($2::uuid[])`, [from, tenants]);
-        for (const r of pol) {
-            const t = r.t;
-            if (!scopes.get(t).from.has(r.n))
-                continue;
-            if (r.off)
-                blind.set(t, [...(blind.get(t) ?? []), r.n]);
-            if (r.ms != null)
-                lim.set(t, Math.min(lim.get(t) ?? Infinity, Number(r.ms)));
-        }
-        this.lim = lim;
-        this.blind = blind;
-        this.from = from;
-        this.scopes = scopes;
-        this.tenants = tenants;
-        this.stale = false;
-        this.resolvedAt = Date.now();
-    }
-    /** Одна пачка журнала. */
-    async step(rep) {
-        return this.tx(async (q) => {
-            if (!(await this.lock(q))) {
-                rep.skipped++;
-                return 'busy';
-            }
-            if (this.due())
-                await this.resolve(q);
-            const meta = await this.state(q);
-            if (!meta.cursor || meta.state === 'rebuilding')
-                return 'rebuild';
-            if (meta.version !== this.def.version)
-                throw this.versionError(meta);
-            this.tenantsPending = Object.values(meta.retenant ?? {}).some((v) => !v.done);
-            // участники, которых чекпоинт не знает (вступили после проекции): начальную перестройку пачками начнёт tenantWork,
-            // их изменения до неё учтёт она же (план 2.0, 7.4 №5)
-            const known = new Set(meta.tenants ?? this.tenants);
-            this.newcomers = this.tenants.filter((x) => !known.has(x) && !meta.failed?.[x] && !meta.retenant?.[x]);
-            if (this.newcomers.length)
-                this.tenantsPending = true;
-            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]);
-            const failed = { ...(meta.failed ?? {}) };
-            for (const t of this.blind.keys())
-                failed[t] ??= this.blindFailure(t, meta.cursor);
-            // время курсора проверяет сам проектор, а не watch_read: без изменений после курсора прореживать было нечего, и
-            // простоявший без событий проектор не истекает. Ярус all — по арендатору (ревью безопасности №2): истёк у всех
-            // участников — cursor_expired, у части — выбывают только они, иначе короткий ярус классов одного арендатора
-            // останавливал бы проектор для всех
-            // перестроенный арендатор считает ярус от начала своей перестройки, пока курсор её не догнал: изменения до неё
-            // учтены перестройкой, и прореженные из них ему не нужны (иначе отстающий проектор выводил бы его снова)
-            if (rows.length && meta.at) {
-                const at = Date.parse(meta.at);
-                const ageOf = (x) => Date.now() - Math.max(at, meta.since?.[x] ? Date.parse(meta.since[x]) : at);
-                const live = this.tenants.filter((x) => !failed[x]);
-                const old = live.filter((x) => (this.lim.get(x) ?? Infinity) < ageOf(x));
-                if (old.length && old.length === live.length) {
-                    throw new LetopisError('cursor_expired', `проектор ${this.name}: курсор старше яруса all политики хранения источников — изменения могли проредиться, нужна перестройка rebuild()`);
-                }
-                for (const x of old) {
-                    failed[x] = { cursor: meta.cursor, code: 'cursor_expired',
-                        message: `проектор ${this.name}: курсор старше яруса all политики хранения источников арендатора ${x} — его изменения могли проредиться, нужна перестройка rebuild({ tenant })` };
-                }
-            }
-            let pos = cur;
-            let changes = [];
-            const away = new Set();
-            for (const r of rows) {
-                const snap = keepSnap(cur.snap, r.tx);
-                pos = { tx: r.tx, seq: r.seq, ...(snap ? { snap } : {}) };
-                const row = toRow(r.row);
-                if (this.newcomers.includes(row.tenant))
-                    continue;
-                const leaves = this.leaves(row, failed);
-                if (!leaves && !this.ours(row, failed))
-                    continue;
-                if (meta.chunks && seen(meta.chunks, row.id, pos.tx))
-                    continue;
-                // после rebuild({ tenant }): транзакция видна в снимке перестройки арендатора — изменение уже учтено
-                const rs = meta.resync?.[row.tenant];
-                if (rs && visible(pos.tx, rs))
-                    continue;
-                // перестройка арендатора пачками: выше последней пачки — прочтёт пачка; в пройденной — если транзакция видна в
-                // её снимке, изменение уже учтено
-                const rt = meta.retenant?.[row.tenant];
-                if (rt && !rt.done && (rt.last === null || row.id > rt.last))
-                    continue;
-                if (rt && seen(rt.chunks, row.id, pos.tx))
-                    continue;
-                const c = change(row, enc(pos));
-                if (leaves)
-                    away.add(c);
-                changes.push(c);
-            }
-            if (away.size)
-                changes = await this.leaving(q, changes, away);
-            if (changes.length) {
-                if (this.def.withBefore)
-                    await this.fillBefore(q, changes);
-                await this.apply(q, changes, rep, failed);
-            }
-            const caught = rows.length < this.batch;
-            // состав — известные нынешние участники: выбывший из участников, вернувшись, снова новичок
-            const next = withFailed({ ...meta, cursor: enc(pos), tenants: this.tenants.filter((x) => known.has(x)) }, failed);
-            if (!rows.length) {
-                // пусто: отметить время прохода, но не чаще раза в минуту — иначе каждый опрос писал бы чекпоинт
-                if (meta.at && Date.now() - Date.parse(meta.at) < 60_000)
-                    return 'empty';
-                next.at = await this.now(q);
-            }
-            else {
-                // догнавший проектор не стареет: cursor_expired считается по времени курсора
-                next.at = caught ? await this.now(q) : rows[rows.length - 1].row.at;
-            }
-            if (next.chunks && next.chunks.every((c) => BigInt(pos.tx) >= BigInt(c.snap.split(':')[1])))
-                delete next.chunks;
-            if (next.resync) {
-                // снимок перестройки арендатора не нужен, когда курсор дошёл до его xmax
-                const left = Object.entries(next.resync).filter(([, s]) => BigInt(pos.tx) < BigInt(s.split(':')[1]));
-                if (left.length)
-                    next.resync = Object.fromEntries(left);
-                else
-                    delete next.resync;
-            }
-            if (next.retenant) {
-                // выбывший посреди своей перестройки — без производных строк: пачки построили их лишь частично (ревью
-                // безопасности №3, №6)
-                const partial = Object.entries(next.retenant).filter(([t, v]) => failed[t] && !v.done).map(([t]) => t);
-                if (partial.length)
-                    await this.clear(q, partial);
-                // перестройка арендатора пачками: выбывший — без неё; законченная — пока курсор не прошёл снимки её пачек
-                const left = Object.entries(next.retenant).filter(([t, v]) => !failed[t]
-                    && !(v.done && v.chunks.every((c) => BigInt(pos.tx) >= BigInt(c.snap.split(':')[1]))));
-                if (left.length)
-                    next.retenant = Object.fromEntries(left);
-                else
-                    delete next.retenant;
-            }
-            if (next.since) {
-                const left = Object.entries(next.since).filter(([, t]) => Date.parse(next.at) < Date.parse(t));
-                if (left.length)
-                    next.since = Object.fromEntries(left);
-                else
-                    delete next.since;
-            }
-            await this.advance(q, meta.cursor, next);
-            rep.batches++;
-            rep.changes += changes.length;
-            return caught ? 'empty' : 'more';
-        });
-    }
-    /** Прошлые версии одним запросом: последняя версия того же id с меньшим номером, кроме служебных записей. */
-    async previous(q, list) {
-        const out = new Map();
-        if (!list.length)
-            return out;
-        const rows = await q.unsafe(`select c.i, ${rowJson('l')} as row
-      from unnest($1::int[], $2::uuid[], $3::int[]) c(i, id, rev)
-      cross join lateral (
-        select x.* from ${this.env.S}.log x
-        where x.id = c.id and x.rev < c.rev and x.op not in ('purge', 'trim', 'reset')
-        order by x.rev desc limit 1) l`, [list.map((_, i) => i), list.map((c) => c.id), list.map((c) => c.rev)]);
-        for (const r of rows)
-            out.set(list[r.i], toRow(r.row));
-        return out;
-    }
-    /**
-     * Прошлые версии (id, rev − 1 и раньше) — всегда того же id. У первой версии нового id после reclass и rekey прошлой
-     * версии нет (null): прежние данные вычитает надгробие прежнего id. Прежде её before была последняя версия прежнего
-     * id, и свёртка вычитала её дважды — через неё и через надгробие. Прошлая версия вне семейства from арендатора —
-     * тоже null: строка вошла в семейство сменой класса без смены id, и в проекции её не было (ревью безопасности №3, №4).
-     */
-    async fillBefore(q, changes) {
-        const need = changes.filter((c) => !SPECIAL.has(c.op));
-        for (const c of need)
-            c.before = null;
-        for (const [c, row] of await this.previous(q, need)) {
-            if (row.op !== 'delete' && this.scopes.get(c.tenant)?.from.has(row.class))
-                c.before = row;
-        }
-    }
-    /**
-     * Смена класса без смены id (класс без ключа: сырой update set class, reclass()), уводящая строку из семейства from:
-     * журнал пишет версию уже другого класса, а для проекции это удаление (ревью безопасности №3, №4). Изменение — op
-     * delete с $deleted, строка — последняя версия в семействе, номер, время и автор — смены класса. Прошлая версия вне
-     * семейства арендатора — изменения нет.
-     */
-    async leaving(q, changes, away) {
-        const prev = await this.previous(q, [...away]);
-        const out = [];
-        for (const c of changes) {
-            if (!away.has(c)) {
-                out.push(c);
-                continue;
-            }
-            const p = prev.get(c);
-            if (!p || p.op === 'delete' || !this.scopes.get(c.tenant)?.from.has(p.class))
-                continue;
-            const { agent: _agent, reason: _reason, moved: _moved, ...last } = p;
-            out.push(change({ ...last, rev: c.rev, at: c.at, author: c.author, op: 'delete', $deleted: true,
-                ...(c.agent !== undefined ? { agent: c.agent } : {}), ...(c.reason !== undefined ? { reason: c.reason } : {}) }, c.cursor));
-        }
-        return out;
-    }
-    /**
-     * handle и запись результатов в транзакции пачки — группами по арендатору (ревью безопасности №2). failed —
-     * отметки выбывших этой пачки: каждая группа идёт под точкой сохранения, и ошибка данных арендатора (tenantFault:
-     * отказ базы при записи или чтении его результатов, отказ out по строке или приращениям) откатывает только группу,
-     * а арендатор попадает в failed (курсор — первого изменения группы, у перестройки — start). Исключение handle,
-     * нарушение границ out и сбой окружения пачку не спасают: откатывается всё. failed null (rebuild({ tenant })) — без
-     * точек сохранения: любая ошибка откатывает перестройку.
-     */
-    async apply(q, changes, rep, failed, start = '') {
-        const groups = new Map();
-        for (const c of changes) {
-            const g = groups.get(c.tenant);
-            if (g)
-                g.push(c);
-            else
-                groups.set(c.tenant, [c]);
-        }
-        for (const [tenant, list] of groups) {
-            const out = new Out(this, q, tenant);
-            if (failed)
-                await q.unsafe('savepoint letopis_projector');
-            try {
-                await this.def.handle(list, out);
-                await out.flush();
-                // handle поймал ошибку базы и не бросил её: транзакция группы всё равно прервана
-                if (out.aborted !== undefined)
-                    throw out.aborted;
-            }
-            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');
-                await q.unsafe('release savepoint letopis_projector');
-                const le = fromDbError(cause);
-                failed[tenant] = {
-                    cursor: list[0].cursor || start,
-                    code: le instanceof LetopisError ? le.code : String(le?.code ?? 'internal'),
-                    message: String(le?.message ?? le).replace(/^letopis: [a-z_]+: /, ''),
-                };
-                continue;
-            }
-            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;
-            rep.unchanged += out.stats.unchanged;
-        }
-    }
-    /**
-     * Перестройка. 'auto' — путь run() (проекции ещё нет, onExpired: 'rebuild'): пачками, а прерванная перестройка
-     * пачками продолжается с места обрыва; блокировку держит другой процесс — 'busy' (run() подождёт), а не
-     * projector_busy, как у rebuild(). Иначе — как просили в rebuild().
-     */
-    async rebuildNow(rep, chunked) {
-        if (chunked === 'auto') {
-            const st = await this.status();
-            return this.chunked(rep, st.state === 'rebuilding', { cursor: st.cursor });
-        }
-        if (chunked)
-            return this.chunked(rep, false);
-        await this.atomic(rep);
-        return 'done';
-    }
-    /** Строка текущего состояния как изменение перестройки; прошлой версии у неё нет. */
-    rebuildChange(raw) {
-        const c = change(toRow(raw), '', true);
-        if (this.def.withBefore)
-            c.before = null;
-        return c;
-    }
-    /** Изменение — из семейства from своего арендатора (сброс арендатора — тоже); выбывший арендатор пропускается. */
-    ours(row, failed) {
-        const sc = this.scopes.get(row.tenant);
-        return sc !== undefined && !failed?.[row.tenant] && (sc.from.has(row.class) || row.class === '#reset');
-    }
-    /** Смена класса без смены id, после которой строка вне семейства from арендатора, — возможно, уход из него (leaving). */
-    leaves(row, failed) {
-        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';
-    }
-    /**
-     * Входит ли класс `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 не складывает: её поля правят строку, и порядок таких правок важен.
-     */
-    foldKey(tenant, cls, row) {
-        const key = this.scopes.get(tenant)?.keys.get(cls) ?? [];
-        const names = Object.keys(row).sort();
-        if (!names.length || !names.every((n) => n === '$id' || key.includes(n)))
-            return null;
-        return JSON.stringify([cls, names.map((n) => [n, row[n]])]);
-    }
-    busy() {
-        return new LetopisError('projector_busy', `проектор ${this.name} работает в другом процессе`);
-    }
-    /** Производные строки арендаторов tenants — только семейства into каждого из них (derived_clear по парам). */
-    async clear(q, tenants) {
-        const ts = [];
-        const cs = [];
-        for (const t of tenants) {
-            for (const c of this.scopes.get(t)?.into ?? []) {
-                ts.push(t);
-                cs.push(c);
-            }
-        }
-        await q.unsafe(`select ${this.env.S}.derived_clear($1, $2::uuid[], $3::text[])`, [this.name, ts, cs]);
-    }
-    /** Атомарная перестройка: одна транзакция, источники — курсором одним снимком. */
-    async atomic(rep) {
-        await this.tx(async (q) => {
-            if (!(await this.lock(q)))
-                throw this.busy();
-            await this.resolve(q);
-            const meta = await this.state(q);
-            await this.clear(q, this.tenants);
-            // курсор держит снимок своего объявления: pg_current_snapshot() в его запросе — этот снимок; строка s
-            // есть всегда, даже без источников
-            await q.unsafe(`declare letopis_rebuild no scroll cursor for
-        with s as (select pg_current_snapshot() as snap)
-        select s.snap::text as snap, pg_snapshot_xmin(s.snap)::text as xmin, case when e.id is null then null else ${rowJson('e')} end as row
-        from s left join ${this.env.S}.entity e on e.class = any ($1::text[]) and e.tenant = any ($2::uuid[])
-        order by e.id`, [this.from, this.tenants]);
-            let head = null;
-            // полная перестройка начинает всех участников заново: отметки выбывших — только её собственные; арендатор, чьи
-            // источники не ведут журнал, выбывает сразу
-            const failed = {};
-            for (const x of this.blind.keys())
-                failed[x] = this.blindFailure(x, '');
-            for (;;) {
-                const rows = await q.unsafe(`fetch ${this.batch} from letopis_rebuild`);
-                if (!rows.length)
-                    break;
-                head ??= { tx: rows[0].xmin, seq: '0', snap: rows[0].snap };
-                const changes = rows.filter((r) => r.row).map((r) => this.rebuildChange(r.row)).filter((c) => this.ours(c.row, failed));
-                if (changes.length) {
-                    await this.apply(q, changes, rep, failed, enc(head));
-                    rep.changes += changes.length;
-                }
-            }
-            await q.unsafe('close letopis_rebuild');
-            for (const x of this.blind.keys())
-                failed[x].cursor = enc(head);
-            // выбывший посреди перестройки — без производных строк: прежние пачки построили их лишь частично
-            if (Object.keys(failed).length)
-                await this.clear(q, Object.keys(failed));
-            await this.advance(q, meta.cursor, withFailed({ cursor: enc(head), at: await this.now(q), version: this.def.version, state: 'running',
-                tenants: [...this.tenants] }, failed));
-            rep.rebuilds++;
-        });
-    }
-    /**
-     * Перестройка пачками: своя транзакция и свой снимок у каждой пачки источников. auto — путь run(): занятую другим
-     * процессом блокировку он пережидает ('busy'), а новую перестройку не начинает, если её уже начал или закончил
-     * другой процесс (курсор чекпоинта — не тот, что видел run()): тогда только продолжает начатую.
-     */
-    async chunked(rep, resume, auto) {
-        const busy = () => {
-            if (!auto)
-                throw this.busy();
-            rep.skipped++;
-            return 'busy';
-        };
-        if (!resume) {
-            const r = await this.tx(async (q) => {
-                if (!(await this.lock(q)))
-                    return busy();
-                await this.resolve(q);
-                const meta = await this.state(q);
-                if (auto && (meta.state === 'rebuilding' || (meta.cursor ?? null) !== auto.cursor))
-                    return 'ok';
-                await this.clear(q, this.tenants);
-                const [h] = await q.unsafe(`select pg_snapshot_xmin(s)::text as xmin, s::text as snap from pg_current_snapshot() s`);
-                const start = enc({ tx: h.xmin, seq: '0', snap: h.snap });
-                // все участники заново: отметки выбывших снимаются; арендатор, чьи источники не ведут журнал, выбывает сразу
-                const failed = {};
-                for (const x of this.blind.keys())
-                    failed[x] = this.blindFailure(x, start);
-                await this.advance(q, meta.cursor, withFailed({ cursor: start, at: await this.now(q), version: this.def.version, state: 'rebuilding',
-                    rebuild: { start, last: null, chunks: [] } }, failed));
-                return 'ok';
-            });
-            if (r === 'busy')
-                return r;
-        }
-        for (;;) {
-            const r = await this.tx(async (q) => {
-                if (!(await this.lock(q)))
-                    return busy();
-                if (this.due())
-                    await this.resolve(q);
-                const meta = await this.state(q);
-                const rb = meta.rebuild;
-                if (meta.state !== 'rebuilding' || !rb)
-                    return 'done';
-                const failed = { ...(meta.failed ?? {}) };
-                for (const x of this.blind.keys())
-                    failed[x] ??= this.blindFailure(x, rb.start);
-                // пачка источников и её снимок — одним оператором; выбывших арендаторов пачка не читает
-                const rows = await q.unsafe(`with s as (select pg_current_snapshot()::text as snap)
-          select s.snap, case when e.id is null then null else ${rowJson('e')} end as row
-          from s left join lateral (select x.* from ${this.env.S}.entity x
-            where x.class = any ($1::text[]) and x.tenant = any ($4::uuid[]) and ($2::uuid is null or x.id > $2::uuid)
-            order by x.id limit $3) e on true`, [this.from, rb.last, this.batch, this.tenants.filter((x) => !failed[x])]);
-                const real = rows.filter((r) => r.row);
-                if (!real.length) {
-                    await this.advance(q, meta.cursor, withFailed({ cursor: rb.start, at: await this.now(q), version: this.def.version, state: 'running',
-                        chunks: [...rb.chunks, { upto: LAST_ID, snap: rows[0].snap }], tenants: [...this.tenants] }, failed));
-                    rep.rebuilds++;
-                    return 'done';
-                }
-                const changes = real.map((r) => this.rebuildChange(r.row)).filter((c) => this.ours(c.row, failed));
-                if (changes.length)
-                    await this.apply(q, changes, rep, failed, rb.start);
-                // выбывший в этой пачке — без производных строк: прежние пачки построили их лишь частично
-                const fresh = Object.keys(failed).filter((x) => !meta.failed?.[x]);
-                if (fresh.length)
-                    await this.clear(q, fresh);
-                rep.changes += changes.length;
-                // граница пачки — последний прочитанный id (а не последнее изменение: строки чужих семейств пропущены)
-                const last = real[real.length - 1].row.id;
-                await this.advance(q, meta.cursor, withFailed({ ...meta, rebuild: { start: rb.start, last, chunks: [...rb.chunks, { upto: last, snap: rows[0].snap }] } }, failed));
-                return 'more';
-            });
-            if (r !== 'more')
-                return r;
-        }
-    }
-    /**
-     * Перестройка одного арендатора (rebuild({ tenant })): одной транзакцией его производные строки удаляются и
-     * строятся заново из его текущих строк источников, отметка выбывшего снимается. Снимок перестройки встаёт в
-     * чекпоинт (meta.resync): изменения арендатора, чья транзакция в нём видна, хвост журнала пропускает — каждое
-     * изменение применено ровно один раз. Ошибка записи откатывает перестройку: арендатор остаётся выбывшим.
-     */
-    async rebuildTenant(rep, tenant) {
-        await this.tx(async (q) => {
-            if (!(await this.lock(q)))
-                throw this.busy();
-            await this.resolve(q);
-            const meta = await this.state(q);
-            if (!meta.cursor || meta.state === 'rebuilding') {
-                throw new LetopisError('rebuild_required', `проектор ${this.name}: проекции ещё нет или идёт перестройка пачками — сначала run() или rebuild()`);
-            }
-            if (meta.version !== this.def.version)
-                throw this.versionError(meta);
-            const sc = this.scopes.get(tenant);
-            if (!sc) {
-                throw new LetopisError('tenant_denied', `проектор ${this.name}: арендатор ${tenant} не участник — у него не все классы ${this.def.into.join(', ')} помечены derivedBy: '${this.name}'${this.only ? ' или его нет в списке tenants' : ''}`);
-            }
-            if (this.blind.has(tenant))
-                throw this.blindError(tenant);
-            await this.clear(q, [tenant]);
-            await q.unsafe(`declare letopis_rebuild no scroll cursor for
-        with s as (select pg_current_snapshot() as snap)
-        select s.snap::text as snap, case when e.id is null then null else ${rowJson('e')} end as row
-        from s left join ${this.env.S}.entity e on e.class = any ($1::text[]) and e.tenant = $2::uuid
-        order by e.id`, [[...sc.from], tenant]);
-            let snap = null;
-            for (;;) {
-                const rows = await q.unsafe(`fetch ${this.batch} from letopis_rebuild`);
-                if (!rows.length)
-                    break;
-                snap ??= rows[0].snap;
-                const changes = rows.filter((r) => r.row).map((r) => this.rebuildChange(r.row)).filter((c) => this.ours(c.row));
-                if (changes.length) {
-                    await this.apply(q, changes, rep, null);
-                    rep.changes += changes.length;
-                }
-            }
-            await q.unsafe('close letopis_rebuild');
-            const failed = { ...(meta.failed ?? {}) };
-            delete failed[tenant];
-            const next = { ...meta, resync: { ...(meta.resync ?? {}), [tenant]: snap }, since: { ...(meta.since ?? {}), [tenant]: await this.now(q) } };
-            if (next.retenant?.[tenant]) {
-                const { [tenant]: _drop, ...rest } = next.retenant;
-                void _drop;
-                if (Object.keys(rest).length)
-                    next.retenant = rest;
-                else
-                    delete next.retenant;
-            }
-            await this.advance(q, meta.cursor, withFailed(next, failed));
-            rep.rebuilds++;
-        });
-    }
-    /** Предусловия перестройки одного арендатора (как у rebuild({ tenant })). */
-    tenantAdmit(meta, tenant) {
-        if (!meta.cursor || meta.state === 'rebuilding') {
-            throw new LetopisError('rebuild_required', `проектор ${this.name}: проекции ещё нет или идёт перестройка пачками — сначала run() или rebuild()`);
-        }
-        if (meta.version !== this.def.version)
-            throw this.versionError(meta);
-        const sc = this.scopes.get(tenant);
-        if (!sc) {
-            throw new LetopisError('tenant_denied', `проектор ${this.name}: арендатор ${tenant} не участник — у него не все классы ${this.def.into.join(', ')} помечены derivedBy: '${this.name}'${this.only ? ' или его нет в списке tenants' : ''}`);
-        }
-        if (this.blind.has(tenant))
-            throw this.blindError(tenant);
-        return sc;
-    }
-    /**
-     * Начало перестройки арендатора пачками: его производные строки удаляются, отметка выбывшего снимается, в чекпоинт
-     * встают пустая карта пачек и время начала. auto — путь run(): занятая блокировка — 'busy', а не projector_busy.
-     */
-    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';
-                await this.resolve(q);
-                const meta = await this.state(q);
-                if (auto) {
-                    // автоматический путь: арендатор, который с последнего прохода перестал подходить (не участник, источник без
-                    // журнала), выбывает с причиной, а не останавливает run() для всех (автоматическое ревью коммита 2b229d2)
-                    if (!meta.cursor || meta.state === 'rebuilding' || meta.version !== this.def.version)
-                        return 'skip';
-                    if (!this.scopes.has(tenant) || this.blind.has(tenant)) {
-                        const failed = { ...(meta.failed ?? {}) };
-                        failed[tenant] = this.scopes.has(tenant) ? this.blindFailure(tenant, meta.cursor)
-                            : { cursor: meta.cursor, code: 'tenant_denied', message: `проектор ${this.name}: арендатор ${tenant} больше не участник` };
-                        await this.advance(q, meta.cursor, withFailed(meta, failed));
-                        return 'skip';
-                    }
-                }
-                this.tenantAdmit(meta, tenant);
-                await this.clear(q, [tenant]);
-                const failed = { ...(meta.failed ?? {}) };
-                delete failed[tenant];
-                const now = await this.now(q);
-                const resync = { ...(meta.resync ?? {}) };
-                delete resync[tenant];
-                const next = { ...meta, retenant: { ...(meta.retenant ?? {}), [tenant]: { last: null, chunks: [] } },
-                    since: { ...(meta.since ?? {}), [tenant]: now }, resync, tenants: [...new Set([...(meta.tenants ?? this.tenants), tenant])] };
-                if (!Object.keys(resync).length)
-                    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')
-                    rep.skipped++;
-                return r;
-            }
-            await new Promise((res) => setTimeout(res, 20));
-        }
-    }
-    /**
-     * Пачка перестройки арендатора: своя транзакция и свой снимок. Ошибка данных арендатора — он выбывает с её кодом,
-     * его частично построенные строки удаляются, перестройка снимается; источников больше нет — перестройка закончена.
-     */
-    async tenantChunk(rep, tenant) {
-        return this.tx(async (q) => {
-            if (!(await this.lock(q))) {
-                rep.skipped++;
-                return 'busy';
-            }
-            if (this.due())
-                await this.resolve(q);
-            const meta = await this.state(q);
-            const rt = meta.retenant?.[tenant];
-            if (!rt || rt.done || meta.failed?.[tenant] || meta.state === 'rebuilding')
-                return 'done';
-            const sc = this.scopes.get(tenant);
-            const failed = { ...(meta.failed ?? {}) };
-            if (!sc || this.blind.has(tenant)) {
-                failed[tenant] = sc ? this.blindFailure(tenant, meta.cursor) : { cursor: meta.cursor, code: 'tenant_denied', message: `арендатор ${tenant} больше не участник проектора ${this.name}` };
-            }
-            else {
-                const rows = await q.unsafe(`with s as (select pg_current_snapshot()::text as snap)
-          select s.snap, case when e.id is null then null else ${rowJson('e')} end as row
-          from s left join lateral (select x.* from ${this.env.S}.entity x
-            where x.class = any ($1::text[]) and x.tenant = $4::uuid and ($2::uuid is null or x.id > $2::uuid)
-            order by x.id limit $3) e on true`, [[...sc.from], rt.last, this.batch, tenant]);
-                const real = rows.filter((r) => r.row);
-                if (!real.length) {
-                    await this.advance(q, meta.cursor, { ...meta, retenant: { ...meta.retenant,
-                            [tenant]: { last: rt.last, chunks: [...rt.chunks, { upto: LAST_ID, snap: rows[0].snap }], done: true } } });
-                    rep.rebuilds++;
-                    return 'done';
-                }
-                const changes = real.map((r) => this.rebuildChange(r.row)).filter((c) => this.ours(c.row, failed));
-                if (changes.length)
-                    await this.apply(q, changes, rep, failed, meta.cursor);
-                rep.changes += changes.length;
-                if (!failed[tenant]) {
-                    const last = real[real.length - 1].row.id;
-                    await this.advance(q, meta.cursor, { ...meta, retenant: { ...meta.retenant, [tenant]: { last, chunks: [...rt.chunks, { upto: last, snap: rows[0].snap }] } } });
-                    return 'more';
-                }
-            }
-            // выбыл посреди перестройки — без производных строк: прежние пачки построили их лишь частично
-            await this.clear(q, [tenant]);
-            const { [tenant]: _drop, ...rest } = meta.retenant ?? {};
-            void _drop;
-            const next = { ...meta };
-            if (Object.keys(rest).length)
-                next.retenant = rest;
-            else
-                delete next.retenant;
-            await this.advance(q, meta.cursor, withFailed(next, failed));
-            return 'done';
-        });
-    }
-    /**
-     * Перестройка арендаторов пачками — проход run(): с start (onExpired: 'rebuild') начинает её у каждого выбывшего по
-     * cursor_expired, затем продвигает на пачку каждую начатую — автоматическую и прерванную rebuild({ tenant, chunked:
-     * true }). true — работа ещё осталась.
-     */
-    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;
-        // новые участники — начальная перестройка пачками и без onExpired (план 2.0, 7.4 №5)
-        const newcomers = this.newcomers;
-        this.newcomers = [];
-        for (const t of newcomers)
-            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 = start || newcomers.length ? 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;
-    }
-    /** Повторять 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) => {
-            const done = () => {
-                clearTimeout(t);
-                this.wake = null;
-                resolve();
-            };
-            const t = setTimeout(done, this.pollMs);
-            this.wake = done;
-        });
-    }
-}