houseplan-card/docs/reviews/SPEC-REVIEW-366-r1.md

# SPEC-REVIEW-366-r1

Issue: #366 — «Glow #20: движущиеся ворота на cover-сущности вызывают до ~100
пересчётов геометрии света за одно открытие»
Этап: ТЗ на ревью (S4-spec-review), лёгкий трек (`small`)
Заход: r1 · блокирующих циклов ревью ТЗ израсходовано 0 из 2 (лимит §4 для лёгкого трека)
Материал: тело issue #366 на момент ревью, дерево `dev` на SHA `f2e365726a6e28a9acf03b6a37b4d2099770229d`
Вердикт: **жёлтый**

## Скоуп

Проблема реальна и локализована точно: `openingLightStateSignature`
(`src/logic.ts:344-357`) строит ключ кэша барьеров света через
`amount.toFixed(3)`, а `amount` для проёма типа door/gate с cover-сущностью,
публикующей `current_position` в процентах, меняется на каждый процент хода
(`openingAmount()`, `src/logic.ts` ~§320-330). Каждое новое значение —
новая сигнатура → новый ключ LRU-пула (`_lightBarrierPool`,
`src/houseplan-card.ts:10368-10373`) → полный пересчёт `physicalBodyParts`
(`:10404-10412`) и вырезов (`:10383-10402`). Направление фикса (квантование
amount к сетке 0.05 в единственной точке сборки) — то, что уже описано в
проблеме автором issue как предпочтительный вариант; предложенный контракт
ему соответствует.

Задача действительно укладывается в `docs/SCOPE.md`: это не новая функция, а
починка перформанс-дефекта уже принятой в J1/J7 (живой обзор дома) отрисовки
Glow (#20), заметного на wall-планшете — ключевой поверхности для персон
«household members» / «guests». Small-трек обоснован: одна поверхность (вход
`_lightBarriers`), геометрические алгоритмы и миграции не тронуты, сложность
≤3 по формулировке автора выглядит правдоподобно.

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

Ревью ТЗ, код ещё не написан — сборка/тесты/смоки не прогонялись, это
предмет код-ревью. Материал: тело issue #366, `docs/SCOPE.md`, `AGENTS.md`,
`PROCESS.md`, `docs/LIGHT.md`, текущее состояние `src/logic.ts` и
`src/houseplan-card.ts` на `dev` (сверка описанных в ТЗ точек кода с
реальным деревом), issue #20 (контекст, откуда взялась Glow-через-дверь и
где лежит существующий смок), `test/logic.test.mjs` (существующие юниты на
`openingLightStateSignature`), `demo/smoke_glow.mjs`,
`demo/smoke_junction_limits.mjs`.

Что именно сверено по коду:

- `src/houseplan-card.ts:10352-10361` — единственное место, где строится
  `passageStates` и вызывается `this._openingAmt(o)`; результат этого поля
  (`amount`) действительно единолично питает и `openingLightStateSignature`
  (`:10362-10366`), и длину выреза через `openingLightApertureLength`
  (`:10383-10388`), и масштаб `lightPartitionCuts`/`scalePartitionOpeningCut`
  (`:10399-10402`). Формулировка К1 «единственная точка» подтверждена —
  квантование там действительно закрывает все три потребителя разом, а не
  только два названных в тексте ТЗ явно (сигнатура + длина выреза; про
  partition-cut ТЗ не говорит отдельно, но он неизбежно накрывается тем же
  местом).
- `src/houseplan-card.ts:12413-12420` (`_openingAmt`) — единственный
  производитель значения; другие потребители того же метода (рендер
  створки, `:8816`, `:12473`, `:12594`) действительно отдельные вызовы,
  которые контракт К1 не трогает — «анимация остаётся плавной» подтверждается.
- `src/houseplan-card.ts:9347-9357` (`_physicalBodiesR`, обычные стены) и
  `:7512-7522` (`_partitionOpeningCuts`, структурные вырезы) используют
  `_cfgEpoch`/конфиг напрямую, а не `_openingAmt` — эта часть геометрии вне
  скоупа задачи по факту кода, не только по декларации ТЗ.
- Формула квантования (`Math.round(clamp(x)/0.05)*0.05`) проверена в Node на
  примерах из AC1: `0→0`, `1→1` точно; `0.30` и `0.31` дают один и тот же
  float (`0.30000000000000004`); `0.33` даёт другой (`0.35000000000000003`);
  `NaN/-1/2` зажимаются в `0`/`0`/`1`. Все утверждения AC1 воспроизводимы,
  плавающая точка не портит проверяемые равенства.
- Полный диапазон 0..1 с шагом 0.05 даёт 21 узел — AC2 «≤21 сигнатура» и К2
  «≤21 пересчёт» математически согласованы.
- `test/logic.test.mjs` содержит текущие юниты на `openingLightStateSignature`
  с амплитудами `1`, `0.5`, `0`, `-2→0`, `2→1` — все совпадают с узлами сетки
  0.05, так что при добавлении квантования выше по стеку (не внутри самой
  функции) эти юниты не потребуют правки, как и утверждает AC3.
