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

# CODE-REVIEW-397-r1

- Issue: #397 — «Undo позиций #74: своё же эхо сбрасывает историю, а
  доказывающий это смок подстроен»
- ТЗ: `docs/specs/397-device-position-echo.md` (ревизия 2, принята жёлтым →
  зелёным в SPEC-REVIEW-397-r1/r2)
- Этап: code, заход r1, блокирующих циклов израсходовано 0 из 4
- Диапазон: `git diff origin/dev...HEAD` (HEAD `08d56122`), реализация в
  коммите `d87cc298` («fix: the card keeps the position it sent, so its echo
  is not foreign (#397)»), артефакты — в `08d56122`

## Скоуп проверки

Диф вне docs/reviews и бандлов:

- `src/houseplan-card.ts` — 5 строк, `_persistDevicePlacement`
- `demo/smoke_device_position_history.mjs` — правка фикстуры (M1) + новые
  проверки AC2/AC5б/AC6/AC7
- `test/device-position-echo.test.mjs` — новый юнит (3 теста)
- `scripts/mutation-gate.mjs` — новый мутант `device-echo-keeps-local-noncanonical`
- `docs/CHANGELOG.md` / `docs/CHANGELOG.ru.md` — пункт User-Visible
- `dist/**`, `custom_components/houseplan/frontend/**`, `docs/images/**` —
  артефакты сборки/скриншотов, сверены с исходником (см. «Как проверялось»)

Продуктовый код в узком скоупе ТЗ: только `_persistDevicePlacement`. Геометрия,
рёбра комнат, `layout`/`marker.space`/`open_spans` не затронуты — гейт
инвариантов (`npm run invariants`) не применим.

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

Зелёного Validate на `08d56122` не было — все гейты прогнаны локально.

1. **Чтение диффа.** `git diff origin/dev...HEAD -- src/houseplan-card.ts`
   построчно сверен с описанием B3 в ТЗ и с текстом коммита. Прочитаны
   контекст `_persistDevicePlacement` (:5224–5261), `applyDevicePlacement`
   (`src/device-position-history.ts:45-67`), `_reloadLayoutOnly`
   (:4904–4948), `_adoptStructuralResponses` (:4203–4269), `_loadFromServer`
   (:4280–…) — чтобы понять, какой путь реально вызывается при reconnect.
2. **Дешёвые гейты** (все на `08d56122`, после `npm run bundle:sync`, чтобы
   поднять `demo/srv/assets`, — без него браузерные смоки не грузят карточку
   вообще, что не связано с задачей, а с локальным окружением):
   - `npx tsc --noEmit` — чисто.
   - `npm test` — **1657 pass / 0 fail / 1 skip** (совпадает с заявлением
     автора).
   - `npm run build` — зелёный; `git status` после сборки чист → три копии
     бандла (`dist/`, `custom_components/houseplan/frontend/`, плюс
     git-игнорируемый `demo/srv/assets`, пересобранный отдельно) совпадают с
     закоммиченными.
   - `node scripts/check-docs.mjs` — «Documentation checks passed (7 files,
     10 external links)», включая отпечаток скриншотов (diff трогает
     `src/**`, значит гейт обязателен) — прошёл, скриншоты
     (`docs/images/01-view-desktop.png`, `09-device-info.png`) и
     `docs/images/screenshots.json` в коммите `08d56122` актуальны.
   - `node scripts/mutation-gate.mjs --check` — все патчи реестра, включая
     новый `device-echo-keeps-local-noncanonical`, ложатся на текущий код
     (`ok device-echo-keeps-local-noncanonical`).
   - `node --test test/mutation-gate.test.mjs` — 10/10, реестр не разошёлся
     с кодом.
3. **`node scripts/smoke-select.mjs --base origin/dev --head HEAD`** —
   результат «НЕОПРЕДЕЛЁННОСТЬ»: единственный изменённый символ `_layout`
   слишком широк (встречается почти везде), `contentFingerprint` не связан ни
   с одним смоком явно. АС задачи прямо называют
   `demo/smoke_device_position_history.mjs` как способ доказательства — этого
   достаточно, полную матрицу (209 файлов) не гонял: диф не расширяет
   поверхность за пределы одного метода и уже названного смока.
4. **`demo/smoke_device_position_history.mjs` — прогнан явно** (`node
   demo/smoke_device_position_history.mjs`, после `npm run bundle:sync`):
   все 31 проверка зелёные, включая новые `localCopyEqualsTheWire`,
   `ownEchoMatchesWhatWentOverTheWire`, `deleteEchoKeepsHistory`,
   `inFlightPositionWinsTheMerge`.
5. **Дисциплина «тест умеет падать» — проверена вручную**, а не принята на
   слово. В `_persistDevicePlacement` временно заменил
   ```
   const pos = canonicalizePosition(this._layout[deviceId]);
   if (contentFingerprint(pos) !== contentFingerprint(this._layout[deviceId])) {
     this._layout = { ...this._layout, [deviceId]: pos };
   }
   ```
   на `const pos = canonicalizePosition(...); void pos;` (то же преобразование,
   что делает мутант `device-echo-keeps-local-noncanonical`), пересобрал
   (`npm run bundle:sync`) и перезапустил смок. Результат:
   ```
   FAILED (3):
     - localCopyEqualsTheWire: expected true, got false
     - sameContentReloadKeepsHistory: expected true, got false
     - ownEchoMatchesWhatWentOverTheWire: expected true, got false
   ```
   Это ровно то расхождение, которое ТЗ требует для AC6, и ровно три проверки,
   которые называет коммит-сообщение автора («three checks red without the
   fix»). После проверки откатил файл (`git diff` снова пуст) и пересобрал,
   чтобы вернуть дерево в исходное состояние.
6. **`node --test test/device-position-echo.test.mjs`** — 3/3 pass отдельно
   от общего прогона, чтобы увидеть их независимо.
7. **Трейлеры и changelog.** `git show d87cc298` содержит `Issue: #397` и
   `User-Visible: yes`; правки обоих `docs/CHANGELOG*.md` лежат в этом же
   коммите (не в отдельном). `git show 08d56122` — `User-Visible: no`,
   корректно для чисто артефактного коммита.

## Разбор по AC

- **AC1** (после `_persistDevicePlacement` `_layout[deviceId]` побайтово
  раве отправленному, отпечаток по нему). Доказано двояко: поведенчески —
  смок `localCopyEqualsTheWire` (зелёный, покраснел при отмене фикса);
  структурно — `test/device-position-echo.test.mjs` (`AC1: the update branch
  stores what it sends, before sending it`) проверяет порядок операторов в
  исходнике. ТЗ просило «юнит с перехватом callWS» — по факту это не
  Node-юнит с мокнутым `hass.callWS`, а (а) браузерный смок с фейковым WS и
  (б) текстовый юнит по исходнику. Проверил, что это не слабее: смок реально
  перехватывает `message.pos` на проводе и сравнивает с `_layout`, то есть
  доказывает AC1 не хуже мокнутого юнита. Отклонение от буквы метода
  доказательства — Low, не блокирует.
- **AC2** (честный reload не чистит историю) — `sameContentReloadKeepsHistory`
  + новый `ownEchoMatchesWhatWentOverTheWire` (пин того, что стороны реально
  совпали — без этого проверка AC2 могла бы быть тавтологией). Зелёные,
  красные при отмене фикса. Выполнено.
- **AC3** (тот же инвариант для `_adoptStructuralResponses`, reconnect-путь,
  пункт 5 плана автотестов) — **не выполнено**. См. находку Medium-1 ниже.
- **AC4** (чужое изменение чистит историю) — `remoteContentClearsHistory`,
  код и фикстура не менялись в этой части, поведение унаследовано и
  подтверждено прогоном (зелёное).
- **AC5а** (удаление: ключ удалён локально до отпечатка) — юнит
  `AC5a: the delete branch removes the key before the fingerprint`, плюс
  чтением подтверждено: `applyDevicePlacement(layout, id, null)` удаляет ключ
  (`src/device-position-history.ts:50-54`), вызывается безусловно в начале
  `_persistDevicePlacement` (:5230) до отправки и до фиксации отпечатка.
  Выполнено.
- **AC5б** (эхо удаления не чистит историю) — `deleteEchoKeepsHistory`,
  зелёный. Отдельно проверено, что `echoProbe` в текущей демо-фикстуре
  разрешается (не `null`) — прогон подтвердил `true`, ветка реально
  исполняется, а не проваливается в `else`-заглушку. Выполнено.
- **AC6** (смок краснеет на коде до фикса) — доказано вручную (раздел «Как
  проверялось», п.5): 3 проверки красные без фикса, все остальные 28 —
  зелёные (значит, откат не сломал ничего постороннего, поломка точечная).
  Выполнено.
- **AC7** (запись в полёте побеждает ответ сервера) — `inFlightPositionWinsTheMerge`,
  зелёный; прочитан код `_reloadLayoutOnly` (:4912-4926) — `_sentPos`
  накладывается на `remote` после `mine`, порядок не менялся этим диффом.
  Выполнено.

## Находки

### Medium-1 (в скоупе, чинится в этом же раунде). AC3 не имеет ни одного
теста — `_adoptStructuralResponses` не упомянут ни в одном изменённом файле

ТЗ (`docs/specs/397-device-position-echo.md:114-117`) требует отдельного
доказательства для `_adoptStructuralResponses` («полная перезагрузка конфига
и layout, reconnect-путь») именно потому, что сам документ называет его
**вторым независимым путём**, читающим то же расхождение (раздел «(1) B3»,
строки 41-49): "Дальше расхождение читают два независимых пути:
`_reloadLayoutOnly`… `_adoptStructuralResponses`…". План автотестов, пункт 5,
прямо предписывает: «Перемещение → полный `_adoptStructuralResponses`
(reconnect) → `canUndo === true` (AC3)».

Ни `demo/smoke_device_position_history.mjs`, ни новый
`test/device-position-echo.test.mjs`, ни любой другой файл в диффе не
упоминают `_adoptStructuralResponses` или `_loadFromServer` (проверено:
`git diff origin/dev...HEAD | grep -i adoptStructural` — пусто). Все новые
проверки (`sameContentReloadKeepsHistory`, `ownEchoMatchesWhatWentOverTheWire`,
`deleteEchoKeepsHistory`, `inFlightPositionWinsTheMerge`) идут через
`_reloadLayoutOnly` — это первый путь, не второй.

**Воспроизведение**: `grep -n "_adoptStructuralResponses" demo/*.mjs
test/*.mjs` внутри изменённых файлов не находит совпадений; в
`docs/specs/397-device-position-echo.md:154` пункт 5 плана заявлен, но не
реализован.

**Разобрано по коду (проверено чтением, не исполнением) — риска регрессии в
проде я не вижу**: `_adoptStructuralResponses` (:4245-4258) сравнивает
`contentFingerprint(nextLayout)` с `(this._layoutContentFingerprint ||
contentFingerprint(this._layout))` — тем же `_layoutContentFingerprint` и тем
же `_layout`, которые фикс в `_persistDevicePlacement` теперь синхронизирует
с отправленным на сервер значением. Других мест, где этот путь читал бы
неканонический слепок, нет. То есть B3 закрыт для обоих потребителей одним и
тем же присваиванием — функционального дефекта, скорее всего, не осталось.

Но это не заменяет обязательство: ТЗ приняло AC3 с явным способом
доказательства, автор его не выполнил и не заявил как исключение. «Верно по
рассуждению ревьюера» — это ровно то временное доверие, из-за которого
заводился прецедент #102 (правка по одному замечанию тихо ломает
непроверяемый соседний путь) — только с обратным знаком: здесь никто и не
проверял. Нужно: добавить в `demo/smoke_device_position_history.mjs`
сценарий пункта 5 (переместить маркер → вызвать полный путь конфиг+layout,
которым реально идёт `_loadFromServer`/reconnect, с честным серверным
слепком → `canUndo === true`) либо явно проговорить в ТЗ/PR, почему этот
путь достаточно покрыт первым, и получить это как решение ревью, а не как
факт по умолчанию.

### Low-1. AC1 доказан не тем способом, что назвало ТЗ

ТЗ: «Доказательство: юнит с перехватом `callWS`». Реализация: браузерный смок
(перехват фейкового WS в `demo/`) + текстовый юнит по исходнику в `test/`. По
существу доказательство не слабее (см. разбор AC1 выше), но название файла в
плане (`test/device-position-persist.test.mjs`) и метод («юнит с перехватом
callWS») разошлись с тем, что реализовано (`test/device-position-echo.test.mjs`,
текстовый разбор + смок). Не блокирует, автор может закрыть комментарием
одной строкой, если согласен, что смок сильнее.

### Low-2. Юнит-план, пункт 3 («каноническая позиция не создаёт лишней
записи»), не имеет отдельного теста

