@observertc/observer-js 1.0.0-beta.16 → 1.0.0-beta.18

package/dist/index.d.ts

@@ -2376,8 +2376,117 @@ type OperationSystem = {
 };
 
 /**
- * A finding raised **by the observer** — `observedCall.addIssue()` / `observer.addIssue()`, surfaced
- * on the bus as `call-issue` / `observer-issue`.
+ * Turning a correlation into a **conclusion**.
+ *
+ * Every detector in this library ultimately reports the same shape of observation: *N clients have
+ * issue X open at once, and here is what they have in common*. That is useful but not yet
+ * actionable — someone still has to know that congestion spread across unrelated calls means the
+ * server, while CPU limitation spread across unrelated calls means a bad client release. This module
+ * holds that interpretation step so it is stated once, consistently, instead of being re-derived by
+ * whoever reads the alert at 3am.
+ *
+ * ### Two functions, because there are two questions
+ *
+ * A detector already knows its scope — it was constructed with an `ObservedCall` or with the
+ * `Observer`. Handing that scope back to a single generic function meant every caller supplied
+ * fields the other scope needed and its own scope ignored: a call-scoped detector passing
+ * `affectedCalls: 1, totalCalls: 1` forever, an observer-scoped one passing a participant ratio that
+ * was deliberately never read. Placeholders like that are a standing invitation to read them as if
+ * they meant something.
+ *
+ * So there are two entry points, each taking only the facts its scope actually has:
+ *
+ * - {@link concludeCallIssue} — within one call. The axis is *how much of the meeting*, and whether
+ *   the affected clients all subscribe to one published track.
+ * - {@link concludeObserverIssue} — across calls. The axis is *how many independent calls*, which is
+ *   the only thing that separates "one bad room" from "our infrastructure".
+ *
+ * Neither the issue family nor the spread concludes anything alone: congestion in one call is a
+ * meeting problem, congestion in six calls is an infrastructure problem, and the issue type is
+ * identical in both.
+ */
+/** Where the fault most likely sits, given who is affected. */
+type IssueFaultDomain = 
+/** Independent calls affected at once — they share only the servers and the network. */
+'infrastructure'
+/** One call, broadly affected — something that call shares (its SFU worker, room, or host). */
+ | 'call'
+/** The subscribers of one published track — the publisher's path or the forwarding of it. */
+ | 'published-track'
+/** A single endpoint — its own device or last mile. */
+ | 'endpoint'
+/** Independent calls affected, but by something endpoints own — a client build, not a server. */
+ | 'client-population'
+/** Not enough signal to attribute. */
+ | 'unknown';
+/** A stated verdict, attached to the raised issue payload. */
+type IssueConclusion = {
+    /** Where to look. */
+    faultDomain: IssueFaultDomain;
+    /** One line, written to be readable in an alert without opening a dashboard. */
+    summary: string;
+    /** What to check first. Omitted when the issue family is unknown to this module. */
+    recommendation?: string;
+    /**
+     * How much the spread alone justifies the verdict, `0..1`. Not a probability — a coarse ranking
+     * so alerting can threshold on it. More independent calls, or a tighter onset, means higher.
+     */
+    confidence: number;
+};
+/** The facts a **call-scoped** conclusion is drawn from. */
+type CallIssueSpread = {
+    issueType: string;
+    /** Distinct clients of this call with the issue open. */
+    affectedClients: number;
+    /** Participants in the call — the denominator. */
+    totalClients: number;
+    /** True when the onsets clustered — a shared trigger rather than drift. */
+    onsetBurst: boolean;
+    /**
+     * Set when the affected clients are the subscriber set of **one published track**.
+     *
+     * The strongest call-scoped statement available: those clients share a publisher and nothing
+     * else, so the receivers are exonerated and the source's path is implicated.
+     */
+    publishedTrackId?: string;
+};
+/** The facts an **observer-scoped** conclusion is drawn from. */
+type ObserverIssueSpread = {
+    issueType: string;
+    /** Distinct clients across the fleet with the issue open. */
+    affectedClients: number;
+    /** Clients in the fleet. Reported for context; it does not gate anything at this scope. */
+    totalClients: number;
+    /** Distinct calls containing at least one affected client. The dimension that matters here. */
+    affectedCalls: number;
+    /** Calls in flight. */
+    totalCalls: number;
+    /** True when the onsets clustered. */
+    onsetBurst: boolean;
+};
+/**
+ * Draw the conclusion for a group of clients **within one call**.
+ *
+ * Ordered most-to-least specific: a track-scoped group is a stronger statement than a call-wide one,
+ * and a single affected endpoint is not a statement about the call at all.
+ */
+declare function concludeCallIssue(spread: CallIssueSpread): IssueConclusion;
+/**
+ * Draw the conclusion for a group of clients spanning **several calls**.
+ *
+ * One affected call is not an observer-scoped finding — it has an obvious local explanation and the
+ * call-scoped detector has already reported it — so that case returns `call` and says so rather than
+ * dressing it up as a fleet event.
+ *
+ * Which domain breadth implicates depends on the family, and this is the whole reason the module
+ * exists: `congestion` across unrelated calls points at the servers, `cpulimitation` across unrelated
+ * calls points at what those *endpoints* share — a client release, a browser version, shared
+ * virtualised hardware — and pointing an SFU team at the second one wastes a night.
+ */
+declare function concludeObserverIssue(spread: ObserverIssueSpread): IssueConclusion;
+
+/**
+ * What every server-raised finding carries, whatever raised it.
  *
  * ### Why this is not `ClientIssue`
  *
@@ -2385,38 +2494,209 @@ type OperationSystem = {
  * string. Server-raised findings were reusing it, which forced every detector to `JSON.stringify` a
  * perfectly good object on the way out and every handler to `JSON.parse` it back on the way in —
  * paying serialisation on a path where nothing is ever serialised, and losing type information in
- * both directions.
- *
- * An observer issue goes straight to an in-process event handler, so it carries the object.
+ * both directions. These go straight to an in-process handler, so they carry the object.
  */
