houseplan-card/docs/reviews/SPEC-REVIEW-197-r3.md

# SPEC-REVIEW-197-r3

- **Issue:** https://github.com/Matysh/houseplan-card/issues/197
- **ТЗ под ревью:** [`docs/specs/197-junction-patch-fail-dark.md`](https://github.com/Matysh/houseplan-card/blob/issue/197-junction-patch-fail-dark/docs/specs/197-junction-patch-fail-dark.md)
  (коммит `b203e8f`, «r2» по внутренней редакции автора), обычный трек —
  не `small`/`trivial`
- **Роль:** ревьюер ТЗ (не автор), этап `S4-spec-review`
- **Трек:** обычный, лимит циклов ревью ТЗ — 4 (§4 PROCESS.md)
- **Цикл:** r3/4 (эта сессия проверяет редакцию, отправленную автором в ответ
  на [`SPEC-REVIEW-197-r1.md`](https://github.com/Matysh/houseplan-card/blob/issue/197-junction-patch-fail-dark/docs/reviews/SPEC-REVIEW-197-r1.md))

## Скоуп ревью

ТЗ #197 предлагает исправление: один вырожденный `virtualJunctionPatches()`
patch (IEEE-754 шум в вершинах митры на виртуальном T-стыке) обнуляет весь
результат `wallBodiesGeometry()`, поскольку цикл добавления junction-патчей
(`src/wall-thickness.ts:1760-1761`) — в отличие от room-ring и wall-edge циклов
рядом — не изолирует отказ одного элемента. Решение: численная стабилизация
координат patch + транзакционный per-patch fallback, без изменения
persisted-схемы, i18n, touch-контракта, оптимизатора и без правки #198/#199.

r1 вернул ТЗ красным с единственной High-находкой: центральное фактическое
утверждение §3 («fixture из issue → ровно один patch → `null`») не
воспроизводилось независимым исполнением того самого вызова, который ТЗ
описывало как «подтверждено исполнением» — из-за не проговорённого координатного
контракта `WallEntry.a/b` (persisted config coordinates, а не render-scaled).
Ревью этой сессии — целиком про то, снимает ли текущая редакция именно эту
находку, а не про повторный обход всего ТЗ: раздел `## 5–10, 13–16` не менялся
между `fe7b28f` и `b203e8f` (`git diff fe7b28f b203e8f -- docs/specs/197-junction-patch-fail-dark.md`
— правки ограничены новым §0, дополнениями в §3 и переформулировкой AC1/AC2), и
все находки r1 «что проверено и корректно» по этим разделам остаются в силе без
повторной проверки.

Не в скоупе ревью: продуктовый код. На ветке `issue/197-junction-patch-fail-dark`
всё ещё нет коммитов класса A — только документация (ТЗ, документы ревью).
Гейты (`typecheck`/`test`/`build`) не прогонялись — на этапе ревью ТЗ
продуктового кода не существует, что вне скоупа этапа (PROCESS.md §2.4/§8).

## Как проверялось

1. Прочитан ответ автора на r1 (issue-комментарий и новый §0 ТЗ) и весь diff
   `fe7b28f..b203e8f` для `docs/specs/197-junction-patch-fail-dark.md`
   (`git diff fe7b28f b203e8f -- docs/specs/197-junction-patch-fail-dark.md`) —
   изменения ограничены §0 (новый), дополнением к §3 (исполняемый reproducer,
   разбор #201) и переформулировкой AC1/AC2; остальные 12 из 17 разделов
   ТЗ побитово идентичны версии, уже прочитанной в r1.
2. **Независимое повторение исправленного reproducer.** Собран `test-build/`
   (`npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs`, зелёно).
   Выполнен ровно тот код из §3 ТЗ: `rooms[].poly` и `open_spans` масштабированы
   через `NORM_W`, `walls[].a/b` переданы **без** предварительного умножения
   (`structuredClone(fixture.walls)`), fixture взят программно из тела issue
   (`gh issue view 197 --json body`, тот же JSON-блок). Результат:
   `counts: [8, 25, 3]`, `nodeCm: [20, 20, 20, 22, 20]` (узел, где патч
   строится, содержит `20`, как заявлено), `failed: true` — `wallBodiesGeometry()`
   вернул `null` на `HEAD` (`b203e8f`, `src/` идентичен `19e92e0`). **High-1 из
   r1 воспроизведён устранённым** — ровно тем способом, что описывает §3.
3. **Проверка patch-list напрямую.** Временно экспортирован (только в
   сгенерированном `test-build/wall-thickness.js`, не в `src/`)
   `virtualJunctionPatches()` без изменения тела и вызван с тем же
   подготовленным fixture. Результат — **ровно один** patch с вершинами
   `[[620.8333333333334,550],[612.5,550],[612.5000000000001,541.6666666666665],
   [620.8333333333334,541.6666666666666]]` — **побайтно совпадает** с числами,
   приведёнными в §3 ТЗ.
4. **Проверка отделения #201.** Прочитан `src/wall-thickness.ts:1549-1607`
   (`virtualJunctionPatches`): функция строит `unique` map через
   `wallIntervals(...)`, `thicknessCmAt()` не вызывается вовсе — подтверждает
   заявление §0/§3 буквально. Дополнительно узел `y=550` в исполненном
   `nodeCm` содержит только ненулевые толщины (`20, 20, 20, 22, 20`) — при живом
   дефекте #201 (`thicknessCmAt() → 0`) он не проявляется на пути, которым
   реально идёт `virtualJunctionPatches()`.
5. **Проверка дополнительных диагностических утверждений §3** — исполнено
   отдельными вариациями того же скрипта:
   - без `open_spans` (отключает `virtualJunctionPatches()`, т.к. функция
     возвращает `[]` при пустом `openCuts`) → `wallBodiesGeometry()` **не**
     `null` — подтверждает «без open cuts валидная geometry»;
   - удаление 15-см wall-записи (микро-интервал из #198) при прочем неизменном
     наборе → результат остаётся `null` — подтверждает «удаление
     микро-интервала не лечит», то есть #198 не является причиной;
   - слияние 15-см записи с соседней 22-см (сдвиг `a` соседней записи на начало
     удалённой) → результат **не** `null` (валидная geometry) — **не
     совпадает** с формулировкой §3 «слияние… тоже оставляет `null`»
     (см. находку Low-1). Затронутый узел `y≈0.346` физически далёк от падающего
     узла `y=550`; расхождение не задевает AC1/AC2 и не меняет решение по
     scope/#198.
   - округление вершин patch до `1e-9` render-unit перед `union()`
     (сохранён неизменным весь остальной алгоритм, правка только в
     сгенерированном `test-build`, не в `src/`) → `wallBodiesGeometry()`
     **не** `null`; площадь результата (`geometryArea`, shoelace по всем
     кольцам) — `124991.31944444453`.
   - тот же fixture, но патч **пропущен** целиком (union бросает исключение —
     без округления — и код просто продолжает со старым `body`, не
     переприсваивая) → тоже валидная geometry, площадь **той же самой**
     величины `124991.31944444453` — подтверждает буквально заявление §3
     «пропуск и успешный стабилизированный union… дают одинаковую площадь»
     (то же самое, что закреплено как предположение §17.5).
6. Перечитаны §7–§17 ТЗ на предмет того, не появилась ли новая догадка,
   выданная за факт, вместе с добавленным текстом §0/§3 — не появилась: новые
   утверждения либо подтверждены исполнением (см. п.2–5), либо, для случая
   Low-1, являются иллюстративной деталью причинного разбора вне AC.
7. Проверено, что новая ссылка `#201` в шапке ТЗ и её описание в §0 согласуются
   с фактическим issue #201 (`gh issue view 201`) — тип/скоуп/статус
   соответствуют тому, как их описывает ТЗ.
8. AC1/AC2 в новой формулировке прочитаны на однозначность: обе теперь прямо
   отсылают к исполняемому reproducer §3 и указывают точные числа (8/25/3,
   20-см intervals, координаты patch) — в отличие от r1, где текст допускал
   неоднозначную интерпретацию масштабирования `walls[].a/b`.

## Находки

### Low-1 — одно диагностическое утверждение §3 не воспроизводится буквально при разумной интерпретации операции «слияние»

**Файл:** `docs/specs/197-junction-patch-fail-dark.md`, §3, абзац
«Дополнительные исполняемые проверки» — предложение «слияние микро-интервала с
соседним участком 22 см оставляет результат `null`».

**Что заявлено.** В числе проверок, отделяющих истинную причину (float-шум
митры на узле `y=550`) от смежных находок, ТЗ утверждает, что слияние
15-см wall-записи (`key: "0.887500,0.345833@0.0000"`, микро-интервал из #198)
с соседней 22-см записью (`key: "0.933333,0.345833@0.0000"`) **не** устраняет
крах — результат остаётся `null`.

**Что получено при независимом исполнении.** При разумной трактовке «слияния»
(удаление 15-см wall-записи, расширение соседней 22-см записи так, чтобы её
`a` совпал с началом удалённой — то есть физическая длина участка сохраняется,
запись становится одной вместо двух) `wallBodiesGeometry()` на этом входе
возвращает **не** `null`, а валидную geometry. Узел, к которому относится
слияние (`y ≈ 0.346`), не совпадает с падающим узлом (`y = 550`) — то есть
слияние в другом месте плана меняет результат в узле, который ТЗ не трогает
напрямую; это согласуется с общим тезисом ТЗ о чувствительности `union()` к
порядку и числу вызовов, но означает, что конкретная фраза «оставляет `null`»
не буквально верна для по крайней мере одного разумного прочтения «слияния».

**Почему это не блокирует.** Утверждение не привязано к AC1–AC11: оно —
иллюстративный аргумент, показывающий, что #198 (микро-интервал) не является
причиной #197, и этот аргумент уже независимо подтверждён другим, точно
описанным тестом того же абзаца («удаление 15-см записи оставляет `null`»,
воспроизведено буквально, см. «Как проверялось», п.5). Решение вынести #198 из
скоупа не опирается только на фразу про «слияние» и не меняется от её
уточнения. Ни один AC не использует формулировку «слияние» как критерий
доказательства.

**Рекомендация.** Low, не блокирует. Снимаю запись самостоятельно: автор может
либо удалить эту конкретную фразу (аргумент о «удалении» уже достаточен и
воспроизведён точно), либо заменить её на точный код операции, если хочет
сохранить оба довода. Ни то, ни другое не меняет AC, scope или вердикт.

## Что проверено и корректно

- **High-1 из r1 закрыт исполнением, а не словами.** Новый §0 не просто
  возражает, а вставляет ровно исполняемый reproducer (программно извлекающий
  fixture из тела issue), и этот код при независимом запуске на HEAD этой
  ветки даёт заявленные числа буквально: `[8, 25, 3]`, узел содержит `20`,
  `failed: true`. Координатный контракт (`walls[].a/b` — persisted config
  coordinates, `entrySpan()` сам умножает на `coordScale`) подтверждён чтением
  `src/wall-thickness.ts:124-129` — не декларация, а факт кода.
- **Ровно один patch с точными вершинами.** Прямой вызов
  `virtualJunctionPatches()` на подготовленном fixture даёт один patch,
  совпадающий с приведёнными в §3 числами вплоть до последнего знака.
- **Разделение с #201 подтверждено чтением и исполнением.**
  `virtualJunctionPatches()` использует `wallIntervals()`, не `thicknessCmAt()`
  — единственный путь, которым #201 мог бы влиять, физически не существует в
  этой функции; на исполненном узле все толщины ненулевые.
- **Техническая состоятельность предлагаемого решения.** Проверена
  экспериментально (round-трюк на вершинах patch перед `union`) — устраняет
  крах на этом самом fixture и даёт ту же площадь geometry, что и вариант
  «пропустить упавший patch, оставить предыдущий body» (§17.5 — предположение,
  подтверждено численно, не только логически). Значит контракт §7.1/§7.2 и
  архитектурное решение §8 не являются недостижимой абстракцией — они реализуемы
  на реальных данных этой задачи.
- **AC1/AC2 однозначны и доказуемы.** Переформулировка убирает ту двусмысленность,
  которая в r1 не позволяла независимо повторить сценарий: числа, порядок
  масштабирования и точный reproducer теперь в тексте ТЗ, а не только в голове
  автора.
- **Оставшиеся разделы ТЗ (не тронутые r2) остаются в силе.** Полнота
  обязательных разделов §7.1 PROCESS.md, продуктовый контракт со ссылкой на
  `docs/specs/141-wall-junctions.md`, границы с #198/#199, трек (обычный),
  технические предположения §17, i18n/touch/миграция/откат/release-артефакты —
  всё это не менялось между r1 и r2 и было проверено в
  `SPEC-REVIEW-197-r1.md`; повторная проверка этой сессией подтверждает, что
  добавленный текст не противоречит и не меняет эти разделы.
- **Открытых продуктовых вопросов к владельцу нет.** Единственная находка этой
  сессии (Low-1) — техническая деталь диагностического текста, не продуктовый
  вопрос («что видит пользователь» и «объём видимых изменений» здесь не
  затрагиваются).

## Чего не проверял

- **AC3–AC11 на уровне реального прогона.** Не запускал `npm test`/`npm run
  build`/browser smoke — на этапе ревью ТЗ продуктового кода нет (ветка несёт
  только документацию), прогон гейтов реализации вне скоупа этапа
  (PROCESS.md §2.4/§8). Формулировки этих AC не менялись между r1 и r2 и уже
  оценивались в `SPEC-REVIEW-197-r1.md` на однозначность текста.
- **Полный causal chain и корректность самого #201** — не проверялся заново;
  эта сессия только подтвердила, что #201 не влияет на путь
  `virtualJunctionPatches()`, а не то, чем именно вызван сам `thicknessCmAt() → 0`
  (это аналитика #201, отдельная задача).
- **Матрица численных вариантов AC2 (`x`, `x ± ulp`, permutation) в полном
  объёме** — воспроизведён только сам факт «один patch с этими вершинами» и
  «округление устраняет крах», не вся заявленная матрица инвариантности
  (перестановка записей, направление сегментов) — она относится к реализации и
  будет доказана unit-тестом AC5, не спецификацией.
- **golden/визуальная сцена (AC9), performance (§13)** — не оценивались: на
  этапе ТЗ артефактов не существует, и раздел не менялся относительно r1.

## Вердикт

Вердикт: зелёный · цикл r3/4 · High: 0 · Medium: 0 · Low: 1 (Low-1, снята
записью в этом документе, не требует issue)

**Зелёный.** r2 закрывает единственную High-находку r1 не декларативно, а
исполняемым reproducer, который я независимо повторил и получил числа,
буквально совпадающие с заявленными в §3 и AC1/AC2 — включая точные вершины
единственного patch и byte-level совпадение результата `null`/не-`null`.
Разделение с #201 подтверждено и чтением кода, и исполнением. Техническая
состоятельность предложенного решения (численная стабилизация ⇒ тот же
результат, что и локальный skip) проверена экспериментально на этом самом
fixture. Единственная находка (Low-1) — неточность одной иллюстративной фразы
в диагностическом тексте §3, не привязанной к AC и не влияющей на scope;
снимаю её без issue, с рекомендацией автору поправить формулировку в следующей
редакции документации (не блокирует переход в `S5-ready`).