houseplan-card/legacy/specs/290-near-axis-authoring-and-repair.md

Issue #290 — не создавать молча почти осевые уступы

• Issue: https://github.com/Matysh/houseplan-card/issues/290
• Статус: первая редакция для внешнего ревью; канонический статус задаётся метками issue
• Тип / приоритет: bug / P2
• Оценка: пользовательская ценность 8/10; ценность для разработки 8/10; сложность 9/10; риск 9/10
• Область: Walls drawing, safe Resize output, единый near-axis classifier, explicit Optimize preview/report/Undo, room/wall/opening rekey и invariants
• Модель данных: schema не меняется; существующая геометрия меняется только после подтверждения Optimize
• Связано: #141, #173, #223, #248, #277, #279, #284, docs/CANVAS.md, docs/RESIZE.md, docs/WALL-THICKNESS.md

1. Сценарий и подтверждённая причина

На реальном плане две комнаты хранят общее ребро от (-401, 708) до (-85, 709) в индексах решётки: 316 шагов вдоль и ровно один поперёк. Угол 0.181315° неразличим на обычном зуме, но это законная grid geometry, поэтому обычная канонизация и текущий Optimize её не меняют. Такой уступ уже потребовал renderer tolerance в #279 и остаётся источником нестабильных junction inputs.

Проблема состоит из двух частей:

1. Walls/Resize не имеют единого authoring-правила, запрещающего почти горизонтальный/вертикальный результат;
2. Optimize не имеет явно разрешённого lossy pass и поэтому правильно считает существующий 316×1 каноническим.

2. Решения владельца

Зафиксированы 2026-08-24:

1. При создании ребро в пределах допуска автоматически выравнивается по ближайшей горизонтальной/вертикальной оси. Специального modifier bypass нет.
2. Существующие уступы исправляются отдельным lossy-пунктом Optimize с отчётом «Выпрямлено стен: N; максимальное перемещение: X» и только после общего подтверждения.
3. Единый допуск — отклонение не более 0.25° от горизонтали или вертикали, тот же продуктовый порог, что использует устойчивый renderer #279.
4. Настоящие диагонали за пределами допуска не меняются.

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

3. Пользовательский результат

При рисовании preview сразу показывает точную горизонталь/вертикаль, и click сохраняет именно её. Resize никогда не оставляет почти осевой side/moving edge. Для старого плана Optimize заранее показывает число исправляемых физических стен и максимальный сдвиг; Cancel оставляет план byte-equivalent, Confirm даёт одну Undo-операцию. Диагональные стены остаются диагональными.

4. Единая классификация

Один pure helper и одна экспортируемая константа являются источником для authoring, Optimize и multi-wall renderer:

• NEAR_AXIS_MAX_DEGREES = 0.25;
• сравнение выполняется по нормализованному отношению minor/major component, эквивалентному tan(0.25°); renderer может продолжать использовать эквивалентный dot/sine form для orthogonal pairs;
• граница включительна;
• zero-length не классифицируется;
• exact horizontal/vertical уже canonical и не считается исправлением;
• endpoint order, winding, coordinate scale и theme не влияют на результат.

Для exact grid edges это означает: 316×1 классифицируется, 316×2 — нет. Порог не расширяется экранным zoom/tolerance и не поглощает полный grid step на коротком сегменте, если угол превышает 0.25°.

5. Authoring contract

5.1 Walls chain

После архитектурного endpoint/grid snap, но до hover preview и commit, free endpoint сравнивается с anchor. Если сегмент near-axis, minor coordinate free endpoint приравнивается minor coordinate anchor. Это точный grid node и один результат для hover/click.

Architectural endpoint на соседнем узле не имеет более высокого приоритета, если соединение создало бы запрещённый near-axis segment: авторская линия остаётся exact-axis, а существующий узел не объявляется соединённым. Resolver обязан показывать фактически сохраняемую точку; невидимый post-click rewrite запрещён.

Shift сохраняет своё действующее 45°-ограничение. Оно сначала выбирает exact 45° ray и потому не превращается в near-axis. Ctrl/Cmd closure применяет то же правило к closing edge; если выравнивание не замыкает exact first node, contour не объявляется закрытым автоматически.

5.2 Resize

Safe Resize #277 по-прежнему принимает только exact horizontal/vertical input с допуском на storage noise. Near-axis edge, существовавшая до задачи, не становится автоматически eligible: для неё есть Optimize.

Каждый candidate Resize строится из axis/normal plan и перед preview проходит тот же exact-axis postcondition. Любая minor-coordinate арифметическая погрешность схлопывается на исходную axis; результат в пределах 0.25° не может быть сохранён как уступ. Это не разрешает diagonal/partial-shared Resize и не меняет topology. Если postcondition потребовал бы сдвинуть unrelated vertex, candidate fail-closed вместо скрытой правки.

6. Explicit Optimize repair

6.1 Кандидаты

