@opetope/runtime 0.1.0

package/docs/how-it-works.ru.md

@@ -0,0 +1,495 @@
+# Как работает Opetope: создание, вычисление, очистка
+
+Статус: **DRAFT**, 2026-09-04. Документ объясняет доступным языком, что происходит в `@opetope/core`, `@opetope/runtime`
+и `@opetope/react` во время работы приложения: что создаётся, когда пересчитывается и как убирается. Нормативный источник — [spec.md](spec.md); здесь только механика и её причины, а пометки `(Dnnn)` ведут в [decisions.md](decisions.md). Ссылки на файлы даны для того, кто захочет проверить утверждение по коду.
+
+## 0. Карта понятий
+
+| Слово                                           | Что это                                                                        | Кто создаёт                                                | Когда умирает                                    |
+| ----------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------ |
+| приложение                                      | список фич, сток ошибок, связанные хостом контракты и условия                  | `defineApplication` + `openApplication`                    | `close()`                                        |
+| условие (`Condition`)                           | именованный `Readable<boolean>`, от которого зависит жизнь группы фич          | `defineCondition`, значение даёт хост или фича-источник    | вместе с приложением                             |
+| фича                                            | определение: `id`, `when`, `imports`, `requires`, `own`, `exports`, `provides` | `defineFeature`, один раз на загрузку модуля               | никогда, это описание                            |
+| экземпляр фичи                                  | живая копия определения: модели, вызовы, ресурсы, вклады                       | runtime, когда фича нужна и её условия истинны             | retire, когда условия ложны или требование снято |
+| модель                                          | запись из `Readable` и `Call`, которой владеет экземпляр                       | фабрика из `own.model()` при открытии экземпляра           | fence и drain экземпляра                         |
+| вызов (`Call`)                                  | операция с очередью, lane, отменой и single-flight                             | `ctx.call` в модели или `call` в `own`                     | отмена при retire                                |
+| ресурс, поток, событие                          | материализация внешних данных с ключом, retention и отменой                    | `ctx.resource`, `ctx.stream`, `ctx.event`                  | закрытие в drain                                 |
+| вклад                                           | что фича вкладывает в чужую цель: слот, pipe, реестр, порт                     | `provides` при открытии экземпляра                         | withdraw в fence                                 |
+| цель (`SlotTarget`, `Pipe`, `Registry`, `Port`) | место, куда вкладывают; живёт вне фич, в файле контрактов                      | `defineSlot`, `definePipe`, `defineRegistry`, `definePort` | никогда                                          |
+
+Три сквозных правила, которые объясняют половину поведения:
+
+1. **Подлинность проверяется по `WeakMap`, а не по форме.** Определение, экземпляр, цель, lane, binding хранятся в
+   закрытых `WeakMap`/`WeakSet`; всё, что туда не попало, отвергается `TypeError('… is not authentic.')`. Поэтому
+   значение фреймворка нельзя подделать литералом.
+2. **Всё, что даёт автор, снимается снапшотом при объявлении** с проверкой точного набора ключей и замораживается.
+   Мутация исходного объекта после этого невидима.
+3. **Порядок всегда канонический.** Фичи по id, вклады по id, импорты по ключу, attachment-ы по слоту; любой разбор
+   идёт в обратном порядке сборки.
+
+## 1. Приложение
+
+### 1.1 Компиляция: `defineApplication({ id, features, reporter })`
+
+Компиляция синхронная и происходит один раз, до открытия чего бы то ни было. Это и есть «compile time» для законов
+графа: ошибка здесь падает в первом же тесте манифеста.
+
+| Шаг | Что происходит                                                                                                                                           | Где                                     |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| 1   | точный набор ключей, `id` строка и уникален среди живых определений процесса (реестр слабый, D127), `reporter` функция                                   | `runtime/src/application-definition.ts` |
+| 2   | мир замыкается: от включённых фич по `imports` до провайдеров, через контракт экспорта                                                                   | там же                                  |
+| 3   | фичи сортируются по id, дубли объекта и id отвергаются                                                                                                   | `runtime/src/application-compiler.ts`   |
+| 4   | рёбра импортов: контракт хоста становится входом приложения, определение фичи резолвится в провайдера                                                    | там же                                  |
+| 5   | рёбра портов `requires ↔ provides`: ровно один провайдер на порт                                                                                         | `application-port-compiler.ts`          |
+| 6   | топологическая сортировка Кана с лексикографическим разрывом связей; цикл жёстких импортов это ошибка                                                    | `application-compiler-graph.ts`         |
+| 7   | проверка времени жизни: для жёсткого ребра `provider.when ⊆ consumer.when`; слабое ребро `optional` от закона включения свободно (D105)                  | `application-compiler.ts`               |
+| 8   | группы по одинаковому набору условий, порядок активации внутри группы и порядок между группами по жёстким рёбрам (D123); план графа для порта наблюдения | там же, `application-group-order.ts`    |
+
+Законы, которые здесь проверяются: один провайдер на контракт и на порт, одна идентичность контракта на id, нет
+провайдера это ошибка, нет циклов, провайдер жёсткого ребра живёт не короче потребителя.
+
+### 1.2 Открытие: `openApplication(app, { cleanupFailure, conditions, imports })`
+
+| Шаг | Что происходит                                                                                                                                                                                                                          |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `imports` принимает только результаты `bind(contract, value)`; каждый контракт хоста связан ровно один раз                                                                                                                              |
+| 2   | `conditions` даёт `Readable<boolean>` на каждое условие без `from`; тип записи выведен из приложения, лишнее и недостающее ловит TypeScript                                                                                             |
+| 3   | `cleanupFailure` необязателен и по умолчанию `report`; `quarantine` заставляет каждый экземпляр этого приложения оставлять провалившуюся уборку повторяемым фронтиром вместо отчёта (D182)                                              |
+| 4   | контроллер стартует в конструкторе: открытие начинается синхронно до первого `await`                                                                                                                                                    |
+| 5   | фичи с пустым `when` открываются **последовательно** в порядке компиляции: `open()`, затем `await ready`, затем следующая                                                                                                               |
+| 6   | условия с `from` вычисляются из экспортов открывшихся фич-источников                                                                                                                                                                    |
+| 7   | для каждой группы условий ставится reconciler: желаемое состояние `all(conditions) === true`; перед открытием группа ждёт готовности провайдеров своих жёстких рёбер из других групп, перед закрытием ждёт ухода их потребителей (D123) |
+| 8   | возвращается `ApplicationExecution` с `ready` и `close()`                                                                                                                                                                               |
+
+Reconciler группы это один сериализованный worker с эпохами: смена условия поднимает эпоху, ограждает незавершённое
+открытие и планирует сверку на микрозадаче; открытие членов идёт последовательно с проверкой актуальности эпохи перед
+каждым, закрытие всегда в обратном порядке и терпимо к ошибкам. Источник условия обязан отдать булево значение
+синхронно при подключении, иначе ошибка сразу.
+
+`close()` однократный: снять подписки условий в обратном порядке, оградить незавершённое открытие, закрыть группы
+в обратном порядке, дождаться `ready`, закрыть постоянные фичи в обратном порядке и собрать отказы в одну ошибку.
+Сессия наблюдения закрывается в `finally` после дренажа и поэтому видит финальные переходы групп, экземпляров
+и вкладов (D167). Общий Promise закрытия существует до вызова любого disposer источника. Если подписка условия
+закрывает приложение до возврата своего disposer, тот снимается сразу после возврата, следующие группы не
+создаются, готовность отклоняется, а close дожидается всей начатой работы (D210).
+
+### 1.3 Время жизни: `when`
+
+Фича объявляет, при каких условиях живёт: `when: [authorized, miningEnabled]`. Пустой `when` это постоянная фича.
+Группа фич с одинаковым набором условий открывается и закрывается вместе, порядок внутри группы задают импорты. Закон
+включения наборов означает простую вещь: нельзя жёстко зависеть от того, кто может умереть раньше тебя. Кто хочет
+читать данные более короткоживущей фичи, берёт слабое ребро `optional` и получает проекцию `Lookup` с состоянием
+`missing` (§2.4); слабое ребро не влияет на активацию провайдера и не тянет его в мир приложения (D106).
+
+## 2. Экземпляр фичи
+
+### 2.1 При определении, один раз
+
+Синхронная форма `defineFeature` выполняет фабрику `own` один раз и строит промежуточное представление из трёх
+видов узлов ядра: scope, attachment, call. Разделённый заголовок объявляет топологию; его `defineFeature.body`
+строит это представление при загрузке кода body (D186, D207). Всё авторское сводится к этим узлам:
+
+| В `own`                                                   | Во что опускается                                                                                                                                                        |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `attach(source, { open, close })`                         | scope с одним attachment-ом                                                                                                                                              |
+| `call({ run, within, lane, once, singleFlight, policy })` | узел call, привязанный к attachment-у из `within`                                                                                                                        |
+| `calls(imports.x, [...])`                                 | неявный attachment на источник без lifecycle плюс один call на ключ                                                                                                      |
+| `lane({ within })`                                        | запись lane, материализуется на экземпляр                                                                                                                                |
+| `effect`, `event`, `resource`, `stream`, `scope.*`        | attachment с контроллером внутри                                                                                                                                         |
+| `requires.x`                                              | один call на скрытом attachment-е требований, который пересылает в провайдера порта; у `optional(port)` он оседает `CallError` `unavailable`, пока провайдера нет (D105) |
+| `model(...)`                                              | **не узел kernel-а**, а описатель данных; фабрика модели здесь не выполняется; владеемое состояние живёт только в модели (`ctx.state`, D139)                             |
+
+`exports` проверяется по форме каждого поля (`Call`, `Readable` или `Resource`), идентичность с `own` намеренно не проверяется; фасад экспортов вычисляется при открытии экземпляра с живым `own` (D88). `provides` выполняется один раз, синхронно, и делится на порты и вклады по тому,
+какой builder породил запись. Каждый attachment фичи критичен: экземпляр не готов, пока не готовы все.
+
+### 2.2 Открытие экземпляра
+
+| Шаг | Что происходит                                                                                                                                                                                                                                                                          | Где                                        |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| 1   | снапшот опций; `imports` и `requirements` содержат ровно нужные поля; вложение берёт значение только из импорта или требования; значение порта проверяется по объявлению                                                                                                                | `runtime/src/feature-generation.ts`        |
+| 2   | создаётся запись экземпляра в состоянии `assembly`                                                                                                                                                                                                                                      | `public-module-instance.ts`                |
+| 3   | **`prepare` синхронно, до открытия первого scope**: регистрация участника отката моделей до запуска фабрик; затем фабрики создают свои узлы, затем фасад экспортов (значения `own` он материализует лениво), затем участник вкладов                                                     | `module-generation.ts`, `feature-model.ts` |
+| 4   | scope открываются последовательно; перед каждым проверяется, не запрошена ли отмена                                                                                                                                                                                                     | `module-generation.ts`                     |
+| 5   | внутри scope вложения одна волна без порядка между ними (D163): критичные стартуют до коммита владельца, готовность считается счётчиками, без рекурсии в промисы; когда критичных не осталось, scope публикует авторитет владельца, вызовы становятся живыми, затем стартуют отложенные | `module-scope-open.ts`                     |
+| 6   | внутренняя ready barrier отдаёт `{ exports }`; затем публикуются вклады, и только после успешной публикации разрешается публичный `instance.ready`                                                                                                                                      | `feature-generation.ts`                    |
+
+Законы: `prepare` обязан вернуться синхронно; участники retire регистрируются до первого открытия scope; отказ критичного attachment-а сразу переводит scope в retire, отказ отложенного не трогает остальные и оставляет scope готовым; отказавшее вложение попадает в карантинный фронтир в каноническом порядке слотов.
+
+Attachment изнутри это маленькая машина с почтовым ящиком: не больше одного активного и одного ожидающего намерения;
+новое намерение либо присоединяется к совместимому, либо заменяет ещё не начатое, либо встаёт в очередь и отменяет
+активное. Открытие берёт разрешение у контроллера готовности, собирает список уборок (первая всегда `close`), и любая
+ошибка откатывает попытку в обратном порядке уборок.
+
+### 2.3 Retire: fence, drain, settle
+
+```text
+retire()  →  fence (синхронно, один проход)  →  drain (асинхронно, параллельно)  →  settle (политика)
+```
+
+1. **Fence.** Состояние `retiring`. Участники в порядке регистрации: вклады снимаются с целей, scope данных
+   ограждается: модели переводятся в неактивные, `AbortController` срабатывает, ячейки `state` закрываются. Затем
+   ограждается каждый scope. Ограждение это то, что превращает любую последующую работу в отмену: авторитет вызовов
+   недействителен, новый вызов через этот attachment завершается `CallError` как отмена, а не как продуктовая ошибка.
+   Ничего не бросается, только собираются фронты уборки.
+2. **Drain.** Все фронты запускаются параллельно; вложения одного scope дренируются целиком одной волной, порядка между ними нет (D163). Вызовы: ожидающие отменяются, исполняющиеся
+   получают abort, кэш `once` и карта single-flight очищаются, аренды lane отпускаются. Таймеры: реестр закрывается,
+   после закрытия `delay` и `interval` бросают. Подписки моделей и disposer-ы выполняются, отказы собираются.
+3. **Settle.** Без отказов: состояние `retired`, все цели вызовов отозваны, ссылки сброшены, результат `closed`. С
+   отказами при политике `report` (по умолчанию): экземпляр всё равно терминальный, а `FeatureError` с кодом
+   `cleanup-failed` уходит в `reporter`. При политике `quarantine`: результат `quarantined`, `FeatureError` с кодом
+   `quarantined` и необязательной capability `retryCleanup()`, повторяющей ровно оставшийся фронт уборок под защитой от повторного входа.
+
+Retire идемпотентен и не может быть запущен из собственного колбэка.
+
+Публичный экземпляр называет эту операцию `close()`; внутренние координаторы сохраняют `retire`. Логическая
+отмена завершает ожидание, но не доказывает, что выполняющийся `open` или вызов физически остановился.
+Дренаж присоединяется к уже допущенной работе и её поздней уборке до освобождения источника. Стрим также ждёт
+активный `consume` до закрытия соединения и освобождения импортированного значения (D170).
+
+### 2.4 Рёбра между фичами
+
+| Ребро                     | Что видит потребитель                                                                                                                                                                                                                   | Кто гарантирует безопасность                                                                           |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `imports: { x: feature }` | живые `Call`, `Readable`, `Resource` экземпляра провайдера                                                                                                                                                                              | порядок: провайдер раньше, потребитель закрывается раньше                                              |
+| `optional(feature)`       | `Readable<Lookup<Exports>>`: `found`, пока экземпляр провайдера открыт, `missing`, пока он закрыт или его нет в приложении                                                                                                              | одна подписка у потребителя; ребро не влияет на активацию провайдера и не тянет его в мир (D105, D106) |
+| `optional(port)`          | `Call`, который оседает `CallError` с кодом `unavailable`, пока нет живого провайдера порта                                                                                                                                             | тот же слабый закон (D105)                                                                             |
+| контракт хоста            | значение, связанное `bind` при `openApplication`; `optional(contract)` даёт `Readable<Lookup<T>>` с `missing`, если хост его не связал; `onDemand(contract)` отдаёт значение как есть и откладывает связывание до первого использования | хост                                                                                                   |
+| порт `port`               | `Call`, провайдера выбрало приложение                                                                                                                                                                                                   | компилятор: ровно один провайдер                                                                       |
+
+Модели через границу фич не ходят никогда: UI-закон «модель читается только внутри своей фичи» держится именно на
+этом.
+
+## 3. Модель и её kernel
+
+### 3.1 Когда что создаётся
+
+| Шаг | Что происходит                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `own.model(Decl, deps?, factory)` при определении только записывает описатель; фабрика не выполняется                                                                                                                                                                                                                                                                                                                     |
+| 2   | при открытии экземпляра, внутри `prepare`, описатели обходятся в порядке объявления: `model` получает свежий kernel с id `<feature>.model.<n>`                                                                                                                                                                                                                                                                            |
+| 3   | kernel это контроллер готовности (он же ограждение модели), реестр таймеров на общем `AbortSignal`, списки исполнителей и disposer-ов                                                                                                                                                                                                                                                                                     |
+| 4   | фабрика выполняется **синхронно**; каждый `ctx.call`, `ctx.calls(source, keys, { lane? })` (те же правила выбора, что у `calls` в `own`: метод `(input, signal) => Output` источника становится `Call`, D143), `ctx.effect`, `ctx.resource`, `ctx.stream`, `ctx.event`, `ctx.scope`, `ctx.lane`, `ctx.state` создаёт узел немедленно с id `<model>.<kind>.<n>`; `ctx.cleanup(disposer)` регистрирует уборку модели (D107) |
+| 5   | возвращённая запись замораживается и кладётся под ref описателя                                                                                                                                                                                                                                                                                                                                                           |
+| 6   | fence модели: готовность снята, таймеры закрыты, затем abort и закрытие ячеек; drain: retire исполнителей, затем все disposer-ы модели в обратном порядке регистрации, отказы репортятся; регистрация после фенса это `TypeError`                                                                                                                                                                                         |
+
+Описатель зависимостей — запись подлинных импортов и call refs текущей фичи. Материализация один раз разрешает
+её в readonly-запись перед фабрикой; optional-импорты остаются lookup-readable. Форма без зависимостей —
+`model(Decl, factory)`. Refs моделей не образуют граф зависимостей. Порт из модели один раз выбирает вызов после
+создания модели и ограничивает фенсом экземпляра-провайдера даже переданный напрямую вызов (D169).
+
+Kernel получает владельца отката до входа в пользовательский код, поэтому узлы фабрики дренируются, даже если
+она после их создания бросила. То же правило держат per-mount UI-модели. Фенс синхронно закрывает каждое
+владеемое состояние и отвергает последующие конструкторы узлов; поздний вызов, таймер или подписка не могут
+выйти за это время жизни (D170).
+
+### 3.2 `state` и `update`
+
+`ctx.state(initial)` возвращает `OwnedState<Value>`, это `Readable` с брендом владения. `ctx.update(state, value)`
+принимает только его: производный `Readable` не компилируется, а `OwnedState` соседней модели отвергается
+в рантайме по приватной записи владельца. Запись после
+ограждения не бросает у писателя, а репортится `FeatureError` с кодом `retired`. Равные по `Object.is` записи молчат.
+
+### 3.3 Вызов: `ctx.call({ run, lane?, once?, singleFlight?, policy? })`
+
+`ctx.call(options)` создаёт команду; `context.invoke(target, input)` в callback `run` исполняет существующую.
+Поле исполнения называется `invoke` во всех контекстах, которые его предоставляют, включая доверенные шаги
+attachment; фабричный `call` и sugar выбора методов `calls` сохраняют имена (D243).
+
+Выбранный метод хоста может не иметь параметров, принимать один input либо input и `AbortSignal`, включая
+необязательные input/signal (D244). Runtime вызывает каждый метод с `(input, signal)` и исходным receiver.
+Число параметров функции не проверяется; единственный параметр всегда input. Физическая работа, игнорирующая
+отмену, остаётся частью drain, даже если вызывающий уже завершился отменой.
+
+Политика `queue` по умолчанию сериализует вызовы через lane, `latest` сериализует так же, но держит одно место
+ожидания, `parallel` запускает сразу; `parallel` с `lane` запрещён. На каждый вызов:
+
+1. если родительский или собственный сигнал уже отменён, возвращается отменённый вызов;
+2. закрытый исполнитель или ограждённый экземпляр дают отмену;
+3. попадание в кэш `once` возвращает уже решённый результат;
+4. попадание по ключу `singleFlight` присоединяется к живому исполнению;
+5. иначе новое исполнение: `parallel` стартует немедленно, `queue` и `latest` берут аренду lane в FIFO, а если lane
+   уже на вершине стека вызывающего, переиспользуют её без ожидания;
+6. `latest` сначала освобождает своё место ожидания: invocation того же вызова, который всё ещё стоит на lane
+   последним, отменяется до того, как этот запросит аренду, поэтому ожидающий вход один, а порядок lane не меняется
+   (D185).
+
+Вложенный `context.invoke(target, input)` наследует время жизни авторитета и стек lane, поэтому отмена родителя
+отменяет ребёнка, а lane не образует цикла: запрос lane, лежащей ниже вершины стека, это ошибка цикла, как и
+присоединение к собственному исполнению.
+
+### 3.4 `effect` и `timers`
+
+`ctx.effect({ from, run, when?, onDispose? })` подписывается на источник и сразу выполняется для начального
+значения. Внутри один сериализованный цикл: новое значение отменяет текущее исполнение, ждёт его disposer, проверяет
+`when`, создаёт новый `AbortController` и реестр таймеров и запускает `run`. Промежуточные значения теряются:
+живёт только последнее. `run` возвращает `void` или disposer.
+
+`ctx.timers.delay(ms, run)` и `ctx.timers.interval(ms, run)` регистрируют отмену в реестре модели; после закрытия
+реестра оба бросают.
+
+### 3.5 UI-модели вклада
+
+Вклад в слот может объявить `models: [model(Decl, (ctx, props) => …)]`: планы, которые frame вклада инстанцирует на
+каждое монтирование. `props` это `Readable` пропсов слота именно этого монтирования, kernel такой модели живёт от
+монтирования до размонтирования. Закон: экземпляры создаются в коммите и никогда в рендере (D188). Первый проход
+вклада не рендерит ничего, `useLayoutEffect` с ключом по идентичности вклада собирает монтирование из тех пропсов,
+которые закоммитились, и публикует его, а React сбрасывает этот дополнительный синхронный рендер до paint; идентичность
+вклада владеет монтированием до реальной замены или размонтирования. Брошенный рендер — двойной вызов StrictMode, прерванный concurrent-проход,
+поддерево, приостановленное ленивым соседом, — не создаёт ничего, поэтому нет ни подметания, ни усыновления, ни
+пересборки, а layout-эффект ребёнка всегда видит живую модель. Входящие пропсы слота доходят до живого
+монтирования своим layout-эффектом, поэтому прерванный рендер по-прежнему не может писать в модель.
+Выдача моделей гибридная (D158): модели `own` фичи монтирование выдаёт неявно любому компоненту своего поддерева, а per-mount модель вклада объявляет через `requiresModels([X])` тот компонент или хук того же модуля, который читает её `useModel(X)`. Объявление принадлежит каждому читателю, а не только месту вклада (D117).
+
+Повтор эффектов StrictMode и скрытие/раскрытие Suspense используют тот же закоммиченный набор моделей и сохраняют
+состояние. Реальная замена или размонтирование освобождает его один раз; при размонтировании скрытого поддерева
+это делает микрозадача, потому что React уже отключил layout-эффекты. Insertion effects отмечают retire без
+уведомления Readable (D209).
+
+Смонтированная модель читает пропсы из состояния монтирования. Прямые пропсы и необязательный props-адаптер
+читают тот же снимок; входящие пропсы слота публикуются в layout до paint. В insertion effects состояние не
+обновляется. Retry спроса хранит идентичность источника, поэтому незавершённый retry заменённого источника
+не блокирует и не перезаписывает retry нового (D170).
+
+## 4. Реактивность
+
+### 4.1 Контракт и источники
+
+```ts
+interface Readable<T> {
+  getSnapshot(): T;
+  subscribe(listener: () => void): () => void;
+}
+```
+
+Слушателю ничего не передают, он перечитывает. Ячейка состояния (`createState`, с D142 только на internal; автор получает её как `ctx.state` модели) хранит значение и множество слушателей; `set` и `update`
+молчат при равенстве по `Object.is`; после `close()` чтение и запись дают `ReadableError` с кодом `closed`. Закрытие распространяется: `close()` это одно уведомление зависимым узлам, после которого активные `derive`, `computed`, `collection` и `selectByKey` отвечают `closed` вместо последнего значения и дальше молчат; неподписанный производный узел получает тот же отказ при следующем чтении (D146).
+
+### 4.2 `derive` и `computed`
+
+Оба это узлы одного графа с моделью «инвалидация толчком, пересчёт вытягиванием»: у узла свежесть `clean`, `check`,
+`dirty` и монотонная ревизия. Неподписанный узел пересчитывается по требованию при `getSnapshot()`, подписки вверх не
+нужны. Узел становится активным, когда у него есть слушатели или зависимые, и деактивируется с задержкой в одну
+микрозадачу, чтобы переподписка в том же тике не сбрасывала аренду вверх.
+
+`computed({ read: get => … })` на каждом пересчёте строит карту зависимостей заново по вызовам `get` и запоминает их
+ревизии; в состоянии `check` тело не выполняется, если ни одна ревизия не сдвинулась. Повторный вход в вычисление это
+ошибка «цикл». Смена `error → value` считается изменением даже при равном значении.
+
+### 4.3 Один scheduler
+
+Глитчей нет структурно: единственный scheduler перед публикацией стабилизирует все ожидающие узлы в топологическом
+порядке, и только потом зовёт слушателей. Инвалидация и обход итеративные, цепочка в тысячу узлов не переполняет стек. Чтение активного чистого узла
+возвращает осевшее значение без обхода графа, O(1) вместо O(графа), и это закреплено бюджетом `coreData.settledRead`
+(D130). Активация транзакционна: если узел не смог активироваться, уже активированные узлы откатываются в обратном
+порядке, а отказы диспозеров при откате агрегируются с исходной причиной, так что часть графа не остаётся активной
+без владельца подписки (D134).
+
+Когда слушатели узнают об изменении:
+
+| Источник                                           | Когда                                                               |
+| -------------------------------------------------- | ------------------------------------------------------------------- |
+| прямые слушатели `State.set`                       | синхронно, внутри транзакции записи                                 |
+| `derive` и `computed` ниже по графу от этой записи | синхронно в конце `set()`: транзакция закрывается и сливает очередь |
+| внешний источник без открытой транзакции           | открывает свою транзакцию, то же самое                              |
+| инвалидация без транзакции                         | следующая микрозадача                                               |
+| вложенные записи                                   | одна публикация на внешней границе транзакции                       |
+
+### 4.4 Коллекции
+
+`collection({ from, key, project })` держит кэш проекций по объекту элемента, стабильные lookup-и по ключу и слушателей
+по ключу: `selectByKey(source, key)` пробуждается только когда меняется его ключ. Дубликаты ключей это ошибка.
+Неиспользуемые селекторы вычищаются через микрозадачу.
+
+### 4.5 Хуки
+
+| Хук                          | Механика                                                                                                                                                                                                                                                                                                                     |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useReadable`, `useSelector` | `useSyncExternalStore` с кэшем выбранного значения; один и тот же getter для клиента и сервера                                                                                                                                                                                                                               |
+| `useResource`                | `useSyncExternalStore` по снапшоту плюс `retain()` в эффекте: монтирование и есть аренда                                                                                                                                                                                                                                     |
+| `useModel`                   | ближайший frame монтирования вклада; вне frame `ContributionError` `missing`, неактивное монтирование `inactive`, чужая модель `missing`                                                                                                                                                                                     |
+| `useCommand`                 | состояние на потребителя, без слушателя на invoker: `run` возвращает промис исхода, `inFlight` на время вызова, `result` последний исход `ok` и переживает следующий запуск, `lastError` ошибка последнего `failed`, очищается только успехом и не сбрасывается стартом повтора (D116); отмена не меняет ни того, ни другого |
+
+`useCommand` держит статус отдельно для хука и invoker и ничего не планирует: каждый `run` доходит до вызова, и
+объявленная политика вызова решает, встанет ли он в очередь, заменит ожидающий вход или пойдёт параллельно (D203).
+У каждого запроса свои callbacks и abort-подписка, уже отменённый signal отвергается, не доходя до вызова, и `run`
+размонтированного потребителя отвергается так же. `inFlight` истинен, пока не завершился хоть один начатый им прогон.
+
+## 5. Ресурсы, потоки, события
+
+И фича, и модель выбирают target через `(source) => Readable<T | null | undefined>`; возвращённый объект
+проверяется до начала работы. Скалярный snapshot контракту не соответствует. `retention` необязателен в обоих
+контекстах, а `scoped({ capacity })` фиксирует LRU-вытеснение (D169).
+
+### 5.1 `resource(from, target, { key, load, retention, retry })`
+
+| Шаг | Что происходит                                                                                                                                                                                                                            |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | retention `scoped({ capacity })` активирует контроллер сразу, ресурс тёплый без наблюдателя; retention `observer` — литерал `{ kind: 'observer' }` и значение по умолчанию — активирует по первой аренде (D160)                           |
+| 2   | активация подписывает на `target` и читает его; `null` цель закрывает выбор                                                                                                                                                               |
+| 3   | смена ключа: тот же ключ обновляет цель без перезагрузки; новый ключ ограждает исполнение, поднимает эпоху ключа и берёт из LRU-кэша, если есть, иначе публикует `opening` (без данных) или `refreshing` (с устаревшими данными) и грузит |
+| 4   | `load(target, { signal, source })`; результат принимается только если исполнение, эпоха ключа и активность не сменились                                                                                                                   |
+| 5   | ошибка: повтор по `retry: { attempts, delayMs }`, затем `status: 'error'` с `retryable: true` и отчёт в `reporter`                                                                                                                        |
+| 6   | последняя аренда снята при `observer`: деактивация через микрозадачу с защитой ревизией                                                                                                                                                   |
+| 7   | закрытие в drain: ограждение, отписка, очистка кэша, `idle`, ожидание незавершённых операций                                                                                                                                              |
+
+`refresh()` перезагружает тот же ключ мимо кэша, сохраняя данные; `retry()` только из `error`; `invalidate()` чистит
+кэш и перезагружает без сохранения данных.
+
+### 5.2 `stream(from, target, { connect, consume, key, backpressure })`
+
+Та же машина ключей и эпох плюс слой допуска из одного слота: единственная политика `latest()` держит только новейшее ожидающее значение (D160).
+Каждое значение сначала кэшируется и публикуется как `ready`, затем передаётся в авторский `consume`. При смене ключа
+новое подключение ждёт завершения disposer-а старого: соединения не перекрываются. `backpressure` обязателен.
+
+### 5.3 `event(from, subscribe, { run, backpressure })`
+
+Очередь на один слот перед последовательным `run`, и опция говорит, кому принадлежит слот. Без `backpressure` он
+принадлежит payload, который занял его первым: пока `run` занят и один payload ждёт, новый `emit` отбрасывается и
+репортится записью отказа `queue-capacity` — это drop-newest, форма `exhaustMap` и `takeLeading`. С
+`backpressure: latest()` новый payload заменяет ожидающий, и ничего не репортится — это склейка, форма `conflate`;
+в отличие от `switchMap` она никогда не прерывает уже идущий `run` (D247). Очередь без потерь это ни та, ни другая
+политика, и она остаётся открытым вопросом (D183). `run` выполняется последовательно, обязан вернуть `undefined`,
+ошибки после отмены глотаются. Отмена владельца закрывает очередь и отбрасывает то, что в ней ждёт, а закрытие ждёт
+disposer и слив очереди.
+
+## 6. Вклады и слоты
+
+### 6.1 Публикация
+
+| Шаг | Что происходит                                                                                                                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1   | при определении `provides` даёт непрозрачные объявления `{ target, value, priority, when }`; значение всегда нормализовано в фабрику экземпляра                                |
+| 2   | каждому вкладу назначается id `<feature>.<key>`, один ключ на объявление                                                                                                       |
+| 3   | компилятор перечисляет вклады по id                                                                                                                                            |
+| 4   | в `prepare` регистрируется участник retire, чей fence снимает публикацию; запоминается авторитет: модели экземпляра                                                            |
+| 5   | **после `ready`** фабрики выполняются с контекстом экземпляра, значение помечается владельцем, `when` резолвится: предикат становится одним computed-readable этого экземпляра |
+| 6   | все затронутые цели обновляются **в одной транзакции**, слушатели зовутся после                                                                                                |
+
+Порядок записей: `priority` по возрастанию, при равенстве по id. `when` (`Readable<boolean>` либо предикат
+экземпляра, который рантайм понижает в такой readable): запись с `false` не
+входит в `entries`, поэтому `Slot`, `fold`, `select` и проверки пустоты её не видят; переключение публикует одной
+транзакцией; уникальность id проверяется по всем опубликованным, так что переключение не может упасть на проверке. Публикация
+атомарна: подписка на `when` и его чтение идут в preflight до любой мутации целей, освобождение наблюдателя ушедшей
+записи идёт после фиксации всех целей, а читает публикация только `when` своих записей, поэтому снятие не читает их
+вовсе (D225). Отказ откатывает добавленных наблюдателей и оставляет цели нетронутыми, `when`, подавший сигнал во
+время проекции, заставляет затронутые цели спроецироваться заново, а снятие публикации, не дошедшей до `published`,
+убирает то, что успело лечь (D124).
+
+### 6.2 Рендер вклада
+
+`Slot` читает `entries` цели через `useReadable`, при пустом списке даёт `null`, иначе рендерит `Component` каждой
+записи с пропсами слота, оборачивая в frame авторитета фичи-контрибьютора: внутри вклада `useModel` достаёт модели
+своей фичи и ничего чужого. Вклад без моделей не платит за frame. Вклад это `{ Component, props?, models? }`:
+`props` переводит пропсы слота в собственные пропсы компонента, `models` даёт per-mount UI-модели, а компонент с
+`requiresModels([...])` объявляет, какие из них ему нужны, и это сверяется типом на границе вклада. Монтирование мемоизировано: публикация или
+снятие одного вклада не перерисовывает остальные монтирования той же цели (D130).
+
+### 6.3 `fold` у pipe
+
+`fold(value, meta, read?)` проходит обработчики по порядку; с переданным читателем внутри `computed` в зависимости
+попадают и список записей, и всё, что прочитали обработчики через свой `{ read }`, поэтому результат пересчитывается
+при смене их источников, а не только при перерегистрации вкладов. Без читателя чтение нетрекаемое.
+
+Обработчик объявляется дескриптором, `pipe(target, { fold })`, и рантайм связывает с ним один контекст вычисления в
+момент публикации вклада: `exports`, `imports` и материализованный `own` разрешаются один раз, от вызова к вызову
+меняется только читатель, поэтому свёртка по многим обработчикам не аллоцирует контекст на обработчик (D223).
+Обработчик запускает только свёртка: объявление, предзагрузка и публикация его не вызывают.
+
+### 6.4 Реестр
+
+`defineRegistry` это цель поверх `collection`: `byId`, `list`, `select(key)` с `{ kind: 'found' | 'missing' }`.
+Дубликат ключа это ошибка.
+
+## 7. Ошибки
+
+Один класс на субъект, состояние в поле `code`.
+
+| Класс                  | Коды                                                         | Кто бросает                                                                                              |
+| ---------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `FeatureError`         | `retired`, `not-ready`, `quarantined`, `cleanup-failed`      | ограждение экземпляра, неудачное открытие, settle retire                                                 |
+| `CallError`            | `cancelled`, `closed`, `publication-rejected`, `unavailable` | kernel вызовов; отмена это только `cancelled` и `closed` (D138)                                          |
+| `ReadableError`        | `closed`                                                     | чтение и запись закрытой ячейки                                                                          |
+| `DeclarationError`     | `invalid-id`                                                 | `declarationId`                                                                                          |
+| `ApplicationError`     | `closed`                                                     | приложение закрыто до готовности                                                                         |
+| `ContributionError`    | `binding-invalid`, `duplicate`, `inactive`, `missing`        | монтирование вклада: хук вне frame, неактивный frame, дубль модели, неверная привязка модели или команды |
+| `CancellationError`    | без кода, только бренд отмены                                | авторская отмена, которую `isCancellation` распознаёт                                                    |
+| `FeatureBoundaryError` | `missing`                                                    | `useFeatureRetry` вне error-поддерева boundary                                                           |
+
+Отмена это свойство ошибки, а не класса: предикат `isCancellation` (internal, автору не нужен — отмену читают `useCommand` и `resource`) смотрит на бренд, который несут `CancellationError`, `CallError` с кодами `cancelled` и `closed`, `FeatureError` с кодом `retired` и `ContributionError` с кодом `inactive`. `unavailable` и `publication-rejected` это ответы продукта: `useCommand` показывает их исходом `failed` с ошибкой в `lastError`, `resource` показывает их ошибкой (D138). `useCommand` и `resource` не показывают отмену как
+ошибку пользователя.
+
+Путь ошибки к приложению: `reporter` из `defineApplication` передаётся в каждый `openFeature`, оттуда в kernel-ы
+моделей, таймеры и контроллеры; единая воронка `reportRuntimeFailure` при отсутствии или падении `reporter` уходит в
+глобальный `reportError` или в отложенный `throw`. Отказы группы условий в работе уходят в `reporter`; удерживаются и бросаются из `close()` только те, что случились уже после начала закрытия.
+
+## 8. Границы и хост
+
+В таблице повседневные входы; полные списки экспортов — в spec.md §3.
+
+| Вход                         | Кому                                     | Что там                                                                                                                                                                                                                                          |
+| ---------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@opetope/core`              | автор фичи                               | `defineModel`, `definePort`, `definePipe`, `defineRegistry`, `declarationId`, `derive`, `computed`, `externalReadable`, `collection`, `selectByKey`, ошибки, типы `Readable`, `Lookup`, `Call`, `Port`, `ModelContext`, `OwnedState`, `Resource` |
+| `@opetope/runtime`           | автор фичи и хост                        | `defineFeature`, `defineHostContract`, `onDemand`, `optional`, `openFeature`, `defineCondition`, `defineApplication`, `openApplication`, `bind`, `scoped`, `latest`                                                                              |
+| `@opetope/react`             | автор компонентов                        | `useModel`, `useReadable`, `useSelector`, `useCommand`, `useResource`, `defineSlot`, `defineSwitchSlot`, `Slot`, `requiresModels`                                                                                                                |
+| `@opetope/react/integration` | хост                                     | `FeatureBoundary`, `useFeature`, `useFeatureRetry`, `FeatureBoundaryError`                                                                                                                                                                       |
+| `@opetope/react/testing`     | тесты                                    | `renderSlot`, `command`, `createScenario`, `ScenarioTimeoutError`                                                                                                                                                                                |
+| `@opetope/*/internal`        | реализация фреймворка и интеграция хоста | kernel, компилятор, контроллеры, `createState`, `isCancellation`, порт наблюдения `createInspectionSession` и порт управления `createControlSession`; авторам недоступно (D142)                                                                  |
+
+Поле `exports` в `package.json` открывает точные входы без wildcard. Авторы фич используют безопасные входы;
+интеграция хоста и тесты — свои выделенные входы. Правила импортов приложения сохраняют это разделение ролей.
+
+Хост с управлением по спросу показывает UI фичи так: `FeatureBoundary` берёт аренду на экземпляр через `useFeature`, открывает его при
+необходимости, показывает `fallback` пока открывается и `error` при отказе, а внутри рендерит `<Slot target props />`,
+куда фича вложила свой UI. Размонтирование boundary отпускает аренду; последняя отпущенная аренда ведёт к retire.
+
+### 8.1 Наблюдение
+
+Порт наблюдения (D122) живёт на `@opetope/runtime/internal`: `createInspectionSession(execution, { ringCapacity })`, где
+`execution` это результат `openApplication`. Связь держит `WeakMap`, глобального хука и публичного значения нет, сессия
+на приложение одна. Пока сессия не открыта, приложение ничего не записывает; `close()` снимает наблюдателя, не трогая
+приложение. Потребитель получает ровно четыре метода, `getSnapshot`, `readSince`, `subscribe` и `close`, и не может
+управлять графом, который читает. Протокол `@opetope/devtools` рантайм реализует, а не импортирует; соответствие
+держит гейт `ci:inspection`.
+
+Оба порта остаются на `/internal`, потому что вызывает их пакет `@opetope/devtools`, а не приложение. Хост
+подключает панель через `installDevtools({ execution, … })` и ради ничего другого на этот вход не заходит (D248).
+
+### 8.2 Управление
+
+Порт записи это вторая, отдельная фабрика на том же входе: `createControlSession(execution)` (D176). Держать сессию
+наблюдения не значит иметь право писать, поэтому у них свои реестры и своя authority. Единственный управляемый
+субъект — условие и через него его группа: `suspend(conditionId)` ставит debug-override, принудительно читающий
+условие как `false`, `resume(conditionId)` его снимает, и группа снова следует собственному источнику. У фичи без
+`when` условия нет, поэтому адресовать её нечем — devtools не становится источником времени жизни, которого в плане
+нет.
+
+Override оборачивает собственный `Readable` условия, поэтому приостановленная группа гаснет обычной транзакцией: тот
+же планировщик, тот же атомарный кадр и закон зависимостей
+[devtools.md §5.3](devtools.ru.md) — приостановка провайдера уводит
+жёстких зависимых их собственной семантикой, а приостановка потребителя провайдера не трогает. Кадр, который
+публикует переход, называет команду управления своей причиной, поэтому «что я сделал» и «что случилось» читаются
+одной лентой, а снимок группы показывает override рядом с продуктовой правдой: `desired.source` — что говорит
+условие, `desired.effective` — по чему действует рантайм, `desired.override` — `force-inactive`, пока override стоит.
+
+`retryCleanup(instanceId)` повторяет уборку ровно карантинного фронтира через существующий retry-контракт; экземпляр
+без карантина отвечает `not-controllable`. Отказ это данные, а не исключение:
+`{ kind: 'rejected', reason: 'not-controllable' | 'stale' | 'unknown-target' }`, а применённая команда отвечает
+номером кадра, в котором виден эффект. `close()` снимает все override сессии, поэтому закрытая панель не оставляет
+приложение в отлаженном состоянии, а сам override живёт только в текущем execution и не переживает reload и HMR.
+
+## 9. Как это проверять
+
+- Экземпляр фичи в тесте: `openFeature(feature, { imports, reporter })`, затем `ready`, затем `close()`; фейки
+  контрактов хоста это обычные объекты.
+- Компонент вклада: `renderSlot(target, { props, models })` монтирует вклад с фикстурой per-mount моделей и даёт
+  `updateProps`; `command(run)` минтит подлинный `Call` для фикстуры.
+- Граф приложения: `defineApplication` в тесте манифеста ловит отсутствие провайдера, цикл и нарушение включения
+  наборов условий до старта.
+- Бюджеты и гейты: `ci:public-surface` считает публичные слова и запрещает kernel- и retired-слова на безопасных
+  входах; `ci:perf-memory` меряет удержанную память, слушателей и линейность стоимости операций, включая `coreData.settledRead` и аллокации записи без слушателей (`unobservedWrite`, медиана из трёх прогонов по 100k операций); `ci:type-stress` меряет стоимость типов, латентность языковой службы печатается только информационно, а инстанцирования, память и диагностики проверяются как обязательные бюджеты (D224); `ci:browser-floor` держит синтаксис и API уровня
+  Chrome 82; `ci:inspection` проверяет контракт порта наблюдения; `ci:size-limit` держит пять бюджетов, которые видит автор (core `author primitives consumer` 1.1 и `data layer consumer` 4.9 кБ, runtime `public feature consumer` 32 и `application graph consumer` 48 кБ, `@opetope/react` 18 кБ).
+- Проверка авторского кода: каждый компонент и хук модуля, который читает per-mount модель вклада через
+  `useModel(X)`, объявляет `requiresModels([X])`; owner-модели читаются без объявления (D117, D158). Импорты используют
+  входы пакетов, разрешённые для своей роли.
+- Проверка сборки приложения: хост-потребитель проверяет бюджеты своего бандла и сохранение задуманных dynamic
+  boundaries после сборки; size-фикстуры пакетов не измеряют приложение целиком.