houseplan-card/docs/specs/292-resize-availability-audit.md

# Issue #292 — объяснимая доступность Resize на реальном плане

- **Issue:** https://github.com/Matysh/houseplan-card/issues/292
- **Статус:** первая редакция для внешнего ревью; канонический статус задаётся метками issue
- **Тип / приоритет:** bug / P1
- **Область:** eligibility safe Resize, причины запрета, реальная regression fixture,
  production pointer smoke и документация ограничений
- **Модель данных:** schema и model version не меняются
- **Зависит от:** #276, #289, #290; активная, но инертная рукоятка исправляется в #293

## 1. Сценарий, персона и подтверждение

**Кто и где:** владелец сложного реального плана открывает Plan → Resize после
импорта либо Optimize и пытается предсказуемо изменить размеры комнаты.

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

**До/после:** до задачи запреты выглядят одинаково и не защищены exact audit;
после задачи каждая разрешимая стена активна, а настоящий запрет имеет
стабильную человеческую причину без внутреннего jargon.

На `test/fixtures/real-plan-second-floor.json` текущий Resize показывает 37
рукояток: 11 разрешены и 26 запрещены. Текущий расклад причин запрета:

| Причина resolver | Рукояток | Наблюдаемая геометрия |
|---|---:|---|
| `unequal-shared` | 7 | соседняя комната имеет другие endpoints/протяжённость |
| `partial-shared` | 6 | сосед владеет только частью moving edge |
| `side-angle` | 6 | примыкающее ребро не строго перпендикулярно |
| `duplicate-physical-wall` | 5 | совпадающая independent geometry |
| `diagonal` | 2 | moving edge не осевая |

Сама доля запретов не является ошибкой: unsafe resize обязан остаться
запрещённым. Ошибка — ложные запреты после исправления/оптимизации геометрии,
отсутствие стабильного аудита реального плана и тексты, из которых пользователь
не понимает, что именно мешает перемещению стены.

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

После попадания зависимостей и повторного Optimize каждая стена, которую можно
сдвинуть без изменения topology, числа стен, физических толщин и более чем двух
комнат, получает активную рукоятку. Остальные рукоятки остаются видимыми и при
click, Enter или Space объясняют ограничение обычным языком и называют действие
только там, где оно безусловно: например, убрать перекрывающую independent
geometry. Статический текст не обещает, что Optimize исправит конкретную
наклонную стену.

Внутренние коды (`partial-shared`, `side-angle` и т. п.) пользователю не
показываются. Разрешённая рукоятка обязана реально двигаться; этот отдельный
интеграционный контракт закрывает #293.

## 3. Детерминированный eligibility audit

Один pure audit проходит те же room polygons, openings, walls, open spans,
partitions, drafts и columns и вызывает тот же `resolveSafeResize`, который
использует production render. Он возвращает:

- общее число rendered handles;
- enabled count;
- disabled count по каждому `SafeResizeReason`;
- стабильный идентификатор handle: room id, edge index, canonical endpoints;
- для exact shared pair — обе owner copies с одинаковым результатом.

Audit не является новой пользовательской телеметрией и не попадает в config.
Его результат для обеих real-plan fixtures хранится как test expectation.
После merge зависимостей implementation фиксирует новый точный baseline в том
же коммите; любое последующее изменение counts требует осознанного обновления
fixture expectation и объяснения в code review.

## 4. Правила доступности

1. Exact horizontal/vertical outer wall с двумя perpendicular side edges и без
   конфликтов разрешена, если существует хотя бы один ненулевой safe grid step.
2. Exact shared wall разрешена только при полном endpoint-to-endpoint владении
   ровно двух комнат и одинаковом допустимом диапазоне; обе owner-рукоятки дают
   один plan и один reason.
3. Ограничение #289 для mixed-role side edge не ослабляется: сохранение одной
   толщины ценой перезаписи другой запрещено.
4. Near-axis вход сначала исправляет явный Optimize #290. Сам Resize не меняет
   старую геометрию молча.
5. Совпадающая independent geometry после canonical cleanup #276 не должна
   оставаться ложным `duplicate-physical-wall`; настоящая partition/draft/column
   продолжает блокировать.
6. `enabled` разрешён только если один шаг в заявленном направлении проходит
   тот же structural/persistence preflight, что live preview. Resolver не может
   обещать операцию, которую первый pointermove гарантированно отвергнет.
7. Нельзя разрешать resize, изменяющий больше двух комнат, vertex count/order,
   число физических wall records либо их `cm`.

## 5. Тексты причин

RU/EN тексты должны отвечать «что мешает», а «что можно сделать» добавляется
только для безусловного действия, не требующего нового geometry analysis.
Минимальный контракт:

| Класс | Пользовательский смысл |
|---|---|
| angled / side angle | стена или примыкание не горизонтально/вертикально; Resize поддерживает только точные оси, без обещания автоматического Optimize |
| independent overlap | поверх границы лежит отдельная перегородка, черновой контур или колонна; её нужно убрать/перенести |
| partial / unequal shared | соседняя комната использует не всю ту же стену; безопасно двигать её как общую нельзя |
| multiple rooms | сдвиг затронул бы более двух комнат |
| thickness / opening | невозможно сохранить толщину либо безопасное положение проёма |
| invalid geometry | перемещение нарушило бы структуру плана; без внутреннего кода ошибки |

