houseplan-card/docs/reviews/SPEC-REVIEW-330-r2.md

# SPEC-REVIEW-330-r2

Issue: #330 · Этап: spec (ТЗ на ревью, PROCESS.md §2.4) · Заход r2 ·
блокирующих циклов 1/4

Материал: `docs/specs/330-junction-limits-performance.md` на SHA `36a4aa70`
(HEAD на момент ревью). Предыдущий вердикт: жёлтый, заход r1, документ
`docs/reviews/SPEC-REVIEW-330-r1.md`, получен на SHA `f1b7c237`.

## Скоуп

Ревизия 2 правит два High и один Medium из r1: пересчитывает перф-бюджеты §5
от профилированных чисел (H1), добавляет два новых среза решения — §4.5
(bucket-индекс для П4 в обеих реализациях) и §4.6 (документ текущей версии
не мигрируется повторно), переписывает AC2–AC7 под новую доказательную базу
и заменяет ссылку AC4 на новый бенч вместо нерелевантного
`benchmark_safe_resize` (H2), добавляет §9 с обязательными разделами i18n/
touch/риски/release-артефакты (M1). Продуктовая рамка (§1: сценарий, что
человек увидит) и граница «вердикты П1–П5 не меняются» (§3) — без изменений.

Дельта не локальна: она меняет состав самого технического решения (два
новых среза, §4.5/§4.6), весь перф-контракт §5 и весь набор AC — то есть
затрагивает больше половины документа и требует полной переверки этой части,
а не только «строк, где стоят r1-H1/H2/M1». Разбор ниже — полный по §2–9;
инвентаризация §7.1 и продуктовая рамка §1 унаследованы из r1 без повторной
проверки (раздел «Унаследовано» ниже) — они делтой не задеты.

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

Чтением, без исполнения — на этапе spec иное не предусмотрено. Против
каждого нового утверждения решения проверялся код, который оно описывает,
чтобы отделить профилированный факт от догадки:

- `custom_components/houseplan/wall_segment_model.py:674-684`
  (`commit_wall_segment_model`) — подтверждает предпосылку §4.6: функция
  прогоняет `_migrate_space`/`_atomize` для КАЖДОГО пространства безусловно,
  включая документ, чей `model_version` уже равен `WALL_SEGMENT_MODEL_VERSION`
  (флаг `initial_migration` меняет логику присвоения id внутри
  `_migrate_space`, но не пропускает атомизацию целиком). Утверждение «деньги
  не в deepcopy, а в `_atomize` даже для актуального документа» — не
  голословно.
- `custom_components/houseplan/junction_limits.py:150-245`
  (`collinear_run_length_units`, `check_node_distances`) — подтверждает, что
  П4 — все пары узлов (`O(n²)`) плюс узел×сегмент, отдельный от П3 дефект
  архитектуры, а не переиспользуемый индекс, как заявлено в §2 п.3 и §4.5.
- `custom_components/houseplan/websocket_api.py:1280-1341` (`ws_config_set`)
  — подтверждает, что `validate_wall_model_transition` (барьер модели)
  выполняется безусловно и валидирует документ целиком ДО
  `validate_junction_limits` — предпосылка §4.6 «барьер ниже по конвейеру
  по-прежнему валидирует документ целиком» верна, риск «клиент прислал
  неканонический v9» действительно закрыт независимым барьером, а не только
  AC5.
- `src/houseplan-card.ts:7418-7473, 12896, 13044` и
  `src/wall-segment-model.ts:821-827` — подтверждают, что фронтенд сам
  выставляет `model_version = 9` при клиентской миграции и различает
  `_serverCfg.model_version >= 9`: гипотеза «типичный кандидат уже v9 после
  первого сохранения» опирается на реальный код, а не на предположение.
- Существующие файлы, на которые ссылаются AC/§7: `test/junction-limits.test.mjs`,
  `tests_backend/test_junction_limits.py`, `demo/smoke_junction_limits.mjs`,
  `demo/smoke_island_rooms.mjs`, `demo/smoke_room_resize.mjs` — существуют.
  `demo/benchmark_junction_limits.mjs` — не существует (и не должен: код ещё
  не написан, это предмет реализации).
