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

CODE-REVIEW-278-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/278
• Этап: код-ревью, заход r1, блокирующих циклов израсходовано 0/4
• Проверяемый диапазон: origin/dev...HEAD (HEAD = 495043791e0fa916708f832248f13dfacf23dbdc, ветка issue/278-wall-union-isolation)
• Спецификация: docs/specs/278-wall-union-isolation.md (зелёное ревью ТЗ, r2)
• Вердикт: жёлтый · High: 0 · Medium: 1 (в скоупе, чинится в этой же задаче)

Скоуп

Локальный сбой boolean-объединения одного extra-body (partition/column/draft/ exterior-shell merge) в wallBodiesGeometry() не должен гасить всю кладку пространства. Диапазон реализует:

• типизированный structural result (ok/degraded-extra/failed-core/ not-applicable) с per-extra transactional изоляцией и components[];
• render-safe проекцию (wallBodiesUnionPath → paths[], отдельные SVG-path на компонент, без объединения в один evenodd-путь);
• единый strict commit barrier (checkSpacePhysicalGeometry / _commitPhysicalGeometry) для всех geometry writers (§7 ТЗ), с откатом, 0 WS/Undo при отказе и локализованным toast;
• parity потребителей: full Plan/View, Static, hidden Iso, Glow/light barrier
  • source guard, sun (через roomGeom);
• production-структурную проверку в model-invariants.mjs (тот же checkOptimizeGeometry, что и Optimize);
• анонимизированную regression-фикстуру, unit/permutation/golden/smoke/ benchmark/mutation-покрытие, RU/EN toast и changelog/доки.

Соответствует J1/J4/J6 из docs/SCOPE.md — устраняет полное визуальное исчезновение архитектуры для персоны Household members/Guests (View — «продукт» для этих персон), не расширяя скоуп продукта.

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

