houseplan-card/docs/reviews/CODE-REVIEW-434-r1.md

# CODE-REVIEW-434-r1

- Issue: #434 — «Полиш аудита v1.71.0-beta.1»
- Этап: код-ревью (PROCESS.md §2.7), полный трек
- Заход: r1 · блокирующих циклов израсходовано 0/4
- SHA материала: `dbda64e89d6b76cabfe57c21f281cb6d5132c257` (HEAD в момент разбора; сверено `git rev-parse HEAD` непосредственно перед выводом)
- Диапазон: `origin/dev...HEAD` (5 коммитов: `8a75c53e` спека, `f383d8fd`/`4190db54` документы спек-ревью r1/r2, `cba13621` реализация, `dbda64e8` довесок-мутант)
- Ветка ребейзнута конвейером на 1 коммит dev (`a71531ba → dbda64e8`) — разбор проведён полностью, не по дельте, как и требуется для r1.

## Скоуп

ТЗ закрывает девять подтверждённых разрывов аудита v1.71.0-beta.1: физический
учёт decor-blobs независимо от sidecar (AC1), recovery orphan-загрузки с честным
`reused` (AC2), точное явное удаление (AC3), недостающий негативный тест
sidecar-без-blob (AC4), capability guard в `houseplan-space-card` + revision-scoped
resolve cache (AC5, AC6), честный «текущий» locale gate для danger confirmation
(AC7), негативный witness Area snapshot cleanup (AC8), bounded smoke timeouts
(AC9), отзыв support-токена из непринятого превью (AC10). Все относятся к Core
user jobs `docs/SCOPE.md` (надёжность View/редактора, честность данных, CI-гигиена
для Contributor); продуктовой рамки, требующей отдельного вопроса владельцу, не
нашёл.

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

### Дешёвые гейты (прогнаны лично, SHA выше)

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | 0 ошибок |
| Unit (JS) | `npm test` | 1813 тестов, 1812 pass, 1 skipped, 0 fail |
| no-new-any | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | «Новых any нет» (60 добавленных строк в 5 файлах) |
| Build + 3 копии бандла | `npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js && npm run bundle:sync` | совпадают байт-в-байт; `git status` после ребилда чист |
| check-docs (diff трогает `src/**`) | `node scripts/check-docs.mjs` | «Documentation checks passed (7 files, 10 external links)» |
| backend pure | `python3 -m pytest tests_backend/test_decor_assets.py -q` | 52 passed |
| model-invariants | не запускал | diff не трогает геометрию (rooms/walls/`layout`/`marker.space`/`open_spans`) — не применимо |

### Отбор смоков (`node scripts/smoke-select.mjs --base origin/dev --head HEAD`)

Матрица 216 смоков, «широкий» символ — порог >43 смоков. Вывод инструмента:
21 «прямое совпадение», 35 «слабая связь», 1 «зарегистрированная связь»
(`smoke_french_locale` ← `languageRenderGate`, не запускал — French locale
сценарий не задет этой задачей, связь регистрируется как «эта функция широко
переиспользуется», не как прямое следствие правки).

Прогнал целенаправленно:

- `demo/smoke_danger_confirm_branches.mjs` — прямое совпадение, единственный
  файл, названный в AC7 и изменённый в диффе. **OK**, все 38 полей `true`.
- `demo/smoke_space_card_decor_capability.mjs` (новый файл, AC5) — **OK**,
  4/4 поля `true`.
- `demo/smoke_support_feedback.mjs` (новый файл, AC10) — **OK**, 29/29 полей `true`.

Остальные 20 «прямых» и 35 «слабых» совпадений — реакция на широко
переиспользуемые символы (`_cfgRev`, `_snap`, `_config`, `_confirmDanger`),
не специфичные для этой задачи логике; полный прогон всей матрицы — предрелизный
гейт (PROCESS §8), не гейт ревью. Golden не запускал — спека прямо говорит
«Golden не требуется» (визуальный кадр не меняется), проверено чтением: diff не
трогает ни один шаблон рендера кроме `_renderRoot`/`_renderDangerConfirm`,
геометрию которых golden не покрывает по замыслу задачи.

### Backend HA harness — НЕ прогонял (честно, гейт пропущен намеренно)

