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

CODE-REVIEW-330-r2

Issue: #330 — «Ограничения стыков (#329) блокируют event loop HA и дёргают ресайз на больших планах» Этап: code (PROCESS.md §2.7) Заход: r2 · блокирующих циклов израсходовано 1 из 4 (до этого раунда) Ветка: issue/330-junction-limits-performance, HEAD ревью — 85636a65

0. Почему разбор полный, а не по дельте

Предыдущий вердикт (code-review r1, 2026-08-28T00:00:48Z) не назвал SHA, на котором он получен — это само по себе процессное упущение (см. ниже). Автор в ответном комментарии называет два SHA до финального ребейза: a7500973 (HEAD на момент публикации r1) и 7513f93d (докс-фикс, слитый до публикации вердикта). Оба объекта в текущем дереве отсутствуют:

$ git cat-file -t a7500973   → fatal: Not a valid object name
$ git cat-file -t 7513f93d   → fatal: Not a valid object name

Ветка была перебазирована на ушедший вперёд dev через мердж #62 («ребейз над мерджем i18n-registry», коммит 85636a65) уже ПОСЛЕ публикации r1. Это ровно исключение §7.2 из брифинга: «ребейз на ушедший вперёд dev — после ребейза это другой код». Пословный git diff <r1 SHA>..HEAD невозможен и не имел бы смысла — базовые деревья разошлись. Разбор ниже полный, по git diff origin/dev...HEAD, с явным закрытием находок r1 отдельным разделом.

Процессное наблюдение (не находка в код, не считается в M/H): ни в вердикте r1, ни в вердикте предыдущего code-review-раунда SHA не был назван текстом. Формат §7.2 этого не требует явно, но по факту это стоило времени на этот раунд — рекомендую в следующих раундах явно указывать SHA в теле вердикта, а не только в документе.

1. Скоуп

Диапазон origin/dev...HEAD, 31 файл, +1731/-258:

• custom_components/houseplan/junction_limits.py — линейный byNode-индекс П3, bucket-решётка П4, _migrated_spaces без ремиграции v9 (§4.6), space_violation_counts/baseline_counts (§4.2).
• custom_components/houseplan/websocket_api.py — цепочка валидаторов ws_config_set/ws_plan_optimize в async_add_executor_job (§4.1), запись/чтение rt.junction_baseline по rev (§4.2).
• custom_components/houseplan/store.py — новое поле рантайма junction_baseline.
• src/junction-limits.ts — те же три среза на фронте (byNode-индекс, bucket-решётка, зеркальная логика).
• src/houseplan-card.ts — _junctionLimitViolations принимает sharedGeometry (§4.7, общий проход топологии/кладки на все комнаты), _junctionLimitsIntroduced — кэш baseline по (identity, _cfgEpoch) (§4.4) и путь «v9 как есть» (§4.6 на фронте).
• demo/benchmark_junction_limits.mjs, package.json, .github/workflows/validate.yml — новый перф-контракт §5/AC7, вшитый в job performance_smoke (не только в еженедельный mutation-gate.yml).
• demo/smoke_junction_limits.mjs — счётчик вызовов _junctionLimitViolations за один жест ресайза (заявленная поведенческая часть AC4).
• scripts/mutation-gate.mjs — три новых мутанта (П3, П4, «протухший baseline-кэш»).
• test/junction-limits.test.mjs, tests_backend/test_junction_limits.py, tests_backend/test_ha_websocket.py — юниты эквивалентности и AC1.
• docs/CHANGELOG.md/.ru.md — одна строка, User-Visible: yes, в том же коммите (c90f5bf0), что и код.
• Скриншоты/screenshots.json — механический пересчёт отпечатка (src/** изменился), содержимое интерфейса не менялось.

Вердикты П1–П5 не меняются нигде в дифф — заявление автора подтверждено чтением: единственная содержательная логика (_length, _distance_to_segment, условия нарушений, epsilons) не тронута; менялись только структуры данных вокруг неё (индексация, кэш, порядок обхода).

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

Все команды выполнены на этом SHA в этой рабочей копии; результат — вывод ниже, не «verified» без числа.

Гейт	Команда	Результат
Типы	npx tsc --noEmit	чисто, без вывода
Юниты фронта	npm test	1419 passed, 1 skipped, 0 failed
Юниты бэкенда (чистый python, без HA)	python3 -m pytest tests_backend/test_junction_limits.py -q	13 passed
Юниты бэкенда (HA-харнесс)	python3 -m pytest tests_backend -q (pytest-homeassistant-custom-component установлен в этой сессии)	423 passed, 1 skipped, 1 error — ошибка теardown (_run_safe_shutdown_loop thread-leak assert) воспроизводится и на НЕ тронутом этой веткой тесте (test_issue_244_...) при отдельном прогоне того же файла — окружение, не диффа. Тест AC1 (test_330_config_set_validators_run_in_the_executor) прошёл исполнением: 1 passed.
Перф-контракт §5/AC7	npm run benchmark:junction-limits	pass: true; tsFullCandidateMs 150.7/400 (2.65×), pyWarm 67.1/300, pyCold 2463/5000
Сборка + идентичность бандла	npm run build + git status --short (чисто) + diff dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js	идентичны, git status чист после ребилда
Докс-гейт	node scripts/check-docs.mjs	«Documentation checks passed (7 files, 10 external links)»
Инварианты модели	не гонял отдельной командой — npm test уже включает test/model-invariants.test.mjs на всех моделях проекта (зелёный); задача не вводит новую конфигурацию для точечной проверки npm run invariants -- --config
Смок-выборка	node scripts/smoke-select.mjs --base origin/dev --head HEAD → 7 прямых совпадений + 1 «зарегистрированная связь» (см. §3)	все 8 + 3 названных в AC6 (island_rooms, room_resize, resize_pointer_real_plan) прогнаны — 11/11 OK (после node scripts/bundle-sync.mjs, без которого demo/srv/assets/houseplan-card.js отсутствовал и смоки падали таймаутом на билд, не на код)
Мутационная проверка (ручная, не полный mutation-gate.mjs)	вручную применил 3 патча из scripts/mutation-gate.mjs (П3-снова-квадратичен, П4-снова-перебор, протухший baseline-кэш) и прогнал их guard-команды	П3 и П4 ловятся бенчем (pass:false, tsSegmentLengthsMs 402.6/60 и tsNodeDistancesMs 207.4/80 соответственно); третий мутант — см. находку M1 ниже, там дисциплина «тест умеет падать» провалилась на смоке
golden	не гонял	diff не трогает рендер/геометрию/стили/слои — только порядок вычислений и кэш валидатора; визуальный результат не может измениться этим кодом
performance-профили сверх §5	не гонял	не названы в AC сверх §5/AC7

3. Смок-выборка — вывод инструмента

Изменено файлов src/**: 2 · символов на изменённых строках: 17
Прямое совпадение (7): smoke_junction_holes, smoke_decor, smoke_glow_fail_dark,
  smoke_glow, smoke_grid_scale_invariance, smoke_junction_limits, smoke_space_scale_defaults
Зарегистрированная связь (1): smoke_real_plan_masonry ← wallBodiesGeometry

Плюс три смока, названных в AC6 автором (island_rooms, room_resize, resize_pointer_real_plan) — не входят в прямые совпадения инструмента для этого diff, но названы в AC, поэтому прогнаны. Итог: 11 смоков, все OK.

4. Находки

M1 (в скоупе) — заявленная «поведенческая половина» AC4 не различает наличие и отсутствие кэша

Файл: demo/smoke_junction_limits.mjs:185-217; коммит c90f5bf0 и подтверждающий комментарий автора («Поведенческая половина AC4 (N move → N+1 вычислений на настоящем pointer-жесте)»).

Смок считает вызовы _junctionLimitViolations за весь жест ресайза и проверяет resizeBaselineCachedPerGesture = jlCalls > 0 && jlCalls <= 12. Я вручную воспроизвёл ровно тот мутант, что заведён в scripts/mutation-gate.mjs под id junction-limit-baseline-cache-stale (отключил запись в _junctionBaselineCache — кэш никогда не срабатывает, baseline пересчитывается на каждый move) и прогнал сам смок (не юнит, который guard мутанта вызывает вместо него):

DEBUG jlCalls= 12    (кэш полностью отключён)
DEBUG jlCalls= 11    (немодифицированный код, кэш работает)
OK                   (оба раза)

Разница между «кэш работает» и «кэш полностью выключен» — один вызов из двенадцати, и порог <= 12 пропускает оба случая. Смок физически не может отличить рабочий кэш от полностью удалённого — он зелёный в обоих случаях. Причина в том, что счётчик window.__jlCalls ловит вообще все обращения к _junctionLimitViolations за время жеста (включая вызовы вне _junctionLimitsIntroduced, например из рендера/подсветки), а не только экономию на baseline — сигнал тонет в шуме, и заявленная арифметика «N+1 против 2N» на практике не воспроизводится этим жестом ни при каком разумном пороге.

Это ровно тот класс дефекта, который автор сам поймал для ЮНИТ-теста тем же приёмом в 7aaf5a72 («тест умеет падать» — контракт перепрятали в проверку по исходнику именно потому, что первая версия юнита не ловила мутанты). Для смока тот же самоконтроль не был применён: заявление в коммите, что поведенческая защита AC4 «живёт в смоке», не подтверждается.

Фактическая защита AC4 сейчас — только regex-проверка по исходнику (test/junction-limits.test.mjs:380-399, ищет литеральную строку cached.epoch === this._cfgEpoch). Она реально работает как барьер (я проверял: мой мутант меняет именно эту подстроку и юнит падает), но это защита от одной конкретной формы регресса (удаление/подмена этого сравнения в тексте), а не от логической. Сама РЕАЛИЗАЦИЯ кэша в продакшен-коде корректна — я прочитал _junctionLimitsIntroduced (houseplan-card.ts:7503-7549) и логика верна: WeakMap по identity previousConfig, инвалидация по _cfgEpoch, который сам ведёт себя как установившийся паттерн в этом файле (бампается в ~30 местах при любом реальном изменении _serverCfg/эпизода редактирования). Это находка про КАЧЕСТВО ТЕСТА, а не про баг в фиче.

Почему в скоупе и Medium: AC4 ТЗ требует доказательства «жест ресайза считает baseline один раз»; заявленное доказательство decorative. Без High это возвращается автору жёлтым, а не заводится отдельным issue — находка про код и тесты ЭТОЙ задачи, не соседнего поведения.

Что нужно поправить: либо ужесточить порог до значения, которое реально разделяет 11 и 12 (например, точное равенство ожидаемому числу вызовов для конкретной синтетической последовательности mouse.move — тогда и сам тест обязан быть проверен на этом же мутанте), либо честно переформулировать комментарий/заявление AC4: поведенческая защита не добавляет покрытия сверх юнита по исходнику, и это нужно признать в документе, а не заявлять как отдельную гарантию.

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

Находка r1	Чем закрыта	Где видно
H1 — докс-гейт красный (screenshots.json/PNG не из одного прогона)	Уже было закрыто 7513f93d до публикации вердикта; после второго ребейза (85636a65) фингерпринт и PNG пересобраны ещё раз тем же правилом	node scripts/check-docs.mjs → «Documentation checks passed» на этом SHA (проверено мной заново)
H2 — бюджеты §5 калиброваны с запасом 1.14× вместо 2-3×, бенч не в CI-воркфлоу	Таблица замеров с обеих машин, бюджеты пересчитаны от худшей; шаг npm run benchmark:junction-limits добавлен в job performance_smoke в validate.yml	.github/workflows/validate.yml:543-547; сам прогон на этом SHA — pass:true, запас 2.65× (150.7/400)
M1 — обещанный AC1-тест на самом деле мерил только тёплый validate_junction_limits, не websocket_api.py/hass	Новый тест test_330_config_set_validators_run_in_the_executor патчит validate_junction_limits обёрткой-шпионом внутри реального HA-харнесса, вердикты (принято/отклонено junction_limit_angle) сверены	tests_backend/test_ha_websocket.py:2322-2385; я прогнал его исполнением (pytest -k 330 → 1 passed), не только чтением
M2 — §4.6-эквивалентность фронта проверена только текстовым паттерном; python-паритет на одной фикстуре	Три граничные фикстуры (as-is==through-migration) на TS (test/junction-limits.test.mjs:401) и на python (tests_backend/test_junction_limits.py:423, три полигона: spike/box/narrow)	Оба набора прогнаны: TS — часть зелёного npm test; python — часть зелёного pytest tests_backend/test_junction_limits.py (13/13)

Все четыре находки r1 закрыты по существу, подтверждено исполнением (не только чтением) там, где это было в моих силах в этой песочнице.

6. Унаследовано из r1 (без повторной проверки)

• Общая архитектура срезов §4.1–§4.6 (rev-кэш, byNode-индекс П3, «v9 как есть» §4.6) — признана в code-review r1 корректной по коду и эквивалентной по вердиктам; в этом раунде я перечитал тот же код заново (диф не менялся с r1 в этой части, кроме docs/CHANGELOG и бенч-калибровки) и подтверждаю тот же вывод самостоятельно, а не по доверию к r1 — это не наследование, а совпавший результат независимой проверки.
• Ничего из r1 не наследуется слепо: поскольку исходный SHA r1 недостижим после ребейза (см. §0), весь код перечитан заново в этом раунде, а не предположен на основании старого вердикта.

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

• Эквивалентность вердиктов П1–П5 до и после — не изменилась ни в одной строке содержательной логики; подтверждено чтением и параллельно зелёными паритет-тестами TS↔Python (test_parity_with_the_frontend_checks, уже существовавший до #330, прошёл в составе 13/13).
• Bucket-решётка П4: прочитал построчно оба зеркала (junction_limits.py:223-291, junction-limits.ts:188-247|); граничный случай (узел и сегмент в соседних ячейках решётки, но ближе порога) закрыт паддингом bbox сегмента на min_units и проверен тестом test_330_p4_bucket_matches_bruteforce_on_cell_borders (4 кейса, включая ровно 4 и 5 см от порога) — прогнан, зелёный. Ассиметрия «узел проверяется в 9 соседних ячейках, сегмент — только в своей» корректна по построению: паддинг сегмента компенсирует то, что для узлов (точек) эквивалентного паддинга нет.
• §4.6 «v9 как есть»: перечитан барьер в websocket_api.py:1325 (schema всё равно валидирует документ целиком независимо от пропуска ремиграции) — риск «подделать v9 без каталога» закрыт независимо от нового теста.
• Executor-обёртка в ws_config_set/ws_plan_optimize: write_lock держится вокруг await, поэтому сериализация записей не нарушена; ошибка too_large в ws_plan_optimize корректно вынесена из executor-функции обратно в вызывающий код перед connection.send_error (сеть — дело event loop, не executor-потока).
• rt.junction_baseline: инвалидация «по факту», а не по всем путям записи — ws_plan_optimize не обновляет кэш вовсе (и не обязан: он не проверяет ограничения стыков ни до, ни после #330 — не регрессия), поэтому следующий config/set просто промахнётся по rev и пересчитает previous с нуля; корректность не зависит от того, кто ещё пишет rev.
• §4.7 общий проход: preflight.wallGeometry, переданный в _junctionLimitsIntroduced как candidateGeometry, построен (_rszSpaceCandidateGeometry) из ТОЙ ЖЕ пары (spaceId, sp), что и limitCandidate — не подмена по случайному кэшу; проверено чтением обеих функций (houseplan-card.ts:9104-9121, 9156-9175).
• CHANGELOG — одна строка в обоих файлах, в том же коммите (c90f5bf0), что и код, при User-Visible: yes.
• Одно число — один источник: diff не добавляет и не меняет ни одной видимой пользователю величины (только внутренние тайминги/пороги бенчмарка, невидимые пользователю) — раздел неприменим.

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

• golden:verify — не гонял; diff не трогает рендер, геометрию, стили или слои, только порядок/кэш вычислений валидатора стыков.
• Полная матрица demo/smoke_*.mjs (194 шт.) — не гонял; задача не меняет ничего, что затрагивает широкие символы (_cfgEpoch, _serverCfg, _space инструмент явно исключил как «не широкие» в данном случае), 11 выбранных/названных в AC смоков — зелёные.
• benchmark_safe_resize — не гонял; это тот самый бенч, про который spec-review r1 (H2) установил, что он не вызывает код лимитов вообще — нерелевантен этой задаче.
• Полный scripts/mutation-gate.mjs прогон (все ~40+ мутантов) — не гонял; это еженедельный гейт (PROCESS.md §8), не гейт ревью. Три НОВЫХ мутанта проверил вручную построчно (см. §2, §4) — этого достаточно для вопроса «умеет ли тест, который я прогонял, падать».
• npm run invariants -- --config <...> отдельной командой — не гонял; задача не вводит новую конфигурацию/фикстуру геометрии за пределами того, что уже покрыто npm test (который включает model-invariants.test.mjs на моделях проекта).
• Ручное тестирование в браузере — вне цикла ревью по регламенту; браузерные смоки — единственная замена, они прогнаны.

9. Итог

Один Medium в скоупе (M1 — заявленная поведенческая защита AC4 не дискриминирует регресс, эмпирически подтверждено), High нет. Основная перф-архитектура (§4.1–§4.7), эквивалентность вердиктов и перф-контракт §5 подтверждены исполнением, а не только чтением или доверием к предыдущему раунду.