letopis 1.1.0 → 1.3.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/sql.js

@@ -693,14 +693,17 @@ 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 — по одному документу на объект шага
@@ -720,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];

package/dist/sync.js

@@ -11,13 +11,22 @@ function canon(v) {
 export async function syncModels(db, models, opts = {}) {
     const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
     const S = `"${db.schema.replace(/"/g, '""')}"`;
-    // предок раньше потомка
+    // предок раньше потомка; класс-источник агрегата раньше цели: агрегат над классом, которого ещё нет, база отклоняет.
+    // Цикл агрегатов база отклоняет сама — обход его только не зацикливает
     const ordered = [];
+    const visiting = new Set();
     const visit = (m) => {
-        if (ordered.includes(m))
+        if (ordered.includes(m) || visiting.has(m))
             return;
+        visiting.add(m);
         if (m.parent && models.includes(m.parent))
             visit(m.parent);
+        for (const a of Object.values(m.describe().aggregate ?? {})) {
+            const src = models.find((x) => x.name === a.of);
+            if (src)
+                visit(src);
+        }
+        visiting.delete(m);
         ordered.push(m);
     };
     models.forEach(visit);

package/dist/types.d.ts

@@ -11,7 +11,7 @@ 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", "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"];
 /**

package/dist/types.js

@@ -23,7 +23,7 @@ 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/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

@@ -53,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

@@ -64,6 +64,8 @@ export class Subscription {
     pollMs;
     /** 'now' — голова журнала в момент подписки (запрос уходит сразу). */
     start = null;
+    /** Вызовы next() — по очереди: параллельные получают разные события (доработки после точки Б). */
+    queue = Promise.resolve();
     constructor(ctx, opts) {
         this.ctx = ctx;
         this.opts = opts;
@@ -97,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 };
@@ -106,10 +116,35 @@ export class Subscription {
         if (!this.pos)
             this.pos = await (this.start ?? this.head());
         const p = this.pos;
-        const rows = await this.ctx.exec.run((q) => q.unsafe(`select l.tx::text as tx, l.seq::text as seq, jsonb_build_object('id', l.id, 'rev', l.rev, 'class', l.class, 'tenant', l.tenant, `
+        const cols = `l.tx::text as tx, l.seq::text as seq, jsonb_build_object('id', l.id, 'rev', l.rev, 'class', l.class, 'tenant', l.tenant, `
             + `'owner', l.owner, 'links', l.links, 'data', l.data, 'tags', l.tags, 'at', l.at, 'author', l.author, 'agent', l.agent, `
-            + `'op', l.op, 'reason', l.reason, 'moved', l.moved) as row `
-            + `from ${this.ctx.S}.watch_read($1::text::xid8, $2::bigint, $3::text::timestamptz, $4::text[], $5::int, $6::text::pg_snapshot) l`, [p.tx, p.seq, p.at, this.ctx.classes, this.batch, p.snap ?? null]), { read: true });
+            + `'op', l.op, 'reason', l.reason, 'moved', l.moved) as row`;
+        // уход строки из классов подписки сменой класса без смены id (хвост ревью безопасности №3) — надгробием прежней
+        // версии в том же окне: полная пачка watch_read ограничивает окно своей последней строкой. Оба потока — одним
+        // оператором: общий снимок и горизонт, иначе курсор перескочил бы событие, зафиксированное между запросами
+        // (автоматическое ревью). Потоки сливаются по (tx, seq) до границы — последней строки потока, обрезанного лимитом
+        const S = this.ctx.S;
+        const both = await this.ctx.exec.run((q) => q.unsafe(`with r as (select l.* from ${S}.watch_read($1::text::xid8, $2::bigint, $3::text::timestamptz, $4::text[], $5::int, $6::text::pg_snapshot) l),
+            u as (select r.tx, r.seq from r where (select count(*) from r) = $5 order by r.tx desc, r.seq desc limit 1)
+       select 0 as src, ${cols} from r l
+       union all
+       select 1 as src, ${cols} from ${S}.watch_leaving($1::text::xid8, $2::bigint, $4::text[], $5::int, $6::text::pg_snapshot,
+         (select tx from u), (select seq from u)) l`, [p.tx, p.seq, p.at, this.ctx.classes, this.batch, p.snap ?? null]), { read: true });
+        const before = (a, b) => BigInt(a.tx) < BigInt(b.tx) || (a.tx === b.tx && BigInt(a.seq) < BigInt(b.seq));
+        const order = (a, b) => (before(a, b) ? -1 : before(b, a) ? 1 : 0);
+        const read = both.filter((r) => r.src === 0).sort(order);
+        const away = both.filter((r) => r.src === 1).sort(order);
+        let rows = read;
+        {
+            const upto = read.length === this.batch ? read[read.length - 1] : null;
+            if (away.length) {
+                let bound = upto;
+                const lastAway = away[away.length - 1];
+                if (away.length === this.batch && (!bound || before(lastAway, bound)))
+                    bound = lastAway;
+                rows = [...read, ...away].sort(order).filter((r) => !bound || !before(bound, r));
+            }
+        }
         for (const r of rows) {
             const row = toRow(r.row);
             const snap = keepSnap(p.snap, r.tx);
@@ -118,7 +153,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';

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';
@@ -115,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;
@@ -162,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;
@@ -388,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)
@@ -742,11 +760,13 @@ export async function execBatch(w, plans) {
             }
             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);

package/llms.txt

@@ -2,17 +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.1:
+Key facts for writing code with letopis 1.3:
 
-- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Letopis (летопись): versioned entity store on PostgreSQL 18 — integrity, history, tenants and access control enforced by the database itself, dot-notation chains on top",
   "keywords": [
     "postgres",
@@ -35,6 +35,10 @@
     "./model": {
       "types": "./dist/model.d.ts",
       "import": "./dist/model.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
     }
   },
   "engines": {
@@ -72,7 +76,8 @@
   "peerDependencies": {
     "zod": "^4",
     "@electric-sql/pglite": "^0.5.8",
-    "@electric-sql/pglite-socket": "^0.2.11"
+    "@electric-sql/pglite-socket": "^0.2.11",
+    "@modelcontextprotocol/server": "^2.4.0"
   },
   "peerDependenciesMeta": {
     "zod": {
@@ -83,14 +88,20 @@
     },
     "@electric-sql/pglite-socket": {
       "optional": true
+    },
+    "@modelcontextprotocol/server": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@electric-sql/pglite-socket": "^0.2.11",
+    "@modelcontextprotocol/client": "^2.4.0",
+    "@modelcontextprotocol/server": "^2.4.0",
     "@types/node": "^22.20.5",
     "letopis-0": "npm:letopis@0.21.0",
     "letopis-1": "npm:letopis@1.0.1",
+    "letopis-11": "npm:letopis@1.1.0",
     "tsx": "^4.23.15",
     "typescript": "~5.9.3",
     "zod": "4.6.5"

package/sql/10-core.sql

@@ -6,7 +6,9 @@
 revoke all on schema @SCHEMA@ from public;
 grant usage on schema @SCHEMA@ to @APP@;
 
--- Все цели концов плоским списком: {роль: id} или {роль: [id, …]}.
+-- Все цели концов плоским списком: {роль: id} или {роль: [id, …]}. Тело — SQL-стандарта (return): имена связываются
+-- при создании и от search_path сеанса не зависят, а колонку ends вычисляет роль приложения. Вариант на plpgsql быстрее
+-- на 17 % (бенч gencols), но его имена разрешались бы при исполнении (ревью безопасности доработок после 1.2.0)
 create or replace function @SCHEMA@.link_ids(links jsonb) returns uuid[]
 language sql immutable parallel safe
 return (
@@ -91,7 +93,11 @@ create table if not exists @SCHEMA@.log (
   changed    jsonb,
   constraint log_id_rev unique (id, rev)
 );
-create index if not exists log_class_at on @SCHEMA@.log (class, at);
+-- срез журнала по классу (asOf, withDeleted) — по арендатору (доработки после точки Б): цена запроса не растёт с
+-- журналом других арендаторов с тем же именем класса. Прежний log_class_at (class, at) снимается при накате; на
+-- большой установке новый индекс можно построить заранее — create index concurrently log_class_tenant_at …
+create index if not exists log_class_tenant_at on @SCHEMA@.log (class, tenant, at);
+drop index if exists @SCHEMA@.log_class_at;
 create index if not exists log_tx_seq on @SCHEMA@.log (tx, seq);
 -- versions({ follow: true }): переход по связи старого и нового id при reclass и rekey (этап 6)
 create index if not exists log_moved on @SCHEMA@.log (moved) where moved is not null;

package/sql/15-errors.sql

@@ -25,7 +25,10 @@ as $$
     ('LT017', 'delete_restricted',      'letopis: delete_restricted: удалению мешают ссылающиеся строки'),
     ('LT018', 'not_deleted',            'letopis: not_deleted: объект не удалён — restore и purge только для удалённых'),
     ('LT019', 'reset_disabled',         'letopis: reset_disabled: reset выключен в этой установке'),
-    ('LT020', 'confirm_mismatch',       'letopis: confirm_mismatch: подтверждение не совпадает с именем схемы')
+    ('LT020', 'confirm_mismatch',       'letopis: confirm_mismatch: подтверждение не совпадает с именем схемы'),
+    ('LT021', 'derived_class',          'letopis: derived_class: строки производного класса пишет только его проектор'),
+    ('LT022', 'aggregate_field',        'letopis: aggregate_field: агрегатное поле считает база'),
+    ('LT023', 'projector_pending',      'letopis: projector_pending: проектор источника ещё не прочёл удаление')
 $$;
 
 create or replace function @SCHEMA@.lt_raise(p_code text, p_name text, p_msg text, p_detail jsonb default null)

package/sql/40-class.sql

@@ -12,7 +12,12 @@
 --   key       [<поле или роль>…] — из них вычисляется id (§2.3); [] — класс без ключа
 --   history   true | false | политика хранения (§2.11)
 --   ownerDefault 'tenant' | 'actor';  cache { ttl };  meta {…} до 64 КБ
---   resolved  развёрнутое описание с учётом предков — пишет триггер, присланное значение перезаписывается
+--   derivedBy имя проектора (план 1.1, §2.4): строки класса пишет только он; наследуется, потомок не меняет
+--   aggregate { <поле>: { sum: <поле источника> | count: true, of: <класс-источник>, via: <роль>, where?: JSON Schema } }
+--             агрегаты в базе (план 1.1, §2.4): поле держит триггер по живым строкам источника; наследуется,
+--             потомок заменяет целиком
+--   resolved  развёрнутое описание с учётом предков — пишет триггер, присланное значение перезаписывается; у
+--             источника агрегатов в нём ещё метка aggregatedBy — какие цели считают его строки (88-derived.sql)
 -- Скомпилированная проверка данных класса лежит в колонке validator строки Class.
 
 create or replace function @SCHEMA@.class_metaschema() returns jsonb
@@ -69,6 +74,23 @@ return $json${
     "ownerDefault": {"type": "string", "enum": ["tenant", "actor"]},
     "cache": {"type": "object"},
     "meta": {"type": "object"},
+    "derivedBy": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_.:-]{0,63}$"},
+    "aggregate": {
+      "type": "object",
+      "propertyNames": {"type": "string", "pattern": "^[^$]"},
+      "additionalProperties": {
+        "type": "object",
+        "required": ["of", "via"],
+        "additionalProperties": false,
+        "properties": {
+          "sum": {"type": "string", "pattern": "^[^$]"},
+          "count": {"type": "boolean", "enum": [true]},
+          "of": {"type": "string", "pattern": "^[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{0,62}$"},
+          "via": {"type": "string", "pattern": "^[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{0,62}$"},
+          "where": {"type": "object"}
+        }
+      }
+    },
     "resolved": {"type": "object"}
   }
 }$json$::jsonb;
@@ -114,6 +136,8 @@ declare
   hist jsonb;
   od text;
   cache jsonb;
+  der text;
+  agg jsonb;
   comp jsonb := '{}';
   i int;
   v jsonb;
@@ -143,6 +167,16 @@ begin
     if v ? 'history' then hist := v->'history'; end if;
     if v ? 'ownerDefault' then od := v->>'ownerDefault'; end if;
     if v ? 'cache' then cache := v->'cache'; end if;
+    -- производный класс (план 1.1, §2.4): проектор задаёт предок, потомок его не меняет
+    if v ? 'derivedBy' then
+      if der is not null and der <> v->>'derivedBy' then
+        perform @SCHEMA@.lt_raise('LT010', 'invalid_class',
+          format('derivedBy класса %s (%s) не совпадает с предком (%s)', v->>'name', v->>'derivedBy', der));
+      end if;
+      der := v->>'derivedBy';
+    end if;
+    -- агрегаты (план 1.1, §2.4): потомок заменяет описание предка целиком, {} — снимает унаследованное
+    if v ? 'aggregate' then agg := v->'aggregate'; end if;
     for m in select * from jsonb_each(coalesce(v->'meta', '{}')) loop
       if m.value = 'null'::jsonb then meta := meta - m.key; else meta := meta || jsonb_build_object(m.key, m.value); end if;
     end loop;
@@ -158,7 +192,9 @@ begin
     'history', coalesce(hist, 'true'),
     'ownerDefault', coalesce(od, 'tenant'),
     'cache', cache,
-    'meta', meta);
+    -- ключи только у производных и у целей агрегатов: у описаний до 1.2 их нет, и сравнение «было — стало» их не задевает
+    'meta', meta) || case when der is not null then jsonb_build_object('derivedBy', der) else '{}'::jsonb end
+                  || case when agg is not null and agg <> '{}'::jsonb then jsonb_build_object('aggregate', agg) else '{}'::jsonb end;
 end $$;
 
 -- Проверка описания класса: метасхема, правила ключа (§2.3), правило unset (§2.10), размер meta.
@@ -243,6 +279,25 @@ begin
       perform @SCHEMA@.lt_raise('LT010', 'invalid_class', format('history: неизвестный часовой пояс %s', res->'history'->>'tz'));
     end if;
   end if;
+  -- производный класс (план 1.1, §2.4): системным не бывает; его строки проектор удаляет и строит заново,
+  -- поэтому они не мешают удалять строки, на которые ссылаются (onDelete только cascade или unset)
+  if res ? 'derivedBy' then
+    if coalesce((data->>'system')::boolean, false) then
+      perform @SCHEMA@.lt_raise('LT010', 'invalid_class', 'системный класс не бывает производным');
+    end if;
+    for e in select key, value from jsonb_each(res->'ends') loop
+      if coalesce(e.value->>'onDelete', 'restrict') not in ('cascade', 'unset') then
+        perform @SCHEMA@.lt_raise('LT010', 'invalid_class',
+          format('конец %s производного класса — onDelete cascade или unset: производная строка не мешает удалять цель', e.key));
+      end if;
+    end loop;
+  end if;
+  -- агрегаты (план 1.1, §2.4; 88-derived.sql): цель — поля, источники, цикл, условия where; источник — метка
+  -- aggregatedBy и та же сверка против агрегатов, которые считают его строки (источник часто описывают после цели)
+  if res ? 'aggregate' then
+    res := @SCHEMA@.agg_prepare(res, data, p_tenant);
+  end if;
+  res := @SCHEMA@.agg_source(res, p_tenant);
   select * into c from @SCHEMA@.compile_validator(res->'schema');
   data := data || jsonb_build_object('resolved', res || jsonb_build_object('rules', c.rules, 'vars', c.vars));
   validator := c.validator;