-type ObserverIssue = {
+type IssueBase = {
     /** What was found, e.g. `'CROSS_CALL_ISSUE_ONSET_BURST'`. */
     type: string;
     /** Observer clock, when the finding was raised. */
     timestamp: number;
     /**
-     * The evidence behind the finding.
+     * What the finding *means* — where to look, and how much the evidence justifies it.
      *
-     * Prefer an object — that is the point of this type. `string` is still accepted so an application
-     * can forward a payload it already has serialised (e.g. relaying a `ClientIssue`) without a
-     * pointless parse-then-restringify round trip. Use {@link issuePayloadOf} to read either form.
+     * A first-class field rather than a key inside {@link payload}, because it is the one part every
+     * finding has in common and the one part an alerting rule reads. Burying it in the evidence made
+     * `payload.conclusion.faultDomain` the path to the most important thing in the object.
+     */
+    conclusion?: IssueConclusion;
+    /**
+     * The evidence, and **only** the evidence.
+     *
+     * Deliberately does not repeat `type`, `scope`, or the ids already present on the event that
+     * delivers it. A payload that restates its envelope invites the two to disagree — and they did,
+     * because nothing kept them in step.
+     */
+    payload?: Record<string, unknown>;
+};
+/**
+ * A finding about **one call**, raised by `observedCall.addIssue()` and delivered as `call-issue`.
+ *
+ * The call is the event's scope (`{ observedCall, observer }`), so the payload does not carry a
+ * `callId` — read it from the event.
+ */
+type CallIssue = IssueBase & {
+    scope: 'call';
+};
+/**
+ * A finding about the **fleet**, raised by `observer.addIssue()` and delivered as `observer-issue`.
+ *
+ * Raised by detectors and validators that reason across calls, so no single call owns it. Where the
+ * finding does concern specific calls — a cross-call correlation, say — they are named in the
+ * evidence, because that *is* the evidence.
+ */
+type ObserverIssue = IssueBase & {
+    scope: 'observer';
+};
+/**
+ * Either kind, discriminated by {@link IssueBase} + `scope`.
+ *
+ * `scope` is on the issue and not merely implied by which event fired, so a finding stays
+ * self-describing once it leaves the bus — funnelled into one handler, a log line, or a queue.
+ */
+type Issue = CallIssue | ObserverIssue;
+/**
+ * The payload as a JSON string, for the boundaries that genuinely need text — a log line, an HTTP
+ * body, a message queue.
+ *
+ * Returns `undefined` for a missing payload, or for one that cannot be serialised (a circular
+ * reference from something an application attached): the caller wanted text, not an exception.
+ */
+declare function issuePayloadAsString(issue: Pick<IssueBase, 'payload'>): string | undefined;
+
+/**
+ * The bus events that carry an `observedCall`, i.e. the ones an enricher can attribute to a summary.
+ *
+ * Derived from the event map rather than listed by hand, so it cannot drift: adding a call-scoped
+ * event makes it enrichable automatically, and an enricher on an observer-scoped event
+ * (`observer-issue`, `validation-ready`) will not compile — there is no single call it belongs to,
+ * and quietly writing a fleet-wide fact into every open summary would be worse than a type error.
+ */
+type CallScopedEventName = {
+    [K in keyof ObserverEvents]: ObserverEvents[K][0] extends ObservedCallScope ? K : never;
+}[keyof ObserverEvents];
+/** A function that folds one event into the summary. Runs on every occurrence, for its own call. */
+type CallSummaryEnricher<K extends CallScopedEventName> = (summary: CallSummary, ...args: ObserverEvents[K]) => void;
+/** The enricher map: any subset of the call-scoped events, each fully typed against its payload. */
+type CallSummaryEnrichers = {
+    [K in CallScopedEventName]?: CallSummaryEnricher<K>;
+};
+/** The built-in sections. Ask for what you want; anything absent is simply not collected. */
+type CallSummarySection = 'clients' | 'issues' | 'turnServers' | 'scores';
+type CallSummaryConfig = {
+    /**
+     * Which built-in sections to accumulate. Empty (the default) collects none of them — a summary
+     * with only `enrich` is a perfectly good summary.
      */
-    payload?: string | Record<string, unknown>;
+    include: CallSummarySection[];
+    /** Fold arbitrary state in from any call-scoped event. See {@link CallSummaryEnrichers}. */
+    enrich?: CallSummaryEnrichers;
+    /** Cap on the retained issue log. Default `500`. See the note on truncation. */
+    maxIssues: number;
+    /** Cap on retained client ids. Default `10_000`. */
+    maxClientIds: number;
 };
 /**
- * The payload of an issue as an object, parsing it only if it happens to be a string.
+ * Who was in the call over its whole life — not just who is in it now.
  *
- * Handlers shouldn't have to care which form arrived. Returns `undefined` for a missing payload or a
- * string that isn't valid JSON — reading evidence must never throw inside an issue handler.
+ * Deliberately identifiers and counts only. Anything *about* a client — browser, platform, region —
+ * is already on `observedClient` while the call is live, and belongs in `attachments` via an enricher
+ * if you want it kept. Duplicating it here would mean the library deciding which client attributes
+ * matter, and it would mean reading the highest-frequency event on the bus to do it.
  */
-declare function issuePayloadOf(issue: Pick<ObserverIssue, 'payload'>): Record<string, unknown> | undefined;
+type CallSummaryClients = {
+    /** Every client id seen, in join order, capped by `maxClientIds`. */
+    clientIds: string[];
+    /** The most participants present at any one moment. */
+    peak: number;
+    joined: number;
+    left: number;
+};
+/** Which TURN relays carried this call's media. */
+type CallSummaryTurnServers = {
+    serverUrls: string[];
+    /** Distinct clients seen relaying through any of them. */
+    clientsRelayed: number;
+};
+/** The call score over time. Percentiles, not a mean — see `utils/stats`. */
+type CallSummaryScores = {
+    min?: number;
+    max?: number;
+    median?: number;
+    /** How many score readings went into the above. `0` means nothing was measured. */
+    samples: number;
+};
+/** What had to be dropped to stay within the caps. Absent when nothing was. */
+type CallSummaryTruncation = {
+    issues?: number;
+    clientIds?: number;
+};
 /**
- * The payload as a JSON string, serialising it only if it is an object.
+ * An accumulating record of one call's life, finalised when the call closes.
+ *
+ * ### Why this exists
+ *
+ * Everything else in this library is about *now*. Detectors answer "is something wrong right now",
+ * validators answer a structural question once, and both read state that the call throws away when
+ * it ends. Nothing kept the answer to *"what happened in that meeting?"* — who was in it, what was
+ * raised, how it scored — and that is the question asked after the call, by support, by billing, by
+ * whoever is writing the incident note.
  *
- * For the boundaries that genuinely need text — a log line, an HTTP body, a message queue. Keep it at
- * the edge rather than in the detector, so in-process handlers never pay for it.
+ * ### It is opt-in, and its sections are opt-in
+ *
+ * `observedCall.summary` is `undefined` unless a summary was configured, and each section is present
+ * only if it was requested. **An absent section means "not collected", never "nothing happened"** —
+ * the same rule as `inconclusive` on a validator. Reading `summary.issues` as "this call had no
+ * issues" when `'issues'` was never in `include` is the one misreading this type invites, so it does
+ * not offer a default-empty section to make it easy.
+ *
+ * ### Read it live, receive it once
+ *
+ * The object is live: read `observedCall.summary` at any point during the call. It is also delivered
+ * on the `call-summary` event, emitted inside `close()` while the call is still reachable — after
+ * that the call is gone from `observer.observedCalls` and there is nothing left to ask.
  */
-declare function issuePayloadAsString(issue: Pick<ObserverIssue, 'payload'>): string | undefined;
+type CallSummary = {
+    callId: string;
+    /** First client join (client clock), as `ObservedCall` computed it. */
+    startedAt?: number;
+    /** Last client leave. */
+    endedAt?: number;
+    /** `endedAt - startedAt`, when both are known. */
+    durationInMs?: number;
+    /** When the summary itself was finalised (observer clock). Set by `close()`. */
+    closedAt?: number;
+    clients?: CallSummaryClients;
+    /**
+     * Every issue raised against this call, in the order they were raised, capped by `maxIssues`.
+     *
+     * Just the issues — no derived tallies. A count is `issues.length`, a per-type count is one
+     * `filter`, and either is cheaper to write at the call site than to keep correct here. The one
+     * thing you cannot derive is what the cap discarded, which is why `truncated.issues` exists:
+     * the issues actually raised is `issues.length + (truncated?.issues ?? 0)`.
+     */
+    issues?: CallIssue[];
+    turnServers?: CallSummaryTurnServers;
+    scores?: CallSummaryScores;
+    /**
+     * Whatever your enrichers put here. The library never writes to it, so it cannot collide with a
+     * section added in a future version.
+     *
+     * **`attachments`, not `appData`, and the distinction is load-bearing.** `appData` is the live
+     * working state an application hangs off an entity for the entity's lifetime, and it may hold
+     * references that cannot be serialised — a mediasoup router, an `RTCPeerConnection`, a socket. A
+     * summary is the opposite: it outlives the call precisely so it can be *shipped* — archived,
+     * queued, written to a column — and it is handed to you on `call-summary` at the moment the call
+     * it came from is being torn down. Anything unserialisable in it is a reference to something
+     * already gone.
+     *
+     * So put serialisable facts here, the same contract as `attachments` on a `ClientSample`. If you
+     * need the live object, read it off `observedCall` / `observedClient` inside the enricher and
+     * attach what you can serialise: the router's `id`, not the router.
+     */
+    attachments: Record<string, unknown>;
+    /**
+     * What the caps discarded, and how much.
+     *
+     * Present **only** when something was actually dropped. A silently truncated summary is worse
+     * than no summary — someone will count `log.length` and report it as the issue count — so the
+     * shortfall is stated rather than left to be inferred from a suspiciously round number.
+     */
+    truncated?: CallSummaryTruncation;
+};
+/** The defaults a summary is created with. Caps are generous but finite; see {@link CallSummary}. */
+declare const defaultCallSummaryConfig: CallSummaryConfig;
+/** A fresh summary for `callId`, with only the requested sections present. */
+declare function createCallSummary(callId: string, config: CallSummaryConfig): CallSummary;
 
 /**
  * What a validator concluded, once it is done.
@@ -2964,7 +3244,15 @@ type ObserverEvents = {
     'call-empty': [ObservedCallScope];
     'call-not-empty': [ObservedCallScope];
     'call-issue': [ObservedCallScope & {
-        issue: ObserverIssue;
+        issue: CallIssue;
+    }];
+    /**
+     * A call's summary was finalised. Emitted from inside `close()`, while the call is still in
+     * `observer.observedCalls` — after that there is nothing left to ask. Only fires for calls that
+     * had a summary configured.
+     */
+    'call-summary': [ObservedCallScope & {
+        summary: CallSummary;
     }];
     'client-added': [ObservedClientScope];
     'client-sink-created': [ObservedClientScope & {
@@ -4575,6 +4863,14 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     readonly clientsUsedTurn: Set<string>;
     readonly calculatedScore: CalculatedScore;
     remoteTrackResolver?: 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?: CallSummary;
     /**
      * Published tracks that currently have **no** subscriber linked to them.
      *
@@ -4614,6 +4910,19 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
      * it back off the registry: `call.detectors.getAll(name)`, or `call.detectors.instances`.
      */
     addDetector<K extends keyof AvailableCallScopeDetectorsConfigs>(name: K, config?: Partial<AvailableCallScopeDetectorsConfigs[K]>): 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(): CallSummary | undefined;
     /**
      * Remove a detector from **this call** by name, returning how many were removed.
      *
@@ -4636,14 +4945,15 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     /**
      * 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: ObserverIssue): void;
+    addIssue(issue: Omit<CallIssue, 'scope'>): void;
     close(): void;
     getObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(clientId: string): ObservedClient<ClientAppData> | undefined;
-    createObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>): ObservedClient<ClientAppData> | undefined;
-    getOrCreateObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>): ObservedClient<ClientAppData> | undefined;
+    createObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>, acceptCtx?: AcceptContext): ObservedClient<ClientAppData> | undefined;
+    getOrCreateObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>, acceptCtx?: AcceptContext): ObservedClient<ClientAppData> | undefined;
     update(context?: AcceptContext): void;
     private _onClientUpdate;
     private _clientJoined;
@@ -5040,6 +5350,62 @@ type AvailableValidatorConfigs = {
 /** A validator name that can be started. */
 type ValidatorName = keyof AvailableValidatorConfigs;
 
+/**
+ * Keeps every configured `CallSummary` up to date, from **observer-level** bus subscriptions.
+ *
+ * ### Why one collector and not one per call
+ *
+ * The obvious implementation subscribes each call's summary to the events it needs. But the bus is
+ * observer-wide: a listener attached for call A is invoked for every event of every call, so that
+ * design costs `calls × events` listeners *and* `calls` invocations per event — quadratic in the
+ * thing most likely to be large. At 500 concurrent calls and eight subscribed events that is 4 000
+ * listeners doing 500 no-op calls each, per event.
+ *
+ * So the collector attaches **one listener per event type, once**, and routes each event to the
+ * summary of the call it names. Cost is O(subscribed event types), independent of how many calls are
+ * in flight, and an event for a call with no summary costs one `undefined` check.
+ *
+ * ### Only call-scoped events
+ *
+ * Routing needs `observedCall` on the payload, which is exactly what `CallScopedEventName` selects.
+ * Observer-scoped events have no single call to attribute to; see that type for why fanning them out
+ * to every open summary would be worse than refusing.
+ */
+declare class CallSummaryCollector {
+    private readonly _observer;
+    private readonly _config;
+    private readonly _scratch;
+    private readonly _listeners;
+    private _closed;
+    constructor(_observer: Observer, _config: CallSummaryConfig);
+    /**
+     * 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: string): CallSummary;
+    /**
+     * 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: ObservedCall): void;
+    /** Drop every bus subscription. Called when the observer closes. */
+    close(): void;
+    /**
+     * 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.
+     */
+    private _on;
+    private _subscribeBuiltIns;
+    private _subscribeEnrichers;
+}
+
 type SampleRejectedReason = 'observer-closed' | 'missing-callId' | 'missing-clientId';
 
 /**
@@ -5064,11 +5430,13 @@ type AcceptMiddleware = Middleware<AcceptMiddlewarePayload>;
 type CallAppDataFactory = (params: {
     callId: string;
     observer: Observer;
+    acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
 /** Produces the initial `appData` for a client created without an explicit `appData`. */
 type ClientAppDataFactory = (params: {
     clientId: string;
     observedCall: ObservedCall;
+    acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
 type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unknown>> = {
     appData?: AppData;
@@ -5083,6 +5451,36 @@ type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unk
      * yourself, and note that observer-scoped detectors and validators run *nowhere else*.
      */
     autoUpdateOnCallUpdate?: boolean;
+    /**
+     * Accumulate a {@link CallSummary} on every call this observer creates.
+     *
+     * **Absent or `null` means no summaries at all** — no accumulation, and not one bus subscription.
+     * Pass an object (`{}` is valid) to switch it on; anything you leave out takes its default from
+     * `defaultCallSummaryConfig`, including `include: []`, which collects *no* built-in section. A
+     * summary that only runs `enrich` is a perfectly good summary.
+     *
+     * ```ts
+     * const observer = new Observer({
+     *   callSummary: {
+     *     include: [ 'clients', 'issues' ],
+     *     enrich: {
+     *       'client-joined': (summary, { observedClient }) => {
+     *         ((summary.attachments.regions ??= []) as string[]).push(String(observedClient.appData.region));
+     *       },
+     *     },
+     *   },
+     * });
+     *
+     * observer.on('call-summary', ({ summary }) => archive(summary));
+     * ```
+     *
+     * This is construction-time and fixed for the observer's life, unlike detectors, which are added
+     * per call as an application decides what to watch. A summary is a record of what happened, and a
+     * record you can turn on halfway through is a record with a hole in it — calls that started
+     * earlier would carry different sections from calls that started later, with nothing on either to
+     * say which. One shape for every call, or none.
+     */
+    callSummary?: Partial<CallSummaryConfig> | null;
     inboundTrackDegradationThresholds?: {
         deltaFreezeCount: number;
         framesDroppedRatio: number;
@@ -5177,6 +5575,14 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
      * ```
      */
     readonly callDetectorConfigs: Map<keyof AvailableCallScopeDetectorsConfigs, Partial<UnconsumedTrackDetectorConfig | TrackDeliveryMismatchDetectorConfig | CallConcurrentIssueDetectorConfig | IssueFanOutDetectorConfig | PublisherFaultCorroborationDetectorConfig>>;
+    /**
+     * 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.
+     */
+    readonly callSummaryCollector?: CallSummaryCollector;
     constructor(config?: Partial<ObserverConfig<AppData>>);
     get numberOfCalls(): number;
     get appData(): AppData | undefined;
@@ -5257,8 +5663,13 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
      */
     cancelValidator(target: keyof AvailableValidatorConfigs | RunningValidator, reason?: string): number;
     getObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(callId: string): ObservedCall<T> | undefined;
-    createObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
-    getOrCreateObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
+    /**
+     * @param acceptCtx the `accept()` context, when this call is being created to receive a sample.
+     * Passed on to `ObserverConfig.createCallAppData`, so the factory can read whatever the caller (or
+     * an accept middleware) put there — a tenant, a region, a trace id.
+     */
+    createObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>, acceptCtx?: AcceptContext): ObservedCall<T> | undefined;
+    getOrCreateObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>, acceptCtx?: AcceptContext): ObservedCall<T> | undefined;
     createObservedMediasoupRouter<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedMediasoupRouterSettings<T> & {
         matchPeerConnectionByWebRtcTransportId?: boolean;
     }): ObservedMediasoupRouter<Record<string, unknown>> | undefined;
@@ -5271,7 +5682,7 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
      *
      * `payload` takes an **object**; see `ObserverIssue`.
      */
-    addIssue(issue: ObserverIssue): void;
+    addIssue(issue: Omit<ObserverIssue, 'scope'>): void;
     /** Emit an Observer-bus event. */
     private _notify;
 }
@@ -5386,116 +5797,6 @@ declare class CallHealthAggregator {
     private _clientHealth;
 }
 
-/**
- * Turning a correlation into a **conclusion**.
- *
- * Every detector in this library ultimately reports the same shape of observation: *N clients have
- * issue X open at once, and here is what they have in common*. That is useful but not yet
- * actionable — someone still has to know that congestion spread across unrelated calls means the
- * server, while CPU limitation spread across unrelated calls means a bad client release. This module
- * holds that interpretation step so it is stated once, consistently, instead of being re-derived by
- * whoever reads the alert at 3am.
- *
- * ### Two functions, because there are two questions
- *
- * A detector already knows its scope — it was constructed with an `ObservedCall` or with the
- * `Observer`. Handing that scope back to a single generic function meant every caller supplied
- * fields the other scope needed and its own scope ignored: a call-scoped detector passing
- * `affectedCalls: 1, totalCalls: 1` forever, an observer-scoped one passing a participant ratio that
- * was deliberately never read. Placeholders like that are a standing invitation to read them as if
- * they meant something.
- *
- * So there are two entry points, each taking only the facts its scope actually has:
- *
- * - {@link concludeCallIssue} — within one call. The axis is *how much of the meeting*, and whether
- *   the affected clients all subscribe to one published track.
- * - {@link concludeObserverIssue} — across calls. The axis is *how many independent calls*, which is
- *   the only thing that separates "one bad room" from "our infrastructure".
- *
- * Neither the issue family nor the spread concludes anything alone: congestion in one call is a
- * meeting problem, congestion in six calls is an infrastructure problem, and the issue type is
- * identical in both.
- */
-/** Where the fault most likely sits, given who is affected. */
-type IssueFaultDomain = 
-/** Independent calls affected at once — they share only the servers and the network. */
-'infrastructure'
-/** One call, broadly affected — something that call shares (its SFU worker, room, or host). */
- | 'call'
-/** The subscribers of one published track — the publisher's path or the forwarding of it. */
- | 'published-track'
-/** A single endpoint — its own device or last mile. */
- | 'endpoint'
-/** Independent calls affected, but by something endpoints own — a client build, not a server. */
- | 'client-population'
-/** Not enough signal to attribute. */
- | 'unknown';
-/** A stated verdict, attached to the raised issue payload. */
-type IssueConclusion = {
-    /** Where to look. */
-    faultDomain: IssueFaultDomain;
-    /** One line, written to be readable in an alert without opening a dashboard. */
-    summary: string;
-    /** What to check first. Omitted when the issue family is unknown to this module. */
-    recommendation?: string;
-    /**
-     * How much the spread alone justifies the verdict, `0..1`. Not a probability — a coarse ranking
-     * so alerting can threshold on it. More independent calls, or a tighter onset, means higher.
-     */
-    confidence: number;
-};
-/** The facts a **call-scoped** conclusion is drawn from. */
-type CallIssueSpread = {
-    issueType: string;
-    /** Distinct clients of this call with the issue open. */
-    affectedClients: number;
-    /** Participants in the call — the denominator. */
-    totalClients: number;
-    /** True when the onsets clustered — a shared trigger rather than drift. */
-    onsetBurst: boolean;
-    /**
-     * Set when the affected clients are the subscriber set of **one published track**.
-     *
-     * The strongest call-scoped statement available: those clients share a publisher and nothing
-     * else, so the receivers are exonerated and the source's path is implicated.
-     */
-    publishedTrackId?: string;
-};
-/** The facts an **observer-scoped** conclusion is drawn from. */
-type ObserverIssueSpread = {
-    issueType: string;
-    /** Distinct clients across the fleet with the issue open. */
-    affectedClients: number;
-    /** Clients in the fleet. Reported for context; it does not gate anything at this scope. */
-    totalClients: number;
-    /** Distinct calls containing at least one affected client. The dimension that matters here. */
-    affectedCalls: number;
-    /** Calls in flight. */
-    totalCalls: number;
-    /** True when the onsets clustered. */
-    onsetBurst: boolean;
-};
-/**
- * Draw the conclusion for a group of clients **within one call**.
- *
- * Ordered most-to-least specific: a track-scoped group is a stronger statement than a call-wide one,
- * and a single affected endpoint is not a statement about the call at all.
- */
-declare function concludeCallIssue(spread: CallIssueSpread): IssueConclusion;
-/**
- * Draw the conclusion for a group of clients spanning **several calls**.
- *
- * One affected call is not an observer-scoped finding — it has an obvious local explanation and the
- * call-scoped detector has already reported it — so that case returns `call` and says so rather than
- * dressing it up as a fleet event.
- *
- * Which domain breadth implicates depends on the family, and this is the whole reason the module
- * exists: `congestion` across unrelated calls points at the servers, `cpulimitation` across unrelated
- * calls points at what those *endpoints* share — a client release, a browser version, shared
- * virtualised hardware — and pointing an SFU team at the second one wastes a night.
- */
-declare function concludeObserverIssue(spread: ObserverIssueSpread): IssueConclusion;
-
 /** An entry retained by {@link SlidingWindow}. */
 type SlidingWindowEntry<T> = {
     timestamp: number;
@@ -5742,4 +6043,4 @@ declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssueSpread, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, ClientSampleSink, type ClientSampleSinkEvents, type ClientSampleSinkFactory, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CorroboratedPublisherFault, type Detector, Detectors, InMemorySink, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkFactoryOptions, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, 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, ObservedClientIssueRegistry, 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, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type PageHinkleyResult, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, RESOLVED_ISSUE_SUFFIX, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RunningValidator, type SampleRejectedReason, type ScoreCalculator, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createJsonlFileSinkFactory, createLogger, createP2pRemoteTrackResolverFactory, defaultClientHealthThresholds, isClientIssueResolutionEntry, issuePayloadAsString, issuePayloadOf, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfSorted, robustZScore, setObserverLogger, summarize };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, ClientSampleSink, type ClientSampleSinkEvents, type ClientSampleSinkFactory, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CorroboratedPublisherFault, type Detector, Detectors, InMemorySink, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkFactoryOptions, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, 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, ObservedClientIssueRegistry, 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, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type PageHinkleyResult, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, RESOLVED_ISSUE_SUFFIX, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RunningValidator, type SampleRejectedReason, type ScoreCalculator, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createJsonlFileSinkFactory, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, isClientIssueResolutionEntry, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfSorted, robustZScore, setObserverLogger, summarize };