letopis 0.20.3 → 1.0.0

package/dist/index.js

@@ -1,188 +1,314 @@
 /**
- * letopis: dot-цепочки над append-only Entity-хранилищем (TimescaleDB).
+ * letopis 1.0 — основная точка входа пакета. Руководство — README.md пакета, машинный каталог API —
+ * docs/api-contract.json репозитория; решения и их причины — reports/PLAN-LETOPIS-1.0.md (этапы ниже).
  *
- * schema — ПОЛНОЕ имя PG-схемы С версией движка ("v1.booking"); префикс либа НЕ достраивает
- * (создаёт up({ schema: 'booking', version: 1 }) либо db/apply.mjs). Шаг цепочки — id ИЛИ
- * alias класса из таблицы Schema (db.Staff ≡ db.Мастер).
- *
- *   const db = await connect({ dsn, schema: 'v1.booking' })   // безличный пул
- *   const t  = await db.as(accountId)                          // арендатор ВЫЗОВА
- *   await t.Мастер({ name: 'Вася' }).навык().Услуга().run()
+ * Этап 2: connect() — подключение под сессией, реестр классов, отложенный сигнал, db.sql.
+ * Этап 3: цепочки чтения t.Класс(…).Связь().rows(); этап 4 — запись цепочками и загрузчик.
+ * Этап 5: db.auth (креды, вход, сессии), db.acl, db.as(аккаунт, { tenant }) — имперсонация.
+ * Этап 6: история (restore, purge, rekey, trimHistory), verify, maintain, reset, watch, кэш результатов.
  */
-// FILE: lib/src/index.ts
-// VERSION: 1.3.0
-// START_MODULE_CONTRACT
-//   PURPOSE: Публичная точка входа пакета — открыть соединение (реестр, опциональный ACL, сборка db) и ре-экспорт публичной поверхности; хелпер курсора.
-//   SCOPE: connect, cursorOf + barrel-реэкспорты
-//   DEPENDS: M-SCHEMA, M-CHAIN, M-TABLES, M-ACL, M-SQL, M-TYPES, M-UP
-//   LINKS: M-CONNECT, V-M-CONNECT
-//   ROLE: RUNTIME
-//   MAP_MODE: EXPORTS
-// END_MODULE_CONTRACT
-//
-// START_MODULE_MAP
-//   connect - открывает pg-соединение, грузит реестр, опц. включает ACL (снимок Resource/Rule на подключение), собирает EntityDb
-//   cursorOf - курсор keyset-пагинации из последней строки страницы
-//   NOTE (re-exports) - up/UpOpts←M-UP; uuidv5/uuidv7/LETOPIS_NS←M-UUID; ops←M-OPS; totpCode/AuthApi/AuthResult←M-AUTH; AclApi←M-ACL; ValidationError←M-WRITE; Registry←M-SCHEMA; Session-типы←M-SESSIONS; базовые типы←M-TYPES; типы chain/tables
-// END_MODULE_MAP
-//
-// START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.3.0 - Словарь Resource/Rule снимается ОДИН раз на подключение и
-//     переиспользуется всеми db.as(): scope-per-request под enforceAcl платил два лишних
-//     SELECT на каждый HTTP-запрос. Per-scope остались чтение своего аккаунта и компиляция
-//     энфорсера (один энфорсер = один субъект). Снимок сбрасывает reloadSchema().
-//     Ранее: BREAKING — opts.account/opts.owner сняты, арендатора называет db.as()]
-// END_CHANGE_SUMMARY
 import postgres from 'postgres';
