letopis 1.4.2 → 3.0.0

package/dist/messages/boot.js

@@ -0,0 +1,256 @@
+/** Подсказка отказов up({ login }): что передать. */
+const LOGIN = 'передать login: { user, password } — имя обычной роли входа (непустое, до 63 байт, не pg_…) и её пароль (непустая строка)';
+/** Подсказка отказов user.roles в createTenant() и up({ tenant }). */
+const ROLES = "передать user.roles — список разных имён ролей членства, например ['staff'], или не передавать: по умолчанию ['owner']";
+/** Подсказка отказов createTenant() об удалённой строке. */
+const GONE = 'вернуть удалённое restore({ expect }) — надгробие из withDeleted().rows() (текст называет, кто это может) или выбрать другое имя или логин: id вычисляется из них';
+export const boot = {
+    // up.ts, substitute(): в тексте SQL (ядро, миграция, свой сид) маркер, которого установщик не знает
+    'boot.unknown_marker': {
+        code: 'invalid_data',
+        ru: 'up: неизвестный маркер {marker} в SQL',
+        hint: 'в своём сиде — только маркеры установщика (@SCHEMA@, @OWNER@, @APP@, @SYSTEM@ и другие — таблица в sql/README.md пакета)',
+    },
+    // up.ts, install(): имя схемы не вида v<N>.<имя>
+    'boot.install_schema_name': {
+        code: 'invalid_data',
+        ru: 'up: bad schema name "{schema}" (нужно v<N>.<имя>)',
+        hint: 'полное имя схемы — v<N>.<имя>: имя из строчных латинских букв, цифр и «_», не с цифры, например v2.salon',
+    },
+    // up.ts, install(): имя роли владельца или приложения (опции owner, app) не по правилу
+    'boot.role_name': {
+        code: 'invalid_data',
+        ru: 'up: bad role name "{role}"',
+        hint: 'имя роли (owner, app) — строчные латинские буквы, цифры и «_», не с цифры, до 63 знаков; по умолчанию letopis_owner и letopis_app',
+    },
+    // up.ts, install(): режим сигналов не из списка; modes — допустимые через запятую
+    'boot.signals_mode': {
+        code: 'invalid_data',
+        ru: 'up: signals — {modes}, а не {signals}',
+        hint: "передать signals: 'class' (по умолчанию у новой схемы), 'tenant', 'opaque' или 'none' — или не передавать: up() оставит режим схемы",
+    },
+    // up.ts, install(): роль владельца создал кто-то другой, а у установщика нет на неё ADMIN OPTION (план 2.0, 7.5 №3)
+    'boot.owner_no_admin': {
+        code: 'admin_required',
+        ru: 'up: роль {owner} уже есть, а у установщика нет на неё ADMIN OPTION — установку ведёт роль, создавшая {owner}, или роль с этим правом (grant {owner} to <установщик> with admin option)',
+        hint: 'запустить up() ролью, создавшей роль владельца, или суперпользователем — либо выдать установщику grant <владелец> to <установщик> with admin option',
+    },
+    // up.ts, install(): имя сида пакета (не путь к .sql) не по правилу
+    'boot.seed_name': {
+        code: 'invalid_data',
+        ru: 'up: bad seed name "{seed}"',
+        hint: "сид пакета — имя из строчных латинских букв, цифр и «-» (например, 'booking'), свой сид — путь к файлу .sql",
+    },
+    // up.ts, install(): свой ключ сервиса (serviceKey) не по формату
+    'boot.service_key_format': {
+        code: 'invalid_data',
+        ru: 'up: serviceKey — lts_ и не меньше 32 шестнадцатеричных знаков',
+        hint: 'передать serviceKey вида lts_ и 32–128 шестнадцатеричных знаков в нижнем регистре — или не передавать: up() выпустит ключ сам',
+    },
+    // up.ts, up(): имя схемы ни <имя>, ни v<N>.<имя>
+    'boot.up_schema_name': {
+        code: 'invalid_data',
+        ru: 'up: bad schema name "{schema}" (нужно <имя> или v<N>.<имя>)',
+        hint: 'имя схемы — <имя> (версия структуры подставится сама) или v<N>.<имя>; имя — строчные латинские буквы, цифры и «_», не с цифры: например, salon или v2.salon',
+    },
+    // up.ts, up(): нет ни dsn, ни sql, ни pglite
+    'boot.no_connection': {
+        code: 'invalid_data',
+        ru: 'up: нужен dsn или sql',
+        hint: 'передать dsn — строку подключения администратора, sql — готовый пул postgres.js или pglite: true для разработки без своего сервера',
+    },
+    // up.ts, up({ login }): login — не объект
+    'boot.login_not_object': {
+        code: 'invalid_data',
+        ru: 'up({ login }): нужен объект { user, password }',
+        hint: LOGIN,
+    },
+    // up.ts, up({ login }): имя роли пустое, длиннее 63 байт, с pg_ или нулевым байтом; user — значение в JSON
+    'boot.login_user': {
+        code: 'invalid_data',
+        ru: 'up({ login }): user {user} — имя роли: непустое, до 63 байт, не pg_…',
+        hint: LOGIN,
+    },
+    // up.ts, up({ login }): пароль — не строка, пустой или с нулевым байтом
+    'boot.login_password': {
+        code: 'invalid_data',
+        ru: 'up({ login }): password — непустая строка',
+        hint: LOGIN,
+    },
+    // up.ts, up({ login }): роль привилегированная, роль-владелец или сама роль приложения — её пароль не меняется
+    'boot.login_privileged': {
+        code: 'invalid_data',
+        ru: 'up({ login }): роль {user} — привилегированная (суперпользователь, CREATEROLE, CREATEDB, REPLICATION, BYPASSRLS, роль-владелец или её член) или сама роль приложения: роль приложения — обычная роль входа, привилегированную up() не трогает',
+        hint: 'выбрать для login другое имя — роль без этих атрибутов и без членства в роли владельца',
+    },
+    // up.ts, createTenant() и up({ tenant }): нет имени арендатора
+    'boot.tenant_name_required': {
+        code: 'invalid_data',
+        ru: 'createTenant: имя арендатора обязательно',
+        hint: 'передать name — имя арендатора: из него вычисляется id, поэтому одно имя — всегда один и тот же арендатор',
+    },
+    // up.ts, createTenant() и up({ tenant }): вид пароля user.kind не по правилу функций кредов; kind — значение в JSON,
+    // kinds — служебные виды через запятую
+    'boot.tenant_kind': {
+        code: 'invalid_data',
+        ru: 'createTenant: user.kind {kind} — вид пароля: заглавная латинская буква, затем заглавные буквы, цифры или «_», всего от 2 до 32 знаков; служебные виды {kinds} заняты (по умолчанию — PASSWORD)',
+        hint: "не передавать user.kind (вход по паролю — вид PASSWORD) или передать вид по правилу auth.setPassword, например 'PIN'",
+    },
+    // up.ts, createTenant() и up({ tenant }): user.roles — не список или пустой
+    'boot.tenant_roles_empty': {
+        code: 'invalid_data',
+        ru: "createTenant: user.roles — непустой список ролей, например ['staff']",
+        hint: ROLES,
+    },
+    // up.ts, createTenant() и up({ tenant }): роль в user.roles — не строка; type — null или typeof значения
+    'boot.tenant_role_type': {
+        code: 'invalid_data',
+        ru: 'createTenant: user.roles — роль — строка, а не {type}',
+        hint: ROLES,
+    },
+    // up.ts, createTenant() и up({ tenant }): роль — маска группы, пустая или с пробелами по краям; role — значение в JSON
+    'boot.tenant_role_mask': {
+        code: 'invalid_data',
+        ru: 'createTenant: user.roles — роль {role}: нужно имя роли, а не маска группы — не пустое, без пробелов по краям, запятых, фигурных скобок и «!» в начале',
+        hint: ROLES,
+    },
+    // up.ts, createTenant() и up({ tenant }): роли в user.roles повторяются
+    'boot.tenant_roles_repeat': {
+        code: 'invalid_data',
+        ru: 'createTenant: user.roles — роли повторяются',
+        hint: ROLES,
+    },
+    // up.ts, createTenant(): строки арендатора нет, а его история в журнале есть
+    'boot.tenant_deleted': {
+        code: 'invalid_data',
+        ru: 'createTenant: арендатор «{name}» ({id}) удалён, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.Account(id).restore({ expect: await db.Account(id).withDeleted().rows() }) от имени системного администратора или выберите другое имя',
+        hint: GONE,
+    },
+    // up.ts, createTenant(): строки аккаунта пользователя нет, а его история в журнале есть
+    'boot.tenant_user_deleted': {
+        code: 'invalid_data',
+        ru: 'createTenant: аккаунт пользователя {login} ({id}) удалён, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.Account(id).restore({ expect: await db.Account(id).withDeleted().rows() }) от имени системного администратора или выберите другой логин',
+        hint: GONE,
+    },
+    // up.ts, createTenant(): строки членства нет, а его история в журнале есть
+    'boot.tenant_member_deleted': {
+        code: 'invalid_data',
+        ru: 'createTenant: членство {login} в арендаторе «{name}» ({id}) удалено, а его история осталась в журнале — повтор удалённое не воскрешает: верните его db.member(id).restore({ expect: await db.member(id).withDeleted().rows() }) в этом арендаторе или выберите другой логин',
+        hint: GONE,
+    },
+    // up.ts, refuse1x(): схема letopis 1.x — ревизия из комментария схемы ниже первой ревизии 2.0 (FIRST_REVISION) или
+    // штампа ревизии нет (rev 0); отказ up() — до любых изменений, connect() — до входа по ключу (план 2.0, 7.10 №5).
+    // first — FIRST_REVISION
+    'boot.schema_1x': {
+        code: 'invalid_data',
+        ru: "схема {schema} ревизии {rev}, а 2.0 — с ревизии {first}: это схема letopis 1.x (или схема без штампа ревизии), 2.0 ставится только заново — up({ schema: '{schema}', fresh: true }) пересоздаст схему, данные 1.x не переносятся",
+        hint: 'схема letopis 1.x: 2.0 ставится только заново — up({ fresh: true }) пересоздаст схему, данные 1.x не переносятся',
+    },
+    // up.ts и pglite.ts: обычный Error с префиксом letopis.up (подходящего кода нет) — текст по записи (lmsg), код записи при
+    // броске не берётся
+    // up.ts, install(): сервер ниже PostgreSQL 18; version — server_version_num
+    'boot.install_pg_version': {
+        code: 'invalid_query',
+        ru: 'нужен PostgreSQL 18 или новее, а сервер — {version}',
+    },
+    // up.ts, checkServer(): сервер ниже PostgreSQL 18; major — основная версия, num — server_version_num
+    'boot.pg_version': {
+        code: 'invalid_query',
+        ru: 'нужен PostgreSQL 18 или новее, а сервер — {major} ({num})',
+    },
+    // up.ts, checkServer(): база не в UTF8
+    'boot.encoding': {
+        code: 'invalid_query',
+        ru: 'база в кодировке {encoding}, нужна UTF8 (casefold и коллация pg_unicode_fast)',
+    },
+    // up.ts, up(): база не ответила за waitTimeoutMs; host — хост строки подключения, seconds — срок в секундах
+    'boot.wait_timeout': {
+        code: 'invalid_query',
+        ru: 'база {host} не готова за {seconds} с',
+    },
+    // up.ts, up(): ревизия схемы новее пакета; rev — ревизия схемы, known — DDL_REVISION
+    'boot.schema_newer': {
+        code: 'invalid_data',
+        ru: 'схема {schema} ревизии {rev}, а библиотека знает только {known} — обновите пакет',
+    },
+    // up.ts, up(): ревизия схемы 2.x старше пакета, а upgrade нет; want — DDL_REVISION
+    'boot.schema_older': {
+        code: 'invalid_data',
+        ru: "схема {schema} ревизии {rev}, библиотека — {want}: обновите её up({ schema: '{schema}', upgrade: true })",
+    },
+    // pglite.ts, startPglite(): нет пакета PGlite; name — имя пакета
+    'boot.pglite_package': {
+        code: 'invalid_query',
+        ru: 'для pglite нужен пакет {name} — npm i -D @electric-sql/pglite @electric-sql/pglite-socket',
+    },
+    // up.ts, checkServer(): предупреждение (UpResult.warnings, lmsg) — сервер ниже 18.2; version — вида 18.1
+    'boot.pg_clog': {
+        code: 'invalid_query',
+        ru: 'PostgreSQL {version}: до 18.2 сервер мог усечь CLOG, который ещё нужен непрочитанным сигналам NOTIFY; обновите сервер до 18.2 или новее',
+    },
+    // up.ts, up(): предупреждение (UpResult.warnings) — после ANALYZE от роли владельца у таблиц всё ещё нет статистики;
+    // tables — схема.таблица через запятую
+    'boot.analyze_skipped': {
+        code: 'invalid_query',
+        ru: 'таблицы без статистики после ANALYZE от роли владельца {owner}: {tables} — проверьте, что они принадлежат ей; иначе статистику соберёт автоочистка или ANALYZE их владельца',
+    },
+    // up.ts, up(): предупреждение (UpResult.warnings) — в схеме есть хабы с именами из RESERVED_CLASS_NAMES, заведённые
+    // мимо проверки базы (план 2.0, этап 4, п. 2; 7.10 №3): up() их оставляет; hubs — «имя (арендатор)» через запятую
+    'boot.reserved_hubs': {
+        code: 'invalid_class',
+        ru: 'хабы с зарезервированными именами: {hubs} — имя занято методом цепочки или корня db, шаг с ним до класса может не дойти; с 2.0 такой хаб не создаётся, а его описание не меняется: переименуйте класс — заведите класс с другим именем и создайте в нём объекты заново',
+    },
+    // up.ts, stampDrift(): предупреждение connect() (его печатает index.ts) — схему той же ревизии обновила более новая
+    // версия; was — версия из штампа схемы, version — версия пакета
+    'boot.stamp_newer': {
+        code: 'invalid_data',
+        ru: 'схему {schema} обновила letopis {was}, библиотека старее ({version}) — обновите пакет: up() этой версией вернул бы прежние функции',
+    },
+    // up.ts, stampDrift(): функции схемы той же ревизии поставила другая версия — по записи на того, кто поставил:
+    // неизвестная версия (в штампе нет engine=: комментарий правили руками), другая сборка той же версии, другая версия
+    'boot.stamp_unknown': {
+        code: 'invalid_data',
+        ru: "функции схемы {schema} поставила неизвестная версия letopis (в штампе нет версии движка), библиотека — {version}: обновите схему — вызовите up({ schema: '{schema}' })",
+    },
+    'boot.stamp_other_build': {
+        code: 'invalid_data',
+        ru: "функции схемы {schema} поставила другая сборка letopis {was}, библиотека — {version}: обновите схему — вызовите up({ schema: '{schema}' })",
+    },
+    'boot.stamp_other_version': {
+        code: 'invalid_data',
+        ru: "функции схемы {schema} поставила letopis {was}, библиотека — {version}: обновите схему — вызовите up({ schema: '{schema}' })",
+    },
+    // up.ts: ход установки в консоли (lmsg, префикс letopis.up добавляет up()) — тексты не для ошибки, код не печатается.
+    // ensureDatabase(): база создана
+    'boot.log_database_created': {
+        code: 'invalid_query',
+        ru: 'база {name} создана',
+    },
+    // up({ fresh })
+    'boot.log_fresh': {
+        code: 'invalid_query',
+        ru: 'схема {schema} удалена и поставлена заново (fresh)',
+    },
+    // итог наката — по записи на исход; revision — ревизия после наката, from — до (у обновления)
+    'boot.log_installed': {
+        code: 'invalid_query',
+        ru: 'схема поставлена: {schema}, ревизия {revision}',
+    },
+    'boot.log_upgraded': {
+        code: 'invalid_query',
+        ru: 'схема обновлена с ревизии {from}: {schema}, ревизия {revision}',
+    },
+    'boot.log_reapplied': {
+        code: 'invalid_query',
+        ru: 'повторный накат: {schema}, ревизия {revision}',
+    },
+    // up({ login }): роль приложения заведена или получила новый пароль
+    'boot.log_login_created': {
+        code: 'invalid_query',
+        ru: 'роль приложения {user}: заведена',
+    },
+    'boot.log_login_updated': {
+        code: 'invalid_query',
+        ru: 'роль приложения {user}: пароль обновлён',
+    },
+};

