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

# CODE-REVIEW-288-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/288
- **Этап:** code (PROCESS.md §2.7)
- **Заход:** r1 · блокирующих циклов израсходовано 0 из 4
- **Ветка:** `issue/288-bounded-multiwall-corridor`
- **SHA на момент ревью:** `4aa79dee6b1e66946c9fb97ee38fc855b0020808`
- **Диапазон:** `origin/dev...HEAD` (2 продуктовых/тестовых коммита: `cb0f9e73`
  спецификация, `fba615e9` доработка ТЗ, `e61315cb`/`3f4b92f5` документы
  ревью ТЗ — фон; код-ревью касается `ff5e393c` fix + `4aa79dee` docs screenshots)

Это первый заход код-ревью для #288 — предыдущие два раунда были ревью ТЗ
(SPEC-REVIEW-288-r1 жёлтый → r2 зелёный). Разбор ниже полный, разделы
«Закрытие r<N-1>»/«Унаследовано из r<N-1>» не нужны (PROCESS.md §2.9 касается
только повторных заходов ОДНОГО и того же этапа).

## Скоуп диффа

`git diff origin/dev...HEAD --stat`: `src/wall-thickness.ts` (+134/-6),
`test/wall-thickness.test.mjs` (+51), `scripts/mutation-gate.mjs` (+14),
`demo/smoke_real_plan_masonry.mjs` (числа `PLANS`/`KNOWN_GAP_*`),
`docs/{WALL-THICKNESS,ARCHITECTURE,TESTING,CHANGELOG,CHANGELOG.ru}.md`,
10 PNG в `docs/images/**` + `screenshots.json`, `dist/houseplan-card.js` и
`custom_components/houseplan/frontend/houseplan-card.js` (сгенерированные,
класс D).

Ядро изменения: в `buildMultiWallNodeMap` каждый `MultiWallNodeRay` получил
поле `continuations` — конечные общие полосы («shared»-стены), примыкающие к
дальнему концу одного из `supports` луча. В `bevelMultiWallBody` эти полосы
восстанавливаются (`multiWallContinuationStripGeometry`) внутри маски узла,
после чего результат `union`-ится вместо старой тройки
`outside/preservedExterior/localInside`.

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

### Прочитанное (владельческий/процессный контекст)

`docs/SCOPE.md` (J1/J6 — план должен правдиво показывать стены), `AGENTS.md`,
`PROCESS.md` §2.7/§4/§7/§8/§12, тело issue #288 и все 5 комментариев (аналитика,
«ТЗ готово», два вердикта ревью ТЗ), `docs/specs/288-bounded-multiwall-corridor.md`
целиком, `docs/WALL-THICKNESS.md`/`docs/ARCHITECTURE.md`/`docs/TESTING.md` (до и
после диффа).

