заведён реестр префиксов, правила канона перенумерованы

- идентификатор правила теперь `<ПРЕФИКС>-<номер>` вместо `R<номер>`:
  префикс уникален по всему канону, поэтому ссылка больше не требует пути
  к файлу и не зависит от того, на какой оси файл лежит
- префикс выбирается под файл, а не выводится по формуле, и хранится в
  conventions/prefixes.toml вместе с выбывшими; номера сохранены один в
  один вместе с дырами

conventions/lang/go/errors.md

@@ -1,3 +1,7 @@
+---
+prefix: GERR
+---
+
 # Ошибки
 
 Как ошибки строятся, оборачиваются и проверяются. Форма записи —
@@ -17,22 +21,22 @@
 
 ## Правила
 
-### R1. Ошибки строятся средствами стандартной библиотеки
+### GERR-1. Ошибки строятся средствами стандартной библиотеки
 
 **ДОЛЖЕН.** Ошибки создаются и оборачиваются через `errors` и
 `fmt.Errorf`; библиотеки со стек-трейсами не подключаются.
 
 **Почему.** Стек и цепочка обёрток решают одну задачу — локализацию места.
-При дисциплине «каждый слой добавляет свой контекст» (R3) цепочка сообщений
+При дисциплине «каждый слой добавляет свой контекст» (GERR-3) цепочка сообщений
 локализует не хуже, а стоит ничего: остальной контекст ошибки уже несёт
 `slog`. Библиотека со стеками добавляет зависимость, собственный тип ошибки
 и обычно инфраструктуру доставки стеков (Sentry) — для домашнего сервиса
 это цена без покупателя.
 
 Единственное место, где стек всё-таки нужен, — восстановленная паника: у
-неё цепочки `%w` нет вовсе (R23).
+неё цепочки `%w` нет вовсе (GERR-23).
 
-### R2. Дефолт не обходится точечно
+### GERR-2. Дефолт не обходится точечно
 
 **НЕ ДОЛЖЕН.** Пакет со стек-трейсами не заводится в отдельном месте
 кодовой базы ради конкретной отладки.
@@ -41,39 +45,39 @@
 перестаёт знать, какой перед ним: обёртки склеиваются по-разному,
 `errors.Is` работает не везде одинаково. Хуже второе: боль, снятая
 локально, перестаёт накапливаться — а накопление и есть единственный
-сигнал, что решение R1 пора пересматривать целиком.
+сигнал, что решение GERR-1 пора пересматривать целиком.
 
-### R3. Каждый слой добавляет свой контекст
+### GERR-3. Каждый слой добавляет свой контекст
 
 **ДОЛЖЕН.** Ошибка, возвращаемая на уровень выше, оборачивается с
 контекстом: `fmt.Errorf("parse magnet: %w", err)`.
 
-**Почему.** На этом держится R1: цепочка заменяет стек ровно настолько,
+**Почему.** На этом держится GERR-1: цепочка заменяет стек ровно настолько,
 насколько слои в неё пишут. Слой, пробросивший ошибку без своего контекста,
 стирает участок пути — по итоговому сообщению нельзя сказать, через какую
 операцию ошибка прошла, и отладка «no such file» начинается с чтения всего
 кода.
 
-### R4. Обёртка по умолчанию — `%w`
+### GERR-4. Обёртка по умолчанию — `%w`
 
 **СЛЕДУЕТ.** Глагол выбирается по тому, раскрываем ли мы причину
 вызывающему:
 
 | № | Ситуация | Глагол |
 |---|---|---|
-| R4.1 | вызывающий может инспектировать причину (обычный случай) | `%w` |
-| R4.2 | причину сознательно не раскрываем | `%v` |
+| GERR-4.1 | вызывающий может инспектировать причину (обычный случай) | `%w` |
+| GERR-4.2 | причину сознательно не раскрываем | `%v` |
 
 **Почему.** Возражение против дефолтного `%w` — «обёрнутая ошибка
 становится частью API» — относится к библиотекам с внешними потребителями.
 Сервис же — приложение: внешнего Go-API нет, весь код наш, контракт
 меняется вместе с вызывающими. Зато `%v` в середине цепочки обрывает
 `errors.Is` и `errors.As` для всех слоёв выше, и ветвление по sentinel'у
