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

# CODE-REVIEW-184-r1 — fail-closed guard в `_savePos()` против stale space id

- **Issue:** https://github.com/Matysh/houseplan-card/issues/184
- **Трек:** `trivial` — AC зафиксированы в теле issue (аналитика владельца 2026-08-19), спек-файла
  нет и не требуется.
- **Диапазон:** `origin/dev..HEAD` = один коммит `fa01590` («fix: reject stale space position
  writes»)
- **Цикл:** r1/4
- **Роль:** ревьюер кода (Claude), свежая сессия, без контекста реализации Codex

## 1. Скоуп

Единственный коммит, класс A+B+D:

- `src/houseplan-card.ts` — в `_savePos(d, x, y)` добавлена одна строка
  `if (!this._spaceModelById(d.space)) return;` перед веткой `_norm`/legacy и перед мутацией
  `this._layout`, `this._dirtyPos.add`, `this._persistLayout()`;
- `scripts/mutation-gate.mjs` — новый мутант `stale-space-position-guard-removed`, удаляющий
  именно эту строку и требующий покраснения нового под-теста;
- `test/optional-space-model-contract.test.mjs` — существующий тест `stable space ids use exact
  lookup and abort before side effects` расширен проверкой порядка подстрок внутри тела
  `_savePos`: `_spaceModelById(d.space)` встречается раньше `this._layout =`, `_dirtyPos.add`,
  `_persistLayout()`;
- `docs/TESTING.md` — формулировка чек-листа расширена с «marker persistence validates its
  target» до «marker/position persistence validates its target»;
- `docs/images/screenshots.json` + `docs/images/06-device-editor.png` — механическая
  ре-фиксация `sourceFingerprint`/`sourceSha256` (привязан к хешу `src/`, любой коммит класса A
  его двигает) и одного PNG;
- три копии бандла (`dist/`, `custom_components/houseplan/frontend/`, `demo/srv/assets/`).

Это ровно короткий трек AC1–AC3 из тела issue: fail-closed guard на единственной оставшейся
persist-границе (`_savePos`), которую #113 не закрыл (закрыл `_livePos`, `_vacPlanRoomAnchors`,
`_vacStartFit`, `_labelMove`, `_rlResizeMove`, `_saveMarker`, но не сам `_savePos`). Соответствует
J6 SCOPE.md («Keep the plan true as the home evolves» — drag/resize, optimistic locking, multi-client
sync): фикс закрывает latent-баг, при котором pointer-событие от устаревшего `DevItem` (после
удаления/переименования одного из нескольких этажей у другого клиента) могло записать позицию в
уже неактуальное пространство.

`User-Visible: no` — корректно: путь достижим только при гонке (WS-удаление/переименование
пространства между рендером и отпусканием указателя), не при обычном взаимодействии; changelog не
трогается, и это правильно.

