letopis 1.4.2 → 2.0.0

package/dist/sql.d.ts

@@ -29,7 +29,7 @@ export interface Step {
 }
 /** Уникальная метка узла пути. */
 export declare const nextNodeKey: () => number;
-export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'countPaths' | 'versions' | 'agg' | 'diff' | 'blame';
+export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'countPaths' | 'versions' | 'agg';
 export interface AggSpec {
     fn: 'sum' | 'avg' | 'min' | 'max' | 'countBy';
     field: string;
@@ -48,6 +48,12 @@ export declare function roleOwners(reg: Registry, role: string): ClassInfo[];
 export declare function roleTargets(reg: Registry, role: string): string[];
 /** Конкретные классы, которые матчит шаг: класс (роль — её цели) и потомки, если не exact(). */
 export declare function stepClasses(reg: Registry, step: Step): string[];
+/**
+ * Отказы построителя, которым не нужны база и путь, — фильтр шага (в том числе неизвестное поле) и поле sort('data.…') или
+ * агрегата по классам шага: план записи проверяет их до первого оператора (write.ts:precheckPlan, §2.5), поэтому
+ * опечатка в фильтре цели не ломает db.begin(). Построитель при чтении проверяет то же самое ещё раз.
+ */
+export declare function precheckStep(reg: Registry, step: Step, order?: string, agg?: AggSpec): void;
 /** Принимает ли список классов конца класс cls (с учётом его предков). */
 export declare const accepts: (reg: Registry, targets: string[], cls: string) => boolean;
 export interface Hop {

package/dist/sql.js

@@ -17,15 +17,43 @@
  * Значения всегда уходят параметрами, поэтому текст запроса зависит только от формы цепочки: его
  * кэширует план (chain.ts), а postgres.js готовит оператор один раз на соединение.
  */
-import { LetopisError } from './errors.js';
+import { lerr, lmsg, similar } from './errors.js';
 import { isOp } from './ops.js';
 import { OP } from './types.js';
 let nodeSeq = 0;
 /** Уникальная метка узла пути. */
 export const nextNodeKey = () => ++nodeSeq;
-const fail = (msg) => {
-    throw new LetopisError('invalid_query', msg);
+/** Отказ построителя по ключу каталога — там, где нужно выражение: `x ?? refuse(ключ)`; в операторах — throw lerr(…). */
+const refuse = (key, params) => {
+    throw lerr(key, params);
 };
+/**
+ * Поля data строк системного класса Class — свойства метасхемы описания класса (class_metaschema() в 40-class.sql): строки
+ * Class проверяет она, а в описании самого класса Class только name. Ключи — свойства описания (ClassDescription) и
+ * служебные system и resolved: новое свойство описания без строки здесь — ошибка типов.
+ */
+const CLASS_ROW_FIELDS = Object.keys({
+    name: true, kind: true, parent: true, abstract: true, alias: true, system: true, fields: true, ends: true, key: true,
+    history: true, ownerDefault: true, cache: true, meta: true, resolved: true,
+});
+/** Поля верхнего уровня data строк класса: он закрыт (class_resolve, 40-class.sql) — в нём только поля описания. */
+const dataFields = (c) => c.name === 'Class' ? CLASS_ROW_FIELDS : Object.keys((c.schema.properties ?? {}));
+/**
+ * Поле фильтра, sort() или агрегата не описано ни в одном классе шага — такое условие ничего не найдёт: invalid_query с
+ * похожими именами (план 2.0, этап 3, п. 3; в 1.5 было предупреждение, 7.9 №6). Проверяется только верхний уровень:
+ * путь внутрь поля-объекта не сверяется. classes — класс шага и все классы, которые он матчит (потомки, если не exact(),
+ * у роли — её цели); ends — роли концов тоже годятся (фильтр).
+ */
+function checkField(classes, field, where, ends) {
+    if (!classes.length)
+        return;
+    if (classes.some((c) => dataFields(c).includes(field) || (ends && c.ends[field] !== undefined)))
+        return;
+    const names = classes.flatMap((c) => [...dataFields(c), ...(ends ? Object.keys(c.ends) : [])]);
+    throw lerr('query.unknown_field', { where, field, cls: classes[0].name, similar: similar(field, names) });
+}
+/** Поле sort('data.<путь>') или агрегата: первый ключ пути. */
+const topField = (field) => field.slice(5).split('.')[0];
 // ---------------------------------------------------------------------------
 // Классы шага и правила переходов
 // ---------------------------------------------------------------------------
@@ -47,6 +75,24 @@ export function stepClasses(reg, step) {
         return base;
     return uniq(base.flatMap((b) => (reg.has(b) ? reg.family(b).map((c) => c.name) : [b])));
 }
+/** Классы шага для типов листьев и сверки полей: класс шага первым, затем прочие классы, которые шаг матчит. */
+function typingOf(reg, step, names = stepClasses(reg, step)) {
+    const infos = names.map((n) => reg.find(n)).filter((c) => !!c);
+    return [step.cls, ...infos.filter((c) => c !== step.cls)];
+}
+/**
+ * Отказы построителя, которым не нужны база и путь, — фильтр шага (в том числе неизвестное поле) и поле sort('data.…') или
+ * агрегата по классам шага: план записи проверяет их до первого оператора (write.ts:precheckPlan, §2.5), поэтому
+ * опечатка в фильтре цели не ломает db.begin(). Построитель при чтении проверяет то же самое ещё раз.
+ */
+export function precheckStep(reg, step, order, agg) {
+    const typing = typingOf(reg, step);
+    compileFilter(reg, typing, step.filter, new Params());
+    if (order?.startsWith('data.'))
+        checkField(typing, topField(order), `sort('${order}')`, false);
+    if (agg?.field.startsWith('data.'))
+        checkField(typing, topField(agg.field), `${agg.fn}('${agg.field}')`, false);
+}
 /** Принимает ли список классов конца класс cls (с учётом его предков). */
 export const accepts = (reg, targets, cls) => (reg.find(cls)?.ancestors ?? [cls]).some((a) => targets.includes(a));
 /** Роли классов from, цели которых принимают хотя бы один класс to. */
@@ -85,7 +131,7 @@ export function resolveHop(reg, prev, next) {
         if ((dir === 'forward' ? fwd : rev).length)
             return { dir, roles: null };
     }
-    throw new LetopisError('no_path', `нет перехода ${prev.name} → ${next.name}: ни один класс не ссылается на другой`);
+    throw lerr('query.no_path', { from: prev.name, to: next.name });
 }
 // ---------------------------------------------------------------------------
 // Фильтры и операторы
@@ -188,7 +234,7 @@ function compileOp(path, leaf, o, p) {
             return compileOp(path, leaf, { [OP]: 'ne', args: [args[0]] }, p);
         }
         default:
-            return fail(`неизвестный оператор ${String(o[OP])}`);
+            throw lerr('query.unknown_op', { op: String(o[OP]) });
     }
 }
 /** Колонка tags: строка | список (все) | has / hasAny / hasAll. */
