letopis 1.0.1 → 1.2.0

package/dist/registry.d.ts

@@ -9,6 +9,17 @@ export interface EndInfo {
     onDelete?: 'restrict' | 'cascade' | 'unset';
     meta?: Record<string, unknown>;
 }
+/**
+ * Агрегат в базе (план 1.1, §2.4): поле — сумма поля sum или число (count) живых строк класса of с потомками того же
+ * арендатора, чей одиночный конец via ведёт на строку; where — JSON Schema над данными строки-источника.
+ */
+export interface AggregateInfo {
+    sum?: string;
+    count?: true;
+    of: string;
+    via: string;
+    where?: JsonSchema;
+}
 /** Тип листа данных для фильтров, сортировки и агрегатов (замена fieldTypeOf 0.21). */
 export type LeafType = 'text' | 'numeric' | 'boolean' | 'timestamptz' | 'date' | 'uuid' | 'jsonb';
 export interface ClassInfo {
@@ -29,6 +40,10 @@ export interface ClassInfo {
         ttl?: number;
     };
     meta: Record<string, unknown>;
+    /** Производный класс: строки пишет только проектор с этим именем (план 1.1, §2.4). */
+    derivedBy?: string;
+    /** Агрегатные поля: их считает база, приложение не пишет (план 1.1, §2.4). */
+    aggregate?: Record<string, AggregateInfo>;
     /** Валидатор на TypeScript (компилируется при первом обращении). */
     validator(): Validator;
 }
@@ -40,6 +55,8 @@ interface ClassRow {
         resolved: Record<string, unknown>;
     };
 }
