houseplan-card/docs/reviews/SPEC-REVIEW-353-r2.md

SPEC-REVIEW-353-r2

Issue: #353 — «Устойчивость lazy-загрузки: терминальный отказ редактора после сетевого сбоя и мёртвый entry-лоадер после обновления» Этап: ревью ТЗ (PROCESS.md §2.4), лёгкий трек (small), заход r2, блокирующих циклов израсходовано 1 из 2 (лимит §4: 2 на лёгком треке). ТЗ живёт в теле issue #353 (лёгкий трек, файла в docs/specs/ нет).

Предыдущий раунд: docs/reviews/SPEC-REVIEW-353-r1.md (в дереве на 07b6a1f2, опубликован коммитом 5044c281), вердикт жёлтый, High: 1 · Medium: 1 (в скоупе) · Low: 1 (снят с запиской). Материал предыдущего раунда — тело issue на момент комментария Matysh 2026-08-28T11:01:48Z (S2→S3). Материал этого раунда — текущее тело issue #353, помеченное автором как «Ревизия 2 (по SPEC-REVIEW-353-r1)» (комментарий Matysh, 2026-08-28T11:14:34Z, вернувший S4-spec-review).

Для ТЗ нет SHA — предмет ревью текст, а не код; дельта раунда — правки тела issue между ревизией 1 (разобрана в r1) и ревизией 2 (этот раунд), названные автором в комментарии и в приписке в конце тела issue.

Вердикт

Зелёный. High: 0 · Medium: 0. Оба блокирующих замечания r1 закрыты текстом ревизии 2 предметно, без появления новых High/Medium. Один Low (остаточная неточность формулировки AC5) отмечаю и снимаю запиской — не блокирует.

Скоуп разбора — по дельте (PROCESS.md §2.10)

Дельта локальна: правки ограничены разделом «К3» (механизм постобработки entry-чанка) и разделом «AC и доказательства» (добавлен AC5). Остальной текст ТЗ — «Проблема», критерии приёмки issue, К1/К2/К4/К5 (кроме способа доставки тоста в К2, который делит AC5), «Откат», User-Visible — не редактировался между ревизиями (совпадает дословно с текстом, разобранным в r1). Изменение не является ребейзом (кода ещё нет), не меняет контракт поведения сверх того, что r1 уже потребовал исправить, не задевает новую подсистему и по объёму меньше исходной задачи — полный повторный разбор всего ТЗ не требуется; разбираю дельту и всё, до чего она дотягивается (AC3 целиком, поскольку К3 переписан; AC5 целиком, поскольку это новый раздел).

Закрытие раунда r1

Находка r1	Чем закрыта	Где это видно
[High] K3 — замена статического реэкспорта на «голый» import().catch() резолвит await import(entry) у потребителя (демо-стенда) раньше, чем главный чанк успевает выполниться и зарегистрировать customElements.define('houseplan-card', …); ломает document.createElement('houseplan-card').setConfig(...) в demo/srv/demo.html:193-197, то есть счастливый путь всего браузерного слоя гейтов.	К3 переписан на top-level await внутри самого entry-чанка: try { await import("./houseplan-assets/houseplan-card-<hash>.js"); } catch (e) { /* define fallback */ }. Это ровно первый из двух путей, которые r1 предложил как исправление («entry сохраняет цепочку ожидания — top-level await внутри самого чанка… чтобы await import(entry) по-прежнему резолвился только после того, как главный чанк загружен либо фолбэк-элемент определён»). Семантика TLA в ES-модулях (format: 'es', rollup.config.mjs:22) гарантирует, что entry не завершает собственное выполнение, пока вложенный import() не разрешится — то есть await import(entry) у demo/srv/demo.html:193 по-прежнему ждёт customElements.define, как и до К3. demo.html не правится — инвариант сохранён без изменения потребителя, как и требовал r1.	Тело issue #353, раздел «К3 — entry переживает несвежесть, не трогая счастливый путь» (блок кода try { await import(...) } catch (e) {...}) + предложение «Семантика TLA: модуль-потребитель… не резолвится, пока entry не довыполнится… гарантия… сохраняется без правки demo.html».
[Medium, в скоупе] K2 (тост на каждый неудачный цикл, ключ по terminal) не имел ни одного AC — реализация, всегда показывающая refresh_advice, проходила весь набор AC1–AC4.	Добавлен AC5: юнит на чистую функцию lazyLoadFailureMessage(t, {terminal}) для обеих комбинаций (true→refresh_advice, false→retry_advice) + структурная проверка «в духе test/houseplan-source.mjs», что failed-колбэки ОБОИХ лоадеров (_editorRuntimeLoader, _onboardingRuntimeLoader в src/houseplan-card.ts:830-835,861-865 на момент r1) вызывают именно этот общий помощник, а не строят текст тоста сами.	Тело issue #353, раздел «AC и доказательства», пункт «AC5 (закрывает К2)»; раздел «Контракт», К2: «Оба лоадера… выбирают текст через ОБЩИЙ экспортируемый помощник lazyLoadFailureMessage(t, { terminal })».
[Low, снято с запиской в r1] USER-GUIDE.ru.md не в объёме задачи.	Без изменений — уже снято в r1 с запиской «чинится в том же коммите реализации», ревизия 2 её подтверждает явной строкой.	Тело issue #353: «Попутно (Low r1): затронутые места docs/USER-GUIDE.ru.md обновляются в том же коммите реализации.»