-import { loadRegistry } from './schema.js';
-import { makeDb } from './chain.js';
-import { makeTables } from './tables.js';
-import { compileEnforcer } from './acl.js';
-import { DDL_REVISION, parseDdlRevision } from './types.js';
-// START_CONTRACT: connect
-//   PURPOSE: Открыть БЕЗЛИЧНОЕ соединение: postgres-пул, реестр схемы, System-аккаунт, хук компиляции ACL — и собрать EntityDb (арендатора вызова называет db.as()).
-//   INPUTS: { opts: ConnectOpts { dsn, schema, partition?='entity', max?=10, enforceAcl?, enforceAccount?=true, onQuery?, slowMs? } }
-//   OUTPUTS: { Promise<EntityDb> - dot-цепочный db без идентичности; db.as(account) даёт scoped-хендл }
-//   SIDE_EFFECTS: открывает пул postgres (timestamptz строкой), читает реестр и System-аккаунт; ставит ctx.compileAcl (зовётся из db.as: читает resources/rules и компилит aclDecide под субъекта scope; при ненайденном аккаунте — 'letopis: enforceAcl — account "…" not found'); без enforceAcl печатает предупреждение один раз на процесс; NB: ESM-цикл M-CONNECT↔M-UP (up ре-экспортится здесь)
-//   LINKS: M-CONNECT, V-M-CONNECT, M-SCHEMA, M-CHAIN, M-TABLES, M-ACL, M-SQL
-// END_CONTRACT: connect
-/** Предупреждение об отключённом enforceAcl печатается один раз на процесс. */
-let warnedNoAcl = false;
-/** Схемы, про чью ревизию движка уже предупредили (один раз на схему за процесс). */
-const warnedDdl = new Set();
-// START_CONTRACT: checkDdlRevision
-//   PURPOSE: Сверить ревизию движка схемы (COMMENT ON SCHEMA) с ожидаемой либой; при отставании предупредить с командой апгрейда.
-//   INPUTS: { sql: Ctx['sql'] - открытый пул; schema: string - полное имя PG-схемы }
-//   OUTPUTS: { Promise<void> }
-//   SIDE_EFFECTS: один SELECT из obj_description; console.warn один раз на схему за процесс (никогда не бросает: правки ddl аддитивны)
-//   LINKS: M-CONNECT, V-M-CONNECT, M-DDL, M-TYPES
-// END_CONTRACT: checkDdlRevision
-async function checkDdlRevision(sql, schema) {
-    // NB: ::regnamespace тут нельзя — имена схем letopis содержат точку ("v1.booking"),
-    // и приведение разберёт их как «схема v1, объект booking» → invalid name syntax.
-    const rows = (await sql `
-    SELECT obj_description(n.oid, 'pg_namespace') AS c FROM pg_namespace n WHERE n.nspname = ${schema}
-  `);
-    const have = parseDdlRevision(rows[0]?.c);
-    if (have === DDL_REVISION)
-        return;
-    if (warnedDdl.has(schema))
-        return;
-    warnedDdl.add(schema);
-    const чего = have === null
-        ? 'ревизия не помечена (схема накатана либой до появления метки)'
-        : `ревизия схемы ${have}, либа ожидает ${DDL_REVISION}`;
-    console.warn(`letopis: движок схемы "${schema}" отстал — ${чего}. Схема продолжит работать, но новых ` +
-        'функций/триггеров в ней нет (например purge/purge_account из 0.19.0) — вызов упадёт ' +
-        'ошибкой PostgreSQL "function … does not exist". ddl.sql идемпотентен, накат повторный ' +
-        'и данные целы: up({ …, upgrade: true }) либо node db/apply.mjs --dsn=… --schema=<имя> ' +
-        '--version=<N> --upgrade');
+import { LetopisError, fromDbError, removed } from './errors.js';
+import { Registry } from './registry.js';
+import { AclPasses, ExplicitTx, Notifier, poolExecutor, runTx } from './tx.js';
+import { makeAuth } from './auth.js';
+import { makeAcl } from './acl.js';
+import { idOf as idOfClass } from './uuid.js';
+import { load } from './load.js';
+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';
+export { DDL_REVISION } from './types.js';
+export { uuidv5, v5Name, v5Id, idOf } from './uuid.js';
+export { LetopisError, ValidationError, fromDbError } from './errors.js';
+export { Registry } from './registry.js';
+export { compileValidator, applyDefaults } from './validate.js';
+export { syncModels, generateTypes, schemaToTs } from './sync.js';
+export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, isOp } from './ops.js';
+export { cursorOf } from './sql.js';
+export { inc, isInc } from './write.js';
+export { totpCode, hashPassword, verifyHash } from './auth.js';
+export { describeText } from './admin.js';
+export { up, createTenant } from './up.js';
+export { RESERVED_CLASS_NAMES, CHAIN_METHODS, DB_METHODS } from './types.js';
+/** Снесено в 1.0.0: id v7 больше не выдаются (§2.3). */
+export function uuidv7() {
+    throw removed('uuidv7()', 'uuidv5() и idOf(): id объекта вычисляется из ключа');
 }
