houseplan-card/docs/specs/421-negative-test-proofs.md

ТЗ #421 — Отрицательные доказательства для трёх защитных проверок

• Issue: https://github.com/Matysh/houseplan-card/issues/421
• Приоритет: P2, tech-debt/tests/infra
• Маршрут: standard; три независимые поверхности нарушают критерий small
• Связанные контракты: #43 (support preview), #404/#407 (browser error guard), #401/#409 (приёмка документационных скриншотов), #85 (mutation gate)

Сценарий

Разработчик меняет lifecycle support-preview, browser error guard или CLI приёмки скриншотов и запускает объявленную для этого контракта проверку. Сейчас она может остаться зелёной после удаления защищающего механизма, поэтому ревьюер получает ложное доказательство и регрессия может попасть в релиз.

После этой задачи тот же намеренный дефект воспроизводится адресным мутантом либо контролируемым red proof. Гейт обязан покраснеть до merge; исправная версия проходит тот же тест зелёной.

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

До: видимого дефекта в текущей версии нет, но три зелёные проверки не гарантируют заявленное поведение. Будущая регрессия может незаметно вернуть пригодность заменённого support-токена, пропустить browser exception или стереть историю приёмки документационных кадров.

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

Цель

Сделать три существующих утверждения доказательными: тест или гейт обязан краснеть, когда ломается ровно тот механизм, защитой которого он объявлен. Пользовательское поведение не меняется; закрепляются уже действующие контракты.

Проблема

1. Lifecycle support-preview

test_support_preview_replacement_and_discard_are_draft_local создаёт три разных токена, а затем отправляет три идемпотентных discard. Успех discard ничего не говорит о наличии токена в runtime-map. Поэтому тест остаётся зелёным, если убрать replacement-loop из ws_support_preview().

Отдельно не доказано истечение SUPPORT_PREVIEW_TTL_S: ни один тест не переводит monotonic clock за границу TTL и не пытается применить истёкший токен.

2. reportPageErrors()

Browser probes guard_tail_exception, guard_tail_rejection и guard_closed_page завершаются через finish(). Существующие мутанты ломают round-trip внутри finish() либо общий registry страниц, но не отдельный round-trip в reportPageErrors(). Удаление этого await остаётся зелёным.

3. Acceptance trace документационных скриншотов

Чистые тесты docsAcceptancePlan() проверяют выбор replace/keep/witnesses, но не ветку в docs-accept.mjs, которая при fingerprint-only refresh переносит предыдущий manifest.acceptance. Возврат к пустому следу приёмки не замечается.

Скоуп

В скоупе:

• реальные submit-проверки заменённого и явно удалённого preview-токена;
• доказательство, что токен другого draft_id не инвалидируется заменой;
• детерминированный TTL-тест без ожидания реального времени;
• отдельная browser probe, использующая reportPageErrors(), а не finish();
• адресный мутант, удаляющий round-trip только из reportPageErrors();
• исполняемая, экспортируемая логика построения нового manifest acceptance внутри docs-accept.mjs и её unit-тест;
• адресный мутант, возвращающий потерю прежнего acceptance trace;
• запись отрицательных доказательств в mutation registry и документ ревью.

Не-скоуп

• изменение WebSocket API, кодов ошибок, TTL, лимитов или idempotency semantics;
• изменение идемпотентного ответа preview/discard для отсутствующего токена;
• изменение UI Help & feedback или текста privacy notice;
• переработка общего browser smoke harness и всех существующих probes;
• изменение правил принятия скриншотов, witness floor или CLI-флагов;
• новый общий процессный документ: требование показать, что тест умеет падать, уже закреплено в AGENTS.md и PROCESS.md;
• полный аудит всех тестов проекта за пределами трёх названных швов.

UX

Новых экранов, сообщений, настроек и действий нет. Help & feedback сохраняет действующие ответы и срок жизни preview; browser smokes и docs acceptance CLI остаются инструментами разработки. Desktop, touch, kiosk, keyboard, focus и ARIA не затронуты.

Контракт

1. Replacement, discard и TTL preview-токена

Для одного HA user и одного draft_id новый preview заменяет предыдущий:

• submit со старым токеном отвечает support_preview_expired;
• submit с новым токеном остаётся доступным, пока токен не удалён, не истёк и не был успешно использован;
• preview другого draft_id того же user заменой не затрагивается и может быть успешно отправлен;
• после успешного preview/discard submit того же токена отвечает support_preview_expired;
• сам discard остаётся идемпотентным и по-прежнему может ответить {ok: true} для уже отсутствующего токена.