## 2. Как проверялось — таблица гейтов

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | OK, без ошибок |
| Unit | `npm test` | `887/887`, совпадает с заявленным в хендоффе |
| Build + 3 копии бандла | `npm run build`, затем `sha256sum dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js demo/srv/assets/houseplan-card.js` | OK, все три `2e0d3a41…` — байт-в-байт совпадение |
| Мутационный чек якорей | `node scripts/mutation-gate.mjs --check` | `ok stale-space-position-guard-removed` + все прежние якоря живы |
| Мутационный guard AC1 | `node scripts/mutation-gate.mjs --id=stale-space-position-guard-removed` | `поймано 1 из 1` — чистый прогон зелёный, мутант (удалённая строка guard) красит именно новый под-тест, т.е. тест **умеет падать** |
| Именованный smoke (AC2) | `node demo/smoke_grid_snap.mjs` | OK, все 13 подпроверок `true` |
| Именованный smoke (AC2) | `node demo/smoke_drag_bounds.mjs` | OK, все 12 подпроверок `true` |
| Регрессия соседней поверхности (empty-space lifecycle, которую #113 уже покрывал и которую этот диф касается по TESTING.md) | `node demo/smoke_optional_space_model.mjs` | OK, все 9 подпроверок `true` |
| Docs/screenshot fingerprint | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links)` |
| Process gate | `node scripts/process-gate.mjs --issues` | `гейт пройден, предупреждений 0` |
| Единственный изменённый PNG — реальная разница | `PIL.ImageChops.difference` между `origin/dev` и `HEAD` версиями `docs/images/06-device-editor.png` | bbox `(1141,18)-(1142,19)` — 1 пиксель, канал G отличается на 1 (17 vs 18) — антиалиасинг-шум перезахвата, не смысловое изменение |

**Не прогонялось, и почему:**

- **Полный набор из 127 браузерных смоков** — diff меняет одну функцию (`_savePos`), которая
  вызывается из двух мест (`_pointerMove` — drag устройства, `_labelMove` — drag подписи
  комнаты); оба покрыты названными в AC2 смоками плюс `smoke_optional_space_model` (соседняя
  space-lifecycle поверхность, которую и трогает TESTING.md-правка). Остальные ~124 смока не
  затрагивают ни `_savePos`, ни space-selection — не прогонялись, сознательное решение
  (PROCESS §8), не молчаливый пропуск.
- **`npm run golden:verify`** — не прогонялся. Guard добавлен *перед* существующей логикой и
  срабатывает только когда `_spaceModelById(d.space)` возвращает `undefined`, то есть когда
  `d.space` не входит в текущую `_model` — при исправной модели (любой обычный рендер, любой из
  golden-сценариев) это невозможно: `d.space` для реальных устройств строится в момент сборки
  `DevItem[]` через `resolveDeviceSpace`/аналог с фоллбэком на `firstSpaceId` (см. `src/devices.ts:999-1012`),
  так что для непустой модели `d.space` всегда указывает на существующее пространство (проверено
  чтением). Видимый пиксельный результат обычного drag/label-move не меняется — подтверждено
  дополнительно исполнением `smoke_grid_snap`/`smoke_drag_bounds` (AC2), которые как раз проверяют
  геометрию после сохранения позиции.
- **`python -m pytest tests_backend`** — не тронут ни один файл `custom_components/**/*.py`.
- **Performance-профили** — не названы в AC; изменение — одна O(1)-проверка (`Array.find` по
  обычно короткому списку пространств) в начале уже существующего обработчика, не hot render
  path. Не прогонялись.

## 3. Проверка AC (тело issue #184, короткий трек)

| AC | Доказательство | Статус |
|---|---|---|
| AC1 — stale write является no-op: `_savePos()` при отсутствующем `d.space` не меняет `_layout`/`_dirtyPos` и не вызывает persist | `test/optional-space-model-contract.test.mjs` — расширенный под-тест проверяет позиционный порядок подстрок в теле `_savePos`: `_spaceModelById(d.space)` строго раньше `this._layout =`, `_dirtyPos.add`, `_persistLayout()`; **подтверждено исполнением**, что тест умеет падать — `node scripts/mutation-gate.mjs --id=stale-space-position-guard-removed` → `поймано 1 из 1` (мутант убирает ровно guard-строку) | доказано unit + mutation-тестом (исполнение) |
| AC2 — valid movement сохраняется: для существующего space координаты/grid/clamp/scale работают как раньше для устройства и room label | `node demo/smoke_grid_snap.mjs` (13/13 true, включая grid snap на устройстве и подписи) и `node demo/smoke_drag_bounds.mjs` (12/12 true, включая `markerSurvivesRebuild`/`labelSurvivesRebuild`) — оба лично перезапущены на пересобранном бандле, зелёные | доказано browser smoke (исполнение) |
| AC3 — selector discipline остаётся структурной: `_spaceModel()` без id; известные call sites на `_spaceModelById()`; source-contract включает `_savePos` в перечень | тот же расширенный под-тест плюс ранее существовавшие проверки в файле (`_livePos`, `_vacPlanRoomAnchors`, `_vacStartFit`, `_labelMove`, `_rlResizeMove`, `_saveMarker`) — не тронуты этим диффом, но перепрогнаны вместе (`npm test` зелёный целиком) | доказано unit-тестом (исполнение) |

## 4. Дисциплина «тест умеет падать» — что лично проверено исполнением

- `node scripts/mutation-gate.mjs --id=stale-space-position-guard-removed` реально применяет
  патч (`if (!this._spaceModelById(d.space)) return;\n    if (this._norm) {` →
  `if (this._norm) {`), пересобирает тестовый TS и гоняет ровно
  `--test-name-pattern="stable space ids"` — вывод: `stale-space-position-guard-removed: тест
  покраснел, как обязан`. Не «предположительно ловит» — подтверждённая красная реакция на живом
  прогоне.
- `node scripts/mutation-gate.mjs --check` подтверждает, что якорь патча (`find`) встречается в
  `src/houseplan-card.ts` ровно один раз — патч ложится туда, куда должен, а не куда попало.

## 5. Находки

Нет находок High. Нет находок Medium.

**Low-1** (не блокирует, снимается с записью). Правило §4 `docs/TESTING.md` («тест, охраняющий
механизм, сопровождается мутантом») реализовано технически (мутант `stale-space-position-guard-removed`
добавлен и работает), но чек-лист-пункт «Empty-space lifecycle (#113)» на строке 40-43, который
этот коммит редактирует (расширяет формулировку с «marker persistence» до «marker/position
persistence»), продолжает ссылаться только на `[unit: optional-space-model-contract.test.mjs]` и не
называет новый мутационный id — в отличие от соседнего пункта строкой ниже
(`[mutation: empty-space-cleanup-disabled]`), который следует этому же паттерну документирования
пофайлово. Косметическое расхождение с собственным соглашением документа, не влияет на
работоспособность гейта (`mutation-gate.mjs --check` его всё равно видит и исполняет). Не требует
отдельного issue — можно поправить одной строкой в следующем touch этого файла или прямо сейчас
автором до мержа, на усмотрение.

## 6. Что проверено и корректно

- Guard стоит **до** обеих веток (`_norm` normalized и legacy `else`), то есть закрывает и
  grid-snapped, и pixel-legacy путь одинаково — проверено чтением diff, строка вставлена перед
  `if (this._norm) {`.
- Оба call site `_savePos` учтены: `_pointerMove` (line ~5609, drag устройства) не имел
  предварительной проверки `d.space` — реальная дыра, которую и закрывает issue; `_labelMove`
  (line ~16951-16964) уже содержит собственный `_spaceModelById(spaceId)` guard с `return` до
  вызова `_savePos` — новый guard там избыточен, но безвреден (defense in depth, как и заявлено
  автором в хендоффе).
- `d.space` — обязательное поле `DevItem.space: string` (не optional), и для реальных устройств
  строится с фоллбэком на `firstSpaceId` в момент сборки списка устройств
  (`src/devices.ts:999-1012`) — то есть при непустой модели и без гонки `d.space` всегда валиден;
  guard не может сработать на обычном путём и не ломает штатный drag (подтверждено smoke AC2).
- `docs/images/screenshots.json`: `sourceFingerprint`/`sourceSha256` пересчитаны для всех 10
  сценариев (ожидаемо — привязаны к хешу всего `src/`, а не к конкретной функции), обновлён
  ровно один `imageSha256` (`device-editor`). Разница в самом PNG — 1×1 пиксель, отличие в 1
  единицу канала G (17 против 18) — проверено попиксельно через `PIL.ImageChops.difference`,
  визуального регресса нет, это шум перезахвата, не следствие правки поведения.
- Коммит `fa01590` несёт `Issue: #184` и `User-Visible: no`; изменений в `docs/CHANGELOG*.md` нет
  и не требуется — путь недостижим при обычном взаимодействии.
- `node scripts/process-gate.mjs --issues` зелёный на этом диапазоне.

## 7. Чего не проверял

- Полный набор из 127 браузерных смоков и `golden:verify` — обоснование сужения в §2 (diff
  затрагивает ровно один метод с двумя call sites, оба покрыты названными в AC смоками).
- `pytest tests_backend` — класс A/B бэкенда не тронут.
- Performance-профили — не названы в AC, hot-path не тронут (обоснование в §2).
- Не воспроизводил вручную саму гонку (WS-удаление пространства во время активного pointer-drag
  другого устройства) в браузере/Playwright — только чтением кода и порядком инструкций в
  source-contract; ручного тестирования в цикле ревью нет по процессу, а сценарий требует
  многоклиентской постановки вне текущего smoke-набора. Логический разбор (см. §6) и
  доказательство «guard строго до side effects» через unit+mutation считаю достаточным для
  latent-race фикса такого размера.

## 8. Вердикт

AC1–AC3 доказаны: AC1 и AC3 — unit/mutation-тестом с подтверждённой способностью падать
(исполнение), AC2 — двумя названными в AC браузерными смоками (исполнение). Гейты typecheck/test/
build/bundle-sync зелёные, process-gate зелёный, docs-fingerprint зелёный. High: 0. Medium: 0.
Одно Low-наблюдение (несогласованность чек-листа `TESTING.md` со своим же соглашением
`[mutation: …]`) снимается с запиской, без нового issue.

**Вердикт: зелёный · цикл r1/4 · High: 0 · Medium: 0 → нет · Документ: docs/reviews/CODE-REVIEW-184-r1.md**