-(R10) молча перестаёт срабатывать — дефект проявляется как «код не заметил
-`ErrNotFound`», далеко от места обрыва. R4.2 остаётся для случая, когда
+(GERR-10) молча перестаёт срабатывать — дефект проявляется как «код не заметил
+`ErrNotFound`», далеко от места обрыва. GERR-4.2 остаётся для случая, когда
 завязывать вызывающего на чужой тип ошибки не хотят намеренно.
 
-### R5. Утечка внутренних деталей лечится трансляцией, а не `%v`
+### GERR-5. Утечка внутренних деталей лечится трансляцией, а не `%v`
 
 **НЕ ДОЛЖЕН.** `%v` не используется как средство не пустить внутреннюю
 ошибку наружу.
@@ -82,9 +86,9 @@
 целиком: наружу отдаёт внешняя граница, и если она отдаёт `err.Error()`,
 детали утекут при любом глаголе. Подмена не решает задачу, ради которой
 сделана, а плату берёт сразу — `errors.Is` ломается у всех вызывающих.
-Настоящее место защиты — R13.
+Настоящее место защиты — GERR-13.
 
-### R6. Текст обёртки — со строчной буквы и без служебных слов
+### GERR-6. Текст обёртки — со строчной буквы и без служебных слов
 
 **СЛЕДУЕТ.** Без точки в конце, без «failed to» и «error».
 
@@ -94,15 +98,15 @@
 нами ошибка, известно из того, что это ошибка. Зато повторяются они на
 каждом уровне и вытесняют из строки полезный контекст.
 
-### R7. Контекст обёртки называет операцию или субъект
+### GERR-7. Контекст обёртки называет операцию или субъект
 
 **СЛЕДУЕТ.** В обёртку идёт то, что делал слой: `"link target: %w"`.
 
-**Почему.** Обёртка ценна ровно тем, что сужает место (R3). «something
+**Почему.** Обёртка ценна ровно тем, что сужает место (GERR-3). «something
 failed» не сужает ничего и при этом занимает в сообщении место, которое мог
 бы занять единственный полезный здесь факт — имя операции.
 
-### R8. Слой не повторяет смысл нижнего
+### GERR-8. Слой не повторяет смысл нижнего
 
 **НЕ СЛЕДУЕТ.** Обёртка не пересказывает то, что уже сказал уровень ниже:
 `"add to qbt: %w"`, а не `"add download failed: add to qbt failed: …"`.
@@ -115,10 +119,10 @@ failed» не сужает ничего и при этом занимает в
 ## Две трансляции
 
 Ошибка меняет форму дважды, и это разные преобразования: инфраструктурная →
-доменная у источника (R9) и доменная → пользовательская на внешней границе
-(R13). Первую делает слой, работающий с зависимостью, вторую — транспорт.
+доменная у источника (GERR-9) и доменная → пользовательская на внешней границе
+(GERR-13). Первую делает слой, работающий с зависимостью, вторую — транспорт.
 
-### R9. Инфраструктурная ошибка транслируется в доменную у источника
+### GERR-9. Инфраструктурная ошибка транслируется в доменную у источника
 
 **ДОЛЖЕН.** Граничная ошибка зависимости превращается в доменную там, где
 возникла: `sql.ErrNoRows` → `store.ErrNotFound` в слое store; то же для
@@ -131,14 +135,14 @@ HTTP-клиентов, файловой системы, внешних SDK.
 состояние «нет записи» одно и то же. Трансляция у источника оставляет
 знание о зависимости в единственном слое, который её и так знает.
 
-### R10. Форма доменной ошибки выбирается по тому, что нужно вызывающему
+### GERR-10. Форма доменной ошибки выбирается по тому, что нужно вызывающему
 
 **ДОЛЖЕН.** Между sentinel'ом и типом выбирают так:
 
 | № | Что нужно вызывающему | Форма |
 |---|---|---|
