@mrclrchtr/supi-code-intelligence 4.9.0 → 5.0.0

package/node_modules/@mrclrchtr/supi-lsp/src/provider/semantic-symbol-mapper.ts

@@ -0,0 +1,207 @@
+import { readFile } from "node:fs/promises";
+import type {
+  CodeLocation,
+  CodeSymbol,
+  DeclarationNesting,
+  DocumentCodeSymbol,
+  SourceRange,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
+import type {
+  DocumentSymbol,
+  Hover,
+  Location,
+  LocationLink,
+  MarkupContent,
+  SymbolInformation,
+} from "../config/types.ts";
+
+/** Map one LSP location result to shared code locations. */
+export function mapLocations(value: Location | Location[] | LocationLink[] | null): CodeLocation[] {
+  if (!value) return [];
+  const locations = Array.isArray(value) ? value : [value];
+  return locations.flatMap((item) => {
+    const location = toCodeLocation(item);
+    return location ? [location] : [];
+  });
+}
+
+function toCodeLocation(item: Location | LocationLink): CodeLocation | null {
+  const loc = item as Record<string, unknown>;
+  const uri = loc.uri ?? loc.targetUri;
+  if (typeof uri !== "string") return null;
+  const range = loc.targetSelectionRange ?? loc.targetRange ?? loc.range;
+  if (!range || typeof range !== "object") return null;
+  const r = range as { start: Record<string, unknown>; end: Record<string, unknown> };
+  if (!r.start || !r.end) return null;
+  return {
+    uri,
+    range: {
+      start: {
+        line: (r.start.line as number) ?? 0,
+        character: (r.start.character as number) ?? 0,
+      },
+      end: { line: (r.end.line as number) ?? 0, character: (r.end.character as number) ?? 0 },
+    },
+  };
+}
+
+const SYMBOL_KIND_NAMES: Record<number, string> = {
+  1: "File",
+  2: "Module",
+  3: "Namespace",
+  4: "Package",
+  5: "Class",
+  6: "Method",
+  7: "Property",
+  8: "Field",
+  9: "Constructor",
+  10: "Enum",
+  11: "Interface",
+  12: "Function",
+  13: "Variable",
+  14: "Constant",
+  15: "String",
+  16: "Number",
+  17: "Boolean",
+  18: "Array",
+  19: "Object",
+  20: "Key",
+  21: "Null",
+  22: "EnumMember",
+  23: "Struct",
+  24: "Event",
+  25: "Operator",
+  26: "TypeParameter",
+};
+
+function symbolKindName(kind: number): string {
+  return SYMBOL_KIND_NAMES[kind] ?? "Unknown";
+}
+
+/** Flatten provider symbols while preserving declaration and name anchors. */
+export async function mapDocumentSymbols(
+  symbols: DocumentSymbol[] | SymbolInformation[],
+  filePath: string,
+): Promise<DocumentCodeSymbol[]> {
+  return flattenDocumentSymbols(symbols, filePath, null, {
+    sourceLines: await readSourceLines(filePath),
+    nesting: "top-level",
+  });
+}
+
+function flattenDocumentSymbols(
+  symbols: DocumentSymbol[] | SymbolInformation[],
+  filePath: string,
+  container: string | null,
+  context: { sourceLines: readonly string[] | null; nesting: DeclarationNesting },
+): DocumentCodeSymbol[] {
+  const result: DocumentCodeSymbol[] = [];
+  for (const sym of symbols) {
+    let information: SymbolInformation | null = null;
+    let document: DocumentSymbol | null = null;
+    if (isSymbolInformation(sym)) information = sym;
+    else document = sym;
+    const declStart = document?.range.start ?? information?.location.range.start;
+    if (!declStart) continue;
+    const nameStart = document
+      ? resolveDocumentSymbolNameStart(document, context.sourceLines)
+      : null;
+    const symbol: DocumentCodeSymbol = {
+      name: sym.name,
+      kind: symbolKindName(sym.kind),
+      file: filePath,
+      declarationAnchor: { line: declStart.line + 1, character: declStart.character + 1 },
+      container: information?.containerName ?? container,
+      nesting: information ? "unknown" : context.nesting,
+    };
+    if (nameStart) {
+      symbol.nameAnchor = { line: nameStart.line + 1, character: nameStart.character + 1 };
+    }
+    result.push(symbol);
+    if (document?.children?.length) {
+      result.push(
+        ...flattenDocumentSymbols(document.children, filePath, sym.name, {
+          sourceLines: context.sourceLines,
+          nesting: "nested",
+        }),
+      );
+    }
+  }
+  return result;
+}
+
+function isSymbolInformation(
+  symbol: DocumentSymbol | SymbolInformation,
+): symbol is SymbolInformation {
+  return "location" in symbol;
+}
+
+async function readSourceLines(filePath: string): Promise<readonly string[] | null> {
+  try {
+    return (await readFile(filePath, "utf-8")).split(/\r?\n/);
+  } catch {
+    return null;
+  }
+}
+
+function resolveDocumentSymbolNameStart(
+  symbol: DocumentSymbol,
+  sourceLines: readonly string[] | null,
+): { line: number; character: number } | null {
+  const selectionStart = symbol.selectionRange?.start;
+  if (!selectionStart) return null;
+  if (!sourceLines) return selectionStart;
+  const sourceLine = sourceLines[selectionStart.line];
+  if (sourceLine === undefined) return null;
+  if (
+    sourceLine.slice(selectionStart.character, selectionStart.character + symbol.name.length) ===
+    symbol.name
+  ) {
+    return selectionStart;
+  }
+  const rangeStart = symbol.range?.start;
+  const rangeEnd = symbol.range?.end;
+  const from = rangeStart?.line === selectionStart.line ? rangeStart.character : 0;
+  const until = rangeEnd?.line === selectionStart.line ? rangeEnd.character : sourceLine.length;
+  const character = sourceLine.indexOf(symbol.name, from);
+  if (character < 0 || character + symbol.name.length > until) return null;
+  return { line: selectionStart.line, character };
+}
+
+/** Map one workspace symbol to the shared representation. */
+export function toCodeSymbol(sym: SymbolInformation): CodeSymbol {
+  const start = sym.location?.range?.start;
+  return {
+    name: sym.name,
+    kind: symbolKindName(sym.kind),
+    file: uriToFile(sym.location?.uri ?? ""),
+    declarationAnchor: {
+      line: start ? start.line + 1 : 0,
+      character: start ? start.character + 1 : 0,
+    },
+    container: sym.containerName ?? null,
+  };
+}
+
+/** Convert an LSP hover response to the shared representation. */
+export function convertLspHover(hover: Hover): { contents: string; range?: SourceRange } {
+  const result: { contents: string; range?: SourceRange } = {
+    contents: extractHoverText(hover.contents),
+  };
+  if (hover.range) {
+    result.range = {
+      start: { line: hover.range.start.line, character: hover.range.start.character },
+      end: { line: hover.range.end.line, character: hover.range.end.character },
+    };
+  }
+  return result;
+}
+
+function extractHoverText(contents: Hover["contents"]): string {
+  if (typeof contents === "string") return contents;
+  if (Array.isArray(contents)) {
+    return contents.map((item) => (typeof item === "string" ? item : item.value)).join("\n");
+  }
+  return (contents as MarkupContent).value ?? "";
+}

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

@@ -1,3 +1,10 @@
+import {
+  type CodeRequestControl,
+  CodeRequestDeadlineError,
+  isCodeRequestInterruption,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
+
 const DEFAULT_SEMANTIC_READY_TIMEOUT_MS = 15_000;
 
 export type ReadinessValueResult<T> =
@@ -5,26 +12,88 @@ export type ReadinessValueResult<T> =
   | { kind: "timeout" }
   | { kind: "unavailable"; reason: string };
 
+/**
+ * Race one promise against request-control interruption (abort or absolute
+ * deadline) and rethrow the interruption. The underlying promise keeps its
+ * own lifecycle; only the caller's wait stops promptly.
+ */
+export async function raceRequestControl<T>(
+  promise: Promise<T>,
+  control?: CodeRequestControl,
+): Promise<T> {
+  if (!control) return promise;
+  // Preflight: an already-cancelled caller stops even when the awaited
+  // promise is already settled.
+  throwIfCodeRequestInterrupted(control);
+  const deadlineRemaining =
+    control.deadline === undefined ? undefined : control.deadline - Date.now();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let abortHandler: (() => void) | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_resolve, reject) => {
+        if (deadlineRemaining !== undefined && deadlineRemaining <= 0) {
+          reject(new CodeRequestDeadlineError());
+          return;
+        }
+        if (deadlineRemaining !== undefined) {
+          timer = setTimeout(() => reject(new CodeRequestDeadlineError()), deadlineRemaining);
+        }
+        abortHandler = () => reject(control.signal?.reason ?? new Error("Request cancelled"));
+        if (control.signal?.aborted) abortHandler();
+        else control.signal?.addEventListener("abort", abortHandler, { once: true });
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (abortHandler) control.signal?.removeEventListener("abort", abortHandler);
+  }
+}
+
 /** Await one readiness operation while preserving its concrete success value. */
 export async function raceReadinessValue<T>(
   readiness: Promise<T>,
   timeoutMs: number | undefined,
+  control?: CodeRequestControl,
 ): Promise<ReadinessValueResult<T>> {
+  // Preflight: an already-cancelled caller stops even when the readiness
+  // promise is already settled.
+  throwIfCodeRequestInterrupted(control);
   const effectiveTimeoutMs = timeoutMs ?? DEFAULT_SEMANTIC_READY_TIMEOUT_MS;
+  const deadlineRemaining =
+    control?.deadline === undefined ? undefined : control.deadline - Date.now();
+  const bindMs =
+    deadlineRemaining === undefined
+      ? effectiveTimeoutMs
+      : Math.min(effectiveTimeoutMs, deadlineRemaining);
   let timer: ReturnType<typeof setTimeout> | null = null;
+  let abortHandler: (() => void) | undefined;
 
   try {
     const value = await Promise.race([
       readiness,
       new Promise<never>((_resolve, reject) => {
         timer = setTimeout(
-          () => reject(new Error("semantic-readiness-timeout")),
-          effectiveTimeoutMs,
+          () =>
+            reject(
+              deadlineRemaining !== undefined && deadlineRemaining < effectiveTimeoutMs
+                ? new CodeRequestDeadlineError()
+                : new Error("semantic-readiness-timeout"),
+            ),
+          Math.max(0, bindMs),
         );
       }),
+      new Promise<never>((_resolve, reject) => {
+        abortHandler = () =>
+          reject(control?.signal?.reason ?? new Error("Readiness wait cancelled"));
+        if (control?.signal?.aborted) abortHandler();
+        else control?.signal?.addEventListener("abort", abortHandler, { once: true });
+      }),
     ]);
     return { kind: "resolved", value };
   } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     if (error instanceof Error && error.message === "semantic-readiness-timeout") {
       return { kind: "timeout" };
     }
@@ -34,5 +103,6 @@ export async function raceReadinessValue<T>(
     };
   } finally {
     if (timer) clearTimeout(timer);
+    if (abortHandler) control?.signal?.removeEventListener("abort", abortHandler);
   }
 }

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

