@opetope/runtime 0.1.0

package/docs/devtools.md

@@ -0,0 +1,423 @@
+# Opetope Devtools
+
+One truthful projection of the compiled topology and the current runtime state, and an answer to the question
+"why is this node in this state". `@opetope/devtools` is an optional development tool; keep its integration out of production bundles.
+
+This document is normative for the devtools: the observation protocol, the architecture that delivers it, the panel
+that renders it, and the condition control that writes back. Where this document and
+the runtime disagree, the runtime and [`spec.md`](spec.md) win, and the difference is recorded in §9.
+
+## 1. What it is and what it is not
+
+It answers: why a feature is not active; what it is waiting for; which instance is current and which retired; what
+its contributions reach; what happened before a failure.
+
+It does not read model or repository values, React props or call payloads. It does not replay side effects, edit the
+declaration graph, replace feature flags, or reach the network. Error text never enters the protocol: a failure is a
+bounded code, a subject and a phase.
+
+## 2. Observation protocol
+
+### 2.1 Two projections
+
+A snapshot carries `plan` — the immutable topology the application compiler produced — and `runtime` — the live
+world it opened. They are never merged: a feature declaration outlives many instances of it, and collapsing the two
+is the mistake this protocol exists to prevent. Topology is immutable inside one session; a plan replacement opens a
+new `sessionId`.
+
+### 2.2 Nodes
+
+Named with the public words of [`spec.md`](spec.md) §3: `application`, `condition`, `condition-group`, `feature`,
+`feature-instance`, `attachment`, `contribution`, `contribution-target`, `port`, `host-contract`, `absent-provider`.
+
+A condition group is the inferred owner of activation: features whose `when` names the same set of conditions form
+one group. A feature with an empty `when` is owned by the application itself. `absent-provider` is a feature export
+contract the plan names with nothing behind it, so an `absent-import` edge has an origin to point at.
+
+### 2.3 Edges
+
+Orientation is fixed: provider, blocker or owner → consumer, waiter or owned node. Three classes:
+
+- **hard** — `hard-import`, `requires-port`. The only edges an activation waits on; they carry `pending`.
+- **weak** — `optional-import`, `optional-port`, `absent-import`, `absent-port`. One word, `optional`, for features
+  and ports. The consumer may outlive the provider, reads a `Lookup` (`found` or `missing`), and never waits.
+- **structural** — `owns`, `provides-port`, `contributes-to`, `condition-control`, `on-demand-import`. No state of
+  their own.
+
+The compiler emits one `requires-port` kind for both strengths; the protocol splits it by
+`CompiledApplicationRequirementIR.optional`, symmetrically to the import pair the compiler splits itself.
+
+### 2.4 State automata and the three axes
+
+There is no universal `node.status`. Each kind carries the automaton the runtime actually has: the condition group
+from `condition-group-execution.ts`, the feature instance from the `FeatureError` codes of `spec.md` §4, the
+attachment from `AttachmentLifecycleSnapshot`, the contribution from the hub (`published`, and `withheld` when its
+`when` reads false), the port from the compiler's single-provider selection, the host contract from `bind`.
+
+The panel styles nodes from three orthogonal axes derived from those unions, never the reverse:
+
+- `desired` — `active` or `inactive`, with source, override and effective values;
+- `lifecycle` — `declared`, `waiting`, `opening`, `ready`, `fencing`, `retiring`, `closed`;
+- `health` — `healthy`, `blocked`, `failed`, `cancelled`, `stale`, `quarantined`.
+
+`declared` is the seventh lifecycle value: a feature the plan declares while nothing has opened it is in none of the
+other six, and calling it `waiting` would claim a blocker that does not exist.
+
+Fetching a header's `body` adds no eighth value. The instance exists and is `opening` until its code arrives, which
+is what the runtime reports and what the panel draws (D186); a `loading` of its own would have been a second word for
+a state the protocol already has, and the legend would have had to explain the difference.
+
+### 2.5 Failures, phases and causes
+
+A failure is the runtime's own error, as a discriminated pair of `subject` and `code`: `feature`, `call`, `readable`,
+`contribution`, `application`, `declaration`. Phases are the vocabulary of D14: `open`, `close`, `rollback`, `fence`,
+`drain`, `retry`. A cause is a ref the panel resolves against the snapshot, never prose.
+
+The protocol has exactly one clock, `cause.at`, and it stamps the trigger rather than the commit. States carry no
+timestamps: a second clock would let the panel show durations the runtime never measured. A frame with no cause has
+no time, and the timeline renders that column empty.
+
+When present, `cause.at` is a non-negative integer of epoch milliseconds no greater than
+`8_640_000_000_000_000`, the maximum valid Date timestamp. Sequence and revision counters retain their separate
+non-negative safe-integer domain (D242).
+
+### 2.6 Identity, labels and redaction
+
+Ids are data, and one id names one thing. A diagnostic id is a kind prefix and the declaration ids of its parts,
+joined with `:`; a part is escaped with `_` first, so a character the consumer's grammar rejects — `/` in a
+declaration id, `|` in the key of a condition group — survives as itself rather than being folded onto its
+neighbour, and the parts of a composed id stay separable (D200). A label is presentation metadata the compiler
+derived from a declaration — the panel renders it and never translates it, and it is never authority. Snapshots
+hold no callbacks, no `FeatureInstance`, no models or resources, no raw `Error`, `AbortSignal` or thenable, no DOM or React instance. Export is canonical data-only JSON
+under record limits, delivered to the clipboard or a local file; there is no network transport.
+
+Application nodes use `application:<encoded declaration id>`; feature nodes keep their encoded declaration id.
+An application and a feature may share a declaration id while their diagnostic identities remain distinct (D242).
+
+## 3. Observation architecture
+
+### 3.1 Ownership of semantics
+
+The runtime owns ids, kinds, transitions and cause refs. Devtools does not scan private maps, patch methods or
+reconstruct the graph from logs, so the production scheduler and the debugger describe one machine.
+`RuntimeInspectionSession` is a _consumed_ interface: the runtime owns its semantics and imports nothing from here,
+so nothing in the runtime knows this package exists. The protocol, the reducer, the projections and the panel import
+no `@opetope/*` package either. The one exception is `./integration`, which opens the ports on behalf of the
+application and therefore holds `@opetope/runtime/internal` (D248).
+
+### 3.2 Attaching
+
+`createInspectionSession(execution)` on `@opetope/runtime/internal`, reachable only by holding the
+`ApplicationExecution` the host created. No process-wide singleton, no global hook. Without a session the runtime
+allocates no records, and closing the application takes the session down with it.
+
+An application never calls that factory. It hands the execution to `installDevtools({ execution, … })` from
+`@opetope/devtools/integration`, which opens the observation port — and, under `mode: 'control'`, the write port —
+and owns both until its handle closes: `/internal` is a seam between the library's own packages, not a surface an
+application is meant to reach (D248).
+
+The attach returns a detach, and it belongs to whoever owns the execution's lifetime, not to whoever opened it. The
+panel arrives through a dynamic import, so an application closed before that import lands would otherwise get a
+panel it no longer has, and the next application would find the previous one still on the page.
+
+### 3.3 Delivery, gaps and resync
+
+The runtime commits a frame and notifies; the client reads the batch itself, so a slow or closed panel creates no
+backpressure. Delivery may be out of band — the listener is not called inside the transition. A frame names its
+session, its base and next revision and its sequence range; a gap, a duplicate, a revision jump or a foreign session
+is rejected in favour of a fresh snapshot, because a partially applied delta is a debugger that lies. History is
+bounded by both frame count and approximate bytes, and overflow leaves a gap marker rather than a silent hole.
+
+The producer's `createInspectionSession(execution, { ringCapacity })` accepts a non-negative safe integer,
+defaulting to 256 frames. Zero retains no frames: snapshots remain available, and a reader behind a dropped
+transition receives `resync-required`. Invalid capacities throw before taking the observation slot (D242).
+A frame with empty `operations` still commits a transaction when it carries an `activity` replacement, including
+an empty replacement that clears the previous activity. A frame with neither change is rejected by the contract kit.
+
+### 3.4 Demand neutrality
+
+Zero, one or many attached inspectors leave the application's own outcomes identical. Observation creates no demand,
+holds no instance alive and never changes what a feature publishes.
+
+## 4. Panel
+
+### 4.1 Two tabs
+
+`Graph` and `Timeline`. One shows the graph at a moment, the other the history of commits. Everything that was once
+a tab is now a filter inside `Graph`.
+
+### 4.2 Edge filter chips and presets
+
+A chip turns one edge kind on or off; a preset is a named set of chips.
+
+| Preset            | Turns on                                                                                                                                | Answers                                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Imports and ports | `hard-import`, `optional-import`, `absent-import`, `on-demand-import`, `requires-port`, `optional-port`, `absent-port`, `provides-port` | Who needs whom, and what of it is unavailable now            |
+| Conditions        | `condition-control`, `owns` from the condition group                                                                                    | What gates this feature, and what else lives in its group    |
+| Ownership         | `owns`                                                                                                                                  | What this node created, and what outlives it                 |
+| Extension points  | `contributes-to`, `owns` down to contributions, plus a second projection step                                                           | Where this feature's contributions go, and who else is there |
+
+The first three are honest edge filters. The fourth is the exception, and it is named as one: a contribution is a
+node _between_ a feature and a target, so a one-hop neighbourhood shows the contributions but not where they go —
+the very question it is opened for. It projects two steps, feature → contributions → targets, and shows the other
+contributors to the same target, because priority and competition are only visible side by side. Selecting a target
+inverts the projection.
+
+### 4.3 Selection, breadcrumbs, inspector
+
+One selection, one graph, one inspector. Changing a preset never changes the selection, and selecting never resets
+the preset. Breadcrumbs show the path to the selected node and navigate: an ancestor crumb returns to it, the
+current node stays a label. The inspector shows identity and provenance, the current state and instance counter, the
+immediate cause, what the node depends on with each weak row's `Lookup`, what it owns, and the last causal chain.
+
+A name too long for its box is shortened by the panel, not by the box: a neighbour is written relative to the
+selection, a name that still overflows is cut from the middle so its last segment survives, a gated group says
+`when` once and names its conditions in the tag beside it, and the full id is always in `title`. An ellipsis on the
+right would eat the tail, and the tail is what tells two siblings apart.
+
+### 4.4 Narrow screens
+
+Below 1100 px the three columns stop being readable and the neighbourhood is drawn as a list. The list and the
+inspector then share the second column, stacked, rather than one of them being dropped: a panel that cannot say what
+a node is waiting for has lost the question it exists to answer. There is no manual `Graph`/`List` switch at any
+width: the list adds nothing the graph does not give, and a second form costs a second layout, second tests and
+second dictionary strings.
+
+### 4.5 Status bar
+
+Always visible, answering "can I trust what I am looking at": `frame · state rev`, the `dropped` count, and `LIVE`.
+Behind `⋯`: `reducer · paint ms`, the theme source and the schema revision — those describe the panel, not the
+application.
+
+### 4.6 State coding, legend, locale
+
+State is never carried by colour alone: glyph, colour and a text tag together, each with a screen-reader label. One
+collapsible legend covers the seven lifecycle states, the three visual edge kinds with the protocol edges each one
+covers, and the three axis badges.
+
+The panel speaks English and Russian, defaulting to the browser and switchable in the header. The prose is
+translated; the vocabulary of the protocol is not — `Feature`, `Condition`, `declared`, `quarantined`, `hard-import`,
+`found`, `missing`, `drain` are identifiers a developer greps for and matches against `spec.md` §3, so they are
+placed _into_ translated sentences rather than replaced. A test renders the panel in Russian across every surface and
+fails on any Latin word outside two lists: the protocol vocabulary, and words the graph itself supplied.
+
+### 4.7 Camera
+
+The lens clips its content, so reaching a node outside the frame is the camera's job: drag empty canvas to pan, wheel
+to zoom around the cursor, buttons for a deliberate 1.2× around the centre, fit-to-view when a node is opened. Wheel
+zoom scales with the size of the gesture rather than by a fixed notch, `deltaMode` is normalized to pixels, and one
+event is clamped so a coarse device cannot cross the range. A drag moves the camera and selects nothing.
+
+## 5. Condition control
+
+### 5.1 What may be controlled
+
+Only a condition and its group. A graph node is a diagnostic record, not a mutable handle: writing state directly
+would bypass the scheduler, hard dependencies, contributions, the fence, cleanup and quarantine. A feature with an
+empty `when` cannot be switched off, and that is the law rather than a gap — synthetic conditions on every feature
+were rejected, because they would make the debugger a source of lifetime the plan does not have.
+
+### 5.2 Actions
+
+| Action          | Where it lives            | What it does                                                             | What it does not promise                    |
+| --------------- | ------------------------- | ------------------------------------------------------------------------ | ------------------------------------------- |
+| `Suspend`       | condition group node      | Sets a forced-false override; the group closes by its normal transaction | It does not cancel the product's own source |
+| `Resume`        | condition group node      | Drops the override; the group follows its source again                   | It does not promise `ready`                 |
+| `Retry cleanup` | quarantined instance node | Retries the quarantined frontier through the existing retry contract     | It does not declare a stuck resource closed |
+
+Retry cleanup lives on the instance because quarantine belongs to the instance: its cleanup is the one that did not
+settle. It is offered only where a quarantined frontier exists, which an application reaches by opening with
+`cleanupFailure: 'quarantine'` (D182); under the default `report` there is no quarantine and therefore no button.
+
+The commands sit in two places, and neither is the card itself: the bar over the canvas, which belongs to the
+selected node without being drawn inside it, and the inspector. A card stays a single selection target — a control
+nested in it would be a button inside a button, and a control floating over it would move with every pan.
+
+An override badge sits beside the commands while an override stands, read from the group's own snapshot rather than
+from what the panel asked for. Applying asks for confirmation, because it changes a live application, and the second
+press names its target. Every application and every rejection reaches the timeline as an audit row.
+
+### 5.3 Dependency law
+
+There is no reverse-demand cascade. Suspending a provider's group sends hard dependents through their normal
+unavailable and retirement semantics, while weak consumers keep running and read `missing`. Suspending a consumer's
+group does not switch the provider off: losing a consumer disables nobody.
+
+### 5.4 Write port contract
+
+A separate factory beside the observation port, because holding an inspection session must not grant the right to
+write.
+
+```ts
+interface RuntimeControlSession {
+  close(): void;
+  resume(conditionId: string): Promise<ControlOutcome>;
+  retryCleanup(instanceId: string): Promise<ControlOutcome>;
+  suspend(conditionId: string): Promise<ControlOutcome>;
+}
+
+type ControlOutcome =
+  | { readonly kind: 'applied'; readonly sequence: number }
+  | { readonly kind: 'rejected'; readonly reason: 'not-controllable' | 'stale' | 'unknown-target' };
+
+declare function createControlSession(execution: ApplicationExecution): RuntimeControlSession;
+```
+
+Application is serialized by the same scheduler that runs condition transitions and publishes an ordinary atomic
+frame, so the panel learns the result the way it learns everything else; `sequence` points at the frame where the
+effect is visible. Rejection is data, not an exception. One execution has at most one live control session: a second
+`createControlSession` throws while the first is open, and `close()` frees the slot so a reloaded panel may take
+control again (D191). The host does not open it either: `installDevtools` does, under `mode: 'control'`, and a
+refusal leaves a failed install rather than a panel that silently came up read-only (D248). `close()` also drops
+every override that session set, so closing the panel leaves the application undebugged, and an override never
+survives a reload or HMR.
+
+Control commands use the current `/3` graph/frame schema without a separate revision. An applied command is expressible: the frame carries
+the existing cause `control-command` with its condition, and the group's snapshot fills the existing
+`desired.override: 'force-inactive'` beside `desired.source`, which is what the override badge reads. A rejection
+emits no frame at all, because a frame that commits nothing would be a lie.
+
+The audit trail is therefore the panel's own: it writes local timeline rows — `control · suspend cond.x · applied →
+frame N`, `control · resume cond.y · rejected · unknown-target` — and links an applied row to the producer's frame by
+the `sequence` the outcome returned. The owner's requirement that every application and every rejection be visible in
+one ribbon is met without inventing a frame the runtime never committed.
+
+`preview → apply` with a one-shot permit is not adopted. There is one controllable subject, its effect is described
+by the dependency law and already drawn in the graph, so a preview would duplicate the graph; confirmation plus an
+audit trail is the proportionate form. If control ever gains a second kind of target, the question reopens.
+
+## 6. Performance and memory
+
+A snapshot builds in `O(N + E)` with no recursive walk on the ingest path; a frame costs `O(changed records)`. The
+tree caches declarative topology for the session and resolves display per rendered row, so a state-only commit does
+not rebuild it. Search, the inspector projection and the graph layout are memoized on the store's version counter,
+which changes exactly once per applied frame. List/inspector virtualization from 200 rows and worker layout from
+300 nodes are proposed thresholds, not implemented behaviour or measured guarantees. The current list and layout
+remain on the main thread; a future implementation needs corpus measurements at those boundaries. The
+panel holds itself to a p95 of 4 ms to apply a frame of at most 100 changed records and to one animation frame to
+paint it, and its own status bar reports both, so a regression shows up where it happens rather than in a report.
+
+A surface the session has not asked for is not in the panel's bundle at all. Four load on demand, each with a budget
+of its own: the control plane when a host passes a write port and the selection has something it can address, the
+legend the first time it is opened, the exporter on the click that uses it, and the timeline with the tab that shows
+it. Each carries its own dictionary as well, so a panel that never opens one ships neither its code nor its words.
+That is what keeps the panel budget honest as the panel grows: 20.18 kB of 21 today, against 1.68, 1.45, 1.14 and
+0.91 kB behind their own caps, and 5.02 of 5.5 kB for the headless session consumer (D240, D241).
+
+A surface can also fail to arrive. The panel holds each one as pending, loaded or failed: a failed surface says so
+where it would have been and offers to ask again, an in-flight fetch is shared rather than started twice, and a
+failed attempt is forgotten so the retry can really retry. Nothing is left as a rejected promise for the host to
+discover — the same rule the copy and the export outcomes follow (§7).
+
+Measure the host application separately with inspection disabled, attached and detached. Record build mode,
+initial and demand-loaded bytes, interaction latency, and retained memory. Application-specific loading and
+backend behaviour are not library performance guarantees.
+
+## 7. Failure semantics
+
+| Event                      | Required behaviour                                          |
+| -------------------------- | ----------------------------------------------------------- |
+| Observer throws            | Detached and reported; the transition is already committed  |
+| Queue overflow             | Bounded gap marker, snapshot resync, application unblocked  |
+| Duplicate or out-of-order  | Reject the frame and resync                                 |
+| Frame from a replaced plan | Ignore                                                      |
+| Snapshot capture failure   | Close the session, report `snapshot-failed`, change nothing |
+| Cleanup quarantined        | The logical fence stands; only an exact retry               |
+| Panel unmounted            | Detach the consumer, free UI state, leave the application   |
+
+Untrusted payloads — a replayed export, a fixture from a bug report — pass a strict decoder with budgets on record
+counts, string length and bytes. Unknown kinds and unexpected fields are rejected with the record rather than
+tolerated; the schema revision, not leniency, carries compatibility forward. An accessor is rejected before it is
+read — a field of a record and an entry of an array alike, and no method of the incoming value is called — so a
+payload cannot execute code inside the decoder. The byte budget is counted in UTF-8 bytes before the parse, because
+a limit named in bytes that counts UTF-16 units is three times looser than it reads.
+
+Ids are held to their own lengths, derived from the producer's laws rather than chosen: an atom is a declaration id
+of at most 160 characters, its escaping can add one character per separator (D200), a node id adds the longest
+prefix, and an edge id escapes both endpoints again. A condition is published as one escaped atom and addressed by
+it, with the declaration id the author wrote left in the label, so it is bounded by the escaped length and read by
+the label everywhere the panel shows it. A flat cap shorter than that arithmetic refuses snapshots a legal
+application produces. A group whose key joins more conditions than one escaped atom can hold is refused as an
+oversized id, which is a budget refusal like `maxNodes` and not a claim about the shape. Contribution priorities
+accept every finite number, including negative and fractional values, matching the runtime producer; counts and
+indexes retain their own integer constraints (D212).
+
+## 8. Acceptance
+
+Topology and instances stay distinct. A snapshot plus contiguous frames deterministically reproduces the state at
+every commit boundary. A frame is visible only after an atomic commit. Stale, duplicate, gapped and foreign-session
+frames are rejected. Every waiting, failed or quarantined state carries a typed reason. Nothing reads as runnable
+after its owner is fenced. The number of inspectors changes no outcome. Production contains no devtools chunk.
+
+The executable form is `assertInspectionSessionContract` in `@opetope/devtools/testing`: a runtime implementing the
+port runs it against its own session without reading devtools sources.
+
+## 9. Decision log
+
+Rows describing current behaviour. Superseded rows are collapsed into one line each rather than kept in full.
+
+### 9.1 Protocol
+
+| №   | Decision                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| T1  | A frame has no clock of its own. `cause.at` is the only one and it stamps the trigger; state records carry no timestamps, and no duration is derived from commit times                                                                                                                                                                                                                                                                                 |
+| T3  | `declared` is the seventh lifecycle value, for a feature the plan declares while nothing has opened it                                                                                                                                                                                                                                                                                                                                                 |
+| T4  | Node taxonomy rebuilt from the plan IR and the public vocabulary; `activation-domain`, `module-*`, `eligibility-attempt`, `capability-resolution`, `scope-generation`, `view-root` are gone                                                                                                                                                                                                                                                            |
+| T6  | Six activation semantics collapse to two classes the compiler distinguishes: hard edges carry `pending`, weak edges carry a `Lookup` and never wait                                                                                                                                                                                                                                                                                                    |
+| T7  | `start-after` has no counterpart: opening order is derived, not declared, and lives in `plan.groups[].order`                                                                                                                                                                                                                                                                                                                                           |
+| T8  | Provider selection happens at compile time, so there is no admission, candidate set or ambiguity at runtime — only whether the selected provider has a live instance                                                                                                                                                                                                                                                                                   |
+| T13 | `requires-port` is split into hard and optional by `CompiledApplicationRequirementIR.optional`, since the compiler emits one kind for both                                                                                                                                                                                                                                                                                                             |
+| T14 | Port edges run through the port node: `provides-port` from the provider, `requires-port` and `absent-port` to the consumer                                                                                                                                                                                                                                                                                                                             |
+| T15 | `absent-provider` is a node so an `absent-import` edge has an origin                                                                                                                                                                                                                                                                                                                                                                                   |
+| T16 | A contribution is two edges: `owns` from the contributor and `contributes-to` to the target                                                                                                                                                                                                                                                                                                                                                            |
+| T17 | Failures are the runtime's own error classes as a discriminated `subject` + `code` pair                                                                                                                                                                                                                                                                                                                                                                |
+| T19 | Schema `opetope.devtools-graph/3` and `opetope.devtools-frame/3`                                                                                                                                                                                                                                                                                                                                                                                       |
+| T23 | The hostile decoder is strict: unknown fields and kinds are rejected with the record, accessors are refused before being read, and the polluting keys always                                                                                                                                                                                                                                                                                           |
+| T25 | The performance corpus is generated, deterministic by construction: 1 330 nodes / 5 008 edges and 26 331 / 70 040                                                                                                                                                                                                                                                                                                                                      |
+| T26 | Tree structure is cached for the session and display resolved per rendered row; search, projection and layout are memoized on the store version                                                                                                                                                                                                                                                                                                        |
+| T28 | Phase 4 canary. A lone `when` flip emits one `contribution-change` frame and moves the contribution `published` ↔ `withheld`; closing a live application removes its instances and contributions. Both were broken and were fixed by D167; the canary tests are written so masking cannot recur                                                                                                                                                        |
+| T29 | The consumed interface takes the ids the runtime declares. Brands are optional markers, so a plain `string` is accepted and no host carries a cast; the guarantee lives in the validators and the decoder                                                                                                                                                                                                                                              |
+| T31 | Close/detach/GC matrix: no leak in the package. Per-cycle growth settles, and the container that survives is held by one of React DOM's own module-level root slots — `rootWithNestedUpdates` or `rootWithPassiveNestedUpdates`; the observed retainer was the passive one, which exists only in the development build. Both hold a single container at a time, both sit outside devtools, and the panel is dev-only, so production never faces either |
+| T33 | The detach returned by the attach is owned by the launcher that owns the execution: it runs before the close, fences a panel whose import lands late, and closes exactly the handle it installed                                                                                                                                                                                                                                                       |
+| T34 | The decoder reads array entries by index through their own descriptors: an entry may be an accessor just as a field may, and `map` on the incoming array is the payload's method, not ours. The text budget counts UTF-8 bytes, bounded above and below by the code-unit length so the exact count stays off the hot path                                                                                                                              |
+| —   | Superseded: T2, T5, T9–T12, T18, T20–T22, T24, T27, T30, T32 described earlier taxonomies, budgets or open questions and are replaced by the rows above and by §2, §4 and §6                                                                                                                                                                                                                                                                           |
+
+### 9.2 Panel
+
+| №   | Decision                                                                                                                                                                                            |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| U11 | Virtualization thresholds are set rather than measured: 200 rows for lists and the inspector, 300 nodes for a worker layout                                                                         |
+| U12 | The lens clips its content; pan, wheel zoom, buttons and fit-to-view are the way to reach what is outside the frame                                                                                 |
+| U13 | An ancestor breadcrumb navigates; the current node stays a label                                                                                                                                    |
+| U14 | Node cards are opaque and above the edges, so a line cannot cross a badge                                                                                                                           |
+| U15 | Export delivers to the clipboard or a local file by capability and always reports the outcome                                                                                                       |
+| U16 | The panel offers no control action it cannot perform; the status bar states once that the control plane is off                                                                                      |
+| U18 | A label is presentation metadata derived from a declaration: never identity, never authority, and never shown as a protocol field name                                                              |
+| U19 | One collapsible legend for states, edges and badges                                                                                                                                                 |
+| U20 | English and Russian, defaulting to the browser, switchable in the header; the English dictionary is the typed source of truth                                                                       |
+| U21 | The translation boundary: prose is translated, the protocol vocabulary is not, and protocol words are placed into translated sentences                                                              |
+| U22 | The panel size cap is 20 kB brotli, raised from 15 with the measurement recorded; the headless consumer stays under 5 kB                                                                            |
+| U24 | Translation completeness is policed by a test that renders the Russian panel across every surface and fails on prose it does not recognise                                                          |
+| U26 | Wheel zoom scales with the size of the gesture; buttons step 1.2×; `deltaMode` is normalized and one event is clamped                                                                               |
+| U27 | A drag moves the camera and selects nothing                                                                                                                                                         |
+| U28 | Two tabs, `Graph` and `Timeline`; the former lenses become edge filter chips with four presets                                                                                                      |
+| U29 | Extension points is a two-step projection preset, not a lens: feature → contributions → targets, inverted when a target is selected                                                                 |
+| U30 | The manual `Graph`/`List` switch is gone; the list is the automatic form below 1100 px                                                                                                              |
+| U31 | The status bar keeps `frame`, `dropped` and `LIVE` visible and hides the panel's own diagnostics behind `⋯`                                                                                         |
+| U32 | Control is limited to condition override, on the group node, through a separate dev-only write port with its own authority                                                                          |
+| U33 | The control plane, the legend, the exporter and the timeline load on demand, each with its own chunk, its own dictionary and its own size budget; the panel carries only what every session uses    |
+| U34 | The control surface is fetched when the selection holds something the port can address — a condition group with a condition, or a quarantined instance — and not merely because a write port exists |
+| —   | Superseded: U1–U10, U17, U23, U25 covered v1 glyphs, the canvas default, the search hit column and the naming of the extension-points preset, and are replaced by the rows above and by §4          |
+
+The inspection graph/frame schema is `/3`, with optional `opetope.runtime-activity/1` snapshots. Within one session,
+a frame without `activity` preserves the previous activity; a full snapshot/reset without it clears that observation
+(D216). Activity-bearing frames replace the previous activity in full.
+Use matching runtime/devtools versions: `/2` readers reject the new revision. Activity identifies the execution,
+actual feature generation, physical Calls, exact current lane blockers, registered resource leases and load attempts.
+Host demand and UI models are unknown; stream observation covers state, not physical load identities. `freshness`
+and `truncated` distinguish a complete live view from a partial or detached one. A closed session is stale;
+`closed: true` requires successful physical application drain. No control authority or product payload is added.
+Activity output is bounded by record capacity. Snapshot collection still visits registered owners, executors and
+resources, so capacity does not bound traversal cost. Collection stops once truncation is proven;
+idle executors may still require traversal to establish completeness. Normal call dispatch allocates no diagnostic record with
+observation disabled. Graph frames remain bounded by the existing ring capacity.