Stabilize diagnostics and receiver stats

Author: Akarithos

docs/backend/diagnostics.md

@@ -71,11 +71,13 @@ themselves reflect the different cadences at which conditions are produced.
 
 ## Delivery is a separate channel from status
 
-Diagnostics travel to the browser on their own channel over the same websocket
-hub that carries the rest of the live state, distinct from the channel that
-carries producer status. The store publishes a full snapshot of the current set
-whenever its contents change, and coalesces bursts of changes into a single
+Backend diagnostics travel to the browser on their own channel over the same
+websocket hub that carries the rest of the live state, distinct from the channel
+that carries producer status. The store publishes a full snapshot of the current
+set whenever its contents change, and coalesces bursts of changes into a single
 publish so a flurry of re-emissions does not turn into a flurry of messages.
+The browser can add local diagnostics for conditions only it observes, such as a
+frontend decode failure or a metric that was present and then stops arriving.
 
 An earlier option was to attach diagnostics directly to the status message, so
 that a status update and the conditions explaining it would always arrive
@@ -106,15 +108,19 @@ or an override that disagrees with the detected setup, are raised as soon as
 there is enough information to identify the problem. Producer identification can
 use receiver, aircraft, statistics, or outline files, so a setup with generic
 receiver metadata may stay unknown until another file provides enough evidence.
-An unknown or ambiguous producer is itself a diagnostic condition rather than a
-stream of per-file warnings.
+Ident gives startup a short observation window before warning that the producer
+is unknown, because the first file to arrive is often incomplete evidence. An
+unknown or ambiguous producer is a diagnostic condition rather than a stream of
+per-file warnings.
 
 Because receiver and producer-identification conditions are event-driven and may
-not change for hours, a heartbeat re-raises active startup conditions every few
-minutes so a stable misconfiguration does not quietly expire between file
-changes. The heartbeat is deduplicated through the same condition identity rules
-as every other diagnostic, so refreshing a condition does not create a second
-notification.
+not change for hours, heartbeats re-raise active startup conditions so a stable
+misconfiguration does not quietly expire between file changes.
+Producer-identification conditions use a shorter heartbeat because startup
+classification can resolve quickly once more files arrive; receiver
+configuration conditions use a slower one. Both are deduplicated through the
+same condition identity rules as every other diagnostic, so refreshing a
+condition does not create a second notification.
 
 ## Expiry must not be mistaken for success
 

docs/backend/producer-normalization.md

@@ -73,11 +73,12 @@ flowchart TD
   R -->|several adapters tie| M[ambiguous]
 ```
 
-Unknown and ambiguous states are surfaced as diagnostics, including the
-strongest evidence `identd` has seen so far. That keeps an unsupported or
-unusual stack visible to the operator without guessing a decoder. Once a decoder
-has already been selected, later ambiguous evidence only blocks a switch away
-from that decoder unless the operator overrides it or stronger evidence appears.
+Unknown and ambiguous states are surfaced as diagnostics once startup has had
+time to observe more than the first arriving file, including the strongest
+evidence `identd` has seen so far. That keeps an unsupported or unusual stack
+visible to the operator without guessing a decoder. Once a decoder has already
+been selected, later ambiguous evidence only blocks a switch away from that
+decoder unless the operator overrides it or stronger evidence appears.
 
 A decoder that no adapter recognizes stays unknown. Some decoders write
 aircraft JSON that Ident could in principle read but are simply not recognized
@@ -112,7 +113,8 @@ aircraft JSON that looks close to a supported shape, but publishing it before an
 adapter is selected would let raw decoder semantics leak into Ident's wire
 contract. The HTTP server still starts immediately, so the interface stays
 reachable while classification is waiting for enough evidence, and the
-diagnostic bell explains why live producer data is not flowing yet.
+diagnostic bell explains why live producer data is not flowing if
+classification remains unresolved.
 
 ## Where the decoders actually differ
 

ident/src/data/frontendDiagnostics.test.ts

@@ -1,7 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest";
 import {
   __resetFrontendDiagnosticsForTest,
-  clearFrontendDiagnostic,
   DEFAULT_FRONTEND_DIAGNOSTIC_TTL_MS,
   emitFrontendDiagnostic,
   FRONTEND_DIAGNOSTIC_CAP,
@@ -130,52 +129,6 @@ describe("frontendDiagnostics", () => {
     ).toHaveLength(0);
   });
 
-  it("clear removes an entry by identity", () => {
-    emitFrontendDiagnostic({
-      severity: "warning",
-      channel: "frontend.x",
-      code: "code.a",
-      message: "m",
-    });
-    clearFrontendDiagnostic("frontend.x", "code.a");
-    expect(snapshotFrontendDiagnostics()).toHaveLength(0);
-  });
-
-  it("clear is a no-op when nothing matches the identity", () => {
-    expect(() =>
-      clearFrontendDiagnostic("frontend.nope", "code.absent"),
-    ).not.toThrow();
-    emitFrontendDiagnostic({
-      severity: "warning",
-      channel: "frontend.x",
-      code: "code.a",
-      message: "m",
-    });
-    clearFrontendDiagnostic("frontend.x", "code.a", "wrong-scope");
-    expect(snapshotFrontendDiagnostics()).toHaveLength(1);
-  });
-
-  it("clear respects scope (matches only the identity with that scope)", () => {
-    emitFrontendDiagnostic({
-      severity: "warning",
-      channel: "frontend.x",
-      code: "code.a",
-      scope: "s1",
-      message: "m1",
-    });
-    emitFrontendDiagnostic({
-      severity: "warning",
-      channel: "frontend.x",
-      code: "code.a",
-      scope: "s2",
-      message: "m2",
-    });
-    clearFrontendDiagnostic("frontend.x", "code.a", "s1");
-    const snap = snapshotFrontendDiagnostics();
-    expect(snap).toHaveLength(1);
-    expect(snap[0].scope).toBe("s2");
-  });
-
   it("evicts the oldest entry when exceeding FRONTEND_DIAGNOSTIC_CAP", () => {
     // Emit one over the cap; the very first entry must be gone.
     for (let i = 0; i <= FRONTEND_DIAGNOSTIC_CAP; i++) {

ident/src/data/frontendDiagnostics.ts

@@ -131,21 +131,6 @@ export function emitFrontendDiagnostic(input: FrontendDiagnosticInput): void {
   scheduleExpiry();
 }
 
-export function clearFrontendDiagnostic(
-  channel: string,
-  code: string,
-  scope?: string,
-): void {
-  const key = identityKey(channel, code, scope ?? "");
-  useFrontendDiagnosticsStore.setState((state) => {
-    if (!state.entries.has(key)) return state;
-    const next = new Map(state.entries);
-    next.delete(key);
-    return { entries: next };
-  });
-  scheduleExpiry();
-}
-
 export function snapshotFrontendDiagnostics(
   nowMs: number = Date.now(),
 ): IdentDiagnostic[] {