feat: add redacted best-effort telemetry contract

package.json

@@ -25,6 +25,7 @@
     "test:all": "pnpm test:runtime-schema && pnpm test:unit && pnpm test:component && pnpm test:integration"
   },
   "dependencies": {
+    "@tanstack/react-query": "5.101.4",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "zod": "4.4.3"

pnpm-lock.yaml

@@ -8,6 +8,9 @@ importers:
 
   .:
     dependencies:
+      '@tanstack/react-query':
+        specifier: 5.101.4
+        version: 5.101.4(react@19.2.8)
       react:
         specifier: 19.2.8
         version: 19.2.8
@@ -396,6 +399,14 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
+  '@tanstack/query-core@5.101.4':
+    resolution: {integrity: sha512-gNwcvOJcRbLWPOLG/2OBm+zM+Yv+MKsXKEOWC57USuZDEsI71hEErQsiEGx5wX9rzWWkfwM0fVSPoiIFSsxfiw==}
+
+  '@tanstack/react-query@5.101.4':
+    resolution: {integrity: sha512-yRg2pfOCxIs4ZJW3XYYHU/WgtD04FHSnfHlpRT7h7pR77hwkdRG4wxbKe4aq6P0RvXUTBSQpQeadS1SUYUe+KA==}
+    peerDependencies:
+      react: ^18 || ^19
+
   '@testing-library/dom@10.4.1':
     resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
     engines: {node: '>=18'}
@@ -1840,6 +1851,13 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
+  '@tanstack/query-core@5.101.4': {}
+
+  '@tanstack/react-query@5.101.4(react@19.2.8)':
+    dependencies:
+      '@tanstack/query-core': 5.101.4
+      react: 19.2.8
+
   '@testing-library/dom@10.4.1':
     dependencies:
       '@babel/code-frame': 7.29.7

src/adapters/auth/external-session-adapter.js

@@ -0,0 +1,45 @@
+/**
+ * Creates the skeleton-owned side of an external session integration.
+ * Credential acquisition and storage stay inside the supplied external owner.
+ *
+ * @param {{
+ *   readState(): import("../../application/ports/auth-session-port.js").SessionState,
+ *   attachCredential(request: Request): Promise<Request>,
+ *   recoverSession(): Promise<"restored" | "no-session">,
+ *   notifyUnauthenticated(): void
+ * }} owner
+ * @returns {import("../../application/ports/auth-session-port.js").AuthSessionPort}
+ */
+export function createExternalAuthSessionAdapter(owner) {
+  return Object.freeze({
+    getState() {
+      return owner.readState();
+    },
+    async attach(request) {
+      const attached = await owner.attachCredential(request);
+      if (!(attached instanceof Request)) {
+        throw new TypeError("Auth owner returned an invalid request");
+      }
+      return attached;
+    },
+    async recover() {
+      const result = await owner.recoverSession();
+      if (result !== "restored" && result !== "no-session") {
+        throw new TypeError("Auth owner returned an invalid recovery state");
+      }
+      return result;
+    },
+    onUnauthenticated() {
+      owner.notifyUnauthenticated();
+    },
+  });
+}
+
+export function createAnonymousSessionAdapter() {
+  return createExternalAuthSessionAdapter({
+    readState: () => "unauthenticated",
+    attachCredential: async (request) => request,
+    recoverSession: async () => "no-session",
+    notifyUnauthenticated: () => {},
+  });
+}

src/adapters/http/client.js

@@ -109,6 +109,11 @@ export function createHttpClient(dependencies) {
         continue;
       }
 
+      if (outcome.error.httpStatus === 401 && recoveryUsed) {
+        authSession.onUnauthenticated();
+        return outcome;
+      }
+
       if (!shouldRetry(operation, outcome.error, retryCount)) {
         return outcome;
       }

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

@@ -0,0 +1,72 @@
+import { QueryClient } from "@tanstack/react-query";
+
+import { createFailure } from "../../contracts/errors.js";
+
+export const QUERY_CACHE_DEFAULTS = Object.freeze({
+  staleTime: 30_000,
+  gcTime: 300_000,
+  refetchOnWindowFocus: true,
+  retry: false,
+  mutationRetry: false,
+  persistence: false,
+});
+
+export function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: QUERY_CACHE_DEFAULTS.staleTime,
+        gcTime: QUERY_CACHE_DEFAULTS.gcTime,
+        refetchOnWindowFocus: QUERY_CACHE_DEFAULTS.refetchOnWindowFocus,
+        retry: QUERY_CACHE_DEFAULTS.retry,
+      },
+      mutations: {
+        retry: QUERY_CACHE_DEFAULTS.mutationRetry,
+      },
+    },
+  });
+}
+
+/**
+ * @param {QueryClient} queryClient
+ * @returns {import("../../application/ports/query-cache-port.js").QueryCachePort}
+ */
+export function createQueryCacheAdapter(queryClient) {
+  return Object.freeze({
+    read(key) {
+      try {
+        return { ok: true, value: queryClient.getQueryData(key) };
+      } catch {
+        return cacheFailure("read", key);
+      }
+    },
+    write(key, value) {
+      try {
+        queryClient.setQueryData(key, structuredClone(value));
+        return { ok: true };
+      } catch {
+        return cacheFailure("write", key);
+      }
+    },
+    async invalidate(namespace) {
+      try {
+        await queryClient.invalidateQueries({ queryKey: namespace, exact: false });
+        return { ok: true };
+      } catch {
+        return cacheFailure("invalidate", namespace);
+      }
+    },
+  });
+}
+
+/** @param {string} phase @param {readonly unknown[]} key */
+function cacheFailure(phase, key) {
+  const namespace = typeof key[0] === "string" ? key[0] : "unknown";
+  return {
+    ok: /** @type {false} */ (false),
+    error: createFailure("QUERY_CACHE_FAILURE", "QUERY_CACHE", 0, {
+      code: `QUERY_CACHE_${phase.toUpperCase()}_FAILED`,
+      causeClass: `namespace:${namespace}`,
+    }),
+  };
+}

