houseplan-card/docs/specs/419-area-snapshot-roster-guard.md

ТЗ #419 — Безопасная уборка Area-снапшота при пустом или усечённом HA-реестре

• Issue: https://github.com/Matysh/houseplan-card/issues/419
• Приоритет: P2, bug
• Маршрут: standard; persistent lifecycle metadata и destructive cleanup
• Связанные контракты: #126 (переезд HA Area), #403 (отказ записи), #406 (уборка осиротевших записей)
• Решения владельца: defaults Q1–Q3 приняты 2026-09-02

Сценарий

Хозяин дома уже расставил устройства на плане. Во время запуска, перезапуска или обновления Home Assistant карточка получает успешный, но переходный пустой либо усечённый ответ Device/Entity Registry. Позже устройство снова появляется и меняет HA Area. House Plan должен помнить последнюю принятую Area и корректно отличить переезд от первого обнаружения устройства.

Поверхности: полная карточка и houseplan-space-card; ошибка возникает в общем registry/runtime-контуре до выбора текущего пространства и не зависит от View, редактора, desktop или touch.

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

До: после временно неполного HA-реестра будущий переезд устройства между Area может потерять автоматический перенос и повести себя как первичное размещение.

После: временно пустой или единичный усечённый ответ ничего не забывает; House Plan переносит устройство после настоящей смены Area так же, как до сбоя.

Проблема

resolveDeviceAreaRelocations() получает devices из buildDevices() и считает этот массив доказательством жизни всех записей settings.marker_area_snapshot. Но это presentation-проекция, а не реестр:

• auto-device без Area, без сопоставленной комнаты либо скрытый legacy-фильтром законно отсутствует в devices, оставаясь в HA;
• точная entity может жить как runtime state без строки Entity Registry;
• успешные registry WebSocket-вызовы гарантируют распознаваемые массивы, но не защищают от переходного пустого или усечённого кадра;
• при devices: [], authoritative: true текущий sweep ставит removeSnapshot: true всем прежним записям и следующая запись конфига стирает provenance целиком.

Тем самым реализация пункта (г) #406 нарушает исходный контракт #126: отсутствие в active/display roster не равно доказанному удалению binding.

Скоуп

В скоупе:

• отделить registry-liveness от отфильтрованной DevItem[]-проекции;
• учитывать соответствующий полный registry namespace, точный живой HA state и сохранённые живые markers как положительные доказательства существования;
• не выполнять orphan cleanup по полностью пустому namespace;
• подтверждать отсутствие binding двумя различными успешными непустыми authoritative registry revisions;
• после первого отсутствия один раз запросить контрольное перечитывание реестров без цикла повторных запросов;
• хранить кандидатов первого отсутствия только в runtime карточки;
• сохранить действующие правила переезда, backfill, rebind, explicit placement, tombstone/delete и отказов записи из #126/#403/#406;
• unit, browser smoke и mutation-защита нового lifecycle-контракта;
• синхронизировать техническую документацию и release notes.

Не-скоуп

• изменение UI, сообщений, настроек, Area mapping или алгоритма выбора комнаты;
• изменение формата marker_area_snapshot, лимита 20 000 или backend-схемы;
• восстановление provenance, уже стёртого выпущенной версией;
• общий аудит полноты HA Registry API и эвристика процентного размера roster;
• уборка known_devices, new_device_ids, layout либо marker tombstones;
• изменение limited/unverified-поведения HA bindings;
• изменение самого контракта автоматического переезда #126.

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

1. Положительное доказательство жизни

Orphan-sweep для entry { id, binding, area } не рассматривает binding как исчезнувший, если выполняется хотя бы одно условие:

1. device:<id> присутствует в текущем полном Device Registry;
2. entity:<entity_id> присутствует в текущем полном Entity Registry;
3. для exact entity:<entity_id> существует hass.states[entity_id], включая unavailable/unknown: это доказательство существования, а не активности;
4. в сохранённом plan roster есть живой, не removed marker с тем же binding либо с тем же snapshot id.