@@ -215,7 +261,7 @@ function compileTags(v, p) {
             }
         }
     }
-    return fail('tags() принимает строку, список или has/hasAny/hasAll');
+    throw lerr('query.tags_arg');
 }
 const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !isOp(v);
 /** Объект-строка ответа как значение: берётся id. */
@@ -227,7 +273,7 @@ function compileFilter(reg, classes, filter, p) {
     // or(…): дизъюнкция под-фильтров — только перепроверка
     if (isOp(filter)) {
         if (filter[OP] !== 'or')
-            fail(`оператор ${String(filter[OP])} на уровне фильтра шага — допустим только or(…)`);
+            throw lerr('query.step_op', { op: String(filter[OP]) });
         const parts = filter.args[0].map((f) => {
             const sub = compileFilter(reg, classes, f, p);
             const frags = [...asFrags(sub, p)];
@@ -241,7 +287,7 @@ function compileFilter(reg, classes, filter, p) {
         return out;
     }
     if (Array.isArray(filter)) {
-        out.ids = filter.map((x) => idOfValue(x) ?? fail('список id: ожидались строки'));
+        out.ids = filter.map((x) => idOfValue(x) ?? refuse('query.id_list'));
         return out;
     }
     const props = (classes[0]?.schema.properties ?? {});
@@ -281,9 +327,9 @@ function compileFilter(reg, classes, filter, p) {
             if (typeof value === 'string')
                 out.ids = [value];
             else if (Array.isArray(value))
-                out.ids = value.map((x) => idOfValue(x) ?? fail('filter.id: ожидались строки'));
+                out.ids = value.map((x) => idOfValue(x) ?? refuse('query.filter_id_list'));
             else
-                fail('filter.id принимает строку или список строк');
+                throw lerr('query.filter_id');
             continue;
         }
         if (isRole(key)) {
@@ -292,12 +338,14 @@ function compileFilter(reg, classes, filter, p) {
                 out.frags.push((a) => `coalesce(${a}.links->${role}, 'null'::jsonb) in ('null'::jsonb, '[]'::jsonb)`);
                 continue;
             }
-            const id = idOfValue(value) ?? fail(`конец ${key}: ожидался id, строка ответа или null`);
+            const id = idOfValue(value) ?? refuse('query.end_value', { role: key });
             out.ends.push(id);
             const ph = p.push(id);
             out.frags.push((a) => `${SCHEMA_MARK}.role_has(${a}.links, array[${role}], ${ph}::uuid)`);
             continue;
         }
+        // поле данных: не описано ни в одном классе шага — invalid_query с похожими (план 2.0, этап 3, п. 3)
+        checkField(classes, key, `${classes[0]?.name ?? ''}({ ${key} })`, true);
         if (isOp(value)) {
             out.frags.push(compileOp([key], leafOf(reg, classes, [key]), value, p));
             continue;
@@ -318,8 +366,12 @@ function compileFilter(reg, classes, filter, p) {
 function asFrags(cf, p) {
     const frags = [...cf.frags];
     if (cf.ids) {
-        const ph = p.push(cf.ids);
-        frags.push((a) => `${a}.id = any (${ph}::uuid[])`);
+        // один id — равенство, а не = any (массив): общий план подготовленного запроса для = any PostgreSQL считает на ~10
+        // элементов, и при неудачной выборке ANALYZE чтение по ключу навсегда оставалось на планах под каждый вызов —
+        // 0,5–0,8 мс планирования на чтение (замер против 1.0.1); общий план равенства стоит как план вызова и выбирается всегда
+        const one = cf.ids.length === 1;
+        const ph = p.push(one ? cf.ids[0] : cf.ids);
+        frags.push((a) => (one ? `${a}.id = ${ph}::uuid` : `${a}.id = any (${ph}::uuid[])`));
     }
     if (cf.eq) {
         const ph = p.push(cf.eq);
@@ -341,7 +393,7 @@ function sortSpec(order, leaf) {
         const t = leaf(path);
         return { expr: (a) => (CAST[t] ? `(${accessor(path)(a)})${CAST[t]}` : accessor(path)(a)), pcast: PCAST[t], field: order, type: t, nullable: true };
     }
-    return fail(`sort: поле 'at', 'rev', 'id' или 'data.<путь>', а не '${order}'`);
+    throw lerr('query.sort_field', { field: order });
 }
 /** Формы значений курсора — как у форматов uuid, date и date-time валидатора (validate.ts). */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -398,9 +450,11 @@ function shown(v) {
     }
     return s.length > 60 ? `${s.slice(0, 59)}…` : s;
 }
+/** Какое значение курсора ждёт поле sort() по своему типу — запись каталога (параметр expect ошибки курсора). */
 const CURSOR_EXPECT = {
-    numeric: 'число', int: 'целое число', boolean: 'true/false', text: 'строка', uuid: 'uuid строкой',
-    timestamptz: 'время строкой вида 2026-10-07T10:00:00Z', date: 'дата строкой вида 2026-10-07', jsonb: 'строка, число, true/false',
+    numeric: 'query.cursor_expect_numeric', int: 'query.cursor_expect_int', boolean: 'query.cursor_expect_boolean',
+    text: 'query.cursor_expect_text', uuid: 'query.cursor_expect_uuid', timestamptz: 'query.cursor_expect_timestamptz',
+    date: 'query.cursor_expect_date', jsonb: 'query.cursor_expect_jsonb',
 };
 /**
  * Параметры keyset из курсора: значение проверяется по типу поля сортировки до запроса. Курсор
@@ -409,16 +463,15 @@ const CURSOR_EXPECT = {
  * Курсор того же типа с другого поля проверка не отличит.
  */
 function cursorParams(c, sort) {
-    const how = `cursorOf(строка, '${sort.field}')`;
     if (typeof c !== 'object' || c === null || c.v === undefined)
-        return fail(`after(cursor): курсор — объект { v, id } из ${how}`);
+        throw lerr('query.cursor_shape', { field: sort.field });
     const { v, id } = c;
     if (typeof id !== 'string' || !UUID_RE.test(id))
-        return fail(`after(cursor): id курсора — uuid строки, а не ${shown(id)}`);
+        throw lerr('query.cursor_id', { id: shown(id) });
     const value = v === null && sort.nullable ? null : cursorValue(v, sort.type);
     if (value === undefined) {
-        return fail(`after(cursor): значение курсора ${shown(v)} не подходит к sort('${sort.field}') — ожидалось: ${CURSOR_EXPECT[sort.type]}`
-            + `${sort.nullable ? ' или null' : ''}; курсор снят с другого поля? Нужен ${how}`);
+        // у поля данных подходит и курсор null — своя запись, а не склейка « или null»
+        throw lerr(sort.nullable ? 'query.cursor_value_nullable' : 'query.cursor_value', { value: shown(v), field: sort.field, expect: lmsg(CURSOR_EXPECT[sort.type]) });
     }
     return { v: value, id };
 }
@@ -428,7 +481,7 @@ function cursorRev(c) {
     if (rev === undefined)
         return undefined;
     if (!Number.isInteger(rev) || rev < 1)
-        return fail(`after(cursor): rev курсора — номер версии (целое ≥ 1), а не ${shown(rev)}`);
+        throw lerr('query.cursor_rev', { rev: shown(rev) });
     return rev;
 }
 /** id узлов пути из курсора paths() по ключам узлов (план 2.0, 7.1 №3); курсор без path — undefined. */
@@ -439,7 +492,7 @@ function cursorPath(c, keys) {
     return keys.map((k) => {
         const id = typeof path === 'object' && path !== null ? path[k] : undefined;
         if (typeof id !== 'string' || !UUID_RE.test(id))
-            return fail(`after(cursor): в курсоре пути нет id узла ${k} — нужен cursorOf(путь, поле) из paths() этой же цепочки`);
+            throw lerr('query.cursor_path', { key: k });
         return id;
     });
 }
@@ -466,7 +519,7 @@ export function cursorOf(row, field) {
             v = v?.[k];
         return { v: (v ?? null), id: row.id, ...rev };
     }
-    return fail(`cursorOf: поле 'at', 'rev', 'id' или 'data.<путь>', а не '${field}'`);
+    throw lerr('query.cursor_of_field', { field });
 }
 // ---------------------------------------------------------------------------
 // Построение запроса
@@ -476,14 +529,14 @@ export function cursorOf(row, field) {
  * заденет литералы — имя поля вида a@S@b прежде портилось (план 2.0, 7.1 №5).
  */
 const SCHEMA_MARK = '\u0000S\u0000';
-const COLS = ['id', 'rev', 'class', 'tenant', 'owner', 'links', 'data', 'tags', 'at', 'author', 'agent', 'op', 'reason', 'moved'];
-/** Колонки журнала, выданные приложению: все, кроме changed (ревью №1 точки А плана 1.1, 10-core.sql). */
-const LOG_COLS = ['seq', 'tx', 'id', 'rev', 'class', 'cv', 'tenant', 'owner', 'links', 'data', 'tags', 'at', 'author', 'agent', 'op', 'reason',
-    'moved', 'prev_hash', 'hash'].map((c) => 'l.' + c).join(', ');
+const COLS = ['id', 'rev', 'class', 'tenant', 'owner', 'links', 'data', 'tags', 'at', 'author', 'agent', 'op', 'reason'];
+/** Колонки журнала (выданные приложению — 10-core.sql). */
+const LOG_COLS = ['seq', 'tx', 'id', 'rev', 'class', 'cv', 'tenant', 'owner', 'links', 'data', 'tags', 'at', 'author', 'agent', 'op', 'reason']
+    .map((c) => 'l.' + c).join(', ');
 const colsOf = (a) => COLS.map((c) => `${a}.${c}`).join(', ');
 export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
     if (!steps.length)
-        fail('пустая цепочка');
+        throw lerr('query.empty_chain');
     const S = `"${schema.replace(/"/g, '""')}"`;
     const p = new Params();
     const cur = mods.asOf === undefined;
@@ -495,7 +548,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         if (s.pivotKey !== undefined) {
             const at = byNodeKey.get(s.pivotKey);
             if (at === undefined)
-                fail(`возврат к узлу ${s.name}: узла нет в этом пути`);
+                throw lerr('query.pivot_missing', { name: s.name });
             real[i] = at;
         }
         else {
@@ -513,8 +566,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
     for (let i = 0; i < steps.length; i++) {
         const step = steps[i];
         const names = stepClasses(reg, step);
-        const infos = names.map((n) => reg.find(n)).filter((c) => !!c);
-        const typing = [step.cls, ...infos.filter((c) => c !== step.cls)];
+        const typing = typingOf(reg, step, names);
         // возврат к узлу: только дофильтры
         if (step.pivotKey !== undefined) {
             const a = `h${real[i]}`;
@@ -563,7 +615,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
             }
             // по классу: id-кандидаты классов шага, последняя версия — любого класса (как find_ids, план 2.0, 7.1 №1)
             return `(select v.id, v.rev from ${versionsAt(at, ids ? `l.id = any (${ids})` : `l.id in (select c.id from ${S}.log c where c.class = any (${clsPh}))`)} v `
-                + `where v.class = any (${clsPh}) and (v.op = 'delete') = ${isDead} and v.op not in ('purge', 'trim', 'reset')${dataCond('v')}${endsCond(`${S}.link_ids(v.links)`)})`;
+                + `where v.class = any (${clsPh}) and (v.op = 'delete') = ${isDead}${dataCond('v')}${endsCond(`${S}.link_ids(v.links)`)})`;
         };
         const entityPart = (src, depth = 'null::int', from = `${S}.entity x`) => `select ${colsOf('x')}, ${depth} as depth from ${from} where ${where('x', src)}`;
         /**
@@ -580,7 +632,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         const parts = [];
         if (i === 0) {
             if (step.deepMax !== undefined)
-                fail('deep() — на шаге перехода к тому же классу, а не на первом шаге');
+                throw lerr('query.deep_first_step');
             if (cur) {
                 // условие id уже в conds — первичный ключ; вложение — поиск по индексу GIN
                 parts.push(!cf.ids && (cf.eq || cf.ends.length) ? entityByIds(`select f.id from ${findIds(null, 'null', false)} f`) : entityPart(undefined));
@@ -601,15 +653,15 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         const rolesCond = (v, src) => (hop.roles ? ` and ${S}.role_has(${v}.links, ${rolesPh}, ${src})` : '');
         if (step.deepMax !== undefined) {
             if (hop.dir !== 'reverse' || !stepClasses(reg, steps[a]).some((c) => names.includes(c))) {
-                fail(`deep() — только на переходе к тому же классу (дети любой глубины): ${steps[a].name} → ${step.name}`);
+                throw lerr('query.deep_hop', { from: steps[a].name, to: step.name });
             }
             if (dead)
-                fail('deep() и withDeleted() не сочетаются');
+                throw lerr('query.deep_with_deleted');
             const maxPh = `${p.push(step.deepMax)}::int`;
             let deepSrc = `${S}.find_deep(${clsPh}, ${rolesPh}, ${srcArr}, ${maxPh}, ${atPh})`;
             if (opts.direct) {
                 // тот же обход под RLS: невидимый узел обрывает поддерево политикой
-                const node = cur ? `${S}.entity` : `(select w.id, w.rev, w.links from ${versionsAt(atPh, `l.class = any (${clsPh})`)} w where w.op not in ('delete', 'purge', 'trim', 'reset'))`;
+                const node = cur ? `${S}.entity` : `(select w.id, w.rev, w.links from ${versionsAt(atPh, `l.class = any (${clsPh})`)} w where w.op <> 'delete')`;
                 const hasSrc = (v, src) => (cur ? `${v}.ends @> array[${src}]` : `${S}.link_ids(${v}.links) @> array[${src}]`);
                 const cls = (v) => (cur ? ` and ${v}.class = any (${clsPh})` : '');
                 deepSrc = `(with recursive d(src, id, rev, depth, seen) as (`
@@ -645,7 +697,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
                 }
                 return `(select s.src, v.id, v.rev from ${versionsAt(at, `l.class = any (${clsPh})`)} v `
                     + `cross join lateral unnest(${S}.link_ids(v.links)) t(x) join ${srcs} on s.src = t.x `
-                    + `where (v.op = 'delete') = ${isDead} and v.op not in ('purge', 'trim', 'reset')${dataCond('v')}${endsCond(`${S}.link_ids(v.links)`)}${rolesCond('v', 's.src')})`;
+                    + `where (v.op = 'delete') = ${isDead}${dataCond('v')}${endsCond(`${S}.link_ids(v.links)`)}${rolesCond('v', 's.src')})`;
             };
             ctes.push(`p${i}a as (select q.src, q.id, q.rev from ${hopCall(atPh, false)} q)`);
             // пары переходов — по одной на (источник, цель): объект, который ссылается на несколько объектов прошлого шага,
@@ -686,6 +738,8 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
     const single = tail.length === 0 && !steps.some((st) => st.pivotKey !== undefined);
     const ents = single ? `n${lastNode}` : `(select z0.* from n${lastNode} z0 where z0.id in (select h${lastNode}.id ${from}${whereOf(tail)}))`;
     const leaf = (path) => leafOf(reg, rowsNode(lastNode), path);
+    if (mods.order?.startsWith('data.'))
+        checkField(rowsNode(lastNode), topField(mods.order), `sort('${mods.order}')`, false);
     const sort = mods.order ? sortSpec(mods.order, leaf) : undefined;
     const dir = mods.desc ? ' desc' : '';
     /** Порядок: поле sort, id строки и разделители равных (id прочих узлов пути). */
@@ -700,7 +754,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         if (!mods.after)
             return undefined;
         if (!sort)
-            fail('after(cursor) требует sort(поле)');
+            throw lerr('query.after_without_sort');
         const c = cursorParams(mods.after, sort);
         const t = ties(mods.after);
         const lt = mods.desc ? '<' : '>';
@@ -724,28 +778,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
     const others = keyed.filter((k) => k.node !== lastNode);
     const pathKeys = [...others, ...keyed.filter((k) => k.node === lastNode)].map((k) => k.key);
     const limitOffset = () => (mods.limit !== undefined ? ` limit ${p.push(mods.limit)}::bigint` : '') + (mods.offset !== undefined ? ` offset ${p.push(mods.offset)}::bigint` : '');
-    // versions({ follow: true }): отрезки истории объектов шага по переносам id (reclass, rekey) в обе стороны — версии
-    // id с номерами (lo, hi]. Надгробие переноса кончает отрезок, первая версия на новом id начинает: объект, заведённый
-    // на прежнем id после переноса, в историю не попадает (план 2.0, 7.1 №2). Тот же обход — history_segments в
-    // lib/sql/75-history.sql (diff и blame); здесь он в самом запросе, чтобы работал и на схеме до up() этой версии.
-    if (mode === 'versions' && mods.follow) {
-        // границы отрезка с версией r: строки переноса id — через парную строку по индексу log_moved (moved друг на друга),
-        // без прохода по версиям id
-        const bounds = (i, r) => `cross join lateral (select greatest(coalesce(max(x.rev) filter (where x.op = 'delete' and x.rev < ${r}), 0), `
-            + `coalesce(max(x.rev - 1) filter (where x.op <> 'delete' and x.rev <= ${r}), 0)) as lo, `
-            + `least(min(x.rev) filter (where x.op = 'delete' and x.rev >= ${r}), min(x.rev - 1) filter (where x.op <> 'delete' and x.rev > ${r})) as hi `
-            + `from ${S}.log m join ${S}.log x on x.moved = m.id and x.id = ${i} where m.moved = ${i}) b`;
-        ctes.push(`f(id, lo, hi, n) as (select z.id, b.lo, b.hi, 0 from ${ents} z ${bounds('z.id', 'z.rev')} `
-            + `union select g.id, b.lo, b.hi, g.n from f cross join lateral (`
-            + `select a.moved as id, (select t.rev from ${S}.log t where t.id = a.moved and t.op = 'delete' and t.moved = f.id `
-            + `order by abs(t.seq - a.seq) limit 1) as r, f.n - 1 as n from ${S}.log a `
-            + `where f.n <= 0 and a.id = f.id and a.rev = f.lo + 1 and a.moved is not null and a.op <> 'delete' `
-            + `union all select t.moved, (select a.rev from ${S}.log a where a.id = t.moved and a.op <> 'delete' and a.moved = f.id `
-            + `order by abs(a.seq - t.seq) limit 1), f.n + 1 from ${S}.log t `
-            + `where f.n >= 0 and t.id = f.id and t.rev = f.hi and t.op = 'delete' and t.moved is not null) g ${bounds('g.id', 'g.r')} `
-            + `where g.r is not null and abs(g.n) <= 1000)`);
-    }
-    const withClause = `with ${mode === 'versions' && mods.follow ? 'recursive ' : ''}${ctes.join(',\n')}\n`;
+    const withClause = `with ${ctes.join(',\n')}\n`;
     let text;
     let aggLeaf;
     switch (mode) {
@@ -772,37 +805,22 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
             break;
         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';
+            // без sort — по id и номеру версии
+            const order = sort ? `${sort.expr('v')}${dir}, v.id${dir}, v.rev${dir}` : 'v.id, v.rev';
             // курсор — поле sort, id и номер версии: версии одного объекта с равным полем не теряются (план 2.0, 7.1 №4)
             const cond = whereOf([after('v', (c) => {
                     const rev = cursorRev(c);
                     return rev === undefined ? [] : [{ col: 'v.rev', val: rev, cast: '::int' }];
                 })]);
-            text = mods.follow
-                ? `${withClause}select to_jsonb(v) as row from (select ${colsOf('l')}, null::int as depth from (select distinct f.id, f.lo, f.hi from f) s `
-                    + `cross join lateral (select ${colsOf('l')} from ${S}.log l where l.id = s.id and l.rev > s.lo and l.rev <= coalesce(s.hi, 2147483647)) l) v`
-                    + `${cond} 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${cond} order by ${order}${limitOffset()}`;
-            break;
-        }
-        case 'diff':
-        case 'blame': {
-            // план 1.1, §2.1: функции базы считают по журналу под RLS — по одному документу на объект шага
-            const h = mods.hist ?? {};
-            const num = (v) => (typeof v === 'number' ? `${p.push(v)}::int` : 'null');
-            const ts = (v) => (typeof v === 'string' ? `${p.push(v)}::text::timestamptz` : 'null');
-            const call = mode === 'diff'
-                ? `${S}.diff_versions(z.id, ${num(h.from)}, ${num(h.to)}, ${ts(h.from)}, ${ts(h.to)}, ${h.follow ? 'true' : 'false'})`
-                : `${S}.blame(z.id, ${ts(h.at)}, ${num(h.limit)})`;
-            text = `${withClause}select ${call} as row from (select distinct z.id from ${ents} z) z order by z.id`;
+            text = `${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${cond} order by ${order}${limitOffset()}`;
             break;
         }
         case 'agg': {
             if (!agg || !agg.field.startsWith('data.'))
-                fail("агрегат по полю 'data.<путь>'");
+                throw lerr('query.agg_field');
             const path = agg.field.slice(5).split('.');
+            checkField(rowsNode(lastNode), path[0], `${agg.fn}('${agg.field}')`, false);
             const acc = accessor(path)('z');
             aggLeaf = leaf(path);
             if (agg.fn === 'countBy') {
@@ -822,14 +840,12 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
 }
 /** Строка из to_jsonb(узла): служебные поля в $deleted / $depth, пустые необязательные — без ключа. */
 export function toRow(raw) {
-    const { depth, agent, reason, moved, changed: _changed, ...rest } = raw;
+    const { depth, agent, reason, ...rest } = raw;
     const row = rest;
     if (agent != null)
         row.agent = agent;
     if (reason != null)
         row.reason = reason;
-    if (moved != null)
-        row.moved = moved;
     if (row.op === 'delete')
         row.$deleted = true;
     if (depth != null)

package/dist/sync.d.ts

@@ -6,7 +6,7 @@
  * мешающими строками отклоняет сама база (`tightening_conflict` с перечнем) уже в сухом прогоне.
  * generateTypes: объявления TypeScript для классов из реестра — в том числе созданных данными.
  */
-import type { Db } from './index.js';
+import type { DbCore } from './index.js';
 import type { AnyModel, LostRule } from './model.js';
 import type { JsonSchema } from './jsonschema.js';
 import type { Registry } from './registry.js';
@@ -20,12 +20,18 @@ export interface SyncResult {
     /** Правила refine, которых нет в базе. */
     lost: LostRule[];
 }
-export declare function syncModels(db: Db, models: readonly AnyModel[], opts?: {
+export declare function syncModels(db: DbCore, models: readonly AnyModel[], opts?: {
     apply?: boolean;
 }): Promise<SyncResult>;
 /** Тип TypeScript по JSON Schema подмножества. */
 export declare function schemaToTs(s: JsonSchema | undefined, indent?: string): string;
-/** Объявления `<Класс>Data` и `<Класс>Links` для классов реестра (кроме системных). */
+/**
+ * Объявления `<Класс>Data` и `<Класс>Links` для классов реестра и `<Класс>Model` — имя, алиас, концы с классами целей
+ * и предки (ModelLike, typed.ts), — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`
+ * (план 2.0, этап 4, п. 1). Классы арендатора System (системные и классы сидов пакета) — только с includeSystem
+ * (`letopis types --system`); без него системные классы даёт встроенный набор SystemModels. Пометка в первой строке —
+ * запись каталога model.types_header.
+ */
 export declare function generateTypes(registry: Registry, opts?: {
     includeSystem?: boolean;
 }): string;

package/dist/sync.js

@@ -1,4 +1,6 @@
-import { LetopisError } from './errors.js';
+import { lerr, lmsg } from './errors.js';
+import { internalsOf } from './internal.js';
+import { RESERVED_CLASS_NAMES } from './types.js';
 const ROLLBACK = Symbol('sync-dry-run');
 /** Канонический JSON: ключи по алфавиту — сравнение описаний без учёта порядка ключей. */
 function canon(v) {
@@ -9,11 +11,17 @@ function canon(v) {
     return JSON.stringify(v);
 }
 export async function syncModels(db, models, opts = {}) {
+    // хаб с именем метода цепочки или корня db (модель собрана мимо hub()) — отказ до записи (план 2.0, этап 4, п. 2;
+    // 7.10 №3); связь с таким именем отклоняет база
+    for (const m of models) {
+        if (m.kind === 'hub' && RESERVED_CLASS_NAMES.includes(m.name))
+            throw lerr('model.sync_hub_name_reserved', { name: m.name });
+    }
     const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
     const S = `"${db.schema.replace(/"/g, '""')}"`;
-    // предок раньше потомка; класс-источник агрегата раньше цели: агрегат над классом, которого ещё нет, база отклоняет.
-    // Круг (агрегат над собственным потомком, цикл агрегатов) так не упорядочить — отказ до записи с самим кругом (хвост
-    // ревью доработок после 1.2.0: раньше обход молча ставил потомка раньше предка)
+    // предок раньше потомка: потомка класса, которого ещё нет, база отклоняет. Круг родителей (модель, собранная мимо
+    // hub()) так не упорядочить — отказ до записи с самим кругом (хвост ревью доработок после 1.2.0: раньше обход молча
+    // ставил потомка раньше предка)
     const ordered = [];
     const path = [];
     const visit = (m) => {
@@ -21,23 +29,21 @@ export async function syncModels(db, models, opts = {}) {
             return;
         const at = path.indexOf(m);
         if (at >= 0) {
-            throw new LetopisError('invalid_class', `syncModels: модели зависят друг от друга по кругу: ${[...path.slice(at), m].map((x) => x.name).join(' → ')} — `
-                + 'родителя и источник агрегата база ждёт раньше класса');
+            throw lerr('model.models_cycle', { cycle: [...path.slice(at), m].map((x) => x.name).join(' → ') });
         }
         path.push(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);
-        }
         path.pop();
         ordered.push(m);
     };
     models.forEach(visit);
+    // у корня connect({ admin }) классы пишет администраторский пул с той же сессией (план 2.0, 7.9 №3): правка класса
+    // со строками требует прав, которых у роли приложения может не быть
+    const adminTx = internalsOf(db)?.adminTx;
+    const run = (fn) => (adminTx ? adminTx(fn) : db.transaction(fn));
     try {
-        await db.transaction(async (tx) => {
+        await run(async (tx) => {
             for (const m of ordered) {
                 const desc = m.describe();
                 const [cur] = await tx.unsafe(`select tenant = ${S}.ctx_tenant() as own, data - 'resolved' as data from ${S}.entity
@@ -108,23 +114,40 @@ export function schemaToTs(s, indent = '') {
         }
     }).join(' | ');
 }
-/** Объявления `<Класс>Data` и `<Класс>Links` для классов реестра (кроме системных). */
+/**
+ * Объявления `<Класс>Data` и `<Класс>Links` для классов реестра и `<Класс>Model` — имя, алиас, концы с классами целей
+ * и предки (ModelLike, typed.ts), — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`
+ * (план 2.0, этап 4, п. 1). Классы арендатора System (системные и классы сидов пакета) — только с includeSystem
+ * (`letopis types --system`); без него системные классы даёт встроенный набор SystemModels. Пометка в первой строке —
+ * запись каталога model.types_header.
+ */
 export function generateTypes(registry, opts = {}) {
-    const out = ['// Сгенерировано letopis types — не править руками.', ''];
+    const out = [`// ${lmsg('model.types_header')}`, ''];
+    const models = [];
+    const lit = (v) => JSON.stringify(v);
     for (const c of registry.all().sort((a, b) => a.name.localeCompare(b.name))) {
         if (!opts.includeSystem && c.tenant === '2eba6d0a-1edd-4bb6-a85a-a703dab49035')
             continue;
         // идентификатор TypeScript — буквы Unicode, цифры, _ и $: кириллические имена классов допустимы (план 2.0, 7.5 №1)
         if (!/^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(c.name))
-            throw new LetopisError('invalid_class', `types: имя класса ${c.name} не годится для идентификатора TypeScript`);
+            throw lerr('model.types_class_name', { name: c.name });
         // additionalProperties: false верхнего уровня в тип не переносится — лишние ключи и так ошибка типов
         const { additionalProperties: _closed, ...open } = c.schema;
         void _closed;
         // объектный литерал — интерфейс; класс без полей, union и открытая схема — псевдоним типа (иначе неверный TypeScript)
         const data = schemaToTs(open);
         out.push(/^\{[\s\S]*\}$/.test(data) && !/\}\s*&/.test(data) ? `export interface ${c.name}Data ${data}` : `export type ${c.name}Data = ${data};`);
-        const ends = Object.entries(c.ends).map(([role, e]) => `  ${JSON.stringify(role)}${e.required || (e.min ?? 0) > 0 ? '' : '?'}: ${e.many ? 'string[]' : 'string'};`);
-        out.push(`export interface ${c.name}Links {${ends.length ? `\n${ends.join('\n')}\n` : ''}}`, '');
+        const required = (e) => e.required === true || (e.min ?? 0) > 0;
+        const ends = Object.entries(c.ends).map(([role, e]) => `  ${lit(role)}${required(e) ? '' : '?'}: ${e.many ? 'string[]' : 'string'};`);
+        out.push(`export interface ${c.name}Links {${ends.length ? `\n${ends.join('\n')}\n` : ''}}`);
+        // концы с классами целей и предки — переходы, слоты и семейства строгих типов (typed.ts: ModelLike)
+        const specs = Object.entries(c.ends).map(([role, e]) => {
+            const targets = (Array.isArray(e.class) ? e.class : [e.class]).map(lit).join(' | ');
+            return `      ${lit(role)}: { targets: ${targets}; many: ${e.many === true}; required: ${required(e)} };`;
+        });
+        out.push(`export interface ${c.name}Model {`, `  readonly name: ${lit(c.name)};`, ...(c.alias ? [`  readonly alias: ${lit(c.alias)};`] : []), '  readonly __types?: {', `    data: ${c.name}Data;`, `    links: ${c.name}Links;`, `    ends: {${specs.length ? `\n${specs.join('\n')}\n    ` : ''}};`, `    ancestors: ${(c.ancestors.length ? c.ancestors : [c.name]).map(lit).join(' | ')};`, '  };', '}', '');
+        models.push(`${c.name}Model`);
     }
+    out.push(`export type Models = readonly [${models.join(', ')}];`, '');
     return out.join('\n');
 }

package/dist/tx.d.ts

@@ -93,6 +93,16 @@ export interface TxContext {
     passes?: AclPasses;
     /** После успешной операции (продление сессии раз в минуту). */
     after?: () => void;
+    /**
+     * Сессия кончилась (no_session): выдать новую и вписать её токен в failed — у подключения по ключу APIKEY ключ
+     * обменивается заново. true — операцию можно повторить (один раз). Нет — no_session как есть.
+     */
+    renew?: (failed: TxContext) => Promise<boolean>;
+    /**
+     * Перед операцией (runTx, ExplicitTx.open): после простоя подключение проверяет, жива ли сессия, — иначе чтение под
+     * истёкшей сессией шло бы как анонимное и молча отдавало пустой ответ. Обновляет токен ctx, если сессию выдали заново.
+     */
+    before?: (ctx: TxContext) => Promise<void>;
     /**
      * После фиксации записи: нагрузки из letopis.changed (сигналы записи, session:<тег>) — кэш
      * результатов сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
@@ -136,7 +146,7 @@ export declare class ExplicitTx implements Executor {
     /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
     private raw;
     private constructor();
-    static open(ctx: TxContext): Promise<ExplicitTx>;
+    static open(ctx: TxContext, renewed?: boolean): Promise<ExplicitTx>;
     /** Транзакция ещё открыта (не зафиксирована и не откачена). */
     get active(): boolean;
     run<T>(fn: (tx: Tx) => Promise<T>, opts?: {