package/dist/messages/codes.d.ts

@@ -0,0 +1,172 @@
+export declare const codes: {
+    'codes.no_session': {
+        code: "no_session";
+        ru: string;
+        hint: string;
+    };
+    'codes.target_not_found': {
+        code: "target_not_found";
+        ru: string;
+        hint: string;
+    };
+    'codes.invalid_data': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
+    'codes.undeclared_end': {
+        code: "undeclared_end";
+        ru: string;
+        hint: string;
+    };
+    'codes.tenant_denied': {
+        code: "tenant_denied";
+        ru: string;
+        hint: string;
+    };
+    'codes.acl_denied': {
+        code: "acl_denied";
+        ru: string;
+        hint: string;
+    };
+    'codes.id_mismatch': {
+        code: "id_mismatch";
+        ru: string;
+        hint: string;
+    };
+    'codes.id_from_db': {
+        code: "id_from_db";
+        ru: string;
+        hint: string;
+    };
+    'codes.immutable_key': {
+        code: "immutable_key";
+        ru: string;
+        hint: string;
+    };
+    'codes.invalid_class': {
+        code: "invalid_class";
+        ru: string;
+        hint: string;
+    };
+    'codes.tightening_conflict': {
+        code: "tightening_conflict";
+        ru: string;
+        hint: string;
+    };
+    'codes.isolation_level': {
+        code: "isolation_level";
+        ru: string;
+        hint: string;
+    };
+    'codes.recreated_in_statement': {
+        code: "recreated_in_statement";
+        ru: string;
+        hint: string;
+    };
+    'codes.delete_restricted': {
+        code: "delete_restricted";
+        ru: string;
+        hint: string;
+    };
+    'codes.not_deleted': {
+        code: "not_deleted";
+        ru: string;
+        hint: string;
+    };
+    'codes.exists': {
+        code: "exists";
+        ru: string;
+        hint: string;
+    };
+    'codes.duplicate': {
+        code: "duplicate";
+        ru: string;
+        hint: string;
+    };
+    'codes.deleted': {
+        code: "deleted";
+        ru: string;
+        hint: string;
+    };
+    'codes.conflict': {
+        code: "conflict";
+        ru: string;
+        hint: string;
+    };
+    'codes.rev_ambiguous': {
+        code: "rev_ambiguous";
+        ru: string;
+        hint: string;
+    };
+    'codes.tx_required': {
+        code: "tx_required";
+        ru: string;
+        hint: string;
+    };
+    'codes.lock_unsupported': {
+        code: "lock_unsupported";
+        ru: string;
+        hint: string;
+    };
+    'codes.commit_unknown': {
+        code: "commit_unknown";
+        ru: string;
+        hint: string;
+    };
+    'codes.tx_rolled_back': {
+        code: "tx_rolled_back";
+        ru: string;
+        hint: string;
+    };
+    'codes.no_key': {
+        code: "no_key";
+        ru: string;
+        hint: string;
+    };
+    'codes.no_path': {
+        code: "no_path";
+        ru: string;
+        hint: string;
+    };
+    'codes.invalid_query': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
+    'codes.admin_required': {
+        code: "admin_required";
+        ru: string;
+        hint: string;
+    };
+    'codes.not_empty': {
+        code: "not_empty";
+        ru: string;
+        hint: string;
+    };
+    'codes.class_not_loadable': {
+        code: "class_not_loadable";
+        ru: string;
+        hint: string;
+    };
+    'codes.bypass_rls': {
+        code: "bypass_rls";
+        ru: string;
+        hint: string;
+    };
+    'codes.user_session_required': {
+        code: "user_session_required";
+        ru: string;
+        hint: string;
+    };
+    'codes.confirmation_required': {
+        code: "confirmation_required";
+        ru: string;
+        hint: string;
+    };
+    'codes.internal': {
+        code: "internal";
+        ru: string;
+        hint: string;
+    };
+};