Все дешёвые гейты (§8) прогнаны заново на этом заходе; тяжёлые — точечно, по диффу/AC, с решением по каждой строке.

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный, без вывода
Unit	npm test	1204/1204 pass, 0 skip, 0 fail (см. «Расхождение с хендоффом» ниже)
Build + 3 копии бандла	npm run build && npm run bundle:sync + cmp dist/, custom_components/houseplan/frontend/, demo/srv/assets/	все три побайтово идентичны
Docs fingerprint	node scripts/check-docs.mjs	«Documentation checks passed (7 files, 10 external links)» — diff трогает src/**, гейт обязателен
Model invariants (плохая фикстура)	npm run invariants -- --config test/fixtures/278-wall-union-isolation.json	exit 1, wall-degraded-extra — AC10 доказан на реальной команде, не заявлением
Model invariants (контрольная валидная фикстура)	npm run invariants -- --config <276-coincident-partition config>	exit 0, ложного срабатывания нет
Смок, названный в AC/диффе	node demo/smoke_wall_union_isolation.mjs	OK, все 11 внутренних проверок true
Дисциплина «тест умеет падать»	ручной мутант: status: ... ? 'degraded-extra' : 'ok' → 'failed-core', пересборка бандла, повторный прогон смока	смок падает с TypeError: Cannot read properties of null (reading 'components') — реальный крах, не тихий зелёный; дерево и бандлы восстановлены, git status чист
smoke-select.mjs (обязательная выборка)	node scripts/smoke-select.mjs --base origin/dev --head HEAD	34 прямых совпадения, 15 слабых; полный список см. «Смоки» ниже
Смоки-соседи той же геометрической подсистемы	smoke_multiwall_junction, smoke_wall_key_roundtrip, smoke_wall_junctions, smoke_free_walls, smoke_zero_divider_taper, smoke_partition_openings	все OK — регрессии в родственных фичах wall-thickness нет
Performance (AC13)	node demo/benchmark_wall_union_isolation.mjs (test-build пересобран fix-test-build.mjs)	valid overhead p95 0.099 ms (лимит 20 ms), relative p95 0.324 ms ≤ лимит 0.330 ms, degraded p95 17.6 ms (лимит 100 ms) → pass: true
Golden (визуальный результат меняется)	npm run golden:verify (полный прогон — флаг --grep не поддерживается demo/golden/run.mjs, ушёл в полный набор)	все просмотренные сцены passed, включая новые wall-union-isolation-view-light/dark и соседние wall-junctions-*, multiwall-junction-bevel-view-dark, wall-key-roundtrip-view-dark, junction-patch-resilience-*
Mutation-gate, реестр	node scripts/mutation-gate.mjs --check	все патчи ложатся ровно один раз, guard-файлы существуют
Mutation-gate, один из 5 новых id живьём	node scripts/mutation-gate.mjs --id=wall-component-failure-kills-primary	команда с --id без = не отфильтровала реестр и упёрлась в отсутствующий pytest на несвязанном backend-мутанте (окружение, не дефект #278); заменено эквивalентной ручной проверкой (см. выше «тест умеет падать» — тот же патч, тот же guard-смок, тот же результат)
Commit-трейлеры	git log по всем 8 коммитам диапазона	Issue: #278 и User-Visible: на каждом; Baseline-Reviewed на обоих коммитах, трогающих demo/golden/baselines/**; User-Visible: yes (8156f801) правит docs/CHANGELOG.md и docs/CHANGELOG.ru.md в том же коммите

Расхождение с хендоффом (не находка, для полноты)

Хендофф автора заявляет «1204 теста: 1203 pass, 1 штатный skip». Локальный прогон дал 1204 pass, 0 skip. Число тестов совпадает, распределение pass/skip — нет. Похоже на окружение-зависимый skip (например, недоступный в CI, но доступный здесь ресурс), не влияет на вердикт: интересующие #278 тесты (wall-thickness, plan-geometry-preflight, wall-union-isolation) все зелёные и не входят в подозреваемый skip.

Находки

Medium (в скоупе, чинится в этой же задаче)

M1 — docs/TESTING.md называет несуществующие id мутантов.

Файл: docs/TESTING.md, блок AC для issue #278 (после строки «Optimize и model-invariants reject the same fixture…»).

Чек-лист перечисляет 5 mutation-id для этого пункта:

`wall-component-failure-kills-primary`,
`isolated-wall-extra-discarded`, `strict-accepts-degraded`,
`wall-thickness-writer-bypasses-barrier`,
`invariants-bypasses-production-geometry`

Фактический реестр scripts/mutation-gate.mjs (проверено --list и --check) содержит другие имена для 4 из 5:

В TESTING.md	Реально в mutation-gate.mjs
wall-component-failure-kills-primary	wall-component-failure-kills-primary ✓ совпадает
isolated-wall-extra-discarded	wall-isolated-extra-discarded
strict-accepts-degraded	strict-wall-barrier-accepts-degraded
wall-thickness-writer-bypasses-barrier	wall-thickness-writer-bypasses-common-barrier
invariants-bypasses-production-geometry	model-invariants-bypasses-production-geometry

Воспроизведение:

$ node scripts/mutation-gate.mjs --check --id=isolated-wall-extra-discarded
мутант «isolated-wall-extra-discarded» не объявлен; --list покажет реестр

Тот, кто пойдёт по docs/TESTING.md проверять пункт #278 командой node scripts/mutation-gate.mjs --id=<имя из чек-листа>, получит отказ на 4 из 5 команд. Это прямое нарушение AC15 («RU/EN changelog и user/wall/architecture/ testing/status docs актуальны») — сам код и сами мутанты корректны (реестр проходит --check, а wall-component-failure-kills-primary независимо воспроизведён вручную выше), дефект только в тексте TESTING.md. Severity — Medium: не влияет на поведение продукта и не показывает, что сам механизм защиты не работает, но делает канонический тест-чеклист нечитаемым машиной и вводит в заблуждение человека. В скоупе задачи (TESTING.md — часть release-артефактов, перечисленных в ТЗ §17), чинится правкой пяти строк в этом же issue, без нового issue (решение владельца 2026-08-19, #202).

Требуется: привести 4 id в docs/TESTING.md к точным именам из scripts/mutation-gate.mjs.

Проверка AC1–AC15

AC	Статус	Как проверено
AC1	✅	test/wall-union-isolation.test.mjs — фикстура даёт degraded-extra, не global null; прогнано npm test
AC2	✅	test/wall-thickness.test.mjs (#278 permutation test) + ручное прочтение цикла extraBodies в wallBodiesGeometry() (try/catch per-index, isolated.push, следующие extras продолжают обрабатываться)
AC3	✅	код: невалидный extra (extra.length < 3, non-finite, polygonArea ≤ 1e-9) инкрементирует degradedExtraCount и continue, не бросает core; failed-core остаётся отдельным catch-блоком снаружи per-extra цикла — проверено чтением
AC4	✅	_renderWallBodies/space-render.ts рисуют united.paths/canonicalWallGeometry.paths отдельными <path> per component (не склеены в один evenodd-path); подтверждено golden wall-union-isolation-view-{light,dark} (passed) и смоком
AC5	✅	построчно проверены все 4 продакшн-потребителя: hidden Iso (_isoSource().build() → united.components.flatMap), Glow/light barrier + source-guard (_lightBarriers → masonry.components → masonryGeometry → pointInOpaquePlanBody), Static (space-render.ts canonicalWallGeometry.paths), Plan/View (_renderWallBodies); roomGeom подтверждённо не включает extras (test/wall-thickness.test.mjs: roomGeom.length === 0 при двух extras)
AC6	✅	checkOptimizeGeometry трактует degraded-extra/failed-core как status:'failed'; unit test/wall-union-isolation.test.mjs («Optimize и model-invariants используют один strict result»)
AC7	✅	все перечисленные в §7 ТЗ писатели физической геометрии сведены к _commitPhysicalGeometry/_applyGeometryState; инвентарный regex-тест test/wall-union-isolation.test.mjs («production source routes physical writers») проверяет 14 history-ключей; смок smoke_wall_union_isolation.mjs подтверждает rollback + toast + 0 WS/Undo вживую на бандле
AC8	✅	decor/backdrop/marker/settings-правки (12 мест _recordGeometry+_saveConfig вне _commitPhysicalGeometry) прочитаны построчно — ни одно не меняет rooms/walls/open_spans/openings/partitions/room_drafts/wall_columns; смок: nonGeometryEditBypassesStrictBarrier: true
AC9	✅	_writeConfig() перепроверяет spacePhysicalGeometryFingerprint перед фактической записью и делает 0 WS-вызовов при отказе; unit checkSpacePhysicalGeometry-тесты + прочтение _pendingPhysicalWrites lifecycle
AC10	✅	npm run invariants -- --config <fixture> лично прогнан на плохой (exit 1, wall-degraded-extra) и на валидной контрольной (exit 0, без ложных срабатываний) фикстурах
AC11	✅	npm test включает существующие #197/junction/fail-dark регрессии — все зелёные; golden junction-patch-resilience-*, wall-junctions-*, multiwall-junction-bevel-view-dark пройдены заново
AC12	частично ✅	реестр --check подтверждает целостность 5 новых id; wall-component-failure-kills-primary независимо воспроизведён вручную (мутант убивает smoke_wall_union_isolation); остальные 4 не прогнаны через mutation-gate.mjs --id= из-за отсутствующего pytest в окружении на несвязанном шаге реестра — см. «Чего не проверял»
AC13	✅	node demo/benchmark_wall_union_isolation.mjs лично прогнан, все три бюджета §13 выполнены с запасом
AC14	✅	tsc/test/build/bundle-сверка/смоки — зелёные (таблица выше)
AC15	⚠️ Medium M1	CHANGELOG RU/EN, USER-GUIDE RU/EN, WALL-THICKNESS.md, ARCHITECTURE.md, CANVAS.md, STATUS.md — точны и соответствуют коду и терминологии docs/USER-GUIDE.ru.md; TESTING.md содержит 4 неверных id мутантов (M1)

«Одно число — один источник»

В диффе нет новой числовой величины, которую видит пользователь дважды: toast — фиксированная строка без чисел, USER-GUIDE-правки не вводят числовых полей. Единственные числа в диффе — внутренние performance-бюджеты (не пользовательский UI) и хэши golden-эталонов. Правило не нарушено.

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

• Типизированный результат wallBodiesGeometry()/wallBodiesUnionPath() корректно заменяет старый null-контракт; happy-path (status: 'ok') математически не меняет прежнюю геометрию — единственный компонент {id:'primary', geom: primary} даёт тот же d, что и раньше (подтверждено отсутствием регрессий в golden/smoke соседних сценариев: wall-junctions, multiwall-junction, wall-key-roundtrip, zero-divider-taper, free-walls, partition-openings).
• Изоляция exterior-shell merge (core) отделена от изоляции extras и не использует один и тот же catch — degradedCoreCount/isolatedCore собираются отдельно, что верно отражает контракт «room masonry остаётся fail-closed, а exterior shell может стать отдельным компонентом» (§5.4 ТЗ, AC3).
• #277→#278 порядок merge подтверждён по git log origin/dev: коммиты #276/#277 уже в dev до ветки #278; временный adapter Resize (!!this._wallUnionGeometry() / _checkOptimizeGeometry на весь план) заменён на точный _checkSpacePhysicalGeometry(candidate, preview.space) — риск «adapter переживает merge» (риск-таблица ТЗ №3) закрыт в этом же коммите, не оставлен.
• model-invariants.mjs осознанно нарушает собственный старый принцип «не импортирует src/**» — задокументировано в комментарии модуля и в docs/ARCHITECTURE.md; npm run invariants включает шаг сборки test-build, так что это не ломает автономность CLI по факту вызова.
• Фикстура test/fixtures/278-wall-union-isolation.json анонимна (только синтетические id/координаты, provenance присутствует), не содержит пользовательских строк.
• Мутационная дисциплина: лично собранный «зелёный, но неверный» мутант (замена degraded-extra→failed-core в возвращаемом статусе) реально ломает smoke_wall_union_isolation.mjs — findings §12 подтверждены не только по тексту реестра.

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

• 4 из 5 новых записей mutation-gate.mjs не прогнаны через полноценный --id=<mutant> (перестройка worktree + бандла на мутанте): у самого инструмента без флага = в этом окружении отсутствует pytest (/usr/bin/python3: No module named pytest) на несвязанном backend-мутанте раньше по реестру, и полный прогон уходит в таймаут раньше, чем добирается до нужных пяти id. Заменено точечной ручной проверкой одного из пяти (wall-component-failure-kills-primary) с тем же продакшн-смоком в роли guard — она реально покраснела. Оставшиеся 4 (wall-isolated-extra-discarded, strict-wall-barrier-accepts-degraded, wall-thickness-writer-bypasses-common-barrier, model-invariants-bypasses-production-geometry) проверены только чтением соответствующих unit-тестов (test/wall-thickness.test.mjs, test/plan-geometry-preflight.test.mjs, test/wall-union-isolation.test.mjs) и подтверждением, что патч ложится ровно один раз (--check), без фактического red/green прогона мутанта. Это предрелизный гейт (§8), не обязательный для этого раунда, но фиксирую прямо, а не молчу.
• Не пересмотрены визуально сами PNG golden-эталонов (принято на слово Baseline-Reviewed-трейлеру и тому, что npm run golden:verify подтвердил соответствие текущего рендера принятым хэшам с указанными допусками).
• Не запускался python -m pytest tests_backend — диапазон не трогает custom_components/houseplan/**/*.py (git diff --stat подтверждает отсутствие таких файлов), гейт неприменим.
• Полный demo/smoke_*.mjs-набор (178 файлов) не прогонялся целиком — прогнаны все «прямые совпадения», прямо относящиеся к теме (wall union/extra bodies/geometry barrier), плюс контрольная выборка родственных wall-thickness-смоков (6 файлов). Не прогнаны остальные ~28 «прямых» совпадений smoke-select, чьи общие символы — исключительно широкие кеш-поля (_frame, _modelCache, _saveConfig), не специфичные для #278 (например smoke_dialog_footer_width, smoke_pan_any_zoom, smoke_canvas_frame) — с низким риском регрессии, так как happy-path геометрии байтово не изменился (см. «Что проверено»); 15 «слабых» совпадений не прогонялись вовсе.
• golden:verify выполнен полным набором (108 сцен) случайно — флаг --grep не поддерживается demo/golden/run.mjs (только --scenario=); раз уж полный прогон уже состоялся и завершился зелёным, использую его как дополнительное (избыточное для этого раунда) подтверждение отсутствия визуальных регрессий, а не как обязательный для этого раунда гейт.

Итог

Blocking (High) находок нет. Одна Medium-находка в скоупе задачи (M1, docs/TESTING.md) — по правилам §2.7/#202 не создаёт отдельный issue, возвращается автору в рамках текущего issue #278. Технический контракт, изоляция per-extra, единый strict barrier, parity потребителей и все проверяемые тестами AC — реализованы корректно и подтверждены не только чтением, но и запуском гейтов и одним живым мутационным экспериментом.