feat: add diagnostics and telemetry runtime

src/adapters/query-cache/tanstack-query-cache.js

@@ -1,6 +1,7 @@
-import { QueryClient } from "@tanstack/react-query";
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
 
 import { createFailure } from "../../contracts/errors.js";
+import { safeErrorKind } from "../../contracts/diagnostics.js";
 
 export const QUERY_CACHE_DEFAULTS = Object.freeze({
   staleTime: 30_000,
@@ -11,8 +12,32 @@ export const QUERY_CACHE_DEFAULTS = Object.freeze({
   persistence: false,
 });
 
-export function createQueryClient() {
+/**
+ * @param {{diagnostics?: import("../../application/ports/diagnostics-port.js").DiagnosticsPort}} [dependencies]
+ */
+export function createQueryClient(dependencies = {}) {
+  /** @param {string} operation @param {unknown} error */
+  function report(operation, error) {
+    try {
+      dependencies.diagnostics?.record({
+        level: "warn",
+        eventId: "cache.operation.failed",
+        context: {
+          operation,
+          error_kind: safeErrorKind(error),
+        },
+      });
+    } catch {
+      // Query behavior remains independent from diagnostics.
+    }
+  }
   return new QueryClient({
+    queryCache: new QueryCache({
+      onError: (error) => report("query", error),
+    }),
+    mutationCache: new MutationCache({
+      onError: (error) => report("mutation", error),
+    }),
     defaultOptions: {
       queries: {
         staleTime: QUERY_CACHE_DEFAULTS.staleTime,
@@ -29,15 +54,16 @@ export function createQueryClient() {
 
 /**
  * @param {QueryClient} queryClient
+ * @param {{diagnostics?: import("../../application/ports/diagnostics-port.js").DiagnosticsPort}} [dependencies]
  * @returns {import("../../application/ports/query-cache-port.js").QueryCachePort}
  */
-export function createQueryCacheAdapter(queryClient) {
+export function createQueryCacheAdapter(queryClient, dependencies = {}) {
   return Object.freeze({
     read(key) {
       try {
         return { ok: true, value: queryClient.getQueryData(key) };
       } catch {
-        return cacheFailure("read", key);
+        return cacheFailure("read", key, dependencies.diagnostics);
       }
     },
     write(key, value) {
@@ -45,7 +71,7 @@ export function createQueryCacheAdapter(queryClient) {
         queryClient.setQueryData(key, structuredClone(value));
         return { ok: true };
       } catch {
-        return cacheFailure("write", key);
+        return cacheFailure("write", key, dependencies.diagnostics);
       }
     },
     async invalidate(namespace) {
@@ -53,15 +79,31 @@ export function createQueryCacheAdapter(queryClient) {
         await queryClient.invalidateQueries({ queryKey: namespace, exact: false });
         return { ok: true };
       } catch {
-        return cacheFailure("invalidate", namespace);
+        return cacheFailure("invalidate", namespace, dependencies.diagnostics);
       }
     },
   });
 }
 
-/** @param {string} phase @param {readonly unknown[]} key */
-function cacheFailure(phase, key) {
+/**
+ * @param {string} phase
+ * @param {readonly unknown[]} key
+ * @param {import("../../application/ports/diagnostics-port.js").DiagnosticsPort | undefined} diagnostics
+ */
+function cacheFailure(phase, key, diagnostics) {
   const namespace = typeof key[0] === "string" ? key[0] : "unknown";
+  try {
+    diagnostics?.record({
+      level: "warn",
+      eventId: "cache.operation.failed",
+      context: {
+        operation: phase,
+        error_kind: "QUERY_CACHE_FAILURE",
+      },
+    });
+  } catch {
+    // Cache behavior remains independent from diagnostics.
+  }
   return {
     ok: /** @type {false} */ (false),
     error: createFailure("QUERY_CACHE_FAILURE", "QUERY_CACHE", 0, {