healthlog/openspec/changes/archive/2026-08-02-dozakryt-nahodki-sushchnostej/design.md

Context

Семь находок дозапущенных проходов ревью (tmp/triage-late.md) по коммиту f8200f7. Каждая имеет прогнанный падающий оракул; оракулы переезжают обычными тестами пакетов, tmp/ в .gitignore и жить в нём им нельзя.

Ограничения, которые задача не выбирает, а наследует:

• Свёртка обязана быть функцией журнала. Живая витрина и reindex обязаны сходиться отпечатком; всё, что зависит от порядка свёртки или от порядка элементов на проводе, — дефект по определению.
• Тренировка приезжает повторно, пока источник её досчитывает (26 копий, три различных содержимых на живом архиве), и значения между копиями расходятся всегда. Поэтому правило полноты точек к сущностям неприменимо, и Covers существует отдельно от Relate.
• Маршрут — 95% веса тренировки, и в экспорте Apple его нет вовсе. Затирание маршрута необратимо: reindex проиграет журнал и получит то же.
• Цена канонизации измерена: тело 40 МиБ → пик кучи 768.3 МиБ; 63 МиБ → блокировка удерживается 5.019 с при busy_timeout 5000.

Goals / Non-Goals

Goals:

• Обеднённая версия сущности не замещает сохранённую и не пропадает из счётчика.
• Победитель — функция множества версий: и внутри доставки, и между доставками.
• Провенанс сущности отражает победителя по журналу, а не первую свёрнутую копию.
• Поле не той формы стоит одного поля, а не сущности; пропуск виден в базе.
• Откат бинаря поверх новой схемы отказывает, а не стартует молча.
• Каноническая форма сущности считается один раз и вне транзакции.
• Диагностика разбора не несёт значений из тела.

Non-Goals:

• Хранение сущности с id и неразобранной меткой (NULL-метка) — требует схемы и правил чтения витрины.
• Пределы на размер одной сущности и суммарный размер секции, потоковый расчёт формы и хеша — новая политика, а не правка.
• Объединение полей несравнимых версий — отвергнуто там же и по той же причине, что для точек.
• Поэлементная сверка содержимого элементов ряда (точка маршрута без altitude) — см. «Риски».

Decisions

1. Covers получает второй разряд, запрет вырождения формы и счёт содержательных элементов

Сегодня Covers(g) требует от f лишь наличия каждого содержательного ключа g и длины верхнеуровневого массива не меньше. Этого хватает, чтобы «скелет» ({"maxHeartRate":1,"heartRateData":[null,null]} против настоящей тренировки) признался равным настоящей и выиграл тай-брейк журнала.

Правило дополняется тремя проверками, все — по верхнему уровню:

1. Второй разряд: ключи без содержания. Каждый ключ g (включая пустые) обязан быть у f. Тот же стандарт записан для точек в canon.Relate: «иначе {date, qty, Min:0, Max:0} и {date, qty} неразличимы, и Min с Max исчезли бы из витрины по жребию тай-брейка». Отличие от Relate: там второй разряд применяется только при равенстве первого, здесь включение всех ключей требуется безусловно. Это эквивалентно при равном первом разряде и строже, когда первый разряд неравен, — а строже здесь и нужно: Covers отвечает «не потеряем ли содержания».
2. Запрет вырождения формы. Покрывающая версия не может подменить объект или массив скаляром: если g[k] — объект, f[k] обязан быть объектом; если массив — массивом. Обратное (скаляр у g, объект у f) разрешено: f богаче формой. Стоимость — O(ключей), первый байт литерала.
3. Содержательные элементы массива. Рядом с длиной считается число непустых элементов. [null,null,null] и [{},{},{}] сохраняют длину, но не несут ничего, а именно так выглядит затёртый маршрут.

