houseplan-card/docs/reviews/SPEC-REVIEW-490-r1.md

SPEC-REVIEW-490-r1

• Issue: #490 — «Атомарный recovery и live-состояние сводной панели»
• Этап: ТЗ на ревью (S4-spec-review), PROCESS.md §2.4
• Заход: r1 · блокирующих циклов израсходовано 0 из 4
• Артефакт ТЗ: docs/specs/490-summary-recovery-live-state.md, коммит 95a34f730a572c06c732e1e029b2c8dc719428b9, ветка issue/490-summary-recovery-live-state
• Трек: полный (не small) — обоснование в S2-комментарии проверено и корректно: больше одной поверхности (save-контракт панели + render dependency projection в houseplan-card.ts), multi-client concurrency/state contract, влияние на высокочастотный render scheduling

Скоуп

Issue заведён по прямой команде владельца из независимого аудита (2026-09-08, §11 п.1/12) по уже опубликованному в dev (но не зарелиженному) #437. Два подтверждённых дефекта:

• F1 — saveDialog() в lost-ACK ветке принимает только rev из повторного config/get, но затем безусловно перезаписывает _serverCfg старым candidate, поэтому параллельная правка другого клиента к несвязанному полю документа теряется при следующей записи;
• F2 — резолвер зависимостей рендера (_captureRenderDeviceSnapshot) не включает entity-источники summary_panel.blocks[].values[], поэтому summary-only датчик не обновляется на обычном HA-tick.

Это соответствует docs/SCOPE.md J1 (live-обзор), J2, J6 (multi-client sync, optimistic locking) — ТЗ не расширяет функциональность #437, а чинит регресс уже принятого контракта.

Как проверялось

Ревью читал ТЗ и сверял каждое заявленное поведение с:

• телом issue #490 и обоими комментариями (аналитика S2, готовность ТЗ S3);
• исходным ТЗ #437 (docs/specs/437-summary-panel.md, §7.1, §7.4, §9.1, §9.2) — контракт, который #490 исправляет, а не переопределяет;
• фактическим кодом на SHA 95a34f73 (ветка задачи): src/summary-panel-runtime-loaded.ts (saveDialog()), src/houseplan-card.ts (_captureRenderDeviceSnapshot, _cfgEpoch/willUpdate, _setAreaLifecycleConfig), custom_components/houseplan/validation.py (SUMMARY_PANEL_SCHEMA — max=10 блоков × max=20 значений);
• существующими тестами, которые ТЗ обещает расширить: test/summary-panel.test.mjs, test/render-device-snapshot.test.mjs, test/render-invalidation.test.mjs, demo/smoke_summary_panel.mjs — все существуют, план тестирования не ссылается на несуществующие файлы.

Продуктовый код не менялся и не оценивался на корректность реализации — это код-ревью следующего этапа. Проверялось только то, что ТЗ описывает проверяемый и технически достижимый контракт.

Проверка root cause (F1)

saveDialog() (src/summary-panel-runtime-loaded.ts, ветка catch (writeError)): при совпадении saved/draft принимает this.host._cfgRev = authoritative.rev, но this.host._serverCfg = candidate (старый локальный кандидат) стоит вне catch-блока и выполняется безусловно после любого исхода try. Соответствует описанию §3 п.1 ТЗ дословно.

Проверка root cause (F2)

entityIds в _captureRenderDeviceSnapshot собирается из room.settings.temp_source/hum_source, openingEntityReferences, decor-текстов и _vacFit.source — обхода settings.summary_panel нет нигде в файле (grep summary_panel src/houseplan-card.ts — 0 совпадений). Соответствует §3 п.2 ТЗ.

Проверка «200 values» (§14, принятое предположение №2)

Не голословно: backend-схема SUMMARY_PANEL_SCHEMA ограничивает blocks vol.Length(max=10), values внутри блока — vol.Length(max=20), итог 10×20=200 — число в ТЗ точное, не придуманное.

Проверка терминологии AC5 (identity/epoch)

