houseplan-card/docs/reviews/CODE-REVIEW-282-r3.md

# CODE-REVIEW-282-r3

- **Issue:** #282 — стабильная идентичность сегментов стен (ADR Stage 1)
- **Ветка:** `issue/282-wall-geometry-model`, HEAD `95fa23ca79db830b201e82d9a34a05dcc3cecb29` (после ребейза на `origin/dev` `5f0a7f5` — по словам автора конфликтов не было; проверено: `git merge-base --is-ancestor origin/dev HEAD` — true, ветка целиком впереди `dev`)
- **ТЗ:** `docs/specs/282-stable-wall-segment-identity.md` (spec-review зелёный на r2, `2f30c481`; в этом раунде правка только строки статуса — см. §1)
- **Этап:** код-ревью (PROCESS.md §2.7)
- **Заход:** r3 · блокирующих циклов израсходовано 2 из 4 до этого вердикта
- **Предыдущий раунд:** `docs/reviews/CODE-REVIEW-282-r2.md`, красный, HEAD на тот момент `3588284f` (после итогового ребейза переименован без конфликта в `0f54daf3` — коммит `git show 0f54daf3` содержит буквально текст «preserve passage validation during wall migration», совпадающий с описанием фикса в исходном r2-документе; сам документ r2 закоммичен в `c75c77d5`)
- **Вердикт:** **красный**

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

Раунд не расширяется до полного повторного разбора всей подсистемы: финальный
ребейз на `dev` `5f0a7f5` прошёл **без конфликта** (в отличие от двух
предыдущих раундов, где конфликт вносил новый код прямо в identity-барьер и
поэтому требовал полного разбора). Дельта r2→r3 (`0f54daf3..HEAD`, что то же
самое, что `c75c77d5..HEAD` за вычетом самого коммита с документом r2) — 5
коммитов, 17 файлов без учёта review-документа:

```
demo/smoke_near_axis_optimize.mjs, demo/smoke_openwall.mjs,
demo/smoke_optimize_coincident_partition.mjs,
demo/smoke_resize_outer_reconciliation.mjs,
demo/smoke_resize_virtual_thick.mjs, demo/smoke_sun.mjs,
demo/smoke_wall_thickness.mjs (новый),
custom_components/houseplan/frontend/houseplan-card.js, dist/houseplan-card.js,
docs/CHANGELOG.md, docs/CHANGELOG.ru.md, docs/images/screenshots.json,
docs/specs/282-stable-wall-segment-identity.md,
src/houseplan-card.ts, src/space-render.ts,
test/open-passage-contract.test.mjs, test/wall-segment-model.test.mjs
```

Разобрана полностью именно эта дельта: обе находки r2 (H1, H2) закрыты в ней
же (коммит `20f5c396` = переименованный `bcf8089`), и следом идёт
самостоятельный коммит `cfc1bb06` («fix: preserve migrated wall interactions»)
с продуктовым кодом в `src/houseplan-card.ts`, не связанным ни с одной находкой
r1/r2 — по методологии §2.10 такой код в дельте разбирается так же строго, как
если бы он пришёл первым разом.

Остальной ~60-файловый диапазон диффа #282 (миграция, backend-зеркало,
import/export, i18n, документация подсистемы, lineage-логика
`wall-segment-model.ts`, mutation-gate) дельтой не затронут — наследуется из
r2 (§6 ниже), она сама наследовала это из r1.