src/adapters/storage/browser-storage-adapter.js

@@ -0,0 +1,137 @@
+import { createFailure } from "../../contracts/errors.js";
+import { getStorageDefinition } from "../../contracts/storage-keys.js";
+
+/**
+ * @param {{
+ *   localStorage?: Storage,
+ *   sessionStorage?: Storage,
+ *   now?: () => number
+ * }} [dependencies]
+ * @returns {import("../../application/ports/storage-port.js").StoragePort}
+ */
+export function createBrowserStorageAdapter(dependencies = {}) {
+  const memory = new Map();
+  const now = dependencies.now ?? Date.now;
+
+  /** @param {string} name */
+  function backendFor(name) {
+    if (name === "localStorage") return dependencies.localStorage;
+    if (name === "sessionStorage") return dependencies.sessionStorage;
+    return undefined;
+  }
+
+  return Object.freeze({
+    read(logicalName) {
+      let definition;
+      try {
+        definition = getStorageDefinition(logicalName);
+      } catch {
+        return unavailable("read", logicalName);
+      }
+
+      const backend = backendFor(definition.backend);
+      try {
+        const raw = backend?.getItem(definition.physicalKey);
+        if (raw === null || raw === undefined) {
+          return { ok: true, value: memory.get(definition.physicalKey) };
+        }
+        const envelope = JSON.parse(raw);
+        if (
+          !envelope ||
+          typeof envelope !== "object" ||
+          envelope.schemaVersion !== definition.schemaVersion
+        ) {
+          backend?.removeItem(definition.physicalKey);
+          return { ok: true, value: undefined };
+        }
+        if (typeof envelope.expiresAt === "number" && envelope.expiresAt <= now()) {
+          backend?.removeItem(definition.physicalKey);
+          return { ok: true, value: undefined };
+        }
+        return { ok: true, value: structuredClone(envelope.value) };
+      } catch {
+        return unavailable("read", logicalName);
+      }
+    },
+
+    write(logicalName, value) {
+      let definition;
+      try {
+        definition = getStorageDefinition(logicalName);
+      } catch {
+        return unavailable("write", logicalName);
+      }
+
+      const expiresAt =
+        typeof definition.ttl === "number" ? now() + definition.ttl : null;
+      const envelope = {
+        schemaVersion: definition.schemaVersion,
+        expiresAt,
+        value: structuredClone(value),
+      };
+      const backend = backendFor(definition.backend);
+
+      try {
+        if (!backend) throw new DOMException("Storage unavailable", "SecurityError");
+        backend.setItem(definition.physicalKey, JSON.stringify(envelope));
+        return { ok: true };
+      } catch (error) {
+        const quota =
+          error instanceof DOMException &&
+          ["QuotaExceededError", "NS_ERROR_DOM_QUOTA_REACHED"].includes(error.name);
+
+        if (definition.quotaFallback === "memory") {
+          memory.set(definition.physicalKey, structuredClone(value));
+          return {
+            ok: false,
+            error: storageFailure(quota, "write", logicalName),
+            fallback: "memory",
+          };
+        }
+        return {
+          ok: false,
+          error: storageFailure(quota, "write", logicalName),
+          fallback: definition.quotaFallback,
+        };
+      }
+    },
+
+    remove(logicalName) {
+      let definition;
+      try {
+        definition = getStorageDefinition(logicalName);
+      } catch {
+        return unavailable("remove", logicalName);
+      }
+      try {
+        backendFor(definition.backend)?.removeItem(definition.physicalKey);
+        memory.delete(definition.physicalKey);
+        return { ok: true };
+      } catch {
+        return unavailable("remove", logicalName);
+      }
+    },
+  });
+}
+
+/** @param {boolean} quota @param {string} phase @param {string} logicalName */
+function storageFailure(quota, phase, logicalName) {
+  return createFailure(
+    quota ? "STORAGE_QUOTA_EXCEEDED" : "STORAGE_UNAVAILABLE",
+    "STORAGE",
+    0,
+    {
+      code: `${logicalName}_${phase.toUpperCase()}_${
+        quota ? "QUOTA_EXCEEDED" : "UNAVAILABLE"
+      }`,
+    },
+  );
+}
+
+/** @param {string} phase @param {string} logicalName */
+function unavailable(phase, logicalName) {
+  return {
+    ok: /** @type {false} */ (false),
+    error: storageFailure(false, phase, logicalName),
+  };
+}

