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

SPEC-REVIEW-330-r1

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

Материал: docs/specs/330-junction-limits-performance.md на SHA f1b7c237 (HEAD ветки issue/330-junction-limits-performance на момент ревью), тело issue #330 и оба комментария (S2-аналитика, объявление ТЗ).

Скоуп

ТЗ описывает исключительно производительность существующей валидации ограничений стыков (#329): вынос цепочки валидаторов ws_config_set/ ws_plan_optimize в executor, rev-кэш счётчиков previous, линеаризация П3 (checkSegmentLengths/check_segment_lengths) через переиспользуемый byNode-индекс, и фронтовый кэш baseline на конфиг-эпоху. Явно заявлено: ни один вердикт П1–П5 не меняется. Трек — полный (перф-влияние исключает small), что верно по критериям §5 PROCESS.md.

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

Читкой, без исполнения. Против каждого пункта решения (§4) и каждого AC (§6) проверялся код, который они описывают, чтобы отделить утверждение от факта:

• custom_components/houseplan/websocket_api.py:1280-1398 (ws_config_set, синхронная цепочка валидаторов под write_lock, MAX_CONFIG_BYTES) — подтверждает описание проблемы дословно.
• custom_components/houseplan/junction_limits.py:150-317 (collinear_run_length_units, check_segment_lengths, check_node_distances, validate_junction_limits) — корень П3 (индекс строится заново на каждый сегмент) подтверждён; заодно проверена стоимость П4.
• src/junction-limits.ts:121-169 и src/houseplan-card.ts:7418-7473 (checkSegmentLengths, checkNodeDistances, _junctionLimitViolations, _junctionLimitsIntroduced) — та же проверка на фронте, плюс состав «полной» функции, на которую ссылается перф-бюджет §5.
• demo/benchmark_safe_resize.mjs (полностью) — существующий бенч, на который опирается AC4.
• grep async_add_executor_job по custom_components/houseplan/*.py — подтверждение прецедента, на который ссылается §4.1.
• docs/SCOPE.md, PROCESS.md §2.4/§2.5/§4/§5/§7.1 — рамка ревью и обязательные разделы.

Не проверялось (и не требовалось на этом этапе): исполнение кода, реальные замеры производительности — числа взяты из S2-аналитики автора и приняты как факт (это их роль на этом этапе; воспроизводить их — работа код-ревью).

Находки

H1 — Перф-бюджеты §5 недостижимы решением из §4: AC2 и AC6 непроверяемы как написаны

docs/specs/330-junction-limits-performance.md §5, AC2, AC6.

Собственные цифры автора (комментарий S2-аналитики и §1 ТЗ) на сетке 12×12 / 576 атомов:

Компонент	Значение	Кем адресуется в §4?
Бэкенд, 1× миграция (commit_wall_segment_model)	754 мс	rev-кэш (§4.2) убирает миграцию только стороны previous; сторона candidate мигрируется заново на КАЖДУЮ запись — это неустранимо текущей архитектурой и в §4 не тронуто.
Бэкенд, П4 (check_node_distances)	376 мс	Не адресуется никем. Ни §2 (корни), ни §4 не называют П4 квадратичным дефектом — и по коду (junction_limits.py:211-245) это не «баг переиспользуемого индекса», как П3, а架构рно O(n²) все-пары-узлов плюс O(n·m) узел-к-стене — линеаризовать так же, как П3, нельзя без отдельного решения (spatial index), которого в ТЗ нет.
Фронт, П4 (checkNodeDistances)	105 мс	Аналогично не адресуется.

Уже из одной только суммы «миграция candidate (754 мс) + П4 бэкенд (376 мс)» = 1130 мс — при заявленном тёплом бюджете ≤ 150 мс (§5) и AC6 «красный при возврате O(n²)». Это не «близко к порогу» — это расхождение на порядок, и оно основано на цифрах, которые сам автор привёл как измеренные. То же для фронта: П4 (105 мс) сам по себе почти вдвое превышает бюджет «полный _junctionLimitViolations кандидата ≤ 60 мс», при том что П4 — только один из компонентов внутри _junctionLimitViolations (src/houseplan-card.ts:7418-7441, там же ещё checkNodes и цикл checkRoomClearance/innerContourForRoom по комнатам, чья стоимость нигде не измерена и не бюджетирована).

Почему это находка, а не придирка к цифре. §4.1–4.4 перечисляют РОВНО четыре среза изменений (executor-вынос, rev-кэш previous, линейный П3, фронт-кэш baseline). Ни один не снижает стоимость (а) обязательной миграции candidate на каждую запись, (б) П4 в обеих реализациях. Значит бюджеты §5 либо взяты без пересчёта относительно уже собственноручно измеренных компонентов (см. таблицу выше — цифры лежат в том же документе/треде), либо подразумевают пятое, неописанное изменение (например, пространственный индекс для П4, или отказ от полной миграции candidate). Ни то, ни другое не названо явно — а значит автор выдал число за решённое, не проверив его арифметикой, которую сам же привёл строкой выше. Это ровно то, что этап spec-review обязан ловить: не «согласиться», а найти, где ТЗ не проверяемо.

Практическое следствие: реализовав буквально §4.1–4.4 и запустив benchmark_junction_limits.mjs из §5, разработчик получит красный перф-контракт независимо от качества работы — потому что AC2/AC6 требуют результата, которого выбранное решение физически не даёт. Это либо возвращает задачу в «В разработке» после несостоявшегося код-ревью (трата цикла впустую), либо толкает разработчика тихо расширить скоуп без ТЗ (находка П4 как quadratic bug, которую §3 явно не резервирует под #331 — #331 про точность ключей и 0°-дубль, не про производительность П4).

Что нужно поправить одним из двух способов:

1. пересчитать бюджеты §5 от реальных достижимых значений (учитывая неустранимую миграцию candidate и нетронутую стоимость П4), с явным указанием, откуда цифра взята; или
2. добавить в §2/§4 пятый срез — оптимизацию П4 (обе реализации) и/или устранение обязательной полной миграции candidate — со своим AC и доказательством, раз она нужна для достижения заявленных 60/150 мс.

Оба варианта — правка внутри этого же issue (Medium по объёму работы, но блокирует как High, потому что без неё AC2/AC6 недоказуемы в принципе, а не «доказуемы с оговоркой»).

H2 — AC4 ссылается на бенч, который не вызывает изменяемый код

docs/specs/330-junction-limits-performance.md AC4: «…плюс существующий benchmark_safe_resize держит прежний pointer-бюджет на large-house».

Прочитан demo/benchmark_safe_resize.mjs целиком: он меряет clampEdgeDrag/resolveSafeResize/clampSafeResize/applySafeResize из test-build/resize.js и checkOptimizeGeometry из test-build/plan-geometry-preflight.js. Ни один из этих путей не вызывает _junctionLimitsIntroduced, checkSegmentLengths или checkNodeDistances — это отдельная реализация ресайза (низкоуровневый safe-resize примитив), не тот код, который правит эта задача. Код, который реально меняется (_junctionLimitsIntroduced в src/houseplan-card.ts:7452-7473, вызывается из _rszSpaceCandidateGeometry на каждый шаг ресайза, houseplan-card.ts: ~9041), в benchmark_safe_resize.mjs не участвует вовсе.

Значит регресс именно в том коде, который §330 чинит, этим бенчем не будет пойман — ни до фикса (он и сейчас не показывает проблему, потому что не меряет её), ни после (он не докажет, что фикс сработал). AC4 как написан создаёт видимость покрытия там, где его нет: «существующий бенч держит бюджет» — верное, но нерелевантное утверждение, поданное как доказательство продуктового обещания «ресайз на large-house держит кадровый бюджет».

Что нужно поправить: либо расширить/создать бенч, который вызывает _junctionLimitsIntroduced/checkSegmentLengths в контексте одного жеста ресайза (это и есть предмет AC4 — «в одном жесте baseline считается один раз»), либо снять ссылку на benchmark_safe_resize из доказательства AC4 и оставить только юнит на счётчик вызовов (который в AC4 уже есть и сам по себе корректен).

M1 — Отсутствуют обязательные разделы ТЗ по §7.1: i18n, touch, риски, release-артефакты

docs/specs/330-junction-limits-performance.md, целиком.

§7.1 PROCESS.md перечисляет обязательные разделы ТЗ: сценарий · что человек увидит до/после · проблема · скоуп/не-скоуп · контракт поведения · UX · модель данных и миграция · i18n · AC с доказательством · план автотестов · риски · откат · release-артефакты. В документе явно закрыты: сценарий (§1), проблема (§1), скоуп/не-скоуп (§3), контракт поведения и модель данных (§4 + §8 «откат» покрывает «формат данных не меняется»), AC (§6), план автотестов (§7), откат (§8).

Полностью отсутствуют как отдельные утверждения:

• i18n — ни слова; для этой задачи корректный ответ тривиален («нет новых строк»), но он должен быть написан, а не подразумеваться — DoR (§2.5) требует «ключи en+ru перечислены» именно как явный пункт;
• touch — не сказано, что жест ресайза (в т.ч. на touch, best-effort по TOUCH-SUPPORT.md) использует тот же код и получает тот же выигрыш; для DoR это обязательный явный пункт, а не факт по умолчанию;
• риски — нет отдельного раздела (в §2 «Корни» перечислены причины медленности, но не риски решения: например, что кэш _junction_baseline на runtime-объекте — единственный слот, и конкурентная запись в другое пространство того же конфига инвалидирует его чаще, чем ожидается — это не баг, но риск, который стоит явно взвесить в ТЗ, а не оставлять ревьюеру код-ревью находить постфактум);
• release-артефакты — не названы changelog RU+EN, документация, golden/скриншоты (для чисто перф-задачи, вероятно, не нужны — но правило §7.1 требует явного «нет», а не отсутствия раздела).

Ничего из этого не блокирует техническую состоятельность решения — все четыре пункта, скорее всего, разрешаются одной строкой каждый («i18n: нет», «touch: тот же код, ускорение применяется одинаково», «риск: единственный слот кэша инвалидируется по rev, race исключён write_lock», «release: changelog не нужен — не user-visible поведенчески, только perf»). Но без явной записи это дыра в DoR §2.5, которая иначе будет обнаружена только на входе в очередь «Готово к разработке» и вернёт задачу обратно.

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

• Корень П3 (checkSegmentLengths/check_segment_lengths строит byNode- индекс заново на каждый сегмент → O(n²)) подтверждён чтением обеих реализаций — не догадка, реальный дефект, фикс (передать индекс третьим опциональным параметром) технически корректен и не меняет публичную сигнатуру для прямых вызовов.
• Синхронность цепочки валидаторов ws_config_set под write_lock в event loop подтверждена построчно (websocket_api.py:1303-1334); прецедент async_add_executor_job в том же файле и соседних модулях (__init__.py, http_api.py) подтверждён — решение §4.1 не изобретает новый паттерн.
• Граница §3 («вердикты П1–П5 не меняются») сформулирована однозначно и проверяема существующим паритет-тестом и тремя мутантами #329 — это не голословное заявление, у него есть механизм проверки.
• Откат (§8) корректен: кэши только в памяти процесса, формат данных не меняется — ревертится действительно чисто.
• AC1, AC3, AC5 однозначны и имеют названный способ доказательства (backend-тест инструментированного времени; тест счётчика вызовов commit_wall_segment_model через monkeypatch; существующие юниты/паритет- тест/смоки/мутанты). Догадок, выданных за факт, в этих трёх AC не найдено.
• Продуктовая рамка (§7.1 «сценарий» + «что человек увидит») по существу присутствует и корректна: персона home admin на десктопе не названа явно, но однозначно выводится из контекста (сохранение конфига и ресайз — только редакторские действия) — это не отдельная находка, различие между «выводится однозначно» и «отсутствует» здесь в пользу автора.
• Открытых продуктовых вопросов, вынесенных владельцу как технические (§7.1, запрещённый класс), в ТЗ и комментариях не найдено — оба комментария автора чисто аналитические/технические и решены им самим, что соответствует правилу «владельцу — только продуктовые вопросы».

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

• Не запускал npm test/pytest/бенчи — на этапе spec-review это не предусмотрено (кода изменения ещё нет, есть только текст ТЗ и уже существующий, не тронутый этой веткой код).
• Не проверял актуальность файла AUDIT-2026-08-28.md, упомянутого в теле issue — файл не найден в дереве репозитория (find не дал результата); это, вероятно, внешний документ или ещё не закоммитчен. Не блокирует ревью ТЗ: цифры из него продублированы и подтверждены в S2-комментарии, который я проверил по коду напрямую.
• Не оценивал точную конструкцию будущего _junction_baseline кэша (структура counts, инвалидация на несколько пространств одного конфига) глубже, чем нужно для проверки конкурентной безопасности под write_lock — это техническая деталь реализации, которую §7.1 явно оставляет на усмотрение авторов кода, а не ТЗ.

Вывод

Решение технически обосновано и корни (кроме недостающего П4) описаны доказательно, не как догадка. Но два High-находки делают документ непроверяемым в буквальном смысле процесса: AC2/AC6 (H1) и AC4 (H2) не могут быть подтверждены тем набором изменений и тем бенчем, которые ТЗ само же описывает. Это возврат автору на правку числа/скоупа решения, не отклонение идеи задачи.