@opetope/runtime 0.1.0

package/docs/agent-guide.ru.md

@@ -0,0 +1,208 @@
+# Opetope: гайд для агентов и людей, пишущих код на фреймворке
+
+Короткий, проверяемый документ: как принять решение о форме кода, что запрещено и какую ошибку вы увидите, какие
+проверки запускать. Подробности в [cookbook.md](cookbook.md), устройство в [how-it-works.md](how-it-works.md),
+законы в [spec.md](spec.md).
+
+## 1. Где что лежит
+
+Разделяйте композицию фичи, реализации моделей и UI на отдельные слои. Пути ниже показывают структуру
+`features/<f>/{integration,models,ui}`; хост владеет объявлением приложения и привязками, которые передаёт при его
+открытии. Границы зависимостей действуют независимо от названий каталогов.
+
+| Что пишете                                                                                     | Куда                                                                                                                                             | Импортирует                                                                                           |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| контракты (`defineHostContract`, `definePort`, `defineSlot`, `defineModel`, `defineCondition`) | `features/<f>/integration/platform/*.contract.ts`, `ui/**/contracts.ts`, `slots.ts`; consumer владеет target-контрактом, фича — значением вклада | `@opetope/core`, `@opetope/runtime`, типы; `@opetope/react` для UI slot targets                       |
+| фича (`defineFeature`)                                                                         | `features/<f>/integration/platform/feature.ts(x)`                                                                                                | контракты, свои модели/UI, `@opetope/runtime`                                                         |
+| модели (`defineModel` + фабрики)                                                               | `features/<f>/models/**`                                                                                                                         | `@opetope/core`                                                                                       |
+| UI вкладов (`requiresModels`, хуки)                                                            | `features/<f>/ui/**`                                                                                                                             | `@opetope/core`, `@opetope/react`                                                                     |
+| композиция приложения и интеграция с хостом                                                    | слои bootstrap и integration приложения                                                                                                          | `@opetope/runtime`, `@opetope/react/integration`; internal-входы только для низкоуровневой интеграции |
+
+Оставляйте `internal`-входы и `@opetope/react/integration` в реализации рантайма, интеграции с хостом и тестах.
+UI фичи и реализации моделей не должны импортировать `@opetope/runtime`, реализацию другой фичи или собственный
+слой integration. Закрепите эти границы зависимостей статическими проверками проекта-хоста.
+
+## 2. Как выбрать форму (чеклист перед `defineFeature`)
+
+1. Что мне дают снаружи? Хост → `defineHostContract` + `imports`. Другая фича → `imports: { x: feature }` (жёстко) или
+   `optional(feature)` (может отсутствовать или выключаться). Возможность по имени → `requires: { p: port }`.
+2. Когда я живу? Всегда → без `when`. При условии → `when: [condition]`; условие объявляет хост
+   (`defineCondition({ id })`) или другая фича (`defineCondition({ from, id, select })`).
+3. Что я делаю? Вызовы хоста → `calls(imports.x, [...])`; свой процесс → `call({ run, lane?, once?, singleFlight?,
+policy?, within })`; данные по ключу → `resource`; поток → `stream` с `latest()`; внешние события → `event`;
+   реакция на изменение → `effect`; подпроцесс при условии → `scope.while`; модель с состоянием → `model(Decl, { source: imports.source }, (ctx, { source }) => …)`.
+4. Что я отдаю? Другим фичам → `exports` (`Call | Readable | Resource`, поля модели, не модель). Приложению →
+   `provides.port`. Интерфейсу → `provides.slot/pipe/register`.
+5. UI? Только вклад в слот. Компонент объявляет per-mount модели через `requiresModels([...])`; модели `own` доступны сами.
+
+Фича с тяжёлой реализацией пишется заголовком и телом: заголовок держит `id`, `imports`, `requires`,
+`provides` как метаданные, `when` и `body: () => import(...)`, а файл тела пишет
+`defineFeature.body(header, { own, exports, provides })`. Приложение и consumers импортируют только заголовок, тело
+загружается при открытии экземпляра (D186, D207). `defineFeature.preload(feature)` подтягивает этот код заранее,
+ничего не открывая; для фичи без тела это успешный no-op (D208).
+
+Стадии декларации (`own` и внешняя `provides`) видят refs. Стадии экземпляра (`exports`, вложенные фабрики
+вкладов и фабрики моделей) получают материализованные значения. Зависимости модели собираются readonly-записью
+импортов и call refs текущей фичи, включая `requires.x`; optional-импорты сохраняют lookup-проекцию.
+Для вызова модели используется `port(Port, { from: own.model, select: value => value.call })`.
+`calls(imports.x, keys)` принимает методы хоста, экспортированные вызовы жёсткого импорта фичи и экспортированные
+вызовы поверх `optional(feature)` — там они отвечают `CallError` `unavailable`, пока провайдера нет. Данные слабого
+ребра читайте через `fromOptional(source, select, { missing })`, а не разворачивая `lookup.kind` руками (D187). У ресурсов
+и стримов `target` выбирает `Readable<T | null | undefined>`, а `retention` необязателен; `scoped({ capacity })`
+фиксирует LRU. Фильтр эффекта — `when(current, previous)`. Это канонические формы без алиасов (D168, D169).
+
+Объявляйте команду через `ctx.call(options)` в модели или `call(options)` в `own`. Исполняйте существующую команду
+через `context.invoke(target, input)` в её контексте исполнения, в том числе с деструктуризацией:
+`run: (input, { invoke }) => invoke(deps.submit, input)`. При миграции меняйте обращения, деструктуризацию и
+собственные типы контекста вместе; фабричные `call`, `calls` и существительное `Call` сохраняются (D243).
+Вложенный вызов наследует отмену, авторитет и стек lane; новую политику он не выбирает.
+
+`when` у вклада это либо `Readable<boolean>`, либо чистый синхронный предикат экземпляра —
+`({ exports, imports, own, read }) => boolean`. Его `read` только записывает, от чего зависит ответ: внутри нельзя
+писать, вызывать и ждать, а сам предикат выполнится снова при смене любого прочитанного источника. В этом контексте
+`own` материализован: поле модели это `Readable`, а не ref декларации (D220). `pipe` объявляет обработчик
+дескриптором с одним ключом — `pipe(target, { fold: (value, meta, context) => next })`, — где `context` это тот же
+контекст вычисления. `fold` выполняется только на свёртке цели: ни объявление, ни `defineFeature.preload`, ни
+открытие экземпляра его не вызывают, поэтому работу, которая обязана произойти при открытии, держите в `own`
+(D223).
+
+## 3. Запрещено — и что вы увидите
+
+| Форма                                                                                                                                                                      | Почему нельзя                                                         | Сигнал                                                                                      |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `exports: ({ own }) => ({ m: own.model })`                                                                                                                                 | модель это запись значений                                            | typetest/`prepare`: `Feature export m must be a Call, a Readable or a Resource.`            |
+| `ctx.update(foreignReadable, v)`                                                                                                                                           | писатель остаётся у владельца                                         | тип; в рантайме `TypeError: Model update accepts only state created by this model context.` |
+| `onDemand(feature)`                                                                                                                                                        | слова нет с D105                                                      | тип и `TypeError` в `feature-contract`                                                      |
+| `optional(optional(x))`                                                                                                                                                    | одна обёртка                                                          | тип и `TypeError`                                                                           |
+| `when: 'authorized'`                                                                                                                                                       | только `Condition`                                                    | тип и `TypeError`                                                                           |
+| жёсткий импорт при `provider.when ⊄ consumer.when`                                                                                                                         | провайдер должен жить не меньше                                       | компилятор: `… cannot depend on shorter-lived provider …; use optional for a weak edge.`    |
+| два провайдера одного порта                                                                                                                                                | один провайдер на приложение                                          | компилятор приложения                                                                       |
+| `useModel(X)` per-mount модели вклада в компоненте или хуке без `requiresModels([X])` (вложенные тоже)                                                                     | тип не видит требования; owner-модели объявлять не нужно (D158)       | ревью деклараций; runtime `missing` только при отсутствии модели во frame                   |
+| `throw` для продуктового исхода команды                                                                                                                                    | исходы — значения (D86)                                               | `useCommand` покажет `lastError` только для `failed`; `cancelled` не ошибка                 |
+| kernel-слова в публичных именах (`Module`, `Attachment`, `Executor`, `Authority`, `Owner`, `Blueprint`, `IR`) и снятые слова (`Task`, `Signal`, `Domain`, `View`, `Setup`) | словарь автора                                                        | гейт `ci:public-surface`                                                                    |
+| `createState`/`isCancellation` из `@opetope/core`, `useFeatureError`                                                                                                       | сняты с безопасных входов (D142)                                      | нет экспорта; `ctx.state`, отмену читает `useCommand`                                       |
+| ручная обёртка каждого метода хоста в `context.call`                                                                                                                       | `context.calls(source, keys, { lane })` (D143)                        | —                                                                                           |
+| `when: () => readable`, `when: async () => …`, `when: ({ read }) => read(counter)`                                                                                         | предикат отвечает фактом, а не источником, промисом или truthy (D220) | тип; в рантайме `TypeError: Feature contribution when predicate must return a boolean.`     |
+| `pipe(target, handler)` или `pipe(target, () => handler)`                                                                                                                  | у `pipe` дескриптор `{ fold }` (D223)                                 | тип; в рантайме `TypeError: Feature pipe expects a descriptor: pipe(target, { fold: … }).`  |
+
+## 4. Ошибки: читайте `code`, не текст
+
+`FeatureError` (`not-ready | retired | quarantined | cleanup-failed`), `CallError` (`cancelled | closed |
+publication-rejected | unavailable`), `ReadableError` (`closed`), `ContributionError` (`missing | inactive | duplicate |
+binding-invalid`), `ApplicationError` (`closed`), `DeclarationError` (`invalid-id`). Отмена это бренд, а не класс: `CallError` только с кодами `cancelled`/`closed`, `FeatureError` `retired`, `ContributionError` `inactive` (D138); `unavailable` и `publication-rejected` — ответы продукта, `useCommand` отдаёт их как `failed` с `lastError`. Предикат `isCancellation` живёт на `@opetope/core/internal` (D142) — автору фичи он не нужен. Закрытое состояние распространяется по производным узлам: `derive` над ушедшим провайдером бросает `closed` (D146).
+
+Фича закрывается через `await instance.close()`. `FeatureError.retryCleanup` необязателен и появляется только
+для повторяемого карантинного фронтира; перед вызовом проверьте его наличие. У других ошибок нет no-op retry.
+Retry спроса принадлежит текущему источнику, а `Resource.retry()` — отдельная операция ресурса (D168, D170).
+
+Состояние модели принадлежит создавшему контексту, даже если другая модель держит `OwnedState` того же типа.
+После фенса ничего не регистрируется. Отказ фабрики должен освобождать частичный kernel, а отмена не должна
+освобождать источник до физического дренажа допущенной работы. В эффектах React зависимостью служит полученный
+деструктуризацией `useCommand(...).run`, а не объект со статусом. Пропсы монтирования меняются одним снимком в
+layout до paint; адаптер и прямые пропсы следуют одному правилу (D170).
+
+Для setter абсолютного значения, где нужно доставить свежий ввод, пока ждёт предыдущий, объявляйте
+`policy: 'latest'` в `context.call` модели; своей политики потребитель не называет (D185, D203). Default `queue`
+выполняет каждый вход по порядку и сохраняет поведение кнопок. Заменённый ожидающий вход получает `cancelled`, без
+callback успеха или ошибки; не объявляйте `latest` для последовательности, где важны промежуточные операции. Lane и
+физическое время жизни остаются у модели.
+
+## 5. Проверки перед коммитом
+
+Из пакета: `npx tsc --noEmit`, `npm run ci:test`, `npm run ci:eslint`, `npm run ci:size-limit`.
+В приложении-потребителе проверьте типы интеграции, тесты затронутых фич, production-сборку, размещение чанков и
+бюджеты размера приложения его собственными командами.
+Из корня: `npm run ci:eslint`, `npm run ci:oxlint`, `npm run ci:format`, `npm run ci:unused`, `npm run ci:docs`.
+Из `tooling/stress`: `npm run ci:public-surface` при любом изменении публичного имени, `ci:type-stress`,
+`ci:perf-memory`, `ci:inspection`.
+
+### Включите `@opetope/lint`
+
+Пакет поставляет проверяемую часть законов выше, поэтому ревью не нужно проговаривать их словами. Подключите его
+flat config к файлам, где живут фичи, модели и их UI:
+
+```js
+// eslint.config.mjs
+import opetope from '@opetope/lint';
+
+export default [
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    ...opetope.configs.recommended,
+  },
+];
+```
+
+В `recommended` входят правила, которым не нужно знать о каталогах хоста. Сами правила, их фиксы и границы —
+в [`../lint/README.md`](../../lint/README.ru.md).
+
+## 6. Меняете фреймворк, а не фичу
+
+- Публичное имя или форма — только с compile-checked пилотом в приложении-потребителе и строкой в decision log; бюджеты
+  size и perf не поднимать ради сокрытия регрессии. Согласованное расширение словаря остаётся в пределах цели
+  public-surface и обновляет записанный бюджет вместе с решением (§5 spec).
+- Файлы `core/runtime/react/src` ≤ 600 строк; делить по машине состояний, компилятору, привязке или границе хоста.
+- Hot path: без `Reflect.apply`/bind/массивов аргументов на вызов, без `Object.freeze` в циклах диспетчера, без
+  `Error` на успешном пути; новая запись на операцию — только с измерением.
+- Внутренние имена = публичные слова того же концепта; `module` — kernel-слово единицы lowering, только в `internal`.
+
+## 7. Ревью своего кода (семь линз коротко)
+
+Закон §4 → где тест; authority → ничего лишнего на публичном входе; гонки → close во время open, retire во время
+вызова, коммит React позже микротаска; производительность → аллокации на вызов, O(N) на событие; DX → слова §3 и
+typetests на негативы, тексты ошибок называют фичу/экземпляр/вклад и подсказывают фикс; over-engineering → есть ли
+у механизма продовый вызов; человек → закрытие гейта объявляет не автор.
+
+## Данные и команды компонента
+
+`useModel(Declaration, (model, { read }) => ({ ... }))` выбирает данные и command consumers одним hook (D205, D214).
+
+Результат выбора модели может быть именованным interface без index signature (D217). Результат — плоская запись данных;
+arrays, functions, constructors и встроенные объекты коллекций, дат и promises не являются selection records.
+Readonly record с выведенными типами преобразует authentic Call в `CommandHook`; остальные поля сохраняют свои типы.
+`read(readable, project?)` читает явно, объединяет подписки на один источник и не делает автоматический Resource retain.
+Поля сравниваются через `Object.is`; новый вложенный объект считается изменением. Чистый callback не вызывает hooks,
+команды или side effects. Замена подписок и допуск команд происходят в commit, не в abandoned render. Ключи, aliases,
+локальные статусы и `.run` следуют `useCommands`. Создание модели, feature acquire и новый scheduler не подразумеваются.
+`useModel(Declaration)` по-прежнему возвращает выданную модель; структура React hooks постоянна при смене selection.
+Общий hook улучшает DX, но сам по себе не гарантирует ускорение.
+
+## Сценарные тесты и физическая активность
+
+`createScenario(application, options)` из `@opetope/react/testing` открывает настоящее приложение и его существующую
+inspection session (D206, D215). Передайте обычные `imports`/`conditions` и принадлежащий тесту адаптер
+`host.mount(Component)`, возвращающий handle с `unmount()`. Пакет не добавляет зависимость от DOM renderer или test runner.
+`scenario.mount(target, { props })` использует опубликованные Slot contributions и возвращает
+`{ host, updateProps, unmount }`; `host` — исходный результат renderer. Typed targets требуют `options.props`,
+а targets без props опускают его, как в `Slot` (D217). Fixtures не обходят authority команд.
+
+Синхронный конструктор возвращает `ready`, поэтому pending lazy body можно исследовать до готовности.
+`waitFor(snapshot => predicate, { label, timeoutMs, pollIntervalMs })` просыпается от inspection и дополнительно
+опрашивает predicates внешнего UI; `notify()` будит его после изменения управляемой fixture. По умолчанию deadline
+равен 1000ms, polling predicate — 10ms. `ScenarioTimeoutError` содержит data-only snapshot, ограниченную историю и
+наблюдаемые conditions, фазы feature, body load, lane blockers и удержания ресурсов. Причины внутри repository
+или сети не выводятся из догадок. `getSnapshot()` и `history()` используют ту же модель наблюдения; по умолчанию
+хранятся 64 снимка, activity ограничена 256 записями. Capacities — целые от 1 до 10000.
+Не заменяйте predicates фиксированным числом ticks.
+
+`close()` синхронно ставит fence admission приложения, размонтирует зарегистрированные экраны и ждёт их cleanup
+вместе с physical application drain. Deadline не отменяет cleanup: последующий `close()` может дождаться того же drain.
+Deadline готовности также оставляет приложение доступным для inspection и явного закрытия.
+`ownership()` описывает только зарегистрированное владение runtime; при отсутствующих, stale или усечённых данных
+возвращается `unknown`. Терминальный stale-снимок считается полным лишь после подтверждённого сценарием успешного
+физического cleanup. Это допускает проверку нулевых счётчиков в данном scope, но не доказывает отсутствие произвольных
+host/UI/GC-утечек. Успешный cleanup очищает imports приложения и внутренние ссылки на renderer. Promise отказавшего
+cleanup может удерживать исходные ошибки и retry capabilities; сохранённый пользователем `mounted.host` удерживает его renderer result.
+
+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.