letopis 1.0.1 → 1.1.0

package/dist/import.js

@@ -26,6 +26,7 @@ import { normalizeSchema } from './jsonschema.js';
 import { RESERVED_CLASS_NAMES } from './types.js';
 import { base32Decode } from './auth.js';
 import { v5Id } from './uuid.js';
+import { initialSession } from './load.js';
 const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
 const SYSTEM_CLASSES = new Set(['Class', 'Account', 'member', 'Resource', 'rule']);
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -427,6 +428,9 @@ const quote = (s) => `"${s.replace(/"/g, '""')}"`;
 export async function import021(opts) {
     const t0 = performance.now();
     const log = opts.quiet ? () => { } : (m) => console.log(`letopis.import: ${m}`);
+    if (opts.initial && (opts.update || opts.commitEvery)) {
+        throw new LetopisError('invalid_data', 'import --initial несовместим с --update и --commit-every: первая заливка — одна транзакция в пустую схему');
+    }
     const partition = opts.partition ?? 'entity';
     const owner = opts.owner ?? 'letopis_owner';
     const src = typeof opts.from === 'string' ? postgres(opts.from, { max: 2, onnotice: () => { } }) : opts.from;
@@ -557,195 +561,212 @@ export async function import021(opts) {
             resources: { loaded: 0, skipped: 0 }, rules: { loaded: 0, skipped: 0 }, objects: { loaded: 0, skipped: 0, updated: 0 },
             uuidFields: {}, droppedFields: {}, ownerLost: 0, verify: { ok: false, issues: 0, anchor: '' }, ms: 0,
         };
-        // --- шаг 1: классы (System, от владельца), предки раньше потомков ---
-        await dst.begin(async (tx) => {
-            await tx.unsafe(`set local role ${quote(owner)}`);
-            for (const r of schemaRows) {
-                const c = b.classes.get(r.id);
-                if (!c)
-                    continue;
-                const [ex] = await tx.unsafe(`select 1 from ${S}.entity where class = 'Class' and data->>'name' = $1`, [c.name]);
-                if (ex) {
-                    report.classes.existing.push(c.name);
-                    continue;
-                }
-                await tx.unsafe(`select ${S}.sys_create(${S}.v5_id($1::uuid, 'Class', array[$2]), 'Class', $1::uuid, '{}', $3::jsonb)`, [SYSTEM_ID, c.name, c.desc]).catch((e) => {
-                    e.message = `import: класс ${c.name}: ${e.message}`;
-                    throw e;
-                });
-                report.classes.created.push(c.name);
-            }
-            await tx.unsafe(`select pg_notify($1, 'Class')`, [opts.schema]);
-        });
-        log(`классы: создано ${report.classes.created.length}, уже были ${report.classes.existing.length}, опущено ${b.omitted.length}`);
-        // --- шаг 2: аккаунты (System) и арендатор данных System ---
-        const accRows = [];
-        for (const a of accounts) {
-            if (systemOld.has(a.id))
-                continue;
-            const data = (a.data ?? {});
-            const name = typeof data.name === 'string' ? data.name : typeof data.id === 'string' ? data.id : a.id;
-            accRows.push({ $class: 'Account', $ext: a.id, name, categories: a.categories.filter((c) => c !== 'System'), enabled: a.enabled !== false });
-        }
-        if (sysTenant)
-            accRows.push({ $class: 'Account', $ext: `tenant:${opts.tenant}`, name: opts.tenant, categories: [], enabled: true });
-        if (accRows.length) {
-            const r = await db.load(accRows, { tenant: SYSTEM_ID, existing: 'skip', agent: 'letopis import' });
-            report.accounts = { loaded: r.loaded, skipped: r.skipped };
-        }
-        // --- шаг 3: креды → secret (от владельца; хэши как есть); совпадение без учёта регистра — первым идёт
-        // подтверждённый, затем более ранний, остальные — в отчёт ---
-        const creds = await src.unsafe(`select account::text as account, category, identifier, meta, confirmed from ${F}."Credential" where deleted is null order by confirmed desc, created, id`);
-        const secretRows = [];
-        for (const c of creds) {
-            const m = (c.meta ?? {});
-            const account = accId(c.account);
-            const kind = String(c.category);
-            const confirmed = c.confirmed !== false;
-            if (kind === 'OTP' || kind.startsWith('OTP_') || typeof m.code === 'string') {
-                report.credentials.otp++;
-                continue;
-            }
-            if (typeof m.password === 'string')
-                secretRows.push({ account, kind, ident: c.identifier, material: Buffer.from(m.password, 'utf8'), meta: { confirmed } });
-            else if (kind === 'APIKEY')
-                secretRows.push({ account, kind, ident: String(m.prefix ?? ''), material: Buffer.from(String(c.identifier), 'hex'), meta: { ...(m.name ? { name: m.name } : {}), confirmed: true } });
-            else if (kind === 'KEYSECRET')
-                secretRows.push({ account, kind, ident: c.identifier, material: Buffer.from(String(m.secret ?? ''), 'hex'), meta: { ...(m.name ? { name: m.name } : {}), confirmed: true } });
-            else if (kind === 'TOTP')
-                secretRows.push({ account, kind, ident: account, material: base32Decode(String(m.secret ?? '')), meta: { confirmed, last_step: Number(m.lastStep ?? 0) } });
-            else
-                secretRows.push({ account, kind, ident: c.identifier, material: null, meta: { ...m, confirmed } });
-        }
-        if (secretRows.length) {
-            await dst.begin(async (tx) => {
-                await tx.unsafe(`set local role ${quote(owner)}`);
-                for (const s of secretRows) {
-                    const [dup] = await tx.unsafe(`select account::text as account from ${S}.secret
-            where kind = $1 and casefold(ident) collate pg_unicode_fast = casefold($2) collate pg_unicode_fast and deleted_at is null`, [s.kind, s.ident]);
-                    if (dup) {
-                        if (dup.account === s.account)
-                            report.credentials.skipped++;
-                        else
-                            report.credentials.conflicts.push({ account: s.account, kind: s.kind, ident: s.ident });
+        const steps = async (x) => {
+            // --- шаг 1: классы (System, от владельца), предки раньше потомков ---
+            await x.begin(async (tx) => {
+                for (const r of schemaRows) {
+                    const c = b.classes.get(r.id);
+                    if (!c)
+                        continue;
+                    const [ex] = await tx.unsafe(`select 1 from ${S}.entity where class = 'Class' and data->>'name' = $1`, [c.name]);
+                    if (ex) {
+                        report.classes.existing.push(c.name);
                         continue;
                     }
-                    await tx.unsafe(`insert into ${S}.secret (account, kind, ident, material, meta) values ($1::uuid, $2, $3, $4, $5::jsonb)`, [s.account, s.kind, s.ident, s.material, s.meta]);
-                    report.credentials.imported++;
+                    await tx.unsafe(`select ${S}.sys_create(${S}.v5_id($1::uuid, 'Class', array[$2]), 'Class', $1::uuid, '{}', $3::jsonb)`, [SYSTEM_ID, c.name, c.desc]).catch((e) => {
+                        e.message = `import: класс ${c.name}: ${e.message}`;
+                        throw e;
+                    });
+                    report.classes.created.push(c.name);
                 }
+                // сигнал — функцией базы: нагрузка по режиму сигналов установки (план 1.1)
+                await tx.unsafe(`select ${S}.signal(array['Class'], array[$1::uuid])`, [SYSTEM_ID]);
             });
-        }
-        // --- шаг 4: права — Resource и rule в System ---
-        const resources = await src.unsafe(`select alias, category, pattern, meta from ${F}."Resource" order by alias`);
-        const resRows = resources.map((r) => {
-            let pattern = r.pattern;
-            if (isObj(pattern) && 'account' in pattern) {
-                const { account, ...rest } = pattern;
-                pattern = { ...rest, tenant: account };
+            log(`классы: создано ${report.classes.created.length}, уже были ${report.classes.existing.length}, опущено ${b.omitted.length}`);
+            // --- шаг 2: аккаунты (System) и арендатор данных System ---
+            const accRows = [];
+            for (const a of accounts) {
+                if (systemOld.has(a.id))
+                    continue;
+                const data = (a.data ?? {});
+                const name = typeof data.name === 'string' ? data.name : typeof data.id === 'string' ? data.id : a.id;
+                accRows.push({ $class: 'Account', $ext: a.id, name, categories: a.categories.filter((c) => c !== 'System'), enabled: a.enabled !== false });
             }
-            const meta = (r.meta ?? {});
-            return { $class: 'Resource', alias: r.alias, category: r.category, ...(isObj(pattern) ? { pattern } : {}),
-                ...(typeof meta.description === 'string' ? { description: meta.description } : {}) };
-        });
-        if (resRows.length) {
-            const r = await db.load(resRows, { tenant: SYSTEM_ID, existing: 'skip', agent: 'letopis import' });
-            report.resources = { loaded: r.loaded, skipped: r.skipped };
-        }
-        const rules = await src.unsafe(`select account, resource, permission, weight, meta, enabled from ${F}."Rule" order by account, resource`);
-        const ruleRows = rules.map((r) => {
-            const meta = (r.meta ?? {});
-            const code = typeof meta.code === 'number' ? meta.code : typeof meta.code === 'string' && /^\d+$/.test(meta.code) ? Number(meta.code) : undefined;
-            return { $class: 'rule', Group: { $key: [r.account] }, Object: { $key: [r.resource] }, permission: r.permission, weight: r.weight ?? 0,
-                enabled: r.enabled !== false, ...(code !== undefined ? { code } : {}), ...(typeof meta.message === 'string' ? { message: meta.message } : {}),
-                ...(typeof meta.description === 'string' ? { description: meta.description } : {}) };
-        });
-        if (ruleRows.length) {
-            const r = await db.load(ruleRows, { tenant: SYSTEM_ID, existing: 'skip', agent: 'letopis import' });
-            report.rules = { loaded: r.loaded, skipped: r.skipped };
-        }
-        // --- шаг 5: данные по арендаторам — загрузчик в режиме истории ---
-        const accountIds = new Set([SYSTEM_ID, ...accounts.map((a) => accId(a.id)), ...(sysTenant ? [sysTenant] : [])]);
-        const oldIds = new Set([...objs.values()].map((o) => o.id));
-        const byTenant = new Map();
-        for (const o of objs.values()) {
-            const t = tenantOf(o.account);
-            if (!byTenant.has(t))
-                byTenant.set(t, []);
-            byTenant.get(t).push(o);
-        }
-        for (const [tenant, list] of byTenant) {
-            const old = list[0].account;
-            report.tenants.push({ old, id: tenant, name: systemOld.has(old) ? opts.tenant : old });
-            const rows = [];
-            const origin = [];
-            const lastRows = [];
-            for (const o of list) {
-                const c = b.classes.get(o.cls);
-                const keyed = b.keyOf(o.cls).length > 0;
-                const src21 = report.source[c.name] ?? (report.source[c.name] = { objects: 0, versions: 0, live: 0 });
-                src21.objects++;
-                src21.versions += o.versions.length;
-                if (!o.versions[o.versions.length - 1].del)
-                    src21.live++;
-                let afterDelete = false;
-                o.versions.forEach((v, k) => {
-                    const data = {};
-                    for (const [f, x] of Object.entries(v.data)) {
-                        if (f === 'id')
-                            continue;
-                        if (f.startsWith('$')) {
-                            report.droppedFields[`${c.name}.${f}`] = (report.droppedFields[`${c.name}.${f}`] ?? 0) + 1;
+            if (sysTenant)
+                accRows.push({ $class: 'Account', $ext: `tenant:${opts.tenant}`, name: opts.tenant, categories: [], enabled: true });
+            if (accRows.length) {
+                const fresh = accRows.filter((row) => !x.taken(v5Id(SYSTEM_ID, 'Account', [String(row.$ext)])));
+                const r = fresh.length ? await x.load(fresh, { tenant: SYSTEM_ID, existing: 'skip', agent: 'letopis import' }) : null;
+                report.accounts = { loaded: r?.loaded ?? 0, skipped: (r?.skipped ?? 0) + accRows.length - fresh.length };
+            }
+            // --- шаг 3: креды → secret (от владельца; хэши как есть); совпадение без учёта регистра — первым идёт
+            // подтверждённый, затем более ранний, остальные — в отчёт ---
+            const creds = await src.unsafe(`select account::text as account, category, identifier, meta, confirmed from ${F}."Credential" where deleted is null order by confirmed desc, created, id`);
+            const secretRows = [];
+            for (const c of creds) {
+                const m = (c.meta ?? {});
+                const account = accId(c.account);
+                const kind = String(c.category);
+                const confirmed = c.confirmed !== false;
+                if (kind === 'OTP' || kind.startsWith('OTP_') || typeof m.code === 'string') {
+                    report.credentials.otp++;
+                    continue;
+                }
+                if (typeof m.password === 'string')
+                    secretRows.push({ account, kind, ident: c.identifier, material: Buffer.from(m.password, 'utf8'), meta: { confirmed } });
+                else if (kind === 'APIKEY')
+                    secretRows.push({ account, kind, ident: String(m.prefix ?? ''), material: Buffer.from(String(c.identifier), 'hex'), meta: { ...(m.name ? { name: m.name } : {}), confirmed: true } });
+                else if (kind === 'KEYSECRET')
+                    secretRows.push({ account, kind, ident: c.identifier, material: Buffer.from(String(m.secret ?? ''), 'hex'), meta: { ...(m.name ? { name: m.name } : {}), confirmed: true } });
+                else if (kind === 'TOTP')
+                    secretRows.push({ account, kind, ident: account, material: base32Decode(String(m.secret ?? '')), meta: { confirmed, last_step: Number(m.lastStep ?? 0) } });
+                else
+                    secretRows.push({ account, kind, ident: c.identifier, material: null, meta: { ...m, confirmed } });
+            }
+            if (secretRows.length) {
+                await x.begin(async (tx) => {
+                    for (const s of secretRows) {
+                        const [dup] = await tx.unsafe(`select account::text as account from ${S}.secret
+            where kind = $1 and casefold(ident) collate pg_unicode_fast = casefold($2) collate pg_unicode_fast and deleted_at is null`, [s.kind, s.ident]);
+                        if (dup) {
+                            if (dup.account === s.account)
+                                report.credentials.skipped++;
+                            else
+                                report.credentials.conflicts.push({ account: s.account, kind: s.kind, ident: s.ident });
                             continue;
                         }
-                        data[f] = x;
-                    }
-                    const links = {};
-                    for (const [k21, target] of Object.entries(v.links)) {
-                        const role = c.roleOf.get(k21) ?? b.classes.get(k21)?.name ?? k21;
-                        links[role] = newId(k21, target) ?? v5Id(tenant, b.classes.get(k21)?.name ?? k21, [`missing:${target}`]);
-                    }
-                    let ownerId = tenant;
-                    if (v.owner && v.owner !== o.account) {
-                        const mapped = systemOld.has(v.owner) ? SYSTEM_ID : accId(v.owner);
-                        if (accountIds.has(mapped))
-                            ownerId = mapped;
-                        else if (k === o.versions.length - 1)
-                            report.ownerLost++;
-                    }
-                    const op = v.del ? 'delete' : k === 0 || afterDelete ? 'create' : 'update';
-                    afterDelete = v.del;
-                    const row = { $class: c.name, $rev: k + 1, $at: v.at, $op: op, ...(keyed ? {} : { $ext: o.id }),
-                        ...(v.tags.length ? { $tags: v.tags } : {}), ...(ownerId !== tenant ? { $owner: ownerId } : {}), ...data, ...links };
-                    rows.push(row);
-                    origin.push({ class: o.cls, id: o.id, rev: k + 1 });
-                    if (k === o.versions.length - 1 && !v.del) {
-                        const { $rev: _r, $at: _a, $op: _o, ...cur } = row;
-                        lastRows.push(cur);
-                        scanUuids(data, `${c.name}`, oldIds, report.uuidFields);
+                        await tx.unsafe(`insert into ${S}.secret (account, kind, ident, material, meta) values ($1::uuid, $2, $3, $4, $5::jsonb)`, [s.account, s.kind, s.ident, s.material, s.meta]);
+                        report.credentials.imported++;
                     }
                 });
             }
-            try {
-                const r = await db.load(rows, { tenant, withHistory: true, existing: 'skip', agent: 'letopis import', ...(opts.commitEvery ? { commitEvery: opts.commitEvery } : {}) });
-                report.objects.loaded += r.loaded;
-                report.objects.skipped += r.skipped;
-                if (opts.update && lastRows.length) {
-                    const u = await db.load(lastRows, { tenant, existing: 'update', agent: 'letopis import' });
-                    report.objects.updated += u.updated;
+            // --- шаг 4: права — Resource и rule в System ---
+            const resources = await src.unsafe(`select alias, category, pattern, meta from ${F}."Resource" order by alias`);
+            const resRows = resources.map((r) => {
+                let pattern = r.pattern;
+                if (isObj(pattern) && 'account' in pattern) {
+                    const { account, ...rest } = pattern;
+                    pattern = { ...rest, tenant: account };
                 }
+                const meta = (r.meta ?? {});
+                return { $class: 'Resource', alias: r.alias, category: r.category, ...(isObj(pattern) ? { pattern } : {}),
+                    ...(typeof meta.description === 'string' ? { description: meta.description } : {}) };
+            });
+            if (resRows.length) {
+                const fresh = resRows.filter((row) => !x.taken(v5Id(SYSTEM_ID, 'Resource', [String(row.alias)])));
+                const r = fresh.length ? await x.load(fresh, { tenant: SYSTEM_ID, existing: 'skip', agent: 'letopis import' }) : null;
+                report.resources = { loaded: r?.loaded ?? 0, skipped: (r?.skipped ?? 0) + resRows.length - fresh.length };
             }
-            catch (e) {
-                // строки загрузчика → объекты 0.21; total, truncated, limit и complete отчёта загрузчика — как есть
-                const err = e;
-                const detail = err.detail;
-                if (detail?.rows) {
-                    const mapped = detail.rows.map((x) => ({ ...origin[x.line - 1], code: x.code, message: x.message }));
-                    throw new LetopisError(err.code ?? 'invalid_data', `import: арендатор ${tenant}: ${err.message}`, { ...detail, rows: mapped, notes: b.notes });
+            const rules = await src.unsafe(`select account, resource, permission, weight, meta, enabled from ${F}."Rule" order by account, resource`);
+            const ruleRows = rules.map((r) => {
+                const meta = (r.meta ?? {});
+                const code = typeof meta.code === 'number' ? meta.code : typeof meta.code === 'string' && /^\d+$/.test(meta.code) ? Number(meta.code) : undefined;
+                return { $class: 'rule', Group: { $key: [r.account] }, Object: { $key: [r.resource] }, permission: r.permission, weight: r.weight ?? 0,
+                    enabled: r.enabled !== false, ...(code !== undefined ? { code } : {}), ...(typeof meta.message === 'string' ? { message: meta.message } : {}),
+                    ...(typeof meta.description === 'string' ? { description: meta.description } : {}) };
+            });
+            if (ruleRows.length) {
+                const res = (alias) => v5Id(SYSTEM_ID, 'Resource', [String(alias)]);
+                const fresh = ruleRows.filter((row) => !x.taken(v5Id(SYSTEM_ID, 'rule', [res(row.Group.$key[0]), res(row.Object.$key[0])])));
+                const r = fresh.length ? await x.load(fresh, { tenant: SYSTEM_ID, existing: 'skip', agent: 'letopis import' }) : null;
+                report.rules = { loaded: r?.loaded ?? 0, skipped: (r?.skipped ?? 0) + ruleRows.length - fresh.length };
+            }
+            // --- шаг 5: данные по арендаторам — загрузчик в режиме истории ---
+            const accountIds = new Set([SYSTEM_ID, ...accounts.map((a) => accId(a.id)), ...(sysTenant ? [sysTenant] : [])]);
+            const oldIds = new Set([...objs.values()].map((o) => o.id));
+            const byTenant = new Map();
+            for (const o of objs.values()) {
+                const t = tenantOf(o.account);
+                if (!byTenant.has(t))
+                    byTenant.set(t, []);
+                byTenant.get(t).push(o);
+            }
+            for (const [tenant, list] of byTenant) {
+                const old = list[0].account;
+                report.tenants.push({ old, id: tenant, name: systemOld.has(old) ? opts.tenant : old });
+                const rows = [];
+                const origin = [];
+                const lastRows = [];
+                for (const o of list) {
+                    const c = b.classes.get(o.cls);
+                    const keyed = b.keyOf(o.cls).length > 0;
+                    const src21 = report.source[c.name] ?? (report.source[c.name] = { objects: 0, versions: 0, live: 0 });
+                    src21.objects++;
+                    src21.versions += o.versions.length;
+                    if (!o.versions[o.versions.length - 1].del)
+                        src21.live++;
+                    let afterDelete = false;
+                    o.versions.forEach((v, k) => {
+                        const data = {};
+                        for (const [f, x] of Object.entries(v.data)) {
+                            if (f === 'id')
+                                continue;
+                            if (f.startsWith('$')) {
+                                report.droppedFields[`${c.name}.${f}`] = (report.droppedFields[`${c.name}.${f}`] ?? 0) + 1;
+                                continue;
+                            }
+                            data[f] = x;
+                        }
+                        const links = {};
+                        for (const [k21, target] of Object.entries(v.links)) {
+                            const role = c.roleOf.get(k21) ?? b.classes.get(k21)?.name ?? k21;
+                            links[role] = newId(k21, target) ?? v5Id(tenant, b.classes.get(k21)?.name ?? k21, [`missing:${target}`]);
+                        }
+                        let ownerId = tenant;
+                        if (v.owner && v.owner !== o.account) {
+                            const mapped = systemOld.has(v.owner) ? SYSTEM_ID : accId(v.owner);
+                            if (accountIds.has(mapped))
+                                ownerId = mapped;
+                            else if (k === o.versions.length - 1)
+                                report.ownerLost++;
+                        }
+                        const op = v.del ? 'delete' : k === 0 || afterDelete ? 'create' : 'update';
+                        afterDelete = v.del;
+                        const row = { $class: c.name, $rev: k + 1, $at: v.at, $op: op, ...(keyed ? {} : { $ext: o.id }),
+                            ...(v.tags.length ? { $tags: v.tags } : {}), ...(ownerId !== tenant ? { $owner: ownerId } : {}), ...data, ...links };
+                        rows.push(row);
+                        origin.push({ class: o.cls, id: o.id, rev: k + 1 });
+                        if (k === o.versions.length - 1 && !v.del) {
+                            const { $rev: _r, $at: _a, $op: _o, ...cur } = row;
+                            lastRows.push(cur);
+                            scanUuids(data, `${c.name}`, oldIds, report.uuidFields);
+                        }
+                    });
+                }
+                try {
+                    const r = await x.load(rows, { tenant, withHistory: true, existing: 'skip', agent: 'letopis import', ...(opts.commitEvery ? { commitEvery: opts.commitEvery } : {}) });
+                    report.objects.loaded += r.loaded;
+                    report.objects.skipped += r.skipped;
+                    if (opts.update && lastRows.length) {
+                        const u = await x.load(lastRows, { tenant, existing: 'update', agent: 'letopis import' });
+                        report.objects.updated += u.updated;
+                    }
                 }
-                throw e;
+                catch (e) {
+                    // строки загрузчика → объекты 0.21; total, truncated, limit и complete отчёта загрузчика — как есть
+                    const err = e;
+                    const detail = err.detail;
+                    if (detail?.rows) {
+                        const mapped = detail.rows.map((x) => ({ ...origin[x.line - 1], code: x.code, message: x.message }));
+                        throw new LetopisError(err.code ?? 'invalid_data', `import: арендатор ${tenant}: ${err.message}`, { ...detail, rows: mapped, notes: b.notes });
+                    }
+                    throw e;
+                }
+                log(`арендатор ${tenant}: объектов ${list.length}, версий ${rows.length}`);
             }
-            log(`арендатор ${tenant}: объектов ${list.length}, версий ${rows.length}`);
-        }
+            return byTenant;
+        };
+        const byTenant = opts.initial
+            // existing в первой заливке — только 'error': строки сида отфильтрованы taken(), прочих объектов в схеме нет
+            ? await initialSession({ sql: dst, schema: opts.schema, tenant: null, admin: true, ownerRole: owner }, (sess) => steps({ begin: (fn) => fn(sess.sql), load: (rows, o) => sess.load(rows, { ...o, existing: undefined }), taken: (id) => sess.taken(id) }))
+            : await steps({
+                begin: (fn) => dst.begin(async (tx) => {
+                    await tx.unsafe(`set local role ${quote(owner)}`);
+                    return fn(tx);
+                }),
+                load: (rows, o) => db.load(rows, o),
+                taken: () => false,
+            });
         // --- шаг 6: проверка — счётчики и verify() ---
         const tenants = [...byTenant.keys()];
         if (tenants.length) {

package/dist/index.d.ts

@@ -34,7 +34,9 @@ export type { LoadOptions, LoadReport, LoadIssue, LoadInput } from './load.js';
 export type { Chain, ChainCore, StepFn, BatchEntry } from './chain.js';
 export type { ModelLike, AnyModelLike, RowOf, FilterOf, FieldFilterOf, TypedChain, StepsOf, PatchOf } from './typed.js';
 export type { Row, Path, Filter, FieldFilter, Cursor, ChainMods, QueryEvent, Op, Scalar } from './types.js';
+export type { DiffChange, DiffResult, DiffOptions, BlameField, BlameResult, BlameOptions } from './types.js';
 export type { CacheOptions, CacheStats } from './cache.js';
+export type { SignalMode } from './signals.js';
 export type { WatchOptions, WatchEvent, Subscription } from './watch.js';
 export type { VerifyResult, VerifyIssue, MaintainOptions, MaintainReport, ResetOptions, ResetResult, ModelDescription } from './admin.js';
 export { describeText } from './admin.js';
@@ -73,7 +75,8 @@ export interface ConnectOptions {
     /**
      * Слушать сигналы базы (LISTEN, по умолчанию да). false — пул в режиме транзакций (PgBouncer):
      * реестр перечитывается через db.refresh(), подписка опрашивает журнал, кэш результатов выключен
-     * (с cache: { ttlOnly: true } — работает только по сроку).
+     * (с cache: { ttlOnly: true } — работает только по сроку). В установке с up({ signals: 'none' })
+     * слушателя нет всегда, а реестр раз в 5 с сверяет отпечаток классов.
      */
     listen?: boolean;
     /** Кэш результатов (§2.12): срок по умолчанию, размер, ttlOnly; false — выключен. */
@@ -139,7 +142,10 @@ export interface DbCore {
         tenant?: string;
     }): Promise<Db>;
     /** Явная транзакция read committed: те же цепочки, commit(), rollback(), lock(), forUpdate(). */
-    begin(): Promise<DbTx>;
+    /** Явная транзакция; reason — причина изменения для всех операций блока (план 1.1). */
+    begin(opts?: {
+        reason?: string;
+    }): Promise<DbTx>;
     /**
      * Загрузчик (§2.6): строки любых классов — проверки в коде, COPY от роли владельца, один запрос по
      * целям вне загрузки. Только на администраторском подключении (иначе admin_required).
@@ -149,7 +155,9 @@ export interface DbCore {
      * Именованная очередь планов фасада: batch.Класс(…).create(…); batch.run() — одной транзакцией. У корня,
      * у каждого db.as() и у каждой db.begin() очереди свои: план исполняется от имени фасада, который его поставил.
      */
-    batch(name: string): Batch;
+    batch(name: string, opts?: {
+        reason?: string;
+    }): Batch;
     /** Advisory-блокировка до конца транзакции — только в db.begin() (иначе tx_required). */
     lock(...keys: (string | number)[]): Promise<void>;
     /** Зафиксировать транзакцию tr (то же, что tr.commit()). */