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

package/dist/index.d.mts

@@ -52,6 +52,12 @@ type ClientIssue = {
     */
     type: string;
     /**
+    * Identity of a **stateful** issue, shared by its raise entry and its `<type>-resolved`
+    * companion, so a server can open an active issue on the raise and close it on the match
+    * (client-monitor-js >= 4.6.0, `sendResolvedIssuesToServer`). One-shot issues have no key.
+    */
+    key?: string;
+    /**
     * The value associated with the event, if applicable.
     */
     payload?: string;
@@ -1585,6 +1591,24 @@ declare class ObservedOutboundRtp implements OutboundRtpStats {
     bitPerPixel: number;
     deltaPacketsSent: number;
     deltaBytesSent: number;
+    deltaFramesSent: number;
+    deltaFramesEncoded: number;
+    deltaKeyFramesEncoded: number;
+    deltaNackCount: number;
+    deltaPliCount: number;
+    deltaFirCount: number;
+    deltaRetransmittedPacketsSent: number;
+    deltaRetransmittedBytesSent: number;
+    deltaEncodeTime: number;
+    deltaQualityLimitationResolutionChanges: number;
+    /**
+     * `true` when the codec, encoder implementation or scalability mode changed in this tick.
+     *
+     * Chrome resets `packetsSent`/`bytesSent` on the SSRC when the codec switches
+     * (crbug.com/webrtc/5361), producing sawtooth spikes and negative bitrates. All deltas for the
+     * tick are suppressed so a codec change is never mistaken for a traffic event.
+     */
+    counterResetBoundary: boolean;
     remoteRttInMs?: number;
     remoteFractionLost?: number;
     remoteJitter?: number;
@@ -1752,6 +1776,46 @@ declare class ObservedInboundRtp implements InboundRtpStats {
     deltaBytesReceived: number;
     deltaReceivedSamples: number;
     deltaSilentConcealedSamples: number;
+    deltaConcealedSamples: number;
+    deltaConcealmentEvents: number;
+    deltaFreezeCount: number;
+    deltaFreezesDuration: number;
+    deltaPliCount: number;
+    deltaNackCount: number;
+    deltaFirCount: number;
+    deltaPacketsDiscarded: number;
+    deltaFramesDecoded: number;
+    deltaFramesReceived: number;
+    deltaFramesRendered: number;
+    deltaFramesDropped: number;
+    deltaKeyFramesDecoded: number;
+    deltaDecodeTime: number;
+    deltaJitterBufferDelay: number;
+    deltaJitterBufferEmittedCount: number;
+    deltaRetransmittedPacketsReceived: number;
+    deltaFecPacketsReceived: number;
+    deltaFecPacketsDiscarded: number;
+    deltaPausesDuration: number;
+    /**
+     * Mean jitter-buffer delay for the frames/samples emitted in this tick (seconds), derived from
+     * the cumulative `jitterBufferDelay` / `jitterBufferEmittedCount` pair — the only correct way to
+     * read those two counters.
+     */
+    jitterBufferDelayInMs?: number;
+    /** Fraction of the samples received in this tick that were concealed (0..1). */
+    concealmentRatio?: number;
+    /** Fraction of the frames received in this tick that were dropped before rendering (0..1). */
+    framesDroppedRatio?: number;
+    /**
+     * `true` when the codec or decoder implementation changed in this tick.
+     *
+     * Chrome resets `packetsReceived`/`bytesReceived` on an SSRC when the codec switches
+     * (crbug.com/webrtc/5361, open since 2015), which shows up as a sawtooth spike or a negative
+     * rate. Every delta in this tick is therefore suppressed to `0` rather than reported as traffic
+     * — otherwise a room-wide codec rollout produces a synchronized fake-degradation alert across
+     * every participant at once.
+     */
+    counterResetBoundary: boolean;
     remoteRttInMs?: number;
     remoteBytesSent?: number;
     remotePacketsSent?: number;
@@ -1941,7 +2005,34 @@ declare class ObservedPeerConnection extends EventEmitter {
     sendingVideoBitrate: number;
     receivingAudioBitrate: number;
     receivingVideoBitrate: number;
+    /**
+     * Median round-trip time of the tick, in ms.
+     *
+     * Prefers {@link rtcpRttInMs} and falls back to {@link iceRttInMs}, so within one tick it always
+     * reports **one** kind of round trip. It used to be the median of both mixed together, which was
+     * a bug: the mixing ratio changed as streams came and went, so the value moved for reasons that
+     * had nothing to do with the network.
+     */
     currentRttInMs?: number;
+    /**
+     * RTT measured by ICE/STUN consent checks, in ms — the trip to **whatever terminates ICE**. In an
+     * SFU topology that is the SFU, so this is the client↔SFU leg, not client↔client.
+     */
+    iceRttInMs?: number;
+    /**
+     * RTT reported by RTCP receiver reports, in ms — an **end-to-end** media-path round trip.
+     *
+     * Not the same trip as {@link iceRttInMs}; the difference between the two is roughly the far side
+     * of the SFU (see {@link sfuHopRttInMs}).
+     */
+    rtcpRttInMs?: number;
+    /**
+     * `rtcpRttInMs - iceRttInMs`, when both are known — an estimate of everything *past* the SFU.
+     *
+     * Useful for splitting "this client's own last mile is slow" (high `iceRttInMs`) from "the path
+     * beyond the SFU is slow" (low ICE, high hop).
+     */
+    sfuHopRttInMs?: number;
     currentJitter?: number;
     usingTCP: boolean;
     usingTURN: boolean;
@@ -2036,6 +2127,72 @@ type OperationSystem = {
     version: string;
 };
 
+/** The suffix client-monitor-js appends to the type of a resolution entry. */
+declare const RESOLVED_ISSUE_SUFFIX = "-resolved";
+/**
+ * A **stateful** client issue the server currently believes to be open.
+ *
+ * client-monitor-js (>= 4.6.0, `sendResolvedIssuesToServer`) puts an issue's whole lifecycle on the
+ * wire as two 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 `ActiveClientIssue` on the raise and closes it on the matching key, which
+ * turns a stream of point-in-time symptom reports into **intervals**. That is what makes the
+ * difference between "several clients reported congestion in the last 10 seconds" (a guess built on
+ * an arbitrary window) and "several clients are congested *right now, simultaneously*" — the latter
+ * being real evidence of a shared cause.
+ *
+ * Issues still active when the client monitor closes are auto-resolved by the client, so a clean
+ * departure does not leak. An unclean one (crash, network death) can, which is why the registry
+ * also expires entries — see `IssueRegistry`.
+ */
+type ActiveClientIssue = {
+    /** Identity shared by the raise and its resolution. Unique per client. */
+    key: string;
+    /** The issue type **without** the `-resolved` suffix (e.g. `'congestion'`). */
+    type: string;
+    /** The client that reported it. */
+    clientId: string;
+    /** When the client raised it (client clock). */
+    raisedAt: number;
+    /** When the observer first saw it (server clock) — skew-free, use this for cross-client timing. */
+    observedAt: number;
+    /** Parsed raise payload, when it was JSON. */
+    payload?: Record<string, unknown>;
+    /** `payload.peerConnectionId`, when present — most client detectors report it. */
+    peerConnectionId?: string;
+    /** `payload.trackId`, when present — the join key to a track (and thus to a publisher). */
+    trackId?: string;
+};
+/** A closed interval: an {@link ActiveClientIssue} plus how it ended. */
+type ResolvedClientIssue = ActiveClientIssue & {
+    /** When the client resolved it (client clock). */
+    resolvedAt: number;
+    /** Observer-clock resolution time. */
+    observedResolvedAt: number;
+    /** `resolvedAt - raisedAt` as reported by the client, else derived from observer clocks. */
+    durationInMs: number;
+    /** Free-form note passed to `resolveIssue`. */
+    comment?: string;
+    /** Payload explicitly passed at resolution (the built-in detectors pass their final payload). */
+    resolutionPayload?: Record<string, unknown>;
+    /**
+     * How the interval ended: the client said so, the observer expired it, or the client left
+     * without resolving.
+     */
+    resolvedBy: 'client' | 'timeout' | 'client-closed';
+};
+/** `true` when the entry is a resolution companion rather than a raise. */
+declare function isResolutionEntry(issue: ClientIssue): boolean;
+/** Strip the `-resolved` suffix, so both entries of a lifecycle share one logical type. */
+declare function baseIssueType(type: string): string;
+/** Best-effort parse of the JSON-string payload the schema carries. */
+declare function parseIssuePayload(payload?: string): Record<string, unknown> | undefined;
+
 /** The lifecycle events a sink may emit (a subset of Node's writable-stream events). */
 type ClientSampleSinkEvents = {
     /** The destination is fully written and closed (e.g. a file flushed and its fd closed). */
@@ -2103,11 +2260,11 @@ type RtpCodecParameters = {
         parameter?: string;
     }[];
 };
-type SampleHistoryItem<T extends string> = Record<string, unknown> & {
+type SampleHistoryItem<T extends string> = {
     type: T;
     timestamp: number;
 };
-type MediasoupRouterSample = Record<string, unknown> & {
+type MediasoupRouterSample = {
     routerId: string;
     attachments: Record<string, unknown>;
     createdAt: number;
@@ -2151,7 +2308,9 @@ type MediasoupDirectTransportSample = {
     type: 'direct';
     history: MediasoupDirectTransportSampleEventMap[];
 };
-type MediasoupTransportSample = Record<string, unknown> & {
+type MediasoupTransportSample = {
+    /** Free-form application data. Attach anything here — see `ObservedMediasoupRouter`. */
+    attachments?: Record<string, unknown>;
     id: string;
     createdAt: number;
     connectedAt?: number;
@@ -2167,7 +2326,9 @@ type MediasoupProducerSampleEventMap = {
 type MediasoupProducerSampleEvent = {
     [K in keyof MediasoupProducerSampleEventMap]: SampleHistoryItem<K>;
 }[keyof MediasoupProducerSampleEventMap];
-type MediasoupProducerSample = Record<string, unknown> & {
+type MediasoupProducerSample = {
+    /** Free-form application data. Attach anything here — see `ObservedMediasoupRouter`. */
+    attachments?: Record<string, unknown>;
     id: string;
     transportId: string;
     createdAt: number;
@@ -2191,7 +2352,9 @@ type MediasoupConsumerSampleEventMap = {
 type MediasoupConsumerSampleEvent = {
     [K in keyof MediasoupConsumerSampleEventMap]: SampleHistoryItem<K>;
 }[keyof MediasoupConsumerSampleEventMap];
-type MediasoupConsumerSample = Record<string, unknown> & {
+type MediasoupConsumerSample = {
+    /** Free-form application data. Attach anything here — see `ObservedMediasoupRouter`. */
+    attachments?: Record<string, unknown>;
     id: string;
     producerId: string;
     transportId: string;
@@ -2200,7 +2363,9 @@ type MediasoupConsumerSample = Record<string, unknown> & {
     kind: 'audio' | 'video';
     history: MediasoupConsumerSampleEvent[];
 };
-type MediasoupDataProducerSample = Record<string, unknown> & {
+type MediasoupDataProducerSample = {
+    /** Free-form application data. Attach anything here — see `ObservedMediasoupRouter`. */
+    attachments?: Record<string, unknown>;
     id: string;
     transportId: string;
     createdAt: number;
@@ -2208,7 +2373,9 @@ type MediasoupDataProducerSample = Record<string, unknown> & {
     label: string;
     protocol: string;
 };
-type MediasoupDataConsumerSample = Record<string, unknown> & {
+type MediasoupDataConsumerSample = {
+    /** Free-form application data. Attach anything here — see `ObservedMediasoupRouter`. */
+    attachments?: Record<string, unknown>;
     id: string;
     dataProducerId: string;
     transportId: string;
@@ -2218,13 +2385,86 @@ type MediasoupDataConsumerSample = Record<string, unknown> & {
     protocol: string;
 };
 
+/**
+ * Declarative enrichment: return the `attachments` to stamp onto an entity's sample the moment it is
+ * created. Called once per entity, before the corresponding `*-sample-added` event.
+ *
+ * The mediasoup object is handed in, so the common case — mirroring mediasoup's own `appData`, where
+ * applications already keep `participantId`, `purpose` and friends — is a one-liner. Returning
+ * `undefined` attaches nothing.
+ */
+type MediasoupSampleEnricher = {
+    transport?: (transport: types.Transport) => Record<string, unknown> | undefined;
+    producer?: (producer: types.Producer, transport: types.Transport) => Record<string, unknown> | undefined;
+    consumer?: (consumer: types.Consumer, transport: types.Transport) => Record<string, unknown> | undefined;
+    dataProducer?: (dataProducer: types.DataProducer, transport: types.Transport) => Record<string, unknown> | undefined;
+    dataConsumer?: (dataConsumer: types.DataConsumer, transport: types.Transport) => Record<string, unknown> | undefined;
+};
 type ObservedMediasoupRouterSettings<AppData extends Record<string, unknown> = Record<string, unknown>> = {
     router: types.Router;
     appData?: AppData;
     attachments?: Record<string, unknown>;
+    /** Stamp `attachments` onto each entity sample as it is created. See {@link MediasoupSampleEnricher}. */
+    enrich?: MediasoupSampleEnricher;
 };
+/**
+ * Lifecycle hooks for building your own report.
+ *
+ * Each entity announces itself as `<entity>-sample-added` when it appears and
+ * `<entity>-sample-closed` when it goes away, carrying **the live sample object** plus the mediasoup
+ * object it came from. Mutating `sample.attachments` inside a handler is the intended way to extend
+ * a sample on the fly — the object you receive is the one held in `observedRouter.sample`, not a copy.
+ */
 type ObservedMediasoupRouterEvents = {
     close: [];
+    'transport-sample-added': [{
+        sample: MediasoupTransportSample;
+        transport: types.Transport;
+    }];
+    'transport-sample-closed': [{
+        sample: MediasoupTransportSample;
+        transport: types.Transport;
+    }];
+    'producer-sample-added': [{
+        sample: MediasoupProducerSample;
+        producer: types.Producer;
+        transport: types.Transport;
+    }];
+    'producer-sample-closed': [{
+        sample: MediasoupProducerSample;
+        producer: types.Producer;
+        transport: types.Transport;
+    }];
+    'consumer-sample-added': [{
+        sample: MediasoupConsumerSample;
+        consumer: types.Consumer;
+        transport: types.Transport;
+    }];
+    'consumer-sample-closed': [{
+        sample: MediasoupConsumerSample;
+        consumer: types.Consumer;
+        transport: types.Transport;
+    }];
+    'data-producer-sample-added': [{
+        sample: MediasoupDataProducerSample;
+        dataProducer: types.DataProducer;
+        transport: types.Transport;
+    }];
+    'data-producer-sample-closed': [{
+        sample: MediasoupDataProducerSample;
+        dataProducer: types.DataProducer;
+        transport: types.Transport;
+    }];
+    'data-consumer-sample-added': [{
+        sample: MediasoupDataConsumerSample;
+        dataConsumer: types.DataConsumer;
+        transport: types.Transport;
+    }];
+    'data-consumer-sample-closed': [{
+        sample: MediasoupDataConsumerSample;
+        dataConsumer: types.DataConsumer;
+        transport: types.Transport;
+    }];
 };
 declare interface ObservedMediasoupRouter {
     on<U extends keyof ObservedMediasoupRouterEvents>(event: U, listener: (...args: ObservedMediasoupRouterEvents[U]) => void): this;
@@ -2250,9 +2490,36 @@ declare class ObservedMediasoupRouter<AppData extends Record<string, unknown> =
     readonly sample: MediasoupRouterSample;
     readonly webrtcTransportIds: Set<string>;
     closed: boolean;
+    private readonly _transportSamples;
+    private readonly _producerSamples;
+    private readonly _consumerSamples;
+    private readonly _dataProducerSamples;
+    private readonly _dataConsumerSamples;
+    private readonly _enrich?;
     constructor(settings: ObservedMediasoupRouterSettings<AppData>);
     get id(): string;
     get attachments(): Record<string, unknown>;
+    getTransportSample(id: string): MediasoupTransportSample | undefined;
+    getProducerSample(id: string): MediasoupProducerSample | undefined;
+    getConsumerSample(id: string): MediasoupConsumerSample | undefined;
+    getDataProducerSample(id: string): MediasoupDataProducerSample | undefined;
+    getDataConsumerSample(id: string): MediasoupDataConsumerSample | undefined;
+    /**
+     * Merge `attachments` into an entity's sample, whichever kind it is.
+     *
+     * Ids are unique across mediasoup entity kinds, so one method covers all of them. Returns `false`
+     * when the id is unknown — a real answer instead of failing quietly, which matters when the
+     * annotation is driven by application events that may race the mediasoup ones.
+     */
+    attachTo(id: string, attachments: Record<string, unknown>): boolean;
+    /**
+     * A **detached deep copy** of the current sample — the basis for building your own report.
+     *
+     * `this.sample` is live: its arrays grow and its `history` entries are appended as the router
+     * runs, so a report built directly on it keeps changing after you think you're done. This returns
+     * a snapshot that never moves.
+     */
+    snapshot(): MediasoupRouterSample;
     close(): void;
     addTransport: (transport: types.Transport) => void;
     addWebRtcTransport(transport: types.WebRtcTransport): void;
@@ -2264,6 +2531,18 @@ declare class ObservedMediasoupRouter<AppData extends Record<string, unknown> =
     addDataProducer(transport: types.Transport, dataProducer: types.DataProducer): void;
     addDataConsumer(transport: types.Transport, dataConsumer: types.DataConsumer): void;
     private attachRouterListeners;
+    private _addTransportSample;
+    private _addProducerSample;
+    private _addConsumerSample;
+    private _addDataProducerSample;
+    private _addDataConsumerSample;
+    /**
+     * Run an enricher and merge what it returns.
+     *
+     * Takes a thunk rather than a value so the **invocation** is inside the guard — application code
+     * runs here, and a throwing enricher must not take the router's bookkeeping down with it.
+     */
+    private _applyEnrichment;
     private _attachTransportObserverListeners;
 }
 
@@ -2304,6 +2583,10 @@ type ObserverEvents = {
         reason: SampleRejectedReason;
         sample: ClientSample;
     }];
+    /** An observer-scoped (cross-call / SFU-wide) finding raised by `observer.addIssue(...)`. */
+    'observer-issue': [ObserverEventBase & {
+        issue: ClientIssue;
+    }];
     'mediasoup-router-added': [ObservedMediasoupRouterScope];
     'mediasoup-router-removed': [ObservedMediasoupRouterScope];
     'mediasoup-router-matched-with-peer-connection': [ObservedMediasoupRouterScope & ObservedPeerConnectionScope];
@@ -2332,6 +2615,14 @@ type ObserverEvents = {
     'client-issue': [ObservedClientScope & {
         issue: ClientIssue;
     }];
+    /**
+     * A stateful client issue ended — the client sent its `<type>-resolved` companion, or the
+     * observer force-closed it because the client went away. Carries the finished **interval**
+     * (`raisedAt` → `resolvedAt`, `durationInMs`).
+     */
+    'client-issue-resolved': [ObservedClientScope & {
+        resolvedIssue: ResolvedClientIssue;
+    }];
     'client-metadata': [ObservedClientScope & {
         metaData: ClientMetaData;
     }];
@@ -2582,6 +2873,16 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     numberOfScoreMeasurements: number;
     readonly mediaDevices: MediaDeviceInfo[];
     issues: ClientIssue[];
+    /**
+     * The client's currently **open** stateful issues, keyed by `ClientIssue.key` — the server-side
+     * mirror of the client monitor's own active-issue map (client-monitor-js >= 4.6.0).
+     *
+     * This turns point-in-time symptom reports into intervals, which is what lets detectors ask
+     * "are these clients broken *at the same time*" instead of "did they both report something
+     * recently". Entries are opened by a raise, closed by the matching `<type>-resolved` entry, and
+     * force-closed when the client closes.
+     */
+    readonly activeIssues: Map<string, ActiveClientIssue>;
     private _pendingInjections;
     private _activeSample?;
     private closeTimer?;
@@ -2596,8 +2897,28 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     injectExtensionStat(stat: ExtensionStat): void;
     injectAttachment(attachments: Record<string, unknown>): void;
     addMetadata(metadata: ClientMetaData): void;
+    /**
+     * Process one `clientIssues[]` entry.
+     *
+     * Entries come in two flavours (client-monitor-js >= 4.6.0):
+     *
+     * - a **raise** — opens an {@link ActiveClientIssue} under `issue.key` and emits `client-issue`;
+     * - a **resolution** — `type` ends in `-resolved` and carries the same `key`; it closes the
+     *   matching active issue and emits `client-issue-resolved`.
+     *
+     * Keyless entries are one-shot: reported, never tracked. A re-raise of a key already active
+     * refreshes the payload rather than opening a second interval.
+     */
     addIssue(issue: ClientIssue): void;
     addExtensionStats(stats: ExtensionStat): void;
+    /**
+     * Close every still-open issue, e.g. because the client is going away. Emits
+     * `client-issue-resolved` for each with the given `resolvedBy`, so correlators relying on the
+     * active set don't keep a departed client's issues open forever.
+     */
+    resolveActiveIssues(resolvedBy?: ResolvedClientIssue['resolvedBy']): void;
+    /** Close the active issue a `<type>-resolved` entry refers to, and announce the finished interval. */
+    private _resolveIssue;
     private _processClientEvent;
     private _updatePeerConnection;
     private _mergePendingInjections;
@@ -2665,6 +2986,12 @@ interface Detector {
     readonly name: string;
     /** Called on every entity update; may raise issues via the entity it observes. */
     update(): void;
+    /**
+     * Optional teardown, called when the detector is removed from its registry (or the registry is
+     * cleared, which happens when the owning call/observer closes). Implement it when the detector
+     * subscribes to events or holds timers, so it doesn't leak.
+     */
+    close?(): void;
 }
 
 declare class Detectors {
@@ -2675,6 +3002,7 @@ declare class Detectors {
     remove(detector: Detector): void;
     update(): void;
     clear(): void;
+    private _close;
 }
 
 type ObservedCallUpdateConfig = {
@@ -2844,6 +3172,13 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
     numberOfPeerConnections: number;
     /** Global, pre-dispatch middleware chain run on every accepted sample. */
     readonly acceptMiddlewares: MiddlewareProcessor<AcceptMiddlewarePayload>;
+    /**
+     * Observer-scoped detector registry (ships empty), run on every `observer.update()` — the place
+     * for findings that span **calls**, e.g. "many calls on the same SFU degraded at once". Detectors
+     * raise findings with `observer.addIssue(...)`, surfaced on the bus as `observer-issue`.
+     * (For findings within a single call use `observedCall.detectors`.)
+     */
+    readonly detectors: Detectors;
     constructor(config?: ObserverConfig<AppData>);
     get numberOfCalls(): number;
     get appData(): AppData | undefined;
@@ -2856,6 +3191,11 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
     close(): void;
     accept(sample: ClientSample, context?: AcceptContext): void;
     update(): void;
+    /**
+     * Raise an observer-scoped (cross-call / SFU-wide) finding. Emitted on the bus as
+     * `observer-issue`. Intended for `observer.detectors`, but the application may call it too.
+     */
+    addIssue(issue: ClientIssue): void;
     /** Emit an Observer-bus event. */
     private _notify;
 }
@@ -2894,6 +3234,911 @@ declare enum ClientEventTypes {
     DATA_CONSUMER_CLOSED = "DATA_CONSUMER_CLOSED"
 }
 
+/**
+ * Small statistics helpers used by the aggregators and detectors.
+ *
+ * Rationale: a mean is a poor summary for call telemetry — one participant with a 1500 ms RTT
+ * skews the average for nine healthy ones. Detectors should reason with medians, high percentiles
+ * and "affected ratios" instead.
+ */
+/** A distribution summary of a numeric sample set. */
+type StatsSummary = {
+    count: number;
+    min: number;
+    max: number;
+    mean: number;
+    median: number;
+    p75: number;
+    p95: number;
+};
+/**
+ * The p-th percentile (0..1) using linear interpolation between closest ranks.
+ * Returns `undefined` for an empty input.
+ */
+declare function percentile(values: number[], p: number): number | undefined;
+/** The median (50th percentile). `undefined` for an empty input. */
+declare function median(values: number[]): number | undefined;
+/** Summarize a numeric sample set. Returns `undefined` for an empty input. */
+declare function summarize(values: number[]): StatsSummary | undefined;
+/**
+ * A counter-reset-safe delta: the increase of a cumulative counter between two observations.
+ *
+ * Returns `0` when the counter went backwards (reset / SSRC reuse) or when either side is missing.
+ * NOTE the guard is `>=` on **defined** values — a previous value of `0` is a perfectly valid
+ * baseline, so `0 -> 5` correctly yields `5` (using a truthiness check here silently drops the
+ * first interval of every counter, which is exactly when the first loss/freeze event happens).
+ */
+declare function counterDelta(previous: number | undefined, current: number | undefined): number;
+/** An entry retained by {@link SlidingWindow}. */
+type SlidingWindowEntry<T> = {
+    timestamp: number;
+    value: T;
+};
+/**
+ * A time-bounded ring buffer used by detectors that reason over a window ("N of M clients degraded
+ * within 10 s"). Entries older than `windowMs` are evicted on write and on read.
+ */
+declare class SlidingWindow<T> {
+    readonly windowMs: number;
+    /** Optional hard cap on retained entries, to bound memory on very chatty inputs. */
+    readonly maxEntries: number;
+    private _entries;
+    constructor(windowMs: number, 
+    /** Optional hard cap on retained entries, to bound memory on very chatty inputs. */
+    maxEntries?: number);
+    /** Add an entry (defaults to `Date.now()`), then evict anything outside the window. */
+    add(value: T, timestamp?: number): void;
+    /** The entries still inside the window, oldest first. */
+    entries(now?: number): SlidingWindowEntry<T>[];
+    /** The values still inside the window, oldest first. */
+    values(now?: number): T[];
+    get size(): number;
+    clear(): void;
+    private _evict;
+}
+
+/**
+ * Thresholds deciding when a single receiver counts as "degraded". A receiver is degraded when it
+ * trips **any** of these in the current tick.
+ */
+type ReceiverHealthThresholds = {
+    /** Fraction of packets lost in the tick (0..1). */
+    fractionLost: number;
+    /** Freezes observed in the tick. */
+    freezeCount: number;
+    /** Fraction of received frames dropped before rendering (0..1). */
+    framesDroppedRatio: number;
+    /** Fraction of received audio samples concealed (0..1). */
+    concealmentRatio: number;
+    /** Mean jitter-buffer delay of the tick (ms). */
+    jitterBufferDelayInMs: number;
+    /** Round-trip time reported for the receiving peer connection (ms). */
+    rttInMs: number;
+};
+declare const defaultReceiverHealthThresholds: ReceiverHealthThresholds;
+/** The per-receiver view the aggregator builds for one subscribed track. */
+type ReceiverDistributionEntry = {
+    observedInboundTrack: ObservedInboundTrack;
+    clientId: string;
+    peerConnectionId: string;
+    degraded: boolean;
+    /** Why it was marked degraded (empty when healthy). */
+    reasons: string[];
+    bitrate: number;
+    fractionLost?: number;
+    jitter?: number;
+    rttInMs?: number;
+    jitterBufferDelayInMs?: number;
+    concealmentRatio?: number;
+    framesDroppedRatio?: number;
+    deltaFreezeCount: number;
+    deltaPliCount: number;
+    deltaNackCount: number;
+    deltaPacketsReceived: number;
+};
+/** The publisher side of the distribution. */
+type PublisherDistributionEntry = {
+    observedOutboundTrack: ObservedOutboundTrack;
+    clientId: string;
+    peerConnectionId: string;
+    /** `true` when the publisher's own egress looks fine (so degradation is downstream). */
+    healthy: boolean;
+    reasons: string[];
+    bitrate: number;
+    /** Loss reported back by the SFU/remote via RTCP (0..1). */
+    remoteFractionLost?: number;
+    remoteRttInMs?: number;
+    qualityLimitationReason?: string;
+    deltaPacketsSent: number;
+};
+/**
+ * One published track and everything observed about how it was delivered to its subscribers.
+ * This is the primitive most cross-client detectors are built on.
+ */
+type ObservedTrackDistribution = {
+    trackId: string;
+    kind: string;
+    publisher: PublisherDistributionEntry;
+    receivers: ReceiverDistributionEntry[];
+    numberOfReceivers: number;
+    numberOfHealthyReceivers: number;
+    numberOfDegradedReceivers: number;
+    /** degradedReceivers / receivers (0..1); `0` when there are no receivers. */
+    degradedRatio: number;
+    /** Distribution summaries across receivers (undefined when no receiver reported the metric). */
+    bitrate?: StatsSummary;
+    fractionLost?: StatsSummary;
+    jitter?: StatsSummary;
+    rttInMs?: StatsSummary;
+    jitterBufferDelayInMs?: StatsSummary;
+    concealmentRatio?: StatsSummary;
+    /** Fan-out counters: how many receivers saw the symptom, and the total across them. */
+    freezes: {
+        affectedReceivers: number;
+        total: number;
+    };
+    plis: {
+        affectedReceivers: number;
+        total: number;
+    };
+    concealment: {
+        affectedReceivers: number;
+    };
+};
+/**
+ * Builds {@link ObservedTrackDistribution}s by walking
+ * `ObservedOutboundTrack.remoteInboundTracks` — the publisher → subscribers links maintained by a
+ * `RemoteTrackResolver`. Without a configured resolver there are no links and the aggregator
+ * yields nothing.
+ *
+ * It is stateless per call: build it once and call `aggregate()` on each `call.update()`.
+ */
+declare class TrackDistributionAggregator {
+    private readonly _call;
+    readonly thresholds: ReceiverHealthThresholds;
+    constructor(_call: ObservedCall, thresholds?: ReceiverHealthThresholds);
+    /** Aggregate every published track in the call that currently has linked subscribers. */
+    aggregate(): ObservedTrackDistribution[];
+    /** Aggregate a single published track, or `undefined` when it has no linked subscribers. */
+    aggregateTrack(outboundTrack: ObservedOutboundTrack): ObservedTrackDistribution | undefined;
+    private _publisherEntry;
+    private _receiverEntry;
+}
+
+/** Thresholds deciding when a client counts as degraded on the receiving / sending side. */
+type ClientHealthThresholds = {
+    /** Inbound loss fraction across the client's received streams (0..1). */
+    inboundFractionLost: number;
+    /** Loss fraction reported back about the client's sent streams via RTCP (0..1). */
+    outboundFractionLost: number;
+    /** Round-trip time (ms). */
+    rttInMs: number;
+    /** Freezes observed across the client's inbound video in the tick. */
+    freezeCount: number;
+    /** Concealment fraction across the client's inbound audio (0..1). */
+    concealmentRatio: number;
+};
+declare const defaultClientHealthThresholds: ClientHealthThresholds;
+/** The per-client health view, split by direction. */
+type ClientHealth = {
+    observedClient: ObservedClient;
+    clientId: string;
+    /** Receiving (download) side is impaired. */
+    inboundDegraded: boolean;
+    /** Sending (upload) side is impaired. */
+    outboundDegraded: boolean;
+    /** `inboundDegraded || outboundDegraded`. */
+    degraded: boolean;
+    reasons: string[];
+    inboundFractionLost?: number;
+    outboundFractionLost?: number;
+    rttInMs?: number;
+    deltaFreezeCount: number;
+    concealmentRatio?: number;
+    /** Quality-limitation reasons seen on this client's outbound video ('cpu' | 'bandwidth' | …). */
+    qualityLimitationReasons: string[];
+    usingTURN: boolean;
+    usingTCP: boolean;
+};
+/** Call-level rollup of the per-client health, using percentiles rather than means. */
+type CallHealth = {
+    callId: string;
+    clients: ClientHealth[];
+    numberOfClients: number;
+    numberOfDegradedClients: number;
+    numberOfInboundDegradedClients: number;
+    numberOfOutboundDegradedClients: number;
+    /** degradedClients / clients (0..1). */
+    degradedRatio: number;
+    inboundDegradedRatio: number;
+    outboundDegradedRatio: number;
+    rttInMs?: StatsSummary;
+    inboundFractionLost?: StatsSummary;
+    concealmentRatio?: StatsSummary;
+    /** How many clients reported each quality-limitation reason on their outbound video. */
+    qualityLimitation: {
+        cpu: number;
+        bandwidth: number;
+        other: number;
+    };
+    freezes: {
+        affectedClients: number;
+        total: number;
+    };
+};
+/**
+ * Aggregates a call along the **client** axis (as `TrackDistributionAggregator` does along the
+ * publisher→subscriber axis): per-client health split into sending vs receiving, plus percentile
+ * rollups and "affected ratio" counts for the whole call.
+ *
+ * Build once per call and call `aggregate()` on each `call.update()`.
+ */
+declare class CallHealthAggregator {
+    private readonly _call;
+    readonly thresholds: ClientHealthThresholds;
+    constructor(_call: ObservedCall, thresholds?: ClientHealthThresholds);
+    aggregate(): CallHealth;
+    private _clientHealth;
+}
+
+/** The finding types this detector raises (as `call-issue.type`). */
+declare const CommonSourceDegradationTypes: {
+    /** The publisher's egress looks fine, yet most subscribers are degraded → downstream/SFU suspected. */
+    readonly publisherHealthySubscribersDegraded: "PUBLISHER_HEALTHY_SUBSCRIBERS_DEGRADED";
+    /** The publisher itself is impaired and every subscriber sees it → source-side problem. */
+    readonly publisherDegradedForAllSubscribers: "PUBLISHER_DEGRADED_FOR_ALL_SUBSCRIBERS";
+    /** Exactly one subscriber is degraded while the rest are fine → that receiver's own problem. */
+    readonly singleSubscriberDegraded: "SINGLE_SUBSCRIBER_DEGRADED";
+    /** Several (but not most) subscribers degraded on the same source. */
+    readonly multipleSubscribersDegraded: "MULTIPLE_SUBSCRIBERS_DEGRADED";
+};
+type CommonSourceDegradationDetectorConfig = {
+    /** Minimum subscribers before a ratio is meaningful. Default `3`. */
+    minReceivers: number;
+    /** degradedRatio at/above which the problem is treated as common to the source. Default `0.6`. */
+    degradedRatioThreshold: number;
+    /** Per-receiver health thresholds (forwarded to the aggregator). */
+    thresholds?: Partial<ReceiverHealthThresholds>;
+    /**
+     * Consecutive ticks a condition must hold before an issue is raised, to avoid flapping on a
+     * single bad sample. Default `2`.
+     */
+    consecutiveTicks: number;
+};
+/**
+ * Compares a published track against **all** of its subscribers and decides where the fault lies.
+ *
+ * This is the detector that only a server-side observer can run: a single browser cannot know
+ * whether the other participants receiving the same source see the same thing. Requires a
+ * `RemoteTrackResolver` (`ObserverConfig.createTrackResolver`) — without publisher↔subscriber links
+ * there is nothing to compare and the detector stays silent.
+ */
+declare class CommonSourceDegradationDetector implements Detector {
+    private readonly _call;
+    readonly name = "common-source-degradation-detector";
+    private readonly _config;
+    private readonly _aggregator;
+    /** trackId -> consecutive ticks the same finding held. */
+    private readonly _streaks;
+    /** The distributions computed on the most recent `update()` (handy for dashboards). */
+    lastDistributions: ObservedTrackDistribution[];
+    constructor(_call: ObservedCall, config?: Partial<CommonSourceDegradationDetectorConfig>);
+    update(): void;
+    private _classify;
+    private _payload;
+}
+
+declare const CallWideDegradationTypes: {
+    /** Most participants degraded at once → shared cause (call/SFU/network), not individual endpoints. */
+    readonly callWideQualityDegradation: "CALL_WIDE_QUALITY_DEGRADATION";
+    /** Most participants' **receiving** side degraded → downstream/egress suspected. */
+    readonly callWideInboundDegradation: "CALL_WIDE_INBOUND_DEGRADATION";
+    /** Most participants' **sending** side degraded → ingress suspected. */
+    readonly callWideOutboundDegradation: "CALL_WIDE_OUTBOUND_DEGRADATION";
+};
+type CallWideDegradationDetectorConfig = {
+    /** Minimum participants before a ratio means anything. Default `3`. */
+    minClients: number;
+    /** Affected-client ratio at/above which the call is considered call-wide degraded. Default `0.5`. */
+    degradedRatioThreshold: number;
+    /** Per-client health thresholds. */
+    thresholds?: Partial<ClientHealthThresholds>;
+    /** Consecutive ticks the condition must hold before raising. Default `2`. */
+    consecutiveTicks: number;
+};
+/**
+ * Raises a call-level finding when a **majority of participants** are degraded in the same window —
+ * the signal that something shared is wrong rather than one person's Wi-Fi.
+ *
+ * It also splits by direction, because that is what makes the finding actionable: if most clients'
+ * receiving side is bad the suspicion is egress/downstream; if most clients' sending side is bad it
+ * points at ingress. Reported with medians/percentiles, never means, so a single 1500 ms outlier
+ * can't manufacture (or mask) a call-wide alert.
+ */
+declare class CallWideDegradationDetector implements Detector {
+    private readonly _call;
+    readonly name = "call-wide-degradation-detector";
+    private readonly _config;
+    private readonly _aggregator;
+    private _streak?;
+    /** The health rollup computed on the most recent `update()`. */
+    lastHealth?: CallHealth;
+    constructor(_call: ObservedCall, config?: Partial<CallWideDegradationDetectorConfig>);
+    update(): void;
+    private _classify;
+    private _payload;
+}
+
+declare const PliAndFreezeFanOutTypes: {
+    /** Many receivers of the same publisher requested keyframes at once. */
+    readonly publisherPliStorm: "PUBLISHER_PLI_STORM";
+    /** Many receivers of the same publisher froze at once. */
+    readonly publishedVideoFrozenForMultipleReceivers: "PUBLISHED_VIDEO_FROZEN_FOR_MULTIPLE_RECEIVERS";
+};
+type PliAndFreezeFanOutDetectorConfig = {
+    /** Minimum receivers of the track before a fan-out ratio is meaningful. Default `3`. */
+    minReceivers: number;
+    /** Fraction of receivers that must be affected within the window. Default `0.5`. */
+    affectedRatioThreshold: number;
+    /** The correlation window (ms) symptoms are counted over. Default `10_000`. */
+    windowMs: number;
+    /** Minimum PLIs across receivers inside the window before a storm is declared. Default `5`. */
+    minPliCount: number;
+    /** Re-arm time (ms) before the same finding can be raised again for a track. Default `30_000`. */
+    cooldownMs: number;
+    thresholds?: Partial<ReceiverHealthThresholds>;
+};
+/**
+ * Detects **fan-out** symptoms: one publisher's stream causing many receivers to request keyframes
+ * (PLI) or to freeze within the same window.
+ *
+ * A single receiver sending PLIs is unremarkable — it lost some packets. Nineteen of twenty
+ * receivers of the *same* source doing it inside ten seconds is not twenty coincidental network
+ * faults; it points at the source's output, the SFU's forwarding, or a keyframe/burst problem
+ * upstream. That distinction requires seeing every subscriber of a track at once, which is why this
+ * belongs server-side.
+ *
+ * Symptoms are accumulated in a sliding window rather than judged per tick, because a burst is
+ * spread over a few samples.
+ */
+declare class PliAndFreezeFanOutDetector implements Detector {
+    private readonly _call;
+    readonly name = "pli-and-freeze-fan-out-detector";
+    private readonly _config;
+    private readonly _aggregator;
+    private readonly _windows;
+    constructor(_call: ObservedCall, config?: Partial<PliAndFreezeFanOutDetectorConfig>);
+    update(): void;
+    close(): void;
+    private _evaluate;
+    private _windowOf;
+}
+
+declare const AudioImpairmentFanOutTypes: {
+    /** Most receivers of one microphone are concealing audio → the problem follows that source. */
+    readonly publishedAudioDegradedForMajority: "PUBLISHED_AUDIO_DEGRADED_FOR_MAJORITY";
+    /** Receivers across the call are under jitter-buffer pressure → shared delivery problem. */
+    readonly callWideAudioJitterBufferStress: "CALL_WIDE_AUDIO_JITTER_BUFFER_STRESS";
+};
+type AudioImpairmentFanOutDetectorConfig = {
+    /** Minimum receivers of a track before a ratio is meaningful. Default `3`. */
+    minReceivers: number;
+    /** Fraction of receivers that must be impaired. Default `0.6`. */
+    affectedRatioThreshold: number;
+    /** Jitter-buffer delay (ms) above which a receiver counts as stressed. Default `500`. */
+    jitterBufferDelayInMs: number;
+    /** Minimum audio receivers in the call before the call-wide check runs. Default `5`. */
+    minCallReceivers: number;
+    /** Consecutive ticks the condition must hold before raising. Default `2`. */
+    consecutiveTicks: number;
+    thresholds?: Partial<ReceiverHealthThresholds>;
+};
+/**
+ * Audio-side fan-out analysis, using the concealment / jitter-buffer metrics WebRTC exposes on the
+ * receiver (NetEQ's own account of how hard it is working to keep audio smooth).
+ *
+ * Two questions a browser can't answer:
+ *
+ * 1. *Does the impairment follow the source?* If every receiver of Alice's microphone is concealing
+ *    ~20% of samples while every receiver of Bob's is at ~0.1%, the fault is on Alice's path, not on
+ *    the receivers.
+ * 2. *Is the whole call's audio delivery under pressure?* One receiver with a huge jitter buffer is
+ *    their own network; fifteen of twenty at once is shared.
+ */
+declare class AudioImpairmentFanOutDetector implements Detector {
+    private readonly _call;
+    readonly name = "audio-impairment-fan-out-detector";
+    private readonly _config;
+    private readonly _aggregator;
+    private readonly _trackStreaks;
+    private _callStreak;
+    constructor(_call: ObservedCall, config?: Partial<AudioImpairmentFanOutDetectorConfig>);
+    update(): void;
+    close(): void;
+    private _evaluateCallWide;
+}
+
+declare const IceDisruptionTypes: {
+    /** Many participants lost/failed their ICE connection inside the same window. */
+    readonly callIceDisruption: "CALL_ICE_DISRUPTION";
+};
+type IceDisruptionDetectorConfig = {
+    /** Minimum participants before a ratio is meaningful. Default `3`. */
+    minClients: number;
+    /** Fraction of participants that must be disrupted within the window. Default `0.5`. */
+    affectedRatioThreshold: number;
+    /** Correlation window (ms). Default `10_000`. */
+    windowMs: number;
+    /** Re-arm time (ms) before raising again. Default `60_000`. */
+    cooldownMs: number;
+};
+/**
+ * Detects an **ICE disruption storm**: many participants of a call losing connectivity inside the
+ * same short window.
+ *
+ * One client losing ICE is routine (they walked out of Wi-Fi range). Twenty-eight of thirty-five
+ * doing it within five seconds is an infrastructure event, and that conclusion is only reachable by
+ * correlating clients — which is the whole point of doing it here rather than in the browser.
+ *
+ * ### Prefer the issue-driven path
+ *
+ * This detector works from **raw ICE state transitions**, which is the fallback for clients that do
+ * not report issues. If your clients run client-monitor-js >= 4.6.0, prefer
+ * `ConcurrentIssueDetector` configured with the ICE issue types instead:
+ *
+ * ```ts
+ * new ConcurrentIssueDetector(observedCall, {
+ *   issueTypes: [ 'ice-disconnected', 'ice-connection-failed', 'ice-transport-stalled', 'unstable-ice-path' ],
+ * });
+ * ```
+ *
+ * The client's own detector is better at deciding *whether* a transport is really disrupted: it
+ * raises `ice-disconnected` only once `disconnected` has persisted past a threshold, so the transient
+ * blips ICE routinely heals on its own never produce an issue at all, and it distinguishes a terminal
+ * `failed` from a stalled transport from an unstable path. This detector cannot make those
+ * distinctions — a raw `disconnected` that recovers in 200 ms looks identical to one that never does.
+ * It also gains resolution intervals, so "they all recovered together" becomes observable.
+ *
+ * ### Why this one subscribes to the bus
+ *
+ * ICE transitions are discrete events that can occur and revert between two `update()` ticks;
+ * polling `iceConnectionState` per tick would miss short flaps. It therefore implements `close()`
+ * to drop its listeners (called automatically when the call closes or the detector is removed).
+ */
+declare class IceDisruptionDetector implements Detector {
+    private readonly _call;
+    readonly name = "ice-disruption-detector";
+    private readonly _config;
+    /** clientId -> the last time that client was seen disrupted, inside the window. */
+    private readonly _disruptions;
+    private _lastRaisedAt;
+    private readonly _onIceStateChanged;
+    private readonly _onConnectionStateChanged;
+    constructor(_call: ObservedCall, config?: Partial<IceDisruptionDetectorConfig>);
+    update(): void;
+    close(): void;
+}
+
+declare const TurnServerHealthTypes: {
+    /** One TURN server's clients are degraded while other servers' clients are fine. */
+    readonly turnServerDegraded: "TURN_SERVER_DEGRADED";
+};
+type TurnServerHealthDetectorConfig = {
+    /** Minimum clients on a server before a ratio is meaningful. Default `5`. */
+    minClientsPerServer: number;
+    /** Fraction of a server's clients that must be degraded. Default `0.5`. */
+    degradedRatioThreshold: number;
+    /** RTT (ms) above which a relayed peer connection counts as degraded. Default `400`. */
+    rttInMs: number;
+    /** Inbound loss fraction above which a relayed peer connection counts as degraded. Default `0.03`. */
+    fractionLost: number;
+    /** Consecutive ticks the condition must hold before raising. Default `2`. */
+    consecutiveTicks: number;
+    /** Re-arm time (ms) before raising again for the same server. Default `60_000`. */
+    cooldownMs: number;
+};
+/** The per-server view this detector builds. */
+type TurnServerHealth = {
+    serverUrl: string;
+    peerConnections: number;
+    degradedPeerConnections: number;
+    degradedRatio: number;
+    rttInMs?: StatsSummary;
+    fractionLost?: StatsSummary;
+    affectedClientIds: string[];
+};
+/**
+ * An **observer-level** detector that groups relayed peer connections by the TURN server carrying
+ * them and compares the servers against each other.
+ *
+ * Counting TURN usage is not useful on its own; knowing that `turn-eu-1` has 22 of 30 clients in
+ * trouble while `turn-eu-2` has 1 of 34 is. Because the comparison spans calls, it lives on
+ * `observer.detectors` and raises `observer-issue` — a single actionable alert instead of fifty
+ * per-client ones.
+ */
+declare class TurnServerHealthDetector implements Detector {
+    private readonly _observer;
+    readonly name = "turn-server-health-detector";
+    private readonly _config;
+    private readonly _streaks;
+    private readonly _lastRaisedAt;
+    /** The per-server rollup computed on the most recent `update()`. */
+    lastServers: TurnServerHealth[];
+    constructor(_observer: Observer, config?: Partial<TurnServerHealthDetectorConfig>);
+    update(): void;
+    close(): void;
+    private _serverHealth;
+}
+
+/** A snapshot of everyone currently reporting one issue type. */
+type IssueCohort = {
+    /** The issue type, without the `-resolved` suffix. */
+    type: string;
+    /** The open intervals of that type, one per (client, key). */
+    issues: ActiveClientIssue[];
+    /** Distinct clients with at least one open interval of this type. */
+    clientIds: string[];
+    /** `clientIds.length / totalClients` (0..1). */
+    affectedRatio: number;
+    /** Clients considered for the ratio. */
+    totalClients: number;
+    /**
+     * Spread of the onsets, in **observer** time (ms) — `max(observedAt) - min(observedAt)`.
+     *
+     * Measured on the observer clock on purpose: `raisedAt` comes from each client's own clock, and
+     * comparing those across machines makes clock skew look like an infrastructure event. A small
+     * spread means the issues began together, which is the signature of a shared cause.
+     */
+    onsetSpreadInMs: number;
+    /** The earliest onset (observer clock). */
+    firstObservedAt: number;
+};
+/** Options controlling how long an unresolved issue is trusted. */
+type IssueRegistryConfig = {
+    /**
+     * Drop an active issue this long after it was opened, even without a resolution (ms).
+     *
+     * A safety net for the case the lifecycle can't cover: a client that dies without its monitor
+     * running `close()` never sends the `-resolved` companion, and a stuck "active" issue would make
+     * every concurrency detector fire forever. Default `120_000`.
+     */
+    maxIssueAgeInMs: number;
+};
+/**
+ * Read-side index over the **active** client issues in a call (or across an observer's calls).
+ *
+ * `ObservedClient.activeIssues` holds the raw per-client state; this puts the questions detectors
+ * actually ask on top of it:
+ *
+ * - *who currently has issue X?* → {@link cohortOf}
+ * - *which issue types are shared by several clients right now?* → {@link cohorts}
+ * - *which receivers of this published track are broken?* → {@link byTrackIds}
+ *
+ * The distinction that matters is **concurrency**. A window-based count ("N clients reported
+ * congestion in the last 10 s") is a heuristic that has to guess whether the symptoms are still
+ * happening; an active-issue set is ground truth, because the client tells the server when the
+ * episode ends. Overlapping intervals are much stronger evidence of a common cause than
+ * near-in-time reports.
+ *
+ * It is a *view*, holding no state of its own beyond configuration, so it can be constructed per
+ * detector and queried on every `update()`.
+ */
+declare class IssueRegistry {
+    private readonly _source;
+    private readonly _config;
+    constructor(_source: ObservedCall | Observer, config?: Partial<IssueRegistryConfig>);
+    /** Every open issue in scope, with stale entries filtered out. */
+    activeIssues(now?: number): ActiveClientIssue[];
+    /** The number of clients in scope — the denominator for every ratio. */
+    get totalClients(): number;
+    /** The cohort for one issue type (empty `issues` when nobody has it open). */
+    cohortOf(type: string, now?: number): IssueCohort;
+    /** One cohort per issue type currently open somewhere in scope, largest first. */
+    cohorts(now?: number): IssueCohort[];
+    /**
+     * Open issues attributed to any of the given track ids — the join that turns a receiver-side
+     * issue into a statement about a **published** track (`trackId` → inbound track →
+     * `remoteOutboundTrack` → publisher).
+     */
+    byTrackIds(trackIds: Iterable<string>, now?: number): ActiveClientIssue[];
+    /** Open issues reported by one client. */
+    byClientId(clientId: string, now?: number): ActiveClientIssue[];
+    private _toCohort;
+    /** Works for both scopes: a call yields its clients, an observer yields every call's clients. */
+    private _clients;
+}
+
+declare const ConcurrentIssueTypes: {
+    /** Several participants have the same issue open **at the same time**. */
+    readonly concurrentClientIssues: "CONCURRENT_CLIENT_ISSUES";
+    /** Those issues also *began* together — the signature of one infrastructure event. */
+    readonly issueOnsetBurst: "ISSUE_ONSET_BURST";
+};
+type ConcurrentIssueDetectorConfig = {
+    /**
+     * Only consider these issue types. Empty (default) means every type the clients report — which
+     * is usually what you want, since the detector is generic over the client's vocabulary.
+     */
+    issueTypes: string[];
+    /** Minimum participants in scope before a ratio is meaningful. Default `3`. */
+    minClients: number;
+    /** Minimum distinct clients sharing the open issue. Default `3`. */
+    minAffectedClients: number;
+    /** Fraction of participants that must share it. Default `0.5`. */
+    affectedRatioThreshold: number;
+    /**
+     * When the onsets of a qualifying cohort fall within this span (ms), the finding is escalated to
+     * `ISSUE_ONSET_BURST` — they didn't just overlap, they started together. Default `2_000`.
+     */
+    onsetBurstWindowInMs: number;
+    /** Re-arm time (ms) per issue type. Default `60_000`. */
+    cooldownMs: number;
+    /** Forwarded to the {@link IssueRegistry} (stale-issue expiry). */
+    registry?: Partial<IssueRegistryConfig>;
+};
+/**
+ * Raises a finding when **several participants have the same issue open simultaneously**.
+ *
+ * This is the generic replacement for a family of symptom-specific detectors. The client already
+ * decides *what* is wrong for itself — `congestion`, `ice-disconnected`, `audio-concealment`,
+ * `video-decoder-overloaded`, and so on — with detectors that have hysteresis and multi-signal
+ * confirmation behind them. Re-deriving those verdicts from raw counters server-side would be
+ * strictly worse. What the server uniquely knows is *how many other participants are in the same
+ * state right now*, which is exactly the difference between "one person's Wi-Fi" and "our problem".
+ *
+ * Concurrency is judged from the **active issue set** (open interval per key), not from a sliding
+ * window of recent reports. That distinction matters: a window has to guess whether a symptom is
+ * still happening, whereas an interval is closed by the client when the episode actually ends
+ * (client-monitor-js >= 4.6.0 ships the `<type>-resolved` companion for this purpose).
+ *
+ * When the onsets also cluster inside `onsetBurstWindowInMs`, the finding is escalated to
+ * `ISSUE_ONSET_BURST`: participants degrading *together within a couple of seconds* is far more
+ * likely to be a deploy, a TURN failover or a link flap than a coincidence. Onsets are compared on
+ * the **observer clock** (`observedAt`), never on client clocks, because clock skew between
+ * machines would otherwise masquerade as a synchronized event.
+ *
+ * Works at both scopes — pass an `ObservedCall` for "this meeting", or the `Observer` for
+ * "everything this SFU is serving".
+ */
+declare class ConcurrentIssueDetector implements Detector {
+    private readonly _scope;
+    readonly name = "concurrent-issue-detector";
+    private readonly _config;
+    private readonly _registry;
+    private readonly _lastRaisedAt;
+    private readonly _isObserverScope;
+    /** The cohorts that qualified on the most recent `update()`. */
+    lastCohorts: IssueCohort[];
+    constructor(_scope: ObservedCall | Observer, config?: Partial<ConcurrentIssueDetectorConfig>);
+    update(): void;
+    close(): void;
+    private _raise;
+}
+
+declare const IssueFanOutTypes: {
+    /** Most receivers of one published track have the same issue open → the fault follows the source. */
+    readonly publishedTrackIssueFanOut: "PUBLISHED_TRACK_ISSUE_FAN_OUT";
+    /** Exactly one receiver of a track has it → that receiver's own problem. */
+    readonly singleReceiverIssue: "SINGLE_RECEIVER_ISSUE";
+};
+type IssueFanOutDetectorConfig = {
+    /** Only consider these issue types. Empty (default) = every type the receivers report. */
+    issueTypes: string[];
+    /** Minimum receivers of the track before a ratio is meaningful. Default `3`. */
+    minReceivers: number;
+    /** Fraction of a track's receivers that must share the issue. Default `0.6`. */
+    affectedRatioThreshold: number;
+    /** Also report the "only one receiver is affected" case. Default `true`. */
+    reportSingleReceiver: boolean;
+    /** Re-arm time (ms) per (track, issue type). Default `60_000`. */
+    cooldownMs: number;
+    registry?: Partial<IssueRegistryConfig>;
+};
+/**
+ * Attributes **client-reported issues to the published track they are about**, then asks how far
+ * the problem fans out across that track's receivers.
+ *
+ * The join is what makes this possible: a receiver-side issue payload carries `trackId` (the client
+ * detectors report it for every track-scoped issue), the observer resolves that to an inbound track,
+ * and `RemoteTrackResolver` links the inbound track to the `remoteOutboundTrack` that published it.
+ * With the whole subscriber set of one source in hand, the verdict is straightforward and is the
+ * single most useful thing a server can say:
+ *
+ * - **most receivers of Alice's track are affected** → the fault is on Alice's path — her uplink, the
+ *   SFU's ingress, or its forwarding of that stream. Corroborated by whether the publisher's own
+ *   egress looks healthy.
+ * - **one receiver of Alice's track is affected** → that receiver's downlink. Nothing to do with
+ *   Alice, even though the symptom is reported against her stream.
+ *
+ * Note this is deliberately generic over the issue vocabulary: `freezed-video-track`,
+ * `keyframe-storm`, `audio-concealment`, `video-decoder-overloaded`, `stuck-decoder` and anything a
+ * custom client detector invents all fan out the same way, so one mechanism replaces a family of
+ * symptom-specific detectors.
+ */
+declare class IssueFanOutDetector implements Detector {
+    private readonly _call;
+    readonly name = "issue-fan-out-detector";
+    private readonly _config;
+    private readonly _registry;
+    private readonly _aggregator;
+    private readonly _lastRaisedAt;
+    constructor(_call: ObservedCall, config?: Partial<IssueFanOutDetectorConfig>);
+    update(): void;
+    close(): void;
+    /** Exposed for tests/dashboards: the distributions this detector reasons over. */
+    distributionsOf(): ObservedOutboundTrack[];
+}
+
+declare const WorstReceiverContagionTypes: {
+    /**
+     * A publisher's sending bitrate is tracking its **worst** receiver — one bad downlink is
+     * dragging the quality everyone else gets.
+     */
+    readonly worstReceiverContagion: "WORST_RECEIVER_CONTAGION";
+};
+type WorstReceiverContagionDetectorConfig = {
+    /** Minimum receivers before the comparison means anything. Default `3`. */
+    minReceivers: number;
+    /** Observation window (ms) the correlation is computed over. Default `30_000`. */
+    windowMs: number;
+    /** Minimum samples inside the window before judging. Default `4`. */
+    minSamples: number;
+    /**
+     * How closely the publisher's bitrate must track the worst receiver's, relative to the spread
+     * between the worst and the median receiver. Default `0.75`.
+     */
+    trackingRatioThreshold: number;
+    /**
+     * The worst receiver must be this much worse than the median receiver before the situation even
+     * counts as "one bad apple" (0..1 of the median). Default `0.5` — i.e. at most half.
+     */
+    outlierRatioThreshold: number;
+    /** Re-arm time (ms) per track. Default `120_000`. */
+    cooldownMs: number;
+};
+/**
+ * Detects the classic SFU misconfiguration: **the sender adapting to the worst receiver**.
+ *
+ * In a correctly built SFU the RTCP feedback loop is *terminated* at the server — each receiver's
+ * reports drive what that receiver is sent, and the publisher encodes for the server, not for the
+ * unluckiest participant. When the loop is instead relayed end to end, the publisher's bandwidth
+ * estimate collapses to the minimum across all receivers, so a single participant on a bad 3G link
+ * silently downgrades the stream *everyone* sees. Simulcast exists precisely to prevent this
+ * "lowest common denominator" outcome, and its absence (or an SFU that forwards RR/REMB verbatim)
+ * reproduces it.
+ *
+ * The signature is a correlation, not a threshold, so it is judged over a window: the publisher's
+ * outbound bitrate moving in lockstep with the *worst* receiver's inbound bitrate, while the median
+ * receiver has ample headroom. A publisher that drops because of its own uplink or CPU shows no such
+ * relationship — every receiver falls together and there is no outlier to track.
+ *
+ * This is arguably the most valuable thing an observer can detect, because the damage is invisible
+ * from every individual endpoint: the publisher sees "my bitrate went down", each healthy receiver
+ * sees "my video got worse", and nobody can see the causal link except the server.
+ */
+declare class WorstReceiverContagionDetector implements Detector {
+    private readonly _call;
+    readonly name = "worst-receiver-contagion-detector";
+    private readonly _config;
+    private readonly _aggregator;
+    private readonly _windows;
+    private readonly _lastRaisedAt;
+    constructor(_call: ObservedCall, config?: Partial<WorstReceiverContagionDetectorConfig>);
+    update(): void;
+    close(): void;
+    private _windowOf;
+}
+
+declare const TrackDeliveryMismatchTypes: {
+    /**
+     * The source is sending, but **none** of its subscribers are receiving → the media is being lost
+     * between the publisher and the receivers. In an SFU that means the forwarding path.
+     */
+    readonly publishedTrackNotDelivered: "PUBLISHED_TRACK_NOT_DELIVERED";
+    /**
+     * The source is sending and most subscribers are fine, but **some** are dry → those consumers are
+     * broken individually (in mediasoup, the usual mitigation is recreating the consumer).
+     */
+    readonly receiverTrackNotDelivered: "RECEIVER_TRACK_NOT_DELIVERED";
+    /**
+     * The source itself stopped producing, so its subscribers being dry is expected and **not** an
+     * SFU fault. Reported so the other two verdicts can be trusted as *not* being this.
+     */
+    readonly publisherTrackDry: "PUBLISHER_TRACK_DRY";
+};
+type TrackDeliveryMismatchDetectorConfig = {
+    /** The receiver-side issue type meaning "no media arriving". Default `'dry-inbound-track'`. */
+    dryInboundIssueType: string;
+    /** The publisher-side issue type meaning "not producing". Default `'dry-outbound-track'`. */
+    dryOutboundIssueType: string;
+    /** Minimum subscribers before "all of them" means anything. Default `2`. */
+    minReceivers: number;
+    /** Fraction of subscribers that must be dry to call it a whole-track delivery failure. Default `1`. */
+    allReceiversRatio: number;
+    /** Re-arm time (ms) per (track, verdict). Default `60_000`. */
+    cooldownMs: number;
+    registry?: Partial<IssueRegistryConfig>;
+};
+/**
+ * Answers **"is the media actually getting through?"** by joining the two ends of a published track.
+ *
+ * A dry track is the clearest possible symptom — no bytes are arriving — but on its own it is
+ * ambiguous, and the ambiguity is precisely what a single endpoint cannot resolve. A receiver seeing
+ * silence cannot tell whether the camera was switched off, the SFU stopped forwarding, or its own
+ * consumer wedged. All three look identical from the browser.
+ *
+ * With the publisher↔subscriber links this becomes a three-way decision:
+ *
+ * | publisher | subscribers | verdict |
+ * |---|---|---|
+ * | sending | **all** dry | `PUBLISHED_TRACK_NOT_DELIVERED` — the SFU/forwarding path |
+ * | sending | **some** dry | `RECEIVER_TRACK_NOT_DELIVERED` — those consumers (recreate them) |
+ * | dry | any dry | `PUBLISHER_TRACK_DRY` — the source stopped; not an SFU fault |
+ *
+ * The publisher side is judged from **both** signals available: its own `dry-outbound-track` issue
+ * when the client reports one, and — as the fallback, and the corroboration when it does not — the
+ * observed outbound RTP (`deltaPacketsSent`). 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 notably it needs **no** mediasoup instrumentation
+ * — the client's own dry-track verdicts plus the resolver links are sufficient.
+ */
+declare class TrackDeliveryMismatchDetector implements Detector {
+    private readonly _call;
+    readonly name = "track-delivery-mismatch-detector";
+    private readonly _config;
+    private readonly _registry;
+    private readonly _aggregator;
+    private readonly _lastRaisedAt;
+    constructor(_call: ObservedCall, config?: Partial<TrackDeliveryMismatchDetectorConfig>);
+    update(): void;
+    close(): void;
+}
+
+declare const UnconsumedTrackTypes: {
+    /** A track is being published to the SFU that nobody is subscribed to — pure wasted uplink. */
+    readonly unconsumedPublishedTrack: "UNCONSUMED_PUBLISHED_TRACK";
+};
+type UnconsumedTrackDetectorConfig = {
+    /** How long a track must stay unconsumed while sending before reporting (ms). Default `30_000`. */
+    minUnconsumedDurationInMs: number;
+    /** Ignore tracks below this bitrate — a trickle isn't worth an alert (bps). Default `50_000`. */
+    minBitrate: number;
+    /** Re-arm time (ms) per track. Default `300_000`. */
+    cooldownMs: number;
+};
+/**
+ * Finds tracks that are **published but consumed by nobody** — uplink and SFU ingress spent on media
+ * that is never forwarded anywhere.
+ *
+ * This is the one detector that reads the resolver's *silence* as the signal: an outbound track with
+ * an empty `remoteInboundTracks` set, still pushing packets. The usual causes are a participant
+ * publishing while everyone has them hidden or muted-in-UI, a simulcast layer no viewer's bandwidth
+ * ever selects, or an application that forgot to stop a track after the last subscriber left.
+ *
+ * It is deliberately slow to fire: `minUnconsumedDurationInMs` must elapse with the track still
+ * sending, because a brief gap between publishing and the first subscription is completely normal at
+ * join time.
+ *
+ * ### Careful: this detector is only sound with a resolver
+ *
+ * "No subscribers" and "no resolver configured" produce the identical observation — an empty link
+ * set. Without a `RemoteTrackResolver` this would report *every* published track in the call as
+ * unconsumed, so it checks `call.remoteTrackResolver` at runtime and does nothing without one.
+ */
+declare class UnconsumedTrackDetector implements Detector {
+    private readonly _call;
+    readonly name = "unconsumed-track-detector";
+    private readonly _config;
+    /** trackId -> when it was first seen sending with no subscribers. */
+    private readonly _unconsumedSince;
+    private readonly _lastRaisedAt;
+    constructor(_call: ObservedCall, config?: Partial<UnconsumedTrackDetectorConfig>);
+    update(): void;
+    close(): void;
+}
+
 interface Logger {
     trace(...args: any[]): void;
     debug(...args: any[]): void;
@@ -2965,4 +4210,4 @@ declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type CallAppDataFactory, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientIssue, type ClientMetaData, ClientMetaTypes, type ClientSample, ClientSampleSink, type ClientSampleSinkEvents, type ClientSampleSinkFactory, type Detector, Detectors, InMemorySink, JsonlFileSink, type JsonlFileSinkFactoryOptions, type JsonlFileSinkOptions, type Logger, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, ObservedCall, type ObservedCallScope, ObservedCertificate, ObservedClient, type ObservedClientScope, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, Observer, type ObserverEventBase, type ObserverEvents, type ObserverLogger, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolvers, type SampleRejectedReason, type ScoreCalculator, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createJsonlFileSinkFactory, createLogger, createP2pRemoteTrackResolverFactory, setObserverLogger };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, AudioImpairmentFanOutDetector, type AudioImpairmentFanOutDetectorConfig, AudioImpairmentFanOutTypes, type CallAppDataFactory, type CallHealth, CallHealthAggregator, CallWideDegradationDetector, type CallWideDegradationDetectorConfig, CallWideDegradationTypes, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientMetaData, ClientMetaTypes, type ClientSample, ClientSampleSink, type ClientSampleSinkEvents, type ClientSampleSinkFactory, CommonSourceDegradationDetector, type CommonSourceDegradationDetectorConfig, CommonSourceDegradationTypes, ConcurrentIssueDetector, type ConcurrentIssueDetectorConfig, ConcurrentIssueTypes, type Detector, Detectors, IceDisruptionDetector, type IceDisruptionDetectorConfig, IceDisruptionTypes, InMemorySink, type IssueCohort, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, IssueRegistry, type IssueRegistryConfig, JsonlFileSink, type JsonlFileSinkFactoryOptions, type JsonlFileSinkOptions, type Logger, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, ObservedCall, type ObservedCallScope, ObservedCertificate, ObservedClient, type ObservedClientScope, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, type ObservedTrackDistribution, Observer, type ObserverEventBase, type ObserverEvents, type ObserverLogger, PliAndFreezeFanOutDetector, type PliAndFreezeFanOutDetectorConfig, PliAndFreezeFanOutTypes, type PublisherDistributionEntry, RESOLVED_ISSUE_SUFFIX, type ReceiverDistributionEntry, type ReceiverHealthThresholds, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolvers, type ResolvedClientIssue, type SampleRejectedReason, type ScoreCalculator, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrackDistributionAggregator, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, WorstReceiverContagionDetector, type WorstReceiverContagionDetectorConfig, WorstReceiverContagionTypes, baseIssueType, counterDelta, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createJsonlFileSinkFactory, createLogger, createP2pRemoteTrackResolverFactory, defaultClientHealthThresholds, defaultReceiverHealthThresholds, isResolutionEntry, median, parseIssuePayload, percentile, setObserverLogger, summarize };