конвенции отделены от обвязки

- сами конвенции переехали в conventions/, описательное — в корень:
  LANGUAGE.md (язык записи) и GUIDE.md (как ведут конвенции)
- conv синхронизирует только conventions/, пути в origin даются
  относительно неё — раскладка копий в репозиториях не меняется

conventions/arch/app-directories.md

@@ -0,0 +1,154 @@
+# Категории директорий приложения
+
+Всё, что приложение пишет на диск, делится на три категории по принципу
+создания и ценности содержимого: конфигурация, данные, кеш. Категория сразу
+отвечает на два вопроса, которые иначе выясняются чтением кода приложения:
+**кто создаёт** содержимое и **что будет, если его потерять**. Из категорий
+механически выводится состав бэкапа. Форма записи — `LANGUAGE.md`.
+
+## Область действия
+
+Раскладка меняется вместе с миграцией данных, поэтому правила
+распространяются на **новые приложения**; существующие переезжают по мере
+касания, отдельной кампанией не переписываются. Разделять данные и кеш
+задним числом имеет смысл тогда, когда кеш заметен по объёму в бэкапе, а не
+ради самой схемы.
+
+## Правила
+
+### R1. Записываемые пути разложены по трём категориям
+
+**ДОЛЖЕН.** Каждая директория, в которую пишет приложение или деплой,
+относится к одной из трёх категорий:
+
+| № | Категория | Директория | Создаёт | Потеря содержимого | В бэкапе |
+|---|---|---|---|---|---|
+| R1.1 | конфигурация | `config/` | деплой | восстанавливается прогоном деплоя | нет |
+| R1.2 | данные | `data/` | приложение | невосполнима | да |
+| R1.3 | кеш | `cache/` | приложение | приложение перегенерирует | нет |
+
+Имена в таблице — умолчание для случая «одна директория на категорию».
+
+**Почему.** Все дальнейшие решения — что попадает в бэкап (R4), что можно
+снести при нехватке места, что переживает переезд на другой диск —
+читаются из категории, а не выясняются по коду приложения. Без единой
+классификации каждое такое решение принимается заново и каждый раз чуть
+по-другому, а цена ошибки несимметрична: лишний кеш в снапшоте стоит места,
+потерянные данные не стоят ничего, потому что их больше нет.
+
+### R2. Категория может состоять из нескольких директорий
+
+**ДОПУСКАЕТСЯ.** Директорий в категории столько, сколько нужно раскладке;
+принадлежность к категории задаётся не именем, а участием в списке бэкапа.
+
+**Почему.** Явное разрешение снимает вопрос, не читается ли R1 как «ровно
+три директории». Крупные файлы отделяют от базы, чтобы двигать их между
+дисками независимо (`media/`, `uploads/` — та же категория «данные», что и
+`data/`); запрет на такое деление вынуждал бы либо держать всё на одном
+диске, либо выводить директорию из-под категорий вовсе. Категорию нельзя
+задавать именем ровно поэтому: имён в категории несколько, и выбираются они
+по содержимому.
+
+### R3. Данные и кеш разделяются по тесту на пересоздание
+
+**ДОЛЖЕН.** Записываемый путь относят к данным или к кешу по содержимому:
+
+| № | Что лежит | Категория |
+|---|---|---|
+| R3.1 | база, загруженные файлы, сгенерированные артефакты | данные |
+| R3.2 | миниатюры, распакованные ассеты, кеш внешних ответов, перестраиваемые индексы | кеш |
+| R3.3 | спорный случай | `rm -rf` и запуск приложения заново: поднялось и наверстало само — кеш; не поднялось или поднялось пустым — данные |
+
+**Почему.** Без внешнего теста граница проводится по ощущению «жалко
+потерять», а оно смещено в одну сторону: дорогой в пересборке кеш
+переезжает в данные и раздувает каждый снапшот. Дорого ≠ невосполнимо, и
+разделяет эти два свойства именно способность приложения пересоздать
+содержимое. Обратная ошибка — данные, названные кешем, — тестом
+обнаруживается в тот же момент, но дёшево: при попытке пересоздать, а не
+при попытке восстановить.
+
+### R4. В бэкап идут данные, и только они
+
+**ДОЛЖЕН.** Директории категории «данные» — в списке бэкапа; конфигурация и
+кеш — нет.
+
+**Почему.** Кеш раздувает снапшот содержимым, которое приложение
+восстановит само. Конфигурацию бэкапить не только незачем, но и вредно: там
+лежат секреты, а бэкапы уезжают в облако — источник истины для
+конфигурации остаётся в репозитории и хранилище секретов, а не в снапшоте.
+Ошибка в другую сторону дороже: директория данных, не попавшая в список,
+обнаруживается в единственный момент, когда исправить её уже нечем.
+
+### R5. Список бэкапа ссылается на те же пути, что и создание директорий
+
+**ДОЛЖЕН.** Список выводится из категорий по R4 и ссылается на те же
+объявления путей, по которым директории создаются, а не набирается
+независимо.
+
+**Почему.** Правило вывода механическое, но применяет его человек или
+шаблон — то есть ошибиться можно. Общая ссылка делает целый класс ошибок
+невозможным: переименование директории отражается в обоих местах сразу.
+Независимо набранный список расходится тихо — ни деплой, ни прогон бэкапа
+на это не жалуются, — и расхождение между тем, что бэкапится, и тем, что
+нужно, проявляется при восстановлении.
+
+### R6. Способ попадания данных в бэкап зависит от того, кто отвечает за консистентность
+
+**ДОЛЖЕН.** Способ выбирается по тому, самодостаточны ли файлы на диске:
+
+| № | Данные | В бэкап |
+|---|---|---|
+| R6.1 | файлы самодостаточны на любой момент времени | копированием |
+| R6.2 | консистентность обеспечивает только сама СУБД | дампом: бэкапится директория дампов, сырой каталог базы — нет |
+
+**Почему.** Файловый снапшот работающей СУБД не гарантирует
+консистентности: скопированный каталог может не восстановиться, и узнают
+об этом при восстановлении. Директория дампов — тоже данные, просто
+производные, поэтому R4 покрывает её без оговорок. Сырой каталог базы из
+списка при этом исключается: он удваивает объём снапшота и добавляет к
+надёжной копии заведомо ненадёжную.
+
+### R7. Способ выбирается при заведении приложения
+
+**ДОЛЖЕН.** Решение «копировать или дампить» (R6) принимается, когда
+приложение заводят.
+
+**Почему.** Неверный выбор ничем себя не проявляет, пока бэкап не
+понадобился: прогоны копирования проходят успешно и накапливают снапшоты, из
+которых база не поднимется. Отложить решение — значит принять его по факту
+первой неудачной попытки восстановления, то есть тогда, когда данных уже
+нет.
+
+### R8. Приложение разводит записываемые пути по категориям
+
+**ДОЛЖЕН.** Конфигурация приложения задаёт отдельные пути для данных и для
+кеша, а не один каталог на всё.
+
+**Почему.** Снаружи категория определяется только тогда, когда разным
+категориям соответствуют разные директории. Всё, сложенное в один каталог,
+заставляет составлять список бэкапа вручную, читая код приложения, — и
+пересматривать его при каждом обновлении, потому что новый подкаталог
+появляется молча. Приложение, которое не умеет разделять, тем самым
+дефектно; раскладка под этот дефект не подстраивается.
+
+### R9. Приложение не пишет в директорию конфигурации
+
+**НЕ ДОЛЖЕН.** Записываемые пути приложения не указывают внутрь
+конфигурации.
+
+**Почему.** Конфигурация восстанавливается прогоном деплоя (R1.1), поэтому
+всё, что приложение туда записало, следующий деплой затирает без
+предупреждения. Вдобавок директория конфигурации может быть подключена
+только на чтение — тогда запись отказывает в рантайме. Ни то ни другое не
+видно в момент, когда приложение настраивают.
+
+<!-- local:отступления -->
+<!-- /local -->
+
+## Связано
+
+<!-- local:эталон -->
+<!-- /local -->
+
+<!-- local:связано -->
+<!-- /local -->

conventions/arch/config.md

@@ -0,0 +1,258 @@
+# Конфигурация приложения
+
+Как устроена конфигурация: где лежит, как попадает в процесс, что с
+секретами и когда падает. Форма записи — `LANGUAGE.md`.
+
+## Область действия
+
+Правила написаны для приложений, которые мы пишем сами: только там мы
+управляем тем, как конфигурация читается. Сторонний образ, живущий на
+переменных окружения, вне области действия — это не повод отказываться от
+конвенции для своих приложений.
+
+## Правила
+
+### R1. Конфигурация — файл, а не окружение
+
+**ДОЛЖЕН.** Приложение читает параметры из файла конфигурации; переменные
+окружения источником конфигурации не служат.
+
+**Почему.** Три довода, по убыванию веса:
+
+- **Один типизированный источник.** Файл несёт секции, комментарии,
+  единицы измерения и валидируется целиком. Окружение — плоский набор
+  нетипизированных строк, который приходится документировать отдельно;
+  появление второго канала конфигурации гарантирует расхождение между ними.
+- **Окружение наследуется дочерними процессами.** Всё, что приложение
+  запускает — конвертер, `git`, шелл-хук, — по умолчанию получает копию
+  секретов, хотя они ему не нужны.
+- **В контейнере окружение расползается по лишним поверхностям.**
+  `docker inspect` показывает его любому, у кого есть доступ к сокету
+  докера; переменные оседают в compose-файле и `.env` на диске — то есть
+  файл всё равно появляется, только без структуры и валидации.
+
+Обратите внимание, чего в этих доводах **нет**: `/proc/<pid>/environ` не
+является аргументом — он имеет права `0400` и защищён проверкой
+`PTRACE_MODE_READ`, то есть доступен ровно тому же кругу, что и файл под
+`0600`.
+
+### R2. Формат конфигурации — текстовый, с секциями и комментариями
+
+**СЛЕДУЕТ.** Конкретный формат (TOML, YAML) выбирается по стеку.
+
+**Почему.** Комментарий у каждого поля (R9) — часть того, ради чего конфиг
+вообще читают; формат, в котором комментарий негде разместить, делает R9
+невыполнимым. Секции дают структуру, которую валидатор проверяет целиком, —
+плоский список пар такой возможности не даёт и возвращает нас к тем же
+свойствам, из-за которых отвергнуто окружение (R1).
+
+### R3. Имя файла фиксировано, путь переопределяется опцией
+
+**СЛЕДУЕТ.** Имя по умолчанию ищется в рабочей директории процесса, а путь
+задаётся опцией командной строки.
+
+**Почему.** Запуск без аргументов работает одинаково в разработке, в
+контейнере и на сервере, и способ запуска не приходится помнить отдельно
+для каждой среды. Опция нужна ровно для случаев, когда конфигов несколько
+(тесты, второй инстанс): без неё их разводят переменной окружения — тем
+самым каналом, который закрывает R1.
+
+### R4. В репозитории лежит образец, а не рабочий конфиг
+
+**НЕ ДОЛЖЕН.** Реальный конфиг не коммитится; в репозитории — образец.
+
+**Почему.** Рабочий конфиг содержит отрендеренные секреты (R12), а секрет,
+попавший в историю, чинится ротацией, а не удалением файла. Кроме того,
+закоммиченный конфиг конкретной среды становится вторым источником истины:
+он расходится с тем, что реально развёрнуто, и расходится молча.
+
+### R5. Конфиг разбирается один раз при старте
+
+**ДОЛЖЕН.** Разбор — при старте, в одну типизированную структуру; чтения
+файла конфигурации в бизнес-коде нет.
+
+**Почему.** Второе место чтения — это второй момент времени: две части кода
+начинают видеть разные значения одного параметра, и расхождение не
+воспроизводится, потому что зависит от того, когда файл потрогали.
+Типизированная структура вдобавок переносит ошибку формата в старт (R17),
+где она видна сразу, а не в первый вызов ветки, которая это поле читает.
+
+### R6. Конфиг неизменяем после старта
+
+**ДОЛЖЕН.** Смена параметров — рестарт процесса.
+
+**Почему.** Изменяемый конфиг делает поведение функцией момента: один
+запрос обслуживается наполовину старыми, наполовину новыми значениями, а
+разбор инцидента требует знать хронологию правок файла, а не его текущее
+содержимое.
+
+Горячая перезагрузка — отдельное решение с отдельным обоснованием, а не
+умолчание.
+
+### R7. Умолчания живут в коде
+
+**ДОЛЖЕН.** Значение по умолчанию задаётся в коде, файл его перекрывает.
+
+**Почему.** Умолчание, живущее в образце, действует только для тех, кто
+образец скопировал: конфиг без этого поля даёт другое поведение, и ни одно
+из двух значений не выглядит ошибкой. Умолчание в коде — одно определённое
+поведение для неполного конфига и одно место, где это значение меняется.
+
+### R8. Образец перечисляет все поля
+
+**ДОЛЖЕН.** В образце присутствуют все секции и все поля, включая те, у
+которых есть умолчание (R7).
+
+**Почему.** Поле, живущее только в коде, для читателя конфига не
+существует: он не знает, что параметр вообще можно менять, и добивается
+нужного поведения обходным путём. Полнота образца — цена, которой R7
+покупает себе видимость.
+
+### R9. У каждого поля образца есть комментарий
+
+**ДОЛЖЕН.** Каждое поле сопровождается комментарием, из которого ясно:
+
+- **зачем** поле — что оно меняет в поведении;
+- **диапазон или допустимые значения** — перечисление либо границы;
+- **единицы измерения**, если применимо: секунды/миллисекунды, байты, доля
+  `0–1`.
+
+**Почему.** Так конфиг читается без открывания кода — этим он и полезен;
+без комментария читатель всё равно идёт в код, и образец перестаёт быть
+справочником. Единицы стоят отдельно: перепутанные секунды и миллисекунды
+дают валидное значение и работающий процесс, а ошибка обнаруживается по
+последствиям — таймаут в тысячу раз не тот.
+
+### R10. Обязательность полей определяется дискриминатором `type`
+
+**ДОЛЖЕН.** Когда набор полей секции зависит от поля-дискриминатора (выбор
+бекенда или внешнего сервиса), валидация идёт по его значению:
+
+| № | Значение `type` | Валидация |
+|---|---|---|
+| R10.1 | поддерживаемое | обязательны поля этого варианта; поля прочих вариантов не требуются |
+| R10.2 | неизвестное | ошибка на старте с перечислением поддерживаемых значений |
+
+**Почему.** Фиксированный на секцию набор обязательных полей оставляет
+выбор из двух плохих: заполнять поля бекенда, который не используется, или
+не проверять обязательность вовсе — то есть выключить валидацию ровно там,
+где вариантов много и ошибиться легче всего. Перечисление поддерживаемых
+значений (R10.2) нужно потому, что опечатка в `type` иначе неотличима от
+неподдерживаемого варианта, и за списком приходится идти в код.
+
+### R11. Образец показывает все варианты `type`
+
+**СЛЕДУЕТ.** Основной вариант предзаполнен рабочими значениями,
+альтернативные — блоками-комментариями ниже, каждый со своим описанием
+полей.
+
+**Почему.** Иначе набор вариантов виден только из кода валидации, и образец
+теряет свойство справочника (R8, R9) ровно на той секции, где выбор
+действительно есть. Закомментированный блок вдобавок переключается правкой
+на месте, а не сборкой секции с нуля по документации.
+
+### R12. Секреты в конфиг приносит деплой
+
+**ДОЛЖЕН.** Деплой рендерит значения секретов прямо в файл конфигурации;
+отдельного слоя секретов в приложении нет.
+
+**Почему.** Источник истины секрета — внешнее хранилище деплоя, не
+репозиторий и не окружение. Любой второй канал — переменная окружения рядом
+с файлом, собственный клиент к хранилищу внутри приложения — возвращает
+вопрос «откуда взялось значение, которое сейчас в процессе». Приложение при
+этом остаётся тривиальным: оно читает файл и про секреты не знает ничего
+особенного.
+
+### R13. Рендеренный конфиг — `0600` и владелец-рантайм
+
+**ДОЛЖЕН.** Права `0600`, владелец — пользователь, от имени которого
+работает процесс.
+
+**Почему.** После R1 и R12 файл конфигурации — единственная поверхность, на
+которой секреты лежат, и весь довод «файл вместо окружения» держится на его
+правах: конфиг, читаемый всеми на машине, раздаёт секреты шире, чем раздало
+бы окружение, — и тогда R1 меняет одну утечку на другую.
+
+### R14. В образце секретные поля — пустые строки
+
+**ДОЛЖЕН.** Значение секретного поля в образце — пустая строка, а не
+пример.
+
+**Почему.** Правдоподобная заглушка доезжает до продакшена как настоящее
+значение: шаблон отрендерился криво, поле осталось от образца, и проверка
+непустоты (R15) его пропускает. Пустая строка делает недорендеренный конфиг
+механически отличимым от заполненного.
+
+### R15. Загрузчик проверяет, что обязательные секреты не пусты
+
+**ДОЛЖЕН.** Непустота обязательных секретов проверяется на старте.
+
+**Почему.** Это ловит криво отрендеренный шаблон до того, как он превратится
+в 401 от внешнего API через час работы, — то есть в момент, когда причина
+ещё очевидна и связана с деплоем.
+
+### R16. Секреты не попадают в логи
+
+**НЕ ДОЛЖЕН.** Значение секретного поля не появляется в записи лога ни на
+одном уровне.
+
+**Почему.** У логов круг доступа шире, чем у файла под `0600` (R13): они
+собираются, пересылаются и попадают в бэкапы, где права исходного файла уже
+ничего не значат. Попавший в лог секрет чинится ротацией, а не удалением
+записи. Типичный источник утечки — отладочный дамп разобранного конфига при
+старте.
+
+<!-- local:секретные-поля -->
+<!-- /local -->
+
+### R17. Конфиг валидируется на старте, до приёма трафика
+
+**ДОЛЖЕН.** Невалидный конфиг — запись уровня `ERROR` и выход с ненулевым
+кодом; процесс не стартует «наполовину».
+
+**Почему.** Наполовину стартовавший процесс проходит проверку живости и
+падает позже — на первом запросе, который трогает испорченный параметр, — и
+падение выглядит дефектом кода, а не ошибкой деплоя. Ненулевой код нужен,
+чтобы неудачный старт увидел супервизор: без него он неотличим от штатного
+завершения, и приложение считается развёрнутым.
+
+### R18. Минимальный набор проверок
+
+**ДОЛЖЕН.** Валидация покрывает как минимум:
+
+| № | Что проверяется | Когда всплывёт без проверки |
+|---|---|---|
+| R18.1 | обязательные поля заданы (непустота секретов — R15) | в ветке, которая это поле читает |
+| R18.2 | пути существуют и доступны на запись/чтение по назначению | при первой записи, уже после отчёта об успешном старте |
+| R18.3 | числовые диапазоны и единицы: доли, таймауты, счётчики попыток | искажённым поведением без единого сообщения об ошибке |
+| R18.4 | строки, которые парсятся во что-то (длительности, зоны, URL), реально парсятся | при первом обращении к тому, что за ними стоит |
+| R18.5 | включённые секции консистентны: у включённой интеграции заданы все обязательные поля | при первом вызове интеграции, часто по расписанию |
+
+**Почему.** Список минимальный и собран по одному признаку — правый
+столбец: каждая из этих ошибок иначе всплывает там, где связь с деплоем уже
+потеряна, и диагностируется как дефект приложения. Проверка на старте
+сводит их все к одному моменту и одному сообщению.
+
+<!-- local:проверки -->
+<!-- /local -->
+
+### R19. Проблемы конфига показываются разом
+
+**ДОЛЖЕН.** Валидация собирает все найденные проблемы и выводит их одним
+списком, а не падает на первой.
+
+**Почему.** Иначе цикл «запуск — одна ошибка — правка» повторяется столько
+раз, сколько в конфиге ошибок, а на сервере каждая итерация — это ещё и
+деплой. Криво отрендеренный шаблон обычно ломает не одно поле, а все поля
+одного источника: разом они читаются как одна причина, по одной — как
+череда несвязанных мелочей.
+
+## Связано
+
+- `arch/time.md` — формат времени; зона отображения — единственный
+  конфигурируемый параметр времени, семантика описана там.
+- `arch/app-directories.md` — конфиг лежит в категории «конфигурация» и
+  доступен приложению только на чтение.
+
+<!-- local:связано -->
+<!-- /local -->

