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

# CODE-REVIEW-375-r1

Issue: #375 · Заход: r1 (код-ревью) · SHA: `29f7f0bbf71e8898c462d5560b1d3813c5a5d7ec`
Ветка: `issue/375-static-glow-caches`, база — актуальный `origin/dev`.
Вердикт: **зелёный** · блокирующих циклов 0/2 · High: 0 · Medium: 0

Это первый заход код-ревью для #375 (ТЗ прошло два раунда spec-ревью,
SPEC-REVIEW-375-r2 — зелёный). Разбор полный: сокращение по дельте (§2.10)
применяется со второго цикла код-ревью, здесь его нет.

## 1. Скоуп

Диф (`git diff origin/dev...HEAD`):

```
docs/CHANGELOG.md                 |   8 ++
docs/CHANGELOG.ru.md              |   8 ++
scripts/mutation-gate.mjs         |  22 ++++++
src/glow-scene.ts                 |   4 +-
src/space-render.ts               | 157 +++++++++++++++++++++++++++---------
test/space-render-caches.test.mjs | 109 ++++++++++++++++++++++++++
tsconfig.test.json                |   2 +-
+ dist/**, custom_components/houseplan/frontend/** (класс D, из build-коммита)
+ docs/images/*.png, docs/images/screenshots.json (регенерация отпечатка скриншотов,
  ожидаемо — check-docs считает его по всему src/**)
```

Два коммита:
- `d762ae02` `fix:` — класс A (`src/glow-scene.ts`, `src/space-render.ts`) +
  класс B (`scripts/mutation-gate.mjs`, `test/space-render-caches.test.mjs`,
  `tsconfig.test.json`) + оба changelog в одном коммите. Трейлеры: `Issue: #375`,
  `User-Visible: yes` — верно, поведение видимо пользователю (перф), правки
  обоих CHANGELOG присутствуют в том же коммите.
- `29f7f0bb` `build:` — класс D (обновление трёх копий бандла + скриншоты).
  `User-Visible: no` — верно, чисто механический коммит.

Реализует все четыре пункта ТЗ rev2 (К1–К4 = V6a–V6d):
K1 — убран spread перед `resolvedLightSources` в `glow-scene.ts:177`.
K2 — `cachedStaticWallGeometry` вешает non-enumerable `sourceFingerprint`
(та же тройка `[spCfg, cellCm, GRID_PITCH]`, что и `revision.geometryFingerprint`).
K3 — `cachedStaticLightBarriers` переведена на LRU-8 на space.
K4 — новый `cachedStaticEnabledClip` (LRU-8) + bbox-префильтр extras.

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

