letopis 1.0.1 → 1.2.0

package/dist/types.js

@@ -2,7 +2,12 @@
  * Общие типы letopis 1.0. Файл наполняется по этапам плана (reports/PLAN-LETOPIS-1.0.md).
  */
 /** Ревизия движка в базе: штамп в lib/sql/99-revision.sql должен совпадать (этап 1). */
-export const DDL_REVISION = 5;
+export const DDL_REVISION = 6;
+/**
+ * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
+ * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
+ */
+export const ACL_CLASS_NAMES = ['rule', 'Resource', 'member', 'Account', 'Class'];
 // ---------------------------------------------------------------------------
 // Методы цепочки — единственный источник зарезервированных имён (план, §2.14, этап 3, п. 10)
 // ---------------------------------------------------------------------------
@@ -11,14 +16,14 @@ export const CHAIN_METHODS = [
     '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',
+    'forUpdate', 'cache', 'rekey', 'run', 'execute', 'account', 'diff', 'blame',
 ];
 /** Свойства корня db (и транзакции db.begin()). */
 export const DB_METHODS = [
     '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',
+    'trimHistory', 'rekeyClass', 'cache', 'projector', 'rebuildAggregates',
 ];
 /** Свойства батча db.batch(name). */
 export const BATCH_METHODS = ['discard', 'size'];

package/dist/up.d.ts

@@ -1,5 +1,6 @@
 import postgres from 'postgres';
 import { type PgliteOptions, type PgliteServer } from './pglite.js';