Про третью проверку важно, что она не добавляет обхода: arrayLen уже сегодня декодирует каждый элемент массива в выбрасываемый json.RawMessage, чтобы посчитать их количество. Добавляется isEmpty по литералу элемента — проверка первого байта и, для чисел, strconv; в дерево значений элемент не разворачивается. Поэтому цена, названная триажем («полный обход маршрута на каждое сравнение»), уже уплачена, и решение её не умножает.

Отвергнуто: сверка содержимого внутри элемента ряда (набор ключей у каждой точки маршрута). Вот она обход действительно умножила бы — на 768 МиБ пика, измеренных пунктом 4, — и остаётся названным пределом (см. «Риски»).

Отношение остаётся частичным порядком — конъюнкция включений множеств и нестрогих неравенств по каждому общему ключу транзитивна. На это опирается решение 2.

2. Победитель внутри доставки — минимум канонической формы среди непревзойдённых

Попарная свёртка pickWithinDelivery нетранзитивна: полнота — частичный порядок, тай-брейк — тотальный, и вместе они образуют цикл. Стандарт для точек записан в architecture.md («победитель — функция множества точек, а не порядка их поступления») и реализован в store.resolve; для сущностей он применяется дословно: собрать версии ключа, отбросить строго покрытые, среди оставшихся взять минимум канонической формы.

Порядок обязан быть тотальным до конца. У точек кандидаты с равной канонической формой схлопываются ещё до сравнения, поэтому минимум единственен; у сущностей схлопывания нет, и при двух версиях, различающихся только порядком ключей или дребезгом последнего разряда (измеренная норма HAE), «минимум формы» неединственен — в хранилище лёг бы тот элемент, что стоял в массиве раньше. Поэтому последним разрядом сравнения идут исходные байты, ровно тем же движением и по той же причине, что записана в canon.Less.

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

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

Здесь требование постановки исполнено по канонической форме, а не по байтам, и это сказано прямо, потому что постановка говорит «при равном содержании и разных байтах обязан считать differs=true». Цель постановки — чтобы счётчик перестал молчать на двух настоящих разных версиях — достигается: случай оракула (маршрут против маршрута из null) считается. Побайтовый вариант отвергнут записанным инвариантом: порядок ключей в JSON от HAE нестабилен и дребезг последнего разряда тоже, ради чего канонизация и заведена, — счётчик по байтам срабатывал бы на норме потока и стал бы неотличим от шума ровно тогда, когда понадобился бы. Детерминизм при этом обеспечен не счётчиком, а тай-брейком по байтам выше.

pickWithinDelivery исчезает: она была парной формой того, что теперь делает множество.

Отбор «максимальные элементы плюс минимум по тотальному порядку» существует в проекте для точек (store.resolve) и объявлен стандартом в architecture.md. Второй рукописный экземпляр — ровно то, чем был pickWithinDelivery, и он разошёлся со стандартом нетранзитивностью. Поэтому механизм выносится в общего помощника, а точки и сущности становятся двумя его вызовами с разными отношениями: architecture.md уже обещает смену тай-брейка точек, когда род метрики будет измерен, то есть правка одного экземпляра при живом втором запланирована заранее.

3. Провенанс обновляется при совпавшем хеше

Совпал хеш — содержимое то же, писать нечего. Но провенанс (delivery_id/delivery_received_at) остаётся от первой свёрнутой копии, а не от победителя журнала. Следствия два: провенанс устаревает гарантированно на каждой из ~26 повторных присылок, и при возврате содержимого к прежнему (A→B→A) живая витрина расходится с reindex — тай-брейк пункта 4 правила сравнивает позиции, а сохранённая позиция неверна.

Решение: при совпавшем хеше сравнить позиции журнала и, если сохранённая раньше приехавшей, обновить только колонки провенанса. Провенанс становится максимумом по журналу среди версий с этим содержимым, то есть функцией множества.

