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

package/README.md

@@ -58,14 +58,15 @@ and emits a single, unified stream of typed events the application can react to.
 8. [API reference](#api-reference)
 9. [Schema types (`ClientSample`)](#schema-types-clientsample)
 10. [Detectors (server-side extension point)](#detectors-server-side-extension-point)
-11. [Remote track resolution (mediasoup / SFU)](#remote-track-resolution-mediasoup--sfu)
-12. [Mediasoup router observation](#mediasoup-router-observation)
-13. [Sinks (per-client sample persistence)](#sinks-per-client-sample-persistence)
-14. [Injecting data into a client](#injecting-data-into-a-client)
-15. [Logging](#logging)
-16. [Design notes](#design-notes)
-17. [Error-handling philosophy](#error-handling-philosophy)
-18. [Development & extension guide](#development--extension-guide)
+11. [Call summaries](#call-summaries)
+12. [Remote track resolution (mediasoup / SFU)](#remote-track-resolution-mediasoup--sfu)
+13. [Mediasoup router observation](#mediasoup-router-observation)
+14. [Sinks (per-client sample persistence)](#sinks-per-client-sample-persistence)
+15. [Injecting data into a client](#injecting-data-into-a-client)
+16. [Logging](#logging)
+17. [Design notes](#design-notes)
+18. [Error-handling philosophy](#error-handling-philosophy)
+19. [Development & extension guide](#development--extension-guide)
 
 ---
 
@@ -391,7 +392,8 @@ See [Mediasoup router observation](#mediasoup-router-observation) for the full d
 | `call-closed` | — | the call closed |
 | `call-empty` | — | last client left the call |
 | `call-not-empty` | — | first client joined a previously-empty call |
-| `call-issue` | `{ issue: ObserverIssue }` | `call.addIssue(...)` (server-side detector finding) |
+| `call-issue` | `{ issue: CallIssue }` | `call.addIssue(...)` (server-side detector finding) |
+| `call-summary` | `{ summary: CallSummary }` | the call is closing and a [summary](#call-summaries) was configured. Emitted **inside** `close()`, while the call is still reachable |
 
 #### Client level — scope `{ observer, observedCall, observedClient }`
 
@@ -463,6 +465,9 @@ type ObserverConfig<AppData = Record<string, unknown>> = {
     appData?: AppData;
     closeClientIfIdleForMs?: number;
     closeCallIfEmptyForMs?: number;
+    // accumulate a per-call summary (see Call summaries). Absent or null = off, and nothing
+    // subscribes to anything. `{}` is valid: a summary with no built-in sections.
+    callSummary?: Partial<CallSummaryConfig> | null;
     // appData factories — run when an entity is created without explicit appData
     // (incl. lazily by accept()). appData is application-owned; accept `context` never touches it.
     createCallAppData?: (p: { callId: string; observer: Observer }) => Record<string, unknown>;
@@ -495,14 +500,24 @@ Key members:
 - `getObservedCall<T>(callId): ObservedCall<T> | undefined`
 - `createObservedCall<T>(settings): ObservedCall<T> | undefined`
 - `getOrCreateObservedCall<T>(settings): ObservedCall<T> | undefined`
+- `addIssue(issue: Omit<ObserverIssue, 'scope'>): void` — raise an **observer-level** finding → emits `observer-issue`. `scope` is stamped for you
 - `update(): void` — force an aggregation/`observer-updated` tick
 - `addObserverDetector(name, config?): this` — build a cross-call detector onto `observer.detectors`
-- `addCallDetector(name, config?): this` / `removeCallDetector(name): this` — register a call-scoped
-  detector for every call created **from now on**
+- `addCallDetector(name, config?): this` — register a call-scoped detector for every call created
+  from now on
+- `removeCallDetector(name, { includeOpenCalls? }): number` — stop building it, and (by default) drop
+  it from calls already open. Returns how many live instances were removed
+- `removeObserverDetector(name): number` — remove an observer-scoped detector. For one specific
+  instance use `observer.detectors.remove(detector)`
 - `addValidator(name, config?): this` — start a one-shot structural check
+- `cancelValidator(name | validator, reason?): number` — stop a running check; it finishes
+  `inconclusive` with the reason and emits `validation-ready`
 - `close(): void`
 - `readonly detectors: Detectors` — observer-scoped registry. **Starts empty**; nothing is implicit
 - `readonly callDetectorConfigs: Map<name, config>` — what `addCallDetector` recorded
+- `readonly callSummaryCollector?: CallSummaryCollector` — owns the resolved `config.callSummary`,
+  the summary subscriptions, and the summaries. `undefined` when summaries are off, which is the
+  only place that answer lives
 - `readonly validators: Set<RunningValidator>` — normally empty; each removes itself on finishing
 - `readonly activeIssuesRegistry: ActiveIssuesRegistry` — the fleet's open client issues
 - `readonly observedCalls: Map<string, ObservedCall>`
@@ -530,8 +545,10 @@ Key members:
 - `readonly callId: string`, `appData: AppData`
 - `readonly observedClients: Map<string, ObservedClient>`, `get numberOfClients()`
 - `getObservedClient<T>(clientId)`, `createObservedClient<T>(settings)`, `getOrCreateObservedClient<T>(settings)` (all `… | undefined`)
-- `addIssue(issue: ObserverIssue): void` — raise a **call-level** issue → emits `call-issue`
+- `addIssue(issue: Omit<CallIssue, 'scope'>): void` — raise a **call-level** finding → emits `call-issue`. `scope` is stamped for you
 - `addDetector(name, config?): this` — build a call-scoped detector onto this call only
+- `removeDetector(name): number` — remove it from this call, `close()`ing it. For one specific
+  instance use `call.detectors.remove(detector)`
 - `readonly detectors: Detectors` — server-side detector registry (empty by default; see [Detectors](#detectors-server-side-extension-point))
 - `readonly activeIssuesRegistry: ActiveIssuesRegistry` — this call's open client issues, propagating into the observer's
 - `readonly unconsumedOutboundTracks: Set<ObservedOutboundTrack>` — maintained by the resolver
@@ -540,6 +557,7 @@ Key members:
 - aggregates: `numberOfIssues`, `numberOfPeerConnections`, `numberOfInboundRtpStreams`,
   `numberOfOutboundRtpStreams`, `numberOfDataChannels`, `maxNumberOfClients`,
   `clientsUsedTurn: Set<string>`, `startedAt?`, `endedAt?`, `closedAt?`, `closed`
+- `summary?: CallSummary` — the live record of this call, when [summaries](#call-summaries) are on
 - `update()`, `close()`
 
 ### `ObservedClient`
@@ -650,7 +668,7 @@ type PeerConnectionSample = {
 };
 
 type ClientEvent     = { type: string; payload?: string; timestamp?: number; /* +ids */ };
-type ClientIssue     = { type: string; payload?: string; timestamp?: number };   // also used for call-issue
+type ClientIssue     = { type: string; payload?: string; timestamp?: number };
 type ClientMetaData  = { type: string; payload?: string; timestamp?: number; /* +ids */ };
 type ExtensionStat   = { type: string; payload?: string };
 ```
@@ -746,14 +764,14 @@ correlate **across** the clients of a call or the calls of a fleet, because that
 server can do better than a browser: per-client signals — packet loss, jitter, RTT, freezes — are
 already detected on the client and arrive on samples as `clientIssues` (surfaced via `client-issue`).
 
-Findings are raised as **`ObserverIssue`** — `{ type, timestamp, payload? }` — and the payload is the
-**object**, not a JSON string. A server-raised finding is delivered to an in-process handler, so
-there is nothing to serialise for:
+Findings are raised as **`CallIssue`** or **`ObserverIssue`** — both share `IssueBase`: `{ type,
+timestamp, conclusion?, payload? }` — and the payload is the **object**, not a JSON string. A
+server-raised finding is delivered to an in-process handler, so there is nothing to serialise for:
 
 ```ts
 observer.on('call-issue', ({ observedCall, issue }) => {
   issue.payload;                  // the object; no JSON.parse
-  issuePayloadOf(issue);          // if you want to accept a string payload too
+  issue.conclusion?.faultDomain;  // a first-class field, not payload.conclusion
   issuePayloadAsString(issue);    // only at an edge that needs text (log, HTTP, queue)
 });
 ```
@@ -771,7 +789,7 @@ class MyCrossClientDetector implements Detector {
   update() {                                   // called on every call.update()
     // …inspect this.call.observedClients across participants…
     if (/* condition only visible server-side */ false) {
-      this.call.addIssue({ type: this.name, payload: JSON.stringify({ /* … */ }), timestamp: Date.now() });
+      this.call.addIssue({ type: this.name, payload: { /* … */ }, timestamp: Date.now() });
       // → emitted on the bus as 'call-issue'
     }
   }
@@ -959,12 +977,63 @@ observer.addObserverDetector('turn-server-outage-detector', { minClientsAtPeak:
 observer.addCallDetector('call-concurrent-issue-detector', {
   issueTypes: [ 'congestion', 'ice-disconnected' ],
 });
-observer.removeCallDetector('unconsumed-track-detector');   // undo, for future calls
-
 // one specific call
 observedCall.addDetector('issue-fan-out-detector', { issueTypes: [ 'freezed-video-track' ] });
 ```
 
+Every `add*` is **chainable** — it returns the owning entity:
+
+```ts
+observer
+  .addObserverDetector('turn-server-health-detector')
+  .addObserverDetector('turn-server-outage-detector', { minClientsAtPeak: 10 })
+  .addValidator('remote-track-resolver');
+```
+
+#### Removing them
+
+By **name**, on the entity — which removes *every* instance under that name:
+
+```ts
+observer.removeObserverDetector('turn-server-outage-detector');   // → 1
+observer.removeCallDetector('call-concurrent-issue-detector');    // stops it everywhere
+observedCall.removeDetector('issue-fan-out-detector');            // this call only
+```
+
+By **instance**, through the registry — which is where instances live, since `add*` returns the
+entity rather than the detector:
+
+```ts
+observer
+  .addObserverDetector('client-population-issue-detector', { issueTypes: [ 'cpulimitation' ], groupBy: 'browser' })
+  .addObserverDetector('client-population-issue-detector', { issueTypes: [ 'cpulimitation' ], groupBy: 'operationSystem' });
+
+const [ byBrowser, byOs ] = observer.detectors.getAll('client-population-issue-detector');
+
+observer.detectors.remove(byOs);   // keeps the browser axis running
+```
+
+`Detectors` is a small collection: `instances` (a copy, in registration order), `listOfNames`,
+`size`, `get(name)`, `getAll(name)`, `has(name)`, `add(detector)`, `remove(detector)`,
+`removeByName(name)`, `clear()`, and it is iterable — `for (const detector of call.detectors)`.
+`instances` being a copy is deliberate: removing while iterating the live array would skip entries,
+and "drop the ones that look like X" is the most natural thing to want to write.
+
+Two things worth knowing:
+
+- **By name removes every instance under it**, not the first. A name can legitimately be registered
+  more than once — `ClientPopulationIssueDetector` is meant to be added once per `groupBy` axis — and
+  "remove whichever is first in the array" is not something a caller can predict from a name. Go via
+  `detectors.getAll(name)` + `detectors.remove(instance)` when you mean one of them.
+- **`removeCallDetector` affects calls already open, by default.** Otherwise whether a detector runs
+  would depend on when a call happened to join, which is not a state anyone can reason about. Pass
+  `{ includeOpenCalls: false }` to change only what future calls are built with.
+
+Every removal path calls the detector's `close()`, so it unsubscribes from the issue registry and
+drops any timers or bus listeners. A detector removed without closing would keep being fed matching
+issues for the life of the call — invisible, unbounded, and it would still look healthy if you
+inspected it.
+
 Detectors are named by their kebab-case `NAME`, and the name types the config — an unknown name or a
 key that belongs to a different detector will not compile. Each detector owns its defaults in its own
 constructor, beside the doc explaining what each threshold means; there is no central table to keep
@@ -1093,6 +1162,23 @@ onDeploy(() => observer.addValidator('simulcast-receivers'));   // check again
 finishing. There is no revalidation timer: a deploy, not elapsed time, is what makes a structural
 verdict stale, so re-checking means starting another.
 
+**Cancelling.** A check that has not decided can be stopped, by name or by instance:
+
+```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');
+```
+
+Cancelling is **not** silent discarding. The validator finishes `inconclusive` with your reason,
+emits `validation-ready` like any other completion, and removes itself. That matters twice over:
+anything waiting on the verdict would otherwise wait forever, and *"we stopped asking"* is a
+materially different outcome from *"we asked and learned nothing"* — which is exactly what an
+`inconclusive` carrying a reason records. Pass a real reason; the default tells the reader nothing
+they could not already infer. `observer.close()` cancels whatever is still running with
+`'observer closed'`.
+
 | Validator | `addValidator` name | Question | Also raises |
 |-----------|---------------------|----------|-------------|
 | `SimulcastReceiverValidator` 🔗 | `simulcast-receivers` | Does the SFU pick layers per receiver, or drag the publisher down to the worst one? | `WORST_RECEIVER_CONTAGION` |
@@ -1141,22 +1227,62 @@ observer.addValidator('remote-track-resolver');
 observer.addValidator('codec-consistency', { expected: { video: 'video/VP9', audio: 'audio/opus' } });
 ```
 
+#### `CallIssue` vs `ObserverIssue`
+
+Server-raised findings come in two kinds, distinguished by the scope that raised them:
+
+| | raised by | delivered as | `scope` |
+|---|---|---|---|
+| `CallIssue` | `observedCall.addIssue(...)` | `call-issue` | `'call'` |
+| `ObserverIssue` | `observer.addIssue(...)` | `observer-issue` | `'observer'` |
+
+Both share `IssueBase` — `type`, `timestamp`, `conclusion?`, `payload?` — and `Issue` is the union,
+discriminated on `scope`.
+
+```ts
+observer.on('call-issue', ({ observedCall, issue }) => {
+  issue.scope;              // 'call'
+  observedCall.callId;      // the call — NOT repeated in the payload
+  issue.conclusion?.faultDomain;
+  issue.payload;            // evidence only
+});
+
+observer.on('observer-issue', ({ issue }) => {
+  issue.scope;              // 'observer'
+});
+```
+
+`scope` is stamped by `addIssue` rather than asked of the detector: it is a fact about *where the
+finding was raised*, which the entity knows and a detector should not have to restate. Having it on
+the issue — not merely implied by which event fired — keeps a finding self-describing once it leaves
+the bus, into a shared handler, a log line or a queue.
+
+**The payload is evidence and nothing else.** It no longer repeats `type`, `scope`, or the `callId`
+already carried by the event, and `conclusion` was lifted out of it to a first-class field. A payload
+that restates its own envelope invites the two to disagree — and they did, because nothing kept them
+in step. `payload` is always an object (the `string` form is gone, along with `issuePayloadOf`); use
+`issuePayloadAsString(issue)` at a boundary that genuinely needs text.
+
 #### Conclusions
 
-Every issue-driven finding carries a `conclusion` in its payload — the interpretation step, so the
-person reading the alert doesn't have to perform it:
+Every issue-driven finding carries a `conclusion` — the interpretation step, so the person reading
+the alert doesn't have to perform it. It sits **beside** the evidence, not inside it:
 
 ```jsonc
 {
   "type": "CROSS_CALL_ISSUE_ONSET_BURST",
-  "issueType": "congestion",
-  "calls": 40, "affectedCalls": 6,
-  "perCall": [ { "callId": "…", "affectedClients": 4, "totalClients": 9 } ],
+  "scope": "observer",
+  "timestamp": 1739812345678,
   "conclusion": {
     "faultDomain": "infrastructure",
     "summary": "network congestion is open across independent calls at the same time — 6 of 40 calls (11/300 clients)",
     "recommendation": "check SFU egress bandwidth and host network saturation before looking at any single participant",
     "confidence": 0.85
+  },
+  "payload": {
+    "issueType": "congestion",
+    "calls": 40, "affectedCalls": 6,
+    "perCall": [ { "callId": "…", "affectedClients": 4, "totalClients": 9 } ]
   }
 }
 ```
@@ -1241,6 +1367,109 @@ rather than trusting the flag alone: **"no subscribers" and "no resolver configu
 identical observation.** Without a resolver it would report every published track in the call as
 unconsumed.
 
+## Call summaries
+
+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 the call throws away when it ends.
+A **call summary** is the one thing that outlives the call: who was in it, what was raised against
+it, how it scored — the questions asked *after* the meeting, by support, by billing, by whoever is
+writing the incident note.
+
+It is configured on the observer, at construction:
+
+```ts
+const observer = new Observer({
+  callSummary: {
+    include: [ 'clients', 'issues', 'turnServers', 'scores' ],
+  },
+});
+
+observer.on('call-summary', ({ summary }) => archive(summary));
+```
+
+Omit `callSummary`, or set it to `null`, and there are no summaries and **not one extra bus
+subscription**. Pass an object — `{}` is valid — and every call this observer creates carries one.
+
+> **Why construction-time, when detectors are added per call?** A summary is a record of what
+> happened, and a record you can switch on halfway through is a record with a hole in it. Calls that
+> started before the switch would carry different sections from calls that started after, with
+> nothing on either to say which. One shape for every call, or none.
+
+### Sections are opt-in, and absence means "not collected"
+
+`include` picks from four built-ins, and **the default is `[]`** — none of them:
+
+| Section | Contains |
+|---------|----------|
+| `clients` | `clientIds` (join order), `peak`, `joined`, `left`. Identifiers and counts only |
+| `issues` | `CallIssue[]`, in the order raised, capped by `maxIssues` |
+| `turnServers` | `serverUrls` that carried media, and `clientsRelayed` |
+| `scores` | `min` / `max` / `median` of the call score, and `samples` |
+
+**A missing section means it was never collected — never "nothing happened".** Reading
+`summary.issues === undefined` as "this call was clean" is the one misreading this type invites, so
+there is no default-empty section to make it easy. This is the same rule as `inconclusive` on a
+validator: silence is not success.
+
+The `clients` section is deliberately identifiers and counts. 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; see below.
+
+### Enrichers: fold in anything, from any call-scoped event
+
+```ts
+new Observer({
+  callSummary: {
+    include: [ 'issues' ],
+    enrich: {
+      'client-joined': (summary, { observedClient }) => {
+        // serialisable facts only — the region string, never the live object it came from
+        ((summary.attachments.regions ??= []) as string[]).push(String(observedClient.appData.region));
+      },
+    },
+  },
+});
+```
+
+Each enricher is typed against its own event's payload. Only **call-scoped** events are accepted —
+the ones carrying an `observedCall`. An enricher on `observer-issue` or `validation-ready` will not
+compile, because there is no single call to attribute a fleet-wide fact to, and quietly writing it
+into every open summary would be worse than a type error.
+
+The library never writes to `summary.attachments`, so nothing you put there can collide with a
+section added in a future version.
+
+> **Why `attachments` and not `appData`.** `appData` is live working state hung off an entity for
+> that entity's lifetime, and it may hold things that cannot be serialised — a mediasoup router, a
+> socket. A summary is the opposite: it outlives the call so it can be **shipped**, and it reaches
+> you on `call-summary` while the call it describes is being torn down, so an unserialisable value
+> in it points at something already gone. Same contract as `attachments` on a `ClientSample`: read
+> the live object off `observedCall` / `observedClient` in the enricher, attach what serialises —
+> the router's `id`, not the router. An enricher that throws is logged and skipped — a summary is a
+side-channel, and nothing about a call should break because a field could not be recorded.
+
+### Caps announce what they dropped
+
+`maxIssues` (default `500`) and `maxClientIds` (default `10_000`) bound the two unbounded lists.
+When either bites, `summary.truncated` appears with the shortfall — present **only** when something
+was actually dropped. That is what makes dropping safe: the true count is recoverable as
+`issues.length + (truncated?.issues ?? 0)`. A silently truncated summary is worse than no summary,
+because someone will count `issues.length` and report it as the issue count.
+
+`issues` is the plain array, with no derived tallies alongside it. A count is `issues.length` and a
+per-type count is one `filter` — both cheaper at the call site than kept correct here.
+
+### Reading it
+
+`observedCall.summary` is live: read it at any point during the call. It is also delivered once on
+`call-summary`, emitted **inside** `close()` while the call is still in `observer.observedCalls` —
+after that the call is gone and there is nothing left to ask. `observer.close()` closes its calls
+first and its collector afterwards, so every summary still makes it out.
+
+Cost is **one bus listener per subscribed event type, for the whole observer** — not one per call. A
+per-call design would be quadratic in concurrent calls: at 500 calls and eight events, 4 000
+listeners each doing 500 no-op invocations per event. Percentiles are computed once, at close.
+
 ## Remote track resolution (mediasoup / SFU)
 
 In an SFU, one participant's **outbound** track is delivered to other participants as **inbound**