healthlog/openspec/changes/archive/2026-08-04-aktivnaya-proverka-novyh-sekcij/design.md

## Context

Разбор перечисляет верхнеуровневые ключи `data`, которых он не покрывает, и
свёртка пишет их в `delivery.uncovered_sections` JSON-массивом (change
`2026-08-01-nerazobrannye-sekcii-dostavki`). Покрыты три секции — `metrics`,
`workouts`, `stateOfMind`; не виденными живьём остаются `symptoms`, `ecg`,
`heartRateNotifications`, `cycleTracking`, `medications`.

Колонка отвечает на вопрос «что останется потерянным, если тело удалить». На
вопрос «а когда именно поток принёс что-то новое» она отвечает только тому, кто
догадается спросить: события нет, а лог свёртки печатает `uncovered` атрибутом
на уровне `INFO`, где оно неотличимо от рутины — поток идёт раз в пять минут.

Ограничения, в которых живёт решение:

- **Хранилище — свёртка по журналу** (`critical`). Пересборка обязана дать то же
  состояние; всё, что наблюдаемо, обязано быть функцией журнала, а не порядка
  прогонов.
- **Поток не останавливается** — наблюдательный механизм не имеет права ронять
  свёртку и не имеет права держать блокировку базы: конкурирующий приём при
  исчерпанном `busy_timeout` отвечает `500` по доставке, тело которой уже на
  диске.
- Схема не трогается: колонка уже есть, задача её и использует.

## Goals / Non-Goals

**Goals:**

- Первая по журналу встреча имени непокрытой секции видна владельцу без запроса
  в базу; повторные встречи молчат.
- Событие переживает отказ свёртки — иначе оно теряется навсегда.
- Перечень накопленного достаётся одной командой.
- Пересборка полного журнала воспроизводит ровно те же события.

**Non-Goals:**

- Разбор новых секций. Формы никто не видел; вслепую разбор не пишется.
- Хранение реестра секций, HTTP-эндпоинт, уведомление наружу. Первое —
  вторая копия факта, второе и третье — отдельные цели (`Read API`,
  `Наблюдаемость`).
- История непокрытых секций, переживающая удаление тел архива. Это предмет
  ретеншена, и цена решения названа ниже.

## Три формы решения и компромисс каждой

Рассматривались три носителя признака «имя встречено впервые»; выбрана первая.

1. **Вывод из журнала запросом (выбрано).** Носителя нет вовсе — признак
   считается по существующей колонке. Компромисс: платим запросом по журналу на
   каждую доставку с непокрытыми секциями (см. решение 3) и наследуем все
   границы колонки — обрезку списка и обнуление пересборкой (решение 7).
2. **Реестр-таблица по образцу `category_value`.** Строка на имя с провенансом
   первой встречи; запрос новизны становится точечным по первичному ключу.
   Компромисс: вторая копия факта, обязанная сходиться с колонкой при каждой
   пересборке, плюс миграция и новая единица хранения витрины (а значит и
   отпечатка). Ноль новых сведений: имя выводимо из журнала. Отвергнуто —
   но не навсегда: ретеншену, срезающему тела, реестр понадобится именно затем,
   чтобы история пережила удаление, и тогда это уже другая цена.
3. **Множество виденных имён в памяти процесса**, наполняемое при старте.
   Запрос один на запуск, дальше — проверка по map. Компромисс: состояние
   становится функцией жизни процесса, а не журнала; наполнение при старте — тот
   же полный проход, только раньше; пересборка и живой приём расходятся в том,
   что считают первой встречей. Отвергнуто по инварианту «свёртка по журналу».

## Decisions

### 1. Новизна выводится из журнала, а не хранится реестром

Форма ответа взята у `category_value` — «когда имя встретилось впервые по
журналу», — а носитель другой: факт уже лежит в `delivery.uncovered_sections`.
Реестр здесь не добавляет ни одного сведения, он кэш запроса, а запрос идёт
считанные разы за жизнь имени.

Новизна считается запросом: «какие из этих имён встречались в доставках, стоящих
в журнале **строго раньше** текущей». Пусто — имя новое.

Прочтение колонки — `json_each` по `delivery`; колонка заведена массивом ровно с
этим расчётом («читается из SQLite через `json_each`», миграция `00005`).

### 2. Сравнение парой `(received_at, id)`, а не по идентификатору

Строгое сравнение пары решает три вещи разом:

- **самоисключение** — своя же строка (её пишет `finish` после) в счёт не идёт
  при любом порядке записи;
- **идемпотентность** — повторная свёртка той же доставки даёт тот же исход,
  поэтому пересборка не выдумывает и не глотает события;