@@ -7,13 +7,16 @@
 //
 // It does NOT import pi event types or ExtensionAPI.
 
+// biome-ignore lint/style/noExcessiveLinesPerFile: session lifecycle, capability projection, and telemetry stay in one controller.
 import type { WorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
 import { loadConfig } from "../config/config.ts";
 import { type LspSettings, loadLspSettings } from "../config/lsp-settings.ts";
 import { clearTsconfigCache } from "../config/tsconfig-scope.ts";
 import type { DetectedProjectServer, LspConfig, ProjectServerInfo } from "../config/types.ts";
+import { truncateIdentity } from "../debug-telemetry.ts";
 import { scanWorkspaceSentinels } from "../diagnostics/workspace-sentinels.ts";
-import { LspManager } from "../manager/manager.ts";
+import { LspManager, type ManagerLifecycleTransition } from "../manager/manager.ts";
 import {
   markLspCapabilitiesReady,
   registerPendingLspCapabilities,
@@ -25,6 +28,7 @@ import {
   setWorkspaceLspRuntimeState,
   type WorkspaceLspRuntime,
 } from "./runtime-registry.ts";
+import { recordLspRuntimeTransition } from "./runtime-transition-debug.ts";
 import { scanMissingServers, scanProjectCapabilities, startDetectedServers } from "./scanner.ts";
 
 // ── Types ─────────────────────────────────────────────────────────────
@@ -72,6 +76,28 @@ export type LspStartResult =
   | { kind: "disabled"; message: string }
   | { kind: "unavailable"; reason: string };
 
+/** Cause of one observable LSP runtime lifecycle transition. */
+export type LspRuntimeTransitionKind =
+  | "startup"
+  | "readiness"
+  | "crash"
+  | "recovery"
+  | "shutdown"
+  | "tracked-files";
+
+/** Immutable aggregate state published when the LSP runtime changes. */
+export interface LspRuntimeTransition {
+  /** Monotonic transition generation for this controller instance. */
+  readonly generation: number;
+  readonly kind: LspRuntimeTransitionKind;
+  /** True only when at least one concrete client is active and ready. */
+  readonly semanticReady: boolean;
+  readonly projectServers: readonly ProjectServerInfo[];
+}
+
+/** Listener for aggregate LSP runtime transitions. */
+export type LspRuntimeTransitionListener = (transition: LspRuntimeTransition) => void;
+
 function supersededStartResult(): LspStartResult {
   return { kind: "unavailable", reason: "LSP startup was superseded by a newer lifecycle event." };
 }
@@ -99,7 +125,13 @@ export class LspRuntimeController {
   readonly #cwd: string;
   #state: LspControllerState;
   #capabilityRuntime: WorkspaceRuntime | null;
-  /** Monotonic ownership token for starts, shutdowns, and async warm-up. */
+  #activeManager: LspManager | null = null;
+  #latestManagerTransition: ManagerLifecycleTransition | null = null;
+  #projectedSemanticReady: boolean | null = null;
+  #lifecycleGeneration = 0;
+  #latestLifecycleTransition: LspRuntimeTransition | null = null;
+  readonly #lifecycleListeners = new Set<LspRuntimeTransitionListener>();
+  /** Monotonic ownership token for starts, shutdowns, and manager callbacks. */
   #readinessGeneration = 0;
 
   constructor(cwd: string, runtime?: WorkspaceRuntime) {
@@ -151,6 +183,22 @@ export class LspRuntimeController {
     this.#capabilityRuntime = runtime;
   }
 
+  /**
+   * Subscribe to aggregate runtime transitions.
+   *
+   * A late subscriber immediately receives the latest transition. The returned
+   * function is idempotent and stops all later notifications for this listener.
+   */
+  subscribeLifecycle(listener: LspRuntimeTransitionListener): () => void {
+    this.#lifecycleListeners.add(listener);
+    if (this.#latestLifecycleTransition) {
+      this.notifyLifecycleListener(listener, this.#latestLifecycleTransition);
+    }
+    return () => {
+      this.#lifecycleListeners.delete(listener);
+    };
+  }
+
   /**
    * Start the LSP session for this controller's cwd.
    *
@@ -191,8 +239,11 @@ export class LspRuntimeController {
    */
   private async cleanupExistingSession(): Promise<void> {
     if (this.#state.kind !== "ready") return;
+    this.#activeManager = null;
+    this.#latestManagerTransition = null;
     await this.#state.runtimeOwner.shutdown();
     if (this.#capabilityRuntime) unregisterLspCapabilities(this.#capabilityRuntime, this.#cwd);
+    this.#projectedSemanticReady = null;
     clearWorkspaceLspRuntime(this.#cwd);
   }
 
@@ -200,7 +251,10 @@ export class LspRuntimeController {
   private setDisabled(generation: number): LspStartResult {
     if (generation !== this.#readinessGeneration) return supersededStartResult();
     const message = "All language servers are disabled by configuration.";
+    this.#activeManager = null;
+    this.#latestManagerTransition = null;
     if (this.#capabilityRuntime) unregisterLspCapabilities(this.#capabilityRuntime, this.#cwd);
+    this.#projectedSemanticReady = null;
     this.#state = { kind: "disabled", message };
     setWorkspaceLspRuntimeState(this.#cwd, { kind: "disabled" });
     return { kind: "disabled", message };
@@ -210,6 +264,10 @@ export class LspRuntimeController {
   private setUnavailable(error: unknown, generation: number): LspStartResult {
     if (generation !== this.#readinessGeneration) return supersededStartResult();
     const reason = error instanceof Error ? error.message : String(error);
+    this.#activeManager = null;
+    this.#latestManagerTransition = null;
+    if (this.#capabilityRuntime) unregisterLspCapabilities(this.#capabilityRuntime, this.#cwd);
+    this.#projectedSemanticReady = null;
     this.#state = { kind: "unavailable", reason };
     setWorkspaceLspRuntimeState(this.#cwd, { kind: "unavailable", reason });
     return { kind: "unavailable", reason };
@@ -229,7 +287,13 @@ export class LspRuntimeController {
     if (Object.keys(config.servers).length === 0) return this.setDisabled(generation);
     this.#state = { kind: "pending" };
 
-    const manager = new LspManager(config, this.#cwd);
+    let manager: LspManager;
+    manager = new LspManager(config, this.#cwd, (transition) => {
+      this.handleManagerLifecycle(manager, generation, transition);
+    });
+    this.#activeManager = manager;
+    this.#latestManagerTransition = null;
+    this.publishLifecycle("startup", false, []);
     manager.setExcludePatterns(settings.exclude);
     setWorkspaceLspRuntimeState(this.#cwd, { kind: "pending" });
 
@@ -237,6 +301,7 @@ export class LspRuntimeController {
     manager.registerDetectedServers(detectedServers);
     await startDetectedServers(manager, detectedServers);
     if (generation !== this.#readinessGeneration) {
+      if (this.#activeManager === manager) this.#activeManager = null;
       await manager.shutdownAll();
       return supersededStartResult();
     }
@@ -249,9 +314,17 @@ export class LspRuntimeController {
 
     if (this.#capabilityRuntime) {
       registerPendingLspCapabilities(this.#capabilityRuntime, this.#cwd, workspaceRuntime);
+      this.#projectedSemanticReady = false;
     }
 
-    const projectServers = workspaceRuntime.getProjectServers();
+    const latestManagerTransition = this
+      .#latestManagerTransition as ManagerLifecycleTransition | null;
+    const projectServers = [
+      ...(latestManagerTransition?.projectServers ?? workspaceRuntime.getProjectServers()),
+    ];
+    const semanticReady =
+      latestManagerTransition?.semanticReady ??
+      projectServers.some((server) => server.status === "running" && server.ready);
 
     this.#state = {
       kind: "ready",
@@ -262,40 +335,88 @@ export class LspRuntimeController {
       settings,
     };
 
-    void this.promoteSemanticReadiness(workspaceRuntime, generation);
+    this.projectSemanticReadiness(workspaceRuntime, semanticReady);
 
     return { kind: "ready", runtime: workspaceRuntime };
   }
 
-  private async promoteSemanticReadiness(
-    workspaceRuntime: WorkspaceLspRuntime,
+  private handleManagerLifecycle(
+    manager: LspManager,
     readinessGeneration: number,
-  ): Promise<void> {
-    try {
-      const readiness = await workspaceRuntime.waitUntilReadyForWorkspace();
-      if (readiness.kind !== "ready") return;
-    } catch {
+    transition: ManagerLifecycleTransition,
+  ): void {
+    if (readinessGeneration !== this.#readinessGeneration) return;
+    if (this.#activeManager !== manager) return;
+    this.#latestManagerTransition = transition;
+    if (this.#state.kind === "ready") {
+      this.#state.projectServers = [...transition.projectServers];
+      this.projectSemanticReadiness(this.#state.workspaceRuntime, transition.semanticReady);
+    }
+    this.publishLifecycle(transition.kind, transition.semanticReady, transition.projectServers);
+  }
+
+  private projectSemanticReadiness(
+    workspaceRuntime: WorkspaceLspRuntime,
+    semanticReady: boolean,
+  ): void {
+    if (!this.#capabilityRuntime) return;
+    if (semanticReady) {
+      if (this.#projectedSemanticReady === true) return;
+      markLspCapabilitiesReady(this.#capabilityRuntime, this.#cwd);
+      this.#projectedSemanticReady = true;
+      this.recordCapabilityTransition(true);
       return;
     }
+    if (this.#projectedSemanticReady === false) return;
+    registerPendingLspCapabilities(this.#capabilityRuntime, this.#cwd, workspaceRuntime);
+    this.#projectedSemanticReady = false;
+    this.recordCapabilityTransition(false);
+  }
 
-    if (!this.isCurrentRuntime(workspaceRuntime, readinessGeneration)) return;
-    if (this.#state.kind !== "ready") return;
+  /** Record one semantic capability ready↔pending transition for telemetry. */
+  private recordCapabilityTransition(ready: boolean): void {
+    recordDebugEvent({
+      source: "lsp",
+      level: "debug",
+      category: "capability.transition",
+      message: `LSP capability transition: ${ready ? "ready" : "pending"}`,
+      cwd: truncateIdentity(this.#cwd),
+      data: { ready },
+    });
+  }
 
-    this.#state.projectServers = workspaceRuntime.getProjectServers();
-    if (this.#capabilityRuntime) {
-      markLspCapabilitiesReady(this.#capabilityRuntime, this.#cwd);
+  private publishLifecycle(
+    kind: LspRuntimeTransitionKind,
+    semanticReady: boolean,
+    projectServers: readonly ProjectServerInfo[],
+  ): void {
+    const transition: LspRuntimeTransition = {
+      generation: ++this.#lifecycleGeneration,
+      kind,
+      semanticReady,
+      projectServers: projectServers.map((server) => ({
+        ...server,
+        fileTypes: [...server.fileTypes],
+        supportedActions: [...server.supportedActions],
+        openFiles: [...server.openFiles],
+      })),
+    };
+    recordLspRuntimeTransition(this.#cwd, transition);
+    this.#latestLifecycleTransition = transition;
+    for (const listener of this.#lifecycleListeners) {
+      this.notifyLifecycleListener(listener, transition);
     }
   }
 
-  private isCurrentRuntime(
-    workspaceRuntime: WorkspaceLspRuntime,
-    readinessGeneration: number,
-  ): boolean {
-    return (
-      readinessGeneration === this.#readinessGeneration &&
-      this.#state.kind === "ready" &&
-      this.#state.workspaceRuntime === workspaceRuntime
-    );
+  private notifyLifecycleListener(
+    listener: LspRuntimeTransitionListener,
+    transition: LspRuntimeTransition,
+  ): void {
+    try {
+      listener(transition);
+    } catch {
+      // Lifecycle observers must not alter runtime behavior.
+    }
   }
 
   /**
@@ -307,10 +428,13 @@ export class LspRuntimeController {
   async shutdown(): Promise<void> {
     this.#readinessGeneration++;
     clearTsconfigCache();
+    this.#activeManager = null;
+    this.#latestManagerTransition = null;
 
     if (this.#capabilityRuntime) {
       unregisterLspCapabilities(this.#capabilityRuntime, this.#cwd);
     }
+    this.#projectedSemanticReady = null;
 
     if (this.#cwd) {
       clearWorkspaceLspRuntime(this.#cwd);
@@ -321,6 +445,7 @@ export class LspRuntimeController {
     }
 
     this.#state = { kind: "initial" };
+    this.publishLifecycle("shutdown", false, []);
   }
 
   /** Get the missing servers warning (servers whose binary is not on PATH). */

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

@@ -0,0 +1,40 @@
+import type { CodeQueryResult, CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
+import type { Diagnostic } from "../config/types.ts";
+import type {
+  DiagnosticEvidenceSummary,
+  OutstandingDiagnosticSummaryEntry,
+  RecoverDiagnosticsResult,
+  WorkspaceDiagnosticSnapshot,
+  WorkspaceDiagnosticSummaryEntry,
+} from "./runtime-diagnostics.ts";
+
+/** Diagnostic and recovery operations owned by a workspace LSP runtime. */
+export interface WorkspaceLspDiagnosticSurface {
+  fileDiagnostics(
+    filePath: string,
+    maxSeverity?: number,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Diagnostic[]>>;
+  /** Re-synchronize tracked documents and return exact five-state evidence coverage. */
+  refreshOpenDiagnostics(
+    options?: { maxWaitMs?: number; quietMs?: number },
+    control?: CodeRequestControl,
+  ): Promise<DiagnosticEvidenceSummary>;
+  /** Return tracked-file counts with aggregate cache freshness and evidence coverage. */
+  getWorkspaceDiagnosticSummary(): WorkspaceDiagnosticSnapshot<WorkspaceDiagnosticSummaryEntry>;
+  /** Return tracked-file messages with aggregate cache freshness and evidence coverage. */
+  getOutstandingDiagnostics(
+    maxSeverity?: number,
+  ): WorkspaceDiagnosticSnapshot<{ file: string; diagnostics: Diagnostic[] }>;
+  /** Return tracked-file severity counts with aggregate cache freshness and evidence coverage. */
+  getOutstandingDiagnosticSummary(
+    maxSeverity?: number,
+  ): WorkspaceDiagnosticSnapshot<OutstandingDiagnosticSummaryEntry>;
+  /** Run best-effort recovery and retain final diagnostic evidence, including failures. */
+  recoverDiagnostics(options?: {
+    restartIfStillStale?: boolean;
+    maxWaitMs?: number;
+    quietMs?: number;
+    control?: CodeRequestControl;
+  }): Promise<RecoverDiagnosticsResult>;
+}