- `demo/smoke_glow.mjs:598-631` — существующий смок реально двигает
  `cover.glow_dynamic_door` через `current_position` и снимает скриншоты на
  позициях `0`, `50` (и `100` раньше по тексту, :360) — обе используемые
  доли (`0`, `0.5`, `1.0`) точно совпадают с узлами сетки 0.05, так что этот
  смок останется зелёным без правки ассертов — подтверждает AC4 фактически,
  но не по названию (см. находку M1 ниже).
- `demo/smoke_junction_limits.mjs` — прочитан начало файла: это гвард лимитов
  на запись стыков стен из #329 (проверка отказа сохранения, а не Glow и не
  `_openingAmt`). Связи с изменённым кодом по факту не нашёл — см. M1.
- `docs/LIGHT.md`, раздел «Caching» (строки 139-147) документирует сам факт
  сигнатуры по amount, но не даёт числового контракта точности — квантование
  формально его не нарушает, но раздел станет неполным без упоминания шага
  (см. M2).

## Находки

### M1 (Medium, в скоупе) — AC4 не называет проверяемое доказательство однозначно

`AC4` в ТЗ: «существующие смоки/golden #20 зелёные без правки ассертов (свип
прогоняется по делу: `smoke_door_glow*` — имя уточню по факту — плюс
`smoke_junction_limits` как полевой сосед)».