`tests_backend/test_ha_websocket.py` содержит новые/изменённые тесты для AC2 и
AC3 (`test_decor_asset_upload_deduplicates_and_rejects_mime_spoofing` расширен,
`test_decor_asset_delete_removes_exact_orphans_only` новый). Окружение этого
ревью — Python 3.12, `pytest-homeassistant-custom-component==0.13.357` требует
Python ≥3.14 (проверил: `pip install` дал `ResolutionImpossible`/no matching
distribution), `.venv-backend` отсутствует. Это ограничение среды ревью, не
находка по коду (AGENTS.md: «только облачные агенты держат харнесс»).
**AC2 и AC3 доказаны чтением, не исполнением** — см. ниже.

### Мутационные свидетели — прогнаны выборочно (`--changed` затронул 109/380, полный прогон непропорционален; проверил вручную 8 новых/изменённых записей, относящихся к этой задаче)

`node scripts/mutation-gate.mjs --changed --check` — все 109 применимых
патчей легли на текущий код (`ok` по каждому, 0 `FAIL`). Живой прогон (патч →
пересборка → гард) сделал для мутантов этой задачи:

| Мутант / AC | Гард | Результат живого прогона |
|---|---|---|
| `decor-physical-inventory-follows-sidecars` (AC1) | `pytest -k physical_inventory` | применил патч руками → **тест покраснел** (`assert [] == [...]`) |
| `decor-catalog-accepts-sidecar-without-blob` (AC4) | `pytest -k valid_shaped_sidecar_without_blob` | применил патч руками → **тест покраснел** (`row is not None`) |
| `danger-confirm-uses-last-rendered-language-gate` (AC7) | `smoke_danger_confirm_branches` | применил патч руками → **смок покраснел** на `warmToReadyAllowsBeforeRender` |
| `danger-confirm-warm-transition-cancel-removed` (AC7) | `smoke_danger_confirm_branches` | применил патч руками → **смок покраснел** на 3 полях (`readyToWarmCancelsOpenConfirmation`, `warmLanguageGateKeepsControllerEmpty`, `warmLanguageGateRemovesDecisionSurface`) |
| `area-cleanup-keeps-candidate-outside-current-snapshot` (AC8) | `node --test -k "absent from the current snapshot"` | применил патч руками → **тест покраснел** (`true !== false`) |
| `support-invalid-response-leaks-issued-token` (AC10) | `smoke_support_feedback` | применил патч руками → **смок покраснел** на `invalidPreviewTokenIsDiscardedExactlyOnce` |

После каждого прогона дерево восстановлено (`git status` чист, `cp` бэкапа
исходника обратно + ребилд). Не прогонял живьём: `decor-orphan-repair-runs-after-quota`,
`decor-orphan-repair-claims-reuse`, `decor-delete-skips-orphan-blobs` — их гард
использует `tests_backend/test_ha_websocket.py`, недоступный в этой среде
(см. выше); патчи прошли `--check` (якорь находится ровно один раз в текущем
коде), сама логика разобрана чтением ниже.

## Разбор по AC

**AC1 — physical inventory.** `physical_asset_blobs()`/`physical_asset_usage()`
(`decor_assets.py`) считают файлы через `stat(follow_symlinks=False)` +
`S_ISREG` + `suffix in ASSET_EXTENSIONS` + `ASSET_ID_RE.fullmatch(stem)` —
директории, symlink, `.json`, неизвестные расширения и prefix-совпадения не
входят; новый тест `test_physical_inventory_counts_exact_promoted_blobs_not_sidecars`
проверяет все эти случаи одним фикстуром. **Доказано**: pytest прогнан, мутация
красит.

**AC2 — upload recovery.** `http_api.py`: recovery-ветка (`if blob.exists(): ...`)
идёт строго ДО вызова `physical_asset_usage()`/проверки квоты — repair не требует
свободного слота, как того требует контракт. `existing = read_asset(...)` (valid
sidecar + verified blob) возвращает `reused:true` без изменений; orphan (blob без
принимаемого catalog row) хешируется, атомарно создаёт sidecar через
`tempfile.mkstemp` + `os.replace`, возвращает `reused:false`; digest mismatch
кидает `invalid_image` до любой записи. Тест `test_decor_asset_upload_deduplicates_and_rejects_mime_spoofing`
покрывает repair-при-полной-квоте (`monkeypatch MAX_DECOR_ASSETS_COUNT=1`) и
digest-mismatch (проверяет, что повреждённый blob и отсутствие sidecar
остаются нетронутыми, `rejected.status==507`). **Проверено чтением, не
исполнением** (харнесс недоступен); тест и код логически согласованы построчно.