conventions/arch/db-identifiers.md

@@ -0,0 +1,137 @@
+# Идентификаторы сущностей
+
+Как выбираются и как выглядят первичные ключи сущностей. Форма записи —
+`LANGUAGE.md`.
+
+## Область действия
+
+Схема базы меняется тяжело: таблица не переезжает от того, что её
+потрогали. Поэтому правила распространяются на **новые таблицы**;
+существующие живут как есть и перечисляются в отступлениях, причём этот
+список постоянный, а не список задач на дочистку.
+
+## Правила
+
+### R1. Вид первичного ключа выбирается один раз на репозиторий
+
+**ДОЛЖЕН.** Репозиторий отвечает на один вопрос и держит ответ для всех
+своих таблиц:
+
+> Есть ли в приложении хотя бы одна сущность, которую адресуют **извне** —
+> по идентификатору из URL, запроса API или callback-данных?
+
+| № | Ответ | Вид ключа |
+|---|---|---|
+| R1.1 | да, хотя бы одна | сортируемый строковый идентификатор, который генерирует приложение (ULID) — во **всех** таблицах, включая внутренние |
+| R1.2 | ни одной | автоинкремент |
+
+**Почему.** Квантор репозиторный, а не потабличный, по двум причинам.
+Внутренние сущности имеют привычку становиться внешними — и тогда
+целочисленный идентификатор утекает в URL задним числом, а миграция ключа
+на живых данных стоит несопоставимо дороже, чем взять строковый сразу.
+Вторая причина дешевле, но важнее в быту: одна ментальная модель избавляет
+от спора при заведении каждой таблицы.
+
+Критерий — именно **адресация**: снаружи по этому идентификатору
+возвращаются к системе. Не «виден в логе»: туда рано или поздно попадает
+любой идентификатор, и по такому критерию ветка R1.2 была бы недостижима.
+
+Запрет смешивания касается двух видов **сгенерированных суррогатных**
+ключей. Естественные и составные ключи у таблиц-деталей (R6) — третья
+категория, они допустимы при любом ответе.
+
+<!-- local:решение -->
+<!-- /local -->
+
+### R2. При выборе R1.1 идентификатор генерирует приложение, а не база
+
+**ДОЛЖЕН.** Значение ключа известно до вставки строки.
+
+**Почему.** Идентификатор нужен раньше, чем база ответит: его пишут в лог
+начатой операции, кладут в связанные записи одной транзакции и возвращают
+клиенту. Генерация на стороне базы вынуждает либо ждать `last_insert_rowid`
+и достраивать связи вторым проходом, либо иметь два источника истины о
+моменте создания.
+
+### R3. Генерация и разбор идентификаторов — в единственной точке
+
+**ДОЛЖЕН.** Один модуль порождает идентификаторы, он же их разбирает.
+Самодельных генераторов и парсеров в коде нет.
+
+**Почему.** Нормализация регистра (R4) и проверка формата обязаны
+применяться ко всем идентификаторам без исключения. Любая вторая точка
+входа рано или поздно окажется той, где нормализацию забыли, — и дефект
+проявится не там, где создан.
+
+### R4. Канонический вид — нижний регистр
+
+**ДОЛЖЕН.** Идентификаторы порождаются и хранятся в нижнем регистре.
+
+**Почему.** Сравнение строк в базе обычно побайтовое, поэтому регистр — не
+косметика, а корректность поиска. Спецификация ULID канонизирует **верхний**
+регистр, и библиотеки по умолчанию отдают именно его: без единой точки (R3)
+разный регистр появится в базе сам собой.
+
+### R5. Внешний идентификатор разбирается до обращения к базе
+
+**ДОЛЖЕН.** Значение, пришедшее снаружи, проходит разбор и нормализацию
+раньше, чем по нему делается запрос. Реакция на неудачный разбор зависит от
+источника:
+
+| № | Откуда пришёл | Разбор не удался → |
+|---|---|---|
+| R5.1 | путь или query URL | «не найдено» без обращения к хранилищу |
+| R5.2 | собственная форма, данные кнопки | «некорректный ввод» либо «элемент устарел» |
+
+**Почему.** Синтаксически невалидное значение не может соответствовать
+записи, поэтому поход в базу за ним — заведомо холостой; отсекая его на
+границе, мы дёшево снимаем целый класс мусорного трафика.
+
+Разделение R5.1 и R5.2 нужно, потому что источники значат разное. Мусор в
+URL — это чужая или протухшая ссылка, и «не найдено» описывает ситуацию
+точно. Мусор из собственной формы — это баг интерфейса или устаревший
+экран; ответ «не найдено» здесь скрывает дефект и лишает диагностики
+единственный момент, когда он заметен.
+
+### R6. У таблиц-деталей допустим естественный или составной ключ
+
+**ДОПУСКАЕТСЯ.** Когда ключ есть по природе данных, отдельный
+сгенерированный идентификатор не заводится.
+
+**Почему.** Суррогат поверх естественного ключа создаёт второй способ
+адресовать ту же строку — а значит, возможность рассинхрона между ними и
+лишний вопрос «по какому из них искать» на каждом запросе. Дополнительной
+информации он не несёт.
+
+### R7. Прочие генерируемые идентификаторы — через ту же точку
+
+**ДОЛЖЕН.** Идентификаторы, не являющиеся первичными ключами (батч,
+задание, корреляционный ключ), порождаются тем же модулем (R3) и в том же
+формате.
+
+**Почему.** Единый формат делает работающим главный побочный эффект
+строковых идентификаторов: `grep` по голому значению собирает все
+упоминания сущности в логах независимо от имени поля. Второй формат
+идентификаторов эту возможность отменяет ровно для тех записей, где она
+чаще всего нужна.
+
+## Почему ULID, а не UUID
+
+Ветка R1.1 требует **сортируемый** строковый идентификатор. UUIDv4 не
+сортируется по времени вовсе. UUIDv7 (RFC 9562) сортируется — и против него
+остаются два довода: 36 символов против 26 и дефисы, из-за которых
+идентификатор не берётся ни двойным кликом, ни `grep`-ом как одно слово.
+
+Сортировка даёт `ORDER BY id` = хронология с точностью до миллисекунды;
+внутри одной миллисекунды порядок произволен, если генератор не монотонный,
+— на порядок событий это не влияет.
+
+<!-- local:отступления -->
+<!-- /local -->
+
+## Связано
+
+- `arch/time.md` — метки времени тоже генерирует приложение, а не схема.
+
+<!-- local:связано -->
+<!-- /local -->

conventions/arch/time.md

@@ -0,0 +1,171 @@
+# Время
+
+Как приложение записывает моменты и длительности: в каком формате, откуда
+берётся значение и где появляется не-UTC. Форма записи —
+`LANGUAGE.md`.
+
+## Область действия
+
+Конвенция описывает фиксацию **свершившихся моментов** — того, что уже
+произошло и попало в базу, лог или ответ API. Планирование будущих событий —
+отдельный случай: там хранят локальное время плюс имя зоны, потому что
+правила зон меняются в промежутке между планированием и наступлением. Пока
+такой сущности нет, правил для неё в файле нет.
+
+## Правила
+
+### R1. Единый формат — RFC 3339, UTC, суффикс `Z`
+
+**ДОЛЖЕН.** Момент времени записывается как `2026-06-28T11:23:45Z` —
+одинаково в хранении, логах, API и обмене с внешними системами.
+
+**Почему.** Разные форматы в разных слоях требуют преобразования на каждой
+границе, а ошибка в таком преобразовании не видна сразу: она всплывает через
+полгода, на переходе на летнее время, когда реальное смещение перестаёт
+совпадать с тем, которое подразумевалось при написании кода. UTC с явным `Z`
+убирает из данных и смещение, и сам вопрос «в какой зоне это записано».
+
+### R2. Ширина строки фиксируется на каждый носитель
+
+**ДОЛЖЕН.** Внутри одной колонки БД и внутри одного потока логов длина
+строки времени одна и от записи к записи не плавает.
+
+**Почему.** Лексикографическая сортировка совпадает с хронологией только
+среди строк одинаковой длины: `…00.123Z` сортируется раньше `…00.12Z`, хотя
+произошло позже. Ради этого ширина и фиксируется — `ORDER BY created_at` по
+текстовому полю обязан давать порядок событий. Плавающая ширина (типичный
+источник — форматирование, отбрасывающее незначащие нули) ломает порядок не
+везде, а только на тех парах записей, где дробная часть оказалась короче, —
+то есть редко, выборочно и невоспроизводимо.
+
+### R3. Точность разных носителей может различаться
+
+**ДОПУСКАЕТСЯ.** У колонки БД и у потока логов каждая своя точность.
+
+**Почему.** Квантор в R2 — на носитель, а не на приложение, потому что
+строки разных носителей между собой не сравниваются: сортировка идёт внутри
+колонки, чтение — внутри потока. Явное разрешение нужно, чтобы R2 не читался
+как «одна точность на всё приложение»: от подгонки формата логов под формат
+колонки ни одна пара строк не становится сравнимой, зато точность режется до
+худшего из носителей.
+
+### R4. Локальное время не хранится и не передаётся
+
+**НЕ ДОЛЖЕН.** Ни в базе, ни в логах, ни в JSON API нет меток в локальной
+зоне.
+
+**Почему.** Метка без зоны неинтерпретируема вне процесса, который её
+записал: чтобы понять, какому моменту она соответствует, читателю нужно
+знать настройки чужой машины на момент записи. И даже зная их, он не
+разберёт час перехода на зимнее время: этот час идёт дважды, две записи
+получают одинаковую метку, и порядок между ними не восстанавливается ничем.
+
+### R5. Единая точка получения «сейчас», форматирования и разбора
+
+**ДОЛЖЕН.** Один модуль отдаёт текущий момент, он же форматирует и разбирает
+метки; прямые вызовы часов по коду не разбросаны.
+
+**Почему.** Формат, зона (R1) и ширина (R2) обязаны выполняться для всех
+меток без исключения, а каждый прямой вызов часов заводит ещё одно место,
+где их можно не соблюсти. Промах такого вызова проявляется не в коде, а в
+данных, и обнаруживается, когда испорченных записей уже накопилось.
+Соображение то же, что для идентификаторов (`arch/db-identifiers.md R3`).
+
+### R6. Дефолтов времени в схеме БД нет
+
+**НЕ ДОЛЖЕН.** Колонки времени не имеют `DEFAULT` с текущим моментом.
+
+**Почему.** Дефолт превращает забытую вставку `created_at` в тихо работающий
+код: значение появляется, но приходит от сервера БД — то есть с других часов
+и в формате, который выбирала не единая точка (R5). Без дефолта та же ошибка
+падает громко и чинится в момент написания, а не при разборе расхождения
+между временем в записи и временем в логе. Правило то же, что для
+идентификаторов (`arch/db-identifiers.md R2`).
+
+### R7. Длительность — отдельная величина, а не пара меток
+
+**ДОЛЖЕН.** Длительность операции записывается числом (обычно
+миллисекундами) в поле вида `duration_ms`.
+
+**Почему.** Метка отвечает на вопрос «когда», длительность — на «сколько».
+Пара меток заставляет каждого потребителя знать, какие именно две из них
+образуют операцию, и вычитать их самому — в запросе, в дашборде и глазами в
+логе; число сравнивается, агрегируется и попадает в перцентили без этого
+шага. Кроме того, разность сохранённых меток считается по стенным часам и
+наследует их дефект (R9).
+
+### R8. Длительность засекает слой, который делает вызов
+
+**СЛЕДУЕТ.** Замер живёт там же, где вызов, границы которого он измеряет.
+
+**Почему.** Обе границы операции видит только этот слой: замер уровнем выше
+приписывает операции чужие накладные расходы, уровнем ниже — теряет часть
+вызова. В обоих случаях число остаётся правдоподобным и потому не
+оспаривается, хотя отвечает не на тот вопрос, который к нему задают.
+
+### R9. Момент и интервал берутся с разных часов
+
+**ДОЛЖЕН.** Источник зависит от того, что записывается:
+
+| № | Величина | Источник |
+|---|---|---|
+| R9.1 | момент события | стенные часы через единую точку (R5) |
+| R9.2 | длительность операции | монотонные часы процесса |
+
+**Почему.** Стенные часы подводит NTP: они могут шагнуть назад, и тогда
+интервал, посчитанный вычитанием, выйдет отрицательным, а при шаге вперёд —
+правдоподобным, но выдуманным. Монотонные часы, наоборот, не годятся для
+меток: их ноль произволен и не переживает перезапуск процесса, так что вне
+процесса такое значение ничего не означает. Отсюда следствие, которое легко
+упустить: источник меток времени и источник интервалов — разные, даже если
+оба называются «часы».
+
+### R10. Не-UTC существует только на слое отображения
+
+**ДОЛЖЕН.** Преобразование в зону пользователя происходит при выводе и не
+проникает в хранение, сортировку и логи.
+
+**Почему.** Как только конвертация уходит вглубь, результат вычислений
+начинает зависеть от настроек конкретного зрителя: одна и та же выборка даёт
+разные группировки, а порядок записей перестаёт быть общим для всех. Ещё
+хуже, что при конвертации в нескольких слоях её легко выполнить дважды —
+смещение удваивается, результат остаётся похожим на правду, а найти
+виновный слой можно только перечитав их все.
+
+### R11. Зона отображения берётся из конфигурации, по умолчанию `UTC`
+
+**ДОЛЖЕН.** Значение приходит из конфигурации (`arch/config.md`), значение
+по умолчанию — `UTC`.
+
+**Почему.** Зашитая в код зона превращает переезд или второго пользователя в
+другом поясе в правку кода и релиз. Значение по умолчанию `UTC` выбрано
+потому, что оно не притворяется настроенным: показанное время совпадает с
+тем, что лежит в базе и в логах, поэтому несовпадение с ожиданиями читается
+как «зону не задали», а не как «где-то потерялось смещение».
+
+### R12. В календарных вычислениях зона указывается явно
+
+**ДОЛЖЕН.** «Сегодня», «за месяц» и прочие календарные границы считаются с
+явно переданной зоной, а не с системной зоной процесса.
+
+**Почему.** Системная зона разная на ноутбуке разработчика и в контейнере на
+сервере, поэтому граница суток уезжает, а вместе с ней — содержимое отчёта:
+расхождение не воспроизводится там, где его заметили, и объясняется средой,
+а не кодом. Явно переданная зона делает результат функцией от аргументов.
+
+Зона по умолчанию здесь та же, что и для отображения (R11); календарная
+логика, которой нужна другая, получает её тем же явным аргументом.
+
+<!-- local:механизировано -->
+<!-- /local -->
+
+<!-- local:отступления -->
+<!-- /local -->
+
+## Связано
+
+- `arch/config.md` — где задаётся зона отображения.
+- `arch/db-identifiers.md` — то же правило «генерирует приложение» для id.
+
+<!-- local:связано -->
+<!-- /local -->

conventions/lang/go/config.md

