houseplan-card/docs/specs/278-wall-union-isolation.md

Issue #278 — локальный сбой extra-body union не гасит всю кладку

• Issue: https://github.com/Matysh/houseplan-card/issues/278
• Статус: первая редакция для ревью; канонический статус задаётся метками issue
• Тип / приоритет: bug / P1
• Оценка: пользовательская ценность 10/10; ценность для разработки 9/10; сложность 7/10; риск 9/10
• Область: canonical wall geometry, independent physical bodies, strict geometry commit barrier, model invariants, Plan/View/static/hidden Iso/Glow
• Модель данных: без schema/migration и без записи во время render
• Связано: #141, #197, #199, #218, #264, #276, #277, docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md

1. Сценарий и персона

После Resize пользователь открывает пространство и видит комнаты, проёмы, подписи и осевые линии, но не видит кладку ни одной стены. Persisted walls при этом содержит 25 записей. Один конфликт physical geometry превращает полноценный этаж в визуально пустой.

После исправления core room masonry остаётся видимой и физически канонической, даже если отдельный independent extra нельзя объединить с ней одной boolean операцией. Локальный extra сохраняется отдельным structural component либо локально деградирует; он не обнуляет уже построенные стены. Ни один новый geometry commit не может записать такой degraded candidate.

2. Доказательная база

На приложенном 33.json из 1.67.0-beta.7:

• 8 rooms, 25 wall records, 8 partitions и 14 openings;
• wallBodiesUnionPath() возвращает null;
• _renderWallBodies() вследствие этого возвращает пустой wall layer;
• production bundle детерминированно показывает кладку на состоянии до Resize и полностью теряет её после;
• scripts/model-invariants.mjs считает состояние валидным;
• shared preflight #199 на точном payload.config корректно возвращает failed / wall-null и блокирует Optimize Apply.

Последний пункт уточняет границу: #199 не сломан. Чистый optimizePlans() сам не ремонтирует input, но UI не записывает его повторно. Проблема в том, что Resize сохранил candidate без такого барьера, renderer применяет общий catch к последовательному extra union, а CLI invariants не повторяют production pass.

Текущая причинная точка — цикл extraBodies в wallBodiesGeometry(): room rings, atomic edges и junction patches имеют локальную изоляцию, а exception при union(body, extra) попадает в внешний catch и возвращает null для всего результата.

3. Зафиксированный продуктовый контракт

1. Один local independent body не может удалить валидную кладку комнат и остальные успешно построенные physical bodies.
2. Existing saved config читается без фоновой записи, удаления объектов или автоматического Optimize.
3. Render может использовать локализованный component fallback, но exact candidate любой geometry-changing операции обязан пройти strict preflight; degraded результат нельзя сохранить как success.
4. Основной structural failure room masonry остаётся fail-closed. Задача не воскрешает старые raw room rings, создававшие facade teeth до #141/#197.
5. Optimize preflight #199 остаётся strict и по-прежнему блокирует wall-null либо degraded candidate. Восстановление конкретной redundant partition выполняет #276.
6. Все canonical consumers получают одно множество физических components; SVG-only обход, отличный от floor/light/static, запрещён.

Открытых продуктовых вопросов нет.

4. Два результата: strict и render-safe

Pure production preparation возвращает типизированный structural result:

• ok — core и все extras успешно объединены;
• degraded-extra — core room masonry успешно, но один или несколько extras нельзя слить с общей geometry; сохранены primary geometry и локальные isolated components;
• failed-core — обязательная room/exterior/opening geometry не построена;
• not-applicable — пространство не содержит физических стен.

Strict mode принимает только ok/not-applicable. Его используют Optimize и commit barrier редакторов.

Render-safe mode принимает ok и degraded-extra. failed-core остаётся null/fail-dark. Режимы используют один computation/result, а не две реализации boolean geometry.

5. Изоляция independent extras