Как проверялось (дельта)

1. Перечитан весь текст тела issue #353 на текущий момент и сверен построчно с цитатами r1 (что изменилось — К3 и «AC и доказательства»; что нет — «Проблема», критерии issue, К1/К4/К5, «Откат», User-Visible).
2. К3 разобран построчно на согласованность заявленного механизма (TLA) с форматом сборки: rollup.config.mjs — input: 'src/houseplan-card.ts', output.format: 'es', intro инжектирует фингерпринт, плагины editorRuntimeRetryUrlPlugin() → bundleManifestPlugin(...) в этом порядке в generateBundle. Новый плагин описан «рядом с editorRuntimeRetryUrlPlugin… ДО bundleManifestPlugin» — та же семья постобработки, тот же порядок, что уже проверен и принят в r1 для аналогичной строковой мутации кода чанка.
3. Проверено рассуждение (без исполнения — кода ещё нет): TLA в ES-модулях означает, что evaluation entry-модуля не завершается, пока вложенный await import(...) не разрешится; следовательно await import(entry) любого потребителя (в т.ч. demo/srv/demo.html:193) транзитивно ждёт того же события, что и раньше (выполнение главного чанка, customElements.define). Ровно то свойство, разрыв которого был предметом High в r1.
4. Сверено, что «именованный экспорт entry исчезает — потребителей нет» осталось тем же утверждением, которое r1 уже независимо перепроверил grep'ом (demo/srv/demo.html:193 — await import(...) без захвата именованного экспорта; в custom_components/**, test/** потребителей нет) — дельта его не меняет, факт наследуется.
5. AC5 сверен с текущим кодом src/houseplan-card.ts (класс HouseplanCard, оба EditorRuntimeLoader, поля _editorRuntimeLoader/ _onboardingRuntimeLoader, оба колбэка failed: (error) => {...}, console.error(...) + this._showToast(...editor.refresh_advice)) — подтверждено, что сегодня оба колбэка игнорируют причину отказа и всегда показывают один и тот же текст; ровно это АС5 обязана ловить.
6. Перечитан test/houseplan-source.mjs — существующий образец «структурной проверки» в этом проекте: AST-разбор TS-исходников через typescript (ts.createSourceFile), сверка членов класса, а не простой grep по подстроке. Это делает правдоподобным заявление АС5, что структурная проверка способна отличить «вызывает помощник с прокинутым info.terminal» от «вызывает помощник с захардкоженным аргументом» — но ТЗ не проговаривает это явно (см. Low ниже).
7. Git: рабочее дерево чистое на 5044c281 (= origin/dev), ветки issue/353-* нет — код по задаче не начат, соответствует этапу S4-spec-review.

Гейты — что прогнано и почему

Не применимо к этому раунду: этап — ревью ТЗ, кода по issue #353 в дереве по-прежнему нет (ветка issue/353-* не создана, дельта — правка текста issue, не коммит). typecheck/test/build/check-docs/smoke-select/ model-invariants относятся к код-ревью (§2.7, §8) и будут прогнаны, когда появится диапазон коммитов. Это то же решение, что и в r1, не молчаливый пропуск.

Унаследовано из r1

Принято без повторной проверки в этом раунде — не задето дельтой:

• Скоуп и трек. Задача остаётся в J1/J4/J6 SCOPE.md, критерии лёгкого трека (§5) выполнены. — docs/reviews/SPEC-REVIEW-353-r1.md, раздел «Что проверено и корректно», на 07b6a1f2.
• К1 (терминальность loader'а) и AC1/AC2 — логика «mismatch на любой попытке ⇒ терминально, иначе ⇒ idle» согласована с test/editor-runtime-loader.test.mjs:61-83 и текущим _loadWithRetry. — там же, раздел «К1», на 07b6a1f2.
• К5/N4 (осиротевшие чанки), AC4 — scripts/bundle-tree.mjs:38-53 подтверждённо не сканирует каталог вне манифеста; фикс и AC4 просты. — там же, раздел «N4/K5», на 07b6a1f2.
• К4 (immutable Cache-Control) — согласуется с frontend_assets.py:34, __init__.py:100/109; откат корректен. — там же, раздел «K4», на 07b6a1f2.
• i18n — новый ключ editor.retry_advice по образцу существующих, словари синхронны. — там же, на 07b6a1f2.
• Бюджет #352 / классификация initial-lazy графа. Постобработка generateBundle (строковая мутация уже посчитанного Rollup чанка) не меняет chunk.imports/chunk.dynamicImports, зафиксированные до генерации бандла — рассуждение в r1 строилось на существующем editorRuntimeRetryUrlPlugin, и новый TLA-плагин относится к той же семье постобработки (см. «Как проверялось», п.2). Отдельно не пересчитывал. — docs/reviews/SPEC-REVIEW-353-r1.md, раздел «Чего не проверял», на 07b6a1f2.
• Поведение реального HA-фронтенда при аналогичной гонке — не оценивалось ни в r1, ни здесь; вывод не меняется — демо-стенд остаётся критерием, и он теперь гонки не имеет.

Находки

[Low, снято с запиской] AC5 не проговаривает, что структурная проверка обязана отличать «параметр info.terminal прокинут в вызов» от «вызов есть, но аргумент захардкожен»

Файл/раздел: тело issue #353, «AC и доказательства», пункт AC5.

АС5 утверждает: «структурная проверка… failed-колбэки ОБОИХ лоадеров… вызывают lazyLoadFailureMessage (реализация «всегда refresh_advice» падает)». Формулировка «вызывают lazyLoadFailureMessage» буквально описывает только факт вызова. Реализация, которая зовёт помощник, но захардкоживает { terminal: true } вместо прокидывания параметра info колбэка, тоже «вызывает lazyLoadFailureMessage» — и без уточнения, что проверяется именно происхождение аргумента (идентификатор info/ info.terminal, а не литерал), такая проверка может пропустить именно ту регрессию, которую AC5 призван ловить (тот же дефект N2, просто воспроизведённый на уровне выбора текста, а не состояния лоадера). Это не голословное сомнение: раздел «Мутанты в реестр» ТЗ перечисляет 5 мутантов для AC1–AC4, но ни один — для AC5, хотя ровно AC5 существует для отлова конкретного класса регрессии (игнорирование terminal).

Не блокирую: test/houseplan-source.mjs — существующий в проекте образец именно такой AST-проверки (разбирает TS через ts.createSourceFile, сверяет структуру, а не текстовые подстроки), так что технически реализуемо и укладывается в стиль проекта; способ доказательства и его точность — по правилу «в теле issue сказано в духе test/houseplan-source.mjs» уже названы, а точная форма AST-проверки — техническая деталь реализации, которую решает автор (PROCESS.md: «где хранится состояние… стратегия теста… решай сам»). Записываю как пункт для код-ревью: убедиться, что реализованный тест действительно падает на мутанте «захардкоженный terminal» — то есть на дисциплину «тест умеет падать», применённую к этому конкретному AC.

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

• К3 (ревизия 2) закрывает High r1 предметно: TLA-обёртка сохраняет гарантию «await import(entry) резолвится не раньше, чем главный чанк выполнен либо фолбэк определён», без правки demo.html — именно то решение, которое r1 предложил как один из двух допустимых путей.
• AC5 закрывает Medium r1: К2 (выбор текста тоста по terminal, для обоих лоадеров) теперь имеет явный AC и явно названный проверяемый дефект («всегда refresh_advice»).
• Плагин К3 задан в той же точке пайплайна (generateBundle, до bundleManifestPlugin), что и уже принятый editorRuntimeRetryUrlPlugin — не открывает новых вопросов к бюджету #352 сверх уже принятого в r1.
• Остальной контракт (К1, К4, К5, «Откат», User-Visible) не редактировался между ревизиями — выводы r1 по ним стоят без изменений.

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

• Не прогонял typecheck/test/build/check-docs/smoke-select/ model-invariants — кода по issue #353 в дереве нет (см. «Гейты» выше).
• Не проверял заново К1, К4, К5, критерии лёгкого трека, i18n-синхронность и бюджет-рассуждение — не задеты дельтой r1→r2, унаследованы из SPEC-REVIEW-353-r1.md (раздел «Унаследовано из r1» выше).
• Не оценивал реальную поддержку top-level await целевыми окружениями (HA frontend resource, res_type: module) — техническая деталь реализации; TLA в ES-модулях — часть спецификации ECMAScript, поддержана всеми актуальными эвергрин-браузерами, отдельного продуктового риска не усматриваю и не отношу к продуктовой неоднозначности, которую решает владелец.