@@ -0,0 +1,224 @@
+---
+extends: arch/config.md
+---
+
+# Конфигурация: реализация на Go
+
+Как `arch/config.md` выглядит в Go-приложении: формат, загрузчик, границы
+запрета на окружение. Форма записи — `LANGUAGE.md`.
+
+Секретов Go-специфика не касается: они приходят из деплоя уже в файле, а
+проверка их непустоты идёт вместе с остальной валидацией — как описано в
+базовой конвенции.
+
+## Правила
+
+### R1. Формат конфигурации — TOML
+
+**ДОЛЖЕН.** Конфиг — файл TOML.
+
+**Почему.** Базовая конвенция оставляет формат за стеком, и этот выбор
+делается один раз на язык, а не в каждом приложении: разные форматы в
+соседних сервисах означают разные загрузчики, разные шаблоны рендера
+конфига в деплое и разное поведение при синтаксической ошибке. TOML при
+этом даёт секции и типизированные скаляры без значимых отступов — конфиг,
+поправленный руками на сервере, ломается заметно, а не меняет вложенность
+молча.
+
+### R2. Разбор и валидация — целиком в `internal/config`
+
+**ДОЛЖЕН.** Чтение файла, наложение умолчаний и проверки живут в
+`internal/config`; наружу пакет отдаёт готовую структуру `Config`.
+
+**Почему.** Пока значение не покинуло пакет, оно может быть невалидным;
+после — уже нет, и это единственная граница, на которой такое утверждение
+проверяемо. Валидация, размазанная по потребителям, отвечает на вопрос
+«проверено ли это поле» только чтением всех вызывающих, часть полей
+неизбежно окажется непроверенной, и fail-fast (R15) выродится в отказ
+посреди работы. Экспортированный разбор вдобавок даёт второй способ
+получить конфиг — мимо умолчаний (R5).
+
+### R3. Весь конфиг — одна корневая структура
+
+**ДОЛЖЕН.** Конфиг представлен одним значением типа `Config`, собранным из
+под-структур по секциям.
+
+**Почему.** Один корень даёт одну точку, после которой конфиг проверен
+целиком, и дальше передаётся как обычный аргумент. Несколько независимых
+структур конфига означают несколько загрузок и вопрос «какая из них уже
+провалидирована» на каждом использовании; связанные между собой поля
+(включена интеграция — заданы все её поля) при этом перестают быть
+проверяемыми в одном месте.
+
+### R4. Под-структуры названы по секциям файла
+
+**СЛЕДУЕТ.** Имя под-структуры совпадает с именем секции TOML.
+
+**Почему.** Имя секции из файла — то, с чего начинают, когда конфиг ведёт
+себя не так, как ожидали. При совпадении имён поиск по нему сразу приводит
+в код и обратно; при расхождении связь между полем файла и полем структуры
+восстанавливается чтением тегов, и проделывать это приходится для каждой
+секции заново.
+
+### R5. Умолчания задаёт `Default()`
+
+**ДОЛЖЕН.** Умолчания собраны в функции `Default()`, разобранный файл
+накладывается поверх.
+
+**Почему.** Нулевое значение в Go неотличимо от «поле не задано»: нулевой
+таймаут и отсутствующий таймаут — один и тот же `0`. Умолчание,
+подставленное по месту использования (`if x == 0 { x = … }`), поэтому не
+видно ни целиком, ни из образца, и два потребителя одного поля со временем
+подставляют разное. `Default()` — единственное место, откуда список
+умолчаний читается разом и переносится в образец.
+
+### R6. Имя файла фиксировано, путь переопределяется флагом
+
+**СЛЕДУЕТ.** По умолчанию читается `config.toml` в рабочей директории,
+путь переопределяет флаг `--config=path`, образец рядом —
+`config.example.toml`.
+
+**Почему.** Фиксированное имя и переопределение из командной строки требует
+базовая конвенция, но конкретные имена она не задаёт. Одинаковые имена во
+всех сервисах означают, что unit-файл, `docker run` и инструкция по запуску
+пишутся, не открывая код приложения. Соседство `config.toml` и
+`config.example.toml` вдобавок делает расхождение образца с реальным
+конфигом видимым обычным `diff`, а не вычиткой.
+
+### R7. Длительности — собственный тип с `UnmarshalText`
+
+**ДОЛЖЕН.** Поля-длительности объявляются своим типом, отдающим
+`time.Duration`:
+
+```go
+type Duration time.Duration
+
+func (d *Duration) UnmarshalText(b []byte) error { … }
+func (d Duration) Std() time.Duration            { … }
+```
+
+**Почему.** `time.Duration` — это `int64`, и TOML разбирает его в голое
+число: в конфиге остаётся `poll_interval = 5000`, о котором читатель не
+знает, секунды это, миллисекунды или наносекунды. Ошибка в тысячу раз
+проходит и разбор, и проверку диапазона, а проявляется нагрузкой или
+зависшим ожиданием. Запись `poll_interval = "5s"` несёт единицу измерения
+в себе и разбирается тем же `time.ParseDuration`, что и остальной код.
+
+У обёртки есть цена: `UnmarshalText` вызывается на разборе TOML, то есть
+раньше, чем начинает работать сбор проблем (R12). Ошибка в длительности
+приходит отдельно и первой, а остальные проблемы конфига в этом запуске не
+показываются.
+
+### R8. Приложение не читает окружение
+
+**НЕ ДОЛЖЕН.** Значения конфигурации не берутся из переменных окружения.
+
+**Почему.** Второй канал конфигурации — то, против чего написана базовая
+конвенция, но в Go он ещё и бесследный: `os.Getenv` вызывается из любого
+пакета, не появляется ни в `Config`, ни в образце и не проходит валидацию.
+Заведённый так параметр нельзя ни увидеть в конфиге, ни узнать иначе как
+чтением всего кода — а узнают о нём обычно на сервере, где переменная не
+выставлена.
+
+### R9. Проверка запрета покрывает все входы в окружение
+
+**ДОЛЖЕН.** Механическая проверка R8 (`forbidigo`) ловит не только
+`os.Getenv`:
+
+```
+^os\.(Getenv|LookupEnv|Environ|ExpandEnv)$
+```
+
+**Почему.** `LookupEnv`, `Environ` и `ExpandEnv` читают ровно то же самое,
+поэтому паттерн на одно имя оставляет три обхода. Хуже, что оставляет
+незаметно: правило числится механизированным, и глазами его больше никто не
+проверяет.
+
+### R10. За границей приложения запрет не действует
+
+**ДОПУСКАЕТСЯ.** Чтение окружения там, где читающий — не конфигурируемое
+приложение:
+
+| № | Кто читает | Вердикт |
+|---|---|---|
+| R10.1 | тесты, включая интеграционные | допустимо: креды и адреса внешних сервисов взять больше неоткуда |
+| R10.2 | Go-рантайм и ОС, а не наш код (`GOMEMLIMIT`, `GOMAXPROCS`, `GODEBUG`, `TZ`) | вне запрета: значение читает не приложение |
+
+**Почему.** R8 — про конфигурацию приложения; расширенный до «никто не
+трогает окружение», он запрещает то, чем не управляет: `GOMEMLIMIT` читает
+рантайм, а тесту креды внешнего сервиса взять неоткуда — в репозиторий их
+не положишь, а отдельный конфиг тестов пришлось бы заводить как ещё один
+механизм. Явное разрешение нужно и потому, что нерасписанная граница
+лечится `//nolint` наугад: там, где легальные случаи приходится глушить
+руками, вместе с ними проходят и нелегальные.
+
+### R11. Прокси задаётся конфигом, а не `HTTP_PROXY`
+
+**ДОЛЖЕН.** Исходящий прокси приходит полем конфига и явным `Transport`.
+
+**Почему.** `HTTP_PROXY`/`HTTPS_PROXY` формально читает не наш код, а
+дефолтный `http.Transport` — но читает он их от имени приложения и меняет
+поведение приложения, а не рантайма. Оставленные окружению, они дают ровно
+тот второй канал, который запрещает R8, и притом самый неудобный: маршрут
+исходящих запросов отличается от машины к машине без единого следа в
+конфиге и в образце, а расследование начинается с вопроса «почему на
+сервере ходит не так, как локально».
+
+### R12. Проблемы конфига собираются `errors.Join`
+
+**ДОЛЖЕН.** Проверки не прерываются на первой неудаче, результат — одна
+ошибка, собранная `errors.Join`.
+
+**Почему.** Возврат первой ошибки превращает починку конфига в серию
+перезапусков по одному полю за раз, причём каждый следующий запуск
+обнаруживает ещё одно. `errors.Join` даёт разом весь список, не требуя
+своего типа ошибки, и `errors.Is`/`errors.As` продолжают работать по каждой
+вложенной проблеме.
+
+### R13. Имя зоны проверяется `time.LoadLocation`
+
+**ДОЛЖЕН.** IANA-зона из конфига загружается на старте, в общей валидации.
+
+**Почему.** Проверить имя зоны нечем, кроме загрузки: оно валидно ровно
+тогда, когда база зон его знает, и никакая проверка формата не отличит
+`Europe/Moscow` от `Europe/Moskow`. Без загрузки на старте опечатка
+доживает до первого форматирования времени — то есть до рантайма, мимо
+fail-fast (R15).
+
+### R14. `time/tzdata` импортируется в `main`
+
+**ДОЛЖЕН.** Импорт `_ "time/tzdata"` стоит в `main`, а не в библиотечном
+пакете.
+
+**Почему.** Импорт в библиотеке навязывает ~450 КБ zoneinfo каждому
+импортёру, включая тех, кому зоны не нужны: выбор «встраивать базу или
+полагаться на системную» принадлежит собираемой программе. Со встроенной
+базой ошибка `LoadLocation` (R13) означает ровно одно — битое имя зоны; без
+неё тот же конфиг валиден на машине разработчика и падает в контейнере без
+zoneinfo, а сообщение указывает не на ту причину.
+
+### R15. Невалидный конфиг — `ERROR` и выход из `main`
+
+**ДОЛЖЕН.** `main` пишет `slog` уровня `ERROR` и вызывает `os.Exit(1)` до
+старта серверов и воркеров.
+
+**Почему.** Выход именно из `main`: `os.Exit` в библиотечном пакете не
+оставляет вызывающему возможности ни залогировать причину, ни дописать
+контекст, и отложенные `defer` при нём не выполняются вовсе. Выход именно
+до старта воркеров: горутина, поднятая раньше валидации, успевает сходить
+во внешний сервис и записать в базу от имени процесса, который потом
+объявит, что не стартовал.
+
+<!-- local:поля -->
+<!-- /local -->
+
+<!-- local:механизировано -->
+<!-- /local -->
+
+## Связано
+
+- `lang/go/time.md` — зона отображения и формат времени.
+- `lang/go/logging.md` — `slog`, которым падает невалидный конфиг.
+
+<!-- local:связано -->
+<!-- /local -->

conventions/lang/go/db-identifiers.md

@@ -0,0 +1,130 @@
+---
+extends: arch/db-identifiers.md
+---
+
+# Идентификаторы: реализация на Go
+
+Как `arch/db-identifiers.md` выглядит в Go-приложении, выбравшем ULID
+(ветка `arch/db-identifiers.md` R1.1). Форма записи — `LANGUAGE.md`.
+
+Единая точка из `arch/db-identifiers.md` R3 — пакет `internal/ident`: он
+порождает идентификаторы (`NewID`, `NewIDAt`) и он же их разбирает
+(`Parse`). Правила ниже говорят, из каких мест кода эти функции зовутся.
+
+## Правила
+
+### R1. Генерация и разбор — только через `internal/ident`
+
+**ДОЛЖЕН.** Идентификаторы порождаются и разбираются функциями пакета
+`internal/ident`; других генераторов и парсеров id в коде нет.
+
+**Почему.** Реализация `arch/db-identifiers.md` R3 и R4. Вызов
+ULID-библиотеки — одна строка, доступная из любого пакета, и на ревью он не
+выглядит нарушением: значение получается валидное, просто мимо нормализации
+регистра. Отдельный пакет переводит запрет в проверяемое свойство — импорт
+библиотеки где-либо, кроме `internal/ident`, находится поиском по имени
+модуля, а «забытая нормализация» не находится ничем, пока запрос молча не
+перестанет находить существующую запись.
+
+### R2. Первичный ключ генерируется в `Create`-методах store
+
+**ДОЛЖЕН.** Новая сущность получает значение PK вызовом `ident.NewID()`
+внутри `Create`-метода слоя store.
+
+**Почему.** `arch/db-identifiers.md` R2 требует, чтобы значение было
+известно до вставки, но не говорит, кто его присваивает. Store — последний
+слой, через который проходят все пути создания строки, включая импорт,
+фоновые задания и тесты. Генерация выше по стеку делает присвоение
+обязанностью каждого нового вызывающего, и первый забывший запишет пустую
+строку в колонку ключа: для строкового PK это валидное значение, база его
+не отклонит, и дефект обнаружится на второй такой вставке.
+
+### R3. Прочие идентификаторы генерируются в точке начала операции
+
+**ДОЛЖЕН.** Идентификатор батча, задания или корреляционный ключ создаётся
+вызовом `ident.NewID()` там, где операция начинается.
+
+**Почему.** Смысл такого идентификатора (`arch/db-identifiers.md` R7) —
+сшивать записи лога всей операции. Созданный ниже по стеку или в момент
+первой записи в базу, он не покрывает начальные шаги — а именно они нужны,
+когда операция упала до того, как что-либо записала: без общего ключа эти
+записи из лога не собираются вообще.
+
+### R4. Бэкфилл в миграциях — `ident.NewIDAt(t)`
+
+**ДОЛЖЕН.** Идентификаторы, проставляемые существующим строкам в
+Go-миграции, порождаются с историческим временем строки, а не с текущим.
+
+**Почему.** Сортировка id тогда сохраняет историческую хронологию, а не
+момент прогона миграции. Иначе все затронутые строки получают метку одного
+момента, склеиваются в нём и встают в порядке обхода — `ORDER BY id`
+начинает врать ровно на том массиве данных, который старше всего.
+Исправить это потом нельзя: исходное время в идентификаторе не
+восстановить.
+
+### R5. Разбор — на входных границах, до обращения к store
+
+**ДОЛЖЕН.** `ident.Parse()` вызывается в обработчике HTTP-роута, формы или
+callback'а бота — раньше, чем идентификатор попадёт в store.
+
+**Почему.** Реализация `arch/db-identifiers.md` R5. Граница выбрана
+транспортная, потому что только на ней известен источник значения, от
+которого зависит реакция (R8): store видит одинаковую строку независимо от
+того, пришла она из URL или из собственной формы, и ответить по-разному
+оттуда уже невозможно.
+
+### R6. Id в структурах — обычный `string`
+
+**СЛЕДУЕТ.** Поля идентификаторов в доменных и store-структурах имеют тип
+`string`.
+
+**Почему.** Отдельный тип окупается только тогда, когда компилятор ловит им
+ошибку. От перепутывания двух идентификаторов одной семьи (`userID` и
+`authorID`) он не спасает — оба будут одного типа, и различают их имена
+параметров. Зато он требует конверсий на каждой границе с sql-драйвером,
+json и шаблонами, то есть даёт цену без выгоды.
+
+### R7. Отдельный тип — когда появляется вторая семья идентификаторов
+
+**ДОПУСКАЕТСЯ.** Когда в коде оказываются два вида идентификаторов, которые
+можно перепутать, для них заводятся различимые типы.
+
+**Почему.** Явное разрешение нужно, чтобы R6 не читался как запрет на
+типизацию навсегда. Условие названо ровно то, при котором тип начинает
+работать: пока все идентификаторы — `string`, подстановка одного вида
+вместо другого компилируется и обнаруживается только на данных.
+
+### R8. Реакция на невалидный id зависит от источника
+
+**ДОЛЖЕН.** Когда разбор не удался, ответ определяется тем, откуда пришло
+значение:
+
+| № | Источник | Ответ |
+|---|---|---|
+| R8.1 | путь или query URL | 404 без обращения к store |
+| R8.2 | собственная форма, callback-данные кнопки | 400 либо понятное сообщение («кнопка устарела») |
+
+**Почему.** Реализация `arch/db-identifiers.md` R5.1 и R5.2 в терминах
+HTTP-кодов. В случае R8.1 снаружи это неотличимо от несуществующей записи —
+и хорошо: чужая или протухшая ссылка описывается так точно. В случае R8.2
+значение сформировало само приложение, и невалидность означает баг
+интерфейса или устаревший экран; ответ «не найдено» здесь выглядит штатно,
+в логах не оставляет аномалии и тем самым съедает единственный момент,
+когда дефект заметен.
+
+### R9. Транспорт не создаёт доменные ошибки
+
+**НЕ ДОЛЖЕН.** Обработчик не конструирует доменный sentinel (например
+`ErrNotFound`), чтобы тут же сопоставить его со своим ответом.
+
+**Почему.** Инверсия правила «трансляция у источника» из
+`lang/go/errors.md`. Sentinel — сообщение от слоя, который знает факт:
+строка не найдена, потому что store её искал. Сфабрикованный транспортом,
+он утверждает непроверенное, и по типу ошибки перестаёт быть видно, был ли
+вообще поход в хранилище — а на этом держится вся диагностика по ошибкам.
+
+<!-- local:механизировано -->
+<!-- /local -->
+
+<!-- local:отступления -->
+<!-- /local -->

conventions/lang/go/db-schema.md