Это множество не зависит от Area mapping, текущего пространства, пользовательской фильтрации, showAll, визуального hidden-state или возможности отрисовать DevItem.

Положительное доказательство в любой последующей revision немедленно снимает runtime-кандидат отсутствия. Оно не превращает HA-disabled binding в active и не меняет его presentation status.

2. Пустой registry namespace

Для device:* оценивается только Device Registry, для entity:* — Entity Registry плюс exact live state.

Если соответствующий namespace пуст, а в marker_area_snapshot есть entries этого вида, кадр считается непригодным для destructive cleanup:

• entries сохраняются независимо от runtime-кандидатов;
• пустой кадр не является первым или вторым подтверждением отсутствия;
• он не запускает бесконечные registry reloads;
• следующий непустой authoritative snapshot продолжает обычную проверку.

Легальный случай «пользователь действительно удалил вообще все устройства» оставляет bounded служебные entries. Это принятая fail-safe цена: потеря provenance опаснее фонового мусора под существующим лимитом.

3. Два подтверждения отсутствия

Если namespace непуст, но binding не имеет ни одного положительного доказательства жизни:

1. первое отсутствие в authoritative revision сохраняет entry и записывает runtime-кандидат { binding, firstRevision };
2. карточка инициирует не более одного контрольного refresh на fingerprint набора кандидатов/registry revision;
3. повторная обработка той же revision не считается вторым подтверждением;
4. отсутствие в следующей отличающейся успешной непустой authoritative revision разрешает removeSnapshot: true;
5. появление binding между проходами снимает кандидат без записи конфига;
6. limited/error frame не подтверждает и не удаляет данные.

Кандидат относится к exact binding. Rebind того же marker id не наследует подтверждение старого binding.

4. Runtime lifecycle

Кандидаты отсутствия не сохраняются в config, Local Storage или backend и не переносятся между reload/remount. После новой карточки первое отсутствие снова только ставит runtime-кандидат. Все экземпляры карточки используют общую authoritative registry revision, но каждый держит собственную fail-safe координацию записи; существующая revision/config-защита остаётся источником истины при конкурентных клиентах.

5. Действующие явные cleanup-пути

Двойное подтверждение применяется только к автоматическому orphan-sweep по отсутствию в HA roster. Оно не задерживает:

• явное удаление marker и removeMarkerAreaSnapshots();
• rebind marker, при котором old binding заменяется новым baseline;
• переход marker в explicit/ineligible placement, где старая registry-following provenance больше не применима;
• нормальное продвижение Area provenance после успешного layout delete.

UX

Новых элементов, уведомлений и настроек нет. Исправление намеренно тихое: переходный registry frame не должен требовать действий от пользователя. При реальном удалении устройства возможна задержка служебной уборки до контрольного registry refresh; на видимый план это не влияет.

Desktop, touch, View, kiosk, редакторы и static card получают одинаковый итог: это общий data lifecycle до input/render-веток.

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

Persisted-модель не меняется:

settings.marker_area_snapshot?: Record<string, {
  binding: `device:${string}` | `entity:${string}`;
  area: string;
}>;

Новых compatibility-полей и backend-миграции нет. Runtime-кандидаты имеют ограничение существующим числом entries снапшота и исчезают при remount. Старый frontend продолжает читать тот же config; новый frontend безопаснее решает, когда удалить entry. Full import/export и space-only import сохраняют контракты #126 без изменений.

i18n

Новых строк и изменений словарей нет: UI не меняется.

Затрагиваемые файлы и модули

Ожидаемый минимальный набор:

• src/device-area-relocation.ts — чистое решение liveness/cleanup и его результаты;
• src/houseplan-card.ts — authoritative registry evidence, runtime-кандидаты, bounded confirmation refresh и повторная резолюция перед записью;
• при необходимости src/ha-binding-status.ts — только read-only проекция полного registry roster/revision, без смены binding status;
• test/device-area-relocation.test.mjs — матрица resolver/coordinator;
• demo/smoke_area_relocation.mjs — wiring через production bundle;
• scripts/mutation-gate.mjs — отрицательные доказательства;
• docs/CONFIG-COMPATIBILITY.md, при необходимости docs/FILTERING.md и docs/TESTING.md — нормативный lifecycle и тестовая матрица;
• docs/CHANGELOG.md, docs/CHANGELOG.ru.md — пользовательский bug fix;
• docs/images/screenshots.json — только канонический source fingerprint, если обязательный docs run подтвердит отсутствие пиксельных изменений.

Ревью может сузить техническую раскладку без изменения контракта.

Производительность

На обычных registry rebuild без пропавших snapshot bindings дополнительных сетевых вызовов нет. Проверка остаётся линейной по bounded snapshot и текущим registry/marker sets.

Первое квалифицированное отсутствие допускает одну дополнительную пару registry WebSocket-запросов. Дедупликация по revision и fingerprint кандидатов обязана исключить запрос на state tick, повторный render, повторную обработку той же revision и бесконечный цикл при пустом namespace. Нового performance-профиля не требуется; smoke доказывает число вызовов.

Touch, accessibility и security

Touch/pointer/keyboard/focus/ARIA не меняются. Новых входных данных, HTML, URL, команд, прав или раскрытия HA metadata нет. Security-review сверх обычного code review не требуется.

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

