healthlog/openspec/specs/storage/spec.md

storage Specification

Purpose

TBD - created by archiving change razbor-metrik-v-obekty. Update Purpose after archive.

Requirements

Requirement: Идентичность точки по координатам

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

Поле source в ключ входить MUST NOT: оно нестабильно — то же измерение с тем же значением приезжает то как Apple Watch Ultra 3|iPad (Anton), то как Apple Watch Ultra 3, потому что Health переосмысливает атрибуцию задним числом.

Начало точки берётся из start, а при его отсутствии — из date; конец — из end, а при его отсутствии — из начала. Измерено: start, когда он есть, всегда совпадает с date (ноль исключений на 22 метриках), поэтому правило не вводит второго источника метки — оно лишь закрывает случай, когда HAE перестанет их дублировать.

Час объекта определяется по началу точки: интервал пересекает границы часов, и любой другой выбор сделал бы принадлежность объекту зависящей от длительности.

Ключ по одной метке проверялся и отвергнут: он схлопывает записи сна. Измерено на всех 94 доставках — 170 координат против 174 и 33 столкновения внутри одной доставки, где received_at общий, тай-брейк по нему неприменим в принципе, и исход решал бы порядок элементов в JSON-массиве, а он нестабилен. При этом разные интервалы под одной меткой всегда несут разное содержимое (проверено по всем метрикам), то есть ключ с интервалом ничего не задваивает.

Идентичность по хешу содержимого проверялась и отвергнута: она задваивала минутный слой целиком — 120 точек в часе вместо 60.

Scenario: Повторная доставка той же точки ничего не меняет

• WHEN точка с теми же координатами и тем же содержимым приезжает снова
• THEN хранилище не изменяется

Scenario: Смена источника не создаёт вторую точку

• WHEN точка с теми же координатами приезжает с другой строкой source
• THEN она остаётся одной точкой, а не превращается в две

Scenario: Записи с одной меткой и разными интервалами не схлопываются

• WHEN в доставке приходят точки sleep_analysis с одинаковым date и разными парами start/end
• THEN каждая сохраняется отдельной точкой

Scenario: Повтор записи в следующей доставке не задваивает

• WHEN точка с тем же началом и концом приезжает следующей доставкой
• THEN она остаётся одной точкой

Scenario: Точка-измерение адресуется вырожденным интервалом

• WHEN точка не несёт end
• THEN её конец равен началу, и ключ имеет ту же форму, что у интервала

Requirement: Разрешение столкновений по полноте

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

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

Измерено (находка 49): настоящих столкновений 2 897 из 444 256 координат (0.65%); из них 981 различаются набором полей — это и есть область правила полноты, — 1 916 несут равные наборы и разные значения, где исход решает тай-брейк, а несравнимых наборов ноль.

Пустым значением MUST считаться null, пустая строка, число, равное нулю (в любой записи), пустой объект и пустой массив: поле без содержания не делает точку полнее точки, где этого поля нет вовсе. Пустота MUST определяться по разобранному значению, а не по байтам: 0, 0.0, 0e0, -0 и { } — та же пустота, что 0 и {}.

false пустотой MUST NOT считаться: для булева поля это одно из двух значений, а не отсутствие содержания (isIndoor: false — тренировка на улице).

Поле source в множество не входит — оно нестабильно и переписывается задним числом (находка 36), так что о полноте измерения ничего не говорит.

Содержимое, которое не разбирается как JSON-объект, SHALL нести пустое множество ключей: так оно проигрывает любой точке с содержанием и не загрязняет наблюдение о несравнимых наборах.

Надмножество побеждает только тогда, когда оно несёт то же содержание: значения ключей, содержательных у обеих точек, MUST совпадать (с точностью до канонической формы). Иначе точки несут разные измерения, и надмножество имён о полноте не говорит ничего — такая пара MUST разрешаться как равнополная. Без этого условия точка {date, qty:0.001, p1:null, p2:null} вытесняла бы {date, qty:72.5}, то есть точка, где ни одно значение не измерение, стирала бы измерение — ровно то, ради отрицания чего правило переписано.

Если множества ключей с непустым значением равны и значения совпали, система SHALL сравнить множества всех ключей, кроме source, и оставить строгое надмножество. Без этого разряда правило теряло бы поля там, где заведено их беречь: точка {date, qty:10, Min:0, Max:0} и точка {date, qty:10} несут одинаковое содержание, и Min с Max исчезли бы из витрины по жребию. Несравнимость на этом разряде исходом MUST NOT быть: лишние ключи там заведомо пусты, объединять в них нечего.

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

Победитель MUST быть функцией множества точек координаты, а не порядка их поступления. Попарная свёртка этого не даёт: полнота — частичный порядок, тай-брейк — тотальный, и вместе они образуют нетранзитивное отношение победы (A превосходит B по полноте, B бьёт C тай-брейком, C бьёт A тай-брейком). При таком цикле повторная свёртка одной и той же доставки меняет содержимое объекта, и витрина перестаёт быть функцией журнала. Поэтому система SHALL отбросить кандидатов, превзойдённых по полноте кем-то другим, и выбрать победителя среди оставшихся по тотальному порядку — обе операции зависят только от состава множества.

