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

# CODE-REVIEW-302-r1

Issue: [#302](https://github.com/Matysh/houseplan-card/issues/302) — «Артефакты на стыках стен: дыры в union-геометрии. Переработка механизма стыков + полноценный сет скриншот-тестов»
Спек: `docs/specs/302-junction-node-material.md` (зелёное ревью ТЗ, `SPEC-REVIEW-302-r1`/`r2`)
Ветка: `issue/302-junction-node-material`, вершина `fa1112e7` (после ребейза на `origin/dev` = `2143e888`, включает #265/#301/#303)
Заход: r1 · блокирующих циклов израсходовано 0 из 4 (этап код-ревью первый; предыдущая попытка `S7-code-review` не состоялась — упёрлась в конфликт ребейза до чтения кода, цикл не расходовался согласно комментарию владельца от 12:43)
Класс изменения: A (продукт) + B (гейты/тесты) + C (документация)

## Скоуп

Полная переработка механики материала в узлах стен (degree-3+, три и более
сходящихся луча): старая смешанная схема «аддитивные патчи + вычитающий
`bevelMultiWallBody`-бевел (#249) с protection-union» заменяется на решение
владельца №5 — **полный mitre по умолчанию** (веер `junctionNodeGeometry`,
mitre в пределах `MITRE_LIMIT`, bevel-хорда за ним, рефлексные сектора
замыкаются обратным mitre или хордой), плюс формальный детектор дыр
`junctionContractHoles` и сет из 16 крупноплановых golden-сцен + сцена-репро
владельца. Старый вычитающий слой `bevelMultiWallBody` не демонтирован
целиком, а сужен до адресного латерального трима для вырожденных
короткосаппортных узлов (#271); `bevelMultiWallPaper` из пути бумаги убран
полностью.

Диапазон: `git diff origin/dev...HEAD` — 47 файлов, ядро в
`src/wall-thickness.ts` (+351/-… строк), тесты (`test/wall-thickness.test.mjs`,
новая фикстура `test/fixtures/302-junction-artifacts.json`), новый смок
`demo/smoke_junction_holes.mjs`, обновлённый `demo/smoke_multiwall_junction.mjs`
и `demo/smoke_grid_scale_invariance.mjs`, 7 новых мутантов
`scripts/mutation-gate.mjs`, 16 новых + 2 изменённых golden-эталона,
`docs/WALL-THICKNESS.md`, оба CHANGELOG.

Это первый содержательный проход код-ревью по этой задаче (первая попытка
`S7-code-review` вернулась конвейером до чтения кода из-за конфликта
ребейза — цикл не расходован, документ по дельте не нужен), поэтому разбор
полный, а не по дельте (§2.10 не применяется).

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

Материал — коммиты `git log --oneline origin/dev..HEAD` (14 штук) и
`git diff origin/dev...HEAD`. Выполнено на этом дереве (SHA `fa1112e7745e0ba0`),
не на слово автора.

| Гейт | Команда | Результат |
|---|---|---|
| typecheck | `npx tsc --noEmit` | чисто |
| unit | `npm test` | 1303 pass / 1 skip / 0 fail (1304 объявлено) |
| build + сверка бандла | `npm run build && cmp dist/… custom_components/…` | идентичны; `npm run bundle:sync` не изменил рабочее дерево (git status чист) |
| docs screenshots fingerprint | `node scripts/check-docs.mjs` | «Documentation checks passed (7 files, 10 external links)» — обязателен, диф трогает `src/**` |
| инварианты модели (диф трогает геометрию узлов/`walls`) | `npm run invariants -- --config <репро #302, обёрнутое {space:{...}}>` | «Инварианты выполнены: ссылки разрешимы, записи толщины находятся» |
| golden | `npm run golden:verify` | **126/126 passed**, локально, целиком (совпадает с заявкой автора) |
| смоки — прямые совпадения `smoke-select.mjs --base origin/dev --head HEAD` | `smoke_junction_holes`, `smoke_real_plan_masonry`, `smoke_grid_scale_invariance` | все OK |
| смоки — AC9 плюс «зарегистрированная связь» | `smoke_multiwall_junction`, `smoke_wall_junctions`, `smoke_junction_patch_resilience`, `smoke_render_perf` | все OK |
| мутанты #302 (выборочно, `--id=`) | `junction-fan-limit-back-to-249`, `junction-detector-blind`, `junction-pieces-unbounded`, `junction-supports-not-restored` | 4/4 корректно ловят поломку («поймано 1 из 1» / «поймано 0 из 1» для guard без мутации, как обязано) |
| мутант `junction-fans-disabled` | `node scripts/mutation-gate.mjs --id=junction-fans-disabled` | **упал на чистом прогоне** — см. находку M1 |
| process-gate офлайн | `node scripts/process-gate.mjs` | «гейт пройден, предупреждений 0» |
| CI на вершине | `gh run view` на прогонах, указанных автором | подтверждено см. ниже |

Не прогонялось и почему:
- `python -m pytest tests_backend` — диф не трогает `custom_components/**/*.py` (не нужен по правилу гейтов);
- полный `demo/smoke_*.mjs` (189 файлов) — задача не «задевает всё», выборка
  дана `smoke-select.mjs` (5 прямых + 2 «зарегистрированная связь») плюс AC9;
  расширил её `smoke_render_perf` (AC8) вручную;
- `npm run mutants` целиком (все ~90 мутантов проекта) — предрелизный гейт
  (§8), не гейт ревью; из новых семи прогнал четыре показательных плюс
  специально диагностировал сломанный;
- полный performance-бенчмарк (`npm run benchmark:*`) — дорогой,
  предрелизный; вместо повторного прогона проверил, что CI job
  `performance_smoke` реально выполнился и был зелёным на `b95c55d3` (см. ниже),
  а не «reuse»-пропущен.

**CI, названный автором.** Прогон [32850091121](https://github.com/Matysh/houseplan-card/actions/runs/32850091121)
на `b95c55d3` (родитель финального docs-коммита): `frontend`, `golden`,
`performance_smoke`, `smoke` (все три шарда), `docs`, `provenance` —
`success`; `process-gate` — `failure` (ожидаемо: before-SHA от форс-пуша,
самовылечился следующим пушем, как и описал автор). Прогон
[32850748475](https://github.com/Matysh/houseplan-card/actions/runs/32850748475)
на финальном `fa1112e7` — `success` целиком; тяжёлые job'ы там `skipped`
через легитимный `reuse` (доки — единственный дифф этого коммита, не
затрагивающий их отпечаток). Вместе оба прогона покрывают полный набор на
проверяемом дереве, как и заявил автор.

## AC — разбор

| AC | Статус | Доказательство |
|---|---|---|
| AC1 (детектор: 0 дыр на всём сете) | ✅ | golden verify 126/126 включает все 16 сцен + репро; `smoke_junction_holes` (прямое исполнение) `noContractHoles: true`; юнит-тест «the owner repro is hole-free end to end» зелёный |
| AC2 (репро владельца: 0 дыр) | ✅ | тот же смок + golden `junction-owner-repro-dark` passed |
| AC3 (несвязанные сцены — побайтно; junction-сцены — легально изменены) | ✅ | `baselines-index.json`: только 16 новых + 2 изменённых (`safe-resize-handles-clamp-*`, названо автором как узловая вершина ромба) хэша; остальные 108 не тронуты — подтверждено чтением индекса |
| AC4 (57°, 50/70 — сплошная кладка) | ✅ | юнит «the 57° mixed-thickness pair takes the full mitre (decision #5)» проверяет ровно эту геометрию (углы 45°/102.3°/332.2°, half 4.861/3.472) |
| AC5 (виртуальный луч не порождает кладку) | ✅ (чтением) | `junctionNodeGeometry`: `rays = node.rays.filter(ray.halfDepth > 0)` — нулевой/виртуальный луч исключён из веерного обхода до сортировки по азимуту, соседи по азимуту становятся его соседями автоматически; golden `junction-t-virtual-arm-dark`/`junction-x-virtual-through-dark` в сете |
| AC6 (узловая механика не содержит `difference`) | ⚠️ частично — см. находку M1/M2 | Буквально неверно: `bevelMultiWallBody` (внутри — `difference`) по-прежнему вызывается для узлов с вырожденно-коротким толстым саппортом (`corePhase = 'multi-wall-trim'`, `wall-thickness.ts:3600-3613`). Регресс-мутант, названный в спеке для этого AC («лимит веера 1.25·h»), проверен и ловится (`junction-fan-limit-back-to-249`). Мутант, названный в спеке для «веера не строятся вовсе», сломан на инфраструктурном уровне — см. M2 |
| AC7 (оба рендерера — один вызов) | ✅ (чтением) | `wallBodiesUnionPath` (единственная точка, `wall-thickness.ts:3714`) вызывается и из `houseplan-card.ts:11692`, и из `space-render.ts:432`; архитектура не менялась, только тело функции |
| AC8 (перф в бюджете) | ✅ с оговоркой | `smoke_render_perf` OK; CI `performance_smoke` реально выполнился и зелёный на `b95c55d3` (не reuse-пропуск, проверено по списку job'ов). Явного числового «замера large-house» в хендоффе нет, спека требовала это отдельной строкой — не блокирует (Low, механизм проверки существует и сработал) |
| AC9 (существующие смоки стыков зелёные) | ✅ | `wall_junctions`, `junction_patch_resilience`, `multiwall_junction`, `real_plan_masonry` — все прогнаны лично, OK |

## Находки

### Medium (в скоупе) — M1: `docs/WALL-THICKNESS.md` не переписан под решение №5, хотя спека требовала это явно

Файл: `docs/WALL-THICKNESS.md:188-196`.

Абзац «**Junction nodes (#302).**» по-прежнему гласит: *«A degree-3+ node
keeps the approved #249 chamfer (`bevelMultiWallBody`, bounded by the node's
join limit `MULTI_WALL_JOIN_LIMIT × halfDepth`), and AFTER it the node
additively gets back what a chamfer must never eat…»* — это описание
**отменённого** утреннего решения «сохранить фаску #249», а не итогового
решения №5 («узлы смыкаются полным mitre… фаска #249 демонтируется целиком»,
`docs/specs/302-junction-node-material.md:65-73`). Фактическое поведение (по
чтению `wall-thickness.ts:3591-3634`) обратное описанному в доке: фаска
(`bevelMultiWallBody`) теперь **опциональна и включается только** для узлов
с вырожденно-коротким толстым саппортом (`needsTrim`), а не «для каждого
degree-3+ узла» как написано; для всех остальных узлов работает чистый
аддитивный веер, что и есть содержательное отличие этой задачи.

Коммит `e8338663` («feat: full mitre at every node — the #249 chamfer
retires», `User-Visible: yes`, решение №5) не тронул `docs/WALL-THICKNESS.md`
вовсе (`git show --stat e8338663` не содержит этот файл). Единственный
последующий докс-коммит `fa1112e7` добавил только раздел «Junction tooling»
(список тестов), не исправив основной абзац.

Нарушает:
- `PROCESS.md` правило 11: «Документация — в том же коммите, что поведение.
  Отдельным «допишу потом» коммитом документация не бывает» — коммит,
  сменивший контракт (`e8338663`, User-Visible: yes), не обновил канонический
  документ подсистемы;
- собственное требование спеки, §15: «`docs/WALL-THICKNESS.md` §3 и §9
  переписываются под новую механику» — раздел §9 (Independent partitions)
  тоже не упоминает #302 вовсе, что ожидаемо (узел независимых партиций не
  трогается), но §3 обязан был обновиться и не обновился.

Почему это находка, а не педантизм: этот файл — канонический документ
подсистемы, который явно предписано читать перед любой работой над стенами
(`AGENTS.md`, сам этот ревью начиналось с его чтения). Ложное описание
«узел всегда получает старую фаску» уведёт следующего агента/автора по
неверному следу при следующей задаче на стыках.

Воспроизведение: `git diff origin/dev...HEAD -- docs/WALL-THICKNESS.md` —
всего 24 добавленные строки, из которых 15 — новый раздел про тестирование;
абзац §3 про механику узла не менялся с коммита `9e68d641` (12:33), то есть
раньше решения №5 (15:13).

Фикс: переписать абзац `docs/WALL-THICKNESS.md:188-196` под фактический
контракт — веер по умолчанию (mitre/bevel-хорда, рефлекс), `bevelMultiWallBody`
только как адресный трим для короткосаппортных узлов, `bevelMultiWallPaper`
убран из бумаги целиком.

### Medium (в скоупе) — M2: мутант `junction-fans-disabled` не работает, вопреки заявлению «краснота проверена исполнением»

Файл: `scripts/mutation-gate.mjs:2213-2225`.

```
guard: 'node demo/smoke_junction_holes.mjs',
```

`demo/smoke_junction_holes.mjs` — единственный смок в проекте, импортирующий
напрямую из `../test-build/wall-thickness.js` (`grep -rl "from '../test-build/"
demo/smoke_*.mjs` находит только его), поэтому его guard обязан собрать
`test-build/` первым (как это делают все соседние #302-мутанты:
`npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs && …`).
У этого мутанта такого префикса нет.

Харнесс сам решает, нужен ли `test-build`, эвристикой
`guardNeedsTestBuild()` (`scripts/mutation-gate.mjs:2920-2922`):
`/(^|[\s&|;])node --test\b/.test(guard) && !guard.includes('tsconfig.test.json')`
— она матчит только guard'ы вида `node --test …`, а не «браузерный» смок,
который тем не менее тоже читает `test-build/`. Результат — воспроизведено
исполнением:

```
$ node scripts/mutation-gate.mjs --id=junction-fans-disabled
FAIL чистый прогон: node demo/smoke_junction_holes.mjs красный без мутанта
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/tmp/hp-mutant-uvmoTK/test-build/wall-thickness.js' …
```

Гейт падает уже на «чистом» прогоне (до применения мутации) — это
означает, что мутант не проверял АБСОЛЮТНО ничего ни разу с момента
создания: ни в момент написания, ни в любом гипотетическом прогоне харнесса
он не мог напечатать «поймано 1 из 1». Это прямо противоречит явному
заявлению в теле коммита `e8338663`: *«мутанты переякорены, краснота каждого
проверена исполнением»* и в хендоффе issue: *«восемь мутантов — краснота
каждого проверена исполнением штатным харнесом»*.

Мутант закрывает первую строку таблицы §14 спеки — `node-fan-disabled`
(«веера не строятся вовсе» → «детектор на сете») — самый фундаментальный
регресс-класс новой механики. Сейчас его прикрывает не он, а косвенно
`junction-supports-not-restored` (другой мутант, который частично
пересекается по эффекту — тоже режет вклад аддитивных кусков — и этот
действительно ловится, «поймано 0 из 1» без мутации, «FAIL» ожидаемо на
чистом прогоне... то есть сам по себе он в порядке). Но заявленное покрытие
«веера отключены полностью» не проверено никем.

Не является блокирующим (High), потому что: (а) это дефект тестовой
инфраструктуры, а не продуктового кода — сама геометрия работает и покрыта
множеством других зелёных проверок (детектор, 126/126 golden, все AC9-смоки);
(б) `mutation-gate` — предрелизный, не блокирующий Validate гейт (§8,
`.github/workflows/mutation-gate.yml` — по расписанию/`workflow_dispatch`,
не на каждый push), поэтому CI branch protection этим не введён в заблуждение
формально. Но это Medium в скоупе: спека прямо обещала эту защиту (§14),
коммит прямо заявил, что она проверена, и оба заявления не соответствуют
действительности.

Фикс: добавить в `guard` этого мутанта тот же префикс сборки, что у соседей —
`'npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs && node demo/smoke_junction_holes.mjs'`
— и повторно прогнать `--id=junction-fans-disabled`, чтобы подтвердить
«поймано 1 из 1» на самом деле.

### Low — L1: `bevelMultiWallPaper` осталась мёртвым кодом

Файл: `src/wall-thickness.ts:2955-2984`.

Функция `bevelMultiWallPaper` (вычитающий бевел для контура бумаги) не имеет
вызовов нигде в дереве (`grep -rn "bevelMultiWallPaper" src/*.ts test/*.mjs
demo/*.mjs` находит только её собственное объявление) — коммит `e8338663`
корректно убрал единственный вызов (`paperGeom`/`floorFootprintGeometry`
теперь используют `paperWithNodeCorners`), но само тело функции осталось.
Не экспортирована, поведения не меняет, `tsc --noEmit` её не флагует
(в проекте нет `noUnusedLocals` для верхнеуровневых функций). Снимаю с
записью — правьте свободно вместе с M1, либо отдельной строкой, решение за
автором: это тривиальная уборка, не тянет на отдельный цикл сама по себе.

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

- Основной контракт (веер `junctionNodeGeometry`, границы mitre/bevel,
  фасадный клип `junctionNodeBound`, спец-случаи виртуального луча,
  коллинеарной пары, degree-1, колонны) прочитан построчно и соответствует
  §8.2-8.3 спеки; тесты `test/wall-thickness.test.mjs` («issue 302 …», 6 новых
  тестов) целятся именно в эти границы, включая регресс на 1.25·h-лимит
  (старый #249) и на вырожденный реверс-mitre (Y-60 из отчёта владельца).
- Формальный детектор `junctionContractHoles` не «слеп»: юнит-тест кормит
  ему заведомо дырявое тело (2 из 3 полос) и требует красноты — прошёл;
  отдельно мутант `junction-detector-blind` подтверждает то же на живом
  харнессе.
- Golden-набор реально расширяет покрытие матрицы §13 почти полностью:
  L отсутствует как отдельная сцена, но обоснованно — `buildMultiWallNodeMap`
  строит узлы только для `rays.length >= 3` (`wall-thickness.ts:1939`),
  обычный двухлучевой угол этим механизмом вообще не обрабатывается (это
  зона старого, не тронутого этой задачей `outsetContour`/`insetContour`
  mitre); включение «L» в таблицу §13 спеки было избыточным пожеланием, а не
  пропущенным требованием — не в счёт находок.
- Трейлеры: оба `User-Visible: yes`-коммита (`9afc410d`, `e8338663`) несут
  правки в `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md` в том же коммите;
  формулировка финальной записи («the old junction chamfers are gone»)
  описывает видимый результат (визуально фаска исчезла — трим невидим,
  работает только на вырожденных геометриях) и не расходится с рендером.
- Golden-коммиты несут `Release:`/`Baseline-Reviewed:` на реальные зелёные
  прогоны CI (проверено — оба run ID существуют и относятся к веткам этой
  задачи).
- `process-gate.mjs` офлайн — 0 предупреждений; ветка полностью содержит
  `origin/dev` (ребейз произведён, конфликтов нет).
- AC3 количественно: индекс эталонов содержит ровно 16 новых + 2 изменённых
  хэша из 126 (сверено чтением `baselines-index.json`, не поверил на слово).

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

- Полный `demo/smoke_*.mjs` (189 файлов) и полный `npm run mutants`
  (~90 мутантов) — предрелизные гейты, задача не задевает всё; выборка
  обоснована в таблице выше.
- Локальный полный `python -m pytest tests_backend` — диф не трогает Python.
- Числовой перф-профиль large-house вручную не переснимал; доверился
  зелёному CI job `performance_smoke` на `b95c55d3` (подтверждено — не reuse).
- Не проверял три «зарегистрированные связи» смока `smoke_decor.mjs` и
  `smoke_space_scale_defaults.mjs` (символ `cellCm` — широко используемый,
  слабая связь по инструменту) — доверился их независимости от узловой
  механики по чтению кода (`cellCm` там используется вне контекста
  multi-wall-узлов).

## Вердикт

High: 0 · Medium: 2 (обе в скоупе) → возврат автору, без нового issue (#202).

Оба Medium дешёво чинятся: M1 — переписать один абзац
`docs/WALL-THICKNESS.md:188-196` под фактический контракт; M2 — добавить
build-префикс в guard одного мутанта и подтвердить «поймано 1 из 1»
исполнением. Ни одна находка не требует правки продуктовой геометрии —
сам механизм (AC1-AC5, AC7, AC9) проверен исполнением и корректен.