letopis 1.0.1 → 1.2.0

package/dist/index.js

@@ -11,6 +11,8 @@ import postgres from 'postgres';
 import { LetopisError, fromDbError, removed } from './errors.js';
 import { Registry } from './registry.js';
 import { AclPasses, ExplicitTx, Notifier, poolExecutor, runTx } from './tx.js';
+import { checkReason } from './write.js';
+import { registerDb } from './internal.js';
 import { makeAuth } from './auth.js';
 import { makeAcl } from './acl.js';
 import { idOf as idOfClass } from './uuid.js';
@@ -19,7 +21,9 @@ import { makeBatch, startEntity, startStep } from './chain.js';
 import { DDL_REVISION } from './types.js';
 import { ACL_CLASSES, ResultCache } from './cache.js';
 import { Subscription } from './watch.js';
-import { describe as describeModel, maintain as runMaintain, rekeyClass as runRekeyClass, reset as runReset, scheduleMaintain, trimHistory as runTrim, verify as runVerify, } from './admin.js';
+import { Projector } from './project.js';
+import { SIGNAL_MODES, Signals, bucket, throttle } from './signals.js';
+import { describe as describeModel, maintain as runMaintain, rebuildAggregates as runRebuildAggregates, rekeyClass as runRekeyClass, reset as runReset, scheduleMaintain, trimHistory as runTrim, verify as runVerify, } from './admin.js';
 export { DDL_REVISION } from './types.js';
 export { uuidv5, v5Name, v5Id, idOf } from './uuid.js';
 export { LetopisError, ValidationError, fromDbError } from './errors.js';
