@opetope/runtime 0.1.0

package/docs/cookbook.ru.md

@@ -0,0 +1,729 @@
+# Opetope: книга рецептов
+
+> Рецепты используют публичные входы; сокращённые фрагменты предполагают окружающие объявления из рецепта.
+> Stress компилирует примеры spec §2, app type gate проверяет production-пилоты; каждый фрагмент cookbook он не
+> компилирует. В §3 и §9 имена _иллюстративные_ (`hasTasks`, `sessionsFeature`, `Badge`): API настоящий,
+> production-вызова пока нет.
+
+Практические варианты использования фреймворка на примерах приложения. Каждый рецепт: когда применять, код,
+что проверяет фреймворк, типичные ошибки. Нормативные законы — в [spec.md](spec.md); как это устроено внутри — в
+[how-it-works.md](how-it-works.md); правила для агентов — в [agent-guide.md](agent-guide.md).
+
+## 0. Форма фичи за минуту
+
+```ts
+const feature = defineFeature({
+  id: 'area.feature',                    // обязателен, единственный
+  when: [authorizedCondition],           // время жизни: пока все условия истинны; без when — с приложением
+  imports: { platform: hostContract, other: otherFeature, maybe: optional(thirdFeature) },
+  requires: { resolve: resolveItemPort },
+  own: ({ imports, requires, calls, attach, call, lane, effect, event, resource, stream, scope, model }) => ({ … }),
+  exports: ({ own }) => ({ x: own.x }),  // Call | Readable | Resource из own; модель целиком — нельзя
+  provides: ({ slot, pipe, register, port, own }) => ({ … }),
+});
+```
+
+Стадии видят только предыдущие: `imports`/`requires` → `own` → `exports`/`provides`. Три слова рёбер:
+жёсткое (`imports: { x: feature }`, `port`) — провайдер живёт не меньше меня и открывается раньше;
+слабое (`optional(x)`) — провайдера может не быть или он может выключиться, я читаю `Lookup`;
+`when` — условия моего собственного времени жизни.
+
+## 1. Хост-контракт и вызовы хоста (`calls`), провайдер порта
+
+Когда: фича берёт внешнюю возможность у приложения и отдаёт её другим фичам через порт.
+
+```ts
+// contract.ts — нейтральный файл, без импорта фич
+const catalogResolveSource = defineHostContract<{
+  resolveItem: (input: ResolveItemInput, signal: AbortSignal) => ItemSummary | null;
+}>('catalog.resolve.platform');
+const resolveItemPort = definePort<ResolveItemInput, ItemSummary | null>('checkoutControl.catalog.resolve');
+
+// feature.ts
+const catalogResolveFeature = defineFeature({
+  id: catalogResolveFeatureId,
+  imports: { platform: catalogResolveSource },
+  own: ({ calls, imports }) => ({ ...calls(imports.platform, ['resolveItem']) }), // методы хоста как Call
+  provides: ({ own, port }) => ({ catalog: port(resolveItemPort, own.resolveItem) }),
+});
+```
+
+Проверяется: у порта ровно один провайдер в приложении (два — ошибка компиляции топологии); `calls` берёт только
+существующие ключи контракта (тип). Ошибка: класть в `own` сырой `imports.platform` или число — `own` принимает
+только значения builder-а.
+
+### Обычные методы и адаптеры клиентов
+
+Не добавляйте `_signal` в обычные методы только ради выбора через `calls` (D244):
+
+```ts
+import type { ModelContext } from '@opetope/core';
+
+type Input = { readonly id: string };
+type Result = { readonly title: string };
+declare const ctx: ModelContext;
+declare const form: { clear(): void; setAmount(amount: number): void };
+declare const client: { load(input: Input, options: { signal: AbortSignal }): Promise<Result> };
+
+const editing = ctx.calls(form, ['clear', 'setAmount']);
+const api = {
+  load: (input: Input, signal: AbortSignal) => client.load(input, { signal }),
+};
+const { load } = ctx.calls(api, ['load']);
+const reload = ctx.call({
+  run: (input: Input, { invoke }) => invoke(load, input),
+});
+```
+
+`editing.clear` принимает `void`, `editing.setAmount` — число, а `load`/`reload` возвращают `Result`.
+`calls` сохраняет `form` как receiver методов. Адаптер явно преобразует options клиента, не меняя клиент и не
+добавляя runtime primitive. Необязательные input и signal принимаются; возможный третий параметр, произвольный
+options-объект на второй позиции или неограниченный rest требуют адаптера.
+
+## 2. Требование порта: сам порт и `optional`
+
+```ts
+const checkoutItemLookupFeature = defineFeature({
+  id: checkoutItemLookupFeatureId,
+  requires: { catalog: resolveItemPort }, // провайдер обязан быть в приложении
+  own: ({ requires }) => ({ resolveItem: requires.catalog }), // requires.x — ref, Call появится у экземпляра
+});
+// слабое требование: requires: { catalog: optional(resolveItemPort) } — вызов без живого провайдера
+// отклоняется CallError с кодом 'unavailable'; useCommand покажет { status: 'failed', error }
+```
+
+## 3. Время жизни: условия и `when`
+
+Когда: фича должна жить только при авторизации, на роуте, при включённом флаге.
+
+```ts
+// условие, которое хост привязывает по id при открытии приложения:
+const flagEnabled = defineCondition({ id: 'sampleApp.flag' });
+// features/auth/…/feature.ts — условие, вычисленное из экспортов фичи; хост привязывает её источник, а не условие,
+// и условие живёт рядом с фичей, которую читает (D184):
+const authorizedCondition = defineCondition({
+  from: authSessionFeature,
+  id: 'sampleApp.authorized',
+  select: exports => exports.authorized,
+});
+
+// у одной фичи может быть несколько условий с разным смыслом: используйте отдельные условия
+// для видимости UI и строгой авторизации, если их предикаты различаются (D204)
+const sessionCondition = defineCondition({
+  from: authSessionFeature,
+  id: 'sampleApp.session',
+  select: exports => exports.hasSession,
+});
+
+const confirmActionFeature = defineFeature({ id, when: [authorizedCondition], … });
+const logOutFeature = defineFeature({ id, when: [sessionCondition], … });
+
+// приложение
+const app = defineApplication({ id: 'sampleApp', features: [...], reporter });
+openApplication(app, { conditions: { 'sampleApp.flag': flagReadable }, imports: [bind(contract, value)] });
+```
+
+Законы: фичи с одним набором условий образуют группу, открываются в каноническом порядке и закрываются в обратном;
+жёсткое ребро законно только если `provider.when ⊆ consumer.when` (иначе компилятор укажет на `optional`); группа-
+потребитель ждёт готовности провайдеров из других групп и закрывается раньше них (D123). Приложение, называющее
+вычисленное условие, обязано включать фичу, из которой оно вычислено, иначе топология не компилируется. Условие из
+закрытой фичи
+читается как `false`.
+
+## 4. Ленивый host-контракт, `attach`, лейны и политики вызовов
+
+Когда: host-контракт приобретается по спросу, а вызовы должны идти строго по очереди с
+инициализацией и без дублей.
+
+```ts
+own: ({ attach, call, imports, lane }) => {
+  const commands = attach(imports.commands);                // imports.commands = onDemand(actionHost)
+  const commandsLane = lane({ within: commands });           // очередь, живущая пока источник подключён
+  const initialize = call({ lane: commandsLane, once: true, within: commands,
+    run: (_input: void, { signal, source }) => source.initialize(signal) });
+  const retry = call({ lane: commandsLane, within: commands,
+    run: (_input: void, context) => context.invoke(initialize, undefined) });
+  const confirmAction = call({ policy: 'parallel', within: commands,
+    singleFlight: (intent: ConfirmActionIntent) => intent.itemId,
+    run: (intent, { signal, source }) => runConfirmActionWorkflow(source, intent, signal) });
+  return { commands, initialize, retry, confirmAction };
+},
+exports: ({ own }) => ({ retry: own.retry, confirmAction: own.confirmAction }),
+```
+
+`once` кэширует первый успешный результат; `singleFlight` склеивает параллельные вызовы с одним ключом; `policy:
+'parallel'` снимает очередь лейна; `within` фенсит вызов вместе с источником. Отмена — это исход `cancelled`, не
+ошибка продукта.
+
+## 5. Модель фичи от импорта и живые экспорты
+
+```ts
+own: ({ imports, model, resource }) => ({
+  form: model(CheckoutCreateFormView, { platform: imports.platform }, (ctx, { platform }) => createCheckoutCreateFormModel(ctx, platform)),
+  tasks: resource(imports.platform, platform => platform.target, {
+    key: target => target, load: (_t, { signal, source }) => source.load(signal),
+    retention: scoped({ capacity: 1 }),
+  }),
+}),
+exports: ({ own }) => ({ tasks: own.tasks }),   // Resource наружу; владеемое состояние сужается до Readable
+```
+
+`model(Decl, { source: imports.source }, (ctx, { source }) => …)` передаёт readonly-запись материализованных
+зависимостей, в том числе для одного источника. `model(Decl, create)` не требует зависимостей. Внутри фабрики: `ctx.state` (владеемое состояние, писать только через `ctx.update`), `ctx.call`, `ctx.lane`,
+`ctx.effect`, `ctx.event`, `ctx.resource`, `ctx.stream`, `ctx.scope`, `ctx.timers`, `ctx.cleanup`. Поля модели —
+только `Readable` и `Call`.
+
+В модели `context.calls(deps, ['setAmount', 'setDirection'], { lane })` выбирает обычные методы без параметров,
+с одним input либо `(input, signal: AbortSignal)` в Calls на одном lane модели (D143, D244). Необязательные
+параметры поддерживаются. Единственный параметр всегда input: для signal-only метода объявите команду через
+`context.call({ run: (_input: void, { signal }) => deps.load(signal) })` или используйте явный адаптер.
+
+Модель может соединить импорт хоста и требуемый вызов, не получая контекст фичи. Фабрика объявляет свой интерфейс
+зависимостей. Вызов модели также может реализовать порт; проекция выполняется один раз до публикации, а время
+жизни провайдера ограничивает выбранный вызов, даже переданный напрямую из зависимости (D169).
+
+```ts
+own: ({ imports, model, requires }) => ({
+  order: model(OrderModel, { platform: imports.platform, lookup: requires.lookup }, createOrderModel),
+}),
+provides: ({ own, port }) => ({
+  submit: port(SubmitPort, { from: own.order, select: order => order.submit }),
+}),
+```
+
+## 6. UI как вклад в слот: per-mount модель, адаптер props, `requiresModels`
+
+```ts
+// ui/…/contracts.ts
+const CheckoutCreateFormActions = defineModel<{ deposit: Call<{ accountId: number; currency: string }, void>; … }>('checkout.createForm.actions');
+const checkoutCreateFormContentSlot = defineSlot<CheckoutCreateFormContentProps>({ id: 'checkout.createForm.content' });
+
+// ui/…/CheckoutCreateFormContent.tsx — компонент объявляет только модели, создаваемые на монтирование
+const CheckoutCreateFormContent = requiresModels([CheckoutCreateFormActions])(({ renderForm }) => renderForm());
+
+// integration/platform/…/feature.tsx
+provides: ({ slot }) => ({
+  content: slot(checkoutCreateFormContentSlot, ({ model }) => ({
+    Component: CheckoutCreateFormContent,
+    models: [model(CheckoutCreateFormActions, (ctx, props: Readable<CheckoutCreateFormContentProps>) => ({
+      deposit: ctx.call({ run: ({ accountId, currency }) => props.getSnapshot().onDepositClick(accountId, currency) }),
+    }))],
+    props: ({ renderForm }: CheckoutCreateFormContentProps) => ({ renderForm }),  // что видит компонент
+  })),
+}),
+```
+
+Модели `own` доступны компоненту вклада автоматически (`useModel(CheckoutCreateFormView)`), per-mount модели живут с
+монтированием, создаются в коммите и закрываются на unmount; их команды после unmount отменяются. Брошенный рендер
+не создаёт модели (D188). Компонент или hook, читающий per-mount модель, обязан объявить её через `requiresModels`:
+проверяйте также вложенные компоненты и хуки. В runtime отсутствие модели среди разрешённых
+монтированию приводит к `ContributionError('missing')`.
+
+UI-модель оборачивает экспорт, когда контракт UI отличается по входу или ошибке:
+
+```ts
+confirmAction: ctx.call({ run: async (_input: void, { invoke }) => {
+  const outcome = await invoke(exports.confirmAction, { itemId: props.getSnapshot().itemId });
+  if (outcome.type !== 'ok') throw new ConfirmActionCommandError(outcome.code, outcome.message);
+}}),
+```
+
+В React: `const { run, inFlight, result, lastError } = useCommand(actions.confirmAction)`; исходы — значения,
+`throw` только для исключительных ситуаций.
+
+Эффект, вызывающий команду, зависит от полученного деструктуризацией `run`: его ссылка стабильна для одного
+invoker. Весь объект результата хука меняется со статусом. Сам хук ничего не планирует: каждый `run` доходит до
+вызова, и решает политика, с которой вызов создан. Setter абсолютного значения — сумма, флаг enabled — объявляется
+`policy: 'latest'` в `context.call` модели, и тогда новый вход заменяет ожидающий, а вытесненный получает
+`cancelled` без callbacks успеха и ошибки (D185, D203). Для submit-кнопок оставляйте `queue` по умолчанию: `latest`
+отбрасывает намерения, которые не успели начаться, и не подходит, если каждую операцию нужно выполнить.
+
+Кнопка, которая не должна сработать дважды, говорит об этом в своём вызове: `submit` объявляет `singleFlight`,
+поэтому второй клик при незавершённой отправке присоединяется к тому же полёту, а не ставит в очередь второй ордер.
+`inFlight` по-прежнему блокирует кнопку; безопасным быстрый двойной клик делает вызов.
+
+Два контрола, перезаписывающих одно значение, используют одну команду: AmountInput передаёт
+`{ amount, currency }` или `{ percent, currency }` в тот же вызов `setAmount`, где и живёт политика. Два вызова
+держали бы по своему месту ожидания и могли бы переставить последнее намерение между контролами. Модель направляет
+union в прежние host-методы.
+
+Прямые пропсы, необязательный адаптер и пропсы модели читают один снимок
+монтирования; новый снимок слота публикуется в layout до paint (D170).
+
+## 7. `pipe` с отслеживаемым чтением и `slot` с `when`
+
+```ts
+provides: ({ pipe, slot }) => ({
+  homeHeader: slot(exampleToolbarSlot('home'), { Component: ExampleActionButton },
+    { priority: 1, when: ({ imports, read }) => read(imports.platform.actions).config.actionId !== '' }),
+  itemCount: pipe(exampleCountPipe, {              // дескриптор, связан один раз (D223)
+    fold: (count: number, _meta, { imports, read }) =>
+      count + read(imports.platform.actions).pendingCount,        // read делает fold отслеживаемым (D82)
+  }),
+}),
+```
+
+`pipe` объявляет обработчик дескриптором `{ fold }`: он видит тот же контекст экземпляра, что и предикат, и
+выполняется на свёртке, а не при объявлении или предзагрузке. Предикат отвечает boolean, а его `read` записывает,
+от чего зависит ответ, поэтому динамическая ветка следует за источником, который прочитан последним. `when: false`
+убирает вклад из `entries` без снятия публикации; смена ответа пересчитывает цель одной транзакцией.
+
+## 8. Ресурсы, потоки, события, эффекты, области
+
+```ts
+own: ({ effect, event, imports, resource, scope, stream }) => ({
+  initialLoad: resource(imports.platform, p => p.target, { key: t => t,
+    load: (_t, { signal, source }) => source.initialize(signal),
+    retention: scoped({ capacity: 1 }), retry: { attempts: 2, delayMs: 1_000 } }),
+  quote: stream(imports.platform, p => p.target, { backpressure: latest(),
+    connect: (target, { emit, source }) => source.connect(target, emit),
+    consume: ({ data, source, target }) => source.updateTitle(`${data.middle} ${target.title}`),
+    key: t => `${t.pageId}:${t.itemId}`, retention: scoped({ capacity: 8 }) }),
+  polling: event(imports.platform, ({ emit, source, timers }) => {
+    timers.interval(pollingIntervalMs, () => emit(undefined));
+    return source.subscribeForeground(() => emit(undefined));
+  }, { run: ({ signal, source }) => (source.isOnline() ? source.refresh(signal) : undefined) }),
+  autoOpen: effect({ from: imports.platform, run: ({ current, source, timers }) => {
+    if (current === null || current.viewed) return;
+    return timers.delay(3_000, () => { if (!source.getSnapshot()?.viewed) source.showDetails(); });
+  }}),
+  inactivePageReset: effect({ from: imports.lifetime,
+    when: (current, previous) => !current.active && (previous === undefined || (!previous.active && previous.pageId !== current.pageId)),
+    run: ({ current }) => current.resetTitle() }),
+  activePage: scope.while({ from: imports.lifetime, when: l => l.active, open: l => () => l.resetTitle() }),
+}),
+```
+
+Позиционная форма везде: `resource(from, target, {…})`, `stream(from, target, {…})`, `event(from, subscribe, {…})`.
+Таймеры (`timers.delay/interval`) живут с экземпляром и отменяются на retire. Диспозеры `effect/event/resource/
+stream/scope/cleanup` выполняются в одном drain в обратном порядке; регистрация после фенса — `TypeError`.
+
+Target-селектор ресурса или стрима возвращает `Readable<T | null | undefined>`, а не скалярный snapshot.
+Nullish target закрывает текущую материализацию. Этот контракт и необязательный `retention` одинаковы у фичи
+и модели; `scoped({ capacity })` использует LRU. Предикат эффекта — `when(current, previous)`.
+Фича закрывается через `await instance.close()`; повтор уборки вызывается только после проверки
+`error.retryCleanup` у карантинного `FeatureError`. Карантин бывает только там, где его попросил хост:
+`openFeature(feature, { cleanupFailure: 'quarantine' })` для одного экземпляра и
+`openApplication(app, { cleanupFailure: 'quarantine', … })` для всех экземпляров приложения; по умолчанию `report`
+отдаёт отказ репортеру и считает экземпляр закрытым (D182). Retry ресурса и бизнес-команды `retry` сохраняют свой
+смысл.
+
+### Контракт внешнего source-адаптера
+
+Адаптер принадлежит хосту, работа — фиче. Адаптер это обычная запись методов и readable-полей, чья форма и есть
+контракт; он не хранит состояние фичи, ничего не открывает и ничего не закрывает.
+
+```ts
+// features/tasks/integration/platform/resourceSource.ts — хостовая сторона `tasks.resource.platform`
+const tasksTarget = Object.freeze({
+  getSnapshot: () => 'tasks' as const, // Readable, поэтому момент чтения выбирает фича
+  subscribe: (_listener: () => void) => () => undefined, // даже постоянный target возвращает disposer
+});
+
+function createTasksResourceSource(tasks: TasksInitializer): TasksResourceSource {
+  return Object.freeze({
+    load: async (signal: AbortSignal) => {
+      signal.throwIfAborted(); // сигнал это контракт, а не украшение
+      await tasks.init({ state: 'load' });
+      signal.throwIfAborted(); // и он проверяется ещё раз после await
+    },
+    target: tasksTarget,
+  });
+}
+```
+
+Четыре правила для любого адаптера: отменяемая работа использует сигнал операции; значение, за которым фича должна
+следить, это `Readable`, а не снимок, который адаптер обновляет сам; `subscribe` возвращает
+disposer нижележащего источника, поэтому освобождение снимает ровно то, что было взято; адаптер не импортирует фичу,
+поэтому направление зависимости совпадает с направлением контракта.
+
+В `load`, `connect` и `consume` используйте сигнал, переданный callback: он принадлежит текущему исполнению target,
+которое может закончиться раньше модели. `ModelContext.signal` живёт со всей моделью. `run` команды также получает
+сигнал собственного исполнения, а вложенный `invoke` наследует отмену; не подставляйте вместо него сигнал модели
+(D243, D244).
+
+Синхронному setter сигнал не нужен. Если внешняя работа неотменяема, укажите это в адаптере вместо косметического
+`_signal`. Вызывающий всё равно может завершиться отменой, а Runtime отвергнет поздний результат Call или публикацию
+Resource/Stream, но физическая работа может продолжиться, и drain обязан её дождаться. Произвольные записи состояния
+внутри этой работы и внешние побочные эффекты требуют собственных проверок signal; отмена не может их откатить.
+Игнорируемый сигнал или проверка после `await` не означают физическую отмену запроса нижележащего клиента.
+
+## 9. Слабое ребро на практике
+
+```ts
+imports: { sessions: optional(sessionsFeature) },
+own: ({ calls, imports, model }) => ({
+  // вызовы того провайдера, который есть сейчас; пока его нет — CallError 'unavailable' (D187)
+  ...calls(imports.sessions, ['confirmAction']),
+  badge: model(Badge, { sessions: imports.sessions }, (ctx, { sessions }) => ({     // sessions: Readable<Lookup<Exports>>
+    // половина данных: `select` выполняется только на found и вправе вернуть значение или Readable провайдера
+    count: fromOptional(sessions, found => found.sessions.count, { missing: 0 }),
+  })),
+}),
+```
+
+Голый `derive({ from: sessions, select: lookup => … })` пишите только когда ветки это действительно разная работа;
+`fromOptional` делает то же самое без церемонии с `lookup.kind` и подписывается на вложенный `Readable` только пока
+провайдер есть.
+
+`found`/`missing` не различают причину: провайдера нет в приложении или его группа условий закрыта. Слабое ребро не
+втягивает провайдера в приложение и не влияет на порядок активации. Вызов слабого порта без провайдера отклоняется `CallError` `unavailable`, и `useCommand` показывает его исходом `failed` с ошибкой в `lastError` — это ответ, а не отмена (D138).
+
+Закрытие распространяется (D146): когда экземпляр провайдера ушёл, его состояние закрыто, `derive`/`computed` над прямым (жёстким) импортом отвечают `ReadableError` `closed` вместо последнего значения; слабое ребро вместо этого показывает `missing` — это и есть причина брать `optional`, если провайдер может умереть раньше.
+
+### Граница спроса на фичу
+
+Когда интеграция с хостом предоставляет `FeatureDemandSource`, `FeatureBoundary` удерживает его lease и отображает
+состояния готовности, ошибки и retry:
+
+```tsx
+// узел в обеих ветвях: поддерево ошибки читает свой retry через `useFeatureRetry`
+<FeatureBoundary demand={host} error={<Retry />} fallback={<Spinner />}>
+  <Slot props={{ itemId }} target={confirmActionContentSlot} />
+</FeatureBoundary>
+
+// render-колбэки, когда ветви нужно то, что знает только граница (D177)
+<FeatureBoundary
+  demand={tasksDemand}
+  error={({ error, retry }) => <Failure error={error} onRetry={retry} />}
+  fallback={null}
+>
+  {({ exports }) => <TasksResourceLease resource={exports.tasks}>{children}</TasksResourceLease>}
+</FeatureBoundary>
+```
+
+Колбэк `children` типизирован по `demand`, поэтому `exports` это запись экспортов той самой фичи; колбэк `error`
+получает `{ error, retry }`. Выполняется только показанная ветвь, а фичу граница уже держит — готовому потребителю
+не нужен второй `useFeature` и он не берёт второе удержание. Хуки живут в дочерних компонентах, которые вернул
+колбэк, а не в самом колбэке: колбэк выполняется в рендере границы, и права на `useModel`/`useCommand` по-прежнему
+даёт вклад через `Slot`.
+
+### Фича двумя файлами
+
+Когда реализация тяжёлая — модели, компоненты, их библиотеки — фича пишется заголовком и телом, и приложение с
+consumers импортируют только заголовок (D186, D207):
+
+```ts
+// features/tasks/…/feature.ts — заголовок: identity, рёбра, объявленная граница, loader
+const tasksFeature = defineFeature({
+  id: 'tasks.resource',
+  imports: { platform: tasksResourcePlatform },
+  when: [authorizedCondition],
+  provides: { screen: tasksScreenSlot }, // метаданные: цель, а когда важен порядок — `{ priority, target }`
+  body: (): Promise<FeatureBody<TasksExports>> =>
+    import(/* webpackChunkName: "feature.tasks" */ './feature.body').then(module => module.tasksBody),
+});
+
+// features/tasks/…/feature.body.ts — тело: те же три секции, в чанке, который грузит заголовок
+const tasksBody = defineFeature.body(tasksFeature, {
+  own: ({ imports, resource }) => ({ tasks: resource(imports.platform /* … */) }),
+  exports: ({ own }) => ({ tasks: own.tasks }),
+});
+```
+
+Тип экспортов пишется один раз, в нейтральном файле контрактов, и называется в loader — именно это не даёт двум
+файлам выводить типы друг из друга по кругу. Тело реализует ровно ту границу, которую объявил заголовок: другая цель,
+другой приоритет или другой порт отвергаются до открытия. Загрузка начинается при открытии экземпляра, а не при
+объявлении, поэтому план компилируется и проверяется, пока тело ещё в сети.
+
+## 10. Тестирование
+
+```ts
+// монтирование вклада без приложения
+const harness = renderSlot(checkoutCreateFormOverlayHeaderSlot, { props, models: [[HeaderModel, { itemId }]] });
+// команда-фикстура для модели
+const confirm = command<ConfirmActionIntent, void>(async () => undefined);
+// одна фича со стабами импортов
+const instance = openFeature(confirmActionFeature, { imports: { commands, view }, reporter: () => undefined });
+await instance.ready; … await instance.close();
+```
+
+Приёмка порта наблюдения — `assertInspectionSessionContract` из `@opetope/devtools/testing` (гейт `ci:inspection` в `tooling/stress`).
+
+## 11. Анти-паттерны
+
+- `exports: ({ own }) => ({ order: own.order })`, где `order` — модель: модель целиком не экспортируется, только поля.
+- `throw` внутри команд для продуктовых исходов: возвращай авторскую запись исхода, например `{ type: 'error', message }`, `throw` — только исключения.
+- `onDemand(feature)` — слова нет; слабое ребро это `optional`. `onDemand` применяется только к host-контрактам.
+- Чтение per-mount модели вклада через `useModel(X)` в компоненте или хуке без `requiresModels([X])`, включая вложенных читателей (D158); owner-модели объявлять не нужно.
+- `imports.platform.submit` внутри фабрики модели — ref, не значение; используй `model(Decl, { platform: imports.platform }, (ctx, { platform }) => platform.submit…)`.
+- Запись в чужой `Readable`: `ctx.update` принимает только `OwnedState`, созданный этим контекстом.
+
+## 12. Практики
+
+0. Разделяйте композицию фичи, модели и UI, например как `features/<f>/{integration,models,ui}`. Хост объявляет
+   граф приложения и передаёт внешние привязки.
+1. Контракты (`defineHostContract`, `definePort`, `defineSlot`, `defineModel`, `defineCondition`) — в нейтральных
+   `*.contract.ts`, без импортов фич; фича импортирует контракт, а не другую фичу, кроме случаев жёсткого ребра.
+2. Один факт объявляется один раз: не дублируй форму хост-контракта в модели вклада, бери `own`-модель.
+3. Держи `own` плоским: имена полей — это словарь `exports` и вкладов.
+4. Ошибки читай по `code` (`FeatureError`, `CallError`, `ReadableError`, `ContributionError`, `ApplicationError`); отмена это только `CallError` `cancelled`/`closed`, `FeatureError` `retired` и `ContributionError` `inactive` (D138) — `unavailable` и `publication-rejected` продукт показывает как ошибку.
+5. Перед коммитом: `tsc`, пакетные `ci:test`, `ci:eslint` и `ci:size-limit`; запустите тесты затронутых фич и
+   проверки production-сборки приложения-потребителя. При изменении публичных имён — `ci:public-surface` и строка
+   в decision log.
+
+## Выбрать контракт компонента из одной модели
+
+Для формы, которая уже получает модель через Slot, выбирайте значения и команды вместе.
+Политика Call остаётся в модели. Команды разных выданных моделей по-прежнему можно объединить через `useCommands`.
+Самодостаточный [React-пример](../../react/README.ru.md#hello-ui) содержит declarations и imports.
+
+```tsx
+const { quantity, setQuantity, submit } = useModel(OrderForm, (model, { read }) => ({
+  quantity: read(model.state, state => state.quantity),
+  setQuantity: model.setQuantity,
+  submit: model.submit,
+}));
+```
+
+Из данных render меняет только выбранное quantity. `submit.inFlight` локален для этого потребителя; aliases независимы.
+Если проекция возвращает объект, раскройте его поля в selection или сохраняйте стабильную ссылку.
+Селектор, вынесенный из тела компонента (функция модуля или `useCallback`), на посторонний render не вызывается
+вовсе; инлайн выполняется снова, а равная selection сохраняет прежний снимок, и работа ниже хука не
+повторяется.
+
+## Проверить приложение через его Slot
+
+Тест передаёт свой renderer и управляемые fixtures репозитория. Эскиз проводки использует React Testing Library.
+
+```tsx
+import { createScenario } from '@opetope/react/testing';
+
+const scenario = createScenario(application, {
+  conditions: {},
+  imports: bindings,
+  host: { mount: Component => render(<Component />) },
+});
+try {
+  await scenario.ready;
+  const screen = scenario.mount(OrderScreenSlot);
+  fireEvent.click(screen.host.getByRole('button', { name: 'Submit' }));
+  await scenario.waitFor(() => repository.submitted.length === 1, { label: 'order submitted' });
+} finally {
+  await scenario.close();
+}
+expect(scenario.ownership()).toMatchObject({ scope: 'registered-runtime', status: 'complete', resources: 0 });
+```
+
+Используйте именованный predicate для ожидания lane или управляемой загрузки. Timeout содержит те же graph/activity facts, что inspector; произвольная работа хоста остаётся неизвестной. См. [контракт сценариев](../../react/README.ru.md).
+
+## Читать модель одним селектором
+
+Компонент показывает несколько полей модели и запускает две её команды. Хук за хуком это превращается в список,
+который никто не читает целиком:
+
+```tsx
+// как это написали в первый раз: модель, потом хук на поле, потом хук на команду
+const actions = useModel(OrderActions);
+const amount = useReadable(actions.amount);
+const currency = useReadable(actions.currency);
+const submit = useCommand(actions.submit);
+const reset = useCommand(actions.reset);
+```
+
+В самом компоненте не сказано, от чего он зависит: ответ собирается чтением тела сверху вниз, а следующее поле — это
+одно `actions.total.getSnapshot()`, чтение без подписки за ним: отрисуется один раз и больше не обновится.
+
+Один селектор говорит это в одном месте:
+
+```tsx
+const { amount, currency, reset, submit } = useModel(OrderActions, (model, { read }) => ({
+  amount: read(model.amount),
+  currency: read(model.currency, value => value.code),
+  reset: model.reset,
+  submit: model.submit,
+}));
+```
+
+Запись это контракт компонента с моделью: `read` единственный вход, поэтому непрочитанное поле не подписано и не
+может тихо устареть; каждый отдельный `Readable` подписан один раз; а аутентичный `Call`, взятый полем, становится
+тем же `CommandHook`, что возвращает отдельный хук, со своими `run`, `inFlight` и `lastError` на каждый алиас
+(D205, D214). Селектор чистый — ни хуков, ни команд, ни побочных эффектов, — а его поля сравниваются по
+`Object.is`, поэтому выбирайте скаляры или проекции, а не заново созданные объекты. Полный контракт выборки — в
+разделе про контракт компонента из одной модели выше.
+
+Это не обещание меньшего числа рендеров: объединение хуков меняет то, что компонент объявляет, а не скорость React.
+Триада остаётся уместной там, где выбирать не из чего: `Readable`, пришедший пропсом или от `Resource`
+(`useReadable`, `useResource`), компонент, который только передаёт выданную модель дальше (одноаргументный
+`useModel`), и общий хук, читающий одно поле для нескольких компонентов, — там один `useReadable` просто меньше
+селектора.
+
+## Решить, слабое ли ребро
+
+Поверхность настроек показывает раздел диагностики, если он есть в этой сборке. Написанное жёстким ребром, это не
+компилируется:
+
+```ts
+// фича настроек живёт всегда; провайдер живёт под флагом разработки
+imports: { devTools: devToolsFeature },
+when: [settingsVisible],
+```
+
+Жёсткое ребро требует `provider.when ⊆ consumer.when`, поэтому компилятор отказывает приложению и называет
+`optional`. Увести потребителя под тот же флаг было бы хуже: вместе с флагом исчезла бы вся поверхность настроек, а
+показать она должна была один раздел.
+
+Ответ это слабое ребро, а его данные читаются без ручного разбора lookup:
+
+```ts
+imports: { devTools: optional(devToolsFeature) },
+own: ({ imports, model }) => ({
+  panel: model(SettingsPanel, { devTools: imports.devTools }, (_context, { devTools }) => ({
+    // devTools: Readable<Lookup<Exports>>; `select` выполняется только на found, а запасной ответ пишется один раз
+    diagnostics: fromOptional(devTools, found => found.diagnostics, { missing: [] }),
+  })),
+}),
+```
+
+Критерий это один вопрос: живёт ли провайдер не меньше этой фичи и открывается ли раньше неё? Да — жёсткий импорт,
+и тип отдаёт экспорты напрямую. Нет — `optional`: другая группа условий, другой флаг, сборка, в которой провайдера
+нет вовсе, или провайдер, которого приложение просто может не включить.
+
+Что это даёт типам и графу: одно слово покрывает и отсутствие, и спрос, а экспорты приходят как
+`Readable<Lookup<Exports>>`, а не чем-то `undefined` на компиляции (D105); слабое ребро не втягивает провайдера в
+приложение и не меняет порядок активации; вызов через слабый порт отвечает `CallError` `unavailable`, а не бросает
+(D187). `found`/`missing` никогда не говорит, какая именно причина — провайдера нет в приложении или он закрыт со
+своей группой условий, — и это намеренно: читатель показывает один и тот же раздел в обоих случаях, а причина, с
+которой ничего не сделать, в ветке не нужна.
+
+## Регистрировать через цель, а не рядом с ней
+
+Несколько фич вкладывают именованные вещи в одно место: способы оплаты, инструменты по id, экраны по маршруту.
+Первое, к чему тянется рука, — модульная map с самодельными уведомлениями:
+
+```ts
+// ui/methods.ts — реестр вне графа
+const entries = new Map<string, PaymentMethod>();
+const listeners = new Set<() => void>();
+
+const registerMethod = (key: string, value: PaymentMethod): (() => void) => {
+  entries.set(key, value);
+  for (const listener of listeners) listener();
+
+  return () => {
+    entries.delete(key);
+    for (const listener of listeners) listener();
+  };
+};
+```
+
+Фича зовёт `registerMethod` из эффекта и освобождает его в cleanup. Запись при этом ничем не связана с фичей: fence
+её не снимает, наполовину провалившееся открытие оставляет её лежать, две фичи с одним ключом обнаруживает тот, кто
+рендерит последним, а инспектор не показывает никакого вклада — пропавший способ оплаты приходится искать чтением
+кода, а не рантайм-графа.
+
+Цель уже существует, и живёт она вне фич:
+
+```ts
+// contracts.ts
+const paymentMethods = defineRegistry<string, PaymentMethodEntry>({ id: 'checkout.methods' });
+
+// feature.ts — запись это вклад, поэтому она открывается и закрывается с экземпляром, который её сделал
+provides: ({ register }) => ({
+  card: register(paymentMethods, ({ exports }) => ({ key: 'card', value: { submit: exports.submit, title: 'Card' } })),
+}),
+
+// UI читает цель, а не модуль провайдера
+const method = useReadable(paymentMethods.select(selectedKey));
+const methods = useReadable(paymentMethods.list);
+```
+
+Публикация атомарна и принадлежит владельцу: запись ложится, когда экземпляр готов, fence снимает её на закрытии,
+дубль ключа отвергается до того, как что-то сдвинулось, порядок это `priority`, затем id, а инспектор показывает
+запись вместе с фичей-владельцем (D127, D196). `select(key)` отвечает тем же `Lookup`, что и слабое ребро, поэтому
+отсутствующий способ это ветка, а не `undefined`.
+
+Локальное состояние UI остаётся локальным: какой способ выбран, открыта ли панель, где курсор. Это поле модели
+монтирования, а не запись реестра: реестр отвечает на «кто что вложил», модель — на «что этот экран делает сейчас».
+
+## Проверить композицию через `createScenario`
+
+Юнит-тесты компонента ничего не говорят о композиции: действительно ли фича под условием публикуется в слот и
+действительно ли забирает вклад обратно. Это один сценарий:
+
+```tsx
+const scenario = createScenario(application, {
+  conditions: { 'checkout.promo': promo }, // источник принадлежит тесту: `getSnapshot`/`subscribe` над локальным флагом
+  host: { mount: Component => render(<Component />) },
+  imports: bindings,
+});
+const ready = (snapshot: RuntimeGraphSnapshot): boolean =>
+  snapshot.runtime.instances.some(node => node.id.includes('checkout.promo') && node.state.kind === 'ready');
+
+try {
+  await scenario.ready;
+  const view = scenario.mount(checkoutAsideSlot);
+
+  expect(view.host.queryByTestId('promo')).toBeNull();
+  promo.set(true);
+  scenario.notify();
+  await scenario.waitFor(ready, { label: 'promo feature ready' });
+  expect(view.host.getByTestId('promo')).toBeTruthy();
+
+  promo.set(false);
+  scenario.notify();
+  await scenario.waitFor(snapshot => !ready(snapshot), { label: 'promo feature retired' });
+  expect(view.host.queryByTestId('promo')).toBeNull();
+} finally {
+  await scenario.close();
+}
+```
+
+Тест ведёт настоящее приложение: свой источник условия, свой рендерер, граф между ними. `notify()` будит предикаты
+после смены фикстуры, не публикуя рантайм-события, а дедлайн `waitFor` сообщает те же факты графа и активности,
+которые держит инспектор, а не голый таймаут (D206, D215).
+
+При обновлении фреймворка он ловит то, чего не поймает тест компонента: форму `when` и момент открытия группы,
+публикацию в слот и её порядок, снятие вклада на закрытии — включая вклад, задержавшийся в `entries` на такт
+дольше. Закрывайте в `finally`, а `scenario.ownership()` проверяйте тогда, когда тест утверждает и то, что
+приложение освободило принадлежавшее ему.
+
+## Сгладить всплески host-источника
+
+Host-источник срабатывает несколько раз за кадр — тик цены, resize, позиция скролла, — и один `run` за ним не
+успевает. Очередь `event` держит один payload, поэтому всплеск стоит по записи отказа `queue-capacity` на каждый
+отброшенный emit, и потребитель, который видит эти записи в своём reporter, обычно сглаживает источник руками:
+
+```ts
+// models/…/TickModel.ts — вторая очередь перед очередью рантайма
+let scheduled = false;
+let last: Tick | undefined;
+
+const emitLatest = (emit: (tick: Tick) => void, tick: Tick): void => {
+  last = tick;
+
+  if (scheduled) return;
+
+  scheduled = true;
+  queueMicrotask(() => {
+    scheduled = false;
+
+    if (last !== undefined) emit(last);
+  });
+};
+```
+
+Эта очередь вне всего: её микрозадача не принадлежит экземпляру, поэтому fence её не отменяет и payload может дойти
+до `emit` после закрытия владельца; она прячет отбрасывания вместо ответа на них; и две очереди теперь расходятся в
+том, какой payload считать последним.
+
+Политика это опция события, и слово у неё то же, что у потока:
+
+```ts
+own: ({ event, imports }) => ({
+  ticks: event(imports.platform, ({ emit, source }) => source.subscribeTicks(emit), {
+    backpressure: latest(),                                   // ожидающий слот достаётся новому payload (D247)
+    run: ({ payload, signal, source }) => source.applyTick(payload, signal),
+  }),
+}),
+```
+
+Пока `run` занят и один payload ждёт, следующий `emit` заменяет ожидающего, и ничего не репортится — репортить
+нечего, потому что доставки того payload никто не просил. Идущий `run` при этом не прерывается: применяемый тик
+доходит до конца сам, меняется только владелец ожидающего слота. Закрытие владельца отбрасывает то, что в слоте
+ждёт, — и при этой политике, и при дефолтной.
+
+Оставляйте дефолт там, где событие это триггер или команда, а не значение: перезапрос по фокусу, отправка,
+намерение «открыть детали». Там важно первое событие всплеска, второе это действительно лишняя работа, а запись
+`queue-capacity` — то, чем reporter сообщает, что источник громче обработчика. Очередь без потерь это ни та, ни
+другая политика, и она остаётся открытым вопросом (D183).