- `scripts/mutation-gate.mjs:541-580` — три существующих мутанта
  `junction-limit-*` подтверждают, что новые имена мутантов в §7
  (`junction-limit-p3-quadratic-again`, `junction-limit-p4-bruteforce-again`,
  `junction-limit-baseline-cache-stale`) следуют реальному соглашению
  именования, а не придуманы.
- Арифметика §5 сверена построчно с числами §2 (корни) и с числами r1-H1
  (754/376/105 мс) — см. «Что проверено и корректно».

Не проверялось: исполнение прототипов (44 мс/бакет-П4 и т.д. — числа автора,
принятые как измеренные там, где так и помечено, и как «ожид.» там, где
помечено оценкой). Это работа код-ревью, не этого этапа.

## Закрытие раунда r1

| Находка r1 | Чем закрыта | Где видно |
|---|---|---|
| **H1** — бюджеты §5 недостижимы решением §4 (сумма «миграция candidate 754 мс + П4 бэкенд 376 мс» = 1130 мс против заявленных ≤150 мс) | Добавлены два новых среза решения: §4.5 (bucket-индекс П4, прототип 372→44 мс на python, вердикты идентичны) и §4.6 (документ с актуальным `model_version` используется без повторной миграции — снимает 754/69 мс на типичном горячем пути). Бюджеты §5 пересчитаны от чисел этих прототипов, с явным разделением «тёплый путь» (v9-кандидат, rev-кэш previous) и «холодный» (легаси, единственный случай, укладывается в лимит только потому, что цепочка уже в executor согласно §4.1) | `docs/specs/330-junction-limits-performance.md` §4.5, §4.6, §5 (таблица), AC1/AC2/AC5. Код-предпосылки подтверждены чтением: `wall_segment_model.py:674-684`, `websocket_api.py:1325-1334` |
| **H2** — AC4 ссылался на `benchmark_safe_resize`, который не вызывает изменяемый код | AC4 переписан: доказательство — юнит-счётчик на `_junctionLimitsIntroduced` (как и было) плюс НОВЫЙ бенч §5, который явно описан как измеряющий «TS-проверки П1–П5 напрямую и полный `_junctionLimitViolations` на смонтированной карточке»; `benchmark_safe_resize` в тексте AC4 прямо названо как не-доказательство («r1-H2») | `docs/specs/330-junction-limits-performance.md` §5, AC4 |
| **M1** — отсутствуют i18n/touch/риски/release-артефакты (§7.1 DoR) | Добавлен §9 с четырьмя явными пунктами: i18n «нет», touch «не задет», три названных риска (executor/write_lock, эквивалентность §4.6, геометрическая эквивалентность bucket-П4) с указанной для каждого проверкой, release-артефакты (обычная бета, одна строка CHANGELOG RU+EN, без миграции) | `docs/specs/330-junction-limits-performance.md` §9 |

## Находки

Нет находок уровня High или Medium.

**Low-1 (снята решением ревьюера, без правки).** Строка §5 «холодный
(легаси-обе-стороны)» описывает синтетический худший случай для бенча, а не
типичный сценарий «первая запись после обновления» (в котором, по коду
фронтенда, `candidate` уже несёт `model_version: 9`, а легаси остаётся только
`previous`). Название не искажает AC и не меняет бюджет — бенч просто держит
более тяжёлый из двух легаси-случаев с запасом. Не блокирует: ни один AC не
опирается на точное соответствие названия сценарию, и §2 отдельно описывает
реальный случай смешанной версии.

**Low-2 (снята решением ревьюера, без правки).** Ряд §5 «TS `checkNodeDistances`
(П4, 576) ~15 мс» помечен как «ожид.», но в тексте §4.5 измерен прототип
только для python (372→44 мс); TS-число — экстраполяция по той же
пропорции, не отдельный замер. Это не «догадка, выданная за факт»: колонка
честно озаглавлена «После фикса (ожид.)», и AC2/AC7 всё равно требуют
подтверждения бенчем и мутантом на этапе код-ревью — оценка не подменяет
доказательство.

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

- Арифметика бюджетов §5 сходится с числами §2 и r1: тёплый путь (линейный
  П3 + bucket-П4 44 мс + отсутствие повторной миграции v9-кандидата) даёт
  порядок «около 100 мс» бэкенд / «около 40 мс» фронт — это прямо снимает
  расхождение на порядок, из-за которого r1 поставил H1. Холодный путь
  (~1.7 с) остаётся только в executor (AC1 требует loop-времени, а не
  общего CPU-времени), поэтому попадание в ≤50 мс loop-бюджета не зависит от
  того, насколько медленна миграция легаси-документа.
