healthlog/openspec/specs/ingest/spec.md

# ingest Specification

## Purpose

Приём доставки от Health Auto Export как самостоятельное поведение: что делает
ответ `200` заслуженным, когда он отдаётся, кто и в каком порядке сворачивает
принятое, что происходит с несвёрнутым при остановке и рестарте. Цена ошибки
здесь наивысшая в проекте — доставка, не попавшая в архив и в журнал, не
восстанавливается: телефон её не перешлёт.
## Requirements
### Requirement: Ответ приёма отражает сохранность, а не разбор

Приём SHALL отвечать `200` после того, как тело записано в сырой архив и
доставка учтена строкой `delivery`, и MUST NOT ждать свёртки. Время ответа
зависеть от ширины доставки MUST NOT.

Порядок обязателен именно такой: тело на диск, затем строка учёта. Обратный дал
бы учтённую доставку без данных. Отказ на любом из двух шагов — отказ приёма, и
о нём отправителю говорится ошибкой: `400` для неразбираемой верхнеуровневой
формы, `413` для тела сверх предела, `500` для отказа записи.

Учёт доставки SHALL вестись на контексте, не отменяемом обрывом соединения:
тело к этому моменту уже на диске, и отказ вставки из-за ушедшего клиента
оставил бы тело без записи в журнале. Проверка формы тела при этом остаётся
отменяемой — там отмена уместна.

Причина разнесения измерена: свёртка 16 тысяч точек занимает 11 секунд, а
`WriteTimeout` в Go ставится до вызова обработчика и потому является общим
бюджетом на чтение тела, запись архива, учёт и свёртку. Исчерпав его, сервер
считает, что отдал `200`, клиент получает обрыв, а запись `accessLog` называет
статус `200` — то есть единственный канал наблюдаемости врёт.

#### Scenario: Ответ отдан до свёртки

- **WHEN** тело принято, записано в архив и учтено
- **THEN** ответ `200` отдан
- **AND** доставка в этот момент числится неразобранной

#### Scenario: Ширина доставки не удлиняет ответ

- **WHEN** приезжает доставка, свёртка которой занимает секунды
- **THEN** время ответа не включает время свёртки

#### Scenario: Обрыв соединения не оставляет тело без учёта

- **WHEN** соединение обрывается после того, как тело записано в архив
- **THEN** строка учёта доставки всё равно записывается

### Requirement: Несвёрнутая доставка числится неразобранной

Учтённая, но ещё не свёрнутая доставка SHALL числиться в статусе `pending`, и
этот статус SHALL быть единственным признаком того, что свёртка ещё должна
произойти. Отдельного, живущего только в памяти представления той же очереди
система иметь MUST NOT.

Отсюда следуют три свойства, и они и есть смысл требования:

- переполнять нечего — доставка ждёт свёртки в базе, а не в буфере, и «очередь
  переполнена» невыразимо;
- падение процесса очереди не теряет — несвёрнутое остаётся `pending`;
- подбор `pending` не является отдельной операцией — он совпадает с обычной
  работой свёртки.

#### Scenario: Принятая доставка ждёт свёртки в базе

- **WHEN** доставка учтена, но ещё не свёрнута
- **THEN** её `parse_status` равен `pending`

#### Scenario: Оборванный процесс не теряет несвёрнутое

- **WHEN** процесс прекращается до того, как свёртка доставки завершилась
- **THEN** доставка остаётся `pending`
- **AND** следующий старт сворачивает её

### Requirement: Исход свёртки отражает доставку, а не обстоятельства

Свёртка SHALL оставлять доставку в очереди — то есть **не менять** её статус, —
когда работа не сделана по причине, к самой доставке не относящейся: отмена
контекста и занятость базы после исчерпания повторов транзакции.

Все прочие отказы разбора и записи точек (непонятое содержимое, невыводимый
слой, нечитаемое или слишком большое тело, исчерпанный дедлайн свёртки, паника
самой свёртки) SHALL давать `failed`: это свойства доставки, и повторять их
бесполезно.

Отказы, случившиеся **до** чтения тела, и отказ самой записи исхода статуса не
меняют по другой причине — записать его нечем. Доставка остаётся `pending`, и
это честно: этим разбором её не досмотрели.

Паника свёртки SHALL перехватываться на той же границе, что пишет исход разбора,
и превращаться в `failed`. Иначе она валит процесс целиком — фоновая горутина
ничем не обёрнута, — а перезапуск берёт ту же доставку первой, то есть дефект
одной доставки становится циклом перезапуска, при котором приём не работает
вовсе. До разнесения ответа и свёртки ту же панику ловил транспорт, и стоила она
одного ответа.