- **порядок журнала, а не порядок прогона.** `received_at` хранится с секундной
  точностью, а строка учёта становится видимой воркеру только после записи тела:
  при конкурентном приёме доставка может стать видимой после более новой. Пока
  окно существует, сравнение по журналу делает исход от него независимым; когда
  окно закроют на самом приёме, сравнение всё равно останется — на нём стоят
  самоисключение и идемпотентность.

Та же лексикографическая пара уже стоит в `mergeCategories` и по той же причине;
здесь она в `WHERE`, а не в `ON CONFLICT`.

Следствие названо вслух: если две доставки стали видимы не в журнальном порядке,
имя может дать событие дважды — сначала на более новой, потом на более старой.
Это не дефект, а честное «первой в журнале была вот эта»; потери здесь нет, а
дублирование ограничено одной парой.

### 3. Цена запроса измерена, а форма выбрана по замеру

Индекса по `uncovered_sections` в схеме нет, и это изменение его не заводит.
Значит запрос — **полный проход по `delivery`** с фильтром по непустому списку,
а не «индексный».

**Это единственное место, где живут числа замера.** Комментарий кода и
`docs/architecture.md` формулируют правило и ссылаются сюда; дублировать цифры
запрещено — они уже разошлись однажды внутри одного изменения.

Метод: синтетический журнал в `./tmp` (`tmp/seenmeasure`, прогон повторяем),
105 тысяч доставок — годовой объём при 288 в сутки; 20 прогонов на случай;
машина ничем другим не занята.

| случай | по имени отдельно | одним запросом (в коде) |
|---|---|---|
| одно имя, первая встреча в начале журнала | 31 мкс | 31 мкс |
| одно имя, первая встреча в хвосте | — | 52 мс |
| одно имя, в журнале не встречалось | 50 мс | 50 мс |
| 32 имени | 1.36 с | 65 мс |

Читается это так, и первое было названо неверно в первой редакции дизайна:

- **ранний выход есть только у давно приезжающей секции.** Строки
  просматриваются от старых к новым, поэтому `LIMIT 1` выходит рано, лишь когда
  первая встреча имени лежит в начале журнала;
- **у секции, появившейся только что, раннему выходу не на чем сработать** — её
  первая встреча в хвосте, и проход идёт почти по всему журналу. Это и есть
  заявленный сценарий задачи: 52 мс на каждой доставке, 288 раз в сутки — около
  15 секунд чтения в сутки, пока секцию не покроет отдельная задача. Позиция
  первой встречи зафиксирована навсегда, поэтому цена сама не рассосётся;
- **32 имени по одному стоили секунду с лишним на доставку**, и тело, выбившее
  границу списка, приезжает раз в пять минут — это режим, а не случай. Поэтому
  имён больше одного спрашиваются одним запросом; частому случаю (одно имя
  давней секции) это ничего не стоит.

Что это стоит в жизни: **пока непокрытых секций нет** (сегодняшний режим — все
три приезжающие секции покрыты) запрос не берётся вовсе, он берётся только при
непустом списке.

**Развилка, вынесенная владельцу** (записана в докладе задачи): принять ли эти
52 мс на доставку или завести частичный индекс по непустому списку. Индекс — это
миграция и правка `docs/database.md`, то есть выход за рамку «схема не
трогается», поэтому в этом изменении он не делается. Остаток доведён с принятой
ценой, названной здесь числом.

### 4. Запрос идёт вне транзакции записи

Прецедент проекта прямой: канонизация внутри транзакции держала блокировку
5.019 с и дала 768 МиБ пика. Проход по журналу внутри транзакции записи объектов
повторил бы ровно этот класс — с той разницей, что отказ конкурирующего приёма
необратим. Сверка выполняется отдельным чтением до записи.

### 5. Событие живёт в едином логирующем чекпоинте свёртки

Своей строки лога у события нет: конвенция проекта — один логирующий чекпоинт на
доменной границе. Имена новых секций идут **атрибутом всегда**, а уровень
поднимается веткой `switch`.

Нормируется **поведение**, а не позиция ветви: запись обязана называть новую
секцию, какие бы повторяющиеся события ни случились в той же доставке. В коде это
достигается тем, что ветвь стоит первой, и это остаётся решением кода, а не
требованием спеки — иначе следующая задача, добавляющая свою ветвь, получит
арбитра в чужой capability.

Уровень назван поимённо — `WARN`. «Выше `INFO`» зеленело бы и на `ERROR`, а
`ERROR` у владельца означает сбой, который надо разбирать.