Все гейты ниже прогнаны лично на SHA `29f7f0bb` — зелёного прогона Validate на
этом SHA не найдено, поэтому дешёвые и часть профильных гейтов взяты на себя.

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | чисто, без вывода |
| Юниты | `npm test` | **1556/0** (1 skipped), совпадает с числом автора |
| Сборка + 3 копии бандла | `npm run bundle:sync` | `git status --porcelain` пуст после — dist / custom_components/houseplan/frontend / demo/srv/assets идентичны источникам, лишнего дифа нет |
| Доки-отпечаток | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links)` — diff трогает `src/**`, гейт обязателен и уже удовлетворён коммитом `29f7f0bb` |
| Мутанты (новые, из этого же коммита) | `node scripts/mutation-gate.mjs --id=static-glow-light-cache-spread` | **поймано 1/1** — тест краснеет при возврате spread |
| Мутанты (новые) | `node scripts/mutation-gate.mjs --id=static-glow-scene-lru-single` | **поймано 1/1** — тест краснеет при LRU=1 |
| Выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 14 «прямых совпадений», все — по широко используемым символам (`GRID_PITCH`, `NORM_W`, `cellCm`, `roomPoly`), ни один не специфичен для glow/кэшей; раздела «зарегистрированная связь»/«НЕОПРЕДЕЛЁННОСТЬ» инструмент не выдал |
| Смок parity (AC5, назван в ТЗ) | `node demo/smoke_glow_blending.mjs` | `{"ok":true,"blend":"screen","pools":60,"staticParity":true,"staticPools":60}` |
| Смок opt-in space-card (AC5) | `node demo/smoke_space_card.mjs` | OK |
| Смок cold view (заявлен автором) | `node demo/smoke_cold_view_toggle.mjs` | OK |
| Смок glow-геометрия (тема диффа, не в прямых совпадениях, но подсистема та же) | `node demo/smoke_glow.mjs` | OK, все 33 инварианта true |
| Смок glow отказоустойчивость | `node demo/smoke_glow_geometry_resilience.mjs` | OK |
| Смок тёмный fallback | `node demo/smoke_glow_fail_dark.mjs` | OK |
| Перф-смок (AC5: «cacheGrowth.glowClip: 0») full-card профиль | `npm run benchmark:glow -- --profile=large-house-glow-overlay-v1 --variants=60 --samples=3 --warmups=1` + `benchmark:compare --absolute-only --budgets=demo/performance/budgets-glow-smoke.json` | все чек-поинты ✅, `cache.growth.glowClip: 0`, `cache.growth.cleanFloor: 0` и др. |
| Перф-смок static-профиль | `npm run benchmark:glow -- --profile=large-space-card-glow-v1 --variants=60 --samples=3 --warmups=1` + `benchmark:compare --absolute-only --budgets=demo/performance/budgets-space-glow-smoke.json` | все чек-поинты ✅, `cache.growth.glowClip: 0` (это `_glowRuntimeState.clipCache`, общий рантайм — не путать с новым K4-кэшем, но именно эта метрика поимённо названа в AC5) |
| Перф-бюджет стыков (#330) | `npm run benchmark:junction-limits` | pass: true, все 5 метрик в бюджете |

Не прогонял: `npm run invariants` — диф не меняет геометрическую модель (рёбра,
записи толщины, `layout`, `marker.space`, `open_spans`); K2/K4 оборачивают уже
существующие вызовы `wallBodiesUnionPath`/`innerContourForRoom`/`floorMinusBodies`
в кэш-функции и добавляют bbox-префильтр (см. §4), но не меняют формулы —
проверено чтением, не исполнением. Полные (`space-default`/`space-glow` с
7 семплами на main/schedule) и предрелизные профили performance.yml —
не гонял, это предрелизный гейт §8, не гейт ревью; сокращённая (60/3/1,
`--absolute-only`) версия того же профиля из обычного Validate прогнана
лично (см. таблицу) и покрывает именно то, что называет AC5.
`python -m pytest tests_backend` — не гонял, `custom_components/**/*.py` не
тронут. Остальные 14 «прямых совпадений» smoke-select — не гонял: все они
привязаны к переиспользуемым по всему проекту символам (сетка/масштаб),
не к световой/кэш-механике; смоки той же подсистемы (`smoke_glow*`) прогнаны
явно вместо них.

## 3. Разбор по AC (ТЗ rev2)

**AC1** (кэш light-графа снова живой). `test/space-render-caches.test.mjs:13-41`
— поведенческий тест (реальный вызов `resolvedLightSources`, сравнение по
идентичности) плюс тест-пин источника (`glow-scene.ts` без спреда). Мутант
`static-glow-light-cache-spread` возвращает спред — тест краснеет (проверено
лично). **Доказано автотестом, тест умеет падать.**

**AC2** (recut-путь в static). `src/space-render.ts:560-568` вешает
`Object.defineProperty(built, 'sourceFingerprint', { value:
contentFingerprint([spCfg, cellCm, GRID_PITCH]), enumerable: false })` —
ровно та же тройка, что `resolveLightBarrierRevision` считает
`geometryFingerprint` (`src/glow-scene.ts:229-231`, `rawSpaceConfig: spCfg` —
`src/space-render.ts:620`). Тест `space-render-caches.test.mjs:48-56` пинит
обе стороны условия регексом — тем же способом, каким уже доказан recut
полной карты (`test/performance-contract.test.mjs:152`, тоже регекс на
`recutWallBodiesGeometry(...)` без поведенческого прогона). Метод не идеален
(не ловит семантический разъезд формулы), но соответствует уже принятому в
проекте прецеденту для той же ветки кода — не считаю находкой. **Доказано
автотестом (source-pin), тест умеет падать** — если убрать `defineProperty`
или изменить тройку, оба regex перестанут совпадать.

**AC3** (LRU-8 на space). `cachedStaticLightBarriers` (`space-render.ts:133-171`)
переведена на `Map<fingerprint, scene>` с `lruGet`/`lruSet` (капасити 8).
Тесты `space-render-caches.test.mjs:61-93`: ping-pong 6 обращений → 2 сборки
(проверено лично: логика `lruGet`/`lruSet` — стандартный move-to-end на Map,
корректна), эвикция на 9-й записи, изоляция по `space`/`cfg`. Мутант
`static-glow-scene-lru-single` (капасити=1) — тест краснеет (проверено лично).
**Доказано автотестом, тест умеет падать.**

**AC4** (кэш `enabledClip`). Новая `cachedStaticEnabledClip`
(`space-render.ts:172-193`) с тем же LRU-паттерном. Ключ на вызове
(`space-render.ts:719-721`) — `` `${revision.geometryFingerprint}|<отсортированный
список id выключенных комнат>` ``. Прочитал вручную: `geometryFingerprint`
целиком покрывает `spCfg` (raw-объект пространства), а `roomGlowOf` берёт
`spCfg`-же `settings.glow`/`fill_mode`/`disp.glow` — то есть список
выключенных комнат уже логически подразумевается фингерпринтом геометрии;
доп. суффикс в ключе избыточен, но безопасен (не может привести к ложному
попаданию в кэш, только к чуть более мелкой грануляции). Bbox-префильтр
extras (`space-render.ts:735-742`) — тот же AABB-тест, что и у полной карты
(`houseplan-card.ts:9388-9392`, сверил построчно) — попадание/непопадание
считается идентично, поведение не меняется, меняется только объём входа в
`floorMinusBodies`. Тест `space-render-caches.test.mjs:98-109` — поведенческий
(реальный вызов, идентичность результата, инвалидация при смене ключа).
**Доказано автотестом, тест умеет падать.**

**AC5** (parity + перф-контракты + `cacheGrowth.glowClip: 0`). Смок
`smoke_glow_blending` — байт-в-байт `staticParity:true`, 60/60 пулов (прогнан
лично). Перф-контракты `space-default`/`space-glow` — тяжёлые профили
(7 семплов) гоняются только в `performance.yml` (main/schedule/manual), это
предрелизный гейт; сокращённая версия того же (`large-house-glow-overlay-v1`
и `large-space-card-glow-v1`, 60/3/1, `--absolute-only`) — часть обычного
Validate, прогнана лично, `cache.growth.glowClip: 0` в обоих прогонах.
**Выполнен.**

**AC6** (мутанты в `scripts/mutation-gate.mjs`). Оба заявленных мутанта
(`static-glow-light-cache-spread`, `static-glow-scene-lru-single`) добавлены
и лично проверены — 1/1 каждый, ловятся юнитами, не сборкой. **Выполнен.**

## 4. Дополнительно проверено

- `resolvedLightSources` теперь получает `input.devices` (тип `readonly D[]`
  сохранился, спред не нужен даже для совместимости типов — `tsc --noEmit`
  чист).
- `spaceModels(o.cfg)` создаёт свежие объекты комнат на КАЖДЫЙ вызов
  `renderSpaceStatic` (`src/space-geometry.ts:135-150`), поэтому сравнение
  `glowEnabledRooms.includes(room)` по ссылке (K4-ключ) остаётся корректным —
  оно происходит внутри одного и того же вызова, а не между тиками; между
  тиками используется строковый ключ (fingerprint), а не ссылка. Проверено
  чтением, не исполнением — это тот участок, где ссылочная нестабильность
  моделей могла бы незаметно сломать кэш, и он не сломан.
- `physicalFingerprint` (extras/декор) — вложен в `spCfg` через `space.partitions`
  / `room_drafts` / `wall_columns`, то есть любое изменение состава extras уже
  меняет и `geometryFingerprint` — новый K4-кэш не может отдать устаревший
  клип при смене декора. Проверено чтением.
- Старый тип `StaticLightBarrierEntry` убран целиком, лишних ссылок не
  осталось (`grep` пуст).
- Трейлеры коммитов, класс правок по путям, оба CHANGELOG — соответствуют
  `AGENTS.md`/`PROCESS.md`.

## 5. Находки

Нет находок уровня High или Medium. Всё в скоупе ТЗ выполнено и доказано.

Low (не блокирует, оставляю на усмотрение автора, не завожу отдельный issue —
он в скоупе, не «попутный дефект соседнего поведения»):
- Ключ `cachedStaticEnabledClip` включает список выключенных комнат отдельно
  от `geometryFingerprint`, хотя последний уже логически покрывает это же
  состояние (см. AC4 выше). Не баг — просто одна избыточная переменная в
  ключе. Не требую правки.

## 6. Унаследовано / не разбиралось заново

Не применимо — это первый заход код-ревью (r1), раздел §2.10 «Унаследовано
из r<N-1>» относится к разбору со второго цикла. ТЗ-стадия (SPEC-REVIEW-375-r1
→ r2) пройдена ранее отдельным этапом и здесь не пересматривается по существу
— код-ревью проверяет реализацию против уже согласованного ТЗ rev2, а не само
ТЗ.

## 7. Итог

Все AC1–AC6 доказаны автотестами, каждый тест лично проверен на способность
падать (два — через `mutation-gate`, три — прямым запуском с иными входами).
Parity full↔static (AC5) подтверждена смоком байт-в-байт. Перф-контракты
(сокращённая версия, доступная вне предрелизного гейта) зелёные, включая
именованную в AC5 метрику `cache.growth.glowClip: 0`. Дешёвые гейты (tsc,
1556 юнитов, build+3 копии бандла, check-docs) зелёные лично. Trailers и
changelog в порядке. Готово к очереди на пре-релиз.