@observertc/observer-js 1.0.0-beta.13 → 1.0.0-beta.14

package/README.md

@@ -40,11 +40,9 @@ and emits a single, unified stream of typed events the application can react to.
 > works whether your project uses `import` (ESM) or `require()` (CommonJS). Everything — including
 > the built-in file sink — is exported from the single `@observertc/observer-js` entry.
 
-> **For AI agents:** [`llms.txt`](./llms.txt) is a curated map of these docs (with a one-file
-> [`llms-full.txt`](./llms-full.txt) export for one-shot ingestion); [`AGENTS.md`](./AGENTS.md)
-> covers build/test commands and conventions for working **in** this repository. `llms-full.txt`
-> ships in the npm package (so it's available wherever the library is installed); `llms.txt` and
-> `AGENTS.md` live in the repo (and `llms.txt` belongs at the root of the docs site).
+> **For AI agents:** [`llms.txt`](./llms.txt) is a curated map of these docs (it belongs at the root
+> of the docs site); [`AGENTS.md`](./AGENTS.md) covers build/test commands and the conventions for
+> working **in** this repository.
 
 ---
 
@@ -363,6 +361,7 @@ additional field(s) on top of that scope.
 | `observer-updated` | — | `observer.update()` ran (per the observer update policy) |
 | `observer-closed` | — | `observer.close()` |
 | `sample-rejected` | `{ reason: 'observer-closed' \| 'missing-callId' \| 'missing-clientId', sample: ClientSample }` | a sample was dropped by `accept()` |
+| `observer-issue` | `{ issue: ClientIssue }` | `observer.addIssue(...)` — a cross-call / SFU-wide finding (see [observer-level detectors](#observer-level-detectors-cross-call--sfu-wide)) |
 
 #### Mediasoup level — scope `{ observer, observedMediasoupRouter }`
 
@@ -396,7 +395,8 @@ See [Mediasoup router observation](#mediasoup-router-observation) for the full d
 | `client-joined` | — | first `CLIENT_JOINED` event seen |
 | `client-left` | — | `CLIENT_LEFT` seen (or inferred on close) |
 | `client-rejoined` | `{ timestamp: number }` | a later `CLIENT_JOINED` after an earlier join |
-| `client-issue` | `{ issue: ClientIssue }` | a client-reported issue arrived, or `client.addIssue(...)` |
+| `client-issue` | `{ issue: ClientIssue }` | a client-reported issue arrived, or `client.addIssue(...)`. A keyed issue also opens an entry in `observedClient.activeIssues` |
+| `client-issue-resolved` | `{ resolvedIssue: ResolvedClientIssue }` | a stateful issue ended — the client sent its `<type>-resolved` companion, or the observer force-closed it. Carries the finished interval (`durationInMs`, `resolvedBy`) — see [client issues](#client-issues-the-lifecycle-and-the-division-of-labour) |
 | `client-metadata` | `{ metaData: ClientMetaData }` | a client meta item arrived |
 | `client-extension-stats` | `{ extensionStats: ExtensionStat }` | an app-defined extension stat arrived |
 | `client-event` | `{ event: ClientEvent }` | any client event was processed |
@@ -562,11 +562,28 @@ Key members:
   `iceCandidates`, `iceCandidatePairs`, `certificates`, `selectedIceCandidatePairs`,
   `selectedIceCandiadtePairForTurn`
 - State: `connectionState?`, `iceConnectionState?`, `iceGatheringState?`, `usingTURN`, `usingTCP`
-- Metrics: `currentRttInMs?`, `currentJitter?`, `availableIncomingBitrate`,
-  `availableOutgoingBitrate`, sending/receiving bitrates, packet rates, and `total*` / `delta*`
-  byte/packet counters
+- Metrics: `currentRttInMs?`, `iceRttInMs?`, `rtcpRttInMs?`, `sfuHopRttInMs?`, `currentJitter?`,
+  `availableIncomingBitrate`, `availableOutgoingBitrate`, sending/receiving bitrates, packet rates,
+  and `total*` / `delta*` byte/packet counters
 - `accept(pcSample, context?)`, `close()`, `get score()`
 
+**Two different round trips — don't mix them.** `iceRttInMs` comes from ICE/STUN consent checks and
+measures the trip to *whatever terminates ICE*: **in an SFU topology that is the SFU**, so it is the
+client↔SFU leg. `rtcpRttInMs` comes from RTCP receiver reports and is an **end-to-end** media-path
+round trip. They are not interchangeable, and averaging them together produces a number that moves
+as streams come and go for reasons unrelated to the network. `currentRttInMs` therefore *prefers*
+RTCP and falls back to ICE — always one kind within a tick, never a blend. `sfuHopRttInMs`
+(`rtcp − ice`) estimates everything past the SFU, which separates "this client's last mile is slow"
+from "the path beyond the SFU is slow".
+
+**Counter-reset boundaries.** Chrome resets an SSRC's cumulative counters when the codec switches
+([crbug/webrtc/5361](https://bugs.chromium.org/p/webrtc/issues/detail?id=5361), open since 2015),
+which otherwise shows up as a sawtooth spike or a negative bitrate. `ObservedInboundRtp` /
+`ObservedOutboundRtp` therefore set **`counterResetBoundary`** on any tick where `codecId`,
+`encoder`/`decoderImplementation` or `scalabilityMode` changed, and suppress every delta for that
+tick. Without this, a room-wide codec rollout fires a synchronized fake-degradation alert across
+every participant at once.
+
 **Remote-RTP correlation (derived).** During `accept()`, receiver/sender reports are linked
 to the local streams by `remoteId` (fallback SSRC) and surfaced as fields:
 
@@ -730,6 +747,302 @@ observer.on('call-added', ({ observedCall }) => {
 observer.on('call-issue', ({ observedCall, issue }) => { /* react */ });
 ```
 
+### Client issues: the lifecycle, and the division of labour
+
+The most important thing to understand about detection in this library is **what it deliberately
+does not do**. A client running
+[`client-monitor-js`](https://github.com/ObserveRTC/client-monitor-js) already ships ~20 detectors
+that decide *what is wrong with that endpoint* — `congestion`, `cpulimitation`, `audio-concealment`,
+`freezed-video-track`, `keyframe-storm`, `video-decoder-overloaded`, `stuck-decoder`,
+`ice-disconnected`, and so on. Those verdicts are better than anything re-derived from raw counters
+server-side, because they carry hysteresis and multi-signal confirmation: `audio-concealment`
+subtracts silent concealment (raw `concealedSamples` rises during ordinary silence, so a naive
+detector flags every quiet moment); `audio-jitter-buffer-stress` requires the buffer to be grown
+**and** NetEQ to be time-stretching (a grown buffer alone means NetEQ is *succeeding*);
+`ice-disconnected` only fires once `disconnected` has persisted, so the blips ICE heals on its own
+never surface.
+
+**observer-js does not repeat that work.** Its job is the question no browser can answer: *who else
+is in this state right now, what do they have in common, and where in publisher → SFU → subscriber
+does the fault begin?*
+
+#### The wire format
+
+From client-monitor-js **4.6.0** the whole issue lifecycle reaches the server. A stateful issue
+arrives as two `clientIssues[]` entries sharing a `key`:
+
+```
+raise:      { type: 'stuck-decoder',          key, payload,                                 timestamp: raisedAt }
+resolution: { type: 'stuck-decoder-resolved', key, payload: { raisedAt, comment, …final },  timestamp: resolvedAt }
+```
+
+The observer opens an entry in `observedClient.activeIssues` on the raise and closes it on the
+matching key, emitting **`client-issue-resolved`** with the finished interval. Handled for you:
+
+- the `-resolved` **suffix** is stripped, so both entries share one logical `type`;
+- a **re-raise** of a live key refreshes the payload without restarting `raisedAt`;
+- **keyless** entries are one-shot — reported via `client-issue`, never tracked;
+- issues still open when a client closes are **force-resolved** (`resolvedBy: 'client-closed'`), and
+  the registry additionally expires stale entries, so a crashed participant can't leave an issue
+  "active" forever.
+
+#### Why intervals beat windows
+
+This turns point-in-time symptom reports into **intervals**, and that is the whole game. *"Several
+clients reported congestion in the last 10 seconds"* is a heuristic that has to guess whether the
+symptoms are still happening. *"Several clients are congested **right now, simultaneously**"* is
+ground truth, because the client says when the episode ends. Overlapping intervals are far stronger
+evidence of a shared cause than near-in-time reports.
+
+```ts
+observer.on('client-issue', ({ observedClient, issue }) => { /* opened (or one-shot) */ });
+observer.on('client-issue-resolved', ({ resolvedIssue }) => {
+  resolvedIssue.type;          // 'stuck-decoder' — suffix stripped
+  resolvedIssue.durationInMs;  // how long the episode lasted
+  resolvedIssue.resolvedBy;    // 'client' | 'timeout' | 'client-closed'
+});
+
+// the live per-client mirror
+observedClient.activeIssues;   // Map<key, ActiveClientIssue>
+```
+
+#### `IssueRegistry` — querying the active set
+
+```ts
+import { IssueRegistry } from '@observertc/observer-js';
+
+const registry = new IssueRegistry(observedCall);   // or `observer` for cross-call scope
+
+registry.cohortOf('congestion');   // { clientIds, affectedRatio, onsetSpreadInMs, … }
+registry.cohorts();                // every shared issue type, largest cohort first
+registry.byTrackIds(trackIds);     // issues attributed to a published track's receivers
+```
+
+`onsetSpreadInMs` is measured on the **observer clock**, never the client's. `raisedAt` comes from
+each participant's own machine, and comparing those across clients makes clock skew look like a
+synchronized infrastructure event.
+
+### Observer-level detectors (cross-call / SFU-wide)
+
+Some findings only exist **above** call scope — "many calls on the same SFU degraded at once" is far
+more actionable than fifty individual client alerts. The same registry exists on the `Observer`,
+runs on every `observer.update()`, and raises findings through `observer.addIssue(...)`, surfaced on
+the bus as **`observer-issue`**:
+
+```ts
+observer.detectors.add({
+  name: 'sfu-wide-degradation',
+  update: () => {
+    const degradedCalls = [ ...observer.observedCalls.values() ].filter(isDegraded);
+
+    if (observer.numberOfCalls > 3 && degradedCalls.length / observer.numberOfCalls > 0.6) {
+      observer.addIssue({ type: 'SFU_WIDE_QUALITY_DEGRADATION', timestamp: Date.now() });
+    }
+  },
+});
+
+observer.on('observer-issue', ({ issue }) => alert(issue));
+```
+
+### Publisher → subscribers: `TrackDistributionAggregator`
+
+The question a single browser can never answer is *"did **everyone** receiving Alice see the same
+degradation?"*. `TrackDistributionAggregator` answers it by walking the publisher→subscriber links
+maintained by a [`RemoteTrackResolver`](#remote-track-resolution-mediasoup--sfu) and summarizing one
+published track against all of its receivers:
+
+```ts
+import { TrackDistributionAggregator } from '@observertc/observer-js';
+
+const aggregator = new TrackDistributionAggregator(observedCall);
+
+for (const d of aggregator.aggregate()) {
+  d.trackId;                     // the published track
+  d.publisher.healthy;           // is the source itself fine? (+ .reasons)
+  d.numberOfReceivers;           // 17
+  d.numberOfDegradedReceivers;   // 14
+  d.degradedRatio;               // 0.82
+  d.fractionLost?.p95;           // percentile summaries across receivers
+  d.freezes;                     // { affectedReceivers, total }  — fan-out counters
+  d.plis;
+  d.receivers;                   // per-receiver entries with `degraded` + `reasons`
+}
+```
+
+Each receiver is judged against `ReceiverHealthThresholds` (loss, freezes, dropped frames,
+concealment, jitter-buffer delay, RTT — override any of them). Summaries are **medians and
+percentiles, not means**, because one participant at 1500 ms RTT would otherwise hide nine healthy
+ones. The helpers behind it (`percentile`, `median`, `summarize`, `counterDelta`, `SlidingWindow`)
+are exported for building your own detectors.
+
+### Call health: `CallHealthAggregator`
+
+The second aggregation axis — the **client** axis. Where `TrackDistributionAggregator` asks "how was
+*this source* delivered?", this asks "how is *each participant* doing, sending vs receiving?":
+
+```ts
+import { CallHealthAggregator } from '@observertc/observer-js';
+
+const health = new CallHealthAggregator(observedCall).aggregate();
+
+health.degradedRatio;             // 0.82 — the number that distinguishes shared faults from individual ones
+health.inboundDegradedRatio;      // receiving side → egress/downstream suspicion
+health.outboundDegradedRatio;     // sending side  → ingress suspicion
+health.rttInMs?.median;           // percentile rollups, never means
+health.qualityLimitation;         // { cpu, bandwidth, other } client counts
+health.clients;                   // per-client entries with `reasons`, direction flags, TURN/TCP
+```
+
+### Built-in detectors
+
+All of them are **opt-in** — the library enables none by default. Register call-scoped ones on
+`observedCall.detectors` and observer-scoped ones on `observer.detectors`:
+
+> **🔗 marks detectors that require a
+> [`RemoteTrackResolver`](#remote-track-resolution-mediasoup--sfu).** They reason about a published
+> track and its subscribers, so without the publisher↔subscriber links they see nothing and stay
+> **silent forever** — which looks exactly like "no problems found". Configure
+> `ObserverConfig.createRemoteTrackResolver` before registering them.
+
+**Issue-driven** (preferred — they consume the client's own verdicts):
+
+| Detector | 🔗 | Scope | Raises |
+|----------|:--:|-------|--------|
+| `ConcurrentIssueDetector` | | call **or** observer | `CONCURRENT_CLIENT_ISSUES`, `ISSUE_ONSET_BURST` |
+| `IssueFanOutDetector` | 🔗 | call | `PUBLISHED_TRACK_ISSUE_FAN_OUT`, `SINGLE_RECEIVER_ISSUE` |
+| `TrackDeliveryMismatchDetector` | 🔗 | call | `PUBLISHED_TRACK_NOT_DELIVERED`, `RECEIVER_TRACK_NOT_DELIVERED`, `PUBLISHER_TRACK_DRY` |
+
+**Metric-driven** (work without client issues — the fallback path, and the things no client issue
+can express):
+
+| Detector | 🔗 | Scope | Raises |
+|----------|:--:|-------|--------|
+| `WorstReceiverContagionDetector` | 🔗 | call | `WORST_RECEIVER_CONTAGION` |
+| `CommonSourceDegradationDetector` | 🔗 | call | `PUBLISHER_HEALTHY_SUBSCRIBERS_DEGRADED`, `PUBLISHER_DEGRADED_FOR_ALL_SUBSCRIBERS`, `SINGLE_SUBSCRIBER_DEGRADED`, `MULTIPLE_SUBSCRIBERS_DEGRADED` |
+| `PliAndFreezeFanOutDetector` | 🔗 | call | `PUBLISHER_PLI_STORM`, `PUBLISHED_VIDEO_FROZEN_FOR_MULTIPLE_RECEIVERS` |
+| `AudioImpairmentFanOutDetector` | 🔗 | call | `PUBLISHED_AUDIO_DEGRADED_FOR_MAJORITY`, `CALL_WIDE_AUDIO_JITTER_BUFFER_STRESS` |
+| `UnconsumedTrackDetector` | 🔗 | call | `UNCONSUMED_PUBLISHED_TRACK` |
+| `CallWideDegradationDetector` | | call | `CALL_WIDE_QUALITY_DEGRADATION`, `CALL_WIDE_INBOUND_DEGRADATION`, `CALL_WIDE_OUTBOUND_DEGRADATION` |
+| `IceDisruptionDetector` | | call | `CALL_ICE_DISRUPTION` |
+| `TurnServerHealthDetector` | | **observer** | `TURN_SERVER_DEGRADED` |
+
+If your clients report issues, the issue-driven pair **subsumes** the fan-out and ICE detectors —
+`IssueFanOutDetector` covers freeze/PLI/concealment fan-out generically, and `ConcurrentIssueDetector`
+with the ICE issue types replaces `IceDisruptionDetector` (and does it better: the client already
+suppresses the transient blips ICE heals by itself). Run both families only while migrating.
+
+#### `TrackDeliveryMismatchDetector` — resolving an ambiguous symptom
+
+A dry track ("no bytes are arriving") is the clearest symptom there is and, on its own, completely
+ambiguous. A receiver seeing silence cannot distinguish *the camera was switched off* from *the SFU
+stopped forwarding* from *my own consumer wedged* — all three look identical from the browser.
+
+Joining the two ends of the published track resolves it:
+
+| publisher | subscribers | verdict |
+|---|---|---|
+| sending | **all** dry | `PUBLISHED_TRACK_NOT_DELIVERED` — the forwarding path |
+| sending | **some** dry | `RECEIVER_TRACK_NOT_DELIVERED` — those consumers (in mediasoup: recreate them) |
+| dry | any dry | `PUBLISHER_TRACK_DRY` — the source stopped; **not** an SFU fault |
+
+The publisher side is judged from both available signals: its own `dry-outbound-track` issue when the
+client reports one, and the observed outbound RTP (`deltaPacketsSent`) as fallback and corroboration.
+That combination is what makes the first row trustworthy — the server can state that packets
+demonstrably left the publisher during the same interval in which every receiver got nothing.
+
+This is the "SFU forwarding mismatch" check, and it needs **no mediasoup instrumentation at all** —
+the clients' own dry-track verdicts plus the resolver links are sufficient.
+
+#### `UnconsumedTrackDetector` — reading the resolver's silence
+
+The one detector where the *absence* of links is the signal: a track still pushing packets whose
+`remoteInboundTracks` set is empty, i.e. uplink and SFU ingress spent on media nobody receives
+(everyone has the publisher hidden, a simulcast layer no viewer selects, or an app that forgot to
+stop a track). It waits `minUnconsumedDurationInMs` first, since a gap between publishing and the
+first subscription is normal at join time.
+
+Note the trap this one has to guard against, and why it checks `call.remoteTrackResolver` at runtime
+rather than trusting the flag alone: **"no subscribers" and "no resolver configured" produce the
+identical observation.** Without a resolver it would report every published track in the call as
+unconsumed.
+
+#### `WorstReceiverContagionDetector` — the one worth reading about
+
+In a correctly built SFU the RTCP feedback loop is **terminated at the server**: each receiver's
+reports drive what *that* receiver is sent. When the loop is relayed end-to-end instead, the
+publisher's bandwidth estimate collapses to the minimum across all receivers — so one participant on
+a bad 3G link silently downgrades the stream **everyone** sees. This is the "lowest common
+denominator" failure simulcast exists to prevent.
+
+It's detected as a *correlation over a window*, not a threshold: the publisher's outbound bitrate
+moving in lockstep with the **worst** receiver's inbound bitrate, while the median receiver has
+headroom — and tracking the worst receiver more closely than the median (otherwise everyone is just
+moving together, which is ordinary adaptation). The damage is invisible from every endpoint: the
+publisher sees "my bitrate dropped", each healthy receiver sees "my video got worse", and only the
+server can see the causal link.
+
+```ts
+import {
+  ConcurrentIssueDetector, IssueFanOutDetector, WorstReceiverContagionDetector,
+  CallWideDegradationDetector, TurnServerHealthDetector,
+} from '@observertc/observer-js';
+
+observer.on('call-added', ({ observedCall }) => {
+  // issue-driven: correlate the verdicts the clients already reached
+  observedCall.detectors.add(new IssueFanOutDetector(observedCall));
+  observedCall.detectors.add(new ConcurrentIssueDetector(observedCall));
+  // metric-driven: things no client issue can express
+  observedCall.detectors.add(new WorstReceiverContagionDetector(observedCall));
+  observedCall.detectors.add(new CallWideDegradationDetector(observedCall));
+});
+
+// cross-call, so these go on the observer and raise `observer-issue`
+observer.detectors.add(new TurnServerHealthDetector(observer));
+observer.detectors.add(new ConcurrentIssueDetector(observer, {
+  issueTypes: [ 'ice-disconnected', 'ice-connection-failed', 'congestion' ],
+}));
+
+observer.on('call-issue', ({ observedCall, issue }) => handle(observedCall, issue));
+observer.on('observer-issue', ({ issue }) => handle(undefined, issue));
+```
+
+Every detector takes an options object to tune `minReceivers`/`minClients`, the ratio thresholds, the
+per-entity health thresholds, and the debounce (`consecutiveTicks`, or `windowMs` + `cooldownMs` for
+the window-based ones) — so an alert needs a condition to *persist*, not just appear in one sample.
+Findings that depend on publisher↔subscriber links need a
+[`RemoteTrackResolver`](#remote-track-resolution-mediasoup--sfu); without one those detectors stay
+silent. A detector may implement `close()` (called when it's removed or the call/observer closes) —
+`IceDisruptionDetector` uses it to drop the bus listeners it subscribes with.
+
+### `CommonSourceDegradationDetector`
+
+The first detector built on the aggregator. It classifies where a fault lies by comparing the source
+against its receivers, and raises a `call-issue` whose `type` is one of:
+
+| Finding | Meaning |
+|---------|---------|
+| `PUBLISHER_HEALTHY_SUBSCRIBERS_DEGRADED` | source egress fine, most receivers degraded → **downstream / SFU** suspected |
+| `PUBLISHER_DEGRADED_FOR_ALL_SUBSCRIBERS` | the source itself is impaired → **publisher-side** |
+| `SINGLE_SUBSCRIBER_DEGRADED` | one receiver suffers while the rest are fine → **that receiver's network** |
+| `MULTIPLE_SUBSCRIBERS_DEGRADED` | several (but not most) receivers on the same source |
+
+```ts
+import { CommonSourceDegradationDetector } from '@observertc/observer-js';
+
+observer.on('call-added', ({ observedCall }) => {
+  observedCall.detectors.add(new CommonSourceDegradationDetector(observedCall, {
+    minReceivers: 3,             // ratios need a meaningful denominator
+    degradedRatioThreshold: 0.6, // "most receivers"
+    consecutiveTicks: 2,         // must hold 2 ticks — avoids flapping on one bad sample
+  }));
+});
+```
+
+The `call-issue` payload carries the evidence: publisher health and reasons, receiver/degraded
+counts, `degradedRatio`, `affectedClientIds`, freeze/PLI fan-out and the loss/bitrate summaries.
+It requires a configured `RemoteTrackResolver` — with no links there is nothing to compare and the
+detector stays silent.
+
 `Detector` interface and the registry:
 
 ```ts
@@ -836,6 +1149,80 @@ on your own cadence read `observedRouter.sample` (snapshot/serialize/persist wha
 you don't, and close routers you no longer track. (mediasoup also typically shards routers across
 workers/cores, which keeps any one router small.)
 
+### Extending the sample, and building your own report
+
+The sample is yours to annotate. Every entity — the router, each transport, producer, consumer, data
+producer and data consumer — has an `attachments?: Record<string, unknown>` slot, and there are three
+ways to fill it, from most declarative to most ad-hoc.
+
+**1. `enrich` — mirror mediasoup's own `appData`.** The common case: your application already keeps
+`participantId`, `purpose` and similar on the mediasoup objects, and you want them on the sample.
+Runs once per entity at creation, before the corresponding event:
+
+```ts
+observer.createObservedMediasoupRouter({
+  router,
+  enrich: {
+    producer: (producer) => ({ participantId: producer.appData.participantId, purpose: producer.appData.purpose }),
+    consumer: (consumer) => ({ subscriberId: consumer.appData.subscriberId }),
+    transport: (transport) => ({ role: transport.appData.role }),
+  },
+});
+```
+
+A throwing enricher is caught and logged — it can't take the router's bookkeeping down with it.
+
+**2. Lifecycle events — enrich on the fly.** Each entity announces itself as
+`<entity>-sample-added` and `<entity>-sample-closed`, carrying **the live sample object** (not a
+copy) plus the mediasoup object it came from. Mutating it in the handler is the intended pattern:
+
+```ts
+observedRouter.on('producer-sample-added', ({ sample, producer, transport }) => {
+  sample.attachments = { ...sample.attachments, participantId: lookup(producer.id) };
+});
+
+observedRouter.on('producer-sample-closed', ({ sample }) => {
+  archive(sample);   // its `closedAt` is set
+});
+```
+
+Events: `transport-sample-added` / `-closed`, `producer-sample-added` / `-closed`,
+`consumer-sample-added` / `-closed`, `data-producer-sample-added` / `-closed`,
+`data-consumer-sample-added` / `-closed`.
+
+**3. `attachTo(id, attachments)` — annotate later, from anywhere.** When the knowledge arrives after
+the entity did (a signalling message, a database lookup that resolved):
+
+```ts
+observedRouter.attachTo(producerId, { participantId, joinedFrom: 'mobile' });   // merges
+```
+
+Ids are unique across mediasoup entity kinds, so one method covers all of them. It returns `false`
+for an unknown id rather than failing quietly — which matters when application events race the
+mediasoup ones. For direct access there are typed accessors: `getTransportSample(id)`,
+`getProducerSample(id)`, `getConsumerSample(id)`, `getDataProducerSample(id)`,
+`getDataConsumerSample(id)`. They index the *same* objects the arrays hold, so a lookup is O(1)
+instead of a `sample.producers.find(...)` scan.
+
+#### Building your own report
+
+`observedRouter.sample` is live — arrays grow and `history` entries are appended as the router runs,
+so a report built directly on it keeps changing after you think you're done. Use **`snapshot()`** for
+a detached deep copy:
+
+```ts
+const report = {
+  ...observedRouter.snapshot(),        // never moves again
+  generatedAt: Date.now(),
+  region: process.env.REGION,
+};
+```
+
+> **Note on typing.** The sample types no longer carry a `Record<string, unknown>` index signature.
+> That signature allowed arbitrary top-level keys but also silently accepted typos on real fields and
+> weakened autocomplete. Custom data belongs in `attachments`, which is typed as such. If you were
+> assigning ad-hoc keys directly onto a sample object, move them into `attachments`.
+
 ### Matching peer connections — by **event**, not by storage
 
 The observer correlates the SFU side with the client side **at the peer-connection level**: a