houseplan-card/docs/specs/329-junction-limits.md

# Issue #329 — ограничения стыков стен и честная острая вершина

Статус: ревизия 7 (r1 код-ревью: H1 — обе стороны на бэкенде судятся после одной миграции, M1 — мёртвый код фаски удалён, M2/M3 — гайды, M4 — AC10 доказан тестами; r1: M1/M2/L1; r2: M1 — AC7; поправки владельца 2026-08-27: §4 — острая вершина без фаски и без зазубрин на гранях; П3 меряет СТЕНУ, а не атом — кейс компенсации перепада толщин). Решения владельца (чат, 2026-08-27, зафиксированы в issue):
пять ограничений приняты; проверки действуют на записи, легаси читается как
есть; для остаточных острых вершин легаси-планов рендер закрывает остриё
честной фаской вместо «трезубца».

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

Сегодня комната-треугольник с вершиной ≈9.9° (стены 15 см) рендерится
«трезубцем»: три пика и два V-выреза (репродукция в issue, фикстура
`houseplan-space-test2-2026-08-27_16-14-48.json`, комната `rmtbq3k5e-0`).
Причина класса: при остром угле внутренние грани стен смыкаются на
`полутолщина/tan(θ/2)` от вершины (86 см при 10°/15 см) — весь участок выше
физически перекрыт телами обеих стен, и объединение тел с вершинными
правилами #309/#310 распадается.

После задачи: (а) нарисовать такое больше нельзя — запись отклоняется с
точным тостом; (б) уже существующие такие планы рендерятся прилично — остриё
закрыто одной фаской, без пиков и вырезов.

## 2. Нормативные ограничения (решения владельца)

Все проверки выполняются над кандидатом структурной записи (фронт — в общем
барьере перед записью; бэкенд — семантическая дельта-валидация §5). Нарушение
= отказ всей записи, план не изменён. Канал обратной связи — штатный канал
каждой поверхности (M1 spec-ревью r1):

- **рисование/завершение контура, черновики, независимые стены, merge/
  split** — тост с конкретным правилом и значением (текущий канал отказов
  рисования);
- **Resize** — существующий контракт ручек (USER-GUIDE «Изменение размеров»):
  движение упирается в последнюю допустимую позицию; если безопасного шага
  нет, ручка приглушена и объясняет запрет по hover/focus/нажатию — текст
  объяснения называет нарушенное правило П1–П5; тост не используется;