Lossy pass рассматривает room polygon edges, saved room drafts и independent partitions после ordinary grid alignment. Physical shared wall считается один раз независимо от двух room owners. Openings, open spans и wall thickness records не являются отдельными кандидатами: они reproject/rekey из исправленной host geometry существующим canonical pipeline.

Для near-horizontal edge рассматриваются две exact-axis цели y=a.y и y=b.y; для near-vertical — x=a.x и x=b.x. Изменяется equivalence class совпадающего topology endpoint во всех owners, чтобы shared centreline не расходилась. Выбирается кандидат:

1. прошедший room simplicity/orientation, ownership, opening fit и production geometry preflight;
2. с меньшим максимальным физическим сдвигом;
3. при равенстве — сохраняющий endpoint с большим числом incident exact edges;
4. при полном равенстве — детерминированный lexicographic endpoint.

Кандидаты не каскадируют: список строится из immutable input, а конфликтующие endpoint changes объединяются только если требуют одну и ту же target node. Конфликт/невалидная цель остаётся неизменной и учитывается как skipped, а не частично записывается.

6.2 Отчёт, Confirm и Undo

OptimizeReport получает как минимум:

• wallsStraightened — число уникальных physical segments;
• maxStraightenShiftCm и пространство, где достигнут максимум;
• wallsStraightenSkipped — число распознанных, но небезопасных кандидатов.

Диалог показывает отдельную строку, не смешивая lossy straightening с coordsCanonicalized или обычным moved. Максимум — верхняя граница по всем реально перемещаемым endpoints через cell_cm собственного пространства. Cancel/закрытие не пишет ничего. Confirm отправляет exact preview pair одной revision-guarded config/layout transaction; обычный Optimize Undo возвращает предыдущую геометрию. Повторный прогон после Confirm идемпотентен.

7. Scope

Входит

• shared near-axis helper/constant и перевод #279 на него;
• Walls hover/click/closure authoring rule;
• exact-axis postcondition safe Resize;
• lossy Optimize pass/report/dialog/Undo;
• wall/open-span/opening rekey и structural preflight;
• RU/EN i18n, unit, production smoke, backend optimize transaction, mutation, targeted golden и performance;
• canonical docs и оба changelog.

Не входит

• изменение grid pitch или координатного барьера #291;
• исправление углов больше 0.25°, arbitrary vertex editor или angle dialog;
• автоматическая миграция на load/save без Optimize confirmation;
• изменение renderer bevel/junction geometry #288;
• modifier для сохранения невидимого уступа;
• auto-repair кандидата, который не проходит structural preflight.

8. Acceptance criteria

AC1. Единая boundary matrix

Pure tests покрывают exact axis, 0.181315°, mirrored/reversed варианты, ровно 0.25°, значение выше порога, 316×1, 316×2, short edges и diagonal 30°. Authoring, Optimize и renderer #279 импортируют один threshold source; source guard запрещает отдельные литералы 0.25 в этих classifiers.

AC2. Walls не сохраняет 316×1

Production-bundle smoke рисует сегмент с raw/grid result 316×1. Hover rubber-band и committed draft/room показывают 316×0; exact endpoint, segment count и thickness metadata согласованы. Отдельно проверяются ordinary click, resumed draft, closure и existing-node snap conflict.

AC3. Resize не создаёт near-axis output

Outer и exact-shared safe drags сохраняют moving/side edges exact-axis на всех grid nodes. Mutation, добавляющая minor component меньше порога перед commit, либо канонизируется без unrelated changes, либо fail-closed. Pre-existing 316×1 handle остаётся disabled как diagonal до Optimize.

AC4. Optimize чинит реальный 316×1

Tracked test/fixtures/279-near-orthogonal-junction.json содержит duplicated shared physical edge 316×1. Preview сообщает wallsStraightened: 1, maximum одного grid step в корректных сантиметрах и ноль double-counting owners. Confirm создаёт exact horizontal shared edge; Cancel оставляет JSON byte-equivalent.

AC5. Related geometry сохраняется

После repair:

• обе room copies имеют exact одинаковые endpoints;
• topology vertex count/order и room ids не меняются;
• wall thickness/open spans rekey lossless;
• openings остаются на host, fit и angle корректны;
• checkWallKeys, checkMixedRoleRecords, references и production geometry preflight дают ноль нарушений;
• повторный Optimize changed:false и все straightening counters нулевые.

AC6. True diagonals не меняются

316×2, 30° room edge, diagonal partition и 45° Walls segment byte-equivalent после preview/Confirm; они не входят в wallsStraightened/skipped.

AC7. Report является верхней границей

Multi-space fixture с разными cell_cm доказывает, что maxStraightenShiftCm не меньше фактического движения ни одного endpoint и правильно называет space. Shared owners не удваивают count. Unsafe candidate не попадает в moved count и остаётся в skipped.

AC8. UI/Undo/revision safety