Файла `demo/smoke_door_glow*.mjs` не существует (`ls demo/smoke_*.mjs` —
проверено). Реальный тест, гоняющий именно cover-driven amount на дверь/ворота
через Glow — `demo/smoke_glow.mjs` (строки 598-631, двигает
`glow_dynamic_door` по `current_position`). Автор сам помечает имя как
неопределённое («уточню по факту») — это ровно то, что §2.5 DoR запрещает:
«у каждого [AC] указано, чем он доказывается» должно быть фактом на момент
ухода в `S5-ready`, а не обещанием уточнить позже. Второй названный смок,
`smoke_junction_limits`, судя по его коду (проверка отказа записи при
нарушении лимитов стыков стен, #329) не имеет видимой связи с
`_openingAmt`/Glow/`passageStates` — названо «полевым соседом» без указания,
какое именно совпадающее поведение он защищает.

**Почему в скоупе и чинится здесь:** правка ТЗ-текстовая, без нового решения
— заменить неопределённое имя на `demo/smoke_glow.mjs` (он уже доказывает
AC4 по факту, просто назван неверно) и либо обосновать релевантность
`smoke_junction_limits` конкретной связью, либо убрать его и заменить
результатом `node scripts/smoke-select.mjs --base origin/dev --head HEAD`,
когда код появится — эта команда есть в гейтах и предназначена ровно для
такого выбора.

### M2 (Medium, в скоупе) — визуальная деградация подана как факт, а не как решение с owner-видимостью

Контракт К2: «Визуальная цена: вырез света ступает по 5% длины проёма — на
реальных планах неразличимо». Это утверждение о том, что *увидит человек* —
ровно категория, которая по §7.1 адресуется владельцу («что человек видит»),
и ровно тот шаблон, который процесс называет «худшим видом дефекта»: догадка
о поведении, поданная как факт, без пометки «принято предположительно».

По существу: до этой правки амплитуда cover входит в сигнатуру с точностью
`toFixed(3)` (≈0.1%), т.е. вырез света визуально отслеживает движение почти
непрерывно (ценой ~1000 пересчётов на полный ход — это и есть баг). После
правки вырез будет физически перескакивать по 5%-ным узлам — не «то же самое
чуть грубее», а намеренный отказ от непрерывности в обмен на
производительность. Сам issue в разделе «Направление фикса» explicitly
называет квант и debounce равноценными альтернативами и не выбирает между
ними — то есть на момент постановки issue выбор ещё не был сделан
владельцем, а ТЗ на S3 сделало его молча.

Моя собственная оценка правдоподобия (не решение вместо владельца, а
основание для важности этой находки): проём двери/ворот на плане обычно
80–120 см, шаг 5% — это 4–6 см видимого скачка мягкого (blurred, см.
`docs/LIGHT.md:130-132`, кромка размыта на 1.5-3.5px) выреза на масштабе
комнаты — вероятно действительно малозаметно, особенно на фоне того, что
сейчас деградация проявляется как подёргивание всей карточки. Но это
«вероятно» — моя оценка, не зафиксированный факт, и распорядиться ею должен
или явный блок «принято предположительно, ревьюер/владелец может оспорить»,
или batched-вопрос владельцу с дефолтом «квант 0.05, деградация
незначительна» — вариант, который стоит владельцу секунд по формату §7.1.

**Почему Medium, не High:** обратимость полная (один revert, конфиг не
затронут), риск — эстетический на фиче, которую сам владелец в #20 назвал
`lowest priority` из-за её редкой применимости (contact-сенсор на *внутренней*
двери — редкость). Блокировать цикл ради этого нет оснований, но оставить
неотмеченной догадку как факт — тоже нельзя.

**Как чинится:** добавить в ТЗ явный блок вида «принято предположительно:
шаг 0.05 визуально неразличим на типовых проёмах 80–120 см; читатель волен
оспорить» — это удовлетворяет и `M2`, и общее требование «не бывает сложной
задачи без единого открытого вопроса» (сейчас в ТЗ такого блока нет вовсе).
Отдельный поход к владельцу не обязателен — цена ошибки низкая и обратимая,
достаточно того, чтобы предположение было промаркировано как предположение,
а не как решённый факт.

### L1 (Low, не блокирует) — строки в ТЗ отстали от `dev` на единицы

`houseplan-card.ts:10361` (в ТЗ) — на текущем `dev` это `:10360`
(`amount: this._openingAmt(o)`), аналогично `:10362`→фактически те же
строки описания сигнатуры сдвинуты на 1. Смысл описания точен (я нашёл
нужное место по цитате кода, не по номеру), правка не требуется для выхода
в разработку, но при финальном коммите номера стоит свериться заново — за
время ревью dev не двигался, но между S3 и S6 может.

### L2 (Low, не блокирует) — `docs/LIGHT.md` не назван в release-артефактах

Раздел «Caching» `docs/LIGHT.md:139-147` описывает сигнатуру по amount как
часть контракта подсистемы, но не удельную точность. Квантование меняет этот
контракт (сигнатура теперь дискретна по построению, а не «просто округлена
для ключа») и вводит намеренную визуальную ступенчатость — то, что канонический
документ подсистемы должен фиксировать по `AGENTS.md` («канонический документ
затронутой подсистемы»). ТЗ называет из release-артефактов только
changelog en+ru. Снимается легко: одна строка в LIGHT.md, тем же коммитом, не
блокирует переход в `S5-ready`; фиксирую как Low с правом автора либо
поправить, либо снять с запиской, если сочтёт достаточным changelog.

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

- Технический выбор единственной точки квантования (`passageStates`)
  реально исключает риск рассинхронизации «сигнатура vs геометрия» (принцип
  «одно число — один источник», §8 PROCESS.md) — geometry (`rlen`,
  partition-cut) и cache-key берут один и тот же квантованный `amount` из
  одного и того же объекта, поэтому исключён класс дефектов вида #234/#233.
- AC1 и AC2 математически корректны и воспроизводимы (проверено расчётом в
  Node, см. выше) — квантование к сетке 0.05 действительно даёт ≤21 узел,
  0 и 1 точные, тестовые примеры (`0.30`/`0.31` совпадают, `0.30`/`0.33`
  различны) подтверждаются без артефактов плавающей точки.
- AC3 (binary-двери байт-в-байт) обеспечен архитектурно: квантование
  применяется выше `openingLightStateSignature`, а не внутри неё, и
  существующие юниты, гоняющие функцию напрямую с сырыми amount, её не
  затрагивают.
- AC5 (мутационный тест «квант → identity» красит AC2) выполним: замена
  `quantizeOpeningLightAmount` на identity вернёт ~1000 различных сигнатур на
  свипе 0.001 вместо ≤21, ассерт «≤21» упадёт детерминированно — тест умеет
  падать по построению AC, не только по обещанию.
- Скоуп геометрии/миграций/touch действительно не затронут: структурные стены
  (`_physicalBodiesR`) и partition-cut вне light-пути (`_partitionOpeningCuts`)
  используют конфиг/epoch напрямую, не `_openingAmt` — small-трек обоснован
  фактически, не только декларативно.
- Откат описан верно и достаточен: один revert, кэш самоинвалидируется
  сигнатурой, конфиг не участвует — миграции назад не требуется.
- `User-Visible: yes` с указанием обоих changelog учтено верно, учитывая
  находку M2 про формулировку.

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

- Код не написан — `typecheck`/`test`/`build`, смоки, golden, инварианты
  модели не прогонялись: на этапе ревью ТЗ это не предмет проверки, будет
  предметом код-ревью (S7). Явно не мой гейт на этом этапе.
- Не проверял реальным глазом (браузер/скриншот) визуальную
  неразличимость 5%-ступени — только оценка масштаба (см. M2); это довод в
  пользу пометить решение как предположение, а не довод «всё в порядке».
- Не искал исчерпывающе все смоки/golden, задевающие `current_position` —
  проверил только те, что явно упоминают `current_position`
  (`smoke_glow`, `smoke_cover_no_plate`, `smoke_cover_tap`); последние два
  проверяю по коду не относящимися к light-пути (тестируют плашку/тап
  cover, не Glow), поэтому не разбирал их подробно.
- `npm run inventory`/точные счётчики тестов не считал — не нужно на этом
  этапе.

## Итог

0 High, 2 Medium в скоупе (M1, M2), 2 Low (L1, L2, на усмотрение автора).
Технически контракт К1/К2 и AC1-AC3, AC5 — корректны и доказуемы; ТЗ
возвращается автору не из-за ошибки в решении, а из-за (а) незакрытого
доказательства AC4 и (б) непомеченной догадки о видимом поведении, которую
процесс требует помечать явно, даже когда цена ошибки невелика.