houseplan-card/docs/specs/033-config-schema-lifecycle.md

ТЗ #33 — Единый registry схемы и lifecycle compatibility-полей

• Issue: https://github.com/Matysh/houseplan-card/issues/33
• Приоритет: P2, tech-debt; полный трек (класс A schema-потребители — решение аналитики 2026-08-15, не оспаривается)
• Ревизия: 3 (2026-08-30) — по SPEC-REVIEW-33-r1 (M1–M3, Low); замеры ревизии: CONFIG_SCHEMA = 212 листовых путей, LAYOUT_SCHEMA = 2, registry = 27 записей, parity/CI/фикстур нет

Сценарий

Разработчик добавляет значение в enum на одной стороне (Voluptuous или TypeScript) и забывает вторую — сегодня это молча живёт до полевого бага. После задачи CI краснеет с понятным диффом («backend fill_mode знает 'glow', frontend SPACE_FILL_MODES — нет: либо допиши, либо внеси в allow-list компат-расхождений»). Владелец плана ничего нового не видит — задача не меняет ни одного байта поведения конфига.

Что человек увидит до и после

Ничего: чисто инженерная страховка. Единственный видимый след — CI-джоба, падающая при дрейфе схемы, и npm run audit:config, который стал полнее.

Проблема

Схема расползлась по четырём мирам (Voluptuous, TS-типы, const-списки runtime, UI) и синхронизируется руками. Registry (27 записей) покрывает только слой «компат-решений» и отстал даже в нём: 4 решения уже реализованы кодом (show_all, weather_entity, ripple-канонизация, aspect/segments через vol.Remove), а новые поля v1.68–v1.69 (decor_default_style, furniture-decor, host=partition) не имеют паспорта. Полного манифеста persisted-путей нет; узаконенные read-compat расхождения (fill_mode 'glow', display 'ripple', tap_action 'cover') нигде не записаны машиночитаемо.

Ключевое решение ревизии 2

Канонический манифест НЕ пишется руками на 212 путей — он генерируется из Voluptuous-схемы: бэкенд — единственный владелец формы persisted-данных, всё остальное сверяется с ним. Registry остаётся отдельным слоем решений ПОВЕРХ манифеста. Судьбы group_lights/exclude_integrations решает #44 — здесь они получают только паспорт ALLOW_EXTRA.

Скоуп (три блока)

Блок 1 — генерируемый манифест схемы

• scripts/dump-config-schema.py: обходит CONFIG_SCHEMA/LAYOUT_SCHEMA (Optional/Required, default, vol.In → enum, vol.Range → min/max, vol.Any → варианты, vol.Remove → отметка dropped, ALLOW_EXTRA → флаг узла) и пишет детерминированный scripts/config-schema.json (сортировка путей, стабильная сериализация; имя БЕЗ суффикса *manifest.json — HACS глобит его по всему клону, tест repo-hygiene). Импорт validation.py без homeassistant — заглушки родительских пакетов (приём проверен инвентаризацией этой ревизии).
• Манифест коммитится; pytest-тест регенерирует его в tmp и сравнивает байт-в-байт — рассинхрон схемы и манифеста ломает CI с diff-ом.

Блок 2 — parity и полнота

