@opetope/runtime 0.1.0

package/docs/devtools.ru.md

@@ -0,0 +1,419 @@
+# Opetope Devtools
+
+Одна правдивая проекция скомпилированной топологии и текущего состояния рантайма и ответ на вопрос «почему этот узел
+сейчас в этом состоянии». `@opetope/devtools` — необязательный инструмент разработки; исключайте подключение панели из production-сборки.
+
+Этот документ нормативен для devtools: протокол наблюдения, архитектура его доставки, панель, которая его рисует, и
+управление условиями, которое пишет обратно. При расхождении этого документа с рантаймом побеждают
+рантайм и [`spec.md`](spec.ru.md), а расхождение фиксируется строкой в §9.
+
+## 1. Что это и чем это не является
+
+Отвечает на вопросы: почему фича не активна; чего она ждёт; какой экземпляр текущий, а какой ушёл; куда доходят её
+вклады; что случилось перед отказом.
+
+Не читает значения моделей и репозиториев, пропсы React и полезную нагрузку вызовов. Не воспроизводит эффекты, не
+меняет граф объявлений, не заменяет продуктовые флаги и не ходит в сеть. Текст ошибки в протокол не попадает: отказ
+это ограниченный код, субъект и фаза.
+
+## 2. Протокол наблюдения
+
+### 2.1 Две проекции
+
+Снимок несёт `plan` — неизменную топологию, которую построил компилятор приложения, — и `runtime` — живой мир,
+который тот открыл. Их никогда не смешивают: объявление фичи переживает много своих экземпляров, а склейка этих двух
+вещей и есть ошибка, ради которой протокол существует. Топология неизменна внутри одной сессии; замена плана
+открывает новый `sessionId`.
+
+### 2.2 Узлы
+
+Названы публичными словами [`spec.md`](spec.ru.md) §3: `application`, `condition`, `condition-group`, `feature`,
+`feature-instance`, `attachment`, `contribution`, `contribution-target`, `port`, `host-contract`, `absent-provider`.
+
+Группа условий это выведенный владелец активации: фичи, чей `when` называет один и тот же набор условий, образуют
+одну группу. Фича с пустым `when` принадлежит самому приложению. `absent-provider` это контракт экспорта фичи,
+который план называет, но за которым ничего нет, чтобы у ребра `absent-import` было начало.
+
+### 2.3 Рёбра
+
+Направление зафиксировано: провайдер, блокер или владелец → потребитель, ожидающий или владеемый узел. Три класса:
+
+- **жёсткие** — `hard-import`, `requires-port`. Единственные рёбра, которых ждёт активация; несут `pending`.
+- **слабые** — `optional-import`, `optional-port`, `absent-import`, `absent-port`. Одно слово `optional` и для фич,
+  и для портов. Потребитель может жить дольше провайдера, читает `Lookup` (`found` или `missing`) и никогда не ждёт.
+- **структурные** — `owns`, `provides-port`, `contributes-to`, `condition-control`, `on-demand-import`. Собственного
+  состояния не несут.
+
+Компилятор выдаёт один вид `requires-port` для обеих сил; протокол делит его по полю
+`CompiledApplicationRequirementIR.optional`, симметрично паре импортов, которую компилятор делит сам.
+
+### 2.4 Автоматы состояний и три оси
+
+Универсального `node.status` нет. Каждый вид несёт тот автомат, который у рантайма действительно есть: группа условий
+из `condition-group-execution.ts`, экземпляр фичи из кодов `FeatureError` в `spec.md` §4, attachment из
+`AttachmentLifecycleSnapshot`, вклад из хаба (`published`, и `withheld`, когда его `when` читается как false), порт из
+компиляторного выбора единственного провайдера, host-контракт из `bind`.
+
+Панель стилизует узлы тремя ортогональными осями, выведенными из этих объединений, и никогда наоборот:
+
+- `desired` — `active` либо `inactive`, со значениями источника, override и итоговым;
+- `lifecycle` — `declared`, `waiting`, `opening`, `ready`, `fencing`, `retiring`, `closed`;
+- `health` — `healthy`, `blocked`, `failed`, `cancelled`, `stale`, `quarantined`.
+
+`declared` это седьмое значение оси: фича, которую план объявил, а экземпляр не открывал, не находится ни в одном из
+остальных шести, и назвать её `waiting` значило бы заявить блокера, которого нет.
+
+Загрузка `body` заголовка восьмого значения не добавляет. Экземпляр существует и находится в `opening`, пока его код
+едет, — так это докладывает рантайм и так это рисует панель (D186); собственный `loading` был бы вторым словом для
+состояния, которое в протоколе уже есть, и легенде пришлось бы объяснять разницу.
+
+### 2.5 Отказы, фазы и причины
+
+Отказ это собственная ошибка рантайма, дискриминированная пара `subject` и `code`: `feature`, `call`, `readable`,
+`contribution`, `application`, `declaration`. Фазы — словарь D14: `open`, `close`, `rollback`, `fence`, `drain`,
+`retry`. Причина это ref, который панель разрешает по снимку, а не проза.
+
+У протокола ровно одни часы, `cause.at`, и они отмечают триггер, а не коммит. Записи состояний часов не несут: вторые
+часы позволили бы панели показать длительность, которой рантайм не измерял. У кадра без причины времени нет, и
+timeline оставляет эту колонку пустой.
+
+Если `cause.at` присутствует, это неотрицательное целое число миллисекунд эпохи не больше
+`8_640_000_000_000_000`, максимального допустимого времени Date. Счётчики sequence и revision сохраняют отдельный
+домен неотрицательных безопасных целых (D242).
+
+### 2.6 Идентичность, метки и редакция
+
+Идентификаторы это данные, и один идентификатор называет одну вещь. Диагностический id это префикс вида и id
+объявлений его частей, соединённые через `:`; часть сначала экранируется через `_`, поэтому символ, который
+грамматика потребителя не принимает — `/` в id объявления, `|` в ключе группы условий, — остаётся собой, а не
+сливается с соседом, и части составного id остаются разделимыми (D200). Метка это presentation metadata, выведенная
+компилятором из объявления: панель её рисует и никогда не переводит, и она никогда не даёт прав. В снимке нет ни колбэков, ни `FeatureInstance`, ни моделей и
+ресурсов, ни сырого `Error`, `AbortSignal` или thenable, ни DOM и React-объектов. Экспорт это канонический
+data-only JSON под лимитами записей, в буфер обмена или локальный файл; сетевого транспорта нет.
+
+Узел приложения имеет id `application:<экранированный id объявления>`; узел фичи сохраняет экранированный id
+объявления. Приложение и фича могут иметь одинаковый id объявления, сохраняя разные диагностические identities (D242).
+
+## 3. Архитектура наблюдения
+
+### 3.1 Кому принадлежит семантика
+
+Рантайм владеет идентификаторами, видами, переходами и причинными ссылками. Devtools не сканирует приватные карты, не
+патчит методы и не восстанавливает граф по логам, поэтому продовый планировщик и отладчик описывают одну машину.
+`RuntimeInspectionSession` это _потребляемый_ интерфейс: семантика принадлежит рантайму, и он ничего отсюда не
+импортирует, поэтому в рантайме об этом пакете ничего не известно. Протокол, редьюсер, проекции и панель тоже не
+импортируют ни один пакет `@opetope/*`. Единственное исключение это `./integration`, который открывает порты за
+приложение и потому держит `@opetope/runtime/internal` (D248).
+
+### 3.2 Подключение
+
+`createInspectionSession(execution)` на `@opetope/runtime/internal`, доступный только тому, кто держит
+`ApplicationExecution`, созданный хостом. Ни process-wide синглтона, ни глобального хука. Без сессии рантайм не
+аллоцирует записей, а закрытие приложения уносит сессию с собой.
+
+Приложение эту фабрику не вызывает. Оно передаёт execution в `installDevtools({ execution, … })` из
+`@opetope/devtools/integration`, который открывает порт наблюдения — и, при `mode: 'control'`, порт записи — и
+владеет обоими до закрытия своего handle: `/internal` это шов между пакетами самой библиотеки, а не поверхность,
+до которой приложению положено доставать (D248).
+
+Подключение возвращает отключение, и оно принадлежит владельцу времени жизни execution, а не тому, кто его открыл.
+Панель приезжает динамическим импортом, поэтому приложение, закрытое до его резолва, иначе получило бы панель,
+которая ему уже не нужна, а следующее приложение застало бы на странице предыдущую.
+
+### 3.3 Доставка, разрывы и resync
+
+Рантайм фиксирует кадр и уведомляет; клиент читает пакет сам, поэтому медленная или закрытая панель не создаёт
+backpressure. Доставка может быть вне очереди перехода — слушателя не зовут внутри транзакции. Кадр называет свою
+сессию, базовую и следующую ревизию и диапазон номеров; разрыв, дубль, скачок ревизии или чужая сессия отвергаются в
+пользу свежего снимка, потому что частично применённая дельта это отладчик, который врёт. История ограничена и числом
+кадров, и приблизительными байтами, а переполнение оставляет метку разрыва, а не молчаливую дыру.
+
+Продюсер `createInspectionSession(execution, { ringCapacity })` принимает неотрицательное безопасное целое,
+по умолчанию 256 кадров. Ноль не удерживает кадры: снимки остаются доступны, а читатель, отставший от отброшенного
+перехода, получает `resync-required`. Неверная ёмкость отвергается до занятия observation slot (D242).
+Кадр с пустыми `operations` всё ещё фиксирует транзакцию, если несёт замену `activity`, включая пустую замену,
+очищающую прежнюю activity. Кадр без обоих изменений отвергается contract kit.
+
+### 3.4 Нейтральность к спросу
+
+Ноль, один или несколько подключённых инспекторов оставляют исходы приложения одинаковыми. Наблюдение не создаёт
+спроса, не удерживает экземпляр и никогда не меняет того, что публикует фича.
+
+## 4. Панель
+
+### 4.1 Две вкладки
+
+`Graph` и `Timeline`. Одна показывает граф в момент времени, другая историю коммитов. Всё, что раньше было вкладкой,
+стало фильтром внутри `Graph`.
+
+### 4.2 Чипы фильтра рёбер и пресеты
+
+Чип включает и выключает вид ребра; пресет это именованный набор чипов.
+
+| Пресет           | Что включает                                                                                                                            | На какой вопрос отвечает                                         |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Импорты и порты  | `hard-import`, `optional-import`, `absent-import`, `on-demand-import`, `requires-port`, `optional-port`, `absent-port`, `provides-port` | Кто кому нужен и что из этого сейчас недоступно                  |
+| Условия          | `condition-control`, `owns` от группы условий                                                                                           | Кто гейтит эту фичу и что ещё живёт в её группе                  |
+| Владение         | `owns`                                                                                                                                  | Что этот узел породил и что переживёт его                        |
+| Точки расширения | `contributes-to`, `owns` до вкладов, плюс второй шаг проекции                                                                           | Куда уходят вклады этой фичи и кто ещё вкладывается в ту же цель |
+
+Первые три — честные фильтры рёбер. Четвёртый исключение, и это названо прямо: вклад это узел _между_ фичей и целью,
+поэтому окрестность в один шаг показывает вклады, но не показывает, куда они идут, — то есть не отвечает на вопрос,
+ради которого её открывают. Он строит два шага, фича → вклады → цели, и показывает других контрибьюторов той же
+цели, потому что приоритет и конкуренция видны только рядом. Выбор цели переворачивает проекцию.
+
+### 4.3 Выделение, breadcrumbs, инспектор
+
+Одно выделение, один граф, один инспектор. Смена пресета не меняет выделение, а выделение не сбрасывает пресет.
+Breadcrumbs показывают путь до выбранного узла и работают как навигация: крошка предка возвращает к нему, текущий
+узел остаётся подписью. Инспектор показывает идентичность и происхождение, текущее состояние и счётчик экземпляра,
+непосредственную причину, зависимости узла с `Lookup` у каждой слабой строки, чем он владеет и последнюю причинную
+цепочку.
+
+Имя, которое не влезает в свою рамку, сокращает панель, а не рамка: сосед пишется относительно выделения, не
+влезающее и после этого имя режется по середине, чтобы уцелел последний сегмент, строка группы говорит `when` один
+раз и называет условия в теге рядом, а полный id всегда лежит в `title`. Многоточие справа съело бы хвост, а именно
+хвост и отличает двух соседей друг от друга.
+
+### 4.4 Узкие экраны
+
+Ниже 1100 px три колонки перестают читаться, и окрестность рисуется списком. Список и инспектор при этом делят вторую
+колонку стопкой, а не выпадает один из них: панель, которая не может сказать, чего узел ждёт, теряет вопрос, ради
+которого существует. Ручного переключателя `Graph`/`List` нет ни на какой ширине: список не даёт ничего сверх графа, а
+вторая форма стоит второй раскладки, вторых тестов и вторых строк словаря.
+
+### 4.5 Статус-бар
+
+Постоянно видно то, что отвечает на вопрос «можно ли верить тому, что я вижу»: `frame · state rev`, число `dropped` и
+`LIVE`. За «⋯»: `reducer · paint ms`, источник темы и ревизия схемы — они описывают панель, а не приложение.
+
+### 4.6 Кодирование состояния, легенда, локаль
+
+Состояние никогда не передаётся одним цветом: глиф, цвет и текстовый тег вместе, у каждого свой label для скринридера.
+Одна сворачиваемая легенда покрывает семь состояний lifecycle, три визуальных вида рёбер с перечислением протокольных
+рёбер под каждым и три бейджа осей.
+
+Панель говорит по-английски и по-русски, по умолчанию берёт язык браузера, переключается в шапке. Проза переводится,
+словарь протокола — нет: `Feature`, `Condition`, `declared`, `quarantined`, `hard-import`, `found`, `missing`, `drain`
+это идентификаторы, которые разработчик грепает и сверяет с `spec.md` §3, поэтому они вставляются _в_ переведённые
+предложения, а не заменяются. Тест рендерит панель по-русски по всем поверхностям и падает на любом латинском слове
+вне двух списков: словаря протокола и слов, пришедших из самого графа.
+
+### 4.7 Камера
+
+Линза обрезает содержимое, поэтому добраться до узла вне кадра — работа камеры: перетаскивание пустого места двигает,
+колесо приближает вокруг курсора, кнопки дают намеренный шаг 1.2× вокруг центра, а открытие узла вписывает граф.
+Колесо масштабирует по величине жеста, а не фиксированным множителем, `deltaMode` приводится к пикселям, и один кадр
+зажат, чтобы грубое устройство не перепрыгнуло диапазон. Протяжка двигает камеру и ничего не выделяет.
+
+## 5. Управление условиями
+
+### 5.1 Что можно переключать
+
+Только условие и его группу. Узел графа это диагностическая запись, а не изменяемая ручка: прямая запись состояния
+обошла бы планировщик, жёсткие зависимости, вклады, фенс, уборку и карантин. Фича с пустым `when` не отключается, и
+это закон, а не пробел: синтетические условия на каждой фиче отвергнуты, потому что сделали бы отладчик источником
+времени жизни, которого в плане нет.
+
+### 5.2 Действия
+
+| Действие        | Где стоит                    | Что делает                                                               | Чего не обещает                          |
+| --------------- | ---------------------------- | ------------------------------------------------------------------------ | ---------------------------------------- |
+| `Suspend`       | узел группы условий          | Ставит override «принудительно false»; группа гаснет обычной транзакцией | Не отменяет продуктовый источник условия |
+| `Resume`        | узел группы условий          | Снимает override; группа снова следует источнику                         | Не обещает `ready`                       |
+| `Retry cleanup` | узел карантинного экземпляра | Повторяет уборку карантинного фронтира через существующий retry-контракт | Не объявляет зависший ресурс закрытым    |
+
+`Retry cleanup` стоит на экземпляре, потому что карантин принадлежит экземпляру: это его уборка не завершилась. Он
+предлагается только там, где карантинный фронтир есть, а приложение доходит до него, открываясь с
+`cleanupFailure: 'quarantine'` (D182); при умолчании `report` карантина не бывает, а значит нет и кнопки.
+
+Команды стоят в двух местах, и ни одно из них не сама карточка: панель над канвасом, которая принадлежит выбранному
+узлу, не будучи нарисованной внутри него, и инспектор. Карточка остаётся одной целью выбора — вложенный в неё
+контрол был бы кнопкой внутри кнопки, а плавающий над ней уезжал бы с каждым панорамированием.
+
+Бейдж override стоит рядом с командами, пока override держится, и читается из снимка самой группы, а не из того, что
+панель просила. Применение спрашивает подтверждение, потому что меняет живое приложение, и второе нажатие называет
+цель. Каждое применение и каждый отказ доходят до timeline отдельной audit-строкой.
+
+### 5.3 Закон зависимостей
+
+Обратного каскада нет. `Suspend` группы-провайдера отправляет жёстких зависимых по их обычной семантике недоступности
+и retirement, а слабые продолжают работать и читают `missing`. `Suspend` группы-потребителя не гасит провайдера:
+потеря потребителя не выключает никого.
+
+### 5.4 Контракт write-порта
+
+Отдельная фабрика рядом с портом наблюдения, потому что держать inspection-сессию не должно значить иметь право
+писать.
+
+```ts
+interface RuntimeControlSession {
+  close(): void;
+  resume(conditionId: string): Promise<ControlOutcome>;
+  retryCleanup(instanceId: string): Promise<ControlOutcome>;
+  suspend(conditionId: string): Promise<ControlOutcome>;
+}
+
+type ControlOutcome =
+  | { readonly kind: 'applied'; readonly sequence: number }
+  | { readonly kind: 'rejected'; readonly reason: 'not-controllable' | 'stale' | 'unknown-target' };
+
+declare function createControlSession(execution: ApplicationExecution): RuntimeControlSession;
+```
+
+Применение сериализуется тем же планировщиком, который ведёт переходы условий, и публикует обычный атомарный кадр,
+поэтому панель узнаёт результат тем же способом, что и всё остальное; `sequence` указывает на кадр, где эффект виден.
+Отказ это данные, а не исключение. У одного execution одновременно живёт не больше одной сессии управления: второй
+`createControlSession` при открытой первой бросает, а `close()` освобождает слот, поэтому перезагруженная панель может
+взять управление снова (D191). Хост его тоже не открывает: это делает `installDevtools` при `mode: 'control'`, и
+отказ даёт провалившуюся установку, а не панель, которая молча поднялась read-only (D248). `close()` снимает и все
+override этой сессии, поэтому закрытие панели не оставляет приложение в отлаженном состоянии, а сам override не
+переживает reload и HMR.
+
+Команды управления используют текущую схему graph/frame `/3` без отдельной revision. Применённая команда выразима: кадр несёт существующую
+причину `control-command` со своим условием, а снимок группы заполняет существующее поле
+`desired.override: 'force-inactive'` рядом с `desired.source` — именно его читает бейдж override. Отказ не порождает
+кадра вовсе, потому что кадр, который ничего не коммитит, лгал бы.
+
+Поэтому audit-след ведёт сама панель: она пишет локальные строки timeline — `control · suspend cond.x · applied →
+frame N`, `control · resume cond.y · rejected · unknown-target` — и связывает применённую строку с кадром продюсера
+по `sequence` из исхода. Требование владельца «каждое применение и каждый отказ видны одной лентой» выполняется без
+изобретения кадра, которого рантайм не коммитил.
+
+Машинерия `preview → apply` с одноразовым permit не берётся. Управляемый субъект один, его эффект описан законом
+зависимостей и уже нарисован в графе, поэтому предпросмотр дублировал бы граф; подтверждение плюс audit-след это
+соразмерная форма. Если у управления появится вторая цель, вопрос откроется заново.
+
+## 6. Производительность и память
+
+Снимок строится за `O(N + E)` без рекурсивного обхода на пути приёма; кадр стоит `O(изменённых записей)`. Дерево
+кэширует декларативную топологию на сессию и разрешает display по нарисованной строке, поэтому коммит, меняющий
+только состояние, его не перестраивает. Поиск, проекция инспектора и layout графа мемоизированы по счётчику версий
+стора, который меняется ровно раз на применённый кадр. Виртуализация списков/инспектора от 200 строк и worker layout
+от 300 узлов — предложенные пороги, не реализованное поведение и не измеренные гарантии. Текущие список и layout
+работают на главном потоке; будущей реализации нужны измерения корпуса на этих границах. Панель держит для
+себя p95 в 4 мс на применение кадра не более чем со 100 изменёнными записями и один кадр анимации на отрисовку, и
+сама показывает обе цифры в status bar, поэтому регрессия видна там, где случилась, а не в отчёте.
+
+Поверхности, о которой сессия не попросила, в бандле панели нет вовсе. Четыре грузятся по требованию, у каждой свой
+бюджет: control plane — когда хост передал порт записи и в выделении есть адресуемый субъект, легенда — при первом
+открытии, выгрузка — по нажатию, которое её использует, хронология — вместе со своей вкладкой. Каждая несёт и
+собственный словарь, поэтому панель, которая ни одну из них не открыла, не везёт ни их кода, ни их слов. Этим бюджет
+панели и остаётся честным по мере её роста: сегодня 20.18 кБ из 21 против 1.68, 1.45, 1.14 и 0.91 кБ за собственными
+cap-ами и 5.02 из 5.5 кБ у headless session consumer (D240, D241).
+
+Поверхность может и не приехать. Панель держит каждую как pending, loaded или failed: не приехавшая говорит об этом
+на своём месте и предлагает попробовать снова, летящий запрос разделяется вместо второго, а неудачная попытка
+забывается, чтобы повтор был настоящим повтором. Ничто не остаётся отклонённым промисом, о котором узнает хост, —
+это то же правило, которому следуют исходы копирования и выгрузки (§7).
+
+Измеряй приложение отдельно с выключенным, подключённым и отключённым inspection. Фиксируй режим сборки,
+начальные байты и загрузку по требованию, задержку взаимодействия и удержанную память. Особенности загрузки
+и backend конкретного приложения не являются гарантиями производительности библиотеки.
+
+## 7. Семантика отказов
+
+| Событие                     | Требуемое поведение                                              |
+| --------------------------- | ---------------------------------------------------------------- |
+| Наблюдатель бросил          | Отцеплен и доложен; переход уже зафиксирован                     |
+| Переполнение очереди        | Ограниченная метка разрыва, resync по снимку, приложение не ждёт |
+| Дубль или нарушение порядка | Отвергнуть кадр и пересинхронизироваться                         |
+| Кадр от заменённого плана   | Игнорировать                                                     |
+| Отказ первого снимка        | Закрыть сессию, доложить `snapshot-failed`, ничего не менять     |
+| Карантин уборки             | Логический фенс сохраняется; только точный повтор                |
+| Панель размонтирована       | Отцепить потребителя, освободить UI-состояние, приложение живёт  |
+
+Недоверенные данные — воспроизведённый экспорт, фикстура из отчёта об ошибке — проходят строгий декодер с бюджетами
+по числу записей, длине строк и байтам. Незнакомые виды и лишние поля отвергаются вместе с записью, а не терпятся:
+совместимость вперёд несёт ревизия схемы, а не снисходительность. Свойство-аксессор отвергается до чтения — и поле
+записи, и элемент массива, — а ни один метод входного значения не вызывается, поэтому payload не может исполнить код
+внутри декодера. Бюджет байтов считается в UTF-8 байтах до разбора: лимит, названный в байтах, но считающий
+UTF-16 units, втрое слабее, чем читается. Приоритет вклада принимает любое конечное число, включая отрицательное
+и дробное, как и producer рантайма; счётчики и индексы сохраняют собственные целочисленные ограничения (D212).
+
+У идентификаторов собственные длины, выведенные из законов producer-а, а не выбранные: атом это declaration id не
+длиннее 160 символов, экранирование добавляет по символу на разделитель (D200), node id добавляет самый длинный
+префикс, а edge id экранирует оба конца ещё раз. Условие публикуется одним экранированным атомом и адресуется им, а
+написанный автором declaration id остаётся в label: границей служит экранированная длина, а показывается условие
+везде по label. Плоский лимит короче этой арифметики отвергает снимки, которые законное приложение производит. Группа, ключ которой соединяет больше условий, чем помещается в один экранированный
+атом, отвергается как слишком длинный id — это отказ по бюджету, как `maxNodes`, а не утверждение о форме.
+
+## 8. Приёмка
+
+Топология и экземпляры не склеиваются. Снимок плюс непрерывные кадры детерминированно воспроизводят состояние на
+каждой границе коммита. Кадр виден только после атомарного коммита. Устаревшие, дублирующие, разорванные и чужие
+кадры отвергаются. У каждого состояния ожидания, отказа и карантина есть типизированная причина. Ничто не читается
+как работающее после фенса владельца. Число инспекторов не меняет исходов. В проде чанка devtools нет.
+
+Исполняемая форма — `assertInspectionSessionContract` в `@opetope/devtools/testing`: рантайм, реализующий порт,
+прогоняет её на своей сессии, не читая исходники devtools.
+
+## 9. Лог решений
+
+Строки, описывающие текущее поведение. Вытесненные свёрнуты в одну строку вместо полного текста.
+
+### 9.1 Протокол
+
+| №   | Решение                                                                                                                                                                                                                                                                                                                                                                                |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T1  | У кадра нет собственных часов. `cause.at` единственные, и они отмечают триггер; записи состояний часов не несут, и длительности из времён коммитов не выводятся                                                                                                                                                                                                                        |
+| T3  | `declared` это седьмое значение оси lifecycle, для фичи, которую план объявил, а экземпляр не открывал                                                                                                                                                                                                                                                                                 |
+| T4  | Таксономия узлов пересобрана по IR плана и публичному словарю; `activation-domain`, `module-*`, `eligibility-attempt`, `capability-resolution`, `scope-generation`, `view-root` удалены                                                                                                                                                                                                |
+| T6  | Шесть activation-семантик сведены к двум классам, которые различает компилятор: жёсткие рёбра несут `pending`, слабые несут `Lookup` и никогда не ждут                                                                                                                                                                                                                                 |
+| T7  | У `start-after` нет соответствия: порядок открытия выведенный, а не объявленный, и живёт в `plan.groups[].order`                                                                                                                                                                                                                                                                       |
+| T8  | Провайдер выбирается на компиляции, поэтому в рантайме нет ни допуска, ни списка кандидатов, ни неоднозначности — только вопрос, есть ли у выбранного провайдера живой экземпляр                                                                                                                                                                                                       |
+| T13 | `requires-port` делится на жёсткий и слабый по `CompiledApplicationRequirementIR.optional`, потому что компилятор выдаёт один вид для обоих                                                                                                                                                                                                                                            |
+| T14 | Рёбра порта идут через узел порта: `provides-port` от провайдера, `requires-port` и `absent-port` к потребителю                                                                                                                                                                                                                                                                        |
+| T15 | `absent-provider` это узел, чтобы у ребра `absent-import` было начало                                                                                                                                                                                                                                                                                                                  |
+| T16 | Вклад это два ребра: `owns` от контрибьютора и `contributes-to` к цели                                                                                                                                                                                                                                                                                                                 |
+| T17 | Отказы это собственные классы ошибок рантайма как дискриминированная пара `subject` и `code`                                                                                                                                                                                                                                                                                           |
+| T19 | Схема `opetope.devtools-graph/3` и `opetope.devtools-frame/3`                                                                                                                                                                                                                                                                                                                          |
+| T23 | Враждебный декодер строгий: незнакомые поля и виды отвергаются вместе с записью, аксессоры отвергаются до чтения, а загрязняющие ключи — всегда                                                                                                                                                                                                                                        |
+| T25 | Перф-корпус генерируется и детерминирован по построению: 1 330 узлов / 5 008 рёбер и 26 331 / 70 040                                                                                                                                                                                                                                                                                   |
+| T26 | Структура дерева кэшируется на сессию, display разрешается по нарисованной строке; поиск, проекция и layout мемоизированы по версии стора                                                                                                                                                                                                                                              |
+| T28 | Canary фазы 4. Одиночный flip `when` даёт один кадр `contribution-change` и переводит вклад `published` ↔ `withheld`; закрытие живого приложения снимает его экземпляры и вклады. Оба были сломаны и починены D167; тесты написаны так, чтобы маскировка не повторилась                                                                                                                |
+| T29 | Потребляемый интерфейс принимает те идентификаторы, которые объявляет рантайм. Бренды это необязательные маркеры, поэтому плоская строка принимается и ни один хост не несёт каста; гарантия живёт в валидаторах и декодере                                                                                                                                                            |
+| T31 | Матрица close/detach/GC: утечки в пакете нет. Рост на цикл затухает, а выживающий контейнер держит один из module-level слотов root-а React DOM — `rootWithNestedUpdates` или `rootWithPassiveNestedUpdates`; наблюдался passive, а он есть только в development-сборке. Оба держат по одному контейнеру за раз, оба вне devtools, а панель dev-only, поэтому в проде вопрос не встаёт |
+| T33 | Отключение, которое возвращает подключение, принадлежит launcher-у, владеющему execution: оно срабатывает до close, отсекает панель с поздним импортом и закрывает ровно тот handle, который поставило                                                                                                                                                                                 |
+| T34 | Декодер читает элементы массива по индексу через их собственные дескрипторы: элемент бывает аксессором ровно так же, как поле, а `map` входного массива — метод payload-а, а не наш. Бюджет текста считает UTF-8 байты, а оценки сверху и снизу по длине в code units держат точный подсчёт вне горячего пути                                                                          |
+| —   | Вытеснены: T2, T5, T9–T12, T18, T20–T22, T24, T27, T30, T32 описывали прежние таксономии, бюджеты и открытые вопросы и заменены строками выше и разделами §2, §4 и §6                                                                                                                                                                                                                  |
+
+### 9.2 Панель
+
+| №   | Решение                                                                                                                                                                                         |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| U11 | Пороги виртуализации заданы, а не измерены: 200 строк для списков и инспектора, 300 узлов для layout в Worker                                                                                   |
+| U12 | Линза обрезает содержимое; pan, zoom колесом, кнопки и fit-to-view это способ добраться до того, что вне кадра                                                                                  |
+| U13 | Крошка предка работает как навигация; текущий узел остаётся подписью                                                                                                                            |
+| U14 | Карточки узлов непрозрачны и выше рёбер, поэтому линия не может пересечь бейдж                                                                                                                  |
+| U15 | Экспорт доставляется в буфер обмена или локальный файл по способностям хоста и всегда сообщает исход                                                                                            |
+| U16 | Панель не предлагает действия, которого не может выполнить; статус-бар один раз сообщает, что control plane выключен                                                                            |
+| U18 | Метка это presentation metadata, выведенная из объявления: не идентичность, не право и никогда не имя протокольного поля на экране                                                              |
+| U19 | Одна сворачиваемая легенда для состояний, рёбер и бейджей                                                                                                                                       |
+| U20 | Английский и русский, по умолчанию язык браузера, переключение в шапке; английский словарь — типизированный источник истины                                                                     |
+| U21 | Граница перевода: проза переводится, словарь протокола нет, и протокольные слова вставляются в переведённые предложения                                                                         |
+| U22 | Cap размера панели 20 кБ brotli, поднят с 15 с записанным измерением; headless-консьюмер остаётся под 5 кБ                                                                                      |
+| U24 | Полноту перевода стережёт тест, который рендерит русскую панель по всем поверхностям и падает на непризнанной прозе                                                                             |
+| U26 | Zoom колесом масштабирует по величине жеста; кнопки дают шаг 1.2×; `deltaMode` приводится к пикселям, и один кадр зажат                                                                         |
+| U27 | Протяжка двигает камеру и ничего не выделяет                                                                                                                                                    |
+| U28 | Две вкладки, `Graph` и `Timeline`; прежние линзы становятся чипами фильтра рёбер с четырьмя пресетами                                                                                           |
+| U29 | «Точки расширения» это пресет-проекция в два шага, а не линза: фича → вклады → цели, с переворотом при выборе цели                                                                              |
+| U30 | Ручного переключателя `Graph`/`List` больше нет; список это автоматическая форма ниже 1100 px                                                                                                   |
+| U31 | Статус-бар держит на виду `frame`, `dropped` и `LIVE`, а собственную диагностику панели прячет за «⋯»                                                                                           |
+| U32 | Управление ограничено override условия, на узле группы, через отдельный dev-only write-порт со своей authority                                                                                  |
+| U33 | Control plane, легенда, выгрузка и хронология грузятся по требованию — у каждой свой чанк, свой словарь и свой бюджет размера; панель везёт только то, чем пользуется каждая сессия             |
+| U34 | Поверхность управления скачивается, когда в выделении есть адресуемый портом субъект — группа условий с условием или карантинный экземпляр, — а не просто потому, что порт записи существует    |
+| —   | Вытеснены: U1–U10, U17, U23, U25 описывали глифы v1, поведение канваса по умолчанию, колонку результата поиска и выбор названия пресета точек расширения и заменены строками выше и разделом §4 |
+
+Inspection graph/frame имеют схему `/3` и optional snapshots `opetope.runtime-activity/1`. В пределах одной session
+frame без `activity` сохраняет предыдущую activity; полный snapshot/reset без этого поля очищает наблюдение (D216).
+Frame с `activity` заменяет предыдущую activity целиком.
+Используйте согласованные версии runtime/devtools: readers `/2` отвергают новую revision. Activity указывает execution,
+фактическое поколение feature, физические Calls, точных текущих lane blockers, зарегистрированные leases и попытки загрузок.
+Спрос хоста и UI-модели неизвестны; у stream наблюдается state, но не физические identities загрузок. `freshness`
+и `truncated` отличают полное live-наблюдение от усечённого или отключённого. Закрытая session имеет stale-снимок;
+`closed: true` требует успешного физического drain приложения. Control authority и продуктовые payload не добавляются.
+Размер activity ограничен capacity записей. Сбор снимка обходит зарегистрированных owners, executors и resources,
+поэтому capacity не ограничивает стоимость обхода. Сбор останавливается после доказанного truncation;
+idle executors могут требовать обхода, чтобы подтвердить полноту данных. Обычный call dispatch не создаёт диагностических записей при
+выключенном наблюдении. Frames ограничены существующей ring capacity.