Сравнение по received_at для этого не годится: у сохранённой точки нет провенанса — ни времени приёма, ни идентификатора доставки, — и сравнивать не с чем. Детерминизм обеспечивается свойством самих значений (например, порядком канонических форм), а не порядком событий.

Если множества несравнимы — каждое несёт ключ с непустым значением, которого нет у другого, — система SHALL выбрать победителя тем же детерминированным правилом, что и при равных множествах, и MUST оставить наблюдение: счётчик в итоге разбора доставки, координаты объекта и запись WARN без значений точки. Несравнимый набор — частный случай столкновения: счётчик перезаписей растёт вместе с ним, а координаты попадают в оба списка.

Объединять поля двух точек система SHALL NOT: на живом потоке несравнимых наборов не встретилось ни разу (0 из 2 897 столкновений, при обоих определениях пустоты), и реализация правила, которое никогда не срабатывает, стоила бы больше, чем счётчик, который скажет, если оно наступит.

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

Scenario: Бедная точка не стирает поля богатой

• WHEN сохранена точка с Avg, Min, Max и context
• AND по тем же координатам приезжает точка только с Avg, Min и Max
• THEN сохранённая точка остаётся с context

Scenario: Поля без содержания полноты не добавляют

• WHEN сохранена точка с пятью полями, значения которых 0, {} и []
• AND по тем же координатам приезжает точка с date и ненулевым qty
• THEN остаётся точка с date и qty

Scenario: При равном содержании поля не теряются

• WHEN сохранена точка {date, qty, Min:0, Max:0}
• AND по тем же координатам приезжает точка {date, qty} с другим qty
• THEN остаётся точка с Min и Max

Scenario: Одинаково полные точки с разными значениями

• WHEN по одним координатам приходят две точки с одинаковыми множествами ключей и разными значениями
• THEN исход определяется детерминированно и не зависит от порядка воспроизведения доставок

Scenario: Несравнимые множества считаются, а не сливаются

• WHEN по одним координатам приходят две точки, каждая из которых несёт ключ с непустым значением, которого нет у другой
• THEN остаётся ровно одна точка, выбранная детерминированно
• AND счётчик несравнимых наборов в итоге разбора доставки растёт
• AND система пишет WARN с координатами объекта и без значений точки

Scenario: Содержимое, которое не разбирается в объект

• WHEN по координатам сталкиваются точка с непустыми полями и содержимое, не разбирающееся как JSON-объект
• THEN остаётся точка с полями
• AND счётчик несравнимых наборов не растёт

Столкновением SHALL считаться расхождение канонических форм, а не байтов. Байты нестабильны — ради этого канонизация и заведена: из 81 952 повторно приехавших точек 67 534 различаются лишь порядком ключей, ещё 63% — последним разрядом double. Побайтовое сравнение давало бы тысячи ложных срабатываний на каждом глубоком проходе, и настоящий отказ правила стал бы неотличим от нормы.

Scenario: Столкновение с различием содержимого оставляет след

• WHEN по одним координатам сохраняется точка, каноническая форма которой отличается от уже сохранённой
• THEN система пишет запись уровня WARN без значений точки
• AND запись несёт координаты объекта: метрику, слой и час
• AND увеличивает счётчик перезаписей в итоге разбора доставки

Scenario: Дребезг сериализации столкновением не считается

• WHEN та же точка приезжает с другим порядком ключей или отличаясь последним разрядом числа
• THEN счётчик перезаписей не растёт и WARN не пишется

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

Requirement: Хранение часовыми объектами

Система SHALL хранить точки часовыми объектами с ключом метрика + слой + час (UTC). Содержимое объекта — сжатый gzip блоб; точки внутри упорядочены по времени.

Объект SHALL нести единицы измерения метрики. Внутри точки их нет — они живут на уровне метрики (проверено: поле units не встретилось ни в одной точке за 89 доставок), поэтому дословное хранение точек их не сохраняет. Без колонки единицы восстановимы только из архива, а для метрик, переставших приходить, — теряются навсегда.

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

Запись — чтение объекта, слияние точек, запись обратно. Точки из объекта MUST NOT удаляться. Содержимое объекта SHALL сериализоваться без HTML-экранирования: &, < и > внутри точки обязаны храниться теми же байтами, какими пришли, иначе «точка хранится дословно» перестаёт быть правдой, а сравнение с последующей доставкой той же точки промахивается навсегда.

Доставка SHALL сворачиваться одной транзакцией. Транзакция на объект давала недетерминированное частичное состояние: обход групп рандомизирован, и при отказе посреди доставки набор уже записанных объектов каждый раз другой (измерено: восемь прогонов одной доставки — семь разных состояний). Это ломает инвариант «состояние пересобираемо».