1. Core room result завершается до extra pass и сохраняется транзакционно: masonry после room openings, roomGeom, paper geometry, depth и opening index.
2. Extra bodies уже представлены после собственных hosted cuts. Каждый body нормализуется/проверяется независимо и получает стабильный порядковый component id, не persisted id.
3. Для каждого extra попытка union выполняется независимо. Присваивание общей geometry происходит только после успешной операции.
4. Если union выбрасывает либо возвращает structurally invalid result, последняя успешная primary geometry сохраняется, а валидный исходный extra добавляется как isolated component. Следующие extras продолжают обрабатываться.
5. Если сам extra non-finite/zero-area/non-simple и не может быть безопасно представлен даже отдельно, пропускается только этот body и результат всё равно degraded-extra; core/остальные extras не исчезают.
6. Isolated component остаётся физическим препятствием для render, hit/source guard, Glow/sun и clean-floor там, где соответствующий consumer ранее учитывал independent bodies. Он не добавляется в roomGeom и room area.
7. Coincident component не вычитается по evenodd из primary body. Renderer получает отдельные path fragments/groups либо эквивалентный non-cancelling representation; простая конкатенация противоположно ориентированных rings в один evenodd path запрещена.
8. Component order и итоговое множество не зависят от порядка partitions, drafts, columns или room records.

6. Canonical consumers

Один structural result определяет:

• full card Plan и View/киоск;
• houseplan-space-card static render;
• hidden Iso footprint/wall faces;
• room inner contour, paper/floor footprint и displayed clean area;
• Glow barriers, source-inside-body guard и spill;
• солнечные препятствия;
• geometry preflight и model invariants.

Presentation может рисовать primary/isolated components разными <path>, но ни один consumer не может молча отбросить isolated physical component, если он способен принять component set. roomGeom намеренно остаётся только room masonry, чтобы independent partitions/columns не меняли площадь комнаты.

7. Strict commit barrier

Pure checkSpacePhysicalGeometry() (имя не API) проверяет exact candidate одной операции через ту же preparation и structural result, что renderer/#199.

В этой задаче аудитом покрываются все frontend операции, способные изменить:

• rooms, walls, open_spans;
• ordinary/hosted openings geometry/host;
• partitions, room_drafts, wall_columns.

Каждая такая операция должна пройти общую transaction boundary до записи. Существующие config edits, не меняющие geometry (marker, colors, names), не перепроверяют весь план и не блокируются из-за legacy degraded space.

Контракт boundary:

1. получает immutable before и exact after;
2. no-op не запускает WS/history;
3. ok/not-applicable разрешает существующий один atomic save;
4. degraded-extra/failed-core/exception откатывает in-memory candidate к before, делает 0 WS calls и 0 Undo entries;
5. показывает bounded RU/EN toast: Изменение отменено: геометрию стен нельзя безопасно построить. / Change canceled: wall geometry could not be built safely.;
6. stale fingerprint перед фактическим save требует повторной проверки exact current candidate; успешный результат другой ревизии не переиспользуется.

#277 использует этот barrier для Resize. Если последовательность реализации временно требует локального adapter, перед merge #278 остаётся один exported source of truth, а дублирующий adapter удаляется.

8. Optimize и recovery

• checkOptimizeGeometry() переиспользует общий strict result и не принимает degraded-extra как green.
• Действующий failure dialog #199 и zero-write behavior сохраняются.
• #276 может превратить exact redundant partition в valid candidate до preflight; после этого Optimize становится green и ремонтирует конкретный fixture.
• #278 не удаляет/перемещает пользовательские extras и не предлагает новый Repair UI.

9. Model invariants

scripts/model-invariants.mjs получает production structural check для каждого пространства экспорта:

• failed-core и degraded-extra являются ошибкой с bounded reason/count;
• никакие title, ids, координаты или полное exception message не печатаются в публичный CI artifact без явного debug-флага;
• script возвращает non-zero на 33.json-классе fixture;
• валидные empty/image-only/virtual-only spaces не становятся false positive;
• source preparation импортируется из общего pure module либо проверяется строгим parity guard; копия production условий в script запрещена.

10. В скоупе