package/dist/messages/codes.js

@@ -0,0 +1,173 @@
+export const codes = {
+    'codes.no_session': {
+        code: 'no_session',
+        ru: 'нет действующей сессии',
+        hint: 'войти заново: истёкшую или отозванную сессию не вернуть',
+    },
+    'codes.target_not_found': {
+        code: 'target_not_found',
+        ru: 'цель не найдена — одинаково для несуществующей, чужой и невидимой',
+        hint: 'проверить id и права: чужой и невидимый объект неотличим от несуществующего',
+    },
+    'codes.invalid_data': {
+        code: 'invalid_data',
+        ru: 'данные не подходят к описанию класса; подробности — в `issues`',
+        hint: 'исправить данные по `issues` (путь, правило, сообщение); проверить до отправки — `compileValidator`',
+    },
+    'codes.undeclared_end': {
+        code: 'undeclared_end',
+        ru: 'у класса нет такого конца (ссылки)',
+        hint: 'объявить конец в модели класса (`ends`) или исправить имя роли',
+    },
+    'codes.tenant_denied': {
+        code: 'tenant_denied',
+        ru: 'чужой арендатор или нет членства в нём',
+        hint: 'работать в арендаторе, где у пользователя есть членство, — сменить его `auth.switch()`',
+    },
+    'codes.acl_denied': {
+        code: 'acl_denied',
+        ru: 'правила доступа запрещают это действие',
+        hint: 'выдать право `db.acl.grant` (правила — класс `rule`) или выполнить действие от пользователя, которому оно разрешено; проверить заранее — `db.acl.checkData`, `db.acl.check`',
+    },
+    'codes.id_mismatch': {
+        code: 'id_mismatch',
+        ru: 'переданный id не совпадает с id, вычисленным из ключа',
+        hint: 'не передавать `id` у класса с ключом — база вычислит его из ключа; узнать заранее — `db.idOf(класс, ключ)`',
+    },
+    'codes.id_from_db': {
+        code: 'id_from_db',
+        ru: 'у класса без ключа id выдаёт база — свой id передавать нельзя',
+        hint: 'не передавать `id` — база выдаст его сама; нужен постоянный id — дать классу ключ',
+    },
+    'codes.immutable_key': {
+        code: 'immutable_key',
+        ru: 'ключевые поля, класс, id, арендатора и владельца правкой не изменить',
+        hint: 'ключ, класс, id, арендатор и владелец строки неизменны: объект с другим ключом или классом — новый объект (`create`)',
+    },
+    'codes.invalid_class': {
+        code: 'invalid_class',
+        ru: 'описание класса отклонено, класс не найден или абстрактный, либо удаляют класс, у которого есть строки, потомки или история',
+        hint: 'проверить имя (`db.registry.has`) и описание класса (`syncModels` без `apply` покажет план); удалить класс можно только без строк, потомков и истории',
+    },
+    'codes.tightening_conflict': {
+        code: 'tightening_conflict',
+        ru: 'ужесточению модели мешают строки, которые ей не подходят',
+        hint: 'исправить или удалить строки из списка ошибки и снова вызвать `syncModels`',
+    },
+    'codes.isolation_level': {
+        code: 'isolation_level',
+        ru: 'удаление работает только на уровне `read committed`',
+        hint: 'удалять в транзакции уровня `read committed` — он стоит по умолчанию',
+    },
+    'codes.recreated_in_statement': {
+        code: 'recreated_in_statement',
+        ru: 'объект удалён и создан заново одним оператором',
+        hint: 'удалить и создать объект разными операторами',
+    },
+    'codes.delete_restricted': {
+        code: 'delete_restricted',
+        ru: 'удалить нельзя: на объект ссылаются строки с действием при удалении `restrict`',
+        hint: 'сначала удалить или перевести ссылающиеся строки — или сменить у их конца действие при удалении (`onDelete`)',
+    },
+    'codes.not_deleted': {
+        code: 'not_deleted',
+        ru: '`restore` работает только для удалённых объектов',
+        hint: 'сначала `delete({ confirm: true, expect })`, потом `restore({ expect })` с надгробиями из ответа `delete()` или `withDeleted().rows()`',
+    },
+    'codes.exists': {
+        code: 'exists',
+        ru: 'объект с таким id уже существует',
+        hint: 'при повторе операции с ключом это ответ «уже записано»; иначе — `update`, `upsert` или другой ключ',
+    },
+    'codes.duplicate': {
+        code: 'duplicate',
+        ru: 'загрузчик: id повторяется во входных данных',
+        hint: 'убрать повторы id из входных данных: первые 100 — в `detail.rows`',
+    },
+    'codes.deleted': {
+        code: 'deleted',
+        ru: 'загрузчик: объект с этим id уже жил раньше и был удалён',
+        hint: "загрузить с `existing: 'update'` — объект оживёт новой версией — или дать ему другой id",
+    },
+    'codes.conflict': {
+        code: 'conflict',
+        ru: 'то, что вы видели, уже изменилось — ничего не записано: `update` с `{ rev }` (строку изменили после чтения, `write.rev_conflict`), `delete({ confirm: true, expect })` (превью изменилось, `write.preview_changed`; в том числе цели уже удалены или не найдены — `detail.preview: []`), `restore({ expect })` (объект меняли после удаления, `write.restore_stale`)',
+        hint: 'перечитать и повторить с новыми данными: `update` — с новым `rev` (для чисел — `inc` вместо записи итога); `delete` — показать новое превью `err.detail.preview` и удалить с ним; `restore` — сообщить пользователю (вещь уже у другого) или `restore({ expect, partial: true })`',
+    },
+    'codes.rev_ambiguous': {
+        code: 'rev_ambiguous',
+        ru: '`{ rev }` указан у шага, который выбрал больше одного объекта',
+        hint: 'сузить шаг до одной строки (id или ключ) или убрать `{ rev }`',
+    },
+    'codes.tx_required': {
+        code: 'tx_required',
+        ru: '`forUpdate()`, `lock()`, `commit()` и `rollback()` работают только внутри `db.begin()`',
+        hint: 'вызывать внутри транзакции: `const tr = await db.begin()` … `await tr.commit()`',
+    },
+    'codes.lock_unsupported': {
+        code: 'lock_unsupported',
+        ru: '`forUpdate()` нельзя сочетать с агрегатом, `asOf`, `versions`, `withDeleted`, `deep` или глаголом',
+        hint: 'брать `forUpdate()` в простом чтении строк, а итоги, срезы и правки делать отдельными шагами',
+    },
+    'codes.commit_unknown': {
+        code: 'commit_unknown',
+        ru: 'связь оборвалась во время `COMMIT` — неизвестно, записалась ли транзакция',
+        hint: 'повторить ту же операцию с тем же ключом: `exists` — она уже записана, успех — в первый раз не записалась; без ключа исход не выяснить, поэтому операциям с деньгами нужен ключ',
+    },
+    'codes.tx_rolled_back': {
+        code: 'tx_rolled_back',
+        ru: 'PostgreSQL откатил транзакцию на `COMMIT`: ошибку перехватили внутри `tr.transaction(fn)`',
+        hint: 'не глушить ошибки внутри `tr.transaction(fn)`: устранить причину и повторить весь блок',
+    },
+    'codes.no_key': {
+        code: 'no_key',
+        ru: 'у класса нет ключа, а `upsert` и `idOf` без ключа не работают',
+        hint: 'дать классу ключ (`key` в модели) или работать по id: `update` вместо `upsert`',
+    },
+    'codes.no_path': {
+        code: 'no_path',
+        ru: 'между классами соседних шагов цепочки нет перехода',
+        hint: 'переходить по объявленным концам: между классами шагов нужна ссылка, роль конца — имя шага',
+    },
+    'codes.invalid_query': {
+        code: 'invalid_query',
+        ru: 'цепочка или вызов API построены неверно',
+        hint: 'исправить цепочку или вызов: текст ошибки называет неверный шаг или аргумент',
+    },
+    'codes.admin_required': {
+        code: 'admin_required',
+        ru: 'нужно подключение администратора: его требует загрузчик',
+        hint: 'запускать загрузчик на администраторском подключении (`allowBypassRls: true`) в отдельном процессе',
+    },
+    'codes.not_empty': {
+        code: 'not_empty',
+        ru: 'первая заливка возможна только в пустую схему',
+        hint: 'первую заливку делать в новую схему (`up({ fresh: true })`), в заполненную — загрузка без `initial`',
+    },
+    'codes.class_not_loadable': {
+        code: 'class_not_loadable',
+        ru: 'загрузчик не принимает строки классов (`Class`) — классы записывает `syncModels`',
+        hint: 'классы записывать `syncModels`, а загрузчику передавать только строки данных',
+    },
+    'codes.bypass_rls': {
+        code: 'bypass_rls',
+        ru: 'роль подключения обходит RLS: `connect()` без `allowBypassRls` или сервер MCP поверх такого подключения',
+        hint: 'подключать приложение отдельной ролью из группы `letopis_app`; администраторскому подключению — `allowBypassRls: true`; сервер MCP — только поверх подключения приложения',
+    },
+    'codes.user_session_required': {
+        code: 'user_session_required',
+        ru: 'серверу MCP нужна сессия пользователя, а не ключ сервиса или пустое подключение',
+        hint: 'создавать сервер MCP на подключении пользователя (`svc.as(…)` или `connect({ token })`), а не на корне сервиса',
+    },
+    'codes.confirmation_required': {
+        code: 'confirmation_required',
+        ru: 'MCP: удаление не подтвердил человек',
+        hint: 'подтвердить удаление в клиенте MCP; клиенту, который не умеет спрашивать человека, удаление недоступно',
+    },
+    // SQLSTATE XX000 с ключом каталога в DETAIL: база не держит условие, которое обязана держать сама (строка-замок)
+    'codes.internal': {
+        code: 'internal',
+        ru: 'внутренняя ошибка letopis: база не держит условие, которое обязана держать сама (например, нет строки-замка)',
+        hint: 'это ошибка letopis: сообщите о ней с текстом, кодом и версией пакета',
+    },
+};