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

SPEC-REVIEW-331-r1

Issue: #331 — «Ограничения стыков (#329): пограничная точность даёт ложные отказы и невидимые дубли» ТЗ: docs/specs/331-junction-limit-precision.md Ветка/SHA материала: issue/331-junction-limit-precision @ 60e125e9 Трек: полный (не small; аналитик явно назвал критерий, который задача не проходит: «две поверхности — оба зеркала + барьер карточки», меняются вердикты граничных классов). Заход: r1 · блокирующих циклов израсходовано (до этого раунда) 0 из 4.

Скоуп

ТЗ описывает шесть нормативных правок к #329 (junction-limits.ts / junction_limits.py): квантование ключа узла + инцидентность П4, снятие фильтра degrees > EPS в П1, итеративный обход П3 с выбором максимальной ветви на развилке, коллинеарность дуги к базе прогона, fail-closed на кандидате, сужение except Exception в _migrated_spaces. Родитель #329, сестринские issue вне скоупа (#333, #339) — учтены и явно исключены. Первого коммита с продуктовым кодом ещё нет — на ветке лежит только файл ТЗ (60e125e9, один файл, спецификация).

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

Прочитаны в порядке из инструкции: docs/SCOPE.md, AGENTS.md, PROCESS.md §2.4/§7.1, тело issue #331 и оба комментария (S2-аналитика, хендофф автора ТЗ), docs/USER-GUIDE.ru.md (раздел «Ограничения стыков стен»), канонический документ подсистемы — здесь это не WALL-THICKNESS.md (он про геометрию mitre/bevel, не про правила П1–П5), а собственный файл родителя docs/specs/329-junction-limits.md, использованный как эталон формата и терминологии. Для проверки числовых утверждений ТЗ прочитан текущий код: src/junction-limits.ts, custom_components/houseplan/ junction_limits.py, src/coordinate-canonicalization.ts и её питон-зеркало coordinate_canonicalization.py (существующий канонический механизм округления координат в этом же репозитории — нужен, чтобы проверить, не изобретает ли ТЗ параллельный, менее надёжный способ).

Гейты typecheck/test/build не гонялись: продуктового кода в диффе нет, дифф — исключительно новый файл docs/specs/331-*.md (класс C). Это стадия spec, а не code; §8/§10.2 PROCESS.md к ней не применяются.

Находки

High

H1. Ключ узла квантуется через round(), а не через уже принятый в этом репозитории cross-language-safe механизм — риск разойтись между TS и Python ровно на точке .5-кванта.

docs/specs/331-junction-limit-precision.md:35 предписывает: «Ключ узла — координаты, квантованные к 1e-7 (round(v·1e7)/1e7)... формат строки ключа одинаков в TS и python». Формулировка не называет, какой именно round имеется в виду, и умалчивает про то, что нативные функции округления в TS и в Python расходятся на .5-тиках: JS Math.round всегда округляет дробную половину в сторону +∞ (Math.round(2.5) === 3, Math.round(-0.5) === -0), а Python round() — банковское округление к чётному (round(2.5) == 2, round(0.5) == 0).

Это не гипотеза, а задокументированный факт этого же репозитория: src/coordinate-canonicalization.ts:47-53 (canonicalizeNumber) и её зеркало custom_components/houseplan/coordinate_canonicalization.py:20-31 (canonicalize_number) намеренно НЕ используют round/Math.round — обе стороны считают sign * floor(abs(value) * FACTOR + 0.5) / FACTOR, и питоновский файл прямо комментирует причину в coordinate_canonicalization.py:45: # JavaScript Math.round: ties go toward +infinity, unlike Python round(). Тот же файл содержит второй метод (canonicalize_lattice_coordinate) — оба используют идентичную формулу именно ради паритета на тиках.

