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

Код-ревью #223 — Optimize канонизирует координаты без floating-point шума

• Цикл: r1/4 (код-ревью; ТЗ прошло отдельный лимит и закрыто зелёным на r3)
• Диапазон: git diff origin/dev...HEAD (7 коммитов, origin/dev..HEAD)
• Реализация: коммит 38f74e0 (fix: canonicalize near-grid coordinates exactly, Issue: #223, User-Visible: yes) — единственный коммит с продуктовым изменением; предыдущие 6 коммитов — ТЗ и его ревью (r1–r3), уже закрыты отдельным циклом.
• ТЗ: docs/specs/223-optimize-coordinate-canonicalization.md, зелёное ревью docs/reviews/SPEC-REVIEW-223-r3.md.

Скоуп проверки

Полный разбор — это первый цикл код-ревью, §2.10 (дельта по раундам) здесь не применяется. Список изменённых файлов (git diff origin/dev...HEAD --name-only) сверен построчно с §4/§12 ТЗ — расхождений нет, попутных правок нет: src/align-grid.ts, src/houseplan-card.ts, src/i18n/{en,ru}.json, test/align-grid.test.mjs, test/plan-optimizer.test.mjs, test/i18n.test.mjs, scripts/mutation-gate.mjs, demo/smoke_optimize_coordinate_canonicalization.mjs, docs/{CANVAS,USER-GUIDE.ru,TESTING,STATUS,CHANGELOG,CHANGELOG.ru}.md, docs/specs/README.md, три копии бандла. custom_components/**/*.py не тронут — контракт ТЗ («persisted schema и backend не меняются») подтверждён структурой diff, не только текстом.

Как проверялось (гейты)

Прогнано в этом цикле:

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	pass, без вывода
Unit	npm test	tests 975, pass 975, fail 0
Build + сверка бандлов	npm run build затем sha256sum dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js demo/srv/assets/houseplan-card.js	все три файла — один и тот же хэш 3f7eaf824d79b33f190b9323e2d873aff7eb19d6eef7749488e96b39c76ad33a (совпадает с хэшем из хендоффа автора)
Targeted browser smoke (AC6/AC7)	node demo/smoke_optimize_coordinate_canonicalization.mjs	13/13 true, OK
Смежные browser smoke (диф трогает общий alignAllToGrid/snapN, используемый этими сценариями)	node demo/smoke_grid_snap.mjs и node demo/smoke_optimize_micro_interval.mjs	оба OK, все проверки true
Mutation guard (AC1)	node scripts/mutation-gate.mjs --id=snapn-returns-input-near-node	поймано 1 из 1 — мутант пойман, чистый прогон зелёный
Mutation registry hygiene	node scripts/mutation-gate.mjs --check	ok snapn-returns-input-near-node среди прочих, без ошибок уникальности find
Process gate (офлайн)	node scripts/process-gate.mjs	гейт пройден, предупреждений 0

Не прогонялось и почему:

• Полный набор из 127 браузерных смоков — diff меняет ровно один batch-путь (alignAllToGrid внутри explicit Optimize) и явно поименованный смок плюс два смежных по тому же пути прогнаны выше; остальные 124 смока не затрагивают ни align-grid.ts, ни отчёт Optimize. Полный набор — предрелизный гейт (PROCESS.md §8), не гейт ревью.
• npm run golden:verify — diff не меняет разметку диалога (тот же .alignmsg, добавлена подстрока в уже существующий текст) и не двигает геометрию видимо: величина правки — доли EPS (≈4.2e-9 нормализованной единицы), она гарантированно ниже порога любого golden-снапшота. Само ТЗ §10 фиксирует это решение («Golden baseline не требуется... перед бетой выполняется общий golden verify по процессу»), и я согласен с этой оценкой после чтения diff.
• python -m pytest tests_backend — ни один файл custom_components/houseplan/**/*.py не тронут (подтверждено списком файлов выше).
• performance-профили — в AC не названы; изменение линейно по уже обходимым координатам, добавляет одну точную проверку на компонент; ТЗ §11 явно снимает необходимость отдельного performance-гейта, и чтение alignAllToGrid (без новых циклов/аллокаций сверх O(1) на компоненту) подтверждает это.

Находки

Находок, блокирующих или требующих правки в задаче, нет.

Low — AC2 (неконечные числа) не имеет отдельного unit-доказательства

• Файл: src/align-grid.ts:69-72 (snapN), контракт — AC2 в docs/specs/223-optimize-coordinate-canonicalization.md:147.
• Что не так: AC2 требует доказательства «boundary unit matrix» для двух утверждений: (1) значение дальше EPS продолжает выравниваться как раньше — это покрыто (test/align-grid.test.mjs:48-50, случай off = node + S/3); (2) «не конечные числа сохраняют прежний результат» — для этого в текущем наборе тестов нет ни одного assert на NaN/Infinity/-Infinity, ни в новых тестах, ни в уже существовавших (git show origin/dev:test/align-grid.test.mjs такого теста тоже не содержит).
• Почему не блокирует: строка if (!Number.isFinite(v)) return v; (src/align-grid.ts:70) в этом diff не менялась — это тот же guard, что был до задачи, и он был непокрыт тестом и раньше. Риск регрессии от этого diff нулевой: изменённая строка (return Math.round(...)) находится строго после guard и не может исполниться для нефинитного входа.
• Решение ревьюера: снимается без правки в этой задаче. AC2 по факту доказан читкой (guard не тронут), а не только тестом; отдельная задача на добавление такого unit-теста не заводится (тривиальная гигиена покрытия, не дефект поведения) — по желанию автора может быть добавлена заодно со следующей правкой этого файла.

Проверено по AC (код-ревью отвечает за «оно вообще работает»)

AC	Доказательство	Как проверено
AC1	test/align-grid.test.mjs:41-51 (юнит), мутант snapn-returns-input-near-node	Юнит прогнан зелёным в составе npm test; мутант отдельно прогнан и пойман (scripts/mutation-gate.mjs --id=... → 1 из 1) — тест умеет падать.
AC2	Юнит на off-случай зелёный; неконечные числа — см. находку Low выше	Частично тестом, частично чтением (guard не тронут).
AC3	test/plan-optimizer.test.mjs:75-107 (six-room ULP fixture), unionBodies	Юнит зелёный в npm test; проверено, что тест реально утверждает moved:0, maxShift:0, coordsCanonicalized>0, changed:true и что unionBodies не падает на результате — тест умеет падать (до фикса snapN возвращал v, координаты остались бы носящими шум, coordsCanonicalized был бы 0, assert.ok(... > 0) покраснел бы).
AC4	test/align-grid.test.mjs:53-94 (poly/rect/partition accepted+rejected/wall_column/decor/marker)	Юнит зелёный; читкой кода (src/align-grid.ts:264-291) подтверждено, что вклад партиции считается после ветвления hostedFit, а не на входе в snapN — ровно то, что требовал r1 ревью ТЗ. Тест явно проверяет, что partitions[1].a[0] (hostedFit=false) остаётся noisy, а счётчик не растёт от неё (coordsCanonicalized === 8, вручную пересчитано по фикстуре — сходится).
AC5	test/align-grid.test.mjs:158-162, test/plan-optimizer.test.mjs:101-106	Юниты зелёные, оба проверяют coordsCanonicalized: 0 и changed: false на повторном проходе, включая глубокое равенство.
AC6	test/i18n.test.mjs:30-40, targeted smoke	i18n-юнит проверяет ровно обе строки RU/EN и обе точки использования в houseplan-card.ts через regex по исходнику; smoke проверяет реальный рендер (previewNamesBothReportUnits, toastExplainsZeroMoveCleanup) — оба зелёные при прогоне выше.
AC7	test/plan-optimizer.test.mjs:83 (assert.deepEqual(config, before, ...)), smoke	Юнит на немутацию preview зелёный; smoke подтверждает Cancel/Apply/Undo на реальном диалоге (previewDoesNotWrite, cancelDoesNotWrite, applyUsesOneAtomicWrite, undoRestoresExactNoisyValues, undoIsOneDeep) — все true в прогоне выше.
AC8	Чтение: grep -rn "alignAllToGrid|snapN(" src/*.ts	alignAllToGrid вызывается ровно из одного места — plan-optimizer.ts:398, внутри optimizePlans(), который сам вызывается только явным _runAlignToGrid/_openAlignDialog (нет вызовов из пути save/render). Проверено чтением, не исполнением. Полный npm test (975/975) зелёный, включая существующие тесты #218.
AC9	git diff по docs, sha256sum трёх бандлов	Документация обновлена по списку §12 ТЗ; хэши бандлов идентичны (см. таблицу гейтов).
AC10	Таблица гейтов выше	typecheck/unit/build/targeted-smoke/mutation — все зелёные.

Что проверено и корректно (сверх таблицы AC)

• Архитектура счётчика. noteCanonicalCoordinate/noteCanonicalPoint (src/align-grid.ts:157-166) считают вклад строго по значению, реально записанному в candidate: для room_drafts вклад учитывается только для точек, попавших в итоговый draft.points (written строится параллельно с points, включая тот же dedup по EPS), и только когда сам draft не был отфильтрован фильтром points.length >= 2 (иначе весь draft уходит в removedDrafts, а не в candidate). Для partition — вклад учитывается только внутри if (snappedLength > EPS && hostedFit), то есть ровно в ветке, где p.a/p.b реально присваиваются.
• Скрещённая проверка арифметики. Вручную пересчитан фикстурный тест near-node report counts only coordinate values actually written to the candidate (test/align-grid.test.mjs:53-88): из восьми noisy-вхождений в фикстуре ожидаемый вклад — poly (1: только x первой вершины), rect (1: x дальнего угла через x0+w0), partition accepted (1), wall_column (1), decor line/box/text (по 1), marker (1) = 8, ровно то, что проверяет assert.equal(result.report.coordsCanonicalized, 8). Партиция rejected корректно исключена.
• OptimizeReport наследует поле честно. plan-optimizer.ts:38 — OptimizeReport extends AlignReport, а итоговый report собирается через { ...alignReport, ... } (plan-optimizer.ts:522) без явного поля — coordsCanonicalized переносится автоматически, не задваивается и не теряется; changed в optimizePlans() вычисляется отдельно, через полное сравнение JSON конфигурации (plan-optimizer.ts:513), поэтому корректно становится true даже если единственная правка — ULP-чистка.
• moved/maxShift* не растут от ULP-правок. Это гарантирует не новый, а существующий note() (src/align-grid.ts:181-187, не изменён этим diff): moved увеличивается только при d > EPS. Новый код добавляет отдельный счётчик параллельно, не переиспользуя и не искажая этот путь.
• UX-терминология. Финальная строка gs.optimize_changes (RU: «обновлено пространств: {c}; устранён шум координат: {p}»; EN аналогично) разводит два счётчика без пересечения с занятым во всём проекте термином «нормализовано»/ «канонизировано» из docs/CANVAS.md — ровно то решение, которое было согласовано на r2/r3 ревью ТЗ; я перечитал docs/CANVAS.md:12,20,333,489,539 и не нашёл нового конфликта термина с этой формулировкой.
• Итоговый toast (gs.align_done, src/houseplan-card.ts:14288-14291) включает coordsCanonicalized в общую сумму обслуженных записей — предположение §13.4 ТЗ реализовано буквально.
• Отсутствие побочных путей записи. Подтверждено чтением (см. AC8), что snapN/alignAllToGrid недостижимы вне явного Optimize — обычные read/render/Save не подвергаются риску скрытой мутации персистентных данных.
• Три копии бандла синхронны, коммит несёт верные трейлеры, оба changelog правлены в том же коммите, что и поведение (38f74e0).

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

• Полный browser-smoke набор (127 сценариев), golden:verify, pytest tests_backend, performance-профили — не прогонялись; причины и обоснование сужения — в таблице гейтов выше. Это решение ревьюера, а не молчаливый пропуск.
• Ручного визуального прогона карточки в браузере (открыть демо, покликать диалог глазами) не делал — заменён точечным browser-smoke и чтением рендер-кода; в процессе фазы ручного тестирования нет (PROCESS.md §2.7), и именно smoke здесь стоит на её месте.
• WSL/полный HA harness и Windows-специфичные smoke не запускались — сессия ревью работает в Linux CI-подобном окружении, что и предусмотрено процессом для код-ревью.

Вердикт

Зелёный. High: 0. Medium: 0. Одна находка Low снята решением ревьюера с записью (см. раздел «Находки») — правка не требуется.