• per-extra transactional union и isolated component representation;
• strict/render-safe typed structural result;
• parity full/static/iso/floor/Glow/sun consumers;
• reusable strict geometry transaction barrier и audit geometry writers;
• integration с #199 без ослабления preflight;
• production structural model invariant;
• анонимизированный minimized fixture из 33.json;
• unit, production-bundle smoke, mutation, performance и targeted golden;
• RU/EN failure toast, docs/changelogs.

11. Не входит

• автоматическое удаление/rehost partition (#276);
• safe Resize eligibility/range (#277);
• замена polyclip-ts;
• оптимистичный raw-room-ring fallback при core failure;
• новая пользовательская recovery/repair панель;
• background write/migration при load/render;
• исправление произвольного invalid source polygon;
• публикация hidden Iso.

12. Архитектурный контракт

1. Общий typed result и per-extra isolation живут в canonical geometry modules, не в Lit render methods.
2. Existing wallBodiesGeometry() может получить совместимый richer result; callers мигрируют атомарно, без периода, когда часть видит isolated bodies, а часть нет.
3. Structural components immutable; caches keyed точным geometry fingerprint и не удерживают config/history.
4. wallBodiesUnionPath() больше не кодирует global success только наличием одной строки d; successful component set и successful-empty различаются.
5. Static и full render используют одну component-to-path projection.
6. Commit barrier вызывается до mutation visibility/save. Если старый handler мутирует config in place, adapter обязан восстановить before до toast и requestUpdate; предпочтителен candidate-first путь.

12.1. Риски и меры

Риск	Мера
#276/#277 ещё проходят ревью, хотя §18 задаёт их раньше #278	Параллельны только независимые ТЗ/review. Код строго последователен: #278 не переходит в S6, пока #276 и #277 не merged; перед началом ветка пересоздаётся/rebase от актуального dev.
Legacy plan навсегда остаётся degraded-extra, если не подходит под безопасный repair #276	Render сохраняет стены, но strict geometry edits остаются заблокированы; user guide предлагает Optimize, затем export/bug report, без скрытого удаления данных.
Временный strict adapter #277 переживает merge и создаёт две расходящиеся проверки	#278 удаляет adapter в том же implementation commit; source guard/call-site inventory и mutant writer-bypass требуют один exported barrier.
Отдельный isolated path визуально вычитает coincident masonry из-за evenodd	Отдельные non-cancelling path fragments/groups, AC4 golden и permutation tests.
Renderer показывает extra, а Glow/sun/static его теряют	Typed component set является общим входом; consumer parity AC5 и code-review call table.
Полностью malformed extra нельзя даже представить отдельно и возникает локальная утечка света/стены	Только этот body получает bounded degraded reason; strict write запрещён, остальные стены сохраняются; invalid-extra negative fixture фиксирует известную локальную деградацию.
Generic barrier блокирует marker/color edit на старом degraded плане	Проверяются только geometry writers; AC8 call-count и non-geometry browser smoke.
In-place handler оставляет candidate после отказа	Immutable before + mandatory rollback before toast/requestUpdate, AC7/AC9 mutation.
Component-aware union замедляет каждый render	Existing structural cache, §13 valid/degraded budgets и bounded cache test.
Per-piece catch скрывает core structural failure и возвращает старый опасный raw-ring fallback	Typed failed-core остаётся fail-dark; #197/core regressions AC11 и global-catch mutant.

13. Производительность

На валидном large-house fixture новый component-aware pass не более чем на 10% и 20 ms p95 медленнее текущего wall geometry same-run baseline. Degraded fixture завершается не более чем за 100 ms p95. Render cache сохраняет прежний bounded lifecycle; strict commit check вызывается только при geometry commit, не на pointermove/state tick. Model-invariants допускает линейный per-space pass.

14. Touch и accessibility

View/киоск touch release-blocking: fallback wall components pointer-transparent и визуально совпадают с desktop. Rejected geometry gesture показывает toast, не требует hover и не оставляет captured pointer. Plan editor остаётся desktop-first; safety behavior обязательно для mouse/touch/pen.

15. Критерии приёмки

AC	Критерий	Доказательство
AC1	Анонимизированный fixture исходно даёт extra union failure при валидном core; новый result — degraded-extra, не global null.	Regression unit with failure proof.
AC2	Exception/invalid result одного extra сохраняет primary и следующие extras; permutations дают то же component set.	Unit + property/permutation matrix.
AC3	Invalid raw extra локально пропускается, count/reason bounded; core room failure остаётся failed-core.	Negative unit matrix.
AC4	Coincident isolated component не вырезает primary path по evenodd и wall layer остаётся видимым в Plan/View.	Production-bundle smoke + golden.
AC5	Full/static/hidden Iso/floor/paper/Glow/source guard/sun используют один component set; room area не включает extras.	Consumer parity tests + code review.
AC6	Strict preflight принимает только ok/not-applicable; #199 остаётся red на degraded candidate и green после valid #276 reconciliation.	Unit + Optimize smoke.
AC7	Каждая geometry writer surface из §7 проходит common barrier; forced degraded result даёт rollback, toast, 0 WS/Undo.	Call-site table + browser mutation smoke.
AC8	Non-geometry config edit не запускает strict pass и не блокируется legacy degraded space.	Call-count unit/browser smoke.
AC9	Stale candidate fingerprint rechecks; exception не оставляет in-memory partial state.	Controlled async unit + smoke.
AC10	model-invariants красный на fixture и зелёный на valid/empty/image-only/virtual-only matrix.	CLI tests.
AC11	Existing #197 junction isolation и core fail-dark regressions остаются зелёными; raw room fallback не возвращён.	Existing + focused unit.
AC12	Mutation guards ловят global-catch regression, discarded isolated body, strict-accepts-degraded, writer-bypass и invariants-bypass.	Mutation gate, 1/1 each.
AC13	Performance/cache budgets §13 выполняются.	Targeted benchmark + cache test.
AC14	Typecheck, unit, build, targeted smokes зелёные; tracked bundles byte-identical.	Fast gates.
AC15	RU/EN changelog и user/wall/architecture/testing/status docs актуальны.	Docs gate + review.

16. План тестов

• минимизировать 33.json до synthetic fixture без пользовательских строк;
• test/wall-thickness.test.mjs: core/extra isolation, invalid/permutations;
• новый pure transaction-barrier test и source/call-site inventory guard;
• test/plan-geometry-preflight.test.mjs: strict degraded classification;
• CLI fixture tests для model-invariants;
• demo/smoke_wall_union_isolation.mjs: production bundle Plan/View/static, failed geometry write, toast/zero-write и valid retry;
• targeted light/dark golden до/после local failure;
• mutation ids из AC12;
• valid/degraded large-house benchmark.

Полные golden/smoke/performance и Linux HA harness запускаются перед бетой.

17. Release-артефакты и rollback

Изменение пользовательское. Implementation commit имеет User-Visible: yes и обновляет:

• docs/CHANGELOG.md, docs/CHANGELOG.ru.md со ссылкой #278;
• docs/USER-GUIDE.md, docs/USER-GUIDE.ru.md — safe rejection/recovery;
• docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md, docs/CANVAS.md;
• docs/TESTING.md, docs/STATUS.md и model-invariants documentation;
• RU/EN i18n, tests/smoke/mutations/benchmark, reviewed golden candidates;
• tracked bundles и docs screenshot fingerprint при source diff.

Rollback — revert implementation commit. Persisted schema не меняется, поэтому обратной миграции нет. После rollback affected legacy plans снова могут терять весь wall layer, а geometry writers — сохранить unchecked candidate; release rollback должен рекомендовать не редактировать геометрию до обновления.

18. Принятые технические предположения

1. Exact class/reason names не API; strict/render-safe semantics являются API внутри продукта.
2. Bounded toast §7 — минимальная обратная связь для редкого race/boolean failure; отдельный dialog и список объектов не нужны.
3. Internal diagnostic может считать failed extras, но production console не печатает пользовательские ids/coordinates и не спамит каждый render.
4. #276, затем #277, затем #278 — порядок merge. При интеграции #278 удаляет временный strict adapter #277, сохраняя его AC.
5. degraded-extra допустим только для чтения существующего config; ни Optimize, ни editor commit не считает его успешной моделью.