-export async function connect(opts) {
-    // timestamptz — строкой (JS Date режет микросекунды → ломал бы asOf/cursorOf по updated)
-    const sql = postgres(opts.dsn, {
-        max: opts.max ?? 10,
-        types: { timestamptz: { to: 1184, from: [1184], serialize: (v) => v, parse: (v) => v } },
-    });
-    const partition = opts.partition ?? 'entity';
-    const registry = await loadRegistry(sql, opts.schema, partition);
-    // Entity.account NOT NULL: fallback — System-аккаунт (семантика legacy-движка)
-    const ident = `"${opts.schema.replace(/"/g, '""')}"`;
-    const sys = (await sql.unsafe(`SELECT id FROM ${ident}."Account" WHERE 'System' = ANY(categories) LIMIT 1`));
-    // START_BLOCK_CHECK_DDL_REVISION
-    // Схема, накатанная более старой либой, не получает аддитивных правок ddl.sql (в 0.19.0
-    // так появились purge/purge_closure/purge_account). Без этой проверки приложение узнаёт
-    // о расхождении из сырого `PostgresError: function … does not exist`.
-    // Предупреждение, а не отказ: правки аддитивны — то, что уже работало, работает.
-    await checkDdlRevision(sql, opts.schema);
-    // END_BLOCK_CHECK_DDL_REVISION
-    const ctx = {
-        sql,
-        registry,
-        pgSchema: opts.schema,
-        partition,
-        // account/owner тут НЕ задаются: подключение безличное, арендатора называет db.as().
-        systemAccount: sys[0]?.id,
-        // Изоляция арендатора ВКЛЮЧЕНА по умолчанию (0.20.0): забыть её было слишком легко,
-        // а цена забывчивости — чужие строки в выдаче. Без идентичности вызова (корневой
-        // хендл) чтение/запись при ней запрещены — см. guardScoped в sql.ts.
-        enforceAccount: opts.enforceAccount ?? true,
-        onQuery: opts.onQuery,
-        slowMs: opts.slowMs,
-    };
-    // START_BLOCK_ENFORCE_ACL
-    // enforceAcl: правила и категории субъекта компилятся в резолвер ПОД КОНКРЕТНЫЙ scope.
-    // Функция живёт на ctx, потому что зовут её двое: db.as() (новый субъект) и reload
-    // (тот же субъект на свежем реестре). Субъект берётся из c.account, т.е. из scope.
-    //
-    // Словарь Resource/Rule ОДИН для всех субъектов — снимается один раз на подключение и
-    // переиспользуется каждым db.as(). Иначе scope-per-request (штатный режим в вебе) платил
-    // бы два лишних SELECT на КАЖДЫЙ HTTP-запрос. Per-scope остаётся только чтение своего
-    // аккаунта (категории субъекта) и сама компиляция: один энфорсер = один субъект, иначе
-    // memo в acl.ts (ключ «класс + операция», без аккаунта) отдал бы чужое решение.
-    // Снимок сбрасывает reloadSchema() — как и обещано в README §9.2/§11.10.
-    let aclDict = null;
-    const aclSource = (c) => {
-        aclDict ??= (async () => {
-            const tables = makeTables(c);
-            const [resources, rules] = await Promise.all([tables.resources.find(), tables.rules.find({ enabled: true })]);
-            return { resources, rules };
-        })().catch((e) => {
-            aclDict = null; // не кэшируем провал: следующий db.as() попробует снова
-            throw e;
-        });
-        return aclDict;
+/** Снесено в 1.0.0: пространство имён v5 — id арендатора. Любое использование значения — ошибка. */
+export const LETOPIS_NS = new Proxy({}, {
+    get(_t, p) {
+        if (p === 'then')
+            return undefined;
+        throw removed('LETOPIS_NS', 'пространство имён v5 — id арендатора: idOf(класс, ключ, { tenant })');
+    },
+});
+const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
+const SCHEMA_NAME = /^v\d+\.[a-z_][a-z0-9_]{0,40}$/;
+/** Опции 0.21, снятые в 1.0.0, и их замены (этап 3, п. 11). */
+const REMOVED_OPTIONS = {
+    partition: 'отдельные схемы установки (v2.<имя>)',
+    enforceAccount: 'изоляция арендаторов включена всегда (RLS)',
+    enforceAcl: 'права включены всегда (этап 5)',
+    container: 'Docker в up() не нужен',
+    image: 'Docker в up() не нужен',
+    dataDir: 'Docker в up() не нужен',
+    redisPort: 'Redis не нужен: сессии в базе',
+    version: 'версия схемы — константа движка',
+};
+const quote = (name) => `"${name.replace(/"/g, '""')}"`;
+/** Фасад db: пул (exec — исполнитель пула) или явная транзакция (tx). */
+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,
+        ...(sh.cache ? { cache: { store: sh.cache, who: () => ({ token: txc.token, account: txc.account, tenant: scope.tenant() }) } } : {}),
     };
-    ctx.compileAcl = async (c) => {
-        if (!opts.enforceAcl)
-            return;
-        if (!c.account)
-            throw new Error('letopis: enforceAcl is on — call db.as(account) to name the subject');
-        const [account, dict] = await Promise.all([makeTables(c).accounts.get(c.account), aclSource(c)]);
-        if (!account)
-            throw new Error(`letopis: enforceAcl — account "${c.account}" not found`);
-        c.aclDecide = compileEnforcer(dict, account.id, account.categories, c.registry);
+    // реестр корня меняется после auth.switch — цепочки берут действующий
+    Object.defineProperty(chainCtx, 'reg', { get: scope.registry, enumerable: true });
+    // очереди батчей — свои у фасада, а не общие на подключение: run() исполняет очередь в контексте фасада
+    // (актор, арендатор, владелец, транзакция), значит, в ней только планы, поставленные этим же фасадом
+    const batches = new Map();
+    const noTx = (what) => {
+        throw new LetopisError('tx_required', `${what} — только внутри db.begin()`);
     };
-    // enforceAcl остаётся OPT-IN: включить его по умолчанию нельзя (он работает
-    // deny-by-default, т.е. без настроенных Resource/Rule выдача стала бы пустой).
-    // Поэтому — предупреждение: молчаливое отсутствие авторизации хуже шумного.
-    // Один раз на процесс, иначе утонет в логах приложения с пулом подключений.
-    if (!opts.enforceAcl && !warnedNoAcl) {
-        warnedNoAcl = true;
-        console.warn('letopis: enforceAcl is off — Resource/Rule are NOT checked, reads and writes pass ' +
-            'authorization unconditionally. For production use connect({ enforceAcl: true }) + db.as(account).');
-    }
-    // db.reloadSchema(): перечитать определения классов из таблицы Schema без реконнекта.
-    // Заодно сбрасывается снимок Resource/Rule: правки словаря ACL подхватываются здесь.
-    // На корневом хендле обновляется только реестр (субъекта тут нет); scoped-хендлы
-    // подхватывают его и перекомпилируют свой энфорсер сами (chain.ts, case 'as').
-    ctx.reload = async () => {
-        aclDict = null;
-        ctx.registry = await loadRegistry(sql, opts.schema, partition);
+    const auth = makeAuth(sh.S, exec, async () => {
+        sh.passes.clear();
+        await sh.refresh();
+    }, scope.root && !tx);
+    const acl = makeAcl(sh.S, exec);
+    const adm = { sql: sh.sql, schema: sh.schema, S: sh.S, txc, exec, registry: scope.registry, tenant: scope.tenant };
+    const core = {
+        schema: sh.schema,
+        get token() { return txc.token; },
+        get tenant() { return scope.tenant(); },
+        get registry() { return scope.registry(); },
+        auth,
+        acl,
+        sql: (strings, ...values) => exec.run((q) => q(strings, ...values), { raw: true }),
+        transaction: (fn) => exec.run(fn),
+        idOf: (cls, key) => {
+            const tenant = scope.tenant();
+            if (!tenant)
+                throw new LetopisError('no_session', 'idOf: нет арендатора сессии');
+            const c = scope.registry().resolve(cls);
+            return idOfClass({ name: c.name, key: c.key, ends: Object.keys(c.ends) }, key, { tenant });
+        },
+        refresh: sh.refresh,
+        flushSignals: () => sh.notifier.flush(),
+        verify: (o) => runVerify(adm, o),
+        maintain: (o) => runMaintain(adm, o),
+        reset: async (o) => {
+            const r = await runReset(adm, o);
+            sh.passes.clear();
+            sh.cache?.clear();
+            return r;
+        },
+        trimHistory: (target, before) => runTrim(adm, target, before),
+        rekeyClass: (cls, key) => runRekeyClass(adm, cls, key),
+        describe: () => describeModel(adm),
+        watch: (o = {}) => {
+            if (typeof o === 'function' || typeof o === 'string')
+                throw removed('watch(cb) и watch(класс, cb)', 'watch({ from }) — подписка по курсору');
+            const reg = scope.registry();
+            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); } } : {}),
+            }, o);
+        },
+        cache: {
+            clear: () => sh.cache?.clear(),
+            stats: () => sh.cache?.stats() ?? { size: 0, hits: 0, misses: 0, stores: 0, raced: 0, signals: 0, listens: 0, enabled: false },
+        },
+        entity: (x) => startEntity(chainCtx, x),
+        as: async (account, o) => {
+            if (tx)
+                throw new LetopisError('invalid_query', 'db.as() — от корня подключения, а не внутри db.begin()');
+            const id = account === null ? undefined : typeof account === 'object' ? account.id : account;
+            const nextOwner = o?.owner ?? owner;
+            if (id === undefined && o?.tenant === undefined) {
+                return makeDb(sh, scope, poolExecutor(txc), nextOwner);
+            }
+            // имперсонация и арендатор проверяются базой сразу: ошибка — здесь, а не на первой цепочке
+            const scoped = { ...txc, account: id ?? txc.account, tenant: o?.tenant ?? (id === undefined ? txc.tenant : undefined) };
+            const [r] = await runTx(scoped, (q) => q.unsafe(`select account, tenant from ${sh.S}.ctx()`), { read: true });
+            if (!r?.account)
+                throw new LetopisError('no_session', 'db.as(): нет действующей сессии');
+            const tenant = r.tenant;
+            const registry = await sh.registryFor(tenant, scoped);
+            return makeDb(sh, { txc: scoped, tenant: () => tenant, registry: () => registry, root: false }, poolExecutor(scoped), nextOwner);
+        },
+        begin: async () => {
+            if (tx)
+                throw new LetopisError('invalid_query', 'вложенных транзакций нет: db.begin() внутри db.begin()');
+            const t = await ExplicitTx.open(txc);
+            return makeDb(sh, scope, 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) => {
+            let q = batches.get(name);
+            if (!q)
+                batches.set(name, (q = []));
+            return makeBatch(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()),
     };
-    // END_BLOCK_ENFORCE_ACL
-    return makeDb(ctx);
+    return new Proxy(core, {
+        get(t, prop, r) {
+            if (typeof prop === 'symbol' || prop in t)
+                return Reflect.get(t, prop, r);
+            switch (prop) {
+                case 'then':
+                    return undefined;
+                case 'reloadSchema':
+                    throw removed('reloadSchema()', 'реестр обновляется сам по сигналу; принудительно — db.refresh()');
+                case 'accounts':
+                case 'credentials':
+                case 'resources':
+                case 'rules':
+                    throw removed(`фасад db.${prop}`, 'системные классы Account, Resource, rule, member и db.auth (accounts.purge — db.auth.purgeAccount)');
+                case 'compact':
+                    throw removed('compact()', 'db.trimHistory(цель, момент), политика хранения history и history: false');
+            }
+            return startStep(chainCtx, prop);
+        },
+    });
 }