**AC3 — explicit delete.** `websocket_api.py::ws_assets_delete._delete()`
перебирает `ASSET_EXTENSIONS` по точному `<aid><ext>`, плюс sidecar; `in_use`
проверяется ДО вызова `_delete()` под `write_lock+upload_lock`, так что ничего
не удаляется при отказе. Новый тест `test_decor_asset_delete_removes_exact_orphans_only`
кладёт orphan `.png`+`.svg`+битый `.json`, соседний `.gif` (неизвестное
расширение), `aid+"0".png` (prefix) и директорию `aid.webp` — все три «не
трогать» кейса проверяются явно. **Проверено чтением, не исполнением** (харнесс
недоступен); код и тест согласованы построчно, включая заявленный `removed`.

**AC4 — regression sidecar-без-blob.** Продуктовый код не менялся (защита
`blob.is_file()` уже была в `_read_catalog_row` на `dev`) — задача добавляла
только пропущенный отрицательный тест, ровно как описано в причине #4. **Доказано**:
pytest прогнан, мутация (удаление `or not blob.is_file()`) красит новый тест.

**AC5 — capability guard.** `config-store.ts`: `decorAssetsApi` — только точное
`=== 1`, localStorage-seed всегда `null`; unit-тесты `config-store.test.mjs`
проверяют апгрейд/даунгрейд/`localStorage`. `space-card.ts`: resolve вызывается
только при `snap.decorAssetsApi === DECOR_ASSETS_API_VERSION`; при отсутствии —
`_decorAssets` безусловно очищается, resolve не вызывается — подтверждено живым
смоком (`oldBackendSkippedResolve`, `downgradeRevokesWithoutResolve`). **Доказано**
смоком + unit.

Отдельно проверил утверждение «принимает capability-only изменение snapshot
даже при неизменных config/layout/vLights fingerprints»
(`decorAssetsCapabilityChanged` в OR-условии замены `this._snap`, space-card.ts:732)
— см. находку Low-1 ниже: код корректен, но заявленный сценарий не
верифицирован тем инструментом, который на него ссылается.

**AC6 — resolve cache.** `resolveDecorAssets()`: `key = JSON.stringify([configEpoch, unique])`,
кэш пишется только после успешного цикла (до `resolveCache.set` включая throw —
исключение прерывает функцию раньше). Три новых/изменённых unit-теста
(`decor-assets.test.mjs`) прогнаны в `npm test`, логика проверена чтением —
мутация «убрать epoch из key» ловится тестом «resolve cache is scoped by
authoritative config epoch» (прочитан, не мутировал вручную — тривиально
следует из кода). **Доказано** unit-тестами.

**AC7 — danger confirmation.** `_dangerConfirmLocaleGate` стал геттером
(никогда не кэшируется), `_confirmDanger` проверяет его на каждый вызов;
`willUpdate` отменяет открытый confirm при переходе в `warm` СИНХРОННО до
`render()`; `render()`/`_renderRoot()` используют один и тот же call site
шаблона, чтобы вложенный `noChange` для тела уживался с независимым удалением
`hp-confirm`. Смок прогнан живьём (зелёный, 38/38), и я вручную применил и
откатил обе новые мутации реестра — оба раза целевые поля красятся именно так,
как заявлено в `because`. **Доказано** смоком + двумя живыми мутациями.

**AC8 — Area snapshot negative witness.** Продуктовый код не менялся (защита
`snapshotBindings.has(binding)` уже была на `dev`) — только новый unit-тест.
**Доказано**: тест прогнан, мутация красит именно этот тест.

**AC9 — bounded smoke execution.** `validate.yml`: job `smoke` получил
`timeout-minutes: 20`; каждый файл — `timeout --kill-after=10s 180s node "$f"`,
статус 124 печатает отдельную диагностическую строку, `continue` внутри цикла
файлов не встречается — падение одного файла не останавливает шард (существующий
код, не тронут). `smoke_danger_confirm_branches.mjs` обернул оба
German-ожидания (`germanStarted`, `germanCompleted`) в `Promise.race` с 1000 мс.
Новый `test/smoke-exception-guard.test.mjs` проверяет все три границы текстовым
соответствием YAML — прогнан, зелёный. Живой смок подтверждает, что German-путь
укладывается в границы (никакого зависания на реальном прогоне). **Доказано**
текстовым контрактным тестом + живым прогоном смока; сам workflow на GitHub
Actions не выполнялся (не гейт ревью, а CI-инфраструктура).

