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

# CODE-REVIEW-330-r3

Issue: #330 — «Ограничения стыков (#329) блокируют event loop HA и дёргают ресайз на больших планах»
Этап: code (PROCESS.md §2.7)
Заход: r3 · блокирующих циклов израсходовано 2 из 4 (до этого раунда)
Ветка: `issue/330-junction-limits-performance`, HEAD ревью — `04bb54ae`

## 0. Разбор по дельте — почему и от какого SHA

Предыдущий вердикт (code-review r2, 2026-08-28T00:30:25Z) назван на HEAD
`85636a65`. Проверено, что этот SHA — прямой предок текущего HEAD и что
между ними ребейза не было:

```
$ git merge-base --is-ancestor 85636a65 HEAD && echo ancestor
ancestor
$ git log --oneline 85636a65..HEAD
04bb54ae fix: the baseline cache keys on geometry, and the smoke tells all three worlds apart (#330 r2-M1)
294d7047 docs: review document for #330
```

Два коммита, оба ожидаемые: `294d7047` — публикация документа r2 (не
код), `04bb54ae` — правка автора на единственную находку r2 (M1). Дельта
локальна: один файл продуктового кода, один смок, один юнит-тест, один
мутант-гвард. Контракт поведения не менялся, новая подсистема не задета,
объём дельты много меньше исходной задачи. Условия §2.10/§7.2 для полного
разбора не выполнены — разбираю по дельте `git diff 85636a65..HEAD`.

## 1. Скоуп дельты

`git diff 85636a65..HEAD --stat`:

```
 .../houseplan/frontend/houseplan-card.js  |   4 +-
 demo/smoke_junction_limits.mjs            |  56 ++++-
 dist/houseplan-card.js                    |   4 +-
 docs/reviews/CODE-REVIEW-330-r2.md        | 257 +++++++++++++
 scripts/mutation-gate.mjs                 |   9 +-
 src/houseplan-card.ts                     |  25 +-
 test/junction-limits.test.mjs             |   6 +-
 7 files changed, 336 insertions(+), 25 deletions(-)
```

Только r2-M1 (АС4 «поведенческая часть кэша не различает рабочий кэш от
удалённого»):

- `src/houseplan-card.ts:7501-7553` (`_junctionLimitsIntroduced`) — ключ
  кэша `_junctionBaselineCache` заменён с `(epoch, spaceId)` на
  `(spaceId, fingerprint)`, где `fingerprint = spacePhysicalGeometryFingerprint(previousSpace)`
  — существующая, уже применяемая в этом же файле утилита (строки 7212,
  7569-7570, 7676, 7751-7752, 7800, 16031), а не новый механизм.
- `demo/smoke_junction_limits.mjs` — счётчик теперь считает ТОЛЬКО вызовы
  `_junctionLimitViolations` с документом `=== card._serverCfg` (вычисления
  baseline, не кандидата), плюс второй жест ресайза с коммитом между ними,
  чтобы отличить «кэш никогда не инвалидируется» от «кэш инвалидируется
  честно».
- `test/junction-limits.test.mjs` — regex источника обновлён под новое имя
  полей (`cached.fingerprint === fingerprint`, `spacePhysicalGeometryFingerprint(previousSpace)`).
- `scripts/mutation-gate.mjs` — guard мутанта `junction-limit-baseline-cache-stale`
  теперь запускает и смок (поведенческая часть), и юнит (исходник), было —
  только юнит.
- `dist/**`/frontend-копия — механический пересчёт бандла тем же коммитом.

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

