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

CODE-REVIEW-291-r2

• Issue: #291 «Барьер записи координат: убрать шум как явление»
• Этап: код-ревью (PROCESS.md §2.7), заход r2
• Диапазон: 52c74301..3c754729 (merge-base с origin/dev .. HEAD ветки issue/291-lattice-coordinate-barrier), 12 коммитов, 38 файлов, +2696/-327
• ТЗ: docs/specs/291-lattice-coordinate-write-barrier.md, зелёное ревью SPEC-REVIEW-291-r3.md
• Ревьюер: свежая сессия, без контекста реализации; артефакты читаны из ветки и через gh, не со слов автора

Почему это ПОЛНЫЙ разбор, а не разбор по дельте

Вердикт r1 (CODE-REVIEW-291-r1.md) получен на диапазоне 10fa0dc7..81d2a801. Между r1 и этим заходом ветка была ребейзнута на ушедший вперёд dev после слияния #290 (комментарий автора 14:17:38 UTC: «Ребейз на актуальный dev после слияния #290 завершён»). Проверено прямо:

$ git cat-file -e 81d2a801^{commit}
fatal: Not a valid object name 81d2a801^{commit}
$ git cat-file -e 7de1f44^{commit}   # коммит с фиксами M1/M2 из r1
fatal: Not a valid object name 7de1f44^{commit}

Оба SHA, на которые ссылался r1 (диапазон ревью и коммит с фиксами), переписаны и не существуют в дереве. Это буквально случай PROCESS.md §2.10 / AGENTS.md §7.2: «после ребейза на ушедший вперёд dev это другой код» — разбор по дельте здесь неприменим, весь диф пройден заново.

Скоуп

Единый барьер записи, приводящий координаты, лежащие ближе 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	1242 passed, 1 skipped, 0 failed (было 1232 на r1 — рост за счёт test/coordinate-write-barrier-guard.test.mjs и правок M1/M2)
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 test/fixtures/real-plan-first-floor.json --lattice (raw fixture)	66.15% шума (127/192), худший 8.00e-8 шага — воспроизводит измеренную причину issue буквально; после барьера (через npm test, см. ниже) — 0
Model invariants (после барьера)	npm test → test('барьер очищает клоны реальных планов, не переписывая source fixtures (#291)')	зелёный: profile.noise===0 на клонах обоих реальных планов, checkWallKeys/checkMixedRoleRecords=0, raw-файл байт-в-байт неизменен
Mutation gate (структурная проверка)	node scripts/mutation-gate.mjs --check	все патчи, включая 6 lattice-мутантов, применяются к текущему коду ровно один раз
Mutation gate (полный прогон, все 6 lattice-мутантов)	--id=lattice-round-truncates, --id=frontend-writes-raw-coords, --id=lattice-noise-threshold-too-small, --id=lattice-noise-threshold-too-large, --id=lattice-layout-allowlist-omitted, --id=lattice-unknown-fields-recursive	все 6: мутант применён → именованный тест покраснел, гейт зафиксировал ловлю (python-lattice-round-truncates не прогнан — backend, см. «Не проверял»)
Performance (AC11)	node demo/benchmark_coordinate_write_barrier.mjs	ratio 0.608 (лимит 1.2), независимый прогон
Smoke — выбор	node scripts/smoke-select.mjs --base origin/dev --head HEAD	3 «прямых совпадения» (cellCm) + 1 «зарегистрированная связь» (repairSpaceReferences) — те же, что на r1
Smoke — по AC4/AC7	smoke_lattice_write_barrier, smoke_optimize_coordinate_canonicalization	оба OK, все под-проверки true
Smoke — композиционное доказательство AC4 (M1)	smoke_wall_chain_thickness, smoke_room_resize, smoke_opening_preview, smoke_free_walls, smoke_decor, smoke_drag_bounds	все 6 OK — реальные production controller paths (wall chain, resize, opening/partition/column, decor, marker/label drag)
Smoke — по smoke-select	smoke_grid_scale_invariance, smoke_space_scale_defaults, smoke_orphan_space_references	все OK
Backend	python -m pytest tests_backend -q	не выполнено — среда без pytest/homeassistant (см. «Не проверял»); backend-.py не менялся ни одним коммитом после 4ccf4a3c (см. ниже), значит это тот же код, что был зелёным в CI
Golden	не прогонялся	сознательное решение, см. «Не проверял»
Process gate	node scripts/process-gate.mjs --github-range --issues локально на HEAD	«гейт пройден, предупреждений 0»
Process gate (CI, точный SHA)	gh run view на run 32737681761 (HEAD 3c754729)	success; docs/process-gate/provenance реально выполнены и зелёные