• test/config-schema-parity.test.mjs читает манифест и сверяет enum-пары с const-декларациями фронта. Готовые экспортируемые массивы существуют для 3 из 7 пар: fill_mode ↔ SPACE_FILL_MODES/ROOM_FILL_MODES, display ↔ DISPLAY_MODES, tap_action ↔ TAP_ACTIONS (все — logic.ts). Для остальных четырёх (M2 r1: сегодня это только TS-union'ы или фолбэки, не runtime-значения) декларации ЗАВОДЯТСЯ этим issue: OPENING_TYPES (types.ts-соседство), VACUUM_TRAIL_MODES, ZERO_WALL_STYLES, BG_MODES — экспортируемые as const-массивы, из которых выводятся существующие union-типы (typeof X[number]), чтобы список и тип не могли разойтись; рантайм-поведение не меняется. Расхождение с манифестом падает, если его нет в машиночитаемом allow-list scripts/schema-compat-allowlist.mjs (каждая запись: сторона-владелец, значение, причина, ссылка на issue). Стартовый allow-list: fill_mode 'glow' (backend-only, read-compat #20-эры), display 'ripple' (backend-only, канонизация в icon_ripple), tap_action 'cover' (backend-only, read-compat).
• Тест полноты registry: каждый id из config-field-registry.mjs разрешается либо в путь манифеста, либо в явный extra-паспорт (show_all, group_lights, exclude_integrations — поля вне схемы, живущие через ALLOW_EXTRA; список — в registry новым полем schema: 'allow-extra'). Registry-запись, не находящая цель, ломает тест (мёртвые решения не накапливаются).
• Актуализация registry как данных (M1 r1: статусная модель НЕ меняется — существующие статусы описывают механизм и не устаревают с появлением кода): 4 реализованных решения получают новое ОПЦИОНАЛЬНОЕ поле enforcedBy — ссылку на кодовую точку/тест, доказывающую механизм (show_all → houseplan-card.ts материализация; weather_entity → editor-runtime сохранение настроек; ripple → _dropLegacySegments + normalizeDeviceDisplay; aspect/segments → vol.Remove в схеме). Новые паспорта со статусом current — settings.decor_default_style (v1.69), decor kind:'furniture' (v1.69), openings[].host=partition (v1.68, model v9). Registry по-прежнему НЕ зеркалит все 212 путей — только поля с нетривиальной судьбой; полноту обычных полей несёт манифест.

Блок 3 — фикстуры lifecycle

• test/fixtures/config-lifecycle/: три фикстуры — oldest-supported (легаси-поля: show_all, weather_entity, display 'ripple', walls-проекция), current (срез v1.69 с decor_default_style/furniture/value_source), future (незнакомые поля на всех уровнях).
• pytest: каждая проходит CONFIG_SCHEMA; future-поля переживают валидацию losslessly (ALLOW_EXTRA-контракт), legacy не отбрасывается кроме задокументированных vol.Remove.
• config-audit.mjs получает НОВУЮ CLI-логику итогового кода (M3 r1: сегодня exitCode зависит только от ошибок разбора). Контракт: 0 — clean (легаси/миграций не найдено), 3 — migration available (найдены поля со статусом migrate-*/deprecated-read), 2 — invalid input (существующее значение, не меняется). Код 3 выбран, чтобы не конфликтовать с текущим 2. Юнит на фикстурах Блока 3 проверяет и counts, и все три кода — расширение test/config-audit.test.mjs.

Не-скоуп

• Изменение поведения ЛЮБОГО поля, новые миграции, изменение схемы.
• Судьба group_lights/exclude_integrations (это #44).
• Автогенерация TS-типов из манифеста (возможный будущий шаг).
• Optimize-превью миграций (существующий механизм не трогается).
• Числовые range-сверки фронта (у фронта нет машиночитаемых range-деклараций; манифест их несёт, сверка появится вместе с декларациями).

Контракт поведения

Ничего в рантайме не меняется. Новые артефакты: манифест (JSON), allow-list (mjs), дамп-скрипт (py), два теста, фикстуры, паспорта в registry.

UX / i18n

Не задето. Новых строк нет.

Модель данных и миграция

Persisted-данные не меняются. Манифест — build-артефакт в git, не в бандле (бюджет initial не растёт).

Критерии приёмки

• AC1: scripts/config-schema.json детерминирован (два прогона дампа байт-идентичны) и покрывает 100% листовых путей CONFIG/LAYOUT-схем; pytest падает при рассинхроне схемы и закоммиченного манифеста, diff показывает пути.
• AC2: parity-тест зелёный на текущем дереве; добавление значения в бэкенд-enum без пары и без allow-записи → красный с именем enum и значением (доказательство мутантом м1).
• AC3: удаление записи allow-list при сохранённом расхождении → красный (расхождения не узакониваются молча).
• AC4: тест полноты registry зелёный; запись с несуществующей целью → красный (мутант м2: сломать selector одной записи).
• AC5: все три фикстуры проходят схему; future-поля возвращаются из валидации без потерь (pytest, сравнение по путям).
• AC6: config-audit.mjs возвращает 0/3/2 по контракту Блока 3 на clean/legacy/битой фикстурах соответственно (юнит).
• AC7: полный гейт зелёный; бюджет initial без изменений (манифест не импортируется бандлом — контракт-проверка отсутствия импорта).

План автотестов

• pytest: AC1 (свежесть манифеста), AC5 (фикстуры) — в tests_backend (обходчик без homeassistant, работает и в песочнице).
• node --test: AC2/AC3 (parity + allow-list), AC4 (полнота registry), AC6 (audit exit-codes), AC7-контракт (нет импорта манифеста из src/**).
• Мутанты (mutation-gate): м1 — подмена одного enum-списка фронта (убрать значение из DISPLAY_MODES-копии проверяемой пары) → красный AC2; м2 — испортить selector одной registry-записи → красный AC4.

Риски

• Дамп-скрипт может отставать от новых конструкций Voluptuous (Coerce, кастомные валидаторы): fail-closed — незнакомый валидатор пишется в манифест как opaque с исходным repr, тест свежести это переживает, parity такие узлы не судит.
• Ложные срабатывания parity на легитимных решениях — гасятся allow-list'ом с обязательной причиной и ссылкой.
• CI-время: дамп-регенерация — миллисекунды (walk по объектам в памяти).

Откат

git revert: все артефакты — новые файлы + паспорта-данные в registry; рантайм не тронут, откат ничего не теряет.

DoR-примечания: миграция/compatibility — нет (только чтение схемы); touch — не влияет; производительность — не влияет (build/test-time).

Release-артефакты

• CHANGELOG + CHANGELOG.ru: короткая запись (инфраструктура защиты схемы), User-Visible: yes у финального коммита (пользователь получает гарантию «старый конфиг не портится молча», это честно назвать).
• docs/ARCHITECTURE.md: абзац «схема как источник истины: манифест, parity, allow-list» со ссылками на скрипты.

Принятые предположения

• Бэкенд-схема — единственный канонический источник формы persisted-данных; фронтовые типы — потребители (соответствует факту: все записи идут через config/set с валидацией).
• Card-level Lovelace-поля (fit, light_pools, show_button…) — НЕ persisted store и в манифест не входят; их учёт — вне скоупа (при желании — отдельный issue).
• Registry остаётся «слоем решений», а не зеркалом схемы, — по исходной шапке файла; полноту несёт манифест.