Dialog light/dark показывает отдельную строку lossy repair. Confirm без актуальных revisions получает conflict и не пишет partial pair; success даёт одну Undo. Reload/event/cold read совпадают с preview.

AC9. Мутанты

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

• порог ниже 0.181315°;
• strict < вместо inclusive boundary;
• bypass authoring snap;
• repair only one owner shared wall;
• считать room copies как две стены;
• применять Optimize без confirmation.

Каждый убивается соответствующим AC без повышения global golden tolerance.

AC10. Реальные планы и видимое снижение

npm run invariants проходит на real-plan-first-floor.json и real-plan-second-floor.json до и после подтверждённого Optimize. Audit считает почти-ортогональные topology nodes до/после без удвоения shared owners; после Confirm их число строго уменьшается на плане с repair candidates. Принятая владельцем строка Optimize «Выпрямлено стен: N; максимальное перемещение: X» показывает это изменение до подтверждения, причём N равно числу уникальных исправляемых physical walls. Повторный Optimize сообщает ноль исправлений. Настоящие диагонали не входят ни в node count, ни в N.

Доказательство: реальный invariants runner, production-bundle Optimize smoke и exact report assertions на обеих tracked fixtures.

AC11. Локальные гейты

• npm run typecheck;
• npm test;
• npm run build и bundle parity;
• npm run invariants;
• node scripts/check-docs.mjs;
• targeted Walls/Resize/Optimize smokes и mutation;
• targeted semantic golden verify.

Полные golden, smoke, performance и Linux HA harness выполняются перед beta.

9. Совместимость, touch, security и performance

Schema/model/storage version не меняются. Old frontend/backend читают исправленный обычный polygon; downgrade не требует migration. Старый near-axis план сохраняется до явного Optimize.

Plan editor desktop-first. Touch editor — best effort: near-axis rule работает для clean tap, а pinch/pan/pointercancel не создают segment и не подтверждают Optimize. View/kiosk rendering fully supported и сохраняет #279.

Новых HA actions/security boundaries нет. Authoring classifier O(1). Optimize pass линейный по edges плюс существующий bounded preflight; candidate evaluation не может стать global unbounded combinatorial search. Safe Resize сохраняет p95 budgets из docs/RESIZE.md; full performance gate обязателен.

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

• Автоматическое authoring-выравнивание без bypass может выбрать неверную ось рядом с порогом. Мера: inclusive boundary matrix AC1, hover/commit parity AC2 и отрицательные true-diagonal cases AC6.
• Lossy Optimize может сдвинуть только одного owner общей стены или потерять opening/thickness metadata. Мера: immutable candidate, shared equivalence class и полный набор invariants AC5/AC10.
• Repair одного уступа может каскадно создать другой либо изменить больше topology, чем показано в отчёте. Мера: кандидаты из immutable input, conflict-as-skipped, верхняя граница AC7 и идемпотентность AC5/AC10.
• Новый classifier может разойтись с renderer #279. Мера: один threshold source и source guard AC1.

11. Откат

Чистый revert implementation-коммита возвращает прежнее authoring/Optimize поведение. Schema не меняется; уже явно подтверждённая пользователем обычная polygon geometry остаётся читаемой и не требует downgrade migration.

12. Ожидаемые файлы

Product code:

• новый/существующий pure axis helper;
• src/wall-thickness.ts (единый threshold import);
• src/houseplan-card.ts;
• src/resize.ts;
• src/align-grid.ts / src/plan-optimizer.ts;
• src/i18n/en.json, src/i18n/ru.json.

Backend boundary:

• websocket Optimize применяет уже существующую exact preview transaction; schema изменения не ожидаются.

Tests/evidence:

• unit для helper, align/optimizer/resize/wall-thickness;
• minimized fixture без пользовательских имён;
• production-bundle Walls/Resize/Optimize smoke;
• mutation registry, targeted golden и performance.

Документация:

• docs/CANVAS.md, docs/RESIZE.md, docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md, docs/USER-GUIDE.md, docs/USER-GUIDE.ru.md, docs/TESTING.md, docs/CONFIG-COMPATIBILITY.md;
• docs/CHANGELOG.md, docs/CHANGELOG.ru.md.

13. Release

Implementation-коммит имеет Issue: #290, User-Visible: yes и оба changelog. Изменившиеся editor/Optimize goldens и docs screenshots принимаются только из штатного Linux artifact после npm run bundle:sync.

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

1. Выравнивается free endpoint, а не anchor текущего Walls segment; уже существующая geometry не сдвигается молча.
2. Near-axis existing edge не становится Resize-eligible: её исправляет только подтверждённый Optimize, после чего ordinary Resize доступен по #277.
3. Если обе exact-axis цели Optimize одинаково безопасны, degree/lexicographic tie-break является техническим детерминизмом, а не новым пользовательским выбором.
4. Unsafe repair перечисляется как skipped; Optimize не обязан чинить structural-invalid geometry любой ценой.
5. Touch editor: best effort / intentionally degraded; safety floor сохранён.