@@ -0,0 +1,196 @@
+# Схема и миграции (SQLite, Go)
+
+Как пишутся миграции и какие типы колонок выбираются для схемы SQLite в
+Go-приложении. Форма записи — `LANGUAGE.md`.
+
+## Область действия
+
+Схема меняется тяжело: таблица не переезжает от того, что её потрогали.
+Правила распространяются на **новые миграции**; существующая схема не
+переписывается, и проверяется граница изменения — то, что миграция
+добавляет, а не то, что уже лежит в базе.
+
+## Миграции
+
+### R1. Миграции ведёт goose
+
+**ДОЛЖЕН.** Набор миграций репозитория применяется одним инструментом —
+goose.
+
+**Почему.** Журнал применённых версий goose держит в самой базе
+(`goose_db_version`) и по нему решает, что ещё не накатывалось. Второй
+инструмент заводит второй журнал: миграция, применённая одним, для другого
+выглядит неприменённой, и попытка накатить её повторно упирается в уже
+существующую таблицу. На сервере это означает ручной разбор состояния
+схемы вместо автоматического деплоя.
+
+### R2. Файлы миграций лежат рядом со store-слоем
+
+**СЛЕДУЕТ.** Миграции хранятся рядом с кодом, который работает с этой
+схемой.
+
+**Почему.** Миграция и код, читающий схему, — одно изменение: колонка
+появляется вместе с полем структуры и запросом. Лежащие в другом конце
+дерева миграции выпадают из поля зрения при правке store, и уезжает либо
+код без миграции, либо миграция без кода; расходятся они на сервере, где
+схема ещё старая.
+
+### R3. Форма миграции выбирается по тому, нужен ли код
+
+**ДОЛЖЕН.** Миграция пишется в той форме, которой требует её содержимое:
+
+| № | Что делает миграция | Форма |
+|---|---|---|
+| R3.1 | DDL: создание таблиц, индексы, изменение структуры | SQL-файл |
+| R3.2 | требует кода: генерация идентификаторов, backfill, перенос данных между формами | Go-миграция (`goose.AddMigrationContext`) |
+
+**Почему.** DDL ничего не вычисляет, и SQL-файл показывает ровно тот текст,
+который уедет в базу; обёртка на Go вокруг него добавляет место, где можно
+ошибиться, не добавляя ничего к результату.
+
+Обратное направление дороже. Перенос данных и генерация идентификаторов
+выражаются на SQL либо громоздко, либо неточно: идентификатор по
+`arch/db-identifiers.md` R2 порождает приложение, и SQL-миграция вынуждена
+завести для него второй генератор — ровно то, что запрещает
+`arch/db-identifiers.md` R3. Единообразие формы здесь покупается
+дублированием логики, которая уже есть в коде.
+
+### R4. В деплое схема движется только вперёд
+
+**НЕ ДОЛЖЕН.** Откат схемы на сервере не выполняется down-миграцией;
+ошибка исправляется новой миграцией вперёд.
+
+**Почему.** Down на сервере не возвращает прежнее состояние, а имитирует
+его: колонка, которую убрал up, восстанавливается пустой, а строки,
+записанные уже по новой схеме, в старую форму не ложатся. Потеря при этом
+происходит молча — миграция отчитывается об успехе. Исправление, приехавшее
+следующей миграцией, оставляет целыми и данные, и журнал применённых
+версий.
+
+### R5. Down пишется, когда он честно обращает up
+
+**ДОЛЖЕН.** Наличие down-миграции определяется тем, обратим ли up:
+
+| № | Что делает up | Down |
+|---|---|---|
+| R5.1 | добавляет структуру: таблицу, колонку, индекс | пишется, убирает добавленное |
+| R5.2 | необратимо преобразует данные | не пишется |
+
+**Почему.** Down — инструмент разработки, где ветку переключают туда-сюда,
+и именно там он обязан действительно обращать up. Имитация опаснее
+отсутствия: разработчик применяет её, получает схему прежней формы и
+продолжает работу, не заметив, что колонка вернулась пустой. Отсутствующий
+down останавливает сразу и заставляет пересоздать базу — это дешевле, чем
+отладка по данным, которых уже нет.
+
+### R6. ER-схема обновляется в том же изменении
+
+**ДОЛЖЕН.** Изменение структуры и правка ER-схемы в спеках едут одним
+изменением.
+
+**Почему.** Диаграмму читают вместо DDL — в этом весь её смысл.
+Разошедшаяся с базой, она не бесполезна, а даёт неверный ответ, и заметить
+это можно, только сверив её с миграциями, то есть проделав работу, которую
+диаграмма экономит. Отложенное обновление не делается: изменение уже
+влито, и повода вернуться к схеме больше нет.
+
+## Типы колонок
+
+Правила ниже описывают хранение в SQLite: выбор типа диктует движок базы,
+а не язык приложения.
+
+### R7. Enum-поля — `TEXT`, допустимые значения держит код
+
+**ДОЛЖЕН.** Поле-перечисление (`state`, `kind`, …) объявляется как `TEXT`
+без `CHECK`-ограничения на список значений.
+
+**Почему.** `ALTER TABLE` в SQLite не умеет менять ограничения ни в одной
+версии. Поэтому каждое новое значение перечисления в `CHECK (... IN (...))`
+превращается из строки в коде в пересоздание таблицы по 12-шаговой
+процедуре, с копированием данных и восстановлением внешних ключей.
+
+Платить эту цену не за что: невалидное значение отсекается типами Go
+раньше, чем дойдёт до вставки, и `CHECK` лишь дублирует защиту, которая
+всё равно нужна выше. `TEXT` при этом читается в дампе и в логе без
+таблицы соответствия, которую пришлось бы держать в голове для числового
+кода.
+
+### R8. Метки времени — `TEXT` в формате из `arch/time.md`
+
+**ДОЛЖЕН.** Колонка с меткой времени объявляется как `TEXT`, значения
+пишутся в формате из `arch/time.md`.
+
+**Почему.** Типа даты в SQLite нет, поэтому единственное, что делает
+значения сравнимыми, — договорённость о формате. Текст в формате из
+`arch/time.md` сортируется лексикографически в том же порядке, что и
+хронологически: `ORDER BY` и диапазонные условия работают без функций
+преобразования, а значит и без потери индекса. Соседство двух форматов в
+одной колонке ломает и сравнение, и разбор на стороне Go.
+
+### R9. Умолчание `DEFAULT (datetime('now'))` не ставится
+
+**НЕ ДОЛЖЕН.** Колонка с меткой времени не получает значение по умолчанию
+на уровне схемы.
+
+**Почему.** Время ставит приложение, и умолчание в схеме заводит второй
+источник этого значения: пропущенное приложением поле не падает, а тихо
+получает время сервера базы — расхождение обнаруживается по данным, а не
+по ошибке.
+
+Вдобавок `datetime('now')` даёт `YYYY-MM-DD HH:MM:SS` — без `T` и без `Z`,
+то есть не тот формат, которого требует R8. В колонке оказываются строки
+двух видов, и ломается ровно то, ради чего формат выбран.
+
+### R10. Булевы поля — `INTEGER` со значениями 0 и 1
+
+**ДОЛЖЕН.** Булево значение хранится как `INTEGER` 0/1.
+
+**Почему.** Отдельного булева типа в SQLite нет, поэтому от разнобоя
+колонку удерживает только договорённость о представлении. Цена ошибки
+здесь несимметрична: строка `'true'` в булевом контексте приводится к
+**0**, то есть даёт противоположный ответ, а не пустую выборку и не ошибку
+типа. Такой дефект не падает, не виден в логе и переживает тесты, которые
+проверяют, что список не пуст.
+
+### R11. Вид первичного ключа задаёт `arch/db-identifiers.md`
+
+**ДОЛЖЕН.** В репозитории, подписанном на `arch/db-identifiers.md`, вид
+ключа выбирается по её R1, и `AUTOINCREMENT` в миграции не пишется.
+
+**Почему.** Вопрос о виде ключа решается один раз на репозиторий
+(`arch/db-identifiers.md` R1). Повторив здесь его ветвление, мы завели бы
+второй источник правды, и соседние таблицы разъехались бы по разным
+ответам на один и тот же вопрос.
+
+`AUTOINCREMENT` не нужен ни в одной из веток R1. Строкового ключа он не
+касается вовсе, а целочисленному даёт единственную гарантию — что значение
+rowid не будет переиспользовано после удаления строки, — ценой служебной
+таблицы `sqlite_sequence` и записи в неё на каждой вставке. Гарантия эта
+имеет смысл, только если старые идентификаторы живут где-то вне базы.
+
+### R12. Вне `arch/db-identifiers.md` первичный ключ — автоинкремент
+
+**ДОПУСКАЕТСЯ.** Репозиторий, не подписанный на `arch/db-identifiers.md`,
+берёт целочисленный автоинкрементный ключ.
+
+**Почему.** Явное разрешение нужно, чтобы R11 не читался как требование
+подписаться на `arch/db-identifiers.md`. Выбор вида ключа — решение уровня
+репозитория, и конвенция про типы колонок его за репозиторий не принимает;
+приложению, сущности которого не адресуют снаружи, целочисленный ключ
+ничего не стоит.
+
+<!-- local:механизировано -->
+<!-- /local -->
+
+<!-- local:отступления -->
+<!-- /local -->
+
+## Связано
+
+- `arch/time.md` — формат меток времени.
+- `arch/db-identifiers.md` — выбор первичных ключей.
+- `lang/go/errors.md` — граничные ошибки `database/sql` транслируются в
+  доменные у источника, в слое store.
+
+<!-- local:связано -->
+<!-- /local -->

conventions/lang/go/errors.md

@@ -0,0 +1,322 @@
+# Ошибки
+
+Как ошибки строятся, оборачиваются и проверяются. Форма записи —
+`LANGUAGE.md`. Где и когда ошибку **логировать** — в
+`lang/go/logging.md` (коротко: лог один раз на доменной границе).
+
+## Правила
+
+### R1. Ошибки строятся средствами стандартной библиотеки
+
+**ДОЛЖЕН.** Ошибки создаются и оборачиваются через `errors` и
+`fmt.Errorf`; библиотеки со стек-трейсами не подключаются.
+
+**Почему.** Стек и цепочка обёрток решают одну задачу — локализацию места.
+При дисциплине «каждый слой добавляет свой контекст» (R3) цепочка сообщений
+локализует не хуже, а стоит ничего: остальной контекст ошибки уже несёт
+`slog`. Библиотека со стеками добавляет зависимость, собственный тип ошибки
+и обычно инфраструктуру доставки стеков (Sentry) — для домашнего сервиса
+это цена без покупателя.
+
+Единственное место, где стек всё-таки нужен, — восстановленная паника: у
+неё цепочки `%w` нет вовсе (R23).
+
+### R2. Дефолт не обходится точечно
+
+**НЕ ДОЛЖЕН.** Пакет со стек-трейсами не заводится в отдельном месте
+кодовой базы ради конкретной отладки.
+
+**Почему.** В коде появляются два способа устроить ошибку, и вызывающий
+перестаёт знать, какой перед ним: обёртки склеиваются по-разному,
+`errors.Is` работает не везде одинаково. Хуже второе: боль, снятая
+локально, перестаёт накапливаться — а накопление и есть единственный
+сигнал, что решение R1 пора пересматривать целиком.
+
+### R3. Каждый слой добавляет свой контекст
+
+**ДОЛЖЕН.** Ошибка, возвращаемая на уровень выше, оборачивается с
+контекстом: `fmt.Errorf("parse magnet: %w", err)`.
+
+**Почему.** На этом держится R1: цепочка заменяет стек ровно настолько,
+насколько слои в неё пишут. Слой, пробросивший ошибку без своего контекста,
+стирает участок пути — по итоговому сообщению нельзя сказать, через какую
+операцию ошибка прошла, и отладка «no such file» начинается с чтения всего
+кода.
+
+### R4. Обёртка по умолчанию — `%w`
+
+**СЛЕДУЕТ.** Глагол выбирается по тому, раскрываем ли мы причину
+вызывающему:
+
+| № | Ситуация | Глагол |
+|---|---|---|
+| R4.1 | вызывающий может инспектировать причину (обычный случай) | `%w` |
+| R4.2 | причину сознательно не раскрываем | `%v` |
+
+**Почему.** Возражение против дефолтного `%w` — «обёрнутая ошибка
+становится частью API» — относится к библиотекам с внешними потребителями.
+Сервис же — приложение: внешнего Go-API нет, весь код наш, контракт
+меняется вместе с вызывающими. Зато `%v` в середине цепочки обрывает
+`errors.Is` и `errors.As` для всех слоёв выше, и ветвление по sentinel'у
+(R10) молча перестаёт срабатывать — дефект проявляется как «код не заметил
+`ErrNotFound`», далеко от места обрыва. R4.2 остаётся для случая, когда
+завязывать вызывающего на чужой тип ошибки не хотят намеренно.
+
+### R5. Утечка внутренних деталей лечится трансляцией, а не `%v`
+
+**НЕ ДОЛЖЕН.** `%v` не используется как средство не пустить внутреннюю
+ошибку наружу.
+
+**Почему.** Обрыв цепочки внутри кода не мешает тексту уехать наружу
+целиком: наружу отдаёт внешняя граница, и если она отдаёт `err.Error()`,
+детали утекут при любом глаголе. Подмена не решает задачу, ради которой
+сделана, а плату берёт сразу — `errors.Is` ломается у всех вызывающих.
+Настоящее место защиты — R13.
+
+### R6. Текст обёртки — со строчной буквы и без служебных слов
+
+**СЛЕДУЕТ.** Без точки в конце, без «failed to» и «error».
+
+**Почему.** Цепочка склеивается в одну строку через `": "`, и обёртка
+читается как «контекст: причина» — заглавные буквы и точки рвут эту строку
+на середине. Слова «failed» и «error» не несут информации: то, что перед
+нами ошибка, известно из того, что это ошибка. Зато повторяются они на
+каждом уровне и вытесняют из строки полезный контекст.
+
+### R7. Контекст обёртки называет операцию или субъект
+
+**СЛЕДУЕТ.** В обёртку идёт то, что делал слой: `"link target: %w"`.
+
+**Почему.** Обёртка ценна ровно тем, что сужает место (R3). «something
+failed» не сужает ничего и при этом занимает в сообщении место, которое мог
+бы занять единственный полезный здесь факт — имя операции.
+
+### R8. Слой не повторяет смысл нижнего
+
+**НЕ СЛЕДУЕТ.** Обёртка не пересказывает то, что уже сказал уровень ниже:
+`"add to qbt: %w"`, а не `"add download failed: add to qbt failed: …"`.
+
+**Почему.** Повтор удлиняет сообщение, не добавляя локализации: одно и то
+же событие названо дважды. Читателю приходится проверять, не два ли это
+разных места в коде, — то есть заикание не просто бесполезно, оно стоит
+времени при каждом чтении лога.
+
+## Две трансляции
+
+Ошибка меняет форму дважды, и это разные преобразования: инфраструктурная →
+доменная у источника (R9) и доменная → пользовательская на внешней границе
+(R13). Первую делает слой, работающий с зависимостью, вторую — транспорт.
+
+### R9. Инфраструктурная ошибка транслируется в доменную у источника
+
+**ДОЛЖЕН.** Граничная ошибка зависимости превращается в доменную там, где
+возникла: `sql.ErrNoRows` → `store.ErrNotFound` в слое store; то же для
+HTTP-клиентов, файловой системы, внешних SDK.
+
+**Почему.** Иначе тип зависимости становится частью контракта всех слоёв
+выше: чтобы отличить «нет записи», доменный код импортирует `database/sql`
+и сравнивает с его sentinel'ом. Замена хранилища или SDK правит тогда не
+адаптер, а все ветвления в приложении — притом что снаружи адаптера
+состояние «нет записи» одно и то же. Трансляция у источника оставляет
+знание о зависимости в единственном слое, который её и так знает.
+
+### R10. Форма доменной ошибки выбирается по тому, что нужно вызывающему
+
+**ДОЛЖЕН.** Между sentinel'ом и типом выбирают так:
+
+| № | Что нужно вызывающему | Форма |
+|---|---|---|
+| R10.1 | ветвление по условию: нет записи, дубликат, неподдерживаемый источник | sentinel `var ErrNotFound = errors.New("not found")`, проверка `errors.Is` |
+| R10.2 | данные ошибки: поле валидации, код, лимит | тип с полями и методом `Error()`, извлечение `errors.As` |
+
+**Почему.** Sentinel — одно значение; сравнение с ним не зависит от
+структуры ошибки и переживает добавление полей. Тип заводится ради данных,
+и тип без данных отвечает вызывающему ровно то же, что sentinel, но ценой
+объявления, `errors.As` и вопроса «сравнивать по типу или по значению» на
+каждой проверке. Две формы для одного условия — это два способа его
+проверить, и про второй рано или поздно забудут.
+
+### R11. Матчинг по тексту сообщения
+
+**НЕ ДОЛЖЕН.** Ветвление по содержимому `err.Error()` не используется.
+
+**Почему.** Текст сообщения — не контракт: R6–R8 разрешают переписывать его
+свободно. Правка формулировки в нижнем слое молча ломает ветвление
+наверху, и компилятор этого не видит. Это то же самое, что публичный API из
+строки лога.
+
+## Граница: приватный канал и публичный
+
+Внутри — богатые обёрнутые ошибки. На внешней границе форма зависит от
+того, кто канал видит: приватный канал — логи (их читает владелец сервиса),
+публичный — пользовательские поверхности (HTTP API, web-UI, бот).
+
+### R12. Полная ошибка идёт в приватный канал
+
+**ДОЛЖЕН.** В лог уходит вся цепочка `%w` с контекстом; где и когда именно
+— `lang/go/logging.md`.
+
+**Почему.** Цепочка — единственный носитель диагностики (R1), и
+единственный канал, где её можно показать целиком, — тот, который видит
+владелец. Не записанная там, она не сохранится нигде: наружу идёт
+нейтральное сообщение (R13), и восстанавливать причину будет не из чего.
+
+### R13. Публичная поверхность получает сообщение по доменной ошибке
+
+**ДОЛЖЕН.** Наружу идёт человекочитаемый текст по доменной ошибке, а не
+`err.Error()` и не детали реализации (`database/sql`, пути, стек).
+
+**Почему.** Внутренние детали пользователю нечитаемы, а владельцу не нужны
+— у него есть лог (R12). Зато они раскрывают устройство системы — имена
+таблиц, пути на диске, версии зависимостей — тому, кто их знать не должен,
+причём раскрывают именно в момент, когда что-то пошло не так.
+
+### R14. Публичное сообщение несёт корреляционный ключ
+
+**ДОЛЖЕН.** Наружу вместе с сообщением идёт id сущности либо `request_id`:
+«При обработке загрузки произошла ошибка, download_id=…» вместо «произошла
+ошибка».
+
+**Почему.** R13 забирает у пользователя всю фактуру; без ключа его
+обращение звучит как «у меня что-то не работает», и владелец ищет запись в
+логе по времени и догадкам. Ключ соединяет нейтральный ответ с полной
+ошибкой в логе, не раскрывая наружу ничего сверх того, что пользователь уже
+видел.
+
+### R15. Маппинг доменных ошибок — в одной точке на все транспорты
+
+**ДОЛЖЕН.** Соответствие «доменная ошибка → сообщение и, для HTTP, статус»
+задаётся один раз; транспорт без статусов (бот) берёт из него только
+сообщение.
+
+**Почему.** Иначе одна и та же ошибка отвечает по-разному в HTTP и в боте,
+и расхождение обнаруживается не как дефект, а как жалоба. Вторая причина
+важнее: единственная точка — это место, куда механически дописывается новая
+ветвь (R16). Маппинг, размазанный по хендлерам, требование «дописать везде»
+ничем не проверяет.
+
+### R16. Новая штатная ветвь отказа сразу попадает в маппинг
+
+**ДОЛЖЕН.** Ожидаемый отказ (конфликт, валидация) заводится sentinel'ом и
+добавляется в маппинг (R15) тем же изменением.
+
+**Почему.** Ветка `default` врёт в обе стороны: транспорт отдаёт 500
+«внутренняя ошибка» на нормальный конфликт, а логирующая граница списывает
+его в `ERROR` вместо `DEBUG`. Второе хуже первого — штатные отказы начинают
+шуметь в логе ровно там, где по нему ищут настоящие поломки.
+
+<!-- local:маппинг -->
+<!-- /local -->
+
+### R17. Форма текста определяется поверхностью
+
+**ДОЛЖЕН.** У публичной границы две разные поверхности, и правило сырого
+текста для них разное:
+
+| № | Поверхность | Текст ошибки |
+|---|---|---|
+| R17.1 | транзиентный ответ на действие: тело ответа, `?err=`, реплика бота по результату команды | строго нейтральный, из маппинга (R15); `err.Error()` наружу не идёт |
+| R17.2 | персистентная диагностика состояния: причина ухода записи в ошибочное состояние, сохранённая в БД и показанная оператору | сырой текст ошибки (пути, фрагмент ответа внешнего сервиса) — пока поверхность видит исключительно владелец |
+
+Появился второй зритель или публичный доступ к экрану состояния —
+поверхность стала публичным каналом, и на неё распространяется R17.1.
+
+**Почему.** Транзиентный ответ читает тот, кто нажал кнопку: сырой текст
+ему ничего не объясняет, а владельцу не нужен — у него лог. Персистентную
+диагностику читает владелец, и она отвечает на вопрос «почему сломалась вот
+эта запись» через месяц, когда лог уже ротировался; нейтральное «произошла
+ошибка» в таком поле не несёт ничего и делает поле бессмысленным. Условие
+про единственного зрителя — ровно то, что делает вторую поверхность
+приватным каналом; без него это обычная публичная поверхность.
+
+### R18. Секретов нет ни на одной из поверхностей
+
+**НЕ ДОЛЖЕН.** Токены, пароли и ключи не попадают ни в транзиентный ответ,
+ни в персистентную диагностику; источник вычищается на границе клиента.
+
+**Почему.** Запрет абсолютен, потому что персистентная диагностика живёт в
+БД: уезжает в бэкапы, попадает в скриншоты и выгрузки и переживает ротацию
+самого секрета. Вычистка на границе клиента — единственное место, где ещё
+известно, какие поля запроса секретны: дальше ошибка едет как текст, и
+отличить в нём токен от идентификатора уже нельзя.
+
+### R19. Диагностика хранится в отдельном поле
+
+**ДОЛЖЕН.** Персистентная диагностика не кладётся в доменное поле, которое
+показывают пользователю.
+
+**Почему.** Различие R17.1 и R17.2 держится на том, что у поверхностей
+разные поля. Одно поле на оба назначения означает, что при первом же показе
+записи наружу сырой текст уедет туда же — не по решению, а потому что поле
+одно.
+
+## panic
+
+### R20. `panic` — только для невосстановимого
+
+**ДОЛЖЕН.** Паникой отмечается нарушенный инвариант (баг программиста) и
+ошибка инициализации, из которой нельзя стартовать.
+
+**Почему.** Паника не оставляет вызывающему выбора: обработать её на месте
+нельзя, можно только уронить единицу обработки. Это верный ответ, когда
+состояние процесса перестало описываться кодом: работа с нарушенным
+инвариантом опаснее падения, а сервис, стартовавший без обязательной
+зависимости, всё равно откажет позже и непонятнее.
+
+### R21. Ожидаемые ошибки — значения `error`
+
+**НЕ ДОЛЖЕН.** Паника не используется для управления потоком: нет сети,
+плохой ввод, отсутствующая запись возвращаются как `error`.
+
+**Почему.** Сигнатура — единственное, что сообщает вызывающему о возможном
+отказе; отказ, брошенный паникой, из неё не виден, и компилятор не заставит
+его обработать. Дальше такая паника долетает до recover-границы (R22), где
+неотличима от бага: штатный отказ попадает в лог со стеком и с интонацией
+«мы сломались».
+
+### R22. `recover` — на верхней границе каждой обрабатывающей единицы
+
+**ДОЛЖЕН.** Своя граница ставится у каждой единицы, мотив у них разный:
+
+| № | Единица | Зачем `recover` |
+|---|---|---|
+| R22.1 | HTTP-хендлер | `net/http` восстанавливает панику сам и процесс не роняет; свой `recover` нужен, чтобы отдать контролируемый 500 и записать событие в `slog`, а не в stdlib-логгер |
+| R22.2 | цикл обработки апдейтов бота, фоновый воркер | паника в горутине роняет процесс; `recover` ставится в той же горутине |
+
+**Почему.** `recover` работает только в той горутине, где случилась паника,
+поэтому «у нас есть recover в HTTP» не защищает воркер — граница нужна у
+каждой единицы отдельно. Без неё один плохой апдейт бота или одна запись с
+неожиданным полем гасят весь сервис, включая части, к этой ошибке
+отношения не имеющие. У HTTP цена бездействия ниже, но не нулевая: паника
+без своего `recover` уходит мимо структурированного лога, а клиент получает
+оборванное соединение вместо ответа.
+
+### R23. Recover-граница пишет `debug.Stack()`
+
+**ДОЛЖЕН.** Логирующий `recover` кладёт в запись стек.
+
+**Почему.** Это единственное место, где стек нужен (R1): у восстановленной
+паники цепочки `%w` нет вовсе. «index out of range» без стека не
+диагностируется в принципе — сообщение не называет ни файла, ни операции,
+по нему нельзя сказать даже, в каком пакете упало.
+
+## Несколько ошибок
+
+### R24. Независимые ошибки собираются `errors.Join`
+
+**СЛЕДУЕТ.** Валидация конфига и подобные проверки отдают все проблемы
+разом; проверка собранного — по-прежнему через `errors.Is`.
+
+**Почему.** Возврат первой ошибки превращает починку конфига в серию
+перезапусков, по одной проблеме за прогон. Склейка сообщений в строку даёт
+тот же список, но убивает ветвление: `errors.Is` по такому результату не
+находит ничего, и вызывающий остаётся с текстом, матчить который запрещено
+(R11).
+
+## Связано
+
+- `lang/go/logging.md` — где и когда ошибка попадает в лог.
+- `arch/db-identifiers.md` R7 — формат корреляционного ключа из R14.
+
+<!-- local:механизировано -->
+<!-- /local -->

