Цена читающего маршрута: чекпойнт WAL по таймеру и условный запрос

- рядом с воркером свёртки живёт горутина, раз в минуту разбирающая журнал пассивным чекпойнтом; «журнал не разбирается» видно строкой владельцу, а не только по `df`. Признак — пара чисел, а не флаг занятости: тот молчит под удерживаемым читателем (`busy=0` при 6256 страницах и пяти перенесённых), а при занятой блокировке отдаёт `-1` вместо ответа, и `-1 >= -1` читалось бы как «разобрано целиком» - каталог отвечает `304` на `If-None-Match`, не открывая снимок витрины. Метка собрана из всего, от чего зависит ответ: версии витрины (`data_version` с закреплённого соединения плюс поколение — значение локально для соединения и не переживает переоткрытия), горизонта измерения и области действия ресурса. Версия снимается до и после сборки: снятая после пометила бы устаревший снимок свежим номером - предел и дедлайн ответа отложены в задачу Read API точек вместе с измеренной ценой первого запроса; попутно починен флаки-тест чужой задачи, искавший значение точки в сыром буфере записи лога
2026-08-02 20:42:22 +03:00
parent 6b729bbd2f
commit 8db2ec7ff4
37 changed files with 3575 additions and 156 deletions
@@ -21,7 +21,6 @@

 ## высокий
 - [Тай-брейк при равной полноте точек](taj-brejk-pri-ravnoj-polnote.md) — Решено: брать бо́льшее значение. Порядок канонических форм берёт меньшее в 96% случаев — для накопительных это систематический недосчёт
- [Цена первого читающего маршрута: память, WAL и повторный опрос](cena-chitayushchego-marshruta.md) — Решено: чекпойнт по таймеру плюс ETag по data_version. Берётся перед Read API — тот строится поверх этой машинерии
 - [Read API: точки, выбор слоя, свёртка по сетке](read-api-tochki.md) — Данные видны только через sqlite на хосте — ни один из трёх потребителей ничего прочитать не может
 - [OpenAPI-спека и Swagger UI](openapi-swagger.md) — Потребителей три и один из них агент — контракт должен читаться машиной, а не пересказываться в чате
 - [MCP-сервер поверх Read API](mcp-server.md) — Агент-медик — первый заказчик проекта, а подключить его сейчас нечем