Единицы измерения MUST NOT переписываться молча: при расхождении сохранённых и пришедших единиц остаётся сохранённое значение, факт учитывается счётчиком и попадает в запись уровня WARN. Внутри точки единиц нет, и у ранее сохранённых точек не остаётся ничего, по чему их единицы восстановимы.

Scenario: Отказ посреди доставки не оставляет части объектов

• WHEN свёртка доставки прерывается на середине
• THEN не записывается ни один объект этой доставки

Scenario: Смена единиц не переподписывает сохранённые точки

• WHEN в объект приезжают точки в единицах, отличных от сохранённых
• THEN единицы объекта остаются прежними
• AND факт учитывается счётчиком и записью WARN

Scenario: Точки за один час ложатся в один объект

• WHEN приходят точки одной метрики и слоя за один час UTC
• THEN они хранятся одним объектом

Scenario: Дозапись в существующий час

• WHEN приходят новые точки за уже существующий час
• THEN объект перечитывается, точки сливаются, объект записывается обратно
• AND ранее сохранённые точки остаются в объекте

Requirement: Хеш как детектор изменений

Система SHALL хранить хеш канонической формы объекта и пропускать запись, если хеш не изменился. Хеш — детектор, а не ключ.

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

Scenario: Повторная присылка того же часа не пишет в базу

• WHEN приезжает доставка, целиком повторяющая уже сохранённый час
• THEN хеш совпадает и запись не выполняется

Requirement: Признак запечатанного часа

Система SHALL хранить признак sealed у часового объекта и SHALL реагировать на изменение запечатанного объекта сигналом, а не отказом.

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

Scenario: Изменение запечатанного часа

• WHEN приходят точки за час, помеченный sealed
• THEN система пишет запись уровня WARN
• AND данные всё равно сохраняются

Requirement: Значения точек не попадают в логи

Данные о здоровье чувствительнее токенов. Система MUST NOT писать значения точек, содержимое сущностей и тела доставок в записи лога уровня выше DEBUG.

Содержимое сущности здесь не менее чувствительно, чем значение точки, а местами более: маршрут тренировки — это геотрек до дома, а labels и associations записи состояния разума — эмоциональные метки. Разрешены координаты: идентификатор и род сущности, метка времени, идентификатор доставки — они описывают, что случилось, а не что измерено.

Непокрытые секции называются в логе именами ключей: имя секции — это форма пакета, а не измерение. Содержимое секции в лог не попадает ни при каком уровне выше DEBUG. Имена идут структурным атрибутом, а не склейкой в текст сообщения: кодировщик экранирует управляющие символы, и имя из чужого тела не разрывает построчный разбор логов. То же относится к идентификатору сущности: он приходит из чужого тела и ограничен по длине при разборе.

Частичный разбор уровня записи не повышает: partial — установившееся состояние половины потока (53 доставки из 118), и постоянный WARN обесценил бы уровень. Повышает уровень другое — срабатывание границ списка: тело с сотнями секций или с именем длиннее предела на HAE не похоже вовсе.

Scenario: Разбор доставки логируется без значений

• WHEN доставка разобрана
• THEN запись лога содержит счётчики (метрик, точек, объектов, сущностей) и идентификатор доставки
• AND не содержит ни значений точек, ни имён устройств

Scenario: Удержанная обеднённая версия логируется координатами

• WHEN приехавшая версия сущности отклонена как теряющая содержание
• THEN запись WARN содержит идентификатор и род сущности
• AND не содержит ни точек маршрута, ни того, какие поля потерялись

Scenario: Непокрытые секции названы именами ключей

• WHEN доставка содержит непокрытую секцию
• THEN запись лога содержит имена непокрытых ключей отдельным атрибутом
• AND не содержит ничего из содержимого этих секций
• AND уровень записи из-за одной лишь частичности не повышается

Scenario: Границы списка сработали

• WHEN список непокрытых ключей усечён по числу имён или по длине имени
• THEN запись лога имеет уровень WARN
• AND содержит число отброшенных имён

Requirement: Учёт частично разобранной доставки

Система SHALL отличать доставку, разобранную целиком, от доставки, в теле которой остались непокрытые разбором секции. Доставка с непустым списком непокрытых ключей MUST получать статус partial, а не parsed.

Статусы разбора:

pending  этим разбором ещё не смотрели — или смотрели, но работа не сделана
         по обстоятельствам (см. ниже)
parsed   разобрано всё, что в теле было
partial  разобрано покрытое; в теле остались непокрытые секции
failed   разобрать не удалось, точек нет

Источник истины — список непокрытых ключей; статус производен от него и от факта отказа, в порядке failed → partial → parsed. Приоритет назван явно, чтобы читатели (ретеншен, статистика) спрашивали статус, а не сравнивали список со строкой.

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

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

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

Список непокрытых ключей SHALL сохраняться рядом с доставкой — именами ключей, без содержимого секций. Он же ответ на вопрос «что останется потерянным, если тело удалить»: для stateOfMind доставки HAE единственный источник, в экспорте Apple его нет (находка 46). Поэтому список MUST сохраняться и при отказе разбора, если разбор успел его собрать: failed с непустым списком — законное состояние.

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

