letopis 1.4.1 → 2.0.0

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) => `@S@.role_has(${a}.links, array[${role}], ${ph}::uuid)`);
+            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,46 +463,80 @@ 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 };
 }
+/** rev курсора: в versions() отделяет версии одного объекта с равным полем сортировки (план 2.0, 7.1 №4). */
+function cursorRev(c) {
+    const rev = c.rev;
+    if (rev === undefined)
+        return undefined;
+    if (!Number.isInteger(rev) || rev < 1)
+        throw lerr('query.cursor_rev', { rev: shown(rev) });
+    return rev;
+}
+/** id узлов пути из курсора paths() по ключам узлов (план 2.0, 7.1 №3); курсор без path — undefined. */
+function cursorPath(c, keys) {
+    const path = c.path;
+    if (path === undefined)
+        return undefined;
+    return keys.map((k) => {
+        const id = typeof path === 'object' && path !== null ? path[k] : undefined;
+        if (typeof id !== 'string' || !UUID_RE.test(id))
+            throw lerr('query.cursor_path', { key: k });
+        return id;
+    });
+}
+const isPath = (x) => typeof x.id !== 'string'
+    && Object.values(x).length > 0 && Object.values(x).every((n) => typeof n === 'object' && n !== null && typeof n.id === 'string');
 /**
- * Курсор постраничного вывода для `after()`: `{ v, id }` — значение поля сортировки и id последней строки страницы.
- * Поле — то же, что в `sort()`; если его нет в данных строки, `v` — `null`.
+ * Курсор постраничного вывода для `after()`: значение поля сортировки, id и номер версии последней строки страницы.
+ * Поле — то же, что в `sort()`; если его нет в данных строки, `v` — `null`. Для пути из `paths()` — то же по его
+ * последнему узлу (узлу последнего шага) и id всех узлов: курсор отделяет пути с общим последним узлом.
  */
 export function cursorOf(row, field) {
+    if (isPath(row)) {
+        const keys = Object.keys(row);
+        const { v, id } = cursorOf(row[keys[keys.length - 1]], field);
+        return { v, id, path: Object.fromEntries(keys.map((k) => [k, row[k].id])) };
+    }
     const f = field === 'updated' ? 'at' : field;
+    const rev = typeof row.rev === 'number' ? { rev: row.rev } : {};
     if (f === 'at' || f === 'rev' || f === 'id')
-        return { v: row[f], id: row.id };
+        return { v: row[f], id: row.id, ...rev };
     if (f.startsWith('data.')) {
         let v = row.data;
         for (const k of f.slice(5).split('.'))
             v = v?.[k];
-        return { v: (v ?? null), id: row.id };
+        return { v: (v ?? null), id: row.id, ...rev };
     }
-    return fail(`cursorOf: поле 'at', 'rev', 'id' или 'data.<путь>', а не '${field}'`);
+    throw lerr('query.cursor_of_field', { field });
 }
 // ---------------------------------------------------------------------------
 // Построение запроса
 // ---------------------------------------------------------------------------
