houseplan-card/docs/specs/291-lattice-coordinate-write-barrier.md

# Issue #291 — единый барьер записи lattice-координат

- **Issue:** https://github.com/Matysh/houseplan-card/issues/291
- **Статус:** первая редакция для внешнего ревью; канонический статус задаётся метками issue
- **Тип / приоритет:** tech-debt / P1
- **Оценка:** пользовательская ценность 7/10; ценность для разработки 10/10;
  сложность 10/10; риск 10/10
- **Область:** frontend/backend config+layout persistence boundary, near-grid
  coordinate canonicalization, explicit Optimize report, imports/Undo/recovery,
  invariant and mutation gates
- **Модель данных:** JSON schema, Store/storage/model version и типы полей не
  меняются; координаты остаются numbers
- **Связано:** #198, #223, #224, #248, #258, #278, #282–#284,
  `docs/adr/282-wall-geometry-representation.md`,
  `docs/CONFIG-COMPATIBILITY.md`, `docs/CANVAS.md`

## 1. Сценарий и измеренная причина

Stage 0 (#283) показала, что на двух живых пространствах владельца 65,38% и
78,77% координат лежат рядом с узлом решётки, но не равны canonical double
этого узла. Худшее отклонение — `8×10⁻⁸` шага. Авторской off-grid geometry
почти нет.

Текущий storage barrier #224 округляет allow-listed numbers до девяти
десятичных знаков. Для шага `1/240` это создаёт стабильную десятичную запись,
но не canonical IEEE-754 result `Math.round(v×240)/240`. Поэтому независимые
пути вычисления одного узла получают разные bits: wall key уезжает в соседний
bucket (#258), а Optimize после round-trip снова видит работу (#248).

Смена schema на integer node ids для устранения этого явления не нужна.
Нужна одна boundary-функция, которую невозможно обойти обычным writer path.

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

Зафиксированы в #284:

1. На lattice canonicalization распространяются и plan geometry, и позиции
   маркеров/room labels в layout.
2. Дальняя authored geometry не притягивается к узлу; она сохраняется и
   перечисляется в отчёте.
3. После migration и после произвольной editing session noise population
   должна быть нулевой.
4. Видимый отчёт Optimize остаётся компактным: общий счётчик исправленных
   координат и максимальный физический сдвиг, затем строки только для
   пространств, где действительно были изменения, с их счётчиками.
   Неизменённые пространства не перечисляются.

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

**Кто и где:** владелец дома с несколькими этажами/пространствами, который
импортировал старый план либо продолжает редактировать его в Plan. Проблема
проявляется в обслуживающем действии Optimize и после обычной записи geometry,
хотя на экране субпиксельный хвост координаты неразличим.

**До:** один визуальный узел может иметь разные double-биты в зависимости от
истории вычислений. Пользователь видит повторную «работу» Optimize, неверный
wall key или последующий дефект стыка, но не может связать его с координатным
шумом.

**После:** любой сохранённый config/layout не содержит near-node noise. Обычная
запись убирает только измеренный невидимый хвост без перемещения authored
off-grid geometry. Перед явным Optimize пользователь видит отдельное от
физических перемещений описание координатной очистки, решает Confirm/Cancel и
получает один Undo. В доме с несколькими этажами отчёт показывает общий итог и
только затронутые пространства, не превращая диалог в полный технический лог.

## 4. Термины и scalar contract

### 4.1 Одна решётка и одна граница noise

- `GRID_N = 240`, canonical node: `Math.round(value × GRID_N) / GRID_N`;
- deviation измеряется в шагах:
  `abs(value × GRID_N − round(value × GRID_N))`;
- `exact`: deviation строго `0`;
- `noise`: `0 < deviation < 1e-4` шага;
- `off-grid`: deviation `>= 1e-4` шага.

`1e-4` — существующая измерительная граница Stage 0 и единый shared constant
для invariant, TypeScript и Python. Она на четыре порядка меньше шага и выше
измеренного ULP-хвоста. Literal «дальше половины шага» из исследования
выражает запрет видимого snap: математически расстояние до *ближайшего* узла
никогда не бывает больше половины шага, поэтому рабочее разделение намеренного
off-grid и noise обязано использовать измеренный `1e-4` threshold.

### 4.2 Две канонизации, не одна рекурсивная

`canonicalizeLatticeCoordinate(value)`:

- finite exact/noise value возвращает canonical nearest node double;
- finite off-grid value не grid-snap'ится и сохраняет действующую
  nine-decimal storage canonicalization #224;
- `-0` становится `+0`;
- non-number/non-finite проходит без изменения до существующей validation.

`canonicalizeScalar(value)` сохраняет nine-decimal contract #224 для
allow-listed angles, transforms, lengths и normalized ratios, которые не
обязаны быть lattice nodes.

Рекурсивное округление любых numbers запрещено: unknown/future fields,
physical centimetres, colours, brightness, vacuum calibration и остальные
неперечисленные значения byte-equivalent.

## 5. Allow-list lattice fields

Near-node canonicalization применяется только к coordinate/size components:

- room `poly[*][0..1]`; legacy rect `x/y/w/h`;
- lossless endpoints `walls[].a/b`;
- `room_drafts[].points`, `partitions[].a/b`, `wall_columns[].center`,
  `open_spans[].a/b`;
- opening `x/y` только как coordinate components; diagonal/wall-bound values,
  попадающие в off-grid population, не притягиваются независимо к lattice;
- decor line endpoints и grid-bound origin/size fields existing allow-list;
- layout position `x/y` для device markers, room labels и сохранённых future
  owners.

Остаются scalar-only: plan backdrop transforms, angles, opening length/host
`t`, decor angle/scale, column angle и marker angle. Их existing
nine-decimal semantics не меняются.

Allow-list реализуется зеркально в frontend и backend и закрепляется общей
fixture. Добавление нового persisted coordinate field требует обновить оба
runtime и registry/test в одном коммите.

## 6. Непроходимый write barrier

### 6.1 Frontend

Все product mutations могут работать с immutable/local candidate, но ни один
config/layout/position payload не отправляется и не принимается в committed
state до общей boundary-функции:

- serialized config write канонизирует целый candidate и frontend принимает
  ровно его;
- individual layout write канонизирует position;
- localStorage/cache канонизирует full layout;
- Optimize/import/Undo/recovery responses принимаются в том exact виде,
  который подтвердил backend, без повторной несовместимой формулы.

Не требуется расставлять snap по десяткам assignments. Source-guard перечисляет
все outbound config/layout writer methods и падает при новом writer, который
не проходит общий boundary.

### 6.2 Backend

`async_save_config_state()` и `async_save_layout_state()` остаются единственной
Store boundary для config/layout. Их shared payload builders применяют Python
mirror до `Store.async_save`; import, optimize, undo, recovery и ordinary WS
writers обязаны сходиться туда. Direct Store write config/layout вне boundary
запрещён source/AST guard'ом. Operational stores (trails, virtual lights) не
являются plan geometry и не канонизируются.

Backend validation возвращает canonical candidate, поэтому stale/old frontend
не может занести noise. Frontend/Python shared fixture сравнивает точные JSON
numbers, а не tolerance.

## 7. Existing data и explicit Optimize report

Read существующего Store не переписывает данные. Первая последующая обычная
config/layout write проходит barrier и устраняет near-node noise во всём
candidate; это невидимый sub-pixel canonicalization, уже разрешённый owner.

Явный **Optimize plans** остаётся немедленным bulk-path и добавляет отчёт:

- total `latticeCoordinatesCanonicalized`;
- `latticeCoordinatesFar` — untouched off-grid coordinate components;
- maximum shift для canonicalized noise в physical units;
- ниже — только изменённые пространства с их
  `latticeCoordinatesCanonicalized` и `latticeCoordinatesFar`; пространства с
  нулём изменений не показываются;
- layout entries входят в общий итог и, если UI имеет отдельного именованного
  owner для layout, показываются по тому же правилу «только изменённые»;
- maximum shift для canonicalized noise в physical units не смешивается с
  видимым `moved/maxShiftCm` обычного grid alignment.

Optimize не пытается snap'ить far population этой задачей; действующий explicit
Align-to-grid pass может предлагать видимое движение отдельно по своему
контракту. UI обязан различать `noise canonicalized` и `elements moved`.

Confirm сохраняет exact preview config/layout revision-guarded transaction и
один Undo. Cancel/close не пишет. Повторный Optimize после storage/event/cold
reload даёт нулевой noise counter и no-op, если других maintenance changes нет.

### 7.1 i18n-контракт отчёта

Новые строки не расширяют общий `gs.optimize_changes`: координатная
канонизация имеет отдельный maximum и не должна смешиваться с обычным
grid-alignment. Добавляются два ключа с нейтральными числовыми формулировками,
не требующими отдельной pluralisation:

| Ключ | English | Русский |
|---|---|---|
| `gs.optimize_lattice_summary` | `Noisy coordinate values canonicalized: {n}; maximum movement: {cm} cm.` | `Канонизировано шумовых значений координат: {n}; максимальный сдвиг: {cm} см.` |
| `gs.optimize_lattice_space` | `{space}: coordinate values canonicalized: {n}; off-grid values left unchanged: {far}.` | `{space}: канонизировано значений координат: {n}; оставлено значений вне сетки: {far}.` |

`gs.optimize_lattice_summary` показывается только при `n > 0`.
`gs.optimize_lattice_space` показывается только для затронутых пространств;
layout без собственного пользовательского имени входит только в summary.
Placeholder `{cm}` передаёт измеренный maximum с тремя значащими цифрами:
обычной десятичной записью при `|cm| >= 0.001`, с удалением незначащих нулей,
и scientific notation при `0 < |cm| < 0.001`. Ненулевой maximum никогда не
округляется до `0` и не использует политику округления вверх до `0.1 см` из
обычного grid-align report; например, `0.000033 cm` показывается как
`3.30e-5 cm`.
Кнопки Confirm/Cancel/Undo и общий lossy-warning используют существующие ключи.

## 8. Scope

### Входит

- lattice-aware scalar + shared constants в TS/Python/invariant;
- typed allow-list config/layout/position traversal;
- frontend/backend boundary and bypass guards;
- existing-data cleanup через next write и explicit Optimize report/Undo;
- import/export/restore/recovery parity;
- real/noisy fixture acceptance, exact idempotence range, mutation and
  performance;
- compatibility/canvas/architecture/testing/user docs и оба changelog.

### Не входит

- integer storage schema, stable wall ids или planar graph from ADR #282;
- выпрямление законного уступа `316×1` (#290);
- renderer corridor #288, partial resize #289 или union algorithm #278;
- grid snap authored off-grid geometry без отдельного Optimize permission;
- изменение grid resolution, unit system или physical cm;
- очистка source fixtures с noise.

## 9. Acceptance criteria

### AC1. Scalar idempotence и exact bits

Для 4801 nodes `k/240`, `k=-2400..2400`:

- canonicalization идемпотентна;
- canonical node не меняется;
- nine-decimal noise form каждого выбранного node превращается точно в тот же
  JS/Python double/JSON number;
- negative range и `-0` корректны;
- off-grid `0.06`, `0.2875` и boundary values вокруг `1e-4` не grid-snap'ятся.

### AC2. Shared allow-list parity

Одна fixture содержит все lattice fields, scalar fields, unknown siblings,
diagonal opening и future layout owner. TS и Python outputs deep-equal expected;
input immutable. Scalar/unknown/off-grid values сохраняют #224 semantics.

### AC3. Живой профиль после migration равен нулю

На privacy-minimized real-plan clones после boundary/Optimize:

```
npm run invariants -- --config <candidate> --lattice
  шум у узла          0 (0.00%)  — ближе 0.0001 шага, но не точно
```

для обоих spaces и layout. `checkWallKeys`, `checkMixedRoleRecords`, references
и production geometry preflight дают ноль violations. Far population остаётся
и совпадает с preview report.

### AC4. Произвольная editing session не возвращает noise

Поведение доказывается композицией, а не вторым mega-smoke, дублирующим все
редакторы:

- production-bundle smokes `smoke_wall_chain_thickness`, `smoke_room_resize`,
  `smoke_opening_preview`, `smoke_free_walls`, `smoke_decor` и
  `smoke_drag_bounds` проходят реальные controller paths для Walls chain,
  Resize, opening, partition, column, decor, device marker и room label;
- executable `coordinate-write-barrier-guard.test` доказывает, что у этих
  controllers нет отдельного outbound config/layout writer и что добавление
  writer мимо общей boundary красит gate;
- `smoke_lattice_write_barrier` исполняет все найденные production writers на
  шумном candidate и после каждой принятой config/layout пары проверяет именно
  `latticeProfile(...).noise === 0`;
- `smoke_optimize_coordinate_canonicalization` отдельно проходит bulk write,
  reload/export-equivalent server snapshot и повторный no-op.

Таким образом после каждого committed pair `latticeProfile.noise === 0`, а
операция не может потребовать отдельного ручного snap call в каждом controller.
Это явная запись способа доказательства AC4 по PROCESS.md §7.1; отдельный
гигантский session-smoke не является дополнительным требованием.

### AC5. Write barrier нельзя обойти

Executable source/AST guard знает все frontend outbound config/layout writers и
backend config/layout Store writers. Добавленный test writer с direct payload
или `Store.async_save` мимо boundary красит gate. Operational non-geometry
stores остаются разрешены explicit allow-list.

### AC6. Source fixtures остаются шумными

`test/fixtures/real-plan-*.json` не переписываются implementation/formatting
tools. Existing profile pins (`noise >= 100`) остаются зелёными на raw files;
tests работают только с clones. Отдельно доказано: barrier на clone даёт ноль,
а raw fixture после теста byte/hash-equivalent.

### AC7. Optimize report и transaction

Preview показывает общий счётчик canonicalized coordinates, maximum physical
noise shift и строки только для пространств с ненулевыми изменениями;
неизменённые пространства отсутствуют. Сумма строк согласована с total; far не
считается moved, maximum noise shift не занижается. Cancel — zero writes; stale
revision — no partial pair; Confirm — один config/layout transaction и один
Undo; reload/cold read deep-equal preview; второй run no-op.

### AC8. Compatibility paths

Full/space/plan-only import, export, duplicate remap, backup restore, optimize
undo, pending recovery и ordinary old-client config/layout write заканчиваются
одинаковой canonical pair. Unknown fields и valid off-grid geometry survive.
No schema/storage/model version bump.

### AC9. Polyclip and structural regression

Точная co-incidence после snap проходит #278 failure-isolation fixtures и full
wall body tests. Barrier не является поводом ослабить preflight или удалять
локальную union isolation. #288/#289/#290 exact-grid regressions сохраняют свои
ожидаемые результаты независимо от noise cleanup.

### AC10. Мутанты

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

- `Math.round`/Python `round-equivalent` → truncation;
- порог меньше measured `8×10⁻⁸` либо больше authored boundary;
- пропуск layout `x/y`;
- direct frontend writer bypass;
- direct backend Store bypass;
- рекурсивная канонизация unknown number.

Каждый mutant убивается AC1–AC6.

### AC11. Performance

Boundary traversal линейный и выполняется один раз на serialized payload, не на
pointermove/render tick. Large config save/Optimize benchmark не регрессирует
действующий p95 более чем на 20% same-run baseline и не добавляет второго full
deep clone сверх существующего candidate contract.

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

- `npm run typecheck`;
- `npm test`;
- `npm run build` и bundle parity;
- backend canonicalization/validation tests;
- `node scripts/check-docs.mjs`;
- targeted write-barrier/Optimize smoke, invariants, mutation and benchmark.

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

## 10. Совместимость, UX, touch и security

JSON numbers и field shapes не меняются, old clients continue reading. Old
writer cannot persist near-node noise because backend owns the boundary. Read
не мигрирует silently; next write canonicalizes tiny measured tails, explicit
Optimize gives report and Undo.

View/touch/kiosk appearance не меняется на видимом масштабе. Device-marker drag
на touch получает тот же final boundary; Plan editor остаётся desktop-first.
Новых HA actions, external data, URL/HTML и permission boundaries нет.

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

- Ошибочно широкий threshold может притянуть намеренную off-grid geometry.
  Мера: measured `1e-4`, boundary cases AC1, typed allow-list AC2 и сохранение
  far population AC3/AC7.
- TS и Python могут получить разные округления одного узла и снова создать
  wall-key drift. Мера: shared exact fixture/JSON bits AC1–AC2 и запрет
  tolerance-сравнения.
- Новый writer может обойти barrier. Мера: executable frontend/backend guard и
  bypass mutants AC5/AC10.
- Full-candidate traversal может удвоить clone/save cost. Мера: один boundary
  pass и same-run benchmark AC11.
- Обычная следующая запись очистит старый noise без отдельного Optimize. Мера:
  граница ограничена доказанным невидимым хвостом; authored off-grid и unknown
  fields byte-equivalent, а explicit bulk path сохраняет preview/Cancel/Undo.

## 12. Откат

Чистый revert implementation-коммита прекращает новую canonicalization; schema
и Store migration откатывать не требуется. Уже сохранённые canonical lattice
bits не восстанавливаются автоматически: они семантически равны прежнему узлу,
а обратное внесение noise было бы новой порчей. Явный Optimize до следующей
операции можно отменить штатным Undo, который хранит pre-transaction snapshot.

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

Product/frontend:

- `src/coordinate-canonicalization.ts`;
- `src/houseplan-card.ts` только для boundary/report UI integration;
- `src/align-grid.ts`, `src/plan-optimizer.ts` для report accounting;
- `src/i18n/en.json`, `src/i18n/ru.json`.

Backend:

- `custom_components/houseplan/coordinate_canonicalization.py`;
- central store/validation/websocket paths только если guard выявит обход.

Tests/evidence:

- shared coordinate fixture и TS/Python tests;
- optimizer/align/import/recovery tests;
- source/bypass guard;
- real-plan clone smoke/invariants;
- mutation registry and save/Optimize benchmark.

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

- `docs/CONFIG-COMPATIBILITY.md`, `docs/CANVAS.md`, `docs/ARCHITECTURE.md`,
  `docs/USER-GUIDE.md`, `docs/USER-GUIDE.ru.md`, `docs/TESTING.md`, ADR note;
- `docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`.

## 14. Release

Implementation-коммит имеет `Issue: #291`, `User-Visible: yes` и оба
changelog. Visual baselines не перепринимаются без semantic change; если
Optimize dialog меняется визуально, targeted golden/docs screenshots
принимаются только из штатного Linux artifact после bundle sync.

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

1. Owner intent «не трогать дальние» означает не grid-snap'ить Stage-0
   `offGrid` population; existing invisible nine-decimal scalar storage
   canonicalization #224 сохраняется.
2. Existing Store не переписывается на read. Immediate bulk path — Optimize;
   ordinary next write применяет общий barrier ко всему candidate.
3. `PLAN_MODEL_VERSION` не повышается: pass data-driven и идемпотентен, schema
   и read semantics не меняются.
4. Diagonal wall-bound coordinates, не попадающие в noise population, остаются
   off-grid; их независимый X/Y snap запрещён.
5. Touch editor: best effort; View/kiosk fully supported.
6. Layout без самостоятельного пользовательского имени агрегируется только в
   общий итог; если UI уже показывает именованного layout-owner, для него
   действует то же правило отчёта, что для пространства: строка появляется
   только при ненулевых изменениях.