letopis 1.4.2 → 3.0.0

package/dist/describe.js

@@ -0,0 +1,195 @@
+import { accepts } from './sql.js';
+const SYSTEM_CLASSES = new Set(['Class', 'Account', 'member', 'Resource', 'rule']);
+// ---------------------------------------------------------------------------
+// Примеры цепочек (план 2.0, этап 3, п. 7): из реестра — ключ, обязательные поля, концы
+// ---------------------------------------------------------------------------
+/** Ключ объекта без кавычек: буквы, цифры, _ и $, не с цифры (имена классов и ролей такие всегда — метасхема Class). */
+const BARE_KEY = /^[A-Za-zА-Яа-яЁё_$][A-Za-zА-Яа-яЁё0-9_$]*$/;
+const ESCAPES = { '\\': '\\\\', "'": "\\'", '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+/** Значение JSON литералом TypeScript, как в README: строки в одинарных кавычках с экранированием, ключи без кавычек, где можно. */
+function lit(v) {
+    if (typeof v === 'string') {
+        return `'${v.replace(/[\\'\u0000-\u001f\u2028\u2029]/g, (ch) => ESCAPES[ch] ?? `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`)}'`;
+    }
+    if (Array.isArray(v))
+        return `[${v.map(lit).join(', ')}]`;
+    if (v !== null && typeof v === 'object') {
+        const entries = Object.entries(v);
+        return entries.length ? `{ ${entries.map(([k, x]) => `${BARE_KEY.test(k) ? k : lit(k)}: ${lit(x)}`).join(', ')} }` : '{}';
+    }
+    return typeof v === 'number' && !Number.isFinite(v) ? '0' : String(v);
+}
+/** Место для id объекта класса конца: '<id Org>', у полиморфного конца — '<id Service|Product>'. */
+const idPlace = (cls) => `<id ${(Array.isArray(cls) ? cls : [cls]).join('|')}>`;
+const isSchema = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const hasDefault = (v) => isSchema(v) && 'default' in v;
+const SAMPLE_DATE = '2026-01-01';
+/** Образцы строк с форматом — первый, что проходит pattern поля (у z.iso.datetime он задаёт знаки после запятой и пояс). */
+const FORMAT_SAMPLES = {
+    'date-time': ['.000Z', 'Z', '.000000Z', '.0Z', '.00Z', '+00:00', '.000+00:00'].map((tail) => `${SAMPLE_DATE}T00:00:00${tail}`),
+    date: [SAMPLE_DATE],
+    email: ['user@example.com'],
+    uuid: ['00000000-0000-4000-8000-000000000000'],
+};
+/** Строка: образец формата или имя поля — с учётом minLength, maxLength и pattern. */
+function stringSample(s, name) {
+    // описание класса задаёт арендатор, а описание модели получает агент через MCP: длина образца ограничена (minLength в
+    // миллиард не выделит гигабайтную строку), а свой pattern здесь не исполняется вовсе — шаблон с катастрофическим
+    // перебором повесил бы процесс и на коротком образце (ревью безопасности коммитов 2e5e6bc, 1e80cf1). Поле с pattern
+    // без examples может получить образец, который проверку не пройдёт, — это оговорено в README
+    const SAMPLE = 16;
+    const min = typeof s.minLength === 'number' ? Math.min(Math.max(0, s.minLength), SAMPLE) : 0;
+    const max = typeof s.maxLength === 'number' ? Math.max(0, s.maxLength) : Infinity;
+    const fit = (x) => (x.length < min ? x.padEnd(min, 'x') : x).slice(0, Math.min(max, SAMPLE * 4));
+    return fit((FORMAT_SAMPLES[s.format] ?? [name || 'x'])[0]);
+}
+/** Число: 1 в пределах minimum, maximum (и исключающих) и кратное multipleOf; integer — целое. */
+function numberSample(s, integer) {
+    const num = (k) => (typeof s[k] === 'number' ? s[k] : undefined);
+    const step = num('multipleOf') ?? (integer ? 1 : undefined);
+    const [min, xmin, max, xmax] = [num('minimum'), num('exclusiveMinimum'), num('maximum'), num('exclusiveMaximum')];
+    let v = 1;
+    if (min !== undefined && v < min)
+        v = min;
+    if (xmin !== undefined && v <= xmin)
+        v = xmin + (step ?? 1);
+    if (max !== undefined && v > max)
+        v = max;
+    if (xmax !== undefined && v >= xmax)
+        v = xmax - (step ?? 1);
+    return step ? Math.ceil(v / step) * step : v;
+}
+/** Поля объекта, которые надо передать: обязательные без умолчания (умолчание подставит база), в порядке описания. */
+function neededFields(s, extra = []) {
+    const props = isSchema(s.properties) ? s.properties : {};
+    const need = new Set([...(Array.isArray(s.required) ? s.required : []), ...extra]);
+    return [...new Set([...Object.keys(props), ...need])].filter((k) => need.has(k) && !hasDefault(props[k]));
+}
+/**
+ * Образец значения по JSON Schema: examples[0], const, default, первое из enum, первая ветка anyOf или oneOf, иначе по
+ * типу — строка, число, true, массив из minItems образцов, объект из обязательных полей.
+ */
+function sample(s, name, depth = 0) {
+    if (!isSchema(s))
+        return name;
+    if (Array.isArray(s.examples) && s.examples.length)
+        return s.examples[0];
+    if ('const' in s)
+        return s.const;
+    if ('default' in s)
+        return s.default;
+    if (Array.isArray(s.enum) && s.enum.length)
+        return s.enum[0];
+    const branch = Array.isArray(s.anyOf) ? s.anyOf[0] : Array.isArray(s.oneOf) ? s.oneOf[0] : undefined;
+    if (isSchema(branch)) {
+        const { anyOf: _a, oneOf: _o, ...rest } = s;
+        return sample({ ...rest, ...branch }, name, depth);
+    }
+    const types = (Array.isArray(s.type) ? s.type : typeof s.type === 'string' ? [s.type] : []);
+    const type = types.find((x) => x !== 'null') ?? (types.length ? 'null' : isSchema(s.properties) ? 'object' : s.items ? 'array' : 'string');
+    if (depth > 8 && (type === 'object' || type === 'array'))
+        return type === 'object' ? {} : [];
+    switch (type) {
+        case 'null': return null;
+        case 'boolean': return true;
+        case 'integer':
+        case 'number': return numberSample(s, type === 'integer');
+        case 'array': return Array.from({ length: Math.min(typeof s.minItems === 'number' ? s.minItems : 0, 3) }, () => sample(s.items, name, depth + 1));
+        case 'object': {
+            const props = isSchema(s.properties) ? s.properties : {};
+            return Object.fromEntries(neededFields(s).map((k) => [k, sample(props[k] ?? s.additionalProperties, k, depth + 1)]));
+        }
+        default: return stringSample(s, name);
+    }
+}
+/** Класс, строки которого цепочкой не создают: абстрактный, системный или его потомок. */
+const notCreatable = (c) => c.abstract || c.ancestors.some((n) => SYSTEM_CLASSES.has(n));
+/** Данные create: поля ключа, обязательные поля без умолчания и поля первой ветки условий anyOf и oneOf. */
+function createData(c) {
+    const s = c.schema;
+    const props = isSchema(s.properties) ? s.properties : {};
+    const conds = [s.anyOf, s.oneOf].map((x) => (Array.isArray(x) ? x[0] : undefined));
+    const extra = conds.flatMap((x) => (isSchema(x) && Array.isArray(x.required) ? x.required : []));
+    const keyFields = c.key.filter((k) => !c.ends[k]);
+    const fields = [...new Set([...neededFields(s, extra), ...keyFields])];
+    return Object.fromEntries(fields.map((k) => [k, sample(props[k], k)]));
+}
+/** «Создать»: данные и слоты обязательных концов и концов ключа; у множественного конца с min — столько разных id. */
+function createExample(c) {
+    if (notCreatable(c))
+        return undefined;
+    let chain = `db.${c.name}().create(${lit(createData(c))})`;
+    for (const [role, e] of Object.entries(c.ends)) {
+        const min = e.min ?? 0;
+        if (!e.required && min === 0 && !c.key.includes(role))
+            continue;
+        const place = idPlace(e.class);
+        if (!e.many)
+            chain += `.${role}.set(${lit(place)})`;
+        else
+            chain += `.${role}.add(${lit(min > 1 ? Array.from({ length: min }, (_, i) => `${place.slice(0, -1)} #${i + 1}>`) : place)})`;
+    }
+    return `${chain}.rows()`;
+}
+/** «Найти»: по ключу (поля — те же образцы, что у create; концы — id) или по первому обязательному простому полю. */
+function findExample(c) {
+    const props = isSchema(c.schema.properties) ? c.schema.properties : {};
+    if (c.key.length) {
+        const filter = Object.fromEntries(c.key.map((k) => [k, c.ends[k] ? idPlace(c.ends[k].class) : sample(props[k], k)]));
+        return `db.${c.name}(${lit(filter)}).first()`;
+    }
+    const required = Array.isArray(c.schema.required) ? c.schema.required : [];
+    const simple = (v) => ['string', 'number', 'boolean'].includes(typeof v);
+    const field = Object.keys(props).find((k) => required.includes(k) && simple(sample(props[k], k)));
+    if (field)
+        return `db.${c.name}(${lit({ [field]: sample(props[field], field) })}).rows()`;
+    const end = Object.entries(c.ends).find(([, e]) => e.required && !e.many);
+    return end ? `db.${c.name}(${lit({ [end[0]]: idPlace(end[1].class) })}).rows()` : `db.${c.name}().rows()`;
+}
+/**
+ * «Перейти к соседям»: вперёд по каждому концу класса (шаг-роль; если так зовут класс или алиас, которого конец не
+ * принимает, — шаг по классу цели) и назад к классам, чьи концы принимают этот класс (у наследника, получившего конец
+ * от предка, — только предок: шаг к нему находит и наследников).
+ */
+function neighborExamples(reg, c, all) {
+    const list = (v) => (Array.isArray(v) ? v : [v]);
+    const steps = Object.entries(c.ends).map(([role, e]) => {
+        const named = reg.find(role);
+        return !named || accepts(reg, list(e.class), named.name) ? role : list(e.class)[0];
+    });
+    const back = all.filter((o) => Object.entries(o.ends).some(([role, e]) => accepts(reg, list(e.class), c.name) && !reg.find(o.ancestors[1] ?? '')?.ends[role]));
+    steps.push(...back.map((o) => o.name).sort((x, y) => x.localeCompare(y)));
+    return [...new Set(steps)].map((step) => `db.${c.name}(${lit(idPlace(c.name))}).${step}().rows()`);
+}
+function examplesOf(reg, c, all) {
+    const create = createExample(c);
+    return { ...(create ? { create } : {}), find: findExample(c), neighbors: neighborExamples(reg, c, all) };
+}
+/**
+ * Описание модели арендатора вместе с метаданными классов (этап 6, п. 12) и примерами цепочек (план 2.0, этап 3, п. 7):
+ * reg — реестр подключения (классы арендатора сессии и System), schema и tenant — схема установки и арендатор сессии.
+ */
+export function describeModel(reg, schema, tenant) {
+    const all = reg.all();
+    const classes = all.map((c) => ({
+        name: c.name,
+        kind: c.kind,
+        ...(c.alias ? { alias: c.alias } : {}),
+        abstract: c.abstract,
+        ...(c.ancestors[1] ? { parent: c.ancestors[1] } : {}),
+        ancestors: c.ancestors,
+        system: SYSTEM_CLASSES.has(c.name),
+        fields: (c.schema.properties ?? {}),
+        required: (c.schema.required ?? []),
+        ...(Array.isArray(c.schema.anyOf) ? { anyOf: c.schema.anyOf } : {}),
+        ...(Array.isArray(c.schema.oneOf) ? { oneOf: c.schema.oneOf } : {}),
+        ends: c.ends,
+        key: c.key,
+        history: c.history,
+        ownerDefault: c.ownerDefault,
+        ...(c.cache ? { cache: c.cache } : {}),
+        meta: c.meta,
+        examples: examplesOf(reg, c, all),
+    })).sort((x, y) => Number(x.system) - Number(y.system) || x.name.localeCompare(y.name));
+    return { schema, tenant, classes };
+}

package/dist/errors.d.ts

@@ -1,29 +1,93 @@
-/**
- * Ошибки letopis 1.0 (план, §7.1, этап 2, п. 10). Текст — «letopis: <код>: <сообщение>», как у ошибок
- * базы; код — имя из каталога (`error_catalog()` в lib/sql/15-errors.sql) или код самой библиотеки.
- */
+import { type MsgKey, type Params } from './messages/index.js';
+export type { MsgKey, Params } from './messages/index.js';
 /** Нарушение правила данных: путь, ключевое слово JSON Schema, сообщение. Один формат для Zod, валидатора и базы. */
 export interface Issue {
     path: (string | number)[];
     keyword: string;
     message: string;
 }
+/** Текст записи каталога с параметрами (params.similar — «— похожие: …»): сообщения нарушений, описания, отчёты CLI. */
+export declare function lmsg(key: MsgKey, params?: Params): string;
+/** Логгер, в который уходит предупреждение (lib/src/log.ts, Log): только то, что нужно lwarn. */
+interface WarnSink {
+    readonly active: boolean;
+    warning(key: string | undefined, msg: string, detail?: Record<string, unknown>): void;
+}
+export declare function setEnvWarnSink(fn: () => WarnSink): void;
+/**
+ * Предупреждение по записи каталога — «letopis: <текст>» в console.warn; once — ключ «один раз на процесс». Неизвестное
+ * поле фильтра, sort() и агрегата с 2.0 — уже не предупреждение, а отказ query.unknown_field (sql.ts, checkField).
+ * Логирование 3.0: задан логгер (opts.log подключения или LETOPIS_LOG) — событие warning в него вместо console.warn.
+ */
+export declare function lwarn(key: MsgKey, params?: Params, opts?: {
+    once?: string;
+    log?: WarnSink;
+}): void;
+/**
+ * Готовый текст предупреждения: в логгер (событие warning с ключом и параметрами), если он задан, иначе console.warn.
+ * Ошибка логгера предупреждение не теряет и операцию не прерывает.
+ */
+export declare function warnText(text: string, key?: string, log?: WarnSink, params?: Params): void;
 export declare class LetopisError extends Error {
     readonly code: string;
     readonly detail: unknown;
-    constructor(code: string, message: string, detail?: unknown);
+    /** Ключ каталога сообщений: у ошибок lerr и у ошибок базы с ключом в DETAIL; у ошибок без ключа — нет. */
+    readonly key?: string;
+    /** Параметры шаблона ключа (similar — похожие имена). */
+    readonly params?: Params;
+    /** Что делать: своя подсказка записи каталога или подсказка кода. */
+    readonly hint?: string;
+    /** Строка кода в разделе «Ошибки» README на GitHub по тегу версии пакета. */
+    readonly docs?: string;
+    constructor(code: string, message: string, detail?: unknown, msg?: {
+        key: string;
+        params?: Params;
+    });
 }
-/** Версия, в которой снято старое API (её берёт и контракт API — scripts/gen-api-contract.mjs). */
-export declare const REMOVED_IN = "1.0.0";
-/** Охранник снесённого API (план, этап 3, п. 11): понятная ошибка с версией и заменой. */
-export declare function removed(name: string, replacement: string): LetopisError;
-/** Данные не проходят описание класса (`invalid_data`). */
+/**
+ * Ошибка по ключу каталога: код — из записи, текст — шаблон с параметрами (params.similar — похожие имена дописываются
+ * сами); extra.detail — подробности (`err.detail`), extra.cause — исходная ошибка.
+ */
+export declare function lerr(key: MsgKey, params?: Params, extra?: {
+    detail?: unknown;
+    cause?: unknown;
+}): LetopisError;
+/** Похожие имена: до пяти ближайших по Левенштейну (без учёта регистра) или содержащих искомое. */
+export declare function similar(name: string, candidates: Iterable<string>, n?: number): string[];
+/**
+ * Неизвестный ключ опций — invalid_data с похожими именами (план 2.0, этап 4, п. 2; 7.10 №4; в 1.5 было предупреждение,
+ * 7.9 №6). known — все ключи опций: объект `satisfies Record<keyof Опции, true>`, пропуск ключа — ошибка типов.
+ */
+export declare function checkOptions(where: string, opts: unknown, known: Readonly<Record<string, true>>): void;
+/**
+ * Первое нарушение для текста ошибки (план 2.1, A8): «: <путь> — <сообщение>», при нескольких — ещё их число. Полный
+ * список — err.issues.
+ */
+export declare function issuesSuffix(issues: readonly Issue[]): string;
+/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed) и первое нарушение. */
 export declare class ValidationError extends LetopisError {
     readonly issues: Issue[];
-    constructor(cls: string, issues: Issue[]);
+    constructor(cls: string, issues: Issue[], msg?: {
+        key: string;
+        params?: Params;
+    });
 }
 /**
- * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL
- * (JSON) переносятся в detail; прочие ошибки возвращаются как есть.
+ * Нарушения из базы (validate_data, inc): у нарушения базы ещё key и params, наружу они не идут — форма та же,
+ * { path, keyword, message }, message — текст, который собрала база. Нарушение без ключа (схема прежней сборки) — как
+ * есть.
+ */
+export declare function issuesFromDb(issues: unknown): Issue[];
+/**
+ * Строки отказа ужесточения из базы (detail.rows от family_conflicts): у строки ещё key и params, наружу они не идут
+ * (problem — текст базы), у нарушений в поле issues — тоже. Строка без ключа — как есть.
+ */
+export declare function findingsFromDb<T>(rows: readonly T[]): T[];
+/**
+ * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL (JSON) переносятся в
+ * detail; ключ каталога и параметры из DETAIL (lt_fail(ключ, …)) — в key и params, текст — тот, что база собрала по ним
+ * из русского шаблона; без ключа — текст базы. У нарушений (issues) и строк отказа (detail.rows) key и params наружу не
+ * идут. Внутренняя ошибка базы (XX000) с ключом в DETAIL — код internal. Повторяемый конфликт (40001, 40P01) и прочие
+ * ошибки возвращаются как есть: на SQLSTATE конфликта держатся повторы (tx.ts).
  */
 export declare function fromDbError(e: unknown): unknown;