-| R10.1 | ветвление по условию: нет записи, дубликат, неподдерживаемый источник | sentinel `var ErrNotFound = errors.New("not found")`, проверка `errors.Is` |
-| R10.2 | данные ошибки: поле валидации, код, лимит | тип с полями и методом `Error()`, извлечение `errors.As` |
+| GERR-10.1 | ветвление по условию: нет записи, дубликат, неподдерживаемый источник | sentinel `var ErrNotFound = errors.New("not found")`, проверка `errors.Is` |
+| GERR-10.2 | данные ошибки: поле валидации, код, лимит | тип с полями и методом `Error()`, извлечение `errors.As` |
 
 **Почему.** Sentinel — одно значение; сравнение с ним не зависит от
 структуры ошибки и переживает добавление полей. Тип заводится ради данных,
@@ -147,14 +151,14 @@ HTTP-клиентов, файловой системы, внешних SDK.
 каждой проверке. Две формы для одного условия — это два способа его
 проверить, и про второй рано или поздно забудут.
 
-### R11. Матчинг по тексту сообщения
+### GERR-11. Матчинг по тексту сообщения
 
 **НЕ ДОЛЖЕН.** Ветвление по содержимому `err.Error()` не используется.
 
-**Почему.** Текст сообщения — не контракт: R6–R8 разрешают переписывать его
-свободно. Правка формулировки в нижнем слое молча ломает ветвление
-наверху, и компилятор этого не видит. Это то же самое, что публичный API из
-строки лога.
+**Почему.** Текст сообщения — не контракт: GERR-6–GERR-8 разрешают
+переписывать его свободно. Правка формулировки в нижнем слое молча ломает
+ветвление наверху, и компилятор этого не видит. Это то же самое, что
+публичный API из строки лога.
 
 ## Граница: приватный канал и публичный
 
@@ -162,39 +166,39 @@ HTTP-клиентов, файловой системы, внешних SDK.
 того, кто канал видит: приватный канал — логи (их читает владелец сервиса),
 публичный — пользовательские поверхности (HTTP API, web-UI, бот).
 
-### R12. Полная ошибка идёт в приватный канал
+### GERR-12. Полная ошибка идёт в приватный канал
 
 **ДОЛЖЕН.** В лог уходит вся цепочка `%w` с контекстом; где и когда именно
 — `lang/go/logging.md`.
 
-**Почему.** Цепочка — единственный носитель диагностики (R1), и
+**Почему.** Цепочка — единственный носитель диагностики (GERR-1), и
 единственный канал, где её можно показать целиком, — тот, который видит
 владелец. Не записанная там, она не сохранится нигде: наружу идёт
-нейтральное сообщение (R13), и восстанавливать причину будет не из чего.
+нейтральное сообщение (GERR-13), и восстанавливать причину будет не из чего.
 
-### R13. Публичная поверхность получает сообщение по доменной ошибке
+### GERR-13. Публичная поверхность получает сообщение по доменной ошибке
 
 **ДОЛЖЕН.** Наружу идёт человекочитаемый текст по доменной ошибке, а не
 `err.Error()` и не детали реализации (`database/sql`, пути, стек).
 
 **Почему.** Внутренние детали пользователю нечитаемы, а владельцу не нужны
-— у него есть лог (R12). Зато они раскрывают устройство системы — имена
+— у него есть лог (GERR-12). Зато они раскрывают устройство системы — имена
 таблиц, пути на диске, версии зависимостей — тому, кто их знать не должен,
 причём раскрывают именно в момент, когда что-то пошло не так.
 
-### R14. Публичное сообщение несёт корреляционный ключ
+### GERR-14. Публичное сообщение несёт корреляционный ключ
 
 **ДОЛЖЕН.** Наружу вместе с сообщением идёт id сущности либо `request_id`:
 «При обработке загрузки произошла ошибка, download_id=…» вместо «произошла
 ошибка».
 
-**Почему.** R13 забирает у пользователя всю фактуру; без ключа его
+**Почему.** GERR-13 забирает у пользователя всю фактуру; без ключа его
 обращение звучит как «у меня что-то не работает», и владелец ищет запись в
 логе по времени и догадкам. Ключ соединяет нейтральный ответ с полной
 ошибкой в логе, не раскрывая наружу ничего сверх того, что пользователь уже
 видел.
 
-### R15. Маппинг доменных ошибок — в одной точке на все транспорты
+### GERR-15. Маппинг доменных ошибок — в одной точке на все транспорты
 
 **ДОЛЖЕН.** Соответствие «доменная ошибка → сообщение и, для HTTP, статус»
 задаётся один раз; транспорт без статусов (бот) берёт из него только
