@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

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

@@ -1,99 +1,135 @@
-// LSP client document synchronization and diagnostic state.
-
-import { existsSync, readFileSync } from "node:fs";
-import type {
-  Diagnostic,
-  DocumentDiagnosticReport,
-  PublishDiagnosticsParams,
-  TextDocumentIdentifier,
-  TextDocumentItem,
-  VersionedTextDocumentIdentifier,
-} from "../config/types.ts";
+// biome-ignore-all lint/style/noExcessiveLinesPerFile: one client's document sync, diagnostics, refresh, and sync-file flow stay in one cohesive class.
+import * as path from "node:path";
+import {
+  type CodeQueryResult,
+  type CodeRequestControl,
+  completedCodeQuery,
+  throwIfCodeRequestInterrupted,
+  unavailableCodeQuery,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { Diagnostic, TextDocumentItem } from "../config/types.ts";
+import type { DiagnosticEvidenceSummary } from "../diagnostics/evidence.ts";
 import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
+import { applyPushDiagnostics, buildClientDiagnosticSnapshot } from "./client-diagnostic-cache.ts";
+import { collectSynchronizedFileDiagnostics } from "./client-diagnostic-collection.ts";
+import {
+  type DiagnosticCacheEntry,
+  type DiagnosticSynchronization,
+  hasCurrentEvidence,
+  hasFreshPush,
+  isCurrentSynchronization,
+  isValidPublishDiagnosticsParams,
+  nextDocumentVersion,
+} from "./client-diagnostic-evidence.ts";
+import type { ClientDiagnosticsHost } from "./client-diagnostic-host.ts";
+import {
+  DiagnosticPublicationTracker,
+  trackerFileIdentityFor,
+} from "./client-diagnostic-publication.ts";
 import {
-  DiagnosticObserver,
-  DiagnosticPullError,
-  type DiagnosticPushWaitOutcome,
-  type DiagnosticSettleResult,
-  isDiagnosticTimeout,
-} from "./client-diagnostic-timing.ts";
+  pullClientDiagnosticEvidenceFromHost,
+  refreshClientOpenDiagnostics,
+  sendDidCloseNotification,
+} from "./client-diagnostic-refresh.ts";
+import { DiagnosticObserver, type DiagnosticPushWaitOutcome } from "./client-diagnostic-timing.ts";
+import { DiagnosticWaitRegistry } from "./client-diagnostic-waiters.ts";
+import {
+  type ClientDiagnosticSnapshot,
+  type DiagnosticEntry,
+  fingerprintDocumentContent,
+  hasConfirmedDiagnosticEvidence,
+  type OpenDocumentState,
+} from "./client-document-state.ts";
+import {
+  clearTrackedDocumentState,
+  reopenDocument,
+  synchronizeTrackedDocument,
+} from "./client-document-sync.ts";
+import { getDiagnosticFileState } from "./client-file-state.ts";
 
 const DIAGNOSTIC_WAIT_MS = 3_000;