+/** Агрегатные поля класса: их считает база (план 1.1, §2.4). */
+export declare const aggregateFields: (cls: Pick<ClassInfo, "aggregate">) => string[];
 export declare class Registry {
     private byName;
     private byAlias;

package/dist/registry.js

@@ -5,6 +5,17 @@
  */
 import { LetopisError } from './errors.js';
 import { compileValidator } from './validate.js';
+/** Агрегатные поля класса: их считает база (план 1.1, §2.4). */
+export const aggregateFields = (cls) => Object.keys(cls.aggregate ?? {});
+/** Описание агрегатов из resolved — без скомпилированного условия (match): оно для базы. */
+function aggregateOf(agg) {
+    return Object.fromEntries(Object.entries(agg).map(([field, d]) => [field, {
+            ...(typeof d.sum === 'string' ? { sum: d.sum } : { count: true }),
+            of: d.of,
+            via: d.via,
+            ...(d.where && typeof d.where === 'object' ? { where: d.where } : {}),
+        }]));
+}
 export class Registry {
     byName = new Map();
     byAlias = new Map();
@@ -30,6 +41,8 @@ export class Registry {
                 ownerDefault: (res.ownerDefault ?? 'tenant'),
                 cache: (res.cache ?? undefined),
                 meta: (res.meta ?? {}),
+                ...(typeof res.derivedBy === 'string' ? { derivedBy: res.derivedBy } : {}),
+                ...(res.aggregate && typeof res.aggregate === 'object' ? { aggregate: aggregateOf(res.aggregate) } : {}),
                 validator: () => (compiled ??= compileValidator(res.schema)),
             };
             this.byName.set(info.name, info);

package/dist/signals.d.ts

@@ -0,0 +1,73 @@
+export type SignalMode = 'class' | 'tenant' | 'opaque' | 'none';
+export declare const SIGNAL_MODES: readonly SignalMode[];
+/** Разобранный сигнал. */
+export type Signal = 
+/** `*` — сброс: кэш, пропуска прав, реестр и ключ — заново. */
+{
+    kind: 'all';
+}
+/** `session:*` — все сессии. */
+ | {
+    kind: 'sessions';
+}
+/** `session:<тег>` — погашенная сессия (тег — начало sha256 токена). */
+ | {
+    kind: 'session';
+    tag: string;
+}
+/** Запись класса; tenant — токен арендатора, null — все арендаторы (System, режим class, процесс без ключа). */
+ | {
+    kind: 'class';
+    cls: string;
+    tenant: string | null;
+}
+/** Режим opaque, процесс без ключа: что записано, неизвестно. */
+ | {
+    kind: 'opaque';
+}
+/** Незнакомый токен класса: класса нет в реестрах процесса (класс другого арендатора или новый). */
+ | {
+    kind: 'unknown';
+    tenant: string | null;
+}
+/** Нагрузка не по режиму установки: режим сменили без перезапуска процесса или сигнал поддельный. */
+ | {
+    kind: 'foreign';
+};
+export declare class Signals {
+    readonly mode: SignalMode;
+    private key;
+    private hex;
+    private names;
+    private byToken;
+    private tenants;
+    private system;
+    constructor(mode?: SignalMode);
+    /** У процесса есть ключ сигналов. */
+    get keyed(): boolean;
+    /** Ключ из signal_key() (hex); null — процесс без ключа. true — ключ сменился (токены другие). */
+    setKey(hex: string | null): boolean;
+    /** Имена классов реестров процесса: по ним узнаются токены классов в режиме opaque. */
+    setClasses(names: Iterable<string>): void;
+    private rebuild;
+    /** Токен — как signal_token() базы. */
+    private token;
+    /** Токен арендатора для записей кэша и фильтра подписки; null — точности по арендатору нет. */
+    tenantToken(id: string | null | undefined): string | null;
+    /** Разобрать нагрузку сигнала или элемент letopis.changed своей транзакции. */
+    parse(p: string): Signal;
+}
+/**
+ * Не чаще раза в ms: первый вызов — сразу, вызовы внутри окна — один раз в его конце. Так заливка
+ * канала сигналами (в том числе поддельными) не превращается в поток перечитываний реестра.
+ */
+/**
+ * Ведро жетонов: count вызовов подряд — сразу, дальше не чаще раза в ms (жетон возвращается раз в ms); вызовы
+ * в ожидании сливаются в один. Короткая серия проходит без задержки, заливка — с заданной частотой.
+ */
+export declare function bucket(fn: () => void, count: number, ms: number): (() => void) & {
+    stop(): void;
+};
+export declare function throttle(fn: () => void, ms: number): (() => void) & {
+    stop(): void;
+};

package/dist/signals.js

@@ -0,0 +1,169 @@
+/**
+ * Сигналы базы по режимам установки (план 1.1, §2.2, этап 2): разбор нагрузки и токены.
+ *
+ * Канал — имя схемы; нагрузку строит функция базы signal() по режиму up({ signals }):
+ *   - class — `Booking` (как в 1.0); tenant — `Booking@<токен арендатора>`;
+ *   - opaque — `<токен класса>@<токен арендатора>`; none — сигналов нет;
+ *   - сессии — `session:<16 hex>` и `session:*`, сброс — `*` (кроме none).
+ * Токен — первые 96 бит HMAC-SHA256 от «назначение:значение» на ключе сигналов (signal_key(): HMAC
+ * ключа строки KEY по 'letopis:signals'), 24 строчных шестнадцатеричных знака. Имя класса не содержит
+ * `@`, `:` и `*` (метасхема Class), поэтому нагрузка разбирается однозначно.
+ *
+ * Процесс с ключом (право letopis.signals, сид выдаёт его сервисам) узнаёт классы по токенам и сбрасывает
+ * кэш с точностью до арендатора. Процесс без ключа работает «грубо»: в режиме tenant сбрасывает класс во
+ * всех арендаторах, в режиме opaque любой сигнал сбрасывает весь кэш.
+ */
+import { createHmac } from 'node:crypto';
+import { ACL_CLASS_NAMES } from './types.js';
+export const SIGNAL_MODES = ['class', 'tenant', 'opaque', 'none'];
+const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
+/** Имя класса — по метасхеме Class (40-class.sql). */
+const NAME = /^[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{0,62}$/;
+const TOKEN = /^[0-9a-f]{24}$/;
+export class Signals {
+    mode;
+    key = null;
+    hex = null;
+    names = new Set(ACL_CLASS_NAMES);
+    byToken = new Map();
+    tenants = new Map();
+    system = null;
+    constructor(mode = 'class') {
+        this.mode = mode;
+    }
+    /** У процесса есть ключ сигналов. */
+    get keyed() {
+        return this.key !== null;
+    }
+    /** Ключ из signal_key() (hex); null — процесс без ключа. true — ключ сменился (токены другие). */
+    setKey(hex) {
+        if (hex === this.hex)
+            return false;
+        this.hex = hex;
+        this.key = hex ? Buffer.from(hex, 'hex') : null;
+        this.tenants.clear();
+        this.system = this.key ? this.token('tenant', SYSTEM_ID) : null;
+        this.rebuild();
+        return true;
+    }
+    /** Имена классов реестров процесса: по ним узнаются токены классов в режиме opaque. */
+    setClasses(names) {
+        this.names = new Set([...ACL_CLASS_NAMES, ...names]);
+        this.rebuild();
+    }
+    rebuild() {
+        this.byToken.clear();
+        if (!this.key || this.mode !== 'opaque')
+            return;
+        for (const n of this.names)
+            this.byToken.set(this.token('class', n), n);
+    }
+    /** Токен — как signal_token() базы. */
+    token(purpose, value) {
+        return createHmac('sha256', this.key).update(`${purpose}:${value}`, 'utf8').digest('hex').slice(0, 24);
+    }
+    /** Токен арендатора для записей кэша и фильтра подписки; null — точности по арендатору нет. */
+    tenantToken(id) {
+        if (!id || !this.key || (this.mode !== 'tenant' && this.mode !== 'opaque'))
+            return null;
+        let t = this.tenants.get(id);
+        if (t === undefined) {
+            if (this.tenants.size >= 10_000)
+                this.tenants.clear();
+            t = this.token('tenant', id.toLowerCase());
+            this.tenants.set(id, t);
+        }
+        return t;
+    }
+    /** Разобрать нагрузку сигнала или элемент letopis.changed своей транзакции. */
+    parse(p) {
+        if (p === '*')
+            return { kind: 'all' };
+        if (p === 'session:*')
+            return { kind: 'sessions' };
+        if (p.startsWith('session:'))
+            return /^session:[0-9a-f]{16}$/.test(p) ? { kind: 'session', tag: p.slice(8) } : { kind: 'foreign' };
+        const at = p.indexOf('@');
+        const head = at < 0 ? p : p.slice(0, at);
+        const tail = at < 0 ? null : p.slice(at + 1);
+        // в режиме none сигналов нет, но своя транзакция копит в letopis.changed имена классов
+        if (this.mode === 'class' || this.mode === 'none') {
+            return tail === null && NAME.test(head) ? { kind: 'class', cls: head, tenant: null } : { kind: 'foreign' };
+        }
+        if (tail === null || !TOKEN.test(tail))
+            return { kind: 'foreign' };
+        // токен System — строки, общие для всех арендаторов: сброс класса везде
+        const tenant = this.key && tail !== this.system ? tail : null;
+        if (this.mode === 'tenant')
+            return NAME.test(head) ? { kind: 'class', cls: head, tenant } : { kind: 'foreign' };
+        if (!TOKEN.test(head))
+            return { kind: 'foreign' };
+        if (!this.key)
+            return { kind: 'opaque' };
+        const cls = this.byToken.get(head);
+        return cls ? { kind: 'class', cls, tenant } : { kind: 'unknown', tenant };
+    }
+}
+/**
+ * Не чаще раза в ms: первый вызов — сразу, вызовы внутри окна — один раз в его конце. Так заливка
+ * канала сигналами (в том числе поддельными) не превращается в поток перечитываний реестра.
+ */
+/**
+ * Ведро жетонов: count вызовов подряд — сразу, дальше не чаще раза в ms (жетон возвращается раз в ms); вызовы
+ * в ожидании сливаются в один. Короткая серия проходит без задержки, заливка — с заданной частотой.
+ */
+export function bucket(fn, count, ms) {
+    let tokens = count;
+    let at = Date.now();
+    let timer = null;
+    const call = () => {
+        if (timer)
+            return;
+        const now = Date.now();
+        tokens = Math.min(count, tokens + (now - at) / ms);
+        at = now;
+        if (tokens >= 1) {
+            tokens -= 1;
+            return fn();
+        }
+        timer = setTimeout(() => {
+            timer = null;
+            call();
+        }, Math.ceil((1 - tokens) * ms));
+        timer.unref?.();
+    };
+    return Object.assign(call, {
+        stop: () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+        },
+    });
+}
+export function throttle(fn, ms) {
+    let last = -Infinity;
+    let timer = null;
+    const run = () => {
+        last = Date.now();
+        fn();
+    };
+    const call = () => {
+        if (timer)
+            return;
+        const wait = last + ms - Date.now();
+        if (wait <= 0)
+            return run();
+        timer = setTimeout(() => {
+            timer = null;
+            run();
+        }, wait);
+        timer.unref?.();
+    };
+    return Object.assign(call, {
+        stop: () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+        },
+    });
+}

package/dist/sql.d.ts

@@ -29,7 +29,7 @@ export interface Step {
 }
 /** Уникальная метка узла пути. */
 export declare const nextNodeKey: () => number;
-export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'countPaths' | 'versions' | 'agg';
+export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'countPaths' | 'versions' | 'agg' | 'diff' | 'blame';
 export interface AggSpec {
     fn: 'sum' | 'avg' | 'min' | 'max' | 'countBy';
     field: string;

package/dist/sql.js

@@ -439,6 +439,9 @@ export function cursorOf(row, field) {
 // Построение запроса
 // ---------------------------------------------------------------------------
 const COLS = ['id', 'rev', 'class', 'tenant', 'owner', 'links', 'data', 'tags', 'at', 'author', 'agent', 'op', 'reason', 'moved'];
+/** Колонки журнала, выданные приложению: все, кроме changed (ревью №1 точки А плана 1.1, 10-core.sql). */
+const LOG_COLS = ['seq', 'tx', 'id', 'rev', 'class', 'cv', 'tenant', 'owner', 'links', 'data', 'tags', 'at', 'author', 'agent', 'op', 'reason',
+    'moved', 'prev_hash', 'hash'].map((c) => 'l.' + c).join(', ');
 const colsOf = (a) => COLS.map((c) => `${a}.${c}`).join(', ');
 export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
     if (!steps.length)
@@ -534,7 +537,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         const logPart = (pairs) => 
         // версия журнала по паре (id, rev): вложенный цикл по индексу log_id_rev, без перебора журнала
         `select ${colsOf('x')}, null::int as depth from (${pairs}) f(id, rev) `
-            + `cross join lateral (select * from ${S}.log l where l.id = f.id and l.rev = f.rev) x where ${where('x')}`;
+            + `cross join lateral (select ${LOG_COLS} from ${S}.log l where l.id = f.id and l.rev = f.rev) x where ${where('x')}`;
         const parts = [];
         if (i === 0) {
             if (step.deepMax !== undefined)
@@ -690,14 +693,29 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         case 'countPaths':
             text = `${withClause}select count(*)::int as n ${from}${whereOf(tail)}`;
             break;
-        case 'versions':
-            // с follow — по времени через все связанные id; без — по id и номеру версии
+        case 'versions': {
+            // с sort — по полю и направлению (последние версии первыми — sort('at', 'desc'), с limit — в самом запросе);
+            // без sort: с follow — по времени через все связанные id, без follow — по id и номеру версии
+            const order = sort ? `${sort.expr('v')}${dir}, v.id${dir}, v.rev${dir}` : mods.follow ? 'v.at, v.id, v.rev' : 'v.id, v.rev';
             text = mods.follow
                 ? `${withClause}select to_jsonb(v) as row from (select ${colsOf('l')}, null::int as depth from ${S}.log l `
-                    + `where l.id in (select f.id from f)) v order by v.at, v.id, v.rev${limitOffset()}`
+                    + `where l.id in (select f.id from f)) v order by ${order}${limitOffset()}`
                 : `${withClause}select to_jsonb(v) as row from (select ${colsOf('l')}, null::int as depth from ${S}.log l `
-                    + `where l.id in (select z.id from ${ents} z)) v order by v.id, v.rev${limitOffset()}`;
+                    + `where l.id in (select z.id from ${ents} z)) v order by ${order}${limitOffset()}`;
             break;
+        }
+        case 'diff':
+        case 'blame': {
+            // план 1.1, §2.1: функции базы считают по журналу под RLS — по одному документу на объект шага
+            const h = mods.hist ?? {};
+            const num = (v) => (typeof v === 'number' ? `${p.push(v)}::int` : 'null');
+            const ts = (v) => (typeof v === 'string' ? `${p.push(v)}::text::timestamptz` : 'null');
+            const call = mode === 'diff'
+                ? `${S}.diff_versions(z.id, ${num(h.from)}, ${num(h.to)}, ${ts(h.from)}, ${ts(h.to)}, ${h.follow ? 'true' : 'false'})`
+                : `${S}.blame(z.id, ${ts(h.at)}, ${num(h.limit)})`;
+            text = `${withClause}select ${call} as row from (select distinct z.id from ${ents} z) z order by z.id`;
+            break;
+        }
         case 'agg': {
             if (!agg || !agg.field.startsWith('data.'))
                 fail("агрегат по полю 'data.<путь>'");
@@ -705,7 +723,8 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
             const acc = accessor(path)('z');
             aggLeaf = leaf(path);
             if (agg.fn === 'countBy') {
-                text = `${withClause}select ${acc} as k, count(*)::int as n from ${ents} z group by 1 order by 2 desc, 1`;
+                // limit и offset — группы по убыванию числа (самые частые значения), а не строки
+                text = `${withClause}select ${acc} as k, count(*)::int as n from ${ents} z group by 1 order by 2 desc, 1${limitOffset()}`;
             }
             else {
                 const cast = agg.fn === 'sum' || agg.fn === 'avg' ? '::numeric' : CAST[aggLeaf];
@@ -718,7 +737,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
 }
 /** Строка из to_jsonb(узла): служебные поля в $deleted / $depth, пустые необязательные — без ключа. */
 export function toRow(raw) {
-    const { depth, agent, reason, moved, ...rest } = raw;
+    const { depth, agent, reason, moved, changed: _changed, ...rest } = raw;
     const row = rest;
     if (agent != null)
         row.agent = agent;

package/dist/tx.d.ts

@@ -17,9 +17,10 @@
  * исходную ошибку — при каждом вызове. Обрыв связи во время COMMIT — commit_unknown, без повтора.
  *
  * Сигналы (решение 9 точки А): транзакции библиотеки помечены `letopis.notify = 'deferred'` —
- * триггер не шлёт NOTIFY, а копит имена изменённых классов в `letopis.changed`; после фиксации
- * их забирает нотификатор процесса и раз в интервал (по умолчанию 100 мс) отправляет одной
- * транзакцией без данных: такая фиксация не ждёт диск и не задерживает чужие записи.
+ * триггер не шлёт NOTIFY, а копит готовые нагрузки (по режиму сигналов установки, план 1.1) в
+ * `letopis.changed`; после фиксации их забирает нотификатор процесса и раз в интервал (по умолчанию
+ * 100 мс) отправляет одной транзакцией без данных: такая фиксация не ждёт диск и не задерживает чужие
+ * записи. Неотправленное (ошибка отправки) остаётся в очереди до следующего интервала.
  */
 import type postgres from 'postgres';
 type Sql = postgres.Sql<Record<string, unknown>>;
@@ -32,7 +33,7 @@ export declare function isLogConflict(e: unknown): boolean;
 export declare function isConnectionError(e: unknown): boolean;
 export declare const RETRIES = 3;
 export declare const retryDelay: (attempt: number) => Promise<void>;
-/** Нотификатор процесса: копит имена классов и отправляет их пачкой раз в интервал. */
+/** Нотификатор процесса: копит нагрузки сигналов и отправляет их пачкой раз в интервал. */
 export declare class Notifier {
     private sql;
     private channel;
@@ -43,8 +44,9 @@ export declare class Notifier {
     private stopped;
     private flushing;
     constructor(sql: Sql, channel: string, intervalMs: number, onError?: (e: unknown) => void);
-    /** Добавить классы из letopis.changed (строка через запятую). */
+    /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed: string | null | undefined): void;
+    private schedule;
     /** Отправить накопленное сейчас (вызывается по таймеру и при закрытии). */
     flush(): Promise<void>;
     close(): Promise<void>;
@@ -77,8 +79,8 @@ export interface TxContext {
     /** После успешной операции (продление сессии раз в минуту). */
     after?: () => void;
     /**
-     * После фиксации записи: имена из letopis.changed (классы, session:<тег>) — кэш результатов
-     * сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
+     * После фиксации записи: нагрузки из letopis.changed (сигналы записи, session:<тег>) — кэш
+     * результатов сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
      */
     onChanged?: (names: string[], raw: boolean) => void;
 }

package/dist/tx.js

@@ -39,7 +39,7 @@ function hintTxRetry(e) {
 }
 export const RETRIES = 3;
 export const retryDelay = (attempt) => new Promise((r) => setTimeout(r, 40 * attempt + Math.random() * 40));
-/** Нотификатор процесса: копит имена классов и отправляет их пачкой раз в интервал. */
+/** Нотификатор процесса: копит нагрузки сигналов и отправляет их пачкой раз в интервал. */
 export class Notifier {
     sql;
     channel;
@@ -55,14 +55,17 @@ export class Notifier {
         this.intervalMs = intervalMs;
         this.onError = onError;
     }
-    /** Добавить классы из letopis.changed (строка через запятую). */
+    /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed) {
         if (!changed || this.stopped)
             return;
         for (const c of changed.split(','))
             if (c)
                 this.queue.add(c);
-        if (!this.timer && this.queue.size)
+        this.schedule();
+    }
+    schedule() {
+        if (!this.timer && this.queue.size && !this.stopped)
             this.timer = setTimeout(() => void this.flush(), this.intervalMs);
     }
     /** Отправить накопленное сейчас (вызывается по таймеру и при закрытии). */
@@ -73,9 +76,16 @@ export class Notifier {
         }
         if (!this.queue.size)
             return this.flushing;
-        const classes = [...this.queue];
+        const payloads = [...this.queue];
         this.queue.clear();
-        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${classes}::text[]) as c`.then(() => undefined, this.onError));
+        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${payloads}::text[]) as c`.then(() => undefined, (e) => {
+            // не отправлено (обрыв связи, отказ базы) — обратно в очередь: уйдёт следующим интервалом
+            // (в 1.0.1 такие сигналы терялись, и кэш других процессов устаревал до срока)
+            for (const c of payloads)
+                this.queue.add(c);
+            this.schedule();
+            this.onError(e);
+        }));
         return this.flushing;
     }
     async close() {

package/dist/typed.d.ts

@@ -70,24 +70,39 @@ export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, R
     owner(v: string | {
         id: string;
     }): TypedChain<C, M>;
-    create(data: Partial<DataOf<C>>): TypedChain<C, M>;
+    create(data: Partial<DataOf<C>>, opts?: {
+        reason?: string;
+    }): TypedChain<C, M>;
     update(patch?: PatchOf<DataOf<C>>, opts?: {
         rev?: number;
+        reason?: string;
+    }): TypedChain<C, M>;
+    upsert(data: Partial<DataOf<C>>, opts?: {
+        reason?: string;
     }): TypedChain<C, M>;
-    upsert(data: Partial<DataOf<C>>): TypedChain<C, M>;
     delete(opts?: {
         confirm?: boolean;
+        reason?: string;
+    }): TypedChain<C, M>;
+    anonymize(fields: (keyof DataOf<C> & string)[], opts?: {
+        reason?: string;
     }): TypedChain<C, M>;
-    anonymize(fields: (keyof DataOf<C> & string)[]): TypedChain<C, M>;
-    reclass(cls: string, data?: Record<string, unknown>): TypedChain<unknown, M>;
+    reclass(cls: string, data?: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): TypedChain<unknown, M>;
     forUpdate(): TypedChain<C, M>;
-    restore(): TypedChain<C, M>;
+    restore(opts?: {
+        reason?: string;
+    }): TypedChain<C, M>;
     purge(opts?: {
         confirm?: boolean;
+        reason?: string;
     }): TypedChain<C, M>;
     rekey(patch: Partial<DataOf<C>> & Partial<Record<keyof LinksOf<C>, string | {
         id: string;
-    }>>): TypedChain<C, M>;
+    }>>, opts?: {
+        reason?: string;
+    }): TypedChain<C, M>;
     cache(opts?: {
         ttl?: number;
     }): TypedChain<C, M>;

package/dist/types.d.ts

@@ -2,11 +2,16 @@
  * Общие типы letopis 1.0. Файл наполняется по этапам плана (reports/PLAN-LETOPIS-1.0.md).
  */
 /** Ревизия движка в базе: штамп в lib/sql/99-revision.sql должен совпадать (этап 1). */
-export declare const DDL_REVISION = 5;
+export declare const DDL_REVISION = 6;
+/**
+ * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
+ * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
+ */
+export declare const ACL_CLASS_NAMES: readonly string[];
 /** Методы цепочки: терминалы, модификаторы, глаголы записи (этап 4), охранники снесённого API. */
-export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "anonymize", "reclass", "restore", "purge", "alias", "tags", "owner", "forUpdate", "cache", "rekey", "run", "execute", "account"];
+export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "anonymize", "reclass", "restore", "purge", "alias", "tags", "owner", "forUpdate", "cache", "rekey", "run", "execute", "account", "diff", "blame"];
 /** Свойства корня db (и транзакции db.begin()). */
-export declare const DB_METHODS: readonly ["as", "begin", "commit", "rollback", "lock", "batch", "watch", "close", "registry", "sql", "load", "verify", "maintain", "reset", "describe", "auth", "acl", "idOf", "refresh", "transaction", "flushSignals", "schema", "token", "tenant", "reloadSchema", "accounts", "credentials", "resources", "rules", "compact", "trimHistory", "rekeyClass", "cache"];
+export declare const DB_METHODS: readonly ["as", "begin", "commit", "rollback", "lock", "batch", "watch", "close", "registry", "sql", "load", "verify", "maintain", "reset", "describe", "auth", "acl", "idOf", "refresh", "transaction", "flushSignals", "schema", "token", "tenant", "reloadSchema", "accounts", "credentials", "resources", "rules", "compact", "trimHistory", "rekeyClass", "cache", "projector", "rebuildAggregates"];
 /** Свойства батча db.batch(name). */
 export declare const BATCH_METHODS: readonly ["discard", "size"];
 /**
@@ -98,10 +103,18 @@ export interface ChainMods {
     cache?: {
         ttl?: number;
     };
+    /** Параметры терминалов diff() и blame() (план 1.1, §2.1): номера версий или моменты (ISO). */
+    hist?: {
+        from?: number | string;
+        to?: number | string;
+        at?: string;
+        follow?: boolean;
+        limit?: number;
+    };
 }
 /** Событие хука onQuery: один запрос цепочки. */
 export interface QueryEvent {
-    mode: 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg';
+    mode: 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg' | 'diff' | 'blame';
     /** Классы шагов цепочки. */
     classes: string[];
     ms: number;
@@ -109,3 +122,63 @@ export interface QueryEvent {
     /** ms > slowMs. */
     slow: boolean;
 }
+/** Изменение пути: added — не было, removed — не стало, changed — другое значение. */
+export interface DiffChange {
+    /** Путь: первый сегмент — раздел строки (data, links, tags, owner, class). */
+    path: string[];
+    kind: 'added' | 'removed' | 'changed';
+    before?: unknown;
+    after?: unknown;
+}
+/** Различия объекта между двумя версиями (diff()). */
+export interface DiffResult {
+    id: string;
+    class: string | null;
+    from: {
+        rev: number;
+        at: string;
+        id?: string;
+    } | null;
+    to: {
+        rev: number;
+        at: string;
+        id?: string;
+        deleted?: true;
+    } | null;
+    changes: DiffChange[];
+}
+/** Кто и почему последним изменил лист версии (blame()). */
+export interface BlameField {
+    path: string[];
+    rev: number;
+    at: string;
+    author: string;
+    agent?: string;
+    op: string;
+    reason?: string;
+    /** Другой id (история прошла через смену id при reclass или rekey). */
+    id?: string;
+    /** false — до найденной версии история неполная: изменение могло быть раньше. */
+    exact: boolean;
+}
+/** Поля версии объекта с версиями, которые их изменили (blame()). */
+export interface BlameResult {
+    id: string;
+    class: string;
+    rev: number;
+    deleted?: true;
+    /** История просмотрена целиком и без пропусков. */
+    complete: boolean;
+    fields: BlameField[];
+}
+/** diff(): «до» и «после» — номер версии или момент (ISO-строка, Date); follow — через смену id. */
+export interface DiffOptions {
+    from?: number | string | Date;
+    to?: number | string | Date;
+    follow?: boolean;
+}
+/** blame(): версия на момент at (по умолчанию текущая); limit — сколько версий просматривать (1000). */
+export interface BlameOptions {
+    at?: string | Date;
+    limit?: number;
+}