@@ -203,13 +207,13 @@ HTTP-клиентов, файловой системы, внешних SDK.
 **Почему.** Иначе одна и та же ошибка отвечает по-разному в HTTP и в боте,
 и расхождение обнаруживается не как дефект, а как жалоба. Вторая причина
 важнее: единственная точка — это место, куда механически дописывается новая
-ветвь (R16). Маппинг, размазанный по хендлерам, требование «дописать везде»
+ветвь (GERR-16). Маппинг, размазанный по хендлерам, требование «дописать везде»
 ничем не проверяет.
 
-### R16. Новая штатная ветвь отказа сразу попадает в маппинг
+### GERR-16. Новая штатная ветвь отказа сразу попадает в маппинг
 
 **ДОЛЖЕН.** Ожидаемый отказ (конфликт, валидация) заводится sentinel'ом и
-добавляется в маппинг (R15) тем же изменением.
+добавляется в маппинг (GERR-15) тем же изменением.
 
 **Почему.** Ветка `default` врёт в обе стороны: транспорт отдаёт 500
 «внутренняя ошибка» на нормальный конфликт, а логирующая граница списывает
@@ -219,14 +223,14 @@ HTTP-клиентов, файловой системы, внешних SDK.
 <!-- local:маппинг -->
 <!-- /local -->
 
-### R25. Непокрытая маппингом ошибка — 500 и `ERROR` с признаком
+### GERR-25. Непокрытая маппингом ошибка — 500 и `ERROR` с признаком
 
-**ДОЛЖЕН.** Доменная ошибка, для которой в маппинге (R15) нет ветви, отдаёт
+**ДОЛЖЕН.** Доменная ошибка, для которой в маппинге (GERR-15) нет ветви, отдаёт
 наружу 500 и нейтральное «внутренняя ошибка», а в лог идёт `ERROR` с
 признаком того, что маппинг её не знает.
 
 **Почему.** Непокрытая ошибка — не класс отказа, а дефект: ветвь забыли
-завести вопреки R16. Адресат у неё владелец в смысле «надо чинить», отсюда
+завести вопреки GERR-16. Адресат у неё владелец в смысле «надо чинить», отсюда
 `ERROR` — уровень выбирается по адресату (`lang/go/logging.md`). Статус
 тоже не выбирается: известное пользовательское состояние лежало бы в
 маппинге, а про неизвестное сказать пользователю нечего, поэтому 4xx
@@ -238,18 +242,18 @@ HTTP-клиентов, файловой системы, внешних SDK.
 находимым одним фильтром — и тогда громкость 500 и `ERROR` работает как
 механизм обнаружения, а не как шум.
 
-### R17. Форма текста определяется поверхностью
+### GERR-17. Форма текста определяется поверхностью
 
 **ДОЛЖЕН.** У публичной границы две разные поверхности, и правило сырого
 текста для них разное:
 
 | № | Поверхность | Текст ошибки |
 |---|---|---|
-| R17.1 | транзиентный ответ на действие: тело ответа, `?err=`, реплика бота по результату команды | строго нейтральный, из маппинга (R15); `err.Error()` наружу не идёт |
-| R17.2 | персистентная диагностика состояния: причина ухода записи в ошибочное состояние, сохранённая в БД и показанная оператору | сырой текст ошибки (пути, фрагмент ответа внешнего сервиса) — пока поверхность видит исключительно владелец |
+| GERR-17.1 | транзиентный ответ на действие: тело ответа, `?err=`, реплика бота по результату команды | строго нейтральный, из маппинга (GERR-15); `err.Error()` наружу не идёт |
+| GERR-17.2 | персистентная диагностика состояния: причина ухода записи в ошибочное состояние, сохранённая в БД и показанная оператору | сырой текст ошибки (пути, фрагмент ответа внешнего сервиса) — пока поверхность видит исключительно владелец |
 
 Появился второй зритель или публичный доступ к экрану состояния —
-поверхность стала публичным каналом, и на неё распространяется R17.1.
+поверхность стала публичным каналом, и на неё распространяется GERR-17.1.
 
 **Почему.** Транзиентный ответ читает тот, кто нажал кнопку: сырой текст
 ему ничего не объясняет, а владельцу не нужен — у него лог. Персистентную