package/dist/errors.js

@@ -1,30 +1,166 @@
 /**
  * Ошибки letopis 1.0 (план, §7.1, этап 2, п. 10). Текст — «letopis: <код>: <сообщение>», как у ошибок
  * базы; код — имя из каталога (`error_catalog()` в lib/sql/15-errors.sql) или код самой библиотеки.
+ *
+ * Каталог сообщений (план 2.0, этап 3, п. 3; lib/src/messages): ошибка по ключу — `lerr(ключ, параметры)`, текст —
+ * шаблон записи с параметрами. У каждой ошибки — подсказка «что делать» (`hint`) и ссылка на строку её кода в разделе
+ * «Ошибки» README на GitHub по тегу версии (`docs`). База собирает текст по ключу и параметрам из того же шаблона и
+ * кладёт их в DETAIL (`lt_fail(ключ, …)`), а fromDbError переносит их в поля ошибки (`key`, `params`); без ключа —
+ * текст базы как есть. У нарушений (validate_data) и строк отказа ужесточения key и params наружу не идут: issuesFromDb,
+ * findingsFromDb.
  */
+import { createRequire } from 'node:module';
+import { SIMILAR, codeOf, msgOf, render } from './messages/index.js';
+const VERSION = createRequire(import.meta.url)('../package.json').version;
+/** Раздел «Ошибки» README по тегу версии пакета; якорь — сам код (`<a id="код"></a>` в строке таблицы). */
+const DOCS = `https://github.com/alepri51/letopis/blob/v${VERSION}/lib/README.md`;
+// ---------------------------------------------------------------------------
+// Тексты и ошибки по каталогу
+// ---------------------------------------------------------------------------
+function textOf(key, params) {
+    const m = msgOf(key);
+    if (!m)
+        return key;
+    const s = render(m.ru, params);
+    const sim = params?.similar;
+    return Array.isArray(sim) && sim.length ? s + render(SIMILAR, { similar: sim.join(', ') }) : s;
+}
+/** Текст записи каталога с параметрами (params.similar — «— похожие: …»): сообщения нарушений, описания, отчёты CLI. */
+export function lmsg(key, params) {
+    return textOf(key, params);
+}
+const warned = new Set();
+/** Логгер по LETOPIS_LOG для предупреждений без подключения — ставит log.ts (без цикла импорта значений). */
+let envSink = null;
+export function setEnvWarnSink(fn) {
+    envSink = fn;
+}
+/**
+ * Предупреждение по записи каталога — «letopis: <текст>» в console.warn; once — ключ «один раз на процесс». Неизвестное
+ * поле фильтра, sort() и агрегата с 2.0 — уже не предупреждение, а отказ query.unknown_field (sql.ts, checkField).
+ * Логирование 3.0: задан логгер (opts.log подключения или LETOPIS_LOG) — событие warning в него вместо console.warn.
+ */
+export function lwarn(key, params, opts = {}) {
+    if (opts.once !== undefined) {
+        if (warned.has(opts.once))
+            return;
+        if (warned.size >= 1000)
+            warned.clear();
+        warned.add(opts.once);
+    }
+    warnText(`letopis: ${textOf(key, params)}`, key, opts.log, params);
+}
+/**
+ * Готовый текст предупреждения: в логгер (событие warning с ключом и параметрами), если он задан, иначе console.warn.
+ * Ошибка логгера предупреждение не теряет и операцию не прерывает.
+ */
+export function warnText(text, key, log, params) {
+    const sink = log?.active ? log : envSink?.();
+    if (sink?.active) {
+        try {
+            sink.warning(key, text, params && Object.keys(params).length ? { ...params } : undefined);
+            return;
+        }
+        catch {
+            // логгер не принял — как без него
+        }
+    }
+    console.warn(text);
+}
 export class LetopisError extends Error {
     code;
     detail;
-    constructor(code, message, detail) {
+    constructor(code, message, detail, msg) {
         super(`letopis: ${code}: ${message}`);
         this.name = 'LetopisError';
         this.code = code;
         this.detail = detail;
+        const self = this;
+        if (msg) {
+            self.key = msg.key;
+            self.params = msg.params ?? {};
+        }
+        const sign = codeOf(code);
+        const hint = (msg ? msgOf(msg.key)?.hint : undefined) ?? sign?.hint;
+        if (hint)
+            self.hint = hint;
+        if (sign)
+            self.docs = `${DOCS}#${code}`;
+    }
+}
+/**
+ * Ошибка по ключу каталога: код — из записи, текст — шаблон с параметрами (params.similar — похожие имена дописываются
+ * сами); extra.detail — подробности (`err.detail`), extra.cause — исходная ошибка.
+ */
+export function lerr(key, params, extra) {
+    const e = new LetopisError(msgOf(key)?.code ?? 'invalid_query', lmsg(key, params), extra?.detail, { key, ...(params ? { params } : {}) });
+    return extra && 'cause' in extra ? Object.assign(e, { cause: extra.cause }) : e;
+}
+// ---------------------------------------------------------------------------
+// Похожие имена (общие: цепочки, фильтры, опции, MCP)
+// ---------------------------------------------------------------------------
+/** Расстояние Левенштейна (вставка, удаление, замена). */
+function distance(a, b) {
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++)
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        prev = cur;
+    }
+    return prev[b.length];
+}
+/** Похожие имена: до пяти ближайших по Левенштейну (без учёта регистра) или содержащих искомое. */
+export function similar(name, candidates, n = 5) {
+    if (name.length > 64)
+        return [];
+    const want = name.toLowerCase();
+    const max = Math.max(2, Math.ceil(want.length / 3));
+    const scored = [];
+    for (const x of new Set(candidates)) {
+        if (x === name)
+            continue;
+        const low = x.toLowerCase();
+        const d = distance(want, low);
+        if (d <= max || (want.length >= 3 && low.includes(want)))
+            scored.push({ x, d });
+    }
+    return scored.sort((p, q) => p.d - q.d || (p.x < q.x ? -1 : p.x > q.x ? 1 : 0)).slice(0, n).map((s) => s.x);
+}
+/**
+ * Неизвестный ключ опций — invalid_data с похожими именами (план 2.0, этап 4, п. 2; 7.10 №4; в 1.5 было предупреждение,
+ * 7.9 №6). known — все ключи опций: объект `satisfies Record<keyof Опции, true>`, пропуск ключа — ошибка типов.
+ */
+export function checkOptions(where, opts, known) {
+    if (!opts || typeof opts !== 'object')
+        return;
+    for (const k of Object.keys(opts)) {
+        if (!Object.hasOwn(known, k))
+            throw lerr('api.unknown_option', { where, name: k, similar: similar(k, Object.keys(known)) });
     }
 }
