letopis 1.4.1 → 2.0.0

package/llms.txt

@@ -1,33 +1,30 @@
 # letopis
 
-> Versioned entity store for Node.js on PostgreSQL 18. Every change is a version in a journal (history, reads as of a date, cursor subscriptions). Integrity, tenant isolation and access rules are enforced by the database itself (triggers and row-level security), so they hold for raw SQL too. Data is read and written with chains like `db.Shop(shop).Product().rows()`.
+> Хранилище версионированных объектов для Node.js на PostgreSQL 18. Каждое изменение — версия в журнале (история, чтение на момент, подписка по курсору). Целостность, изоляцию арендаторов и права доступа проверяет сама база (триггеры и политики RLS), поэтому они действуют и для сырого SQL. Данные читают и пишут цепочками вида `db.Shop(shop).Product().rows()`.
 
-Key facts for writing code with letopis 1.4:
+Главное для кода на letopis:
 
-- ESM package, Node 22+, PostgreSQL 18+ with pgcrypto, database encoding UTF8. Runtime dependency: `postgres`. Zod 4 is an optional peer dependency needed only by `letopis/model`; `@modelcontextprotocol/server`, only by `letopis/mcp`.
-- Install a schema with `up({ dsn, schema })` from an admin role; the schema is named `v2.<name>`. The application connects with a LOGIN role that is a member of `letopis_app`: `connect({ dsn, schema: 'v2.<name>', token | apiKey })`. A role that bypasses RLS is refused (`bypass_rls`) unless `allowBypassRls: true`.
-- Classes are hubs (objects) and links (relations with ends), described with `hub()`/`link()` from `letopis/model` and written to the database with `syncModels()` or `letopis sync`. A class with a key gets a deterministic UUID v5 id (`db.idOf`); uniqueness is the key.
-- Verbs return a chain; a terminal (`rows`, `first`, `ids`, `count`, …) executes the whole plan in one transaction. `create` only creates (a taken key is `exists`), `update` merges and never creates, `upsert` replaces the whole object (keyed classes only), `delete()` is a preview and `delete({ confirm: true })` deletes.
-- Money and counters: `update({ balance: inc(n) })` adds inside the statement; `update(patch, { rev })` fails with `conflict` if the row changed; `forUpdate()` locks rows inside `db.begin()`.
-- History: `versions()`, `diff({ from, to })` and `blame()` (who, when and why last changed each field); verbs, `db.begin()` and `db.batch()` take `{ reason }`.
-- Bulk loading from an admin connection: `db.load(rows)`; into an empty schema `db.load(rows, { initial: true })` — one transaction, indexes and triggers rebuilt at the end.
-- Projectors from an admin connection: `db.projector(name, { from, into, version, handle })` builds rows of derived classes (`derivedBy: name`) from the journal; each batch is one transaction and every change is applied exactly once; `run()`, `rebuild()`, `status()`. Only the projector writes derived rows: the application, raw SQL and the loader get `derived_class`. Only an administrator creates, changes and deletes derived classes (an admin connection with a tenant session, or `letopis sync` with the admin `--dsn`); for an application session it is `acl_denied`. `purge()` of a deleted source object waits until the projector has read the deletion (`projector_pending`).
-- Aggregates in the database: the class option `aggregate: { balance: { sum: 'amount', of: 'Movement', via: 'Wallet' } }` (or `count: true`, `where` as a JSON Schema) keeps the field equal to the total of live source rows of the same tenant; a trigger after each statement recalculates it for the library, raw SQL, cascades and the loader; only the database writes the field (`aggregate_field`); repair with `db.rebuildAggregates(class)` on an admin connection, check with `db.verify({ data: true })`.
-- Subscriptions: `db.watch({ from, classes })` — `await sub.ready()` before a write that must reach the stream (`from: 'now'` fixes its starting point with the first query); parallel `next()` calls get different events.
-- NOTIFY signals are visible to any database role: `up({ signals: 'class' | 'tenant' | 'opaque' | 'none' })` chooses what they reveal (default `class`).
-- Access rules are always on and deny by default; `up({ tenant })` or `createTenant()` creates a tenant with the rule "authenticated users may do everything" and its first user.
-- MCP: `createMcpServer(db)` from `letopis/mcp` and `letopis mcp` (stdio, a user session token only) give an AI agent the tools `letopis_model`, `letopis_query` (a JSON chain, no SQL), `letopis_history` and, with `write: true`, `letopis_write`; the agent acts with the rights of one user, and a deletion needs a human confirmation through elicitation; by default `letopis_write` does not write the permission classes (`allowAclWrite`), and a session in the System tenant is refused (`allowSystemAdmin`). `structuredContent` of a tool result is `{ notice, data }` (an error — `{ notice, error }`): `notice` warns that `data` holds untrusted stored data, not instructions.
-- Errors carry a lowercase `err.code`: `exists`, `conflict`, `invalid_data` (`err.issues`), `target_not_found`, `acl_denied`, `no_session`, `removed` (0.21 API with its replacement), …
+- Пакет ESM, Node 22+, PostgreSQL 18+ с pgcrypto, кодировка базы UTF8. Зависимость времени выполнения — `postgres`. Zod 4 — необязательная peer-зависимость, нужна только `letopis/model`; `@modelcontextprotocol/server` — только `letopis/mcp`.
+- Схему ставит `up({ dsn, schema })` от администраторской роли; имя схемы — `v2.<имя>`; `up({ upgrade: true })` обновляет схему отставшей ревизии (миграции и повторный накат), `up({ schema, fresh: true })` пересоздаёт схему — данные теряются. Приложение подключается ролью LOGIN — членом `letopis_app`: `connect({ dsn, schema: 'v2.<имя>', token | apiKey })`. Роль в обход RLS отклоняется (`bypass_rls`), если не передать `allowBypassRls: true`.
+- Классы — хабы (объекты) и связи (отношения с концами). Их описывают `hub()` и `link()` из `letopis/model` и пишут в базу `syncModels()` или `letopis sync`. У класса с ключом id детерминированный, UUID v5 (`db.idOf`); уникальность — по ключу.
+- Глаголы возвращают цепочку; терминал (`rows`, `first`, `ids`, `count`, …) исполняет весь план одной транзакцией. `create` только создаёт (занятый ключ — `exists`), `update` сливает и никогда не создаёт, `upsert` заменяет объект целиком (только у классов с ключом), `delete()` — превью, `delete({ confirm: true })` удаляет.
+- Строгий режим. `connect({ models })` или `connect<Models>()` с файлом `letopis types` дают строгие типы: шаг — только класс или алиас моделей и системных классов, переходы — по концам, слоты — роли класса, поля фильтров, `or()` и агрегатов — поля класса; имя, известное только во время выполнения, — `loose(db)[имя]()`. Во время выполнения: `update()` и `delete({ confirm: true })` без фильтра, id, `tags()`, `owner()` и `limit()` ни у одного шага — `invalid_query` (все строки — `{ all: true }`); неизвестное поле фильтра, `sort()` или агрегата — `invalid_query` с похожими именами (сверяется первый ключ пути), неизвестный класс или роль — `invalid_class` с похожими; неизвестная опция `connect()`, `up()`, `load()`, `watch()`, `createMcpServer()` — `invalid_data` с похожими именами; `after()` перед `count()` и агрегатами — `invalid_query`; хаб с именем метода цепочки, корня `db` или батча — `invalid_class`.
+- Деньги и счётчики: `update({ balance: inc(n) })` прибавляет внутри оператора; `update(patch, { rev })` даёт `conflict`, если строка изменилась; `forUpdate()` блокирует строки внутри `db.begin()`.
+- История: `versions()` (у версии — автор, время, вид операции и причина) и срез `asOf(момент)`; глаголы, `db.begin()` и `db.batch()` принимают `{ reason }`. Журнал хранит каждую версию; `history: false` у класса — журнала нет.
+- Массовая загрузка с администраторского подключения: `db.load(rows)`; в пустую схему — `db.load(rows, { initial: true })`: одна транзакция, индексы и триггеры перестраиваются в конце.
+- Подписка: `db.watch({ from, classes })` — `await sub.ready()` перед записью, которая должна попасть в поток (`from: 'now'` фиксирует начало первым запросом); параллельные `next()` получают разные события.
+- Сигналы NOTIFY видны любой роли базы: `up({ signals: 'class' | 'tenant' | 'opaque' | 'none' })` выбирает, что они раскрывают (по умолчанию `class`).
+- Права действуют всегда и по умолчанию запрещают; `up({ tenant })` или `createTenant()` заводит арендатора с правилом «вошедшим можно всё» и его первого пользователя.
+- MCP: `createMcpServer(db)` из `letopis/mcp` и `letopis mcp` (stdio, только токен сессии пользователя) дают ИИ-агенту инструменты `letopis_model`, `letopis_query` (JSON-цепочка, без SQL), `letopis_history` и, с `write: true`, `letopis_write`; агент действует с правами одного пользователя, удаление подтверждает человек через elicitation. `structuredContent` ответа — `{ notice, data }` (отказ — `{ notice, error }`): `notice` предупреждает, что в `data` — данные базы, а не инструкции.
+- У ошибок строчный код `err.code`: `exists`, `conflict`, `invalid_data` (`err.issues`), `target_not_found`, `acl_denied`, `no_session`, …; `err.hint` — что делать, `err.docs` — ссылка на код в разделе «Ошибки» README.
 
