letopis 1.4.2 → 3.0.0

package/llms.txt

@@ -1,33 +1,50 @@
 # 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()`.
-
-Key facts for writing code with letopis 1.4:
-
-- 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), …
-
-## 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)
-
-## 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
+> ИИ-агенту: код на letopis пишите по [AGENT-CHEATSHEET.md](AGENT-CHEATSHEET.md) — памятка лежит в пакете рядом с этим файлом (`node_modules/letopis/AGENT-CHEATSHEET.md`); прочитайте её целиком: «Правила для любой задачи», рабочий цикл и «Грабли».
+>
+> Хранилище версионированных объектов для Node.js на PostgreSQL 18, версия 3.0. Каждое изменение — версия в журнале (история, чтение на момент, подписка по курсору). Целостность, изоляцию арендаторов и права доступа проверяет сама база (триггеры и политики RLS), поэтому они действуют и для сырого SQL. Данные читают и пишут цепочками вида `db.Team(g).Item().rows()`.
+
+Безопасность по умолчанию (одна строка — одно правило):
+
+- Удаление — только по превью: `delete()` → показать → `delete({ confirm: true, expect: превью })`; `delete({ confirm: true })` без `expect` — `invalid_query` (`write.confirm_without_expect`).
+- Восстановление — только по надгробиям: `restore({ expect: ответ delete() })`; `restore()` без `expect`, и по явному id тоже, — `invalid_query` (`write.restore_without_expect`).
+- Массовое и без сверки — только явно и только в осознанных скриптах: `{ all: true }` у `update`, `delete({ confirm: true, all: true })`, `restore({ all: true })`.
+- Арендатор — только из серверной сессии (`svc.auth.session(token)`), никогда из параметра клиента.
+- Права по умолчанию запрещают; подключение в обход RLS — `bypass_rls`, пока нет `allowBypassRls: true`.
+- `createTenant(admin, …)` — `admin` только пул `postgres()`, иначе `invalid_query` (`api.create_tenant_admin`).
+- Журнал событий маскирует значения полей с паролями, токенами, ключами, секретами и кредами (и полей из `redact`), учётные данные в строке подключения и пароль в тексте SQL; значения параметров SQL, тексты ошибок PostgreSQL и поле `data` строк в подробностях ошибок не пишет. Значения фильтров чтения в `chain` пишутся как есть — персональные поля добавьте в `redact`.
+
+Главное для кода на letopis:
+
+- Установка: `npm pkg set type=module && npm i letopis zod postgres@3 && npm i -D tsx` (код приложения — ESM; `postgres@3` — та же мажорная версия, что у letopis, иначе `createTenant` не проходит проверку типов). Node 22+, PostgreSQL 18+ с pgcrypto, база UTF8. Zod 4 нужен только `letopis/model`, `@modelcontextprotocol/server` — только `letopis/mcp`.
+- Схему ставит `up({ dsn, schema, login, tenant })` от администратора (суперпользователь или роль с `CREATEROLE`, `CREATE` в базе и `CREATEDB`, если базы нет); роль приложения заводит `login`, её строка подключения — `r.login.dsn`. Ключ сервиса выдаёт только первый `up()` — храните его сами или передавайте свой `up({ serviceKey })`; `connect({ apiKey: null | '' })` — сразу `invalid_data` (`api.connect_empty_credential`), а `undefined` — подключение без сессии, поэтому ключ проверяйте до `connect()`; `up({ upgrade: true })` обновляет схему отставшей ревизии, `up({ fresh: true })` пересоздаёт её с потерей данных.
+- Вход пользователя: одно подключение сервиса на процесс (`connect({ apiKey })`), `svc.auth.verifyPassword()` → `{ account, token }`, затем `svc.as(account, { tenant })` на запрос. Без `{ tenant }` сессия — в **личном** арендаторе пользователя (классов там нет, `invalid_class`); проверка — `db.tenant`. По погашенной сессии чтение отдаёт пустые ответы, запись — `no_session`, поэтому `svc.auth.session(token)` — в начале каждого запроса.
+- Классы — хабы (объекты) и связи (отношения с концами): `hub()` и `link()` из `letopis/model`, в базу — `syncModels()` или `letopis sync` (в арендатора сессии). Имя роли конца одно на арендатора; роли `Group`, `Object`, `User`, `Tenant` заняты системными классами `rule` и `member` — конец с таким именем на другой класс — `invalid_class` (`model.end_role_system`).
+- Уникальность и инварианты держит ключ, а не проверка в коде: у класса с ключом id — UUID v5 (`db.idOf`), второй такой `create()` — `exists`, и под гонкой. «Одна открытая запись на объект» — связь с ключом по концу (`key: ['Obj']`); `restore()` бизнес-правил не проверяет, поэтому и при возврате инвариант держит только ключ.
+- Глаголы возвращают цепочку; терминал (`rows`, `first`, `ids`, `count`, …) исполняет весь план одной транзакцией. `create` только создаёт, `update` сливает патч и никогда не создаёт (`undefined` в патче — поле не меняется), `upsert` заменяет данные целиком (поле с `undefined` пропадает; только у классов с ключом).
+- Удаление ровно показанного атомарно: превью сверяется под блокировкой каскада, расхождение — `conflict` (`write.preview_changed`) с новым превью в `err.detail.preview`. Целей нет: непустой `expect` — `conflict` с `err.detail.preview: []` («уже удалено или не найдено»), `expect: []` — пустой ответ.
+- Возврат — по ответу `delete()` (или надгробиям `withDeleted()` по id): `restore({ expect })` — всё или отказ по смыслу (`write.restore_already`, `write.restore_id_taken` — `not_deleted`; `write.restore_stale` — `conflict`); `restore({ expect, partial: true })` — что можно, пропуски — строки `$action: 'skip'` с `$why`. Цель конца — первой, каскад — следующим шагом, оба — в одной `db.begin()` с `commit()`/`rollback()`.
+- Гонка за прочитанное — `forUpdate()` в `db.begin()` (только с `rows`, `first`, `ids`), `update(patch, { rev })` (`conflict`) или ключ; счётчик — `update({ n: inc(k) })`. Фильтр `update()` по данным, концам, `tags()`, `owner()` перепроверяется под блокировкой строки: выведенную параллельной транзакцией из-под фильтра строку он не правит (из двух одновременных правок со `status: 'new'` проходит одна); фильтр только по id — пройдут обе. Форма транзакции — `const tr = await db.begin(); try { …; await tr.commit() } catch (e) { await tr.rollback(); throw e }`; `db.begin(fn)` — `invalid_query`.
+- Строгий режим: `connect({ models })` или `connect<Models>()` дают строгие типы; неизвестное поле, класс или опция — отказ с похожими именами; `update()` без фильтра — `invalid_query` (все строки — `{ all: true }`); id не uuid — `invalid_query` до запроса; фильтр `undefined` — шаг без фильтра и предупреждение.
+- Концы связи — не поля данных: из пути или слотом `.Роль.set(id)`; имя конца в данных — `invalid_data` (`write.link_in_data`).
+- Модификаторы выборки (`sort`, `limit`, `offset`, `after`, `forUpdate`) — последнему шагу; `withDeleted()` — своему шагу. `versions()` — терминал; по пути — только живые, с удалёнными — `withDeleted()` на шаге или явный id.
+- Ответы и ошибки: строка — `{ id, class, rev, links, data, … }`, превью — с `$action`, надгробие — `$deleted: true`; ошибка — `LetopisError` с `err.code`, `err.key`, `err.detail`, `err.hint`, у данных — `ValidationError` с `err.issues: [{ path, keyword, message }]`. Штатные отказы (`exists`, `conflict`, `not_deleted`, `target_not_found`, `tenant_denied`, `acl_denied`, `no_session`, …) — ответ человеку своими фразами по `err.key`/`err.code`; ошибки кода — 500.
+- Логирование: `connect({ log, logLevel, redact })` и `up({ … })` — функция или объект-логгер (`console`, pino), порог `debug|info|warn|error|off` (по умолчанию `info`); без кода — `LETOPIS_LOG=info` (JSON-строки в stderr), CLI — `--log[=уровень]`. События `delete` и `restore` — что удалено и что не вернулось; внутри `db.begin()` событие значит «выполнено в транзакции», фиксацию доказывает `tx.commit` с тем же `tx`. Штатные отказы — событие `error` уровня `warn`, ошибки кода — уровня `error`.
+- Обслуживание — `maintain()` (администраторское подключение, системный администратор или право `letopis.maintain`, иначе `acl_denied`); загрузка — `db.load(rows)` с администраторского подключения; подписка — `db.watch({ from, classes })` и `await sub.ready()` перед записью.
+- MCP: `createMcpServer(await svc.as(пользователь, { tenant }))` из `letopis/mcp` и `letopis mcp` дают ИИ-агенту `letopis_model`, `letopis_query`, `letopis_history` и, с `write: true`, `letopis_write`; удаление подтверждает человек, удаляется ровно показанное превью.
+- Лицензия — PolyForm Noncommercial 1.0.0 (SPDX `PolyForm-Noncommercial-1.0.0`): исходный код доступен, некоммерческое использование бесплатно, коммерческое — только по отдельной лицензии владельца (запрос — issue на https://github.com/alepri51/letopis/issues).
+
+## Документы
+
+- [Памятка для агента](AGENT-CHEATSHEET.md): общие правила для любой задачи на letopis, рабочий цикл одной программой и грабли
+- [Руководство](README.md): руководство по задачам, справочник API, ограничения
+- [Безопасность по умолчанию](README.md#безопасность-по-умолчанию): что отклоняется без сверки и как это сделать осознанно
+- [Логирование](README.md#логирование): опции, уровни, `LETOPIS_LOG`, формат события, маскировка, список событий
+- [Ошибки](README.md#15-ошибки): все коды и ключи — что значит, что делать и что сказать человеку
+- Машинный каталог API и ошибок — `api-contract.json` в пакете (`node_modules/letopis/api-contract.json`)
+
+## Дополнительно
+
+- [Изменения по версиям](CHANGELOG.md): что изменилось при переходе на 3.0 и чем заменить снятое
+- [Лицензия](LICENSE) и [коммерческое использование](LICENSE-COMMERCIAL.md): что можно без разрешения и как получить коммерческую лицензию
+- Модель конкретной установки для агента — инструмент MCP `letopis_model`: классы, ключи, поля, концы и рабочие цепочки этой схемы

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "letopis",
-  "version": "1.4.2",
-  "description": "Letopis (летопись): versioned entity store on PostgreSQL 18 — integrity, history, tenants and access control enforced by the database itself, dot-notation chains on top",
+  "version": "3.0.0",
+  "description": "Letopis (летопись): хранилище версионированных сущностей на PostgreSQL 18 — целостность, история, арендаторы и права проверяет сама база, поверх — цепочки через точку. ИИ-агенту — AGENT-CHEATSHEET.md и llms.txt в пакете; исходный код доступен (PolyForm Noncommercial 1.0.0)",
   "keywords": [
     "postgres",
     "postgresql",
@@ -14,9 +14,12 @@
     "jsonb",
     "multi-tenant",
     "acl",
-    "uuidv5"
+    "uuidv5",
+    "llms-txt",
+    "ai-agents",
+    "agent-cheatsheet"
   ],
-  "license": "MIT",
+  "license": "PolyForm-Noncommercial-1.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alepri51/letopis.git",
@@ -51,23 +54,23 @@
     "dist",
     "sql",
     "README.md",
-    "README.en.md",
     "AGENT-CHEATSHEET.md",
-    "AGENT-CHEATSHEET.en.md",
     "llms.txt",
+    "api-contract.json",
     "CHANGELOG.md",
-    "MIGRATION.md",
-    "LICENSE"
+    "LICENSE",
+    "LICENSE-COMMERCIAL.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "typecheck:all": "tsc --noEmit",
     "test": "tsx --test --test-concurrency=1 --test-force-exit test/*.test.ts",
     "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",
+    "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",
@@ -102,10 +105,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",
-    "letopis-141": "npm:letopis@1.4.1",
     "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,15 +56,20 @@ 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;
+    -- аккаунта нет (не заводили или удалён) — «не найден», а не «нельзя» (3.0): сервис с правом имперсонации отличит
+    -- опечатку в id от запрета
+    if a.id is null then
+      perform @SCHEMA@.lt_fail('sql-core.impersonation_no_account', jsonb_build_object('id', imp));
+    end if;
     -- от имени System, сервисов, системных администраторов и отключённых аккаунтов действовать нельзя
-    if a.id is null or not coalesce((a.data->>'enabled')::boolean, true) or a.id = '@SYSTEM@'::uuid
+    if not coalesce((a.data->>'enabled')::boolean, true) or a.id = '@SYSTEM@'::uuid
        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 +78,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 +91,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;
@@ -119,7 +124,7 @@ begin
 end $$;
 
 -- Вход по API-ключу (APIKEY): префикс ищется в ident, ключ сверяется по sha256. Сессия помнит ключ
--- (meta.cred): отзыв ключа гасит только его сессии.
+-- (meta.cred): отзыв ключа гасит только его сессии. Вход и отзыв синхронизированы по строке ключа (for share).
 create or replace function @SCHEMA@.login_apikey(p_key text) returns text
 language plpgsql volatile security definer
 set search_path = pg_catalog, @SCHEMA@, pg_temp
@@ -135,9 +140,13 @@ begin
     and s.material = sha256(convert_to(p_key, 'UTF8'))
     and (s.expires_at is null or s.expires_at > clock_timestamp())
     and coalesce((s.meta->>'enabled')::boolean, true)
-    and coalesce((a.data->>'enabled')::boolean, true);
+    and coalesce((a.data->>'enabled')::boolean, true)
+  -- строка ключа — под блокировкой до конца транзакции входа: отзыв (auth_revoke_credential) ждёт её
+  -- фиксации и гасит открытую здесь сессию, а вход после отзыва ключа не находит
+  for share of s;
   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 $$;