TTL проверяется управляемым monotonic clock:

• до expires токен пригоден;
• при now >= expires следующий submit вызывает pruning и отвечает support_preview_expired;
• relay transport для отклонённого токена не вызывается;
• тест не использует sleep и не зависит от скорости CI.

Тесты используют разные idempotency keys, чтобы результат lifecycle токена не маскировался relay/idempotency-кэшем.

2. Отдельный отрицательный путь reportPageErrors()

Новая browser probe:

1. запускает настоящий Chromium через существующий harness;
2. регистрирует страницу штатным watchPage/launch путём;
3. создаёт page error в хвосте текущего browser turn;
4. завершает сценарий только через await reportPageErrors();
5. ожидает ненулевой exit code и сообщение uncaught exception(s) inside the card.

Probe не вызывает finish(): иначе она снова доказывала бы чужую ветку. verify-guard.mjs запускает probe рядом с существующими и отличает ожидаемый красный вердикт от timeout/crash без диагностического сообщения.

Mutation registry содержит адресный патч, который удаляет await roundTripLivePages() только из тела reportPageErrors(). Патч обязан иметь уникальный anchor и краснеть на новой probe.

3. Сохранение acceptance trace

CLI-owned функция построения принятого manifest получает:

• candidate manifest;
• прежний acceptance либо отсутствие значения;
• решение docsAcceptancePlan();
• флаг/причину сознательного пропуска witnesses.

Она возвращает новый manifest без мутации входов:

• если decision.replace непуст, записывает новый trace с точными declared, witnesses, floor и, при необходимости, witnessesSkippedBecause;
• если пиксели не заменялись, сохраняет все поля прежнего trace и добавляет lastWriteWasFingerprintOnly: true;
• если прежнего trace нет, fingerprint-only refresh создаёт только lastWriteWasFingerprintOnly: true, не выдумывая witnesses;
• main() использует эту функцию как единственный путь формирования поля acceptance перед записью docs/images/screenshots.json.

Unit-тест живёт рядом с тестами docs-accept.mjs, а не только в тестах чистого планировщика. Mutation registry возвращает старый пустой fallback и обязан получить красный результат именно от этого теста.

Затрагиваемые файлы

Ожидаемый набор:

• tests_backend/test_ha_websocket.py — submit-проверки replacement/discard и отдельный TTL case;
• demo/guard/guard_report_page_errors.mjs — новая отрицательная browser probe;
• demo/guard/verify-guard.mjs — запуск и проверка новой probe;
• scripts/docs-accept.mjs — тестируемая CLI-owned сборка acceptance trace;
• test/docs-accept.test.mjs — точная матрица нового/сохранённого trace;
• scripts/mutation-gate.mjs — адресные мутанты трёх разрывов;
• test/mutation-gate.test.mjs — существующая применимость реестра; новые специальные тесты нужны только если текущий общий контракт их не покрывает;
• docs/TESTING.md — только если без короткого описания новых guard IDs их невозможно обнаружить из действующего runbook.

Production modules custom_components/houseplan/websocket_api.py и demo/serve.mjs менять не требуется, если новые доказательства подтверждают текущее поведение. Если тест выявит реальный дефект поведения, реализация останавливается и найденный продуктовый scope оформляется отдельно.

Модель данных и миграция

Persisted config/layout, support-package schema, WebSocket payloads и runtime records preview не меняются; миграция и compatibility-поля не нужны.

Тестируемая функция docs-accept.mjs перестраивает тот же manifest, который CLI пишет сейчас. Формат docs/images/screenshots.json не расширяется: при реальной замене пикселей создаётся уже существующий acceptance trace, а при fingerprint-only refresh переносятся его прежние поля и добавляется уже действующий lastWriteWasFingerprintOnly. Старые manifests без acceptance остаются допустимыми.

i18n, compatibility, touch и security

• новых строк и изменений словарей нет;
• persisted config, import/export и WebSocket schema не меняются;
• desktop/touch/kiosk/accessibility не меняются;
• новых входов, прав, URL и раскрытия данных нет;
• тесты support preview не должны писать raw package/message в failure output;
• временные mutation worktrees удаляются существующим cleanup-контрактом.

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

Обычный npm test получает только дешёвые unit/registry проверки. HA integration test выполняется в закреплённом backend job. Новая browser probe и адресные мутанты входят в дорогой mutation/release gate и не запускаются на каждом обычном frontend unit прогоне сверх уже существующего verify-guard там, где он явно вызван.