Доставка в статусе `failed` в очередь свёртки возвращаться MUST NOT — её
подбирает только пересборка журнала. Это названная граница: обратное означало бы
бесконечный повтор заведомо безнадёжного.

Без такого различения занятость базы — а свёртка теперь конкурирует с приёмом за
неё штатно — стирала бы доставку с полки молча, и вернуть её могла бы только
ручная операция с остановкой сервиса.

#### Scenario: Занятая база не выводит доставку из очереди

- **WHEN** свёртка не прошла из-за занятости базы
- **THEN** доставка остаётся `pending`
- **AND** следующий проход пробует её снова

#### Scenario: Непонятое содержимое выводит доставку из очереди

- **WHEN** свёртка не прошла из-за содержимого тела
- **THEN** доставка получает статус `failed`
- **AND** следующий проход её не выбирает

### Requirement: Свёртку ведёт один фоновый воркер в порядке журнала

Свёртку принятых доставок SHALL вести одна горутина, обрабатывающая доставки в
порядке журнала — `(received_at, id)`, как он определён capability пересборки.
Распараллеливать свёртку MUST NOT.

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

Проход воркера SHALL прекращаться на первой доставке, чей исход свёртки
**классифицирован как отложенный** (занятость базы, отмена снаружи), а не
перешагивать её. Перешагнув, проход свернул бы её преемниц раньше неё.

Предикат остановки — именно класс исхода, а не статус доставки. Доставка,
оставшаяся `pending` из-за отказа записи самого исхода, курсор двигает и проход
не останавливает: иначе проход выбирал бы её бесконечно, свёртка встала бы
целиком, а приём продолжал бы отвечать `200`.

Очередь при этом не встаёт: собственный дедлайн свёртки обстоятельством
MUST NOT считаться — доставка, не уложившаяся в бюджет, получает `failed` и
очередь освобождает, а занятость базы блокирует запись всем одинаково. Проход
возобновляется сигналом приёма или периодическим пробуждением.

Стоящая голова очереди молчать MUST NOT: у неё нет верхнего предела ожидания, и
снаружи она неотличима от здорового потока, потому что приём продолжает отвечать
`200`. Метка отставания (см. ниже) SHALL писаться и на выходе прохода по
барьеру, а не только на пустой выборке: занятая голова очереди до пустой
выборки не пропускает проход НИКОГДА, и метка, привязанная к ней, молчала бы
ровно в том состоянии, ради которого заведена. Флаг «первый проход завершён»
при этом взводиться MUST NOT — проход до конца очереди не дошёл.

Достижимая гарантия называется точно: в порядке `(received_at, id)`
сворачиваются все доставки, **видимые воркеру** на момент выборки. Доставка,
ставшая видимой позже курсора прохода, подбирается следующим проходом;
абсолютного порядка при конкурентных приёмах система не обещает, потому что
строка учёта становится видимой только после записи тела (измерено 184 мс на
62 МиБ).

Остаточное окно молчать MUST NOT. Перед свёрткой воркер SHALL спрашивать
журнал, есть ли доставка **позже** этой по `(received_at, id)`, уже записавшая
исход разбора в витрину — то есть в статусе `parsed` или `partial`. Есть —
пишется одна запись `WARN` на доставку, с её идентификатором, ожиданием в
секундах и без значений точек.

Спрашивать журнал система SHALL **до** свёртки, а писать запись — **после** и
только если свёртка состоялась: после свёртки предикат уже видит саму эту
доставку разобранной, а отложенная доставка витрину не трогала, и запись о
свёртке вне порядка утверждала бы событие, которого не было, — да ещё
повторялась бы каждым проходом, пока голова очереди занята. Это единственное наблюдение, по которому расхождение живой витрины с
пересборкой вообще обнаружимо до сверки отпечатков; лечится оно
`healthlog reindex`.

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

Пересборка эту проверку выполнять MUST NOT: она идёт в порядке журнала по
построению, и её тишина здесь содержательна.

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

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

Воркер SHALL продвигаться по неразобранным доставкам строго возрастающим
курсором в пределах одного прохода. Курсор обязателен для завершимости:
доставка, у которой не удалось записать даже исход разбора, остаётся `pending`,
и проход без курсора выбирал бы её бесконечно.

Приём SHALL будить воркер после того, как доставка учтена. Потеря сигнала
отказом быть MUST NOT: доставка от этого не перестаёт числиться `pending`.
Помимо сигнала воркер SHALL просыпаться периодически — иначе доставка,
оставшаяся `pending` по причине выше, ждала бы следующей доставки, а ночью
телефон молчит часами.

