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

SPEC-REVIEW-353-r1

Issue: #353 — «Устойчивость lazy-загрузки: терминальный отказ редактора после сетевого сбоя и мёртвый entry-лоадер после обновления» Этап: ревью ТЗ (PROCESS.md §2.4), лёгкий трек (small), заход r1, блокирующих циклов израсходовано 0 из 2 (лимит §4: 2). ТЗ живёт в теле issue #353 (лёгкий трек, файла в docs/specs/ нет). Материал ревью: тело issue #353 на момент разбора (комментарий Matysh, S2→S3, 2026-08-28T11:01:48Z), метки bug · P1 · S4-spec-review · small.

Вердикт

Жёлтый. High: 1 · Medium: 1 (в скоупе) · Low: 1 (снят с запиской, см. ниже). Причина: K3 (устойчивый entry) как буквально описан ломает инвариант, на который опирается сам демо-стенд, а значит и весь браузерный конвейер гейтов, построенный поверх него — при этом ни один AC этого не ловит. Остальной контракт (K1, K2, K4, K5) и критерии приёмки методологически крепкие и не требуют доработки.

Скоуп разбора

Первый заход — разбор полный, весь текст ТЗ в теле issue #353. Раздел «Унаследовано» и «Закрытие предыдущего раунда» не нужны — предыдущих раундов нет.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md (полностью, включая §2.4, §2.9/2.10, §5, §7.1, §8).
2. Прочитано тело issue #353 и единственный комментарий (переход S2→S3).
3. Прочитан связанный issue #337 (родительский контракт lazy-бандла) для понимания, что «терминально»/«лениво» значило до этой задачи.
4. Построчно сверены все технические утверждения ТЗ с текущим кодом:
   • src/editor-runtime-loader.ts (класс EditorRuntimeLoader, текущая семантика retry/terminal);
   • src/houseplan-card.ts:802-930 (оба лоадера, _requestMode, тосты editor.load_failed/editor.refresh_advice, customElements.define на строке 12889-12890);
   • dist/houseplan-card.js — реальное содержимое собранного entry-чанка: globalThis.__HOUSEPLAN_BUILD_FINGERPRINT__="...";export{d6 as HouseplanCard}from"./houseplan-assets/houseplan-card-BarpA18i.js"; (подтверждает описание N3 буквально);
   • rollup.config.mjs, scripts/bundle-manifest.mjs (editorRuntimeRetryUrlPlugin, bundleManifestPlugin, buildBundleManifest — как считаются initial/lazy графы);
   • scripts/bundle-tree.mjs (verifyBundleTree — подтверждён пробел N4: проверяет только файлы ИЗ манифеста, не сканирует каталог на лишнее);
   • scripts/bundle-budget.mjs + test/bundle-assets.test.mjs (гейт #352, как считается initialViewGzipBytes);
   • custom_components/houseplan/frontend_assets.py, frontend_asset_manifest.py, __init__.py:85-132 (текущие Cache-Control, fail-closed резолвер, регистрация res_type: module);
   • demo/srv/demo.html:180-209 (загрузка карточки демо-стендом — ключевая находка, см. ниже);
   • test/editor-runtime-loader.test.mjs (существующее покрытие: retry ровно один раз для любой ошибки, терминальность только для mismatch — подтверждает описание N2 буквально);
   • src/i18n/en.json, ru.json, de.json (текущие editor.load_failed/ editor.refresh_advice, три словаря синхронны, новый ключ вписывается по образцу).
5. git status/git log — рабочее дерево чистое на 07b6a1f2 (= origin/dev), ветки issue/353-* нет: код по этой задаче ещё не начат, что ожидаемо на этапе S4-spec-review.

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

Этап — ревью ТЗ, кода по issue #353 в дереве нет (задача ещё не покидала S4-spec-review, ветки issue/353-* не существует). typecheck/test/ build/check-docs/smoke-select/model-invariants — гейты код-ревью (PROCESS.md §8, §2.7) и относятся к диффу кода, которого здесь нет; на этапе ТЗ (§2.4) прогонять их нечего и не о чем — сверять было бы не с чем. Ничего не пропущено умалчиванием: раздел «Гейты» в этом документе не применим к этапу spec, и это явное решение, а не пропуск.

Находки

[High] K3: замена статического реэкспорта на «голый» import().catch() рвёт гарантию await import(entry) ⇒ элемент зарегистрирован, на которую опирается сам демо-стенд

Файл/раздел: тело issue #353, раздел «К3 — entry переживает несвежесть».

Что не так. Сейчас dist/houseplan-card.js — это ES-реэкспорт:

export{d6 as HouseplanCard}from"./houseplan-assets/houseplan-card-BarpA18i.js";

Это статический import-edge: спецификация ES-модулей гарантирует, что await import('/assets/houseplan-card.js') не резолвится, пока весь граф, достижимый через export...from, не будет получен, слинкован и выполнен — то есть пока customElements.define('houseplan-card', HouseplanCard) (строка houseplan-card.ts:12889-12890, лежит внутри чанка houseplan-card-<hash>.js) гарантированно не отработает.

К3 предписывает заменить это на import("./houseplan-assets/…").catch(…) — не export, а голый вызов внутри тела entry-чанка, судя по формулировке и по аналогии с editorRuntimeRetryUrlPlugin (пост-обработка уже сгенерированного chunk.code строковой заменой в generateBundle, после того как Rollup уже посчитал граф). Promise такого import() никуда не экспортируется и не await'ится потребителем entry-модуля. Значит, top-level выполнение entry-чанка завершается почти сразу — до того, как динамически запрошенный houseplan-card-<hash>.js успеет загрузиться и выполниться, — и именно в этот момент резолвится await import('/assets/houseplan-card.js') у любого потребителя.

Демо-стенд, на котором держится вся браузерная часть гейтов, устроен именно так — demo/srv/demo.html:193-197:

await import('/assets/houseplan-card.js');
const card=document.createElement('houseplan-card');
card.setConfig({type:'custom:houseplan-card', ...});

После К3 await import(...) резолвится раньше, чем элемент houseplan-card зарегистрирован. document.createElement('houseplan-card') в этот момент создаёт обычный неапгрейженный HTMLElement (в спецификации Custom Elements апгрейд элемента до пользовательского класса происходит именно в момент customElements.define, а не раньше) — метода setConfig на нём ещё нет. Следующая строка card.setConfig(...) бросает TypeError: card.setConfig is not a function синхронно, в самом бутстрапе demo.html.

Почему это не мелочь и не ловится AC. Это не побочный редкий кейс — это обычный, счастливый путь загрузки (когда главный чанк грузится успешно). Он ломает бутстрап demo-стенда для каждого существующего demo/smoke_*.mjs, для golden:capture/golden:verify, для performance_smoke и для demo/docs/capture.mjs (снятие скриншотов документации) — то есть весь браузерный слой CI одномоментно. AC3 из ТЗ этого не поймает: (а) юнит-тест — это проверка текста собранного файла на подстроки (dynamic import, catch, define-фолбэк), не поведения при исполнении; (б) demo/smoke_entry_stale.mjs намеренно воспроизводит испорченный главный чанк — сценарий, где import() падает и код уходит в catch быстро; обычный работающий путь загрузки (когда import() успешен) в AC не проверяется вовсе, а именно там гонка и стреляет.

Как воспроизвести рассуждение (без исполнения — стадия ТЗ, кода ещё нет): прочитать текущее содержимое dist/houseplan-card.js (статический реэкспорт), заменить его мысленно на буквальный текст К3 (import(...).catch(...) без export/await), проследить, что await import(entry) у потребителя больше не транзитивно ждёт вложенный import(), и сопоставить это с demo/srv/demo.html:193-197, где document.createElement + setConfig идут немедленно и синхронно после await import(entry).

Что нужно поправить в ТЗ. Явно решить один из двух путей и записать его в контракт K3:

• либо entry сохраняет цепочку ожидания — например top-level await внутри самого чанка (await import(...).catch(...), ES2022 top-level await, Rollup format es его поддерживает) с реэкспортом результата, чтобы await import(entry) по-прежнему резолвился только после того, как главный чанк загружен либо фолбэк-элемент определён; это сохраняет сегодняшний инвариант без правок demo.html;
• либо явно принять, что гонка есть, и добавить в объём задачи правку demo/srv/demo.html (и любого другого потребителя entry, включая то, как HA резолвит res_type: module) на ожидание customElements.whenDefined('houseplan-card') вместо немедленного document.createElement+setConfig — тогда это меняет объём файлов и, вероятно, поверхность (demo/** — класс B, но задачу это не выводит из лёгкого трека автоматически; решить нужно явно, а не молчанием).

Без этого уточнения ТЗ не выполнимо буквально: реализация по тексту К3 ломает работающий сегодня демо-стенд и, транзитивно, красит smoke, golden, performance_smoke, docs — не после дефекта в проде, а сразу на первом прогоне гейтов реализации.

[Medium, в скоупе] K2 не имеет ни одного AC/доказательства

Файл/раздел: тело issue #353, «К2 — тост на каждый неудачный цикл» vs раздел «AC и доказательства».

К2 — не мелочь: это ядро продуктового сценария issue-AC1 («каждая неудача видима тостом», сетевая — новым ключом editor.retry_advice, терминальная — старым editor.refresh_advice, для обоих лоадеров, editor и onboarding). Но ни один из перечисленных AC1…AC4 его не проверяет:

• AC1 — юнит на уровне модуля editor-runtime-loader.test.mjs, проверяет только сам класс EditorRuntimeLoader (колбэк failed(error, {terminal:false}), переход в idle) — не то, какой текст тоста выберет houseplan-card.ts в своих двух колбэках failed: (error) => {...} (строки 832-835, 860-863), которые как раз и нужно переписать на (error, info) => info.terminal ? refresh_advice : retry_advice.
• AC2 — про терминальность mismatch, тоже не про текст тоста.
• AC3/AC4 — про entry-чанк и orphan-проверку, к тостам отношения не имеют.

Реализация, которая продолжит всегда показывать refresh_advice (игнорируя info.terminal) для обоих лоадеров, пройдёт весь названный набор AC без единого красного теста — при том что это именно та регрессия, из-за которой issue вообще завели (N2: «тост… показывается один раз… все последующие нажатия — молчаливый no-op»; K2 — прямое лекарство от этого).

Фикс, полностью в скоупе задачи: добавить AC5, например: юнит на уровне houseplan-card.ts (или на уровне колбэков failed, вынесенных в проверяемую точку), который стабом задаёт failed(error, {terminal: true|false}) для _editorRuntimeLoader и _onboardingRuntimeLoader и проверяет, что показанный тост содержит editor.refresh_advice в терминальном случае и editor.retry_advice в сетевом, для обоих лоадеров (4 комбинации). С High это не связано и не требует отдельного цикла как самостоятельная находка — фиксируется тем же заходом, что и K3.

[Low, снято с запиской] docs/USER-GUIDE.ru.md не упомянут в объёме задачи, хотя описывает контракт, который эта задача меняет

docs/USER-GUIDE.ru.md:108-111 и :1740 документируют сегодняшнее поведение («после одной повторной попытки… предлагает обновить страницу»; «После обновления старая версия → перезапустите HA, перезагрузите ресурсы/браузер»). После K1–K4 часть этого текста устареет: сетевой сбой станет самостоятельно устраняемым повторным нажатием «Редактировать», а несвежий entry — понятным баннером вместо тишины. ТЗ (как и полагается лёгкому треку, §5) не обязано перечислять release-артефакты явно, а docs/** — документация в тему той же задачи по DoD (PROCESS.md §2.6, правило 11: «документация — в том же коммите, что поведение»), так что формально это не пробел ТЗ. Снимаю находку записью здесь, а не как блокирующую: автору стоит обновить эти два места в USER-GUIDE.ru.md в том же коммите, что и код, но это не требует правки самого ТЗ.

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

• Скоуп и трек. Задача чинит регресс поведения уже принятого механизма #337 (терминальность/несвежесть lazy-доставки), не расширяет продукт — укладывается в J1/J4/J6 SCOPE.md («редакторы остаются доступны», «план остаётся верным»). Критерии лёгкого трека (§5) все выполнены формально: одна логическая поверхность (конвейер доставки lazy-бандла), риск заявлен ≤3, миграций конфига нет, новый UX-контракт не вводит новых элементов интерфейса (то же нажатие «Редактировать», тот же тост).
• K1 (терминальность loader'а). Логика «mismatch на ЛЮБОЙ попытке ⇒ терминально, иначе ⇒ idle и новый явный ensure()» согласована с существующим кодом _loadWithRetry (attempt 1 использует cache-buster — то есть mismatch на attempt 1 после успешного обхода кэша действительно означает версионный дрейф, а не транзиентный сетевой сбой) и с уже существующим тестом (editor-runtime-loader.test.mjs:61-83), который остаётся зелёным без правки ассертов. AC1/AC2 однозначны и проверяемы юнитом.
• N4/K5 (осиротевшие чанки). Утверждение «verifyBundleTree не детектирует лишние файлы вне манифеста» подтверждено чтением scripts/bundle-tree.mjs:38-53 буквально — функция итерирует только manifest.files, каталог не сканирует. Фикс и AC4 просты и корректны.
• Проверенный факт вместо догадки. Утверждение К3 «именованный экспорт entry исчезает — потребителей нет… проверено grep'ом» подтверждено независимо: единственное место, где entry импортируется как модуль — demo/srv/demo.html:193, await import(...) без захвата именованного экспорта; в custom_components/**, test/** потребителей нет. Это не голословная догадка, а верно проверенный факт.
• K4 (immutable Cache-Control). Согласуется с текущим кодом (frontend_assets.py:34 — no-cache меняется на public, max-age=31536000, immutable; __init__.py:100/109 — entry остаётся cache_headers=False, K4 явно это не трогает). Хэшированные имена чанков делают инвалидацию неактуальной проблемой — решение обратимо, откат корректен.
• Откат. Один revert, конфиг/схема/миграции не затронуты — соответствует фактическому масштабу изменения (два флага поведения + один rollup-плагин
  • один HTTP-заголовок + одна проверка каталога).
• i18n. Новый ключ editor.retry_advice вписывается по образцу существующих editor.load_failed/editor.refresh_advice, которые уже синхронны между en.json/ru.json/de.json.

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

• Не прогонял typecheck/test/build/check-docs/smoke-select/ model-invariants — на этапе ревью ТЗ кода по issue #353 в дереве нет (ветка issue/353-* не создана), сравнивать не с чем; эти гейты относятся к код-ревью (§2.7, §8) и будут прогнаны в следующем цикле, когда появится диапазон коммитов.
• Не оценивал реальное поведение HA Lovelace (res_type: module) при гонке из находки High — оценка ограничена наблюдаемым фактом, что demo-стенд ломается гарантированно; поведение реального HA-фронтенда (который, вероятно, толерантен к асинхронной регистрации через customElements.whenDefined с таймаутом) не проверялось и не входит в этот репозиторий — не меняет вывода: даже если прод HA переживёт гонку, собственный демо-стенд проекта, на котором держится весь браузерный слой гейтов, не переживёт, и этого достаточно для блокирующей находки.
• Не пересчитывал вручную содержимое initialViewGzipBytes/бюджета #352 после гипотетической реализации K3: проверено чтением bundle-manifest.mjs, что chunk.imports/chunk.dynamicImports — метаданные, которые Rollup фиксирует до generateBundle, и последующая строковая мутация chunk.code (аналогично уже существующему editorRuntimeRetryUrlPlugin) их не меняет; отдельной находки по бюджету #352 в этом ТЗ не завожу, так как классификация initial/lazy остаётся корректной независимо от K3.