houseplan-card/docs/specs/296-optimize-hidden-obstacles.md

# Issue #296 — Optimize удаляет доказанно избыточные скрытые стены

- **Issue:** https://github.com/Matysh/houseplan-card/issues/296
- **Редакция:** первая редакция для независимого ревью; статус определяется только метками issue
- **Тип / приоритет:** bug / P1
- **Трек:** обычный
- **Оценка:** пользовательская ценность 9/10; ценность для разработки 8/10;
  сложность и риск 7/10
- **Область:** Optimize, составные совпадения `partitions`, полностью избыточные
  `room_drafts`, backend-доказательство изменения host, диагностический слой редактора
- **Связано:** #137, #173, #276, #277, #280, #281, #282, #292, #294,
  `docs/CANVAS.md`, `docs/RESIZE.md`, `docs/WALL-THICKNESS.md`

## 1. Сценарий и продуктовый контекст

**Персона:** администратор дома, поддерживающий точную планировку в редакторе Плана.

**Поверхность:** редактор Плана и явная команда «Оптимизировать планы» в настройках.

**Момент:** после нескольких циклов рисования, импорта и редактирования одна
независимая стена или сохранённая цепочка геометрически оказывается точно под
стенами комнат. В View лишний объект не различим, но Resize считает его отдельным
физическим препятствием и блокирует безопасную ручку.

Задача поддерживает **J6**: существующий план можно диагностировать, исправить и
дальше редактировать без ручного исправления JSON.

## 2. Что человек увидит до и после

**До:** Optimize сообщает, что изменений нет, хотя невидимые `partition` и
`room_draft` продолжают блокировать Resize. В редакторе их оси и узлы скрыты телом
другой стены, поэтому причину нельзя найти визуально.

**После:** в редакторе оси и исходные узлы перекрытых независимых стен видны выше
всех тел стен. Optimize по частям преобразует только доказанно совпадающие участки
`partition` в канонические стены комнат, удаляет только целиком доказанно
избыточные drafts, сохраняет все остальные участки и проёмы. После применения и
reload безопасные Resize-ручки становятся активными.

## 3. Подтверждённая причина

На приложенном экспорте `houseplan-full-2026-08-24_17-36-50.json` текущий `dev`
возвращает `changed:false`, `partitionsReconciled:0`, `removedDrafts:0` и оставляет:

- `partition-mt2on9ou-0` — вертикаль `x=-401`, `y=304…928`, `30 cm`;
- `partition-room-mt7ijuyq-0` — вертикаль `x=-85`, `y=549…928`, `20 cm`;
- `draft-mt7igts5` — двухточечную горизонталь `y=928`, `x=-85…254`, `30 cm`.

`scripts/model-invariants.mjs` независимо классифицирует их как две
`partition_over_room_wall` и один `unusable_draft`.

Причины в коде:

1. `reconcileCoincidentPartitions()` принимает лишь полное `sameSegment()` одной
   partition и одного `WallInterval`; составная линия из нескольких соседних
   интервалов никогда не получает owners.
2. `alignAllToGrid()` удаляет только drafts короче двух точек. Незамкнутая цепочка
   из двух точек законна по #173/#294, поэтому point-count нельзя сделать новым
   разрушительным критерием.
3. `_safe_optimize_partition_rehost()` на backend доказывает покрытие удалённого
   host только одним room edge и не принимает эквивалентное составное покрытие.
4. Snap-геометрия #137 дедуплицирует совпадающую ось в пользу комнаты и существует
   только в инструменте рисования; это не является постоянной диагностикой
   скрытого самостоятельного объекта.

## 4. Scope

В issue входят:

1. Piecewise reconciliation одной `partition`, совпадающей с несколькими
   последовательными solid-интервалами стен комнат.
2. Сохранение непримирённых остатков partition и безопасная перепривязка hosted
   openings после её разрезания.
3. Удаление `room_draft` целиком только при доказанной полной избыточности каждого
   его сегмента.
4. Симметричное fail-closed доказательство допустимого Optimize-delta на backend.
5. Диагностические оси и исходные узлы перекрытых `partition`/сохранённых drafts
   выше всех тел стен во всём редакторе Плана.
