letopis 1.0.1 → 1.2.0

package/dist/load.js

@@ -9,6 +9,9 @@
  *   await db.load({ Org: orgs, Staff: staff })            // объект «класс → строки»
  *   await db.load(rows)                                    // массив или поток строк с полем $class
  *
+ * Первая заливка (план 1.1, §2.3, этап 3) — load(rows, { initial: true }) и initialSession: пустая схема,
+ * одна транзакция, без индексов и триггеров на время COPY (FREEZE), перестройка в конце.
+ *
  * Строка — объект: поля данных и роли концов на верхнем уровне; $class — класс строки, $ext —
  * внешний ключ класса без ключа (повторяемый импорт), $tags — теги, $owner — владелец (аккаунт; не
  * с { as }: там владелец по ownerDefault). Значение конца — id, { $key: [...] } или { $ext: '…' }, у
@@ -17,19 +20,24 @@
 import { randomUUID } from 'node:crypto';
 import { LetopisError, fromDbError, removed } from './errors.js';
 import { isOp } from './ops.js';
-import { Registry } from './registry.js';
+import { Registry, aggregateFields } from './registry.js';
 import { accepts } from './sql.js';
 import { v5Id } from './uuid.js';
 import { applyDefaults } from './validate.js';
 import { isInc } from './write.js';
+import { ACL_CLASS_NAMES } from './types.js';
 const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
-/** Классы, строки которых меняют права: загрузка их строк повышает счётчик изменений прав. */
-const ACL_CLASSES = ['rule', 'Resource', 'member', 'Account', 'Class'];
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Классы, строки которых первая заливка сохраняет и возвращает: описания классов, аккаунты, членства, права. */
+const SYSTEM_CLASSES = ['Class', 'Account', 'member', 'Resource', 'rule'];
+// значения без обратной косой, табуляции и переводов строки (почти все: uuid, числа, время) — как есть, без четырёх
+// замен (профиль первой заливки: esc — 14 % процессора)
+const ESCAPED = /[\\\t\n\r]/;
 const esc = (v) => {
     if (v === null || v === undefined)
         return '\\N';
-    return String(v).replace(/\\/g, '\\\\').replace(/\t/g, '\\t').replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+    const s = String(v);
+    return ESCAPED.test(s) ? s.replace(/\\/g, '\\\\').replace(/\t/g, '\\t').replace(/\n/g, '\\n').replace(/\r/g, '\\r') : s;
 };
 const hex = (b) => (b ? '\\x' + b.toString('hex') : null);
 const ENTITY_COLS = 'id, rev, class, cv, tenant, owner, links, data, tags, at, created_at, author, agent, op, reason, moved, prev_hash, validator';
@@ -147,6 +155,10 @@ function shape(reg, tenant, cls, raw, check) {
             data[k] = v;
         }
     }