src/adapters/telemetry/best-effort-telemetry.js

@@ -0,0 +1,99 @@
+import { projectTelemetryEvent } from "../../contracts/telemetry.js";
+
+export const noOpTelemetry = Object.freeze({
+  emit: () => {},
+});
+
+/**
+ * @param {{
+ *   enabled: boolean,
+ *   endpoint?: string,
+ *   fetcher?: typeof fetch,
+ *   maxQueue?: number,
+ *   schedule?: (callback: () => void) => void
+ * }} options
+ */
+export function createTelemetryAdapter(options) {
+  if (!options.enabled || !options.endpoint) {
+    return Object.freeze({
+      ...noOpTelemetry,
+      flush: async () => {},
+      pendingCount: () => 0,
+      droppedCount: () => 0,
+    });
+  }
+
+  const endpoint = /** @type {string} */ (options.endpoint);
+  const fetcher = options.fetcher ?? fetch;
+  const maxQueue = options.maxQueue ?? 100;
+  const schedule = options.schedule ?? queueMicrotask;
+  const queue =
+    /** @type {Array<{eventName: string, attributes: Readonly<Record<string, unknown>>}>} */ (
+      []
+    );
+  let scheduled = false;
+  let flushing = false;
+  let dropped = 0;
+
+  /** @param {string} eventName @param {Record<string, unknown>} attributes */
+  function emit(eventName, attributes) {
+    const projected = projectTelemetryEvent(eventName, attributes);
+    if (!projected.success) {
+      dropped += 1;
+      return;
+    }
+
+    if (queue.length >= maxQueue) {
+      queue.shift();
+      dropped += 1;
+    }
+    queue.push(projected.event);
+
+    if (!scheduled) {
+      scheduled = true;
+      schedule(() => {
+        scheduled = false;
+        void flush();
+      });
+    }
+  }
+
+  async function flush() {
+    if (flushing || queue.length === 0) return;
+    flushing = true;
+    const batch = queue.splice(0, queue.length);
+    try {
+      const response = await fetcher(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ events: batch }),
+        keepalive: true,
+      });
+      if (!response.ok) dropped += batch.length;
+    } catch {
+      dropped += batch.length;
+    } finally {
+      flushing = false;
+    }
+  }
+
+  return Object.freeze({
+    emit,
+    flush,
+    pendingCount: () => queue.length,
+    droppedCount: () => dropped,
+  });
+}
+
+/**
+ * Propagates only a structurally valid W3C traceparent. Invalid/raw headers are
+ * discarded rather than logged or surfaced.
+ *
+ * @param {string | null | undefined} traceparent
+ */
+export function safeTraceparent(traceparent) {
+  return typeof traceparent === "string" &&
+    /^00-[0-9a-f]{32}-[0-9a-f]{16}-0[01]$/i.test(traceparent)
+    ? traceparent.toLowerCase()
+    : null;
+}

src/application/ports/query-cache-port.js