6. Точные пользовательские счётчики preview/result и один Undoable Optimize.
7. Реальные обезличенные fixtures второго и первого этажей, unit, backend,
   production-bundle smoke, invariant/Resize audit, golden и performance-покрытие.
8. RU/EN документация и changelog.

## 5. Non-scope

В issue не входят:

- автоматический Optimize при загрузке, рисовании или Resize;
- удаление draft только из-за незамкнутости или числа точек;
- частичное разрезание `room_draft`;
- исправление произвольных пересечений, зазоров, почти совпадающих или
  неколлинеарных стен;
- удаление законных колонн и не влияющей на Resize перегородки первого этажа;
- новые кнопки, настройки, предупреждения или режим очистки;
- изменение правил доступности Resize, кроме результата удаления реального
  дублирующего препятствия;
- изменение snap-приоритетов и hit-testing #137;
- показ диагностического слоя в View, kiosk, editor Устройств/Декора/Подложки или
  скрытом изометрическом режиме;
- миграция схемы или изменение `model_version` только ради этой задачи.

## 6. Piecewise reconciliation partitions

### 6.1 Источник доказательства

Алгоритм остаётся чистой частью явного Optimize и не мутирует вход. Для каждой
исходной partition в стабильном порядке `id` он строит одномерную координату вдоль
её оси и собирает breakpoints из:

- начала и конца partition;
- концов всех коллинеарных solid `WallInterval`, имеющих положительное пересечение
  с partition;
- границ hosted openings на этой partition.

Соседние одинаковые координаты дедуплицируются с действующим геометрическим
epsilon. Нулевые куски отбрасываются. Направление входной partition не влияет на
результат и стабильность идентификаторов.

Для каждого положительного атомарного участка независимо доказывается контракт
#276:

- участок целиком совпадает с solid-стеной, а не `open`, `open-span` или вырезом;
- owner-kind однозначен: ровно одна комната для `outer` либо ровно две разные
  комнаты для `shared`;
- все owners описывают тот же атомарный участок и одну эффективную толщину;
- нет перекрытия другой независимой partition, draft или wall column;
- неизвестные поля исходной partition отсутствуют;
- преобразование не создаёт пересекающихся проёмов и проходит общий geometry
  preflight.

Неполное покрытие всего исходного сегмента не отменяет доказанные атомарные
участки. Небезопасный участок остаётся независимой стеной.

### 6.2 Толщина и каноническая стена

Для каждого согласованного участка итоговая физическая толщина равна
`max(roomWallCm, partition.cm)`. Толщина никогда не уменьшается. Она записывается
через действующий интервальный контракт `walls`, после чего обычная канонизация
может объединить соседние равные участки.

Для `partition-mt2on9ou-0` профиль `30/20/30 cm` становится `30/30/30 cm`. Для
участков второй partition действует то же правило `max`, без расширения вне её
фактического span.

### 6.3 Остатки и идентификаторы

Все непримирённые соседние атомарные участки с одинаковой толщиной и совместимым
набором hosted openings объединяются обратно в максимальные остатки. Если остаток
один, он сохраняет исходный `id`. Если остатков несколько:

- первый в каноническом порядке сохраняет исходный `id`;
- остальные получают детерминированные collision-safe производные id;
- повторный Optimize/reload не создаёт новые id и не меняет порядок;
- лимит `MAX_PARTITIONS=2000` проверяется до принятия преобразования.

Если безопасно разместить все остатки и их openings в пределах лимита нельзя,
исходная partition сохраняется целиком и не попадает в счётчик.

### 6.4 Hosted openings

Каждый hosted opening сначала разрешается относительно исходной целой partition в
абсолютные `center`, `angle`, `length`.

- Opening, целиком лежащий на доказанно согласованном участке, материализуется как
  обычный room-wall opening по #276; все пользовательские поля сохраняются.
- Opening на остатке получает корректный residual host и новый `t`; абсолютная
  геометрия и остальные поля остаются прежними.
- Opening, пересекающий breakpoint или границу согласованного участка, делает
  затронутый непрерывный диапазон остатком. Его нельзя делить, обрезать или терять;
  доказанные несвязанные куски той же partition можно согласовать.
- Неразрешимый host, неоднозначная room association, наложение openings или
  нарушение jamb-margin оставляет затронутый исходный кандидат без изменений.

