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

CODE-REVIEW-291-r1

• Issue: #291 «Барьер записи координат: убрать шум как явление»
• Этап: код-ревью (PROCESS.md §2.7), заход r1 (первый заход код-ревью; ревью ТЗ прошло отдельно, 3 захода, зелёное на r3 — сюда не засчитывается, §10.4 «цикл считается по этапу»)
• Диапазон: 10fa0dc7..81d2a801 (merge-base с origin/dev .. HEAD ветки issue/291-lattice-coordinate-barrier), 10 коммитов, 37 файлов, +2374/-328
• ТЗ: docs/specs/291-lattice-coordinate-write-barrier.md, зелёное ревью SPEC-REVIEW-291-r3.md
• Ревьюер: свежая сессия, без контекста реализации; артефакты читаны из ветки, а не со слов автора

Скоуп

Единый барьер записи, приводящий координаты, лежащие ближе 1e-4 шага сетки к узлу k/240, к точному double этого узла — во frontend и backend, в layout и config, с отдельным отчётом Optimize и защитой от обхода. Не входит: смена схемы хранения, #288/#289/#290, union-алгоритм #278, снап авторской off-grid геометрии. Это первый код-ревью раунд — предмет разбора полный, дельты по предыдущему раунду нет.

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

Гейты по PROCESS.md §8, соразмерно задаче (диапазон трогает src/**, custom_components/**/*.py, геометрию и ссылки на неё):

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный
Unit	npm test	1232 passed, 1 skipped, 0 failed
Build + bundle parity	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	node scripts/model-invariants.mjs --config <real-plan-first-floor.json как config> --lattice (сам, до и после canonicalizeConfigGeometry)	до барьера: шум 66.15% (127/192), совпадает по порядку с измерением issue (65.38%/78.77%); после барьера: шум 0 (0.00%), законно вне сетки 2 (1.04%) — воспроизводит формат AC3 буквально; второй прогон канонизации байт-в-байт идентичен первому (AC1/AC4 idempotence на живых данных, исполнено, не только прочитано)
Model invariants (violations)	node scripts/model-invariants.mjs --config <migrated>	«Инварианты выполнены»; 2 наблюдения (exact-endpoint fallback) — не нарушения, не относится к #291
Mutation gate (структурная проверка)	node scripts/mutation-gate.mjs --check	все 180 патчей (включая 6 новых lattice-мутантов) применяются к текущему коду ровно один раз
Mutation gate (полный прогон, выборочно)	--id=lattice-round-truncates, --id=frontend-writes-raw-coords	оба: мутант применён → именованный тест покраснел, гейт зафиксировал ловлю. --id=optimize-config-storage-half-raw (backend-мутант, переиспользованный из #248 для «direct backend Store bypass») упал на отсутствии pytest/homeassistant в этой среде — не показатель дефекта, показатель среды (см. «Не проверял»)
Performance (AC11)	node demo/benchmark_coordinate_write_barrier.mjs	ratio 0.666 (лимит 1.2) — независимый локальный прогон, не только цифра автора (0.823, тоже под лимитом)
Smoke — выбор	node scripts/smoke-select.mjs --base origin/dev --head HEAD	3 «прямых совпадения» (cellCm) + 1 «зарегистрированная связь» (repairSpaceReferences) — вывод приложен ниже
Smoke — по AC	node demo/smoke_lattice_write_barrier.mjs, node demo/smoke_optimize_coordinate_canonicalization.mjs	оба OK, все под-проверки true
Smoke — по выбору	smoke_decor, smoke_grid_scale_invariance, smoke_space_scale_defaults, smoke_orphan_space_references	все OK
Backend	python -m pytest tests_backend/test_coordinate_canonicalization.py -q	не выполнено — в среде ревью нет homeassistant (ModuleNotFoundError), см. «Не проверял»
Golden	не прогонялся	сознательное решение, см. «Не проверял»
Полный набор смоков (182 файла)	не прогонялся	вне объёма код-ревью (PROCESS.md §8: «полные наборы — предрелизный гейт»)
Process gate	node scripts/process-gate.mjs --github-range --issues локально на HEAD	«гейт пройден, предупреждений 0»

Вывод smoke-select.mjs:

Изменено файлов src/**: 3 · символов проекта на изменённых строках: 26
Прямое совпадение (3): smoke_decor.mjs ← cellCm; smoke_grid_scale_invariance.mjs ← cellCm;
  smoke_space_scale_defaults.mjs ← cellCm
Зарегистрированная связь (1): smoke_orphan_space_references.mjs ← repairSpaceReferences

Все четыре прогнаны (таблица выше), все зелёные.

CI на ветке — что нашёл и как учёл

Validate на коммите с реализацией (9a42c856, run 32732620838) завершился cancelled, с process-gate: failure и docs: failure; golden/smoke/ performance_smoke не завершились (cancelled), потому что следующий пуш (81d2a801) отменил незавершённый прогон (штатное поведение concurrency.cancel-in-progress, AGENTS.md). Разобрал каждую причину:

• docs: failure — ожидаемо, отпечаток скриншотов был устаревшим; закрыто тем же следующим коммитом (docs: accept screenshots for lattice barrier);
• process-gate: failure — git cat-file -e 89f8b581...^{commit} не находит объект: BEFORE_SHA ссылался на коммит, переписанный до этого пуша (амend/форс на личной ветке задачи, что процессом не запрещено). Транзиентная инфраструктурная причина, не нарушение правил — на финальном HEAD process-gate зелёный и в CI (run 32732834660), и в моём локальном прогоне;
• golden/smoke/performance_smoke для финального HEAD в CI не запускались вовсе — на ветках задач changes-job фильтрует по diff последнего пуша (а не всей ветки), и пуш 81d2a801 тронул только docs/images/**. Это осознанный дизайн (validate.yml: «настоящую приёмку там делает код-ревью, которое гоняет гейты само, #127») — то есть именно код-ревью (эта сессия), а не CI, отвечает за targeted-гейты, что я и сделал выше.

Ссылка автора в хендоффе («Linux backend … зелёный in Validate 32732620838») точна для job backend, но не упоминает, что сам прогон был cancelled и два job упали — это не искажение факта, но неполная картина. Отмечаю как наблюдение, не как находку: обе причины разобраны и не относятся к поведению #291.

AC — построчно

AC	Доказательство	Вердикт
AC1 Идемпотентность/точные биты	test/coordinate-canonicalization.test.mjs: цикл по 4801 узлам, идемпотентность, -0→+0, 0.06/0.2875 не снапятся, граница 1e-4 в обе стороны — плюс мой прогон на живой фикстуре (см. таблицу)	✅ доказано автотестом + исполнением
AC2 Shared allow-list parity	одна fixture (test/fixtures/coordinate-canonicalization.json), deep-equal TS/Python (test_python_and_frontend_share_the_scalar_lattice_fixture_contract), input immutable	✅ доказано автотестом (TS выполнен; Python — проверено чтением, см. «Не проверял»)
AC3 Живой профиль после migration = 0	test/model-invariants.test.mjs: real-plan-*.json clone → profile.noise===0, far===measured.far, checkWallKeys/checkMixedRoleRecords = 0, raw file byte-equal до/после — плюс мой независимый прогон CLI на real-plan-first-floor.json (66.15%→0.00%, идемпотентность подтверждена вторым прогоном)	✅ доказано автотестом + исполнением
AC4 Произвольная editing session не возвращает noise	см. находку M1 — нет production-bundle smoke, который бы рисовал/продолжал Walls chain, делал Resize, ставил opening/partition/column/decor, двигал marker/room label и проверял latticeProfile.noise===0 после каждого шага, как требует буква AC	⚠️ не доказано ни тестом, ни явной записью «проверено чтением» — структурно вероятно верно (AC5+AC1), но не показано
AC5 Write barrier нельзя обойти	test/coordinate-write-barrier-guard.test.mjs (инвентарь всех 4 frontend-writer'ов + 2 backend Store boundary в store.py); мутанты frontend-writes-raw-coords (#224, переиспользован) и optimize-config/layout-storage-half-raw (#248, переиспользован) целятся именно в bypass; первый прогнан мной полностью и покраснел как положено	✅ доказано автотестом (frontend выполнено; backend-мутант не выполнен, см. «Не проверял»)
AC6 Source fixtures остаются шумными	test('барьер очищает клоны реальных планов, не переписывая source fixtures (#291)'): readFileSync до/после теста байт-в-байт равны; profile.noise >= 100 пин остаётся	✅ доказано автотестом, выполнено
AC7 Optimize report и transaction	smoke_optimize_coordinate_canonicalization.mjs (17/17 true, выполнено мной), test/plan-optimizer.test.mjs (идемпотентность, latticeCoordinatesCanonicalized/Far не путается с coordsCanonicalized, лёгко проверяемый порядок: барьер применяется до alignAllToGrid, поэтому align не видит уже исправленный шум и не задваивает счётчик — проверено чтением plan-optimizer.ts:415-420 и подтверждено тем, что coordsCanonicalized===0 рядом с latticeCoordinatesCanonicalized>0 в тесте «issue 273»/«ULP source»)	✅ доказано автотестом + smoke, выполнено
AC8 Compatibility paths	test_backend_schemas_apply_the_same_allowlist, optimize-storage-roundtrip.json, 280-optimize-rehost-candidate.json обновлены канонизацией; no schema/version bump подтверждён (модель/сторедж не тронуты)	✅ проверено чтением + существующими тестами (backend часть не исполнена мной)
AC9 Polyclip/#278 regression	npm test включает все 5 тестов #278 … (1207-1211), все зелёные; барьер не трогает physical-geometry.ts/union	✅ доказано автотестом, выполнено
AC10 Мутанты	6 новых lattice-мутантов + 2 переиспользованных (#224/#248) закрывают все 6 категорий буквы AC10 (round→truncate TS+Python, threshold too small/large, layout allow-list omission, unknown-field recursion, frontend writer bypass, backend Store bypass). --check зелёный на всех 180; полностью прогнаны мной 2 из 8 релевантных (TS-side); backend-мутант не прогнан (среда)	✅ доказано структурно + частично исполнением, backend — проверено чтением
AC11 Performance	demo/benchmark_coordinate_write_barrier.mjs, ratio 0.666 (я) / 0.823 (автор), лимит 1.2; линейный один проход, без второго deep-clone (проверено чтением plan-optimizer.ts: canonicalizeConfigGeometryInPlace работает по месту, autor явно закомментировал это решение)	✅ доказано автотестом/бенчмарком, выполнено
AC12 Локальные гейты	typecheck/test/build/bundle-parity/check-docs — выполнены (таблица выше); backend — не выполнен (среда)	✅/⚠️ частично, см. «Не проверял»

Находки

M1 (Medium, в скоупе) — AC4 не доказан ни автотестом, ни явной записью

AC4 требует production-bundle smoke, который последовательно: рисует/ продолжает Walls chain → Resize → ставит/двигает opening/partition/column/ decor → двигает device marker и room label → делает config/layout write, reload, export — и после каждого commit проверяет latticeProfile.noise === 0. Ни один смок в диффе (новый smoke_lattice_write_barrier.mjs, обновлённый smoke_optimize_coordinate_canonicalization.mjs) этого не делает: smoke_lattice_write_barrier.mjs подаёт шумные данные напрямую в card._serverCfg/card._layout и проверяет 4 writer-call-site, минуя контроллеры инструментов (wall chain, resize, opening/partition/column/decor, drag маркера/подписи). Ни одного смока в репозитории, ссылающегося на latticeProfile, я не нашёл (grep -rl latticeProfile demo/*.mjs — пусто).

Структурно AC5 (единый барьер, непроходимый) + AC1 (сама функция корректна) делают результат весьма вероятным без отдельного прогона — но это не то же самое, что показать его для реальных контроллеров, которые формируют кандидат разными путями (snap при рисовании, resize-пересчёт, поворот проёма). Именно ради этой уверенности AC4 сформулирован отдельно от AC5, и именно эту рамку (§7.1: «либо автотест, либо явная запись ревьюера») сейчас не закрывает ни тест, ни хендофф-комментарий автора (там нет фразы вида «AC4 закрыт составом AC1+AC5, отдельный смок не написан»).

Воспроизведение отсутствия: grep -rl "latticeProfile\|noise === 0" demo/*.mjs → пусто; diff не трогает ни один из смоков с реальными жестами (smoke_wall_chain_*, smoke_room_resize, smoke_opening_preview, smoke_free_walls и т.п.).

Правка: либо добавить проверку latticeProfile.noise===0 после committed-пар в один из существующих session-смоков (например, расширить smoke_lattice_write_barrier.mjs реальными жестами через инструменты, а не прямой инъекцией в _serverCfg), либо явно задокументировать в ТЗ/хендоффе, что AC4 закрывается композицией AC1+AC5, и получить с этим согласие ревьюера. Второй путь дешевле и, на мой взгляд, содержательно корректен — но должен быть сказан, а не подразумеваться.

M2 (Medium, в скоупе) — docs/USER-GUIDE.ru.md не обновлён

Спецификация (§13 «Ожидаемые файлы») называет оба файла: docs/USER-GUIDE.md и docs/USER-GUIDE.ru.md. В диффе изменён только docs/USER-GUIDE.md (добавлен абзац о невидимом floating-point хвосте, отчёте Optimize и автоматической защите обычных правок) — git diff origin/dev...HEAD --stat -- docs/USER-GUIDE.ru.md пуст.

RU-версия при этом не «пусто молчит»: раздел 19 уже содержит общее описание похожего механизма (устранение «невидимого вычислительного шума» при обычном сохранении, разделение строк «обновлено» и «шум устранён» в превью), — но это описание существовало до #291 (git blame: 2026-08-20/23, до ветки задачи) и не называет ни нового per-space разбиения (gs.optimize_lattice_space), ни физического максимума с тремя значащими цифрами (formatLatticeShiftCm) — то, что EN-версия получила явно.

Это нарушает не абстрактное «обе версии», а конкретное правило: AGENTS.md — «interface wording comes from docs/USER-GUIDE.ru.md… or the UI starts speaking developer»; PROCESS §2.6 — документация в том же коммите, что поведение; коммит помечен User-Visible: yes и уже поправил оба CHANGELOG (RU+EN) — тот же стандарт должен быть применён и к самому руководству пользователя.

Воспроизведение: git diff origin/dev...HEAD --stat -- docs/USER-GUIDE.ru.md → пустой вывод; сравнить с непустым для docs/USER-GUIDE.md.

Правка: перенести/адаптировать на русский абзац, добавленный в docs/USER-GUIDE.md (раздел 19), с упоминанием per-space строк и физического максимума — по терминологии gs.optimize_lattice_summary/ gs.optimize_lattice_space из src/i18n/ru.json.

Low — не блокируют, зафиксированы без правки

• L1. Хендофф-комментарий автора цитирует run 32732620838 как «зелёный» для backend-job, не упоминая, что сам прогон cancelled и два job упали (docs, process-gate) — разобрано выше в «CI на ветке», причины не относятся к #291 и с тех пор устранены. Отмечаю как точность цитирования, не как дефект реализации.

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

• Формула maxShiftCm = shift * LATTICE_GRID_N * cellCm в coordinate-canonicalization.ts не баг: она буквально повторяет уже существующую конвенцию align-grid.ts:185 (d * GRID_N * cellCm) — нормализованные координаты записаны в долях полной ширины плана (NORM_W/GRID_N=240 шагов на ширину), поэтому перевод в см требует именно этого множителя. Проверил перекрёстно чтением обоих файлов.
• «Одно число — один источник»: formatLatticeShiftCm(r.latticeMaxShiftCm) в диалоге Optimize (houseplan-card.ts:16405-16416) взят из того же OptimizeReport, что и Confirm, и не смешивается с d.cm/gs.align_count (обычный grid-align) — разные ключи, разные строки, разные источники данных (lattice.maxShiftCm vs alignReport.maxShiftCm), явно разведены и в коде, и в документации (CANVAS.md: «kept separate from visible moved/maxShift*»). Единственное смешение — суммарный счётчик в toast gs.align_done (m: ... + d.report.latticeCoordinatesCanonicalized + ...), но это легитимная сумма разнородных счётчиков для одной итоговой фразы, а не повторное отображение одной и той же величины.
• Порядок операций в optimizePlans(): latticeCanonicalizationReport() считается до canonicalizeConfigGeometryInPlace/ canonicalizeLayoutGeometryInPlace, которые в свою очередь идут до alignAllToGrid — отчёт не искажён последующей мутацией, а align не задваивает то, что уже поправил барьер (числами подтверждено в тесте «Optimize canonicalizes the six-room ULP source…»: coordsCanonicalized===0 рядом с latticeCoordinatesCanonicalized>0).
• changed (готовность к записи) считается по финальному persistedConfig после lattice-канонизации — поэтому latticeCoordinatesCanonicalized>0 всегда подтверждает changed=true, без риска репортить ненулевые счётчики при changed=false (читал код, логической рассинхронизации не нашёл).
• Backend-зеркало (coordinate_canonicalization.py): math.floor(scaled + 0.5) корректно воспроизводит tie-breaking JS Math.round (к +∞, включая отрицательные .5) — проверено на нескольких контрольных значениях вручную (-0.5→0, -1.5→-1, -2.5→-2, совпадает с JS). store.py не тронут диффом вообще: расширение поведения происходит через уже существующий единый вызов canonicalize_config_geometry/ canonicalize_layout_geometry внутри async_save_config_state/ async_save_layout_state (оба — из #224), что и есть корректный способ расширить барьер без создания второй точки входа.
• Гвард scripts/coordinate-write-barrier-guard.mjs: пересчитал руками все 4 frontend-паттерна (config/set ×1, layout/update ×2, localStorage. setItem(LS_KEY ×1) прямым grep по src/houseplan-card.ts — счётчики гварда совпадают с реальным числом occurrences.
• i18n: оба новых ключа (gs.optimize_lattice_summary, gs.optimize_lattice_space) присутствуют в en.json/ru.json буквально как в §7.1 ТЗ; test/i18n.test.mjs проверяет и текст, и точки вызова в houseplan-card.ts.
• Трейлеры: все 10 коммитов несут Issue: #291 и корректный User-Visible: yes|no; единственный User-Visible: yes коммит (9a42c856) правит оба docs/CHANGELOG.md/docs/CHANGELOG.ru.md в одном коммите.
• node scripts/process-gate.mjs --github-range --issues, прогнан локально на HEAD: «гейт пройден, предупреждений 0».
• Документация подсистемы (CANVAS.md, CONFIG-COMPATIBILITY.md, ARCHITECTURE.md, TESTING.md) содержательно и точно описывает новую границу, терминологию не изобретает, ссылается на реальные имена полей отчёта.

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

• Backend pytest (tests_backend/test_coordinate_canonicalization.py, включая мутанты python-lattice-round-truncates, optimize-*-storage-half-raw): в среде ревью не установлен homeassistant (ModuleNotFoundError, даже с pytest доустановленным) — известное и задокументированное ограничение (AGENTS.md: «A full Home Assistant harness cannot run on native Windows… locally only the pure subset runs»; здесь и чистый subset не собрался, так как модуль virtual_lights тянет homeassistant.components.frontend уже на импорте). Заменил чтением: TS/Python реализации построчно идентичны по структуре, тест-файл 1:1 зеркалит TS-тест по значениям (те же 4801 узлов, те же граничные случаи), а автор сослался на зелёный backend job в CI (run 32732620838, JSON подтверждён мной через gh run view) — «проверено чтением, не исполнением» для backend-части AC1/AC2/ AC5/AC8/AC10.
• npm run golden:verify: не прогонял. Diff потенциально меняет видимый Optimize-диалог (новые строки отчёта), но test('модели проекта не несут шума решётки (#282)') (зелёный, в npm test) доказывает, что все demo-фикстуры, включая golden-geometry, не содержат lattice-шума — значит новые строки (${r.latticeCoordinatesCanonicalized ? html\...` : nothing}) в golden-сценариях optimize-preflight-dialog-*не отрenders, и визуального расхождения не должно быть. Не стал тратить на это предрелизный гейт; если ошибаюсь —golden:verify` перед бетой это покажет.
• Полный набор из 182 браузерных смоков: не прогонял, кроме выбранных 6 (2 по AC + 4 по smoke-select) — по правилу §8 «полные наборы — гейт предрелиза, не код-ревью».
• Полный HA-харнесс / WSL: недоступен в среде ревью.
• Не проверял детально совместимость с #290 (уступ 316×1) и #288/#289 — их регрессионные тесты в npm test прошли без изменений в диффе, а сам диф их не трогает; это не отдельная точка риска этой задачи.

Итог

High-находок нет. Две находки Medium, обе в скоупе задачи (обе — про собственные акцептанс-критерии/список файлов ТЗ, не сторонний код) и обе чинятся в этой же задаче без нового issue: M1 (нет production-smoke для буквы AC4 либо явного признания замены на структурное доказательство) и M2 (docs/USER-GUIDE.ru.md не обновлён при User-Visible: yes). Ядро реализации — сама канонизация, барьер записи, backend-зеркало, идемпотентность, защита от обхода, производительность — проверено и работает, включая независимое исполнение на реальных (privacy-minimized) данных из issue.

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