@@ -64,6 +68,7 @@ function makeDb(sh, scope, exec, owner, tx) {
     const txc = scope.txc;
     const chainCtx = {
         reg: scope.registry(), schema: sh.schema, exec, tenant: scope.tenant, owner, onQuery: sh.onQuery, slowMs: sh.slowMs,
+        reason: txc.reason ?? '', txReason: txc.reason ?? '',
         ...(sh.cache ? { cache: { store: sh.cache, who: () => ({ token: txc.token, account: txc.account, tenant: scope.tenant() }) } } : {}),
     };
     // реестр корня меняется после auth.switch — цепочки берут действующий
@@ -116,7 +121,10 @@ function makeDb(sh, scope, exec, owner, tx) {
             const classes = o.classes ? [...new Set(o.classes.flatMap((c) => reg.family(c).map((x) => x.name)))] : null;
             return new Subscription({
                 S: sh.S, exec: poolExecutor(txc), classes,
-                ...(sh.listen ? { onSignal: (fn) => { sh.signals.add(fn); return () => void sh.signals.delete(fn); } } : {}),
+                ...(sh.listen ? {
+                    onSignal: (fn) => { sh.signals.add(fn); return () => void sh.signals.delete(fn); },
+                    tenant: () => (sh.allTenants ? null : sh.sig.tenantToken(scope.tenant())),
+                } : {}),
             }, o);
         },
         cache: {
@@ -141,29 +149,48 @@ function makeDb(sh, scope, exec, owner, tx) {
             const registry = await sh.registryFor(tenant, scoped);
             return makeDb(sh, { txc: scoped, tenant: () => tenant, registry: () => registry, root: false }, poolExecutor(scoped), nextOwner);
         },
-        begin: async () => {
+        begin: async (o) => {
             if (tx)
                 throw new LetopisError('invalid_query', 'вложенных транзакций нет: db.begin() внутри db.begin()');
-            const t = await ExplicitTx.open(txc);
-            return makeDb(sh, scope, t, owner, t);
+            // причина блока ставится в начале транзакции (setupSql) и действует на все её операции
+            const btx = o?.reason !== undefined ? { ...txc, reason: checkReason(o.reason, 'db.begin()') } : txc;
+            const t = await ExplicitTx.open(btx);
+            return makeDb(sh, btx === txc ? scope : { ...scope, txc: btx }, t, owner, t);
         },
         load: async (input, o) => {
             if (tx)
                 throw new LetopisError('invalid_query', 'load() — своей транзакцией, не внутри db.begin()');
             return load({ sql: sh.sql, schema: sh.schema, tenant: scope.tenant(), admin: sh.admin, ownerRole: sh.ownerRole }, input, o);
         },
-        batch: (name) => {
+        projector: (name, o) => {
+            if (tx)
+                throw new LetopisError('invalid_query', 'projector() — от корня подключения, а не внутри db.begin()');
+            if (!sh.admin)
+                throw new LetopisError('admin_required', 'проектору нужно администраторское подключение (connect({ allowBypassRls: true }) роли, которая может стать владельцем схемы)');
+            return new Projector({
+                sql: sh.sql, schema: sh.schema, S: sh.S, ownerRole: sh.ownerRole,
+                ...(sh.listen ? { onSignal: (fn) => { sh.signals.add(fn); return () => void sh.signals.delete(fn); } } : {}),
+            }, name, o);
+        },
+        rebuildAggregates: async (cls) => {
+            if (tx)
+                throw new LetopisError('invalid_query', 'rebuildAggregates() — своей транзакцией, не внутри db.begin()');
+            if (!sh.admin)
+                throw new LetopisError('admin_required', 'ремонту агрегатов нужно администраторское подключение (connect({ allowBypassRls: true }) роли, которая может стать владельцем схемы)');
+            return runRebuildAggregates({ sql: sh.sql, S: sh.S, ownerRole: sh.ownerRole }, cls);
+        },
+        batch: (name, o) => {
             let q = batches.get(name);
             if (!q)
                 batches.set(name, (q = []));
-            return makeBatch(chainCtx, q);
+            return makeBatch(o?.reason !== undefined ? { ...chainCtx, reason: checkReason(o.reason, 'db.batch()') } : chainCtx, q);
         },
         lock: async (...keys) => (tx ? tx.lock(...keys) : noTx('lock()')),
         commit: async (tr) => (tr ? tr.commit() : tx ? tx.commit() : noTx('commit()')),
         rollback: async (tr) => (tr ? tr.rollback() : tx ? tx.rollback() : noTx('rollback()')),
         close: () => (tx ? tx.rollback() : sh.close()),
     };
-    return new Proxy(core, {
+    const facade = new Proxy(core, {
         get(t, prop, r) {
             if (typeof prop === 'symbol' || prop in t)
                 return Reflect.get(t, prop, r);
@@ -183,6 +210,9 @@ function makeDb(sh, scope, exec, owner, tx) {
             return startStep(chainCtx, prop);
         },
     });
+    // модули пакета (letopis/mcp) узнают обход RLS по самому подключению, а не со слов вызывающего (internal.ts)
+    registerDb(facade, { allTenants: sh.allTenants, explicit: Boolean(tx) });
+    return facade;
 }
 export async function connect(opts) {
     if (!SCHEMA_NAME.test(opts.schema))
@@ -227,10 +257,20 @@ export async function connect(opts) {
             throw new LetopisError('invalid_data', `connect: схемы ${opts.schema} нет — установите её: up({ schema })`);
         if (rev < DDL_REVISION)
             console.warn(`letopis: движок схемы ${opts.schema} ревизии ${rev}, библиотека ждёт ${DDL_REVISION} — обновите: up({ schema: '${opts.schema}', upgrade: true })`);
+        // режим сигналов установки (план 1.1, §2.2); схема, накатанная до него (нет signal_mode()), — class
+        const [sm] = await sql.unsafe(`select ${S}.signal_mode() as m`).catch((e) => {
+            if (e.code === '42883')
+                return [{ m: 'class' }];
+            throw fromDbError(e);
+        });
+        const mode = SIGNAL_MODES.includes(sm?.m) ? sm.m : 'class';
+        const sig = new Signals(mode);
         const notifier = new Notifier(sql, opts.schema, opts.notifyIntervalMs ?? 100);
         const passes = new AclPasses(S);
-        const listen = opts.listen !== false;
-        const cache = opts.cache === false ? null : new ResultCache(opts.cache ?? {});
+        // режим none: сигналов нет — без LISTEN, кэш только по сроку (ttlOnly), подписка опрашивает журнал
+        const listen = opts.listen !== false && mode !== 'none';
+        // подключение в обход RLS видит строки всех арендаторов: его ответы сбрасывает сигнал из любого
+        const cache = opts.cache === false ? null : new ResultCache(opts.cache ?? {}, sig, Boolean(bypass));
         const signals = new Set();
         // продление сессии (§2.9): отдельным вызовом не чаще раза в минуту; ошибка (реплика,
         // транзакции только для чтения) не мешает работе
@@ -241,60 +281,182 @@ export async function connect(opts) {
             refreshedAt = Date.now();
             void runTx({ sql, token, notifier: null }, (q) => q.unsafe(`select ${S}.auth_refresh()`), { retries: 0 }).catch(() => { });
         };
-        const ctx = { sql, token, notifier, passes, after: touch, ...(cache ? { onChanged: (names, raw) => cache.changed(names, raw) } : {}) };
+        // в режиме none нотификатор не отправляет: letopis.changed своей транзакции сбрасывает только свой кэш
+        const ctx = { sql, token, notifier: mode === 'none' ? null : notifier, passes, after: touch,
+            ...(cache ? { onChanged: (names, raw) => cache.changed(names, raw) } : {}) };
         const root = { tenant: null, registry: new Registry() };
-        const loadClasses = (txc) => runTx(txc, (q) => q.unsafe(`select tenant, rev, data from ${S}.entity where class = 'Class' and tenant in (${S}.ctx_tenant(), '${SYSTEM_ID}')`), { read: true });
+        // классы арендатора tenant под контекстом txc; null — контекст уже не в этом арендаторе (сессия кончилась,
+        // пользователь выбыл из арендатора): тогда прежний реестр остаётся, а не пустеет (доработки после точки Б)
+        const loadClasses = (txc, tenant) => runTx(txc, async (q) => {
+            const [t] = await q.unsafe(`select ${S}.ctx_tenant() as t`);
+            if (String(t?.t ?? '').toLowerCase() !== tenant.toLowerCase())
+                return null;
+            return q.unsafe(`select tenant, rev, data from ${S}.entity where class = 'Class' and tenant in (${S}.ctx_tenant(), '${SYSTEM_ID}')`);
+        }, { read: true });
+        // реестры db.as() — общие на арендатора; txc — контекст последнего успешного as() этого арендатора
         const others = new Map();
-        const refresh = async () => {
+        const loading = new Map();
+        // токены классов (режим opaque) — по именам всех реестров подключения
+        const tokens = () => sig.setClasses([root.registry, ...[...others.values()].map((o) => o.registry)].flatMap((r) => r.all().map((c) => c.name)));
+        // only — токены арендаторов из сигналов Class (режимы tenant и opaque): реестры db.as() только этих арендаторов
+        const refresh = async (only) => {
             const rows = await runTx(ctx, async (q) => {
                 const [t] = await q.unsafe(`select ${S}.ctx_tenant() as t`);
                 root.tenant = t?.t ?? null;
                 return q.unsafe(`select tenant, rev, data from ${S}.entity where class = 'Class' and tenant in (${S}.ctx_tenant(), '${SYSTEM_ID}')`);
             });
             root.registry.load(rows);
-            for (const o of others.values())
-                o.registry.load(await loadClasses(o.txc).catch(() => []));
+            for (const [tenant, o] of others) {
+                if (only && !only.has(sig.tenantToken(tenant) ?? ''))
+                    continue;
+                const loaded = await loadClasses(o.txc, tenant).catch(() => null);
+                if (loaded)
+                    o.registry.load(loaded);
+            }
+            tokens();
         };
         const registryFor = async (tenant, txc) => {
             if (tenant === root.tenant)
                 return root.registry;
             const known = others.get(tenant);
-            if (known)
+            if (known) {
+                known.txc = txc;
                 return known.registry;
-            const registry = new Registry();
-            registry.load(await loadClasses(txc));
-            others.set(tenant, { registry, txc });
-            return registry;
+            }
+            // одновременные as() нового арендатора получают один реестр
+            let pending = loading.get(tenant);
+            if (!pending) {
+                pending = (async () => {
+                    const registry = new Registry();
+                    registry.load(((await loadClasses(txc, tenant)) ?? []));
+                    others.set(tenant, { registry, txc });
+                    tokens();
+                    return registry;
+                })().finally(() => loading.delete(tenant));
+                loading.set(tenant, pending);
+            }
+            return pending;
         };
+        // ключ сигналов (режимы tenant и opaque) — сессии с правом letopis.signals; без права процесс
+        // работает без ключа: арендатора (а в opaque — и класса) в сигнале не различает
+        const fetchKey = async () => {
+            if (mode !== 'tenant' && mode !== 'opaque')
+                return;
+            const key = await runTx(ctx, (q) => q.unsafe(`select ${S}.signal_key() as k`), { read: true }).then((r) => r[0]?.k ?? null, (e) => {
+                if (e instanceof LetopisError && (e.code === 'acl_denied' || e.code === 'no_session'))
+                    return null;
+                throw e;
+            });
+            // ключ сменился (reset({ all })): ответы с токенами старого ключа сигналы больше не узнают
+            if (sig.setKey(key))
+                cache?.clear();
+        };
+        await fetchKey();
         await refresh();
-        // описания классов меняются — реестр перечитывается по сигналу; строки прав — пропуска заново;
-        // кэш результатов и подписки — по именам классов; (пере)подключение слушателя — кэш целиком
-        const onSignal = (cls) => {
-            if (ACL_CLASSES.has(cls) || cls === '*')
+        // ключ, реестр и пропуска прав — заново по *, незнакомому токену, нагрузке не по режиму, а у процесса
+        // без ключа в режиме opaque — по любому сигналу; не чаще раза в 5 с: заливка канала (в том числе
+        // поддельными сигналами) не становится потоком перечитываний
+        const resync = throttle(() => {
+            passes.clear();
+            void fetchKey().then(() => refresh()).catch(() => { });
+        }, 5000);
+        // сигнал Class — реестр сразу, как в 1.0: правка описания доходит без задержки; пока идёт перечитывание, новые
+        // сигналы сливаются в одно следующее. Три перечитывания подряд — сразу, дальше не чаще раза в 5 с: заливка
+        // канала, в том числе поддельными Class, не становится потоком перечитываний (план 1.1, §7.7 №32; ревью №1
+        // точки А)
+        let reloading = false;
+        let again = false;
+        // какие реестры db.as() перечитать: токены арендаторов из сигналов или все (сигнал без арендатора)
+        let reloadAll = false;
+        const reloadTokens = new Set();
+        const startReload = bucket(() => {
+            reloading = true;
+            const only = reloadAll ? null : new Set(reloadTokens);
+            reloadAll = false;
+            reloadTokens.clear();
+            void refresh(only).catch(() => { }).finally(() => {
+                reloading = false;
+                if (again) {
+                    again = false;
+                    reload(undefined);
+                }
+            });
+        }, 3, 5000);
+        // tenant: null — все реестры, строка — токен арендатора сигнала, undefined — то, что уже накоплено
+        const reload = (tenant) => {
+            if (tenant === null)
+                reloadAll = true;
+            else if (tenant !== undefined)
+                reloadTokens.add(tenant);
+            if (reloading) {
+                again = true;
+                return;
+            }
+            startReload();
+        };
+        // строки прав — пропуска заново; кэш результатов и подписки — по классу и арендатору сигнала;
+        // (пере)подключение слушателя — кэш целиком, после обрыва — и ключ с реестром (сигналы потеряны)
+        const onSignal = (payload) => {
+            const s = sig.parse(payload);
+            if (s.kind === 'class' && ACL_CLASSES.has(s.cls))
                 passes.clear();
-            if (cls === 'Class' || cls === '*')
-                void refresh().catch(() => { });
-            cache?.signal(cls);
+            if (s.kind === 'class' && s.cls === 'Class')
+                reload(s.tenant);
+            else if (s.kind === 'all' || s.kind === 'opaque' || s.kind === 'unknown' || s.kind === 'foreign')
+                resync();
+            cache?.signal(s);
             for (const fn of signals)
-                fn(cls);
+                fn(s);
         };
+        let listened = false;
         const listener = listen
             ? await sql.listen(opts.schema, onSignal, () => {
+                if (listened)
+                    resync();
+                listened = true;
                 cache?.listen();
                 for (const fn of signals)
-                    fn('*');
+                    fn({ kind: 'all' });
             })
             : null;
+        // режим none: о новых и изменённых классах сигнала нет — отпечаток классов раз в 5 с
+        let stamper = null;
+        if (mode === 'none') {
+            const stampOf = (txc) => runTx(txc, (q) => q.unsafe(`select ${S}.class_stamp() as s`), { read: true }).then((r) => String(r[0]?.s ?? ''));
+            const stamp = async () => [await stampOf(ctx), ...(await Promise.all([...others.values()].map((o) => stampOf(o.txc).catch(() => ''))))].join('|');
+            let last = await stamp();
+            let busy = false;
+            stamper = setInterval(() => {
+                if (busy)
+                    return;
+                busy = true;
+                void stamp().then(async (cur) => {
+                    if (cur === last)
+                        return;
+                    last = cur;
+                    await refresh();
+                }).catch(() => { }).finally(() => {
+                    busy = false;
+                });
+            }, 5000);
+            stamper.unref?.();
+        }
         let stopMaintain = null;
         const shared = {
             sql, schema: opts.schema, S, notifier, passes, root, registryFor, refresh, onQuery: opts.onQuery, slowMs: opts.slowMs,
             admin: Boolean(bypass && (role.rolsuper || role.can_set)),
             ownerRole: owner,
             cache,
+            sig,
+            allTenants: Boolean(bypass),
             signals,
             listen,
             async close() {
                 stopMaintain?.();
+                resync.stop();
+                startReload.stop();
+                if (stamper)
+                    clearInterval(stamper);
                 await notifier.close();
                 await listener?.unlisten();
                 if (own)

package/dist/internal.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Внутренний канал между модулями пакета (план 1.1, этап 5): свойства подключения, которых нет в публичном API.
+ * Модуля нет в exports package.json — снаружи пакета его не импортировать; letopis/mcp узнаёт по нему, что
+ * фасад db обходит RLS, не полагаясь на то, что сообщает о себе сам вызывающий.
+ */
+/** Что фасад db (корень, db.as(), db.begin()) сообщает модулям пакета. */
+export interface DbInternals {
+    /** Подключение в обход RLS (суперпользователь, BYPASSRLS, член роли-владельца): видит строки всех арендаторов. */
+    readonly allTenants: boolean;
+    /** Фасад явной транзакции db.begin(). */
+    readonly explicit: boolean;
+}
+/** Запомнить фасад (зовёт makeDb для каждого фасада, который отдаёт наружу). */
+export declare function registerDb(db: object, info: DbInternals): void;
+/** Свойства фасада; undefined — объект не фасад connect() этого пакета. */
+export declare function internalsOf(db: unknown): DbInternals | undefined;

package/dist/internal.js

@@ -0,0 +1,14 @@
+/**
+ * Внутренний канал между модулями пакета (план 1.1, этап 5): свойства подключения, которых нет в публичном API.
+ * Модуля нет в exports package.json — снаружи пакета его не импортировать; letopis/mcp узнаёт по нему, что
+ * фасад db обходит RLS, не полагаясь на то, что сообщает о себе сам вызывающий.
+ */
+const facades = new WeakMap();
+/** Запомнить фасад (зовёт makeDb для каждого фасада, который отдаёт наружу). */
+export function registerDb(db, info) {
+    facades.set(db, info);
+}
+/** Свойства фасада; undefined — объект не фасад connect() этого пакета. */
+export function internalsOf(db) {
+    return db !== null && (typeof db === 'object' || typeof db === 'function') ? facades.get(db) : undefined;
+}

package/dist/load.d.ts

@@ -1,5 +1,6 @@
 import type postgres from 'postgres';
 import { type Issue } from './errors.js';
+import { Registry } from './registry.js';
 type Sql = postgres.Sql<Record<string, unknown>>;
 type Raw = Record<string, unknown>;
 export interface LoadOptions {
@@ -27,6 +28,12 @@ export interface LoadOptions {
      * existing: 'update' — прежние) значения строк; цели ссылок ему видны; владелец — по ownerDefault.
      */
     as?: string;
+    /**
+     * Первая заливка (план 1.1, §2.3): только в пустую схему (кроме строк системных классов — иначе
+     * not_empty), одной транзакцией; на время загрузки схема закрыта, индексы и триггеры сняты и
+     * перестраиваются в конце. Без commitEvery, existing (кроме 'error') и { as }.
+     */
+    initial?: boolean;
 }
 export interface LoadReport {
     /** Строк во входе. */
@@ -65,6 +72,50 @@ export interface LoadEnv {
     /** Подключение может стать владельцем (set role) — иначе admin_required. */
     admin: boolean;
     ownerRole: string;
+    /** Сессия первой заливки (initialSession): загрузка идёт на её соединении и в её транзакции. */
+    session?: InitialState;
+}
+/** Внутренние настройки первой заливки — для разбивки замера (bench/initial-load.mjs); в публичные типы не входят. */
+export interface InitialTuning {
+    /** COPY … FREEZE (по умолчанию да). */
+    freeze?: boolean;
+    /** Оставить триггеры (BEFORE ROW делает COPY построчным). */
+    keepTriggers?: boolean;
+    /** Оставить первичный ключ и уникальные ограничения. */
+    keepKeys?: boolean;
+    /** Оставить индексы GIN. */
+    keepGin?: boolean;
+}
+/** Проверки загрузки, отложенные до конца первой заливки: по перестроенным индексам. */
+interface Pending {
+    reg: Registry;
+    tenant: string;
+    external: Map<string, {
+        line: number;
+        role: string;
+        allowed: string[];
+    }>;
+    owners: Map<string, number>;
+    /** verify: true — id записанных строк. */
+    verify: string[] | null;
+}
+/** Состояние сессии первой заливки. */
+export interface InitialState {
+    conn: Sql;
+    /** id строк системных классов и объектов, уже записанных сессией: первичного ключа на время загрузки нет. */
+    ids: Set<string>;
+    pending: Pending[];
+    /** Арендатор → классы записанных строк: сигнал в конце сессии. */
+    touched: Map<string, Set<string>>;
+    freeze: boolean;
+}
+/** Первая заливка для нескольких загрузок (импорт): соединение и транзакция сессии. */
+export interface InitialSession {
+    /** Соединение сессии (роль владельца): свои операторы импорта — в той же транзакции. */
+    readonly sql: Sql;
+    load(input: LoadInput, opts?: LoadOptions): Promise<LoadReport>;
+    /** id уже есть в схеме: строка системного класса или объект, записанный этой сессией. */
+    taken(id: string): boolean;
 }
 /**
  * Загрузить строки (§2.6). Одна транзакция (или порции commitEvery): описания классов под
@@ -73,4 +124,16 @@ export interface LoadEnv {
  * называет строки и нарушения.
  */
 export declare function load(env: LoadEnv, input: LoadInput, opts?: LoadOptions): Promise<LoadReport>;
+/**
+ * Первая заливка (план 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 declare function initialSession<T>(env: LoadEnv, fn: (s: InitialSession) => Promise<T>, tune?: InitialTuning): Promise<T>;
 export {};