diff --git a/docs/reviews/SPEC-REVIEW-331-r2.md b/docs/reviews/SPEC-REVIEW-331-r2.md new file mode 100644 index 00000000..7c9af300 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-331-r2.md @@ -0,0 +1,180 @@ +# SPEC-REVIEW-331-r2 + +Issue: #331 — «Ограничения стыков (#329): пограничная точность даёт ложные +отказы и невидимые дубли» +ТЗ: `docs/specs/331-junction-limit-precision.md` +Материал раунда: ревизия 2, SHA `2d703543` (issue-комментарий автора называет +этот SHA явно). +Предыдущий раунд: r1, вердикт «красный», документ +`docs/reviews/SPEC-REVIEW-331-r1.md`, материал на SHA `60e125e9`. +Трек: полный (не `small`) — не изменился, дифф r1→r2 не расширяет и не +сужает трек: тот же файл, только правки нормативных пунктов и AC. +Заход: r2 · блокирующих циклов израсходовано 1 из 4 (израсходован r1, r2 +жёлтый бюджет не тратит по правилу «зелёный не тратит», но зелёного нет — +см. вердикт). + +## Скоуп разбора (дельта, не заново) + +Согласно инструкции по дельте: дифф `git diff 60e125e9..2d703543 -- +docs/specs/331-junction-limit-precision.md` — предмет этого раунда. Дельта +не локальна в смысле «одна строка»: она переписывает нормативный текст трёх +из шести пунктов §2 (2.1, 2.3, 2.6) и правит §1, §3, AC1, AC3, §6/Release — +то есть ревизия закрывает пять из пяти находок (H1, M1–M4) плюс L1 +содержательными правками, а не декларацией. Это оправдывает не полный +повторный разбор с нуля, но полную проверку каждой правки по существу +(арифметика, согласованность с остальным документом, согласованность +AC↔нормативный пункт) — именно так и сделано ниже. Не трогавшиеся куски +(§2.2, §2.4, §2.5, AC2, AC4, AC5, §5, i18n/touch) — унаследованы из r1 без +повторной проверки, см. раздел ниже. + +## Как проверялось + +1. `docs/SCOPE.md` — не перечитывался заново (не задет дельтой); вывод r1 + («соответствует J6») наследуется. +2. `PROCESS.md` §2.4/§2.9/§7.1/§7.2 — перечитаны для формата документа и + verdict-строки этого раунда. +3. Тело issue #331 и оба исходных комментария (уже читаны в r1) плюс два + новых комментария: вердикт r1 (`claude`, красный) и хендофф автора о + ревизии 2 — оба через `gh issue view 331 --comments`. +4. `git diff 60e125e9..2d703543 -- docs/specs/331-junction-limit-precision.md` + — построчно, каждая правка сверена с текстом находки, которую она + заявляет закрывающей. +5. Для проверки арифметики и терминологии H1/M1 — код: `src/ + coordinate-canonicalization.ts` и `custom_components/houseplan/ + coordinate_canonicalization.py` (формула `sign(v)·floor(|v|·factor+0.5)/ + factor` подтверждена побайтово в обоих файлах — не изобретена заново). +6. Для проверки M3 (семантика «сумма компоненты» вместо «максимальной + ветви») — текущая реализация `collinearRunLengthUnits` (`src/ + junction-limits.ts:133-158`) и `checkNodes`/П1 (`:63-96`), чтобы оценить, + действительно ли переопределение алгоритма меняет наблюдаемое поведение + на легитимных (не патологических) входах. +7. Для M4 — существование `docs/USER-GUIDE.md` (английское зеркало) рядом с + `.ru.md`, и раздел «Ограничения стыков стен» (`docs/USER-GUIDE.ru.md:420- + 444`) как целевое место правки. +8. i18n: `src/i18n/ru.json:590` / `en.json:590` (`junction.limit_distance`) + — сверка иллюстративной фразы §1 с реальным текстом тоста (не выдумана). + +Гейты `typecheck`/`test`/`build`/`check-docs`/инварианты модели не гонялись: +дифф раунда — исключительно `docs/specs/331-*.md` (класс C, стадия `spec`). +Продуктового кода в диффе по-прежнему нет — §8/§10.2 PROCESS.md к спек-ревью +не применяются. Смоки/golden/backend-pytest/perf-профили — не применимы по +той же причине (нет исполняемого изменения). + +## Закрытие раунда r1 + +| Находка r1 | Чем закрыта в r2 | Где это видно | +|---|---|---| +| **H1** — квантование ключа через нативный `round`, риск разъезда TS/Python на .5-тике | §2.1 переписан на явную формулу `sign(v)·floor(|v|·1e7+0.5)/1e7` с ссылкой на `coordinate-canonicalization`; AC1 добавляет прямой юнит на `v=2.5e-7` | `docs/specs/331-…md:43-51`, AC1 `:127-128`. Формула сверена побайтово с `src/coordinate-canonicalization.ts:47-50` и `.py:20-31` — совпадает. Для `v=2.5e-7`: `floor(2.5+0.5)=3` в обеих реализациях (не `Math.round`/банковское округление) → один ключ `3e-7`. **Закрыто.** | +| **M1** — пример AC1 (`−5.1e-8`/`5.1e-8`) не проходит заявленный порог `≤1e-7` (реальная дистанция 1.02e-7) | Порог инцидентности поднят до `2e-7` по сырым координатам; текст AC1 сам приводит арифметику `1.02e-7 ≤ 2e-7` | `:53-55`, AC1 `:125-127`. Проверено арифметически: `1.02e-7 < 2e-7` — верно. Верхняя граница порога (2e-7) остаётся на четыре порядка меньше реального минимума правил (5 см ≈ 4e-4), запаса достаточно, чтобы не поглотить настоящие «слишком близко». **Закрыто.** | +| **M2** — §2.6 сужает `except` не различая `previous`/`candidate`; риск нового fail-closed на несвязанной стороне | §2.6 переписан: кандидат — узкий except (fail-closed), `previous` — прежний широкий фолбэк (fail-open) явно, симметрично §2.5 | `:98-105`. Нормативный текст закрыт. **AC6 не тронут диффом** (см. новую находку M-r2-1 ниже) — тестовый критерий не различает стороны, значит асимметрия, которую только что ввёл §2.6, не имеет однозначного доказательства. **Закрыто частично.** | +| **M3** — максимальная ветвь ищется DFS-перебором вариантов, сложность `2^K..3^K` по числу развилок, не застрахована стресс-тестом | §2.3 переписан: вместо перебора вариантов — обход по рёбрам с visited-множеством, каждый атом входит в прогон не более раза, `O(E)` независимо от числа развилок; AC3 добавляет кейс «100 развилок подряд — линейное время» | `:69-79`, AC3 `:132-137`. Механизм действительно `O(E)` (посещение атома один раз гарантировано visited-набором) — линейность по числу развилок доказана конструкцией, а не тестом отдельно, но AC3 добавляет и прямую проверку. Проверено дополнительно: любой вход, где в одном узле есть ≥2 коллинеарных продолжения одной толщины («развилка» в терминах §2.3), по построению даёт две почти сонаправленные стены в одном узле — угол между ними < 15° и попадает под П1 независимо от версии этого пункта (порог 15° в `MIN_JUNCTION_ANGLE_DEG`, `src/junction-limits.ts:15`, не относится к правкам этой задачи). Значит запись с «развилкой» и так отклоняется П1 до того, как её увидит П3 — смена семантики «максимум пути» → «сумма компоненты связности» не открывает новый способ пропустить нелегитимную запись. **Закрыто.** (Остаточная стилистическая нестыковка — см. Low L2 ниже.) | +| **M4** — Release не называет `docs/USER-GUIDE.ru.md` | Release-абзац дополнен: «`docs/USER-GUIDE.ru.md` и `.md` — раздел «Ограничения стыков стен» дополняется предложением о тосте `junction.limit_check_failed`» | `:171-174`. Место правки (раздел «Ограничения стыков стен», `docs/USER-GUIDE.ru.md:420-444`) существует и является верным целевым разделом; английское зеркало `docs/USER-GUIDE.md` существует. **Закрыто.** | +| **L1** — §1 не даёт открытой пользовательской фразы | §1 открывается сценарием от первого лица пользователя («заканчивает ресайз… получает отказ… хотя ничего не нарушал») до технического перечня | `:12-15`. Иллюстративная фраза тоста сверена с реальным `junction.limit_distance` (`src/i18n/ru.json:590`) — не выдуманный текст, обоснованный парафраз. **Закрыто.** | + +## Находки + +### Medium (в скоупе, чинится в этом же ТЗ) + +**M-r2-1 (наследник M2, закрыт частично). AC6 не различает сторону +(`previous`/`candidate`) — новая асимметрия §2.6 введена нормативно, но не +имеет однозначного теста.** + +`docs/specs/331-junction-limit-precision.md` — §2.6 (`:96-105`) в этой +редакции чётко разводит поведение `_migrated_spaces` по сторонам: для +кандидата TypeError/RecursionError теперь всплывают честной ошибкой WS +(fail-closed), для `previous` — по-прежнему тихий широкий фолбэк «нет базы» +(fail-open). Это ровно то различение, которое требовал r1-M2. + +Но AC6 (`:144-146`) — байт-в-байт тот же текст, что был на SHA `60e125e9` +(до правки; сверено `git show 60e125e9:...` против текущего файла): «Битая +форма документа (TypeError в миграции) — честная ошибка WS, не тихое +«нарушений нет»; `WallSegmentMigrationError` — прежний фолбэк «нет базы». +Backend-юниты.» Ни слова о том, к какой стороне относится «битая форма +документа» — а именно этот вопрос был явно поставлен в r1-M2 («AC6 не +говорит, к какой стороне… относится тестовый документ… — без этого AC не +проверяем однозначно») и остаётся без ответа. + +Реализация по такому AC пройдёт формально, даже если асимметрия перепутана +местами (например, если TypeError на `previous` тоже станет честной ошибкой +WS — регресс именно того симптома, ради которого заведена вся задача, +P1, #316/#319) или не введена вовсе (оба случая ловятся широким фолбэком) — +единственный тест, который отличил бы эти реализации друг от друга, не +описан. + +Правка: AC6 должен явно завести два случая — «TypeError при миграции +КАНДИДАТА → честная ошибка WS» и «TypeError при миграции `previous` → +фолбэк «нет базы», запись не заблокирована» — по образцу того, как AC5 уже +различает сторону («исключение в проверке кандидата… исключение на +baseline…»). + +### Low + +**L2. §6 «Риски» (2) описывает механизм, которого §2.3 больше не содержит +(«максимальная ветвь»), хотя §2.3 в этой же редакции заменён на «сумму +компоненты связности».** + +`:165-168` (не тронуто диффом r1→r2): «(2) выбор максимальной ветви может +легализовать ранее отклонявшиеся конфигурации…». После правки §2.3 (`:69- +79`) алгоритм больше не выбирает «максимальную ветвь» — он суммирует ВСЮ +коллинеарную компоненту связности. Общий вывод риска (2) («может +легализовать») остаётся верным (сумма ≥ максимум одной ветви, то есть ещё +менее строго), но конкретное описание механизма устарело и не совпадает с +текстом §2.3 в этой же ревизии — при повторном чтении документа это читается +как рассинхрон между разделами. Не блокирует (сам вывод риска верен, M3 +закрыт по существу — см. таблицу выше); достаточно одной правки слова +«ветвь» → «компонента» при следующей правке файла. + +## Унаследовано из r1 (без повторной проверки) + +Ниже — то, что r1 (`docs/reviews/SPEC-REVIEW-331-r1.md`, материал @ +`60e125e9`) проверил и признал корректным, и что дельта r1→r2 не затрагивает +(ни один символ в этих разделах не изменился между `60e125e9` и `2d703543`): + +- Скоуп/не-скоуп: сёстры #333/#339 вне скоупа, §3 границы, П1–П5 пороги не + меняются — соответствие `docs/SCOPE.md` J6. +- §2.2 (снятие фильтра `degrees > EPS`) и AC2: не создаёт ложных + срабатываний на легитимной прямой стене/T-стыке. +- §2.4 (коллинеарность к базе цепочки) и AC4: числа внутренне согласованы. +- §2.5 (fail-closed кандидата) и AC5: согласован с прецедентом #278, канал + тоста и ключ i18n названы. +- Структура «один AC на нормативный пункт + AC7 на паритет/регресс». +- i18n: один новый ключ, `en+ru` — формат совпадает с существующими + `junction.limit_*`. +- Touch: не задет, обоснованно. +- Обязательство обновить `docs/specs/329-junction-limits.md` §2 — учтено, + не заводит параллельного источника истины. + +## Что проверено и признано корректным (эта ревизия) + +- H1, M1, M3, M4, L1 закрыты содержательно, не декларативно — арифметика, + формулы и ссылки на код проверены, а не приняты на слово автора. +- Новый текст §1 не вводит поведения, которого нет ни в одном документе: + иллюстративная фраза тоста сверена с `src/i18n/ru.json:590`. +- M3: явно проверено, что смена семантики «максимальная ветвь» → «сумма + компоненты» не открывает новый путь пропустить нелегитимную запись, + потому что любая входная конфигурация с «развилкой» одновременно и + обязательно нарушает П1 (угол между двумя почти сонаправленными + продолжениями в одном узле физически меньше 15°) — этот вывод не назван в + самом ТЗ, но проверяем по коду и не противоречит документу. + +## Чего не проверял + +- Всё, что унаследовано из r1 (список выше) — не перепроверялось повторно. +- Производительность фактическая — по-прежнему нет кода, только текстовая + гарантия §2.3/AC3 (линейность по построению правдоподобна, но не + измерена). +- Backend-паритет численно — нет кода для запуска + `test_parity_with_the_frontend_checks`. +- `docs/CONFIG-COMPATIBILITY.md` — не тронут дельтой и не должен быть. +- Собственно реализация AC6 с учётом M-r2-1 — по определению этой находки: + пока сам критерий не различает стороны, доказать реализацию по нему + нельзя. + +## Вердикт + +Medium M-r2-1 — в скоупе задачи (наследник не полностью закрытого r1-M2), +чинится точечной правкой AC6 без нового цикла продуктового анализа. High +нет. Low L2 — на усмотрение автора, можно закрыть заодно с M-r2-1 или +отдельной запиской. + +`Вердикт: жёлтый · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 1 → в задаче · Документ: <публикуется шагом публикации>`