conventions/lang/go/logging.md

@@ -0,0 +1,550 @@
+---
+extends: arch/time.md
+---
+
+# Логирование
+
+Как и когда писать логи. Это правила оформления кода (How), а не
+спецификация поведения: наблюдаемые требования к логам, входящие в контракт
+функциональности, живут в спеках. Форма записи — `LANGUAGE.md`.
+
+Лог читают инструментами, а не глазами: повседневно — `jq`
+(`jq 'select(.download_id=="a1b2")' app.jsonl`), тяжёлое (агрегации, JOIN) —
+DuckDB поверх JSONL прямо из файла. Отсюда почти все правила ниже: запись
+существует для запроса к ней.
+
+```json
+{"time":"2026-06-28T11:23:45.123Z","level":"INFO","msg":"download accepted","download_id":"01jz2k7f8q9r3s4t5v6w7x8y9z","media_type":"movie"}
+```
+
+## Формат записи
+
+### R1. Структурированный JSON, один формат для dev и prod
+
+**ДОЛЖЕН.** Хендлер — `slog.JSONHandler`, одинаково в разработке и в
+проде.
+
+**Почему.** Довод не в том, что текстовый вывод «расходит поля»: смена
+хендлера структуру атрибутов не меняет. Довод в читателе — с текстовым
+dev-выводом перестаёшь ежедневно гонять собственные `jq`-пайплайны, и
+поломки словаря (опечатка в имени поля, потерянный атрибут, склеенное
+значение) обнаруживаются только в проде, где заметить их заранее уже
+некому.
+
+### R2. Данные — в типизированных полях, а не в тексте сообщения
+
+**ДОЛЖЕН.** Каждая величина — отдельный ключ со значением своего типа.
+
+**Почему.** Фильтрация и агрегация работают по ключам; величина, вклеенная
+в текст, достаётся только регуляркой, а регулярка ломается при первой же
+правке формулировки. Тип важен отдельно от ключа: число внутри строки не
+сравнивается и не суммируется, то есть попадает в лог, но не в отчёт.
+
+### R3. Время записи — UTC
+
+**ДОЛЖЕН.** `time` приводится к UTC через `ReplaceAttr` по `slog.TimeKey`
+(см. `lang/go/time.md`).
+
+**Почему.** По умолчанию UTC не получится: встроенные хендлеры пишут время
+в зоне самого `time.Time`, то есть в локальной зоне процесса. Записи одного
+процесса до и после смены TZ (или записи рядом с данными из БД) перестают
+складываться в одну хронологию, причём сдвиг на целые часы глазом не виден
+— в отличие от явно неверной даты, он выглядит как правдоподобный порядок
+событий.
+
+Точность `JSONHandler` — миллисекунды фиксированной ширины; это другая
+точность, чем в БД, и по `arch/time.md` так и должно быть: ширина
+фиксируется на носитель.
+
+## Сообщение
+
+### R4. `msg` — константа в нижнем регистре
+
+**ДОЛЖЕН.** Текст сообщения не собирается из переменных:
+`log.Info("download accepted", "download_id", id)`.
+
+**Почему.** `msg` — то, по чему записи группируют и считают. Интерполяция
+превращает одну категорию в множество уникальных строк, и вопрос «сколько
+раз это случилось» перестаёт решаться группировкой. Нижний регистр — чтобы
+одна категория не двоилась на варианты, различающиеся только заглавной
+буквой.
+
+### R5. `msg` не несёт префикса подсистемы
+
+**НЕ ДОЛЖЕН.** `recognition done`, а не `recognize: done`; подсистема —
+отдельное поле.
+
+**Почему.** Префикс кладёт в текст ровно то, по чему потом фильтруют, и
+фильтр по подсистеме становится сопоставлением с началом строки вместо
+сравнения значения поля. Заодно это второй способ записать одно и то же:
+категория дробится на варианты с префиксом и без, а совпадать они обязаны
+посимвольно.
+
+### R6. Смена состояния сущности — единая категория
+
+**ДОЛЖЕН.** `state transition` с полями `from`/`to`/`code`; какое именно
+состояние и по какой причине — данные, а не текст.
+
+**Почему.** С отдельной категорией на каждый переход жизненный цикл
+сущности собирается перечислением всех известных `msg` — и переход,
+добавленный в код позже, в это перечисление не попадёт: выборка тихо
+останется неполной. Единая категория даёт весь цикл одним фильтром и не
+требует обновлять запрос вслед за кодом.
+
+### R7. Физический эффект — отдельная запись, а не вместо перехода
+
+**НЕ ДОЛЖЕН.** Запись о действии, сопровождающем переход, не подменяет
+запись самого перехода.
+
+**Почему.** Иначе из выборки по R6 выпадают именно те переходы, у которых
+был заметный эффект, — то есть самые интересные. Вторая запись стоит одной
+строки в логе; восстановление пропущенного перехода не стоит ничего, потому
+что невозможно.
+
+## Уровни
+
+### R8. Уровень выбирается по адресату
+
+**ДОЛЖЕН.** Уровень отвечает на вопрос «кому сообщение», а не «насколько
+громко сломалось».
+
+| № | Уровень | Кому и когда |
+|---|---|---|
+| R8.1 | `DEBUG` | разработчику при отладке; в проде выключен |
+| R8.2 | `INFO` | владельцу, аудит постфактум |
+| R8.3 | `WARN` | владельцу, «может стать проблемой» |
+| R8.4 | `ERROR` | владельцу, в разбор |
+
+**Почему.** Адресат — единственный признак, по которому разные авторы в
+разных местах кода выберут уровень одинаково. «Насколько серьёзно» каждый
+оценивает по-своему, шкала расползается — и вместе с ней теряет смысл
+базовый порог в проде (R40), потому что он отсекает уже не то, что
+задумано.
+
+### R9. Уровень не зависит от подсистемы
+
+**НЕ ДОЛЖЕН.** Происхождение записи на выбор уровня не влияет: `ERROR`
+везде одинаково серьёзен.
+
+**Почему.** Фильтр по уровню собирает записи из всех подсистем сразу. Если
+в шумной подсистеме `ERROR` «дешевле», читателю приходится помнить
+происхождение каждой записи, чтобы понять, надо ли реагировать, — то есть
+уровень перестаёт быть фильтром и становится подсказкой, требующей знания
+кода.
+
+### R10. `WARN` — только когда «может стать проблемой»
+
+**ДОЛЖЕН.** Если «может» не про эту запись, уровень — `INFO`.
+
+**Почему.** `WARN` разбирают вручную и целиком. Как только в нём заводится
+«ничего страшного», его перестают читать — и вместе с шумом теряется то
+единственное, ради чего уровень существует: предупреждение, на которое ещё
+есть время отреагировать.
+
+### R11. Событийное — `INFO`, рутинно-частое — `DEBUG`
+
+**ДОЛЖЕН.** Уровень зависит от того, стоит ли за операцией событие.
+
+| № | Операция | Уровень |
+|---|---|---|
+| R11.1 | по реальному действию или изменению | `INFO` |
+| R11.2 | повторяющаяся служебная, по таймеру или поллингу, сама по себе события не несущая (healthcheck, опрос статуса, авто-рефреш UI) | `DEBUG` |
+
+**Почему.** `INFO` — аудит постфактум (R8.2), и его пригодность
+определяется долей записей, за которыми что-то стоит. Периодическая
+операция даёт ровный поток при нулевой информации, в котором настоящие
+события тонут количественно: их не отфильтровать, потому что фильтровать
+приходится по содержанию, а не по уровню.
+
+### R12. Фатальный сбой на старте — `ERROR` и ненулевой код возврата
+
+**ДОЛЖЕН.** `slog` не разделяет CRITICAL/FATAL, поэтому недостающую
+степень даёт завершение процесса.
+
+**Почему.** Супервизор (docker, journald, systemd) отличает падение от
+штатной остановки по коду возврата, а не по уровню последней записи.
+Процесс, который написал `ERROR` и продолжил жить с неработающей
+конфигурацией, выглядит здоровым и будет получать трафик; изобретать же
+уровень выше `ERROR` не нужно — сам факт завершения информативнее.
+
+## Поля: единый словарь
+
+### R13. Одно поле — одно имя по всему коду
+
+**ДОЛЖЕН.** Не `mediaType`/`media`/`media_type` вперемешку.
+
+**Почему.** Имя поля — и есть интерфейс запроса к логам. Второе имя для той
+же величины делает любую выборку по ней молча неполной: фильтр отработает,
+часть записей в него не попадёт, и заметить это можно, только заранее зная,
+что они должны были быть.
+
+### R14. Форма имени зависит от вида поля
+
+**ДОЛЖЕН.** Две формы, третьей нет.
+
+| № | Вид поля | Форма имени |
+|---|---|---|
+| R14.1 | бизнес-поле | плоский `snake_case`: `download_id`, `media_type` |
+| R14.2 | системный домен | точечная иерархия (адаптация OpenTelemetry): `http.*`, `ext.*` |
+
+**Почему.** Точка отделяет поля, приходящие от инфраструктуры и одинаковые
+в любом проекте, от доменных, которые в каждом свои: по общему префиксу
+запрос «все внешние вызовы» пишется без перечисления имён. Заимствование
+словаря OpenTelemetry снимает необходимость изобретать имена тому, что уже
+названо, и спорить о них на каждом ревью.
+
+### R15. Запись плоская
+
+**НЕ ДОЛЖЕН.** Вложенных объектов в записи нет; точка в имени — часть
+имени, а не уровень вложенности.
+
+**Почему.** Плоский ключ адресуется одинаково в `jq`, в DuckDB и в любой
+записи независимо от её категории. Вложенность требует знать глубину
+заранее, а она у разных категорий разная — и один запрос перестаёт покрывать
+весь лог, распадаясь на запрос под каждую форму записи.
+
+### R16. Набор полей определяется ситуацией
+
+**ДОЛЖЕН.** Записи каждой ситуации несут её набор целиком.
+
+| № | Когда добавляем | Поля |
+|---|---|---|
+| R16.1 | входящий HTTP-запрос (middleware) | `http.method`, `http.route`, `http.status_code`, `duration_ms`, `transport` — если транспортов больше одного |
+| R16.2 | работа с сущностью (scoped-логгер) | `<entity>_id` и доменные атрибуты |
+| R16.3 | запись об ошибке | `error` |
+| R16.4 | вызов внешнего сервиса | `ext.service`, `ext.operation` (логическая операция, не URL), `ext.status_code`, `duration_ms`, `retry` |
+
+**Почему.** Набор задан не «на всякий случай»: без него запись не отвечает
+на свой вопрос. HTTP-запись без `duration_ms` не показывает деградацию,
+`ext`-запись без `ext.service` не отделяет «легла зависимость» от «у нас
+баг», запись о сущности без идентификатора не корреллируется (R19). Полный
+набор делает записи однородными — один запрос работает по всем вызовам, а
+не по тем, где автор вспомнил про поле.
+
+### R17. `service.*` и `host.*` не заводим
+
+**НЕ СЛЕДУЕТ.** Пока это один бинарь на одном хосте.
+
+**Почему.** Поле с одним и тем же значением во всех записях не несёт
+информации, но стоит места в каждой строке и внимания при чтении. Условие
+названо явно, поэтому правило отпадёт вместе со своей причиной: с
+появлением нескольких инстансов различающее поле (`service.version`)
+добавляется одной строкой при старте.
+
+<!-- local:словарь -->
+<!-- /local -->
+
+## Корреляция
+
+### R18. Ключ корреляции — идентификатор сущности, а не `trace_id`
+
+**НЕ СЛЕДУЕТ.** Отдельный случайный `trace_id` не заводится, если у
+сущностей есть стабильные уникальные идентификаторы. (Как их выбирают —
+`arch/db-identifiers.md`, если конвенция взята.)
+
+**Почему.** Идентификатор сущности уже существует, стабилен между
+процессами и во времени — по нему собираются записи не одного прохода, а
+всей истории сущности, включая вчерашнюю. `trace_id` даёт то же самое
+только внутри одной операции, то есть дублирует ключ и добавляет второй
+способ спросить об одном. Условие применимости названо: там, где сущности
+со стабильным идентификатором нет, связывать записи больше нечем.
+
+### R19. Запись о сущности несёт её идентификатор
+
+**ДОЛЖЕН.** Поле `<entity>_id` в каждой записи, относящейся к сущности.
+
+**Почему.** Принадлежность записи восстанавливается только в момент
+записи; постфактум её не вывести — остаётся воспроизводить инцидент заново.
+Это же условие, при котором работает R18: отказ от `trace_id` оплачен тем,
+что идентификатор стоит везде, а не в удобных местах.
+
+Все записи одной операции собираются одним фильтром:
+`jq 'select(.download_id=="01jz…")' app.jsonl`. Если идентификатор
+глобально уникален across сущностей, штатно работает и простой `grep` по
+голому значению — он находит все упоминания независимо от имени поля.
+
+### R20. Долгая операция ведётся scoped-логгером через `context.Context`
+
+**СЛЕДУЕТ.** Логгер с дописанным ключом протаскивается сквозь асинхронные
+стадии:
+
+```go
+log := log.With("download_id", id)
+ctx = logctx.With(ctx, log) // достаём логгер из ctx в каждой стадии
+```
+
+**Почему.** Ручное дописывание ключа пропускают не в основном сценарии, а в
+редких ветках — обработке ошибок и ранних выходах, где корреляция нужнее
+всего. Логгер из контекста дописывает ключ сам, и запись без
+идентификатора становится невозможной, а не маловероятной.
+
+## Ошибки
+
+### R21. Ошибка логируется атрибутом `error`
+
+**ДОЛЖЕН.** `log.Error("layout failed", "error", err, "download_id", id)`.
+
+**Почему.** Ошибка, вклеенная в текст сообщения, дробит категорию (R4) и
+уносит текст туда, где по нему нельзя отфильтровать. Ключ единый — так же,
+как по умолчанию в zap/zerolog: выборка «все записи с ошибкой» не должна
+зависеть от того, кто писал конкретный вызов, и ради этого единообразия
+краткостью жертвуют.
+
+### R22. Промежуточный слой либо логирует, либо возвращает
+
+**НЕ ДОЛЖЕН.** Слой, возвращающий ошибку выше, её не логирует — только
+оборачивает (`%w`).
+
+**Почему.** Иначе один сбой даёт столько записей, сколько слоёв он прошёл,
+и количество `ERROR` перестаёт соответствовать количеству отказов — а
+считают именно его. Контекст при этом не теряется: он накапливается в
+цепочке обёрток и попадает в единственную запись на границе (R23).
+
+### R23. Ошибка логируется один раз — на границе доменного слоя
+
+**ДОЛЖЕН.** Логирует единый чокпоинт, определяющий исход операции.
+
+**Почему.** У ошибки нужен ровно один логирующий, иначе неизбежны дубли; и
+этим местом выбрана доменная граница, а не транспорт, потому что там
+известен исход операции целиком и, значит, класс отказа (R25) — транспорт
+знает лишь то, что ему вернули ошибку. Побочный эффект того же выбора:
+транспорты остаются тонкими.
+
+<!-- local:границы -->
+<!-- /local -->
+
+### R24. Транспорт не логирует ошибку повторно
+
+**НЕ ДОЛЖЕН.** Транспорт переводит возвращённую ошибку в свой ответ
+(статус, сообщение пользователю) и на этом останавливается.
+
+**Почему.** Запись уже сделана на границе (R23); вторая отличается от неё
+только формулировкой и читается как второй сбой. Когда транспортов над
+одним доменом несколько, дублирование ещё и множится, а расследование
+начинается с вопроса, один это инцидент или два.
+
+### R25. Уровень доменного отказа — по классу отказа
+
+**ДОЛЖЕН.** Уровень выбирает единственный логирующий (R23), и выбирает по
+классу, а не по месту в коде.
+
+| № | Класс отказа | Кому | Уровень |
+|---|---|---|---|
+| R25.1 | штатный конфликт состояния или некорректный ввод | пользователю, он уже получил ответ | `DEBUG` |
+| R25.2 | расхождение производного или учётного состояния, первичные данные целы | владельцу, «может стать проблемой» | `WARN` |
+| R25.3 | сбой БД, ФС, недоступность зависимости | владельцу, в разбор | `ERROR` |
+
+**Почему.** Это применение R8 к отказам: пользователь уже увидел причину на
+экране — владельцу разбирать нечего; целостность первичных данных отделяет
+«надо посмотреть» от «надо чинить сейчас». Привязка к месту дала бы разный
+уровень для одного и того же отказа в зависимости от того, какой транспорт
+его вызвал, — и невалидный ввод из формы копился бы в `ERROR` наравне с
+упавшей базой.
+
+### R26. Тот же отказ в асинхронной стадии — уровнем выше
+
+**ДОЛЖЕН.** Когда пользователь не ждёт результата, отказ адресован
+владельцу как деградация автоматики: коллизия в ручном действии — `DEBUG`,
+она же в авто-обработке — `WARN`.
+
+**Почему.** В ручном действии человек видит причину на экране и сам решает,
+что делать дальше; запись нужна только для отладки. В автоматике не увидел
+никто, задача осталась недоведённой, и лог — единственное место, где это
+вообще проявится.
+
+### R27. Повторяющийся сбой фонового цикла — `WARN`
+
+**ДОЛЖЕН.** Тот же класс сбоя внутри синхронной операции — `ERROR`:
+уровень задаёт наличие штатного повтора, а не текст ошибки.
+
+**Почему.** Одиночный промах тика транзиентен — следующий тик повторит, и
+вмешательство не требуется; `ERROR` на каждый такой промах обесценивает
+уровень, на который смотрят в первую очередь. Синхронная операция повтора
+не имеет: она провалилась целиком, результат никто не восстановит, и это
+ровно тот случай, ради которого `ERROR` держат чистым.
+
+## Внешние сервисы
+
+### R28. Каждый вызов внешнего сервиса логируется
+
+**ДОЛЖЕН.** Все вызовы, включая успешные; поля — по R16.4.
+
+**Почему.** Это единственный способ отличить «у нас баг» от «зависимость
+легла»: на своей стороне видно лишь то, что операция не удалась.
+Выборочное логирование ломает и второе применение — доля неуспехов и
+распределение `duration_ms` считаются, только если знаменатель полный.
+
+### R29. Уровень `ext`-записи — по исходу вызова
+
+**ДОЛЖЕН.** Исход считается по одному вызову с его ретраями.
+
+| № | Исход | Уровень |
+|---|---|---|
+| R29.1 | успешный событийный вызов | `INFO` |
+| R29.2 | успешный рутинно-частый вызов (поллинг, авто-рефреш) | `DEBUG` |
+| R29.3 | попытка не удалась, делается retry | `WARN` |
+| R29.4 | ретраи исчерпаны, сервис недоступен | `ERROR` |
+
+**Почему.** Неудачная попытка, за которой следует повтор, — ещё не отказ:
+операция может завершиться успешно, и `ERROR` на каждую попытку сделал бы
+уровень непригодным для главного вопроса «зависимость доступна?».
+Исчерпание ретраев и есть момент, когда транспорт сдался и дальше
+разбираться владельцу. Различение R29.1 и R29.2 — то же самое разделение
+событийного и рутинного, что в R11: поллинг внешнего сервиса зашумляет
+аудит так же, как любой другой.
+
+## Два цикла повтора — не путать
+
+Слово «ретрай» означает два разных механизма, и уровень считается по
+каждому отдельно: повтор вызова внутри одной операции (ретраи HTTP-клиента)
+задаёт уровень `ext`-записи, повтор тика внешним циклом (поллинг, сверка) —
+уровень доменной записи об исходе тика.
+
+```
+WHEN зависимость недоступна и ретраи вызова исчерпаны → ext-запись `ERROR`   (R29.4)
+AND  тик фонового цикла упал по той же причине        → доменная запись `WARN` (R27)
+```
+
+Из этого следует, что у лежащей зависимости `ext`-запись пишет `ERROR`
+каждый тик. Это и есть механизм эскалации: доменный слой не паникует, а
+телеметрия зависимости честно показывает, что она недоступна. Если поток
+`ERROR` от поллинга мешает — это лечится понижением частоты тика или
+подавлением повторов в самом клиенте, а не переклассификацией уровня.
+
+### R30. Ответ 4xx — успех на транспортном уровне
+
+**ДОЛЖЕН.** Завершённый HTTP-ответ с 4xx логируется как успешный вызов
+(`ext.status_code` записан); решение «это ошибка» принимает доменный
+вызывающий.
+
+**Почему.** Транспорт своё дело сделал: запрос доставлен, ответ получен и
+разобран. Классифицировать 4xx как сбой транспорта значит смешать «сервис
+недоступен» с «сервис ответил нам нет» — это разные инциденты с разной
+реакцией, и различает их как раз `ext`-уровень. Что 404 значит для
+операции, знает только вызывающий: для одной это отказ, для другой —
+штатный ответ.
+
+## HTTP и healthcheck
+
+### R31. Входящий запрос — `INFO` независимо от кода ответа
+
+**ДОЛЖЕН.** Поля по R16.1; 4xx остаётся `INFO`-записью доступа.
+
+**Почему.** Это аудит обращений, а не отладка: запись отвечает на «кто и
+когда приходил», и ценность у неё одинаковая при любом коде ответа.
+Уровень, зависящий от кода, делает аудит неполным именно на тех запросах,
+которые чаще всего разбирают. Доменную оценку исхода даёт отдельная запись
+(R25) — она и адресована по-другому.
+
+### R32. Для корреляции запроса допустим `request_id`
+
+**ДОПУСКАЕТСЯ.** Это отдельный слой от корреляции по сущности.
+
+**Почему.** Явное разрешение снимает вопрос, не запрещает ли `request_id`
+правило R18. Не запрещает: R18 отказывается от случайного ключа там, где
+уже есть стабильный идентификатор сущности, а у HTTP-запроса собственной
+сущности нет — связать его записи между собой больше нечем.
+
+### R33. Healthcheck, liveness, readiness — `DEBUG`
+
+**ДОЛЖЕН.** Периодические проверки живости пишутся на отладочном уровне.
+
+**Почему.** Частный случай R11.2, названный отдельно, потому что нарушают
+его чаще всего: проверку дёргают по таймеру, и на `INFO` она вытесняет из
+аудита всё остальное — в проде с базовым `INFO` (R40) лог превратился бы в
+опрос самого себя. На `DEBUG` она не пишется вовсе и при этом остаётся
+доступной при отладке.
+
+## Безопасность: что не логируем
+
+### R34. Секреты не логируются
+
+**НЕ ДОЛЖЕН.** Ни в полях, ни в сообщениях: пароли и cookie сессий,
+API-ключи и токены, `Authorization`-заголовки, аутентификационные параметры
+в ссылках.
+
+**Почему.** Лог уезжает целиком в чужое хранилище, читается шире, чем код,
+и переживает ротацию самого секрета. Попавший в него секрет скомпрометирован
+с момента записи, а не с момента, когда это заметили, и вычистить его задним
+числом из уже собранных копий нельзя.
+
+### R35. Недоверенные и большие тела — только на `DEBUG`, после вычистки и обрезки
+
+**ДОЛЖЕН.** Тела запросов и ответов внешних API, сырой вывод LLM —
+`DEBUG`, с вычисткой секретов и обрезкой по длине.
+
+**Почему.** Содержимое пришло снаружи: размер не ограничен, состав
+неизвестен, а секрет в нём возможен по недосмотру той стороны. `DEBUG`
+выключен в проде (R40), поэтому цена ошибки ограничена отладочной сессией;
+обрезка не даёт одной записи вытеснить весь остальной лог за период.
+
+### R36. При сомнении логируется факт, а не значение
+
+**СЛЕДУЕТ.** `"has_api_key", true` вместо самого значения.
+
+**Почему.** Для отладки почти всегда достаточно ответа «значение было или
+не было» — потеря полезности близка к нулю, а риск снимается целиком.
+Правило нужно потому, что решение принимается в момент написания строки,
+когда чувствительность значения ещё неочевидна, а перечитывать этот выбор
+никто не придёт.
+
+### R37. `*url.Error` санитизируется на границе клиента
+
+**ДОЛЖЕН.** Ошибка разворачивается в первопричину **до** лога и до
+обёртки — раньше трансляции в доменную (`lang/go/errors.md`).
+
+**Почему.** `*url.Error` встраивает полный URL запроса, а секрет живёт
+прямо в нём: токен в пути, `api_key` в query. Go редактирует только пароль
+из userinfo, остального не трогает, поэтому ошибка уносит секрет и в
+обёртку, и в лог целиком. Порядок — часть нормы: санитизация после
+трансляции уже опоздала, секрет к этому моменту скопирован в текст обёртки.
+Цена — теряется `Op` и сам факт «это был HTTP-транспорт» (`errors.Is` на
+причину сохраняется); альтернатива с редактированием URL сохранила бы
+структуру, но сложнее.
+
+### R38. Секрет не кладётся в URL, если у API есть заголовок
+
+**НЕ ДОЛЖЕН.** Аутентификация параметром ссылки — только когда другого
+способа нет.
+
+**Почему.** Секрет в URL попадает не только в ошибку транспорта (R37), но и
+в любую запись, куда URL попал целиком, — то есть обязывает помнить про
+санитизацию в каждой такой точке, и одна забытая сводит остальные на нет.
+Заголовок снимает задачу в источнике: чего нет в URL, того нет и в ошибке.
+
+<!-- local:секреты -->
+<!-- /local -->
+
+## Куда пишем
+
+### R39. Логи идут в `stdout` одним потоком
+
+**ДОЛЖЕН.** Сбор и ротацию делает окружение (docker, journald); по файлам
+не маршрутизируем.
+
+**Почему.** Приложение, которое само решает, что куда писать, дублирует
+работу супервизора и расходится с ней при первой же смене окружения: срок
+хранения, сжатие и ротация оказываются настроены в двух местах и по-разному.
+Один поток вдобавок сохраняет порядок записей — маршрутизация по файлам
+теряет его ровно там, где важен ход событий.
+
+### R40. Базовый уровень — `INFO` в проде и `DEBUG` в dev
+
+**ДОЛЖЕН.** `DEBUG` в проде включается конфигом.
+
+**Почему.** Уровень — единственный регулятор объёма, доступный без
+пересборки; если `DEBUG` в проде включается только правкой кода, его не
+включают, и разбор инцидента идёт вслепую. `INFO` выбран базовым потому,
+что на нём аудит полон (R8.2), а рутинно-частое уже отсечено (R11.2).
+
+## Связано
+
+- `arch/time.md` — точность и зона меток времени фиксируются на носитель.
+- `lang/go/time.md` — как ставится UTC в `ReplaceAttr` (R3).
+- `lang/go/errors.md` — трансляция ошибки в доменную, порядок относительно
+  санитизации (R37).
+- `arch/db-identifiers.md` — откуда берутся стабильные идентификаторы,
+  на которых держится корреляция (R18).
+
+<!-- local:механизировано -->
+<!-- /local -->

