healthlog/openspec/changes/archive/2026-08-02-trenirovki-i-zapisi/specs/parsing/spec.md

ADDED Requirements

Requirement: Разбор секций с собственными идентификаторами

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

Покрываются две такие секции: data.workouts и data.stateOfMind. Секции ecg, symptoms, cycleTracking, medications и heartRateNotifications покрытыми MUST NOT становиться: живой поток не приносил их ни разу (118 доставок), их форма никем не наблюдалась, а полнота покрытия HealthKit ради полноты целью проекта не является. Они остаются в списке непокрытых, и доставка с ними остаётся partial.

Из тренировки разбор SHALL брать только то, по чему потом идёт выборка: идентификатор, имя, начало, конец, офсет исходной зоны и длительность. Всё остальное — включая маршрут, внутренние ряды (heartRateData, activeEnergy, heartRateRecovery) и сводки — MUST храниться содержимым сущности дословно, теми же байтами, какими пришло. Раскладывать структуру тренировки по колонкам значило бы решить за Apple, что в ней главное: сводки дублируют ряды (distance — это сумма walkingAndRunningDistance), а набор полей зависит от типа тренировки (у уличной есть route, avgSpeed, flightsClimbed, у домашней — temperature, humidity, intensity).

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

Началом сущности SHALL быть start, при его отсутствии — date. Конец берётся из end; при отсутствии или неразбираемости конца он SHALL равняться началу, а истина остаётся в содержимом. Вырождение интервала здесь безопасно, в отличие от точки: ключ сущности — id, схлопывать координаты нечем. Офсет исходной зоны SHALL браться из начала: колонка одна, а тренировка через смену зоны дала бы два разных.

Из записи разбор SHALL брать идентификатор, род секции, метку времени и офсет; всё остальное хранится дословно. Род записи SHALL быть верхнеуровневым ключом секции HAE дословно (stateOfMind, не state_of_mind): инвариант «форма Apple не транслируется» относится и к именам секций.

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

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

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

Отсутствие покрытой секции в теле ошибкой быть MUST NOT: доставки из одних метрик — большинство потока.

Scenario: Тренировка разбирается вместе с маршрутом

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

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

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

Scenario: Запись состояния разума разбирается

• WHEN тело содержит data.stateOfMind с элементом, несущим id и start
• THEN разбор отдаёт запись с родом stateOfMind, идентификатором, меткой времени и содержимым исходными байтами

Scenario: Сущность без идентификатора пропускается

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

Scenario: Элемент секции не является объектом

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

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

Scenario: Сущность без разбираемой метки времени пропускается

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

Scenario: Сущность со слишком длинным идентификатором пропускается

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

Scenario: Длительность берётся из тела, а не из интервала

• WHEN тренировка несёт duration равный 91.746 при интервале start/end в 91 секунду
• THEN длительность сущности равна 91.746

Scenario: Тренировка без длительности сохраняется без неё

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

Scenario: Нечитаемый конец тренировки не отбрасывает её

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

Scenario: Незнакомое поле тренировки переживает разбор

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

Scenario: Непокрытая секция с собственными id остаётся непокрытой

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

MODIFIED Requirements

Requirement: Отказ разбора остаётся всё или ничего

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

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

Правило SHALL распространяться и на невыводимый слой: доставка, у которой есть метрики, но слой их не определяется, не сохраняет и своих сущностей, хотя слоя у сущности нет. Соблазн «сущности от слоя не зависят, запишем их» ломает то же «всё или ничего» — доставка получила бы failed при частично записанной витрине, и повторная свёртка перестала бы быть no-op. Цена названа вслух: если такая доставка когда-нибудь принесёт stateOfMind, его записи доедут не сразу, а пересборкой; тело при этом остаётся в архиве, и failed ретеншену трогать нельзя.

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

Scenario: Тело оборвано после секции метрик

• WHEN тело содержит целую секцию metrics, а следующий член data оборван
• THEN разбор завершается ошибкой и точек не отдаёт

Scenario: Тело оборвано после секции тренировок

• WHEN тело содержит целую секцию workouts, а следующий член data оборван
• THEN разбор завершается ошибкой и сущностей не отдаёт

Scenario: Невыводимый слой не сохраняет и сущностей

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

Scenario: Секция метрик встречается дважды

• WHEN объект data содержит два ключа metrics
• THEN точки обеих секций попадают в результат

