houseplan-card/docs/reviews/CODE-REVIEW-302-r2.md

# CODE-REVIEW-302-r2

Issue: #302 · Этап: code · Заход: r2 · блокирующих циклов израсходовано 1/4 до
этого захода

## Скоуп раунда

r1 (SHA `fa1112e7`) закончился жёлтым: High 0, Medium 2 (M1 — доку
`docs/WALL-THICKNESS.md` не переписали под решение №5; M2 — гвард мутанта
`junction-fans-disabled` инфраструктурно сломан, «поймано» не было проверено
исполнением). Автор хендоффнул исправление на вершине `a5ea578`
(комментарий issue 2026-08-25T14:00:05Z), затем конвейер перед ревью
ребейзнул ветку на свежий `dev` — вершина стала `42e02396`.

**Проверка ребейза (§7.2).** `git diff a5ea578..42e02396 --stat` даёт ровно
один файл: `docs/reviews/SPEC-REVIEW-304-r1.md` (+128, чужой issue). Дерево
кода/тестов/доки #302 идентично байт-в-байт. Это не «другой код» — единственный
привнесённый ребейзом файл не пересекается ни с одним путём этой задачи и не
проходит фильтр `frontend`-триггера CI (подтверждено логом job `changes`,
CI-прогон 32856428594). Разбор веду **по дельте** r1→r2: `git diff
fa1112e7..HEAD` — четыре файла по существу (`docs/WALL-THICKNESS.md`,
`scripts/mutation-gate.mjs`, `src/wall-thickness.ts`, плюс пересборка бандла и
`docs/images/screenshots.json`), plus два review-документа. Расширил разбор за
пределы формальной дельты в одном месте (см. находку M3) — при чтении
`src/wall-thickness.ts` полностью для оценки M2/Low вокруг него нашёл
расхождение AC6 с реализацией; код этого места не менялся между r1 и r2, но
находка целиком в скоупе задачи, а не в скоупе только этой правки, поэтому
привожу её отдельно, а не молчу.

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

Гейты «всегда» (исполнением, на HEAD `42e02396`):

| гейт | команда | результат |
|---|---|---|
| типы | `npx tsc --noEmit` | чисто |
| юниты | `npm test` | 1303 pass / 1 skip / 0 fail |
| сборка | `npm run build` + `diff dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | rollup ok; `git status` после билда чист (свежий `dist` побайтно совпал с закоммиченным) — три копии (пересобранная, `dist/`, `custom_components/`) идентичны |
| доки | `node scripts/check-docs.mjs` | «Documentation checks passed (7 files, 10 external links)» |
| инварианты | `npm run invariants -- --config test/fixtures/302-junction-artifacts.json` | «ссылки разрешимы, записи толщины находятся» |

Мутанты, названные M2/Low (исполнением, штатным харнессом
`scripts/mutation-gate.mjs --id=...`):

| id | результат |
|---|---|
| `junction-fans-disabled` | поймано 1 из 1 |
| `junction-fan-ignores-thick-length` | поймано 1 из 1 |
| `junction-reflex-outer-mitre-missing` | поймано 1 из 1 |
| `junction-fan-limit-back-to-249` | поймано 1 из 1 |
| `junction-detector-blind` | поймано 1 из 1 |
| `junction-pieces-unbounded` | поймано 1 из 1 |
| `partition-merge-ignores-junction` | поймано 1 из 1 |
| `junction-checks-room-vertices-only` | поймано 1 из 1 |

`junction-supports-not-restored` и `multi-wall-paper-full-origin-cut` из
реестра удалены этим диффом — проверено, что их find-паттерны (обращения к
удалённым `paperWithNodeCorners`/`[...corners.supports, ...corners.fans]`)
больше не существуют в файле: мутанты стали неприменимы к текущему коду, снятие
не притворное.

Смоки/golden: `smoke-select.mjs` для дельты `fa1112e7..HEAD` даёт прямые
совпадения `smoke_junction_holes`, `smoke_decor`, `smoke_grid_scale_invariance`,
`smoke_real_plan_masonry`, `smoke_space_scale_defaults` и пять
«зарегистрированных связей» (`junction_patch_resilience`, `multiwall_junction`,
`multiwall_strip_containment`, `resize_pointer_real_plan`,
`resize_wall_thickness`). Локально браузерные проверки (`golden:verify`,
`demo/smoke_*.mjs`) **не выполнились**: `page.route` не перехватывает
динамический `import()` в этом окружении — `Failed to fetch dynamically
imported module: http://demo.local/assets/houseplan-card.js`. Проверил, что
это ограничение песочницы, а не регрессия: та же ошибка воспроизводится
байт-в-байт на чистом `origin/dev` (worktree, символическая ссылка на
`node_modules`) с давно существующим `demo/smoke_align_guides.mjs`, который
дифф не касается.