Раздел «Риски» ТЗ (`docs/specs/397-device-position-echo.md:169-172`) просил
юнит на то, что уже каноническая позиция не вызывает лишнего присваивания
`_layout` (мера против лишнего ре-рендера). Гвард в коде
(`if (contentFingerprint(pos) !== contentFingerprint(this._layout[deviceId])) {…}`)
присутствует и корректен — проверено чтением: при равенстве отпечатков блок
не выполняется, второе присваивание `_layout` не происходит. Отдельного теста
на это нет ни в `test/`, ни в смоке. Riск-митигация без теста хуже, чем без
митигации, но здесь код всё же есть и логика прямолинейна (`!==` перед
присваиванием) — не блокирует, оставляю на усмотрение автора.

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

- Порядок операций в `_persistDevicePlacement` соответствует контракту ТЗ:
  локальная запись канонического значения → `_sentPos.set` →
  `hass.callWS(...)` → `_layoutContentFingerprint` по актуальному `_layout`.
  Порядок «локальная запись раньше `_sentPos`» (риск-митигация из ТЗ)
  сохранён — проверено чтением :5241-5253.
- Ветка удаления использует тот же безусловный `applyDevicePlacement` в
  начале функции (:5230), отдельного расхождения между «обновить» и
  «удалить» в части фиксации отпечатка нет.