`openingsRehosted` считает только openings, с которых действительно снят partition
host; перепривязка между residual partitions в этот счётчик не входит.

### 6.5 Счётчик

`partitionsReconciled` считает успешно преобразованные максимальные непрерывные
участки, а не число исходных записей. Один исходный объект может дать несколько
единиц. RU/EN текст результата должен говорить об «участках независимых стен», а
не обещать число удалённых записей.

## 7. Полностью избыточные room drafts

Незамкнутость и число точек сами по себе не являются основанием удаления.

Сохранённый draft удаляется только целиком, когда для **каждого** положительного
сегмента доказано:

- конечные координаты и ненулевая длина;
- полное коллинеарное покрытие одним или несколькими соседними solid-интервалами
  стен комнат;
- отсутствие open/open-span/проёма на покрываемой части;
- отсутствие уникального выступа, зазора или неоднозначности.

Если любой сегмент не проходит проверку, весь draft, его `points`, `segments`, id,
порядок и неизвестные разрешённые поля сохраняются без изменений. Draft не
нарезается. `draft-mt7igts5` проходит доказательство и удаляется; обычная
двухточечная свободная цепочка #173/#294 остаётся.

`removedDrafts` увеличивается на число удалённых исходных drafts. Удаление входит
в preview, одну транзакцию Apply и общий Undo.

## 8. Backend security contract

Backend не доверяет frontend-счётчикам и независимо доказывает delta относительно
предыдущей конфигурации при `allow_optimize_rehost=true`.

Расширенное доказательство обязано:

1. восстановить ось и атомарное покрытие старой partition стенами комнат в новой
   конфигурации;
2. доказать, что удалённые диапазоны полностью покрыты solid room walls не уже
   старой partition;
3. доказать эквивалентность всех сохранённых остаточных диапазонов, их толщин,
   ids/host bindings и абсолютной геометрии openings;
4. разрешать снятие host только для opening, целиком покрытого доказанным room-wall
   диапазоном, с неизменными пользовательскими полями и без overlap;
5. отклонять crafted candidate при зазоре, open span, лишнем/потерянном остатке,
   уменьшении толщины, изменённом opening, неоднозначном owner или неизвестном
   поле.

Обычные записи вне endpoint Optimize остаются под прежним строгим контрактом.
Ошибка backend не оставляет частично применённый frontend-state.

## 9. Диагностическая видимость скрытых стен

### 9.1 Что считается скрытым объектом

Диагностический кандидат — сегмент независимой `partition` или сохранённого
`room_draft`, имеющий положительное точное коллинеарное совпадение с телом другой
стены. Почти параллельные, пересекающиеся только в точке и просто близкие стены не
подсвечиваются.

Для каждого кандидата отображаются:

- полная ось исходного независимого сегмента;
- его реальные исходные endpoints, включая endpoint внутри более длинной стены;
- отдельные исходные endpoints совпадающих самостоятельных объектов, даже когда
  snap-resolver дедуплицирует их координату.

### 9.2 Когда и где виден слой

Слой существует во всём редакторе Плана при любом активном инструменте, чтобы
препятствие было видно до выбора Resize и во время диагностики. Он отсутствует в
View, kiosk и остальных редакторах.

Он рисуется после тел **всех** реальных и виртуальных стен и до проёмов,
selection/editor chrome и transient previews. Поэтому кладка не может закрыть ось
или узел. Слой имеет `pointer-events:none`, `aria-hidden=true`, не получает focus и
не меняет существующий выбор/редактирование объекта.

В режиме рисования действующий snap-overlay #137 продолжает показывать всю
архитектуру и выбирать каноническую комнату для совпадающей оси. Диагностическая
проекция строится отдельно и не меняет `buildPlanSnapGeometry()`, приоритеты,
line-snap, endpoint-snap или ambiguity resolution.

### 9.3 Визуальный контракт

Ось — 1 CSS px с `non-scaling-stroke`. Исходный узел сохраняет физический радиус
5 cm из #137. Диагностические линии и узлы используют существующие контрастные
tokens светлой/тёмной/forced-colours тем без анимации. Совпадение с обычным
snap-overlay не должно визуально удваивать stroke/opacity.

