houseplan-card/docs/specs/330-junction-limits-performance.md

# Issue #330 — производительность ограничений стыков (#329)

Статус: ревизия 1. Родитель: #329 (лимиты выпущены, вердикты корректны —
подтверждено паритет-тестом и код-ревью r1–r3). Эта задача меняет ТОЛЬКО
стоимость вычисления вердиктов; ни один вердикт не меняется ни на бит.
Смежный #331 (пограничная точность) сознательно вне скоупа.

## 1. Сценарий и пользовательский результат

Замеры на `dev` `2c20f2dc`, синтетическая сетка комнат 300×300 см, стены
15 см, легаси-хранение (худший и одновременно типичный случай: первый
структурный write после обновления карточки):

| План | Бэкенд `validate_junction_limits` | из них 1 миграция | П3 | П4 |
|---|---|---|---|---|
| 6×6, 144 атома | 189 мс | 53 мс | 16 мс | 23 мс |
| 12×12, 576 атомов | **2 835 мс** | 754 мс | 285 мс | 376 мс |

Вся цепочка валидаторов `ws_config_set` выполняется синхронно в event loop
HA под write_lock — на 576 атомах каждое сохранение замораживает ВЕСЬ Home
Assistant почти на 3 секунды. `MAX_CONFIG_BYTES` = 2 МБ допускает документы
ещё на порядок больше. Гайдлайн HA: >50 мс в event loop недопустимо.

Фронтенд, те же 576 атомов: `checkSegmentLengths` — 289 мс/вызов,
`checkNodeDistances` — 105 мс; в ресайзе проверка кандидата зовётся на
каждый pointermove, а baseline (клон конфига + миграция + П1–П5 + polyclip
по комнатам) пересчитывается там же, хотя в течение жеста неизменен.

Результат для пользователя: сохранение большого плана не подвешивает HA;
ресайз на большом плане держит существующий кадровый бюджет.

## 2. Корни (по убыванию вклада)

1. **Две полные миграции на запись.** `validate_junction_limits` гонит и
   `previous`, и `candidate` через `commit_wall_segment_model` (deepcopy +
   каноникализация) — ~1.5 с из 2.8 на 12×12. `previous` между записями не
   меняется: его миграция и подсчёт нарушений выбрасываются и повторяются.
2. **П3 квадратичен в обеих реализациях.** `collinearRunLengthUnits` /
   `collinear_run_length_units` строит индекс узлов заново для КАЖДОГО
   сегмента → O(n²) с тяжёлой константой. Зеркала честно скопировали дефект
   друг друга.
3. **Фронтовый baseline без кэша.** `_junctionLimitsIntroduced` строит
   baseline-нарушения из previousConfig на каждый вызов; в жесте ресайза —
   на каждый move.

## 3. Границы

- Вердикты П1–П5 байт-идентичны текущим на любом входе. Существующие юниты
  границ, паритет-тест TS↔Python и все три мутанта #329 проходят без правок
  их семантики (мутантам разрешено обновить якоря, если строки сместились).
- Спека #329 (наследование по правилу, обе стороны после одной миграции,
  скоуп применения §3) не меняется.