Список — снимок покрытия на момент свёртки. Задача, которая начинает разбирать секцию, тем же изменением SHALL переводить partial-строки с этим ключом в pending; ретеншену позволено смотреть на partial только при соблюдении этого правила.

Статусы, поставленные разбором, который частичного исхода не различал, доверия не заслуживают: под parsed у них лежат и полностью разобранные доставки, и доставки без метрик вовсе. Такие строки MUST переводиться в pending — «этим разбором ещё не смотрели». Число точек у них до пересвёртки остаётся прежним: оно производно от объектов витрины, которые никуда не делись.

Scenario: Доставка с непокрытой секцией отмечается частичной

• WHEN разбор доставки вернул непустой список непокрытых ключей
• THEN parse_status доставки равен partial
• AND список непокрытых ключей сохранён вместе с доставкой
• AND точки покрытой секции сохранены как обычно

Scenario: Доставка без непокрытых секций остаётся parsed

• WHEN разбор доставки не дал непокрытых ключей
• THEN parse_status равен parsed
• AND сохранённый список непокрытых ключей пуст

Scenario: Отказ разбора сильнее частичности

• WHEN разбор доставки завершился ошибкой в самом разборе или в записи точек
• THEN parse_status равен failed
• AND список непокрытых ключей сохранён, если разбор успел его собрать

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

• WHEN разбор не состоялся из-за занятости базы или отмены работы снаружи
• THEN parse_status остаётся pending

Scenario: Пересвёртка после того, как секция стала покрытой

• WHEN доставка со статусом partial сворачивается повторно разбором, который эту секцию покрывает
• THEN parse_status становится parsed
• AND сохранённый список непокрытых ключей пуст

Requirement: Хранение сущностей с собственным идентификатором

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

Единиц хранения две:

тренировка   ключ  id
             заголовок колонками: имя, начало, конец, офсет зоны, длительность
запись       ключ  род секции + id
             заголовок колонками: род, метка времени, офсет зоны

Сущность SHALL нести провенанс — идентификатор доставки, чья версия лежит сейчас, и метку приёма этой доставки. Он нужен не отчётности: по нему разрешается тай-брейк между версиями равной полноты (см. «Замена версии сущности…»), и без него WARN об удержанной обеднённой версии не связать с телом в архиве.

Длительность тренировки SHALL допускать отсутствие значения, отличимое от нуля: ноль — законная длительность, и потребитель, сложивший столбец, иначе не отличил бы «источник не прислал» от «измерено ноль».

Ключ записи SHALL быть парой род + id, а не одним id. Собственный id наблюдался живьём только у stateOfMind, где он UUID HealthKit; форма идентификатора остальных пяти секций не наблюдалась никем, и короткий несквозной id в двух разных секциях затёр бы одну запись другой молча. Пара стоит ноль: запросы к записям всегда идут с родом.

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

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

Сущности доставки SHALL записываться той же транзакцией, что и её точки. Доставка — единица свёртки; частичное состояние ломает инвариант «состояние пересобираемо», а наблюдение «секции не смешиваются в одной доставке» собрано за двое суток и основанием для второй транзакции не является.

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

Сравнение SHALL начинаться с хеша, читаемого без содержимого сохранённой сущности: маршрут доходит до мегабайта, разжимать и канонизировать его на каждой из 44 копий не за чем.

Каноническая форма приехавшей сущности SHALL считаться один раз на версию и до входа в транзакцию, а хеш SHALL браться из уже посчитанной формы. Внутри транзакции канонизации приехавших версий быть MUST NOT: транзакция открывается immediate, то есть блокирует запись, и повторяется до пяти раз при занятости базы — измерено, что тело 40 МиБ даёт пик кучи 768 МиБ, а тело 63 МиБ удерживает блокировку 5.019 с при busy_timeout 5000, после чего конкурентная доставка исчерпывает повторы. Считать форму дважды (в хеше и в сравнении) система MUST NOT: это ровно та же работа над теми же байтами.

Остаточный предел называется вслух: разбор сохранённой версии остаётся внутри транзакции — её содержимое читается оттуда же и только когда хеш разошёлся. Значит удержание блокировки по-прежнему пропорционально размеру сохранённой сущности, и класс отказа «конкурентный приём исчерпал повторы → 500 по доставке, тело которой уже в архиве» этим требованием не закрывается, а лишь становится различимым в логе. Закрыть его может только предел на размер сущности вместе с потоковым расчётом — отдельная задача.

Scenario: Тренировка хранится одной строкой с маршрутом

• WHEN приезжает тренировка с маршрутом
• THEN она хранится одной строкой, адресуемой своим id
• AND маршрут и внутренние ряды лежат в её содержимом дословно

Scenario: Ряд пульса тренировки не попадает в метрику

• WHEN тренировка несёт heartRateData
• THEN объектов метрики heart_rate эта доставка не создаёт

Scenario: Записи разных родов с одинаковым id не сталкиваются