_cfgEpoch — реальный существующий механизм (houseplan-card.ts, willUpdate, комментарий DEV-B701-01), уже используемый именно как сигнал «геометрию нужно пересчитать» отдельно от _cfgRev (concurrency-номер). Существует прецедент атомарной подмены _serverCfg без бампа эпохи (_setAreaLifecycleConfig) — доказывает, что контракт §6.2 «принять весь authoritative config через общий adoption seam» и §7.2 «relevant tick не меняет geometry epoch» технически реализуем в существующей архитектуре, а не выдуман.

Проверка словаря AC5 (relevant/irrelevant tick)

test/render-invalidation.test.mjs уже использует ровно эти термины (an unrelated HA state row does not invalidate..., a dependency row identity or presence change invalidates state...) — ТЗ говорит на языке существующего теста, план тестирования реалистичен.

Находки

Нет High. Нет Medium (ни в скоупе, ни вне скоупа). Нет Low.

Что проверено и корректно

• Обязательные разделы §7.1 присутствуют по существу: сценарий (§1), до/после (§2), проблема как «подтверждённые причины» (§3), скоуп (§4), не-скоуп (§5), контракт поведения (§6–7), совместимость/данные/i18n (§8, явно «миграции нет»), AC1–AC6 с доказательством (§9), план автотестов (§10), риски (§11), откат (§12), release-артефакты (§13).
• Каждый AC — проверяемое утверждение с указанным способом доказательства (unit/integration/smoke), не общая фраза; AC3 и негативная матрица явно отделяют «настоящий конфликт» от «потерянного ACK», что закрывает главный риск регрессии #102-типа (правка по одному AC не должна ломать соседний).
• Не-скоуп (§5) корректно исключает #493 (picker/scale/mobile/lifecycle) и не переопределяет backend/API/схему — F1/F2 действительно локальны к save-контракту и render-dependency-проекции.
• Раздел «Принятые предположения» (§14) размечен явно и корректно: все четыре пункта — технические решения (детектирование lost ACK, bounded dependency set, семантика unavailable/missing, отсутствие нового UX-контракта), ни один не маскирует продуктовый вопрос под факт. Проверка по существу (см. «200 values» выше) показала, что предположения не являются догадками, а выводимы из уже существующего кода/схемы.
• Продуктовых вопросов владельцу нет и не должно быть: ожидаемое поведение уже зафиксировано контрактом #437 (§7.1, §7.4, §9.1) — задача восстанавливает, а не придумывает поведение. Никакого технического вопроса, ошибочно адресованного владельцу, не найдено.
• Откат (§12) специфичен для этой задачи: явно запрещает частичный rollback одной из двух половин фикса, если тесты по-прежнему обещают общий контракт — не шаблонная фраза.
• Release-артефакты (§13) корректно называют «golden не требуется» с обоснованием (нет визуальных изменений) вместо молчаливого пропуска.

Чего не проверял

• Не проверялась реализация — код по этой задаче ещё не написан (issue в S4-spec-review, не S6/S7). Проверка «работает ли реализация» — предмет код-ревью следующего этапа.
• Не запускались гейты (typecheck/test/build) — на этапе ТЗ они не относятся к предмету ревью (нет изменений в src/**/test/** этой задачи; коммит 95a34f73 — только docs/specs/**, класс C).
• Не проверялась производительность существующего render-invalidation пути вне контекста этой задачи — вне скоупа.

Материал раунда

• SHA: 95a34f730a572c06c732e1e029b2c8dc719428b9 (ветка issue/490-summary-recovery-live-state)
• ТЗ: docs/specs/490-summary-recovery-live-state.md на этом SHA

Вердикт

Зелёный. ТЗ технически обоснованно, каждое заявленное расхождение с контрактом #437 подтверждено чтением кода на указанных строках, все AC проверяемы и снабжены способом доказательства, план тестов ссылается на существующие файлы, предположения размечены и не подменяют продуктовые решения. High: 0, Medium: 0.

---

Материал раунда

• Ветка: issue/490-summary-recovery-live-state, коммит 95a34f730a57 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 17238622e9af7346270d88a5100e8b6260789ca6

  git log --all --format='%H %T' | grep 17238622e9af
  

• ТЗ docs/specs/490-summary-recovery-live-state.md, блоб d4bfd4ea63f1b2ce1cb255b2764fe14d25661df7

  git log --all --find-object=d4bfd4ea63f1b2ce1cb255b2764fe14d25661df7 -- docs/specs/490-summary-recovery-live-state.md