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

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

Статус: ревизия 3 (r1: M1/M2/L1; r2: M1 — AC7 доказывает каналы §2). Решения владельца (чат, 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 см.
- **П4. Минимальная дистанция:** несмежные узлы — не ближе **5 см**; узел —
  не ближе 5 см к стене, которой он не принадлежит (касание конца о середину
  чужой стены остаётся T-стыком и валидно — правило про «почти-касание» без
  инцидентности). Порог абсолютный, в сантиметрах, и НЕ зависит от
  `cell_cm` пространства.
- **П5. Просвет комнаты:** после вычета тел стен внутренняя область комнаты
  непуста и её площадь ≥ **25 см²**. Порог абсолютный и не зависит от
  `cell_cm`.

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

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

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

Для пары стен вершины, чьи внутренние грани смыкаются на расстоянии `d` от
вершины, меньшем длины обеих стен (эквивалентно: угол мал настолько, что
существует зона полного перекрытия тел):

- остриё обрезается **одной плоской фаской**, перпендикулярной биссектрисе,
  проходящей через точку смыкания внутренних граней;
- выше фаски тел нет вовсе (никаких пиков), ниже — обычная кладка; V-вырезы
  запрещены; штриховка непрерывна;
- правило дополняет #309/#310 и включается только в вырожденной зоне
  (`d` внутри длины стен); обычные острые пары (#310, остриё вне зоны
  перекрытия) не меняются.

## 5. Бэкенд

Семантическая дельта-валидация по образцу существующих (например, jamb
margin): правила П1–П5 применяются к элементам, которых касается дельта
записи (новые/изменённые сегменты, узлы, комнаты); унаследованные нарушения
нетронутых элементов проходят. Ошибки — стабильные коды
`junction_limit_<rule>` в общем формате `vol.Invalid`/семантических ошибок.
Питоновское зеркало обязано давать решения, идентичные фронту.

## 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/validation.py` — дельта-правила §5;
  `tests_backend` — кейсы принятия унаследованного и отказа нового.
- Тесты фронта: юниты на каждую формулу П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 см — отказ (длина < толщины).
- **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 рендерится без «трезубца»: одна фаска,
  ноль V-вырезов; golden-сцена + пиксельная проверка смоком (нет разрывов
  тела выше фаски).
- **AC7a (Resize, канал §2).** Resize, приводящий к нарушению любого из
  П1–П5, упирается в последнюю допустимую позицию; при отсутствии
  безопасного шага ручка приглушена, и её объяснение (hover/focus/нажатие)
  называет нарушенное правило. План байт-неизменен; тост не показывается.
  Смок проверяет и байт-неизменность, и текст объяснения ручки.
- **AC7b («Толщина», канал §2).** Значение толщины, нарушающее П3/П5, не
  применяется; показывается тост с названием правила (образец отказа нуля
  #313). План байт-неизменен. Смок проверяет текст тоста.
- **AC8.** Миграция/импорт/restore фикстуры с нарушениями проходят.
- **AC9 (§5).** Бэкенд: эхо-запись унаследованного нарушения проходит;
  запись, добавляющая новое нарушение, отклоняется стабильным кодом.
- **AC10.** Идемпотентность: повторный commit валидного конфига байт-иден-
  тичен; Optimize на легаси-фикстуре не создаёт новых нарушений (AC-пост-
  условие §3).

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

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

## 10. Риски

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

## 11. Откат

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