- M1 закрыт: `serverLayout = structuredClone(c._layout)` перед
  `_reloadLayoutOnly()` убран из смока; сервер теперь только то, что реально
  ушло по фейковому WS. Подтверждено падением 3 проверок при отмене фикса.
- `_sentPos` продолжает побеждать в `_reloadLayoutOnly` (:4918-4926) —
  код этого пути не тронут диффом, AC7 подтверждает поведение, а не чинит
  регрессию.
- CHANGELOG (`docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`) — пункт добавлен в
  том же коммите, что и фикс; трейлеры `Issue: #397` / `User-Visible: yes`
  на месте.
- Бандл-артефакты (`dist/`, `custom_components/houseplan/frontend/`,
  скриншоты) актуальны — подтверждено пересборкой и чистым `git status`.
- Мутант `device-echo-keeps-local-noncanonical` зарегистрирован корректно,
  guard (`node demo/smoke_device_position_history.mjs`) существует и реально
  ловит поломку (проверено вручную, см. «Как проверялось», п.5), реестр не
  разошёлся с кодом (`test/mutation-gate.test.mjs` зелёный).

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

- **`node scripts/mutation-gate.mjs` (полный/по `--id=device-echo-keeps-local-noncanonical`)** —
  не гонял через штатный раннер: он в этой песочнице падает на не связанном
  с задачей препятствии (`python3 -m pytest tests_backend/...` — «No module
  named pytest», модуль не установлен) ещё на этапе чистого прогона,
  до применения самого мутанта. Это гейт предрелизного окна
  (`.github/workflows/mutation-gate.yml`), не гейт ревью, и файл сам себя так
  описывает («прогон дорогой… его место — перед стабильным релизом»).
  Заменил его точечной ручной проверкой (см. п.5 «Как проверялось»),
  которая доказывает то же самое для конкретного мутанта.
