@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-diagnostics.ts

@@ -0,0 +1,92 @@
+import type { Diagnostic } from "../config/types.ts";
+import type { DiagnosticEvidenceSummary } from "../diagnostics/evidence.ts";
+
+export type {
+  DiagnosticEvidenceDocument,
+  DiagnosticEvidenceStatus,
+  DiagnosticEvidenceSummary,
+} from "../diagnostics/evidence.ts";
+
+/** Workspace diagnostic snapshot with explicit cache freshness and coverage. */
+export interface WorkspaceDiagnosticSnapshot<T> {
+  entries: T[];
+  current: boolean;
+  evidence: DiagnosticEvidenceSummary;
+}
+
+/** Workspace diagnostic summary grouped by file. */
+export interface WorkspaceDiagnosticSummaryEntry {
+  file: string;
+  errors: number;
+  warnings: number;
+}
+
+/**
+ * One coherent post-refresh observation of workspace diagnostics.
+ *
+ * Both projections are captured from the same client snapshots. The report is
+ * short-lived and must not be retained as the runtime's last refresh attempt.
+ */
+export interface WorkspaceDiagnosticReport {
+  summary: WorkspaceDiagnosticSnapshot<WorkspaceDiagnosticSummaryEntry>;
+  outstanding: WorkspaceDiagnosticSnapshot<{
+    file: string;
+    diagnostics: Diagnostic[];
+  }>;
+}
+
+/** Outstanding diagnostics grouped by file, including info and hint counts. */
+export interface OutstandingDiagnosticSummaryEntry {
+  file: string;
+  total: number;
+  errors: number;
+  warnings: number;
+  information: number;
+  hints: number;
+}
+
+/** Result from a workspace diagnostic recovery pass. */
+export interface RecoverDiagnosticsResult {
+  /** Active clients targeted by the best-effort refresh, not confirmed successful refreshes. */
+  attemptedClients: number;
+  restartedClients: number;
+  /** Evidence collected by the refresh and recovery operations. */
+  diagnosticEvidence: DiagnosticEvidenceSummary;
+  /** Final diagnostic report captured after all refresh and recovery work. */
+  diagnosticReport: WorkspaceDiagnosticReport;
+  /** Failure from the first refresh, when no later pass replaced it. */
+  refreshFailureReason?: string;
+  /** Wall-clock duration of the whole recovery pass, for telemetry. */
+  elapsedMs: number;
+  staleAssessment: {
+    suspected: boolean;
+    matchedFiles: Array<{ file: string; diagnostics: Diagnostic[] }>;
+    warning: string | null;
+  };
+}
+
+/** One tracked file's tsconfig scope decision, for debug telemetry. */
+export interface ScopeDecisionEntry {
+  /** Workspace-relative file path. */
+  file: string;
+  status: "included" | "excluded" | "no-config" | "out-of-tree";
+  /** Decision mechanism; null when no decision applies. */
+  basis: string | null;
+}
+
+/** Aggregate tsconfig scope decisions for all tracked files, for debug telemetry. */
+export interface ScopeDecisionSummary {
+  caseSensitiveFileNames: boolean;
+  counts: {
+    included: number;
+    excluded: number;
+    noConfig: number;
+    outOfTree: number;
+  };
+  /** Exact decision-basis counts; keys are {@link ScopeDecisionEntry.basis} values. */
+  basisCounts: Record<string, number>;
+  /** Bounded workspace-relative entries (oldest first), not the full set. */
+  entries: ScopeDecisionEntry[];
+  /** Total number of tracked files the summary was computed over. */
+  totalFiles: number;
+}

package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-registry.ts

@@ -1,10 +1,15 @@
 // Shared session-scoped LSP service registry reused by peer extensions.
 