+import { type SignalMode } from './signals.js';
 export declare const SYSTEM_ID = "2eba6d0a-1edd-4bb6-a85a-a703dab49035";
 export declare const SCHEMA_VERSION = "v2";
 export interface InstallOptions {
@@ -25,6 +26,12 @@ export interface InstallOptions {
     migrationsDir?: string;
     /** Свой ключ сервиса: зарегистрировать, если такого ещё нет (вместо выпуска случайного). */
     serviceKey?: string;
+    /**
+     * Режим сигналов NOTIFY (план 1.1, §2.2): 'class' (по умолчанию, как в 1.0) — имена классов; 'tenant' —
+     * имя класса и токен арендатора; 'opaque' — только токены; 'none' — сигналов нет. Режим хранится в
+     * схеме: накат без опции его не меняет, reset({ all }) — сохраняет.
+     */
+    signals?: SignalMode;
 }
 /** Политика хранения истории (§2.11): сроки ярусов по возрастанию, 'forever' — бессрочно. */
 export interface HistoryPolicy {
@@ -44,6 +51,8 @@ export interface InstallResult {
     serviceKey: string | null;
     /** Применённые миграции. */
     migrations: string[];
+    /** Режим сигналов установки после наката. */
+    signals: SignalMode;
 }
 export declare const quoteIdent: (name: string) => string;
 /** Файлы ядра по номеру: `10-core.sql` … `99-revision.sql`; сиды демо-домена сюда не входят. */
@@ -88,6 +97,8 @@ export interface UpResult extends InstallResult {
     pglite?: PgliteServer;
     /** up({ tenant }): арендатор (и его первый пользователь с сессией). */
     tenant?: TenantResult;
+    /** Предупреждения (версия сервера); без quiet каждое уже напечатано через console.warn. */
+    warnings: string[];
 }
 type Ping = {
     ok: true;
@@ -100,8 +111,11 @@ type Ping = {
 export declare function pgPing(dsn: string): Promise<Ping>;
 /** Создать базу строки подключения, если её нет (гонка параллельных up() — 42P04 — не ошибка). */
 export declare function ensureDatabase(dsn: string, log?: (m: string) => void): Promise<boolean>;
-/** Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8). */
-export declare function checkServer(versionNum: number, encoding: string): void;
+/**
+ * Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8) —
+ * иначе отказ. Возвращает предупреждения: с чем установка работает, но рискует.
+ */
+export declare function checkServer(versionNum: number, encoding: string): string[];
 /** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
 export declare function schemaRevision(sql: postgres.Sql, schema: string): Promise<number | null>;
 /**

package/dist/up.js

@@ -20,6 +20,7 @@ import { startPglite } from './pglite.js';
 import { hashPassword } from './auth.js';
 import { LetopisError } from './errors.js';
 import { v5Id } from './uuid.js';
+import { SIGNAL_MODES } from './signals.js';
 export const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
 export const SCHEMA_VERSION = 'v2';
 const SQL_DIR = fileURLToPath(new URL('../sql/', import.meta.url));
@@ -48,6 +49,9 @@ export async function install(sql, opts) {
     for (const r of [owner, app])
         if (!ROLE_NAME.test(r))
             throw new Error(`letopis.up: bad role name "${r}"`);
+    if (opts.signals !== undefined && !SIGNAL_MODES.includes(opts.signals)) {
+        throw new Error(`letopis.up: signals — ${SIGNAL_MODES.join(', ')}, а не ${String(opts.signals)}`);
+    }
     const [{ v }] = await sql `select current_setting('server_version_num') as v`;
     if (Number(v) < 180000)
         throw new Error(`letopis.up: нужен PostgreSQL 18 или новее, а сервер — ${v}`);
@@ -81,14 +85,27 @@ export async function install(sql, opts) {
         HISTORY_DEFAULT: quoteLiteral(JSON.stringify(opts.history ?? null)),
         // методы цепочки — в тексте функции reserved_names() (план, §2.14)
         RESERVED_NAMES: RESERVED_CLASS_NAMES.map(quoteLiteral).join(', '),
+        // режим сигналов — после set role: сохранённый режим лежит в строке ключа secret владельца
+        SIGNALS: 'class',
     };
     // Схема создаётся до set role: у владельца может не быть права CREATE в базе.
     await sql.unsafe(`create schema if not exists ${quoteIdent(opts.schema)} authorization ${quoteIdent(owner)}`);
     const files = await engineFiles(opts.upTo);
     const migrations = opts.migrateFrom === undefined ? [] : await migrationFiles(opts.migrationsDir ?? MIGRATE_DIR, opts.migrateFrom);
     let serviceKey = null;
+    let signals = 'class';
     await sql.begin(async (tx) => {
         await tx.unsafe(`set local role ${quoteIdent(owner)}`);
+        // режим сигналов (план 1.1, §2.6): опция, иначе сохранённый в схеме (meta строки ключа), иначе class
+        let saved = null;
+        const [reg] = await tx.unsafe(`select to_regclass($1) is not null as ok`, [`${quoteIdent(opts.schema)}.secret`]);
+        if (reg?.ok) {
+            const [k] = await tx.unsafe(`select meta->>'signals' as m from ${quoteIdent(opts.schema)}.secret where id = $1::uuid and kind = 'KEY'`, [SYSTEM_ID]);
+            if (SIGNAL_MODES.includes(k?.m))
+                saved = k.m;
+        }
+        signals = opts.signals ?? saved ?? 'class';
+        vars.SIGNALS = signals;
         // структурные изменения прежних ревизий — до повторного наката функций (этап 6, п. 10)
         for (const m of migrations) {
             try {
@@ -155,7 +172,7 @@ export async function install(sql, opts) {
             }
         }
     });
-    return { schema: opts.schema, owner, app, serviceKey, migrations };
+    return { schema: opts.schema, owner, app, serviceKey, migrations, signals };
 }
 /** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */
 export async function migrationFiles(dir, from) {
@@ -213,12 +230,22 @@ export async function ensureDatabase(dsn, log = () => { }) {
         await sql.end({ timeout: 1 });
     }
 }
-/** Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8). */
+/**
+ * Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8) —
+ * иначе отказ. Возвращает предупреждения: с чем установка работает, но рискует.
+ */
 export function checkServer(versionNum, encoding) {
     if (versionNum < 180000)
         throw new Error(`letopis.up: нужен PostgreSQL 18 или новее, а сервер — ${Math.floor(versionNum / 10000)} (${versionNum})`);
     if (encoding.toUpperCase() !== 'UTF8')
         throw new Error(`letopis.up: база в кодировке ${encoding}, нужна UTF8 (casefold и коллация pg_unicode_fast)`);
+    const warnings = [];
+    // план 1.1, этап 2: исправлено в 18.2
+    if (versionNum < 180002) {
+        warnings.push(`PostgreSQL ${Math.floor(versionNum / 10000)}.${versionNum % 10000}: до 18.2 сервер мог усечь CLOG, который ещё нужен `
+            + 'непрочитанным сигналам NOTIFY; обновите сервер до 18.2 или новее');
+    }
+    return warnings;
 }
 /** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
 export async function schemaRevision(sql, schema) {
@@ -267,7 +294,10 @@ export async function up(opts) {
     try {
         const [srv] = await sql `select current_setting('server_version_num')::int as v, pg_encoding_to_char(encoding) as enc
       from pg_database where datname = current_database()`;
-        checkServer(srv.v, srv.enc);
+        const warnings = checkServer(srv.v, srv.enc);
+        if (!opts.quiet)
+            for (const w of warnings)
+                console.warn(`letopis.up: ${w}`);
         if (opts.fresh) {
             await sql.unsafe(`drop schema if exists ${quoteIdent(schema)} cascade`);
             log(`схема ${schema} удалена (fresh)`);
@@ -290,7 +320,7 @@ export async function up(opts) {
         const revision = (await schemaRevision(sql, schema)) ?? 0;
         log(`${before === null ? 'схема поставлена' : before < DDL_REVISION ? `схема обновлена с ревизии ${before}` : 'повторный накат'}: ${schema}, ревизия ${revision}`);
         const tenant = opts.tenant ? await createTenant(sql, schema, opts.tenant, opts.owner) : undefined;
-        return { ...res, created: before === null, upgraded: before !== null && before < DDL_REVISION, revision, analyzed,
+        return { ...res, created: before === null, upgraded: before !== null && before < DDL_REVISION, revision, analyzed, warnings,
             ...(lite ? { pglite: lite } : {}), ...(tenant ? { tenant } : {}) };
     }
     catch (e) {

package/dist/uuid.js

@@ -5,18 +5,29 @@
  * (`v5_name` в lib/sql/30-validate.sql — текстовый вид jsonb-массива): элементы через JSON.stringify,
  * разделитель — запятая с пробелом. Совпадение закрепляет общий файл векторов lib/test/vectors/v5.json.
  */
-import { createHash } from 'node:crypto';
+import { hash } from 'node:crypto';
 import { LetopisError } from './errors.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// байты пространств имён (арендаторов): в загрузке их единицы, а проверка и разбор шли на каждый id
+const NS = new Map();
+function nsBytes(ns) {
+    let b = NS.get(ns);
+    if (!b) {
+        if (!UUID.test(ns))
+            throw new LetopisError('invalid_data', `пространство имён v5 — не uuid: ${ns}`);
+        b = Buffer.from(ns.replace(/-/g, ''), 'hex');
+        if (NS.size >= 10_000)
+            NS.clear();
+        NS.set(ns, b);
+    }
+    return b;
+}
 /** RFC 4122 v5: sha1(пространство + имя); одно имя в одном пространстве — один id. */
 export function uuidv5(name, ns) {
-    if (!UUID.test(ns))
-        throw new LetopisError('invalid_data', `пространство имён v5 — не uuid: ${ns}`);
-    const h = createHash('sha1').update(Buffer.from(ns.replace(/-/g, ''), 'hex')).update(name, 'utf8').digest().subarray(0, 16);
-    h[6] = (h[6] & 0x0f) | 0x50; // версия 5
-    h[8] = (h[8] & 0x3f) | 0x80; // вариант 10xx
-    const x = h.toString('hex');
-    return `${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20, 32)}`;
+    const x = hash('sha1', Buffer.concat([nsBytes(ns), Buffer.from(name, 'utf8')]), 'hex');
+    // версия 5 — старшая тетрада байта 6; вариант 10xx — старшие биты байта 8
+    const variant = ((parseInt(x[16], 16) & 0x3) | 0x8).toString(16);
+    return `${x.slice(0, 8)}-${x.slice(8, 12)}-5${x.slice(13, 16)}-${variant}${x.slice(17, 20)}-${x.slice(20, 32)}`;
 }
 /** Имя v5: JSON-массив из имени класса и значений ключа — как `jsonb_build_array(…)::text` в базе. */
 export function v5Name(cls, values) {

package/dist/watch.d.ts

@@ -1,5 +1,6 @@
 import type { Executor } from './tx.js';
 import type { Row } from './types.js';
+import type { Signal } from './signals.js';
 export interface WatchOptions {
     /** Откуда: курсор события, 'now' (по умолчанию — изменения после подписки) или 'start' (весь журнал). */
     from?: string;
@@ -26,9 +27,17 @@ export interface WatchCtx {
     exec: Executor;
     /** Классы подписки с потомками (null — все). */
     classes: string[] | null;
-    /** Подписка на сигналы базы; возвращает отписку. */
-    onSignal?: (fn: (name: string) => void) => () => void;
+    /** Подписка на сигналы базы (разобранные); возвращает отписку. */
+    onSignal?: (fn: (s: Signal) => void) => () => void;
+    /** Токен арендатора подписки (null — процесс без ключа или режим без токенов). */
+    tenant?: () => string | null;
 }
+/**
+ * Будит ли сигнал подписку: свои классы (watched; null — все) и свой арендатор (mine — токен; null —
+ * любой); сессии не будят; *, opaque без ключа и нагрузка не по режиму — будят. Незнакомый токен класса
+ * будит только подписку на все классы: классы подписки с перечнем есть в реестре, их токены известны.
+ */
+export declare function wakes(s: Signal, watched: ReadonlySet<string> | null, mine: string | null): boolean;
 export declare class Subscription implements AsyncIterable<WatchEvent> {
     private ctx;
     private opts;
@@ -44,13 +53,25 @@ export declare class Subscription implements AsyncIterable<WatchEvent> {
     private readonly pollMs;
     /** 'now' — голова журнала в момент подписки (запрос уходит сразу). */
     private start;
+    /** Вызовы next() — по очереди: параллельные получают разные события (доработки после точки Б). */
+    private queue;
     constructor(ctx: WatchCtx, opts: WatchOptions);
     /** Курсор последнего выданного события (или начальной точки). */
     get cursor(): string | null;
+    /**
+     * Начальная точка взята (доработки после точки Б): у from: 'now' — горизонт и снимок момента подписки (watch_head());
+     * у 'start' и курсора — сразу. Запись после await sub.ready() придёт в поток; ошибка начальной точки — отказ.
+     */
+    ready(): Promise<void>;
     private head;
     /** Следующая пачка событий ниже горизонта; пусто — горизонт ещё не дошёл или событий нет. */
     private fetch;
+    /**
+     * Следующее событие. Вызовы идут по очереди: параллельные next() получают разные события, без двойных. Вызов,
+     * брошенный по таймауту (Promise.race), всё равно получит своё событие — держите его обещание.
+     */
     next(): Promise<IteratorResult<WatchEvent>>;
+    private take;
     /**
      * Отставание, мс: сколько ждёт самое старое событие, которое уже зафиксировано, но ещё не ушло за
      * горизонт (его держит более старая открытая транзакция); 0 — ждать нечего.

package/dist/watch.js

@@ -8,8 +8,9 @@
  * транзакций (pg_snapshot_xmin) — транзакцию с меньшим номером, зафиксированную позже, курсор уже
  * не обгонит, поэтому событий нет ни потерянных, ни повторных. Поток стоит, пока открыта более
  * старая пишущая транзакция (горизонт общий для кластера); метрика — lag(). Чтение идёт под RLS
- * журнала: каждый видит только своё. Сигнал базы с именем класса только будит подписку (чужие
- * классы — не будят); без LISTEN и на случай потери сигнала — запасной опрос.
+ * журнала: каждый видит только своё. Сигнал базы только будит подписку: свои классы и свой арендатор
+ * (чужие — не будят; процесс без ключа сигналов арендатора не различает, в режиме opaque — и класса);
+ * без LISTEN и на случай потери сигнала — запасной опрос.
  *
  * Курсор подписчика старше яруса all политики хранения его классов — cursor_expired: события могли
  * проредиться, нужно перечитать текущее состояние и подписаться заново.
@@ -28,6 +29,25 @@ function decode(c) {
 }
 /** Снимок ещё нужен: курсор не дошёл до его xmax. */
 const keepSnap = (snap, tx) => snap && BigInt(tx) < BigInt(snap.split(':')[1]) ? snap : undefined;
+/**
+ * Будит ли сигнал подписку: свои классы (watched; null — все) и свой арендатор (mine — токен; null —
+ * любой); сессии не будят; *, opaque без ключа и нагрузка не по режиму — будят. Незнакомый токен класса
+ * будит только подписку на все классы: классы подписки с перечнем есть в реестре, их токены известны.
+ */
+export function wakes(s, watched, mine) {
+    const ours = (t) => t === null || mine === null || t === mine;
+    switch (s.kind) {
+        case 'session':
+        case 'sessions':
+            return false;
+        case 'class':
+            return (!watched || watched.has(s.cls)) && ours(s.tenant);
+        case 'unknown':
+            return !watched && ours(s.tenant);
+        default:
+            return true;
+    }
+}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class Subscription {
     ctx;
@@ -44,6 +64,8 @@ export class Subscription {
     pollMs;
     /** 'now' — голова журнала в момент подписки (запрос уходит сразу). */
     start = null;
+    /** Вызовы next() — по очереди: параллельные получают разные события (доработки после точки Б). */
+    queue = Promise.resolve();
     constructor(ctx, opts) {
         this.ctx = ctx;
         this.opts = opts;
@@ -60,10 +82,8 @@ export class Subscription {
         }
         if (ctx.onSignal) {
             const watched = ctx.classes ? new Set(ctx.classes) : null;
-            this.off = ctx.onSignal((name) => {
-                if (name === '' || name.startsWith('session:'))
-                    return;
-                if (watched && name !== '*' && !watched.has(name))
+            this.off = ctx.onSignal((s) => {
+                if (!wakes(s, watched, ctx.tenant?.() ?? null))
                     return;
                 this.dirty = true;
                 this.wake?.();
@@ -79,6 +99,14 @@ export class Subscription {
     get cursor() {
         return this.pos ? encode(this.pos) : null;
     }
+    /**
+     * Начальная точка взята (доработки после точки Б): у from: 'now' — горизонт и снимок момента подписки (watch_head());
+     * у 'start' и курсора — сразу. Запись после await sub.ready() придёт в поток; ошибка начальной точки — отказ.
+     */
+    async ready() {
+        if (!this.pos && this.start)
+            this.pos = await this.start;
+    }
     async head() {
         const [r] = await this.ctx.exec.run((q) => q.unsafe(`select tx::text as tx, seq::text as seq, snap::text as snap from ${this.ctx.S}.watch_head()`), { read: true });
         return { tx: r.tx, seq: r.seq, at: null, snap: r.snap };
@@ -100,7 +128,16 @@ export class Subscription {
         }
         return rows.length;
     }
-    async next() {
+    /**
+     * Следующее событие. Вызовы идут по очереди: параллельные next() получают разные события, без двойных. Вызов,
+     * брошенный по таймауту (Promise.race), всё равно получит своё событие — держите его обещание.
+     */
+    next() {
+        const p = this.queue.then(() => this.take(), () => this.take());
+        this.queue = p.catch(() => undefined);
+        return p;
+    }
+    async take() {
         let empty = 0;
         for (;;) {
             if (this.failure)

package/dist/write.d.ts

@@ -1,4 +1,4 @@
-import type { ClassInfo, Registry } from './registry.js';
+import { type ClassInfo, type Registry } from './registry.js';
 import { type AggSpec, type BuiltQuery, type ReadMode, type Step } from './sql.js';
 import type { Tx } from './tx.js';
 import type { ChainMods, Row } from './types.js';
@@ -17,7 +17,8 @@ export declare function inc(by: number, opts?: {
     start?: number;
 }): IncMarker;
 export declare const isInc: (v: unknown) => v is IncMarker;
-export type PlanOp = {
+/** Глагол плана; reason — причина изменения этого глагола (план 1.1, §2.1). */
+export type PlanOp = ({
     kind: 'create';
     data: Record<string, unknown>;
 } | {
@@ -45,7 +46,11 @@ export type PlanOp = {
 } | {
     kind: 'rekey';
     data: Record<string, unknown>;
+}) & {
+    reason?: string;
 };
+/** Причина изменения: строка до 1000 символов без NUL (её не принимает set_config). */
+export declare function checkReason(v: unknown, where: string): string;
 /** Значение слота: id, список id, строка ответа или ленивая цепочка (в той же транзакции). */
 export type SlotValue = string | string[] | {
     id: string;
@@ -81,6 +86,10 @@ export interface WriteCtx {
     tenant: string | null;
     /** Владелец новых строк по умолчанию (db.as(…, { owner })). */
     owner?: string;
+    /** Причина по умолчанию для глаголов плана и та, что стоит в транзакции; cur — выставленная сейчас. */
+    reason?: string;
+    txReason?: string;
+    cur?: string;
 }
 /** Чтение в транзакции плана — тот же построитель, что у цепочек. */
 export declare function readIn<T>(w: WriteCtx, steps: Step[], mods: ChainMods, mode: ReadMode, agg?: AggSpec): Promise<{

package/dist/write.js

@@ -19,6 +19,7 @@
  */
 import { LetopisError, ValidationError } from './errors.js';
 import { isOp } from './ops.js';
+import { aggregateFields } from './registry.js';
 import { accepts, buildRead, nextNodeKey, resolveHop, stepClasses, toRow } from './sql.js';
 import { idOf } from './uuid.js';
 import { applyDefaults } from './validate.js';
@@ -35,6 +36,13 @@ export function inc(by, opts = {}) {
     return Object.freeze({ [INC]: true, by, ...(opts.start !== undefined ? { start: opts.start } : {}) });
 }
 export const isInc = (v) => typeof v === 'object' && v !== null && v[INC] === true;
+/** Причина изменения: строка до 1000 символов без NUL (её не принимает set_config). */
+export function checkReason(v, where) {
+    if (typeof v !== 'string' || v.length > 1000 || v.includes('\0')) {
+        throw new LetopisError('invalid_query', `${where}: reason — строка до 1000 символов`);
+    }
+    return v;
+}
 const fail = (code, msg, detail) => {
     throw new LetopisError(code, msg, detail);
 };
@@ -108,13 +116,26 @@ function checkFullData(cls, data, verb, full = true) {
                 scan(x, [...path, k]);
     };
     scan(data, []);
+    // агрегатные поля считает база (план 1.1, §2.4): переданное значение — aggregate_field до отправки, а для ранней
+    // проверки поле — 0, как его поставит база
+    const obj = data;
+    const agg = aggregateFields(cls);
+    const given = agg.filter((f) => f in obj);
+    if (given.length)
+        fail('aggregate_field', `поля ${given.join(', ')} класса ${cls.name} считает база (aggregate) — их не передают`);
     // описания системных классов проверяет только база (метасхема Class, class_admit)
     if (!full || cls.name === 'Class' || cls.abstract)
         return;
-    const issues = cls.validator()(applyDefaults(cls.schema, data));
+    const issues = cls.validator()(applyDefaults(cls.schema, agg.length ? { ...obj, ...Object.fromEntries(agg.map((f) => [f, 0])) } : obj));
     if (issues.length)
         throw new ValidationError(cls.name, issues);
 }
+/** Патч update не трогает агрегатные поля класса шага (план 1.1, §2.4): их считает база. */
+function checkAggregatePatch(cls, patch) {
+    const given = aggregateFields(cls).filter((f) => f in patch);
+    if (given.length)
+        fail('aggregate_field', `поля ${given.join(', ')} класса ${cls.name} считает база (aggregate) — update их не меняет`);
+}
 /** Всё, что проверяется без базы, — до отправки первого оператора (§2.5). */
 export function precheckPlan(reg, steps) {
     let prevOp;
@@ -126,6 +147,8 @@ export function precheckPlan(reg, steps) {
             continue;
         }
         const verb = op.kind;
+        if (op.reason !== undefined)
+            checkReason(op.reason, `${verb}()`);
         const m = s.opMods ?? {};
         if (m.asOf !== undefined)
             fail('invalid_query', `${verb}(): asOf описывает прошлое — записывать в него нельзя`);
@@ -153,6 +176,7 @@ export function precheckPlan(reg, steps) {
                 if (!isPlain(op.data))
                     fail('invalid_data', 'update(): патч — объект');
                 splitPatch(op.data);
+                checkAggregatePatch(s.cls, op.data);
                 if (op.rev !== undefined && (!Number.isInteger(op.rev) || op.rev < 1))
                     fail('invalid_query', 'update(patch, { rev }): rev — номер версии строки');
                 break;
@@ -188,6 +212,14 @@ export function precheckPlan(reg, steps) {
         prevOp = op;
     }
 }
+/** letopis.reason перед оператором глагола — только если причина меняется (план 1.1, §2.1). */
+async function useReason(w, want) {
+    if (want === (w.cur ?? w.txReason ?? ''))
+        return;
+    await query(w, `select set_config('letopis.reason', $1, true)`, [want]);
+    w.cur = want;
+}
+const reasonFor = (w, s) => s.op?.reason ?? w.reason ?? '';
 const quoteId = (name) => `"${name.replace(/"/g, '""')}"`;
 /** Строка ответа в том же виде, что у чтения (to_jsonb колонок узла). */
 const rowJson = (a) => `jsonb_build_object('id', ${a}.id, 'rev', ${a}.rev, 'class', ${a}.class, 'tenant', ${a}.tenant, 'owner', ${a}.owner, `
@@ -371,13 +403,16 @@ async function createOp(w, steps, opStep, upsert) {
     const links = applySlotsLocal(await pathEnds(w, steps, new Set(slots.map((x) => x.role))), slots);
     const given = typeof opStep.filter === 'string' ? opStep.filter : undefined;
     const owner = opStep.ownerFilter ?? w.owner ?? null;
+    // агрегатные поля (план 1.1, §2.4): в excluded их поставил триггер вставки (0) — замена данных идёт без них, и
+    // триггер правки возвращает прежние значения
+    const agg = aggregateFields(cls);
     const conflict = upsert
-        ? ` on conflict (id) do update set data = excluded.data, links = excluded.links, tags = excluded.tags`
+        ? ` on conflict (id) do update set data = excluded.data${agg.length ? ' - $7::text[]' : ''}, links = excluded.links, tags = excluded.tags`
         : '';
     const text = `insert into ${S}.entity (id, class, links, data, tags, owner) values ($1::uuid, $2::text, $3::jsonb, $4::jsonb, $5::text[], $6::uuid)`
         + `${conflict} returning old.rev as old_rev, ${rowJson('new')} as row`;
     try {
-        const res = await query(w, text, [given ?? null, cls.name, links, op.data, tagsValue(opStep), owner]);
+        const res = await query(w, text, [given ?? null, cls.name, links, op.data, tagsValue(opStep), owner, ...(upsert && agg.length ? [agg] : [])]);
         return res.map((r) => {
             const row = toRow(r.row);
             if (upsert)
@@ -578,7 +613,8 @@ async function rekeyOp(w, steps, opStep) {
     const res = await query(w, `select ${rowJson('e')} as row from ${S}.entity e where e.id = any ($1::uuid[]) order by e.id`, [moved]);
     return res.map((r) => toRow(r.row));
 }
-function opCall(w, steps, opStep) {
+async function opCall(w, steps, opStep) {
+    await useReason(w, reasonFor(w, opStep));
     switch (opStep.op.kind) {
         case 'create': return createOp(w, steps, opStep, false);
         case 'upsert': return createOp(w, steps, opStep, true);
@@ -652,9 +688,11 @@ export async function execPlan(w, steps, mods, mode, agg) {
             : kind === 'purge' ? [] : last;
         prevOp = opStep;
     }
+    // причина глагола не переходит на следующие операторы транзакции
+    await useReason(w, w.reason ?? '');
     const opStep = segments[segments.length - 1].steps.at(-1);
     const key = opStep.aliasKey ?? opStep.name;
-    if (tail.length || mode === 'versions' || mode === 'agg') {
+    if (tail.length || mode === 'versions' || mode === 'agg' || mode === 'diff' || mode === 'blame') {
         if (!start.length)
             return { kind: 'read', q: null, res: [] };
         const { q, res } = await readIn(w, [fromRows(opStep, start.map((r) => r.id)), ...tail], mods, mode, agg);
@@ -708,7 +746,10 @@ export async function execBatch(w, plans) {
             const group = [];
             const seen = new Set();
             let j = i;
-            while (j < plans.length && pureKind(plans[j]) === 'keyed' && plans[j][0].op.kind === verb && plans[j][0].cls.name === head.cls.name) {
+            // одна причина на оператор: другая причина режет группу
+            const why = reasonFor(w, head);
+            while (j < plans.length && pureKind(plans[j]) === 'keyed' && plans[j][0].op.kind === verb && plans[j][0].cls.name === head.cls.name
+                && reasonFor(w, plans[j][0]) === why) {
                 const s = plans[j][0];
                 const id = idFor(s);
                 if (!id || (verb === 'upsert' && seen.has(id)))
@@ -717,12 +758,15 @@ export async function execBatch(w, plans) {
                 group.push({ at: j, s, id });
                 j++;
             }
+            await useReason(w, why);
             const input = group.map((g) => ({ d: g.s.op.data, t: tagsValue(g.s), o: g.s.ownerFilter ?? w.owner ?? null }));
+            // агрегатные поля — без них, как у одиночного upsert (план 1.1, §2.4)
+            const agg = aggregateFields(head.cls);
             const conflict = verb === 'upsert'
-                ? 'on conflict (id) do update set data = excluded.data, links = excluded.links, tags = excluded.tags'
+                ? `on conflict (id) do update set data = excluded.data${agg.length ? ' - $3::text[]' : ''}, links = excluded.links, tags = excluded.tags`
                 : 'on conflict (id) do nothing';
             const res = await query(w, `insert into ${S}.entity (class, data, tags, owner) select $1::text, x.d, x.t, x.o `
-                + `from jsonb_to_recordset($2::jsonb) as x(d jsonb, t text[], o uuid) ${conflict} returning old.rev as old_rev, ${rowJson('new')} as row`, [head.cls.name, input]);
+                + `from jsonb_to_recordset($2::jsonb) as x(d jsonb, t text[], o uuid) ${conflict} returning old.rev as old_rev, ${rowJson('new')} as row`, [head.cls.name, input, ...(verb === 'upsert' && agg.length ? [agg] : [])]);
             const byId = new Map(res.map((r) => [r.row.id, r]));
             for (const g of group) {
                 const r = byId.get(g.id);
@@ -738,9 +782,11 @@ export async function execBatch(w, plans) {
         }
         else if (kind === 'keyless') {
             let j = i;
-            while (j < plans.length && pureKind(plans[j]) === 'keyless')
+            const why = reasonFor(w, head);
+            while (j < plans.length && pureKind(plans[j]) === 'keyless' && reasonFor(w, plans[j][0]) === why)
                 j++;
-            // однострочные вставки без ожидания ответа каждой — postgres.js шлёт их конвейером
+            // причина — до конвейера; однострочные вставки без ожидания ответа каждой — postgres.js шлёт их конвейером
+            await useReason(w, why);
             const rows = await Promise.all(plans.slice(i, j).map((p) => createOp(w, p, p[0], false)));
             rows.forEach((r, k) => (out[i + k] = r));
             i = j;
@@ -751,5 +797,6 @@ export async function execBatch(w, plans) {
             i++;
         }
     }
+    await useReason(w, w.txReason ?? '');
     return out;
 }

package/llms.txt

@@ -2,14 +2,21 @@
 
 > Versioned entity store for Node.js on PostgreSQL 18. Every change is a version in a journal (history, reads as of a date, cursor subscriptions). Integrity, tenant isolation and access rules are enforced by the database itself (triggers and row-level security), so they hold for raw SQL too. Data is read and written with chains like `db.Shop(shop).Product().rows()`.
 
-Key facts for writing code with letopis 1.0:
+Key facts for writing code with letopis 1.2:
 
-- ESM package, Node 22+, PostgreSQL 18+ with pgcrypto, database encoding UTF8. Runtime dependency: `postgres`. Zod 4 is an optional peer dependency needed only by `letopis/model`.
+- ESM package, Node 22+, PostgreSQL 18+ with pgcrypto, database encoding UTF8. Runtime dependency: `postgres`. Zod 4 is an optional peer dependency needed only by `letopis/model`; `@modelcontextprotocol/server`, only by `letopis/mcp`.
 - Install a schema with `up({ dsn, schema })` from an admin role; the schema is named `v2.<name>`. The application connects with a LOGIN role that is a member of `letopis_app`: `connect({ dsn, schema: 'v2.<name>', token | apiKey })`. A role that bypasses RLS is refused (`bypass_rls`) unless `allowBypassRls: true`.
 - Classes are hubs (objects) and links (relations with ends), described with `hub()`/`link()` from `letopis/model` and written to the database with `syncModels()` or `letopis sync`. A class with a key gets a deterministic UUID v5 id (`db.idOf`); uniqueness is the key.
 - Verbs return a chain; a terminal (`rows`, `first`, `ids`, `count`, …) executes the whole plan in one transaction. `create` only creates (a taken key is `exists`), `update` merges and never creates, `upsert` replaces the whole object (keyed classes only), `delete()` is a preview and `delete({ confirm: true })` deletes.
 - Money and counters: `update({ balance: inc(n) })` adds inside the statement; `update(patch, { rev })` fails with `conflict` if the row changed; `forUpdate()` locks rows inside `db.begin()`.
+- History: `versions()`, `diff({ from, to })` and `blame()` (who, when and why last changed each field); verbs, `db.begin()` and `db.batch()` take `{ reason }`.
+- Bulk loading from an admin connection: `db.load(rows)`; into an empty schema `db.load(rows, { initial: true })` — one transaction, indexes and triggers rebuilt at the end.
+- Projectors from an admin connection: `db.projector(name, { from, into, version, handle })` builds rows of derived classes (`derivedBy: name`) from the journal; each batch is one transaction and every change is applied exactly once; `run()`, `rebuild()`, `status()`. Only the projector writes derived rows: the application, raw SQL and the loader get `derived_class`. Only an administrator creates, changes and deletes derived classes (an admin connection with a tenant session, or `letopis sync` with the admin `--dsn`); for an application session it is `acl_denied`. `purge()` of a deleted source object waits until the projector has read the deletion (`projector_pending`).
+- Aggregates in the database: the class option `aggregate: { balance: { sum: 'amount', of: 'Movement', via: 'Wallet' } }` (or `count: true`, `where` as a JSON Schema) keeps the field equal to the total of live source rows of the same tenant; a trigger after each statement recalculates it for the library, raw SQL, cascades and the loader; only the database writes the field (`aggregate_field`); repair with `db.rebuildAggregates(class)` on an admin connection, check with `db.verify({ data: true })`.
+- Subscriptions: `db.watch({ from, classes })` — `await sub.ready()` before a write that must reach the stream (`from: 'now'` fixes its starting point with the first query); parallel `next()` calls get different events.
+- NOTIFY signals are visible to any database role: `up({ signals: 'class' | 'tenant' | 'opaque' | 'none' })` chooses what they reveal (default `class`).
 - Access rules are always on and deny by default; `up({ tenant })` or `createTenant()` creates a tenant with the rule "authenticated users may do everything" and its first user.
+- MCP: `createMcpServer(db)` from `letopis/mcp` and `letopis mcp` (stdio, a user session token only) give an AI agent the tools `letopis_model`, `letopis_query` (a JSON chain, no SQL), `letopis_history` and, with `write: true`, `letopis_write`; the agent acts with the rights of one user, and a deletion needs a human confirmation through elicitation; by default `letopis_write` does not write the permission classes (`allowAclWrite`), and a session in the System tenant is refused (`allowSystemAdmin`). `structuredContent` of a tool result is `{ notice, data }` (an error — `{ notice, error }`): `notice` warns that `data` holds untrusted stored data, not instructions.
 - Errors carry a lowercase `err.code`: `exists`, `conflict`, `invalid_data` (`err.issues`), `target_not_found`, `acl_denied`, `no_session`, `removed` (0.21 API with its replacement), …
 
 ## Docs