После успешного Optimize слой исчезает только потому, что доказанно избыточный
самостоятельный объект удалён/согласован из модели. Preview Optimize не скрывает
объект до Apply.

## 10. Atomicity, Undo и идемпотентность

- Preview не мутирует config/layout и показывает точные счётчики.
- Apply записывает config/layout одной существующей Optimizer-транзакцией.
- Любая ошибка schema, geometry preflight или backend отменяет весь Apply.
- Один Undo возвращает partitions, drafts, hosts, openings и прежние толщины.
- После успешной записи и reload второй Optimize возвращает `changed:false` и
  нулевые новые счётчики.
- Optimize не создаёт изменений только ради `model_version` или диагностического
  слоя.

## 11. Данные, i18n и accessibility

Новых schema fields, storage keys и миграции нет. Разрезание partition использует
действующие `partitions`, `walls` и opening `host`; диагностическая проекция
полностью производная и не сохраняется.

Новых кнопок и сообщений нет. Изменившаяся строка счётчика участков обновляется в
обоих встроенных словарях RU/EN, без смешения языков. Маркеры декоративны,
`aria-hidden`, не меняют keyboard/focus order и не заменяют существующие controls.

## 12. Принятые предположения

1. Действующий геометрический epsilon, wall-key pitch и единицы конфигурации
   остаются авторитетными; новый пользовательский tolerance не вводится.
2. Unknown fields на partition делают исходную запись неделимой и сохраняемой
   целиком. Для draft действует all-or-nothing сохранение записи.
3. Первый residual span сохраняет исходный id в каноническом направлении, чтобы
   минимизировать churn ссылок; это техническая деталь без нового schema field.
4. Диагностический слой показывает только действительно перекрытые независимые
   сегменты, а не все стены во всех инструментах; полный общий overlay остаётся
   draw-only по #137.
5. Счётчик `partitionsReconciled` относится к максимальным согласованным участкам
   после атомарного доказательства.

## 13. Acceptance criteria

### AC1. Реальный второй этаж очищается

На обезличенном fixture второго этажа после Optimize:

- отсутствуют `partition-mt2on9ou-0`, `partition-room-mt7ijuyq-0` и
  `draft-mt7igts5`;
- `partitionsReconciled >= 2`, `removedDrafts == 1`;
- профиль первой линии равен `30/30/30 cm`, а физическая толщина нигде не меньше
  исходной room/partition;
- invariant и Resize audit не находят `duplicate-physical-wall`; целевые ручки
  Master bath/Garderobe и Bedroom/Office доступны;
- openings, комнаты, layout и несвязанные объекты эквивалентны входу.

**Evidence:** real-fixture optimizer unit + `scripts/model-invariants.mjs` +
resize-availability audit.

### AC2. Partial match сохраняет остаток

Partition с одним совпадающим и одним свободным диапазоном преобразует только
совпадающую часть. Остаток сохраняет толщину, geometry и стабильный id; повторный
Optimize не режет его снова.

**Evidence:** focused unit для прямого/обратного направления и round-trip.

### AC3. Openings не теряются

Opening на согласованной части становится обычным room opening; opening на
остатке остаётся hosted с теми же абсолютными center/angle/length; opening через
breakpoint сохраняет свой непрерывный host и блокирует только затронутый диапазон.
Ни один вариант не меняет пользовательские поля и не создаёт overlap.

**Evidence:** frontend unit + Python backend positive/negative tests + production
smoke Optimize write.

### AC4. Законные drafts сохраняются

Свободная незамкнутая двухточечная цепочка, частично совпадающий draft, draft над
проёмом и неоднозначный draft остаются byte-equivalent. Полностью совпадающий
`draft-mt7igts5` удаляется целиком; частичной нарезки нет.

**Evidence:** optimizer units и real fixture.

### AC5. Первый этаж не переочищается

На fixture первого этажа законная partition с длинным id и две колонны остаются;
доступно прежнее число Resize handles, а `partial-shared`/`unequal-shared` не
маскируются как enabled.

**Evidence:** exact negative fixture audit.

### AC6. Backend отклоняет подделанные delta

Backend принимает только эквивалентный piecewise Optimize/rehost и отклоняет
каждое отдельное нарушение из §8, включая потерянный residual и opening.