• WHEN две записи разных родов приезжают с одним и тем же id
• THEN в хранилище лежат обе

Scenario: Повторная присылка той же тренировки не пишет в базу

• WHEN приезжает тренировка, содержимое которой совпадает с сохранённым, и её доставка стоит в журнале не позже сохранённой
• THEN хеш совпадает и запись не выполняется

Scenario: Отказ посреди доставки не оставляет части сущностей

• WHEN свёртка доставки прерывается на середине
• THEN не записывается ни одна сущность этой доставки

Scenario: Каноническая форма сущности считается один раз

• WHEN доставка с сущностью сворачивается, и транзакция повторяется из-за занятости базы
• THEN каноническая форма приехавшей сущности не пересчитывается ни на повторе, ни отдельно от хеша

Requirement: Замена версии сущности не теряет содержания

Сущность с собственным id SHALL замещаться целиком, а не сливаться по полям: она приезжает повторно, пока источник её досчитывает. Замер на живом архиве: одна тренировка приехала 26 раз в трёх различных содержимых — сперва добавились stepCadence и stepCount вместе с изменившимся рядом activeEnergy, затем при том же наборе полей досчитались totalEnergy и basalEnergy.

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

1. хеш канонического содержимого совпал        → содержимое не пишется,
                                                  провенанс поднимается до
                                                  более поздней позиции журнала
2. содержание приехавшей покрывает сохранённую
   и сверх того                                → приехавшая замещает целиком
3. приехавшая теряет содержание сохранённой    → остаётся сохранённая,
                                                  счётчик + WARN
4. содержание сравнимо, наборы равны           → версия из более поздней
                                                  доставки журнала
5. наборы несравнимы                           → остаётся сохранённая,
                                                  счётчик + WARN

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

Покрытие SHALL проверяться четырьмя условиями, все — по верхнему уровню содержимого:

1. каждый ключ сохранённой с непустым значением есть у приехавшей и тоже непуст;
2. при равенстве множеств содержательных ключей — каждый ключ сохранённой, включая пустые, есть у приехавшей. Тот же второй разряд записан для точек, и с тем же условием: иначе ключ с пустым значением исчезает по жребию тай-брейка. Безусловным он быть MUST NOT — проверено оракулом: версия с пустым ключом и без маршрута оказывалась несравнимой с законным досчётом, у которого маршрут приехал, а этого ключа нет, и маршрут не доезжал НИКОГДА;
3. форма значения не вырождается: где у сохранённой объект, у приехавшей MUST быть объект; где массив — массив. Версия, подменившая объект или массив скаляром, покрывающей быть MUST NOT — иначе «скелет» из скаляров и null-ов той же длины признаётся равным настоящей тренировке и выигрывает тай-брейк журнала;
4. верхнеуровневый массив не теряет ни длины, ни содержательных элементов: усечённый маршрут (три точки вместо 593) ключа не теряет, а маршрут из [null,null,null] не теряет и длины — притом что маршрут это 95% содержимого тренировки. Досчёт ряды удлиняет, поэтому и укорачивание, и опустошение элементов — законные признаки «приехало меньше».

Содержательность элемента ряда SHALL определяться той же пустотой, что и содержательность поля точки: null, пустая строка, ноль в любой записи, пустой объект, пустой массив; false содержателен. Второй словарь пустоты в проекте завёл бы два ответа на один вопрос. Цена этого выбора называется вслух: ряд из настоящих нулей ([0,0,0]) считается лишённым содержания, поэтому версия с таким рядом сохранённую не заместит. Ошибка направлена в безопасную сторону — правило удерживает, а не затирает, — и событие видно счётчиком; наблюдённые ряды HAE состоят из объектов, а не из чисел.

Условия 3 и 4 применяются к ключам, содержательным у сохранённой версии. Ключ, содержания не несущий, проверяется только на присутствие (условие 2): формы у пустоты нет, и требовать её сохранения означало бы отличать [] от 0 там, где ни то, ни другое ничего не несёт.

Предел правила называется вслух и не закрывается: сокращение внутри элемента ряда (точка маршрута без altitude при непустом элементе и той же длине) не ловится ничем, кроме сверки с телом в архиве.

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

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

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

Ровно поэтому провенанс сущности SHALL обновляться и тогда, когда хеш совпал: сохранённая позиция журнала участвует в тай-брейке пункта 4, и если в ней осталась первая свёрнутая копия вместо победителя журнала, отложенная доставка вернёт витрину к прежнему содержимому — то есть живая витрина разойдётся с пересборкой. Обновление MUST касаться только провенанса; содержимое при совпавшем хеше не переписывается, счётчик записанных сущностей не растёт (он считает содержимое витрины, и его сравнимость с прежними замерами важнее учёта обновления), и метка изменения содержимого не двигается тоже: иначе она стала бы меткой касания строки и дребезжала бы двадцать шесть раз на неизменившейся тренировке, а потребитель запроса «что изменилось с момента X» получил бы шум, неотличимый от настоящего досчёта. Провенанс несёт собственную метку — времени приёма своей доставки, — и для тай-брейка её достаточно.

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

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

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