@@ -1,98 +0,0 @@
-# Цена первого читающего маршрута: память, WAL и повторный опрос
-
-**Приоритет:** высокий
-
-**Решение принято 2026-08-02: вариант (г) плюс (в), именно в таком порядке.**
-Разбирается без владельца: контракт хранения не меняется, данные не трогаются,
-а обе части — общепринятая практика, а не собственный дизайн. Чекпойнт по
-таймеру закрывает единственное проявление, которое ломает приём (диск), и стоит
-одной горутины; `ETag` по `PRAGMA data_version` — один запрос к базе, снимает и
-повтор, и большую часть читающих транзакций, не заводя кеша ответа.
-
-Вариант (а) — предел и дедлайн маршрута — **не отвергнут, а отложен** до
-[Read API точек](read-api-tochki.md): там предел размера ответа всё равно
-проектируется, и делать его дважды не нужно. Вариант (б) не берём, пока
-счётчик не заговорит. Вариант (д) — последним, если (в) окажется мало.
-
-Задача берётся **перед** Read API: тот строится поверх этой машинерии.
-Ниже — исходная постановка блокера, она же ТЗ.
-
-## Что решить
-
-Чем ограничить стоимость маршрута чтения, у которого нет ни предела ответа, ни
-собственного дедлайна, ни условного запроса. Вопрос поднялся на каталоге
-(`GET /api/v1/metrics`, change `2026-08-02-katalog-i-rod-agregacii`), но
-принадлежит не ему: тот же ответ понадобится Read API точек и MCP, и решать его
-трижды нельзя.
-
-Три измеренных проявления одной причины.
-
-**Память.** Снимок каталога держит разжатые точки окна по всем метрикам сразу,
-хотя измерение идёт по одной метрике. Замер враждебного прохода ревью: 20 метрик
-× 8 часов × 5000 точек — 693 мс и +153 МиБ живой кучи на один запрос.
-Предварительный отбор по учётным колонкам (сделан) снял разжатие заведомо
-непригодных часов, но множители «метрики × окно × точки × одновременные запросы»
-остались без потолка. Приём живёт в том же процессе и уже даёт пик 768 МиБ на
-теле 40 МиБ; OOM убивает приём, а доставка, не попавшая в архив, телефоном не
-переприсылается.
-
-**WAL.** Замер эксплуатационного прохода на копии с драйвером и PRAGMA проекта:
-непрерывная запись плюс четыре читающих транзакции внахлёст дают рост `-wal`
-около 7 МБ/с без верхней границы (40 МБ за пять секунд), тогда как тот же
-писатель без читателей стабилизируется на 4 МБ. Пассивный чекпойнт SQLite не
-продвигается дальше снимка самого старого активного читателя, и ошибки при этом
-нет — виден только растущий файл. `PRAGMA wal_checkpoint` в проекте не
-вызывается нигде.
-
-**Повторный опрос.** Спека каталога требует побайтового совпадения двух ответов
-на неизменившейся витрине — то есть ресурс по построению пригоден для условного
-запроса, а `ETag`/`304` не выставляется. Потребителей трое (агент-медик, трекер,
-игра), и самый частый их запрос — повтор неизменившегося.
-
-## Варианты и цена
-
-**а. Предел и дедлайн у маршрута.** Потолок числа метрик и точек в одном ответе,
-собственный `context.WithTimeout`, честный отказ при превышении. Цена: клиент
-обязан уметь читать частичный каталог, то есть появляется пагинация — контракт
-чтения усложняется на первой же ручке.
-
-**б. Измерение потоком по метрике внутри той же транзакции.** Точки метрики
-освобождаются сразу после вердикта; требование «один снимок» не нарушается. Цена:
-хранилище перестаёт возвращать снимок значением и начинает отдавать его
-последовательно (итератор или колбэк) — то есть меняется форма границы
-`store`/`catalog`, ради случая, которого живой поток пока не производит.
-
-**в. Условный запрос: `ETag` по `PRAGMA data_version`.** Снимает и стоимость
-повтора, и большую часть читающих транзакций разом: клиент с непротухшим `ETag`
-получает `304`, и снимок не открывается вовсе. Цена: один лишний запрос к базе на
-каждый вызов и обещание клиенту, что версия витрины меняется не чаще, чем данные.
-
-**г. Периодический `wal_checkpoint(PASSIVE)` по таймеру рядом с воркером.**
-Лечит только WAL, зато дёшево и без изменения контракта. Память и повтор
-остаются.
-
-**д. Кеш ответа на короткий TTL.** Закрывает всё сразу, но заводит третье
-представление того же факта, и его инвалидация становится новым местом, где можно
-ошибиться молча. Дизайн каталога отверг кеш именно поэтому.
-
-## Что заблокировано
-
-Ничего сегодня: на живом корпусе каталог собирается за 45 мс, потребителей у него
-пока нет, а маршрут живёт в доверенной сети. Блокировано будущее — Read API
-точек, где объёмы на порядок больше, и выкладка наружу, где опрос станет
-непрерывным.
-
-## Рекомендация
-
-**г + в, именно в таком порядке.** Чекпойнт по таймеру закрывает единственное
-проявление, которое ломает приём (диск), и стоит одной горутины без изменения
-контракта. `ETag` по `data_version` — один запрос к базе, снимает и повтор, и
-большую часть читающих транзакций, и делает это без кеша ответа.
-
-Вариант «а» откладывать до Read API точек: там предел размера ответа всё равно
-проектируется (`read-api-tochki.md`), и делать его дважды не нужно. Вариант «б»
-не брать, пока счётчик не заговорит: он меняет форму границы ради случая,
-которого поток не производит. Вариант «д» — последним, если «в» окажется мало.
-
-Связано: `docs/architecture.md` → «Измерение рода агрегации», `read-api-tochki.md`,
-`stats-nablyudaemost.md`.
@@ -21,6 +21,14 @@
 исчерпанного первого, и `BaseContext`, производный от контекста жизненного цикла,
 чтобы долгий запрос об остановке узнавал.