**Evidence:** targeted Python tests и HA/Linux CI harness.

### AC7. Скрытая геометрия заметна поверх стен

Во всех инструментах редактора Плана перекрытая partition и сохранённый draft
показывают полную ось и исходные endpoints поверх real/virtual wall bodies. Во
View DOM слоя нет. Snap результата #137 и pointer hit targets не меняются.

**Evidence:** pure projection unit, production-bundle DOM/layer smoke и editor
golden для светлой/тёмной темы до/после Optimize.

### AC8. Отчёт, Undo и reload честны

Preview и result используют одинаковые счётчики; Cancel не меняет данные; один
Undo восстанавливает всё; после Apply+reload повторный Optimize — no-op.

**Evidence:** plan-optimizer/store-flow tests и smoke.

### AC9. Лимиты и производительность fail-closed

Кандидат, превышающий schema limits, сохраняет исходную partition вместо частичной
записи. На large-house fixture Optimize и построение диагностической проекции
остаются в утверждённых budgets без pointermove-dependent полного render.

**Evidence:** limit unit + benchmarks `coincident-partitions` и
`large-house-plan-snap`/обновлённые budgets только при обоснованной необходимости.

## 14. Тестовый план

Обязательны:

1. `test/coincident-partitions.test.mjs`: composite full/partial/reversed,
   differing cm, stable residual ids, limits, unknown fields, columns, other
   partitions/drafts, openings на трёх позициях, idempotence.
2. `test/plan-optimizer.test.mjs` и `test/resize-optimize.test.mjs`: counters,
   preview/Apply/Undo/reload и Resize reason transitions.
3. Обезличенный `test/fixtures/real-plan-second-floor.json` с тремя blockers и
   первый этаж как negative fixture.
4. `test/plan-snap-overlay.test.mjs` либо отдельный pure projection suite:
   independent coincident sources не теряют endpoints, snap authority комнаты не
   меняется, non-overlap не получает diagnostic marker.
5. Python tests `_safe_optimize_partition_rehost`: positive composite/residual и
   отдельный negative case на каждую fail-closed границу.
6. Named production smokes для реального Optimize/Resize и layer ordering;
   существующие unrelated smokes остаются зелёными.
7. Mutation gate: удалить all-or-nothing draft guard, заменить `max` толщины,
   потерять residual/opening, доверить frontend delta или поместить overlay под
   стенами — тест обязан покраснеть.

В реализации запускаются `npm run typecheck`, unit и build плюс адресные named
smokes. Golden, полный smoke и performance — по канону перед бетой; Linux CI
остаётся каноном полного HA harness.

## 15. Performance и touch

Piecewise pass выполняется только по явному Optimize. Индексация интервалов и
breakpoints должна быть ограничена затронутыми коллинеарными осями, без полного
quadratic scan на каждый атомарный кусок.

Диагностическая проекция вычисляется из immutable model snapshot и кэшируется по
тем же revision inputs, что архитектурная геометрия. Pointermove не перестраивает
её. Touch получает те же статические маркеры; новых hover-only действий нет.

## 16. Документация и release artifacts

В том же user-visible коммите обязательны:

- `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`;
- RU/EN user guide: доказательная piecewise-очистка, сохранение незавершённых
  цепочек и значение счётчиков;
- `docs/CANVAS.md`: диагностическая проекция и layer order;
- `docs/RESIZE.md`: исчезновение только реального duplicate obstacle;
- `docs/WALL-THICKNESS.md` и при необходимости `docs/ARCHITECTURE.md`: атомарный
  Optimize/rehost контракт;
- актуальный screenshot fingerprint, если изменился пользовательский UI;
- editor golden light/dark для скрытой partition/draft; baseline принимается по
  Linux CI review, не по случайному Windows raster.

## 17. Риски и rollback

Главные риски: потеря residual/opening, разрушение законного draft, уменьшение
толщины, backend/frontend рассинхрон, id churn, лишний editor DOM и ложная
доступность Resize.

Rollback выполняется единым откатом коммита #296. Новых schema fields нет, поэтому
старые клиенты читают сохранённую каноническую геометрию. Пользовательский rollback
одной операции — существующий Undo до ухода со страницы; после durable save
восстановление возможно из обычного backup/export.