letopis 0.20.3 → 1.0.0

package/dist/acl.d.ts

@@ -1,53 +1,29 @@
-/**
- * ACL по таблицам Resource/Rule. Pattern каждой категории — шаблон «своей» сущности:
- *
- *   category='ACCOUNT' — шаблон Account: {"categories": "{A,B}"} — есть любая;
- *     "!{A,B}" — нет ни одной; NULL — все аккаунты. Субъекты правил.
- *   category='API'     — шаблон адреса эндпоинта: {"endpoint": "v2.auth.apikey.*"};
- *     маска: '.'-сегменты, '{a,b}' — альтернативы (вложенные ок), '*' — хвост 1+ сегментов.
- *   category='READ' | 'WRITE' | 'DELETE' — ШАБЛОН СТРОКИ Entity (операция = категория):
- *     ключи — реальные колонки (class, owner, account, tags, data, links, id, partition),
- *     значения — литералы или "$account" (id текущего аккаунта, подставляется в запрос).
- *     "class" — маска с lineage (класс или любой его предок); нет ключа/NULL — все строки.
- *     Остальные ключи победившего allow-правила вливаются в SQL ДО сортировки и лимита —
- *     пагинация/count/keyset работают по уже суженному множеству.
- *
- * Rule(субъект-alias → объект-alias, permission allow|deny, weight): правила никогда не
- * указывают на конкретный аккаунт — принадлежность группе вычисляется из categories.
- * Побеждает РОВНО ОДНО правило: max weight; при равном весе deny бьёт allow (равные
- * allow — детерминированно по alias ресурса); НЕТ правил — deny (deny-by-default).
- */
-import type { AclOp, AclDecision, ClassDef, Resource, Rule } from './types.js';
-import type { Registry } from './schema.js';
-import type { Tables } from './tables.js';
-export declare const ACL_OPS: readonly AclOp[];
-/** pattern.categories: "{A,B}" | "!{A,B}" | отсутствие/NULL (матч всех). */
-export declare function matchCategories(pattern: Record<string, unknown> | null, cats: string[]): boolean;
-export declare function matchMask(mask: string, value: string): boolean;
-export interface AclApi {
-    /** Может ли аккаунт дёрнуть эндпоинт (Resource category='API'). */
-    check(account: string | {
-        id: string;
-    }, endpoint: string): Promise<AclDecision>;
-    /** Решение операции над классом: allow + остаточный шаблон строк (filter) | deny. */
-    checkData(account: string | {
+import type { Executor } from './tx.js';
+export type AclOp = 'READ' | 'WRITE' | 'DELETE';
+/** Решение по эндпоинту API. */
+export interface AclDecision {
+    allow: boolean;
+    /** Победившее правило: id, группа и объект (alias ресурсов), вес, разрешение. */
+    rule?: {
         id: string;
-    }, className: string, op: AclOp): Promise<AclDecision>;
-    /**
-     * Сбросить кэш Resource/Rule ЭТОГО фасада (db.acl.check/checkData).
-     * NB: энфорсер цепочек под `enforceAcl` — отдельная подсистема; его пересобирает
-     * `db.reloadSchema()` (реестр + ACL-резолвер), а не этот reload().
-     */
-    reload(): void;
+        group: string;
+        object: string;
+        weight: number;
+        permission: 'allow' | 'deny';
+    };
+    /** Код и сообщение запрещающего правила (поля code, message строки rule). */
+    code?: number;
+    message?: string;
 }
-interface AclSource {
-    resources: Resource[];
-    rules: Rule[];
+/** Решение по операции над классом: разрешено и, если есть, условие на строки (шаблон колонок). */
+export interface AclDataDecision {
+    allow: boolean;
+    filter?: Record<string, unknown>;
+}
+export interface AclApi {
+    /** Может ли актор вызвать эндпоинт (ресурсы категории API; правила System и арендатора). */
+    check(endpoint: string): Promise<AclDecision>;
+    /** Решение операции над классом для актора: allow и условие на строки (filter). */
+    checkData(className: string, op: AclOp): Promise<AclDataDecision>;
 }
-export declare function makeAcl(tables: Tables, registry: Registry): AclApi;
-/** Синхронный резолвер для цепочек: категории субъекта и правила — снимок на момент
- *  компиляции (connect либо db.reloadSchema(), который пересобирает энфорсер). */
-export declare function compileEnforcer(src: AclSource, account: string, cats: string[], registry: Registry): (cls: ClassDef, op: AclOp) => AclDecision;
-/** Читаемая ошибка отказа для цепочек. */
-export declare function aclDenied(op: AclOp, clsId: string, d: AclDecision): Error;
-export {};
+export declare function makeAcl(S: string, exec: Executor): AclApi;

package/dist/acl.js

@@ -1,271 +1,26 @@
-export const ACL_OPS = ['READ', 'WRITE', 'DELETE'];
-// --- матчеры -----------------------------------------------------------------
-// START_CONTRACT: matchCategories
-//   PURPOSE: Проверить шаблон pattern.categories ("{A,B}" | "!{A,B}" | NULL) против категорий аккаунта.
-//   INPUTS: { pattern: object|null - шаблон ресурса ACCOUNT; cats: string[] - категории аккаунта }
-//   OUTPUTS: { boolean - подходит ли субъект }
-//   SIDE_EFFECTS: none
-//   LINKS: M-ACL, V-M-ACL
-// END_CONTRACT: matchCategories
-/** pattern.categories: "{A,B}" | "!{A,B}" | отсутствие/NULL (матч всех). */
-export function matchCategories(pattern, cats) {
-    const spec = pattern?.categories;
-    if (typeof spec !== 'string')
-        return true;
-    const neg = spec.startsWith('!');
-    const list = spec
-        .replace(/^!/, '')
-        .replace(/^\{/, '')
-        .replace(/\}$/, '')
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-    const hit = list.some((c) => cats.includes(c));
-    return neg ? !hit : hit;
-}
-// START_CONTRACT: maskBody
-//   PURPOSE: Скомпилировать тело маски в regex-фрагмент: '{a,b}' → альтернативы (рекурсивно), '*' → хвост из 1+ сегментов.
-//   INPUTS: { mask: string - маска с '.'-сегментами }
-//   OUTPUTS: { string - regex-исходник без якорей }
-//   SIDE_EFFECTS: none
-//   LINKS: M-ACL, V-M-ACL
-// END_CONTRACT: maskBody
-/** Маска → regex: '{a,b}' — альтернативы (рекурсивно), '*' — хвост из 1+ сегментов. */
-function maskBody(mask) {
-    // START_BLOCK_MASK_COMPILE
-    let out = '';
-    for (let i = 0; i < mask.length; i++) {
-        const ch = mask[i];
-        if (ch === '{') {
-            let depth = 1;
-            let j = i + 1;
-            for (; j < mask.length && depth; j++) {
-                if (mask[j] === '{')
-                    depth++;
-                else if (mask[j] === '}')
-                    depth--;
-            }
-            const inner = mask.slice(i + 1, j - 1);
-            const parts = [];
-            let d = 0;
-            let start = 0;
-            for (let k = 0; k <= inner.length; k++) {
-                const c = inner[k];
-                if (k === inner.length || (c === ',' && d === 0)) {
-                    parts.push(inner.slice(start, k));
-                    start = k + 1;
-                }
-                else if (c === '{')
-                    d++;
-                else if (c === '}')
-                    d--;
-            }
-            out += '(?:' + parts.map(maskBody).join('|') + ')';
-            i = j - 1;
-        }
-        else if (ch === '*') {
-            out += '[^.]+(?:\\.[^.]+)*';
-        }
-        else if ('.\\+?()[]^$|'.includes(ch)) {
-            out += '\\' + ch;
-        }
-        else {
-            out += ch;
-        }
-    }
-    // END_BLOCK_MASK_COMPILE
-    return out;
-}
-const regexCache = new Map();
-// START_CONTRACT: matchMask
-//   PURPOSE: Сопоставить значение с маской, кэшируя скомпилированный RegExp.
-//   INPUTS: { mask: string; value: string }
-//   OUTPUTS: { boolean }
-//   SIDE_EFFECTS: заполняет regexCache
-//   LINKS: M-ACL, V-M-ACL
-// END_CONTRACT: matchMask
-export function matchMask(mask, value) {
-    let re = regexCache.get(mask);
-    if (!re) {
-        re = new RegExp(`^${maskBody(mask)}$`);
-        regexCache.set(mask, re);
-    }
-    return re.test(value);
-}
-// --- резолюция ----------------------------------------------------------------
-/** Все имена, под которыми класс виден правилам: id+алиас его самого и каждого предка. */
-function classNames(cls, registry) {
-    const names = [];
-    for (const id of cls.ancestors) {
-        names.push(id);
-        try {
-            const a = registry.resolve(id).alias;
-            if (a && a !== id)
-                names.push(a);
-        }
-        catch {
-            /* предок вне реестра — пропуск */
-        }
-    }
-    return names;
-}
-const matchesApi = (r, endpoint) => {
-    if (r.category !== 'API')
-        return false;
-    if (r.pattern == null)
-        return true;
-    const m = r.pattern.endpoint;
-    return typeof m === 'string' && matchMask(m, endpoint);
-};
-/** Ресурс операции op применим к классу? (class-ключ — маска с lineage; нет ключа — все). */
-const matchesRow = (r, op, names) => {
-    if (r.category !== op)
-        return false;
-    if (r.pattern == null)
-        return true;
-    const clsMask = r.pattern.class;
-    return typeof clsMask !== 'string' || names.some((n) => matchMask(clsMask, n));
-};
-/** "$account" → id субъекта, рекурсивно по значениям шаблона. */
-function substitute(v, account) {
-    if (v === '$account')
-        return account;
-    if (Array.isArray(v))
-        return v.map((x) => substitute(x, account));
-    if (v && typeof v === 'object') {
-        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, substitute(x, account)]));
-    }
-    return v;
-}
-/** Остаточный шаблон строки победившего allow: все ключи, кроме class, с подстановкой. */
-function rowFilter(r, account) {
-    if (r.pattern == null)
-        return undefined;
-    const rest = Object.entries(r.pattern).filter(([k]) => k !== 'class');
-    if (!rest.length)
-        return undefined;
-    return Object.fromEntries(rest.map(([k, v]) => [k, substitute(v, account)]));
-}
-// START_CONTRACT: decide
-//   PURPOSE: Выбрать РОВНО ОДНО победившее правило: max weight; при равенстве deny бьёт allow, равные allow — по alias ресурса.
-//   INPUTS: { rules: Rule[]; subjects: Set<string> - alias'ы субъекта; objects: Map<string,Resource> - применимые ресурсы }
-//   OUTPUTS: { { winner?: Rule } }
-//   SIDE_EFFECTS: none
-//   LINKS: M-ACL, V-M-ACL
-// END_CONTRACT: decide
-/** Победитель: max weight; равный вес — deny бьёт allow, равные allow — по alias объекта. */
-function decide(rules, subjects, objects) {
-    // START_BLOCK_DECIDE_WINNER
-    let winner;
-    for (const rule of rules) {
-        if (!rule.enabled || !subjects.has(rule.account) || !objects.has(rule.resource))
-            continue;
-        if (!winner) {
-            winner = rule;
-            continue;
-        }
-        const w = rule.weight ?? 0;
-        const ww = winner.weight ?? 0;
-        if (w > ww ||
-            (w === ww && winner.permission === 'allow' && rule.permission !== 'allow') ||
-            (w === ww && winner.permission === rule.permission && rule.resource < winner.resource)) {
-            winner = rule;
-        }
-    }
-    // END_BLOCK_DECIDE_WINNER
-    return { winner };
-}
-// START_CONTRACT: toDecision
-//   PURPOSE: Превратить победителя в AclDecision (allow + остаточный row-фильтр | deny + code/message | deny-by-default).
-//   INPUTS: { winner?: Rule; objects: Map<string,Resource>; account: string }
-//   OUTPUTS: { AclDecision }
-//   SIDE_EFFECTS: none
-//   LINKS: M-ACL, V-M-ACL, type-AclDecision
-// END_CONTRACT: toDecision
-function toDecision(winner, objects, account) {
-    if (!winner)
-        return { allow: false, message: 'no matching rule (deny by default)' };
-    if (winner.permission !== 'allow') {
-        const meta = (winner.meta ?? {});
-        return { allow: false, rule: winner, code: meta.code, message: meta.message };
-    }
-    const res = objects.get(winner.resource);
-    // остаточный шаблон строк — только у ресурсов-операций (у API pattern — не строки Entity)
-    const filter = ACL_OPS.includes(res.category) ? rowFilter(res, account) : undefined;
-    return filter ? { allow: true, rule: winner, filter } : { allow: true, rule: winner };
-}
-const subjectAliases = (resources, cats) => new Set(resources.filter((r) => r.category === 'ACCOUNT' && matchCategories(r.pattern, cats)).map((r) => r.alias));
-const toMap = (rs) => new Map(rs.map((r) => [r.alias, r]));
-const accId = (a) => (typeof a === 'object' ? a.id : a);
-// START_CONTRACT: makeAcl
-//   PURPOSE: Построить рантайм-фасад AclApi (check по эндпоинту / checkData по классу+op / reload) с кэшом Resource/Rule.
-//   INPUTS: { tables: Tables; registry: Registry }
-//   OUTPUTS: { AclApi }
-//   SIDE_EFFECTS: лениво читает resources/rules через tables (кэш до reload())
-//   LINKS: M-ACL, V-M-ACL
-// END_CONTRACT: makeAcl
-export function makeAcl(tables, registry) {
-    let cache = null;
-    const load = () => (cache ??= (async () => ({
-        resources: await tables.resources.find(),
-        rules: await tables.rules.find({ enabled: true }),
-    }))());
-    const catsOf = async (account) => (await tables.accounts.get(accId(account)))?.categories ?? [];
-    return {
-        async check(account, endpoint) {
-            const [{ resources, rules }, cats] = await Promise.all([load(), catsOf(account)]);
-            const objects = toMap(resources.filter((r) => matchesApi(r, endpoint)));
-            const { winner } = decide(rules, subjectAliases(resources, cats), objects);
-            return toDecision(winner, objects, accId(account));
-        },
-        async checkData(account, className, op) {
-            const [{ resources, rules }, cats] = await Promise.all([load(), catsOf(account)]);
-            const names = classNames(registry.resolve(className), registry);
-            const objects = toMap(resources.filter((r) => matchesRow(r, op, names)));
-            const { winner } = decide(rules, subjectAliases(resources, cats), objects);
-            return toDecision(winner, objects, accId(account));
+/**
+ * db.acl — решения прав для приложения (план, §2.8, этап 5, п. 7). Сами права применяет база
+ * (политики RLS по плану прав, 50-acl.sql); эти вызовы отвечают «можно ли» заранее — для интерфейса
+ * и эндпоинтов приложения. Правила — строки Resource и rule (группа → объект, allow | deny, вес);
+ * решение — ровно одно правило с наибольшим весом, при равном весе запрет сильнее, нет правил — запрет.
+ */
+import { removed } from './errors.js';
+export function makeAcl(S, exec) {
+    const api = {
+        async check(endpoint) {
+            const [r] = await exec.run((q) => q.unsafe(`select ${S}.acl_check($1) as d`, [endpoint]), { read: true });
+            return r.d;
         },
-        reload() {
-            cache = null;
+        async checkData(className, op) {
+            const [r] = await exec.run((q) => q.unsafe(`select ${S}.acl_check_data($1, $2) as d`, [className, op]), { read: true });
+            return r.d;
         },
     };
-}
-// --- enforce-компилятор (connect({enforceAcl: true})) ----------------------------
-// START_CONTRACT: compileEnforcer
-//   PURPOSE: Скомпилировать синхронный энфорсер (ClassDef, op) → AclDecision с мемоизацией — субъект и правила снимаются В МОМЕНТ вызова (на connect либо на db.reloadSchema()).
-//   INPUTS: { src: AclSource; account: string; cats: string[]; registry: Registry }
-//   OUTPUTS: { (cls: ClassDef, op: AclOp) => AclDecision }
-//   SIDE_EFFECTS: none (мемо-кэш решений)
-//   LINKS: M-ACL, V-M-ACL, M-SQL, M-WRITE
-// END_CONTRACT: compileEnforcer
-/** Синхронный резолвер для цепочек: категории субъекта и правила — снимок на момент
- *  компиляции (connect либо db.reloadSchema(), который пересобирает энфорсер). */
-export function compileEnforcer(src, account, cats, registry) {
-    // START_BLOCK_ENFORCER_MEMO
-    const subjects = subjectAliases(src.resources, cats);
-    const memo = new Map();
-    return (cls, op) => {
-        const key = `${cls.id} ${op}`;
-        let d = memo.get(key);
-        if (!d) {
-            const names = classNames(cls, registry);
-            const objects = toMap(src.resources.filter((r) => matchesRow(r, op, names)));
-            const { winner } = decide(src.rules, subjects, objects);
-            d = toDecision(winner, objects, account);
-            memo.set(key, d);
-        }
-        return d;
-    };
-}
-// END_BLOCK_ENFORCER_MEMO
-// START_CONTRACT: aclDenied
-//   PURPOSE: Собрать читаемую Error отказа ACL для цепочек (её бросают вызывающие sql/write).
-//   INPUTS: { op: AclOp; clsId: string; d: AclDecision }
-//   OUTPUTS: { Error }
-//   SIDE_EFFECTS: none (возвращает Error, не бросает)
-//   LINKS: M-ACL, V-M-ACL
-// END_CONTRACT: aclDenied
-/** Читаемая ошибка отказа для цепочек. */
-export function aclDenied(op, clsId, d) {
-    return new Error(`letopis: acl denies ${op} on ${clsId}${d.message ? ` — ${d.message}` : ''}`);
+    return new Proxy(api, {
+        get(t, p, r) {
+            if (p === 'reload')
+                throw removed('db.acl.reload()', 'права обновляются сами: база применяет действующие правила');
+            return Reflect.get(t, p, r);
+        },
+    });
 }

package/dist/admin.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Эксплуатация (план, этап 6, п. 3, 4, 6–8, 12): verify, maintain и его запуск по расписанию, reset,
+ * обрезка истории, новый ключ класса, describe. Всё проверяет база: функции владельца 90-time.sql
+ * сами сверяют права (letopis.* — системный администратор или администраторское подключение).
+ */
+import type postgres from 'postgres';
+import type { Registry } from './registry.js';
+import { type Executor, type TxContext } from './tx.js';
+type Sql = postgres.Sql<Record<string, unknown>>;
+export interface VerifyIssue {
+    id: string;
+    rev?: number;
+    class?: string;
+    problem: string;
+    [k: string]: unknown;
+}
+export interface VerifyResult {
+    ok: boolean;
+    issues: VerifyIssue[];
+    /** Хэш всех голов цепочек — храните вне базы: подмену последних версий выдаст его расхождение. */
+    anchor: string;
+}
+export interface MaintainOptions {
+    /** Момент «сейчас» для прореживания — только в установке с allowReset (тесты). */
+    now?: string | Date;
+    /** Пачек прореживания за вызов (по умолчанию 100); каждая — своя транзакция. */
+    batches?: number;
+    /** Версий в пачке (по умолчанию 10 000). */
+    limit?: number;
+}
+export interface MaintainReport {
+    /** Другой процесс уже обслуживает установку (advisory-блокировка): этот вызов ничего не делал. */
+    skipped: boolean;
+    /** Удалено истёкших и погашенных сессий и одноразовых кодов. */
+    sessions: number;
+    codes: number;
+    /** Прорежено версий журнала. */
+    thinned: number;
+    batches: number;
+    /** Прореживание не дошло до конца журнала — следующий вызов продолжит. */
+    more: boolean;
+    /** Заполнение очереди сигналов PostgreSQL (0…1); больше половины — предупреждение. */
+    queue: number;
+}
+export interface ResetOptions {
+    level: 'sessions' | 'tenant' | 'all';
+    /** Подтверждение — имя схемы установки. */
+    confirm: string;
+    /** level: 'tenant' — арендатор (по умолчанию — арендатор сессии). */
+    tenant?: string;
+}
+export interface ResetResult {
+    level: string;
+    sessions?: number;
+    tenant?: string;
+    rows?: number;
+    versions?: number;
+    /** level: 'all' — новый ключ сервиса: прежние сессии и ключи больше не действуют. */
+    serviceKey?: string;
+}
+/** Машинное описание модели (db.describe()). */
+export interface ModelDescription {
+    schema: string;
+    tenant: string | null;
+    classes: {
+        name: string;
+        kind: 'hub' | 'link';
+        alias?: string;
+        abstract: boolean;
+        parent?: string;
+        ancestors: string[];
+        system: boolean;
+        fields: Record<string, unknown>;
+        required: string[];
+        ends: Record<string, unknown>;
+        key: string[];
+        history: unknown;
+        ownerDefault: string;
+        cache?: {
+            ttl?: number;
+        };
+        meta: Record<string, unknown>;
+    }[];
+    methods: {
+        chain: readonly string[];
+        db: readonly string[];
+    };
+}
+export interface AdminCtx {
+    sql: Sql;
+    schema: string;
+    /** Схема в кавычках. */
+    S: string;
+    txc: TxContext;
+    exec: Executor;
+    registry: () => Registry;
+    tenant: () => string | null;
+}
+export declare function verify(a: AdminCtx, opts?: {
+    data?: boolean;
+}): Promise<VerifyResult>;
+/**
+ * Обслуживание: истёкшие сессии и коды, прореживание журнала пачками (каждая — своя транзакция,
+ * долгих блокировок нет), заполнение очереди сигналов. Из нескольких процессов работает один: пачка
+ * первым делом берёт транзакционную advisory-блокировку (pg_try_advisory_xact_lock), и та снимается
+ * с фиксацией пачки. Сеансовая блокировка за пулом в режиме транзакций (PgBouncer) оставалась бы на
+ * серверном соединении, которое пул отдаёт другим клиентам, — и обслуживание молча вставало бы
+ * (skipped у всех). Блокировку держит другой процесс: до первой пачки — skipped; между пачками —
+ * вызов останавливается (продолжит тот процесс), отчёт — о сделанном, more: true.
+ */
+export declare function maintain(a: AdminCtx, opts?: MaintainOptions): Promise<MaintainReport>;
+/** Предупреждение о заполненной очереди сигналов (§2.12): больше половины — зависший слушатель. */
+export declare function queueWarning(queue: number): string | null;
+/** Интервал расписания: число мс или '30s', '15m', '1h', '1d'. */
+export declare function parseInterval(v: string | number): number;
+/** Запуск maintain() по расписанию (connect({ maintain: '1h' })): ошибки — предупреждением. */
+export declare function scheduleMaintain(run: () => Promise<unknown>, every: string | number): () => void;
+/**
+ * Сброс (этап 6, п. 6). Предохранители — в базе: флаг allowReset установки, право letopis.reset,
+ * подтверждение именем схемы. tenant — пачками (длинная операция не держит горизонт подписок).
+ */
+export declare function reset(a: AdminCtx, opts: ResetOptions): Promise<ResetResult>;
+/**
+ * Обрезка истории (этап 6, п. 3): версии строже момента before удаляются, текущая — никогда; на место
+ * версии 1 встаёт запись trim. target — имя класса (с потомками), id или список id, строка ответа.
+ */
+export declare function trimHistory(a: AdminCtx, target: string | string[] | {
+    id: string;
+} | {
+    id: string;
+}[], before: string | Date): Promise<number>;
+/** Новый ключ класса (этап 6, п. 7): строки семейства переносятся на новые id. Возвращает их число. */
+export declare function rekeyClass(a: AdminCtx, cls: string, key: string[]): Promise<number>;
+/** Машинное описание модели арендатора вместе с метаданными классов (этап 6, п. 12). */
+export declare function describe(a: AdminCtx): ModelDescription;
+/** Описание модели текстом для языковых моделей (llms.txt). */
+export declare function describeText(d: ModelDescription): string;
+export {};