**AC10 — support token cleanup.** `_buildSupportPreview()`: `issuedToken`
фиксируется сразу после парсинга ответа (валидация формы `^[0-9a-f]{48}$`), ДО
общей проверки hash/format/version/size/spaces/expires/text, которая кидает
`support_rejected`; `catch`-блок discard'ит `issuedToken`, если он не был
обнулён успешным путём. Malformed/отсутствующий токен никогда не попадает в
`issuedToken`. Живой смок зелёный (29/29), живая мутация (снятие discard в
catch) красит ровно `invalidPreviewTokenIsDiscardedExactlyOnce`. **Доказано**
смоком + живой мутацией.

**AC11 — совместимость/документация.** Grep диффа не находит изменений схемы,
версии API (`DECOR_ASSETS_API_VERSION` остался `1`), i18n-ключей или визуальных
шаблонов вне `_renderRoot`/`_renderDangerConfirm` (сам рендер тех же узлов, что и
раньше, просто перегруппированный). `docs/ARCHITECTURE.md`, `CONFIG-COMPATIBILITY.md`,
`SUPPORT-PRIVACY.md`, `TESTING.md`, оба `CHANGELOG*` изменены в одном коммите
`cba13621` с трейлерами `Issue: #434` / `User-Visible: yes`. **Проверено
чтением**: diff review + `check-docs` зелёный.

**AC12 — гейты.** Typecheck/unit/build/bundle-sync/no-new-any/check-docs —
зелёные (таблица выше). Backend pure — зелёный. Backend HA — не прогонял
(ограничение среды, см. выше, отражено честно). Отобранные смоки — зелёные.
Мутационные свидетели — 6/9 новых прогнаны живьём и красят корректно, 3/9
(HA-зависимые) проверены `--check` + чтением. Golden/full performance —
предрелизные, не гейт ревью (спека сама это утверждает).

## Находки

### Low-1 — `decorAssetsCapabilityChanged` в `space-card.ts:711-732` не влияет на
наблюдаемое поведение и не верифицируется смоком, на который ссылается спека

`this._snap.decorAssetsApi` пишется в двух местах (`space-card.ts:733` и `:736-737`
через частичное обновление) и читается **только** в вычислении самого
`decorAssetsCapabilityChanged` (`:711-712`) — больше нигде в проекте
(`grep -n "decorAssetsApi" src/*.ts` даёт ровно 6 строк, все либо запись, либо
сравнение с только что полученным `snap`, а не с `this._snap`). Реальная
семантика AC5 — вызов/невызов `resolve` и очистка `_decorAssets` — читает
**свежий** `snap.decorAssetsApi` напрямую (`:713`, `:740`), а не `this._snap`.
Поэтому замена `this._snap` целиком против частичного обновления `rev`/`layoutRev`
не производит никакой разницы, которую можно было бы пронаблюдать.

**Как проверил.** Убрал `|| decorAssetsCapabilityChanged` из условия на
`:732`, пересобрал бандл, прогнал `smoke_space_card_decor_capability.mjs`
(остался зелёным, 4/4) и отдельным зондом (`page.evaluate`, три `_load()`
подряд: null→1→null) убедился, что `_snap.decorAssetsApi` меняется
`null → 1 → null` **даже без строки** — потому что `virtualLightsChanged`
в этой фикстуре (и, по прослеживанию кода, в любом реальном сценарии, где
`fetchFresh()` вообще выполняется — `cache` в `config-store.ts` всегда `null`
на входе в `fetchFresh`, значит `virtualLightSnapshot()` каждый раз строит
новый объект) уже безусловно `true` ровно тогда, когда снимок вообще меняется.

`test/space-card-audit-lows.test.mjs` проверяет присутствие строки
`decorAssetsCapabilityChanged` в исходнике текстовым `assert.match` — это ловит
буквальное удаление термина, но не поведенческую регрессию, и не то же самое,
что «тест умеет падать» в смысле PROCESS §2.7 (сам мутационный реестр не
содержит записи для этой строки).

**Не блокирует.** Строка не создаёт неверного поведения (она безвредно
избыточна), реальный контракт AC5 (запрет resolve на старом backend, очистка
map при даунгрейде, кэш по epoch) доказан отдельно и надёжно. Снимаю как Low с
запиской: если авторы захотят вычистить, это чистое упрощение (убрать термин
из OR и из текстового теста, ничего не потеряв); можно и оставить как
задел на случай, если `_snap.decorAssetsApi` найдёт читателя в будущем.

### Low-2 — `_dangerConfirmLocaleGate` геттер может вызвать `languageRenderGate()`
дважды за один цикл обновления, пока открыт danger confirm

