houseplan-card/docs/specs/442-marker-write-rollback.md

ТЗ #442 — Атомарный откат отклонённых записей маркера

• Issue: https://github.com/Matysh/houseplan-card/issues/442
• Приоритет: P2, bug
• Статус ТЗ: готово к ревью
• Маршрут: full; меняются основной Save устройства и сохранение калибровки робота, включая отказный UX и конкурентный контракт
• Связанные контракты: #439 (guarded optimistic rollback общих настроек), #441 (атомарные CRUD-операции маршрутов карт), #162 (маршрутная калибровка робота), #314 (отдельный откат физической геометрии)

Сценарий

Home admin редактирует устройство либо калибрует карту робота. Backend отклоняет config/set из-за semantic validation, конфликта или транспортной ошибки. Карточка должна сразу снова показывать последнее подтверждённое сервером состояние, но не терять введённый в открытом UI draft: пользователь исправляет значение или повторяет сохранение без перезагрузки карточки и без повторной ручной подгонки.

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

До: после отказа основной Device editor сообщает об ошибке, но локальный marker остаётся изменённым и может попасть в View либо в следующую запись. Калибровка закрывается и показывает success до ответа сервера; при отказе на экране остаётся фантомная матрица, а ручную подгонку приходится повторять.

После: непринятый marker config автоматически возвращается к последнему подтверждённому состоянию. Device editor остаётся открыт с введёнными полями. Auto/manual calibration остаётся открытой и занятой до ответа: при успехе она закрывается и только затем сообщает об успехе, при отказе сохраняет рассчитанный draft для Retry и показывает ошибку.

Подтверждённая проблема

1. HouseplanEditorRuntime._saveMarker() меняет cfg.markers до await _saveConfigNow(). Обычный catch снимает busy и показывает toast, но не возвращает _serverCfg, не перестраивает devices и не отделяет отказ config/set от ошибок последующих layout/file housekeeping.
2. Backend реально может отклонить доступные из Device editor изменения через validate_marker_controls, validate_marker_light_entities, validate_marker_value_badges и validate_marker_vacuum_routes.
3. _vacSaveMatrix() мутирует marker in-place, перестраивает devices и вызывает debounced _saveConfig(), после чего callers сразу закрывают _vacCalConfirm/_vacFit и показывают vac.autocal_done либо vac.cal_done. Promise результата у UI нет.
4. CRUD маршрутов в src/editors/vacuum-maps-section.ts уже использует optimisticAttempt()/rollbackOptimistic() и остаётся эталоном, а не второй реализацией в рамках #442.
5. Общий writer уже сериализует запросы и отдельно обрабатывает conflict и physical geometry. #442 не должен подменять эти механизмы глобальным reload либо откатом несвязанной транзакции.

Скоуп

В скоупе:

• атомарный immutable candidate для основного Save устройства;
• guarded rollback всего config-кандидата при отказе именно его config/set;
• восстановление производных marker/device представлений после отката;
• сохранение draft Device editor и возможность Retry;
• асинхронная запись auto-calibration, принятого high-residual proposal и manual fit;
• busy-состояние калибровочного UI до ответа сервера;
• success toast и закрытие calibration UI только после подтверждённой записи;
• сохранение рассчитанной матрицы или параметров ручной подгонки при отказе;
• конкурентные случаи conflict reload и более новой локальной ревизии;
• регрессия атомарных маршрутов #441;
• unit, browser smoke и mutation witnesses;
• документация и оба changelog.

Не-скоуп

• атомаризация всех 18 generic _saveConfig() call sites;
• Hide/Show, удаление marker, discovery seeding, обычные live, trail_mode и source настройки робота, если они не входят в сохраняемый calibration/route candidate;
• изменение четырёх backend validators, schema либо формата ошибок;
• изменение математики auto-calibration, residual threshold или manual fit;
• изменение маршрутизации карт, route identity либо выбора этажа;
• откат физической геометрии или замена механизма #314;
• транзакционное удаление безвредных файлов-копий после rejected rebind;
• новый глобальный transaction manager для всех editor writes;
• новые тексты ошибок, отдельные модальные предупреждения или дополнительные подтверждения.

Контракт поведения

1. Граница marker-транзакции