- §4.6 не противоречит #329: барьер `validate_wall_model_transition`
  (`websocket_api.py:1325`) выполняется независимо от лимитов и валидирует
  документ целиком, так что пропуск повторной миграции в путях лимитов не
  открывает дыру для непроверенного «поддельного v9».
- AC5 (эквивалентность §4.6) сформулирован проверяемо: конкретные фикстуры
  границ (14°/15°, 19/20 см, T-стык, доборный атом), существующий механизм —
  паритет-тест, который уже есть в `test/junction-limits.test.mjs`/
  `tests_backend/test_junction_limits.py`.
- AC4 больше не создаёт видимость покрытия: новый бенч явно вызывает именно
  изменяемый код, а не соседний примитив ресайза.
- §9 закрывает все четыре пункта M1 явными и по существу корректными
  ответами (в частности, риск «неканонический v9» получает named
  mitigation, а не декларацию).
- Имена новых мутантов и ссылки на существующие смоки/тесты в §7
  соответствуют реальному дереву репозитория — не выдуманы.
- Открытых продуктовых вопросов владельцу по-прежнему нет; ревизия 2 —
  целиком технический ответ на технические находки r1, что и требовалось
  (§7.1: технический спор автора и ревьюера решается вердиктом ревью, не
  эскалируется).

## Чего не проверял

- Не запускал `npm test`/`pytest tests_backend`/`typecheck`/бенчи — на этапе
  spec-review это не предусмотрено PROCESS.md §2.4 (кода этой задачи ещё
  нет; тронут только текст ТЗ).
- Не выполнял прототипы автора (cProfile/bucket-индекс) — их числа приняты
  как измеренные там, где это прямо написано («по профилю», «прототип на
  python»), и как оценка там, где написано «ожид.» (см. Low-2). Воспроизвести
  эти числа под нагрузкой — работа код-ревью по AC1/AC2/AC7.
- Не проверял детали будущей структуры bucket-индекса П4 (шаг сетки,
  9-окрестность) глубже, чем нужно для проверки правдоподобия заявленного
  ускорения — §7.1 оставляет конструкцию реализации на усмотрение авторов
  кода.
- Не проверял `AUDIT-2026-08-28.md` (упомянут в теле issue) — не найден в
  дереве репозитория; как и в r1, не блокирует: цифры продублированы и
  подтверждены в аналитике и в этом документе напрямую по коду.

## Унаследовано из r1

Без повторной проверки в этом раунде — делта их не касается:

- Продуктовая рамка §7.1 («сценарий», «что человек увидит», персона home
  admin на десктопе выводится из контекста) — принята в
  `docs/reviews/SPEC-REVIEW-330-r1.md` на SHA `f1b7c237`, текст §1 не менялся
  в ревизии 2 (сверено диффом `f1b7c237..36a4aa70`).
- Корень П3 (`collinear_run_length_units` строит индекс заново на каждый
  сегмент) и синхронность цепочки `ws_config_set` под `write_lock` в event
  loop — подтверждены чтением кода в r1 (`junction_limits.py`,
  `websocket_api.py:1303-1334`), в этом раунде код не менялся, повторно не
  перечитывал построчно (кроме диапазона 1280-1341, проверенного заново для
  H1/§4.6 — см. «Как проверялось»).
- Граница §3 «вердикты П1–П5 не меняются ни на бит» и механизм её проверки
  (паритет-тест + три мутанта #329) — принята в r1, текст границы в ревизии 2
  расширен (добавлена одна строка про атомизацию вне скоупа), но сама
  граница и её проверяемость не изменились.
- Откат §8 (чистый revert, кэши только в памяти) — не менялся, принят в r1.
- Отсутствие открытых продуктовых вопросов владельцу — подтверждено в r1 и
  остаётся верным: оба цикла (r1→r2) были чисто техническими.

## Вывод

Оба High и Medium из r1 закрыты по существу, с кодовым подтверждением
ключевых новых предпосылок (§4.6 — барьер модели независим и валидирует
документ целиком; премисса «типичный кандидат уже v9» опирается на реальный
код фронтенда, а не на догадку). Новых High/Medium решение не вносит.
Вердикт: зелёный.