-## Docs
+## Документы
 
-- [Agent cheatsheet](AGENT-CHEATSHEET.en.md): one page for an AI agent writing code with letopis — working cycle and pitfalls
-- [Guide](README.en.md): task-based guide, API reference, errors, limitations
-- [Шпаргалка для агента](AGENT-CHEATSHEET.md): the cheatsheet in Russian (original)
-- [Руководство](README.md): the guide in Russian (original)
+- [Шпаргалка для агента](AGENT-CHEATSHEET.md): одна страница для ИИ-агента, который пишет код на letopis, — рабочий цикл и грабли
+- [Руководство](README.md): руководство по задачам, справочник API, ограничения
+- [Ошибки](README.md#15-ошибки): все коды — что значит и что делать
 
-## Optional
+## Дополнительно
 
-- [Migration from 0.21](MIGRATION.md): data import with `letopis import` and the API replacement table (Russian)
-- [Changelog](CHANGELOG.md): decisions by version, BREAKING changes of 1.0 (Russian)
-- Model of a concrete installation for an agent: `letopis describe --format text --out llms.txt` or `describeText(db.describe())` — classes, keys, fields and ends of that schema
+- [Изменения по версиям](CHANGELOG.md): решения по версиям, несовместимые изменения
+- Модель конкретной установки для агента — инструмент MCP `letopis_model`: классы, ключи, поля, концы и рабочие цепочки этой схемы

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "1.4.1",
+  "version": "2.0.0",
   "description": "Letopis (летопись): versioned entity store on PostgreSQL 18 — integrity, history, tenants and access control enforced by the database itself, dot-notation chains on top",
   "keywords": [
     "postgres",
@@ -51,12 +51,9 @@
     "dist",
     "sql",
     "README.md",
-    "README.en.md",
     "AGENT-CHEATSHEET.md",
-    "AGENT-CHEATSHEET.en.md",
     "llms.txt",
     "CHANGELOG.md",
-    "MIGRATION.md",
     "LICENSE"
   ],
   "scripts": {
@@ -66,18 +63,21 @@
     "check:docs": "node scripts/check-docs.mjs",
     "check:package": "node scripts/check-package.mjs",
     "seed:booking": "tsx scripts/gen-seed-booking.mjs",
-    "test:import-salon": "tsx bench/import-salon.mjs",
     "api:contract": "node scripts/gen-api-contract.mjs",
-    "prepublishOnly": "npm run typecheck && npm run check:docs && npm run build"
+    "ops:tables": "tsx scripts/gen-ops-tables.mjs",
+    "prepublishOnly": "npm run typecheck && npm run check:docs && npm run build",
+    "check:semver": "node scripts/check-semver.mjs",
+    "prerelease": "node scripts/prerelease.mjs",
+    "soak": "tsx bench/soak.mjs"
   },
   "dependencies": {
     "postgres": "^3.4.9"
   },
   "peerDependencies": {
-    "zod": "^4",
     "@electric-sql/pglite": "^0.5.8",
     "@electric-sql/pglite-socket": "^0.2.11",
-    "@modelcontextprotocol/server": "^2.4.0"
+    "@modelcontextprotocol/server": "^2.4.0",
+    "zod": "^4"
   },
   "peerDependenciesMeta": {
     "zod": {
@@ -99,9 +99,6 @@
     "@modelcontextprotocol/client": "^2.4.0",
     "@modelcontextprotocol/server": "^2.4.0",
     "@types/node": "^22.20.5",
-    "letopis-0": "npm:letopis@0.21.0",
-    "letopis-1": "npm:letopis@1.0.1",
-    "letopis-11": "npm:letopis@1.1.0",
     "tsx": "^4.23.15",
     "typescript": "~5.9.3",
     "zod": "4.6.5"

package/sql/10-core.sql

@@ -17,25 +17,6 @@ return (
   from jsonb_path_query(coalesce(links, '{}'::jsonb), 'lax $.*[*]') as v
 );
 
--- Снимок версии для хэша (§2.2). Не зависит от настроек сеанса: время — числом микросекунд,
--- остальное — через текстовый вид jsonb, который от настроек не зависит.
-create or replace function @SCHEMA@.snapshot(
-  id uuid, rev int, class text, tenant uuid, owner uuid, links jsonb, data jsonb, tags text[],
-  at timestamptz, author uuid, agent text, op text, reason text, moved uuid
-) returns bytea
-language sql immutable parallel safe
-return convert_to(
-  jsonb_build_array(
-    id, rev, class, tenant, owner, links, data, to_jsonb(tags),
-    (extract(epoch from at) * 1000000)::bigint, author, agent, op, reason, moved
-  )::text,
-  'UTF8'
-);
-
-create or replace function @SCHEMA@.version_hash(prev_hash bytea, snap bytea) returns bytea
-language sql immutable parallel safe
-return sha256(coalesce(prev_hash, ''::bytea) || snap);
-
 create table if not exists @SCHEMA@.entity (
   id         uuid primary key,
   rev        int not null,
@@ -53,10 +34,6 @@ create table if not exists @SCHEMA@.entity (
   agent      text,
   op         text not null,
   reason     text,
-  moved      uuid,
-  prev_hash  bytea,
-  hash       bytea generated always as (@SCHEMA@.version_hash(prev_hash,
-               @SCHEMA@.snapshot(id, rev, class, tenant, owner, links, data, tags, at, author, agent, op, reason, moved))) stored,
   validator  jsonpath
 );
 create index if not exists entity_class_tenant on @SCHEMA@.entity (class, tenant);
@@ -84,32 +61,19 @@ create table if not exists @SCHEMA@.log (
   agent      text,
   op         text not null,
   reason     text,
-  moved      uuid,
-  prev_hash  bytea,
-  hash       bytea generated always as (@SCHEMA@.version_hash(prev_hash,
-               @SCHEMA@.snapshot(id, rev, class, tenant, owner, links, data, tags, at, author, agent, op, reason, moved))) stored,
-  -- пути изменения против предыдущей версии (план 1.1, ревизия 6): производные, в снимок и хэш не входят;
-  -- null — не посчитано (создание, загрузчик, импорт), blame досчитывает сравнением
-  changed    jsonb,
   constraint log_id_rev unique (id, rev)
 );
 -- срез журнала по классу (asOf, withDeleted) — по арендатору (доработки после точки Б): цена запроса не растёт с
--- журналом других арендаторов с тем же именем класса. Прежний log_class_at (class, at) снимается при накате; на
--- большой установке новый индекс можно построить заранее — create index concurrently log_class_tenant_at …
+-- журналом других арендаторов с тем же именем класса
 create index if not exists log_class_tenant_at on @SCHEMA@.log (class, tenant, at);
-drop index if exists @SCHEMA@.log_class_at;
 create index if not exists log_tx_seq on @SCHEMA@.log (tx, seq);
--- versions({ follow: true }): переход по связи старого и нового id при reclass и rekey (этап 6)
-create index if not exists log_moved on @SCHEMA@.log (moved) where moved is not null;
 -- срез asOf и withDeleted по переходу и deep (ревизия 5): версии, ссылавшиеся на id, — как entity_ends у
 -- текущего состояния; без него поиск в журнале перебирал все версии класса (бенч этапа 7)
 create index if not exists log_ends on @SCHEMA@.log using gin (@SCHEMA@.link_ids(links));
--- журнал часто прореживается (§2.11): чаще чистим
-alter table @SCHEMA@.log set (autovacuum_vacuum_scale_factor = 0.02, autovacuum_analyze_scale_factor = 0.02);
 
--- account — строка entity (аккаунт; у служебных строк KEY, LOCK, PROJECTOR — System): удалённый аккаунт уносит свои строки
--- каскадом внешнего ключа — сессии, хэши паролей и ключей, секреты TOTP, внешние учётные записи (ревизия 7; в схему
--- прежней ревизии ключ добавляет миграция 0007). Строка Account у System не удаляется (trg_entity_bd_account, 60-write.sql)
+-- account — строка entity (аккаунт; у служебных строк KEY и LOCK — System): удалённый аккаунт уносит свои строки
+-- каскадом внешнего ключа — сессии, хэши паролей и ключей, секреты TOTP, внешние учётные записи (ревизия 7). Строка
+-- Account у System не удаляется (trg_entity_bd_account, 60-write.sql)
 create table if not exists @SCHEMA@.secret (
   id          uuid primary key default gen_random_uuid(),
   account     uuid not null constraint secret_account_fkey references @SCHEMA@.entity (id) on delete cascade,
@@ -131,24 +95,17 @@ alter table @SCHEMA@.entity owner to @OWNER@;
 alter table @SCHEMA@.log owner to @OWNER@;
 alter table @SCHEMA@.secret owner to @OWNER@;
 alter function @SCHEMA@.link_ids(jsonb) owner to @OWNER@;
-alter function @SCHEMA@.snapshot(uuid, int, text, uuid, uuid, jsonb, jsonb, text[], timestamptz, uuid, text, text, text, uuid) owner to @OWNER@;
-alter function @SCHEMA@.version_hash(bytea, bytea) owner to @OWNER@;
 
 -- Права приложения (§2.7, этап 1, п. 1): только пользовательские колонки.
 revoke all on @SCHEMA@.entity, @SCHEMA@.log, @SCHEMA@.secret from public, @APP@;
 grant select, delete on @SCHEMA@.entity to @APP@;
 grant insert (id, tenant, class, links, data, tags, owner) on @SCHEMA@.entity to @APP@;
 grant update (class, links, data, tags) on @SCHEMA@.entity to @APP@;
--- журнал — без колонки changed (ревью №1 точки А плана 1.1): её пути описывают разницу с предыдущей версией, а та
--- читателю может быть не видна (условие ACL скрыло её и пропустило следующую); blame получает пути через
--- version_paths, которая проверяет видимость обеих версий (75-history.sql)
-grant select (seq, tx, id, rev, class, cv, tenant, owner, links, data, tags, at, author, agent, op, reason, moved, prev_hash, hash)
+grant select (seq, tx, id, rev, class, cv, tenant, owner, links, data, tags, at, author, agent, op, reason)
   on @SCHEMA@.log to @APP@;
 alter table @SCHEMA@.entity enable row level security;
 alter table @SCHEMA@.log enable row level security;
 alter table @SCHEMA@.secret enable row level security;
 revoke all on all functions in schema @SCHEMA@ from public;
--- генерируемые колонки ends и hash вычисляются с правами пишущей роли: функции чистые, без побочных эффектов
-grant execute on function @SCHEMA@.link_ids(jsonb),
-  @SCHEMA@.snapshot(uuid, int, text, uuid, uuid, jsonb, jsonb, text[], timestamptz, uuid, text, text, text, uuid),
-  @SCHEMA@.version_hash(bytea, bytea) to @APP@;
+-- генерируемая колонка ends вычисляется с правами пишущей роли: функция чистая, без побочных эффектов
+grant execute on function @SCHEMA@.link_ids(jsonb) to @APP@;

package/sql/15-errors.sql

@@ -16,19 +16,11 @@ as $$
     ('LT008', 'id_from_db',             'letopis: id_from_db: id класса без ключа выдаёт база'),
     ('LT009', 'immutable_key',          'letopis: immutable_key: ключевое поле менять нельзя'),
     ('LT010', 'invalid_class',          'letopis: invalid_class: описание класса отклонено'),
-    ('LT011', 'use_reclass',            'letopis: use_reclass: класс с ключом меняется функцией reclass()'),
-    ('LT012', 'reclass_denied',         'letopis: reclass_denied: смена класса отклонена'),
     ('LT013', 'tightening_conflict',    'letopis: tightening_conflict: ужесточению описания мешают строки'),
     ('LT014', 'isolation_level',        'letopis: isolation_level: операция разрешена только в read committed'),
     ('LT015', 'recreated_in_statement', 'letopis: recreated_in_statement: id удалён и создан заново одним оператором'),
-    ('LT016', 'cursor_expired',         'letopis: cursor_expired: курсор подписки старше яруса all'),
     ('LT017', 'delete_restricted',      'letopis: delete_restricted: удалению мешают ссылающиеся строки'),
-    ('LT018', 'not_deleted',            'letopis: not_deleted: объект не удалён — restore и purge только для удалённых'),
-    ('LT019', 'reset_disabled',         'letopis: reset_disabled: reset выключен в этой установке'),
-    ('LT020', 'confirm_mismatch',       'letopis: confirm_mismatch: подтверждение не совпадает с именем схемы'),
-    ('LT021', 'derived_class',          'letopis: derived_class: строки производного класса пишет только его проектор'),
-    ('LT022', 'aggregate_field',        'letopis: aggregate_field: агрегатное поле считает база'),
-    ('LT023', 'projector_pending',      'letopis: projector_pending: проектор источника ещё не прочёл удаление')
+    ('LT018', 'not_deleted',            'letopis: not_deleted: объект не удалён — restore только для удалённых')
 $$;
 
 create or replace function @SCHEMA@.lt_raise(p_code text, p_name text, p_msg text, p_detail jsonb default null)
@@ -52,12 +44,74 @@ begin
   perform @SCHEMA@.lt_raise(coalesce(c, 'LT000'), p_name, p_msg, p_detail);
 end $$;
 
+-- Каталог сообщений базы (план 2.0, этап 3, п. 3): ключ → имя ошибки и русский шаблон, {имя} — параметр. Строки
+-- подставляет установщик (@MESSAGES@) из разделов sql-* каталога библиотеки (lib/src/messages). Обновляет обычный up(),
+-- как прочие функции.
+create or replace function @SCHEMA@.message_catalog() returns table (key text, name text, ru text)
+language sql immutable parallel safe
+as $catalog$
+  select m.key, m.value->>'name', m.value->>'ru' from jsonb_each(@MESSAGES@::jsonb) m
+$catalog$;
+
+-- Русский текст по ключу каталога: шаблон, где {имя} — значение p_params текстом (null — пусто, как у format('%s'));
+-- ключа нет — сам ключ. Выдана приложению: функции, которые оно исполняет (lt_fail ему не выдан), бросают raise с ней.
+create or replace function @SCHEMA@.lt_text(p_key text, p_params jsonb default null)
+returns text
+language plpgsql stable parallel safe
+as $$
+declare
+  t text;
+  p record;
+begin
+  select m.ru into t from @SCHEMA@.message_catalog() m where m.key = p_key;
+  t := coalesce(t, p_key);
+  for p in select * from jsonb_each_text(coalesce(p_params, '{}'::jsonb)) loop
+    t := replace(t, '{' || p.key || '}', coalesce(p.value, ''));
+  end loop;
+  return t;
+end $$;
+
+-- Ошибка по ключу каталога сообщений: имя (и SQLSTATE) — из каталога, текст — русский шаблон с параметрами (его видит
+-- сырой SQL), в DETAIL — поля p_detail и ещё key, params: библиотека переносит их в поля ошибки (key, params).
+-- Без параметров — один аргумент: литерал без типа вторым аргументом выбрал бы lt_fail(имя, текст).
+-- p_detail — прежний DETAIL места: не передан — {} (так всегда делала lt_raise); JSON null (p_detail => 'null') — DETAIL
+-- не было (место бросало raise без detail): в DETAIL признак nodetail, и у ошибки библиотеки detail нет, как раньше.
+create or replace function @SCHEMA@.lt_fail(p_key text, p_params jsonb default '{}'::jsonb, p_detail jsonb default null)
+returns void
+language plpgsql
+as $$
+declare
+  n text;
+begin
+  select m.name into n from @SCHEMA@.message_catalog() m where m.key = p_key;
+  perform @SCHEMA@.lt_fail(coalesce(n, p_key), @SCHEMA@.lt_text(p_key, p_params),
+    case when jsonb_typeof(p_detail) = 'null' then '{"nodetail": true}'::jsonb else coalesce(p_detail, '{}'::jsonb) end
+      || jsonb_build_object('key', p_key, 'params', coalesce(p_params, '{}'::jsonb)));
+end $$;
+
+-- То же со своим SQLSTATE не из каталога (например, 40001 — повторяемый конфликт).
+create or replace function @SCHEMA@.lt_raise(p_code text, p_key text, p_params jsonb, p_detail jsonb default null)
+returns void
+language plpgsql
+as $$
+declare
+  n text;
+begin
+  select m.name into n from @SCHEMA@.message_catalog() m where m.key = p_key;
+  perform @SCHEMA@.lt_raise(p_code, coalesce(n, p_key), @SCHEMA@.lt_text(p_key, p_params),
+    case when jsonb_typeof(p_detail) = 'null' then '{"nodetail": true}'::jsonb else coalesce(p_detail, '{}'::jsonb) end
+      || jsonb_build_object('key', p_key, 'params', coalesce(p_params, '{}'::jsonb)));
+end $$;
+
 do $$
 declare f text;
 begin
-  foreach f in array array['error_catalog()', 'lt_raise(text, text, text, jsonb)', 'lt_fail(text, text, jsonb)'] loop
+  foreach f in array array['error_catalog()', 'lt_raise(text, text, text, jsonb)', 'lt_fail(text, text, jsonb)',
+      'message_catalog()', 'lt_text(text, jsonb)', 'lt_fail(text, jsonb, jsonb)', 'lt_raise(text, text, jsonb, jsonb)'] loop
     execute format('alter function @SCHEMA@.%s owner to @OWNER@', f);
     execute format('revoke all on function @SCHEMA@.%s from public', f);
   end loop;
 end $$;
 grant execute on function @SCHEMA@.error_catalog() to @APP@;
+grant execute on function @SCHEMA@.message_catalog() to @APP@;
+grant execute on function @SCHEMA@.lt_text(text, jsonb) to @APP@;

package/sql/20-context.sql

@@ -48,7 +48,7 @@ begin
   if imp is not null and imp is distinct from s.account::text then
     -- имперсонация (этап 5, п. 3): право сервиса — по правилам System, в его собственном арендаторе
     if not pg_input_is_valid(imp, 'uuid') then
-      perform @SCHEMA@.lt_fail('acl_denied', 'letopis.account — не id аккаунта');
+      perform @SCHEMA@.lt_fail('sql-core.account_not_id');
     end if;
     scats := array(select jsonb_array_elements_text(coalesce(a.data->'categories', '[]'::jsonb)));
     stenant := tenant;
@@ -56,7 +56,7 @@ begin
       select jsonb_array_elements_text(coalesce(x.data->'roles', '[]'::jsonb)) from @SCHEMA@.entity x
       where x.id = @SCHEMA@.v5_id(stenant, 'member', array[s.account::text, stenant::text]) and x.class = 'member') end;
     if not coalesce((@SCHEMA@.acl_api_for(stenant, scats, sroles, 'auth.impersonate', true)->>'allow')::boolean, false) then
-      perform @SCHEMA@.lt_fail('acl_denied', 'нет права auth.impersonate');
+      perform @SCHEMA@.lt_fail('sql-core.no_impersonate_right');
     end if;
     select e.id, e.data into a from @SCHEMA@.entity e where e.id = imp::uuid and e.class = 'Account' and e.tenant = '@SYSTEM@'::uuid;
     -- от имени System, сервисов, системных администраторов и отключённых аккаунтов действовать нельзя
@@ -64,7 +64,7 @@ begin
        or coalesce(a.data->'categories' ?| array['System', 'Service'], false)
        or exists (select 1 from @SCHEMA@.entity x
                   where x.id = @SCHEMA@.v5_id('@SYSTEM@'::uuid, 'member', array[a.id::text, '@SYSTEM@']) and x.class = 'member') then
-      perform @SCHEMA@.lt_fail('acl_denied', 'действовать от имени этого аккаунта нельзя');
+      perform @SCHEMA@.lt_fail('sql-core.impersonation_denied');
     end if;
     service := s.account;
     agent := s.account::text;
@@ -73,7 +73,7 @@ begin
   end if;
   if want is not null then
     if not pg_input_is_valid(want, 'uuid') then
-      perform @SCHEMA@.lt_fail('tenant_denied', 'letopis.tenant — не id арендатора');
+      perform @SCHEMA@.lt_fail('sql-core.tenant_not_id');
     end if;
     tenant := want::uuid;
   end if;
@@ -86,7 +86,7 @@ begin
     select e.id into t from @SCHEMA@.entity e
     where e.id = tenant and e.class = 'Account' and e.tenant = '@SYSTEM@'::uuid and coalesce((e.data->>'enabled')::boolean, true);
     if m is null or t.id is null then
-      perform @SCHEMA@.lt_fail('tenant_denied', 'нет членства в арендаторе');
+      perform @SCHEMA@.lt_fail('sql-core.no_membership');
     end if;
     roles := array(select jsonb_array_elements_text(coalesce(m.data->'roles', '[]'::jsonb)));
   end if;
@@ -137,7 +137,8 @@ begin
     and coalesce((s.meta->>'enabled')::boolean, true)
     and coalesce((a.data->>'enabled')::boolean, true);
   if k.account is null then
-    raise exception using errcode = 'LT001', message = 'letopis: no_session: неверный ключ';
+    -- DETAIL не было и до каталога (raise без detail): p_detail => 'null' (15-errors.sql)
+    perform @SCHEMA@.lt_fail('sql-core.bad_api_key', p_detail => 'null');
   end if;
   return @SCHEMA@.new_session(k.account, interval '7 days', jsonb_build_object('methods', jsonb_build_array('APIKEY'), 'cred', k.id));
 end $$;

package/sql/30-validate.sql

@@ -41,7 +41,8 @@ return to_jsonb(s)::text;
 -- Перевод шаблона JavaScript в регулярное выражение PostgreSQL (этап 1, п. 5): разбор по символам,
 -- как translatePattern в lib/src/jsonschema.ts. \d \w \s и их отрицания — явными наборами (внутри
 -- [ ] — без скобок), экранированная обратная косая черта остаётся собой; \b, \p{…}, именованные
--- группы и обратные ссылки отклоняются.
+-- группы и обратные ссылки отклоняются. Отказы здесь и в jp_compile — lt_fail(…, p_detail => 'null'): DETAIL у них
+-- не было и до каталога (raise без detail), у ошибки библиотеки detail нет (15-errors.sql).
 create or replace function @SCHEMA@.jp_pattern(p text) returns text
 language plpgsql immutable strict
 as $$
@@ -52,7 +53,6 @@ declare
   n text;
   in_class boolean := false;
   sp constant text := ' \t\n\r\f\v';
-  why text;
 begin
   while i <= length(p) loop
     c := substr(p, i, 1);
@@ -60,7 +60,7 @@ begin
       n := substr(p, i + 1, 1);
       i := i + 2;
       if n = '' then
-        why := 'обратная косая черта в конце шаблона';
+        perform @SCHEMA@.lt_fail('sql-core.pattern_trailing_backslash', jsonb_build_object('pattern', p), p_detail => 'null');
       elsif n = 'd' then
         res := res || case when in_class then '0-9' else '[0-9]' end;
       elsif n = 'w' then
@@ -69,26 +69,23 @@ begin
         res := res || case when in_class then sp else '[' || sp || ']' end;
       elsif n in ('D', 'W', 'S') then
         if in_class then
-          why := '\' || n || ' внутри набора [ ] не переводится';
+          perform @SCHEMA@.lt_fail('sql-core.pattern_escape_in_set', jsonb_build_object('pattern', p, 'escape', '\' || n), p_detail => 'null');
         else
           res := res || case n when 'D' then '[^0-9]' when 'W' then '[^A-Za-z0-9_]' else '[^' || sp || ']' end;
         end if;
       elsif n in ('b', 'B') then
-        why := '\' || n || ' в PostgreSQL значит другое';
+        perform @SCHEMA@.lt_fail('sql-core.pattern_word_boundary', jsonb_build_object('pattern', p, 'escape', '\' || n), p_detail => 'null');
       elsif n in ('p', 'P') then
-        why := '\p{…} не поддерживается';
+        perform @SCHEMA@.lt_fail('sql-core.pattern_unicode_property', jsonb_build_object('pattern', p), p_detail => 'null');
       elsif n = 'k' or n ~ '[1-9]' then
-        why := 'обратные ссылки не поддерживаются';
+        perform @SCHEMA@.lt_fail('sql-core.pattern_backreference', jsonb_build_object('pattern', p), p_detail => 'null');
       else
         res := res || c || n;
       end if;
-      if why is not null then
-        raise exception using errcode = 'LT010', message = 'letopis: invalid_class: шаблон ' || p || ' несовместим с регулярными выражениями PostgreSQL (' || why || ')';
-      end if;
       continue;
     end if;
     if not in_class and substr(p, i, 3) = '(?<' and substr(p, i + 3, 1) not in ('=', '!') then
-      raise exception using errcode = 'LT010', message = 'letopis: invalid_class: шаблон ' || p || ' несовместим с регулярными выражениями PostgreSQL (именованные группы не поддерживаются)';
+      perform @SCHEMA@.lt_fail('sql-core.pattern_named_group', jsonb_build_object('pattern', p), p_detail => 'null');
     end if;
     if c = '[' and not in_class then
       in_class := true;
@@ -153,11 +150,11 @@ begin
     rules := r; return;
   end if;
   if jsonb_typeof(p_schema) <> 'object' then
-    raise exception using errcode = 'LT010', message = format('letopis: invalid_class: описание узла %s — не объект', p_disp);
+    perform @SCHEMA@.lt_fail('sql-core.schema_node_not_object', jsonb_build_object('node', p_disp::text), p_detail => 'null');
   end if;
   for k in select jsonb_object_keys(p_schema) loop
     if not (k = any (allowed) or k like 'x-%') then
-      raise exception using errcode = 'LT010', message = format('letopis: invalid_class: ключевое слово %s не поддерживается (узел %s)', k, p_disp);
+      perform @SCHEMA@.lt_fail('sql-core.keyword_unsupported', jsonb_build_object('keyword', k, 'node', p_disp::text), p_detail => 'null');
     end if;
   end loop;
 
@@ -170,7 +167,7 @@ begin
       tcond := @SCHEMA@.jp_type_cond(p_schema->>'type');
     end if;
     if tcond is null then
-      raise exception using errcode = 'LT010', message = format('letopis: invalid_class: неизвестный тип в узле %s', p_disp);
+      perform @SCHEMA@.lt_fail('sql-core.unknown_type', jsonb_build_object('node', p_disp::text), p_detail => 'null');
     end if;
     r := r || jsonb_build_object('path', p_disp, 'keyword', 'type', 'path_expr', p_path, 'cond', tcond, 'vars', '{}'::jsonb);
   end if;
@@ -181,7 +178,7 @@ begin
     for v in select x from jsonb_array_elements(coalesce(p_schema->'enum', jsonb_build_array(p_schema->'const'))) x loop
       if jsonb_typeof(v) in ('object', 'array') then
         if p_in_any then
-          raise exception using errcode = 'LT010', message = format('letopis: invalid_class: перечисление объектов внутри anyOf не поддерживается (узел %s)', p_disp);
+          perform @SCHEMA@.lt_fail('sql-core.enum_objects_in_any_of', jsonb_build_object('node', p_disp::text), p_detail => 'null');
         end if;
         r := r || jsonb_build_object('path', p_disp, 'keyword', case when p_schema ? 'enum' then 'enum' else 'const' end,
           'path_expr', p_path, 'cond', 'true', 'vars', '{}'::jsonb, 'extra', jsonb_build_object('kind', 'enum', 'values', coalesce(p_schema->'enum', jsonb_build_array(p_schema->'const'))));
@@ -227,11 +224,11 @@ begin
         when 'email' then '^[^@[:space:]]+@[^@[:space:]]+\.[^@[:space:]]+$'
         else null end) || ')');
     if t not in ('uuid', 'date', 'date-time', 'email') then
-      raise exception using errcode = 'LT010', message = format('letopis: invalid_class: format %s не поддерживается (узел %s)', t, p_disp);
+      perform @SCHEMA@.lt_fail('sql-core.format_unsupported', jsonb_build_object('format', t, 'node', p_disp::text), p_detail => 'null');
     end if;
     if t in ('date', 'date-time') then
       if p_in_any then
-        raise exception using errcode = 'LT010', message = format('letopis: invalid_class: format %s внутри anyOf не поддерживается (узел %s)', t, p_disp);
+        perform @SCHEMA@.lt_fail('sql-core.format_in_any_of', jsonb_build_object('format', t, 'node', p_disp::text), p_detail => 'null');
       end if;
       r := r || jsonb_build_object('path', p_disp, 'keyword', 'format', 'path_expr', p_path, 'cond', 'true', 'vars', '{}'::jsonb,
         'extra', jsonb_build_object('kind', 'date', 'type', case t when 'date' then 'date' else 'timestamptz' end,
@@ -241,7 +238,7 @@ begin
   end if;
   if p_schema ? 'minLength' or p_schema ? 'maxLength' then
     if p_in_any then
-      raise exception using errcode = 'LT010', message = format('letopis: invalid_class: длина строки внутри anyOf не поддерживается (узел %s)', p_disp);
+      perform @SCHEMA@.lt_fail('sql-core.string_length_in_any_of', jsonb_build_object('node', p_disp::text), p_detail => 'null');
     end if;
     r := r || jsonb_build_object('path', p_disp, 'keyword', case when p_schema ? 'minLength' then 'minLength' else 'maxLength' end,
       'path_expr', p_path, 'cond', 'true', 'vars', '{}'::jsonb,
@@ -258,7 +255,7 @@ begin
   end loop;
   if coalesce((p_schema->>'uniqueItems')::boolean, false) then
     if p_in_any then
-      raise exception using errcode = 'LT010', message = format('letopis: invalid_class: uniqueItems внутри anyOf не поддерживается (узел %s)', p_disp);
+      perform @SCHEMA@.lt_fail('sql-core.unique_items_in_any_of', jsonb_build_object('node', p_disp::text), p_detail => 'null');
     end if;
     r := r || jsonb_build_object('path', p_disp, 'keyword', 'uniqueItems', 'path_expr', p_path, 'cond', 'true', 'vars', '{}'::jsonb,
       'extra', jsonb_build_object('kind', 'unique'));
@@ -277,7 +274,7 @@ begin
   end if;
   if p_schema ? 'minProperties' or p_schema ? 'maxProperties' then
     if p_in_any then
-      raise exception using errcode = 'LT010', message = format('letopis: invalid_class: minProperties внутри anyOf не поддерживается (узел %s)', p_disp);
+      perform @SCHEMA@.lt_fail('sql-core.min_properties_in_any_of', jsonb_build_object('node', p_disp::text), p_detail => 'null');
     end if;
     r := r || jsonb_build_object('path', p_disp, 'keyword', case when p_schema ? 'minProperties' then 'minProperties' else 'maxProperties' end,
       'path_expr', p_path, 'cond', 'true', 'vars', '{}'::jsonb,
@@ -356,6 +353,8 @@ end $$;
 
 -- Проверка данных: общий вызов jsonb_path_match; при отказе — список нарушений по правилам.
 -- Результат сравнивается через is true: ошибка внутри выражения даёт NULL, а не «да» (этап 1, п. 5).
+-- Нарушение — { path, keyword, message, key, params }: message — русский текст по ключу каталога, рядом его key и
+-- params; библиотека убирает key и params (fromDbError, загрузчик).
 create or replace function @SCHEMA@.validate_data(p_rules jsonb, p_validator jsonpath, p_vars jsonb, p_data jsonb) returns jsonb
 language plpgsql stable
 as $$
@@ -364,6 +363,7 @@ declare
   bad jsonb := '[]'::jsonb;
   ok boolean;
   x jsonb;
+  p jsonb;
 begin
   ok := jsonb_path_match(p_data, p_validator, p_vars, true) is true;
   if ok and not exists (select 1 from jsonb_array_elements(p_rules) r where r ? 'extra') then
@@ -375,36 +375,44 @@ begin
         if (e->'extra'->>'kind') = 'length' and jsonb_typeof(x) = 'string' then
           if char_length(x #>> '{}') < coalesce((e->'extra'->>'min')::int, 0)
              or char_length(x #>> '{}') > coalesce((e->'extra'->>'max')::int, 2147483647) then
-            bad := bad || jsonb_build_object('path', e->'path', 'keyword', e->>'keyword', 'message', 'длина строки вне границ');
+            bad := bad || jsonb_build_object('path', e->'path', 'keyword', e->>'keyword', 'message', @SCHEMA@.lt_text('sql-core.issue_string_length'),
+              'key', 'sql-core.issue_string_length', 'params', '{}'::jsonb);
           end if;
         elsif (e->'extra'->>'kind') = 'unique' and jsonb_typeof(x) = 'array' then
           if (select count(*) from jsonb_array_elements(x)) <> (select count(distinct y) from jsonb_array_elements(x) y) then
-            bad := bad || jsonb_build_object('path', e->'path', 'keyword', 'uniqueItems', 'message', 'элементы повторяются');
+            bad := bad || jsonb_build_object('path', e->'path', 'keyword', 'uniqueItems', 'message', @SCHEMA@.lt_text('sql-core.issue_unique_items'),
+              'key', 'sql-core.issue_unique_items', 'params', '{}'::jsonb);
           end if;
         elsif (e->'extra'->>'kind') = 'date' and jsonb_typeof(x) = 'string' then
           -- смысл проверяется только у строки правильной формы: форму проверяет правило format
           if (x #>> '{}') ~ (e->'extra'->>'re') and not pg_input_is_valid(x #>> '{}', e->'extra'->>'type') then
-            bad := bad || jsonb_build_object('path', e->'path', 'keyword', 'format', 'message', 'такой даты не бывает');
+            bad := bad || jsonb_build_object('path', e->'path', 'keyword', 'format', 'message', @SCHEMA@.lt_text('sql-core.issue_date'),
+              'key', 'sql-core.issue_date', 'params', '{}'::jsonb);
           end if;
         elsif (e->'extra'->>'kind') = 'props' and jsonb_typeof(x) = 'object' then
           if (select count(*) from jsonb_object_keys(x)) < coalesce((e->'extra'->>'min')::int, 0)
              or (select count(*) from jsonb_object_keys(x)) > coalesce((e->'extra'->>'max')::int, 2147483647) then
-            bad := bad || jsonb_build_object('path', e->'path', 'keyword', e->>'keyword', 'message', 'число ключей вне границ');
+            bad := bad || jsonb_build_object('path', e->'path', 'keyword', e->>'keyword', 'message', @SCHEMA@.lt_text('sql-core.issue_property_count'),
+              'key', 'sql-core.issue_property_count', 'params', '{}'::jsonb);
           end if;
         elsif (e->'extra'->>'kind') = 'enum' then
           if not exists (select 1 from jsonb_array_elements(e->'extra'->'values') y where y = x) then
-            bad := bad || jsonb_build_object('path', e->'path', 'keyword', e->>'keyword', 'message', 'значение не из перечисления');
+            bad := bad || jsonb_build_object('path', e->'path', 'keyword', e->>'keyword', 'message', @SCHEMA@.lt_text('sql-core.issue_enum'),
+              'key', 'sql-core.issue_enum', 'params', '{}'::jsonb);
           end if;
         end if;
       end loop;
     elsif not ok then
       if jsonb_path_match(p_data, ('strict !exists(' || (e->>'path_expr') || ' ? (!(' || (e->>'cond') || ')))')::jsonpath, e->'vars', true) is not true then
-        bad := bad || jsonb_build_object('path', e->'path', 'keyword', e->>'keyword', 'message', 'нарушено правило ' || (e->>'keyword'));
+        p := jsonb_build_object('keyword', e->>'keyword');
+        bad := bad || jsonb_build_object('path', e->'path', 'keyword', e->>'keyword', 'message', @SCHEMA@.lt_text('sql-core.issue_rule', p),
+          'key', 'sql-core.issue_rule', 'params', p);
       end if;
     end if;
   end loop;
   if not ok and bad = '[]'::jsonb then
-    bad := jsonb_build_array(jsonb_build_object('path', '[]'::jsonb, 'keyword', 'schema', 'message', 'данные не проходят описание'));
+    bad := jsonb_build_array(jsonb_build_object('path', '[]'::jsonb, 'keyword', 'schema', 'message', @SCHEMA@.lt_text('sql-core.issue_schema'),
+      'key', 'sql-core.issue_schema', 'params', '{}'::jsonb));
   end if;
   return bad;
 end $$;