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

# CODE-REVIEW-276-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/276
- **Ветка:** `issue/276-reconcile-coincident-partition`
- **Проверенный HEAD:** `496e79a6dff56db2d5e491d11d02c67ca77d08d2` (совпадает с заявленным в хендоффе автора)
- **Диапазон:** `origin/dev...HEAD` (`origin/dev` = `240316a6`)
- **ТЗ:** `docs/specs/276-coincident-partition-reconciliation.md`, зелёное ревью
  `docs/reviews/SPEC-REVIEW-276-r3.md` (3 захода на этапе spec, 1/4
  блокирующих циклов израсходовано там; счётчик код-ревью отдельный)
- **Заход:** r1 (код-ревью) · блокирующих циклов до этого раунда: 0/4

## 1. Скоуп проверки

Полный разбор (это первый заход код-ревью, §2.10 не применяется).
Диапазон коммитов:

```
a06c94b9 docs: specify coincident partition reconciliation      (ТЗ, r1..r3 циклы spec)
ca516643 docs: address spec review for partition reconciliation
cfc8f211 docs: cover nested coincident partition thickness
a6056111 fix: reconcile coincident partitions during Optimize   ← продуктовый код
434995be test: strengthen coincident partition mutation
496e79a6 docs: refresh screenshot fingerprint
```