Вместо локального прогона поднял CI-прогоны по `gh run view`:
- `32855773018` (headSha `30b4bbf6`, кодово идентичен `a5ea578`/`42e02396` по
  `src/**`/`test/**`/`scripts/**` — единственная разница дальше по цепочке это
  фикс отпечатка скриншотов) — `frontend`, `golden`, все три шарда `smoke`,
  `performance_smoke` зелёные; красным был только `docs` (протухший отпечаток
  скриншотов — это и есть то, что чинит следующий коммит `42e02396`, дока
  «refresh the screenshot fingerprint»);
- `32856428594` (headSha `a5ea578`) — `docs` зелёный (фингерпринт поправлен),
  `frontend`/`golden`/`smoke` пропущены самим `changes`-джобом: между
  `30b4bbf6` и `a5ea578` изменился только `docs/images/screenshots.json`, под
  фронтенд-триггер не попадает;
- `32856829923` (headSha `42e02396`, текущий HEAD) — красный один
  `process-gate` на несуществующем в раннере before-SHA (артефакт force-push
  после ребейза на dev, автор описывает его же во всех трёх последних
  хендоффах); `frontend`/`docs`/`provenance` зелёные, `golden`/`smoke`
  пропущены — тем же основанием (после `a5ea578` изменился только чужой
  `SPEC-REVIEW-304-r1.md`).

Собранные вместе, эти три прогона покрывают полный набор гейтов на
кодово-идентичном дереве, включая golden и все смоки — считаю это equivalent
доказательству «оно работает», раз локальный браузерный прогон недоступен.

## Закрытие раунда r1

| находка r1 | чем закрыта | где видно |
|---|---|---|
| **M1** — `docs/WALL-THICKNESS.md` §3 описывал отменённое решение «фаска #249 сохраняется» | Абзац переписан под решение №5 целиком: полный mitre в секторе, `bevelMultiWallBody` — только адресный трим для #271, `bevelMultiWallPaper` убрана | `docs/WALL-THICKNESS.md:185-206` (коммит `72a5992f`); прочитано и сверено построчно с текущим кодом `junctionNodeGeometry`/`bevelMultiWallBody` — соответствует |
| **M2** — гвард `junction-fans-disabled` был `node demo/smoke_junction_holes.mjs` без сборки `test-build`, падал `ERR_MODULE_NOT_FOUND` на чистом дереве | Guard переведён на `npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs && node --test --test-name-pattern="issue 302" ...`; дополнительно (второй виток, коммит `af33c49e`) сама проверка переведена с самоссылочного контракт-проб-детектора на независимый юнит формы `issue 302 a T node covers every sector with a fan or a mitre` (`test/wall-thickness.test.mjs:2930-2940`) | `scripts/mutation-gate.mjs:2174-2190`; исполнено лично — `node scripts/mutation-gate.mjs --id=junction-fans-disabled` → «поймано 1 из 1» |
| Low — `bevelMultiWallPaper` мёртвый код | Функция удалена целиком (`src/wall-thickness.ts`, было `:2955-2994`); следом измерением снята и re-union саппорт-квадов в теле (`31ba14e0`), плюс два осиротевших мутанта из реестра | `git diff fa1112e7..HEAD -- src/wall-thickness.ts` — оба блока отсутствуют; live-подтверждение — тест `issue 302 the owner repro is hole-free end to end` (`test/wall-thickness.test.mjs:3026-3054`) гоняет упрощённый пайплайн на реальной фикстуре репро и не находит дыр |

## Находки

### M3 (Medium, в скоупе задачи) — AC6 не выполнен: узловая механика не «безоперационна по difference», спека это не признаёт

**Файл:** `src/wall-thickness.ts:3535-3555` (вызов), `src/wall-thickness.ts:2856-2953`
(тело `bevelMultiWallBody`); спека `docs/specs/302-junction-node-material.md:64-73`
(§4, решение №5), `:129-131` (§8.2), `:196-198` (AC6).