-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(', ');
+/**
+ * Метка схемы во фрагментах, собранных до имени схемы: символ NUL не бывает в тексте PostgreSQL, поэтому замена не
+ * заденет литералы — имя поля вида 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'];
+/** Колонки журнала (выданные приложению — 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;
@@ -460,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 {
@@ -478,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]}`;
@@ -526,8 +613,9 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
                 return `(select v.id, v.rev from ${S}.entity v where v.class = any (${clsPh})${dataCond('v')}${endsCond('v.ends')}`
                     + `${ids ? ` and v.id = any (${ids})` : ''})`;
             }
-            return `(select v.id, v.rev from ${versionsAt(at, ids ? `l.id = any (${ids})` : `l.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)`)})`;
+            // по классу: 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}${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)}`;
         /**
@@ -544,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));
@@ -565,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 (`
@@ -609,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)`);
             // пары переходов — по одной на (источник, цель): объект, который ссылается на несколько объектов прошлого шага,
@@ -650,43 +738,59 @@ 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' : '';
-    const orderBy = (a) => (sort ? ` order by ${sort.expr(a)}${dir}, ${a}.id${dir}` : '');
-    const after = (a) => {
+    /** Порядок: поле sort, id строки и разделители равных (id прочих узлов пути). */
+    const orderBy = (a, more = []) => (sort ? ` order by ${[sort.expr(a), `${a}.id`, ...more].map((x) => `${x}${dir}`).join(', ')}` : '');
+    /**
+     * «Строго после курсора» в порядке order by: поле sort, id строки и разделители равных из курсора — rev версии
+     * (versions()) или id прочих узлов пути (paths()). Без них страница начиналась бы после всех строк с тем же полем
+     * и id: терялись бы другие версии объекта и другие пути к тому же узлу. Курсор без rev или path сравнивается по
+     * началу порядка, как прежде.
+     */
+    const after = (a, ties = () => []) => {
         if (!mods.after)
             return undefined;
         if (!sort)
-            fail('after(cursor) требует sort(поле)');
+            throw lerr('query.after_without_sort');
         const c = cursorParams(mods.after, sort);
-        if (!sort.nullable)
-            return `(${sort.expr(a)}, ${a}.id) ${mods.desc ? '<' : '>'} (${p.push(c.v)}${sort.pcast}, ${p.push(c.id)}::uuid)`;
+        const t = ties(mods.after);
+        const lt = mods.desc ? '<' : '>';
         // Поле данных бывает null (или его нет): order by ставит такие строки в конец при возрастании и в
         // начало при убывании, а сравнение строк с null даёт null — одно сравнение их теряло, курсор null
         // давал пустую страницу. Здесь null — значение после всех прочих (asc) или перед ними (desc); текст
         // один на оба вида курсора (параметр — с явным приведением: он стоит и в is null).
+        const v = `${p.push(c.v)}${sort.nullable ? sort.pcast || '::text' : sort.pcast}`;
+        const cols = [`${a}.id`, ...t.map((x) => x.col)];
+        const vals = [`${p.push(c.id)}::uuid`, ...t.map((x) => `${p.push(x.val)}${x.cast}`)];
+        if (!sort.nullable)
+            return `(${sort.expr(a)}, ${cols.join(', ')}) ${lt} (${v}, ${vals.join(', ')})`;
         const e = `(${sort.expr(a)})`;
-        const v = `${p.push(c.v)}${sort.pcast || '::text'}`;
-        const id = `${p.push(c.id)}::uuid`;
+        const rest = cols.length === 1 ? `${cols[0]} ${lt} ${vals[0]}` : `(${cols.join(', ')}) ${lt} (${vals.join(', ')})`;
         return mods.desc
-            ? `((${e}, ${a}.id) < (${v}, ${id}) or (${v} is null and (${e} is not null or ${a}.id < ${id})))`
-            : `((${e}, ${a}.id) > (${v}, ${id}) or (${e} is null and (${v} is not null or ${a}.id > ${id})))`;
+            ? `((${e}, ${cols.join(', ')}) < (${v}, ${vals.join(', ')}) or (${v} is null and (${e} is not null or ${rest})))`
+            : `((${e}, ${cols.join(', ')}) > (${v}, ${vals.join(', ')}) or (${e} is null and (${v} is not null or ${rest})))`;
     };
+    // ключи пути — в порядке шагов, узел последнего шага (его строки отдают rows()) — последним: по нему cursorOf(путь)
+    // берёт поле и id курсора, по прочим — разделители путей к одному узлу (план 2.0, 7.1 №3)
+    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, связанные колонкой moved (reclass, rekey), в обе стороны
-    if (mode === 'versions' && mods.follow) {
-        ctes.push(`f(id) as (select z.id from ${ents} z union select x.id from f cross join lateral (`
-            + `select l.moved as id from ${S}.log l where l.id = f.id and l.moved is not null `
-            + `union select l.id from ${S}.log l where l.moved = f.id) x)`);
-    }
-    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) {
         case 'paths': {
             const obj = keyed.map(({ key, node }) => `${lit(key)}::text, to_jsonb(h${node})`).join(', ');
             const h = `h${lastNode}`;
-            text = `${withClause}select jsonb_build_object(${obj}) as path ${from}${whereOf([...tail, after(h)])}${orderBy(h)}${limitOffset()}`;
+            const ties = (c) => {
+                const ids = cursorPath(c, others.map((k) => k.key));
+                return ids ? others.map((k, j) => ({ col: `h${k.node}.id`, val: ids[j], cast: '::uuid' })) : [];
+            };
+            text = `${withClause}select jsonb_build_object(${obj}) as path ${from}${whereOf([...tail, after(h, ties)])}`
+                + `${orderBy(h, others.map((k) => `h${k.node}.id`))}${limitOffset()}`;
             break;
         }
         case 'rows':
@@ -701,31 +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';
-            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 ${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 ${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`;
+            // без 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 = `${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') {
@@ -741,18 +836,16 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
             break;
         }
     }
-    return { text: text.replaceAll('@S@', S), params: p.list, keys: keyed.map((k) => k.key), aggLeaf };
+    return { text: text.replaceAll(SCHEMA_MARK, S), params: p.list, keys: pathKeys, aggLeaf };
 }
 /** Строка из 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;