Продуктовая логика — единственный коммит `a6056111`. Он несёт `Issue: #276`,
`User-Visible: yes`, и в нём же — оба changelog (`docs/CHANGELOG.md`,
`docs/CHANGELOG.ru.md`), `docs/USER-GUIDE.md`/`.ru.md`, `docs/WALL-THICKNESS.md`,
`docs/ARCHITECTURE.md`, `docs/TESTING.md`, `docs/STATUS.md`, все тесты, demo
smoke, `scripts/mutation-gate.mjs`, `scripts/smoke-links.mjs` и три копии
бандла. `434995be` — тест-только правка мутанта (`User-Visible: no`, верно).
`496e79a6` — обновление отпечатка скриншотов (`User-Visible: no`, верно,
отдельный коммит по прецеденту #237).

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

Дешёвые гейты — всегда, в этом раунде тоже:

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | green, без вывода |
| Unit | `npm test` | **1176/1176 passed**, 0 skipped, 0 failed (авторский хендофф заявлял 1175 passed + 1 штатно skipped — расхождение на 1 тест воспроизведено средой: пропуски в `test/process-gate.test.mjs` условны на `git`/`gh`-стаб и различаются Windows/Linux; не дефект диффа) |
| Build + sync | `npm run build && npm run bundle:sync` | green; `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` и `demo/srv/assets/houseplan-card.js` — три копии byte-identical, `git status` чистый после сборки |
| check-docs | `node scripts/check-docs.mjs` | green: «Documentation checks passed (7 files, 10 external links)» — обязателен, диффа задел `src/**` |

`node scripts/smoke-select.mjs --base origin/dev --head HEAD` — полный вывод
приложен ниже с решением по каждой строке.

```
Прямое совпадение (13): smoke_zero_divider_taper, smoke_decor_layer_order,
  smoke_drag_bounds, smoke_furniture, smoke_glow, smoke_grid_snap,
  smoke_infinite_canvas, smoke_merge_split, smoke_open_passage,
  smoke_opening_tunnel_fill, smoke_optimize_micro_interval,
  smoke_optional_space_model, smoke_split_corner_wall
Зарегистрированная связь (3): smoke_optimize_coincident_partition,
  smoke_resize_wall_thickness, smoke_wall_key_roundtrip
```

Решение: все 13 «прямых совпадений» — следствие того, что новый модуль
импортирует широко используемые имена (`wallKey`, `NORM_W`, `GRID_PITCH`,
`SpaceModel`), а не потому что диффа меняет их контракт — классический
«слабая связь по распространённому имени» (PROCESS.md §8). Ни один из этих
13 смоков не относится к теме issue (decor layer order, furniture, glow
generic, grid snap, infinite canvas…), и полный прогон всех 16 не
пропорционален задаче. Прогнаны:

- `demo/smoke_optimize_coincident_partition.mjs` — прямо назван в AC6/AC7,
  запущен: **все 11 проверок true** (Preview не пишет, один атомарный
  Apply, reload сохраняет каноническое тело, one-shot Undo восстанавливает
  hosted-форму, Boundary видит shared wall, Thickness меняет единственное тело);
- `demo/smoke_wall_key_roundtrip.mjs` — «зарегистрированная связь» напрямую
  касается AC10 (consumer parity Plan/View/kiosk/Static/hidden Iso/light):
  запущен, **все 24 проверки true**;
- `demo/smoke_resize_wall_thickness.mjs` — «зарегистрированная связь» по
  `WallEntry`, который использует `setWallThickness`: запущен, **все 7
  проверок true**; Resize сам по себе вне скоупа (#277), но это дешёвая
  проверка отсутствия регресса в общем помощнике.

Остальные 10 «прямых совпадений» не прогонялись — тема (decor/furniture/
glow/grid snap/infinite canvas/merge-split/open passage/tunnel fill/split
corner) не пересекается ни с одним AC #276, а связь чисто по имени
импортированной утилиты.

Мутации (AC12, три идентификатора):

```
node scripts/mutation-gate.mjs --id=optimizer-coincident-opening-rehost-disabled
  → поймано 1 из 1
node scripts/mutation-gate.mjs --id=optimizer-coincident-partial-accepted
  → поймано 1 из 1
node scripts/mutation-gate.mjs --id=optimize-preflight-bypassed   (общий #199 мутант,
  переиспользован — reconciliation идёт через тот же `d.preflight?.ok` гейт)
  → поймано 1 из 1
```

Инварианты модели (диффа меняет геометрию/ссылки — обязателен, PROCESS.md §8,
#254/#253/#244/#252/#258/#259). Прогнан на выходе `optimizePlans()` для
фикстуры issue (5-см офсеты, room 15/partition 20) и на синтетической
nested-fixture (room 30/partition 20):

```
npm run invariants -- --config /tmp/276-reconciled.json
  → Инварианты выполнены: ссылки разрешимы, записи толщины находятся.
npm run invariants -- --config /tmp/276-nested.json
  → Инварианты выполнены: ссылки разрешимы, записи толщины находятся.
```

Оба файла получены прогоном `test-build/plan-optimizer.js` на входных
данных теста (команда воспроизводима, не «verified» без результата).

**Одно число — один источник.** Новые видимые числа — два счётчика Optimize
report (`partitionsReconciled`, `openingsRehosted`); каждый рендерится ровно
в одном месте (`src/houseplan-card.ts` вокруг строки 16233) через
существующий `_t()`-путь, как остальные счётчики отчёта. Итоговая толщина
общей стены (`max(roomCm, partitionCm)`) после Apply читается Thickness и
Boundary из одного и того же `space.walls` — тот же источник, что и для
любой обычной стены, второго хранения нет. `node --test
test/single-source-numbers.test.mjs` — 3/3 green, диффа не касается
форматтера.

## 3. Не прогонялось и почему

- **Полный `golden` матрикс (155 сценариев)** — предрелизный гейт (PROCESS.md
  §8, §11.4), не гейт код-ревью; диффа не меняет ни один существующий golden
  fixture (нет coincident-partition геометрии ни в одном текущем сценарии
  `demo/golden/matrix.mjs`), поэтому целевой прогон был бы no-op, а полный —
  не соразмерен задаче. См. находку M3 — целевой сценарий для #276 в матрицу
  не добавлен вовсе, поэтому полный/предрелизный прогон и не смог бы его
  проверить.
- **`python -m pytest tests_backend`** — диффа не касается `custom_components/**/*.py`.
- **Полная performance-матрица / `demo/benchmark_large_house.mjs` как есть** —
  не тот профиль (это render/pointer-путь, не «Optimize candidate pass»);
  вместо него — целевое измерение см. §4, M1.
- **`node demo/smoke_*.mjs` полный набор (177)** — не соразмерно; выбор по
  инструменту и теме см. §2.

## 4. Находки

Все три ниже — **Medium, в скоупе задачи** (High не найдено, красного нет).
По правилу §2.7/§4 это жёлтый вердикт, автор чинит в этом же issue, фикс
проходит следующий раунд.

### M1 — AC11 (перф-бюджет §10) не доказан ни автотестом, ни явным
«проверено чтением, не исполнением»

`docs/specs/276-coincident-partition-reconciliation.md` §10 обещает
«дополнительный p95 не превышает 15%... и 25 ms абсолютного overhead» на
large-house fixture, а AC11 называет доказательство: «Benchmark +
call-count test». Ни то, ни другое не добавлено:

- `demo/benchmark_large_house.mjs` — рендер/pointer-профиль, не измеряет
  `optimizePlans()`;
- `demo/benchmark_optimize_geometry_preflight.mjs` — измеряет только #199
  preflight, вызывается на данных, подготовленных `prepareSpacePhysicalGeometryInputs`,
  и не включает новый pass;
- ни один тест не проверяет счётчик вызовов `reconcileCoincidentPartitions`
  (call-count) — то есть будущая регрессия «функция стала вызываться на
  render/pointer path» не будет отловлена ничем.

Я измерил бюджет сам (не входит в зачёт «тест умеет падать» — это ad hoc
проверка ревьюера, а не доказательство автора), чтобы понять, реален ли
риск:

```
git worktree add --detach /tmp/hp-baseline cfc8f211   # до продуктового коммита
# baseline (без reconciliation), large-house fixture, N=30:
BASELINE min 31.20 median 34.59 p95 50.25 max 107.17
# HEAD (496e79a6), тот же прогон:
HEAD     min 30.62 median 34.07 p95 50.98 max 105.23
```

Разница p95 — 0.73 ms (~1.5%), внутри бюджета §10 с большим запасом.
**Фактического риска для перфоманса нет**, но это устанавливает ревьюер
разовым замером, а не тест, который переживёт следующую правку и умеет
упасть. Чинится добавлением: (а) целевого бенчмарка `optimizePlans()` на
large-house fixture с ассертом бюджета §10, аналогично
`benchmark_optimize_geometry_preflight.mjs`; (б) unit-теста, считающего
вызовы `reconcileCoincidentPartitions` только из `optimizePlans()` (например,
через инструментированный импорт/счётчик), либо равноценного доказательства
«не вызывается на render/pointer» по коду с явной пометкой в тесте.

### M2 — AC3 «несколько hosted openings на одной partition» не покрыто тестом

Спецификация (AC3) и план тестов (§13) требуют доказательства для «один И
**несколько** hosted door/window/gate». Все три источника (fixture
`test/fixtures/276-coincident-partition.json`, `test/coincident-partitions.test.mjs`,
`test/plan-optimizer.test.mjs`) используют ровно один hosted opening на
кандидата; парный overlap-цикл в `src/coincident-partitions.ts:265-270`
(`for i; for j > i;`) и `openingsRehosted += nextHosted.length` для случая
`length > 1` остаются непроверенными автотестом.

Проверил сам, чтобы понять фактический риск (ad hoc, не входит в зачёт
автора):

```js
// два hosted openings (door + window) на одной coincident partition
partitionsReconciled 1 openingsRehosted 2
// оба opening корректно материализованы на своих x/y/angle, host снят,
// повторный optimizePlans() — changed=false
```

Код и в этом случае работает верно — но это не устраняет разрыв: без
committed-теста регресс в парном overlap-цикле не будет пойман никем. Чинится
добавлением одного кандидата с двумя (лучше — тремя, чтобы задеть все пары
`i<j`) hosted openings в `test/coincident-partitions.test.mjs` либо
`test/plan-optimizer.test.mjs`, включая позитивный (не конфликтующие) и
негативный (два новых opening перекрылись бы после rehost → fail-closed)
случай.

### M3 — AC5 «targeted golden» не добавлен ни в каком виде

`docs/specs/276-coincident-partition-reconciliation.md` §13 обещает
«targeted golden: short 5-cm offsets + hosted door до/после 10/30/virtual», и
AC5 называет доказательством «Canonical geometry unit + targeted golden».
`demo/golden/matrix.mjs` не тронут этим диффом — ни один сценарий для #276 не
существует. Геометрическая часть AC5 полностью доказана (`wallIntervals`
unit-проверка в `test/coincident-partitions.test.mjs`/`plan-optimizer.test.mjs`
+ browser-smoke), но визуальный/пиксельный канал, который отдельно ловил
предыдущие регрессы такого рода (#234: подсветка «Толщины» и запись
расходились именно на уровне рендера, не геометрии), для этой фичи не
существует вовсе — ни сейчас, ни в будущем предрелизном прогоне, потому что
сценарий просто не описан в матрице. Это не блокирует Apply/AC своей
неполнотой сегодня (риск чисто визуального дефекта низкий: путь рендера
переиспользует давно проверенный `physicalBodyParts()`/`wallBodiesGeometry`,
никакой новой отрисовки не добавлено), но обещанный тест-план не выполнен.
Чинится добавлением сценария в `demo/golden/matrix.mjs` (короткие 5-см
офсеты + hosted door, до/после 10/30/virtual) — сама запись сценария не
требует прохождения через `golden:accept`, это делает пре-релизный гейт
(§8/§11.4) при первом реальном захвате.

## 5. Проверка AC — что доказано и как

| AC | Статус | Доказательство |
|---|---|---|
| AC1 | ✅ | `test('issue 276 exact proof ignores endpoint direction and room order')` — матрица 2×2 (direction×room order), все проходят |
| AC2 | ✅ | `test/plan-optimizer.test.mjs`: same-cm (20/20), nested narrower (30/20→30), nested wider (20/30→30), partial (byte-equivalent), ambiguous second partition (byte-equivalent); `test/coincident-partitions.test.mjs`: orphan/overlap/draft/column/unknown-field все byte-equivalent |
| AC3 | 🟡 частично | один hosted opening — unit + unknown-field round-trip (`future_field`) доказаны; **несколько** — не покрыто автотестом (M2), верно по факту исполнения (проверено мной ad hoc), но не доказано committed-тестом |
| AC4 | ✅ | `test('issue 276 fails closed for an orphan host, overlap, draft, column and unknown partition data')` — 5 вариантов, все fail-closed |
| AC5 | 🟡 частично | геометрическая эквивалентность — unit (`wallIntervals` после Apply) + browser smoke; **targeted golden не добавлен** (M3) |
| AC6 | ✅ | `smoke_optimize_coincident_partition.mjs`: `boundarySeesSharedWall`, `thicknessToolSelectsCanonicalWall`, `thicknessChangesSingleBody`, `previewDoesNotWrite` — все true |
| AC7 | ✅ | i18n unit (`test/i18n.test.mjs` проверяет обе строки в исходнике card) + smoke (`reportRendersBothCounters`, `applyUsesOneAtomicWrite`, `applyEnablesUndo`, `undoRestoresHostedPartition`) |
| AC8 | ✅ | Идемпотентность доказана в обоих unit-тестах (`second.changed === false`, `second.report.partitionsReconciled === 0`, `deepEqual(second.config, first.config)`) и smoke (reload) |
| AC9 | ✅ (проверено чтением, переиспользует #199) | `_runAlignToGrid()` блокирует Apply на `!d.preflight?.ok` (src/houseplan-card.ts:15112) — путь общий для всех Optimize-кандидатов, включая новый; мутант `optimize-preflight-bypassed` подтверждён (1/1) |
| AC10 | ✅ (проверено чтением) | Все консумеры (Plan/View/kiosk/Static/hidden Iso/Glow/sun) читают геометрию из одного `model.partitions`/`space.walls` через `physicalBodyParts()`/`modelOf()` — нет отдельной копии на consumer; после Apply запись `partitions` удаляется из персистентной конфигурации целиком, поэтому расхождения консумеров структурно невозможны. Отдельного dedicated parity-теста для #276 нет, но `smoke_wall_key_roundtrip.mjs` (запущен, 24/24 green) подтверждает единый источник для смежного случая |
| AC11 | 🟡 частично | call-count и бюджет §10 не доказаны автотестом (M1); эмпирически бюджет выполняется (p95 +1.5%, см. M1) |
| AC12 | ✅ | 3 мутанта, все 1/1 (см. §2) |
| AC13 | ✅ | typecheck/test/build+sync — все green, см. §2 |
| AC14 | ✅ | оба changelog, USER-GUIDE (RU/EN), WALL-THICKNESS.md, ARCHITECTURE.md, TESTING.md, STATUS.md — все в одном коммите с кодом, терминология («Толщина», «Граница») соответствует USER-GUIDE |

## 6. Прочее (не находки, для полноты)

- Хостинг документации/строк использует существующую терминологию
  («Граница», «Толщина») — не изобретена.
- `rawPartitionKnown()` фильтрует по сырому JSON (`{id,a,b,cm}`), а не по
  нормализованной модели — верно, иначе неизвестное поле терялось бы до
  проверки; подтверждено тестом `unknown partition data`.
- Эпсилон `Math.max(GRID_PITCH * 0.0002, 1e-9)` — доля шага сетки (~0.02%
  клетки), а не сама сетка; соответствует запрету ТЗ «пользовательская сетка
  не является epsilon».
- `columnBlocks()` использует точный circumradius (квадрат — `size *
  Math.SQRT1_2`, круг — `size * 0.5`), что совпадает с фактической
  геометрией `columnBody()` в `src/physical-geometry.ts` — не эвристика.

## 7. Вывод

Ядро реализации корректно, идемпотентно и хорошо покрыто тестами по
основным путям; все проверенные мной гейты (typecheck/test/build/check-docs/
целевые smoke/mutation/invariants) зелёные, три копии бандла синхронны,
трейлеры и changelog на месте. Три Medium-находки — все про **полноту
доказательной базы**, названной в самом ТЗ (AC3/AC5/AC11), а не про дефект
поведения; ни одна не про-функциональна (я лично исполнением подтвердил, что
множественные hosted openings и перф-бюджет фактически работают верно).
Все три в скоупе issue #276 и чинятся автором в этом же issue.

**Вердикт: жёлтый.**