updated_at при этом не двигается — и это отдельное решение, а не экономия. Тренировка приезжает до двадцати шести раз, и бамп метки на каждой сделал бы её меткой касания строки, а не изменения содержимого. Потребитель запроса «что изменилось с момента X» — естественного для коллектора и уже заказанного Read API — получил бы двадцать шесть ложных изменений, неотличимых от настоящего досчёта, и выяснилось бы это после того, как потребитель написан. Провенанс несёт собственную метку (время приёма своей доставки), и для тай-брейка её достаточно.

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

Слово «провенанс» после этого означает у сущности не то, что у часового объекта: у объекта хранится доставка, создавшая его, и она не поднимается. Асимметрия законная — у объекта нет замещения версии целиком, — но записана в спеке явно, иначе читатель перенесёт смысл с одного на другое.

4. Каноническая форма считается один раз, вне транзакции

Комментарий bucket.go утверждает, что канонизация вынесена наружу; фактически analyze() зовётся из compareEntities внутри inTx, а его результат пишется в копию элемента среза и не переживает даже одной попытки.

Ключевое наблюдение: canon.Hash(raw) уже считает полную каноническую форму и выбрасывает её, а analyze() считает ту же форму заново. То есть дорогая часть и так платится на каждой версии, в prepareEntities, вне транзакции.

Решение: canon отдаёт форму и хеш одним проходом (FormAndHash, внутри — запись в io.MultiWriter(буфер, sha256), той же формой, какой уже написан HashAll), newEntityVersion зовёт его один раз и держит результат вместе с canon.Analyze. Ленивость, analyze() и флаг parsed уходят.

Отдельный вызов HashForm(form []byte) отвергнут: он вводит контракт очерёдности («сперва Form, потом HashForm»), где передача сырых байт вместо формы даёт правдоподобный, но неверный хеш, — а компилятор такую подмену не ловит.

Баланс работы назван честно, потому что он не односторонний:

• на пути разошедшегося хеша (одна доставка из сорока четырёх) — минус одна полная канонизация: сегодня форма считается дважды;
• на пути совпавшего хеша (сорок три из сорока четырёх) — плюс один мелкий разбор json.Unmarshal в map[string]json.RawMessage, то есть проход по телу и копия каждого верхнеуровневого значения. Сегодня на этом пути analyze() не зовётся вовсе.

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

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

5. Страж версии схемы переезжает в Open

OpenForRead сверяет версию схемы и отказывает при расхождении; Open мигрирует безусловно. Поэтому старый бинарь поверх схемы 7 стартует молча, незнакомые секции игнорирует, а доставки за окно отката помечает разобранными — и ничто не намекает, что для этого окна нужен reindex.

Асимметрия у Open законная: версия базы ниже версии бинаря — это ровно то, ради чего миграции существуют. Отказ ставится на «версия базы выше версии бинаря». Асимметрия относится только к Open: OpenForRead сохраняет строгое равенство, как требует спека пересборки, — иначе reindex начал бы читать рабочую базу схемы старее бинаря по колонкам, которых там нет. В одно место выносится чтение версии, а не сравнение.

Чтение берётся у самого goose (Provider.GetVersions отдаёт и текущую версию базы, и целевую), потому что имя таблицы учёта, имя колонки и правило «максимум = текущая версия» принадлежат ему: рукописная копия его приватной схемы разошлась бы при обновлении зависимости — и не отказом, а тем, что страж перестал бы ловить. Если окажется, что на соединении только для чтения этот путь требует записи или отдаёт лишнюю задержку (SQLite-диалект goose не умеет TableExists, поэтому на отсутствующей таблице уходит в повторы), копия допустима, но одной функцией и с названной причиной — и тогда «таблицы нет» распознаётся структурно (sqlite_master) и NULL читается как NULL (sql.NullInt64), а не по тексту ошибки драйвера: сообщения драйвера не контракт, это уже записанное правило проекта.

