@opetope/runtime 0.1.0

package/docs/cookbook.md

@@ -0,0 +1,734 @@
+# Opetope: cookbook
+
+> Recipes use the public entries; abbreviated snippets assume the surrounding declarations shown in the recipe.
+> Stress compiles spec §2 examples, and the app type gate checks production pilots; it does not compile every
+> cookbook fragment. Sections 3 and 9 use _illustrative_ names (`hasTasks`, `sessionsFeature`, `Badge`): the API is
+> real, the production caller does not exist yet.
+
+Practical uses of the framework through application examples. Every recipe gives you: when to apply it, the
+code, what the framework checks, and the typical mistakes. The normative laws are in [spec.md](spec.md); how it
+works inside is in [how-it-works.md](how-it-works.md); the rules for agents are in
+[agent-guide.md](agent-guide.md).
+
+## 0. The shape of a feature in one minute
+
+```ts
+const feature = defineFeature({
+  id: 'area.feature',                    // required, and the only required option
+  when: [authorizedCondition],           // lifetime: while every condition holds; without when — with the application
+  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 out of own; a whole model is not allowed
+  provides: ({ slot, pipe, register, port, own }) => ({ … }),
+});
+```
+
+A stage sees only the stages before it: `imports`/`requires` → `own` → `exports`/`provides`. Three words for edges:
+hard (`imports: { x: feature }`, `port`) — the provider lives at least as long as I do and opens earlier;
+weak (`optional(x)`) — the provider may be absent or may switch off, and I read a `Lookup`;
+`when` — the conditions of my own lifetime.
+
+## 1. Host contract and host calls (`calls`), port provider
+
+When: the feature takes an external capability from the application and hands it to other
+features through a port.
+
+```ts
+// contract.ts — a neutral file, with no feature imports
+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']) }), // host methods as Call
+  provides: ({ own, port }) => ({ catalog: port(resolveItemPort, own.resolveItem) }),
+});
+```
+
+What is checked: a port has exactly one provider in the application (two is a topology compile error); `calls` takes
+only keys that exist on the contract (a type check). The mistake: putting the raw `imports.platform`, or a number,
+into `own` — `own` accepts only values the builder produced.
+
+### Plain methods and client adapters
+
+Do not add `_signal` to ordinary methods just to select them with `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` takes `void`, `editing.setAmount` takes a number, and `load`/`reload` return `Result`.
+`calls` preserves `form` as the methods' receiver. The adapter explicitly maps a client's options without changing
+the client or adding a runtime primitive. Optional inputs and optional signals are accepted; a possible third
+parameter, an arbitrary options object in the second position or an unbounded rest parameter needs an adapter.
+
+## 2. Requiring a port: a bare port and `optional`
+
+```ts
+const checkoutItemLookupFeature = defineFeature({
+  id: checkoutItemLookupFeatureId,
+  requires: { catalog: resolveItemPort }, // the provider must be present in the application
+  own: ({ requires }) => ({ resolveItem: requires.catalog }), // requires.x is a ref; the Call appears on the instance
+});
+// a weak requirement: requires: { catalog: optional(resolveItemPort) } — a call with no live provider
+// rejects with CallError code 'unavailable'; useCommand shows it as { status: 'failed', error }
+```
+
+## 3. Lifetime: conditions and `when`
+
+When: the feature must live only while authorized, on a route, or behind an enabled flag.
+
+```ts
+// a condition the host binds by id when it opens the application:
+const flagEnabled = defineCondition({ id: 'sampleApp.flag' });
+// features/auth/…/feature.ts — a condition computed from the exports of a feature; the host binds its source, not
+// the condition, and the condition lives next to the feature it reads (D184):
+const authorizedCondition = defineCondition({
+  from: authSessionFeature,
+  id: 'sampleApp.authorized',
+  select: exports => exports.authorized,
+});
+
+// one feature may own several conditions with different meanings: use separate conditions for
+// UI visibility and strict authorization when their predicates differ (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], … });
+
+// the application
+const app = defineApplication({ id: 'sampleApp', features: [...], reporter });
+openApplication(app, { conditions: { 'sampleApp.flag': flagReadable }, imports: [bind(contract, value)] });
+```
+
+The laws: features that share one set of conditions form a group, open in canonical order and close in reverse; a
+hard edge is legal only when `provider.when ⊆ consumer.when` (otherwise the compiler points you at `optional`); a
+consumer group waits for the providers in other groups to be ready and closes before them (D123). A condition read
+from a closed feature reads as `false`. An application that names a computed condition must enable the feature it is
+computed from; otherwise the topology does not compile.
+
+## 4. Lazy host contract, `attach`, lanes and call policies
+
+When: the host contract is acquired on demand, and the calls must run strictly in order, with
+an initialization step and without duplicates.
+
+```ts
+own: ({ attach, call, imports, lane }) => {
+  const commands = attach(imports.commands);                // imports.commands = onDemand(actionHost)
+  const commandsLane = lane({ within: commands });           // a queue that lives while the source is attached
+  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` caches the first successful result; `singleFlight` joins parallel calls that share one key; `policy:
+'parallel'` lifts the lane queue; `within` fences the call together with its source. Cancellation is a `cancelled`
+outcome, not a product error.
+
+## 5. A feature model built from an import, and live exports
+
+```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 }),   // a Resource goes out; owned state narrows to Readable
+```
+
+`model(Decl, { source: imports.source }, (ctx, { source }) => …)` passes a readonly map of materialized
+dependencies, including a single source. `model(Decl, create)` needs no dependencies. Inside the factory: `ctx.state` (owned state, written only through `ctx.update`), `ctx.call`, `ctx.lane`,
+`ctx.effect`, `ctx.event`, `ctx.resource`, `ctx.stream`, `ctx.scope`, `ctx.timers`, `ctx.cleanup`. Model fields are
+only `Readable` and `Call`.
+
+Inside a model, `context.calls(deps, ['setAmount', 'setDirection'], { lane })` selects ordinary methods with no
+parameters, one input, or `(input, signal: AbortSignal)` into Calls on one model lane (D143, D244). Optional
+parameters are supported. A single parameter is always the input: for a signal-only method declare a command
+with `context.call({ run: (_input: void, { signal }) => deps.load(signal) })` or use an explicit adapter.
+
+A model can compose a host import and a required call without receiving the feature context. Its factory declares
+its own dependency interface. A model call may also implement a port; the projection runs once before publication
+and the provider's lifetime fences the selected call even when it is passed through from a dependency (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 as a slot contribution: per-mount model, props adapter, `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 — the component declares only the models created per mount
+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 }),  // what the component sees
+  })),
+}),
+```
+
+The `own` models are available to the contribution component automatically (`useModel(CheckoutCreateFormView)`);
+per-mount models are created in commit and close on unmount, and their commands are cancelled after unmount. An
+abandoned render creates no models (D188). A component or hook reading a per-mount model must declare it through
+`requiresModels`; check nested components and hooks as well. At runtime, a model absent
+from the mount’s granted models fails with `ContributionError('missing')`.
+
+A UI model wraps an export when the UI contract differs in input or in error shape:
+
+```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);
+}}),
+```
+
+In React: `const { run, inFlight, result, lastError } = useCommand(actions.confirmAction)`; outcomes are values, and
+`throw` is only for exceptional situations.
+
+For an effect that invokes a command, depend on its destructured `run`, whose identity is stable for one invoker.
+The whole hook result object changes with status. The hook itself schedules nothing: every `run` reaches the call,
+and the policy the call was created with decides. An absolute setter such as amount or an enabled flag is declared
+`policy: 'latest'` in the model's `context.call`, so the newest input replaces the waiting one and the displaced
+input settles as `cancelled` without success or failure callbacks (D185, D203). Leave the default `queue` for submit
+buttons: `latest` drops intents that never started and is wrong when every operation must execute.
+
+A button that must not act twice says so in its call: `submit` declares `singleFlight`, so a second click while the
+first submit is in flight joins that flight instead of queueing a second order. `inFlight` still disables the button;
+the call is what makes a fast double click harmless.
+
+Two controls that overwrite the same value need one command intent: AmountInput sends either
+`{ amount, currency }` or `{ percent, currency }` to the same `setAmount` call, which is where the policy lives.
+Two calls would each keep their own waiting place and could reorder the newest intent across controls. The model
+dispatches the union to the existing host methods.
+
+Direct props, an optional props adapter and model props all read the same mount
+snapshot; a new slot snapshot publishes in layout before paint (D170).
+
+## 7. `pipe` with tracked reads and `slot` with `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, {              // a descriptor, bound once (D223)
+    fold: (count: number, _meta, { imports, read }) =>
+      count + read(imports.platform.actions).pendingCount,        // read makes the fold trackable (D82)
+  }),
+}),
+```
+
+A `pipe` declares its handler as a `{ fold }` descriptor, which sees the same instance context as the predicate and
+runs on a fold, never at declaration or preload. A predicate answers a boolean and its `read` records what the answer
+depends on, so a dynamic branch follows the source it read last. `when: false` removes the contribution from
+`entries` without withdrawing the publication; a change of the answer recomputes the target in one transaction.
+
+## 8. Resources, streams, events, effects, scopes
+
+```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() }),
+}),
+```
+
+The positional form everywhere: `resource(from, target, {…})`, `stream(from, target, {…})`, `event(from, subscribe, {…})`.
+Timers (`timers.delay/interval`) live with the instance and are cancelled on retire. The disposers of `effect/event/
+resource/stream/scope/cleanup` run in one drain, in reverse order; registering after the fence is a `TypeError`.
+
+The `target` selector of a resource or stream returns a `Readable<T | null | undefined>`, never a scalar snapshot.
+Nullish targets close the current materialization. This contract and optional `retention` are identical in feature
+and model factories; `scoped({ capacity })` uses LRU. The effect predicate is `when(current, previous)`.
+Close a feature with `await instance.close()`; retry cleanup only after checking `error.retryCleanup` on a
+quarantined `FeatureError`. A `FeatureError` is quarantined only when the host asked for it:
+`openFeature(feature, { cleanupFailure: 'quarantine' })` for one instance and
+`openApplication(app, { cleanupFailure: 'quarantine', … })` for every instance of an application; the default,
+`report`, hands the failure to the reporter and calls the instance closed (D182). Resource retry and business commands named `retry` keep their existing meaning.
+
+### The contract of an external source adapter
+
+The host owns the adapter, the feature owns the work. An adapter is a plain record of methods and readables whose
+shape is the contract; it holds no state of the feature, opens nothing, and closes nothing.
+
+```ts
+// features/tasks/integration/platform/resourceSource.ts — the host side of `tasks.resource.platform`
+const tasksTarget = Object.freeze({
+  getSnapshot: () => 'tasks' as const, // a Readable, so the feature decides when to read it
+  subscribe: (_listener: () => void) => () => undefined, // a constant target still returns a disposer
+});
+
+function createTasksResourceSource(tasks: TasksInitializer): TasksResourceSource {
+  return Object.freeze({
+    load: async (signal: AbortSignal) => {
+      signal.throwIfAborted(); // the signal is the contract, not decoration
+      await tasks.init({ state: 'load' });
+      signal.throwIfAborted(); // and it is checked again after the await
+    },
+    target: tasksTarget,
+  });
+}
+```
+
+Four rules hold for every adapter: cancellable work uses the operation's signal; a value the feature must follow
+is a `Readable`, never a snapshot the adapter refreshes itself; `subscribe` returns the disposer
+of the underlying source, so releasing it releases exactly what was taken; and the adapter never imports the feature,
+so the direction of the dependency is the direction of the contract.
+
+In `load`, `connect` and `consume`, keep the signal passed by that callback: it belongs to the current target
+execution, which can end before the model does. `ModelContext.signal` lasts for the whole model. A command's `run`
+likewise gets its own execution signal, and nested `invoke` inherits cancellation; do not substitute the model
+signal for it (D243, D244).
+
+A synchronous setter needs no signal. If external work cannot be cancelled, state that in the adapter instead of
+adding a cosmetic `_signal`. The caller can still settle as cancelled and Runtime rejects late Call results or
+Resource/Stream publication, but the physical work may continue and drain must wait for it. Arbitrary state writes
+inside that work and external side effects need their own signal checks; cancellation cannot undo them. Never assume
+that an ignored signal or a check after `await` physically cancels the underlying client request.
+
+## 9. A weak edge in practice
+
+```ts
+imports: { sessions: optional(sessionsFeature) },
+own: ({ calls, imports, model }) => ({
+  // the calls of the provider that is there now; while nothing provides them: CallError 'unavailable' (D187)
+  ...calls(imports.sessions, ['confirmAction']),
+  badge: model(Badge, { sessions: imports.sessions }, (ctx, { sessions }) => ({     // sessions: Readable<Lookup<Exports>>
+    // the data half: `select` runs only on found, may return a value or the provider's own Readable
+    count: fromOptional(sessions, found => found.sessions.count, { missing: 0 }),
+  })),
+}),
+```
+
+Write the raw `derive({ from: sessions, select: lookup => … })` only when the two branches are genuinely different work;
+`fromOptional` is the same thing without the `lookup.kind` ceremony, and it tracks a nested `Readable` only while
+the provider exists.
+
+`found`/`missing` do not tell you the reason: either the provider is absent from the application, or its condition
+group is closed. A weak edge does not pull the provider into the application and does not affect activation order.
+A call on a weak port without a provider rejects with `CallError` `unavailable`, and `useCommand` reports it as `failed` with the error in `lastError` — an answer, not a cancellation (D138).
+
+Closing propagates (D146): once the provider instance is gone, its state is closed, and `derive`/`computed` over a direct (hard) import answer with a `ReadableError` `closed` instead of the last value; a weak edge shows `missing` instead — which is exactly the reason to take `optional` when the provider can die first.
+
+### A feature demand boundary
+
+When host integration supplies a `FeatureDemandSource`, `FeatureBoundary` holds its lease and renders readiness,
+failure and retry states:
+
+```tsx
+// a node in both branches: the error subtree reads its retry with `useFeatureRetry`
+<FeatureBoundary demand={host} error={<Retry />} fallback={<Spinner />}>
+  <Slot props={{ itemId }} target={confirmActionContentSlot} />
+</FeatureBoundary>
+
+// render callbacks, when the branch needs what only the boundary knows (D177)
+<FeatureBoundary
+  demand={tasksDemand}
+  error={({ error, retry }) => <Failure error={error} onRetry={retry} />}
+  fallback={null}
+>
+  {({ exports }) => <TasksResourceLease resource={exports.tasks}>{children}</TasksResourceLease>}
+</FeatureBoundary>
+```
+
+The callback of `children` is typed by the demand, so `exports` is the export record of that feature; the callback of
+`error` receives `{ error, retry }`. Only the branch that is shown runs its callback, and the boundary already holds
+the feature — a ready consumer therefore needs no second `useFeature` and takes no second lease. Hooks belong in the
+child components the callback returns, not in the callback itself: the callback runs during the boundary's own
+render, and the authority for `useModel`/`useCommand` still comes from a contribution through `Slot`.
+
+### A feature in two files
+
+When the implementation is heavy — models, components, their libraries — the feature is written as a header and a
+body, and only the header is imported by the application and by consumers (D186, D207):
+
+```ts
+// features/tasks/…/feature.ts — the header: identity, edges, declared border, loader
+const tasksFeature = defineFeature({
+  id: 'tasks.resource',
+  imports: { platform: tasksResourcePlatform },
+  when: [authorizedCondition],
+  provides: { screen: tasksScreenSlot }, // metadata: the target, and `{ priority, target }` when it matters
+  body: (): Promise<FeatureBody<TasksExports>> =>
+    import(/* webpackChunkName: "feature.tasks" */ './feature.body').then(module => module.tasksBody),
+});
+
+// features/tasks/…/feature.body.ts — the body: the three sections, in the chunk the header loads
+const tasksBody = defineFeature.body(tasksFeature, {
+  own: ({ imports, resource }) => ({ tasks: resource(imports.platform /* … */) }),
+  exports: ({ own }) => ({ tasks: own.tasks }),
+});
+```
+
+The export type is written once, in the neutral contract file, and named by the loader — that is what keeps the two
+files from inferring each other in a circle. The body implements exactly the border the header declared: another
+target, another priority or another port is refused before anything opens. Loading starts when an instance opens,
+never at declaration, so the plan is compiled and checked while the body is still on the network.
+
+## 10. Testing
+
+```ts
+// mounting a contribution with no application
+const harness = renderSlot(checkoutCreateFormOverlayHeaderSlot, { props, models: [[HeaderModel, { itemId }]] });
+// a command fixture for a model
+const confirm = command<ConfirmActionIntent, void>(async () => undefined);
+// one feature with stubbed imports
+const instance = openFeature(confirmActionFeature, { imports: { commands, view }, reporter: () => undefined });
+await instance.ready; … await instance.close();
+```
+
+The acceptance check for the inspection port is `assertInspectionSessionContract` from `@opetope/devtools/testing` (the `ci:inspection` gate in
+`tooling/stress`).
+
+## 11. Anti-patterns
+
+- `exports: ({ own }) => ({ order: own.order })` where `order` is a model: a whole model is not exported, only its fields.
+- `throw` inside commands for product outcomes: return an author-defined outcome record such as `{ type: 'error', message }`; `throw` is for exceptions only.
+- `onDemand(feature)` — no such word; a weak edge is `optional`. `onDemand` applies only to host contracts.
+- Reading a per-mount contribution model with `useModel(X)` in a component or hook without `requiresModels([X])`, including nested readers (D158); `own` models need no declaration.
+- `imports.platform.submit` inside a model factory — that is a ref, not a value; use `model(Decl, { platform: imports.platform }, (ctx, { platform }) => platform.submit…)`.
+- Writing into someone else's `Readable`: `ctx.update` accepts only an `OwnedState` created by this context.
+
+## 12. Practices
+
+0. Separate feature composition, models and UI, for example as `features/<f>/{integration,models,ui}`. The host
+   declares the application graph and supplies external bindings.
+1. Contracts (`defineHostContract`, `definePort`, `defineSlot`, `defineModel`, `defineCondition`) go into neutral
+   `*.contract.ts` files with no feature imports; a feature imports a contract, not another feature, except for a
+   hard edge.
+2. One fact is declared once: do not duplicate the shape of a host contract in a contribution model, take the
+   `own` model.
+3. Keep `own` flat: the field names are the vocabulary of `exports` and of the contributions.
+4. Read errors by `code` (`FeatureError`, `CallError`, `ReadableError`, `ContributionError`, `ApplicationError`); cancellation is only `CallError` `cancelled`/`closed`, `FeatureError` `retired` and `ContributionError` `inactive` (D138) — `unavailable` and `publication-rejected` are shown by the product as an error.
+5. Before a commit: `tsc`, the package `ci:test`, `ci:eslint` and `ci:size-limit`; run the consuming application's
+   affected feature tests and production build checks. When a public name changes — `ci:public-surface` and a line
+   in the decision log.
+
+## Select a component contract from one model
+
+For a form that already receives its model through a Slot, select the values and commands together.
+Keep the Call policy in the model. Different granted models can still be combined with `useCommands`.
+The standalone [React example](../../react/README.md#hello-ui) contains declarations and imports.
+
+```tsx
+const { quantity, setQuantity, submit } = useModel(OrderForm, (model, { read }) => ({
+  quantity: read(model.state, state => state.quantity),
+  setQuantity: model.setQuantity,
+  submit: model.submit,
+}));
+```
+
+Only the selected quantity drives data renders. `submit.inFlight` is local to this consumer; aliases are independent.
+For a projection returning an object, spread its fields into the returned selection or keep its reference stable.
+A selector extracted from the component body (a module function or `useCallback`) is not called at all on an
+unrelated render; an inline one runs again, and an equal selection keeps the previous snapshot, so the work
+below the hook does not repeat.
+
+## Exercise an application through its Slot
+
+The test supplies its existing renderer and controlled repository fixtures. This wiring sketch uses 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 });
+```
+
+Use a named predicate for a lane wait or controlled load. A timeout contains the same graph/activity facts as the inspector; arbitrary host work remains unknown. See the [scenario contract](../../react/README.md).
+
+## Read a model through one selector
+
+A component shows several fields of a model and runs two of its commands. Taken hook by hook, that becomes a list
+nobody reads as a whole:
+
+```tsx
+// what a consumer wrote first: the model, then a hook per field, then a hook per command
+const actions = useModel(OrderActions);
+const amount = useReadable(actions.amount);
+const currency = useReadable(actions.currency);
+const submit = useCommand(actions.submit);
+const reset = useCommand(actions.reset);
+```
+
+Nothing in the component states what it depends on: the answer is assembled by reading the body top to bottom, and
+the next field is one `actions.total.getSnapshot()` away — a read with no subscription behind it, which renders once
+and never updates again.
+
+One selection says it in one place:
+
+```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,
+}));
+```
+
+The record is the component's contract with the model: `read` is the only way in, so a field that is not read is not
+subscribed and cannot silently go stale; each distinct `Readable` is subscribed once; and an authentic `Call` taken
+as a field becomes the same `CommandHook` the individual hook returns, with its own `run`, `inFlight` and
+`lastError` per alias (D205, D214). The selector is pure — no hooks, no commands, no side effects — and its fields
+are compared with `Object.is`, so select scalars or projections rather than freshly allocated objects. The full
+contract of the selection is in the section on selecting a component contract above.
+
+This is not a promise of fewer renders: combining hooks changes what the component declares, not how fast React is.
+The triad stays right where there is no model selection to make — a `Readable` that arrived as a prop or from a
+`Resource` (`useReadable`, `useResource`), a component that only passes the granted model on (the one-argument
+`useModel`), and a shared hook that reads one field for several components, where one `useReadable` is simply
+smaller than a selector.
+
+## Decide whether an edge is weak
+
+A settings surface shows a diagnostics section when the build has one. Written as a hard edge, it does not compile:
+
+```ts
+// the settings feature, always alive; the provider lives under a development flag
+imports: { devTools: devToolsFeature },
+when: [settingsVisible],
+```
+
+A hard edge requires `provider.when ⊆ consumer.when`, so the compiler refuses this application and names `optional`.
+Putting the consumer under the same flag would compile and be worse: the whole settings surface would then disappear
+with the flag it was only supposed to show one section for.
+
+The weak edge is the answer, and its data is read without unfolding the lookup by hand:
+
+```ts
+imports: { devTools: optional(devToolsFeature) },
+own: ({ imports, model }) => ({
+  panel: model(SettingsPanel, { devTools: imports.devTools }, (_context, { devTools }) => ({
+    // devTools: Readable<Lookup<Exports>>; `select` runs only on found, and the fallback is written once
+    diagnostics: fromOptional(devTools, found => found.diagnostics, { missing: [] }),
+  })),
+}),
+```
+
+The criterion is one question: does the provider live at least as long as this feature and open before it? Yes — a
+hard import, and the type gives the exports directly. No — `optional`: another condition group, another flag, a
+build that does not ship the provider at all, or a provider the application may simply not enable.
+
+What it gives the types and the graph: one word covers both absence and demand, and the exports arrive as
+`Readable<Lookup<Exports>>` rather than something `undefined` at compile time (D105); a weak edge neither pulls the
+provider into the application nor changes activation order; a call through a weak port answers `CallError`
+`unavailable` instead of throwing (D187). `found`/`missing` never says which reason applies — absent from the
+application or closed with its condition group — and that is deliberate: the reader shows the same section either
+way, and a reason that cannot be acted on has no place in the branch.
+
+## Register through the target, not beside it
+
+Several features contribute named things to one place: payment methods, tools by id, screens by route. The shape a
+consumer reaches for first is a module-level map with hand-made notifications:
+
+```ts
+// ui/methods.ts — a registry outside the graph
+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();
+  };
+};
+```
+
+A feature then calls `registerMethod` from an effect and releases it in cleanup. Nothing ties that entry to the
+feature: a fence does not withdraw it, an opening that failed halfway leaves it behind, two features that claim one
+key are discovered by whoever renders last, and the inspector shows no contribution at all — a missing payment
+method is then debugged by reading code instead of the runtime graph.
+
+The target already exists, and it belongs outside features:
+
+```ts
+// contracts.ts
+const paymentMethods = defineRegistry<string, PaymentMethodEntry>({ id: 'checkout.methods' });
+
+// feature.ts — the entry is a contribution, so it opens and closes with the instance that made it
+provides: ({ register }) => ({
+  card: register(paymentMethods, ({ exports }) => ({ key: 'card', value: { submit: exports.submit, title: 'Card' } })),
+}),
+
+// UI reads the target, never the provider's module
+const method = useReadable(paymentMethods.select(selectedKey));
+const methods = useReadable(paymentMethods.list);
+```
+
+The publication is atomic and owned: the entry lands when the instance is ready, the fence withdraws it on close, a
+duplicate key is refused before anything moves, the order is `priority` and then id, and the inspector lists the
+entry with the feature that owns it (D127, D196). `select(key)` answers the same `Lookup` as a weak edge, so an
+absent method is a branch rather than an `undefined`.
+
+Local UI state is still local: which method is selected, whether the panel is open, what the cursor is on. That is a
+model field of the mount, not a registry entry — a registry answers "who contributed what", a model answers "what
+this screen is doing right now".
+
+## Test a composition with `createScenario`
+
+The unit tests of a component say nothing about the composition: whether the feature under a condition really
+publishes into the slot, and whether it really takes the contribution back. That is one scenario:
+
+```tsx
+const scenario = createScenario(application, {
+  conditions: { 'checkout.promo': promo }, // the test owns this source: `getSnapshot`/`subscribe` over a local flag
+  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();
+}
+```
+
+The test drives the real application: its own condition source, its own renderer, the graph in between. `notify()`
+wakes the predicates after a fixture change without publishing a runtime event, and a `waitFor` deadline reports the
+graph and activity facts the inspector holds rather than a bare timeout (D206, D215).
+
+What it catches on an upgrade of the framework is what a component test cannot: the form of `when` and the moment a
+group opens, the publication into the slot and its ordering, and the withdrawal on close — including a contribution
+that stays in `entries` one turn too long. Close in `finally`, and assert `scenario.ownership()` when the test also
+claims the application released what it owned.
+
+## Smooth a bursty host source
+
+A host source fires several times per frame — a price tick, a resize, a scroll position — and one `run` cannot keep
+up with it. The `event` queue holds one payload, so a burst costs a `queue-capacity` failure record per dropped
+emit, and a consumer that sees those records in its reporter usually smooths the source by hand:
+
+```ts
+// models/…/TickModel.ts — a second queue in front of the runtime's own
+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);
+  });
+};
+```
+
+That queue is outside everything: its microtask is not owned by the instance, so a fence does not cancel it and a
+payload can reach `emit` after the owner closed; it hides the drops instead of answering them; and the two queues
+now disagree about which payload is the newest one.
+
+The policy is an option of the event, and it is the same word a stream uses:
+
+```ts
+own: ({ event, imports }) => ({
+  ticks: event(imports.platform, ({ emit, source }) => source.subscribeTicks(emit), {
+    backpressure: latest(),                                   // the newest payload takes the waiting slot (D247)
+    run: ({ payload, signal, source }) => source.applyTick(payload, signal),
+  }),
+}),
+```
+
+While `run` is busy and one payload waits, the next `emit` replaces the one that waits, and nothing is reported —
+there is nothing to report, because no author asked for that payload to be delivered. A `run` in flight is never
+interrupted, so the tick being applied finishes on its own; only the waiting slot changes hands. Closing the owner
+drops whatever waits in it, under this policy and under the default alike.
+
+Keep the default where an event is a trigger or a command rather than a value: a refetch on focus, a submit, an
+"open the details" intent. There the first event of a burst is the one that matters, the second is genuinely
+excess work, and the `queue-capacity` record is how the reporter tells you the source is louder than the handler.
+A queue that loses nothing is neither policy and remains an open question (D183).