-/** Версия, в которой снято старое API (её берёт и контракт API — scripts/gen-api-contract.mjs). */
-export const REMOVED_IN = '1.0.0';
-/** Охранник снесённого API (план, этап 3, п. 11): понятная ошибка с версией и заменой. */
-export function removed(name, replacement) {
-    // «опция …» — женского рода; методы и свойства — мужского
-    const verb = name.startsWith('опция ') ? 'снята' : / и /.test(name) ? 'сняты' : 'снят';
-    return new LetopisError('removed', `${name} ${verb} в ${REMOVED_IN} — ${replacement}`);
+/**
+ * Первое нарушение для текста ошибки (план 2.1, A8): «: <путь> — <сообщение>», при нескольких — ещё их число. Полный
+ * список — err.issues.
+ */
+export function issuesSuffix(issues) {
+    const first = issues[0];
+    if (!first)
+        return '';
+    const path = Array.isArray(first.path) && first.path.length ? first.path.join('.') : textOf('api.validation_root', undefined);
+    const more = issues.length > 1 ? textOf('api.validation_more', { n: issues.length }) : '';
+    return `: ${textOf('api.validation_issue', { path, issue: first.message })}${more}`;
 }
-/** Данные не проходят описание класса (`invalid_data`). */
+/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed) и первое нарушение. */
 export class ValidationError extends LetopisError {
     issues;
-    constructor(cls, issues) {
-        super('invalid_data', `данные не проходят описание класса ${cls}`, { issues });
+    constructor(cls, issues, msg) {
+        const m = msg ?? { key: 'api.validation_failed', params: { cls } };
+        super('invalid_data', textOf(m.key, m.params) + issuesSuffix(issues), { issues }, m);
         this.name = 'ValidationError';
         this.issues = issues;
     }
@@ -33,14 +169,55 @@ export class ValidationError extends LetopisError {
 const LT_NAMES = {
     LT001: 'no_session', LT002: 'target_not_found', LT003: 'invalid_data', LT004: 'undeclared_end', LT005: 'tenant_denied',
     LT006: 'acl_denied', LT007: 'id_mismatch', LT008: 'id_from_db', LT009: 'immutable_key', LT010: 'invalid_class',
-    LT011: 'use_reclass', LT012: 'reclass_denied', LT013: 'tightening_conflict', LT014: 'isolation_level',
-    LT015: 'recreated_in_statement', LT016: 'cursor_expired', LT017: 'delete_restricted', LT018: 'not_deleted',
-    LT019: 'reset_disabled', LT020: 'confirm_mismatch', LT021: 'derived_class', LT022: 'aggregate_field',
-    LT023: 'projector_pending',
+    LT013: 'tightening_conflict', LT014: 'isolation_level',
+    LT015: 'recreated_in_statement', LT017: 'delete_restricted', LT018: 'not_deleted',
 };
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Нарушения из базы (validate_data, inc): у нарушения базы ещё key и params, наружу они не идут — форма та же,
+ * { path, keyword, message }, message — текст, который собрала база. Нарушение без ключа (схема прежней сборки) — как
+ * есть.
+ */
+export function issuesFromDb(issues) {
+    if (!Array.isArray(issues))
+        return issues;
+    return issues.map((i) => {
+        if (!isObj(i) || typeof i.key !== 'string')
+            return i;
+        const { key: _key, params: _params, ...rest } = i;
+        rest.message = String(rest.message ?? '');
+        return rest;
+    });
+}
 /**
- * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL
- * (JSON) переносятся в detail; прочие ошибки возвращаются как есть.
+ * Строки отказа ужесточения из базы (detail.rows от family_conflicts): у строки ещё key и params, наружу они не идут
+ * (problem — текст базы), у нарушений в поле issues — тоже. Строка без ключа — как есть.
+ */
+export function findingsFromDb(rows) {
+    return rows.map((r) => {
+        if (!isObj(r) || typeof r.key !== 'string')
+            return r;
+        const { key: _key, params: _params, ...rest } = r;
+        if (Array.isArray(rest.issues))
+            rest.issues = issuesFromDb(rest.issues);
+        return rest;
+    });
+}
+/** DETAIL ошибки базы: JSON — разобранный, иначе строка как есть. */
+function parseDetail(detail) {
+    try {
+        return detail ? JSON.parse(detail) : undefined;
+    }
+    catch {
+        return detail;
+    }
+}
+/**
+ * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL (JSON) переносятся в
+ * detail; ключ каталога и параметры из DETAIL (lt_fail(ключ, …)) — в key и params, текст — тот, что база собрала по ним
+ * из русского шаблона; без ключа — текст базы. У нарушений (issues) и строк отказа (detail.rows) key и params наружу не
+ * идут. Внутренняя ошибка базы (XX000) с ключом в DETAIL — код internal. Повторяемый конфликт (40001, 40P01) и прочие
+ * ошибки возвращаются как есть: на SQLSTATE конфликта держатся повторы (tx.ts).
  */
 export function fromDbError(e) {
     const err = e;
@@ -48,25 +225,49 @@ export function fromDbError(e) {
     // которому существующую строку менять нельзя («USING expression»), остаётся 42501 (§2.5). Признак —
     // функция сервера, а не текст: текст зависит от языка сервера
     if (err.code === '42501' && err.routine === 'ExecWithCheckOptions' && !/USING/.test(err.message ?? '')) {
-        return Object.assign(new LetopisError('acl_denied', 'новые значения строки запрещают правила доступа'), { cause: e });
+        return lerr('api.row_check_denied', undefined, { cause: e });
     }
-    const name = err.code ? LT_NAMES[err.code] : undefined;
-    if (!name)
-        return e;
+    // значение не того типа (22P02: «invalid input syntax for type uuid» и т. п.), которое не поймала проверка до запроса,
+    // — ошибка letopis, а не сырая ошибка PostgreSQL (план 2.1, A7); 40001 и 40P01 остаются как есть — на них держатся повторы
+    if (err.code === '22P02')
+        return lerr('api.db_bad_value', { text: err.message ?? '' }, { cause: e });
+    let name;
     let detail;
-    try {
-        detail = err.detail ? JSON.parse(err.detail) : undefined;
+    if (err.code === 'XX000') {
+        // своя внутренняя ошибка — lt_raise('XX000', ключ, …): ключ каталога в DETAIL; голые XX000 самого PostgreSQL («tuple
+        // concurrently updated» и т. п.) — как есть
+        detail = parseDetail(err.detail);
+        if (isObj(detail) && typeof detail.key === 'string')
+            name = 'internal';
     }
-    catch {
-        detail = err.detail;
+    else if (err.code) {
+        name = LT_NAMES[err.code];
+        if (name)
+            detail = parseDetail(err.detail);
+    }
+    if (!name)
+        return e;
+    // ключ каталога (план 2.0, этап 3, п. 3): в detail остаются прежние поля, а ключ и параметры — в key и params
+    let msg;
+    if (isObj(detail) && typeof detail.key === 'string') {
+        const { key, params, nodetail, ...rest } = detail;
+        msg = { key: key, params: isObj(params) ? params : {} };
+        // detail — как до каталога: прежние поля, {} в том числе (lt_fail без detail давала {}); признак nodetail — DETAIL у
+        // места не было (raise без detail), и detail нет. Сам признак наружу не идёт
+        detail = nodetail === true ? undefined : rest;
     }
+    // текст база собрала по ключу и параметрам из того же русского шаблона — он остаётся как есть
     const text = (err.message ?? '').replace(/^letopis: [a-z_]+: /, '');
+    // строки отказа с находками (ужесточение: problem по ключу) — без key и params
+    if (isObj(detail) && Array.isArray(detail.rows))
+        detail = { ...detail, rows: findingsFromDb(detail.rows) };
     const issues = detail?.issues;
     if (name === 'invalid_data' && Array.isArray(issues)) {
-        const cls = /класса (\S+)/.exec(text)?.[1] ?? '?';
-        const v = new ValidationError(cls, issues);
-        // текст базы целиком: в нём бывает больше, чем имя класса (у проектора — арендатор и id строки)
-        return Object.assign(v, { cause: e, ...(text ? { message: `letopis: invalid_data: ${text}` } : {}) });
+        const cls = msg ? String(msg.params.cls ?? '?') : /класса (\S+)/.exec(text)?.[1] ?? '?';
+        const list = issuesFromDb(issues);
+        const v = new ValidationError(cls, list, msg);
+        // текст — тот, что собрала база по шаблону записи, и первое нарушение (план 2.1, A8)
+        return Object.assign(v, { cause: e, ...(text ? { message: `letopis: invalid_data: ${text}${issuesSuffix(list)}` } : {}) });
     }
-    return Object.assign(new LetopisError(name, text, detail), { cause: e });
+    return Object.assign(new LetopisError(name, text, detail, msg), { cause: e });
 }