Вывод smoke-select.mjs (идентичен r1 — диф по src/** не расширился сверх трёх изменённых файлов):

Изменено файлов 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

Итого прогнано лично 11 браузерных смоков (2 по AC + 6 по композиции AC4 + 3 по smoke-select), все зелёные.

CI на финальном SHA — что реально проверено автоматикой, а что нет

Проверил независимо от слов автора, через gh run view --json jobs:

• 3c754729 (текущий HEAD): Validate success, но changes-job отфильтровал диапазон последнего пуша (только docs/images/screenshots.json) — frontend/backend/smoke/golden/performance_smoke skipped, не «зелёные», а не запускались вовсе;
• 81d2a801 (пуш со скриншотами, SHA которого больше не существует после ребейза): та же картина — все браузерные/backend job'ы skipped;
• 9a42c85 (SHA пре-ребейз реализации, тоже переписан): здесь frontend/hacs/hassfest/backend реально success до отмены прогона следующим пушем; golden/smoke/performance_smoke — cancelled (штатное поведение concurrency.cancel-in-progress), а не «зелёные».

Вывод: ни один CI-прогон в истории этой задачи (ни до, ни после ребейза) не довёл golden/smoke/performance_smoke до завершения. Это не искажение со стороны автора (в хендоффах формулировка точная — «Linux backend … зелёный», без утверждений про golden/smoke), но практическая проверка ложится на код-ревью, что и сделано выше (11 смоков лично, бенчмарк лично, invariants лично). Backend — единственный пробел, не покрытый ни CI на актуальном коде, ни локальным исполнением (см. «Не проверял»), закрыт чтением и тем, что файл не менялся с последнего зелёного backend-прогона.

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

Находка r1	Чем закрыта	Где это видно
M1 (Medium) — AC4 не доказан ни автотестом, ни явной записью: smoke_lattice_write_barrier инъецировал шум напрямую в _serverCfg/_layout, минуя контроллеры	ТЗ переписан (AC4, коммит 3f633888): явно зафиксирована композиционная схема доказательства — 6 production-bundle смоков реальных контроллеров + executable writer-inventory guard + smoke_lattice_write_barrier на уровне общей границы. docs/TESTING.md получил два новых пункта с той же формулировкой и списком [auto: …]. Комментарий в самом смоке (smoke_lattice_write_barrier.mjs:96-99) прямо называет разделение ответственности	docs/specs/291-lattice-coordinate-write-barrier.md §AC4 (текст «Поведение доказывается композицией, а не вторым mega-smoke»); docs/TESTING.md два новых пункта [auto: ...]; прогнал лично все 6 controller-смоков + writer-inventory тест — все зелёные (таблица выше)
M2 (Medium) — docs/USER-GUIDE.ru.md не обновлён при User-Visible: yes, хотя docs/USER-GUIDE.md (EN) получил абзац	RU-раздел 19 получил абзац с тем же контрактом: общий счётчик, максимум с тремя значащими цифрами, scientific notation ниже 0.001 см, только затронутые пространства, неизменность off-grid значений	git diff origin/dev...HEAD -- docs/USER-GUIDE.ru.md — непустой, абзац на месте (см. «Что проверено» ниже за точный текст)
L1 (Low) — хендофф цитировал cancelled прогон как «зелёный» для backend-job без упоминания отмены	Не требовал правки (наблюдение о точности цитирования, не о коде); не блокирует, статус не менялся	—

Обе Medium-находки закрыты по существу и проверены построчно (диффы выше, не заявление автора), не сняты игнорированием. Third M2-related risk — не перепутана ли RU-формулировка с устаревшей — проверена: абзац называет 3.30e-5 cm-подобную scientific-notation политику и «только затронутые пространства», то есть терминологию именно #291, а не старый общий текст раздела 19 (написанный до ветки задачи).

Унаследовано из r1

Поскольку разбор в этом заходе полный (см. «Почему это полный разбор» выше), формально «наследовать без проверки» нечего — весь диф пройден заново этим документом. Единственное, что взято как факт без повторной проверки: зелёный вердикт ревью ТЗ (SPEC-REVIEW-291-r3.md, SHA 4ec43ffd+ и 23fb41d4+, три захода, зелёное на r3) — ревью кода не пересматривает продуктовые решения владельца, зафиксированные на этапе ТЗ (Q1 про детализацию Optimize-отчёта, threshold 1e-4, allow-list полей).

AC — построчно (повторная проверка, полный разбор)

AC	Доказательство	Вердикт
AC1 Идемпотентность/точные биты	test/coordinate-canonicalization.test.mjs: 4801 узел, идемпотентность, -0→+0, 0.06/0.2875 не снапятся, граница 1e-4 — в npm test (зелёный)	✅ доказано автотестом, выполнено
AC2 Shared allow-list parity	Общая fixture, deep-equal TS/Python; TS-часть выполнена (npm test); backend-часть проверена чтением (файл не менялся с последнего зелёного backend CI)	✅ доказано автотестом (TS) + чтением (backend)
AC3 Живой профиль после migration = 0	test/model-invariants.test.mjs: real-plan clone → noise=0, checkWallKeys/checkMixedRoleRecords=0, raw byte-equal — зелёный в npm test; плюс мой независимый CLI-прогон на сыром real-plan-first-floor.json (66.15% шума, воспроизводит измерение issue)	✅ доказано автотестом + исполнением
AC4 Произвольная editing session не возвращает noise	Композиционное доказательство теперь явно задокументировано (закрытие M1 выше) и лично прогнано целиком: 6 production controller smokes + writer-inventory guard test + smoke_lattice_write_barrier (граница) — все зелёные	✅ доказано композицией автотестов, все компоненты лично исполнены
AC5 Write barrier нельзя обойти	test/coordinate-write-barrier-guard.test.mjs (инвентарь всех frontend-writer'ов + backend Store boundary); мутанты lattice-round-truncates/frontend-writes-raw-coords лично прогнаны — красятся	✅ доказано автотестом, выполнено
AC6 Source fixtures остаются шумными	Тест в npm test: raw-файл байт-в-байт равен до/после, profile.noise>=100 пин остаётся	✅ доказано автотестом, выполнено
AC7 Optimize report и transaction	smoke_optimize_coordinate_canonicalization (лично, зелёный, 13/13); порядок операций в plan-optimizer.ts проверен чтением: lattice-отчёт измеряется один раз до мутаций (строка 427), финальный safety-pass канонизации (строки 649-650) явно прокомментирован как «internal work must not leak into the user-visible report» и гейтится тем же changed-флагом, что и остальные счётчики — не создаёт второго источника числа	✅ доказано автотестом + smoke + чтением, отдельно проверено на предмет «одно число — один источник» после интеграции с #290 (near-axis repair/повторный align)
AC8 Compatibility paths	Существующие тесты не тронуты диффом сверх заявленного; no schema/version bump	✅ проверено чтением + существующими тестами
AC9 Polyclip/#278 regression	npm test включает все 5 тестов #278 …, зелёные (видел в хвосте прогона: #278 anonymized regression…, #278 component set is deterministic…, #278 Optimize and model-invariants use the same strict structural result, #278 physical fingerprint…, #278 production source routes physical writers…)	✅ доказано автотестом, выполнено
AC10 Мутанты	6 lattice-мутантов — все лично прогнаны и красятся (таблица гейтов); backend-мутант не прогнан (среда, см. «Не проверял»)	✅ доказано исполнением (frontend), backend — чтением
AC11 Performance	demo/benchmark_coordinate_write_barrier.mjs, ratio 0.608 (я, независимый прогон), лимит 1.2	✅ доказано бенчмарком, выполнено
AC12 Локальные гейты	typecheck/test/build/bundle-parity/check-docs — выполнены и зелёные (таблица выше); backend — не выполнен (среда)	✅/⚠️ частично, backend — см. «Не проверял»

Находки

Находок уровня High или Medium в этом заходе нет. Обе находки r1 закрыты (таблица выше), нового Medium/High разбор не вскрыл.

Low — не блокируют

• L2 (унаследовано из r1/спек-ревью, не относится к коду): формулировка тела issue «Стадия 1 из ADR #282» технически неточна (по ADR #282 «Стадия 1» — stable wall ids, явно вынесенные в «Не входит» этого же ТЗ). Не влияет на код-ревью, отмечен ещё на этапе ТЗ, не блокирует.
• L4 (новое наблюдение этого захода) — ни один CI-прогон в истории ветки не довёл golden/smoke/performance_smoke до завершения (см. раздел про CI выше): либо changes-path-filter не включил их (докозаписи пуши), либо следующий пуш отменил незавершённый прогон. Не дефект процесса (штатное поведение concurrency.cancel-in-progress и путевого фильтра, задокументированное в r1), но фактическую нагрузку по этим трём категориям целиком несёт код-ревью — что и сделано (11 смоков + бенчмарк лично). Не блокирует, фиксирую как честное описание происхождения зелёных цифр.

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

• Ребейз не сломал заявленный порядок операций. plan-optimizer.ts:427-432 измеряет lattice-отчёт и применяет барьер до alignAllToGrid/ repairNearAxisRoomWalls (новый шаг #290); финальный safety-pass в canonicalizeConfigGeometryInPlace/canonicalizeLayoutGeometryInPlace (строки 649-650) идёт после второго align-прохода для выпрямленных стен и явно прокомментирован как «internal work… must not leak into the user-visible report» — то есть отчёт lattice не задваивается и не занижается интеграцией с #290. Автор описал это словами в хендоффе («canonicalization до Align → near-axis repair → повторный Align → финальная canonicalization»); я проверил это построчно по коду, а не поверил формулировке.
• «Одно число — один источник» для нового placeholder {cm}. formatLatticeShiftCm (использован в диалоге Optimize) и latticeReport()/бенчмарк используют одну и ту же функцию форматирования с тремя значащими цифрами; не смешивается с обычной политикой округления moved/maxShiftCm grid-align (разные ключи i18n, разные поля отчёта).
• Backend не менялся с последнего зелёного backend-CI. git log -- 'custom_components/houseplan/*.py' в диапазоне задачи показывает единственный коммит 4ccf4a3c — тот же контент, что был протестирован в run 32732620838 (backend: success, до отмены прогона следующим пушем). Ни один последующий коммит backend-файлы не трогал — чтение актуального кода эквивалентно чтению того, что уже прошло CI.
• i18n. gs.optimize_lattice_summary/gs.optimize_lattice_space присутствуют в en.json/ru.json буквально как в ТЗ §7.1; проверил оба файла напрямую.
• Трейлеры. Все 12 коммитов диапазона несут Issue: #291 и User-Visible: yes|no; единственный User-Visible: yes (4ccf4a3c) правит оба docs/CHANGELOG.md/docs/CHANGELOG.ru.md в одном коммите (проверил дифф обоих файлов напрямую).
• Process gate. И локальный прогон, и CI на точном финальном SHA (3c754729, run 32737681761) зелёные.
• Гвард scripts/coordinate-write-barrier-guard.mjs — структурная проверка количества writer call-site'ов (1 config/set, 2 layout/update, 1 localStorage, 1 Optimize write во frontend; central Store writer'ы в backend) читана целиком: любой новый writer, обходящий единую границу, меняет счётчик occurrences и красит checkCoordinateWriteBarriers.

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

• Backend pytest (tests_backend/test_coordinate_canonicalization.py): среда ревью не имеет pytest/homeassistant (.venv-backend отсутствует, это известное ограничение не-облачного окружения, AGENTS.md). Заменил чтением плюс фактом, что backend-.py не менялся с последнего зелёного backend CI-прогона (32732620838, до отмены следующим пушем) — см. «Что проверено».
• npm run golden:verify: не прогонял. Тест 'модели проекта не несут шума решётки (#282)' (зелёный в npm test) доказывает, что golden-фикстуры не содержат lattice-шума — значит новые условные строки Optimize-диалога (${r.latticeCoordinatesCanonicalized ? …}) не рендерятся в golden-сценариях и визуального расхождения не должно быть. Golden — предрелизный гейт (PROCESS.md §8), не гейт код-ревью.
• Полный набор из 183 браузерных смоков: не прогонял, кроме выбранных 11 (2 AC + 6 композиция AC4 + 3 smoke-select) — по правилу §8 «полные наборы — гейт предрелиза».
• Полный HA-харнесс / WSL: недоступен в среде ревью.
• Не проверял отдельно совместимость с #288/#289/#290 сверх того, что их регрессионные тесты (в т.ч. #278 …, #290 near-axis audit…) прошли в npm test без изменений в диффе, не относящихся к #291.

Итог

High-находок нет. Обе Medium-находки r1 (M1 — композиционное доказательство AC4 не было названо явно; M2 — docs/USER-GUIDE.ru.md не обновлён) закрыты по существу и проверены построчно, не заявлением автора. Разбор в этом заходе полный, а не по дельте, потому что ребейз на ушедший вперёд dev переписал оба SHA, на которые ссылался r1 (диапазон ревью и коммит с фиксами) — код на ветке буквально другой. Ядро реализации — канонизация, единый непроходимый write barrier, backend-зеркало, идемпотентность, защита от обхода, производительность, интеграция с новым near-axis/align пайплайном #290 — проверено заново и работает, включая независимое исполнение 11 браузерных смоков, 6 мутантов, бенчмарка и invariants на реальных данных.

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