From 72275de56737812ac8bb0acc6ba84fa4052c5be7 Mon Sep 17 00:00:00 2001 From: Sergey Matyunin Date: Thu, 20 Aug 2026 13:43:20 +0300 Subject: [PATCH] docs: add risk analysis for glow geometry Issue: #218 User-Visible: no --- docs/specs/218-glow-floor-geometry.md | 46 ++++++++++++++++++++------- 1 file changed, 34 insertions(+), 12 deletions(-) diff --git a/docs/specs/218-glow-floor-geometry.md b/docs/specs/218-glow-floor-geometry.md index 58c9410c..f4225eb2 100644 --- a/docs/specs/218-glow-floor-geometry.md +++ b/docs/specs/218-glow-floor-geometry.md @@ -219,11 +219,30 @@ saved room coordinates (immutable) - warning redacted согласно §9; - fail-dark security boundary не ослабляется. -## 15. Acceptance criteria +## 15. Риски -1. **AC1 — ULP union.** Два прямоугольника с общей гранью, отличающейся на один - ULP, после `unionBodies()` дают валидную объединённую геометрию. - **Доказательство:** unit, красный при mutant без normalization. +| Риск | Последствие | Снижение риска и доказательство | +|---|---|---| +| Квантование находится в общем `unionBodies()`, а не только в Glow | Невидимый ранее сдвиг кладки, clean floor или `physicalBodiesPath` у соседнего потребителя | Quantum остаётся на много порядков меньше физической и экранной точности; unit покрывает площадь, вершины и input immutability, а существующие wall/floor/physical-geometry tests и golden обязаны остаться зелёными | +| Legacy-план содержит реально перекрывающиеся комнаты | На fallback покомнатные fragments могут дать иное evenodd-покрытие, чем общий merged path | Fast path с общим union сохраняется; fallback не склеивает перекрывающиеся fragments в один evenodd path без нормализации покрытия; отдельная overlap-fixture сравнивает площадь/coverage с общим union | +| Наблюдение `0 из 6` для Glow-base имеет другую причину | Основной баг будет исправлен, но вторичное наблюдение останется без объяснения | Targeted smoke фиксирует результат; при иной причине в implementation evidence прямо записывается отрицательный результат и создаётся отдельный issue только после подтверждения пользовательской проблемы | +| Полный mutation gate слишком дорог для одного review-цикла | Реализация задержится либо мутанты будут заявлены без доказательства | Перед S7 обязательны `--check` и целевые мутанты #218; полный реестр остаётся предрелизным гейтом по PROCESS | +| Повторный render одной битой комнаты заспамит консоль или раздует dedupe-set | Диагностика сама станет performance/memory-регрессией | Warning дедуплицируется по ограниченному space/fingerprint/room lifecycle, повторный render проверяется console-capture тестом, размер структуры проверяется source review | +| Слишком широкий fallback случайно вернёт raw visibility fan | Свет протечёт за пределы дома или через кладку | Empty floor, source-in-masonry, outside-floor и total-failure tests остаются строгими fail-dark; existing `smoke_glow_fail_dark` не изменяется ради прохождения задачи | + +Откат §19 безопасен для данных и является последней мерой, если соседний +boolean-потребитель меняет видимую геометрию либо performance выходит за +действующий Glow budget. + +## 16. Acceptance criteria + +1. **AC1 — ULP normalization.** Два прямоугольника с общей гранью, + отличающейся на один ULP, после `unionBodies()` дают одно тело, а + normalization-specific assertion подтверждает канонические координаты без + мутации входа. Простая пара является проверкой контракта normalization, но + не обязана падать на старом polyclip сама по себе. + **Доказательство:** unit; assertion координат красный при mutant без + normalization. 2. **AC2 — реальная regression fixture.** Анонимизированная шестикомнатная fixture с точными проблемными парами координат даёт непустой `lit` и непустой DOM clipPath включённого источника. **Доказательство:** unit + @@ -255,9 +274,9 @@ saved room coordinates (immutable) generated bundles и screenshot/golden fingerprints актуальны. **Доказательство:** docs check, build parity и review diff. -## 16. План автотестов +## 17. План автотестов -### 16.1. Цикл реализации +### 17.1. Цикл реализации ```bash npm run typecheck @@ -274,7 +293,7 @@ Unit matrix: - input immutability, repeatability, reversed/permuted bodies; - structured callback и diagnostic dedupe. -### 16.2. Targeted smoke перед S7 +### 17.2. Targeted smoke перед S7 ```bash node demo/smoke_glow.mjs @@ -285,7 +304,7 @@ node demo/smoke_glow_fail_dark.mjs Добавляется отдельный узкий smoke либо детерминированное расширение `smoke_glow` для ULP-fixture, DOM clipPath, Glow-base и console warning. -### 16.3. Mutation gate +### 17.3. Mutation gate | id | Мутация | Обязанный guard | |---|---|---| @@ -297,7 +316,7 @@ node demo/smoke_glow_fail_dark.mjs Перед S7 выполняются `node scripts/mutation-gate.mjs --check` и целевые мутанты, если их runtime укладывается в локальный review gate. -### 16.4. Golden и предрелиз +### 17.4. Golden и предрелиз Golden verify выполняется на существующих Glow-сценах: валидные планы не должны получить видимый raster diff. Если для #218 добавляется новый visual scenario, @@ -305,7 +324,7 @@ Golden verify выполняется на существующих Glow-сцен полному Linux CI artifact перед бетой. Полный smoke/golden/performance — предрелизный гейт по PROCESS, не цикл реализации. -## 17. Release-артефакты +## 18. Release-артефакты В user-visible implementation commit обязательны: @@ -318,13 +337,13 @@ Golden verify выполняется на существующих Glow-сцен User Guide не меняется: настройки и пользовательский сценарий остаются прежними. -## 18. Откат +## 19. Откат Откат выполняется одним user-visible implementation commit вместе с tests, bundles и changelog. Persisted rollback/migration не нужен. При откате вернётся старый полный fail-dark, но сохранённые планы останутся совместимыми. -## 19. Принятые предположения +## 20. Принятые предположения Можно свободно изменить на ревью ТЗ без вопроса владельцу: @@ -335,3 +354,6 @@ bundles и changelog. Persisted rollback/migration не нужен. При от 4. приватный реальный экспорт не коммитится — только минимальная геометрия с сохранёнными проблемными double-значениями; 5. наблюдение Glow-base считается частью #218 только при той же корневой причине. +6. простая пара прямоугольников с 1 ULP на текущем polyclip уже объединяется; + поэтому красный до исправления regression gate строится на конфликтующей + многокомнатной топологии, а простая пара проверяет сам normalization contract.