Динамический признак «Optimize способен исправить эту стену» и новые варианты
`SafeResizeReason` не вводятся этой задачей. Если в будущем появится такой
контракт, он оформляется отдельно и не является условием #292.

## 6. Scope

### Входит

- общий deterministic audit production eligibility;
- устранение доказанных ложных запретов после #276/#290;
- согласование owner copies exact shared wall;
- actionable RU/EN причины и keyboard/click activation;
- exact-count tests на обеих реальных фикстурах;
- production-bundle smoke, который проходит UI Plan → Resize.

### Не входит

- ослабление safe-resize ограничений для partial/mixed/diagonal topology;
- произвольный vertex editor или перемещение более двух комнат;
- исправление pointer no-op разрешённой рукоятки (#293);
- автоматический lossy repair при load/save;
- пользовательская аналитика/телеметрия.

## 7. Acceptance criteria

### AC1. Реальный baseline зафиксирован

После rebase поверх #276/#289/#290 тест запускает audit на
`real-plan-first-floor.json` и `real-plan-second-floor.json`, сравнивает exact
total/enabled/reason counts и печатает diff по handle id при расхождении.
Expectation не допускает `>=`, snapshots без причин или глобальную tolerance.

### AC2. Известная общая стена разрешена

Стена `room-a` edge 2 / `room-b` edge 2 второй фикстуры классифицируется как
одна exact shared physical wall: обе owner copies enabled, plan содержит ровно
две комнаты, endpoints и safe range совпадают. Ни одна третья комната не входит.

### AC3. Ложные причины исчезают после repair

Targeted fixtures доказывают, что подтверждённый near-axis repair #290 снимает
`diagonal`/`side-angle`, а canonical cleanup #276 снимает только ложный
`duplicate-physical-wall`. Настоящие diagonal и independent partition остаются
запрещены с правильной причиной.

### AC4. Unsafe cases остаются закрыты

Partial shared, unequal endpoints, mixed-role side edge #289, third-room,
thickness conflict и opening collision остаются disabled. Mutation, удаляющая
любой guard, убивается точным reason/count либо geometry invariant.

### AC5. Причина доступна в production UI

Production bundle показывает disabled handle с `aria-disabled=true`, доступным
focus и локализованным `aria-label`. Click, Enter и Space показывают тот же
actionable текст; pointerdown не создаёт drag и не пишет config/history.

### AC6. Resolver и render не расходятся

Source/production-path guard доказывает, что audit и render используют один
resolver и один reason type. Нельзя иметь отдельную упрощённую копию условий
для тестового счётчика.

### AC7. Первый шаг согласован с preview

Для каждого enabled handle хотя бы одно направление имеет ненулевой grid step,
проходящий topology и persistence preflight. Если оба направления отвергаются,
handle disabled с детерминированной причиной, а не active no-op.

### AC8. Инварианты

После всех разрешённых targeted moves на real fixtures проходят wall keys,
mixed-role records, references, opening host/fit, room simplicity/orientation,
physical geometry preflight; число стен и multiset `wall.cm` не меняются.

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

- `npm run typecheck`;
- `npm test`;
- `npm run build` и bundle parity;
- `node scripts/check-docs.mjs`;
- targeted eligibility audit, production smoke и mutation.

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

## 8. Совместимость, touch и performance

Schema/storage не меняются. Старый frontend продолжает читать тот же план.
Touch editor остаётся best effort, но disabled reason доступен через tap, а
активный pointer stream не конфликтует с pinch/pan/pointercancel.

Audit выполняется только в тестах. Production render сохраняет существующий
snapshot cache: resolver не должен пересчитываться более одного раза на handle
за frame. Performance budget safe Resize из `docs/RESIZE.md` не меняется.

## 9. Риски и меры

- Погоня за меньшим процентом disabled может разрешить unsafe topology. Мера:
  точная negative matrix AC4 и structural/persistence preflight AC7–AC8.
- Counts могут разойтись с production render из-за второй реализации audit.
  Мера: один resolver/reason type и source guard AC6.
- Статический текст может пообещать repair, которого нет для true diagonal.
  Мера: §5 запрещает такое обещание; fixtures проверяют near-axis и настоящую
  диагональ раздельно.
- Полный audit в render может ухудшить editor responsiveness. Мера: test-only
  audit и существующий per-snapshot eligibility cache.

## 10. Откат

Чистый revert implementation-коммита возвращает прежнюю eligibility и тексты;
миграция/feature flag не требуются, persisted geometry/schema не меняются.

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

- `src/resize.ts`, `src/houseplan-card.ts`;
- `src/i18n/en.json`, `src/i18n/ru.json`;
- unit/production-path tests и exact fixture audit;
- `demo/smoke_room_resize.mjs` либо отдельный real-plan smoke;
- `docs/RESIZE.md`, `docs/TESTING.md`, при необходимости `docs/ARCHITECTURE.md`;
- `docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`.

## 12. Release

Implementation-коммит имеет `Issue: #292`, `User-Visible: yes` и обновляет оба
changelog. Issue не закрывается вручную: она закрывается выпуском beta.

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

1. Метрика 70% — диагностический сигнал, а не продуктовая цель «разрешить любой
   ценой»; после исправлений число запретов может оставаться высоким.
2. Точный post-dependency baseline фиксируется только после rebase всех трёх
   зависимостей, иначе тест законсервирует заведомо переходное состояние.
3. Дублированные owner handles допустимы в DOM для hit testing, но обязаны иметь
   одинаковый resolution; audit явно показывает physical equivalence.