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

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

• Issue: https://github.com/Matysh/houseplan-card/issues/33
• Приоритет: P1
• Статус ТЗ: Stage A частично реализован; документ определяет завершение

Цель

Сделать drift между TypeScript, UI, runtime и Voluptuous обнаруживаемым в CI, а судьбу каждого public/legacy/internal поля — явной и проверяемой.

Канонический registry

Развить scripts/config-field-registry.mjs до полного manifest. Запись поля:

path, owner, value kind, enum/range/default, inheritance,
frontend type, backend schema, UI surface, runtime consumers,
introduced, write policy, read-compat-until, migration, unknown-child policy

Manifest описывает все сохраняемые config и layout поля, а не только legacy. Для dynamic maps (calibration, layout ids) фиксируется shape значения и policy ключей. Секреты/контент в manifest не попадают.

Паритет и CI

1. Скрипт извлекает/нормализует enum/ranges из frontend declarations и backend schema adapters.
2. Любой отсутствующий field decision или несовпадение enum/range ломает CI.
3. extra=ALLOW_EXTRA сохраняет future fields, но не освобождает известное поле от регистрации.
4. Fixtures содержат oldest-supported, current и future-field config; load/save без explicit optimization сохраняет неизвестные поля и визуальную семантику.

Локальный audit

scripts/config-audit.mjs принимает экспортированный JSON локально, ничего не отправляет наружу и выдаёт counts по legacy fields, planned migrations и unknown paths без значений персональных данных. Exit codes различают clean, migration available и invalid.

Lifecycle

• read-only legacy: читается, но никогда не пишется новым UI;
• migrate-on-explicit-optimize: preview diff → atomic write → undo;
• deprecated: имеет дату/версию окончания чтения и changelog;
• internal supported: получает documented UI/default либо становится фиксированным правилом и удаляется из storage;
• неизвестное future field сохраняется losslessly.

Первый decision set включает tap_action, display ripple, show_all, weather_entity, vacuum room_highlight/segment_map, group_lights и exclude_integrations; последние два координируются с #44.

Приёмка

• 100% известных persisted paths зарегистрированы;
• schema drift имеет понятный CI diff;
• audit не выводит имена/id/координаты по умолчанию;
• Optimize показывает точные изменения до записи и имеет безопасный undo;
• обычное открытие/сохранение старого/future config не меняет визуал.