Цена отказа названа, потому что она реальна. Страж останавливает сервис целиком, а телефон шлёт непрерывно и молча: доставка, не попавшая в архив, в журнал не попадает вовсе. Взвешено так: откат бинаря — действие оператора, который в этот момент рядом и видит crash-loop сразу; дыры плотных метрик за время простоя закроют широкий и глубокий проходы синхронизации. Не закроют stateOfMind — у него доставки HAE единственный источник, — и это цена решения. Она меньше цены молчания: молчаливый старт портит витрину за всё окно отката, а узнать об этом неоткуда, и после ретеншена тел чинить будет нечем. Отвергнуты: деградированный режим «принимать и архивировать, свёртку не начинать» (сохраняет оба инварианта, но заводит режим, о существовании которого надо помнить, и правила его видимости) и отказ только воркеру свёртки (требует доказать, что старый бинарь корректно пишет учёт в новую схему, — доказательства нет).

6. Мягкий заголовок сущности

entityHead держит ID/Name/Date/Start/End типизированными строками, и сущность теряется целиком при смене типа любого из пяти. Причина названа точно, потому что от неё зависит выбор решения: роняет не encoding/json, а строка entity.go:51-53, где любая ошибка разбора считается фатальной. Сам json.Unmarshal «skips that field and completes the unmarshaling as best it can» и возвращает *UnmarshalTypeError.

Отсюда напрашивается трёхстрочная альтернатива — errors.As(err, &ute) и продолжить с уже заполненным заголовком. Она отвергается, и по названной причине: та же документация тут же оговаривает — «it's not guaranteed that all the remaining fields following the problematic one will be unmarshaled». Разбор, построенный на дозаполнении, перестал бы быть функцией тела: одна и та же тренировка давала бы разный заголовок в зависимости от порядка ключей на проводе, а он у HAE нестабилен.

Решение — штатная точка расширения encoding/json: тип softString с UnmarshalJSON, который на нестроковом значении ничего не пишет и возвращает nil. Теги остаются декларативными, ручных извлечений нет, гарантия полная. Заодно сохраняется различение счётчиков: элемент, который сам не объект, даёт ошибку верхнего уровня и по-прежнему уходит в «не разобралось как объект», а не в «нет id».

id при этом остаётся требованием, а не полем: без него сущность не адресуема. Число вместо строки в id — это сменившаяся форма идентификатора, и превращать 42 в "42" значило бы придумать идентичность за источник. Такая сущность пропускается прежним счётчиком.

start, приехавший не строкой, на date не откатывается. Мягкое чтение объявляет непонятое значение отсутствующим, а фолбэк start → date существует для сущностей, у которых start не прислан вовсе; композиция этих двух правил подставила бы метку другого момента времени, неотличимую от настоящей и ничем не считаемую. Поэтому нестроковый start — это неразбираемая метка.

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

Пропуски становятся видны в базе. Миграция 00008 добавляет доставке колонку skipped_entities; свёртка пишет туда сумму трёх счётчиков пропуска сущностей. Причина не в отчётности: ретеншен решает «что потеряется, если тело удалить», по базе, и сегодня получает ответ «терять нечего» ровно там, где теряется тренировка с маршрутом.

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

7. Диагностика разбора без значений из тела

fmt.Errorf("… встречено %v", tok) подставляет токен целиком: тело 8 МиБ даёт текст ошибки 8 МиБ, который уходит атрибутом error на уровень WARN. Инвариант «тела запросов только на DEBUG и с обрезкой» нарушен буквально.

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

Три формы решения главного узла и компромисс каждой

Главный узел — глубина сравнения содержания при слиянии версий сущности. Рассматривались три, и выбор записан не по умолчанию:

