feat: add diagnostics and telemetry runtime

tests/unit/application-boundary.test.ts

@@ -36,6 +36,7 @@ describe("application input/output boundary", () => {
   it("uses fake output ports for preference, session, and safe diagnostics flows", () => {
     const write = vi.fn(() => ({ ok: true as const }));
     const emit = vi.fn();
+    const record = vi.fn();
     const ports = {
       session: {
         getState: () => "authenticated" as const,
@@ -49,7 +50,8 @@ describe("application input/output boundary", () => {
         write,
         remove: () => ({ ok: true as const }),
       },
-      diagnostics: { emit },
+      diagnostics: { record },
+      telemetry: { emit },
       releaseInfo: {
         getCurrent: async () => ({
           buildId: "build-a",
@@ -82,20 +84,43 @@ describe("application input/output boundary", () => {
       buildId: "build-a",
       boundaryName: "route",
     });
+    expect(record).toHaveBeenCalledWith({
+      level: "error",
+      eventId: "ui.render.failed",
+      context: {
+        route_id: "APP_HOME",
+        build_id: "build-a",
+        component_boundary: "route",
+      },
+    });
     expect(emit).toHaveBeenCalledWith("ui.render.failed", {
       route_id: "APP_HOME",
       build_id: "build-a",
       component_boundary: "route",
     });
+    application.diagnostics.reportRouteChanged({
+      routeId: "APP_HOME",
+      buildId: "build-a",
+    });
+    expect(record).toHaveBeenCalledWith({
+      level: "info",
+      eventId: "route.changed",
+      context: { route_id: "APP_HOME", build_id: "build-a" },
+    });
   });
 
   it("does not let a failing diagnostics output escape into presentation", () => {
     const application = createTestApplication({
       diagnostics: {
-        emit() {
+        record() {
           throw new Error("sink details");
         },
       },
+      telemetry: {
+        emit() {
+          throw new Error("telemetry details");
+        },
+      },
     });
 
     expect(() =>

tests/unit/chunk-recovery-runtime.test.ts

@@ -3,6 +3,8 @@ import { describe, expect, it, vi } from "vitest";
 import { createApplication } from "../../src/application/create-application.js";
 import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
 import type { StoragePort } from "../../src/application/ports/storage-port.js";
+import type { DiagnosticsPort } from "../../src/application/ports/diagnostics-port.js";
+import type { TelemetryPort } from "../../src/application/ports/telemetry-port.js";
 
 type ReleaseFixture = {
   buildId: string;
@@ -40,12 +42,15 @@ function applicationWith(options: {
   storage?: StoragePort;
   refresh?: () => Promise<ReturnType<typeof release>>;
   reload?: () => void;
+  diagnostics?: DiagnosticsPort;
+  telemetry?: TelemetryPort;
 }) {
   const current = release("build-a", "release-a");
   return createApplication({
     session: createAnonymousSessionAdapter(),
     preferences: options.storage ?? memoryStorage(),
-    diagnostics: { emit: () => {} },
+    diagnostics: options.diagnostics ?? { record: () => {} },
+    telemetry: options.telemetry ?? { emit: () => {} },
     releaseInfo: {
       getCurrent: async () => current,
       refresh:
@@ -59,7 +64,13 @@ function applicationWith(options: {
 describe("production chunk recovery application input", () => {
   it("reloads exactly once for one active build/release pair", async () => {
     const reload = vi.fn();
-    const application = applicationWith({ reload });
+    const record = vi.fn<DiagnosticsPort["record"]>();
+    const emit = vi.fn<TelemetryPort["emit"]>();
+    const application = applicationWith({
+      reload,
+      diagnostics: { record },
+      telemetry: { emit },
+    });
     const input = {
       chunkId: "route-home",
       failureKind: "CHUNK_LOAD_FAILURE" as const,
@@ -69,6 +80,20 @@ describe("production chunk recovery application input", () => {
       action: "reload-once",
       releasePair: "build-a/release-a->build-b/release-b",
     });
+    expect(record).toHaveBeenCalledWith({
+      level: "warn",
+      eventId: "release.mismatch.detected",
+      context: {
+        build_id: "build-a",
+        active_release_id: "release-b",
+        mismatch_kind: "BUILD_MISMATCH",
+      },
+    });
+    expect(emit).toHaveBeenCalledWith("release.mismatch.detected", {
+      build_id: "build-a",
+      active_release_id: "release-b",
+      mismatch_kind: "BUILD_MISMATCH",
+    });
     await expect(application.recovery.recoverChunk(input)).resolves.toEqual({
       action: "support",
       reason: "reload-already-attempted",

tests/unit/diagnostics.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createDiagnosticsAdapter,
+  getLastBootEvidence,
+  noOpDiagnostics,
+  recordBootFailure,
+} from "../../src/adapters/diagnostics/bounded-diagnostics.js";
+import {
+  projectDiagnosticRecord,
+  safeErrorKind,
+} from "../../src/contracts/diagnostics.js";
+
+describe("structured diagnostics contract", () => {
+  it("projects only registered, bounded context with deterministic time", () => {
+    const projected = projectDiagnosticRecord(
+      {
+        level: "info",
+        eventId: "route.changed",
+        context: { route_id: "APP_HOME", build_id: "build-a" },
+      },
+      () => 0,
+    );
+
+    expect(projected).toEqual({
+      success: true,
+      record: {
+        level: "info",
+        eventId: "route.changed",
+        timestamp: "1970-01-01T00:00:00.000Z",
+        context: { route_id: "APP_HOME", build_id: "build-a" },
+      },
+    });
+    expect(
+      projectDiagnosticRecord({
+        level: "error",
+        eventId: "ui.render.failed",
+        context: { raw_url: "https://example.test/private?token=secret" },
+      }),
+    ).toEqual({ success: false, reason: "unknown-context" });
+    expect(
+      projectDiagnosticRecord({
+        level: "error",
+        eventId: "ui.render.failed",
+        context: { route_id: "private value with whitespace" },
+      }),
+    ).toEqual({ success: false, reason: "invalid-context" });
+  });
+
+  it("bounds evidence and isolates throwing sinks and hostile error objects", () => {
+    const sink = vi.fn(() => {
+      throw new Error("sink-secret");
+    });
+    const adapter = createDiagnosticsAdapter({
+      maxEntries: 1,
+      now: () => 0,
+      sink,
+    });
+    const circular: Record<string, unknown> = { name: "TypeError" };
+    circular.self = circular;
+    const hostile = new Proxy(
+      {},
+      {
+        get() {
+          throw new Error("private getter");
+        },
+        ownKeys() {
+          throw new Error("private keys");
+        },
+      },
+    );
+
+    expect(safeErrorKind(circular)).toBe("TYPE_ERROR");
+    expect(safeErrorKind(hostile)).toBe("UNKNOWN_FAILURE");
+    expect(
+      projectDiagnosticRecord({
+        level: "error",
+        eventId: "ui.render.failed",
+        context: hostile,
+      }),
+    ).toEqual({ success: false, reason: "serialization-failure" });
+    expect(() =>
+      adapter.record({
+        level: "info",
+        eventId: "route.changed",
+        context: { route_id: "APP_HOME" },
+      }),
+    ).not.toThrow();
+    adapter.record({
+      level: "warn",
+      eventId: "cache.operation.failed",
+      context: { operation: "query", error_kind: "UNKNOWN_FAILURE" },
+    });
+
+    expect(adapter.entries()).toHaveLength(1);
+    expect(adapter.entries()[0]?.eventId).toBe("cache.operation.failed");
+    expect(adapter.dropped()).toEqual({
+      "queue-full": 1,
+      "sink-failure": 2,
+    });
+    expect(JSON.stringify(adapter.entries())).not.toMatch(
+      /sink-secret|private getter/,
+    );
+  });
+
+  it("creates safe pre-mount boot evidence and supports a true no-op", () => {
+    const circular: Record<string, unknown> = {
+      name: "TypeError",
+      token: "credential-value",
+      stack: "private-stack",
+    };
+    circular.self = circular;
+
+    expect(() =>
+      recordBootFailure(
+        circular,
+        {
+          buildId: "build-a",
+          configSchemaVersion: "1",
+          supportReference: "support-private",
+        },
+        () => 0,
+      ),
+    ).not.toThrow();
+    const evidence = getLastBootEvidence();
+    expect(evidence?.diagnostic?.eventId).toBe("app.boot.failed");
+    expect(evidence?.telemetry).toMatchObject({
+      eventName: "app.boot.failed",
+      timestamp: "1970-01-01T00:00:00.000Z",
+    });
+    expect(JSON.stringify(evidence)).not.toMatch(
+      /credential-value|private-stack|support-private/,
+    );
+    expect(() =>
+      noOpDiagnostics.record({
+        level: "error",
+        eventId: "app.boot.failed",
+      }),
+    ).not.toThrow();
+  });
+});

tests/unit/query-cache.test.js

@@ -52,7 +52,10 @@ describe("TanStack QueryCachePort adapter", () => {
   it("normalizes adapter exceptions without raw key data", async () => {
     const client = new QueryClient();
     vi.spyOn(client, "invalidateQueries").mockRejectedValue(new Error("secret-key"));
-    const adapter = createQueryCacheAdapter(client);
+    const record = vi.fn();
+    const adapter = createQueryCacheAdapter(client, {
+      diagnostics: { record },
+    });
     const result = await adapter.invalidate(["resource", "sensitive-filter"]);
 
     expect(result).toMatchObject({
@@ -60,5 +63,16 @@ describe("TanStack QueryCachePort adapter", () => {
       error: { kind: "QUERY_CACHE_FAILURE" },
     });
     expect(JSON.stringify(result)).not.toContain("sensitive-filter");
+    expect(record).toHaveBeenCalledWith({
+      level: "warn",
+      eventId: "cache.operation.failed",
+      context: {
+        operation: "invalidate",
+        error_kind: "QUERY_CACHE_FAILURE",
+      },
+    });
+    expect(JSON.stringify(record.mock.calls)).not.toMatch(
+      /sensitive-filter|secret-key/,
+    );
   });
 });

tests/unit/runtime-adapters.test.js

@@ -46,6 +46,9 @@ describe("runtime adapter composition", () => {
       releaseId: "release-a",
     });
     expect(adapters.infrastructure.queryClient).toBeDefined();
+    expect(adapters.outputPorts.diagnostics.record).toEqual(expect.any(Function));
+    expect(adapters.outputPorts.telemetry.emit).toEqual(expect.any(Function));
+    expect(adapters.outputPorts.telemetry.pendingCount()).toBe(0);
     expect(adapters).not.toHaveProperty("http");
     expect(adapters).not.toHaveProperty("storage");
   });

tests/unit/storage-registry.test.js

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 
 import { createBrowserStorageAdapter } from "../../src/adapters/storage/browser-storage-adapter.js";
 import {
@@ -61,13 +61,27 @@ describe("storage registry", () => {
 
   it("falls back to memory when preference storage quota is exceeded", () => {
     const localStorage = createStorage({ quota: true });
-    const adapter = createBrowserStorageAdapter({ localStorage });
+    const record = vi.fn();
+    const adapter = createBrowserStorageAdapter({
+      localStorage,
+      diagnostics: { record },
+    });
     expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({
       ok: false,
       fallback: "memory",
       error: { kind: "STORAGE_QUOTA_EXCEEDED" },
     });
     expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" });
+    expect(record).toHaveBeenCalledOnce();
+    expect(record).toHaveBeenCalledWith({
+      level: "warn",
+      eventId: "storage.operation.failed",
+      context: {
+        operation: "write:COLOR_SCHEME",
+        error_kind: "STORAGE_QUOTA_EXCEEDED",
+      },
+    });
+    expect(JSON.stringify(record.mock.calls)).not.toContain("dark");
   });
 
   it("discards data from a previous schema version", () => {

tests/unit/telemetry.test.js

@@ -33,15 +33,26 @@ describe("telemetry registry and redaction", () => {
     }
   });
 
-  it("uses a default-deny attribute projection", () => {
+  it("redacts forbidden attributes and rejects unknown context", () => {
     const projected = projectTelemetryEvent("api.request.failed", {
       ...validAttributes,
       raw_url: "https://api.test/path?token=secret",
-      unregistered: "private",
     });
 
     expect(projected.success).toBe(true);
-    expect(JSON.stringify(projected)).not.toMatch(/raw_url|token|secret|unregistered/);
+    expect(JSON.stringify(projected)).not.toMatch(/raw_url|token|secret/);
+    expect(
+      projectTelemetryEvent("api.request.failed", {
+        ...validAttributes,
+        unregistered: "private",
+      }),
+    ).toEqual({ success: false, reason: "unknown-attributes" });
+    expect(
+      projectTelemetryEvent("api.request.failed", {
+        ...validAttributes,
+        route_id: "/users/actual-user-id",
+      }),
+    ).toEqual({ success: false, reason: "invalid-attribute-value" });
   });
 
   it("validates traceparent without exposing invalid values", () => {
@@ -71,10 +82,18 @@ describe("best-effort telemetry adapter", () => {
 
     expect(adapter.pendingCount()).toBe(2);
     expect(adapter.droppedCount()).toBe(1);
+    expect(adapter.dropReasons()).toEqual({ "queue-full": 1 });
+    expect(adapter.deliveryEvidence()).toMatchObject({
+      eventName: "telemetry.delivery.dropped",
+      attributes: { reason: "queue-full", queue_size_bucket: "1-10" },
+    });
     expect(scheduled).toHaveLength(1);
   });
 
   it("degrades on sink failure without throwing or recursive events", async () => {
+    const onDrop = vi.fn(() => {
+      throw new Error("observer unavailable");
+    });
     const adapter = createTelemetryAdapter({
       enabled: true,
       endpoint: "https://telemetry.test/events",
@@ -82,13 +101,50 @@ describe("best-effort telemetry adapter", () => {
       fetcher: async () => {
         throw new Error("sink unavailable");
       },
+      onDrop,
     });
     expect(() => adapter.emit("api.request.failed", validAttributes)).not.toThrow();
     await expect(adapter.flush()).resolves.toBeUndefined();
     expect(adapter.droppedCount()).toBe(1);
+    expect(adapter.dropReasons()).toEqual({ "sink-failure": 1 });
+    expect(onDrop).toHaveBeenCalledOnce();
     expect(adapter.pendingCount()).toBe(0);
   });
 
+  it("never serializes circular or unbounded event context", () => {
+    const adapter = createTelemetryAdapter({
+      enabled: true,
+      endpoint: "https://telemetry.test/events",
+      schedule: () => {},
+    });
+    const circular = {};
+    circular.self = circular;
+    const hostile = new Proxy(
+      {},
+      {
+        ownKeys() {
+          throw new Error("private proxy value");
+        },
+      },
+    );
+
+    expect(() =>
+      adapter.emit("api.request.failed", {
+        ...validAttributes,
+        unregistered: circular,
+      }),
+    ).not.toThrow();
+    expect(adapter.pendingCount()).toBe(0);
+    expect(adapter.dropReasons()).toEqual({ "invalid-context": 1 });
+    expect(() =>
+      adapter.emit("api.request.failed", hostile),
+    ).not.toThrow();
+    expect(adapter.dropReasons()).toEqual({
+      "invalid-context": 1,
+      "serialization-failure": 1,
+    });
+  });
+
   it("performs no network or queue work when disabled", async () => {
     const fetcher = vi.fn();
     const adapter = createTelemetryAdapter({
@@ -102,4 +158,25 @@ describe("best-effort telemetry adapter", () => {
     expect(fetcher).not.toHaveBeenCalled();
     expect(adapter.pendingCount()).toBe(0);
   });
+
+  it("flushes on page exit and removes the lifecycle listener", async () => {
+    const lifecycle = new EventTarget();
+    const remove = vi.spyOn(lifecycle, "removeEventListener");
+    const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
+    const adapter = createTelemetryAdapter({
+      enabled: true,
+      endpoint: "https://telemetry.test/events",
+      schedule: () => {},
+      lifecycle,
+      fetcher,
+    });
+    adapter.emit("api.request.failed", validAttributes);
+
+    lifecycle.dispatchEvent(new Event("pagehide"));
+    await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
+    adapter.dispose();
+
+    expect(adapter.pendingCount()).toBe(0);
+    expect(remove).toHaveBeenCalledWith("pagehide", expect.any(Function));
+  });
 });