| Находка r2 | Чем закрыта | Где это видно |
|---|---|---|
| M1 (в скоупе) — заявленная «поведенческая половина» AC4 не различала рабочий и удалённый кэш (11 против 12 вызовов тонули в шуме); реальный баг вскрылся тем же разбором: кэш ключевался на `_cfgEpoch`, который тикает на каждом принятом превью-оверлее без изменения хранимого документа, поэтому baseline пересчитывался ~4 раза за жест, а не 1 | Ключ кэша заменён на identity документа + `spacePhysicalGeometryFingerprint` его пространства — содержание, не счётчик; превью-оверлей fingerprint не трогает, in-place structural commit меняет геометрию и инвалидирует честно. Смок считает отдельно вычисления baseline (документ `===_serverCfg`) через два жеста с коммитом между ними: ожидание строго 1, затем строго 2 | `src/houseplan-card.ts:7518-7553`; `demo/smoke_junction_limits.mjs:186-254`; я применил ровно мутант `junction-limit-baseline-cache-stale` (условие кэша обратно на `cached.spaceId === spaceId` без fingerprint) и прогнал сам смок — `resizeBaselineRecomputedAfterCommit: expected true, got false` (см. §3); без мутанта смок и `mutation-gate.mjs --id=junction-limit-baseline-cache-stale` — оба зелёные (см. §3) |

Находка закрыта по существу и подтверждена исполнением, не только чтением.

## 3. Как проверялось (дельта, r3)

Зелёного Validate на `04bb54ae` не найдено — гоняю дешёвые гейты сам, плюс
`check-docs` (диф трогает `src/**`) и целевой смок/мутант по дельте.

| Гейт | Команда | Результат |
|---|---|---|
| Типы | `npx tsc --noEmit` | чисто, без вывода |
| Юниты | `npm test` | `# tests 1420 / pass 1419 / fail 0 / skipped 1` |
| Сборка + идентичность 3 копий бандла | `npm run build && npm run bundle:sync`, затем `cmp` попарно всех трёх файлов | все три `cmp` — молча, идентичны; `git status --short` после сборки чист |
| Докс-гейт (диф трогает `src/**`) | `node scripts/check-docs.mjs` | **`exit 1`** — `ERROR screenshot source fingerprint is stale; run npm run build && node demo/docs/capture.mjs`. Проверил напрямую: записанный `sourceFingerprint` в `docs/images/screenshots.json` — `2a5ae6c1…`, реальный `visualFingerprint()` на этом дереве — `dbac4a84…`. Последний коммит, трогавший `screenshots.json`, — `85636a65` (ДО фикса); `04bb54ae` поменял `src/houseplan-card.ts` и не пересчитал фингерпринт — см. находку H1 |
| Целевой смок AC4 | `node demo/smoke_junction_limits.mjs` | `OK` (после свежей сборки и `bundle:sync`) |
| Тест умеет падать (AC4/мутант) | вручную заменил условие кэша в `src/houseplan-card.ts` на мутант `junction-limit-baseline-cache-stale` (`if (cached && cached.spaceId === spaceId)`, без fingerprint), пересобрал бандл, прогнал смок | `FAILED (1): resizeBaselineRecomputedAfterCommit: expected true, got false` — мутант ловится; источник восстановлен, пересобран, смок снова `OK`, `git status --short` пуст |
| Тот же мутант через гвард | `node scripts/mutation-gate.mjs --id=junction-limit-baseline-cache-stale` | `ok junction-limit-baseline-cache-stale: тест покраснел, как обязан`; «поймано 1 из 1» |
| Выборка смоков по дельте | `node scripts/smoke-select.mjs --base 85636a65 --head HEAD` | 1 файл `src/**` изменён, 3 символа на изменённых строках. Одна **зарегистрированная связь**: `demo/smoke_wall_union_isolation.mjs` ← `spacePhysicalGeometryFingerprint`. Прогнан отдельно (см. ниже) |
| `smoke_wall_union_isolation.mjs` (по связи из smoke-select) | `node demo/smoke_wall_union_isolation.mjs` | `OK`, все 11 полей `true` |
| Перф-контракт §5/AC7 (не трогается дельтой, но это перф-задача — перепроверил) | `npm run benchmark:junction-limits` | `pass: true`, `tsFullCandidateMs: 152` (бюджет 400, запас 2.6×) |

### Отдельная проверка: не добавила ли дельта скрытую перф-регрессию

`_junctionLimitsIntroduced` теперь считает `spacePhysicalGeometryFingerprint`
на КАЖДЫЙ вызов (и при попадании в кэш, и при промахе) — раньше сравнение
было целочисленным O(1). Измерил стоимость самой функции на фикстуре §5
(576 атомов, 12×12) отдельно от бенчей (ни `benchmark_junction_limits.mjs`,
ни `benchmark_safe_resize.mjs` не проходят через этот метод класса — оба
вызывают чистые функции/`resize.js` напрямую, это отмечено ещё в r1/r2):