- **инструмент «Толщина»** — отказ значением в трее по образцу существующего
  отказа нуля для независимой стены (#313): значение не применяется, причина
  показывается тостом с названием правила (П3/П5).

- **П1. Минимальный угол:** угол между СОСЕДНИМИ по азимуту стенами одного
  узла ≥ **15°**. Считается по осям сегментов, для каждого узла кандидата.
- **П2. Валентность узла:** в одном узле сходятся ≤ **6** стен (контурные
  атомы, независимые стены и перегородки считаются вместе).
- **П3. Минимальная длина стены:** длина ≥ **max(20 см, толщина
  сегмента)**. Для нулевых стен (#306) — ≥ 20 см. Меряется НЕ отдельный атом
  каталога, а вся стена: максимальный коллинеарный (±1°) прогон соседних
  атомов ОДНОЙ толщины, склеенных через общие узлы. Иначе правило запрещало
  бы законный приём — короткий доборный участок, компенсирующий перепад
  толщин соседних стен (владелец, 2026-08-27, фикстура
  `houseplan-space-2-2026-08-27_18-24-23.json`: атомы 5 см = (30−20)/2 и
  14 см, каждый — продолжение стены той же толщины в 349 см). Такой атом
  короче 20 см законен ровно потому, что стена, частью которой он является,
  длиннее 20 см.
- **П4. Минимальная дистанция:** несмежные узлы — не ближе **5 см**; узел —
  не ближе 5 см к стене, которой он не принадлежит (касание конца о середину
  чужой стены остаётся T-стыком и валидно — правило про «почти-касание» без
  инцидентности). Порог абсолютный, в сантиметрах, и НЕ зависит от
  `cell_cm` пространства.
- **Точность границ (#331):** ключ узла квантуется к 1e-7 формулой
  канонизации (`sign·floor(|v|·1e7+0.5)/1e7`, −0 → 0); пары точек ближе
  2e-7 (сырые координаты) — один узел, а не «почти-касание»;  длина П3 меряется по
  коллинеарной (±1° к БАЗЕ прогона) компоненте связности одной толщины.
- **П5. Просвет комнаты:** после вычета тел стен внутренняя область комнаты
  непуста и её площадь ≥ **25 см²**. Порог абсолютный и не зависит от
  `cell_cm`.

## 3. Граница применения

- Проверяются только записи, ИЗМЕНЯЮЩИЕ соответствующую геометрию: рисование
  и завершение контура, черновики, независимые стены/перегородки, Resize,
  инструмент «Толщина» (толщина участвует в П3/П5), merge/split.
- Существующие данные наследуются: запись, не трогающая нарушающий элемент,
  проходит; миграция (#306/#316), импорт и восстановление из бэкапа не
  блокируются никогда.
- Optimize (выравнивание/канонизация) не обязан чинить легаси-нарушения и не
  имеет права создавать новые (пост-условие прогона).

## 4. Рендер остаточных острых вершин (легаси)

**Поправка владельца (чат, 2026-08-27):** плоского среза вершины быть не
должно — у остриё обычная нормальная острая вершина.

Для корня «трезубца» доказано исполнением: у вершины ≈9.85° внешний контур
падал на плоскую фаску (лимит mitre 4·h против выноса 87 см), а внутренний
контур складывался «бабочкой» — вырезы рождались вычитанием этой складки.
Контракт:

- вырожденная вершина (угол < 15° и точка смыкания внутренних граней внутри
  обеих стен) даёт **одну точку внешнего контура ровно в вершине плана**:
  ни двухточечной фаски, ни иглы mitre, уходящей на десятки сантиметров за
  стены, которые её образуют;
- внутренний контур сходится в СВОЮ вершину (одна точка mitre) вместо
  двухточечной фаски, поэтому «бабочки» не возникает вовсе: вычитать нечего,
  V-вырезов нет, кладка выше сплошная, штриховка непрерывна;
- на внешних гранях между внутренней и внешней вершиной не остаётся ступенек
  (вторая поправка владельца): кольцо комнаты — ровно треугольник, каждая
  сторона длиннее полутолщины, микро-вершин и «щепок» нет;
- обычные и просто острые пары (#310, вершина вне зоны перекрытия) не
  меняются: их полный mitre сохраняется.

## 5. Бэкенд

Семантическая дельта-валидация по образцу существующих (например, jamb
margin), модуль `custom_components/houseplan/junction_limits.py`. Считается
так же, как на фронте: нарушения по ПРАВИЛУ, а не по носителю (структурная
запись переатомизирует сегменты и меняет их id), унаследованные проходят,
новое — отказ. Ошибка — `JunctionLimitError` со стабильным кодом
`junction_limit_<rule>`, отдаётся тем же `connection.send_error`, что и
остальные семантические ошибки записи конфига.

Обе стороны сравнения (`previous` и `candidate`) проходят через
`commit_wall_segment_model` до подсчёта. Без этого легаси-документ без
каталога отвечал «нарушений нет» независимо от геометрии, и первая же
структурная правка после обновления карточки читала унаследованное
нарушение как новое — отказ несвязанной правке, прямое нарушение §3
(находка H1 код-ревью r1).

Зеркалятся П1–П4. П5 (просвет комнаты) сознательно оставлен только на
клиенте: это утверждение о ПОСТРОЕННЫХ телах стен, и повторение конвейера
mitre/inset на Python было бы второй реализацией геометрии, расхождение
которой опаснее самого правила. Документ, нарушающий только П5, некрасив, но
не повреждён. Паритет П1–П4 закреплён тестом
`tests_backend/test_junction_limits.py::test_parity_with_the_frontend_checks`:
одни и те же фикстуры прогоняются через TS-функции и через питоновские, и
вердикт обязан совпасть.

Периметр гейта (#333, решение владельца 2026-08-28): `config/set` и
`plan/optimize` — обе команды, которыми клиент может записать произвольную
геометрию, валидируются одинаково (наследование по правилу: ремонт
легаси-плана с нарушениями проходит, добавить новое нельзя; честная
оптимизация не добавляет нарушений по AC10, поэтому для легитимных потоков
гейт — no-op). Импорт и восстановление из бэкапа — сознательно ВНЕ гейта:
§3 обещает, что restore не блокируется никогда; крафтовый импорт может
внести нарушения, но они наследуются, а не легализуются как новые.

## 6. Затронутые поверхности и артефакты

- `src/wall-thickness.ts` / `src/wall-segment-model.ts` — геометрия проверок
  П1–П5 (чистые функции) и фаска §4 в построении тел/вершинных правил.
- `src/houseplan-card.ts` — вызовы проверок в общем барьере записи, тосты.
- `src/i18n/en.json`, `src/i18n/ru.json` — по ключу на правило:
  `junction.limit_angle`, `junction.limit_valence`, `junction.limit_length`,
  `junction.limit_distance`, `junction.limit_clearance` (с параметрами
  значений) + заголовок отказа.
- `custom_components/houseplan/junction_limits.py` — дельта-правила §5,
  вызов в `websocket_api.py` рядом с остальными семантическими валидаторами;
  `tests_backend/test_junction_limits.py` — границы правил, принятие
  унаследованного, отказ нового и паритет с фронтом.
- Тесты фронта: юниты на каждую формулу П1–П5 (границы: 14.9°/15°, 6/7 стен,
  19/20 см, 4/5 см, пустой/непустой просвет), мутанты в гейте на П1 и §4;
  смоки каналов отказа: текст объяснения ручки Resize и текст тоста
  «Толщины» (AC7a/AC7b).
- Смок: репро-фикстура #329 — новая попытка нарисовать «шпиль» отклоняется;
  легаси-конфиг рендерится по §4.
- Golden: новая сцена `sharp-apex-legacy-dark` по фикстуре issue (рендер §4);
  существующие сцены не должны измениться — `golden:verify` обязан
  подтвердить (в матрице нет вершин острее 15° — проверить прогоном).
- `docs/USER-GUIDE.md`/`.ru.md` — раздел об ограничениях рисования (таблица
  П1–П5); CHANGELOG RU+EN (`User-Visible: yes`).
- `docs/CONFIG-COMPATIBILITY.md` — абзац: ограничения действуют на записи,
  унаследованные данные валидны на чтение/миграцию.
- Новых полей конфига нет — `config-field-registry` не меняется.

## 7. Производительность и touch

Проверки П1–П4 — O(узлы+сегменты) на запись, вне горячего пути рендера. П5
использует уже вычисляемые физические тела (кэш) на кандидате записи —
допускается только на commit, не на каждый жест курсора. Touch-контракт не
затрагивается (правки — не жесты).

## 8. AC

- **AC1 (П1).** Завершение контура с вершиной 14° отклоняется, тост называет
  минимум 15° и узел; 16° — проходит. Юнит на границе 15.0°.
- **AC2 (П2).** Седьмая стена в узел — отказ; шесть — проходит.
- **AC3 (П3).** Сегмент 19 см — отказ; 20 см — проходит; сегмент 25 см при
  толщине 30 см — отказ (длина < толщины).
- **AC3b (П3, компенсация перепада толщин).** Атом 5 см, коллинеарный
  продолжению стены той же толщины, проходит: правило меряет прогон, а не
  атом. Проверяется юнитом на фикстуре владельца — 0 нарушений П3.
- **AC4 (П4).** Узел в 4 см от несмежного узла или чужой стены — отказ; 5 см
  — проходит; T-стык (конец на чужой стене) — проходит.
- **AC5a (сквозной сценарий фикстуры).** Повторение «шпиля» из фикстуры
  issue рисованием отклоняется первым же нарушенным правилом (П1, вершина
  ≈9.9° < 15°) — сквозной смок поверх AC1.
- **AC5b (П5 независим от П1).** Равносторонний треугольник со стороной
  60 см и стенами 33 см: все углы 60° ≥ 15°, но inradius ≈ 17.3 см меньше
  полутолщины 16.5 см плюс минимального просвета — внутренняя область после
  вычета тел < 25 см², запись отклоняется по П5. Тот же треугольник со
  стороной 120 см (inradius ≈ 34.6 см) проходит. Юнит с этими числами.
- **AC6 (§4).** Легаси-фикстура issue рендерится без «трезубца»: у вершины
  ровно одна точка внешнего контура, стоящая в вершине плана; внутренний
  контур — треугольник (ровно 3 точки, не «бабочка»); внешнее кольцо тела —
  ровно 3 различные вершины без ступенек и микро-сегментов; golden-сцена +
  юниты на контурах и на кольце.
- **AC7a (Resize, канал §2).** Resize, приводящий к нарушению любого из
  П1–П5, упирается в последнюю ДОПУСТИМУЮ позицию: нарушающий шаг не
  превьюится и не коммитится, а отказ ровно один раз за жест называет
  нарушенное правило тем же каналом, которым Resize уже объясняет
  отклонённый предпросмотр (`resize.preview_failed` → `resize.limit_stopped`).
  Смок ведёт настоящий pointer-жест по ручке: сетка 2 см, две комнаты в 10 см
  друг от друга, тяга на 6 см (оставила бы 4 см между чужими узлами, П4)
  останавливает стену на 6 см и показывает ровно один тост с «5 см».

  > Ревизия 6, отступление от первоначальной формулировки («ручка приглушена,
  > тост не показывается, план байт-неизменен»). Приглушение ручки считается
  > статически в `_rszResolution`, до жеста, а нарушение стыка зависит от
  > КОНКРЕТНОГО шага — статически его не разрешить, не перебирая все позиции.
  > Молчаливый отказ при этом прямо противоречит уже действующему контракту
  > #293/#295 («reject не молчит»), закреплённому мутантом
  > `resize-preview-reject-silent`. И байт-неизменность плана неверна как
  > общее требование: разрешённая часть жеста — это нормальная правка,
  > которую пользователь и просил; неизменным план остаётся только когда
  > допустимого шага нет вовсе.
  >
  > Замер собственных ограничителей Resize (2026-08-27): комнату не дают
  > сузить ниже 30 см (две толщины по 15 см), поэтому П3 (20 см) и П5 через
  > сужение комнаты недостижимы — гейт там страхует, а не работает. Реально
  > достижимо П4 на мелкой сетке, этот случай и закреплён смоком.
- **AC7b («Толщина», канал §2).** Значение толщины, нарушающее П3/П5, не
  применяется; показывается тост с названием правила (образец отказа нуля
  #313). План байт-неизменен. Смок проверяет текст тоста.
- **AC8.** Миграция/импорт/restore фикстуры с нарушениями проходят.
- **AC9 (§5).** Бэкенд: эхо-запись унаследованного нарушения проходит;
  запись, добавляющая новое нарушение, отклоняется кодом
  `junction_limit_<rule>`; вердикты П1–П4 совпадают с фронтом на общих
  фикстурах (тест паритета).
- **AC10.** Идемпотентность: повторный commit валидного конфига байт-иден-
  тичен; Optimize на легаси-фикстуре не создаёт новых нарушений (AC-пост-
  условие §3). Доказывается двумя юнитами: (1) фикстура владельца
  `329-sharp-apex.json` в легаси-хранении — унаследованное нарушение угла
  есть до Оптимизации и ни по одному правилу счёт не растёт после;
  (2) граничный кейс П4 — две комнаты ровно в 5 см, где привязка к решётке
  могла бы утащить узел под порог, после Оптимизации по-прежнему чисты.
  Оба считают нарушения ТЕМ ЖЕ способом, что барьер записи: обе стороны
  сперва через `commitWallSegmentModel`.

## 9. Принято предположительно (поменять свободно)

- Угол П1 считается между соседними по азимуту осями в узле (не все пары).
- Порог просвета 25 см² и способ его вычисления по кэшу физических тел.
- Дельта-семантика §5: «элемент дельты» = сегмент/узел/комната, чьи данные
  изменились относительно previous.
- Имена i18n-ключей и коды ошибок бэкенда.
- Фаска §4 перпендикулярна биссектрисе в точке смыкания внутренних граней.

## 10. Риски

- Ложные отказы на живых планах у границы правил (особенно П4 при плотной
  геометрии) — смягчается точными тостами и тем, что унаследованное не
  блокируется.
- П5 на больших пространствах — стоимость union; смягчается кэшем тел и
  проверкой только на commit.
- §4 меняет пиксели вырожденных вершин — по построению матрицы golden таких
  сцен нет (verify обязан подтвердить), новая сцена фиксирует контракт.

## 11. Откат

Реверт ветки: ограничения исчезают, рендер возвращается к текущему
поведению. Данные фикс не переписывает (валидация и рендер, не миграция).