feat: add diagnostics and telemetry runtime

tests/features/reference-feature/reference-diagnostics.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createHttpClient } from "../../../src/adapters/http/client.js";
+import { createReferenceHttpGateway } from "../../../src/features/reference-feature/adapters/reference-http-gateway.js";
+import { createReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.js";
+import { REFERENCE_FEATURE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract.js";
+import { mapReferenceOperation } from "../../../src/features/reference-feature/contracts/reference-mapper.js";
+import {
+  validateReferencePayload,
+  validateReferenceRequest,
+} from "../../../src/features/reference-feature/contracts/reference-schemas.js";
+
+describe("reference feature diagnostics correlation", () => {
+  it("preserves route, operation and request correlation through the vertical path", async () => {
+    const record = vi.fn();
+    const operations =
+      REFERENCE_FEATURE_CONTRACT.apiOperations as Readonly<
+        Record<
+          string,
+          ReturnType<
+            NonNullable<Parameters<typeof createHttpClient>[0]["getOperation"]>
+          >
+        >
+      >;
+    const client = createHttpClient({
+      baseUrl: "https://api.test",
+      fetcher: async () =>
+        Response.json({
+          success: true,
+          data: [{ id: "reference-1", name: "Reference" }],
+          meta: { requestId: "safe-request", traceId: "safe-trace" },
+        }),
+      getOperation(operationId) {
+        const operation = operations[operationId];
+        if (!operation) throw new Error("Unregistered reference operation");
+        return operation;
+      },
+      validatePayload: validateReferencePayload,
+      validateRequest: validateReferenceRequest,
+      mapPayload: mapReferenceOperation,
+      correlationIdFactory: () => "reference-correlation",
+      diagnostics: { record },
+      scheduler: {
+        setTimeout: () => 1,
+        clearTimeout: () => {},
+      },
+    });
+    const application = createReferenceFeatureInput(
+      createReferenceHttpGateway(client),
+    );
+
+    await expect(
+      application.listResources({ limit: 20 }),
+    ).resolves.toMatchObject({ ok: true });
+    expect(record).toHaveBeenCalledOnce();
+    expect(record).toHaveBeenCalledWith({
+      level: "info",
+      eventId: "http.request.completed",
+      context: expect.objectContaining({
+        route_id: "REFERENCE_RESOURCE_LIST",
+        operation_id: "LIST_REFERENCE_RESOURCES",
+        correlation_id: "reference-correlation",
+        outcome: "success",
+      }),
+    });
+  });
+});

tests/fixtures/diagnostics/forbidden/direct-console.ts

@@ -0,0 +1,3 @@
+export function leakToConsole(token: string) {
+  console.error("UNKNOWN_DIAGNOSTIC_EVENT", token);
+}

tests/fixtures/diagnostics/forbidden/raw-context.ts

@@ -0,0 +1,8 @@
+export function leakSensitiveContext(telemetry: {
+  emit(eventName: string, context: Record<string, unknown>): void;
+}) {
+  telemetry.emit("api.request.failed", {
+    authorization: "Bearer secret",
+    request_body: { email: "private@example.test" },
+  });
+}

tests/fixtures/typecheck/invalid-diagnostics-port.ts

@@ -0,0 +1,11 @@
+import type { DiagnosticsPort } from "../../../src/application/ports/diagnostics-port.js";
+import type { TelemetryPort } from "../../../src/application/ports/telemetry-port.js";
+
+declare const diagnostics: DiagnosticsPort;
+declare const telemetry: TelemetryPort;
+
+diagnostics.record({
+  level: "fatal",
+  eventId: "UNKNOWN_DIAGNOSTIC_EVENT",
+});
+telemetry.emit("unknown.telemetry.event", {});

tests/helpers/create-test-application.js

@@ -5,7 +5,8 @@ import { createApplication } from "../../src/application/create-application.js";
  * @param {{
  *   session?: import("../../src/application/ports/auth-session-port.js").AuthSessionPort,
  *   preferences?: import("../../src/application/ports/storage-port.js").StoragePort,
- *   diagnostics?: import("../../src/application/ports/telemetry-port.js").TelemetryPort,
+ *   diagnostics?: import("../../src/application/ports/diagnostics-port.js").DiagnosticsPort,
+ *   telemetry?: import("../../src/application/ports/telemetry-port.js").TelemetryPort,
  *   releaseInfo?: import("../../src/application/ports/release-info-port.js").ReleaseInfoPort,
  *   navigation?: { reload(): void },
  *   featureInputs?: Readonly<Record<string, unknown>>
@@ -22,7 +23,8 @@ export function createTestApplication(overrides = {}) {
           write: () => ({ ok: /** @type {const} */ (true) }),
           remove: () => ({ ok: /** @type {const} */ (true) }),
         },
-      diagnostics: overrides.diagnostics ?? { emit: () => {} },
+      diagnostics: overrides.diagnostics ?? { record: () => {} },
+      telemetry: overrides.telemetry ?? { emit: () => {} },
       releaseInfo:
         overrides.releaseInfo ??
         {

tests/integration/http-diagnostics.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createHttpClient } from "../../src/adapters/http/client.js";
+import type { DiagnosticRecordInput } from "../../src/contracts/diagnostics.js";
+import { TEST_HTTP_CONTRACT } from "../helpers/http-contract-fixture.js";
+
+function successResponse(data: unknown) {
+  return Response.json({
+    success: true,
+    data,
+    meta: { requestId: "request-1", traceId: "trace-1" },
+  });
+}
+
+function failureResponse(status: number) {
+  return Response.json(
+    {
+      success: false,
+      error: { code: "TEMPORARY" },
+      meta: { requestId: "request-1", traceId: "trace-1" },
+    },
+    { status },
+  );
+}
+
+type EmittedEvent = Readonly<{
+  eventName: string;
+  attributes: Readonly<Record<string, unknown>>;
+}>;
+
+function harness(fetcher: typeof fetch, maxRetryAttempts = 1) {
+  const records: DiagnosticRecordInput[] = [];
+  const emitted: EmittedEvent[] = [];
+  let currentTime = 0;
+  const client = createHttpClient({
+    ...TEST_HTTP_CONTRACT,
+    baseUrl: "https://api.test",
+    fetcher,
+    maxRetryAttempts,
+    clock: {
+      now: () => currentTime,
+      sleep: async () => {
+        currentTime += 150;
+      },
+    },
+    scheduler: {
+      setTimeout: () => 1,
+      clearTimeout: () => {},
+    },
+    correlationIdFactory: () => "correlation-fixed",
+    diagnostics: {
+      record(input) {
+        records.push(structuredClone(input));
+      },
+    },
+    telemetry: {
+      emit(eventName, attributes) {
+        emitted.push({
+          eventName,
+          attributes: structuredClone(attributes),
+        });
+      },
+    },
+  });
+  return { client, records, emitted };
+}
+
+describe("HTTP diagnostics and terminal telemetry", () => {
+  it("records one successful reference route outcome and no failure event", async () => {
+    const { client, records, emitted } = harness(
+      vi.fn(async () => successResponse([])),
+    );
+
+    await expect(
+      client.execute({
+        operationId: "LIST_ENTITIES",
+        routeId: "TEST_ROUTE",
+      }),
+    ).resolves.toMatchObject({ ok: true });
+
+    expect(records).toEqual([
+      {
+        level: "info",
+        eventId: "http.request.completed",
+        context: {
+          route_id: "TEST_ROUTE",
+          operation_id: "LIST_ENTITIES",
+          correlation_id: "correlation-fixed",
+          outcome: "success",
+          error_kind: "NONE",
+          http_status_group: "none",
+          attempt_count_bucket: "1",
+          duration_bucket: "lt100ms",
+        },
+      },
+    ]);
+    expect(emitted).toEqual([]);
+  });
+
+  it("summarizes retry recovery once without a terminal failure event", async () => {
+    const fetcher = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(failureResponse(503))
+      .mockResolvedValueOnce(successResponse([]));
+    const { client, records, emitted } = harness(fetcher);
+
+    await expect(
+      client.execute({
+        operationId: "LIST_ENTITIES",
+        routeId: "TEST_ROUTE",
+      }),
+    ).resolves.toMatchObject({ ok: true });
+
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(records).toHaveLength(1);
+    expect(records[0]).toMatchObject({
+      eventId: "http.request.completed",
+      context: {
+        outcome: "recovered",
+        correlation_id: "correlation-fixed",
+        duration_bucket: "100-499ms",
+      },
+    });
+    expect(emitted).toEqual([]);
+  });
+
+  it("emits one bounded terminal failure after all attempts", async () => {
+    const fetcher = vi.fn(async () => failureResponse(503));
+    const { client, records, emitted } = harness(fetcher);
+
+    await expect(
+      client.execute({
+        operationId: "CREATE_ENTITY",
+        routeId: "TEST_ROUTE",
+        body: { name: "private user input" },
+        idempotencyKey: "private-idempotency-key",
+      }),
+    ).resolves.toMatchObject({
+      ok: false,
+      error: { kind: "SERVER_FAILURE" },
+    });
+
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(records).toHaveLength(1);
+    expect(emitted).toEqual([
+      {
+        eventName: "api.request.failed",
+        attributes: {
+          error_kind: "SERVER_FAILURE",
+          http_status_group: "5xx",
+          attempt_count_bucket: "2",
+          route_id: "TEST_ROUTE",
+          operation_id: "CREATE_ENTITY",
+          duration_bucket: "100-499ms",
+        },
+      },
+    ]);
+    expect(JSON.stringify({ records, emitted })).not.toMatch(
+      /private user input|private-idempotency-key/,
+    );
+  });
+
+  it("records navigation abort without failure telemetry", async () => {
+    const caller = new AbortController();
+    caller.abort("navigation");
+    const fetcher = vi.fn(async (request: RequestInfo | URL) => {
+      const signal = (request as Request).signal;
+      if (signal.aborted) throw new DOMException("aborted", "AbortError");
+      return successResponse([]);
+    });
+    const { client, records, emitted } = harness(
+      fetcher as unknown as typeof fetch,
+    );
+
+    await expect(
+      client.execute({
+        operationId: "LIST_ENTITIES",
+        routeId: "TEST_ROUTE",
+        signal: caller.signal,
+      }),
+    ).resolves.toMatchObject({
+      ok: false,
+      error: { kind: "REQUEST_ABORTED" },
+    });
+
+    expect(records).toHaveLength(1);
+    expect(records[0]).toMatchObject({
+      eventId: "http.request.completed",
+      context: { outcome: "aborted", error_kind: "REQUEST_ABORTED" },
+    });
+    expect(emitted).toEqual([]);
+  });
+});

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));
+  });
 });