```
$ node --input-type=module -e '... spacePhysicalGeometryFingerprint(space) × 200 ...'
avg ms per call: 1.71
```

~1.7 мс на вызов на самой крупной фикстуре задачи — на два порядка меньше
бюджета кадра и на два порядка меньше стоимости, которую §4.4 устраняет
(до фикса пересчёт baseline стоил сотни мс — 4.2 с на полный набор до §4.7).
Не блокирует, отмечаю как проверенное наблюдение: этот путь остаётся не
покрыт числовым перф-бюджетом ни в одном бенче — не находка этой задачи
(оба бенча так же не покрывали его в r1/r2), но стоит иметь в виду, если
§330 продолжится следующим срезом.

## 4. Находки

### H1 — докс-гейт красный на HEAD ревью (в скоупе, блокирует)

`node scripts/check-docs.mjs` завершается `exit 1`:

```
ERROR screenshot source fingerprint is stale; run npm run build && node demo/docs/capture.mjs
```

Коммит `04bb54ae` меняет `src/houseplan-card.ts` (комментарий + логика
кэша), но не пересчитывает `docs/images/screenshots.json`. Отпечаток
считается по всему `src/**` (PROCESS.md §8), поэтому любая правка
фронтенда делает его устаревшим механически, без вариантов трактовки —
ровно класс дефекта, который уже стоил `dev` красного джоба `docs` на
#230/#234 (найдено только на следующей задаче, #237). Сама задача #330
уже дважды проходила через этот гейт (r1-H1 в code-review, тот же класс)
и знает цену пропуска. UI не изменился (изменение сугубо внутреннее,
кэш-логика), поэтому PNG, вероятно, останутся байт-в-байт те же — но
запись `sourceFingerprint` обязана быть пересчитана командой `npm run
build && node demo/docs/capture.mjs` и принята `npm run docs:accept
-- --reviewed --from=<артефакт>` тем же правилом, что и раньше в этой
задаче; самому пересобирать и коммитить в рабочей копии не в праве
(ревьюер не правит код).

**Что нужно поправить:** пересчитать фингерпринт/скриншоты и закоммитить
вместе (или отдельным коммитом класса C поверх), убедиться, что
`check-docs` зелёный на итоговом SHA.

Находок Medium/Low, не закрытых в тексте, нет.

## 5. Унаследовано из r2 (без повторной проверки)

- **Архитектура срезов §4.1–§4.7** (executor-цепочка, rev-кэш `previous`,
  byNode-индекс П3, bucket-решётка П4, §4.6 «v9 как есть», общий проход
  §4.7) — признана верной по коду и по вердиктам в code-review r2
  (`docs/reviews/CODE-REVIEW-330-r2.md`, HEAD `85636a65`, разделы 3 и 7).
  Дельта r3 их не касается ни одной строкой (см. §1) — принимаю без
  повторного чтения.
- **AC1 (event loop/executor)** — HA-харнесс тест
  `test_330_config_set_validators_run_in_the_executor`, прогнан исполнением
  в r2 (`pytest -k 330` → `1 passed`, документ r2 §5/§6). Дельта r3 не
  трогает `custom_components/**`.
- **AC2/AC3/AC5 (линейный П3/П4, rev-кэш бэкенда, эквивалентность §4.6)** —
  подтверждены исполнением в r2 (паритет-тесты TS↔Python, границы ячеек,
  `pytest tests_backend -q` 423 passed). Ни один из файлов бэкенда не в
  дельте r3.
- **AC7/перф-контракт §5, включение в `validate.yml`** — подтверждено в r2
  чтением воркфлоу (`validate.yml:543-547`) и исполнением
  (`pass:true`, запас 2.65×). Я перепрогнал `benchmark:junction-limits`
  заново в этом раунде (см. §3) — тот же результат в пределах шума
  раннера (152 мс против 150.7 мс в r2), воркфлоу-файл не в дельте, не
  перечитывал.