Отличие от точки здесь содержательное: у точки на одних координатах законно встречаются два разных измерения, и предпочитать позднее нет оснований — там исход решает порядок канонических форм. У сущности id — идентичность одного объекта HealthKit, и вторая версия есть тот же объект, пересчитанный источником; тай-брейк по канонической форме заморозил бы тренировку на произвольной из версий навсегда, вместе с недосчитанной энергией.

Версии одного ключа внутри одной доставки позициями не различаются, и победитель среди них SHALL быть функцией множества версий, а не порядка элементов массива: сперва отбрасываются строго покрытые кем-то из остальных, среди оставшихся берётся минимум канонической формы. «Строго покрыта» означает «покрыта другой версией и сама её не покрывает»: покрытие — предпорядок, две версии могут покрывать друг друга взаимно, и отбрасывание всего покрытого опустошило бы множество, потеряв обе. Порядок при этом обязан быть тотальным до конца: при совпавших канонических формах решает минимум исходных байтов — иначе победителем оказывается тот, кто стоял в массиве раньше, а порядок ключей в JSON от HAE нестабилен, и в хранилище легли бы разные байты при одинаковом содержимом. Попарная свёртка здесь неверна ровно так же, как она была неверна для точек: покрытие — частичный порядок, тай-брейк — тотальный, и вместе они дают нетранзитивное отношение победы, при котором [A,B,C] и [B,C,A] дают разных победителей, а порядок элементов в JSON-массиве нестабилен. Сворачиваться между собой такие версии SHALL до сравнения с сохранённой.

Факт «в одном теле приехали две версии одного ключа с разным содержанием» SHALL считаться симметрично и тоже быть функцией множества: считаются кандидаты, чья каноническая форма отличается от формы победителя. Счётчик этот SHALL быть ОТДЕЛЬНЫМ от счётчика удержаний: две версии в одном теле содержания не теряют — победитель ложится в витрину целиком, — и одно число на два события отвечало бы ни на одно. На счётчик удержаний опирается единственный контроль того, что правило покрытия не стало слишком строгим; примесь делает его неотличимым от шума.

Версии с совпавшей канонической формой SHALL схлопываться ДО выбора победителя. Выбор квадратичен по числу кандидатов, а их число приходит из чужого тела; без схлопывания тело в пределах приёма занимает свёртку на часы. Отбор SHALL видеть отмену: иначе дедлайн свёртки, заведённый ровно против зависшей работы, не значит ничего. Побайтовое различие при совпавшей канонической форме событием MUST NOT считаться — порядок ключей в JSON от HAE нестабилен и дребезг последнего разряда double тоже, так что счётчик по байтам срабатывал бы на измеренной норме потока. Различие содержимого при совпадающих множествах ключей и длинах массивов считаться SHALL: сегодня ровно этот случай даёт ноль и молчащий счётчик.

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

Исход SHALL быть функцией журнала в его порядке. Остаточный предел называется вслух: сравнение сохранённой с приехавшей попарно — в витрине лежит победитель прошлых слияний, а не все кандидаты истории, — поэтому при несравнимых наборах (пункт 5) исход зависит от порядка проигрывания. Тот же предел есть у часового объекта; пункты 1–4 от порядка свёртки не зависят, а пункт 5 сопровождается счётчиком и WARN.

Scenario: Доехавший маршрут замещает тренировку без маршрута

• WHEN та же тренировка приезжает повторно, добавив route
• THEN в хранилище лежит версия с маршрутом

Scenario: Досчитанные значения при том же наборе полей побеждают

• WHEN та же тренировка приезжает повторно с тем же набором полей и изменившимися значениями, доставкой с более поздней позицией журнала
• THEN в хранилище лежит приехавшая версия

Scenario: Версия из более ранней доставки не откатывает витрину

• WHEN две доставки несут одну тренировку с равными наборами полей, и свёрнута сперва более поздняя по журналу, затем более ранняя
• THEN в хранилище лежит версия из более поздней доставки
• AND тот же исход даёт свёртка в обратном порядке

Scenario: Обеднённая версия сохранённую не затирает

• WHEN та же тренировка приезжает повторно без route, который был у сохранённой, и с изменившимися значениями общих полей
• THEN в хранилище остаётся сохранённая версия
• AND факт учитывается счётчиком и записью WARN с идентификатором тренировки

Scenario: Усечённый маршрут сохранённый не затирает

• WHEN та же тренировка приезжает повторно с тем же набором полей, но route короче сохранённого
• THEN в хранилище остаётся сохранённая версия
• AND факт учитывается тем же счётчиком

Scenario: Маршрут из пустых элементов сохранённый не затирает

• WHEN та же тренировка приезжает повторно с route той же длины, все элементы которого пусты (null либо пустой объект)
• THEN в хранилище остаётся сохранённая версия с координатами маршрута
• AND факт учитывается тем же счётчиком