### Гейты — выполнено

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | чисто, без ошибок |
| Unit | `npm test` | `1221 tests, 1220 pass, 1 skipped, 0 fail` |
| Build + bundle parity | `npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | идентичны, `git status` после сборки чист (детерминированный бандл) |
| Docs fingerprint | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links)` |
| Выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 3 «зарегистрированные связи» на `MultiWallNodeRaySupport`: `smoke_junction_patch_resilience`, `smoke_multiwall_junction`, `smoke_multiwall_strip_containment`; порог «широкого» символа (36) не превышен → не считается диффом, задевающим всё |
| Целевой смок AC1/AC2/AC5 | `node demo/smoke_real_plan_masonry.mjs` (после `npm run bundle:sync`) | `second-floor: gapCount 0, totalGapSteps 0` (45757 samples); `first-floor: gapCount 0, totalGapSteps 0` (8048 samples); все 8 проверок `true`, итог `OK` |
| 3 «зарегистрированные связи» | `node demo/smoke_junction_patch_resilience.mjs`, `node demo/smoke_multiwall_junction.mjs`, `node demo/smoke_multiwall_strip_containment.mjs` | все три — `OK`, все булевы поля `true` (включая #249 discarded wedge, #261 retained wedge, #271 finite rays, #275 protected orthogonal strips — прямое покрытие AC4) |
| Инварианты модели | `npm run invariants -- --config <second-floor as {spaces:[space]}>` и то же для first-floor (space взят из `test/fixtures/real-plan-*-floor.json`) | second-floor: `Инварианты выполнены`, без наблюдений; first-floor: `Инварианты выполнены`, 2 наблюдения «exact endpoints вместо своего ключа» (не нарушения; см. ниже) |
| Мутант AC7 | `node scripts/mutation-gate.mjs --id=multi-wall-shared-continuation-protection-disabled` | чистый прогон зелёный, мутант красный (`тест покраснел, как обязан`), `поймано 1 из 1` |

### Гейты — не выполнено, с причиной

- **`npm run golden:verify` (полная матрица).** `demo/golden/policy.mjs`
  жёстко запрещает частичный прогон (`--scenario=` кидает
  `golden verify must run the complete matrix; use capture for a diagnostic
  --scenario run`) — то есть у этого гейта нет «облегчённой» формы, только
  весь матрикс. Это ровно тот «полный набор», который PROCESS.md §8 называет
  предрелизным гейтом, а не гейтом ревью. AC6 сам делает семантический
  `gapCount === 0` (доказан выше живым прогоном smoke) первичным доказательством,
  а pixel-baseline — вторичным, принимаемым только из Linux CI. Локально не
  прогонял; риск регрессии старых `wall-junctions-*`/`multiwall-junction-bevel-*`
  golden-сцен закрыт иначе: все три «зарегистрированные связи» смоков (см.
  выше) браузерно проверяют именно эти контракты (#249/#261/#271/#275) через
  реальный SVG fill API и дают `OK`.
- **`python -m pytest tests_backend -q`.** Дифф не трогает
  `custom_components/**/*.py` — не применимо.
- **`npm run performance`/`benchmark_*`.** Не назван в AC8 (только
  typecheck/test/build/check-docs/targeted smoke/mutation); spec §6 явно
  относит performance-профиль к предрелизному гейту («перед beta»), не к
  этому ревью.

### Прочитано, не исполнено

- Полная бинарная эквивалентность трёх копий бандла подтверждена `cmp` и `npm
  run bundle:sync`; байтовое содержимое самого JS не читал построчно —
  достаточно детерминированной сборки без diff после `npm run build`.
- Логика `nearbyBuckets`/дедупликации `continuationKeys`/самоисключения через
  `candidate.other == node.point` в `buildMultiWallNodeMap`
  (`src/wall-thickness.ts:1704-1743`) прочитана построчно и прослежена вручную
  на unit-фикстуре AC3 — корректна.
- Архитектурный вопрос «не съедает ли маска ДРУГОГО узла B то, что узел A
  только восстановил через `continuations`, если их радиусы перекрываются»
  (тот самый класс риска, для которого уже существует `protectedStrips`,
  см. комментарий в коде на `src/wall-thickness.ts:2393-2395`) — не доказательство
  чтением, а **выполнено экспериментально**: собраны два синтетических
  сценария через `wallBodiesGeometry` (один — независимый удалённый узел с
  искусственно гигантским радиусом 833, другой — реалистичная цепочка «A—тонкая
  стена—B», где стена короткая для ОБОИХ узлов и оба регистрируют
  continuation друг на друга). В обоих случаях итоговая геометрия не теряет
  ни одной точки (`coverage=1.000` по всей длине связывающей стены). Причина:
  реальное удаление материала выполняют только `outerCuts`/`retainedCuts`
  (направленные вдоль конкретных лучей узла), а не абстрактный квадрат маски;
  всё остальное внутри маски восстанавливает `preservedExterior`
  (`difference(intersection(boundedCurrent, mask), centre)`), которая не
  зависит от того, чьему узлу принадлежит стена. Регрессии не найдено, риск
  не подтвердился — фиксирую как проверенный и закрытый, а не как находку.
  Скрипты одноразовые, в репозиторий не коммитились (правило «не создавать
  файлов в рабочей копии»), `git status` после проверки чист.

## Находки

### Medium (в скоупе, чинится в этом же ТЗ) — нарушен собственный порядок релиза из §10/issue

Issue #288 (тело, раздел «При слиянии») и `docs/specs/288-bounded-multiwall-corridor.md`
§10 требуют одно и то же прямым текстом: ветка `issue/260-fixture-wall-keys`
должна попасть в `dev` **до** финальной пересъёмки docs screenshots для #288
— «Порядок обязателен — съёмка до слияния обесценивается слиянием».

Проверено по SHA:

```
git merge-base --is-ancestor 9031ba0d origin/dev   # НЕ ancestor
git branch -a --contains 9031ba0d                  # только remotes/origin/issue/260-fixture-wall-keys
git show origin/dev:demo/fixtures/wall-key.mjs      # fatal: path does not exist
```

`9031ba0d` («test(fixtures): write the real wall key, in one place»,
`Issue: #260`) — последний коммит ветки #260 — не является предком
`origin/dev` и нигде в `dev` не присутствует (файл `demo/fixtures/wall-key.mjs`
там просто отсутствует). При этом коммит `4aa79dee` («docs: accept screenshots
after junction repair», автор Sergey Matyunin, `Issue: #288`) уже переснял и
принял 10 PNG в `docs/images/**` на текущей ветке #288 — то есть пересъёмка
состоялась раньше, чем требовал сам issue.

**Смягчающее обстоятельство**, которое понижает это до Medium, а не High:
`#260` меняет только `demo/fixtures/**` и тестовые фикстуры (`large-house`,
`visual-matrix` для golden/perf), не `src/**`. Отпечаток `check-docs.mjs`
считается по `src/**`, поэтому механически job `docs` не покраснеет и
пересъёмка не станет технически «протухшей» само по себе. Риск —
не в поломке, а в том, что мандатный порядок релиза, который сам issue
объявил обязательным именно для экономии повторного прогона «Docs
screenshots», не был соблюдён, и решение об этом принял продуктовый автор
(коммит от Sergey Matyunin), а не тот, кому issue явно отвёл слияние #260
(«не обходится ручным слиянием автора продуктовой задачи» — про слияние
самой ветки #260, но дух того же правила: порядок операций реализует не
автор #288 в одностороннем порядке).

Правка: либо (а) дождаться слияния `issue/260-fixture-wall-keys` в `dev`,
затем повторно прогнать `Docs screenshots` и принять командой `npm run
docs:accept -- --reviewed --from=<артефакт>` на дереве, которое уже включает
#260 (даже если PNG не изменятся байтово — процессная гарантия, которую
установил сам issue), либо явно зафиксировать в issue отказ от этого пункта
с обоснованием владельца (если порядок уже неактуален). Само по себе это не
блокирует корректность правки `wall-thickness.ts`.

### Low — AC3 не проверяет геометрию тела, только метаданные `continuations`

`test/wall-thickness.test.mjs`, тест «issue #288 keeps a shared wall attached
beyond a short node ray finite» (добавлен этим диффом) строит узел через
`buildMultiWallNodeMap` и проверяет только структуру `ray.continuations`
(`start`/`u`/`length`/`halfDepth`), но не строит `wallBodiesGeometry` и не
измеряет фактическую утрату площади соседней стены — то, что буквально
требует AC3 («longitudinal material loss соседней тонкой стены не превышает
её собственного half-depth»). Сравните с более старым тестом «issue #271
keeps finite co-directional ray supports…» в том же файле (строки
1199–1240), который для той же категории дефекта дополнительно гоняет
`wallBodiesGeometry` и `assertProbeInside/Outside` — паттерн уже есть в файле,
здесь не использован.

Не блокирует: фактическое поведение на уровне тела подтверждено (а) реальным
`demo/smoke_real_plan_masonry.mjs` на двух живых планах (AC1/AC2, строгий
`gapCount: 0`), (б) мутантом AC7, который убивает именно этот код (хотя и
через тот же метаданными-ограниченный юнит), (в) моей собственной ручной
проверкой через `wallBodiesGeometry` на синтетических конфигурациях (см.
«Прочитано, не исполнено» выше) — везде `coverage=1.000`, потерь площади не
обнаружено. Правка опциональна: добавить в AC3-тест такую же геометрическую
проверку, как в #271-тесте, для более прямого соответствия тексту AC3.
Оставляю на решение автора — не блокирует зелёный вердикт при отсутствии
High.

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

- **AC1/AC2** — доказаны напрямую живым прогоном `smoke_real_plan_masonry.mjs`:
  оба реальных плана дают `gapCount: 0`/`totalGapSteps: 0`, проверены ВСЕ
  точки контура комнат (плотная выборка), а не только 4 исторических гэпа.
  `PLANS`/`KNOWN_GAP_COUNT`/`KNOWN_GAP_STEPS` обновлены на нули в том же
  коммите `ff5e393c`.
- **AC3** — юнит `issue #288 keeps a shared wall attached beyond a short node
  ray finite` прогоняет три масштаба (`scale: 1, 5, 30`, соответствует
  `cell_cm: 1/5/30`), прямой и реверсированный порядок rays/endpoints, и
  отдельно проверяет, что при `kind: 'outer'` на дальнем конце `continuations`
  пуст (не нарушает контракт #249/exterior corridor). Метаданные
  (`start`/`u`/`length`/`halfDepth`) точно совпадают с ожидаемыми для
  топологии `349/120/5` шагов, `30/30/20` см. Геометрический вывод (что это
  реально ограничивает потерю площади) подтверждён отдельно смоком и моей
  ручной проверкой (см. Low выше и раздел «прочитано, не исполнено»).
- **AC4** — регресс всех семи прежних контрактов (#249/#261/#271/#272/#275/#278/#279)
  покрыт: `npm test` включает их юниты без сбоев (например, тест `issue 230…`,
  `#278 anonymized regression…`, `#271 keeps finite co-directional…` —
  видны в живом прогоне выше), и три браузерных смока с прямым совпадением по
  `MultiWallNodeRaySupport` (`junction_patch_resilience`, `multiwall_junction`,
  `multiwall_strip_containment`) зелёные, включая явные поля
  `excessWedgeIsEmpty` (#249), `nodeRemainsFilled` (#261),
  `viewStopsAtFiniteRayEndpoint` (#271) и полное покрытие `cell_5_mixed_depth_t`/
  `cell_1_thick_crossbar_t` (#275).
- **AC5** — тот же `smoke_real_plan_masonry.mjs` меряет через реальный
  production-бандл (`npm run bundle:sync` перед прогоном) и `isPointInFill` в
  Plan/View; структурные консюмеры (roomGeom/geom/paperGeom) используют один
  и тот же canonical `wallBodiesGeometry` — код не создаёт consumer-specific
  патчей (проверено чтением: `multiWallContinuationStripGeometry` вызывается
  один раз внутри `bevelMultiWallBody`, до всех downstream потребителей).
- **AC7** — мутант `multi-wall-shared-continuation-protection-disabled`
  зарегистрирован в `scripts/mutation-gate.mjs`, инвертирует ключевую проверку
  `candidate.kind !== 'shared'` → `=== 'shared'`, и убивается юнитом AC3
  (продемонстрировано живым прогоном выше).
- **AC8 (локальные гейты)** — все выполнены и зелёные (таблица выше).
- **Docs/changelog** — `docs/WALL-THICKNESS.md`, `docs/ARCHITECTURE.md`,
  `docs/TESTING.md` описывают именно то, что делает код (проверено построчно
  против диффа `src/wall-thickness.ts`); `docs/CHANGELOG.md`/`CHANGELOG.ru.md`
  правлены в том же коммите `ff5e393c` с `User-Visible: yes` — трейлеры на
  обоих коммитах диапазона корректны (`Issue: #288` + `User-Visible: yes/no`).
- **Одно число — один источник.** Дифф не добавляет и не меняет ни одной
  пользовательски видимой числовой величины (это фикс геометрии заливки/
  рендера стен, не текстовое отображение размеров); `test/single-source-numbers.test.mjs`
  прошёл в составе `npm test` без изменений с его стороны — неприменимо по
  существу, не только механически.
- **Совместимость/touch/security/perf (спека §6/§11)** — не подтверждаю
  отдельным прогоном (не требуется по AC8), но проверено чтением: изменение
  локально по `rays`/`supports` одного узла, не вводит новый глобальный
  проход по стенам, не меняет schema/config/layout/Optimize (дифф не трогает
  соответствующие файлы), не добавляет HA service calls.

## Гейты, которые прогнал/не прогнал — сводка

Прогнал: `tsc --noEmit`, `npm test`, `npm run build` + `cmp` бандлов,
`node scripts/check-docs.mjs`, `node scripts/smoke-select.mjs`,
`demo/smoke_real_plan_masonry.mjs`, три «зарегистрированные связи» смока
(`smoke_junction_patch_resilience`, `smoke_multiwall_junction`,
`smoke_multiwall_strip_containment`), `npm run invariants` на конфигах,
собранных из обеих real-plan фикстур, целевой мутант AC7.

Не прогнал: полный `npm run golden:verify` (запрещён частичный прогон
инструментом, это предрелизный гейт §8), `pytest tests_backend` (Python не
тронут), performance-профили (не названы в AC8).

## Вердикт

Жёлтый. Геометрический фикс (`src/wall-thickness.ts`) корректен, полностью
покрыт тестами/смоками/мутантом и подтверждён живым прогоном на обоих реальных
планах — по существу задача решена и решает заявленный сценарий (J1/J6:
непрерывные стены на реальном плане). Единственная причина жёлтого —
процессная: пересъёмка docs-скриншотов в этом же диапазоне коммитов состоялась
раньше, чем сам issue/спека предписывают слияние `issue/260-fixture-wall-keys`
в `dev`. High нет; Medium — один, в скоупе.