@@ -1,8 +1,11 @@
 /**
  * @typedef {{
- *   read(key: readonly unknown[]): unknown,
- *   write(key: readonly unknown[], value: unknown): void,
- *   invalidate(namespace: readonly unknown[]): Promise<void>
+ *   read(key: readonly unknown[]): { ok: true, value: unknown } |
+ *     { ok: false, error: import("../../contracts/errors.js").ApiFailure },
+ *   write(key: readonly unknown[], value: unknown): { ok: true } |
+ *     { ok: false, error: import("../../contracts/errors.js").ApiFailure },
+ *   invalidate(namespace: readonly unknown[]): Promise<{ ok: true } |
+ *     { ok: false, error: import("../../contracts/errors.js").ApiFailure }>
  * }} QueryCachePort
  */
 

src/application/ports/storage-port.js

@@ -1,8 +1,12 @@
 /**
  * @typedef {{
- *   read(logicalName: string): { ok: true, value: unknown } | { ok: false, error: unknown },
- *   write(logicalName: string, value: unknown): { ok: true } | { ok: false, error: unknown },
- *   remove(logicalName: string): { ok: true } | { ok: false, error: unknown }
+ *   read(logicalName: string): { ok: true, value: unknown } |
+ *     { ok: false, error: import("../../contracts/errors.js").ApiFailure },
+ *   write(logicalName: string, value: unknown): { ok: true } |
+ *     { ok: false, error: import("../../contracts/errors.js").ApiFailure,
+ *       fallback?: string },
+ *   remove(logicalName: string): { ok: true } |
+ *     { ok: false, error: import("../../contracts/errors.js").ApiFailure }
  * }} StoragePort
  */
 

src/contracts/query-keys.js

@@ -0,0 +1,36 @@
+const RESOURCE_NAMESPACE = Object.freeze(["resource", 1]);
+
+export const queryKeys = Object.freeze({
+  resource: Object.freeze({
+    all: () => RESOURCE_NAMESPACE,
+    list: (filters = {}) =>
+      Object.freeze([...RESOURCE_NAMESPACE, "list", canonicalize(filters)]),
+    /** @param {string} resourceId */
+    detail: (resourceId) =>
+      Object.freeze([...RESOURCE_NAMESPACE, "detail", String(resourceId)]),
+  }),
+});
+
+export const QUERY_REGISTRY = Object.freeze({
+  RESOURCE: Object.freeze({
+    namespace: RESOURCE_NAMESPACE,
+    serialization: "canonical-object-order",
+    identity: "no-pii-token-or-raw-url",
+    invalidation: "resource namespace after successful mutation",
+    version: 1,
+    persistence: "disabled",
+  }),
+});
+
+/** @param {unknown} value @returns {unknown} */
+export function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonicalize(item)]),
+    );
+  }
+  return value;
+}

src/contracts/storage-keys.js

@@ -0,0 +1,102 @@
+const APP_NAMESPACE = "ca-frontend";
+
+export const STORAGE_REGISTRY = Object.freeze({
+  COLOR_SCHEME: defineStorageKey({
+    logicalName: "COLOR_SCHEME",
+    scope: "preference",
+    name: "color-scheme",
+    backend: "localStorage",
+    classification: "public-preference",
+    schemaVersion: 1,
+    ttl: null,
+    migration: "discard",
+    quotaFallback: "memory",
+  }),
+  CHUNK_RELOAD_GUARD: defineStorageKey({
+    logicalName: "CHUNK_RELOAD_GUARD",
+    scope: "release",
+    name: "chunk-reload-guard",
+    backend: "sessionStorage",
+    classification: "opaque-cache",
+    schemaVersion: 1,
+    ttl: "session",
+    migration: "discard",
+    quotaFallback: "no-persist",
+  }),
+  QUERY_PERSISTENCE: defineStorageKey({
+    logicalName: "QUERY_PERSISTENCE",
+    scope: "cache",
+    name: "query-persistence",
+    backend: "disabled",
+    classification: "sensitive-forbidden",
+    schemaVersion: 1,
+    ttl: null,
+    migration: "discard",
+    quotaFallback: "feature-disable",
+  }),
+  AUTH_TOKEN: defineStorageKey({
+    logicalName: "AUTH_TOKEN",
+    scope: "auth",
+    name: "auth-token",
+    backend: "forbidden",
+    classification: "sensitive-forbidden",
+    schemaVersion: 1,
+    ttl: null,
+    migration: "discard",
+    quotaFallback: "feature-disable",
+  }),
+});
+
+/**
+ * @typedef {{
+ *   logicalName: string,
+ *   scope: string,
+ *   name: string,
+ *   backend: "memory" | "sessionStorage" | "localStorage" | "indexedDB" |
+ *     "disabled" | "forbidden",
+ *   classification: "public-preference" | "opaque-cache" | "sensitive-forbidden",
+ *   schemaVersion: number,
+ *   ttl: number | "session" | null,
+ *   migration: "discard" | ((value: unknown) => unknown),
+ *   quotaFallback: "memory" | "no-persist" | "feature-disable"
+ * }} StorageKeyInput
+ */
+
+/** @param {StorageKeyInput} definition */
+export function defineStorageKey(definition) {
+  if (definition.classification === "sensitive-forbidden") {
+    if (!["disabled", "forbidden"].includes(definition.backend)) {
+      throw new Error("Sensitive client storage registration is forbidden");
+    }
+  }
+  if (!Number.isInteger(definition.schemaVersion) || definition.schemaVersion < 1) {
+    throw new Error("Storage schemaVersion must be a positive integer");
+  }
+
+  return Object.freeze({
+    ...definition,
+    physicalKey: buildPhysicalKey(
+      definition.scope,
+      definition.schemaVersion,
+      definition.name,
+    ),
+  });
+}
+
+/** @param {string} scope @param {number} schemaVersion @param {string} name */
+export function buildPhysicalKey(scope, schemaVersion, name) {
+  return `${APP_NAMESPACE}:${scope}:v${schemaVersion}:${name}`;
+}
+
+/** @param {string} logicalName */
+export function getStorageDefinition(logicalName) {
+  const registry = /** @type {Record<string, ReturnType<typeof defineStorageKey>>} */ (
+    STORAGE_REGISTRY
+  );
+  const definition = registry[logicalName];
+  if (!definition) throw new Error(`Unregistered storage key: ${logicalName}`);
+  if (definition.classification === "sensitive-forbidden") {
+    throw new Error(`Forbidden storage key: ${logicalName}`);
+  }
+  return definition;
+}