- **golden:verify** — не гонял, как и в r2: дельта не трогает рендер,
  геометрию, стили, слои, только ключ кэша и подсчёт вызовов в смоке.
- **Полная матрица `demo/smoke_*.mjs` (194 шт.)** и **полный
  `mutation-gate.mjs`** — не гонял целиком, как и в r2: это предрелизные
  гейты (PROCESS.md §8), не гейт ревью. По дельте прогнал точечно —
  `smoke_junction_limits.mjs` (прямое совпадение) и
  `smoke_wall_union_isolation.mjs` (зарегистрированная связь по
  `spacePhysicalGeometryFingerprint`, см. §3) — плюс единственный
  релевантный дельте мутант через `--id=`.
- **`pytest tests_backend`** — не гонял; дельта не содержит ни одного
  файла `.py` (см. `git diff --name-only 85636a65..HEAD`).
- **`npm run invariants -- --config <...>`** отдельной командой — не
  гонял; дельта не вводит новую геометрию/фикстуру, только ключ кэша по
  уже существующему `spacePhysicalGeometryFingerprint`; `npm test`
  прогоняет инварианты модели на существующих моделях проекта и прошёл
  (см. §3).
- **Одно число — один источник** — неприменимо: дельта не вводит и не
  меняет ни одной пользователю видимой величины (внутренний счётчик
  вызовов в смоке и внутренний кэш-ключ невидимы пользователю).
- **CHANGELOG** — не требуется: коммит `04bb54ae` несёт `User-Visible: no`
  (внутренняя правка кэша, поведение для пользователя не меняется);
  трейлеры коммита корректны (`Issue: #330`, `User-Visible: no`).

## 6. Что проверено и корректно (эта дельта)

- Новый ключ кэша (`spaceId + fingerprint`) читается из `previousConfig`,
  вычисляется безопасно через `try/catch` с пустой строкой на ошибке;
  пустой fingerprint явно исключён из условия попадания в кэш И из записи
  в кэш (`&& fingerprint`) — сбой вычисления fingerprint отключает
  кэширование для этого вызова, а не выдаёт ложное попадание.
  Прочитано построчно (`src/houseplan-card.ts:7526-7553`).
- `spacePhysicalGeometryFingerprint` — не новый механизм, а уже
  используемый в этом же файле барьер физической геометрии (6 других
  мест), корректность и покрытие которого не в скоупе этой находки.
- Смок теперь физически различает три мира (рабочий кэш = 1 затем 2,
  вечный кэш = 1 затем 1, отключённый кэш = ~10 затем ~20) — проверено
  и мутантом (см. §3), и обычным прогоном.
- Трейлеры коммита `04bb54ae` — `Issue: #330`, `User-Visible: no`,
  корректны для внутренней правки.

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

- `pytest tests_backend` — дельта не трогает `.py`, наследую r2 (§5).
- `golden:verify` — дельта не трогает визуал, наследую r2 (§5).
- Полная матрица смоков (194) и полный `mutation-gate.mjs` (все мутанты) —
  предрелизные гейты, не гейт ревью; прогнал точечно по выводу
  `smoke-select.mjs` плюс единственный релевантный мутант.
- Перф-бюджет самой `spacePhysicalGeometryFingerprint` внутри
  `_junctionLimitsIntroduced` — не заведён отдельным числом ни в одном
  бенче (см. §3, «отдельная проверка»); измерил вручную (1.7 мс/вызов на
  576-атомной фикстуре) вместо гона несуществующего гейта — не блокирует,
  записано как наблюдение.
- Ручное тестирование в браузере — вне цикла ревью по регламенту;
  браузерный смок прогнан, это и есть замена.

## 8. Итог

High: 1 (докс-гейт красный на этом SHA — механический пропуск
`check-docs` после правки `src/**`, в скоупе, чинится в этой же задаче).
Medium: 0. Единственная находка r2 (M1) закрыта по существу и
подтверждена мутантом лично. Архитектурная часть решения (§4.1–§4.7)
унаследована из r2 без повторной проверки — дельта её не касается.