## 2. Как проверялось — таблица гейтов

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | зелёный |
| Build + sync бандла | `npm run build && npm run bundle:sync` | зелёный; дерево осталось чистым (`git status` пусто) — предъявленный бандл побайтово совпадает с пересобранным из исходников на HEAD |
| Unit/frontend | `npm test` | 1335 тестов, **1334 passed, 0 failed, 1 skipped** — H1(r2) закрыт, регрессий нет |
| Docs fingerprint | `node scripts/check-docs.mjs` | зелёный (7 файлов, 10 внешних ссылок) — обязателен, дельта трогает `src/**` |
| Model invariants (синтетика) | часть `npm test` | зелёный |
| Model invariants (реальная нагрузка) | `node scripts/model-invariants.mjs --config <large-house dump, v7 и после commitWallSegmentModel>` | зелёный до и после миграции: «ссылки разрешимы, записи толщины находятся» |
| Model invariants — решётка | `node scripts/model-invariants.mjs --config <large-house v8> --lattice` | 0.00% шума у узла на всех классах объектов (room/partition/wall/column/opening/decor) |
| Smoke selection (delta-scoped) | `node scripts/smoke-select.mjs --base c75c77d5 --head HEAD` | 7 прямых совпадений, 0 зарегистрированных, 0 слабых — см. §4 разбор по каждой строке |
| Целевые смоки дельты | `node demo/smoke_{junction_holes,active_chain_ink,drag_bounds,grid_snap,infinite_canvas,sun,wall_union_isolation}.mjs` | все 7 — **OK** |
| Смоки, изменённые самой дельтой | `node demo/smoke_{openwall,resize_virtual_thick,near_axis_optimize,optimize_coincident_partition,resize_outer_reconciliation,wall_thickness}.mjs` | все 6 — **OK** |
| AC7-евиденс смок (не в дельте, но прямо касается найденного) | `node demo/smoke_open_passage.mjs` | формально **OK** (все 13 проверок), но см. H1 — сама проверка `staticCutsAndFillsPassage` не способна обнаружить найденный дефект (проверяет наличие элементов, не форму пути) |
| Целевой диагностический прогон (не входит в проектный набор) | см. H1: точечный запуск `wallBodiesUnionPath` с продукционными константами + модифицированная **локальная копия** `smoke_open_passage.mjs` (не коммитилась, лежит вне репозитория) | воспроизводит дефект детерминированно, дважды |
| CI на точном SHA | `gh run view 32910611706` + `gh run view 32911155216` (`Matysh/houseplan-card`) | первый прогон: `frontend/hacs/hassfest/backend/performance_smoke/golden/smoke(1-3)` зелёные, `process-gate` красный (инфраструктурная причина — force-push обнулил `before`); второй прогон: `process-gate` зелёный, тяжёлые джобы легитимно reused (побайтово те же входы, механизм #208) |
| Mutation gate | не перепрогонял отдельно — дельта не трогает ни один из трёх поименованных `wall-identity-*`-мутантов (файлы `plan-optimizer.ts`/history-restore/editor-commit не в дельте); автор заявляет 226/226 на этом же HEAD | принято из хендоффа автора, не переисполнено мной |
| `pytest tests_backend` | не прогонялся — среда без `homeassistant` (как в r2 §8) | backend в дельте не тронут вовсе (все 17 файлов — frontend/demo/docs) — не требуется в этом раунде |
| Полный `performance_smoke`, `golden:verify` локально | не прогонялся отдельно | пре-релизный гейт; CI-прогон (см. выше) покрывает golden/performance на точном SHA |

Дешёвые гейты и все целевые смоки дельты — зелёные. Но целевой AC7-evidence
смок, при точечной проверке глубже штатной ассерции, обнаруживает находку H1.

## 3. High — блокирующие находки

### H1. AC7 всё ещё нарушен: Static-карточка рисует сплошную стену прямо по месту прохода после миграции в v8

**Файл:** `src/space-render.ts:437` (`renderSpaceStatic`, канонический геометрический
union стен для Static-карточки) — строка **не входит в дельту r2→r3** (не
менялась ни в `20f5c396`, ни в любом более раннем коммите #282), но её
поведение изменилось из-за самой Stage 1: до миграции проход без хозяина не
имел `opening.host` вовсе; после миграции в v8 **любой** не-partition opening
получает `host: {kind:'wall', id, t}` (`hostRoomOpenings`,
`src/wall-segment-model.ts:531-557`, не тронут дельтой, но это и есть
источник новых входных данных для строки 437).

```ts
// src/space-render.ts:434-443 (без изменений в этой дельте)
const canonicalWallGeometry = needsCanonicalWallGeometry
  ? cachedStaticWallGeometry(o.cfg, space.id, wallGeometryFingerprint, () => wallBodiesUnionPath(
    space.rooms, walls, [], [
      ...staticPassages.filter((opening) => !opening.host).map((opening) => ({
        x: opening.rx, y: opening.ry, angle: opening.angle, length: opening.rlen,
      })),
      ...hostedCompositeOpenings,
    ], GRID_STEP_N, cellCm, GRID_PITCH, NORM_W, extras,
  ))
  : null;
```

Ровно двумя строками выше, в этой же дельте, H2(r2) закрыт правильным
паттерном: `opening.host?.kind !== 'partition'` / `!opening.host ||
opening.host.kind === 'wall'` (строки 221, 279). Строка 437 использует старый
одноусловный `!opening.host` — единственное оставшееся место в файле с этим
паттерном (проверено `grep -n "\.host\b" src/*.ts`: везде, где встречается
`opening.host`/`o.host` вне `space-render.ts:437`, различение
`kind === 'wall'` уже сделано — `plan-geometry-preflight.ts:207,259`,
`houseplan-card.ts:9204`, и сам `space-render.ts:221,279`).

**Последствие:** после того как пространство мигрирует в v8 (любое структурное
редактирование, Optimize, либо просто открытие Plan-редактора), обычный
(не-partition) `passage` получает `host.kind === 'wall'` и **выпадает** из
списка вырезов, который `wallBodiesUnionPath` вычитает из сплошной кладки —
масонри рисуется **сплошным** прямо по месту прохода. Декоративная заливка
тоннеля (`passageDataTunnels`, не затронута багом) продолжает рисоваться, но
раньше в DOM-порядке (`space-render.ts:540/544` против `545` для
`.wallbodies`) — сплошная стена рисуется поверх неё. Проход, который ТЗ
называет «negative architecture» (комментарий в самом
`demo/smoke_open_passage.mjs:1-3`), визуально становится обычной глухой
стеной на Static-карточке.

`showBorders` (стены вообще рисуются на Static) по умолчанию **включён**
именно для пространств без залитого plan-изображения (`src/logic.ts:1265`,
`showBorders: s.show_borders ?? noPlan` — «spaces without a plan default to
visible markup») — то есть для основного онбординг-сценария J4
(`docs/SCOPE.md`: «от нуля до плана за вечер... draw»), не для редкого угла.

**Доказательство (исполнено, не только прочитано):**

1. Точечный прогон чистой функции с продукционными константами проекта
   (`GRID_STEP_N=1/240`, `GRID_PITCH=1000/240`, `NORM_W=1000`), скомпилированной
   тем же `tsc -p tsconfig.test.json`, что используют штатные unit-тесты:
   ```
   wallBodiesUnionPath(rooms, walls, [], [passage], ...).d
     → "M 491.67 100 L 508.33 100 L 508.33 455 L 491.67 455 Z
         M 491.67 545 L 508.33 545 L 508.33 900 L 491.67 900 Z"   (разрыв есть)
   wallBodiesUnionPath(rooms, walls, [], [], ...).d
     → "M 491.67 100 L 508.33 100 L 508.33 900 L 491.67 900 Z"   (сплошная стена)
   ```
   Присутствие/отсутствие объекта прохода в 4-м аргументе детерминированно
   решает, будет ли в стене разрыв — то есть исключение `host.kind==='wall'`
   этим фильтром гарантированно убирает разрыв.

2. Полный браузерный прогон: **локальная копия** (вне репозитория, не
   коммитилась и не будет) `demo/smoke_open_passage.mjs` с одной добавленной
   диагностикой — чтением `d` у реального `<path>` внутри `.wallbodies` на
   том же самом fixture, что и штатный смок (проход `passage-main`,
   `x=0.5,y=0.45,length=0.1`, стена `cm:20`, после реального
   `_saveOpening()` → `_commitPhysicalGeometry` → v8), собранная тем же
   `npm run build && npm run bundle:sync`, что и остальные гейты этого
   раунда:
   ```
   "wallbodyPathCount": 2,
   "wallbodyD": "M 491.67 200 L 508.33 200 L 508.33 700 L 491.67 700 Z
                  || M 491.67 200 L 508.33 200 L 508.33 700 L 491.67 700 Z",
   "wallVerticesNearPassage": []
   ```
   Оба пути — сплошной прямоугольник от y=200 до y=700, разрыва у y=450
   (центр прохода) нет. Воспроизведено дважды, детерминированно.

3. Почему штатный `smoke_open_passage.mjs` (тот, что числится evidence AC7 в
   самом ТЗ, §-«Доказательство: source guard + projection snapshots +
   existing geometry suite») это пропускает: его единственная проверка формы
   — `staticCutsAndFillsPassage = !!staticRoot.querySelector('.wallbodies') &&
   !!staticRoot.querySelector('.static-opening-tunnels [data-kind="passage"]')`
   — оба селектора существуют независимо от того, вырезана ли стена: группа
   `.wallbodies` рендерится, если есть стены вообще, а тоннель считается по
   отдельному, не затронутому багом пути (`passageTunnelGeometry`, строки
   444-452, использует нефильтрованный `staticPassages`). Проверка смотрит на
   присутствие DOM-узлов, а не на геометрию пути — она не может упасть на
   этом классе дефекта ни сейчас, ни раньше.

**Дополнительно:** `docs/CHANGELOG.md`/`.ru.md`, добавленные тем же коммитом
`20f5c396`, который закрывал H2(r2), формулируют это как решённое: «The
compact space card keeps wall-hosted doors, windows, gates **and passages**
visible after the migration as well» / «...двери, окна, ворота **и проходы**,
привязанные к стенам». Для дверей/окон/ворот это верно (они не проходят через
`wallBodiesUnionPath` вовсе — Static рисует их старым символьным путём).
Для проходов утверждение неточное: символ и тоннель-заливка видимы, но
физический вырез в кладке — нет.

**Итог:** прямое нарушение AC7 («projection даёт текущим full, static...
consumers прежние inputs»; сам ТЗ называет доказательством именно
«existing geometry suite», и это ровно тот тест, который проверка выше не
способна исполнить содержательно) на документированной поверхности продукта
(`houseplan-space-card`, `ARCHITECTURE.md` «Second card», с v1.16.0),
конфликт с J1/J2 `docs/SCOPE.md` (план должен показывать, что происходит и
где — «negative architecture» превращается в глухую стену), тот же класс
дефекта, что и H2(r2), только один код-путь глубже в той же функции. Блокирует.

## 4. Medium — по существу задачи

Новых находок Medium нет. Мелкое наблюдение без действия: `smoke_near_axis_optimize.mjs`
ослабил проверку точного соответствия индексов вершин (`north.poly[1] ===
south.poly[0]`) до `.some(point => samePoint(...))` — без сопроводительного
комментария, чем вызвано изменение порядка точек. Не поднимаю до находки:
сама геометрическая позиция всё ещё проверяется байт-точно, теряется только
проверка порядка индексов, который не является частью ни одного AC.

## 5. Закрытие раунда r2

| Находка r2 | Чем закрыта | Где это видно |
|---|---|---|
| **H1** — `npm test` красный: `validate_opening_passages(` встречается 3 раза в `websocket_api.py`, тест ожидал 2 | `test/open-passage-contract.test.mjs:76-82` теперь ожидает 3 и явно матчит оба вызова (до и после барьера v7→v8) по тексту | `npm test` → 1334 passed / 1 skipped / **0 failed** (было 1329 passed / 1 failed) — перепрогнано мной |
| **H2** — AC7: `houseplan-space-card` теряет wall-hosted opening (символ/материализация) после v8 | `resolvedHosted` теперь `if (opening.host?.kind !== 'partition') return []`; `resolvedRawOpenings` теперь `if (!opening.host \|\| opening.host.kind === 'wall') return [opening]` | `src/space-render.ts:217-282`; `node demo/smoke_open_passage.mjs` → `staticDoesNotInventPassageSymbol`/`staticCutsAndFillsPassage` OK — перепрогнано мной. **Но** соседняя строка 437 этой же функции, отвечающая за физический вырез кладки под проходом, не была приведена к тому же паттерну — см. H1 этого раунда: класс дефекта H2(r2) закрыт не полностью, только для символа/материализации, не для геометрии кладки |

Находка закрыта частично: правка правильная и достаточная для того, что она
адресовала (материализация/символ), но не покрывает соседний код-путь той же
функции, потребляющий тот же новый `host.kind === 'wall'` — ровно та
проверка, которую сам документ r2 в итоговом абзаце (§9) явно рекомендовал:
«стоит проверить на этом же файле и другие пути, потребляющие opening.host…».

## 6. Унаследовано из r2

Дельта `0f54daf3..HEAD` не касается — принято на основании выводов r2
(`docs/reviews/CODE-REVIEW-282-r2.md`, HEAD на котором получен вывод —
`3588284f`/переименован в `0f54daf3`), которая сама наследовала это из r1
(`5adfdb5d`/`466a6765`):

- **Migration determinism/idempotence**, **backend-зеркало валидации**
  (unique-id, owner-count, dangling refs, edge-geometry parity,
  `_wall_catalog_projection`), **import/export remap**, **i18n-ключи**
  (`toast.wall_model_migration_blocked`, `toast.wall_model_client_outdated`,
  `gs.wall_segments_migrated`, `wall_model.reason.*`), **документация**
  (`WALL-THICKNESS.md`, `CANVAS.md`, `USER-GUIDE.{ru,}.md`, `TESTING.md`),
  **`config-field-registry.mjs`**, **три `wall-identity-*` мутанта
  mutation-gate**, **lineage hints** (`fixedTopologyWallLineageHints`),
  **off-grid guard база** (`wallModelOffGridValueCount`, до добавления
  `additionalAuthoredPoints` в этой дельте) — не в дельте r2→r3 (проверено
  `git diff --stat c75c77d5..HEAD`, приведён в §1), наследуется без
  переразбора.
- **Guard-порядок #278**, **8 именованных structural-smoke из H2(r1)** — файлы
  не в дельте r2→r3, наследуются из r2 §5/§6 (которая сама перепроверила их
  исполнением на своём HEAD).

Обоснование: находка этого раунда (H1) обнаружена не потому, что унаследованный
код изменился, а потому, что дельта r2→r3 (миграция `host.kind==='wall'`,
действующая с самого Stage 1, то есть с r1) впервые была прослежена до всех
потребителей `opening.host` в файле, который сама дельта модифицировала —
это ревизия по следу дельты (§2.10), а не расширение на несвязанный код.

## 7. Что проверено и корректно

- **Sun rays после структурного редактирования** (`cfc1bb06`,
  `src/houseplan-card.ts:15465-15471`) — фильтр окон-источников солнца
  заменён с `!o.host` на `o.host?.kind !== 'partition'` по той же причине,
  что и H2(r2); прочитано и подтверждено прогоном: `node demo/smoke_sun.mjs`
  → все проверки OK, включая переписанные `aboveThresholdDrawn`/
  `backAboveThreshold` (теперь защищены от `null` через `layer()?.`).
- **`additionalAuthoredPoints` в `_commitPhysicalGeometry`**
  (`src/houseplan-card.ts:7296-7367`) — открытая пользователем граница
  добавляет свои же конечные точки в список «авторских» точек до сравнения
  off-grid-счётчика, так что открытие границы на уже мигрированном плане не
  выглядит как рост шума и не блокируется собственным guard-ом; прочитано,
  подтверждено `node demo/smoke_openwall.mjs` → OK (все проверки), включая
  переработанный сценарий второго открытого пролёта через инструмент
  `boundary`, а не через прямую инъекцию `open_to`.
- **Явный ноль толщины не воскресает** (`src/houseplan-card.ts:12002-12010`,
  зеркалирование `next`→`wall_segments[].cm` до `_normalizeWalls`) — новый
  unit-тест `test/wall-segment-model.test.mjs` («an explicit canonical zero is
  not resurrected…») зелёный в составе `npm test`; логика прочитана и
  соответствует комментарию в коде.
- **Обновлённые смоки редактирования** (`smoke_resize_virtual_thick`,
  `smoke_near_axis_optimize`, `smoke_optimize_coincident_partition`,
  `smoke_resize_outer_reconciliation`, `smoke_wall_thickness`) — изменения
  адаптируют ассерции к тому, что после Optimize/Resize пространство законно
  становится v8 и все openings несут `host.kind==='wall'`; новый предикат
  `wallHostResolves` проверяет не только присутствие `host`, но и то, что он
  реально резолвится к существующему `wall_segments[]` — это усиление
  проверки, не ослабление; все 6 файлов перепрогнаны мной, зелёные.
- **Model invariants на реальной нагрузке** (`large-house`, 3486 координат) —
  0% шума у узла до и после `commitWallSegmentModel`, ссылки разрешимы —
  перепрогнано мной с нуля (собственный дамп фикстуры), не только принято из
  хендоффа автора.
- **Трейлеры** — все 5 коммитов дельты (`20f5c396`, `cfc1bb06`, `ad54716d`,
  `063026bc`, `95fa23ca`) несут `Issue: #282`; два `User-Visible: yes`
  (`20f5c396`, `cfc1bb06`) правят оба changelog в том же коммите (проверено
  `git show --stat` на каждом).
- **CI на точном SHA** — смоки (3 шарда), golden, performance, backend,
  frontend, hacs, hassfest зелёные (первый прогон, за вычетом инфраструктурного
  сбоя `process-gate` от force-push); повторный прогон закрыл `process-gate`
  и легитимно переиспользовал тяжёлые джобы (побайтово идентичные входы).

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

- **`pytest tests_backend`** — не запускался: backend не входит в дельту
  r2→r3 вовсе (все 17 изменённых файлов — frontend/demo/docs), не требуется
  в этом раунде; полный HA-харнесс остаётся Linux CI-гейтом.
- **Mutation gate, полный `performance_smoke`, `golden:verify` локально** —
  не перепрогонялись мной отдельно: ни один из трёх поимённых
  `wall-identity-*` мутантов не задет дельтой (файлы вне диффа), а
  golden/performance покрыты зелёным CI-прогоном на точном SHA (§2) — считаю
  это достаточным для этих трёх пунктов в данном раунде.
- **7 «слабая связь» смоков** (`smoke_align_guides` и другие, связь только по
  `_path`) из полного `origin/dev..HEAD` смок-подбора — не прогонялись:
  методология не изменилась с r2, найденная блокирующая находка (H1) уже
  достаточна для возврата, а сама находка обнаружена не через этот список, а
  через целевой разбор дельты.
- **Глубокий аудит остальных потребителей `.host` за пределами
  `space-render.ts`** (hidden-isometric, `iso-openings.ts`) — точечно
  проверено (`grep` не находит там обращений к `.host` вовсе — изометрия
  потребляет уже резолвленные `_openingsR` из `houseplan-card.ts`, где паттерн
  подтверждённо корректен ещё с r2), но не воспроизведено исполнением
  отдельным браузерным прогоном — риск ниже, чем у Static, так как код там
  не содержит собственного `!opening.host`-фильтра.

## 9. Резюме

Красный вердикт, третий подряд, но предметно иной находке, чем r1/r2: обе
находки r2 (H1, H2) закрыты — H1 полностью и подтверждено исполнением
(`npm test` зелёный), H2 закрыт для символа/материализации, но не для
физического выреза кладки под проходом в той же функции того же файла.
Именно этот непокрытый код-путь — `src/space-render.ts:437` — воспроизведён
исполнением (не только прочитан) как реальный дефект: Static-карточка рисует
сплошную стену прямо по месту прохода на любом пространстве, мигрировавшем в
v8, если проход не привязан к перегородке. Это прямое нарушение AC7 задачи на
документированной, реально используемой поверхности продукта, в сценарии, где
стены по умолчанию видимы (J4, безкартиночный план).

Задача возвращается в «В разработке». Фикс структурно локален (тот же паттерн
`opening.host?.kind !== 'partition'` уже применён двумя строками выше в этом
же файле) и не должен требовать полного повторного разбора подсистемы в r4,
если дельта останется ограничена этой строкой и её прямыми следствиями —
но стоит одновременно перепроверить, не остался ли где-то в проекте ещё один
потребитель `opening.host` с тем же устаревшим одноусловным `!opening.host`
(в этом раунде такой список исчерпан `grep`, но `grep` не ловит эквивалентную
логику, выраженную иначе).