-
-type OpenDocument = { version: number };
-type DiagnosticWaiter = (outcome: "published" | "released") => void;
-
-type DiagnosticCacheEntry = {
-  diagnostics: Diagnostic[];
-  receivedAt: number;
-  version?: number;
-  resultId?: string;
-};
-
-/** One file's stored diagnostics as consumed by manager-level collection. */
-export interface DiagnosticEntry {
-  uri: string;
-  diagnostics: Diagnostic[];
-}
-
-interface ClientDiagnosticsHost {
-  isOperational(): boolean;
-  supportsPullDiagnostics(): boolean;
-  sendNotification(method: string, params: unknown): void;
-  pullDocumentDiagnostics(
-    uri: string,
-    previousResultId: string | undefined,
-    timeoutMs: number,
-  ): Promise<DocumentDiagnosticReport | null>;
-}
-
-/**
- * Owns one LSP client's open documents, diagnostic cache, waiters, and refresh policy.
- *
- * The host supplies transport and readiness operations. Callers use `LspClient` as
- * the external seam and do not access this state directly.
- */
+/** Bounded push wait after a reopen-resync fallback, in milliseconds. */
+const REOPEN_EVIDENCE_WAIT_MS = 1_000;
+/** Own one client's document and diagnostic evidence; revisions prevent stale reuse. */
 export class ClientDiagnostics {
-  readonly #openDocs = new Map<string, OpenDocument>();
+  readonly #openDocs = new Map<string, OpenDocumentState>();
   readonly #diagnosticStore = new Map<string, DiagnosticCacheEntry>();
-  readonly #diagnosticWaiters = new Map<string, DiagnosticWaiter[]>();
-
-  constructor(private readonly host: ClientDiagnosticsHost) {}
+  readonly #waiters = new DiagnosticWaitRegistry();
+  readonly #versionHistory = new Map<string, number>();
+  readonly #failedUris = new Set<string>();
+  /** Bounded push-publication telemetry for one client's diagnostic state. */
+  readonly #publications: DiagnosticPublicationTracker;
+  /** Client-side sync moment per URI: unversioned pushes before it stay rejected. */
+  readonly #unversionedPushSyncMoments = new Map<string, number>();
+  /** URIs closed by a lifecycle operation: versioned pushes stay fail-closed. */
+  readonly #closedVersionedBarrier = new Set<string>();
+  #evidenceRevision = 0;
+  #nextSynchronizationId = 0;
+
+  constructor(private readonly host: ClientDiagnosticsHost) {
+    this.#publications = new DiagnosticPublicationTracker(
+      { server: host.server, cwd: host.cwd },
+      trackerFileIdentityFor(host.cwd),
+    );
+  }
 
   get openFiles(): string[] {
     return Array.from(this.#openDocs.keys()).map(uriToFile);
   }
 
-  /** Release all waiters and remove all document and diagnostic state. */
-  clear(): void {
+  clear(options: { preserveFailedDocuments?: boolean } = {}): void {
+    if (options.preserveFailedDocuments) {
+      for (const uri of [...this.#openDocs.keys(), ...this.#diagnosticStore.keys()]) {
+        this.#failedUris.add(uri);
+        this.#closedVersionedBarrier.add(uri);
+      }
+    } else {
+      this.#failedUris.clear();
+      this.#closedVersionedBarrier.clear();
+    }
     this.#openDocs.clear();
     this.#diagnosticStore.clear();
-    this.#releaseAllDiagnosticWaiters();
+    this.#versionHistory.clear();
+    this.#evidenceRevision++;
+    this.#unversionedPushSyncMoments.clear();
+    this.#waiters.releaseAll();
+    this.#waiters.cancelSettle();
   }
 
-  /** Open a document, or update it when it is already open. */
   didOpen(filePath: string, content: string): void {
     if (!this.host.isOperational()) return;
 
     const uri = fileToUri(filePath);
+    this.#failedUris.delete(uri);
     if (this.#openDocs.has(uri)) {
       this.didChange(filePath, content);
       return;
     }
 
     const languageId = detectLanguageId(filePath);
-    this.#openDocs.set(uri, { version: 1 });
+    this.#waiters.cancelSettle();
+    // A didOpen is a synchronization: pushes the server sends after it are
+    // responses to the open and can become fresh evidence (ADR 0020).
+    this.#unversionedPushSyncMoments.set(uri, Date.now());
+    this.#closedVersionedBarrier.delete(uri);
+    const version = nextDocumentVersion(this.#versionHistory, uri);
+    this.#openDocs.set(uri, {
+      version,
+      synchronizationId: ++this.#nextSynchronizationId,
+      evidenceRevision: this.#evidenceRevision,
+      content,
+      contentFingerprint: fingerprintDocumentContent(content),
+    });
     this.host.sendNotification("textDocument/didOpen", {
       textDocument: {
         uri,
         languageId,
-        version: 1,
+        version,
         text: content,
       } satisfies TextDocumentItem,
     });
   }
 
-  /** Update a document, or open it when it is not tracked yet. */
   didChange(filePath: string, content: string): void {
     if (!this.host.isOperational()) return;
 
@@ -103,295 +139,409 @@ export class ClientDiagnostics {
       this.didOpen(filePath, content);
       return;
     }
-
-    doc.version++;
-    this.#sendDidChange(uri, doc.version, content);
+    const nextFingerprint = fingerprintDocumentContent(content);
+    if (doc.contentFingerprint === nextFingerprint) return;
+    synchronizeTrackedDocument({
+      uri,
+      content,
+      document: doc,
+      nextVersion: () => nextDocumentVersion(this.#versionHistory, uri),
+      nextSynchronizationId: () => ++this.#nextSynchronizationId,
+      evidenceRevision: this.#evidenceRevision,
+      incrementalSync: this.host.usesIncrementalDocumentSync(),
+      waiters: this.#waiters,
+      sendNotification: (method, params) => this.host.sendNotification(method, params),
+      markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
+      clearFailedFile: () => this.#failedUris.delete(uri),
+      open: () => this.didOpen(filePath, content),
+    });
   }
 
-  /** Close a document and remove its cached diagnostic state. */
   didClose(filePath: string): void {
     const uri = fileToUri(filePath);
     const wasOpen = this.#openDocs.has(uri);
-    this.#clearFileState(uri);
+    this.#failedUris.delete(uri);
+    this.#unversionedPushSyncMoments.delete(uri);
+    this.#closedVersionedBarrier.add(uri);
+    clearTrackedDocumentState(this.#openDocs, this.#diagnosticStore, this.#waiters, uri);
 
     if (wasOpen && this.host.isOperational()) {
-      this.#sendDidClose(uri);
+      sendDidCloseNotification(this.host, uri);
     }
   }
 
-  /** Remove missing open documents and diagnostics, and return their file paths. */
   pruneMissingFiles(): string[] {
-    const uris = new Set([...this.#openDocs.keys(), ...this.#diagnosticStore.keys()]);
+    const uris = new Set([
+      ...this.#openDocs.keys(),
+      ...this.#diagnosticStore.keys(),
+      ...this.#failedUris,
+    ]);
     const removedFiles: string[] = [];
 
     for (const uri of uris) {
       const filePath = uriToFile(uri);
-      if (existsSync(filePath)) continue;
+      if (getDiagnosticFileState(filePath) !== "removed") continue;
 
       const wasOpen = this.#openDocs.has(uri);
-      this.#clearFileState(uri);
+      this.#failedUris.delete(uri);
+      this.#unversionedPushSyncMoments.delete(uri);
+      this.#closedVersionedBarrier.add(uri);
+      clearTrackedDocumentState(this.#openDocs, this.#diagnosticStore, this.#waiters, uri);
       removedFiles.push(filePath);
-      if (wasOpen && this.host.isOperational()) this.#sendDidClose(uri);
+      if (wasOpen && this.host.isOperational()) sendDidCloseNotification(this.host, uri);
     }
 
     return removedFiles;
   }
+  /** Retain a failed document outcome when a replacement cannot reopen it. */
+  markFailedFile(filePath: string): void {
+    const uri = fileToUri(filePath);
+    this.#failedUris.add(uri);
+    this.#unversionedPushSyncMoments.delete(uri);
+    this.#closedVersionedBarrier.add(uri);
+  }
 
+  getOpenDocumentVersion(filePath: string): number | null {
+    return this.#openDocs.get(fileToUri(filePath))?.version ?? null;
+  }
   getDiagnostics(filePath: string): Diagnostic[] {
     return this.#diagnosticStore.get(fileToUri(filePath))?.diagnostics ?? [];
   }
-
-  /** Return non-empty diagnostics for files that still exist. */
+  getDiagnosticSnapshot(): ClientDiagnosticSnapshot {
+    return buildClientDiagnosticSnapshot({
+      store: this.#diagnosticStore,
+      openDocuments: this.#openDocs,
+      failedDocuments: this.#failedUris,
+      evidenceRevision: this.#evidenceRevision,
+    });
+  }
   getAllDiagnostics(): DiagnosticEntry[] {
-    const result: DiagnosticEntry[] = [];
-    for (const [uri, entry] of this.#diagnosticStore) {
-      if (entry.diagnostics.length === 0 || !existsSync(uriToFile(uri))) continue;
-      result.push({ uri, diagnostics: entry.diagnostics });
-    }
-    return result;
+    return this.getDiagnosticSnapshot().entries;
   }
-
-  /** Force the next pull refresh to request complete diagnostic reports. */
   clearPullResultIds(): void {
     for (const entry of this.#diagnosticStore.values()) delete entry.resultId;
   }
-
-  /** Apply diagnostics received through `textDocument/publishDiagnostics`. */
-  handlePublishDiagnostics(params: PublishDiagnosticsParams): void {
-    if (params.version !== undefined && params.version !== null) {
-      const openDoc = this.#openDocs.get(params.uri);
-      if (openDoc && params.version < openDoc.version) return;
+  /** Invalidate cache proof while retaining its data as partial fallback. */
+  invalidateCachedEvidence(): void {
+    this.#evidenceRevision++;
+    const knownUris = new Set([
+      ...this.#openDocs.keys(),
+      ...this.#diagnosticStore.keys(),
+      ...this.#versionHistory.keys(),
+      ...this.#failedUris,
+    ]);
+    // A watched-file notification is sent immediately after this call, so the
+    // recorded moment gates unversioned pushes around the invalidation: only
+    // pushes the server sends after the change can become fresh evidence.
+    const moment = Date.now();
+    for (const uri of knownUris) {
+      this.#unversionedPushSyncMoments.set(uri, moment);
+      this.#closedVersionedBarrier.add(uri);
     }
+  }
 
-    this.#diagnosticStore.set(params.uri, {
-      diagnostics: params.diagnostics,
-      receivedAt: Date.now(),
-      version: params.version ?? undefined,
+  handlePublishDiagnostics(params: unknown): void {
+    if (!isValidPublishDiagnosticsParams(params)) return;
+    const result = applyPushDiagnostics({
+      store: this.#diagnosticStore,
+      openDocuments: this.#openDocs,
+      params,
+      evidenceRevision: this.#evidenceRevision,
+      unversionedSyncMoment: this.#unversionedPushSyncMoments.get(params.uri),
+      closedVersionedBarrier: this.#closedVersionedBarrier.has(params.uri),
     });
-    this.#releaseDiagnosticWaiters(params.uri, "published");
+    if (!result.accepted) return;
+    const entry = this.#diagnosticStore.get(params.uri);
+    if (entry?.synchronizationId !== undefined && entry.evidenceRevision !== undefined) {
+      this.#publications.record(
+        params.uri,
+        entry.synchronizationId,
+        entry.evidenceRevision,
+        entry.receivedAt,
+      );
+      if (result.promoted) {
+        this.#publications.promoted(
+          params.uri,
+          entry.synchronizationId,
+          entry.evidenceRevision,
+          entry.receivedAt,
+        );
+      }
+    }
+    this.#waiters.releaseFile(params.uri, "published");
+    this.#waiters.notifySettle();
   }
-
-  /** Re-read open documents, then collect pull diagnostics or wait for push diagnostics. */
   async refreshOpenDiagnostics(
-    options: { maxWaitMs?: number; quietMs?: number } = {},
-  ): Promise<void> {
-    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();
-    observer.synchronized();
-    const documentCount = this.#openDocs.size;
-    if (documentCount === 0) {
-      observer.skipped(0);
-      return;
-    }
+    options: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl = {},
+  ): Promise<DiagnosticEvidenceSummary> {
+    return this.#refreshOpenDiagnostics(options, false);
+  }
 
-    if (supportsPull) {
-      try {
-        await this.#pullDiagnosticsForOpenDocuments(syncStart, maxWaitMs);
-        observer.pullCompleted(documentCount);
-        return;
-      } catch (error) {
-        observer.pullFailed(error);
-      }
-    }
+  /** Force a full document resynchronization for a server refresh request. */
+  async refreshForServerRequest(): Promise<DiagnosticEvidenceSummary> {
+    return this.#refreshOpenDiagnostics({}, true);
+  }
 
-    const settle = await this.#waitForDiagnosticSettle(syncStart, maxWaitMs, quietMs);
-    observer.pushSettled(documentCount, settle);
+  async #refreshOpenDiagnostics(
+    options: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl,
+    forceResynchronize: boolean,
+  ): Promise<DiagnosticEvidenceSummary> {
+    const requestedFiles = Array.from(
+      new Set([...this.#openDocs.keys(), ...this.#diagnosticStore.keys(), ...this.#failedUris]),
+    ).map(uriToFile);
+    return refreshClientOpenDiagnostics({
+      host: this.host,
+      openDocuments: this.#openDocs,
+      diagnosticStore: this.#diagnosticStore,
+      waiters: this.#waiters,
+      versionHistory: this.#versionHistory,
+      requestedFiles,
+      evidenceRevision: () => this.#evidenceRevision,
+      failedFiles: () => new Set(Array.from(this.#failedUris).map(uriToFile)),
+      isRelatedUriTracked: (uri) => this.#openDocs.has(uri) || this.#versionHistory.has(uri),
+      nextSynchronizationId: () => ++this.#nextSynchronizationId,
+      invalidateEvidence: (uri) => {
+        this.#failedUris.add(uri);
+        const document = this.#openDocs.get(uri);
+        if (document) document.evidenceRevision = -1;
+      },
+      clearFile: (uri) => {
+        this.#failedUris.delete(uri);
+        this.#unversionedPushSyncMoments.delete(uri);
+        this.#closedVersionedBarrier.add(uri);
+        clearTrackedDocumentState(this.#openDocs, this.#diagnosticStore, this.#waiters, uri);
+      },
+      markUnversionedSyncMoment: (uri) => this.#unversionedPushSyncMoments.set(uri, Date.now()),
+      clearFailedFile: (uri) => this.#failedUris.delete(uri),
+      forceResynchronize,
+      options,
+      publications: {
+        emitSummary: (summaryOptions) =>
+          this.#publications.emitSummary({
+            ...summaryOptions,
+            identity: {
+              server: this.host.server,
+              cwd: this.host.cwd,
+              ...summaryOptions.identity,
+            },
+          }),
+      },
+    });
   }
 
-  /** Sync one file and return its diagnostics after pull or push collection. */
-  async syncAndWaitForDiagnostics(filePath: string, content: string): Promise<Diagnostic[]> {
+  async syncAndWaitForDiagnostics(
+    filePath: string,
+    content: string,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Diagnostic[]>> {
+    // Reject immediately when the request was already cancelled: no document
+    // synchronization or protocol traffic may start for a caller that no
+    // longer awaits a result.
+    throwIfCodeRequestInterrupted(control);
     const supportsPull = this.host.supportsPullDiagnostics();
-    const observer = new DiagnosticObserver("sync-file", supportsPull);
+    const observer = new DiagnosticObserver("sync-file", supportsPull, control, {
+      server: this.host.server,
+      cwd: this.host.cwd,
+      file: relativeDiagnosticFile(this.host.cwd, filePath),
+    });
     const uri = fileToUri(filePath);
+    const cached = this.#diagnosticStore.get(uri);
+    const cachedDiagnostics = cached ? [...cached.diagnostics] : null;
     const syncStart = Date.now();
-    this.didChange(filePath, content);
+    const openDocument = this.#openDocs.get(uri);
+    const contentUnchanged =
+      openDocument?.contentFingerprint === fingerprintDocumentContent(content);
+    const synchronizationCurrent = openDocument?.evidenceRevision === this.#evidenceRevision;
+    // Equivalent content joins the current synchronization. Cached evidence
+    // cannot force a no-op didChange that cancels an in-flight push or pull.
+    if (!contentUnchanged || !synchronizationCurrent) {
+      synchronizeTrackedDocument({
+        uri,
+        content,
+        document: this.#openDocs.get(uri),
+        nextVersion: () => nextDocumentVersion(this.#versionHistory, uri),
+        nextSynchronizationId: () => ++this.#nextSynchronizationId,
+        evidenceRevision: this.#evidenceRevision,
+        incrementalSync: this.host.usesIncrementalDocumentSync(),
+        waiters: this.#waiters,
+        sendNotification: (method, params) => this.host.sendNotification(method, params),
+        markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
+        clearFailedFile: () => this.#failedUris.delete(uri),
+        open: () => this.didOpen(filePath, content),
+      });
+    }
+    const synchronization = this.#openDocs.get(uri);
     observer.synchronized();
-
-    if (supportsPull) {
-      const remaining = DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart);
-      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);
-      }
+    if (!synchronization) {
+      return unavailableCodeQuery("The document could not be synchronized for diagnostics.");
     }
-
-    const push = await this.#waitForDiagnostics(
+    if (
+      contentUnchanged &&
+      hasConfirmedDiagnosticEvidence(synchronization, cached, this.#evidenceRevision)
+    ) {
+      observer.cacheReused(1);
+      return completedCodeQuery(cachedDiagnostics ?? []);
+    }
+    const request = {
       uri,
-      Math.max(0, DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart)),
+      synchronizationId: synchronization.synchronizationId,
+      evidenceRevision: synchronization.evidenceRevision,
+    };
+    return this.#collectFileDiagnosticsWithReopenRetry(
+      {
+        filePath,
+        content,
+        uri,
+        supportsPull,
+        syncStart,
+        request,
+        cachedDiagnostics,
+        observer,
+      },
+      control,
     );
-    observer.pushWaitCompleted(1, push);
-    return this.getDiagnostics(filePath);
   }
 
-  #resyncOpenDocuments(): void {
-    for (const [uri, doc] of this.#openDocs) {
-      const filePath = uriToFile(uri);
-      try {
-        if (!existsSync(filePath)) {
-          this.#clearFileState(uri);
-          this.#sendDidClose(uri);
-          continue;
-        }
-        const content = readFileSync(filePath, "utf-8");
-        doc.version++;
-        this.#sendDidChange(uri, doc.version, content);
-      } catch {
-        // Keep the document open when a transient read fails.
+  /**
+   * Collect diagnostics for one synchronized document, retrying once through
+   * a reopen-resync on push-only routes when the first wait times out.
+   */
+  async #collectFileDiagnosticsWithReopenRetry(
+    options: {
+      filePath: string;
+      content: string;
+      uri: string;
+      supportsPull: boolean;
+      syncStart: number;
+      request: DiagnosticSynchronization;
+      cachedDiagnostics: Diagnostic[] | null;
+      observer: DiagnosticObserver;
+    },
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Diagnostic[]>> {
+    const {
+      filePath,
+      content,
+      uri,
+      supportsPull,
+      syncStart,
+      request,
+      cachedDiagnostics,
+      observer,
+    } = options;
+    let pushOutcome: DiagnosticPushWaitOutcome | undefined;
+    let attemptRequest = request;
+    let attemptSyncStart = syncStart;
+    let attemptMaxWaitMs = DIAGNOSTIC_WAIT_MS;
+    let reopenedOnce = false;
+    let result: CodeQueryResult<Diagnostic[]>;
+    for (;;) {
+      result = await collectSynchronizedFileDiagnostics(
+        {
+          supportsPull,
+          syncStart: attemptSyncStart,
+          maxWaitMs: attemptMaxWaitMs,
+          request: attemptRequest,
+          cachedDiagnostics,
+          observer,
+          waiters: this.#waiters,
+          current: () => isCurrentSynchronization(this.#openDocs, attemptRequest),
+          freshPush: () =>
+            hasFreshPush(this.#diagnosticStore, attemptRequest, this.#evidenceRevision),
+          currentPushReceivedAt: () => {
+            const entry = this.#diagnosticStore.get(attemptRequest.uri);
+            return entry?.source === "push" &&
+              hasCurrentEvidence(this.#diagnosticStore, attemptRequest, this.#evidenceRevision)
+              ? entry.receivedAt
+              : undefined;
+          },
+          diagnostics: () => this.getDiagnostics(filePath),
+          pullDiagnostics: (timeoutMs, signal) =>
+            pullClientDiagnosticEvidenceFromHost({
+              host: this.host,
+              store: this.#diagnosticStore,
+              openDocuments: this.#openDocs,
+              currentEvidenceRevision: () => this.#evidenceRevision,
+              isRelatedUriTracked: (relatedUri) =>
+                this.#openDocs.has(relatedUri) || this.#versionHistory.has(relatedUri),
+              request: {
+                uri,
+                timeoutMs,
+                synchronizationId: attemptRequest.synchronizationId,
+                evidenceRevision: attemptRequest.evidenceRevision ?? this.#evidenceRevision,
+                signal,
+                deadline: control?.deadline,
+                operationId: control?.operationId,
+              },
+            }),
+          onPushWait: (outcome) => {
+            pushOutcome = outcome;
+          },
+        },
+        control,
+      );
+      // Reopen-resync fallback (R2): on push-only routes a document that
+      // timed out with no push stays unconfirmed — a clean file gets no
+      // push on didChange at all. Close and reopen it over the protocol so
+      // the server publishes on didOpen, then wait once more with a bounded
+      // budget. The cache entry and version history survive the reopen.
+      const document = this.#openDocs.get(uri);
+      if (
+        supportsPull ||
+        reopenedOnce ||
+        result.kind === "completed" ||
+        pushOutcome !== "timed-out" ||
+        !document ||
+        !isCurrentSynchronization(this.#openDocs, attemptRequest)
+      ) {
+        break;
       }
-    }
-  }
-
-  async #pullDiagnosticsForOpenDocuments(syncStart: number, maxWaitMs: number): Promise<void> {
-    const deadline = syncStart + maxWaitMs;
-    const uris = Array.from(this.#openDocs.keys());
-    const results = await Promise.allSettled(
-      uris.map(async (uri) => {
-        const remaining = deadline - Date.now();
-        if (remaining <= 0) throw new Error("pull diagnostic timeout");
-        return this.#pullDiagnosticsForUri(uri, remaining);
-      }),
-    );
-
-    const anySuccess = results.some((result) => result.status === "fulfilled" && result.value);
-    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)));
-    }
-  }
-
-  async #pullDiagnosticsForUri(uri: string, timeoutMs: number): Promise<boolean> {
-    const previousResultId = this.#diagnosticStore.get(uri)?.resultId;
-    const report = await this.host.pullDocumentDiagnostics(uri, previousResultId, timeoutMs);
-    if (!report) return false;
-    this.#applyPullReport(uri, report);
-    return true;
-  }
-
-  #applyPullReport(uri: string, report: DocumentDiagnosticReport): void {
-    if (report.kind === "full") {
-      this.#diagnosticStore.set(uri, {
-        diagnostics: report.items,
-        receivedAt: Date.now(),
-        resultId: report.resultId,
-      });
-    } else {
-      const current = this.#diagnosticStore.get(uri);
-      if (current) current.resultId = report.resultId;
-    }
-
-    for (const [relatedUri, relatedReport] of Object.entries(report.relatedDocuments ?? {})) {
-      if (relatedReport.kind !== "full") continue;
-      this.#diagnosticStore.set(relatedUri, {
-        diagnostics: relatedReport.items,
-        receivedAt: Date.now(),
-        resultId: relatedReport.resultId,
+      reopenDocument({
+        uri,
+        content,
+        document,
+        languageId: detectLanguageId(filePath),
+        nextVersion: () => nextDocumentVersion(this.#versionHistory, uri),
+        nextSynchronizationId: () => ++this.#nextSynchronizationId,
+        evidenceRevision: this.#evidenceRevision,
+        waiters: this.#waiters,
+        sendNotification: (method, params) => this.host.sendNotification(method, params),
+        markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
       });
-    }
-  }
-
-  async #waitForDiagnosticSettle(
-    syncStart: number,
-    maxWaitMs: number,
-    quietMs: number,
-  ): Promise<DiagnosticSettleResult> {
-    const deadline = syncStart + maxWaitMs;
-    while (Date.now() < deadline) {
-      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 {
-    let latest = 0;
-    for (const entry of this.#diagnosticStore.values()) {
-      if (entry.receivedAt > afterTime && entry.receivedAt > latest) latest = entry.receivedAt;
-    }
-    return latest;
-  }
-
-  #sendDidChange(uri: string, version: number, content: string): void {
-    this.host.sendNotification("textDocument/didChange", {
-      textDocument: { uri, version } satisfies VersionedTextDocumentIdentifier,
-      contentChanges: [{ text: content }],
-    });
-  }
-
-  #sendDidClose(uri: string): void {
-    this.host.sendNotification("textDocument/didClose", {
-      textDocument: { uri } satisfies TextDocumentIdentifier,
-    });
-  }
-
-  #clearFileState(uri: string): void {
-    this.#openDocs.delete(uri);
-    this.#diagnosticStore.delete(uri);
-    this.#releaseDiagnosticWaiters(uri);
-  }
-
-  #waitForDiagnostics(uri: string, timeoutMs: number): Promise<DiagnosticPushWaitOutcome> {
-    if (timeoutMs <= 0) return Promise.resolve("timed-out");
-
-    return new Promise<DiagnosticPushWaitOutcome>((resolve) => {
-      const waiter: DiagnosticWaiter = (outcome) => {
-        clearTimeout(timer);
-        this.#removeDiagnosticWaiter(uri, waiter);
-        resolve(outcome);
+      observer.reopened(1);
+      reopenedOnce = true;
+      attemptRequest = {
+        uri,
+        synchronizationId: document.synchronizationId,
+        evidenceRevision: document.evidenceRevision,
       };
-      const timer = setTimeout(() => {
-        this.#removeDiagnosticWaiter(uri, waiter);
-        resolve("timed-out");
-      }, timeoutMs);
-      const waiters = this.#diagnosticWaiters.get(uri) ?? [];
-      waiters.push(waiter);
-      this.#diagnosticWaiters.set(uri, waiters);
-    });
-  }
-
-  #removeDiagnosticWaiter(uri: string, waiter: DiagnosticWaiter): void {
-    const waiters = this.#diagnosticWaiters.get(uri);
-    if (!waiters) return;
-    const next = waiters.filter((entry) => entry !== waiter);
-    if (next.length > 0) this.#diagnosticWaiters.set(uri, next);
-    else this.#diagnosticWaiters.delete(uri);
-  }
-
-  #releaseAllDiagnosticWaiters(): void {
-    for (const uri of Array.from(this.#diagnosticWaiters.keys())) {
-      this.#releaseDiagnosticWaiters(uri);
+      attemptSyncStart = Date.now();
+      attemptMaxWaitMs = REOPEN_EVIDENCE_WAIT_MS;
     }
+    observer.pushWaitCompleted(1, pushOutcome ?? "timed-out");
+    this.#publications.emitSummary({
+      operation: "sync-file",
+      identity: {
+        server: this.host.server,
+        cwd: this.host.cwd,
+        file: relativeDiagnosticFile(this.host.cwd, filePath),
+      },
+      synchronizations: [
+        {
+          uri,
+          synchronizationId: attemptRequest.synchronizationId,
+          evidenceRevision: attemptRequest.evidenceRevision ?? this.#evidenceRevision,
+          confirmed: result.kind === "completed",
+        },
+      ],
+      operationId: control?.operationId,
+    });
+    return result;
   }
+}
 
-  #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(outcome);
-  }
+/** Return a workspace-relative diagnostic file path for telemetry identity. */
+function relativeDiagnosticFile(cwd: string | undefined, filePath: string): string | undefined {
+  if (cwd === undefined) return undefined;
+  return path.relative(cwd, path.resolve(cwd, filePath));
 }