letopis 1.4.2 → 2.0.0

package/dist/write.js

@@ -1,7 +1,7 @@
 /**
- * Запись планами (план, §2.5, этап 4, п. 1–7, 10): глаголы create, update, upsert, delete, anonymize
- * и reclass — звенья цепочки; терминал исполняет весь план одной транзакцией. Этап 6: restore и
- * purge — над удалёнными объектами шага, rekey — новое значение ключа (функции базы).
+ * Запись планами (план, §2.5, этап 4, п. 1–7, 10): глаголы create, update, upsert и delete — звенья
+ * цепочки; терминал исполняет весь план одной транзакцией. Этап 6: restore — над удалёнными объектами
+ * шага (функция базы).
  *
  *   await db.Org(org).Staff().create({ name: 'Вася', phone: '+7' }).rows()      // концы из пути: { Org }
  *   await db.Customer(c).booking({ notes: 'x' }).update({ notes: 'y' }).rows()
@@ -17,10 +17,9 @@
  * строка видна, но править нельзя — acl_denied; строки уже нет — target_not_found; номер версии
  * разошёлся со { rev } — conflict.
  */
-import { LetopisError, ValidationError } from './errors.js';
+import { lerr, 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 { accepts, buildRead, nextNodeKey, precheckStep, resolveHop, stepClasses, toRow } from './sql.js';
 import { idOf } from './uuid.js';
 import { applyDefaults } from './validate.js';
 // ---------------------------------------------------------------------------
@@ -40,13 +39,10 @@ export const isInc = (v) => typeof v === 'object' && v !== null && v[INC] === tr
 /** Причина изменения: строка до 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 символов`);
+        throw lerr('write.bad_reason', { where });
     }
     return v;
 }
-const fail = (code, msg, detail) => {
-    throw new LetopisError(code, msg, detail);
-};
 const asList = (v) => (Array.isArray(v) ? v : [v]);
 const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date) && !isInc(v) && !isOp(v);
 /** Патч update → остаток для merge и список приращений. Недопустимое — invalid_data до отправки. */
@@ -54,9 +50,9 @@ export function splitPatch(patch) {
     const incs = [];
     const noMarkers = (v, path) => {
         if (isInc(v))
-            fail('invalid_data', `inc() внутри массива (${path.join('.')}) не поддерживается`);
+            throw lerr('write.inc_in_array', { path: path.join('.') });
         if (isOp(v))
-            fail('invalid_data', `оператор фильтра в данных (${path.join('.')}) — данные записываются значениями`);
+            throw lerr('write.op_in_data', { path: path.join('.') });
         if (Array.isArray(v))
             v.forEach((x, i) => noMarkers(x, [...path, String(i)]));
         else if (isPlain(v))
@@ -71,13 +67,13 @@ export function splitPatch(patch) {
             const p = [...path, k];
             if (isInc(v)) {
                 if (!Number.isFinite(v.by))
-                    fail('invalid_data', `inc(${v.by}) по пути ${p.join('.')}: величина — конечное число`);
+                    throw lerr('write.inc_by_not_finite', { by: v.by, path: p.join('.') });
                 if (v.start !== undefined && !Number.isFinite(v.start))
-                    fail('invalid_data', `inc: start по пути ${p.join('.')} — конечное число`);
+                    throw lerr('write.inc_start_not_finite', { path: p.join('.') });
                 incs.push({ path: p, by: v.by, ...(v.start !== undefined ? { start: v.start } : {}) });
             }
             else if (isOp(v)) {
-                fail('invalid_data', `оператор фильтра в патче (${p.join('.')}) — update записывает значения`);
+                throw lerr('write.op_in_patch', { path: p.join('.') });
             }
             else if (Array.isArray(v)) {
                 noMarkers(v, p);
@@ -101,15 +97,15 @@ export function splitPatch(patch) {
 // ---------------------------------------------------------------------------
 // Проверки до отправки (precheckPlan)
 // ---------------------------------------------------------------------------
-/** Данные create/upsert: объект без маркеров; ранняя проверка валидатором на TypeScript (full — объект целиком). */
-function checkFullData(cls, data, verb, full = true) {
+/** Данные create/upsert: объект без маркеров; ранняя проверка валидатором на TypeScript. */
+function checkFullData(cls, data, verb) {
     if (!isPlain(data))
-        fail('invalid_data', `${verb}(): данные — объект`);
+        throw lerr('write.data_not_object', { verb });
     const scan = (v, path) => {
         if (isInc(v))
-            fail('invalid_data', `inc() работает только в update(): ${verb}() по пути ${path.join('.')}`);
+            throw lerr('write.inc_outside_update', { verb, path: path.join('.') });
         if (isOp(v))
-            fail('invalid_data', `оператор фильтра в данных ${verb}() (${path.join('.')}) — данные записываются значениями`);
+            throw lerr('write.op_in_verb_data', { verb, path: path.join('.') });
         if (Array.isArray(v))
             v.forEach((x, i) => scan(x, [...path, String(i)]));
         else if (isPlain(v))
@@ -117,33 +113,45 @@ 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)
+    if (cls.name === 'Class' || cls.abstract)
         return;
-    const issues = cls.validator()(applyDefaults(cls.schema, agg.length ? { ...obj, ...Object.fromEntries(agg.map((f) => [f, 0])) } : obj));
+    const issues = cls.validator()(applyDefaults(cls.schema, data));
     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 их не меняет`);
+/** Фильтр шага сужает цели: id, список id, оператор, строка ответа, объект хотя бы с одним заданным полем. */
+const narrowingFilter = (f) => f !== undefined && f !== null && (typeof f !== 'object' || Array.isArray(f) || isOp(f) || Object.values(f).some((v) => v !== undefined));
+/**
+ * Цели глагола шага i сужены (план 2.0, этап 4, п. 2; 7.10 №2): у него или у шага до него есть фильтр, id, tags()
+ * (пустой список подходит любой строке), owner() или limit(), либо до него был create() или upsert() — дальше путь
+ * идёт от записанных строк.
+ */
+function narrowed(steps, i) {
+    for (let j = 0; j <= i; j++) {
+        const s = steps[j];
+        if (narrowingFilter(s.filter) || s.ownerFilter !== undefined || s.opMods?.limit !== undefined)
+            return true;
+        if (s.tagsFilter !== undefined && s.tagsFilter !== null && !(Array.isArray(s.tagsFilter) && !s.tagsFilter.length))
+            return true;
+        if (j < i && (s.op?.kind === 'create' || s.op?.kind === 'upsert'))
+            return true;
+    }
+    return false;
 }
-/** Всё, что проверяется без базы, — до отправки первого оператора (§2.5). */
-export function precheckPlan(reg, steps) {
+/**
+ * Всё, что проверяется без базы, — до отправки первого оператора (§2.5). Фильтры шагов и поля sort() и агрегатов
+ * (неизвестное поле — invalid_query, план 2.0, этап 3, п. 3) — precheckStep построителя; order и agg — модификатор и
+ * агрегат чтения за последним глаголом (терминал цепочки).
+ */
+export function precheckPlan(reg, steps, order, agg) {
     let prevOp;
     for (let i = 0; i < steps.length; i++) {
         const s = steps[i];
         const op = s.op;
+        const tail = i === steps.length - 1;
         if (!op) {
+            precheckStep(reg, s, tail ? order : undefined, tail ? agg : undefined);
             prevOp = undefined;
             continue;
         }
@@ -152,67 +160,54 @@ export function precheckPlan(reg, steps) {
             checkReason(op.reason, `${verb}()`);
         const m = s.opMods ?? {};
         if (m.asOf !== undefined)
-            fail('invalid_query', `${verb}(): asOf описывает прошлое — записывать в него нельзя`);
-        // restore и purge сами ищут удалённые объекты шага
-        if (m.withDeleted && verb !== 'restore' && verb !== 'purge')
-            fail('invalid_query', `${verb}(): withDeleted описывает удалённые — записывать в них нельзя`);
+            throw lerr('write.as_of_write', { verb });
+        // restore сам ищет удалённые объекты шага
+        if (m.withDeleted && verb !== 'restore')
+            throw lerr('write.with_deleted_write', { verb });
         switch (op.kind) {
             case 'create':
             case 'upsert':
                 if (s.self)
-                    fail('invalid_query', `${verb}() сразу после ${prevOp?.kind}() — между глаголами нужен шаг`);
+                    throw lerr('write.verb_after_verb', { verb, prev: prevOp?.kind });
                 if (s.pivotKey !== undefined)
-                    fail('invalid_query', `${verb}() на возврате к узлу — он ведёт к существующей сущности, используйте update()`);
+                    throw lerr('write.create_on_pivot', { verb });
                 if (s.filter !== undefined && typeof s.filter !== 'string') {
-                    fail('invalid_query', `${verb}() не ищет: ${s.name}(id).${verb}(…) задаёт id, поиск — это update()`);
+                    throw lerr('write.create_with_filter', { verb, step: s.name });
                 }
                 if (op.kind === 'upsert' && !s.cls.key.length)
-                    fail('no_key', `upsert(): у класса ${s.cls.name} нет ключа — сравнивать не с чем, используйте create()`);
+                    throw lerr('write.upsert_no_key', { cls: s.cls.name });
                 checkFullData(s.cls, op.data, verb);
                 if (s.tagsFilter !== undefined && typeof s.tagsFilter !== 'string' && !Array.isArray(s.tagsFilter)) {
-                    fail('invalid_query', `.tags() перед ${verb}() — строка или список`);
+                    throw lerr('write.bad_tags', { verb });
                 }
                 break;
             case 'update':
                 if (!isPlain(op.data))
-                    fail('invalid_data', 'update(): патч — объект');
+                    throw lerr('write.patch_not_object');
                 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;
-            case 'anonymize': {
-                if (!Array.isArray(op.fields) || !op.fields.length)
-                    fail('invalid_query', 'anonymize(поля): нужен список полей');
-                for (const f of op.fields) {
-                    // поля нет в классе — так и сказано, а не «поле jsonb» (план 2.0, 7.5 №3)
-                    if (!(f in (s.cls.schema.properties ?? {})))
-                        fail('invalid_query', `anonymize(): поля ${f} нет в классе ${s.cls.name}`);
-                    const t = reg.leafType(s.cls.name, [f]);
-                    if (t !== 'text')
-                        fail('invalid_query', `anonymize() затирает только строковые поля; ${f} — ${t}`);
+                    throw lerr('write.bad_rev');
+                // строгий режим (план 2.0, этап 4, п. 2; 7.10 №2): правка без сужения целей — отказ до записи, все строки —
+                // { all: true }; data.id у шага без фильтра — тоже цель (updateOp)
+                if (!op.all && !(s.filter === undefined && typeof op.data.id === 'string') && !narrowed(steps, i)) {
+                    throw lerr('write.no_filter', { call: 'update()', cls: s.cls.name });
                 }
                 break;
-            }
-            case 'reclass':
-                reg.resolve(op.cls);
-                if (op.data !== undefined)
-                    checkFullData(reg.resolve(op.cls), op.data, 'reclass');
-                break;
             case 'delete':
-            case 'restore':
-            case 'purge':
+                // превью (без confirm) ничего не удаляет — его не сужают
+                if (op.confirm && !op.all && !narrowed(steps, i))
+                    throw lerr('write.no_filter', { call: 'delete({ confirm: true })', cls: s.cls.name });
                 break;
-            case 'rekey':
-                if (!s.cls.key.length)
-                    fail('no_key', `rekey(): у класса ${s.cls.name} нет ключа — id выдаёт база, менять нечего`);
-                checkFullData(s.cls, op.data, 'rekey', false);
+            case 'restore':
                 break;
         }
         for (const sl of s.slots ?? []) {
             if (op.kind !== 'create' && op.kind !== 'update' && op.kind !== 'upsert')
-                fail('invalid_query', `слот .${sl.role} после ${verb}() — слоты у create(), update() и upsert()`);
+                throw lerr('write.slot_bad_verb', { role: sl.role, verb });
         }
+        precheckStep(reg, s, s.opMods?.order);
+        if (tail && (order !== undefined || agg !== undefined))
+            precheckStep(reg, s, order, agg);
         prevOp = op;
     }
 }
@@ -228,7 +223,7 @@ 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, `
     + `'links', ${a}.links, 'data', ${a}.data, 'tags', ${a}.tags, 'at', ${a}.at, 'author', ${a}.author, 'agent', ${a}.agent, `
-    + `'op', ${a}.op, 'reason', ${a}.reason, 'moved', ${a}.moved)`;
+    + `'op', ${a}.op, 'reason', ${a}.reason)`;
 async function query(w, text, params) {
     return (await w.q.unsafe(text, params, { prepare: true }));
 }
@@ -254,16 +249,18 @@ export function slotRole(reg, owner, name) {
         return name;
     const c = reg.find(name);
     if (!c)
-        fail('invalid_class', `класс или роль ${name} не найдены`);
+        throw lerr('write.slot_unknown', { name });
     const roles = rolesAccepting(reg, owner, c.name);
     if (roles.length === 1)
         return roles[0];
     if (!roles.length)
-        fail('invalid_query', `${name} — не конец класса ${owner.name} (концы: ${Object.keys(owner.ends).join(', ') || '—'})`);
-    return fail('invalid_query', `слот ${name} у класса ${owner.name} неоднозначен: роли ${roles.join(', ')} — назовите роль`);
+        throw lerr('write.slot_not_end', { name, cls: owner.name, ends: Object.keys(owner.ends).join(', ') || '—' });
+    throw lerr('write.slot_ambiguous', { name, cls: owner.name, roles: roles.join(', ') });
 }
 /** Неоднозначная роль конца из пути. */
-const ambiguous = (step, target, roles) => fail('invalid_query', `конец класса ${target.name} для шага ${step.name} неоднозначен: роли ${roles.join(', ')} — назовите шаг ролью или задайте слот`);
+const ambiguous = (step, target, roles) => {
+    throw lerr('write.end_ambiguous', { cls: target.name, step: step.name, roles: roles.join(', ') });
+};
 /**
  * Роль из нескольких кандидатов: роли, заданные слотами, не участвуют; из оставшихся — роль с именем
  * класса шага (duty.Member для шага Member, а Backup — слотом). Иначе — неоднозначно.
@@ -317,7 +314,7 @@ async function pathEnds(w, steps, taken) {
         else {
             const rows = await readRows(w, steps.slice(0, k + 1).map(bare), { limit: 2 });
             if (rows.length !== 1)
-                fail('invalid_query', `шаг ${s.name} должен дать ровно одну сущность для конца ${tcls.name} (найдено ${rows.length})`);
+                throw lerr('write.end_not_single', { step: s.name, cls: tcls.name, count: rows.length });
             id = rows[0].id;
             if (!roles) {
                 roles = pickRole(s, tcls, rolesAccepting(w.reg, tcls, rows[0].class), taken, rows[0].class);
@@ -368,7 +365,7 @@ async function resolveSlots(w, cls, slots) {
         const end = cls.ends[sl.role];
         const ids = sl.op === 'unset' ? [] : await slotIds(w, sl.value);
         if (sl.op === 'set' && sl.value !== null && !end.many && ids.length !== 1) {
-            fail('invalid_query', `слот .${sl.role}.set(): конец одиночный, а значение дало ${ids.length} сущностей`);
+            throw lerr('write.slot_single_many', { role: sl.role, count: ids.length });
         }
         out.push({ role: sl.role, op: sl.op, value: sl.op === 'unset' || sl.value === null ? null : end.many ? ids : ids[0] });
     }
@@ -405,7 +402,8 @@ function existsError(w, cls, data, links, given, cause) {
             id = undefined;
         }
     }
-    return Object.assign(new LetopisError('exists', `объект класса ${cls.name} уже существует${id ? ` (id ${id})` : ''}`, { id: id ?? null }), { cause });
+    const detail = { id: id ?? null };
+    return id ? lerr('write.exists_id', { cls: cls.name, id }, { detail, cause }) : lerr('write.exists', { cls: cls.name }, { detail, cause });
 }
 const isPkConflict = (e) => {
     const err = e;
@@ -419,16 +417,11 @@ 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${agg.length ? ' - $7::text[]' : ''}, links = excluded.links, tags = excluded.tags`
-        : '';
+    const conflict = upsert ? ' on conflict (id) do update set data = excluded.data, 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, ...(upsert && agg.length ? [agg] : [])]);
+        const res = await query(w, text, [given ?? null, cls.name, links, op.data, tagsValue(opStep), owner]);
         return res.map((r) => {
             const row = toRow(r.row);
             if (upsert)
@@ -449,12 +442,17 @@ async function createOp(w, steps, opStep, upsert) {
 async function explainMissing(w, missing, rev) {
     const S = quoteId(w.schema);
     const seen = await query(w, `select id, rev from ${S}.entity where id = any ($1::uuid[])`, [missing]);
-    if (!seen.length)
-        return fail('target_not_found', missing.length === 1 ? `цель ${missing[0]} не найдена` : `цели не найдены: ${missing.join(', ')}`, { ids: missing });
+    if (!seen.length) {
+        throw missing.length === 1
+            ? lerr('write.target_missing', { id: missing[0] }, { detail: { ids: missing } })
+            : lerr('write.targets_missing', { ids: missing.join(', ') }, { detail: { ids: missing } });
+    }
     if (rev !== undefined && seen.some((r) => r.rev !== rev)) {
-        return fail('conflict', `строку ${seen[0].id} успели изменить: версия ${seen[0].rev}, а не ${rev} — перечитайте и повторите`, { id: seen[0].id, rev: seen[0].rev, expected: rev });
+        const detail = { id: seen[0].id, rev: seen[0].rev, expected: rev };
+        throw lerr('write.rev_conflict', detail, { detail });
     }
-    return fail('acl_denied', `строки видны, но изменить их нельзя: ${seen.map((r) => r.id).join(', ')}`, { ids: seen.map((r) => r.id) });
+    const ids = seen.map((r) => r.id);
+    throw lerr('write.rows_denied', { ids: ids.join(', ') }, { detail: { ids } });
 }
 /**
  * Строки ответа глагола — в порядке целей (`targetIds`: по `sort()` до глагола, иначе по id). `update … returning`
@@ -464,14 +462,14 @@ function inTargetOrder(ids, rows) {
     const pos = new Map(ids.map((id, i) => [id, i]));
     return rows.sort((a, b) => (pos.get(a.id) ?? 0) - (pos.get(b.id) ?? 0));
 }
-/** Цели update/delete/anonymize/reclass: id из пути (limit и sort сужают); data.id — если у шага нет фильтра. */
+/** Цели update и delete: id из пути (limit и sort сужают); data.id — если у шага нет фильтра. */
 async function targetIds(w, steps, opStep, dataId) {
     const path = steps.map(bare);
     if (opStep.filter === undefined && dataId !== undefined)
         path[path.length - 1] = { ...path[path.length - 1], filter: dataId };
     const ids = await readIds(w, path, opStep.opMods ?? {});
-    // без явного порядка — по id: глаголы по списку целей (reclass, rekey и др.) пишут журнал по очереди, и порядок
-    // записей не должен зависеть от плана чтения
+    // без явного порядка — по id: глаголы по списку целей пишут журнал по очереди, и порядок записей не должен
+    // зависеть от плана чтения
     return opStep.opMods?.order ? ids : [...ids].sort();
 }
 async function updateOp(w, steps, opStep) {
@@ -483,9 +481,9 @@ async function updateOp(w, steps, opStep) {
     const ids = await targetIds(w, steps, opStep, useDataId ? dataId : undefined);
     if (op.rev !== undefined) {
         if (ids.length > 1)
-            fail('rev_ambiguous', `update(patch, { rev }): у шага ${opStep.name} ${ids.length} целей — проверить версию { rev } можно только у одной цели`);
+            throw lerr('write.rev_many_targets', { step: opStep.name, count: ids.length });
         if (!ids.length)
-            fail('target_not_found', `update(patch, { rev }): у шага ${opStep.name} нет цели`);
+            throw lerr('write.rev_no_target', { step: opStep.name });
     }
     if (!ids.length)
         return [];
@@ -550,41 +548,13 @@ async function deleteOp(w, steps, opStep) {
     }
     return out;
 }
-async function anonymizeOp(w, steps, opStep) {
-    const op = opStep.op;
-    const S = quoteId(w.schema);
-    const ids = await targetIds(w, steps, opStep);
-    if (!ids.length)
-        return [];
-    const res = await query(w, `update ${S}.entity e set data = e.data || coalesce((select jsonb_object_agg(f, '[erased]'::text) from unnest($2::text[]) f where e.data ? f), '{}'::jsonb), `
-        + `tags = (select array_agg(distinct t order by t) from unnest(e.tags || array['anonymized']) t) `
-        + `where e.id = any ($1::uuid[]) returning ${rowJson('new')} as row`, [ids, op.fields]);
-    if (res.length < ids.length) {
-        const got = new Set(res.map((r) => r.row.id));
-        await explainMissing(w, ids.filter((x) => !got.has(x)));
-    }
-    return inTargetOrder(ids, res.map((r) => toRow(r.row)));
-}
-async function reclassOp(w, steps, opStep) {
-    const op = opStep.op;
-    const S = quoteId(w.schema);
-    const ids = await targetIds(w, steps, opStep);
-    if (!ids.length)
-        return [];
-    const cls = w.reg.resolve(op.cls).name;
-    // у класса без ключа id сохраняется, у класса с ключом — новый id и перевод ссылок (reclass() в базе)
-    const moved = await query(w, `select ${S}.reclass(x, $2::text, $3::jsonb) as id from unnest($1::uuid[]) with ordinality as u(x, i) order by u.i`, [ids, cls, op.data ?? null]);
-    const res = await query(w, `select ${rowJson('e')} as row from ${S}.entity e where e.id = any ($1::uuid[])`, [moved.map((m) => m.id)]);
-    // строки ответа — в порядке целей (moved — по порядку целей, план 2.0, 7.2 №2)
-    return inTargetOrder(moved.map((m) => m.id), res.map((r) => toRow(r.row)));
-}
-/** Удалённые объекты шага (restore, purge): живые цели без удалённых — not_deleted. */
+/** Удалённые объекты шага (restore): живые цели без удалённых — not_deleted. */
 async function deletedTargets(w, steps, opStep, verb) {
     const rows = await readRows(w, steps.map(bare), { ...(opStep.opMods ?? {}), withDeleted: true });
     const dead = rows.filter((r) => r.$deleted);
     if (!dead.length && rows.length)
-        fail('not_deleted', `объект не удалён: ${verb}() — только для удалённых${verb === 'purge' ? ', сначала delete()' : ''}`, { ids: rows.map((r) => r.id) });
-    // без явного порядка — по id: restore и purge пишут журнал по очереди целей
+        throw lerr('write.not_deleted', { verb }, { detail: { ids: rows.map((r) => r.id) } });
+    // без явного порядка — по id: restore пишет журнал по очереди целей
     return opStep.opMods?.order ? dead : [...dead].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
 /** Восстановление (этап 6, п. 2): последний снимок новой версией; база перепроверяет его по текущему описанию. */
@@ -598,52 +568,6 @@ async function restoreOp(w, steps, opStep) {
     const res = await query(w, `select ${rowJson('e')} as row from ${S}.entity e where e.id = any ($1::uuid[])`, [ids]);
     return inTargetOrder(ids, res.map((r) => toRow(r.row)));
 }
-/**
- * Стирание истории удалённых (этап 6, п. 3): без { confirm: true } — превью (надгробия и число
- * версий $versions), с ним — версии стёрты, на месте версии 1 — запись purge ($purged).
- */
-async function purgeOp(w, steps, opStep) {
-    const op = opStep.op;
-    const S = quoteId(w.schema);
-    const dead = await deletedTargets(w, steps, opStep, 'purge');
-    const out = [];
-    for (const row of dead) {
-        const [{ r }] = await query(w, `select ${S}.purge($1::uuid, $2::boolean) as r`, [row.id, op.confirm]);
-        out.push({ ...row, $versions: r.versions, ...(r.purged ? { $purged: true } : {}) });
-    }
-    return out;
-}
-/** Новое значение ключа (этап 6, п. 7): строка с новым id, ссылки переведены, журнал связывает id. */
-async function rekeyOp(w, steps, opStep) {
-    const op = opStep.op;
-    const S = quoteId(w.schema);
-    const ids = await targetIds(w, steps, opStep);
-    if (!ids.length)
-        return [];
-    // поля — в данные, роли концов — в концы
-    const data = {};
-    const links = {};
-    for (const [k, v] of Object.entries(op.data)) {
-        if (opStep.cls.ends[k])
-            links[k] = typeof v === 'object' && v !== null && !Array.isArray(v) ? v.id : v;
-        else
-            data[k] = v;
-    }
-    const moved = [];
-    for (const id of ids) {
-        try {
-            const [{ id: nid }] = await query(w, `select ${S}.rekey($1::uuid, $2::jsonb, $3::jsonb) as id`, [id, data, links]);
-            moved.push(nid);
-        }
-        catch (e) {
-            if (isPkConflict(e))
-                throw Object.assign(new LetopisError('exists', `rekey(): объект класса ${opStep.cls.name} с таким ключом уже существует`, { id }), { cause: e });
-            throw e;
-        }
-    }
-    const res = await query(w, `select ${rowJson('e')} as row from ${S}.entity e where e.id = any ($1::uuid[])`, [moved]);
-    return inTargetOrder(moved, res.map((r) => toRow(r.row)));
-}
 async function opCall(w, steps, opStep) {
     await useReason(w, reasonFor(w, opStep));
     switch (opStep.op.kind) {
@@ -651,11 +575,7 @@ async function opCall(w, steps, opStep) {
         case 'upsert': return createOp(w, steps, opStep, true);
         case 'update': return updateOp(w, steps, opStep);
         case 'delete': return deleteOp(w, steps, opStep);
-        case 'anonymize': return anonymizeOp(w, steps, opStep);
-        case 'reclass': return reclassOp(w, steps, opStep);
         case 'restore': return restoreOp(w, steps, opStep);
-        case 'purge': return purgeOp(w, steps, opStep);
-        case 'rekey': return rekeyOp(w, steps, opStep);
     }
 }
 /** Разрезать план: сегменты (…шаги + шаг с глаголом) и читающий хвост после последнего глагола. */
@@ -712,18 +632,17 @@ export async function execPlan(w, steps, mods, mode, agg) {
         else {
             last = await opCall(w, [fromRows(prevOp, start.map((r) => r.id)), ...seg.steps], opStep);
         }
-        // после удаления продолжение — от удалённых строк класса цели (замыкание каскада шире); после
-        // стирания истории продолжать не от чего
+        // после удаления продолжение — от удалённых строк класса цели (замыкание каскада шире)
         start = kind === 'delete' && opStep.op.confirm
             ? last.filter((r) => stepClasses(w.reg, opStep).includes(r.class))
-            : kind === 'purge' ? [] : last;
+            : 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' || mode === 'diff' || mode === 'blame') {
+    if (tail.length || mode === 'versions' || mode === 'agg') {
         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);
@@ -793,13 +712,11 @@ 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${agg.length ? ' - $3::text[]' : ''}, links = excluded.links, tags = excluded.tags`
+                ? 'on conflict (id) do update set data = excluded.data, 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, ...(verb === 'upsert' && agg.length ? [agg] : [])]);
+                + `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]);
             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

@@ -1,33 +1,30 @@
 # letopis
 
-> 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()`.
+> Хранилище версионированных объектов для Node.js на PostgreSQL 18. Каждое изменение — версия в журнале (история, чтение на момент, подписка по курсору). Целостность, изоляцию арендаторов и права доступа проверяет сама база (триггеры и политики RLS), поэтому они действуют и для сырого SQL. Данные читают и пишут цепочками вида `db.Shop(shop).Product().rows()`.
 
-Key facts for writing code with letopis 1.4:
+Главное для кода на letopis:
 
-- 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), …
+- Пакет ESM, Node 22+, PostgreSQL 18+ с pgcrypto, кодировка базы UTF8. Зависимость времени выполнения — `postgres`. Zod 4 — необязательная peer-зависимость, нужна только `letopis/model`; `@modelcontextprotocol/server` — только `letopis/mcp`.
+- Схему ставит `up({ dsn, schema })` от администраторской роли; имя схемы — `v2.<имя>`; `up({ upgrade: true })` обновляет схему отставшей ревизии (миграции и повторный накат), `up({ schema, fresh: true })` пересоздаёт схему — данные теряются. Приложение подключается ролью LOGIN — членом `letopis_app`: `connect({ dsn, schema: 'v2.<имя>', token | apiKey })`. Роль в обход RLS отклоняется (`bypass_rls`), если не передать `allowBypassRls: true`.
+- Классы — хабы (объекты) и связи (отношения с концами). Их описывают `hub()` и `link()` из `letopis/model` и пишут в базу `syncModels()` или `letopis sync`. У класса с ключом id детерминированный, UUID v5 (`db.idOf`); уникальность — по ключу.
+- Глаголы возвращают цепочку; терминал (`rows`, `first`, `ids`, `count`, …) исполняет весь план одной транзакцией. `create` только создаёт (занятый ключ — `exists`), `update` сливает и никогда не создаёт, `upsert` заменяет объект целиком (только у классов с ключом), `delete()` — превью, `delete({ confirm: true })` удаляет.
+- Строгий режим. `connect({ models })` или `connect<Models>()` с файлом `letopis types` дают строгие типы: шаг — только класс или алиас моделей и системных классов, переходы — по концам, слоты — роли класса, поля фильтров, `or()` и агрегатов — поля класса; имя, известное только во время выполнения, — `loose(db)[имя]()`. Во время выполнения: `update()` и `delete({ confirm: true })` без фильтра, id, `tags()`, `owner()` и `limit()` ни у одного шага — `invalid_query` (все строки — `{ all: true }`); неизвестное поле фильтра, `sort()` или агрегата — `invalid_query` с похожими именами (сверяется первый ключ пути), неизвестный класс или роль — `invalid_class` с похожими; неизвестная опция `connect()`, `up()`, `load()`, `watch()`, `createMcpServer()` — `invalid_data` с похожими именами; `after()` перед `count()` и агрегатами — `invalid_query`; хаб с именем метода цепочки, корня `db` или батча — `invalid_class`.
+- Деньги и счётчики: `update({ balance: inc(n) })` прибавляет внутри оператора; `update(patch, { rev })` даёт `conflict`, если строка изменилась; `forUpdate()` блокирует строки внутри `db.begin()`.
+- История: `versions()` (у версии — автор, время, вид операции и причина) и срез `asOf(момент)`; глаголы, `db.begin()` и `db.batch()` принимают `{ reason }`. Журнал хранит каждую версию; `history: false` у класса — журнала нет.
+- Массовая загрузка с администраторского подключения: `db.load(rows)`; в пустую схему — `db.load(rows, { initial: true })`: одна транзакция, индексы и триггеры перестраиваются в конце.
+- Подписка: `db.watch({ from, classes })` — `await sub.ready()` перед записью, которая должна попасть в поток (`from: 'now'` фиксирует начало первым запросом); параллельные `next()` получают разные события.
+- Сигналы NOTIFY видны любой роли базы: `up({ signals: 'class' | 'tenant' | 'opaque' | 'none' })` выбирает, что они раскрывают (по умолчанию `class`).
+- Права действуют всегда и по умолчанию запрещают; `up({ tenant })` или `createTenant()` заводит арендатора с правилом «вошедшим можно всё» и его первого пользователя.
+- MCP: `createMcpServer(db)` из `letopis/mcp` и `letopis mcp` (stdio, только токен сессии пользователя) дают ИИ-агенту инструменты `letopis_model`, `letopis_query` (JSON-цепочка, без SQL), `letopis_history` и, с `write: true`, `letopis_write`; агент действует с правами одного пользователя, удаление подтверждает человек через elicitation. `structuredContent` ответа — `{ notice, data }` (отказ — `{ notice, error }`): `notice` предупреждает, что в `data` — данные базы, а не инструкции.
+- У ошибок строчный код `err.code`: `exists`, `conflict`, `invalid_data` (`err.issues`), `target_not_found`, `acl_denied`, `no_session`, …; `err.hint` — что делать, `err.docs` — ссылка на код в разделе «Ошибки» README.
 
-## Docs
+## Документы
 
-- [Agent cheatsheet](AGENT-CHEATSHEET.en.md): one page for an AI agent writing code with letopis — working cycle and pitfalls
-- [Guide](README.en.md): task-based guide, API reference, errors, limitations
-- [Шпаргалка для агента](AGENT-CHEATSHEET.md): the cheatsheet in Russian (original)
-- [Руководство](README.md): the guide in Russian (original)
+- [Шпаргалка для агента](AGENT-CHEATSHEET.md): одна страница для ИИ-агента, который пишет код на letopis, — рабочий цикл и грабли
+- [Руководство](README.md): руководство по задачам, справочник API, ограничения
+- [Ошибки](README.md#15-ошибки): все коды — что значит и что делать
 
-## Optional
+## Дополнительно
 
-- [Migration from 0.21](MIGRATION.md): data import with `letopis import` and the API replacement table (Russian)
-- [Changelog](CHANGELOG.md): decisions by version, BREAKING changes of 1.0 (Russian)
-- Model of a concrete installation for an agent: `letopis describe --format text --out llms.txt` or `describeText(db.describe())` — classes, keys, fields and ends of that schema
+- [Изменения по версиям](CHANGELOG.md): решения по версиям, несовместимые изменения
+- Модель конкретной установки для агента — инструмент MCP `letopis_model`: классы, ключи, поля, концы и рабочие цепочки этой схемы