-/** Курсор keyset-пагинации из последней строки страницы (field как в .sort(), вложенные пути поддержаны). */
-// START_CONTRACT: cursorOf
-//   PURPOSE: Собрать курсор keyset-пагинации из последней строки страницы.
-//   INPUTS: { row: Row - строка результата; field?: string='updated' - поле сортировки как в .sort() (вложенные пути 'data.*' поддержаны) }
-//   OUTPUTS: { Cursor - { v, id } для следующей страницы }
-//   SIDE_EFFECTS: none
-//   LINKS: M-CONNECT, V-M-CONNECT, M-TYPES
-// END_CONTRACT: cursorOf
-export function cursorOf(row, field = 'updated') {
-    const v = field === 'updated'
-        ? row.updated
-        : field.slice(5).split('.').reduce((o, k) => o?.[k], row.data);
-    return { v, id: row.id };
+export async function connect(opts) {
+    if (!SCHEMA_NAME.test(opts.schema))
+        throw new LetopisError('invalid_data', `connect: схема ${opts.schema} — нужно v<N>.<имя>`);
+    if (!opts.sql && !opts.dsn)
+        throw new LetopisError('invalid_data', 'connect: нужен dsn или sql');
+    for (const k of Object.keys(opts))
+        if (k in REMOVED_OPTIONS)
+            throw removed(`опция connect({ ${k} })`, REMOVED_OPTIONS[k]);
+    const own = !opts.sql;
+    // timestamptz — строкой: Date в JS режет микросекунды, а на них держатся asOf и курсоры по времени
+    const sql = (opts.sql ?? postgres(opts.dsn, {
+        max: opts.max ?? 10,
+        onnotice: () => { },
+        types: { timestamptz: { to: 1184, from: [1184], serialize: (v) => (v instanceof Date ? v.toISOString() : v), parse: (v) => v } },
+    }));
+    const S = quote(opts.schema);
+    const owner = opts.owner ?? 'letopis_owner';
+    try {
+        // роль, которая обходит RLS, видела бы данные всех арендаторов (§2.9)
+        const [role] = await sql `select r.rolsuper, r.rolbypassrls,
+        pg_has_role(current_user, ${owner}, 'USAGE') as inherits, pg_has_role(current_user, ${owner}, 'SET') as can_set
+      from pg_roles r where r.rolname = current_user`;
+        const bypass = role.rolsuper || role.rolbypassrls || role.inherits || role.can_set;
+        if (bypass && !opts.allowBypassRls) {
+            throw new LetopisError('bypass_rls', 'роль подключения обходит RLS (суперпользователь, BYPASSRLS или член роли-владельца); администраторское подключение — только с опцией allowBypassRls');
+        }
+        if (bypass)
+            console.warn('letopis: администраторское подключение — RLS не действует, данные всех арендаторов видны');
+        let token = opts.token ?? null;
+        const apiKey = opts.apiKey ?? opts.service;
+        if (!token && apiKey) {
+            const [r] = await sql.unsafe(`select ${S}.login_apikey($1) as t`, [apiKey]).catch((e) => {
+                throw fromDbError(e);
+            });
+            token = r.t;
+        }
+        // ревизия движка: библиотека новее схемы — накат отстал (этап 6, п. 10)
+        const [rv] = await sql `select obj_description(n.oid, 'pg_namespace') as c from pg_namespace n where n.nspname = ${opts.schema}`;
+        const rev = Number(/ddl_revision=(\d+)/.exec(String(rv?.c ?? ''))?.[1] ?? 0);
+        if (!rv)
+            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 })`);
+        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 ?? {});
+        const signals = new Set();
+        // продление сессии (§2.9): отдельным вызовом не чаще раза в минуту; ошибка (реплика,
+        // транзакции только для чтения) не мешает работе
+        let refreshedAt = Date.now();
+        const touch = () => {
+            if (!token || opts.refreshSession === false || Date.now() - refreshedAt < 60_000)
+                return;
+            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) } : {}) };
+        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 });
+        const others = new Map();
+        const refresh = async () => {
+            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(() => []));
+        };
+        const registryFor = async (tenant, txc) => {
+            if (tenant === root.tenant)
+                return root.registry;
+            const known = others.get(tenant);
+            if (known)
+                return known.registry;
+            const registry = new Registry();
+            registry.load(await loadClasses(txc));
+            others.set(tenant, { registry, txc });
+            return registry;
+        };
+        await refresh();
+        // описания классов меняются — реестр перечитывается по сигналу; строки прав — пропуска заново;
+        // кэш результатов и подписки — по именам классов; (пере)подключение слушателя — кэш целиком
+        const onSignal = (cls) => {
+            if (ACL_CLASSES.has(cls) || cls === '*')
+                passes.clear();
+            if (cls === 'Class' || cls === '*')
+                void refresh().catch(() => { });
+            cache?.signal(cls);
+            for (const fn of signals)
+                fn(cls);
+        };
+        const listener = listen
+            ? await sql.listen(opts.schema, onSignal, () => {
+                cache?.listen();
+                for (const fn of signals)
+                    fn('*');
+            })
+            : null;
+        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,
+            signals,
+            listen,
+            async close() {
+                stopMaintain?.();
+                await notifier.close();
+                await listener?.unlisten();
+                if (own)
+                    await sql.end({ timeout: 5 });
+            },
+        };
+        const db = makeDb(shared, { txc: ctx, tenant: () => root.tenant, registry: () => root.registry, root: true }, poolExecutor(ctx));
+        if (opts.maintain !== undefined)
+            stopMaintain = scheduleMaintain(() => db.maintain(), opts.maintain);
+        return db;
+    }
+    catch (e) {
+        if (own)
+            await sql.end({ timeout: 1 });
+        throw e;
+    }
 }
-// одна точка входа: контейнер + готовность + схема + connect
-export { up } from './up.js';
-// генерация id (attributes.id): формула v5 открыта — id считается ДО создания
-export { uuidv5, uuidv7, LETOPIS_NS } from './uuid.js';
-// операторы фильтров
-export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, } from './ops.js';
-export { totpCode } from './auth.js';
-export { ValidationError } from './write.js';
-export { Registry } from './schema.js';

package/dist/jsonschema.d.ts

@@ -0,0 +1,22 @@
+type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+export type JsonSchema = {
+    [k: string]: Json;
+};
+/** Подмножество, которое понимают база и валидатор. */
+export declare const SUPPORTED: Set<string>;
+/**
+ * Перевод шаблона JavaScript в форму, которую одинаково понимают JavaScript (без флага u) и
+ * PostgreSQL: обозначения классов заменяются явными наборами, остальное не трогается.
+ */
+export declare function translatePattern(p: string, where?: string): string;
+export interface NormalizeOptions {
+    /** Имя модели или поля — для сообщений. */
+    where?: string;
+    /** Проверять, что имена полей верхнего уровня не начинаются с $. */
+    topLevel?: boolean;
+}
+/** Нормализует JSON Schema; бросает LetopisError('invalid_class') с названием поля и ключевого слова. */
+export declare function normalizeSchema(input: JsonSchema, opts?: NormalizeOptions): JsonSchema;
+export {};