docs: review document for #375

Issue: #375
User-Visible: no

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

@@ -0,0 +1,190 @@
+# 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 в порядке. Готово к очереди на пре-релиз.