conventions/lang/go/time.md

@@ -0,0 +1,171 @@
+---
+extends: arch/time.md
+---
+
+# Время: реализация на Go
+
+Как требования `arch/time.md` выполняются в Go-коде: откуда берётся
+«сейчас», в каком виде время попадает в базу и в логи, что делать с зонами.
+Форма записи — `LANGUAGE.md`.
+
+## Правила
+
+### R1. «Сейчас» берётся у слоя хранилища
+
+**ДОЛЖЕН.** Текущее время приходит из `store.Now()`, возвращающего
+`time.Now().UTC()`, а не из `time.Now()` по коду.
+
+**Почему.** Единая точка даёт гарантированный UTC и один формат: ни одна
+ветка кода не может о них забыть. Разъехавшиеся зоны чинятся только чтением
+всех записей — по метке `2026-06-28T11:23:45Z` уже не видно, была ли она
+когда-то локальной, и восстановить смещение задним числом не по чему.
+
+Тестируемость мотивом **не является**: точка — единственное место, которое
+придётся превратить в переменную или поле, если однажды понадобится
+подменять часы, но само по себе оно подмены не даёт.
+
+### R2. Форматирование и разбор — через `store.FormatTime` / `store.ParseTime`
+
+**ДОЛЖЕН.** Пара функций поверх `time.RFC3339` — единственный способ
+получить строку времени и прочитать её обратно.
+
+**Почему.** Layout, набранный по месту вызова, превращает формат хранения в
+свойство каждой отдельной строки кода. Фиксированная ширина (R4) и
+взаимная обратимость записи и чтения держатся ровно до первого второго
+layout — а расхождение проявится не на записи, а при сравнении значений,
+записанных разными местами.
+
+### R3. Прямой `time.Now()` запрещён линтером, список исключений исчерпывающий
+
+**ДОЛЖЕН.** Запрет механизируется `forbidigo`; исключений ровно два, и оба
+прописаны явно:
+
+| № | Исключение | Почему оно не покрывается R1 |
+|---|---|---|
+| R3.1 | сама точка `store.Now()` | внутри неё вызов `time.Now()` и происходит |
+| R3.2 | обёртка измерения длительности | приведение к UTC срезает монотонную составляющую (R10) |
+
+**Почему.** R1 без механической проверки держится на внимании, а
+`time.Now()` пишется рефлекторно — и в новом коде, и в мелкой правке;
+нарушение молчит до тех пор, пока процесс не окажется в не-UTC зоне.
+Исключения перечисляются исчерпывающе, потому что каждое из них — само по
+себе нарушение запрета: непрописанные, они либо роняют линтер, либо будут
+«починены» тем, кто увидит в них дефект, и конвенция начнёт противоречить
+сама себе.
+
+### R4. В БД время хранится с секундной точностью, ширина 20 символов
+
+**ДОЛЖЕН.** Каноническое значение в колонке — `2026-06-28T11:23:45Z`.
+
+**Почему.** Строки в колонке `TEXT` сравниваются побайтово, поэтому
+лексикографический порядок совпадает с хронологическим только при
+одинаковых ширине и форме. Значение с долями секунды сортируется **раньше**
+целой секунды того же момента (`.` меньше `Z`), то есть ломаются и
+`ORDER BY`, и диапазонные условия — на конкретных данных, а не на всех
+сразу.
+
+Ширина достаётся даром: layout `time.RFC3339` не содержит долей секунды,
+поэтому `Format` их не выведет.
+
+### R5. `time.RFC3339Nano` не используется
+
+**НЕ ДОЛЖЕН.** Ни как layout вывода, ни как формат хранения.
+
+**Почему.** Он отбрасывает хвостовые нули, из-за чего длина строки зависит
+от значения: соседние записи получают разную ширину, и свойство, на котором
+держится R4, исчезает незаметно. Проверка «формат корректен» при этом
+проходит — отказывает только порядок.
+
+### R6. Чужой вход нормализуется явно
+
+**ДОЛЖЕН.** Значение времени, пришедшее не от нашего писателя, приводится
+к каноническому виду явно, а не считается каноническим по факту успешного
+разбора.
+
+**Почему.** `time.Parse(time.RFC3339, …)` принимает и доли секунды, и
+офсеты, отличные от `Z`, — разбор шире вывода. Канонический вид гарантирует
+**писатель**, а не читатель; пока писатель один, этого достаточно, но
+значение из чужой системы, положенное в базу как пришло, нарушает R4 и
+обнаруживается не на записи, а на первой сортировке.
+
+### R7. В драйвер передаётся строка, а не `time.Time`
+
+**СЛЕДУЕТ.** В запрос идёт результат `FormatTime`.
+
+**Почему.** Колонка — `TEXT`, и передача `time.Time` отдаёт форматирование
+драйверу: появляется вторая точка формата вне `FormatTime` (R2), с
+собственным layout, который меняется вместе с версией драйвера, а не вместе
+с конвенцией.
+
+### R8. Время в логах приводится к UTC через `ReplaceAttr`
+
+**ДОЛЖЕН.** Хендлер `slog` переопределяет атрибут `slog.TimeKey`:
+
+```go
+func utcTime(_ []string, a slog.Attr) slog.Attr {
+    if a.Key == slog.TimeKey {
+        a.Value = slog.TimeValue(a.Value.Time().UTC())
+    }
+    return a
+}
+```
+
+**Почему.** `slog` по умолчанию UTC не даёт: встроенные хендлеры пишут
+время в зоне самого `time.Time`, то есть в локальной зоне процесса — на
+ноутбуке разработчика логи молча уезжают в `+03:00`. Умолчание тихое,
+неверная зона выглядит как совершенно валидное время, а записи из разных
+мест перестают складываться в одну хронологию с метками хранилища.
+
+### R9. Точность времени в логах отличается от точности в БД
+
+**ДОПУСКАЕТСЯ.** `JSONHandler` пишет миллисекунды — три знака, и это не
+приводится к секундной точности R4.
+
+**Почему.** Явное разрешение нужно, чтобы R4 не читался как требование
+одной точности везде. Ширина фиксируется на носитель: три знака в логе —
+такая же фиксированная ширина, и свойство, ради которого R4 существует, не
+нарушено. Общее у лога и базы одно — зона (R8).
+
+### R10. Обёртка измерения длительности берёт `time.Now()` напрямую
+
+**ДОПУСКАЕТСЯ.** Обёртка вызывает `time.Now()` и считает `time.Since` — с
+локальным `//nolint`.
+
+**Почему.** `store.Now()` приводит время к UTC через `.UTC()`, а это
+срезает монотонную составляющую `time.Time`. Интервал, посчитанный по таким
+меткам, зависит от подводки часов: перевод назад даёт отрицательную
+длительность, скачок вперёд — выброс в измерениях, и оба случая
+невоспроизводимы. Разрешение записано явно, иначе исключение R3.2 читается
+как недосмотр и его «чинят».
+
+### R11. `time/tzdata` импортируется в `main`
+
+**ДОЛЖЕН.** База зон вшивается в бинарь.
+
+**Почему.** Без неё `LoadLocation` зависит от файлов зон в системе, которых
+в минимальном образе нет: отказ происходит в рантайме, на первой же попытке
+применить зону, — то есть после выкладки, а не на сборке. Импорт именно в
+`main` держит это решение в одном видимом месте, а не в случайном пакете,
+откуда его удаляют при чистке зависимостей.
+
+### R12. Зона отображения применяется только в UI
+
+**ДОЛЖЕН.** Зона из конфига используется в шаблонах и форматтерах
+представления, но не в хранимых значениях и не в вычислениях.
+
+**Почему.** Зона отображения — настройка, и её меняют. Протекая в
+вычисления и хранение, она делает уже записанные данные зависимыми от
+текущего значения настройки: смена зоны задним числом сдвигает границы
+суток у того, что давно посчитано и сохранено.
+
+Календарные вычисления бизнес-логики берут зону явно — как описано в
+`arch/time.md`.
+
+<!-- local:механизировано -->
+<!-- /local -->
+
+## Связано
+
+- `arch/time.md` — базовая конвенция: UTC как формат хранения, явная зона в
+  календарных вычислениях.
+- `lang/go/config.md` — валидация зоны отображения загрузчиком конфига.