+// biome-ignore lint/style/noExcessiveLinesPerFile: session registry, runtime recovery, and telemetry stay in one file; splitting would hide the recovery contract.
 import {
   type CodeQueryResult,
+  type CodeRequestControl,
+  isCodeRequestInterruption,
   mapCodeQueryResult,
+  throwIfCodeRequestInterrupted,
   unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
+import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
 import { createSessionStateRegistry } from "@mrclrchtr/supi-core/session";
 import type {
   CodeAction,
@@ -21,9 +26,35 @@ import type {
   WorkspaceEdit,
   WorkspaceSymbol,
 } from "../config/types.ts";
+import { boundServerNames, truncateIdentity } from "../debug-telemetry.ts";
 import type { LspManager } from "../manager/manager.ts";
 import { resolveSessionPath } from "../utils.ts";
 import { raceReadinessValue } from "./readiness.ts";
+import type { DiagnosticEvidenceSummary, RecoverDiagnosticsResult } from "./runtime-diagnostics.ts";
+import type {
+  RoutedMutationResponse,
+  SemanticReadinessResult,
+  WorkspaceLspRuntime,
+  WorkspaceLspRuntimeState,
+} from "./workspace-lsp-runtime.ts";
+
+export type { WorkspaceLspDiagnosticSurface } from "./runtime-diagnostic-surface.ts";
+export type {
+  DiagnosticEvidenceDocument,
+  DiagnosticEvidenceStatus,
+  DiagnosticEvidenceSummary,
+  OutstandingDiagnosticSummaryEntry,
+  RecoverDiagnosticsResult,
+  WorkspaceDiagnosticReport,
+  WorkspaceDiagnosticSnapshot,
+  WorkspaceDiagnosticSummaryEntry,
+} from "./runtime-diagnostics.ts";
+export type {
+  RoutedMutationResponse,
+  SemanticReadinessResult,
+  WorkspaceLspRuntime,
+  WorkspaceLspRuntimeState,
+} from "./workspace-lsp-runtime.ts";
 
 function isRange(value: Position | Range): value is Range {
   return "start" in value && "end" in value;
@@ -33,97 +64,31 @@ function unavailableFileQuery<T>(operation: string, file: string): CodeQueryResu
   return unavailableCodeQuery(`No routed LSP client could complete ${operation} for ${file}.`);
 }
 
-/** Workspace diagnostic summary grouped by file. */
-export interface WorkspaceDiagnosticSummaryEntry {
-  file: string;
-  errors: number;
-  warnings: number;
-}
-
-/** Outstanding diagnostics grouped by file, including info and hint counts. */
-export interface OutstandingDiagnosticSummaryEntry {
-  file: string;
-  total: number;
-  errors: number;
-  warnings: number;
-  information: number;
-  hints: number;
-}
-
-/** Result from a workspace diagnostic recovery pass. */
-export interface RecoverDiagnosticsResult {
-  /** Active clients targeted by the best-effort refresh, not confirmed successful refreshes. */
-  attemptedClients: number;
-  restartedClients: number;
-  staleAssessment: {
-    suspected: boolean;
-    matchedFiles: Array<{ file: string; diagnostics: Diagnostic[] }>;
-    warning: string | null;
-  };
-}
-
-export type WorkspaceLspRuntimeState =
-  | { kind: "ready"; runtime: WorkspaceLspRuntime }
-  | { kind: "inactive"; runtime: WorkspaceLspRuntime }
-  | { kind: "pending" }
-  | { kind: "disabled" }
-  | { kind: "unavailable"; reason: string };
-
-export type SemanticReadinessResult =
-  | { kind: "ready" }
-  | { kind: "timeout" }
-  | { kind: "unavailable"; reason: string };
-
-/**
- * Workspace-scoped LSP interface that owns routing, readiness, semantic operations,
- * diagnostics, and recovery without exposing clients or the mutable manager.
- * File path inputs may be absolute or session-cwd-relative; a leading `@` is stripped
- * to match pi's built-in path-tool convention. Position arguments use raw 0-based LSP
- * coordinates; use `toLspPosition()` from `@mrclrchtr/supi-lsp/api` when starting from
- * user-facing 1-based line and character values.
- */
-export interface WorkspaceLspRuntime {
-  hover(filePath: string, position: Position): Promise<CodeQueryResult<Hover | null>>;
-  definition(
-    filePath: string,
-    position: Position,
-  ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>>;
-  references(filePath: string, position: Position): Promise<CodeQueryResult<Location[]>>;
-  implementation(
-    filePath: string,
-    position: Position,
-  ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>>;
-  documentSymbols(
-    filePath: string,
-  ): Promise<CodeQueryResult<DocumentSymbol[] | SymbolInformation[]>>;
-  workspaceSymbol(query: string): Promise<CodeQueryResult<SymbolInformation[] | WorkspaceSymbol[]>>;
-  rename(filePath: string, position: Position, newName: string): Promise<WorkspaceEdit | null>;
-  codeActions(filePath: string, positionOrRange: Position | Range): Promise<CodeAction[] | null>;
-  /** Succeeds only when the concrete routed client exists and is query-ready. */
-  waitUntilReadyForFile(
-    filePath: string,
-    options?: { timeoutMs?: number },
-  ): Promise<SemanticReadinessResult>;
-  /** Succeeds only when at least one concrete workspace client is active and query-ready. */
-  waitUntilReadyForWorkspace(options?: { timeoutMs?: number }): Promise<SemanticReadinessResult>;
-  getProjectServers(): ProjectServerInfo[];
-  isSupportedSourceFile(filePath: string): boolean;
-  trackFile(filePath: string): Promise<boolean>;
-  closeFile(filePath: string): void;
-  pruneMissingFiles(): readonly string[];
-  noteWorkspaceChanges(changes: FileEvent[]): void;
-  fileDiagnostics(filePath: string, maxSeverity?: number): Promise<CodeQueryResult<Diagnostic[]>>;
-  refreshOpenDiagnostics(options?: { maxWaitMs?: number; quietMs?: number }): Promise<void>;
-  getWorkspaceDiagnosticSummary(): WorkspaceDiagnosticSummaryEntry[];
-  getOutstandingDiagnostics(
-    maxSeverity?: number,
-  ): Array<{ file: string; diagnostics: Diagnostic[] }>;
-  getOutstandingDiagnosticSummary(maxSeverity?: number): OutstandingDiagnosticSummaryEntry[];
-  recoverDiagnostics(options?: {
-    restartIfStillStale?: boolean;
-    maxWaitMs?: number;
-    quietMs?: number;
-  }): Promise<RecoverDiagnosticsResult>;
+/** Emit one aggregate tsconfig scope-decision event after a recovery pass. */
+function recordScopeDecisionEvent(manager: LspManager): void {
+  try {
+    const summary = manager.getScopeDecisionSummary();
+    recordDebugEvent({
+      source: "lsp",
+      level: "debug",
+      category: "diagnostics.scope",
+      message: "LSP diagnostic tsconfig scope decisions",
+      cwd: truncateIdentity(manager.getCwd()),
+      data: {
+        caseSensitiveFileNames: summary.caseSensitiveFileNames,
+        counts: summary.counts,
+        basisCounts: summary.basisCounts,
+        totalFiles: summary.totalFiles,
+        entries: summary.entries.map((entry) => ({
+          file: truncateIdentity(entry.file),
+          status: entry.status,
+          ...(entry.basis ? { basis: entry.basis } : {}),
+        })),
+      },
+    });
+  } catch {
+    // Telemetry must never turn a completed recovery into a failure.
+  }
 }
 
 class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
@@ -136,29 +101,38 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
 
   // ── Semantic lookups ────────────────────────────────────────────────
 
-  async hover(filePath: string, position: Position): Promise<CodeQueryResult<Hover | null>> {
+  async hover(
+    filePath: string,
+    position: Position,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Hover | null>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
     if (!client) return unavailableFileQuery("hover", resolvedPath);
-    return client.hover(resolvedPath, position);
+    return client.hover(resolvedPath, position, control);
   }
 
   async definition(
     filePath: string,
     position: Position,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
     if (!client) return unavailableFileQuery("definition", resolvedPath);
-    return client.definition(resolvedPath, position);
+    return client.definition(resolvedPath, position, control);
   }
 
-  async references(filePath: string, position: Position): Promise<CodeQueryResult<Location[]>> {
+  async references(
+    filePath: string,
+    position: Position,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Location[]>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
     if (!client) return unavailableFileQuery("references", resolvedPath);
     return mapCodeQueryResult(
-      await client.references(resolvedPath, position),
+      await client.references(resolvedPath, position, control),
       (data) => data ?? [],
     );
   }
@@ -166,43 +140,58 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
   async implementation(
     filePath: string,
     position: Position,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
     if (!client) return unavailableFileQuery("implementation", resolvedPath);
-    return client.implementation(resolvedPath, position);
+    return client.implementation(resolvedPath, position, control);
   }
 
   async documentSymbols(
     filePath: string,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<DocumentSymbol[] | SymbolInformation[]>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
     if (!client) return unavailableFileQuery("document symbols", resolvedPath);
-    return mapCodeQueryResult(await client.documentSymbols(resolvedPath), (data) => data ?? []);
+    return mapCodeQueryResult(
+      await client.documentSymbols(resolvedPath, control),
+      (data) => data ?? [],
+    );
   }
 
   async workspaceSymbol(
     query: string,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<SymbolInformation[] | WorkspaceSymbol[]>> {
-    return this.manager.workspaceSymbol(query);
+    return this.manager.workspaceSymbol(query, control);
   }
 
   async rename(
     filePath: string,
     position: Position,
     newName: string,
-  ): Promise<WorkspaceEdit | null> {
+    control?: CodeRequestControl,
+  ): Promise<RoutedMutationResponse<WorkspaceEdit | null> | null> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
     if (!client) return null;
-    return client.rename(resolvedPath, position, newName);
+    return {
+      value: await client.rename(resolvedPath, position, newName, control),
+      authorizedMutationRoots: [client.root],
+    };
+  }
+
+  getOpenDocumentVersion(filePath: string): number | null {
+    return this.manager.getOpenDocumentVersion(this.resolveFilePath(filePath));
   }
 
   async codeActions(
     filePath: string,
     positionOrRange: Position | Range,
-  ): Promise<CodeAction[] | null> {
+    control?: CodeRequestControl,
+  ): Promise<RoutedMutationResponse<CodeAction[] | null> | null> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
     if (!client) return null;
@@ -215,7 +204,10 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       .filter((diagnostic) => diagnostic.range.end.line >= range.start.line)
       .filter((diagnostic) => diagnostic.range.start.line <= range.end.line);
 
-    return client.codeActions(resolvedPath, range, { diagnostics });
+    return {
+      value: await client.codeActions(resolvedPath, range, { diagnostics }, control),
+      authorizedMutationRoots: [client.root],
+    };
   }
 
   /**
@@ -225,6 +217,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
   async waitUntilReadyForFile(
     filePath: string,
     options: { timeoutMs?: number } = {},
+    control?: CodeRequestControl,
   ): Promise<SemanticReadinessResult> {
     const resolvedPath = this.resolveFilePath(filePath);
     if (!this.manager.canServeFile(resolvedPath)) {
@@ -235,8 +228,9 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     }
 
     const readiness = await raceReadinessValue(
-      this.manager.waitUntilFileReady(resolvedPath),
+      this.manager.waitUntilFileReady(resolvedPath, control),
       options.timeoutMs,
+      control,
     );
     if (readiness.kind !== "resolved") return readiness;
     if (readiness.value === null) {
@@ -254,10 +248,12 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
    */
   async waitUntilReadyForWorkspace(
     options: { timeoutMs?: number } = {},
+    control?: CodeRequestControl,
   ): Promise<SemanticReadinessResult> {
     const readiness = await raceReadinessValue(
-      this.manager.waitUntilWorkspaceReady(),
+      this.manager.waitUntilWorkspaceReady(control),
       options.timeoutMs,
+      control,
     );
     if (readiness.kind !== "resolved") return readiness;
     if (readiness.value === 0) {
@@ -297,7 +293,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
   /** Notify routed clients of workspace file changes and reset pull state. */
   noteWorkspaceChanges(changes: FileEvent[]): void {
     this.manager.clearAllPullResultIds();
-    this.manager.notifyWorkspaceFileChanges(changes);
+    this.manager.noteWorkspaceChanges(changes);
   }
 
   async #shutdown(): Promise<void> {
@@ -310,34 +306,36 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
   async fileDiagnostics(
     filePath: string,
     maxSeverity: number = 4,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<Diagnostic[]>> {
     const resolvedPath = this.resolveFilePath(filePath);
     if (!this.manager.canServeFile(resolvedPath)) {
       return unavailableFileQuery("diagnostics", resolvedPath);
     }
-    return this.manager.syncFileAndGetDiagnostics(resolvedPath, maxSeverity);
+    return this.manager.syncFileAndGetDiagnostics(resolvedPath, maxSeverity, control);
   }
 
   /** Re-sync every open document and wait for diagnostics to settle. */
-  async refreshOpenDiagnostics(options?: { maxWaitMs?: number; quietMs?: number }): Promise<void> {
-    await this.manager.refreshOpenDiagnostics(options);
+  async refreshOpenDiagnostics(
+    options?: { maxWaitMs?: number; quietMs?: number },
+    control?: CodeRequestControl,
+  ): Promise<DiagnosticEvidenceSummary> {
+    return this.manager.refreshOpenDiagnostics({ ...options, ...control });
   }
 
   /** Get a lightweight workspace diagnostic summary for all tracked files. */
-  getWorkspaceDiagnosticSummary(): WorkspaceDiagnosticSummaryEntry[] {
-    return this.manager.getDiagnosticSummary();
+  getWorkspaceDiagnosticSummary() {
+    return this.manager.getDiagnosticSnapshot();
   }
 
   /** Get outstanding diagnostics grouped by file at or above the supplied severity threshold. */
-  getOutstandingDiagnostics(
-    maxSeverity: number = 1,
-  ): Array<{ file: string; diagnostics: Diagnostic[] }> {
-    return this.manager.getOutstandingDiagnostics(maxSeverity);
+  getOutstandingDiagnostics(maxSeverity: number = 1) {
+    return this.manager.getOutstandingDiagnosticsSnapshot(maxSeverity);
   }
 
   /** Get outstanding diagnostic counts grouped by file. */
-  getOutstandingDiagnosticSummary(maxSeverity: number = 1): OutstandingDiagnosticSummaryEntry[] {
-    return this.manager.getOutstandingDiagnosticSummary(maxSeverity);
+  getOutstandingDiagnosticSummary(maxSeverity: number = 1) {
+    return this.manager.getOutstandingDiagnosticSummarySnapshot(maxSeverity);
   }
 
   /** Trigger a workspace-wide diagnostics refresh and stale-state recovery pass. */
@@ -345,8 +343,53 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     restartIfStillStale?: boolean;
     maxWaitMs?: number;
     quietMs?: number;
+    /** Evidence from a refresh the caller already completed; skips this pass's own refresh when no watched-file changes apply. */
+    initialEvidence?: DiagnosticEvidenceSummary;
+    control?: CodeRequestControl;
   }): Promise<RecoverDiagnosticsResult> {
-    return this.manager.recoverWorkspaceDiagnostics(options);
+    const recoveryStartedAt = Date.now();
+    try {
+      const result = await this.manager.recoverWorkspaceDiagnostics(options);
+      const outcome = result.refreshFailureReason ? "failed" : "completed";
+      recordDebugEvent({
+        source: "lsp",
+        level: "debug",
+        category: "runtime.recovery",
+        message: `LSP diagnostic recovery ${outcome}`,
+        cwd: truncateIdentity(this.manager.getCwd()),
+        data: {
+          outcome,
+          elapsedMs: result.elapsedMs,
+          attemptedClients: result.attemptedClients,
+          restartedClients: result.restartedClients,
+          attemptedServers: boundServerNames(result.attemptedServers ?? []),
+          restartedServers: boundServerNames(result.restartedServers ?? []),
+          ...(result.restartReason ? { reason: result.restartReason } : {}),
+        },
+      });
+      recordScopeDecisionEvent(this.manager);
+      return result;
+    } catch (error) {
+      // A cancelled pass has no result object, so telemetry records the
+      // cancelled outcome, the elapsed time, and the server names that are
+      // still running at cancellation. Restart identity is unavailable
+      // because the pass produced no result.
+      if (isCodeRequestInterruption(error, options?.control)) {
+        recordDebugEvent({
+          source: "lsp",
+          level: "debug",
+          category: "runtime.recovery",
+          message: "LSP diagnostic recovery cancelled",
+          cwd: truncateIdentity(this.manager.getCwd()),
+          data: {
+            outcome: "cancelled",
+            elapsedMs: Date.now() - recoveryStartedAt,
+            attemptedServers: boundServerNames(this.manager.getRunningClientNames()),
+          },
+        });
+      }
+      throw error;
+    }
   }
 
   private resolveFilePath(filePath: string): string {
@@ -380,15 +423,19 @@ export function getWorkspaceLspRuntime(cwd: string): WorkspaceLspRuntimeState {
 export async function waitForWorkspaceLspRuntime(
   cwd: string,
   timeoutMs: number = 250,
+  control?: CodeRequestControl,
 ): Promise<WorkspaceLspRuntimeState> {
   const deadline = Date.now() + Math.max(0, timeoutMs);
   let state = getWorkspaceLspRuntime(cwd);
 
   while (state.kind === "pending" && Date.now() < deadline) {
+    throwIfCodeRequestInterrupted(control);
     await new Promise((resolve) => setTimeout(resolve, WAIT_INTERVAL_MS));
     state = getWorkspaceLspRuntime(cwd);
   }
 
+  // A cancelled poll must not hand a runtime to a caller that no longer awaits.
+  throwIfCodeRequestInterrupted(control);
   return state;
 }
 

package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-transition-debug.ts

@@ -0,0 +1,49 @@
+import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
+import type { ProjectServerInfo } from "../config/types.ts";
+import { MAX_SERVERS, truncateIdentity } from "../debug-telemetry.ts";
+import type { LspRuntimeTransition } from "./runtime-controller.ts";
+
+/** One bounded server entry in a runtime-transition payload. */
+export interface TransitionServerEntry {
+  readonly name: string;
+  readonly status: ProjectServerInfo["status"];
+  readonly ready: boolean;
+}
+
+/** Bound a project-server snapshot to MAX_SERVERS name/status/ready entries. */
+function boundedServerEntries(
+  projectServers: readonly ProjectServerInfo[],
+): TransitionServerEntry[] {
+  return projectServers.slice(0, MAX_SERVERS).map((server) => ({
+    name: truncateIdentity(server.name),
+    status: server.status,
+    ready: server.ready,
+  }));
+}
+
+/** Record bounded aggregate telemetry for one runtime transition. */
+export function recordLspRuntimeTransition(cwd: string, transition: LspRuntimeTransition): void {
+  const readyClients = transition.projectServers.filter(
+    (server) => server.status === "running" && server.ready,
+  ).length;
+  const trackedFiles = transition.projectServers.reduce(
+    (count, server) => count + server.openFiles.length,
+    0,
+  );
+  recordDebugEvent({
+    source: "lsp",
+    level: transition.kind === "crash" ? "warning" : "debug",
+    category: "runtime.transition",
+    message: `LSP runtime transition: ${transition.kind}`,
+    cwd: truncateIdentity(cwd),
+    data: {
+      generation: transition.generation,
+      kind: transition.kind,
+      semanticReady: transition.semanticReady,
+      readyClients,
+      totalClients: transition.projectServers.length,
+      trackedFiles,
+      servers: boundedServerEntries(transition.projectServers),
+    },
+  });
+}