Конкретное воспроизведение расхождения для формулы ТЗ «round(v·1e7)/1e7», если её реализовать буквально нативными функциями: v = 0.00000025 (2.5e-7 в нормализованных координатах — не экзотика, а ровно середина между двумя соседними квантами, куда попадают, например, масштабированные «круглые» координаты после cmToUnits). v·1e7 = 2.5. Math.round(2.5) = 3 → ключ 3e-7. Python round(2.5) = 2 → ключ 2e-7. Один и тот же candidate получает разные ключи узла на фронте и на бэкенде — то есть ровно тот класс дефекта, который в этом же ревью явно назван дважды дорогим (#258, #259: ключ записи толщины не совпал с ключом решёточного ребра). AC1 требует паритет «через паритет-набор», но паритет-набор проверяет исходы, а не формулу; конкретно эта пара тиков в него может не попасть, и тогда разъезд ключей останется незамеченным до продакшна — ровно тем способом, каким приходили #258/#259.

Правка ТЗ: заменить round(v·1e7)/1e7 на явную, одинаковую в обеих сторонах формулу с зафиксированным направлением округления половинки (например, переиспользовать уже принятый в проекте sign * floor(abs(v)*1e7+0.5)/1e7 из coordinate-canonicalization, а не изобретать новую). Замечание в скоупе задачи, чинится тем же ТЗ.

Medium

M1. Собственный пример AC1 не проходит собственный порог инцидентности.

docs/specs/331-junction-limit-precision.md:44 формулирует инцидентность П4 так: «пары узлов с евклидовой дистанцией ≤ 1e-7 считаются ОДНИМ узлом... (например −5.1e-8 и 5.1e-8)», и AC1 (:98) повторяет этот же пример как «пара «через границу кванта» — ноль [нарушений]».

Арифметика: |5.1e-8 − (−5.1e-8)| = 1.02e-7, что строго больше 1e-7. По букве правила эта пара НЕ инцидентна (дистанция не ≤ 1e-7), а значит по П4 это два разных узла на дистанции 1.02e-7 нормализованных единиц — величина на четыре порядка меньше реального порога 5 см (≈4e-4), то есть ровно тот случай, который правило обязано отклонить как «слишком близко». Реализованная строго по тексту формула провалит собственный пример AC1: либо порог должен быть не ≤1e-7, а как минимум ≤1.02e-7 (например 2× кванта, что заодно естественно закрывает произвольную пару тиков по разные стороны границы округления), либо числа примера должны быть скорректированы (например −4.9e-8/4.9e-8, дистанция 9.8e-8 ≤ 1e-7). Как написано, AC1 неоднозначен ровно на том примере, который должен его иллюстрировать.

M2. Не решено, распространяется ли fail-closed §2.6 на сторону previous, и не создаёт ли это новый способ отклонить непричастную запись.

_migrated_spaces (custom_components/houseplan/junction_limits.py:300-330) вызывается для ОБЕИХ сторон сравнения: _migrated_spaces(previous) (baseline) и _migrated_spaces(config) (candidate). ТЗ §2.6 сужает except Exception до (WallSegmentMigrationError, ValueError) для этой функции целиком, не различая вызовы.

Для candidate это соответствует уже принятому в этом же ТЗ принципу fail-closed (§2.5). Но для previous ТЗ прямо в соседнем пункте (§2.5) формулирует другой принцип: «Baseline остаётся fail-open (недоказуемое наследование не повод отклонять запись) — асимметрия сознательная и комментируется в коде». §2.6 эту асимметрию не упоминает вовсе. Если _migrated_spaces(previous) теперь бросает TypeError/RecursionError на каком-то экзотическом, но уже существующем (то есть когда-то принятом) документе, а не глотает его — запись, вообще не касающаяся геометрии стен, будет честно отклонена ошибкой WS. Это именно симптом «легитимная запись отклонена», ради устранения которого заведена вся задача (P1, дважды ударивший по бетам — #316, #319), только теперь по новой причине.

Может быть, это осознанный выбор (surfacing реальных багов миграции важнее доступности) — но тогда он должен быть назван явно, как назван для §2.5, а не выведен по умолчанию из общей формулировки. AC6 (:113) не говорит, к какой стороне (previous/candidate/обеим) относится тестовый документ с TypeError — без этого AC не проверяем однозначно.

M3. Максимальная ветвь ищется DFS-перебором вариантов; наихудшая сложность не оценена и не застрахована стресс-тестом, при жёстком требовании удержать бюджет бенча #330.

§2.3 (:58-60): «При развилке из нескольких коллинеарных продолжений одной толщины берётся максимальная ветвь (DFS по вариантам, visited на рёбрах)». Валентность узла ограничена П2 (≤6), но это ограничивает только ветвление В ОДНОМ узле, а не число узлов-развилок вдоль цепочки: документ, где подряд идут K развилок по 2-3 равноценные по толщине коллинеарные продолжения, даёт полный перебор комбинаций порядка 2^K..3^K, а не линейную сложность. Это тот же класс входа, что уже один раз уронил П3 (рекурсия на длинной цепочке, #331 п.3) — только вместо глубины стека уязвимое место сместилось на число развилок.

§3 требует бюджеты бенча #330 зелёными без изменений, AC7 — то же самое, но план тестов (§5) и AC3 проверяют только (а) один прямой прогон на 10 000 атомов (проверяет только стек, без развилок) и (б) «развилку двух коллинеарных ветвей» — судя по формулировке, единичную, не цепочку из многих развилок. Ни один AC/мутант не нагружает именно комбинаторику перебора. Это не значит, что реализация обязательно медленная — но ТЗ утверждает бюджет бенча гарантированным, не предъявляя для этого доказательства по самому изменяемому алгоритму.

M4. Release-артефакты не называют docs/USER-GUIDE.ru.md.

§6 «Release» перечисляет только CHANGELOG. Новый канал отказа — junction.limit_check_failed, тост при поломке САМОЙ проверки — это новое наблюдаемое пользователем состояние (запись отклонена без названия конкретного правила П1–П5). Раздел «Ограничения стыков стен» в docs/USER-GUIDE.ru.md:420-444 уже документирует ровно этот класс информации (пороги, где виден отказ, чем отличаются каналы рисования/ Resize/«Толщины») — тем самым методом, каким его заводил #329 (docs/ specs/329-junction-limits.md §6: «раздел об ограничениях рисования»). ТЗ формально можно закрыть без этой правки (гейт check-docs.mjs её не поймает — там нет src/**-диффа для этой строки), но тогда справочник опишет отказы неполно. Фиксируется одной строкой в §6 ТЗ; не блокирует — можно решить и отклонить с запиской, если авторы считают ошибку проверки внутренним деталем, а не пользовательским контрактом.

Low

L1. §1 не отвечает на два обязательных продуктовых вопроса ТЗ в открытой форме — какая персона, на какой поверхности, и что человек видит одной фразой без терминов реализации (PROCESS.md §7.1, AGENTS.md).

Раздел «Сценарий и пользовательский результат» и особенно строка «Результат: ...вердикты честные и одинаковые в обоих зеркалах; переполнений стека нет; отказ проверки — это отказ записи, не пропуск» написаны в терминах реализации («зеркала», «ключи узлов», «отказ проверки» вместо «домашний админ теряет правку плана» или подобного). Персона (Home admin, docs/SCOPE.md) и поверхность (редактор плана, десктоп) не названы явно, хотя подразумеваются списком каналов (рисование/Resize/«Толщина»). Для сравнения — принятый ТЗ-предшественник docs/specs/329-junction-limits.md §1 формулирует результат как «(а) нарисовать такое больше нельзя... (б) уже существующие такие планы рендерятся прилично» — на том же уровне детализации технической подоплёки, но с явным «что человек увидит». Не блокирует (стиль документа уже был принят один раз для #329 в этом же скоупе задач), но следующая редакция должна дать одно предложение такого рода.

Что проверено и признано корректным

• Скоуп/не-скоуп: сестринские issue #333/#339 явно исключены, границы §3 чёткие, пороги П1–П5 намеренно не меняются — соответствует docs/SCOPE.md (J6, «Keep the plan true as the home evolves»).
• §2.2 (снятие фильтра degrees > EPS): прослежена текущая реализация checkNodes (src/junction-limits.ts:76-95) — снятие фильтра не создаёт ложных срабатываний на легитимной прямой стене через узел (ровно 2 луча на 180° друг от друга всегда дают на круге две дуги ~180°, а не близкую к нулю, независимо от точности координат) и на T-стыке (3+ луча, но вырожденная пара образуется только у геометрически совпадающих лучей). AC2 однозначен и проверяем.
• §2.4 (коллинеарность дуги к базе): числа AC4 (30×0.9°, 20 см, 0.5° излом) внутренне согласованы с описанным механизмом (накопление к базе вместо предыдущего атома).
• §2.5 (fail-closed кандидата): согласован с прецедентом #278, канал тоста и ключ i18n названы, AC5 проверяем смоком/юнитом.
• Один AC на нормативный пункт §2 (1:1, AC1↔§2.1 ... AC6↔§2.6) плюс AC7 на паритет/регресс — структура полная, план тестов называет способ доказательства для каждого пункта (юнит/смок/бэкенд-юнит/мутант).
• i18n: один новый ключ, en+ru — соответствует формату остальных junction.limit_* в src/i18n/en.json/ru.json.
• Touch: не задет, обоснованно (валидация записи, не жест).
• Обязательство обновить сам файл #329 (§2, абзац про квантование и 0°) учтено — не заводит параллельный источник истины.

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

• Производительность фактическая (нет кода — только оценка риска в M3 по описанию алгоритма).
• Полнота списка golden-сцен/скриншотов — не требуется на этой стадии, задача не меняет рендер (только вердикты записи и один новый текст тоста).
• Backend-паритет численно (нет кода для запуска test_parity_with_the_frontend_checks).
• docs/CONFIG-COMPATIBILITY.md — не тронут задачей и не должен быть, новых полей конфига нет; проверено чтением §3 (наследование данных не переопределяется).

Вердикт

High (H1) блокирует переход в «Готово к разработке». Medium (M1–M4) — в скоупе задачи, чинятся той же правкой ТЗ без отдельного issue. Low (L1) — на усмотрение автора, можно снять запиской при повторном заходе.

Вердикт: красный · заход r1 · блокирующих циклов 1/4 · High: 1 · Medium: 4 → в задаче · Документ: docs/reviews/SPEC-REVIEW-331-r1.md