conventions/stack/ansible/app-directories.md

@@ -0,0 +1,122 @@
+---
+extends: arch/app-directories.md
+---
+
+# Категории директорий: реализация в Ansible
+
+Как категории из `arch/app-directories.md` раскладываются на сервере
+плейбуком. Форма записи — `LANGUAGE.md`.
+
+## Область действия
+
+Раскладка меняется вместе с миграцией данных, поэтому правила
+распространяются на **новые приложения**; существующие переезжают по мере
+касания, отдельной кампанией не переписываются.
+
+## Правила
+
+### R1. Каждая директория объявлена переменной `*_dir`
+
+**ДОЛЖЕН.** Директория приложения объявляется переменной плейбука внутри
+`base_dir`, имя оканчивается на `_dir`. Для случая «одна директория на
+категорию» это `config_dir`, `data_dir`, `cache_dir`; когда категория
+состоит из нескольких директорий, имя даётся по содержимому (`media_dir`,
+`uploads_dir`, `dumps_dir`).
+
+**Почему.** Переменная — единственная ссылка, которую разделяют задача
+создания директории и список бэкапа (R4). Литерал пути в одном из этих мест
+означает, что переименование директории молча разойдётся с бэкапом, и
+обнаружится это при восстановлении.
+
+### R2. Директории создаются одной задачей циклом по списку
+
+**СЛЕДУЕТ.** Список директорий в единственной задаче создания.
+
+**Почему.** Этот список — единственное место, где декларировано всё, что
+приложение пишет на диск. Разнесённое по нескольким задачам создание
+отвечает на вопрос «какие директории есть у приложения» только чтением
+всего плейбука, а именно этот вопрос задают при заведении бэкапа и при
+разборе места на диске.
+
+### R3. Владелец директорий — пользователь, от имени которого работает приложение
+
+**ДОЛЖЕН.** Конкретная модель — выделенный пользователь на приложение
+(`app_owner_uid == app_owner_gid`) или общий `primary_user` — выбирается на
+репозиторий и фиксируется ниже.
+
+**Почему.** Правило про соответствие владельца рантайму, а не про
+конкретную модель: приложение в контейнере пишет от определённого uid, и
+если директория принадлежит другому, отказ произойдёт не при деплое, а при
+первой записи — то есть после того, как плейбук отчитался об успехе. Выбор
+же модели — свойство репозитория: сервер с одним пользователем и сервер с
+изоляцией по приложениям решают разные задачи, и навязывать одну модель
+обоим значит гарантировать вечное отступление.
+
+<!-- local:модель-владельца -->
+<!-- /local -->
+
+### R4. Список бэкапа собирается из тех же переменных
+
+**ДОЛЖЕН.** Плейбук кладёт в `base_dir` файл `backup-targets`, строки
+которого ссылаются на переменные `*_dir` из R1, а не на литеральные пути.
+
+**Почему.** Правило вывода списка механическое (R5), но применяет его
+человек или шаблон — то есть ошибиться можно. Общая переменная делает целый
+класс ошибок невозможным: переименовал директорию — переименовалось в
+обоих местах. Независимо набранный список расходится тихо и проявляется в
+единственный момент, когда это уже неисправимо.
+
+### R5. В список бэкапа идут только данные
+
+**ДОЛЖЕН.** Директории категории «данные», включая директорию дампов, — в
+списке; конфигурация и кеш — нет.
+
+**Почему.** Реализация правила базовой конвенции. Кеш раздувает снапшот без
+пользы, а конфигурация содержит отрендеренные секреты — бэкап уезжает в
+облако, и источником истины для секретов остаётся vault, а не снапшот.
+
+### R6. Конфигурация монтируется только на чтение
+
+**СЛЕДУЕТ.** В compose конфигурация подключается с `:ro`.
+
+**Почему.** Плейбук — источник истины для конфигурации, и `:ro` превращает
+это из договорённости в свойство системы: приложение, которое втихую
+переписывает свой конфиг, падает сразу, а не расходится с репозиторием
+незаметно. Приложение, которому запись в конфиг нужна по устройству,
+монтируется на запись — это отступление, и оно записывается.
+
+### R7. `docker-compose.yml` лежит в корне `base_dir`
+
+**ДОЛЖЕН.** Файл не переносится во вложенную директорию.
+
+**Почему.** Туда смотрит `project_src` модуля `docker_compose_v2`. Правило
+внешнее по происхождению, но нарушается легко — при попытке «навести
+порядок» и убрать compose в `config/`, где ему по смыслу категорий было бы
+место.
+
+### R8. Секреты рендерятся в файл конфигурации
+
+**СЛЕДУЕТ.** Значения приходят из vault-переменных и попадают в файл,
+принадлежащий пользователю приложения.
+
+**Почему.** Файл под `0600` не наследуется дочерними процессами, не виден в
+`docker inspect` и не оседает в compose-файле на диске. Это те же три
+довода, по которым базовая конвенция конфигурации выбирает файл вместо
+окружения.
+
+### R9. Когда приложение не умеет файловые секреты — `environment` под `no_log`
+
+**ДОПУСКАЕТСЯ.** Задача рендера идёт с `no_log: true`.
+
+**Почему.** Явное разрешение нужно, чтобы R8 не читался как запрет на
+деплой такого приложения. Способ вынужденный: секрет попадает в метаданные
+контейнера и в compose-файл на диске. Приложение, научившееся читать
+секреты из файла, переводится на R8 при ближайшем касании.
+
+<!-- local:отступления -->
+<!-- /local -->
+
+## Связано
+
+<!-- local:связано -->
+<!-- /local -->

conventions/stack/htmx/web-ui.md