Scenario: Секция тренировок встречается дважды

• WHEN объект data содержит два ключа workouts
• THEN сущности обеих секций попадают в результат

Scenario: Член data встречается дважды

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

Requirement: Разбор форматов времени

Система SHALL разбирать метку формата 2026-07-31 21:03:51 +0300 и приводить её к UTC, сохраняя офсет исходной зоны. В секции data.metrics других форматов меток не встречается.

Система SHALL разбирать вторым форматом RFC 3339 в UTC (2026-07-31T18:03:51Z): им приходят метки секции data.stateOfMind, тогда как тренировки и метрики шлют первый формат. Оба формата SHALL приниматься у любой метки сущности, а не приписываться секции жёстко: формы однозначны и не пересекаются, а HAE выравнивает секции между собой по ходу своих обновлений — stateOfMind уже шлёт стабильные коды HealthKit там, где старые секции шлют переводы. Приписанный секции формат ломался бы молча в день такого выравнивания.

Метка RFC 3339 в UTC даёт офсет 0, и это MUST означать «источник прислал UTC», а не «человек находился в нулевой зоне»: местной зоны у секции stateOfMind в потоке нет вовсе.

Метка точки при этом остаётся строгой — один формат, — и асимметрия намеренная. По метке точки выводится слой, причём по метке в исходной зоне; терпимость к RFC 3339 означала бы, что метка в UTC тихо портит выравнивание и часовая выгрузка складывается с минутной (наблюдалось: удвоение суммы за час). У сущности слоя нет, и терять на строгости нечего, а у точки строгий парсер отдаёт непонятую метку в счётчик пропусков — тело остаётся в архиве, и пересборка вернёт его, когда формат станет известен.

Unix-эпоха дробным числом (1785446196.4132624) встречается внутри heartbeatSeries и меткой точки не является. Система MUST NOT преобразовывать её: элементы серии проходят как исходные байты. Преобразование во time.Unix и обратно не гарантирует дословности, а серия составляет 93% объёма метрики heart_rate_variability.

Время внутри маршрута тренировки (route[].timestamp) меткой сущности тоже не является и MUST проходить дословно, не разбираясь.

Scenario: Локальное время со смещением

• WHEN метка имеет вид 2026-07-31 21:03:51 +0300
• THEN точка получает время в UTC и офсет +10800 секунд

Scenario: RFC 3339 в UTC

• WHEN метка сущности имеет вид 2026-07-31T18:03:51Z
• THEN сущность получает время в UTC и офсет 0

Scenario: Тренировка со временем в формате метрик

• WHEN тренировка несёт start вида 2026-08-01 10:04:31 +0300
• THEN сущность получает время в UTC и офсет +10800 секунд

Scenario: Время внутри серии ударов

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

Scenario: Время внутри маршрута не разбирается

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

Requirement: Перечисление непокрытых секций доставки

Разбор SHALL перечислять верхнеуровневые ключи объекта data и возвращать вызывающему те из них, которые он не покрывает. Содержимое непокрытой секции MUST NOT удерживаться после того, как разбор прошёл мимо неё: тела доходят до 42 МиБ, и удержание кучи здесь — часть контракта, а не деталь реализации.

Покрытых ключей сегодня три — metrics, workouts и stateOfMind. Разбор и перечисление MUST ходить по одному объявленному множеству покрытых имён: состояние «секция разбирается, но числится непокрытой» невыразимо по построению.

Непокрытым ключ считается независимо от того, что лежит внутри: содержимое не интерпретируется, поэтому и о пустоте секции разбор честно ничего не знает. Измерено на живом архиве — пустых секций HAE не присылает ни разу (118 доставок).

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

Отсутствие непокрытых ключей и отсутствие секции metrics — разные события, и оба нормальны: половина потока состоит из доставок без метрик вовсе (53 из 118).

Scenario: Незнакомая секция попадает в список непокрытых

• WHEN тело содержит data.ecg наряду с data.metrics
• THEN разбор возвращает ecg в списке непокрытых ключей
• AND точки секции metrics разбираются как обычно

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

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

Scenario: Доставка из одного состояния разума непокрытых ключей не даёт

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

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

• WHEN единственный ключ data — metrics
• THEN список непокрытых ключей пуст

Scenario: Один и тот же набор секций даёт один и тот же список

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

Scenario: Содержимое непокрытой секции не удерживается в памяти

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