Основной Save строит новый ServerConfig как отдельный candidate из текущего подтверждённого root. До отправки не допускается in-place изменение предыдущего cfg.markers: предыдущий config должен оставаться пригодным для точного восстановления.

Одна попытка фиксирует:

• глубокую копию предыдущего config;
• предыдущий _cfgContentFingerprint;
• _cfgRev до отправки;
• candidate и его content fingerprint.

Candidate может быть показан оптимистично, но при отклонении его config/set вызывается guarded rollback. После успешного rollback карточка сбрасывает marker-derived caches/signature, перестраивает devices и запрашивает render. Ни одно поле непринятого marker не остаётся в View или следующей записи.

Конфигурационная транзакция заканчивается сразу после успешного _saveConfigNow(). Layout update, очистка старого layout id и файловое housekeeping выполняются только после durable config acceptance. Ошибка такого последующего best-effort шага не имеет права откатывать уже принятый сервером config.

2. Guarded rollback и конкуренция

Rollback применяется только если текущие revision и content fingerprint всё ещё принадлежат не принятому candidate. Сравнение content обязательно и для того же object identity: более новая in-place правка не может быть затёрта старым reject.

Таблица решений:

Событие во время попытки	Итог
semantic/schema/transport reject, candidate всё ещё текущий	восстановить previous config и прежний fingerprint
conflict, _saveConfigNow() уже перечитал server truth	не откатывать authoritative reload
появилась более новая local revision/content	не откатывать новую правку
пользователь закрыл диалог во время запроса	config откатывается по guard; диалог не воскрешается; toast остаётся
config принят, затем упал layout/file side effect	принятый config остаётся; сообщается ошибка соответствующего шага

Сериализация через существующую _writeChain и expected_rev сохраняется. Pending debounced write не должен обгонять прямой marker/calibration save; один и тот же candidate не отправляется повторно скрытым debounce.

3. Основной Device editor

При Save UI становится busy и не запускает вторую попытку. После успеха сохраняется текущий UX: диалог закрывается, devices перестраиваются и показывается toast.marker_saved.

При отказе config-записи:

• _serverCfg и отображение возвращаются к accepted state;
• диалог, если он ещё открыт, остаётся открыт и выходит из busy;
• его локальные поля остаются такими, какими их ввёл пользователь;
• Retry строит новый immutable candidate поверх актуального server config;
• success toast не показывается; показывается существующая локализованная ошибка;
• если диалог закрыт пользователем, он не создаётся заново.

Rebind сохраняет порядок безопасности файлов: copy допустим до config save, cleanup — только после acceptance. Оставшаяся после reject копия безвредна и остаётся вне скоупа housekeeping.

4. Routes/maps

Добавление, переназначение и удаление map_routes продолжает использовать атомарный persistRoutes() из #441. #442 не возвращает эти операции к общему debounce и не создаёт второй route writer.

Основной Save устройства обязан переносить текущий vacuum block в candidate, не стирая уже принятую route transaction. Ошибка основного Save откатывает его полный candidate к состоянию непосредственно перед попыткой, а не к снимку до последней успешно принятой route-операции.

5. Запись калибровки

_vacSaveMatrix() становится асинхронной атомарной операцией либо делегирует такой операции. Она:

1. строит отдельный config candidate;
2. материализует минимальный marker в candidate для first-use vacuum, не изменяя previous config;
3. записывает matrix в exact route/legacy target через существующий writeVacuumMatrix();
4. фиксирует optimistic attempt, присваивает candidate и перестраивает preview;
5. ожидает _saveConfigNow();
6. возвращает success только после server acceptance;
7. при reject выполняет guarded rollback, перестраивает devices и возвращает failure вызывающему UI.

6. Calibration UX

Для low-residual auto-calibration Device editor остаётся на экране. На время записи соответствующие calibration controls busy/disabled; повторный клик не создаёт второй запрос. vac.autocal_done появляется только после acceptance. При reject диалог остаётся открыт, busy снимается, показывается ошибка; Retry повторно использует тот же пользовательский вход и снова рассчитывает matrix.

Для high-residual proposal:

• Apply не очищает _vacCalConfirm до ответа;
• proposal получает busy state, закрытие, Cancel, Fit и повторный Apply на это время недоступны;
• success закрывает proposal и показывает vac.autocal_done;
• reject оставляет тот же proposal/matrix открытым, снимает busy и позволяет Retry либо переход в ручную подгонку.