### 6. Путь отказа проверяется, отложенный — нет

Список непокрытых секций переживает отказ разбора (`residueOf`): доставка, у
которой не вывелся слой, всё равно записывает имена. Значит проверка новизны идёт
**до** ветвления на успех и отказ, а новые имена доезжают до `fail` и печатаются
его строкой.

Отложенный исход (занятость базы, отмена) — отдельный случай: он не пишет учётной
записи вовсе, доставка возвращается следующим проходом. Событие там не
печатается: оно не потеряно, а повторение на каждом проходе занятой базы
превратило бы однократный признак в дребезг.

### 7. Границы носителя названы, а не замолчаны

Признак и перечень производны от колонки, у которой три слепые зоны, и все три
идут в спеку:

- **обрезка списка**: имя, стоящее в теле после 32 незнакомых ключей, в колонку
  не попадает — события не будет. Наблюдаемым остаётся счётчик отброшенных имён,
  который уже поднимает уровень записи («тело на HAE не похоже вовсе»).
  Объявлять при обрезке новыми **видимые** имена рассматривалось и отвергнуто:
  невидимого это не возвращает, а сигнал об обрезке уже есть и уже громкий;
- **пересборка** обнуляет производные от разбора поля и заполняет их заново
  только по сохранившимся телам. Ретеншен, срезающий тела, стирает историю
  непокрытых секций вместе с ними — поэтому «те же события» пересборка
  воспроизводит при **полном** архиве. Это же и есть будущая цена решения 1;
- **покрытие секции**: пересвёртка убирает имя из колонки, и перечень отвечает о
  текущем состоянии покрытия, а не об истории. Она же может дать событие
  повторно — журнал тот же, а колонка заполняется заново.

### 8. Перечень отдаёт подкоманда `healthlog uncovered`

Той же формы, что `reindex` и `healthcheck`: конфиг флагом, человекочитаемый
вывод в stdout, ненулевой код на отказ. HTTP-маршрут отвергнут — Read API ещё
нет, а инструмент нужен на той же машине, где лежит база.

Имя `uncovered`, а не `sections`: команда перечисляет только непокрытое, а
широкое имя заняло бы место под будущий вопрос «какие секции покрыты» (его
сегодня закрывает сверка глазами, критерий К4). Словарь при этом закреплён:
`uncovered` — состояние покрытия (колонка, атрибут, capability
`uncovered-sections`), `new` — событие первой встречи (атрибут новых секций).

База открывается **только на чтение** (`store.OpenForRead`): команда
диагностическая, и запуск её при живом сервисе не должен ни мигрировать схему,
ни писать. Отказ открытия говорит причину и даёт ненулевой код — пустой перечень
от молчаливого отказа неотличим.

Строки — имя, число доставок, первая и последняя встреча (метка журнала и
идентификатор доставки; по идентификатору достают тело из архива). Вывод имеет
объявленный предел строк с остатком числом: предел разбора в 32 имени действует
на одну доставку, а различных имён журнал накопит сколько угодно — достаточно
версии HAE, кладущей в ключ переменную часть.

Имя печатается **экранированным** (`%q`): оно приходит верхнеуровневым ключом
чужого тела, обрезано по длине на разборе, но по содержимому не ограничено ничем
— сырая печать в терминал впустила бы туда управляющие последовательности.

Данных о здоровье в выводе нет: имя секции — структурный ключ, а не измерение.

## Risks / Trade-offs

- **Полный проход по журналу на каждой доставке с непокрытыми секциями**
  (решение 3) → измерено на синтетическом годовом журнале; цена принята и
  названа числом там же, развилка про индекс вынесена владельцу. Замер
  повторяем (`tmp/seenmeasure`).
- **Долгий читатель против чекпоинта WAL**: команда перечня делает проход по
  `delivery` вторым процессом, а удерживаемый читатель останавливает продвижение
  чекпоинта (измерено раньше: журнал 51 МБ при лимите 8 МиБ) → запрос
  одиночный и короткий, снимок не удерживается дольше вывода; команда
  диагностическая и запускается руками.
- **Слепые зоны носителя** (решение 7) → названы в спеке требованием «перечень
  честен относительно своего носителя»; молчание о них было бы хуже самих зон.
- **Дублирование события при несовпадении видимости с журналом** (решение 2) →
  ограничено парой строк, потери нет; альтернатива сделала бы событие функцией
  очереди и разошлась бы с пересборкой.
- **Лишние `WARN` при отказе сверки** (спека «Несостоявшаяся сверка не молчит»)
  → ограничены доставками с непокрытыми секциями и сопровождаются атрибутом о
  причине.