`languageRenderGate()` (`src/i18n/language-runtime.ts:105`) не чистая функция:
мутирует `pendingHosts`/`committedHosts`, дёргает `host.setAttribute`, и — что
существеннее — при `state === 'pending'` безусловно подписывает новый
`.then()` на `runtime.ensure(code)` при **каждом** вызове, не только при первом
вхождении в pending. `willUpdate()` (`houseplan-card.ts:4192-4194`) читает
геттер, когда `this._dangerConfirm` истинен, и `_renderBody()` (`:11239`) читает
его снова безусловно — при открытом danger confirm это два вызова за один
рендер-цикл вместо одного до этой правки (когда значение кэшировалось полем).

**Не блокирует.** Оба вызова происходят синхронно в одном тике (между
`willUpdate` и `render()` нет await), поэтому `runtime.state(code)` не может
измениться между ними — итоговое значение геттера согласовано на всём проходе.
Лишняя подписка `.then()` на уже существующий (мемоизированный) промис
`runtime.ensure()` добавляет не более одного лишнего `requestUpdate()` при
разрешении — Lit схлопывает такие вызовы. Открытый danger confirm — не самое
частое состояние карточки. Снимаю как Low без правки.

## Унаследовано / повторная проверка

Не применимо — это первый заход код-ревью (r1) по этому issue; разделы
«Закрытие r(N-1)» и «Унаследовано из r(N-1)» не ведутся согласно PROCESS §2.10.
(Два документа `SPEC-REVIEW-434-r1.md`/`-r2.md` в диффе относятся к
предыдущему этапу — ревью ТЗ, а не коду; их вердикт не переоткрывал.)

## Чего не проверял и почему

- **`tests_backend/test_ha_websocket.py` (полный HA-харнесс)** — среда ревью
  Python 3.12, пин `pytest-homeassistant-custom-component==0.13.357` требует
  ≥3.14, `.venv-backend` недоступен. AC2/AC3 доказаны чтением построчного
  соответствия теста и кода (см. разбор выше), не исполнением.
- **Полный `npm run golden:verify`** — спека прямо утверждает «Golden не
  требуется» (нулевая визуальная дельта в устойчивых состояниях); чтением
  подтвердил, что изменённые рендер-точки (`_renderRoot`) рисуют тот же набор
  DOM-узлов, что и раньше, в другой обёртке.
- **`npm run golden:capture`/`performance_smoke`/полный набор `demo/smoke_*.mjs` (216 файлов)**
  — предрелизный гейт (PROCESS §8), непропорционален объёму этой задачи; выбрал
  3 смока, прямо названных в AC и физически изменённых в диффе.
- **Полный `node scripts/mutation-gate.mjs`(без `--changed`) — 380 мутантов** —
  предрелизный гейт по определению самого скрипта («прогон дорогой... его
  место — перед стабильным релизом»); ограничился `--changed --check` (все 109
  затронутых патчей применимы) плюс живым прогоном 6 из 9 новых/изменённых
  записей, относящихся именно к этой задаче.
- **`node scripts/model-invariants.mjs`** — diff не касается геометрии
  (rooms/walls/layout/marker.space/open_spans), гейт неприменим.
- **French locale smoke (`smoke_french_locale.mjs`)** — «зарегистрированная
  связь» через `languageRenderGate`, но сценарий (network/lazy German chunk)
  не задет этой задачей; решил не гонять.
- **35 «слабых» совпадений smoke-select** — общие символы (`_cfgRev`, `_config`
  и т.п.), не специфичные для этой правки; не гонял, полагаясь на unit/typecheck
  как более узкое доказательство отсутствия регрессии в этих поверхностях.

## Итог

High: 0. Medium: 0. Low: 2, обе сняты с запиской (см. выше), правки не требуют.
Все 12 AC доказаны — либо зелёным тестом/смоком с подтверждённой (в 8 из 10
защитных случаев — лично прогнанной) способностью падать, либо честной пометкой
«проверено чтением, не исполнением» там, где харнесс недоступен в среде ревью.
Документация, changelog и трейлеры в порядке. Вердикт: **зелёный**.

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

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

- Ветка: `issue/434-v171-polish-audit`, коммит `a71531ba30d2` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `840317519dfa1ae59a2ecf7317ce53bd819c4504`
  ```
  git log --all --format='%H %T' | grep 840317519dfa
  ```
- ТЗ `docs/specs/434-v171-polish-audit.md`, блоб `e235fcef2bcd817c39c0c5a9134fd2ec8f6eb2f1`
  ```
  git log --all --find-object=e235fcef2bcd817c39c0c5a9134fd2ec8f6eb2f1 -- docs/specs/434-v171-polish-audit.md
  ```