Отказ отдельного прохода воркер SHALL переживать: отказ выборки пишется `ERROR`
и прекращает проход, но не цикл. Отмена работы снаружи отказом при этом
считаться MUST NOT — штатная остановка не должна писать `ERROR`. Воркер, умерший
от временного отказа базы, остановил бы свёртку до конца жизни процесса, пока
приём продолжал бы отвечать `200`.

#### Scenario: Видимые доставки сворачиваются в порядке журнала

- **GIVEN** несколько доставок числятся `pending` до начала прохода
- **WHEN** воркер делает проход
- **THEN** он сворачивает их в порядке `(received_at, id)`
- **AND** доставка без плотных метрик наследует слой предшествующей ей по этому
  порядку доставки той же автоматизации, а не соседа по времени вставки

#### Scenario: Отложенная доставка держит очередь

- **GIVEN** в очереди несколько доставок, и свёртка первой из них отложена
  занятостью базы
- **WHEN** воркер делает проход
- **THEN** её преемницы в этом проходе не сворачиваются
- **AND** следующий проход снова начинает с отложенной доставки

#### Scenario: Свёртка вне порядка журнала не молчит

- **GIVEN** доставка стала видимой после того, как её преемница по журналу уже
  вышла из очереди
- **WHEN** воркер сворачивает её
- **THEN** система пишет `WARN` с идентификатором доставки и без значений точек

#### Scenario: Доставка, не записавшая исход, не зацикливает проход

- **WHEN** свёртка доставки не смогла записать исход разбора и оставила её
  `pending`
- **THEN** проход воркера завершается, а не выбирает её повторно

#### Scenario: Доставка без входящего потока всё равно подбирается

- **GIVEN** доставка осталась `pending`, и новых доставок не приезжает
- **WHEN** наступает очередное периодическое пробуждение
- **THEN** воркер пробует свернуть её снова
### Requirement: Подбор неразобранного при старте — та же операция

При старте система SHALL сворачивать доставки, числящиеся неразобранными, тем
же путём, каким сворачивает вновь принятые: отдельного кода подбора
существовать MUST NOT.

Порядок журнала при подборе SHALL соблюдаться так же, как при обычной работе —
подбор это тот же проход воркера, а не особый режим.

Классификация исхода свёртки (свёрнуто; слой не выведен; содержимое не
разобрано; прочий отказ; частичный разбор; несравнимые наборы полей) SHALL быть
общей с пересборкой журнала: второй классификатор разошёлся бы с первым молча.
Классифицироваться SHALL только ошибка свёртки; решение «работу прекратили
снаружи» MUST NOT приниматься классификатором — у пересборки и у воркера
контекст свёртки означает разное, и общая ветка отмены дала бы одному из них
противоположный смысл.

Счётчики частичного разбора и несравнимых наборов SHALL читаться только у
успешной свёртки — у отказавшей они заполнены частично, и `partial` занижался бы,
а по нему принимается решение о судьбе тела.

#### Scenario: Доставки, оставшиеся неразобранными, подбираются при старте

- **GIVEN** в учёте есть доставки со статусом `pending`
- **WHEN** сервис стартует
- **THEN** они сворачиваются в порядке `(received_at, id)`

#### Scenario: Размер задолженности назван при старте

- **WHEN** сервис стартует и неразобранные доставки есть
- **THEN** их число попадает в лог одной записью уровня `INFO`

### Requirement: Остановка не оставляет доставку в неопределённом состоянии

Остановка сервиса SHALL сперва прекращать приём, затем останавливать воркер.
Обратный порядок оставил бы доставки, принятые после остановки воркера, никого
не разбудившими.

Инвариант остановки: после неё не существует доставки, которая числится
разобранной, а записана частично; всё несвёрнутое остаётся `pending`. Обещать,
что текущая доставка непременно досворачивается, система MUST NOT — бюджет
остановки меньше бюджета свёртки, и такое обещание исполнялось бы не всегда.

Свёртка SHALL идти на контексте, не отменяемом остановкой, а отмена SHALL
проверяться **между** доставками. Причина названа: свёртка помечает доставку
`failed` на ошибке, а `failed` воркер не подбирает — то есть отмена снаружи
превратилась бы в свойство доставки.

Исчерпание бюджета остановки отказом сервиса считаться MUST NOT: и штатное
завершение воркера, и его прерывание оставляют состояние определённым. Факт
SHALL называться предупреждением, а не ошибкой старта.

#### Scenario: Остановка не оставляет половины

- **WHEN** сервис останавливается во время свёртки доставки
- **THEN** доставка либо свёрнута целиком, либо числится `pending`
- **AND** частично записанных объектов от неё не остаётся

#### Scenario: Приём прекращается раньше воркера