@@ -259,7 +263,7 @@ HTTP-клиентов, файловой системы, внешних SDK.
 про единственного зрителя — ровно то, что делает вторую поверхность
 приватным каналом; без него это обычная публичная поверхность.
 
-### R18. Секретов нет ни на одной из поверхностей
+### GERR-18. Секретов нет ни на одной из поверхностей
 
 **НЕ ДОЛЖЕН.** Токены, пароли и ключи не попадают ни в транзиентный ответ,
 ни в персистентную диагностику; источник вычищается на границе клиента.
@@ -270,19 +274,19 @@ HTTP-клиентов, файловой системы, внешних SDK.
 известно, какие поля запроса секретны: дальше ошибка едет как текст, и
 отличить в нём токен от идентификатора уже нельзя.
 
-### R19. Диагностика хранится в отдельном поле
+### GERR-19. Диагностика хранится в отдельном поле
 
 **ДОЛЖЕН.** Персистентная диагностика не кладётся в доменное поле, которое
 показывают пользователю.
 
-**Почему.** Различие R17.1 и R17.2 держится на том, что у поверхностей
+**Почему.** Различие GERR-17.1 и GERR-17.2 держится на том, что у поверхностей
 разные поля. Одно поле на оба назначения означает, что при первом же показе
 записи наружу сырой текст уедет туда же — не по решению, а потому что поле
 одно.
 
 ## panic
 
-### R20. `panic` — только для невосстановимого
+### GERR-20. `panic` — только для невосстановимого
 
 **ДОЛЖЕН.** Паникой отмечается нарушенный инвариант (баг программиста) и
 ошибка инициализации, из которой нельзя стартовать.
@@ -293,25 +297,25 @@ HTTP-клиентов, файловой системы, внешних SDK.
 инвариантом опаснее падения, а сервис, стартовавший без обязательной
 зависимости, всё равно откажет позже и непонятнее.
 
-### R21. Ожидаемые ошибки — значения `error`
+### GERR-21. Ожидаемые ошибки — значения `error`
 
 **НЕ ДОЛЖЕН.** Паника не используется для управления потоком: нет сети,
 плохой ввод, отсутствующая запись возвращаются как `error`.
 
 **Почему.** Сигнатура — единственное, что сообщает вызывающему о возможном
 отказе; отказ, брошенный паникой, из неё не виден, и компилятор не заставит
-его обработать. Дальше такая паника долетает до recover-границы (R22), где
+его обработать. Дальше такая паника долетает до recover-границы (GERR-22), где
 неотличима от бага: штатный отказ попадает в лог со стеком и с интонацией
 «мы сломались».
 
-### R22. `recover` — на верхней границе каждой обрабатывающей единицы
+### GERR-22. `recover` — на верхней границе каждой обрабатывающей единицы
 
 **ДОЛЖЕН.** Своя граница ставится у каждой единицы, мотив у них разный:
 
 | № | Единица | Зачем `recover` |
 |---|---|---|
-| R22.1 | HTTP-хендлер | `net/http` восстанавливает панику сам и процесс не роняет; свой `recover` нужен, чтобы отдать контролируемый 500 и записать событие в `slog`, а не в stdlib-логгер |
-| R22.2 | цикл обработки апдейтов бота, фоновый воркер | паника в горутине роняет процесс; `recover` ставится в той же горутине |
+| GERR-22.1 | HTTP-хендлер | `net/http` восстанавливает панику сам и процесс не роняет; свой `recover` нужен, чтобы отдать контролируемый 500 и записать событие в `slog`, а не в stdlib-логгер |
+| GERR-22.2 | цикл обработки апдейтов бота, фоновый воркер | паника в горутине роняет процесс; `recover` ставится в той же горутине |
 
 **Почему.** `recover` работает только в той горутине, где случилась паника,
 поэтому «у нас есть recover в HTTP» не защищает воркер — граница нужна у
@@ -321,26 +325,26 @@ HTTP-клиентов, файловой системы, внешних SDK.
 без своего `recover` уходит мимо структурированного лога, а клиент получает
 оборванное соединение вместо ответа.
 