src/contracts/telemetry.js

@@ -0,0 +1,145 @@
+export const TELEMETRY_ATTRIBUTE_ALLOWLIST = Object.freeze([
+  "app_version",
+  "build_id",
+  "release_id",
+  "config_schema_version",
+  "api_contract_version",
+  "route_id",
+  "operation_id",
+  "error_kind",
+  "http_status_group",
+  "attempt_count_bucket",
+  "duration_bucket",
+  "component_boundary",
+  "active_release_id",
+  "mismatch_kind",
+  "reason",
+  "queue_size_bucket",
+]);
+
+export const TELEMETRY_FORBIDDEN_ATTRIBUTES = Object.freeze([
+  "access_token",
+  "refresh_token",
+  "authorization_header",
+  "cookie",
+  "email",
+  "user_name",
+  "raw_user_id",
+  "raw_url",
+  "query_string",
+  "request_body",
+  "response_body",
+  "storage_value",
+  "stack_in_user_message",
+]);
+
+/**
+ * @typedef {{
+ *   eventName: string,
+ *   trigger: string,
+ *   requiredAttributes: readonly string[],
+ *   optionalAttributes: readonly string[],
+ *   forbiddenAttributes: readonly string[],
+ *   sampling: string,
+ *   delivery: string
+ * }} TelemetryDefinition
+ */
+
+/**
+ * @param {string} eventName
+ * @param {string} trigger
+ * @param {string[]} requiredAttributes
+ * @param {string[]} [optionalAttributes]
+ * @param {string} [sampling]
+ * @returns {Readonly<TelemetryDefinition>}
+ */
+const event = (
+  eventName,
+  trigger,
+  requiredAttributes,
+  optionalAttributes = [],
+  sampling = "all",
+) =>
+  Object.freeze({
+    eventName,
+    trigger,
+    requiredAttributes: Object.freeze(requiredAttributes),
+    optionalAttributes: Object.freeze(optionalAttributes),
+    forbiddenAttributes: TELEMETRY_FORBIDDEN_ATTRIBUTES,
+    sampling,
+    delivery: "best-effort",
+  });
+
+export const TELEMETRY_REGISTRY = Object.freeze({
+  "app.boot.failed": event("app.boot.failed", "boot validation failure", [
+    "error_kind",
+    "build_id",
+    "config_schema_version",
+  ]),
+  "api.request.failed": event("api.request.failed", "terminal API failure", [
+    "error_kind",
+    "http_status_group",
+    "attempt_count_bucket",
+    "route_id",
+  ]),
+  "ui.render.failed": event("ui.render.failed", "React boundary catch", [
+    "route_id",
+    "build_id",
+    "component_boundary",
+  ]),
+  "release.mismatch.detected": event(
+    "release.mismatch.detected",
+    "release tuple mismatch",
+    ["build_id", "active_release_id", "mismatch_kind"],
+  ),
+  "telemetry.delivery.dropped": event(
+    "telemetry.delivery.dropped",
+    "queue or sink failure",
+    ["reason", "queue_size_bucket"],
+    [],
+    "internal-counter",
+  ),
+});
+
+/**
+ * @param {string} eventName
+ * @param {Record<string, unknown>} attributes
+ */
+export function projectTelemetryEvent(eventName, attributes) {
+  const registry =
+    /** @type {Record<string, (typeof TELEMETRY_REGISTRY)[keyof typeof TELEMETRY_REGISTRY]>} */ (
+      TELEMETRY_REGISTRY
+    );
+  const definition = registry[eventName];
+  if (!definition) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "unregistered-event",
+    };
+  }
+
+  const projected = Object.fromEntries(
+    Object.entries(attributes).filter(
+      ([key]) =>
+        TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
+        !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key),
+    ),
+  );
+  const missing = definition.requiredAttributes.filter(
+    (key) => projected[key] === undefined,
+  );
+  if (missing.length > 0) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "missing-required-attributes",
+    };
+  }
+
+  return {
+    success: /** @type {true} */ (true),
+    event: Object.freeze({
+      eventName,
+      attributes: Object.freeze(projected),
+    }),
+  };
+}