1. Поэлементная сверка содержимого рядов (у каждого элемента маршрута сравнивать набор ключей). Ловит всё, включая точку маршрута без altitude. Компромисс: полный обход маршрута с материализацией каждого элемента на каждое сравнение — умножение уже измеренных 768 МиБ пика; плюс пересмотр правила слияния целиком. Отвергнута ценой.
2. Второй разряд + запрет вырождения формы + счёт содержательных элементов (выбрана). Ловит скелет из скаляров, обнулённый ряд и исчезающий пустой ключ. Компромисс: строже правила точек, поэтому чаще удерживает; событие видно счётчиком, но контроль требует вывести счётчик в отчёт пересборки — иначе мера «сходимость verify:archive» его не увидит по построению. Стоимость — O(ключей) плюс isEmpty на элементах в уже существующем обходе.
3. Принять предел, оставить только наблюдаемость (счётчик по различию байт, предел записан в architecture.md). Компромисс: маршрут продолжает теряться необратимо при обеднённой версии, а восстановить его после ретеншена тел неоткуда — в экспорте Apple маршрута нет. Отвергнута последствием.

Форма (2) принята владельцем в постановке; здесь она не переоткрывается, а уточняется недостающими определениями (пустота элемента, строгость покрытия, тотальность порядка) и получает контроль, которого у неё не было.

Risks / Trade-offs

• Порча внутри элемента ряда не ловится (точка маршрута без altitude: длина та же, элемент непуст, форма не выродилась) → предел записывается в architecture.md рядом с описанием Covers так же прямо, как он записан в комментарии кода. Закрыть его может только сверка с телом в архиве, а тело живёт до ретеншена.
• Второй разряд Covers строже прежнего правила и может удержать версию, которая раньше замещала: досчёт, потерявший ключ с пустым значением, теперь проигрывает. Мера контроля — не сходимость verify:archive: живой приём и пересборка пользуются одним правилом и одинаково сойдутся на одинаково замороженной версии, то есть слишком строгое правило выглядело бы идеальной сходимостью. Контроль — счётчик удержаний, выведенный в отчёт пересборки, и замер его значения на живом архиве.
• isEmpty считает ноль пустотой, и это переносится на элементы ряда: ряд настоящих нулей будет выглядеть опустошённым → ошибка направлена в безопасную сторону (удерживаем, а не затираем) и видна счётчиком; наблюдённые ряды HAE состоят из объектов. Записано в спеку, потому что после мерджа это часть правила слияния навсегда.
• Мягкий заголовок принимает больше входов, то есть сущности, ранее уходившие в SkippedEntityMalformed, начнут попадать в витрину → это изменение разбора, и по правилу «покрыли — пересверните» такие доставки надо пересворачивать. Замер на живом архиве сделан до утверждения формулировок: 118 тел, пропусков noID=0 noTime=0 malformed=0, то есть пересворачивать нечего, и data-миграции нет.
• Мягкий заголовок увеличивает долю тел, доходящих до канонизации: сущность, раньше отсекавшаяся на разборе заголовка почти бесплатно, теперь канонизуется целиком, и худший случай по памяти становится достижим на входах, которые до него не доходили → предел на размер сущности из задачи-остатка перестаёт быть желательным и становится обязательным условием; записано в её теле.
• Обновление провенанса при совпавшем хеше — дополнительная запись там, где раньше её не было: ~26 повторных присылок на тренировку → запись касается трёх колонок без payload, то есть не трогает самое тяжёлое; счётчик записанных сущностей и updated_at не двигаются, и сравнимость замеров сохраняется.
• Страж версии схемы отказывает при старте — сервис не поднимется на базе из будущего, то есть приём останавливается, а телефон не перешлёт → цена взвешена выше, в решении 5, вместе с отвергнутыми альтернативами; в architecture.md уезжает эксплуатационный контракт: как это выглядит (crash-loop контейнера) и чем лечится (возврат бинаря).
• Пункт 5 правила (несравнимые наборы) остаётся функцией порядка проигрывания, и второй разряд Covers делает этот исход чаще → приёмочный критерий сходимости сформулирован условно (перестановка даёт один отпечаток при нулевом счётчике несравнимых), а сам предел записан в architecture.md как единственная точка, где витрина не является функцией множества доставок.