+    // агрегатные поля считает база (план 1.1, §2.4): переданное значение не пишется — 0, итог посчитает триггер
+    // после оператора, а первая заливка — agg_fill
+    for (const f of aggregateFields(cls))
+        data[f] = 0;
     if (!check)
         return { data, links };
     const scan = (v, path) => {
@@ -260,10 +272,16 @@ function classGroups(reg, names) {
             visit(n);
     return groups;
 }
+/** Строки COPY уходят кусками примерно такой длины: postgres.js шлёт каждую запись в поток отдельным CopyData. */
+const COPY_CHUNK = 262144;
+/** Уступить циклу событий: запись в сокет и колбэки потока COPY идут в нём же. */
+const tick = () => new Promise((r) => setImmediate(r));
 /**
  * COPY … from stdin. postgres.js 3.4 теряет ошибку сервера, пришедшую после конца потока: запрос
  * уже разрешён потоком, а колбэк завершения не вызывается — промис повис бы. Поэтому reject
- * запроса перехватывается до начала потока и отклоняет ожидание.
+ * запроса перехватывается до начала потока и отклоняет ожидание. Строки склеиваются в куски до
+ * COPY_CHUNK символов: запись в сокет на каждую строку стоила дороже подготовки самой строки
+ * (замер первой заливки, план 1.1, этап 3), а границы сообщений протокол COPY не связывает со строками.
  */
 async function copyLines(conn, text, lines) {
     if (!lines.length)
@@ -288,7 +306,10 @@ async function copyLines(conn, text, lines) {
         let i = 0;
         const pump = () => {
             while (i < lines.length) {
-                if (!w.write(lines[i++])) {
+                let chunk = lines[i++];
+                while (i < lines.length && chunk.length < COPY_CHUNK)
+                    chunk += lines[i++];
+                if (!w.write(chunk)) {
                     w.once('drain', pump);
                     return;
                 }
@@ -298,6 +319,23 @@ async function copyLines(conn, text, lines) {
         pump();
     });
 }
+/** verify: true — загруженные строки перепроверяет проверка базы (данные и цели концов); нарушения — в to. */
+async function verifyIds(conn, S, ids, to) {
+    const bad = await conn.unsafe(`select e.id, e.class, ${S}.validate_data(c.data->'resolved'->'rules', c.validator, c.data->'resolved'->'vars', e.data) as issues
+    from ${S}.entity e cross join lateral ${S}.class_row(e.class, e.tenant) c
+    where e.id = any ($1::uuid[]) and ${S}.validate_data(c.data->'resolved'->'rules', c.validator, c.data->'resolved'->'vars', e.data) <> '[]'::jsonb limit ${ISSUES_LIMIT}`, [ids]);
+    for (const r of bad)
+        to.add({ line: 0, code: 'invalid_data', message: `проверка базы: строка ${r.id} не проходит описание класса ${r.class}`, id: r.id, issues: r.issues });
+    if (bad.length >= ISSUES_LIMIT)
+        to.unchecked.add(`проверка базы называет не больше ${ISSUES_LIMIT} строк`);
+    const [t] = await conn.unsafe(`select ${S}.targets_bad((select jsonb_agg(jsonb_build_object('class', e.class, 'tenant', e.tenant, 'links', e.links))
+    from ${S}.entity e where e.id = any ($1::uuid[]) and e.links <> '{}'::jsonb), false) as role`, [ids]);
+    const role = t?.role;
+    if (role?.startsWith('!'))
+        to.add({ line: 0, code: 'derived_class', message: `проверка базы: конец ${role.slice(1)} ведёт на строку производного класса` });
+    else if (role)
+        to.add({ line: 0, code: 'target_not_found', message: `проверка базы: цель конца ${role} не найдена` });
+}
 /**
  * Загрузить строки (§2.6). Одна транзакция (или порции commitEvery): описания классов под
  * разделяемыми блокировками семейств, проверки в коде, COPY пачками, запрос по целям вне загрузки,
@@ -316,6 +354,16 @@ export async function load(env, input, opts = {}) {
         throw new LetopisError('invalid_data', 'load({ as }) и режим истории несовместимы: историю импортирует администратор');
     if (opts.withHistory && opts.existing === 'update')
         throw new LetopisError('invalid_data', "режим истории: existing — 'error' или 'skip' (новую версию существующего объекта пишет загрузка без истории)");
+    const ini = env.session ?? null;
+    if (opts.initial || ini) {
+        // снятые индексы и TRUNCATE — одна транзакция; в пустой схеме пропускать и обновлять нечего
+        if (opts.commitEvery)
+            throw new LetopisError('invalid_data', 'первая заливка (initial) несовместима с commitEvery: снятые индексы и TRUNCATE требуют одной транзакции');
+        if (opts.existing !== undefined && opts.existing !== 'error')
+            throw new LetopisError('invalid_data', "первая заливка (initial): existing — только 'error', в пустой схеме пропускать и обновлять нечего");
+        if (asAcc !== undefined)
+            throw new LetopisError('invalid_data', 'первая заливка (initial) — от администратора, без { as }');
+    }
     const tenant = opts.tenant ?? asAcc ?? env.tenant;
     if (!tenant)
         throw new LetopisError('invalid_data', 'load(): нет арендатора — сессия без арендатора и не задан { tenant }');
@@ -330,6 +378,13 @@ export async function load(env, input, opts = {}) {
     const report = { rows: rows.length, loaded: 0, updated: 0, skipped: 0, duplicates: 0, byClass: {}, external: 0, portions: 0, ms: 0 };
     if (!rows.length)
         return report;
+    // первая заливка одной загрузкой — своя сессия; вход уже прочитан (поток второй раз не читается)
+    if (opts.initial && !ini) {
+        const r = await initialSession(env, (sess) => sess.load(rows, opts));
+        // время — вместе с перестройкой, отложенными проверками и ANALYZE сессии
+        r.ms = performance.now() - t0;
+        return r;
+    }
     const readRegistry = async (q) => {
         const reg = new Registry();
         reg.load(await q.unsafe(`select tenant, rev, data from ${S}.entity where class = 'Class' and tenant in ($1::uuid, $2::uuid)`, [tenant, SYSTEM_ID]));
@@ -345,7 +400,8 @@ export async function load(env, input, opts = {}) {
     const targets = new Map();
     /** Владельцы ($owner) порции, кроме арендатора: id → первая строка; сверяются запросом в конце. */
     const owners = new Map();
-    const reg0 = await readRegistry(env.sql);
+    // в первой заливке таблицы заблокированы сессией: читать — на её соединении
+    const reg0 = await readRegistry(ini?.conn ?? env.sql);
     const p1 = new Array(rows.length);
     const lineOf = new Map();
     const chosen = new Set();
@@ -370,12 +426,24 @@ export async function load(env, input, opts = {}) {
             p1[i] = null;
             continue;
         }
+        // строки производного класса пишет только его проектор (план 1.1, §2.4)
+        if (cls.derivedBy) {
+            issues.add({ line, code: 'derived_class', message: `класс ${cls.name} производный: его строки пишет проектор ${cls.derivedBy}`, class: cls.name });
+            p1[i] = null;
+            continue;
+        }
         const id = idOfRow(reg0, tenant, cls, raw);
         if (typeof id !== 'string') {
             issues.add({ line, code: 'invalid_data', message: id.error, class: cls.name });
             p1[i] = null;
             continue;
         }
+        // первая заливка: первичного ключа нет — повтор id со строками системных классов и прошлых загрузок сессии ловит проход 1
+        if (ini?.ids.has(id)) {
+            issues.add({ line, code: 'exists', message: 'объект уже есть в схеме: строка системного класса или запись этой же первой заливки', id, class: cls.name });
+            p1[i] = null;
+            continue;
+        }
         p1[i] = { cls, id };
         if (opts.withHistory) {
             const list = versions.get(id) ?? [];
@@ -457,13 +525,16 @@ export async function load(env, input, opts = {}) {
         owners.clear();
         issues.unchecked.clear();
         laterUnchecked(portion, issues);
-        const conn = await env.sql.reserve();
+        // первая заливка: транзакцию, роль и пояс поставила сессия, фиксирует и откатывает тоже она
+        const conn = ini ? ini.conn : await env.sql.reserve();
         const written = [];
         let failed = null;
         try {
-            await conn.unsafe('begin isolation level read committed');
-            await conn.unsafe(`set local role ${`"${env.ownerRole.replace(/"/g, '""')}"`}`);
-            await conn.unsafe(`select set_config('TimeZone', 'UTC', true)`);
+            if (!ini) {
+                await conn.unsafe('begin isolation level read committed');
+                await conn.unsafe(`set local role ${`"${env.ownerRole.replace(/"/g, '""')}"`}`);
+                await conn.unsafe(`select set_config('TimeZone', 'UTC', true)`);
+            }
             // описания классов под разделяемыми блокировками семейств, затем — свежие
             const roots = [...new Set(portion.map((i) => p1[i].cls.ancestors[p1[i].cls.ancestors.length - 1]))].sort();
             // ключ блокировки — арендатор корневого класса и имя корня (корень из System — ключ System)
@@ -531,7 +602,10 @@ export async function load(env, input, opts = {}) {
                 todo = portion.filter((i) => !taken.has(p1[i].id));
             }
             if (opts.withHistory) {
-                await historyWrite(conn, reg, todo, inLoad, external, xid, classesTouched);
+                await historyWrite(conn, reg, todo, inLoad, external, xid, classesTouched, written);
+            }
+            else if (ini) {
+                await pipeline(conn, reg, portion, inLoad, external, ts, xid, classesTouched, written, live, past);
             }
             else {
                 for (let b = 0; b < portion.length; b += batch) {
@@ -541,6 +615,19 @@ export async function load(env, input, opts = {}) {
             }
             if (issues.any)
                 issues.fail();
+            if (ini) {
+                // цели, владельцы, арендатор и проверка базы — в конце сессии, по перестроенным индексам
+                report.external += external.size;
+                ini.pending.push({ reg, tenant: tenant, external, owners: new Map(owners), verify: opts.verify ? written : null });
+                for (const id of inLoad.keys())
+                    ini.ids.add(id);
+                let set = ini.touched.get(tenant);
+                if (!set)
+                    ini.touched.set(tenant, (set = new Set()));
+                for (const c of classesTouched)
+                    set.add(c);
+                return;
+            }
             // цели вне загрузки — один запрос в конце с блокировкой до фиксации (§2.6, п. 7)
             const ext = [...external.keys()].sort();
             report.external += ext.length;
@@ -553,6 +640,9 @@ export async function load(env, input, opts = {}) {
                     if (!f || (f.tenant !== tenant && f.tenant !== SYSTEM_ID) || !accepts(reg, ref.allowed, f.class)) {
                         issues.add({ line: ref.line, code: 'target_not_found', message: `цель конца ${ref.role} не найдена`, id });
                     }
+                    else if (reg.find(f.class)?.derivedBy) {
+                        issues.add({ line: ref.line, code: 'derived_class', message: `цель конца ${ref.role} — строка производного класса ${f.class}`, id });
+                    }
                 }
             }
             // владельцы ($owner) — аккаунты: из загрузки (живые) или из базы, с блокировкой до фиксации
@@ -581,12 +671,18 @@ export async function load(env, input, opts = {}) {
                 issues.add({ line: portion.length ? portion[0] + 1 : 0, code: 'tenant_denied', message: `арендатор ${tenant} не найден или отключён` });
             if (issues.any)
                 issues.fail();
-            if (opts.verify && written.length)
-                await verifyRows(conn, reg, written);
-            if (classesTouched.size)
-                await conn.unsafe(`select pg_notify($1, c) from unnest($2::text[]) c`, [env.schema, [...classesTouched]]);
+            if (opts.verify && written.length) {
+                await verifyIds(conn, S, written, issues);
+                if (issues.any)
+                    issues.fail();
+            }
+            // сигнал — функцией базы, как у триггеров: нагрузка по режиму сигналов установки (план 1.1)
+            if (classesTouched.size) {
+                const touched = [...classesTouched];
+                await conn.unsafe(`select ${S}.signal($1::text[], $2::uuid[])`, [touched, touched.map(() => tenant)]);
+            }
             // строки прав меняют планы: пропуска прав клиентов — заново
-            if ([...classesTouched].some((c) => ACL_CLASSES.includes(c)))
+            if ([...classesTouched].some((c) => ACL_CLASS_NAMES.includes(c)))
                 await conn.unsafe(`select ${S}.acl_bump()`);
             if (portion.length >= 10000)
                 await conn.unsafe(`analyze ${S}.entity; analyze ${S}.log`);
@@ -594,14 +690,16 @@ export async function load(env, input, opts = {}) {
         }
         catch (e) {
             failed = e;
-            await conn.unsafe('rollback').catch(() => { });
+            if (!ini)
+                await conn.unsafe('rollback').catch(() => { });
         }
         finally {
-            conn.release();
+            if (!ini)
+                conn.release();
         }
         if (failed) {
             const err = failed;
-            if (err.code === '23505' && (err.constraint_name === 'entity_pkey' || err.constraint_name === 'log_id_rev')) {
+            if (!ini && err.code === '23505' && (err.constraint_name === 'entity_pkey' || err.constraint_name === 'log_id_rev')) {
                 await explainTaken(portion);
             }
             throw fromDbError(failed);
@@ -691,12 +789,56 @@ export async function load(env, input, opts = {}) {
         }
         return sh;
     }
+    /** Пачка — подготовка и запись по очереди. */
     async function writeBatch(conn, reg, part, inLoad, external, ts, xid, touched, written, live, past) {
+        const p = await prepareBatch(reg, part, inLoad, external, ts, xid, touched, written, live, past, 0);
+        if (p)
+            await flushBatch(conn, p, ts, touched, written);
+    }
+    /**
+     * Первая заливка — конвейером (решение точки А плана 1.1): следующая пачка готовится, пока база пишет текущую.
+     * Подготовка уступает циклу событий каждые 256 строк — иначе COPY в полёте не получал бы следующих кусков, пока
+     * идёт синхронная работа. Отказ записи до её await ловит пустой обработчик (иначе — необработанный отказ
+     * процесса); при ошибке подготовки запись в полёте доходит до конца, и откат идёт по готовому соединению.
+     */
+    async function pipeline(conn, reg, portion, inLoad, external, ts, xid, touched, written, live, past) {
+        let flushing = null;
+        try {
+            for (let b = 0; b < portion.length; b += batch) {
+                const p = await prepareBatch(reg, portion.slice(b, b + batch), inLoad, external, ts, xid, touched, written, live, past, 256);
+                const prev = flushing;
+                flushing = null;
+                if (prev)
+                    await prev;
+                if (!p || issues.any)
+                    return;
+                flushing = flushBatch(conn, p, ts, touched, written);
+                flushing.catch(() => { });
+            }
+            const last = flushing;
+            flushing = null;
+            if (last)
+                await last;
+        }
+        catch (e) {
+            if (flushing)
+                await flushing.catch(() => { });
+            throw e;
+        }
+    }
+    /**
+     * Подготовка пачки без запросов к базе: проверки, id, концы, строки COPY. yieldEvery — уступать циклу событий
+     * каждые столько строк (конвейер первой заливки). Нарушения — null.
+     */
+    async function prepareBatch(reg, part, inLoad, external, ts, xid, touched, written, live, past, yieldEvery) {
         const ent = [];
         const log = [];
         const updates = [];
         const rowsAcl = [];
+        let n = 0;
         for (const i of part) {
+            if (yieldEvery && ++n % yieldEvery === 0)
+                await tick();
             const { id, cls } = p1[i];
             if (existing === 'skip' && (live.has(id) || past.has(id))) {
                 report.skipped++;
@@ -719,10 +861,12 @@ export async function load(env, input, opts = {}) {
             const tags = sh.tags ?? [];
             if (acl)
                 rowsAcl.push({ i, class: cls.name, id, owner, tags, data: sh.data, links: sh.links });
-            const common = [id, rev, cls.name, cur.rev, tenant, owner, JSON.stringify(sh.links), JSON.stringify(sh.data), pgArray(tags), atv];
-            ent.push([...common, atv, author, agent, 'create', null, null, hex(prev?.hash), null].map(esc).join('\t') + '\n');
+            // общая голова строк entity и log — одной сборкой и одним экранированием
+            const head = [id, rev, cls.name, cur.rev, tenant, owner, JSON.stringify(sh.links), JSON.stringify(sh.data), pgArray(tags), atv].map(esc).join('\t');
+            const ph = esc(hex(prev?.hash));
+            ent.push(`${head}\t${esc(atv)}\t${esc(author)}\t${esc(agent)}\tcreate\t\\N\t\\N\t${ph}\t\\N\n`);
             if (cur.history !== false)
-                log.push([...common, author, agent, 'create', null, null, hex(prev?.hash), xid].map(esc).join('\t') + '\n');
+                log.push(`${head}\t${esc(author)}\t${esc(agent)}\tcreate\t\\N\t\\N\t${ph}\t${esc(xid)}\n`);
             report.loaded++;
             report.byClass[cls.name] = (report.byClass[cls.name] ?? 0) + 1;
             touched.add(cls.name);
@@ -731,8 +875,13 @@ export async function load(env, input, opts = {}) {
         if (issues.any) {
             if (aclRan)
                 issues.unchecked.add('условия ACL следующих пачек не проверялись');
-            return;
+            return null;
         }
+        return { ent, log, updates, rowsAcl };
+    }
+    /** Запись подготовленной пачки: условия ACL ({ as }) — запросом на пачку, COPY в entity и log, правки существующих. */
+    async function flushBatch(conn, p, ts, touched, written) {
+        const { ent, log, updates, rowsAcl } = p;
         if (acl) {
             aclRan = true;
             // условия ACL на строки — одним запросом на пачку: файл пользователя — не доверенные данные
@@ -756,11 +905,15 @@ export async function load(env, input, opts = {}) {
             if (issues.any)
                 return;
         }
-        await copyLines(conn, `copy ${S}.entity (${ENTITY_COLS}) from stdin`, ent);
-        await copyLines(conn, `copy ${S}.log (${LOG_COLS}) from stdin`, log);
+        // первая заливка: FREEZE — таблицы опустошены этой же транзакцией. Журнал — раньше строк: агрегатные поля новой
+        // цели триггер после COPY досчитывает в ту же версию — и в entity, и в уже записанную версию журнала (план 1.1, §2.4)
+        await copyLines(conn, `copy ${S}.log (${LOG_COLS}) from stdin${ini?.freeze ? ' with (freeze)' : ''}`, log);
+        await copyLines(conn, `copy ${S}.entity (${ENTITY_COLS}) from stdin${ini?.freeze ? ' with (freeze)' : ''}`, ent);
         if (updates.length) {
-            // новая версия из заблокированных значений — одним оператором; без изменений — без версии
-            const res = await conn.unsafe(`with u as (select * from jsonb_to_recordset($1::jsonb) as x(id uuid, data jsonb, links jsonb, tags text[])),
+            // новая версия из заблокированных значений — одним оператором; без изменений — без версии; агрегатные поля —
+            // прежние (agg_keep): их считает база
+            const res = await conn.unsafe(`with u as (select x.id, ${S}.agg_keep(e.class, e.tenant, e.data, x.data) as data, x.links, x.tags
+            from jsonb_to_recordset($1::jsonb) as x(id uuid, data jsonb, links jsonb, tags text[]) join ${S}.entity e on e.id = x.id),
           up as (
             update ${S}.entity e set data = u.data, links = u.links, tags = coalesce(u.tags, e.tags), rev = e.rev + 1, prev_hash = e.hash,
               at = greatest($2::timestamptz, e.at + interval '1 microsecond'), author = $3::uuid, agent = $4::text, op = 'update',
@@ -782,7 +935,7 @@ export async function load(env, input, opts = {}) {
         }
     }
     /** Режим истории: версии волнами — после каждой волны база отдаёт хэши, они prev_hash следующей. */
-    async function historyWrite(conn, reg, portion, inLoad, external, xid, touched) {
+    async function historyWrite(conn, reg, portion, inLoad, external, xid, touched, written) {
         const byId = new Map();
         for (const i of portion) {
             const id = p1[i].id;
@@ -861,24 +1014,158 @@ export async function load(env, input, opts = {}) {
                 rows[l[0]].$at, SYSTEM_ID, agent, op, null, null, hex(cur.history === false ? null : lastPrev.get(id) ?? null), null].map(esc).join('\t') + '\n');
             report.loaded++;
             report.byClass[cls.name] = (report.byClass[cls.name] ?? 0) + 1;
+            // verify: true проверяет и строки режима истории (в 1.0.1 список был пуст — проверка не шла)
+            written.push(id);
         }
-        await copyLines(conn, `copy ${S}.entity (${ENTITY_COLS}) from stdin`, ent);
+        await copyLines(conn, `copy ${S}.entity (${ENTITY_COLS}) from stdin${ini?.freeze ? ' with (freeze)' : ''}`, ent);
     }
-    /** verify: true — загруженные строки перепроверяет проверка базы (данные и цели концов). */
-    async function verifyRows(conn, reg, ids) {
-        const bad = await conn.unsafe(`select e.id, e.class, ${S}.validate_data(c.data->'resolved'->'rules', c.validator, c.data->'resolved'->'vars', e.data) as issues
-      from ${S}.entity e cross join lateral ${S}.class_row(e.class, e.tenant) c
-      where e.id = any ($1::uuid[]) and ${S}.validate_data(c.data->'resolved'->'rules', c.validator, c.data->'resolved'->'vars', e.data) <> '[]'::jsonb limit ${ISSUES_LIMIT}`, [ids]);
-        for (const r of bad)
-            issues.add({ line: 0, code: 'invalid_data', message: `проверка базы: строка ${r.id} не проходит описание класса ${r.class}`, id: r.id, issues: r.issues });
-        if (bad.length >= ISSUES_LIMIT)
-            issues.unchecked.add(`проверка базы называет не больше ${ISSUES_LIMIT} строк`);
-        const [t] = await conn.unsafe(`select ${S}.targets_bad((select jsonb_agg(jsonb_build_object('class', e.class, 'tenant', e.tenant, 'links', e.links))
-      from ${S}.entity e where e.id = any ($1::uuid[]) and e.links <> '{}'::jsonb), false) as role`, [ids]);
-        if (t?.role)
-            issues.add({ line: 0, code: 'target_not_found', message: `проверка базы: цель конца ${t.role} не найдена` });
-        void reg;
+}
+/** Определения из каталога: ограничения (первичный ключ, уникальные), прочие индексы, триггеры с режимом, колонки. */
+async function catalogOf(conn, S) {
+    const rels = [`${S}.entity`, `${S}.log`];
+    const sel = `(select x::regclass from unnest($1::text[]) x)`;
+    const constraints = await conn.unsafe(`select conname as name, conrelid::regclass::text as tbl, pg_get_constraintdef(oid) as def
+    from pg_constraint where conrelid in ${sel} and contype in ('p', 'u') order by conrelid, conname`, [rels]);
+    const indexes = await conn.unsafe(`select i.indexrelid::regclass::text as name, pg_get_indexdef(i.indexrelid) as def
+    from pg_index i where i.indrelid in ${sel}
+      and not exists (select 1 from pg_constraint c where c.conindid = i.indexrelid and c.conrelid = i.indrelid and c.contype in ('p', 'u', 'x'))
+    order by i.indrelid, i.indexrelid`, [rels]);
+    const triggers = await conn.unsafe(`select tgname as name, tgrelid::regclass::text as tbl, pg_get_triggerdef(oid) as def, tgenabled::text as enabled
+    from pg_trigger where tgrelid in ${sel} and not tgisinternal order by tgrelid, tgname`, [rels]);
+    // колонки без генерируемых: их значения считает база
+    const cols = async (rel) => (await conn.unsafe(`select string_agg(quote_ident(attname), ', ' order by attnum) as c from pg_attribute
+    where attrelid = $1::regclass and attnum > 0 and not attisdropped and attgenerated = ''`, [rel]))[0].c;
+    return {
+        constraints: constraints,
+        indexes: indexes,
+        triggers: triggers,
+        entityCols: await cols(rels[0]),
+        logCols: await cols(rels[1]),
+    };
+}
+/**
+ * Первая заливка (план 1.1, §2.3): загрузки fn — одной транзакцией в пустую схему. Блокировка таблиц до
+ * проверки; в схеме только строки системных классов и записи reset (иначе not_empty); они (с seq и tx
+ * журнала) и определения ограничений, индексов и триггеров из каталога (с режимом включения tgenabled:
+ * pg_get_triggerdef его не передаёт) сохраняются в памяти; TRUNCATE; триггеры, ограничения и индексы
+ * снимаются — BEFORE ROW делает COPY построчным одним своим наличием, триггеры после оператора копят
+ * переходные таблицы; системные строки возвращаются (seq журнала — generated always: overriding system
+ * value); загрузки пишут COPY FREEZE. В конце — ограничения (дубликат найдёт сортировка), индексы,
+ * триггеры с прежним режимом, отложенные проверки загрузок, сигнал, счётчик прав и ANALYZE. Любая ошибка
+ * откатывает всё: DDL в PostgreSQL транзакционен.
+ */
+export async function initialSession(env, fn, tune = {}) {
+    if (!env.admin)
+        throw new LetopisError('admin_required', 'загрузчику нужно администраторское подключение (connect({ allowBypassRls: true }) роли, которая может стать владельцем схемы)');
+    const S = `"${env.schema.replace(/"/g, '""')}"`;
+    const ident = (n) => `"${n.replace(/"/g, '""')}"`;
+    const conn = await env.sql.reserve();
+    const q = (text, params = []) => conn.unsafe(text, params);
+    try {
+        await q('begin isolation level read committed');
+        await q(`set local role ${ident(env.ownerRole)}`);
+        await q(`select set_config('TimeZone', 'UTC', true)`);
+        // 1. блокировка — до проверки: строка, вставленная между проверкой и TRUNCATE, пропала бы молча
+        await q(`lock table ${S}.entity, ${S}.log in access exclusive mode`);
+        // 2. пустая схема: кроме строк системных классов и записей reset — ничего
+        const [busy] = await q(`select exists (select 1 from ${S}.entity where class <> all ($1::text[]))
+        or exists (select 1 from ${S}.log where class <> all ($2::text[])) as b`, [SYSTEM_CLASSES, [...SYSTEM_CLASSES, '#reset']]);
+        if (busy.b) {
+            throw new LetopisError('not_empty', 'первая заливка — только в пустую схему: в entity и log, кроме строк системных классов (Class, Account, member, Resource, rule) и записей reset, ничего быть не должно');
+        }
+        // 3. системные строки и определения из каталога — в память процесса (так режим не повторяет 10-core.sql)
+        const [sys] = await q(`select coalesce((select jsonb_agg(to_jsonb(e)) from ${S}.entity e), '[]') as ent,
+        coalesce((select jsonb_agg(to_jsonb(l)) from ${S}.log l), '[]') as log`);
+        const ids = new Set([...sys.ent, ...sys.log].map((r) => r.id));
+        const cat = await catalogOf(conn, S);
+        const triggers = tune.keepTriggers ? [] : cat.triggers;
+        const keys = tune.keepKeys ? [] : cat.constraints;
+        const indexes = cat.indexes.filter((i) => !(tune.keepGin && /\busing gin\b/i.test(i.def)));
+        // 4. TRUNCATE; триггеры, ограничения и индексы — снять
+        await q(`truncate ${S}.entity, ${S}.log`);
+        for (const t of triggers)
+            await q(`drop trigger ${ident(t.name)} on ${t.tbl}`);
+        for (const c of keys)
+            await q(`alter table ${c.tbl} drop constraint ${ident(c.name)}`);
+        for (const i of indexes)
+            await q(`drop index ${i.name}`);
+        // 5. системные строки — обратно, с прежними seq и tx
+        await q(`insert into ${S}.entity (${cat.entityCols}) select ${cat.entityCols} from jsonb_populate_recordset(null::${S}.entity, $1::jsonb)`, [sys.ent]);
+        await q(`insert into ${S}.log (${cat.logCols}) overriding system value select ${cat.logCols} from jsonb_populate_recordset(null::${S}.log, $1::jsonb)`, [sys.log]);
+        const state = { conn: conn, ids, pending: [], touched: new Map(), freeze: tune.freeze !== false };
+        const out = await fn({
+            sql: conn,
+            load: (input, opts = {}) => load({ ...env, session: state }, input, opts),
+            taken: (id) => state.ids.has(id.toLowerCase()),
+        });
+        // 6. агрегаты в базе (план 1.1, §2.4): триггеров нет — поле целей считает agg_fill, одним оператором на агрегат, и
+        // пишет его в ту же (последнюю) версию в entity и log: строки ещё никто не видел, хэши — генерируемые колонки
+        await q(`select ${S}.agg_fill()`);
+        // 7. ограничения, затем индексы; память и параллельные исполнители сборки — не меньше серверных
+        await q(`select set_config('maintenance_work_mem', (greatest(pg_size_bytes(current_setting('maintenance_work_mem')), 268435456) / 1024)::bigint || 'kB', true),
+      set_config('max_parallel_maintenance_workers', greatest(current_setting('max_parallel_maintenance_workers')::int,
+        least(current_setting('max_parallel_workers')::int, 4))::text, true)`);
+        for (const c of keys)
+            await q(`alter table ${c.tbl} add constraint ${ident(c.name)} ${c.def}`);
+        for (const i of indexes)
+            await q(i.def);
+        // 8. триггеры — с прежним режимом включения (ENABLE ALWAYS работает и при session_replication_role = replica)
+        for (const t of triggers) {
+            await q(t.def);
+            const mode = t.enabled === 'A' ? 'enable always' : t.enabled === 'R' ? 'enable replica' : t.enabled === 'D' ? 'disable' : null;
+            if (mode)
+                await q(`alter table ${t.tbl} ${mode} trigger ${ident(t.name)}`);
+        }
+        // 10. отложенные проверки загрузок, сигнал, счётчик прав
+        const issues = new Issues();
+        for (const p of state.pending) {
+            const ext = [...p.external.keys()].sort();
+            if (ext.length) {
+                const found = new Map((await q(`select e.id, e.tenant, e.class from ${S}.entity e where e.id = any ($1::uuid[])`, [ext]))
+                    .map((r) => [r.id, r]));
+                for (const id of ext) {
+                    const ref = p.external.get(id);
+                    const f = found.get(id);
+                    if (!f || (f.tenant !== p.tenant && f.tenant !== SYSTEM_ID) || !accepts(p.reg, ref.allowed, f.class)) {
+                        issues.add({ line: ref.line, code: 'target_not_found', message: `цель конца ${ref.role} не найдена`, id });
+                    }
+                    else if (p.reg.find(f.class)?.derivedBy) {
+                        issues.add({ line: ref.line, code: 'derived_class', message: `цель конца ${ref.role} — строка производного класса ${f.class}`, id });
+                    }
+                }
+            }
+            if (p.owners.size) {
+                const own = [...p.owners.keys()].sort();
+                const found = new Set((await q(`select e.id from ${S}.entity e where e.id = any ($1::uuid[]) and e.class = 'Account'`, [own])).map((r) => r.id));
+                for (const id of own)
+                    if (!found.has(id))
+                        issues.add({ line: p.owners.get(id), code: 'target_not_found', message: `владелец ${id} не найден`, id });
+            }
+            const [acc] = await q(`select coalesce((data->>'enabled')::boolean, true) as enabled from ${S}.entity where id = $1::uuid and class = 'Account'`, [p.tenant]);
+            if (!acc || !acc.enabled)
+                issues.add({ line: 0, code: 'tenant_denied', message: `арендатор ${p.tenant} не найден или отключён` });
+            if (p.verify?.length)
+                await verifyIds(conn, S, p.verify, issues);
+        }
         if (issues.any)
             issues.fail();
+        const pairs = [...state.touched].flatMap(([t, cs]) => [...cs].map((c) => [c, t]));
+        if (pairs.length)
+            await q(`select ${S}.signal($1::text[], $2::uuid[])`, [pairs.map((x) => x[0]), pairs.map((x) => x[1])]);
+        if (pairs.some(([c]) => ACL_CLASS_NAMES.includes(c)))
+            await q(`select ${S}.acl_bump()`);
+        // ANALYZE обязателен: в PostgreSQL до 18.6 параллельная сборка GIN могла записать неверный reltuples (вплоть
+        // до бесконечности), и автоочистка переставала обрабатывать таблицу
+        await q(`analyze ${S}.entity`);
+        await q(`analyze ${S}.log`);
+        await q('commit');
+        return out;
+    }
+    catch (e) {
+        await q('rollback').catch(() => { });
+        throw e instanceof LetopisError ? e : fromDbError(e);
+    }
+    finally {
+        conn.release();
     }
 }

package/dist/mcp.d.ts

@@ -0,0 +1,28 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { Db } from './index.js';
+export interface McpOptions {
+    /** Инструмент letopis_write (create, update, upsert, delete); по умолчанию сервер только читает. */
+    write?: boolean;
+    /** Строк в ответе не больше (по умолчанию 100); дальше — курсор. */
+    maxRows?: number;
+    /** Байт JSON строк в ответе не больше (по умолчанию 50 000); дальше — курсор. */
+    maxBytes?: number;
+    /**
+     * letopis_write пишет и классы прав — rule, Resource, member, Account, Class и их потомков (правила, членства,
+     * описания классов). По умолчанию — отказ acl_denied: агент под инъекцией в данных выдал бы постороннему членство или
+     * правило без подтверждения человека (ревью безопасности №2, О5).
+     */
+    allowAclWrite?: boolean;
+    /**
+     * Сессия в арендаторе System — так работает системный администратор: его роль admin даёт права на аккаунты,
+     * членства, правила и letopis.*. По умолчанию — отказ user_session_required (ревью безопасности №2, О5).
+     */
+    allowSystemAdmin?: boolean;
+}
+/**
+ * Сервер MCP для одного пользователя letopis: инструменты letopis_model, letopis_query, letopis_history и при
+ * { write: true } — letopis_write. Подключение — сессия пользователя (connect({ token })) или фасад db.as(пользователь).
+ * Транспорт выбирает приложение: server.connect(транспорт), serveStdio(() => createMcpServer(db)) или
+ * createMcpHandler(() => createMcpServer(db)) SDK — со своей авторизацией.
+ */
+export declare function createMcpServer(db: Db, opts?: McpOptions): Promise<McpServer>;