@mrclrchtr/supi-lsp 4.8.0 → 4.10.0

package/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -48,7 +48,7 @@ Config file locations:
 ### Shared registries
 
 - context-provider registry for `/supi-context`
-- debug-event registry for producers that want shared debug capture
+- debug-event registry and monotonic phase timers for producers that want shared debug capture
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers
@@ -108,5 +108,7 @@ export default function myExtension(pi: ExtensionAPI) {
 
 - `src/api.ts` — exported library surface
 - `src/config.ts` — shared config loading and writing
+- `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
+- `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
 - `src/settings/` — settings registry, schema, scope resolution, and persistence
 - `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -4,6 +4,9 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";
+
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {
@@ -180,6 +183,11 @@ export function getDebugRegistryConfig(): DebugRegistryConfig {
   return cloneConfig(getState().config);
 }
 
+/** Return whether the Debug Registry currently retains producer events. */
+export function isDebugRegistryEnabled(): boolean {
+  return getState().config.enabled;
+}
+
 /** Best-effort redaction helper for data exposed through sanitized debug views. */
 export function redactDebugData<T>(value: T): T {
   return redactValue(value, 8) as T;

package/node_modules/@mrclrchtr/supi-core/src/debug-timing.ts

@@ -0,0 +1,120 @@
+import { performance } from "node:perf_hooks";
+import {
+  type DebugEvent,
+  type DebugEventInput,
+  isDebugRegistryEnabled,
+  recordDebugEvent,
+} from "./debug-registry.ts";
+
+/** Monotonic duration data added to a timed debug event. */
+export interface DebugTiming {
+  readonly durationMs: number;
+  readonly phasesMs: Readonly<Record<string, number>>;
+}
+
+/** Debug event input whose data can receive the reserved `timing` field. */
+export interface TimedDebugEventInput extends Omit<DebugEventInput, "data"> {
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+/** Test seam for the monotonic clock used by a debug timer. */
+export interface DebugTimerOptions {
+  readonly now?: () => number;
+}
+
+/** Lazy timed-event input that is not evaluated when Debug is disabled. */
+export type TimedDebugEventFactory = () => TimedDebugEventInput;
+
+/** One-shot debug timer with optional sequential phase measurements. */
+export interface DebugTimer {
+  /** Whether this timer sampled Debug as enabled when it started. */
+  readonly enabled: boolean;
+  /** Finish the current phase and start the next unnamed interval. */
+  mark(phase: string): void;
+  /** Record one event. A second call returns `null` without recording another event. */
+  finish(
+    input: TimedDebugEventInput | TimedDebugEventFactory,
+    finalPhase?: string,
+  ): DebugEvent | null;
+}
+
+/**
+ * Start a monotonic timer for one debug event.
+ *
+ * Each `mark(name)` stores the interval since the previous mark. `finish()`
+ * stores the total duration and can name the final interval. Repeated phase
+ * names are accumulated. Event data reserves the `timing` field. When Debug is
+ * disabled at start, this returns a no-op timer and does not read the clock.
+ * Pass a factory to `finish()` to avoid event-data construction when disabled.
+ * Clock, event-construction, and registry failures are isolated from the
+ * measured operation and make the timer a no-op.
+ */
+export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
+  if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
+  const now = options.now ?? performance.now.bind(performance);
+  let startedAt: number;
+  try {
+    startedAt = now();
+  } catch {
+    return DISABLED_DEBUG_TIMER;
+  }
+  let previousAt = startedAt;
+  let finished = false;
+  let failed = false;
+  const phases = new Map<string, number>();
+
+  const markAt = (phase: string, current: number): void => {
+    const name = phase.trim();
+    if (!name) return;
+    phases.set(name, (phases.get(name) ?? 0) + Math.max(0, current - previousAt));
+    previousAt = current;
+  };
+
+  return {
+    enabled: true,
+    mark(phase) {
+      if (finished || failed) return;
+      try {
+        markAt(phase, now());
+      } catch {
+        failed = true;
+      }
+    },
+    finish(input, finalPhase) {
+      if (finished || failed) return null;
+      finished = true;
+      try {
+        if (!isDebugRegistryEnabled()) return null;
+        const completedAt = now();
+        if (finalPhase) markAt(finalPhase, completedAt);
+        const phasesMs = Object.fromEntries(
+          [...phases.entries()].map(([name, value]) => [name, duration(value)]),
+        );
+        const timing: DebugTiming = {
+          durationMs: duration(completedAt - startedAt),
+          phasesMs,
+        };
+        const eventInput = typeof input === "function" ? input() : input;
+        return recordDebugEvent({
+          ...eventInput,
+          data: { ...eventInput.data, timing },
+        });
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+const DISABLED_DEBUG_TIMER: DebugTimer = Object.freeze({
+  enabled: false,
+  mark() {},
+  finish() {
+    return null;
+  },
+});
+
+function duration(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(Math.max(0, value) * 10) / 10;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "Language Server Protocol runtime for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
     "vscode-jsonrpc": "^9.0.0",
     "vscode-languageserver-protocol": "^3.17.5",
     "vscode-languageserver-types": "^3.17.5",
-    "@mrclrchtr/supi-code-runtime": "4.8.0",
-    "@mrclrchtr/supi-core": "4.8.0"
+    "@mrclrchtr/supi-code-runtime": "4.10.0",
+    "@mrclrchtr/supi-core": "4.10.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/src/client/client-diagnostic-timing.ts

@@ -0,0 +1,155 @@
+import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
+
+type DiagnosticCollection = "fallback" | "none" | "pull" | "push";
+type DiagnosticFreshness = "not-observed" | "observed";
+type DiagnosticOutcome = "completed" | "skipped" | "timed-out";
+type DiagnosticPullOutcome = "completed" | "failed" | "not-supported" | "not-used" | "timed-out";
+type DiagnosticPushOutcome = "not-used" | "published" | "released" | "settled" | "timed-out";
+type DiagnosticSettleOutcome = "not-used" | "published" | "quiet" | "released" | "timed-out";
+type DiagnosticTimingOperation = "refresh-open" | "sync-file";
+
+/** Result of waiting for a quiet push-diagnostic window. */
+export interface DiagnosticSettleResult {
+  readonly outcome: "quiet" | "timed-out";
+  readonly freshness: DiagnosticFreshness;
+}
+
+/** Result of waiting for one file's push diagnostics. */
+export type DiagnosticPushWaitOutcome = "published" | "released" | "timed-out";
+
+interface DiagnosticTimingData {
+  readonly collection: DiagnosticCollection;
+  readonly documentCount: number;
+  readonly fallback: boolean;
+  readonly freshness: DiagnosticFreshness;
+  readonly outcome: DiagnosticOutcome;
+  readonly pull: DiagnosticPullOutcome;
+  readonly push: DiagnosticPushOutcome;
+  readonly settle: DiagnosticSettleOutcome;
+  readonly timedOut: boolean;
+}
+
+/** Internal pull failure that retains only whether a timeout occurred. */
+export class DiagnosticPullError extends Error {
+  constructor(readonly timedOut: boolean) {
+    super("pull diagnostics incomplete");
+  }
+}
+
+/**
+ * Record one diagnostic operation without document identifiers or diagnostic text.
+ *
+ * The observer owns result classification so diagnostic control flow does not
+ * duplicate the event shape.
+ */
+export class DiagnosticObserver {
+  readonly #timer = startDebugTimer();
+  #pull: "failed" | "not-supported" | "timed-out";
+
+  constructor(
+    readonly operation: DiagnosticTimingOperation,
+    readonly supportsPull: boolean,
+  ) {
+    this.#pull = supportsPull ? "failed" : "not-supported";
+  }
+
+  synchronized(): void {
+    this.#timer.mark("synchronize");
+  }
+
+  skipped(documentCount: number): void {
+    this.#finish({
+      collection: "none",
+      documentCount,
+      fallback: false,
+      freshness: "not-observed",
+      outcome: "skipped",
+      pull: "not-used",
+      push: "not-used",
+      settle: "not-used",
+      timedOut: false,
+    });
+  }
+
+  pullCompleted(documentCount: number): void {
+    this.#finish(
+      {
+        collection: "pull",
+        documentCount,
+        fallback: false,
+        freshness: "observed",
+        outcome: "completed",
+        pull: "completed",
+        push: "not-used",
+        settle: "not-used",
+        timedOut: false,
+      },
+      "pull",
+    );
+  }
+
+  pullFailed(error: unknown): void {
+    this.#pull = isDiagnosticTimeout(error) ? "timed-out" : "failed";
+    this.#timer.mark("pull");
+  }
+
+  pullTimedOut(): void {
+    this.#pull = "timed-out";
+    this.#timer.mark("pull");
+  }
+
+  pushSettled(documentCount: number, settle: DiagnosticSettleResult): void {
+    const timedOut = settle.outcome === "timed-out";
+    this.#finish(
+      {
+        collection: this.supportsPull ? "fallback" : "push",
+        documentCount,
+        fallback: this.supportsPull,
+        freshness: settle.freshness,
+        outcome: timedOut ? "timed-out" : "completed",
+        pull: this.#pull,
+        push: timedOut ? "timed-out" : "settled",
+        settle: settle.outcome,
+        timedOut: timedOut || this.#pull === "timed-out",
+      },
+      "push-settle",
+    );
+  }
+
+  pushWaitCompleted(documentCount: number, push: DiagnosticPushWaitOutcome): void {
+    const timedOut = push === "timed-out";
+    this.#finish(
+      {
+        collection: this.supportsPull ? "fallback" : "push",
+        documentCount,
+        fallback: this.supportsPull,
+        freshness: push === "published" ? "observed" : "not-observed",
+        outcome: timedOut ? "timed-out" : "completed",
+        pull: this.#pull,
+        push,
+        settle: push,
+        timedOut: timedOut || this.#pull === "timed-out",
+      },
+      "push-settle",
+    );
+  }
+
+  #finish(data: DiagnosticTimingData, finalPhase?: "pull" | "push-settle" | "synchronize"): void {
+    this.#timer.finish(
+      () => ({
+        source: "lsp",
+        level: "debug",
+        category: "diagnostics.timing",
+        message: `LSP diagnostic ${this.operation} ${data.outcome}`,
+        data: { operation: this.operation, ...data },
+      }),
+      finalPhase,
+    );
+  }
+}
+
+/** Return whether a diagnostic failure represents a timeout without retaining its message. */
+export function isDiagnosticTimeout(error: unknown): boolean {
+  if (error instanceof DiagnosticPullError) return error.timedOut;
+  return error instanceof Error && /\btimed? ?out\b|\btimeout\b/i.test(error.message);
+}

package/src/client/client-diagnostics.ts

@@ -10,10 +10,18 @@ import type {
   VersionedTextDocumentIdentifier,
 } from "../config/types.ts";
 import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
+import {
+  DiagnosticObserver,
+  DiagnosticPullError,
+  type DiagnosticPushWaitOutcome,
+  type DiagnosticSettleResult,
+  isDiagnosticTimeout,
+} from "./client-diagnostic-timing.ts";
 
 const DIAGNOSTIC_WAIT_MS = 3_000;
 
 type OpenDocument = { version: number };
+type DiagnosticWaiter = (outcome: "published" | "released") => void;
 
 type DiagnosticCacheEntry = {
   diagnostics: Diagnostic[];
@@ -48,7 +56,7 @@ interface ClientDiagnosticsHost {
 export class ClientDiagnostics {
   readonly #openDocs = new Map<string, OpenDocument>();
   readonly #diagnosticStore = new Map<string, DiagnosticCacheEntry>();
-  readonly #diagnosticWaiters = new Map<string, Array<() => void>>();
+  readonly #diagnosticWaiters = new Map<string, DiagnosticWaiter[]>();
 
   constructor(private readonly host: ClientDiagnosticsHost) {}
 
@@ -160,53 +168,72 @@ export class ClientDiagnostics {
       receivedAt: Date.now(),
       version: params.version ?? undefined,
     });
-    this.#releaseDiagnosticWaiters(params.uri);
+    this.#releaseDiagnosticWaiters(params.uri, "published");
   }
 
   /** Re-read open documents, then collect pull diagnostics or wait for push diagnostics. */
   async refreshOpenDiagnostics(
     options: { maxWaitMs?: number; quietMs?: number } = {},
   ): Promise<void> {
-    if (!this.host.isOperational()) return;
+    const supportsPull = this.host.supportsPullDiagnostics();
+    const observer = new DiagnosticObserver("refresh-open", supportsPull);
+    if (!this.host.isOperational()) {
+      observer.skipped(0);
+      return;
+    }
 
     const maxWaitMs = options.maxWaitMs ?? 3_000;
     const quietMs = options.quietMs ?? 200;
     const syncStart = Date.now();
-
     this.#resyncOpenDocuments();
-    if (this.#openDocs.size === 0) return;
+    observer.synchronized();
+    const documentCount = this.#openDocs.size;
+    if (documentCount === 0) {
+      observer.skipped(0);
+      return;
+    }
 
-    if (this.host.supportsPullDiagnostics()) {
+    if (supportsPull) {
       try {
         await this.#pullDiagnosticsForOpenDocuments(syncStart, maxWaitMs);
+        observer.pullCompleted(documentCount);
         return;
-      } catch {
-        // Pull diagnostics failed. Wait for push diagnostics instead.
+      } catch (error) {
+        observer.pullFailed(error);
       }
     }
 
-    await this.#waitForDiagnosticSettle(syncStart, maxWaitMs, quietMs);
+    const settle = await this.#waitForDiagnosticSettle(syncStart, maxWaitMs, quietMs);
+    observer.pushSettled(documentCount, settle);
   }
 
   /** Sync one file and return its diagnostics after pull or push collection. */
   async syncAndWaitForDiagnostics(filePath: string, content: string): Promise<Diagnostic[]> {
+    const supportsPull = this.host.supportsPullDiagnostics();
+    const observer = new DiagnosticObserver("sync-file", supportsPull);
     const uri = fileToUri(filePath);
     const syncStart = Date.now();
     this.didChange(filePath, content);
+    observer.synchronized();
 
-    if (this.host.supportsPullDiagnostics()) {
+    if (supportsPull) {
       const remaining = DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart);
-      if (remaining > 0) {
-        try {
-          const pulled = await this.#pullDiagnosticsForUri(uri, remaining);
-          if (pulled) return this.getDiagnostics(filePath);
-        } catch {
-          // Pull diagnostics failed. Wait for push diagnostics instead.
-        }
+      try {
+        if (remaining <= 0) observer.pullTimedOut();
+        else if (await this.#pullDiagnosticsForUri(uri, remaining)) {
+          observer.pullCompleted(1);
+          return this.getDiagnostics(filePath);
+        } else observer.pullFailed(undefined);
+      } catch (error) {
+        observer.pullFailed(error);
       }
     }
 
-    await this.#waitForDiagnostics(uri, Math.max(0, DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart)));
+    const push = await this.#waitForDiagnostics(
+      uri,
+      Math.max(0, DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart)),
+    );
+    observer.pushWaitCompleted(1, push);
     return this.getDiagnostics(filePath);
   }
 
@@ -240,9 +267,9 @@ export class ClientDiagnostics {
     );
 
     const anySuccess = results.some((result) => result.status === "fulfilled" && result.value);
-    const hadFailure = results.some((result) => result.status === "rejected");
-    if ((hadFailure || !anySuccess) && uris.length > 0) {
-      throw new Error("pull diagnostics incomplete");
+    const failures = results.filter((result) => result.status === "rejected");
+    if ((failures.length > 0 || !anySuccess) && uris.length > 0) {
+      throw new DiagnosticPullError(failures.some((result) => isDiagnosticTimeout(result.reason)));
     }
   }
 
@@ -280,16 +307,25 @@ export class ClientDiagnostics {
     syncStart: number,
     maxWaitMs: number,
     quietMs: number,
-  ): Promise<void> {
+  ): Promise<DiagnosticSettleResult> {
     const deadline = syncStart + maxWaitMs;
     while (Date.now() < deadline) {
-      const lastReceived = this.#lastDiagnosticReceivedAfter(syncStart) || syncStart;
-      const elapsed = Date.now() - lastReceived;
-      if (elapsed >= quietMs) return;
+      const observedAt = this.#lastDiagnosticReceivedAfter(syncStart);
+      const elapsed = Date.now() - (observedAt || syncStart);
+      if (elapsed >= quietMs) {
+        return {
+          outcome: "quiet",
+          freshness: observedAt > 0 ? "observed" : "not-observed",
+        };
+      }
       await new Promise((resolve) =>
         setTimeout(resolve, Math.min(quietMs - elapsed, deadline - Date.now(), 50)),
       );
     }
+    return {
+      outcome: "timed-out",
+      freshness: this.#lastDiagnosticReceivedAfter(syncStart) > 0 ? "observed" : "not-observed",
+    };
   }
 
   #lastDiagnosticReceivedAfter(afterTime: number): number {
@@ -319,18 +355,18 @@ export class ClientDiagnostics {
     this.#releaseDiagnosticWaiters(uri);
   }
 
-  #waitForDiagnostics(uri: string, timeoutMs: number): Promise<void> {
-    if (timeoutMs <= 0) return Promise.resolve();
+  #waitForDiagnostics(uri: string, timeoutMs: number): Promise<DiagnosticPushWaitOutcome> {
+    if (timeoutMs <= 0) return Promise.resolve("timed-out");
 
-    return new Promise<void>((resolve) => {
-      const waiter = () => {
+    return new Promise<DiagnosticPushWaitOutcome>((resolve) => {
+      const waiter: DiagnosticWaiter = (outcome) => {
         clearTimeout(timer);
         this.#removeDiagnosticWaiter(uri, waiter);
-        resolve();
+        resolve(outcome);
       };
       const timer = setTimeout(() => {
         this.#removeDiagnosticWaiter(uri, waiter);
-        resolve();
+        resolve("timed-out");
       }, timeoutMs);
       const waiters = this.#diagnosticWaiters.get(uri) ?? [];
       waiters.push(waiter);
@@ -338,7 +374,7 @@ export class ClientDiagnostics {
     });
   }
 
-  #removeDiagnosticWaiter(uri: string, waiter: () => void): void {
+  #removeDiagnosticWaiter(uri: string, waiter: DiagnosticWaiter): void {
     const waiters = this.#diagnosticWaiters.get(uri);
     if (!waiters) return;
     const next = waiters.filter((entry) => entry !== waiter);
@@ -352,10 +388,10 @@ export class ClientDiagnostics {
     }
   }
 
-  #releaseDiagnosticWaiters(uri: string): void {
+  #releaseDiagnosticWaiters(uri: string, outcome: "published" | "released" = "released"): void {
     const waiters = this.#diagnosticWaiters.get(uri);
     if (!waiters) return;
     this.#diagnosticWaiters.delete(uri);
-    for (const waiter of waiters) waiter();
+    for (const waiter of waiters) waiter(outcome);
   }
 }

package/src/client/transport.ts

@@ -3,6 +3,7 @@
 // and notification/request dispatching through vscode-jsonrpc's MessageConnection.
 
 import type { Readable, Writable } from "node:stream";
+import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
 import {
   CancellationTokenSource,
   createMessageConnection,
@@ -20,6 +21,9 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 export type NotificationHandler = (method: string, params: unknown) => void;
 export type RequestHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
 
+type RequestMethodClass = "diagnostic" | "lifecycle" | "other" | "refactor" | "semantic";
+type RequestOutcome = "cancelled" | "completed" | "failed" | "timed-out";
+
 /** Re-export ResponseError so callers don't need a separate vscode-jsonrpc import. */
 const JsonRpcRequestError = ResponseError;
 
@@ -83,14 +87,23 @@ export class JsonRpcClient {
     params?: unknown,
     options?: { timeoutMs?: number },
   ): Promise<unknown> {
+    const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
+    const methodClass = classifyRequestMethod(method);
+    const timer = startDebugTimer();
     if (this.closed || !this.connection) {
+      recordRequestTiming(timer, {
+        methodClass,
+        outcome: "cancelled",
+        timeoutMs,
+        timedOut: false,
+        cancelled: true,
+      });
       return Promise.reject(new Error("JSON-RPC client is closed"));
     }
 
-    const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
     const tokenSource = new CancellationTokenSource();
-
     let timeout: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
     const timeoutError = new Error(`Request ${method} timed out after ${timeoutMs}ms`);
 
     const request = this.connection.sendRequest(method, params, tokenSource.token);
@@ -106,13 +119,43 @@ export class JsonRpcClient {
       request,
       new Promise<never>((_resolve, reject) => {
         timeout = setTimeout(() => {
+          timedOut = true;
           tokenSource.cancel();
           reject(timeoutError);
         }, timeoutMs);
       }),
-    ]).finally(() => {
-      if (timeout !== undefined) clearTimeout(timeout);
-    });
+    ])
+      .then(
+        (result) => {
+          recordRequestTiming(timer, {
+            methodClass,
+            outcome: "completed",
+            timeoutMs,
+            timedOut: false,
+            cancelled: false,
+          });
+          return result;
+        },
+        (error: unknown) => {
+          const cancelled = timedOut || this.closed || isCancellationError(error);
+          const outcome: RequestOutcome = timedOut
+            ? "timed-out"
+            : cancelled
+              ? "cancelled"
+              : "failed";
+          recordRequestTiming(timer, {
+            methodClass,
+            outcome,
+            timeoutMs,
+            timedOut,
+            cancelled,
+          });
+          throw error;
+        },
+      )
+      .finally(() => {
+        if (timeout !== undefined) clearTimeout(timeout);
+      });
 
     // Prevent unhandled rejection when dispose() cancels requests
     promise.catch(() => {});
@@ -142,3 +185,59 @@ export class JsonRpcClient {
     }
   }
 }
+
+const SEMANTIC_REQUESTS = new Set([
+  "textDocument/definition",
+  "textDocument/documentSymbol",
+  "textDocument/hover",
+  "textDocument/implementation",
+  "textDocument/references",
+  "workspace/symbol",
+]);
+
+/** Classify requests into bounded groups without retaining the raw method. */
+function classifyRequestMethod(method: string): RequestMethodClass {
+  if (method === "initialize" || method === "shutdown") return "lifecycle";
+  if (method === "textDocument/diagnostic" || method === "workspace/diagnostic") {
+    return "diagnostic";
+  }
+  if (method === "textDocument/codeAction" || method === "textDocument/rename") {
+    return "refactor";
+  }
+  return SEMANTIC_REQUESTS.has(method) ? "semantic" : "other";
+}
+
+function isCancellationError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const code = (error as Error & { code?: unknown }).code;
+  return (
+    code === -32_800 ||
+    code === -32_802 ||
+    error.name === "CancellationError" ||
+    /\bcancell?ed\b/i.test(error.message)
+  );
+}
+
+interface RequestTimingObservation {
+  readonly methodClass: RequestMethodClass;
+  readonly outcome: RequestOutcome;
+  readonly timeoutMs: number;
+  readonly timedOut: boolean;
+  readonly cancelled: boolean;
+}
+
+function recordRequestTiming(
+  timer: ReturnType<typeof startDebugTimer>,
+  observation: RequestTimingObservation,
+): void {
+  timer.finish(
+    () => ({
+      source: "lsp",
+      level: "debug",
+      category: "request.timing",
+      message: `LSP ${observation.methodClass} request ${observation.outcome}`,
+      data: { ...observation },
+    }),
+    "request",
+  );
+}