Scenario: Скелет из скаляров сохранённую тренировку не затирает

• WHEN та же тренировка приезжает повторно, где каждый вложенный объект заменён числом, а каждый массив — массивом той же длины из null
• THEN в хранилище остаётся сохранённая версия
• AND факт учитывается тем же счётчиком

Scenario: Ключ с пустым значением не исчезает по жребию

• WHEN та же тренировка приезжает повторно без ключа, значение которого у сохранённой было пустым, при совпадающих содержательных ключах
• THEN в хранилище остаётся сохранённая версия
• AND факт учитывается тем же счётчиком удержаний

Scenario: Пустой ключ не запирает законный досчёт

• WHEN у сохранённой версии есть ключ с пустым значением, а приехавшая его не несёт, но приносит содержательный ключ, которого у сохранённой не было
• THEN приехавшая замещает сохранённую
• AND счётчик удержаний не растёт

Scenario: Две версии одной сущности в одном теле

• WHEN тело содержит два элемента секции с одним id
• THEN исход не зависит от их порядка в массиве
• AND счётчик различающихся версий тоже не зависит от их порядка

Scenario: Три версии одной сущности в одном теле

• WHEN тело содержит три элемента секции с одним id, из которых один покрывает второй, а третий несравним с обоими
• THEN победитель одинаков при любой перестановке этих трёх элементов

Scenario: Две версии разного содержания при равной длине массивов

• WHEN тело содержит два элемента секции с одним id, содержимое которых различается, но множества ключей и длины верхнеуровневых массивов совпадают
• THEN факт учитывается счётчиком различающихся версий

Scenario: Разные байты при совпавшей канонической форме событием не считаются

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

Scenario: Повторная присылка обновляет провенанс

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

Scenario: Отложенная доставка не возвращает витрину к прежнему содержимому

• WHEN журнал несёт содержимое A, затем B, затем снова A, и доставка с B свёрнута последней
• THEN содержимое сущности и отпечаток витрины совпадают со свёрткой того же журнала в его порядке

Scenario: Составной ключ не даёт коллизии отпечатка

• WHEN две витрины различаются только тем, где проходит граница между родом и идентификатором записи
• THEN отпечатки не совпадают

Scenario: Несравнимые наборы полей не объединяются

• WHEN приехавшая версия несёт содержательный ключ, которого нет у сохранённой, и теряет содержательный ключ, который у сохранённой есть
• THEN в хранилище остаётся сохранённая версия
• AND факт учитывается тем же счётчиком

Scenario: Повторная свёртка того же журнала состояния не меняет

• WHEN те же доставки сворачиваются повторно в том же порядке
• THEN содержимое сущностей не меняется

Requirement: Отпечаток витрины покрывает все её сущности

Отпечаток витрины SHALL включать тренировки и записи наравне с часовыми объектами: он единственный оракул сходимости пересборки, и отпечаток одних объектов давал бы «состояние сошлось» при разъехавшихся тренировках — то есть ломался бы молча ровно тем изменением, которое добавляет данные.

В отпечаток идут координаты сущности и хеш её содержимого. Значений он раскрывать MUST NOT — как и для точек.

Порядок обхода SHALL быть детерминированным и заданным запросом, а не порядком строк в файле базы. Строки разных разделов SHALL различаться константным признаком раздела: без него строка одного раздела может совпасть со строкой другого, и два разных состояния дали бы один отпечаток. По той же причине составной ключ SHALL идти в отпечаток отдельными полями с собственными длинами, а не склейкой: склейка выполняется до взятия длины, и пара (a, b/c) даёт ту же строку, что (a/b, c).

Границу оракула стоит назвать вслух: в отпечаток идут координаты и хеш содержимого, а колонки заголовка сущности (имя, конец интервала, офсет, длительность) — нет. Они производны от содержимого, поэтому их расхождение означает изменившийся код извлечения заголовка, а не разъехавшееся состояние; но «отпечатки совпали» не является утверждением о них.

Все разделы SHALL читаться одним снимком базы. Отпечаток рабочей витрины снимается под живым приёмом, и запросы вне общей транзакции чтения дали бы смесь «объекты до» и «тренировки после» — то есть ложное расхождение у единственного оракула сходимости.

Scenario: Расхождение тренировок видно в отпечатке

• WHEN две витрины совпадают по часовым объектам, но содержимое одной тренировки различается
• THEN отпечатки не совпадают

Scenario: Отпечаток одинаков при одинаковом содержимом

• WHEN та же витрина собрана повторно из того же журнала
• THEN отпечаток совпадает

Scenario: Запись во время снятия отпечатка не смешивает разделы

• WHEN отпечаток снимается, а параллельно коммитится свёртка
• THEN отпечаток отражает одно состояние базы, а не смесь снимков

Requirement: Открытие базы отказывает при схеме из будущего

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

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

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