- **WHEN** сервис останавливается
- **THEN** приём перестаёт принимать раньше, чем останавливается воркер

#### Scenario: Не уложились в бюджет остановки

- **WHEN** воркер не успевает выйти в отведённый бюджет
- **THEN** факт попадает в лог предупреждением
- **AND** команда не сообщает об ошибке

### Requirement: Отставание воркера видно в логе

Система SHALL писать `WARN`, когда доставка ждала свёртки дольше периода
быстрого прохода синхронизации (пять минут): дольше этого срока очередь растёт,
а не рассасывается. Ожидание считается от `received_at` до начала свёртки.

Записей SHALL быть **одна на проход**, а не одна на доставку: задолженность в
сотню тел давала бы сотню одинаковых предупреждений каждую минуту, и уровень, по
которому вмешиваются, перестал бы что-либо значить. Строка называет число
задержанных и худшее ожидание с идентификатором доставки.

Метка SHALL вычисляться на выборке прохода, а не только по факту успешной
свёртки: состояние «работа есть, прогресса нет» обязано быть отличимо от
здорового пустого потока, иначе наблюдаемость молчит ровно там, где нужна.

Задолженность, накопленную **до** старта, метка задержки помечать MUST NOT: она
названа отдельной записью `INFO` о размере задолженности, а сотня одинаковых
`WARN` при первом же старте обесценила бы уровень. Метка включается после того,
как первый проход воркера завершился.

Записи воркера значений точек и имён устройств содержать MUST NOT — как и любые
записи свёртки.

#### Scenario: Отставший воркер называет задержку

- **GIVEN** первый проход воркера завершён
- **WHEN** доставки дожидаются свёртки дольше пяти минут
- **THEN** в лог идёт одна запись `WARN` на проход с числом задержанных и
  худшим ожиданием

#### Scenario: Задолженность при старте не даёт шквала предупреждений

- **GIVEN** неразобранными числятся доставки, накопленные до старта
- **WHEN** воркер сворачивает их первым проходом
- **THEN** записей `WARN` о задержке по ним нет

### Requirement: Длинный бюджет ответа принадлежит маршруту приёма

Обработчик приёма SHALL выставлять собственный дедлайн записи ответа перед
чтением тела, и этот дедлайн SHALL покрывать чтение тела вместе с отправкой
ответа. Полагаться на общий `write_timeout` сервера система MUST NOT: он
ставится до вызова обработчика и потому обрывает загрузку, идущую дольше него, —
делая `read_timeout` обещанием, которого сервер не исполняет.

Общий `write_timeout` сервера при этом расширяться MUST NOT: длинный бюджет
нужен одному маршруту, а остальные теряли бы защиту от застрявшей записи ответа.

Транспорт, не поддерживающий установки дедлайна, отказом приёма считаться MUST
NOT: факт уходит в `DEBUG`, приём продолжается.

#### Scenario: Медленная загрузка тела не обрывается

- **WHEN** тело приезжает дольше, чем общий `write_timeout` сервера, но
  укладывается в `read_timeout`
- **THEN** ответ доходит до отправителя

#### Scenario: Прочие маршруты бюджета не наследуют

- **WHEN** запрос идёт не на приём
- **THEN** его бюджет записи ответа остаётся общим `write_timeout`

### Requirement: Отказ учёта доставки называет класс причины

Система SHALL логировать отказ, случившийся **после** того, как тело легло в архив, но до появления учётной записи, так, чтобы владелец отличал **занятость базы** от прочих причин. Различается именно занятость: у неё уже есть доменная ошибка, и она означает конкуренцию за запись, которая будет повторяться.

Расширять признак до «обстоятельств вообще» система MUST NOT, хотя предикат с таким смыслом в проекте есть: он включает ещё и отмену работы снаружи, а на этом пути отмена невозможна по построению — учёт ведётся на контексте, переживающем обрыв соединения. Назвать отменённую работу занятостью базы значило бы отправить владельца искать конкуренцию там, где её нет.

Уровень при этом остаётся `ERROR` независимо от класса: тело лежит в архиве без
учётной записи, то есть осиротело, и вернуть его в журнал может только
пересборка. Занятость базы этого не отменяет — она объясняет причину, а не
снимает работу. Смысл различения в другом: занятость означает конкуренцию за
запись, которая будет повторяться и лечится не тем же, чем лечится сбой диска
или испорченная база.

#### Scenario: Занятая база при учёте доставки видна как отдельный класс

- **WHEN** запись учёта доставки не проходит из-за занятости базы
- **THEN** отказ логируется на уровне `ERROR` вместе с путём тела в архиве
- **AND** запись отличает занятость базы от прочих причин отказа
- **AND** тот же отказ по другой причине этого признака не несёт