@observertc/observer-js 1.0.0-beta.15 → 1.0.0-beta.17

package/dist/index.mjs

@@ -37,8 +37,8 @@ function createLogger(moduleName) {
     }
   }();
 }
-function setObserverLogger(logger9) {
-  mainLogger = logger9;
+function setObserverLogger(logger10) {
+  mainLogger = logger10;
 }
 
 // src/ObservedCall.ts
@@ -2632,6 +2632,10 @@ var ObservedClient = class extends EventEmitter2 {
   }
   close() {
     if (this.closed) return;
+    if (this.closeTimer) {
+      clearTimeout(this.closeTimer);
+      this.closeTimer = void 0;
+    }
     this._flushPendingInjections();
     const activeIssues = [...this.activeIssues.values()];
     for (const issue of activeIssues) {
@@ -2794,6 +2798,7 @@ var ObservedClient = class extends EventEmitter2 {
       this.closeTimer = setTimeout(() => {
         this.close();
       }, this.settings.closeClientIfIdleForMs);
+      this.closeTimer.unref?.();
     }
     this._activeSample = void 0;
     try {
@@ -3265,6 +3270,24 @@ var Detectors = class {
   constructor(...detectors) {
     this._detectors = detectors;
   }
+  /**
+   * Every registered detector, in registration order.
+   *
+   * This is **the** way to get hold of an instance: `addDetector` / `addObserverDetector` are
+   * chainable and return the owning entity, so the registry is where instances live. Read it to
+   * inspect a detector's state, or to pick one out and {@link remove} it.
+   *
+   * A copy, not the live array — a caller iterating this while removing would otherwise skip
+   * entries, and that is exactly what "remove the ones that look like X" does.
+   */
+  get instances() {
+    return [...this._detectors];
+  }
+  /** Iterate the registry directly: `for (const detector of call.detectors)`. */
+  [Symbol.iterator]() {
+    return this.instances[Symbol.iterator]();
+  }
+  /** The names in registration order. Duplicates are meaningful — see {@link getAll}. */
   get listOfNames() {
     return this._detectors.map((d) => d.name);
   }
@@ -3274,12 +3297,48 @@ var Detectors = class {
   add(detector) {
     this._detectors.push(detector);
   }
+  /** The first detector registered under `name`. See {@link getAll} when several can share one. */
   get(name) {
     return this._detectors.find((detector) => detector.name === name);
   }
+  /**
+   * Every detector registered under `name`.
+   *
+   * More than one is legitimate: `ClientPopulationIssueDetector` is meant to be added once per
+   * `groupBy` axis, and two instances of it share a name.
+   */
+  getAll(name) {
+    return this._detectors.filter((detector) => detector.name === name);
+  }
+  has(name) {
+    return this._detectors.some((detector) => detector.name === name);
+  }
+  /** Remove one specific instance. Returns `false` if it was not registered here. */
   remove(detector) {
-    this._detectors = this._detectors.filter((d) => d !== detector);
+    const remaining = this._detectors.filter((candidate) => candidate !== detector);
+    if (remaining.length === this._detectors.length) return false;
+    this._detectors = remaining;
     this._close(detector);
+    return true;
+  }
+  /**
+   * Remove **every** detector registered under `name`, returning how many were removed.
+   *
+   * All of them rather than the first, because a name can legitimately be registered more than once
+   * (see {@link getAll}) and "remove the `client-population-issue-detector`" cannot sensibly mean
+   * "remove whichever axis happens to be first in the array". Removing all of them is the only
+   * behaviour that leaves the registry in a state the caller can predict from the name alone.
+   *
+   * Each removed detector gets `close()`, so trackers unsubscribe from the issue registry, bus
+   * listeners drop, and timers clear — a detector removed without closing keeps being fed issues
+   * forever.
+   */
+  removeByName(name) {
+    const removed = this._detectors.filter((detector) => detector.name === name);
+    if (removed.length === 0) return 0;
+    this._detectors = this._detectors.filter((detector) => detector.name !== name);
+    for (const detector of removed) this._close(detector);
+    return removed.length;
   }
   update() {
     for (const detector of this._detectors) {
@@ -3397,7 +3456,6 @@ var UnconsumedTrackDetector = class _UnconsumedTrackDetector {
         type: UnconsumedTrackTypes.unconsumedPublishedTrack,
         timestamp: now,
         payload: {
-          type: UnconsumedTrackTypes.unconsumedPublishedTrack,
           trackId: outboundTrack.id,
           kind: outboundTrack.kind,
           publisherClientId: peerConnection?.client.clientId,
@@ -3543,7 +3601,6 @@ var TrackDeliveryMismatchDetector = class _TrackDeliveryMismatchDetector {
         type,
         timestamp: now,
         payload: {
-          type,
           trackId: outboundTrackId,
           publisherClientId: delivery.publisherClientId,
           publisherSending: delivery.publisherSending,
@@ -3796,12 +3853,9 @@ var CallConcurrentIssueDetector = class _CallConcurrentIssueDetector {
       this._call.addIssue({
         type: issueType,
         timestamp: now,
+        conclusion,
         payload: {
-          type: issueType,
           issueType: type,
-          scope: "call",
-          conclusion,
-          callId: this._call.callId,
           clients: group.totalClients,
           affectedClients: group.clientIds.length,
           affectedRatio: group.affectedRatio,
@@ -3925,10 +3979,9 @@ var IssueFanOutDetector = class _IssueFanOutDetector {
         this._call.addIssue({
           type,
           timestamp: now,
+          conclusion,
           payload: {
-            type,
             issueType,
-            conclusion,
             trackId: publisher.id,
             kind: publisher.kind,
             publisherClientId: publisher.getPeerConnection().client.clientId,
@@ -4075,18 +4128,14 @@ var PublisherFaultCorroborationDetector = class _PublisherFaultCorroborationDete
       this._call.addIssue({
         type: PublisherFaultTypes.corroboratedPublisherFault,
         timestamp: now,
-        payload: {
-          type: PublisherFaultTypes.corroboratedPublisherFault,
-          callId: this._call.callId,
-          ...fault,
-          conclusion: {
-            faultDomain: "published-track",
-            summary: `${fault.publisherClientId} reports ${fault.publisherIssueTypes.join(", ")} on track ${fault.trackId} while ${fault.affectedReceivers} of ${fault.receivers} subscribers report ${fault.receiverIssueTypes.join(", ")} \u2014 both ends agree`,
-            recommendation: "the source is implicated, not inferred: check that publisher's capture, encoder and uplink before looking at the SFU or the receivers",
-            // Higher than any single-ended finding: two independent parties, one conclusion.
-            confidence: 0.9
-          }
-        }
+        conclusion: {
+          faultDomain: "published-track",
+          summary: `${fault.publisherClientId} reports ${fault.publisherIssueTypes.join(", ")} on track ${fault.trackId} while ${fault.affectedReceivers} of ${fault.receivers} subscribers report ${fault.receiverIssueTypes.join(", ")} \u2014 both ends agree`,
+          recommendation: "the source is implicated, not inferred: check that publisher's capture, encoder and uplink before looking at the SFU or the receivers",
+          // Higher than any single-ended finding: two independent parties, one conclusion.
+          confidence: 0.9
+        },
+        payload: { ...fault }
       });
     }
   }
@@ -4142,6 +4191,14 @@ var ObservedCall = class extends EventEmitter3 {
     value: void 0
   };
   remoteTrackResolver;
+  /**
+   * The accumulating record of this call's life, or `undefined` when no summary was configured.
+   *
+   * Live — read it at any point during the call. It is also delivered once on `call-summary` when
+   * the call closes. See `CallSummary`: an absent section means "not collected", never "nothing
+   * happened".
+   */
+  summary;
   /**
    * Published tracks that currently have **no** subscriber linked to them.
    *
@@ -4181,6 +4238,12 @@ var ObservedCall = class extends EventEmitter3 {
   get score() {
     return this.calculatedScore.value;
   }
+  /**
+   * Build a call-scoped detector onto this call. Chainable.
+   *
+   * To get a handle on what was built — to inspect it, or to remove that exact instance later — read
+   * it back off the registry: `call.detectors.getAll(name)`, or `call.detectors.instances`.
+   */
   addDetector(name, config = {}) {
     if (this.closed) return this;
     let detector;
@@ -4213,20 +4276,61 @@ var ObservedCall = class extends EventEmitter3 {
     this.detectors.add(detector);
     return this;
   }
+  /**
+   * Start accumulating this call's summary, if the observer was configured for summaries.
+   *
+   * Called by `createObservedCall`; you should not need it. It takes no configuration of its own on
+   * purpose: the collector subscribes to exactly the events the observer's `include` requires, so a
+   * per-call section outside that set would be created and then never written to — an empty section
+   * that reads as "nothing happened". One shape per observer is the only shape that can be filled.
+   *
+   * The collector builds it rather than this method, so the resolved configuration never has to
+   * leave the one object that owns it. Returns `undefined` when summaries are off, and is
+   * idempotent: an existing summary is kept, not restarted.
+   */
+  enableSummary() {
+    return this.summary ??= this.observer.callSummaryCollector?.createSummary(this.callId);
+  }
+  /**
+   * Remove a detector from **this call** by name, returning how many were removed.
+   *
+   * **Every** instance under the name goes — a name can legitimately be registered more than once.
+   * When you want one of them specifically, go through the registry, which deals in instances:
+   *
+   * ```ts
+   * const [ first ] = call.detectors.getAll('issue-fan-out-detector');
+   *
+   * call.detectors.remove(first);
+   * ```
+   *
+   * Either route `close()`s the detector, so it unsubscribes from `activeIssuesRegistry` — without
+   * that the registry keeps feeding a detector nobody is running any more, and its tracked set grows
+   * for the life of the call.
+   *
+   * To stop building it on *future* calls too, use `observer.removeCallDetector(name)`.
+   */
+  removeDetector(name) {
+    return this.detectors.removeByName(name);
+  }
   /**
    * Raise a call-level (server-side) finding; surfaced on the Observer bus as `call-issue`.
    *
-   * `payload` takes an **object** — it is delivered to in-process handlers, so there is nothing to
-   * serialise for. Pass a string only if you already have one.
+   * `payload` is an **object** and holds evidence only — it is delivered to an in-process handler,
+   * so there is nothing to serialise for. `scope` is stamped here, and the `callId` is already on
+   * the event, so neither belongs in the payload. Put the interpretation in `conclusion`.
    */
   addIssue(issue) {
     if (this.closed) return;
-    this._notify("call-issue", { ...this.eventScope, issue });
+    this._notify("call-issue", { ...this.eventScope, issue: { ...issue, scope: "call" } });
   }
   close() {
     if (this.closed) return;
     this.update();
     this.closed = true;
+    if (this.closeTimer) {
+      clearTimeout(this.closeTimer);
+      this.closeTimer = void 0;
+    }
     let minSampleTimestamps;
     let maxSampleTimestamps;
     const clients = [...this.observedClients.values()];
@@ -4238,6 +4342,10 @@ var ObservedCall = class extends EventEmitter3 {
     if (this.startedAt === void 0) this.startedAt = minSampleTimestamps;
     if (this.endedAt === void 0) this.endedAt = maxSampleTimestamps;
     this.closedAt = Date.now();
+    if (this.summary) {
+      this.observer.callSummaryCollector?.finalise(this);
+      this._notify("call-summary", { ...this.eventScope, summary: this.summary });
+    }
     this.detectors.clear();
     this.activeIssuesRegistry.clear();
     this.emit("close");
@@ -4285,6 +4393,7 @@ var ObservedCall = class extends EventEmitter3 {
           this.closeTimer = setTimeout(() => {
             this.close();
           }, this.settings.closeCallIfEmptyForMs);
+          this.closeTimer.unref?.();
         }
       }
       ++this.totalRemovedClients;
@@ -4997,6 +5106,166 @@ var ActiveIssuesRegistry = class {
   }
 };
 
+// src/summaries/CallSummary.ts
+var defaultCallSummaryConfig = {
+  include: [],
+  maxIssues: 500,
+  maxClientIds: 1e4
+};
+function createCallSummary(callId, config) {
+  const summary = { callId, attachments: {} };
+  if (config.include.includes("clients")) {
+    summary.clients = { clientIds: [], peak: 0, joined: 0, left: 0 };
+  }
+  if (config.include.includes("issues")) {
+    summary.issues = [];
+  }
+  if (config.include.includes("turnServers")) {
+    summary.turnServers = { serverUrls: [], clientsRelayed: 0 };
+  }
+  if (config.include.includes("scores")) {
+    summary.scores = { samples: 0 };
+  }
+  return summary;
+}
+
+// src/summaries/CallSummaryCollector.ts
+var logger8 = createLogger("CallSummaryCollector");
+var CallSummaryCollector = class {
+  constructor(_observer, _config) {
+    this._observer = _observer;
+    this._config = _config;
+    this._subscribeBuiltIns();
+    this._subscribeEnrichers();
+  }
+  _observer;
+  _config;
+  _scratch = /* @__PURE__ */ new WeakMap();
+  _listeners = [];
+  _closed = false;
+  /**
+   * Build a summary for `callId` and start tracking it.
+   *
+   * Creating it here, rather than letting the call create one and hand it over, keeps the resolved
+   * configuration inside the single object that owns it — and makes it impossible to end up with a
+   * summary whose sections nobody subscribed to fill.
+   */
+  createSummary(callId) {
+    const summary = createCallSummary(callId, this._config);
+    this._scratch.set(summary, { scores: [], turnClientIds: /* @__PURE__ */ new Set() });
+    return summary;
+  }
+  /**
+   * Finalise `call`'s summary: fold in what only makes sense once, and stamp the closing times.
+   *
+   * Percentiles are computed here rather than on every update — a median recomputed per tick over a
+   * growing array is quadratic work to produce a number nobody reads until the end.
+   */
+  finalise(call) {
+    const summary = call.summary;
+    if (!summary) return;
+    const scratch = this._scratch.get(summary);
+    summary.startedAt = call.startedAt;
+    summary.endedAt = call.endedAt;
+    summary.durationInMs = summary.startedAt !== void 0 && summary.endedAt !== void 0 ? Math.max(0, summary.endedAt - summary.startedAt) : void 0;
+    summary.closedAt = Date.now();
+    if (summary.scores && scratch) {
+      summary.scores.samples = scratch.scores.length;
+      if (0 < scratch.scores.length) {
+        summary.scores.min = Math.min(...scratch.scores);
+        summary.scores.max = Math.max(...scratch.scores);
+        summary.scores.median = percentile(scratch.scores, 0.5);
+      }
+    }
+    if (summary.turnServers && scratch) {
+      summary.turnServers.clientsRelayed = scratch.turnClientIds.size;
+    }
+  }
+  /** Drop every bus subscription. Called when the observer closes. */
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    for (const { event, listener } of this._listeners) {
+      this._observer.off(event, listener);
+    }
+    this._listeners.length = 0;
+  }
+  /**
+   * Subscribe `listener` to `event`, routed to the summary of the call the event names.
+   *
+   * The `observedCall` is read off the payload rather than closed over, which is what lets one
+   * subscription serve every call.
+   */
+  _on(event, handler) {
+    const listener = (...args) => {
+      const summary = args[0].observedCall.summary;
+      if (!summary) return;
+      const scratch = this._scratch.get(summary);
+      if (!scratch) return;
+      try {
+        handler(summary, scratch, ...args);
+      } catch (err) {
+        logger8.warn("A call-summary handler for %s threw; continuing. %o", event, err);
+      }
+    };
+    this._observer.on(event, listener);
+    this._listeners.push({ event, listener });
+  }
+  _subscribeBuiltIns() {
+    const include = this._config.include;
+    if (include.includes("clients")) {
+      this._on("client-added", (summary, _scratch, { observedCall, observedClient }) => {
+        const clients = summary.clients;
+        if (!clients) return;
+        clients.joined += 1;
+        clients.peak = Math.max(clients.peak, observedCall.observedClients.size);
+        if (clients.clientIds.length < this._config.maxClientIds) {
+          clients.clientIds.push(observedClient.clientId);
+        } else {
+          summary.truncated = { ...summary.truncated, clientIds: (summary.truncated?.clientIds ?? 0) + 1 };
+        }
+      });
+      this._on("client-closed", (summary) => {
+        if (summary.clients) summary.clients.left += 1;
+      });
+    }
+    if (include.includes("issues")) {
+      this._on("call-issue", (summary, _scratch, { issue }) => {
+        const issues = summary.issues;
+        if (!issues) return;
+        if (issues.length < this._config.maxIssues) issues.push(issue);
+        else summary.truncated = { ...summary.truncated, issues: (summary.truncated?.issues ?? 0) + 1 };
+      });
+    }
+    if (include.includes("scores") || include.includes("turnServers")) {
+      this._on("call-updated", (summary, scratch, { observedCall }) => {
+        if (summary.scores && observedCall.score !== void 0) scratch.scores.push(observedCall.score);
+        if (!summary.turnServers) return;
+        for (const clientId of observedCall.clientsUsedTurn) scratch.turnClientIds.add(clientId);
+        for (const client of observedCall.observedClients.values()) {
+          for (const peerConnection of client.observedPeerConnections.values()) {
+            for (const pair of peerConnection.selectedIceCandiadtePairForTurn) {
+              const url = pair.getLocalCandidate()?.url;
+              if (url && !summary.turnServers.serverUrls.includes(url)) {
+                summary.turnServers.serverUrls.push(url);
+              }
+            }
+          }
+        }
+      });
+    }
+  }
+  _subscribeEnrichers() {
+    const enrich = this._config.enrich;
+    if (!enrich) return;
+    for (const name of Object.keys(enrich)) {
+      const enricher = enrich[name];
+      if (!enricher) continue;
+      this._on(name, (summary, _scratch, ...args) => enricher(summary, ...args));
+    }
+  }
+};
+
 // src/detectors/SfuCongestionDetector.ts
 var SfuCongestionDetector = class _SfuCongestionDetector {
   constructor(_observer, config = {}) {
@@ -5125,13 +5394,10 @@ var SfuCongestionDetector = class _SfuCongestionDetector {
       absoluteIncrease: evaluation.absoluteIncrease,
       relativeIncrease: evaluation.relativeIncrease
     };
-    this._observer.emit("observer-issue", {
-      issue: {
-        type: this._config.emittedObserverIssueType,
-        timestamp: Date.now(),
-        payload
-      },
-      observer: this._observer
+    this._observer.addIssue({
+      type: this._config.emittedObserverIssueType,
+      timestamp: Date.now(),
+      payload: { ...payload }
     });
   }
   /**
@@ -5245,11 +5511,9 @@ var ObserverConcurrentIssueDetector = class _ObserverConcurrentIssueDetector {
       this._observer.addIssue({
         type: issueType,
         timestamp: now,
+        conclusion,
         payload: {
-          type: issueType,
           issueType: type,
-          scope: "observer",
-          conclusion,
           clients: group.totalClients,
           affectedClients: group.clientIds.length,
           affectedRatio: group.affectedRatio,
@@ -5422,16 +5686,13 @@ var ClientPopulationIssueDetector = class _ClientPopulationIssueDetector {
         this._observer.addIssue({
           type: ClientPopulationIssueTypes.clientPopulationIssue,
           timestamp: now,
-          payload: {
-            type: ClientPopulationIssueTypes.clientPopulationIssue,
-            ...rollup,
-            conclusion: {
-              faultDomain: "client-population",
-              summary: `'${issueType}' is ${this._riskText(rollup.relativeRisk)} more likely on ${population} than on the rest of the fleet (${rollup.affectedClients}/${rollup.clients} vs ${rollup.controlAffectedClients}/${rollup.controlClients})`,
-              recommendation: "this is not an SFU symptom \u2014 look at what those clients share: a recent release, a browser version, or shared/virtualised hardware",
-              confidence: this._confidenceOf(rollup)
-            }
-          }
+          conclusion: {
+            faultDomain: "client-population",
+            summary: `'${issueType}' is ${this._riskText(rollup.relativeRisk)} more likely on ${population} than on the rest of the fleet (${rollup.affectedClients}/${rollup.clients} vs ${rollup.controlAffectedClients}/${rollup.controlClients})`,
+            recommendation: "this is not an SFU symptom \u2014 look at what those clients share: a recent release, a browser version, or shared/virtualised hardware",
+            confidence: this._confidenceOf(rollup)
+          },
+          payload: { ...rollup }
         });
       }
     }
@@ -5533,7 +5794,7 @@ var TurnServerHealthDetector = class _TurnServerHealthDetector {
       this._observer.addIssue({
         type: TurnServerHealthTypes.turnServerDegraded,
         timestamp: now,
-        payload: { type: TurnServerHealthTypes.turnServerDegraded, ...health, otherServers }
+        payload: { ...health, otherServers }
       });
     }
     for (const serverUrl of [...this._streaks.keys()]) {
@@ -5641,7 +5902,6 @@ var TurnServerOutageDetector = class _TurnServerOutageDetector {
         type: TurnServerOutageTypes.turnServerOutage,
         timestamp: now,
         payload: {
-          type: TurnServerOutageTypes.turnServerOutage,
           serverUrl,
           peakClients: peak,
           currentClients: live,
@@ -5915,17 +6175,13 @@ var SimulcastReceiverValidator = class _SimulcastReceiverValidator {
       this._observer.addIssue({
         type: LOWEST_COMMON_DENOMINATOR_ISSUE,
         timestamp: decidedAt,
-        payload: {
-          type: LOWEST_COMMON_DENOMINATOR_ISSUE,
-          checks: this._checks,
-          ...outcome.evidence,
-          conclusion: {
-            faultDomain: "infrastructure",
-            summary: "one bad receiver is dragging a publisher's bitrate down for everyone \u2014 the SFU is not selecting layers per consumer",
-            recommendation: "check that simulcast/SVC is enabled and layers are chosen per consumer, and that the SFU terminates receiver reports instead of forwarding them; this is a build/config property, not a transient",
-            confidence: 0.8
-          }
-        }
+        conclusion: {
+          faultDomain: "infrastructure",
+          summary: "one bad receiver is dragging a publisher's bitrate down for everyone \u2014 the SFU is not selecting layers per consumer",
+          recommendation: "check that simulcast/SVC is enabled and layers are chosen per consumer, and that the SFU terminates receiver reports instead of forwarding them; this is a build/config property, not a transient",
+          confidence: 0.8
+        },
+        payload: { checks: this._checks, ...outcome.evidence }
       });
     }
     this.onDone(this.report);
@@ -6028,17 +6284,13 @@ var RemoteTrackResolverValidator = class _RemoteTrackResolverValidator {
       this._observer.addIssue({
         type: UNRESOLVED_TRACK_LINKS_ISSUE,
         timestamp: decidedAt,
-        payload: {
-          type: UNRESOLVED_TRACK_LINKS_ISSUE,
-          checks: this._checks,
-          ...outcome.evidence,
-          conclusion: {
-            faultDomain: "infrastructure",
-            summary: "a RemoteTrackResolver is configured but has never linked a subscriber to a publisher",
-            recommendation: "check the id the resolver joins on (mediasoup producerId, or your own convention) \u2014 until it links, IssueFanOutDetector, TrackDeliveryMismatchDetector, UnconsumedTrackDetector and SimulcastReceiverValidator all silently do nothing",
-            confidence: 0.9
-          }
-        }
+        conclusion: {
+          faultDomain: "infrastructure",
+          summary: "a RemoteTrackResolver is configured but has never linked a subscriber to a publisher",
+          recommendation: "check the id the resolver joins on (mediasoup producerId, or your own convention) \u2014 until it links, IssueFanOutDetector, TrackDeliveryMismatchDetector, UnconsumedTrackDetector and SimulcastReceiverValidator all silently do nothing",
+          confidence: 0.9
+        },
+        payload: { checks: this._checks, ...outcome.evidence }
       });
     }
     this.onDone(this.report);
@@ -6149,17 +6401,16 @@ var CodecConsistencyValidator = class _CodecConsistencyValidator {
       this._observer.addIssue({
         type: CODEC_MISMATCH_ISSUE,
         timestamp: decidedAt,
+        conclusion: {
+          faultDomain: "infrastructure",
+          summary: outcome.verdict === "codec-split" ? "participants of one call are using different codecs \u2014 an SFU that forwards without transcoding cannot serve all of them" : "the deployment is consistently negotiating a codec other than the expected one",
+          recommendation: outcome.verdict === "codec-split" ? "check codec preferences and any SDP munging; a split usually means one endpoint could not negotiate the preferred codec and the others were not renegotiated with it" : "check codec preferences and endpoint support \u2014 a silent fallback keeps working, at a higher bitrate than you budgeted for",
+          confidence: 0.85
+        },
         payload: {
-          type: CODEC_MISMATCH_ISSUE,
           verdict: outcome.verdict,
           checks: this._checks,
-          evidence: outcome.evidence,
-          conclusion: {
-            faultDomain: "infrastructure",
-            summary: outcome.verdict === "codec-split" ? "participants of one call are using different codecs \u2014 an SFU that forwards without transcoding cannot serve all of them" : "the deployment is consistently negotiating a codec other than the expected one",
-            recommendation: outcome.verdict === "codec-split" ? "check codec preferences and any SDP munging; a split usually means one endpoint could not negotiate the preferred codec and the others were not renegotiated with it" : "check codec preferences and endpoint support \u2014 a silent fallback keeps working, at a higher bitrate than you budgeted for",
-            confidence: 0.85
-          }
+          evidence: outcome.evidence
         }
       });
     }
@@ -6173,7 +6424,7 @@ function mediaKindOf(mimeType) {
 }
 
 // src/Observer.ts
-var logger8 = createLogger("Observer");
+var logger9 = createLogger("Observer");
 var Observer = class extends EventEmitter6 {
   observedTURN = new ObservedTURN();
   observedCalls = /* @__PURE__ */ new Map();
@@ -6229,6 +6480,14 @@ var Observer = class extends EventEmitter6 {
    * ```
    */
   callDetectorConfigs = /* @__PURE__ */ new Map();
+  /**
+   * Owns every call's summary: the resolved `config.callSummary`, the bus subscriptions that keep
+   * the summaries current (one per event type, not one per call), and the summaries themselves.
+   *
+   * `undefined` when `config.callSummary` was absent or `null` — so its presence *is* the answer to
+   * "are summaries on", and nothing is subscribed to anything.
+   */
+  callSummaryCollector;
   constructor(config = {}) {
     super();
     this.setMaxListeners(Infinity);
@@ -6240,6 +6499,12 @@ var Observer = class extends EventEmitter6 {
       closeClientIfIdleForMs: 6e4,
       ...config
     };
+    if (this.config.callSummary) {
+      this.callSummaryCollector = new CallSummaryCollector(this, {
+        ...defaultCallSummaryConfig,
+        ...this.config.callSummary
+      });
+    }
   }
   get numberOfCalls() {
     return this.observedCalls.size;
@@ -6247,6 +6512,12 @@ var Observer = class extends EventEmitter6 {
   get appData() {
     return this.config.appData;
   }
+  /**
+   * Build a cross-call detector onto `observer.detectors`. Chainable.
+   *
+   * To get a handle on what was built — to inspect it, or to remove that exact instance later — read
+   * it back off the registry: `observer.detectors.getAll(name)`, or `observer.detectors.instances`.
+   */
   addObserverDetector(name, config = {}) {
     if (this.closed) return this;
     let detector;
@@ -6272,7 +6543,7 @@ var Observer = class extends EventEmitter6 {
         break;
       }
       default: {
-        logger8.warn("Unknown detector name %s; skipping", name);
+        logger9.warn("Unknown detector name %s; skipping", name);
         return this;
       }
     }
@@ -6290,10 +6561,41 @@ var Observer = class extends EventEmitter6 {
     this.callDetectorConfigs.set(name, config);
     return this;
   }
-  /** Stop building `name` on calls created from now on. Calls already open are untouched. */
-  removeCallDetector(name) {
+  /**
+   * Remove an observer-scoped detector by name, returning how many were removed.
+   *
+   * **Every** instance registered under the name goes, since a name can legitimately be registered
+   * more than once (`ClientPopulationIssueDetector` is meant to be added once per `groupBy` axis).
+   * When you want one of them specifically, go through the registry, which deals in instances:
+   *
+   * ```ts
+   * const [ byBrowser, byOs ] = observer.detectors.getAll('client-population-issue-detector');
+   *
+   * observer.detectors.remove(byOs);   // keeps the browser axis running
+   * ```
+   *
+   * Either route `close()`s the detector, so it unsubscribes from the issue registry and drops any
+   * timers or bus listeners it held.
+   */
+  removeObserverDetector(name) {
+    return this.detectors.removeByName(name);
+  }
+  /**
+   * Stop building `name` on calls created from now on.
+   *
+   * By default this also removes it from the calls **already open**, so that "remove this detector"
+   * means the same thing whether you say it before or after a call started — the alternative leaves
+   * a fleet where the detector is live on some calls and not others, decided by join time. Pass
+   * `{ includeOpenCalls: false }` to change only what future calls are built with.
+   *
+   * Returns the number of live detector instances removed (`0` when only the config changed).
+   */
+  removeCallDetector(name, { includeOpenCalls = true } = {}) {
     this.callDetectorConfigs.delete(name);
-    return this;
+    if (!includeOpenCalls) return 0;
+    let removed = 0;
+    for (const call of this.observedCalls.values()) removed += call.removeDetector(name);
+    return removed;
   }
   /**
    * Start a structural check. It runs on each `observer.update()` until it can decide, reports once
@@ -6326,23 +6628,53 @@ var Observer = class extends EventEmitter6 {
         break;
     }
     if (!validator) {
-      logger8.warn("Unknown validator name %s; skipping", name);
+      logger9.warn("Unknown validator name %s; skipping", name);
       return this;
     }
     this.validators.add(validator);
     return this;
   }
+  /**
+   * Stop a running validation, by name or by instance. Returns how many were cancelled.
+   *
+   * Cancelling is **not** silent discarding. The validator finishes with `inconclusive` and the given
+   * `reason`, emits `validation-ready` like any other completion, and removes itself. That matters
+   * because anything waiting on the verdict — a deploy gate, a dashboard, a promise — would otherwise
+   * wait forever, and because "we stopped asking" is a materially different outcome from "we asked
+   * and learned nothing", which is exactly what `inconclusive` with a reason records.
+   *
+   * ```ts
+   * observer.cancelValidator('simulcast-receivers', 'sfu redeployed');
+   *
+   * // or one specific instance — `observer.validators` holds what is running
+   * for (const validator of observer.validators) observer.cancelValidator(validator, 'shutting down');
+   * ```
+   *
+   * Pass a real reason. The default tells the reader nothing they could not already infer.
+   */
+  cancelValidator(target, reason = "cancelled") {
+    const running = [...this.validators];
+    const matching = typeof target === "string" ? running.filter((validator) => validator.name === target) : running.filter((validator) => validator === target);
+    for (const validator of matching) {
+      try {
+        validator.cancel(reason);
+      } catch (err) {
+        logger9.warn("Error cancelling validator %s: %o", validator.name, err);
+      }
+    }
+    return matching.length;
+  }
   getObservedCall(callId) {
     if (this.closed || !this.observedCalls.has(callId)) return;
     return this.observedCalls.get(callId);
   }
   createObservedCall(settings) {
     if (this.closed) {
-      logger8.warn("Attempted to create a call (callId: %s) on a closed observer", settings.callId);
+      logger9.warn("Attempted to create a call (callId: %s) on a closed observer", settings.callId);
       return void 0;
     }
     if (this.observedCalls.has(settings.callId)) {
-      logger8.warn("Observed Call with id %s already exists; returning the existing instance", settings.callId);
+      logger9.warn("Observed Call with id %s already exists; returning the existing instance", settings.callId);
       return this.observedCalls.get(settings.callId);
     }
     const callSettings = {
@@ -6357,6 +6689,7 @@ var Observer = class extends EventEmitter6 {
       callActiveIssuesRegistry
     );
     observedCall.remoteTrackResolver = this.config.createRemoteTrackResolver?.(observedCall);
+    observedCall.enableSummary();
     for (const [name, detectorConfig] of this.callDetectorConfigs) {
       observedCall.addDetector(name, detectorConfig);
     }
@@ -6379,11 +6712,11 @@ var Observer = class extends EventEmitter6 {
   }
   createObservedMediasoupRouter(settings) {
     if (this.closed) {
-      logger8.warn("Attempted to create mediasoup router (id: %d) on a closed observer", settings.router.id);
+      logger9.warn("Attempted to create mediasoup router (id: %d) on a closed observer", settings.router.id);
       return void 0;
     }
     if (this.observedMediasoupRouters.has(settings.router.id)) {
-      logger8.warn("Observed Mediasoup Router (id %s) already exists; returning the existing instance", settings.router.id);
+      logger9.warn("Observed Mediasoup Router (id %s) already exists; returning the existing instance", settings.router.id);
       return this.observedMediasoupRouters.get(settings.router.id);
     }
     const observedMediasoupRouter = new ObservedMediasoupRouter(settings);
@@ -6414,13 +6747,14 @@ var Observer = class extends EventEmitter6 {
   }
   close() {
     if (this.closed) {
-      return logger8.debug("Attempted to close twice");
+      return logger9.debug("Attempted to close twice");
     }
     this.closed = true;
     for (const call of [...this.observedCalls.values()]) call.close();
     this.detectors.clear();
-    for (const validator of [...this.validators]) validator.cancel();
+    for (const validator of [...this.validators]) validator.cancel("observer closed");
     this.validators.clear();
+    this.callSummaryCollector?.close();
     this.activeIssuesRegistry.clear();
     this._notify("observer-closed", { ...this.eventScope });
   }
@@ -6431,7 +6765,7 @@ var Observer = class extends EventEmitter6 {
     try {
       this.acceptMiddlewares.process({ sample, context });
     } catch (err) {
-      logger8.warn("An accept middleware threw; dropping the sample. %o", err);
+      logger9.warn("An accept middleware threw; dropping the sample. %o", err);
     }
     if (!sample.callId) {
       this._notify("sample-rejected", { ...this.eventScope, reason: "missing-callId", sample });
@@ -6483,7 +6817,7 @@ var Observer = class extends EventEmitter6 {
       try {
         validator.update();
       } catch (err) {
-        logger8.warn("Error running validator %s: %o", validator.name, err);
+        logger9.warn("Error running validator %s: %o", validator.name, err);
       }
     }
     this._notify("observer-updated", { ...this.eventScope });
@@ -6496,7 +6830,7 @@ var Observer = class extends EventEmitter6 {
    */
   addIssue(issue) {
     if (this.closed) return;
-    this._notify("observer-issue", { ...this.eventScope, issue });
+    this._notify("observer-issue", { ...this.eventScope, issue: { ...issue, scope: "observer" } });
   }
   /** Emit an Observer-bus event. */
   _notify(type, ...args) {
@@ -6614,18 +6948,11 @@ var CallHealthAggregator = class {
   }
 };
 
-// src/common/ObserverIssue.ts
-function issuePayloadOf(issue) {
-  const payload = issue.payload;
-  if (payload === void 0) return void 0;
-  return typeof payload === "string" ? parseJsonObject(payload) : payload;
-}
+// src/common/Issue.ts
 function issuePayloadAsString(issue) {
-  const payload = issue.payload;
-  if (payload === void 0) return void 0;
-  if (typeof payload === "string") return payload;
+  if (issue.payload === void 0) return void 0;
   try {
-    return JSON.stringify(payload);
+    return JSON.stringify(issue.payload);
   } catch {
     return void 0;
   }
@@ -6919,6 +7246,7 @@ export {
   CallConcurrentIssueDetector,
   CallConcurrentIssueTypes,
   CallHealthAggregator,
+  CallSummaryCollector,
   ClientEventTypes,
   ClientMetaTypes,
   ClientPopulationIssueDetector,
@@ -6977,16 +7305,17 @@ export {
   concludeObserverIssue,
   correlation,
   counterDelta,
+  createCallSummary,
   createDefaultMediasoupRemoteTrackResolverFactory,
   createInMemorySink,
   createJsonlFileSink,
   createJsonlFileSinkFactory,
   createLogger,
   createP2pRemoteTrackResolverFactory,
+  defaultCallSummaryConfig,
   defaultClientHealthThresholds,
   isClientIssueResolutionEntry,
   issuePayloadAsString,
-  issuePayloadOf,
   mannKendall,
   mannKendallVerdict,
   median,