letopis 1.0.1 → 1.2.0

package/dist/admin.d.ts

@@ -4,7 +4,7 @@
  * сами сверяют права (letopis.* — системный администратор или администраторское подключение).
  */
 import type postgres from 'postgres';
-import type { Registry } from './registry.js';
+import type { AggregateInfo, Registry } from './registry.js';
 import { type Executor, type TxContext } from './tx.js';
 type Sql = postgres.Sql<Record<string, unknown>>;
 export interface VerifyIssue {
@@ -29,7 +29,7 @@ export interface MaintainOptions {
     limit?: number;
 }
 export interface MaintainReport {
-    /** Другой процесс уже обслуживает установку (advisory-блокировка): этот вызов ничего не делал. */
+    /** Другой процесс уже обслуживает установку (держит строку-замок обслуживания): этот вызов ничего не делал. */
     skipped: boolean;
     /** Удалено истёкших и погашенных сессий и одноразовых кодов. */
     sessions: number;
@@ -72,6 +72,10 @@ export interface ModelDescription {
         system: boolean;
         fields: Record<string, unknown>;
         required: string[];
+        /** Условия по нескольким полям (`fields.anyOf` описания с учётом наследования): хотя бы одно должно выполняться. */
+        anyOf?: unknown[];
+        /** Условия по нескольким полям (`fields.oneOf`): ровно одно должно выполняться. */
+        oneOf?: unknown[];
         ends: Record<string, unknown>;
         key: string[];
         history: unknown;
@@ -80,6 +84,10 @@ export interface ModelDescription {
             ttl?: number;
         };
         meta: Record<string, unknown>;
+        /** Производный класс: строки пишет только проектор с этим именем (план 1.1, §2.4). */
+        derivedBy?: string;
+        /** Агрегатные поля: сумма или число живых строк класса-источника, их считает база (план 1.1, §2.4). */
+        aggregate?: Record<string, AggregateInfo>;
     }[];
     methods: {
         chain: readonly string[];
@@ -102,8 +110,9 @@ export declare function verify(a: AdminCtx, opts?: {
 /**
  * Обслуживание: истёкшие сессии и коды, прореживание журнала пачками (каждая — своя транзакция,
  * долгих блокировок нет), заполнение очереди сигналов. Из нескольких процессов работает один: пачка
- * первым делом берёт транзакционную advisory-блокировку (pg_try_advisory_xact_lock), и та снимается
- * с фиксацией пачки. Сеансовая блокировка за пулом в режиме транзакций (PgBouncer) оставалась бы на
+ * первым делом берёт строку-замок обслуживания (lock_try в maintain() базы: for update skip locked строки
+ * secret, которую посторонняя роль не займёт), и та снимается с фиксацией пачки. Сеансовая блокировка
+ * за пулом в режиме транзакций (PgBouncer) оставалась бы на
  * серверном соединении, которое пул отдаёт другим клиентам, — и обслуживание молча вставало бы
  * (skipped у всех). Блокировку держит другой процесс: до первой пачки — skipped; между пачками —
  * вызов останавливается (продолжит тот процесс), отчёт — о сделанном, more: true.
@@ -131,6 +140,17 @@ export declare function trimHistory(a: AdminCtx, target: string | string[] | {
 }[], before: string | Date): Promise<number>;
 /** Новый ключ класса (этап 6, п. 7): строки семейства переносятся на новые id. Возвращает их число. */
 export declare function rekeyClass(a: AdminCtx, cls: string, key: string[]): Promise<number>;
+/**
+ * Ремонт агрегатов (план 1.1, §2.4): поля класса и его потомков во всех арендаторах — заново из живых источников,
+ * под исключительными блокировками семейств целей и источников (запись в них ждёт). Версия пишется только там, где
+ * значение изменилось; возвращает число исправленных строк. Функция владельца — от его роли (set local role), как
+ * загрузчик; подключение проверил вызывающий (admin_required).
+ */
+export declare function rebuildAggregates(env: {
+    sql: Sql;
+    S: string;
+    ownerRole: string;
+}, cls: string): Promise<number>;
 /** Машинное описание модели арендатора вместе с метаданными классов (этап 6, п. 12). */
 export declare function describe(a: AdminCtx): ModelDescription;
 /** Описание модели текстом для языковых моделей (llms.txt). */

package/dist/admin.js

@@ -1,4 +1,4 @@
-import { LetopisError } from './errors.js';
+import { LetopisError, fromDbError } from './errors.js';
 import { runTx } from './tx.js';
 import { CHAIN_METHODS, DB_METHODS } from './types.js';
 const SYSTEM_CLASSES = new Set(['Class', 'Account', 'member', 'Resource', 'rule']);
@@ -7,13 +7,12 @@ export async function verify(a, opts = {}) {
     const r = await one(a, `select ${a.S}.verify($1::boolean) as v`, [opts.data === true]);
     return r.v;
 }
-/** Ключ advisory-блокировки обслуживания: форма с двумя int4, своё пространство (19541). */
-const MAINTAIN_LOCK = (schema) => [19541, schema];
 /**
  * Обслуживание: истёкшие сессии и коды, прореживание журнала пачками (каждая — своя транзакция,
  * долгих блокировок нет), заполнение очереди сигналов. Из нескольких процессов работает один: пачка
- * первым делом берёт транзакционную advisory-блокировку (pg_try_advisory_xact_lock), и та снимается
- * с фиксацией пачки. Сеансовая блокировка за пулом в режиме транзакций (PgBouncer) оставалась бы на
+ * первым делом берёт строку-замок обслуживания (lock_try в maintain() базы: for update skip locked строки
+ * secret, которую посторонняя роль не займёт), и та снимается с фиксацией пачки. Сеансовая блокировка
+ * за пулом в режиме транзакций (PgBouncer) оставалась бы на
  * серверном соединении, которое пул отдаёт другим клиентам, — и обслуживание молча вставало бы
  * (skipped у всех). Блокировку держит другой процесс: до первой пачки — skipped; между пачками —
  * вызов останавливается (продолжит тот процесс), отчёт — о сделанном, more: true.
@@ -23,12 +22,10 @@ export async function maintain(a, opts = {}) {
         throw new LetopisError('invalid_query', 'maintain() — пачками в своих транзакциях, не внутри db.begin()');
     const now = opts.now === undefined ? null : opts.now instanceof Date ? opts.now.toISOString() : opts.now;
     const report = { skipped: false, sessions: 0, codes: 0, thinned: 0, batches: 0, more: false, queue: 0 };
-    const [k1, k2] = MAINTAIN_LOCK(a.schema);
     const max = opts.batches ?? 100;
     for (let i = 0; i < max; i++) {
-        // блокировка и пачка — одним оператором: case вычисляет maintain() только при взятой блокировке
-        const [{ r }] = await runTx(a.txc, (q) => q.unsafe(`select case when pg_try_advisory_xact_lock($1::int, hashtext($2::text))
-        then ${a.S}.maintain($3::text::timestamptz, $4::int) end as r`, [k1, k2, now, opts.limit ?? 10_000]));
+        // блокировку берёт сама maintain() базы — строку-замок, которую посторонняя роль не займёт; занята — null
+        const [{ r }] = await runTx(a.txc, (q) => q.unsafe(`select ${a.S}.maintain($1::text::timestamptz, $2::int) as r`, [now, opts.limit ?? 10_000]));
         if (r === null) {
             if (i === 0)
                 return { ...report, skipped: true };
@@ -122,6 +119,25 @@ export async function rekeyClass(a, cls, key) {
     const r = await one(a, `select ${a.S}.rekey_class($1, $2::jsonb) as n`, [name, key]);
     return r.n;
 }
+/**
+ * Ремонт агрегатов (план 1.1, §2.4): поля класса и его потомков во всех арендаторах — заново из живых источников,
+ * под исключительными блокировками семейств целей и источников (запись в них ждёт). Версия пишется только там, где
+ * значение изменилось; возвращает число исправленных строк. Функция владельца — от его роли (set local role), как
+ * загрузчик; подключение проверил вызывающий (admin_required).
+ */
+export async function rebuildAggregates(env, cls) {
+    if (typeof cls !== 'string' || !cls)
+        throw new LetopisError('invalid_data', 'rebuildAggregates(класс): имя класса');
+    const role = `"${env.ownerRole.replace(/"/g, '""')}"`;
+    return env.sql.begin(async (q) => {
+        await q.unsafe(`set local role ${role}`);
+        await q.unsafe(`select set_config('letopis.reason', 'rebuildAggregates', true)`);
+        const [{ n }] = await q.unsafe(`select ${env.S}.rebuild_aggregates($1) as n`, [cls]);
+        return n;
+    }).catch((e) => {
+        throw fromDbError(e);
+    });
+}
 /** Машинное описание модели арендатора вместе с метаданными классов (этап 6, п. 12). */
 export function describe(a) {
     const classes = a.registry().all().map((c) => ({
@@ -134,12 +150,16 @@ export function describe(a) {
         system: SYSTEM_CLASSES.has(c.name),
         fields: (c.schema.properties ?? {}),
         required: (c.schema.required ?? []),
+        ...(Array.isArray(c.schema.anyOf) ? { anyOf: c.schema.anyOf } : {}),
+        ...(Array.isArray(c.schema.oneOf) ? { oneOf: c.schema.oneOf } : {}),
         ends: c.ends,
         key: c.key,
         history: c.history,
         ownerDefault: c.ownerDefault,
         ...(c.cache ? { cache: c.cache } : {}),
         meta: c.meta,
+        ...(c.derivedBy ? { derivedBy: c.derivedBy } : {}),
+        ...(c.aggregate ? { aggregate: c.aggregate } : {}),
     })).sort((x, y) => Number(x.system) - Number(y.system) || x.name.localeCompare(y.name));
     return { schema: a.schema, tenant: a.tenant(), classes, methods: { chain: CHAIN_METHODS, db: DB_METHODS } };
 }
@@ -158,12 +178,22 @@ export function describeText(d) {
         });
         if (fields.length)
             out.push(`- поля: ${fields.join(', ')}`);
+        if (c.anyOf)
+            out.push(`- условия anyOf (хотя бы одно): ${JSON.stringify(c.anyOf)}`);
+        if (c.oneOf)
+            out.push(`- условия oneOf (ровно одно): ${JSON.stringify(c.oneOf)}`);
         const ends = Object.entries(c.ends).map(([k, v]) => {
             const e = v;
             return `${k}${e.required ? '*' : ''} → ${Array.isArray(e.class) ? e.class.join('|') : e.class}${e.many ? '[]' : ''}`;
         });
         if (ends.length)
             out.push(`- концы: ${ends.join(', ')}`);
+        if (c.derivedBy)
+            out.push(`- производный: строки пишет проектор ${c.derivedBy}, приложение только читает`);
+        for (const [field, a] of Object.entries(c.aggregate ?? {})) {
+            const what = a.sum !== undefined ? `сумма ${a.sum}` : 'число';
+            out.push(`- агрегат ${field} = ${what} строк ${a.of} по концу ${a.via}${a.where ? `, условие ${JSON.stringify(a.where)}` : ''}; поле считает база, приложение его не пишет`);
+        }
         out.push('');
     }
     return out.join('\n');

package/dist/cache.d.ts

@@ -1,3 +1,4 @@
+import { Signals, type Signal } from './signals.js';
 /** Классы, строки которых меняют права и схему: их сигнал сбрасывает весь кэш. */
 export declare const ACL_CLASSES: ReadonlySet<string>;
 export interface CacheOptions {
@@ -25,14 +26,22 @@ export interface CacheStats {
 /** Снимок счётчиков до запроса: ответ кладётся, только если они не изменились. */
 export interface CacheToken {
     epoch: number;
-    classes: [string, number][];
+    /** Класс, его счётчик и счётчик пары «класс, арендатор» (без арендатора — сигналов класса в любом). */
+    classes: [string, number, number][];
     session: number;
+    /** Токен арендатора запроса; null — ответ сбрасывается сигналом класса из любого арендатора. */
+    tenant: string | null;
 }
 /** Начало sha256 токена — так база называет сессию в сигнале session:<16 hex>. */
 export declare const sessionTag: (token: string | null) => string;
 export declare class ResultCache {
+    private sig;
+    private allTenants;
     private map;
     private classEpoch;
+    /** Сигналы класса в арендаторе: по паре и по классу в любом арендаторе (для ответов без арендатора). */
+    private pairEpoch;
+    private anyEpoch;
     private sessionEpoch;
     private epoch;
     private listening;
@@ -40,7 +49,11 @@ export declare class ResultCache {
     readonly ttlMs: number;
     readonly ttlOnly: boolean;
     private max;
-    constructor(opts?: CacheOptions);
+    /**
+     * sig — режим сигналов и ключ подключения (разбор нагрузки, токены арендаторов); allTenants —
+     * подключение видит строки всех арендаторов (обходит RLS): ответ сбрасывается сигналом из любого.
+     */
+    constructor(opts?: CacheOptions, sig?: Signals, allTenants?: boolean);
     /** Кэш работает: слушатель на месте или режим только по сроку. */
     get enabled(): boolean;
     /** Ключ ответа: запрос, параметры и тот, кто спрашивает. */
@@ -49,24 +62,35 @@ export declare class ResultCache {
         account?: string;
         tenant?: string | null;
     }): string;
-    /** Снимок счётчиков классов и сессии — до запроса. */
-    token(classes: readonly string[], session: string): CacheToken;
+    /** Снимок счётчиков классов, пар с арендатором запроса (id) и сессии — до запроса. */
+    token(classes: readonly string[], session: string, tenantId?: string | null): CacheToken;
+    private pairCount;
     get(key: string): unknown[] | undefined;
     /** Положить ответ, если с момента снимка не было сигналов о его классах и сессии. */
     set(key: string, value: unknown[], classes: readonly string[], session: string, tok: CacheToken, ttlMs: number, sessionExpires: number | null): boolean;
-    /** Сбросить ответы, читавшие эти классы. */
+    /** Сбросить ответы, читавшие эти классы (во всех арендаторах). */
     invalidate(classes: Iterable<string>): void;
+    /** Сбросить ответы класса в арендаторе (токен) и ответы без арендатора; null — во всех. */
+    private invalidateIn;
     /** Сбросить ответы сессии (тег — начало sha256 токена). */
     invalidateSession(tag: string): void;
+    /**
+     * Счётчик сигналов по ключу (класс, пара «класс, арендатор», сессия). Ключи приходят в нагрузке сигнала, а её
+     * может прислать любая роль базы: при переполнении карта очищается, и снимки в полёте устаревают целиком
+     * (epoch), — иначе заливка разными именами копила бы счётчики без предела (ревью №1 точки А плана 1.1).
+     */
+    private bump;
     /** Весь кэш. */
     clear(): void;
+    /** Сброс по разобранному сигналу. */
+    apply(s: Signal): void;
     /**
-     * Имена из сигнала или из letopis.changed своей транзакции: классы, `*`, `session:<тег>`,
-     * `session:*`. raw — запись через db.sql: весь кэш.
+     * Нагрузки из letopis.changed своей транзакции (те же, что уйдут сигналом). raw — запись через db.sql:
+     * весь кэш.
      */
     changed(names: Iterable<string>, raw?: boolean): void;
-    /** Сигнал от базы. */
-    signal(name: string): void;
+    /** Сигнал от базы: нагрузка или уже разобранный. */
+    signal(s: string | Signal): void;
     /** Слушатель (пере)подключился: сигналы за время обрыва потеряны — весь кэш. */
     listen(): void;
     stats(): CacheStats;

package/dist/cache.js

@@ -6,23 +6,34 @@
  * запрос разным пользователям отдаёт разные строки. Сброс:
  *   - свои записи — сразу после фиксации, по классам из letopis.changed (туда попадают и классы
  *     каскада, unset, смены класса и ключа); запись через db.sql — весь кэш;
- *   - чужие записи — по сигналу базы с именем класса; классы прав и схемы (rule, Resource, member,
- *     Account, Class) и «*» — весь кэш; `session:<16 hex>` — ответы погашенной сессии, `session:*` — все;
- *   - гонка запроса и сигнала: счётчики сигналов по классам и сессиям снимаются до запроса, ответ
- *     кладётся, только если они не изменились;
+ *   - чужие записи — по сигналу базы (нагрузка по режиму установки, signals.ts): класс в арендаторе
+ *     сигнала (ответ помнит токен арендатора запроса; сигнал System и процесс без ключа — во всех), в режиме
+ *     opaque без ключа — весь кэш; классы прав и схемы (rule, Resource, member, Account, Class) и «*» —
+ *     весь кэш; `session:<16 hex>` — ответы погашенной сессии, `session:*` — все;
+ *   - гонка запроса и сигнала: счётчики сигналов по классам, парам «класс, арендатор» и сессиям
+ *     снимаются до запроса, ответ кладётся, только если они не изменились;
  *   - (пере)подключение слушателя сигналов — весь кэш: сигналы за время обрыва потеряны; без слушателя
  *     кэш выключен (с ttlOnly — работает только по сроку);
  *   - срок (по умолчанию 60 с) — предохранитель; ответы истёкшей сессии не используются.
  * Внутри db.begin() и в db.sql кэш не работает.
  */
 import { createHash } from 'node:crypto';
+import { ACL_CLASS_NAMES } from './types.js';
+import { Signals } from './signals.js';
 /** Классы, строки которых меняют права и схему: их сигнал сбрасывает весь кэш. */
-export const ACL_CLASSES = new Set(['rule', 'Resource', 'member', 'Account', 'Class']);
+export const ACL_CLASSES = new Set(ACL_CLASS_NAMES);
+/** Счётчиков сигналов в каждой карте не больше: имена в нагрузке присылает любая роль базы. */
+const EPOCH_MAX = 100_000;
 /** Начало sha256 токена — так база называет сессию в сигнале session:<16 hex>. */
 export const sessionTag = (token) => token ? createHash('sha256').update(token, 'utf8').digest('hex').slice(0, 16) : '';
 export class ResultCache {
+    sig;
+    allTenants;
     map = new Map();
     classEpoch = new Map();
+    /** Сигналы класса в арендаторе: по паре и по классу в любом арендаторе (для ответов без арендатора). */
+    pairEpoch = new Map();
+    anyEpoch = new Map();
     sessionEpoch = new Map();
     epoch = 0;
     listening = false;
@@ -30,7 +41,13 @@ export class ResultCache {
     ttlMs;
     ttlOnly;
     max;
-    constructor(opts = {}) {
+    /**
+     * sig — режим сигналов и ключ подключения (разбор нагрузки, токены арендаторов); allTenants —
+     * подключение видит строки всех арендаторов (обходит RLS): ответ сбрасывается сигналом из любого.
+     */
+    constructor(opts = {}, sig = new Signals(), allTenants = false) {
+        this.sig = sig;
+        this.allTenants = allTenants;
         this.ttlMs = (opts.ttl ?? 60) * 1000;
         this.ttlOnly = opts.ttlOnly === true;
         this.max = opts.max ?? 10_000;
@@ -43,14 +60,19 @@ export class ResultCache {
     key(text, params, who) {
         return JSON.stringify([text, params, who.token ?? '', who.account ?? '', who.tenant ?? '']);
     }
-    /** Снимок счётчиков классов и сессии — до запроса. */
-    token(classes, session) {
+    /** Снимок счётчиков классов, пар с арендатором запроса (id) и сессии — до запроса. */
+    token(classes, session, tenantId) {
+        const tenant = this.allTenants ? null : this.sig.tenantToken(tenantId);
         return {
             epoch: this.epoch,
-            classes: classes.map((c) => [c, this.classEpoch.get(c) ?? 0]),
+            classes: classes.map((c) => [c, this.classEpoch.get(c) ?? 0, this.pairCount(c, tenant)]),
             session: this.sessionEpoch.get(session) ?? 0,
+            tenant,
         };
     }
+    pairCount(cls, tenant) {
+        return (tenant === null ? this.anyEpoch.get(cls) : this.pairEpoch.get(`${cls}@${tenant}`)) ?? 0;
+    }
     get(key) {
         if (!this.enabled)
             return undefined;
@@ -71,70 +93,97 @@ export class ResultCache {
             return false;
         const stale = tok.epoch !== this.epoch
             || tok.session !== (this.sessionEpoch.get(session) ?? 0)
-            || tok.classes.some(([c, n]) => (this.classEpoch.get(c) ?? 0) !== n);
+            || tok.classes.some(([c, n, m]) => (this.classEpoch.get(c) ?? 0) !== n || this.pairCount(c, tok.tenant) !== m);
         if (stale) {
             this.st.raced++;
             return false;
         }
         if (this.map.size >= this.max)
             this.map.delete(this.map.keys().next().value);
-        this.map.set(key, { value, classes: [...classes], session, expires: Date.now() + ttlMs, sessionExpires });
+        this.map.set(key, { value, classes: [...classes], session, tenant: tok.tenant, expires: Date.now() + ttlMs, sessionExpires });
         this.st.stores++;
         return true;
     }
-    /** Сбросить ответы, читавшие эти классы. */
+    /** Сбросить ответы, читавшие эти классы (во всех арендаторах). */
     invalidate(classes) {
         const set = new Set(classes);
         if (!set.size)
             return;
         for (const c of set)
-            this.classEpoch.set(c, (this.classEpoch.get(c) ?? 0) + 1);
+            this.bump(this.classEpoch, c);
         for (const [k, e] of this.map)
             if (e.classes.some((c) => set.has(c)))
                 this.map.delete(k);
     }
+    /** Сбросить ответы класса в арендаторе (токен) и ответы без арендатора; null — во всех. */
+    invalidateIn(cls, tenant) {
+        if (tenant === null)
+            return this.invalidate([cls]);
+        this.bump(this.pairEpoch, `${cls}@${tenant}`);
+        this.bump(this.anyEpoch, cls);
+        for (const [key, e] of this.map)
+            if ((e.tenant === null || e.tenant === tenant) && e.classes.includes(cls))
+                this.map.delete(key);
+    }
     /** Сбросить ответы сессии (тег — начало sha256 токена). */
     invalidateSession(tag) {
-        this.sessionEpoch.set(tag, (this.sessionEpoch.get(tag) ?? 0) + 1);
+        this.bump(this.sessionEpoch, tag);
         for (const [k, e] of this.map)
             if (e.session === tag)
                 this.map.delete(k);
     }
+    /**
+     * Счётчик сигналов по ключу (класс, пара «класс, арендатор», сессия). Ключи приходят в нагрузке сигнала, а её
+     * может прислать любая роль базы: при переполнении карта очищается, и снимки в полёте устаревают целиком
+     * (epoch), — иначе заливка разными именами копила бы счётчики без предела (ревью №1 точки А плана 1.1).
+     */
+    bump(m, k) {
+        if (m.size >= EPOCH_MAX && !m.has(k)) {
+            m.clear();
+            this.epoch++;
+        }
+        m.set(k, (m.get(k) ?? 0) + 1);
+    }
     /** Весь кэш. */
     clear() {
         this.epoch++;
         this.map.clear();
     }
+    /** Сброс по разобранному сигналу. */
+    apply(s) {
+        switch (s.kind) {
+            case 'session':
+                return this.invalidateSession(s.tag);
+            case 'class':
+                return ACL_CLASSES.has(s.cls) ? this.clear() : this.invalidateIn(s.cls, s.tenant);
+            case 'unknown':
+                // класса нет в реестрах процесса — и ответов с ним нет
+                return;
+            default:
+                // *, session:*, opaque без ключа, нагрузка не по режиму
+                return this.clear();
+        }
+    }
     /**
-     * Имена из сигнала или из letopis.changed своей транзакции: классы, `*`, `session:<тег>`,
-     * `session:*`. raw — запись через db.sql: весь кэш.
+     * Нагрузки из letopis.changed своей транзакции (те же, что уйдут сигналом). raw — запись через db.sql:
+     * весь кэш.
      */
     changed(names, raw = false) {
-        const classes = [];
         let any = false;
         for (const n of names) {
             if (!n)
                 continue;
             any = true;
-            if (n === '*' || n === 'session:*' || ACL_CLASSES.has(n)) {
-                this.clear();
-                return;
-            }
-            if (n.startsWith('session:'))
-                this.invalidateSession(n.slice(8));
-            else
-                classes.push(n);
+            if (!raw)
+                this.apply(this.sig.parse(n));
         }
-        if (raw && any) {
+        if (raw && any)
             this.clear();
-            return;
-        }
-        this.invalidate(classes);
     }
-    /** Сигнал от базы. */
-    signal(name) {
+    /** Сигнал от базы: нагрузка или уже разобранный. */
+    signal(s) {
         this.st.signals++;
-        this.changed([name]);
+        this.apply(typeof s === 'string' ? this.sig.parse(s) : s);
     }
     /** Слушатель (пере)подключился: сигналы за время обрыва потеряны — весь кэш. */
     listen() {

package/dist/chain.d.ts

@@ -2,7 +2,7 @@ import { type ResultCache } from './cache.js';
 import type { ClassInfo, Registry } from './registry.js';
 import { type Step } from './sql.js';
 import type { Executor } from './tx.js';
-import type { ChainMods, Cursor, Filter, Path, QueryEvent, Row } from './types.js';
+import type { BlameOptions, BlameResult, ChainMods, Cursor, DiffOptions, DiffResult, Filter, Path, QueryEvent, Row } from './types.js';
 export interface ChainCtx {
     readonly reg: Registry;
     readonly schema: string;
@@ -16,6 +16,9 @@ export interface ChainCtx {
     readonly slowMs?: number;
     /** Цепочка из батча: план копится в очереди до batch.run(). */
     readonly batch?: BatchRef;
+    /** Причина изменения по умолчанию для глаголов (db.batch(имя, { reason })) и та, что стоит в транзакции (db.begin({ reason })). */
+    readonly reason?: string;
+    readonly txReason?: string;
     /** Кэш результатов подключения и тот, кто спрашивает (ключ ответа, §2.12). */
     readonly cache?: {
         store: ResultCache;
@@ -61,6 +64,10 @@ export interface ChainCore {
     versions(opts?: {
         follow?: boolean;
     }): Promise<Row[]>;
+    /** Что изменилось между двумя версиями или моментами (по умолчанию — предыдущая версия → последняя), план 1.1. */
+    diff(opts?: DiffOptions): Promise<DiffResult[]>;
+    /** Кто, когда и почему последним изменил каждое поле версии (по умолчанию текущей), план 1.1. */
+    blame(opts?: BlameOptions): Promise<BlameResult[]>;
     /** Агрегаты по полю последнего шага ('data.<путь>') — по сущностям, считает база. */
     sum(field: string): Promise<number | null>;
     avg(field: string): Promise<number | null>;
@@ -92,31 +99,46 @@ export interface ChainCore {
     /** Вставить узел: ленивая цепочка-паттерн или строка ответа; та же переменная повторно — возврат к её узлу. */
     entity(x: Chain | Row): Chain;
     /** Создать объект: концы — из пути и слотов; занятый ключ — ошибка exists с id. */
-    create(data?: Record<string, unknown>): Chain;
+    create(data?: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): Chain;
     /** Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — строгий режим. */
     update(patch?: Record<string, unknown>, opts?: {
         rev?: number;
+        reason?: string;
     }): Chain;
     /** Создать или заменить целиком (класс с ключом); строка ответа несёт $upsert. */
-    upsert(data: Record<string, unknown>): Chain;
+    upsert(data: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): Chain;
     /** Удалить цели шага с каскадом; без { confirm: true } — превью замыкания ($action). */
     delete(opts?: {
         confirm?: boolean;
+        reason?: string;
     }): Chain;
     /** Затереть строковые поля ('[erased]') и пометить тегом anonymized. */
-    anonymize(fields: string[]): Chain;
+    anonymize(fields: string[], opts?: {
+        reason?: string;
+    }): Chain;
     /** Сменить класс: у класса с ключом — новый id и перевод ссылок. */
-    reclass(cls: string, data?: Record<string, unknown>): Chain;
+    reclass(cls: string, data?: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): Chain;
     /** Чтение с блокировкой строк последнего шага до конца db.begin() (rows, first, ids). */
     forUpdate(): Chain;
     /** Восстановить удалённые объекты шага: последний снимок новой версией (id прежний). */
-    restore(): Chain;
+    restore(opts?: {
+        reason?: string;
+    }): Chain;
     /** Стереть историю удалённых объектов шага; без { confirm: true } — превью ($versions). */
     purge(opts?: {
         confirm?: boolean;
+        reason?: string;
     }): Chain;
     /** Новое значение ключа: строка с новым id, ссылки переведены (поля — данные, роли — концы). */
-    rekey(patch: Record<string, unknown>): Chain;
+    rekey(patch: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): Chain;
     /** Кэш результатов (§2.12): ответ хранится в памяти процесса ttl секунд (по умолчанию 60). */
     cache(opts?: {
         ttl?: number;