tests/integration/auth-recovery.test.js

@@ -0,0 +1,103 @@
+import { HttpResponse, http } from "msw";
+import { setupServer } from "msw/node";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+
+import { createExternalAuthSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
+import { createHttpClient } from "../../src/adapters/http/client.js";
+
+let responseStatuses = [];
+const server = setupServer(
+  http.get("https://api.test/api/sample/resources", () => {
+    const status = responseStatuses.shift() ?? 200;
+    if (status === 401) {
+      return HttpResponse.json(
+        {
+          success: false,
+          error: { code: "UNAUTHENTICATED" },
+          meta: { requestId: "request-1", traceId: "trace-1" },
+        },
+        { status },
+      );
+    }
+    return HttpResponse.json({
+      success: true,
+      data: [{ id: "resource-1", name: "Example" }],
+      meta: { requestId: "request-2", traceId: "trace-1" },
+    });
+  }),
+);
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => {
+  responseStatuses = [];
+  server.resetHandlers();
+});
+afterAll(() => server.close());
+
+const clock = { now: () => 0, sleep: async () => {} };
+
+describe("bounded 401 session recovery", () => {
+  it("calls recovery once and replays a safe request once", async () => {
+    responseStatuses = [401, 200];
+    const recoverSession = vi.fn(async () => "restored");
+    const authSession = createExternalAuthSessionAdapter({
+      readState: () => "authenticated",
+      attachCredential: async (request) => request,
+      recoverSession,
+      notifyUnauthenticated: vi.fn(),
+    });
+    const client = createHttpClient({
+      baseUrl: "https://api.test",
+      authSession,
+      clock,
+    });
+
+    await expect(client.execute("LIST_SAMPLE_RESOURCES")).resolves.toMatchObject({
+      ok: true,
+    });
+    expect(recoverSession).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops after a second 401 and notifies unauthenticated once", async () => {
+    responseStatuses = [401, 401];
+    const notifyUnauthenticated = vi.fn();
+    const authSession = createExternalAuthSessionAdapter({
+      readState: () => "authenticated",
+      attachCredential: async (request) => request,
+      recoverSession: async () => "restored",
+      notifyUnauthenticated,
+    });
+    const client = createHttpClient({
+      baseUrl: "https://api.test",
+      authSession,
+      clock,
+    });
+
+    await expect(client.execute("LIST_SAMPLE_RESOURCES")).resolves.toMatchObject({
+      ok: false,
+      error: { kind: "AUTH_REQUIRED" },
+    });
+    expect(notifyUnauthenticated).toHaveBeenCalledTimes(1);
+  });
+
+  it("normalizes attach and invalid recovery failures", async () => {
+    const attachFailure = createExternalAuthSessionAdapter({
+      readState: () => "authenticated",
+      attachCredential: async () => {
+        throw new Error("credential detail");
+      },
+      recoverSession: async () => "restored",
+      notifyUnauthenticated: vi.fn(),
+    });
+    const client = createHttpClient({
+      baseUrl: "https://api.test",
+      authSession: attachFailure,
+      clock,
+    });
+
+    await expect(client.execute("LIST_SAMPLE_RESOURCES")).resolves.toMatchObject({
+      ok: false,
+      error: { kind: "AUTH_INTEGRATION_FAILURE" },
+    });
+  });
+});