Никаких runtime-издержек продукта нет. Реальные sleep запрещены; TTL управляет mocked monotonic clock.

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

• AC1. После replacement submit старого токена получает support_preview_expired, а submit токена другого draft_id достигает подменённого transport с точными preview bytes. Доказательство: HA backend test + отрицательный прогон без replacement-loop.
• AC2. После preview/discard submit удалённого токена получает support_preview_expired; идемпотентный success самого discard не используется как доказательство удаления. Доказательство: HA backend test + отрицательный прогон без удаления записи.
• AC3. Токен принимается до TTL и отклоняется при now >= expires, transport после истечения не вызывается; тест не ждёт реальное время. Доказательство: HA backend test + отрицательный прогон без submit-pruning.
• AC4. Новая browser probe завершается ожидаемым failure и сообщением через reportPageErrors() без вызова finish(). Доказательство: node demo/guard/verify-guard.mjs.
• AC5. Мутант, удаляющий round-trip только из reportPageErrors(), оставляет probe без требуемого вердикта и mutation gate считает мутанта пойманным. Доказательство: адресный запуск scripts/mutation-gate.mjs --id=....
• AC6. При замене пикселей новый acceptance trace точен; при fingerprint-only refresh прежние declared, witnesses, floor и произвольные совместимые поля сохраняются, выставляется lastWriteWasFingerprintOnly. Входы не мутируются. Доказательство: unit.
• AC7. Мутант, возвращающий пустой fingerprint-only trace, краснеет на тесте CLI-owned функции, а не на тесте docsAcceptancePlan(). Доказательство: адресный запуск mutation gate.
• AC8. node scripts/mutation-gate.mjs --check, typecheck, полный frontend unit suite, build и затронутые backend tests зелёные. Доказательство: локальные гейты и Linux CI.
• AC9. Runtime product behavior, публичные API, i18n, config schema и пиксели не изменены. Доказательство: diff/code review; smoke/golden/docs screenshots не требуются при отсутствии product-source visual delta.

План отрицательной проверки

До реализации или в review evidence фиксируются три независимых красных результата:

1. удалён replacement-loop (и отдельно pruning/discard для AC2–AC3) — HA-тесты падают на ожидаемом коде/transport call;
2. удалён round-trip только из reportPageErrors() — новая browser probe не выдаёт требуемый красный вердикт, verify-guard/mutation gate падает;
3. fingerprint-only fallback заменён пустым trace — unit CLI-owned функции показывает потерю прежних полей.

Зелёный прогон без зафиксированного соответствующего red proof не закрывает AC.

Риски

• Backend test маскирует результат успешным relay mock. Каждый submit проверяет и WebSocket response, и число/байты transport calls.
• TTL test становится flaky. Время передаётся через monkeypatch time.monotonic; ожидания и реальные таймеры запрещены.
• Новая probe снова попадает в finish(). Source/contract test фиксирует, что её развязка вызывает reportPageErrors() напрямую.
• Мутант ложится в одноимённый round-trip finish(). Anchor включает имя функции и уникальный соседний код; --check требует ровно одно совпадение.
• Тест manifest helper расходится с CLI. main() не дублирует ветку и вызывает экспортированную функцию непосредственно.
• Release mutation gate дорожает. Добавляются только адресные guards; backend/browser выполнение остаётся в существующих shard/time budgets.

Откат

Откат одного implementation-коммита удаляет новые тесты/probe/mutants и возвращает inline-сборку acceptance trace. Данные, API и пользовательская конфигурация не мигрируются. Откат безопасен для runtime, но снова оставляет три заявленных контракта без отрицательного доказательства.

Release-артефакты

• changelog RU/EN не меняется: пользовательское поведение не изменено;
• golden, docs screenshots, performance profile и security artefact не нужны;
• документ код-ревью обязан перечислить red proof для AC1–AC7;
• issue остаётся открытым в S8-merged до пакетного закрытия при выпуске беты.

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

• Текущая production-реализация трёх контрактов верна; задача чинит их доказательства. Красный тест, выявивший реальную ошибку поведения, расширением этой задачи автоматически не считается.
• Для backend mutation guard используется действующий scripts/backend-test-guard.mjs, чтобы запускать один именованный HA-тест.
• Сохранение произвольных совместимых полей прежнего acceptance trace важнее жёсткого перечисления только declared/witnesses/floor: fingerprint-only refresh не является новой приёмкой и не должен переписывать её историю.
• Названия probe и mutant IDs технические и могут быть уточнены при реализации без изменения AC.