@@ -0,0 +1,459 @@
+# Веб-UI на htmx
+
+Как пишется код веб-UI: частичный своп фрагментов, поллинг живых
+обновлений, обработчики действий, деградация без JS, ошибки. Что именно UI
+показывает и какие действия поддерживает — в спеках, не здесь. Форма записи
+— `LANGUAGE.md`.
+
+Логирование запросов — `lang/go/logging.md` (HTTP-поля, рутинно-частое на
+`DEBUG`). Трансляция доменных ошибок наружу — `lang/go/errors.md`
+(приватный канал = логи, публичный = сообщение плюс корреляционный ключ).
+Здесь — только специфика htmx-транспорта, без дублирования.
+
+## Область действия
+
+Утверждения о поведении htmx относятся к **2.x**: дефолты обработки ответов
+между мажорами менялись. Правила описывают то, как написан код веб-UI, а не
+то, какие экраны и действия у приложения есть.
+
+## Стек и границы
+
+### R1. Стек: роутер, серверные шаблоны, htmx
+
+**ДОЛЖЕН.** UI собирается из серверных шаблонов и htmx — без шага сборки,
+без Node и бандлера, без реактивного фреймворка.
+
+**Почему.** Шаг сборки — это второй язык, второй менеджер зависимостей и
+артефакт, который расходится с исходником; приложению, где разметку целиком
+отдаёт сервер, он не покупает ничего. Реактивный фреймворк добавляет вторую
+модель состояния рядом с серверной (R2), и дальше на каждом экране
+приходится решать, какая из них главная. Сам htmx — вендорный ассет и
+живёт по правилам вендоринга (R32, R33): внешний CDN добавил бы к аптайму
+приложения аптайм чужого хоста.
+
+### R2. Клиент не пересчитывает доменное состояние
+
+**НЕ ДОЛЖЕН.** Свой JS делает только то, чего серверу знать не нужно
+(копирование в буфер обмена и подобное); доменное состояние считает сервер,
+клиент свопит присланную разметку.
+
+**Почему.** Пересчёт на клиенте — вторая реализация той же логики, которую
+никто не сверяет: расходится она тихо, а проявляется как «на экране одно, в
+базе другое». Вдобавок клиентский пересчёт по определению не работает в
+деградированном режиме (R11, R12) — значит, серверную версию того же
+вычисления всё равно придётся держать.
+
+### R3. Реактивный слой вводится отдельным решением
+
+**НЕ ДОЛЖЕН.** Alpine.js и подобное не появляется попутно с задачей —
+только когда есть виджет, которому он действительно нужен, и отдельным
+решением.
+
+**Почему.** Реактивный слой, попавший в проект ради одного выпадающего
+списка, немедленно доступен всему остальному коду — и граница R1/R2
+перестаёт держаться сама собой. Отдельное решение — единственный момент,
+когда цену видно целиком: она не в килобайтах, а в том, что дальше на
+каждом экране есть выбор между двумя моделями состояния.
+
+## Единый источник разметки
+
+### R4. Партиал = страница = фрагмент
+
+**ДОЛЖЕН.** Переиспользуемый кусок разметки — именованный шаблон в
+`partials/`, и он же рендерится инлайн на странице и как ответ-фрагмент
+обработчика; отдельной разметки под фрагмент нет.
+
+**Почему.** Две копии одной разметки расходятся молча: правку вносят в ту,
+что открыта, и страница начинает выглядеть иначе, чем результат свопа того
+же региона. Заметно это становится только на глаз и только тому, кто открыл
+оба пути подряд.
+
+### R5. Корень партиала — элемент с целевым `id`
+
+**ДОЛЖЕН.** Корневой узел шаблона несёт тот `id`, по которому адресуют
+регион, и ответный фрагмент несёт тот же `id`.
+
+**Почему.** `hx-swap="outerHTML"` заменяет корневой узел целиком, вместе с
+его атрибутами. Если пришедший фрагмент несёт другой `id` или не несёт его
+вовсе, первый своп проходит успешно, а следующее действие и поллер уже не
+находят таргет: регион застывает без единой ошибки — ни в консоли, ни в
+логе.
+
+### R6. Сборку view делает общая функция
+
+**СЛЕДУЕТ.** Один view-builder зовут и обработчик полной страницы, и
+htmx-ветка.
+
+**Почему.** Общий шаблон (R4) гарантирует одинаковую разметку, но не
+одинаковые данные: скопированная сборка view расходится по набору полей, и
+фрагмент начинает показывать не то, что показала бы страница. Это ровно тот
+класс расхождений, который R4 закрывает для разметки.
+
+## Обработчик действия
+
+### R7. Доменный вызов одинаков для htmx и обычного запроса
+
+**ДОЛЖЕН.** Обработчик определяет htmx-запрос по заголовку
+`HX-Request: true`, зовёт доменную операцию до ветвления и ветвится только
+на способе ответа:
+
+| № | Запрос | Ответ |
+|---|---|---|
+| R7.1 | `HX-Request: true` | фрагмент тем же партиалом (R4) по перечитанному состоянию |
+| R7.2 | обычный | PRG-редирект (303) |
+
+```go
+actionErr := fn(r.Context(), id) // доменный вызов идентичен для htmx и не-htmx
+
+if !isHTMX(r) {
+    redirect(w, r, id, msg) // без htmx — обычный PRG-редирект (303)
+    return
+}
+data, _ := s.deps.Read(r.Context(), id) // перечитать актуальное состояние
+view := buildView(id, data, "")         // тем же view-builder'ом
+if actionErr != nil {
+    view.BlockError = userErr(r, actionErr, id)
+}
+s.render(w, "source_block", view)       // фрагмент = тот же шаблон
+```
+
+**Почему.** Ветвление до вызова даёт две реализации одного действия, и
+дальше дефект воспроизводится только на одной поверхности — причём
+деградированный путь (R11) открывают реже, то есть чинить будут не тот.
+Перечитанное состояние в htmx-ветке нужно потому, что своп заменяет регион
+целиком: view, собранный из аргументов запроса, покажет намерение, а не
+результат.
+
+### R8. Шаблон рендерится в буфер, потом в ответ
+
+**ДОЛЖЕН.** Именованный шаблон собирается целиком в буфер, и только затем
+буфер пишется в ответ.
+
+**Почему.** Прямая запись в ответ отправляет клиенту статус и часть
+разметки раньше, чем шаблон дошёл до ошибки: сообщить об отказе уже нечем,
+а htmx свопит в DOM полученный обрывок. Внешне это «исчезла половина
+региона», и причина по такому симптому не читается.
+
+## Одно действие — два региона
+
+### R9. Второй регион едет тем же ответом через `hx-swap-oob`
+
+**СЛЕДУЕТ.** Когда действие меняет не только свой регион, второй фрагмент
+отдаётся в том же ответе с `hx-swap-oob="true"` — обычным именованным
+партиалом с тем же `id`, что и на странице (R4, R5).
+
+**Почему.** Второй запрос с клиента вводит гонку: два ответа считают
+состояние в разные моменты и приезжают в произвольном порядке, поэтому
+панель действий может отразить состояние до действия. Плюс лишний
+раунд-трип на каждое действие.
+
+### R10. Отдельный запрос за вторым регионом — когда он обновляется реже действия
+
+**ДОПУСКАЕТСЯ.** `HX-Trigger` в ответе плюс отдельный `hx-get`, если второй
+регион меняется не на каждое действие.
+
+**Почему.** Явное разрешение нужно, чтобы R9 не читался как запрет любого
+второго запроса. Когда регион обновляется редко, oob-ветка гоняет
+одинаковую разметку на каждое действие и связывает два шаблона там, где
+связи нет; гонка же тем менее наблюдаема, чем реже обновление.
+
+## Graceful degradation
+
+### R11. Форма действия работает без JS
+
+**ДОЛЖЕН.** Действие — обычная `<form method="post" action="…">`, на которую
+`hx-post`/`hx-target`/`hx-swap` накладываются сверху; `action` ведёт на
+рабочий обработчик.
+
+**Почему.** htmx может не загрузиться — ошибка вендоринга, блокировщик,
+медленная сеть, — и без рабочего `action` форма в этот момент не отправляет
+ничего, молча. Тот же `action` — единственное, что делает действие
+проверяемым без браузера с JS.
+
+### R12. Фильтр, поиск и пагинация — серверные
+
+**ДОЛЖЕН.** Отбор списка задаётся GET-параметрами и выполняется на сервере;
+клиентской фильтрации загруженной разметки нет.
+
+**Почему.** Клиент видит только текущую страницу списка, поэтому клиентский
+фильтр отвечает по неполным данным и делает это молча — результат выглядит
+валидным. Вдобавок состояние отбора в query переживает своп (R25) и
+перезагрузку, его можно послать ссылкой и увидеть в логе.
+
+### R13. Область обязательной деградации
+
+**ДОЛЖЕН.** Требование работать без JS распространяется не на весь UI:
+
+| № | Поверхность | Поведение без JS |
+|---|---|---|
+| R13.1 | действия и навигация | работают полностью (R11, R12) |
+| R13.2 | интерактивный виджет выбора, у которого нет осмысленного не-JS поведения | может не работать; записывается в отступления |
+
+**Почему.** Без явной границы правило деградации читается как запрет на
+любой JS-виджет — и тогда его либо тихо нарушают, либо отказываются от
+виджета, который был нужен. Запись в отступления держит список честным:
+видно, какие именно места ломаются с выключенным JS, а не «где-то
+что-то».
+
+## Ошибки на htmx-пути
+
+### R14. Ошибка действия на htmx-пути — 200 с фрагментом
+
+**ДОЛЖЕН.** Провалившееся действие отдаёт статус 200 и фрагмент с
+сообщением; доменная ошибка на htmx-пути не транслируется в HTTP-статус.
+
+**Почему.** В htmx 2.x ответы 4xx/5xx по умолчанию не свопят DOM — то есть
+пользователь не увидит ничего. Настроить это можно
+(`htmx.config.responseHandling`, расширение `response-targets`, слушатель
+`htmx:responseError`), но любая настройка — свой JS-конфиг на клиенте, и
+платится она из R1 и R2. Для REST API и не-JS редиректа с `?err=` статус
+по-прежнему используется: там его кто-то читает.
+
+Цена решения: в логе доступа провалившееся действие выглядит как `200`.
+Искать его надо по доменной записи об исходе операции (`lang/go/logging.md`),
+а не по коду ответа.
+
+### R15. Наружу идёт сообщение публичного канала
+
+**ДОЛЖЕН.** Во фрагмент попадает нейтральный текст по правилам
+`lang/go/errors.md`; `err.Error()` в разметку не рендерится.
+
+**Почему.** htmx-фрагмент выглядит внутренней деталью приложения, и на нём
+легче всего забыть, что это тот же публичный канал, что и страница:
+разметка уезжает в браузер пользователя целиком. Статус 200 (R14)
+дополнительно снимает ощущение «это ошибочный ответ, его никто не увидит».
+
+### R16. Сообщение об ошибке — в отдельном поле view
+
+**ДОЛЖЕН.** У view есть поле под ошибку действия; доменные поля под
+сообщение не переиспользуются.
+
+**Почему.** У доменного поля может быть своё непустое значение, и сообщение
+его перекроет: пользователь получит текст ошибки вместо данных, а шаблон —
+необходимость угадывать, что сейчас лежит в поле. Отдельное поле делает оба
+состояния — данные и ошибку — выразимыми одновременно, а это ровно то, чего
+требует R17.
+
+### R17. При ошибке активное состояние не меняется
+
+**НЕ ДОЛЖЕН.** Фрагмент, отданный после неудачного действия, показывает
+прежний выбор плюс сообщение.
+
+**Почему.** Своп заменяет регион целиком, поэтому фрагмент — единственное,
+что пользователь узнает о состоянии. Показав намеренное состояние вместо
+фактического, интерфейс расходится с сервером, и следующее действие человек
+делает по ложной картине — на сервере оно применится к другому объекту.
+
+## Живой поллинг
+
+Живое обновление устроено как фрагмент-эндпоинт под `/fragments/…` плюс
+`hx-get`, `hx-trigger="every Ns"`, `hx-swap="outerHTML"` в разметке:
+
+```html
+{{define "progress"}}<div id="item-live-{{.ID}}"
+  {{if .Active}} hx-get="/fragments/items/{{.ID}}/progress"
+                 hx-trigger="every 3s" hx-swap="outerHTML"{{end}}>
+  ...
+</div>{{end}}
+```
+
+### R18. Поллер самозавершается
+
+**ДОЛЖЕН.** Когда состояние вышло из «живого», фрагмент возвращается без
+`hx-*`-атрибутов.
+
+**Почему.** Иначе опрос не прекращается никогда: каждая открытая вкладка
+держит постоянный поток запросов за неизменными данными, и закрывает его
+только пользователь. Условие остановки живёт в разметке ответа, потому что
+это единственный канал, которым сервер управляет поллером.
+
+Встроенная альтернатива — ответ со статусом 286 — не используется: она не
+совместима с R4, ведь свежезагруженная страница рендерится тем же партиалом
+и тоже без поллера.
+
+### R19. Условие живости ведёт собственное состояние приложения
+
+**ДОЛЖЕН.** Признак «живо ли ещё» вычисляется по состоянию, которым владеет
+приложение, а не по ответу внешнего сервиса.
+
+**Почему.** Внешний сервис отвечает не всегда и не одинаково: на его
+недоступности поллер либо останавливается, пока работа идёт, либо не
+останавливается никогда. Приложение — единственный участник, который знает
+про операцию всё и может ответить на каждом тике.
+
+### R20. Поллер свопит фрагмент целиком через `outerHTML`
+
+**ДОЛЖЕН.** Тик заменяет весь фрагмент (`hx-swap="outerHTML"`), а не его
+содержимое.
+
+**Почему.** `outerHTML` удаляет старый узел вместе с его `hx-trigger` и
+инициализирует новый — так поллер живёт ровно в одном экземпляре и так же
+выключается (R18). Своп содержимого оставил бы старый узел с его таймером,
+и через несколько обновлений опрос шёл бы в несколько потоков. Работает это
+при совпадении корневого `id` (R5).
+
+### R21. Поллер не свопит контейнер с активными полями ввода
+
+**НЕ ДОЛЖЕН.** Живость включается только в тех состояниях фрагмента, где
+редактировать нечего.
+
+**Почему.** Своп поддерева теряет фокус, выделение и незасабмиченный текст
+внутри него. У поллера это происходит по таймеру, то есть в момент, который
+пользователь не выбирал: текст исчезает посреди набора и воспроизводится
+как «приложение стирает мой ввод».
+
+### R22. Браузер не ходит во внешний сервис напрямую
+
+**НЕ ДОЛЖЕН.** Поллинг и прочие запросы страницы идут на свой сервер.
+
+**Почему.** Прямой запрос из браузера выносит наружу адрес и учётные данные
+внешнего сервиса и делает страницу заложником его CORS-политики. Вдобавок
+контракт внешнего сервиса протекает в разметку: его смена перестаёт быть
+серверным изменением.
+
+### R23. Источник данных для тика
+
+**ДОЛЖЕН.** Тик читает данные там, где они уже есть, не ходя в сеть:
+
+| № | Что показывает тик | Откуда берёт |
+|---|---|---|
+| R23.1 | состояние внешнего сервиса | in-memory снимок, обновляемый воркером |
+| R23.2 | собственное состояние приложения | своё хранилище; снимок не требуется |
+
+**Почему.** Тик умножается на число открытых вкладок, поэтому сеть на
+каждом тике превращает интерфейс в генератор нагрузки на внешний сервис — и
+его недоступность становится недоступностью страницы. Снимок разрывает эту
+связь: частоту обращений к внешнему сервису задаёт воркер, а не
+пользователи. Контракт снимка держат узким, чтобы способ доставки
+(поллинг сегодня, SSE потом) менялся, не задевая остальной код. Для
+собственного состояния той же цены нет: хранилище и так своё, а лишний слой
+кеша добавил бы только рассинхрон.
+
+### R24. Поллинг URL страницы вместо отдельного фрагмент-роута
+
+**ДОПУСКАЕТСЯ.** Когда живой фрагмент — почти вся страница, `hx-get` идёт
+на URL самой страницы, а нужный узел вырезается `hx-select`:
+
+```html
+hx-get="/item/{{.ID}}" hx-trigger="every 3s"
+hx-select="#item-main" hx-swap="outerHTML"
+```
+
+**Почему.** Отдельный `/fragments/…`-роут в этом случае дублирует
+обработчик страницы целиком — вместе с перечитыванием состояния и сборкой
+view, — и дальше два обработчика расходятся по тому же сценарию, что и две
+копии разметки (R4).
+
+Инвариант корневого `id` (R5) действует и здесь: `hx-select` выбирает тот
+же узел, который свопится.
+
+## Своп и выход со страницы
+
+### R25. Действие не уводит со страницы, если предмет остаётся на ней
+
+**НЕ ДОЛЖЕН.** Такое действие свопит свой регион на месте.
+
+**Почему.** Своп сохраняет прокрутку и не трогает серверные фильтр, поиск и
+пагинацию — они в query (R12). Полная навигация ради изменения одного
+региона возвращает пользователя в начало списка и стоит перерисовки всей
+страницы. Не сохраняется при свопе только контекст внутри самого
+заменяемого поддерева — фокус, выделение, введённый текст (R21).
+
+### R26. Выход со страницы — форма без `hx-*`
+
+**ДОЛЖЕН.** Действие, после которого предмет покидает страницу, остаётся
+обычной POST-формой без htmx-атрибутов, то есть полной навигацией.
+
+**Почему.** Своп для такого действия оставил бы на месте регион,
+описывающий объект, которого на странице больше нет. Отсутствие
+htmx-атрибутов при этом само работает маркером «это выход»: намерение видно
+прямо в разметке, и не нужен `HX-Redirect` — то есть ещё один способ
+сменить страницу, существующий только на htmx-пути.
+
+### R27. Асинхронное действие свопит промежуточное состояние
+
+**ДОЛЖЕН.** Если работу доделывает воркер, ответ на действие показывает
+промежуточное состояние, а итог догоняет самозавершающийся поллер (R18).
+
+**Почему.** Мнимый результат расходится с сервером до следующего тика, и
+всё это время пользователь принимает решения по несуществующему исходу —
+включая повтор действия, которое на самом деле выполняется. Промежуточное
+состояние вдобавок объясняет, почему регион продолжает обновляться сам.
+
+## Различение поверхности одного действия
+
+### R28. Поверхность различается скрытым полем формы
+
+**ДОЛЖЕН.** Когда один роут зовут с разных страниц и своп-ответ различается
+фрагментом, поверхность передаётся явным скрытым полем
+(`surface=list|detail`), а не выводится из `HX-Target` или `Referer`.
+
+**Почему.** `HX-Target` — свойство разметки вызывающей страницы, `Referer`
+может не прийти вовсе; и то и другое меняется без участия обработчика, и
+ответ начинает приходить не тем фрагментом. Поле же видно в форме рядом с
+действием, поэтому связь «эта страница → этот фрагмент» читается там, где
+её заводят.
+
+## Статика, вендоринг, кэш
+
+Раздел не про htmx — это упаковка любого server-rendered приложения;
+разъедется в языковой слой, когда понадобится там.
+
+### R29. Ассеты встроены в бинарь и отдаются иммутабельным кэшем
+
+**ДОЛЖЕН.** Статика подключается через `go:embed` и отдаётся с
+`Cache-Control: public, max-age=31536000, immutable`.
+
+**Почему.** Встроенные ассеты делают деплой одним артефактом: нет второго
+шага раскладки файлов, который может отстать от бинаря и оставить новую
+разметку со старым css. Иммутабельный кэш безопасен ровно потому, что URL
+меняется вместе с содержимым (R30, R31); без этого условия год кэша был бы
+способом навсегда закрепить у пользователя старый файл.
+
+### R30. Меняемые ассеты версионируются хешем содержимого
+
+**ДОЛЖЕН.** css и js адресуются с `?v=<короткий sha256 содержимого>`, и URL
+строит хелпер шаблона.
+
+**Почему.** Хеш содержимого — единственная версия, которую невозможно
+забыть обновить: она меняется от самой правки. Ручной номер и дата сборки
+от этого не защищают, а цена промаха при иммутабельном кэше (R29) —
+устаревший файл у пользователя до ручной очистки кэша. Хелпер нужен, чтобы
+хеш не проставляли в каждом шаблоне руками.
+
+### R31. Вендорный ассет в `?v=` не нуждается
+
+**ДОПУСКАЕТСЯ.** Вендор адресуется по неизменному имени файла, без
+параметра версии.
+
+**Почему.** Содержимое под этим именем не меняется: обновление вендора
+приходит новым именем файла, то есть новым URL. Кэш-бастер защищает от
+подмены содержимого под тем же адресом, а такой ситуации здесь нет — и
+явное разрешение снимает вопрос, не нарушает ли это R30.
+
+### R32. Вендор не коммитится, а добывается по манифесту
+
+**ДОЛЖЕН.** Идемпотентная задача скачивает вендорные файлы по манифесту
+(`путь  url  sha256`) с проверкой контрольной суммы; сборка зависит от этой
+задачи.
+
+**Почему.** Манифест делает версию и происхождение ассета видимыми в
+diff'е — у закоммиченного минифицированного файла обновление выглядит
+стеной непрозрачных изменений, и подмену в ней не разглядеть. Sha256 —
+единственная проверка, что скачали то же самое, что проверяли; зависимость
+сборки от задачи не даёт собраться без ассета в свежем клоне.
+
+### R33. Шрифты и скрипты — self-hosted
+
+**ДОЛЖЕН.** Внешних хостов во время выполнения нет.
+
+**Почему.** Каждый внешний хост — это чужой аптайм внутри своей страницы и
+третья сторона, видящая каждый запрос пользователя. Самодостаточный бинарь
+вдобавок разворачивается в сети без выхода наружу, где CDN просто не
+отвечает.
+
+<!-- local:эталоны -->
+<!-- /local -->
+
+<!-- local:отступления -->
+<!-- /local -->