Для manual fit:

• Save не очищает _vacFit до ответа;
• overlay получает busy state; drag, rotate/mirror, Save и выход, который мог бы потерять draft, на время запроса не создают новую попытку;
• success закрывает overlay и показывает vac.cal_done;
• reject оставляет exact FitParams и route identity, снимает busy, возвращает accepted config и позволяет Retry без повторной подгонки.

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

Данные и совместимость

• Persisted schema, marker/vacuum shape и revision protocol не меняются.
• Миграции данных нет.
• Успешные marker, route и calibration payloads должны быть эквивалентны текущим после canonicalization.
• Legacy calibration и explicit map_routes сохраняют контракт #162/#443.
• First-use write сохраняет остальные принятые поля marker: clone-and-patch не удаляет неизвестные/future поля marker, config или vacuum.

Touch, клавиатура и доступность

Busy является настоящим disabled-состоянием controls, а не только визуальным индикатором. Повторные touch/click/Enter не создают дополнительный Save. Focus остаётся в том же открытом dialog/overlay после reject. Закрытие через Esc/scrim во время уже начатой попытки не воскрешает UI после ответа и не мешает config rollback. Новых targets, жестов и строк i18n нет.

Ошибки и крайние случаи

Случай	Ожидаемое поведение
controls cycle отклонён backend	marker в View прежний, draft dialog сохранён, Retry доступен
invalid light/value source отклонён	тот же guarded rollback без частичного marker
route calibration отклонена	accepted matrix остаётся в config, новая fit/proposal остаётся UI-draft
first first-use vacuum calibration отклонена	synthetic marker не остаётся локально
повторный Save во время pending	один config/set
conflict reload во время reject	server truth выигрывает, старый rollback no-op
новая локальная правка поверх candidate	новая content revision выигрывает
Esc закрыл Device editor в полёте	config восстановлен, dialog не воскрешён, error toast виден
config принят, layout update не удался	config не откатывается и не расходится с сервером
route CRUD #441 reject/retry	прежний атомарный UX остаётся зелёным

Acceptance criteria и доказательства

AC1. Основной Save атомарен

Unit/contract test доказывает, что _saveMarker() строит отдельный candidate и при semantic reject восстанавливает весь previous config/fingerprint. Browser smoke отклоняет controls или другой реально валидируемый field, сверяет View, сохранённый dialog draft, busy=false и успешный Retry.

AC2. Откат не затирает владельца новой ревизии

Unit покрывает обычный reject, conflict reload, заменённый root и более новую in-place правку того же candidate. Mutant с unconditional rollback и mutant, который пропускает fingerprint для same identity, обязаны краснеть.

AC3. Main Save отделяет durable config от side effects

Test double принимает config/set, затем отклоняет layout/file operation. Принятый marker остаётся локально, старый config не восстанавливается, а операция не показывает toast.marker_saved до завершения обязательной части успешного пути.

AC4. Auto-calibration ждёт сервер

Browser smoke держит config/set deferred: до resolve отсутствует success, Device editor/proposal остаётся открыт и busy, повторный Apply не пишет второй раз. Resolve закрывает нужный UI и даёт ровно один success toast.

AC5. Reject auto proposal сохраняет Retry

High-residual proposal при reject остаётся с той же matrix/route identity, accepted config восстановлен, busy снят и второй Apply может успешно записать ровно одну калибровку.

AC6. Reject manual fit сохраняет подгонку

Browser smoke фиксирует изменённые FitParams, отклоняет Save и проверяет: overlay не закрыт, параметры не изменились, pointer/кнопки снова доступны, config вернулся к accepted matrix. Retry success закрывает overlay и только тогда показывает vac.cal_done.

AC7. First-use и route identity сохранены

Тест отклоняет первую калибровку auto-discovered vacuum: minimal marker не остаётся в _serverCfg. Существующие multifloor/first-use tests подтверждают, что successful retry пишет matrix в exact route и не возвращает legacy path.

AC8. #441 не регрессировал

smoke_vacuum_route_draft продолжает доказывать atomic add/reassign/delete, reject/retry и отсутствие пустого route draft в persisted config. Основной marker Save не стирает только что принятую route transaction.

