@opetope/runtime 0.1.0

package/docs/how-it-works.md

@@ -0,0 +1,521 @@
+# How Opetope works: creation, computation, cleanup
+
+Status: **DRAFT**, 2026-09-04; describes branch `tech-opetope`. This document explains in plain language what happens
+inside `@opetope/core`, `@opetope/runtime` and `@opetope/react` while an application runs: what is created, when it is
+recomputed, and how it is cleaned up. The normative source is [spec.md](spec.md); here you get only the mechanics and the reasons for them, and the `(Dnnn)` pointers lead to [decisions.md](decisions.md). File references are given for anyone who wants to check a statement against the code.
+
+## 0. Map of concepts
+
+| Word                                              | What it is                                                                              | Who creates it                                                       | When it dies                                               |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------- |
+| application                                       | a list of features, an error sink, host-bound contracts and conditions                  | `defineApplication` + `openApplication`                              | `close()`                                                  |
+| condition (`Condition`)                           | a named `Readable<boolean>` a group of features lives by                                | `defineCondition`; the value comes from the host or a source feature | with the application                                       |
+| feature                                           | a definition: `id`, `when`, `imports`, `requires`, `own`, `exports`, `provides`         | `defineFeature`, once per module load                                | never, it is a description                                 |
+| feature instance                                  | the live copy of a definition: models, calls, resources, contributions                  | the runtime, when the feature is needed and its conditions are true  | retire, when a condition turns false or demand is released |
+| model                                             | a record of `Readable` and `Call` an instance owns                                      | the factory from `own.model()`, when the instance opens              | the fence and drain of the instance                        |
+| call (`Call`)                                     | an operation with a queue, a lane, cancellation and single-flight                       | `ctx.call` in a model, or `call` in `own`                            | cancelled at retire                                        |
+| resource, stream, event                           | external data materialized with a key, a retention and cancellation                     | `ctx.resource`, `ctx.stream`, `ctx.event`                            | closed in drain                                            |
+| contribution                                      | what a feature contributes to someone else's target: a slot, a pipe, a registry, a port | `provides`, when the instance opens                                  | withdrawn in fence                                         |
+| target (`SlotTarget`, `Pipe`, `Registry`, `Port`) | the place a contribution lands; it lives outside features, in a contracts file          | `defineSlot`, `definePipe`, `defineRegistry`, `definePort`           | never                                                      |
+
+Three cross-cutting rules explain half of the behaviour:
+
+1. **Authenticity is checked through a `WeakMap`, not by shape.** A definition, an instance, a target, a lane and a
+   binding live in closed `WeakMap`/`WeakSet` registries; anything that never entered one is refused with
+   `TypeError('… is not authentic.')`. A framework value therefore cannot be forged with an object literal.
+2. **Everything the author supplies is snapshotted at declaration**, with an exact key-set check, and frozen. A
+   mutation of the source object after that is invisible.
+3. **Order is always canonical.** Features by id, contributions by id, imports by key, attachments by slot; every
+   teardown walks the reverse of the assembly order.
+
+## 1. The application
+
+### 1.1 Compilation: `defineApplication({ id, features, reporter })`
+
+Compilation is synchronous and happens once, before anything is opened. This is the "compile time" of the graph laws:
+a violation fails in the first manifest test.
+
+| Step | What happens                                                                                                                                                         | Where                                   |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| 1    | exact key set, `id` is a string and unique among the live definitions of the process, `reporter` is a function                                                       | `runtime/src/application-definition.ts` |
+| 2    | the world closes: from the enabled features along `imports` to their providers, through the export contract                                                          | same file                               |
+| 3    | features are sorted by id; a duplicate object and a duplicate id are refused                                                                                         | `runtime/src/application-compiler.ts`   |
+| 4    | import edges: a host contract becomes an application input, a feature definition resolves to its provider                                                            | same file                               |
+| 5    | port edges `requires ↔ provides`: exactly one provider per port                                                                                                      | `application-port-compiler.ts`          |
+| 6    | a Kahn topological sort with a lexicographic tie-break; a cycle of hard imports is an error                                                                          | `application-compiler-graph.ts`         |
+| 7    | the lifetime check: a hard edge requires `provider.when ⊆ consumer.when`; a weak `optional` edge is free of the inclusion law (D105)                                 | `application-compiler.ts`               |
+| 8    | groups by identical condition sets, the activation order inside a group and the order between groups from hard edges (D123); the graph plan for the observation port | same file, `application-group-order.ts` |
+
+The laws checked here: one provider per contract and per port, one contract identity per id, no provider is an error,
+no cycles, and the provider of a hard edge lives at least as long as its consumer.
+
+### 1.2 Opening: `openApplication(app, { cleanupFailure, conditions, imports })`
+
+| Step | What happens                                                                                                                                                                                                                                                      |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | `imports` accepts only the results of `bind(contract, value)`; every host contract is bound exactly once, and a contract that only weak imports name may be left unbound                                                                                          |
+| 2    | `conditions` supplies a `Readable<boolean>` for every condition without `from`; the record type is derived from the application, so TypeScript catches a missing and an extra key, and the runtime repeats both checks                                            |
+| 3    | `cleanupFailure` is optional and defaults to `report`; `quarantine` makes every instance of this application keep a failed cleanup as a retryable frontier instead of a report (D182)                                                                             |
+| 4    | the controller starts in its constructor: opening begins synchronously, before the first `await`                                                                                                                                                                  |
+| 5    | features with an empty `when` open **sequentially**, in compilation order: `open()`, then `await ready`, then the next one                                                                                                                                        |
+| 6    | conditions with `from` are computed from the exports of the source features that opened                                                                                                                                                                           |
+| 7    | every condition group gets a reconciler: the desired state is `all(conditions) === true`; before it opens, a group waits for the providers of its hard edges in other groups to become ready, and before it closes it waits for their consumers to be gone (D123) |
+| 8    | an `ApplicationExecution` with `ready` and `close()` is returned                                                                                                                                                                                                  |
+
+A group reconciler is one serialized worker with epochs: a condition change raises the epoch, fences the unfinished
+opening and schedules a reconcile on a microtask; members open sequentially with an epoch check before each one, and
+closing always runs in reverse order and tolerates failures. A condition source must publish a boolean synchronously
+when it is installed, otherwise the error is immediate.
+
+`close()` runs once: it releases the condition subscriptions in reverse order, fences the unfinished opening,
+closes the groups in reverse order, awaits `ready`, retires the permanent features in reverse order, and collects
+failures into one error. The observation session closes in `finally`, after the drain, so it sees the final group,
+instance and contribution transitions (D167). The shared close promise exists before any source disposer runs.
+If a condition subscription closes the application before returning its disposer, that disposer is released
+immediately on return, no further group is installed, readiness rejects and close drains all started work (D210).
+
+### 1.3 Lifetime: `when`
+
+A feature declares the conditions it lives under: `when: [authorized, miningEnabled]`. An empty `when` is a permanent
+feature. Features with an identical condition set open and close together, and imports order them inside the group.
+The set-inclusion law says something simple: you may not hard-depend on something that can die before you do. A
+consumer that wants to read the data of a shorter-lived feature takes the weak `optional` edge and gets a `Lookup`
+projection with a `missing` state (§2.4); a weak edge neither affects the activation of its provider nor pulls it into
+the application world (D106).
+
+## 2. The feature instance
+
+### 2.1 At definition, once
+
+The eager `defineFeature` form runs the `own` factory once and turns it into an intermediate representation made
+of three kinds of kernel node: scope, attachment, call. A split header instead declares topology; its
+`defineFeature.body` builds that representation when the body code loads (D186, D207). Everything authored reduces
+to these nodes:
+
+| In `own`                                                  | What it lowers to                                                                                                                                                                             |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `attach(source, { open, close })`                         | a scope with one attachment                                                                                                                                                                   |
+| `call({ run, within, lane, once, singleFlight, policy })` | a call node bound to the attachment from `within`                                                                                                                                             |
+| `calls(imports.x, [...])`                                 | an implicit attachment on the source with no lifecycle, plus one call per key                                                                                                                 |
+| `lane({ within })`                                        | a lane record, materialized per instance                                                                                                                                                      |
+| `effect`, `event`, `resource`, `stream`, `scope.*`        | an attachment with a controller inside                                                                                                                                                        |
+| `requires.x`                                              | one call on the hidden requirements attachment, which forwards to the port provider; with `optional(port)` it settles a `CallError` with code `unavailable` while there is no provider (D105) |
+| `model(...)`                                              | **not a kernel node** but a data descriptor; the model factory does not run here; owned state lives only inside the model (`ctx.state`, D139)                                                 |
+
+`exports` is a factory of the form `({ own }) => …`. It runs when the instance opens, against a live `own`, and every
+field of the record it returns must be a live value form — a `Call`, a `Readable` or a `Resource` — checked key by key
+(D88). `provides` runs once, synchronously, and is split into ports and contributions by the builder that produced each
+entry. Every attachment of a feature is critical: the instance is not ready until all of them are.
+
+### 2.2 Opening an instance
+
+| Step | What happens                                                                                                                                                                                                                                                                                                             | Where                                      |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
+| 1    | options are snapshotted; `imports` and `requirements` hold exactly the declared fields; an attachment takes its value only from an import or a requirement; a port value is checked against its declaration                                                                                                              | `runtime/src/feature-generation.ts`        |
+| 2    | an instance record is created in state `assembly`                                                                                                                                                                                                                                                                        | `public-module-instance.ts`                |
+| 3    | **`prepare` runs synchronously, before the first scope opens**: the model rollback participant is registered before any factory runs; then the factories create their owned nodes; then the export facade is built (it materializes `own` values lazily); then the contribution participant is registered                | `module-generation.ts`, `feature-model.ts` |
+| 4    | scopes open sequentially; before each one the runtime checks whether cancellation was requested                                                                                                                                                                                                                          | `module-generation.ts`                     |
+| 5    | inside a scope the attachments form one wave with no order among them (D163): critical ones start before the owner commits, readiness is counted with counters and never recurses into promises; when no critical one is left the scope publishes the owner authority, calls become live, and deferred attachments start | `module-scope-open.ts`                     |
+| 6    | the internal ready barrier yields `{ exports }`; contributions are then published, and only after successful publication does public `instance.ready` resolve                                                                                                                                                            | `feature-generation.ts`                    |
+
+The laws: `prepare` must return synchronously; retire participants are registered before the first scope opens; the failure of a critical attachment moves the scope straight into retire, while the failure of a deferred one leaves the others and the scope's readiness untouched; a failed attachment lands in the quarantine frontier in canonical slot order.
+
+Seen from the inside, an attachment is a small machine with a mailbox: at most one active and one waiting intent; a new
+intent either joins a compatible one, replaces one that has not started, or queues up and cancels the active one.
+Opening takes a permit from the readiness controller, collects a cleanup list (the first entry is always `close`), and
+any error rolls the attempt back in the reverse order of that list.
+
+### 2.3 Retire: fence, drain, settle
+
+```text
+retire()  →  fence (synchronous, one pass)  →  drain (asynchronous, in parallel)  →  settle (policy)
+```
+
+1. **Fence.** The state becomes `retiring`. Participants run in registration order: contributions are withdrawn from
+   their targets, the data scope is fenced — models are made inactive, the `AbortController` fires, `state` cells are
+   closed. Then every scope is fenced. Fencing is what turns any later work into a cancellation: the call authority is
+   invalid, and a new call through that attachment settles with a `CallError` as a cancellation rather than as a product
+   failure. Nothing is thrown; only the cleanup frontiers are collected.
+2. **Drain.** All frontiers run in parallel; the attachments of one scope drain as one wave, with no order among them (D163). Calls: pending ones are cancelled, executing ones get an
+   abort, the `once` cache and the single-flight map are cleared, lane leases are released. Timers: the registry is
+   closed, and after that `delay` and `interval` throw. Model subscriptions and disposers run, and failures are
+   collected.
+3. **Settle.** With no failures: state `retired`, every call target revoked, references dropped, the outcome is
+   `closed`. With failures under the `report` policy (the default): the instance is workspace anyway, and a
+   `FeatureError` with code `cleanup-failed` goes to the `reporter`. Under the `quarantine` policy: the outcome is
+   `quarantined`, with a `FeatureError` carrying code `quarantined` and an optional `retryCleanup()` capability that repeats exactly the
+   remaining cleanup frontier under a re-entry guard.
+
+Retire is idempotent and cannot be started from its own callback.
+
+The public instance names this operation `close()`; internal coordinators keep `retire`. Logical cancellation
+settles a waiter without proving that an in-progress `open` or call physically stopped. The drain joins the work
+already admitted and its late cleanup before releasing the source. A stream also joins its active `consume`
+before closing the connection and releasing the imported value (D170).
+
+### 2.4 Edges between features
+
+| Edge                      | What the consumer sees                                                                                                                                                                                                                | Who guarantees safety                                                                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `imports: { x: feature }` | the live `Call`, `Readable` and `Resource` values of the provider instance                                                                                                                                                            | order: the provider opens first, the consumer closes first                                                                         |
+| `optional(feature)`       | `Readable<Lookup<Exports>>`: `found` while the provider instance is open, `missing` while it is closed or absent from the application                                                                                                 | one subscription on the consumer side; the edge neither affects the provider's activation nor pulls it into the world (D105, D106) |
+| `optional(port)`          | a `Call` that settles a `CallError` with code `unavailable` while there is no live port provider                                                                                                                                      | the same weak law (D105)                                                                                                           |
+| a host contract           | the value bound with `bind` at `openApplication`; `optional(contract)` gives `Readable<Lookup<T>>` with `missing` when the host did not bind it, while `onDemand(contract)` keeps the plain value and only marks the edge as deferred | the host                                                                                                                           |
+| a port, `port`            | a `Call`; the application picked the provider                                                                                                                                                                                         | the compiler: exactly one provider                                                                                                 |
+
+Models never cross a feature boundary: the UI law "a model is read only inside its own feature" rests precisely on
+that.
+
+## 3. The model and its kernel
+
+### 3.1 What is created when
+
+| Step | What happens                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | at definition, `own.model(Decl, deps?, factory)` only records a descriptor; the factory does not run                                                                                                                                                                                                                                                                                                                                    |
+| 2    | when the instance opens, inside `prepare`, the descriptors are walked in declaration order and each `model` receives a fresh kernel with the id `<feature>.model.<n>`                                                                                                                                                                                                                                                                   |
+| 3    | the kernel is a readiness controller (which is also the fence of the model), a timer registry on a shared `AbortSignal`, and the lists of executors and disposers                                                                                                                                                                                                                                                                       |
+| 4    | the factory runs **synchronously**; every `ctx.call`, `ctx.calls(source, keys, { lane? })` (the same selection rules as `calls` in `own`: a source method `(input, signal) => Output` becomes a `Call`, D143), `ctx.effect`, `ctx.resource`, `ctx.stream`, `ctx.event`, `ctx.scope`, `ctx.lane` and `ctx.state` creates its node immediately with the id `<model>.<kind>.<n>`; `ctx.cleanup(disposer)` registers a model cleanup (D107) |
+| 5    | the returned record is frozen and stored under the descriptor ref                                                                                                                                                                                                                                                                                                                                                                       |
+| 6    | the model fence: readiness is withdrawn and the timers are closed, then the abort fires and the cells close; the drain: executors are retired, then every model disposer runs in the reverse order of registration and failures are reported; registering anything after the fence is a `TypeError`                                                                                                                                     |
+
+The dependency descriptor is a map of authentic current-feature import and call refs. Materialization resolves
+it once to a readonly map before calling the factory; optional imports stay lookup readables. The zero-dependency
+form is `model(Decl, factory)`. Model-to-model refs are not a dependency graph. A model-backed port selects its
+call once after model creation and wraps even a passthrough call with the provider instance's fence (D169).
+
+The kernel owns rollback before entering user code, so a factory that creates nodes and then throws still drains
+them. The same rule holds for per-mount UI models. A fence synchronously closes every owned state and rejects
+all subsequent node constructors; no late call, timer or subscription can escape that lifetime (D170).
+
+### 3.2 `state` and `update`
+
+`ctx.state(initial)` returns an `OwnedState<Value>`: a `Readable` with an ownership brand. `ctx.update(state, value)`
+accepts only that — a derived `Readable` does not compile, and a sibling model's `OwnedState` is rejected at runtime
+by a private owner lookup. A write after
+the fence does not throw at the writer; it is reported as a `FeatureError` with code `retired`. Writes that are equal
+under `Object.is` stay silent.
+
+### 3.3 The call: `ctx.call({ run, lane?, once?, singleFlight?, policy? })`
+
+`ctx.call(options)` creates the command; the `run` callback's `context.invoke(target, input)` executes an existing
+one. The execution member is `invoke` in every context that provides it, including trusted attachment steps;
+the factory `call` and the selected-method sugar `calls` keep their names (D243).
+
+Selected host methods can take no parameters, one input, or an input followed by `AbortSignal`, including optional
+input/signal (D244). The runtime calls each method with `(input, signal)` and its original receiver. It does not
+inspect function arity; a lone parameter is always the input. Physical work that ignores cancellation still drains,
+even if its caller has already settled as cancelled.
+
+The default `queue` policy serializes calls through a lane; `latest` serializes them the same way but keeps one
+waiting place; `parallel` starts them immediately, and `parallel` with a `lane` is refused. Per call:
+
+1. if the parent signal or its own signal is already aborted, a cancelled call is returned;
+2. a closed executor or a fenced instance yields a cancellation;
+3. a hit in the `once` cache returns the already settled result;
+4. a hit on a `singleFlight` key joins the live execution;
+5. otherwise a new execution: `parallel` starts at once, `queue` and `latest` take a lane lease in FIFO order, and if
+   the lane is already on top of the caller's stack it is reused without waiting;
+6. `latest` first frees its waiting place: the invocation of the same call that still sits last on the lane is
+   cancelled before this one asks for the lease, so one waiting input survives and lane order is untouched (D185).
+
+A nested `context.invoke(target, input)` inherits the lifetime of the authority and the lane stack, so cancelling the
+parent cancels the child, and a lane cannot form a cycle: requesting a lane that sits below the top of the stack is a
+cycle error, and so is joining your own execution.
+
+### 3.4 `effect` and `timers`
+
+`ctx.effect({ from, run, when?, onDispose? })` subscribes to the source and runs immediately for the initial
+value. Inside it is one serialized loop: a new value cancels the current run, waits for its disposer, checks
+`when`, creates a new `AbortController` and timer registry, and starts `run`. Intermediate values are lost: only
+the latest one lives. `run` returns `void` or a disposer.
+
+`ctx.timers.delay(ms, run)` and `ctx.timers.interval(ms, run)` register their cancellation in the model registry; once
+the registry is closed, both throw.
+
+### 3.5 The UI models of a contribution
+
+A slot contribution may declare `models: [model(Decl, (ctx, props) => …)]`: plans that the contribution frame
+instantiates on every mount. `props` is a `Readable` of the slot props of that particular mount, and the kernel of
+such a model lives from mount to unmount. The law: instances are created in commit and never in render (D188). The
+first pass of a contribution renders nothing, a `useLayoutEffect` keyed by the identity of the contribution builds the
+mount from the props that committed and publishes it, and React flushes that extra synchronous render before paint;
+the contribution identity owns it until actual replacement or unmount. A render that is thrown away — StrictMode's double invoke, an abandoned
+concurrent pass, a subtree suspended by a lazy sibling — therefore creates nothing, so there is no sweep, no adoption
+and no rebuild, and a child layout effect always sees a live model. Incoming slot props reach the live mount through
+its own layout effect, so an interrupted render still cannot write to a model. Granting is hybrid (D158): the `own` models of the feature reach every component of the mount's subtree implicitly, while a per-mount UI model is declared with `requiresModels([X])` by the component or hook of the same module that reads it with `useModel(X)`. The declaration belongs to each reader, not only to the contribution site (D117).
+
+StrictMode effect replay and Suspense hide/reveal reuse the same committed model bundle and preserve state.
+Actual replacement or unmount releases it once; when a hidden subtree unmounts, a microtask releases it because
+React has already disconnected its layout effects. Insertion effects mark retirement without notifying Readables
+(D209).
+
+A mounted model reads props from the mount-owned state. Direct props and the optional props adapter read that
+same snapshot; incoming slot props are published in layout before paint. No state update runs in insertion
+effects. A demand retry keeps its source identity, so an unfinished retry from a replaced source cannot block
+or overwrite the new source's retry (D170).
+
+## 4. Reactivity
+
+### 4.1 The contract and the sources
+
+```ts
+interface Readable<T> {
+  getSnapshot(): T;
+  subscribe(listener: () => void): () => void;
+}
+```
+
+A listener is handed nothing; it re-reads. A state cell (`createState`, internal only since D142; the author receives
+it as `ctx.state` of a model) holds the value and a set of listeners; `set` and `update` stay silent on an `Object.is`
+match; after `close()` both reading and writing raise a `ReadableError` with code `closed`. Closing propagates:
+`close()` is one notification to the dependents, after which active `derive`, `computed`, `collection` and
+`selectByKey` answer `closed` instead of the last value and then stay silent; an unsubscribed derived node gets the
+same failure on its next read (D146).
+
+### 4.2 `derive` and `computed`
+
+Both are nodes of one graph with a "push invalidation, pull recomputation" model: a node has a freshness of `clean`,
+`check` or `dirty` and a monotonic revision. An unsubscribed node recomputes on demand in `getSnapshot()`, with no
+upstream subscription needed. A node becomes active when it has listeners or dependents, and deactivates with a
+one-microtask delay so that resubscribing within the same tick does not drop the upstream lease.
+
+`computed({ read: get => … })` rebuilds its dependency map on every recomputation from the `get` calls and remembers
+their revisions; in the `check` state the body does not run if no revision moved. Re-entering a computation is a
+"cycle" error. A transition from `error` to `value` counts as a change even when the value is equal.
+
+### 4.3 One scheduler
+
+Glitches are impossible by construction: a single scheduler stabilizes every pending node in topological order before
+it publishes, and only then calls the listeners. Invalidation and traversal are iterative, so a chain of a thousand
+nodes does not overflow the stack. Reading an active clean node returns the settled value with no graph walk, O(1)
+instead of O(graph), and that is pinned by the `coreData.settledRead` budget (D130). Activation is transactional: if a
+node fails to activate, the already activated nodes roll back in reverse order, and disposer failures during the
+rollback are aggregated with the original cause, so no part of the graph stays active without a subscription owner
+(D134).
+
+When listeners learn about a change:
+
+| Source                                           | When                                                                             |
+| ------------------------------------------------ | -------------------------------------------------------------------------------- |
+| the direct listeners of `State.set`              | synchronously, inside the write transaction                                      |
+| `derive` and `computed` downstream of that write | synchronously at the end of `set()`: the transaction closes and drains the queue |
+| an external source with no open transaction      | it opens its own transaction, then the same                                      |
+| an invalidation with no transaction              | the next microtask                                                               |
+| nested writes                                    | one publication at the outer transaction boundary                                |
+
+### 4.4 Collections
+
+`collection({ from, key, project })` keeps a projection cache keyed by the item object, stable lookups by key, and
+listeners per key: `selectByKey(source, key)` wakes only when its own key changes. Duplicate keys are an error. Unused
+selectors are swept through a microtask.
+
+### 4.5 Hooks
+
+| Hook                         | Mechanics                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useReadable`, `useSelector` | `useSyncExternalStore` with a cache of the selected value; the same getter for client and server                                                                                                                                                                                                                                                            |
+| `useResource`                | `useSyncExternalStore` over the snapshot plus `retain()` in an effect: the mount is the lease                                                                                                                                                                                                                                                               |
+| `useModel`                   | the nearest contribution mount frame; outside a frame a `ContributionError` `missing`, an inactive mount `inactive`, a foreign model `missing`                                                                                                                                                                                                              |
+| `useCommand`                 | per-consumer state, with no listener on the invoker: `run` returns a promise of the outcome, `inFlight` for the duration of the call, `result` the last `ok` outcome, which survives the next run, `lastError` the error of the last `failed`, cleared only by a success and never reset by starting a retry (D116); a cancellation changes neither of them |
+
+`useCommand` keeps status per hook and invoker, and schedules nothing: every `run` reaches the call, whose declared
+policy decides whether it queues, replaces a waiting input or runs in parallel (D203). Each request owns its
+callbacks and abort subscription, an already-aborted signal is refused without reaching the call, and a run of an
+unmounted consumer is refused the same way. `inFlight` is true while any run this consumer started is unsettled.
+
+## 5. Resources, streams, events
+
+Both the feature and the model select their target with `(source) => Readable<T | null | undefined>`; the
+returned object is checked before work starts. A scalar snapshot does not satisfy the contract. `retention` is
+optional in either context and `scoped({ capacity })` fixes LRU eviction (D169).
+
+### 5.1 `resource(from, target, { key, load, retention, retry })`
+
+| Step | What happens                                                                                                                                                                                                                                                    |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | the retention `scoped({ capacity })` activates the controller immediately, so the resource is warm with no observer; the `observer` retention — the literal `{ kind: 'observer' }` and the default — activates on the first lease (D160)                        |
+| 2    | activation subscribes to `target` and reads it; a `null` target closes the selection                                                                                                                                                                            |
+| 3    | a key change: the same key updates the target without a reload; a new key fences the execution, advances the key epoch and takes the value from the LRU cache if it is there, otherwise it publishes `opening` (no data) or `refreshing` (stale data) and loads |
+| 4    | `load(target, { signal, source })`; the result is accepted only if the execution, the key epoch and the activity did not change                                                                                                                                 |
+| 5    | on failure: a retry per `retry: { attempts, delayMs }`, then `status: 'error'` with `retryable: true` and a report to the `reporter`                                                                                                                            |
+| 6    | the last lease released under `observer`: deactivation through a microtask, guarded by a revision                                                                                                                                                               |
+| 7    | closing in drain: fence, unsubscribe, clear the cache, `idle`, await the unfinished operations                                                                                                                                                                  |
+
+`refresh()` reloads the same key past the cache and keeps the data; `retry()` works only from `error`; `invalidate()`
+clears the cache and reloads without keeping the data.
+
+### 5.2 `stream(from, target, { connect, consume, key, backpressure })`
+
+The same key-and-epoch machine plus a one-slot admission layer: the only policy, `latest()`, keeps the newest pending value (D160). Every value is cached and published as `ready` first, then handed to the
+author's `consume`. On a key change the new connection waits for the disposer of the old one: connections never
+overlap. `backpressure` is required at runtime.
+
+### 5.3 `event(from, subscribe, { run, backpressure })`
+
+A one-slot queue in front of a sequential `run`, and the option says who owns the slot. Without `backpressure` it
+belongs to the payload that reached it first: while `run` is busy and one payload waits, a newer `emit` is dropped and
+reported as a `queue-capacity` failure record — drop-newest, the shape `exhaustMap` and `takeLeading` have. With
+`backpressure: latest()` the newest payload replaces the waiting one and nothing is reported — conflation, the shape
+`conflate` has; unlike `switchMap` it never interrupts the `run` that is already going (D247). A lossless queue is
+neither policy and stays an open question (D183). `run` executes sequentially, must resolve to `undefined`, and
+errors after a cancellation are swallowed. Cancelling the owner closes the queue and drops whatever waits in it, and
+closing waits for the disposer and for the queue to drain.
+
+## 6. Contributions and slots
+
+### 6.1 Publication
+
+| Step | What happens                                                                                                                                                                          |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | at definition `provides` yields opaque declarations `{ target, value, priority, when }`; the value is always normalized to an instance-scoped factory                                 |
+| 2    | every contribution gets the id `<feature>.<key>`, one key per declaration                                                                                                             |
+| 3    | the compiler enumerates the contributions by id                                                                                                                                       |
+| 4    | in `prepare` a retire participant is registered whose fence withdraws the publication; the authority is captured: the models of the instance                                          |
+| 5    | **after `ready`** the factories run with the instance context, the value is marked with its owner, and `when` is resolved: a predicate becomes one computed readable of that instance |
+| 6    | every affected target is updated **in one transaction**, and listeners are called afterwards                                                                                          |
+
+Entry order: `priority` ascending, ties broken by id. `when` (a `Readable<boolean>`, or a predicate of the instance
+that the runtime lowers to one): an entry whose value is `false`
+is not part of `entries`, so `Slot`, `fold`, `select` and emptiness checks never see it; a flip publishes in one
+transaction; id uniqueness is checked across everything published, so a flip can never fail validation. Publication is
+atomic: subscribing a `when` and reading it happen in a preflight before any target is mutated, releasing the watcher
+of a departing entry happens after every target is committed, and a publication reads only the `when` of its own
+entries, so a withdrawal reads none at all (D225). A failure rolls back the observers that were added and leaves the
+targets untouched, a `when` that signals mid-projection makes the affected targets project again, and withdrawing a
+publication that never reached `published` removes whatever did land (D124).
+
+### 6.2 Rendering a contribution
+
+`Slot` reads the `entries` of the target through `useReadable`, returns `null` for an empty list, and otherwise renders
+the `Component` of every entry with the slot props, wrapped in the authority frame of the contributing feature: inside
+a contribution, `useModel` reaches the models of its own feature and nothing foreign. A contribution with no models
+does not pay for the frame. A contribution is `{ Component, props?, models? }`: `props` maps the slot props into the
+component's own props, `models` supplies the per-mount UI models, and a component built with `requiresModels([...])`
+declares which of them it needs, which is checked by the type at the contribution boundary. A mount is memoized:
+publishing or withdrawing one contribution does not re-render the other mounts of the same target (D130).
+
+### 6.3 `fold` on a pipe
+
+`fold(value, meta, read?)` walks the handlers in order; with a reader passed inside a `computed`, the dependencies
+include both the entry list and everything the handlers read through their `{ read }`, so the result recomputes when
+their sources change rather than only when contributions are re-registered. Without a reader the reads are untracked.
+
+A handler is declared as a descriptor, `pipe(target, { fold })`, and the runtime binds one evaluation context to it
+when the contribution publishes: `exports`, `imports` and the materialized `own` are resolved once and the reader is
+the only thing that changes from call to call, so folding over many handlers allocates no per-handler context
+(D223). A `fold` is the only thing that runs a handler: declaring, preloading and publishing do not.
+
+### 6.4 The registry
+
+`defineRegistry` is a target built on top of `collection`: `byId`, `list`, and `select(key)` with
+`{ kind: 'found' | 'missing' }`. A duplicate key is an error.
+
+## 7. Errors
+
+One class per subject, with the state in the `code` field.
+
+| Class                  | Codes                                                        | Who throws it                                                                                                           |
+| ---------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `FeatureError`         | `retired`, `not-ready`, `quarantined`, `cleanup-failed`      | the instance fence, a failed opening, the settle of a retire                                                            |
+| `CallError`            | `cancelled`, `closed`, `publication-rejected`, `unavailable` | the call kernel; cancellation is only `cancelled` and `closed` (D138)                                                   |
+| `ReadableError`        | `closed`                                                     | reading and writing a closed cell                                                                                       |
+| `DeclarationError`     | `invalid-id`                                                 | `declarationId`                                                                                                         |
+| `ApplicationError`     | `closed`                                                     | the application closed before it was ready                                                                              |
+| `ContributionError`    | `binding-invalid`, `duplicate`, `inactive`, `missing`        | a contribution mount: a hook outside a frame, an inactive frame, a duplicate model, an invalid model or command binding |
+| `CancellationError`    | no code, only the cancellation brand                         | an author cancellation, which `isCancellation` recognizes                                                               |
+| `FeatureBoundaryError` | `missing`                                                    | `useFeatureRetry` outside the error subtree of a boundary                                                               |
+
+Cancellation is a property of the error, not a class: the predicate `isCancellation` (internal, the author does not
+need it — cancellation is read by `useCommand` and `resource`) looks at the brand carried by `CancellationError`, by
+`CallError` with codes `cancelled` and `closed`, by `FeatureError` with code `retired`, and by `ContributionError` with
+code `inactive`. `unavailable` and `publication-rejected` are product answers: `useCommand` shows them as a `failed`
+outcome with the error in `lastError`, and `resource` shows them as an error (D138). Neither `useCommand` nor
+`resource` shows a cancellation as a user-facing error.
+
+The path an error takes to the application: the `reporter` from `defineApplication` is passed to every `openFeature`,
+and from there into model kernels, timers and controllers; the single funnel `reportRuntimeFailure` falls back to the
+global `reportError` or to a deferred `throw` when the `reporter` is absent or itself fails. A condition group reports
+its failures while it is running and holds only the ones raised after `close()` started, which `close()` then throws.
+
+## 8. Boundaries and the host
+
+The table names the everyday entries; the exhaustive export lists live in spec.md §3.
+
+| Entry                        | For whom                        | What is there                                                                                                                                                                                                                                                 |
+| ---------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@opetope/core`              | the feature author              | `defineModel`, `definePort`, `definePipe`, `defineRegistry`, `declarationId`, `derive`, `computed`, `externalReadable`, `collection`, `selectByKey`, the errors, and the types `Readable`, `Lookup`, `Call`, `Port`, `ModelContext`, `OwnedState`, `Resource` |
+| `@opetope/runtime`           | the feature author and the host | `defineFeature`, `defineHostContract`, `onDemand`, `optional`, `openFeature`, `defineCondition`, `defineApplication`, `openApplication`, `bind`, `scoped`, `latest`                                                                                           |
+| `@opetope/react`             | the component author            | `useModel`, `useReadable`, `useSelector`, `useCommand`, `useResource`, `defineSlot`, `defineSwitchSlot`, `Slot`, `requiresModels`                                                                                                                             |
+| `@opetope/react/integration` | the host                        | `FeatureBoundary`, `useFeature`, `useFeatureRetry`, `FeatureBoundaryError`                                                                                                                                                                                    |
+| `@opetope/react/testing`     | tests                           | `renderSlot`, `command`, `createScenario`, `ScenarioTimeoutError`                                                                                                                                                                                             |
+| `@opetope/*/internal`        | framework and host integration  | the kernel, the compiler, the controllers, `createState`, `isCancellation`, the observation port `createInspectionSession` and the control port `createControlSession`; unavailable to authors (D142)                                                         |
+
+The `exports` field of `package.json` exposes exact entry points without wildcards. Feature authors use the safe
+entries; host integration and testing use their dedicated entries. Application import rules preserve this
+separation between roles.
+
+A demand-driven host shows feature UI like this: `FeatureBoundary` takes a lease on the instance through `useFeature`,
+opens it if needed, shows `fallback` while it opens and `error` on failure, and inside renders `<Slot target props />`,
+which is where the feature contributed its UI. Unmounting the boundary releases the lease; the last released lease
+leads to a retire.
+
+### 8.1 Observation
+
+The observation port (D122) lives on `@opetope/runtime/internal`:
+`createInspectionSession(execution, { ringCapacity })`, where `execution` is the result of `openApplication`. A
+`WeakMap` holds the link; there is no global hook and no public value, and an application has at most one session.
+Until a session is opened the application records nothing; `close()` detaches the observer without touching the
+application. The consumer gets exactly four methods — `getSnapshot`, `readSince`, `subscribe` and `close` — and cannot
+steer the graph it reads. The runtime implements the `@opetope/devtools` protocol rather than importing it, and the
+`ci:inspection` gate holds the correspondence.
+
+Both ports stay on `/internal` because the package that calls them is `@opetope/devtools`, not the application. A
+host attaches the panel with `installDevtools({ execution, … })` and touches this entry for nothing else (D248).
+
+### 8.2 Control
+
+The write port is a second, separate factory on the same entry: `createControlSession(execution)` (D176). Holding an
+inspection session does not mean holding the right to write, so the two have their own registries and their own
+authority. The only controllable subject is a condition and, through it, its group: `suspend(conditionId)` sets a
+debug override that forces the condition to read `false`, `resume(conditionId)` removes it, and the group follows its
+own source again. A feature without `when` has no condition and is therefore not addressable at all — devtools never
+becomes a source of lifetime the plan does not have.
+
+The override wraps the condition's own `Readable`, so a suspended group deactivates through the ordinary
+transactional path: the same scheduler, the same atomic frame, and the dependency law of
+[devtools.md §5.3](devtools.md) —
+suspending a provider takes its hard dependents with it through their own semantics, while suspending a consumer
+leaves its provider alone. The frame the transition publishes names the control command as its cause, so «what I did»
+and «what happened» read as one line of the timeline, and the group snapshot reports the override next to the product
+truth: `desired.source` is what the condition says, `desired.effective` is what the runtime acts on, and
+`desired.override` is `force-inactive` while the override stands.
+
+`retryCleanup(instanceId)` repeats the cleanup of an exact quarantined frontier through the existing retry contract;
+an instance that is not quarantined answers `not-controllable`. A refusal is data, never an exception:
+`{ kind: 'rejected', reason: 'not-controllable' | 'stale' | 'unknown-target' }`, and an applied command answers with
+the sequence of the frame its effect is visible in. `close()` releases every override the session holds, so closing a
+panel never leaves the application in a debugged state, and an override lives only in the current execution — it does
+not survive a reload or HMR.
+
+## 9. How to verify this
+
+- A feature instance in a test: `openFeature(feature, { imports, reporter })`, then `ready`, then `close()`; fakes of
+  host contracts are ordinary objects.
+- A contribution component: `renderSlot(target, { props, models })` mounts the contribution with a fixture of per-mount
+  models and gives back `updateProps`; `command(run)` mints an authentic `Call` for a fixture.
+- The application graph: `defineApplication` in a manifest test catches a missing provider, a cycle and a violation of
+  the condition-set inclusion law before anything starts.
+- Budgets and gates: `ci:public-surface` counts the public words and forbids kernel and retired words on the safe
+  entries; `ci:perf-memory` measures retained memory, listeners and the linearity of operation cost, including
+  `coreData.settledRead` and the allocations of a write with no listeners (`unobservedWrite`, the median of three runs
+  of 100k operations); `ci:type-stress` measures the cost of the types, and language-service latency is printed for
+  information only; instantiations, memory and diagnostics are enforced (D224); `ci:browser-floor` holds the syntax and API level
+  of Chrome 82; `ci:inspection` checks the contract of the observation port; `ci:size-limit` holds five budgets the
+  author sees (core `author primitives consumer` 1.1 kB and `data layer consumer` 4.9 kB, runtime
+  `public feature consumer` 32 kB and `application graph consumer` 48 kB, and `@opetope/react` 18 kB).
+- Authoring review: every component and hook of the module that reads a per-mount contribution model with
+  `useModel(X)` declares `requiresModels([X])`; owner models need no declaration (D117, D158). Imports use the
+  package entry points permitted for their role.
+- Application build verification: the consuming host checks its bundle budgets and verifies that intended dynamic
+  boundaries survive bundling; package size fixtures do not measure the complete application.