В одно место SHALL выноситься чтение версии, а не сравнение: сравнивают эти два способа открытия по-разному, а читают одинаково. Отсутствие журнала миграций (новая база) SHALL означать версию 0, и распознаваться это MUST по структуре базы, а не по тексту ошибки драйвера — сообщения драйвера контрактом не являются, и это уже записанное правило проекта.

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

Эксплуатационная цена отказа называется вслух, потому что она реальна: сервис не поднимется, а телефон шлёт непрерывно и молча, и доставка, не попавшая в архив, в журнал не попадает вовсе. Выбор сделан так потому, что откат бинаря — действие оператора, который в этот момент рядом и видит отказ сразу, а дыры плотных метрик закрывают широкий и глубокий проходы синхронизации. Не закрывается ими stateOfMind: у него доставки HAE единственный источник, и окно простоя для него — потеря без возврата. Молчаливый старт при этом стоит дороже: он портит витрину за всё окно отката, и узнать об этом неоткуда.

Scenario: Старый бинарь не открывает базу из будущего

• WHEN в журнале миграций базы стоит версия выше последней, вшитой в бинарь
• THEN открытие завершается отказом с указанием обеих версий
• AND миграции не накатываются

Scenario: Новая база открывается и мигрирует

• WHEN базы ещё нет либо журнал миграций пуст
• THEN открытие проходит и накатывает миграции до версии бинаря

Scenario: Открытие только на чтение остаётся строгим

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

Requirement: Пропущенные сущности видны в учётной записи доставки

Учётная запись доставки SHALL нести число сущностей, которые разбор пропустил: без id, с непомерно длинным id, с неразбираемой меткой времени или не разобравшихся как объект.

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

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

«Не измерялось» SHALL быть отличимо от нуля, и на пути отказа тоже. Разбор, вернувший ошибку, отдаёт нулевые счётчики по построению, а не по измерению; записать этот ноль значило бы объявить проверенной доставку, содержимое которой никто не смотрел. Число SHALL записываться только когда разбор досчитал; во всех прочих исходах колонка MUST оставаться нетронутой — той же идиомой, какой уже сохраняется выведенный слой. Доставки, свёрнутые разбором, который пропусков не считал, значения не имеют, и подстановка нуля объявила бы их проверенными: ретеншен получил бы то самое ложное «терять нечего», ради которого счётчик и заводится, — только теперь с видом измерения. Поэтому колонка допускает отсутствие значения, миграция его не подставляет, а читатель, принимающий по счётчику необратимое решение, SHALL трактовать отсутствие как «не удалять». Замер на живом архиве (118 тел) даёт ноль пропусков всех классов, то есть исторический корпус ничего не потерял, — но «ничего не потерял по замеру» и «проверено этим разбором» это разные утверждения, и колонка обязана их различать.

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

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

Scenario: Пропущенная сущность видна в учёте доставки

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

Scenario: Пересвёртка без пропусков обнуляет счётчик

• WHEN доставка с ненулевым числом пропущенных сущностей сворачивается повторно разбором, который эти элементы понимает
• THEN число пропущенных сущностей у доставки равно нулю

Scenario: Доставка, свёрнутая до появления счётчика, отличима от нулевой

• WHEN доставка была свёрнута разбором, который пропусков не считал, и с тех пор не пересворачивалась
• THEN её число пропущенных сущностей отсутствует, а не равно нулю

Requirement: Перечисление разрезов не читает содержимое объектов

Хранилище SHALL отвечать на вопрос «какие слои есть у метрики, за какой период и сколько в них точек» по учётным колонкам объекта, не разжимая payload и не затрагивая страниц с содержимым. Тот же запрет действует на поиск часов, за которые у метрики есть объекты сразу в двух слоях.

Запрет ограничен именно этими двумя выборками. Измерение рода обязано прочитать значения точек, то есть разжать содержимое объектов окна, и требование его не касается — иначе оно запрещало бы то, ради чего каталог существует.

Причина в форме таблицы: bucket объявлена WITHOUT ROWID, то есть строка целиком, вместе со сжатым содержимым, живёт в дереве первичного ключа. Обход всех строк ради агрегата тащил бы за собой страницы содержимого — при 260 тысячах объектов за год это сотни мегабайт на каждый запрос каталога, притом что сам ответ несёт три десятка строк.

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

Scenario: Разрезы метрики за длинную историю

• GIVEN в витрине объекты за многие месяцы
• WHEN запрашиваются слои метрики с границами и числом точек
• THEN запрос отвечает по индексу, не читая содержимого объектов

Scenario: Общие часы двух слоёв

• WHEN запрашиваются самые свежие часы, за которые у метрики есть объекты и в минутном, и в часовом слое
• THEN запрос отвечает по индексу и читает не больше запрошенного числа часов

Requirement: Объекты перечисленных часов читаются пакетом

Хранилище SHALL уметь отдать объекты двух слоёв за перечисленные часы одной метрики одним запросом, а не по объекту за раз.

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

Scenario: Окно из многих часов

• GIVEN запрошены объекты двух слоёв за сорок восемь часов
• WHEN выполняется выборка
• THEN число обращений к базе не зависит от числа часов