- Вне скоупа: итеративный walk, точность ключей узлов, 0°-дубль (#331);
  optimize/import-лазейка (#333); пропуск миграции для уже-v9 документов —
  рассмотрен и отклонён: он меняет сравниваемое представление (кандидат от
  клиента не каноникализован) и рискует паритетом ради экономии, которую
  даёт rev-кэш.

## 4. Решение

### 4.1 Бэкенд: цепочка валидаторов в executor

В `ws_config_set` вынести CPU-часть цепочки (validate_wall_model_transition,
CONFIG_SCHEMA, marker/passage/host-валидаторы, validate_junction_limits) в
`async_add_executor_job` одной функцией над данными: вход — `msg["config"]`
и снапшот `data.get("config")`, выход — validated config либо типизированная
ошибка. Применение результата (`msg["config"].clear()/update`) и отправка
ответа остаются в loop. write_lock сохраняется — исключается только
блокировка loop, не сериализация записей. Паттерн в кодовой базе есть:
parse/merge импорта уже выполняются в executor.

`ws_plan_optimize` — тем же способом (он уже страдает той же синхронной
CONFIG_SCHEMA + миграцией на больших планах).

### 4.2 Бэкенд: кэш baseline по config_rev

На runtime-объекте — один слот `_junction_baseline: (config_rev, counts)`,
где counts — счётчики нарушений previous ПО ПРАВИЛАМ (то, что и потребляет
сравнение; сами документы не хранятся). Заполняется лениво при первом
validate, инвалидируется несовпадением rev. Повторные записи одного клиента
перестают мигрировать previous вовсе. `validate_junction_limits` получает
опциональный параметр `baseline_counts`; его отсутствие — прежний путь
(миграция previous), чтобы прямые вызовы и тесты не изменились.

### 4.3 Обе реализации: линейный П3

`checkSegmentLengths` / `check_segment_lengths` строит byNode-индекс один
раз и передаёт его в прогон коллинеарной цепочки; публичная сигнатура
`collinearRunLengthUnits(segment, segments)` сохраняется (индекс — третий
опциональный аргумент; без него строится как раньше — для прямых вызовов
из тестов).

### 4.4 Фронтенд: кэш baseline на конфиг-эпоху

`_junctionLimitsIntroduced` кэширует baseline-нарушения по ключу
`${spaceId}|${cfgEpoch}` (один слот, как _wallUnionCache). `_cfgEpoch`
инкрементится при каждом изменении конфига, поэтому инвалидация бесплатна и
консервативна: любой реальный write сбрасывает кэш. Жест ресайза считает
baseline один раз вместо «на каждый move».

## 5. Перф-контракт (новый, в CI)

`demo/benchmark_junction_limits.mjs` по образцу `benchmark_safe_resize.mjs`:
сетка 12×12 (576 атомов), бюджеты в файле бенча:

- фронт: `checkSegmentLengths` ≤ 25 мс, полный `_junctionLimitViolations`
  кандидата ≤ 60 мс (p95 из N прогонов);
- бэкенд (запускается тем же бенчем через python3): полный
  `validate_junction_limits` с тёплым rev-кэшем ≤ 150 мс, холодный ≤ 900 мс.

Бюджеты — 2–3× от замеренного после фикса, чтобы бенч ловил регресс класса
«вернули O(n²)», а не дрожание раннера. Включается в перф-джобу CI рядом с
существующими бенчами.

## 6. Acceptance criteria

- **AC1 (event loop).** Запись 576-атомного конфига блокирует event loop
  ≤ 50 мс: backend-тест меряет время синхронной части `ws_config_set`
  (инструментированный вызов); полная цепочка живёт в executor.
- **AC2 (П3 линейный).** 576 атомов: `checkSegmentLengths` ≤ 25 мс (фронт),
  `check_segment_lengths` ≤ 100 мс (python) — бенч из §5; вердикты на
  фикстурах паритет-теста не изменились (существующий тест).
- **AC3 (rev-кэш).** Две подряд записи с одним previous: вторая не вызывает
  `commit_wall_segment_model` для previous (тест со счётчиком вызовов через
  monkeypatch); смена rev инвалидирует кэш; вердикты идентичны пути без
  кэша на обеих фикстурах (унаследованное нарушение / новое нарушение).
- **AC4 (фронт-кэш).** В одном жесте ресайза baseline считается один раз:
  юнит на `_junctionLimitsIntroduced` со счётчиком, плюс существующий
  `benchmark_safe_resize` держит прежний pointer-бюджет на large-house.
- **AC5 (семантика не тронута).** Все существующие юниты #329, паритет-тест,
  смоки `smoke_junction_limits`/`smoke_island_rooms`/`smoke_room_resize` и
  мутанты `junction-limit-*` зелёные без изменения ожиданий.
- **AC6 (перф-контракт).** Бенч §5 в CI, красный при возврате O(n²)
  (проверяется мутантом на «строить индекс на каждый сегмент»).

## 7. План тестов

Юниты: rev-кэш (заполнение, инвалидация, эквивалентность вердиктов),
baseline-кэш фронта (одно вычисление на эпоху), эквивалентность П3 с
индексом и без на фикстурах границ. Бенч §5. Мутанты: `junction-limit-p3-
quadratic-again` (индекс на каждый сегмент — бенч красный),
`junction-limit-baseline-cache-stale` (кэш не инвалидируется по rev — тест
эквивалентности красный). Бэкенд: тест синхронного времени AC1.

## 8. Откат

Чистый revert: изменения не трогают формат данных, конфиг и контракт
WebSocket-команд; кэши — только в памяти процесса.