AC9. Общие гейты

Зелёные typecheck, unit, build и синхрон трёх bundle trees. Для diff в src/** обязателен check-docs; smoke-select определяет дополнительные browser scenarios. Полный Linux HA harness остаётся каноническим CI. Изменение не трогает геометрию, поэтому model-invariants неприменим. Visible busy/reject UX проверяется smoke; постоянный golden добавляется только при наличии подходящей canonical surface.

План тестирования

• расширить test/serialized-write-queue.test.mjs проверкой same-identity content change;
• выделить pure candidate/rollback helpers для marker и calibration там, где это уменьшает stateful browser setup;
• добавить browser smoke rejected marker Save + preserved draft + Retry;
• расширить vacuum smoke deferred/rejected auto proposal и manual fit;
• сохранить зелёными smoke_vacuum_route_draft, smoke_vacuum_firstuse, smoke_vacuum_multifloor, smoke_vacuum и smoke_dialog_zombie;
• добавить mutation-gate anchors для отсутствующего marker/calibration rollback, раннего success/close и same-identity fingerprint guard;
• выполнить typecheck, npm test, build, bundle:sync, check-docs, выбранные smokes и обязательный CI на exact SHA.

Карта реализации

• src/serialized-write-queue.ts — строгий guarded rollback при изменённом content того же object identity;
• src/houseplan-editor-runtime.ts — immutable marker/calibration candidates, async persistence, rollback/rebuild и delayed success/close;
• src/houseplan-card.ts — типы busy-state, render/disabled contract и async delegates;
• при необходимости небольшой отдельный pure-модуль marker candidate, чтобы не раздувать editor runtime;
• test/, demo/smoke_*.mjs, scripts/mutation-gate.mjs — witnesses;
• docs/CONFIG-COMPATIBILITY.md, docs/VACUUM.md, оба changelog и screenshot fingerprint — release artifacts.

Риски и rollback

• Главный риск — откатить authoritative conflict reload или более новую правку; закрывается revision + unconditional content-fingerprint guard.
• Второй риск — принять config на сервере, затем ошибочно вернуть локально previous из-за layout/file failure; закрывается явной durable boundary.
• Третий риск — потерять first-use marker либо route identity при clone; его закрывают first-use и multifloor witnesses.
• Четвёртый риск — закрыть calibration UI до реального ответа и потерять draft; закрывается deferred/reject/retry smoke.
• Rollback реализации — revert frontend/tests/docs/bundle. Data migration нет; принятые marker/calibration payloads совместимы с предыдущей версией.

Release-артефакты

• В том же user-visible implementation commit обновляются docs/CHANGELOG.md и docs/CHANGELOG.ru.md со ссылкой на #442.
• docs/CONFIG-COMPATIBILITY.md фиксирует: semantic reject marker write не остаётся локальной конфигурацией, conflict/newer revision выигрывают.
• docs/VACUUM.md фиксирует, что success калибровки означает подтверждённую запись, а reject сохраняет auto/manual draft для Retry.
• Любой src/** diff требует канонической Docs screenshots съёмки и приёмки fingerprint по процессу. Если существующий кадр реально меняется, его diff просматривается; несвязанные локальные baseline differences не принимаются.
• Новая постоянная golden surface не требуется, если calibration pending/reject UI отсутствует в текущей canonical matrix; light/dark и keyboard/touch состояние подтверждается browser smoke.
• Нового performance или security artifact не требуется: payload size, вычислительная геометрия и trust boundary не меняются.

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

• Default Q1: в #442 входят только UI-пути, которые могут изменить поля четырёх marker semantic validators; generic marker/config writes вне этого множества не атомаризируются.
• Default Q2: calibration UI остаётся открытым и busy до ответа; reject сохраняет рассчитанный draft для Retry, success закрывает UI после acceptance.
• Любой reject semantic marker attempt откатывает только эту попытку; conflict reload и более новая revision/content имеют приоритет.
• Draft основного Device editor живёт отдельно от _serverCfg и не теряется при rollback.
• Backend/schema/i18n, успешный View и физическая геометрия не меняются.
• Файлы, скопированные перед rejected rebind, остаются безопасным остатком и не удаляются новой клиентской гонкой.