+**Цена этой ветки выросла** (change `cena-chitayushchego-marshruta`): база в ней
+не закрывается, а значит не закрывается и закреплённое соединение версии
+витрины — последнего соединения к базе не наступает, SQLite не делает финального
+чекпойнта, и рядом с базой остаётся неразобранный `-wal` до 64 МиБ. Данные целы
+(следующее открытие проиграет журнал), но файл базы в этом состоянии нельзя
+переносить без его `-wal`. Обвинение в логе при этом стало честнее: этап
+называется `background`, а не `fold-worker`, потому что ждут двоих.
+
 **Миграция молчит и не прерывается штатной остановкой.** `store.migrate` не
 пишет ни одной записи — ни «начал», ни «закончил», ни длительность, — а первая
 строка в логе появляется уже после успешного открытия базы. Если миграция идёт
@@ -37,5 +45,5 @@
 Готово, когда `WARN` о превышении бюджета называет виновный этап честно, а в логе
 старта видно, что миграции накатывались и сколько это заняло.

-Связано: `cmd/healthlog/serve.go`, `internal/store/store.go`,
-`cena-chitayushchego-marshruta.md`.
+Связано: `cmd/healthlog/serve.go`, `internal/store/store.go`, change
+`2026-08-02-cena-chitayushchego-marshruta` (архив).
@@ -36,10 +36,26 @@
 величины выглядят как «0.5», означая разное; полярность придётся назвать вслух в
 `architecture.md`, иначе через полгода два места кода поймут поле по-разному.

-**Предел размера ответа тоже здесь.** У каталога его нет намеренно: правило
-размера — общее для маршрутов чтения, и задавать его мимоходом на первой ручке
-значило бы решить контракт до того, как известна форма тяжёлого ответа. Каталог
-станет первым его потребителем.
+**Предел размера ответа тоже здесь, и он унаследовал измеренную цену.** У
+каталога предела нет намеренно: правило размера — общее для маршрутов чтения, и
+задавать его мимоходом на первой ручке значило бы решить контракт до того, как
+известна форма тяжёлого ответа. Каталог станет первым его потребителем.
+
+Цена измерена на каталоге (задача «цена читающего маршрута», закрыта чекпойнтом
+WAL и условным запросом): 693 мс и +153 МиБ живой кучи на враждебном запросе
+(20 метрик × 8 часов × 5000 точек), при том что приём в том же процессе уже даёт
+пик 768 МиБ на теле 40 МиБ. Условный запрос снял повтор, но первый запрос стоит
+столько же, а множители «метрики × окно × точки × одновременные запросы»
+по-прежнему без потолка. Сюда же уезжают отложенные варианты той задачи:
+собственный дедлайн маршрута и потоковое измерение по метрике (второе — только
+если счётчик заговорит).
+
+**Машинерия условного запроса готова, и её надо взять, а не написать заново.**
+`store.VersionedRead` держит правило «версией, снятой после чтения, не
+подписывать»; `httpapi` — разбор `If-None-Match` и `304`. Метка обязана нести
+**область действия**: у точек ответ есть функция параметров запроса, и
+`etag(scope, version)` требует их канонизированную форму — иначе `304` ответит
+на другой набор данных. Детали — `docs/architecture.md`, «Условный запрос».

 **Форма провода наследуется от каталога, и это надо решить один раз.** Сегодня
 типы `internal/catalog` сами несут json-теги, а транспорт владеет только
@@ -48,3 +48,12 @@
 запроса, ни адреса клиента: жалобу потребителя не сопоставить с записью, а
 выгрузку каталога посторонним — не отличить от планового опроса агента. У приёма
 корреляция есть (`delivery_id`), у чтения аналога нет.
+
+**Обслуживание журнала WAL тоже спрашивается здесь.** Признак «журнал не
+разбирается» (чекпойнт по таймеру, change `cena-chitayushchego-marshruta`)
+живёт одной строкой `WARN` в ротируемом docker-логе: состояние держится днями, а
+сказано о нём один раз. Вопрос «журнал сейчас разбирается?» сегодня не имеет
+ответа нигде, кроме `df`. В `/stats` просятся последний исход чекпойнта (когда,
+сколько страниц лежит и сколько перенесено) и — тем же полем — доля ответов
+чтения, которые удалось подписать `ETag`: механизм условного запроса может
+перестать окупаться под плотным потоком, и снаружи это неотличимо от нормы.