• AC1. Пустой derived devices не удаляет entry, если exact binding есть в соответствующем полном HA Registry, даже когда устройство отфильтровано или его Area не сопоставлена комнате. Доказательство: unit + browser smoke.
• AC2. Полностью пустой Device Registry не удаляет ни одну device:* entry, а полностью пустой Entity Registry не удаляет entity:* entries; повторный пустой snapshot тоже не становится подтверждением. Доказательство: unit + browser smoke.
• AC3. Exact live hass.states[entity_id] сохраняет entity:* entry без registry row; unavailable и unknown тоже сохраняют её. Доказательство: parameterized unit.
• AC4. Живой сохранённый marker сохраняет matching binding/id независимо от presentation filtering; removed: true не считается живым. Доказательство: unit.
• AC5. Первое отсутствие binding в непустой authoritative revision не меняет persisted snapshot и создаёт runtime-кандидат; повтор той же revision не удаляет entry. Доказательство: unit + browser smoke.
• AC6. Второе отсутствие того же exact binding в отличающейся успешной непустой authoritative revision разрешает удалить только matching entries; живые соседние entries остаются. Доказательство: unit + browser smoke.
• AC7. Возврат binding между двумя проходами снимает кандидат и не вызывает config write; последующее отсутствие снова считается первым. Доказательство: unit + browser smoke.
• AC8. Limited/error revision ничего не подтверждает и не удаляет; reload/remount не наследует первый кандидат. Доказательство: unit.
• AC9. После первого квалифицированного отсутствия выполняется ровно один confirmation refresh; state ticks, повтор той же revision, пустой namespace и неизменный кандидат не создают reload-loop. Доказательство: browser smoke с точным счётчиком registry WS-вызовов.
• AC10. Явное удаление/rebind/explicit-ineligible cleanup и успешный Area relocation сохраняют прежнее однопроходное поведение; новая защита их не задерживает. Доказательство: существующие и дополнительные unit cases плюс весь demo/smoke_area_relocation.mjs.
• AC11. При ошибке записи config подтверждённая cleanup decision остаётся повторяемой, а неподтверждённая никогда не попадает в write batch. Доказательство: browser smoke на отказ config/set и следующий rebuild.
• AC12. Мутанты «вернуть derived roster как authority», «считать первое отсутствие достаточным» и «разрешить cleanup пустого namespace» краснеют на целевых тестах/смоке. Доказательство: node scripts/mutation-gate.mjs --check.
• AC13. Typecheck, полный unit suite и build зелёные; bundle-копии синхронны, новых any нет. Доказательство: локальные гейты процесса.
• AC14. Технические документы и оба changelog описывают новый fail-safe контракт; визуал не меняется. Для изменения src/** канонический Docs screenshots run на task branch принят, все imageSha256 остаются прежними, меняется только source fingerprint при необходимости. Доказательство: check-docs, CI run и diff manifest.

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

Unit

Расширить test/device-area-relocation.test.mjs матрицей:

1. derived roster пуст, raw device существует;
2. device/entity namespace пуст один и несколько проходов;
3. entity без registry row со states on, unavailable, unknown;
4. живой/removed marker;
5. первое отсутствие, повтор той же revision, второе отсутствие в новой;
6. восстановление между проходами и повторный первый кандидат;
7. independent device/entity namespaces;
8. новый runtime coordinator после remount;
9. explicit placement, rebind и normal relocation без задержки.

Browser smoke

Расширить demo/smoke_area_relocation.mjs production-bundle сценариями:

• переходный усечённый frame → нет config write → один refresh → binding вернулся → snapshot прежний;
• два непустых distinct revisions без binding → удалена только orphan entry;
• два пустых frames → snapshot не меняется, refresh-loop отсутствует;
• confirmed cleanup + отказ config/set → решение повторяется безопасно;
• существующая матрица #126/#403/#406 остаётся зелёной.

Mutation

Добавить три точечных мутанта из AC12, каждый со штатным witness. Полная smoke- матрица, golden и performance остаются предрелизными; целевой area smoke входит в цикл реализации.

Риски и смягчение

• Два переходных усечённых ответа подряд. Они всё ещё могут выглядеть как подтверждённое удаление. Пустой namespace защищён безусловно; для непустого roster принята владельцем граница двух distinct revisions и контрольный refresh. Более сильная гарантия потребовала бы backend tombstones HA.
• Reload-loop. Confirmation refresh может сам породить новую revision. Смягчение: один запрос на fingerprint первого кандидата, второй проход либо удаляет, либо сбрасывает; пустые namespaces запрос не размножают (AC9).
• Уборка настоящего orphan задерживается или не выполняется при полностью пустом HA. Это принятая fail-safe деградация; map bounded 20 000 entries.
• Presentation и registry снова смешаются. API чистого resolver явно разделяет devices для relocation и binding-evidence для sweep; мутант AC12 защищает шов.
• Два клиента подтверждают в разное время. Удаление идемпотентно, config revision/conflict path остаётся authoritative; runtime-кандидат не становится вторым persisted источником.

Откат

Feature flag не нужен: UI и schema не меняются. Откат — revert frontend- коммита. Persisted config останется совместимым в обе стороны; записи, сохранённые новым guard, старый frontend сможет прочитать. Уже удалённые старой версией entries автоматически не восстанавливаются.

Release-артефакты

• docs/CHANGELOG.md и docs/CHANGELOG.ru.md: одна user-visible запись со ссылкой на #419;
• актуализация нормативного lifecycle в docs/CONFIG-COMPATIBILITY.md и, если затронута формулировка фильтрации/проверок, docs/FILTERING.md / docs/TESTING.md;
• golden не меняется; обязательный canonical Docs screenshots run подтверждает отсутствие визуальной дельты для src/**;
• новых performance/security/release assets нет;
• issue остаётся открытым до пакетного закрытия при выпуске беты.

Принято предположительно, поменять свободно при ревью

• Runtime-кандидаты удобно хранить по exact binding и первой qualifying registry revision; persisted candidate map не вводится.
• Resolver получает отдельно presentation devices и read-only registry/state/ marker evidence либо заранее построенные sets; конкретная сигнатура не часть продукта.
• Empty guard применяется раздельно к Device и Entity Registry, чтобы пустой Entity Registry не блокировал уборку доказанно исчезнувшего device:*, и наоборот.
• Confirmation refresh использует существующий shared registry cache и его debounce; отдельная подписка и новый таймер не создаются.
• Положительное evidence снимает candidate до построения write batch; решение об intentional cleanup собственного marker id остаётся выше orphan-sweep.