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

CODE-REVIEW-333-r1

Issue: #333 · Заход: r1 · Блокирующих циклов израсходовано 0 из 2 Материал: git log --oneline origin/dev..HEAD = один коммит c29df29b (fix: plan/optimize passes the junction gate; import stays free by design (#333)), родитель 73406225 (= origin/dev на момент проверки).

1. Скоуп

ТЗ (тело issue, small-трек, ревизия 2, оба раунда spec-ревью зелёные — docs/reviews/SPEC-REVIEW-333-r1.md, -r2.md) требует:

1. ws_plan_optimize вызывает validate_junction_limits(candidate, stored, …) внутри существующей executor-функции _validate_optimize_cpu, ПОСЛЕ миграции кандидата — наследование по правилу (легаси-нарушение проходит, новое — отказ junction_limit_<rule>).
2. Успешный optimize обновляет rt.junction_baseline счётчиками кандидата.
3. Import/restore остаются вне гейта; докстринг junction_limits.py и docs/specs/329-junction-limits.md §5 фиксируют периметр честно.

Продуктовая рамка (docs/SCOPE.md): изменение защищает контракт «карточка отказывает записи, ломающей П1–П5» (Core user jobs: геометрия остаётся валидной) от обхода через второй командный путь — попадает в скоуп. User-Visible: no в трейлере коммита корректен: поведение честного клиента не меняется (AC10 #329 уже доказывает, что оптимизация не добавляет нарушений), меняется только реакция на крафтовый payload.

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

Дешёвые гейты, на которые ссылался бриф ревью («Validate на c29df29b завершился success»), не могут считаться подтверждёнными — см. находку H1 ниже. Прогнал сам:

• npx tsc --noEmit — чисто.
• npm test — 1425 passed, 0 failed, 1 skipped (без изменений от базовой линии).
• npm run build + cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js — идентичны.
• node scripts/mutation-gate.mjs --check — реестр консистентен, новый мутант junction-limit-optimize-unguarded зарегистрирован корректно (patch-строка совпадает с реальным кодом).
• Ручная проверка «мутант умеет убивать»: применил patch мутанта (return validate_junction_limits(...) → return {}, None) к websocket_api.py, прогнал pytest tests_backend/test_ha_websocket.py -k test_333_optimize_refuses_a_crafted_violation — тест красный (assert not True), рабочее дерево вернул к исходному (git status чист). Тест умеет падать.
• python -m pytest tests_backend -q (полный бэкенд-набор, HA-харнес реально поднимается в этом окружении, вопреки заметке автора о песочнице) — 1 failed, 428 passed, 1 skipped, 1 error. Разбор ниже (находка H1).
• node scripts/smoke-select.mjs --base 73406225 --head c29df29b — «исполняемого frontend-диффа нет», браузерные смоки не выбираются (diff не трогает src/**) — решение подтверждено инструментом.
• check-docs / golden / invariants — не гонял, diff не трогает src/** и не меняет геометрию/ссылки на неё (только добавляет вызов уже существующего валидатора на втором командном пути); обоснование ниже, §4.

Не гонял и не буду: python -m pytest tests_backend -q уже покрывает паритет П1–П4 (test_junction_limits.py::test_parity_with_the_frontend_checks) без дополнительных прогонов.

3. Находки

H1 (High, в скоупе). Optimize новым гейтом ломает существующий бэкенд-тест — подтверждённая регрессия

plan/optimize на конфиге, который НИКОГДА не сохранялся (пустое config_data.get("config"), expected_config_rev: 0), теперь отказывает на junction_limit_length, если в кандидате есть хоть один сегмент короче 20 см — потому что для «предыдущего» состояния old_counts пуст, и существующее правило («первая запись не может прийти уже сломанной», junction_limits.py:415) считает любое нарушение новым.

Ровно это происходит с существующим (не тронутым этим диффом) тестом test_plan_optimize_persists_exact_storage_roundtrip_target (tests_backend/test_ha_websocket.py:599, фикстура test/fixtures/optimize-storage-roundtrip.json, тест — про #248, байт-точный роундтрип storage, а не про геометрию): пространство fine содержит комнату 6×6/12 «условных» см (специально крошечную — фикстура проверяет округление на разных cell_cm), после миграции в ней есть стена длиной 6 см — П3, минимум 20 см.

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

$ python -c "
from custom_components.houseplan.junction_limits import validate_junction_limits
import json
config = json.load(open('test/fixtures/optimize-storage-roundtrip.json'))['input']['config']
validate_junction_limits(config, None)
"
JunctionLimitError: space=fine; rule=length; subject=wall-2p5v3xgwtvsbainkhyk4; actual=6; limit=20

Доказано двумя прогонами полного pytest tests_backend/test_ha_websocket.py -k test_plan_optimize_persists_exact_storage_roundtrip_target:

• на родителе 73406225 (до фикса #333): 1 passed (плюс тот же фоновый teardown-ERROR, см. ниже — он не от этого коммита);
• на c29df29b (после фикса): 1 failed (assert response["success"] → False).

Это не «недостающий тест», это диффом сломанный существующий зелёный тест — полный набор pytest tests_backend -q на c29df29b красный (1 failed, 428 passed). Мёртвого запуска этого набора на CI сейчас не происходит (см. находку вне скоупа ниже), поэтому красный статус не был замечен автоматически, но ревью обязано было его поймать — и поймало.

Фикс — решение автора; правдоподобные варианты: (а) поправить фикстуру optimize-storage-roundtrip.json, вложив в тест уже сохранённое предыдущее состояние с тем же нарушением (echo-паттерн AC2), раз тест не должен проверять геометрию; (б) явно обсудить в ТЗ, должен ли plan/optimize как первая-когда-либо запись (config_rev==0) подчиняться тому же правилу, что и config/set — если да, чинится тест; если нет, гейту нужно исключение, и это уже требует правки контракта, а не только кода.

Блокирует. Verdict: жёлтый.

Вне скоупа (заведено отдельным issue)

Тестируя допущение брифа «Validate на c29df29b завершился success ⇒ tsc/ npm test/npm build уже подтверждены», обнаружил, что job'ы Фронтенд: типы, юниты, мутанты, синхрон бандла и Бэкенд: pytest в Home Assistant в этом прогоне — skipped, а не success; общий «success» рана этого не показывает. Причина — в классификации изменённых файлов (.github/workflows/validate.yml, job changes): BEFORE_SHA этого push ссылается на коммит, вышедший из истории веткой при force-push (аменд предыдущего пуша той же ветки, run 33145390451, cancelled), фолбэк на merge-base origin/dev HEAD разрешился так, что диапазон включил только два doc-коммита ревью и потерял сам код-фикс — backend/frontend вышли false, тяжёлые job тихо пропущены.

Дефект соседний (инфраструктура CI, не продуктовый код этой задачи) и не чинится в этой ветке. Заведён: #347 — ci: классификация файлов Validate теряет диапазон после force-push, тяжёлые job тихо skip'аются (labels: bug, infra, P1, S1-new, ссылка на #333).

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

• Контракт п.1 (вызов гейта в optimize). websocket_api.py:1609-1710: validate_junction_limits(msg["config"], config_data.get("config")) вызывается ПОСЛЕ CONFIG_SCHEMA/миграции кандидата (commit_wall_segment_model при необходимости) и после остальных семантических валидаторов, внутри _validate_optimize_cpu — то же место в конвейере, что и в config/set (websocket_api.py:1343). JunctionLimitError в except-списке (было мёртвым) теперь действительно ловится и транслируется в connection.send_error тем же стабильным кодом junction_limit_<rule>.
• AC1 (крафтовый payload). Тест test_333_optimize_refuses_a_crafted_violation_and_keeps_the_plan (tests_backend/test_ha_websocket.py:2388) прогнан — PASSED. Мутант подтверждён ручным патчем (см. §2). Хранимые config и rev побайтово не изменились после отказа — проверено ассертами теста. Layout-неизменность из формулировки AC1 тестом не проверяется явно, но гарантирована структурой кода: JunctionLimitError ловится ДО первого async_save_layout_state/async_save_config_state в функции — физически нечему меняться (см. Low-замечание ниже).
• AC2 (наследование в optimize). Тест test_333_optimize_inherits_stored_violations — PASSED: эхо-оптимизация пространства с унаследованным нарушением угла проходит. Согласуется с #329 AC10 (легаси-оптимизация не создаёт новых нарушений).
• AC3 (обновление кэша). Тест test_333_optimize_refreshes_the_junction_baseline_cache — PASSED: через recording-обёртку над validate_junction_limits подтверждено, что следующий config/set вызывается с baseline_counts из кэша (rt.junction_baseline), не пересчитывая previous. websocket_api.py:1783 (rt.junction_baseline = (int(new_config_rev), optimize_counts or {})) — симметрично строке 1396 в config/set.
• AC4 (докстринг/спека). Прочитал оба текста целиком: junction_limits.py:1-15 больше не обещает «hostile client cannot post» без оговорок — явно называет периметр (config/set и plan/optimize) и сознательно исключённый import/restore, с обоснованием (§3 #329: restore не блокируется никогда). docs/specs/329-junction-limits.md §5 (новый абзац, строки 127-134) — тот же периметр и тот же трейд-офф, ссылка на решение владельца 2026-08-28. Текст соответствует коду, догадок, выданных за решённое поведение, не нашёл.
• Паритет П1–П4 и остальной бэкенд. test_parity_with_the_frontend_checks и все прочие 424 теста tests_backend (кроме H1) прошли без изменений.
• Трейлеры коммита. Issue: #333, User-Visible: no — оба на месте, соответствуют характеру изменения (нет пользовательского поведения, видимого честному клиенту).
• Реестр мутаций. --check зелёный, новый мутант описан честно (because указывает на реальный риск — крафтовый optimize-payload легализует нарушение для будущих config/set).

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

• check-docs, golden:verify, browser-смоки — diff не трогает src/** вообще (только custom_components/**/*.py, docs/specs/*.md, scripts/mutation-gate.mjs, tests_backend/*.py); smoke-select.mjs подтвердил инструментом «исполняемого frontend-диффа нет». Рендер и геометрия не меняются — гейты не относятся к этому diff.
• npm run invariants — diff не меняет геометрию, рёбра комнат, записи толщины, layout, marker.space или open_spans; добавляет только вызов уже существующего Python-валидатора на втором командном пути. Инварианты модели тут не про что проверять.
• performance-профили — не названы в AC; #330 §4.1 уже вынесла всю дорогую цепочку (включая validate_junction_limits) в executor, это не трогается.
• Полный node scripts/mutation-gate.mjs (все мутанты) — избыточен: диффу соответствует ровно один новый мутант, он проверен точечно (ручной патч + прогон целевого теста), это дешевле и доказательнее, чем гонять весь реестр.
• HA-харнес — вопреки заметке автора («локальная песочница… не поднимает»), в ЭТОЙ ревью-сессии pytest-homeassistant-custom-component установился и харнес поднялся; воспользовался этим и прогнал реальные прогоны, а не читал код вслепую. Один посторонний ERROR на teardown каждого HA-теста (assert isinstance(thread, threading._DummyThread) or thread.name.startswith("waitpid-")) — известная нестыковка версии pytest-homeassistant-custom-component с Python 3.12 (первый поток теста назван иначе), воспроизводится одинаково и на родителе 73406225, и на c29df29b, до и после патча мутанта — не связан с этим диффом, тестовые тела он не затрагивает (различаю FAILED/PASSED в основном теле от ERROR в teardown).

6. Вердикт

Контракт ТЗ реализован технически точно (AC1–AC4 каждый по отдельности доказан тестом, который умеет падать), но диффом ломается несвязанный существующий тест — реальная, воспроизведённая регрессия уровня High. Правки ТЗ не требуется (если автор выберет чинить фикстуру/тест), либо требуется ревизия контракта (если выберет явно исключить «первую запись» из-под гейта optimize) — в обоих случаях нужен повторный код-ревью цикл.

Вердикт: жёлтый · заход r1 · блокирующих циклов 0/2 · High: 1 · Medium: 1 → #347