-### R23. Recover-граница пишет `debug.Stack()`
+### GERR-23. Recover-граница пишет `debug.Stack()`
 
 **ДОЛЖЕН.** Логирующий `recover` кладёт в запись стек.
 
-**Почему.** Это единственное место, где стек нужен (R1): у восстановленной
+**Почему.** Это единственное место, где стек нужен (GERR-1): у восстановленной
 паники цепочки `%w` нет вовсе. «index out of range» без стека не
 диагностируется в принципе — сообщение не называет ни файла, ни операции,
 по нему нельзя сказать даже, в каком пакете упало.
 
 ## Несколько ошибок
 
-### R26. После `recover` единица продолжает работу, исключив упавшее
+### GERR-26. После `recover` единица продолжает работу, исключив упавшее
 
 **ДОЛЖЕН.** Что происходит после перехвата, зависит от того, где стоит
 граница:
 
 | № | Где перехвачена паника | Что дальше |
 |---|---|---|
-| R26.1 | обработчик HTTP-запроса | ответ 500, если он ещё не начат; процесс и прочие запросы не затрагиваются |
-| R26.2 | итерация цикла обработки — бот, воркер | цикл продолжается со следующего элемента, упавший элемент повторно не берётся |
+| GERR-26.1 | обработчик HTTP-запроса | ответ 500, если он ещё не начат; процесс и прочие запросы не затрагиваются |
+| GERR-26.2 | итерация цикла обработки — бот, воркер | цикл продолжается со следующего элемента, упавший элемент повторно не берётся |
 
 **Почему.** Паника внутри обработки одного элемента почти всегда говорит о
 баге в работе с данными этого элемента, а не о порче общего состояния, —
@@ -348,7 +352,7 @@ HTTP-клиентов, файловой системы, внешних SDK.
 не буквально: в OTP падает изолированный процесс под супервизором, а не узел
 целиком, и в Go ближайшая замена такой изоляции — граница итерации, а не
 граница процесса. Обратное при этом верно и делает `recover` в цикле
-обязательным (R22): неперехваченная паника в любой горутине завершает весь
+обязательным (GERR-22): неперехваченная паника в любой горутине завершает весь
 процесс.
 
 Продолжать, не исключив упавший элемент, нельзя: детерминированная паника
@@ -359,16 +363,16 @@ HTTP-клиентов, файловой системы, внешних SDK.
 строку состоянием, — механизм для этого уже есть, заводить отдельный не
 нужно.
 
-Оговорка «если ответ ещё не начат» в R26.1 не формальность: статус
+Оговорка «если ответ ещё не начат» в GERR-26.1 не формальность: статус
 отправляется один раз, и после первой записи в тело поменять его нечем —
 клиент получит обрывок с кодом 200. Отсюда же общее предпочтение собирать
 ответ целиком до записи там, где это возможно.
 
-Из R26.1 есть одно исключение: `http.ErrAbortHandler` — сигнал «прервать
+Из GERR-26.1 есть одно исключение: `http.ErrAbortHandler` — сигнал «прервать
 обработку намеренно», и recover-обёртка пробрасывает его дальше, а не
 превращает в 500. Так поступают и стандартные обёртки вроде chi.
 
-### R24. Независимые ошибки собираются `errors.Join`
+### GERR-24. Независимые ошибки собираются `errors.Join`
 
 **СЛЕДУЕТ.** Валидация конфига и подобные проверки отдают все проблемы
 разом; проверка собранного — по-прежнему через `errors.Is`.
@@ -377,12 +381,13 @@ HTTP-клиентов, файловой системы, внешних SDK.
 перезапусков, по одной проблеме за прогон. Склейка сообщений в строку даёт
 тот же список, но убивает ветвление: `errors.Is` по такому результату не
 находит ничего, и вызывающий остаётся с текстом, матчить который запрещено
-(R11).
+(GERR-11).
 
 ## Связано
 
 - `lang/go/logging.md` — где и когда ошибка попадает в лог.
-- `arch/db-identifiers.md` R7 — формат корреляционного ключа из R14.
+- `KEYS-7` (`arch/db-identifiers.md`) — формат корреляционного ключа
+  из `GERR-14`.
 
 <!-- local:механизировано -->
 <!-- /local -->