- **`python -m pytest tests_backend -q`** — диф не трогает
  `custom_components/**/*.py`, гейт не применим.
- **`npm run invariants`** — диф не трогает геометрию/рёбра/`layout`-ключи
  решётки, гейт не применим.
- **`npm run golden:verify`** — диф не меняет рендер/геометрию/стили/слои,
  только служебное поле `_layout` и порядок присваиваний; визуального следа
  у AC нет.
- **HA-харнесс** — в этой песочнице нет Home Assistant; это предрелизный
  гейт на точном SHA, автор пометил то же самое в своём комментарии.
- **Полная матрица `demo/smoke_*.mjs` (209 файлов)** — не запускал:
  `scripts/smoke-select.mjs` не нашёл сильной связи за пределами уже
  названного в АС смока, а сам диф не расширяет поверхность (один метод,
  один смок, названный ТЗ явно).

## Унаследовано из этапа spec

SPEC-REVIEW-397-r1 (жёлтый, Medium: AC5б/AC7 без способа доказательства) и
SPEC-REVIEW-397-r2 (зелёный) заранее проверили точность самого диагноза (B3,
M1) построчно против кода на SHA `83692e79`/`6edcde01` — до реализации.
Диагноз принят без повторной проверки номеров строк из ТЗ (они успели
сместиться в ходе реализации на единицы строк, что нормально и не меняет
сути); сам код B3/M1 в этом раунде я перечитал заново на HEAD, а не
унаследовал.