**Что заявлено.** Решение владельца №5 (принято в день ребейза, зафиксировано
в спеке и в теле коммита `79e86b0a`): «фаска #249 демонтируется **целиком**...
слой `bevelMultiWallBody`/`bevelMultiWallPaper` **удаляется**». §8.2 повторяет
это как формальный контракт: «**В узловой механике нет ни одной операции
`difference`** (вычитающий слой фаски демонтирован): дыра между полосами
невозможна **по построению**». AC6 — то же самое как проверяемый критерий.

**Что в коде.** `bevelMultiWallBody` (старая реализация фаски #249, с
`difference()` на строках 2889, 2898, 2922, 2924) не удалена: она вызывается
на подмножестве узлов, отфильтрованном `needsTrim` (короткий толстый саппорт,
#271) — `src/wall-thickness.ts:3542-3554`. Это не мёртвый код: комментарий на
`fixture #197` (`test/wall-thickness.test.mjs:2236-2240`) прямо говорит, что
тест полагается на этот трим («#271 removes only the area that the old
node-wide 8H rectangles invented»), и площадь фикстуры (`closeTo(...,
124535.20808099362, ...)`) посчитана с его участием.

**Почему это не придирка к формулировке.** Весь смысл переработки #302 —
уйти от вычитающих ремонтных слоёв, потому что именно они были источником
рецидивирующих дыр (это буквально сюжет issue: 29 коммитов «point fixes»,
которые не сходились). «Дыра невозможна по построению» — это утверждение
именно про отсутствие `difference`; для узлов, где реально срабатывает
`needsTrim`, инвариант «hole-free» держится не построением, а корректностью
унаследованного вычитающего кода — той же категории кода, что и раньше ломался.
Спека и коммит основного решения (`79e86b0a`) заявляют «удаляется целиком», но
имплементация — тот же коммит! — сохраняет узкий трим и честно объясняет
зачем в комментарии кода. То есть автор знал про исключение в момент
написания контрактной формулировки, но не отразил его ни в §4/§8.2/AC6 спеки.
`docs/WALL-THICKNESS.md` (живой документ подсистемы) это исключение описывает
верно — именно потому что M1 в этом самом раунде его туда вписал; спека
(контракт, по которому пишутся AC) осталась с абсолютной, невыполненной
формулировкой.

Отдельно: ни один этап ревью до сих пор AC6 не подтверждал. Решение №5
поменяло текст спеки уже ПОСЛЕ обоих раундов SPEC-REVIEW (они зелёные на
версии «фаска #249 сохраняется» — SHA `3b19111a`); AC6 в его текущей редакции
никогда не проходил ни одного ревью. В вердикте r1 (комментарий issue
2026-08-25T13:29:36Z) явно перечислены как проверенные AC1, AC2, AC4, AC5,
AC7, AC9 — AC6 в списке демонстративно нет, то есть r1 либо не проверял его,
либо проверял и не сообщил результат.

**Воспроизведение.** `grep -n "difference(" src/wall-thickness.ts` в диапазоне
2856-2953 (`bevelMultiWallBody`) — 4 вызова; трассировка вызова от
`wallBodiesGeometry` (`:3542-3554`) до этой функции безусловна при
`trimNodes.length > 0`. `needsTrim` реально истинен минимум для узла фикстуры
#197 (по прямому указанию комментария теста, задача #271).

**Серьёзность и что чинить.** Не блокирует релиз функционально — вся
визуальная/golden матрица подтверждает, что заявленный владельцем результат
(без вырезов/рожков, полный mitre) достигнут, и трим — узкий, адресный,
дисциплинированно закомментированный код, а не регресс. Но AC — формальный
критерий приёмки этой задачи, и он не выполнен в буквальном прочтении. Дёшево
чинится без правки кода: привести спеку в соответствие с уже написанной (в
этом же раунде) правдой `docs/WALL-THICKNESS.md` — явно назвать исключение
#271 в §4.5/§8.2 и переформулировать AC6 («узловая механика аддитивна для
всех узлов, кроме адресного #271-трима, унаследованного из #249 и суженного
до вырожденного случая»), либо, если владелец сочтёт исключение
неприемлемым, вернуть задачу на технический разбор устранения самого трима.
Это решение продуктовое/архитектурное, не моё — фиксирую находку, не
предписываю какой из двух путей выбрать.

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

- M1, M2, Low из r1 закрыты по существу, не только по заявлению — см. таблицу
  выше; для M2 лично прогнал мутант и получил «поймано 1 из 1», а не поверил
  тексту коммита (текст коммита `72a5992f` сам признаёт, что автор один раз
  уже ошибочно заявил «проверено исполнением», не проверив).
- Удаление `bevelMultiWallPaper`/`paperWithNodeCorners`/двух мутантов —
  полное, без осиротевших ссылок; подтверждено `grep` по обеим удалённым
  сигнатурам и живым тестом на реальном пайплайне (`the owner repro is
  hole-free end to end`).
- `docs/WALL-THICKNESS.md` после M1 фактически точен для того путя, который
  описывает M3 (адресный трим назван прямо) — то есть подсистемная дока не
  расходится с кодом, расходится только сама спека issue.
- Трейлеры всех четырёх коммитов дельты (`72a5992f`, `af33c49e`, `31ba14e0`,
  `42e02396`) содержат `Issue: #302` и `User-Visible: no` — корректно: эти
  четыре коммита не меняют видимое поведение относительно того, что уже было
  выпущено с `User-Visible: yes` в `79e86b0a`/`a5d30467` (там же в том же
  коммите обновлены оба CHANGELOG — проверено `git show 79e86b0a --
  docs/CHANGELOG.md docs/CHANGELOG.ru.md`).
- tsc/test/build/check-docs/invariants — все чисто, гейты не помечены как
  условно пройденные.
- Мутационное покрытие узловой механики (8 мутантов, включая переписанный
  M2) — самопроверено исполнением, не только чтением реестра.

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

- **`npm run golden:verify` и `demo/smoke_*.mjs` — не выполнил локально.**
  Окружение ревью не даёт Chromium перехватить динамический `import()`
  (воспроизведено то же самое на чистом `origin/dev` с чужим смоком —
  ограничение песочницы, не регрессия дельты). Компенсировано тремя
  CI-прогонами на кодово-идентичном дереве (см. «Как проверялось»): golden
  126/126 и все три шарда смоков зелёные на `30b4bbf6`; `docs`-джоб зелёный на
  `a5ea578`/`42e02396` после фикса отпечатка.
- **Полный golden-набор и весь `demo/smoke_*.mjs` (не только выбранные
  smoke-select) не гонял вручную** — избыточно: `smoke-select.mjs` дал узкий
  список, а CI уже прогнал полный набор (все три шарда — это весь
  `demo/smoke_*.mjs`, не подмножество) на этом дереве.
- **Продуктовую визуальную приёмку 16 новых junction-сцен не пересматривал
  глазами** — это решение владельца (комментарии issue 2026-08-25 11:40 и
  12:42), не предмет код-ревью; полагаюсь на golden pixel-diff.
- **AC3, AC8** (пиксельное совпадение непричастных сцен, перф-бюджет) —
  унаследованы из r1/из CI (`performance_smoke` зелёный в `32855773018`), не
  передельфрено отдельно: дельта r1→r2 не трогает рендер-путь и перф-профиль.

## Унаследовано из r1

Документ r1: `docs/reviews/CODE-REVIEW-302-r1.md` (комментарий issue
2026-08-25T13:29:36Z), проверен на SHA `fa1112e7`.

Принято без повторной проверки, так как дельта r1→r2 не касается этого кода:
- геометрия веера/mitre/bevel-хорды/рефлекса (`junctionNodeGeometry`) —
  «прочитана построчно и соответствует контракту §8» (кроме уточнения по
  AC6 выше — то новая находка этого раунда, не подтверждение r1);
- AC1, AC2, AC4, AC5, AC7, AC9 — сочтены выполненными и проверенными
  исполнением в r1; код, который их обеспечивает, не менялся между `fa1112e7`
  и `HEAD` (сверено `git diff fa1112e7..HEAD -- src/wall-thickness.ts` —
  единственные правки вне M1/M2/Low перечислены в разделе «Закрытие раунда
  r1» и не затрагивают mitre/bevel/reflex ветки);
- продуктовая рамка (SCOPE.md, J1/J2) и полнота DoR спеки — не пересматривал,
  дельта не продуктовая;
- решение владельца №5 (полный mitre, отказ от фаски #249 как видимого
  эффекта) как таковое не оспариваю — это принятое продуктовое решение;
  находка M3 — про честность формальной формулировки AC6, а не про само
  решение.

## Вывод

Мultimedia M1/M2/Low закрыты добросовестно и проверены исполнением, а не на
слово. Обнаружена одна новая находка в скоупе (M3): AC6 этой же задачи не
выполнен буквально, и это никогда не проходило ревью (решение №5 переписало
спеку уже после двух зелёных SPEC-REVIEW). Возвращаю жёлтым для приведения
спеки в соответствие с уже написанной верной докой подсистемы либо для
явного решения владельца по трим-исключению.