tests/unit/auth-session-adapter.test.js

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createAnonymousSessionAdapter,
+  createExternalAuthSessionAdapter,
+} from "../../src/adapters/auth/external-session-adapter.js";
+
+describe("external AuthSessionPort adapter", () => {
+  it("attaches opaque credentials without exposing a token-shaped session", async () => {
+    const adapter = createExternalAuthSessionAdapter({
+      readState: () => "authenticated",
+      attachCredential: async (request) => {
+        const headers = new Headers(request.headers);
+        headers.set("X-Session-Attached", "true");
+        return new Request(request, { headers });
+      },
+      recoverSession: async () => "restored",
+      notifyUnauthenticated: vi.fn(),
+    });
+
+    const request = await adapter.attach(new Request("https://api.test/resource"));
+    expect(request.headers.get("X-Session-Attached")).toBe("true");
+    expect(adapter.getState()).toBe("authenticated");
+    expect(adapter).not.toHaveProperty("accessToken");
+    expect(adapter).not.toHaveProperty("refreshToken");
+  });
+
+  it("fails invalid recovery states closed", async () => {
+    const adapter = createExternalAuthSessionAdapter({
+      readState: () => "authenticated",
+      attachCredential: async (request) => request,
+      recoverSession: async () => "unexpected",
+      notifyUnauthenticated: vi.fn(),
+    });
+
+    await expect(adapter.recover()).rejects.toThrow("invalid recovery state");
+  });
+
+  it("provides a safe anonymous adapter", async () => {
+    const adapter = createAnonymousSessionAdapter();
+    expect(adapter.getState()).toBe("unauthenticated");
+    await expect(adapter.recover()).resolves.toBe("no-session");
+  });
+});

tests/unit/query-cache.test.js

@@ -0,0 +1,55 @@
+import { QueryClient } from "@tanstack/react-query";
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createQueryCacheAdapter,
+  createQueryClient,
+} from "../../src/adapters/query-cache/tanstack-query-cache.js";
+import { queryKeys } from "../../src/contracts/query-keys.js";
+
+describe("query key registry", () => {
+  it("canonicalizes filter order into the same stable key", () => {
+    expect(queryKeys.resource.list({ page: 1, status: "open" })).toEqual(
+      queryKeys.resource.list({ status: "open", page: 1 }),
+    );
+  });
+
+  it("contains no raw URL or token material", () => {
+    expect(JSON.stringify(queryKeys.resource.detail("resource-1"))).toBe(
+      '["resource",1,"detail","resource-1"]',
+    );
+  });
+});
+
+describe("TanStack QueryCachePort adapter", () => {
+  it("reads, writes, and invalidates only the declared namespace", async () => {
+    const client = createQueryClient();
+    const adapter = createQueryCacheAdapter(client);
+    const listKey = queryKeys.resource.list({ page: 1 });
+    const otherKey = ["other", 1];
+
+    expect(adapter.write(listKey, [{ id: "resource-1" }])).toEqual({ ok: true });
+    expect(adapter.write(otherKey, "preserved")).toEqual({ ok: true });
+    expect(adapter.read(listKey)).toMatchObject({
+      ok: true,
+      value: [{ id: "resource-1" }],
+    });
+
+    await adapter.invalidate(queryKeys.resource.all());
+    expect(client.getQueryState(listKey)?.isInvalidated).toBe(true);
+    expect(client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+  });
+
+  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 result = await adapter.invalidate(["resource", "sensitive-filter"]);
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: { kind: "QUERY_CACHE_FAILURE" },
+    });
+    expect(JSON.stringify(result)).not.toContain("sensitive-filter");
+  });
+});

