letopis 1.4.2 → 3.0.0

package/dist/sql.js

@@ -17,15 +17,44 @@
  * Значения всегда уходят параметрами, поэтому текст запроса зависит только от формы цепочки: его
  * кэширует план (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';
+import { PG_UUID_RE, UUID_RE } from './uuid.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 +76,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 +132,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 });
 }
 // ---------------------------------------------------------------------------
 // Фильтры и операторы
@@ -116,12 +163,33 @@ function leafOf(reg, classes, path) {
     }
     return 'jsonb';
 }
-function compileOp(path, leaf, o, p) {
+/**
+ * Тип поля у классов шага не один (потомок переопределил тип: Base.price — число, Child.price — строка; у другой цели
+ * полиморфного конца поля нет или оно другого типа): приведение к типу листа должно быть безопасным — значение, которое
+ * к нему не приводится, сравнивается и сортируется как null, а не роняет весь запрос ошибкой приведения.
+ */
+function leafMixed(reg, classes, path, leaf) {
+    return !!CAST[leaf] && classes.some((c) => reg.leafType(c.name, path) !== leaf);
+}
+/** Имя типа для pg_input_is_valid по типу листа. */
+const PG_TYPE = {
+    text: 'text', jsonb: 'jsonb', numeric: 'numeric', boolean: 'boolean', timestamptz: 'timestamptz', date: 'date', uuid: 'uuid',
+};
+/**
+ * Значение поля, приведённое к типу листа (скобки обязательны: '::' сильнее '->>'). safe — тип поля в семействе
+ * разный (leafMixed): то, что не приводится, — null.
+ */
+function castLeaf(expr, leaf, safe) {
+    const cast = CAST[leaf];
+    if (!cast)
+        return expr;
+    return safe ? `(case when pg_input_is_valid(${expr}, ${lit(PG_TYPE[leaf])}) then (${expr})${cast} end)` : `(${expr})${cast}`;
+}
+function compileOp(path, leaf, o, p, safe = false) {
     const lhs = accessor(path);
     const cast = CAST[leaf];
     const pc = PCAST[leaf];
-    // скобки обязательны: '::' сильнее '->>'
-    const L = cast ? (a) => `(${lhs(a)})${cast}` : lhs;
+    const L = cast ? (a) => castLeaf(lhs(a), leaf, safe) : lhs;
     const args = o.args;
     switch (o[OP]) {
         case 'ne':
@@ -182,13 +250,13 @@ function compileOp(path, leaf, o, p) {
             return (a) => `${lhs(a)} is null`;
         case 'not': {
             if (isOp(args[0])) {
-                const inner = compileOp(path, leaf, args[0], p);
+                const inner = compileOp(path, leaf, args[0], p, safe);
                 return (a) => `not coalesce(${inner(a)}, false)`;
             }
-            return compileOp(path, leaf, { [OP]: 'ne', args: [args[0]] }, p);
+            return compileOp(path, leaf, { [OP]: 'ne', args: [args[0]] }, p, safe);
         }
         default:
-            return fail(`неизвестный оператор ${String(o[OP])}`);
+            throw lerr('query.unknown_op', { op: String(o[OP]) });
     }
 }
 /** Колонка tags: строка | список (все) | has / hasAny / hasAll. */
@@ -215,19 +283,31 @@ 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. */
 const idOfValue = (v) => typeof v === 'string' ? v : isPlain(v) && typeof v.id === 'string' ? v.id : undefined;
+/**
+ * id фильтра шага, `{ id }` или конца — uuid, который примет приведение базы (PG_UUID_RE): иначе invalid_query до запроса,
+ * а не сырая ошибка PostgreSQL 22P02 (у null — TypeError; план 2.1, A7).
+ */
+function idCheck(v, where) {
+    if (typeof v === 'string' && PG_UUID_RE.test(v))
+        return v;
+    throw lerr('query.bad_uuid', { where, value: shown(v) });
+}
 function compileFilter(reg, classes, filter, p) {
     const out = { ends: [], frags: [] };
     if (filter === undefined)
         return out;
+    const at = `${classes[0]?.name ?? ''}(…)`;
+    if (filter === null)
+        idCheck(filter, at);
     // 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)];
@@ -237,11 +317,11 @@ function compileFilter(reg, classes, filter, p) {
         return out;
     }
     if (typeof filter === 'string') {
-        out.ids = [filter];
+        out.ids = [idCheck(filter, at)];
         return out;
     }
     if (Array.isArray(filter)) {
-        out.ids = filter.map((x) => idOfValue(x) ?? fail('список id: ожидались строки'));
+        out.ids = filter.map((x) => idCheck(idOfValue(x) ?? refuse('query.id_list'), at));
         return out;
     }
     const props = (classes[0]?.schema.properties ?? {});
@@ -257,7 +337,8 @@ function compileFilter(reg, classes, filter, p) {
                 continue;
             const at = [...path, k];
             if (isOp(v)) {
-                out.frags.push(compileOp(at, leafOf(reg, classes, at), v, p));
+                const t = leafOf(reg, classes, at);
+                out.frags.push(compileOp(at, t, v, p, leafMixed(reg, classes, at, t)));
                 hadOps = true;
             }
             else if (isPlain(v)) {
@@ -278,12 +359,13 @@ function compileFilter(reg, classes, filter, p) {
         if (value === undefined)
             continue;
         if (key === 'id') {
+            const w = `${classes[0]?.name ?? ''}({ id })`;
             if (typeof value === 'string')
-                out.ids = [value];
+                out.ids = [idCheck(value, w)];
             else if (Array.isArray(value))
-                out.ids = value.map((x) => idOfValue(x) ?? fail('filter.id: ожидались строки'));
+                out.ids = value.map((x) => idCheck(idOfValue(x) ?? refuse('query.filter_id_list'), w));
             else
-                fail('filter.id принимает строку или список строк');
+                throw lerr('query.filter_id');
             continue;
         }
         if (isRole(key)) {
@@ -292,14 +374,17 @@ 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 = idCheck(idOfValue(value) ?? refuse('query.end_value', { role: key }), `${classes[0]?.name ?? ''}({ ${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));
+            const t = leafOf(reg, classes, [key]);
+            out.frags.push(compileOp([key], t, value, p, leafMixed(reg, classes, [key], t)));
             continue;
         }
         if (isPlain(value)) {
@@ -318,8 +403,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);
@@ -327,7 +416,7 @@ function asFrags(cf, p) {
     }
     return frags;
 }
-function sortSpec(order, leaf) {
+function sortSpec(order, leaf, mixed) {
     const f = order === 'updated' ? 'at' : order;
     const col = { field: order, nullable: false };
     if (f === 'at')
@@ -339,12 +428,16 @@ function sortSpec(order, leaf) {
     if (f.startsWith('data.')) {
         const path = f.slice(5).split('.');
         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 };
+        const safe = mixed(path, t);
+        return { expr: (a) => castLeaf(accessor(path)(a), t, safe), pcast: PCAST[t], field: order, type: t, nullable: true, safe };
     }
-    return fail(`sort: поле 'at', 'rev', 'id' или 'data.<путь>', а не '${order}'`);
+    // имя поля данных без префикса (sort('code')) — подсказка «data.code?»: принять его молча нельзя — колонки at, rev, id
+    // и поле данных с тем же именем разошлись бы, а курсор cursorOf(строка, 'code') — с ними
+    if (/^[\p{L}_$][\p{L}\p{N}_$]*(\.[\p{L}\p{N}_$]+)*$/u.test(order))
+        throw lerr('query.sort_field_data', { field: 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;
+/** Формы значений курсора — как у форматов uuid (UUID_RE, uuid.ts), date и date-time валидатора (validate.ts). */
 const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
 const TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d{1,6})?(?:Z|[+-](\d{2}):(\d{2}))$/;
 /** Дата (и время), которую примет приведение базы ::date / ::timestamptz: форма и смысл полей. */
@@ -398,9 +491,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 +504,18 @@ 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)}`);
-    const value = v === null && sort.nullable ? null : cursorValue(v, sort.type);
+        throw lerr('query.cursor_id', { id: shown(id) });
+    let value = v === null && sort.nullable ? null : cursorValue(v, sort.type);
+    // строка потомка с другим типом поля (курсор её значения) стоит среди null — как в castLeaf
+    if (value === undefined && sort.safe && v !== undefined && typeof v !== 'object')
+        value = null;
     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 +525,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 +536,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 +563,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 +573,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 +592,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 +610,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]}`;
@@ -547,7 +643,9 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         const dataP = lazy(() => (cf.eq ? `${p.push(cf.eq)}::jsonb` : 'null'));
         const endsP = lazy(() => (cf.ends.length ? `${p.push(cf.ends)}::uuid[]` : 'null'));
         const idsP = lazy(() => (cf.ids ? `${p.push(cf.ids)}::uuid[]` : 'null'));
-        const dead = mods.withDeleted === true && i === lastNode;
+        // надгробия узла: withDeleted() этого шага (план 2.1, A9) или versions() по явным id последнего шага — история
+        // удалённого объекта (план 2.1, A10)
+        const dead = step.withDeleted === true || (mode === 'versions' && i === lastNode && cf.ids !== undefined && step.deepMax === undefined);
         const dataCond = (v) => (cf.eq ? ` and ${v}.data @> ${dataP()}` : '');
         const endsCond = (col) => (cf.ends.length ? ` and ${col} @> ${endsP()}` : '');
         /** Версии журнала: последняя версия каждого id не позже момента. */
@@ -563,7 +661,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 +678,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 +699,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 +743,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)`);
             // пары переходов — по одной на (источник, цель): объект, который ссылается на несколько объектов прошлого шага,
@@ -665,15 +763,19 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         joins.push(`join p${i} on p${i}.src = h${a}.id join n${i} h${i} on h${i}.id = p${i}.id`);
     }
     // ключи шагов в путях
+    // повтор имени — суффикс _2, _3…, свободный среди всех уже выданных ключей: алиас x_2 и второй шаг x не
+    // совпадают (x, x_2, x → x, x_2, x_3), иначе узел терялся бы в jsonb_build_object
     const keyed = [];
-    const seen = new Map();
+    const used = new Set();
     steps.forEach((s, i) => {
         if (s.pivotKey !== undefined)
             return;
         const base = s.aliasKey ?? s.name;
-        const n = (seen.get(base) ?? 0) + 1;
-        seen.set(base, n);
-        keyed.push({ key: n === 1 ? base : `${base}_${n}`, node: i });
+        let key = base;
+        for (let n = 2; used.has(key); n++)
+            key = `${base}_${n}`;
+        used.add(key);
+        keyed.push({ key, node: i });
     });
     const from = `from n0 h0${joins.length ? ' ' + joins.join(' ') : ''}`;
     const whereOf = (conds) => {
@@ -686,7 +788,10 @@ 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);
-    const sort = mods.order ? sortSpec(mods.order, leaf) : undefined;
+    const mixed = (path, t) => leafMixed(reg, rowsNode(lastNode), path, t);
+    if (mods.order?.startsWith('data.'))
+        checkField(rowsNode(lastNode), topField(mods.order), `sort('${mods.order}')`, false);
+    const sort = mods.order ? sortSpec(mods.order, leaf, mixed) : undefined;
     const dir = mods.desc ? ' desc' : '';
     /** Порядок: поле sort, id строки и разделители равных (id прочих узлов пути). */
     const orderBy = (a, more = []) => (sort ? ` order by ${[sort.expr(a), `${a}.id`, ...more].map((x) => `${x}${dir}`).join(', ')}` : '');
@@ -700,7 +805,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 +829,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 +856,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') {
@@ -810,10 +879,11 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
                 text = `${withClause}select ${acc} as k, count(*)::int as n from ${ents} z group by 1 order by 2 desc, 1${limitOffset()}`;
             }
             else {
-                const cast = agg.fn === 'sum' || agg.fn === 'avg' ? '::numeric' : CAST[aggLeaf];
+                const t = agg.fn === 'sum' || agg.fn === 'avg' ? 'numeric' : aggLeaf;
                 // у boolean в PostgreSQL нет min и max; false меньше true: наименьшее — «все ли true», наибольшее — «есть ли true»
                 const fn = aggLeaf === 'boolean' && agg.fn === 'min' ? 'bool_and' : aggLeaf === 'boolean' && agg.fn === 'max' ? 'bool_or' : agg.fn;
-                text = `${withClause}select ${fn}((${acc})${cast}) as v from ${ents} z`;
+                // тип поля в семействе разный — значения, которые не приводятся к типу листа, агрегат пропускает (как null)
+                text = `${withClause}select ${fn}(${castLeaf(acc, t, aggLeaf === t && mixed(path, t))}) as v from ${ents} z`;
             }
             break;
         }
@@ -822,14 +892,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';
@@ -17,15 +17,21 @@ export interface SyncResult {
     unchanged: string[];
     /** Классы системного арендатора: их меняет только установка. */
     skipped: string[];
-    /** Правила refine, которых нет в базе. */
+    /** Правила refine, которых нет в базе (преобразования Zod syncModels отклоняет — model.transform_unsupported). */
     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;