tests/unit/storage-registry.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+
+import { createBrowserStorageAdapter } from "../../src/adapters/storage/browser-storage-adapter.js";
+import {
+  STORAGE_REGISTRY,
+  buildPhysicalKey,
+  defineStorageKey,
+} from "../../src/contracts/storage-keys.js";
+
+function createStorage({ quota = false } = {}) {
+  const values = new Map();
+  return {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => {
+      if (quota) throw new DOMException("full", "QuotaExceededError");
+      values.set(key, value);
+    },
+    removeItem: (key) => values.delete(key),
+    clear: () => values.clear(),
+    key: () => null,
+    get length() {
+      return values.size;
+    },
+  };
+}
+
+describe("storage registry", () => {
+  it("builds namespace and schema-versioned physical keys", () => {
+    expect(buildPhysicalKey("preference", 2, "theme")).toBe(
+      "ca-frontend:preference:v2:theme",
+    );
+    expect(STORAGE_REGISTRY.COLOR_SCHEME.physicalKey).toContain(":v1:");
+  });
+
+  it("rejects token or secret persistence registrations", () => {
+    expect(() =>
+      defineStorageKey({
+        logicalName: "TOKEN",
+        scope: "auth",
+        name: "token",
+        backend: "localStorage",
+        classification: "sensitive-forbidden",
+        schemaVersion: 1,
+        ttl: null,
+        migration: "discard",
+        quotaFallback: "feature-disable",
+      }),
+    ).toThrow("Sensitive client storage registration is forbidden");
+  });
+
+  it("round-trips public preferences through the adapter", () => {
+    const localStorage = createStorage();
+    const adapter = createBrowserStorageAdapter({ localStorage });
+    expect(adapter.write("COLOR_SCHEME", "dark")).toEqual({ ok: true });
+    expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" });
+  });
+
+  it("falls back to memory when preference storage quota is exceeded", () => {
+    const localStorage = createStorage({ quota: true });
+    const adapter = createBrowserStorageAdapter({ localStorage });
+    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" });
+  });
+
+  it("discards data from a previous schema version", () => {
+    const localStorage = createStorage();
+    localStorage.setItem(
+      STORAGE_REGISTRY.COLOR_SCHEME.physicalKey,
+      JSON.stringify({ schemaVersion: 0, value: "dark" }),
+    );
+    const adapter = createBrowserStorageAdapter({ localStorage });
+    expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: undefined });
+  });
+});

tests/unit/telemetry.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createTelemetryAdapter,
+  safeTraceparent,
+} from "../../src/adapters/telemetry/best-effort-telemetry.js";
+import {
+  TELEMETRY_REGISTRY,
+  projectTelemetryEvent,
+} from "../../src/contracts/telemetry.js";
+
+const validAttributes = {
+  error_kind: "SERVER_FAILURE",
+  http_status_group: "5xx",
+  attempt_count_bucket: "3",
+  route_id: "SAMPLE_RESOURCE_LIST",
+};
+
+describe("telemetry registry and redaction", () => {
+  it("defines all event contract fields", () => {
+    for (const definition of Object.values(TELEMETRY_REGISTRY)) {
+      expect(definition).toEqual(
+        expect.objectContaining({
+          eventName: expect.any(String),
+          trigger: expect.any(String),
+          requiredAttributes: expect.any(Array),
+          optionalAttributes: expect.any(Array),
+          forbiddenAttributes: expect.any(Array),
+          sampling: expect.any(String),
+          delivery: "best-effort",
+        }),
+      );
+    }
+  });
+
+  it("uses a default-deny attribute projection", () => {
+    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/);
+  });
+
+  it("validates traceparent without exposing invalid values", () => {
+    expect(
+      safeTraceparent(
+        "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+      ),
+    ).toBe("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
+    expect(safeTraceparent("Bearer secret")).toBeNull();
+  });
+});
+
+describe("best-effort telemetry adapter", () => {
+  it("bounds the queue using oldest-drop without blocking callers", () => {
+    const scheduled = [];
+    const adapter = createTelemetryAdapter({
+      enabled: true,
+      endpoint: "https://telemetry.test/events",
+      maxQueue: 2,
+      schedule: (callback) => scheduled.push(callback),
+      fetcher: vi.fn(),
+    });
+
+    adapter.emit("api.request.failed", validAttributes);
+    adapter.emit("api.request.failed", validAttributes);
+    adapter.emit("api.request.failed", validAttributes);
+
+    expect(adapter.pendingCount()).toBe(2);
+    expect(adapter.droppedCount()).toBe(1);
+    expect(scheduled).toHaveLength(1);
+  });
+
+  it("degrades on sink failure without throwing or recursive events", async () => {
+    const adapter = createTelemetryAdapter({
+      enabled: true,
+      endpoint: "https://telemetry.test/events",
+      schedule: () => {},
+      fetcher: async () => {
+        throw new Error("sink unavailable");
+      },
+    });
+    expect(() => adapter.emit("api.request.failed", validAttributes)).not.toThrow();
+    await expect(adapter.flush()).resolves.toBeUndefined();
+    expect(adapter.droppedCount()).toBe(1);
+    expect(adapter.pendingCount()).toBe(0);
+  });
+
+  it("performs no network or queue work when disabled", async () => {
+    const fetcher = vi.fn();
+    const adapter = createTelemetryAdapter({
+      enabled: false,
+      endpoint: "https://telemetry.test/events",
+      fetcher,
+    });
+    adapter.emit("api.request.failed", validAttributes);
+    await adapter.flush();
+
+    expect(fetcher).not.toHaveBeenCalled();
+    expect(adapter.pendingCount()).toBe(0);
+  });
+});