@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

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

@@ -0,0 +1,413 @@
+import {
+  type CodeQueryResult,
+  partialCodeQuery,
+  unavailableCodeQuery,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type {
+  Diagnostic,
+  DocumentDiagnosticReport,
+  PublishDiagnosticsParams,
+} from "../config/types.ts";
+import type { DiagnosticStateWait } from "./client-diagnostic-waiters.ts";
+
+/** Validate one untrusted LSP diagnostic publication before it enters the cache. */
+export function isValidPublishDiagnosticsParams(value: unknown): value is PublishDiagnosticsParams {
+  if (!isRecord(value) || !isValidUri(value.uri)) return false;
+  if (value.version !== undefined && !isInteger(value.version)) return false;
+  return Array.isArray(value.diagnostics) && value.diagnostics.every(isValidDiagnostic);
+}
+
+/** Validate one untrusted LSP pull report before it enters the cache. */
+export function isValidDocumentDiagnosticReport(
+  value: unknown,
+  allowRelatedDocuments = true,
+): value is DocumentDiagnosticReport {
+  if (!isRecord(value)) return false;
+  // gopls v0.23.0 ships a non-conforming pull report with an empty `kind`
+  // discriminator and no resultId (upstream work in progress). Treat a
+  // missing/empty kind with an items array as a full report; every other
+  // kind value stays strict.
+  if (value.kind === "full" || value.kind === undefined || value.kind === "") {
+    if (!Array.isArray(value.items) || !value.items.every(isValidDiagnostic)) return false;
+    if (value.resultId !== undefined && typeof value.resultId !== "string") return false;
+  } else if (value.kind === "unchanged") {
+    if (typeof value.resultId !== "string") return false;
+  } else {
+    return false;
+  }
+  return allowRelatedDocuments
+    ? isValidRelatedDocuments(value.relatedDocuments)
+    : value.relatedDocuments === undefined;
+}
+
+function isValidRelatedDocuments(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!isRecord(value)) return false;
+  return Object.entries(value).every(
+    ([uri, report]) => isValidUri(uri) && isValidDocumentDiagnosticReport(report, false),
+  );
+}
+
+function isValidDiagnostic(value: unknown): value is Diagnostic {
+  if (!isRecord(value) || !isValidRange(value.range) || !isValidDiagnosticMessage(value.message)) {
+    return false;
+  }
+  return (
+    isValidOptionalSeverity(value.severity) &&
+    isValidOptionalCode(value.code) &&
+    isValidOptionalCodeDescription(value.codeDescription, value.code) &&
+    isValidOptionalSource(value.source) &&
+    isValidOptionalTags(value.tags) &&
+    isValidOptionalRelatedInformation(value.relatedInformation)
+  );
+}
+
+function isValidOptionalSeverity(value: unknown): boolean {
+  return value === undefined || isDiagnosticSeverity(value);
+}
+
+function isValidOptionalCode(value: unknown): boolean {
+  return value === undefined || isInteger(value) || typeof value === "string";
+}
+
+function isValidOptionalCodeDescription(value: unknown, code: unknown): boolean {
+  return value === undefined || (code !== undefined && isRecord(value) && isValidUri(value.href));
+}
+
+function isValidOptionalSource(value: unknown): boolean {
+  return value === undefined || typeof value === "string";
+}
+
+function isValidOptionalTags(value: unknown): boolean {
+  return (
+    value === undefined || (Array.isArray(value) && value.every((tag) => tag === 1 || tag === 2))
+  );
+}
+
+function isValidOptionalRelatedInformation(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (Array.isArray(value) && value.every(isValidDiagnosticRelatedInformation))
+  );
+}
+
+function isValidDiagnosticMessage(value: unknown): boolean {
+  if (typeof value === "string") return true;
+  return (
+    isRecord(value) &&
+    (value.kind === "plaintext" || value.kind === "markdown") &&
+    typeof value.value === "string"
+  );
+}
+
+function isValidDiagnosticRelatedInformation(value: unknown): boolean {
+  return isRecord(value) && isValidLocation(value.location) && typeof value.message === "string";
+}
+
+function isValidLocation(value: unknown): boolean {
+  return isRecord(value) && isValidUri(value.uri) && isValidRange(value.range);
+}
+
+function isValidRange(value: unknown): value is {
+  start: { line: number; character: number };
+  end: { line: number; character: number };
+} {
+  if (!isRecord(value) || !isValidPosition(value.start) || !isValidPosition(value.end)) {
+    return false;
+  }
+  return (
+    value.start.line < value.end.line ||
+    (value.start.line === value.end.line && value.start.character <= value.end.character)
+  );
+}
+
+function isValidPosition(value: unknown): value is { line: number; character: number } {
+  return (
+    isRecord(value) &&
+    isInteger(value.line) &&
+    value.line >= 0 &&
+    value.line <= 2_147_483_647 &&
+    isInteger(value.character) &&
+    value.character >= 0 &&
+    value.character <= 2_147_483_647
+  );
+}
+
+function isValidUri(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0) return false;
+  try {
+    return new URL(value).protocol.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function isDiagnosticSeverity(value: unknown): boolean {
+  return value === 1 || value === 2 || value === 3 || value === 4;
+}
+
+function isInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Stored diagnostic data and the protocol evidence that established it. */
+export interface DiagnosticCacheEntry {
+  diagnostics: Diagnostic[];
+  receivedAt: number;
+  source: "pull" | "push";
+  synchronizationId?: number;
+  evidenceRevision?: number;
+  version?: number;
+  resultId?: string;
+  /**
+   * Valid publications observed for the entry's synchronization. The first
+   * valid publication for a synchronization is tentative; a later valid
+   * publication promotes the entry to confirmed (ADR 0021). A confirmed
+   * pull entry counts as the first publication when a push continues the
+   * same synchronization, so that push keeps the confirmation. Pull
+   * entries as such carry no count and are confirmed on arrival.
+   */
+  publications?: number;
+}
+
+/**
+ * Test whether one push entry is still tentative for its synchronization.
+ *
+ * A pull entry confirms on arrival; a push entry confirms only after a
+ * later valid publication for the same synchronization (ADR 0021).
+ */
+export function isTentativePushEntry(entry: DiagnosticCacheEntry | undefined): boolean {
+  return Boolean(entry && entry.source === "push" && (entry.publications ?? 1) < 2);
+}
+
+/** One document synchronization that needs current diagnostic evidence. */
+export interface DiagnosticSynchronization {
+  readonly uri: string;
+  readonly synchronizationId: number;
+  readonly evidenceRevision?: number;
+}
+
+/** Monotonic document version state retained across close and reopen. */
+export type DocumentVersionHistory = Map<string, number>;
+
+/** Allocate the next document version for one URI. */
+export function nextDocumentVersion(history: DocumentVersionHistory, uri: string): number {
+  const version = (history.get(uri) ?? 0) + 1;
+  history.set(uri, version);
+  return version;
+}
+
+/** Test whether a synchronization still names the open document state. */
+export function isCurrentSynchronization(
+  openDocs: ReadonlyMap<string, { synchronizationId: number; evidenceRevision?: number }>,
+  synchronization: DiagnosticSynchronization,
+): boolean {
+  const document = openDocs.get(synchronization.uri);
+  return Boolean(
+    document?.synchronizationId === synchronization.synchronizationId &&
+      (synchronization.evidenceRevision === undefined ||
+        document.evidenceRevision === synchronization.evidenceRevision),
+  );
+}
+
+/** Test whether a fresh push confirms the supplied synchronization. */
+export function hasFreshPush(
+  store: ReadonlyMap<string, DiagnosticCacheEntry>,
+  synchronization: DiagnosticSynchronization,
+  currentEvidenceRevision?: number,
+): boolean {
+  const entry = store.get(synchronization.uri);
+  return Boolean(
+    entry?.source === "push" &&
+      !isTentativePushEntry(entry) &&
+      entry.synchronizationId === synchronization.synchronizationId &&
+      (synchronization.evidenceRevision === undefined ||
+        entry.evidenceRevision === synchronization.evidenceRevision) &&
+      (currentEvidenceRevision === undefined || entry.evidenceRevision === currentEvidenceRevision),
+  );
+}
+
+/**
+ * Test whether stored evidence matches a synchronization without a
+ * confirmation gate. A tentative push matches here but cannot confirm.
+ */
+export function hasCurrentEvidence(
+  store: ReadonlyMap<string, DiagnosticCacheEntry>,
+  synchronization: DiagnosticSynchronization,
+  currentEvidenceRevision?: number,
+): boolean {
+  const entry = store.get(synchronization.uri);
+  return Boolean(
+    entry &&
+      entry.synchronizationId === synchronization.synchronizationId &&
+      (synchronization.evidenceRevision === undefined ||
+        entry.evidenceRevision === synchronization.evidenceRevision) &&
+      (currentEvidenceRevision === undefined || entry.evidenceRevision === currentEvidenceRevision),
+  );
+}
+
+/** Test whether pull or push evidence confirms the supplied synchronization. */
+export function hasFreshEvidence(
+  store: ReadonlyMap<string, DiagnosticCacheEntry>,
+  synchronization: DiagnosticSynchronization,
+  currentEvidenceRevision?: number,
+): boolean {
+  return (
+    hasCurrentEvidence(store, synchronization, currentEvidenceRevision) &&
+    !isTentativePushEntry(store.get(synchronization.uri))
+  );
+}
+
+/**
+ * Return the latest cache update that matches one of the synchronizations.
+ *
+ * Every accepted publication restarts the settle quiet period, tentative
+ * publications included, so this helper does not apply the confirmation
+ * gate (ADR 0021).
+ */
+export function latestCurrentEvidenceReceivedAt(
+  store: ReadonlyMap<string, DiagnosticCacheEntry>,
+  synchronizations: DiagnosticSynchronization[],
+  currentEvidenceRevision?: number,
+): number {
+  let latest = 0;
+  for (const synchronization of synchronizations) {
+    const entry = store.get(synchronization.uri);
+    if (hasCurrentEvidence(store, synchronization, currentEvidenceRevision)) {
+      latest = Math.max(latest, entry?.receivedAt ?? 0);
+    }
+  }
+  return latest;
+}
+
+interface PullRaceOptions {
+  readonly pull: Promise<boolean>;
+  readonly waitForChange: () => DiagnosticStateWait;
+  readonly freshPush: () => boolean;
+  readonly current: () => boolean;
+}
+
+/** Race a pull against fresh push evidence and lifecycle release. */
+export async function raceDiagnosticPull(
+  options: PullRaceOptions,
+): Promise<"pull" | "push" | "released"> {
+  const pull = options.pull.then((confirmed) =>
+    confirmed ? ("pull" as const) : ("released" as const),
+  );
+  while (options.current()) {
+    if (options.freshPush()) return "push";
+    const change = options.waitForChange();
+    let outcome: "changed" | "pull" | "released";
+    try {
+      outcome = await Promise.race([pull, change.promise.then(() => "changed" as const)]);
+    } finally {
+      change.cancel();
+    }
+    if (outcome !== "changed") return outcome;
+  }
+  return "released";
+}
+
+/** Return explicit partial or unavailable evidence after fresh collection fails. */
+export function incompleteDiagnosticResult(
+  cachedDiagnostics: Diagnostic[] | null,
+  outcome: "released" | "timed-out",
+): CodeQueryResult<Diagnostic[]> {
+  if (outcome === "released") {
+    return unavailableCodeQuery(
+      "Diagnostic collection ended before the current document synchronization was confirmed.",
+    );
+  }
+  if (cachedDiagnostics) {
+    return partialCodeQuery(
+      cachedDiagnostics,
+      "Fresh diagnostics were not confirmed for the current document synchronization; cached diagnostics are partial evidence.",
+    );
+  }
+  return unavailableCodeQuery(
+    "Fresh diagnostics were not confirmed for the current document synchronization.",
+  );
+}
+
+interface ApplyPullReportOptions {
+  readonly store: Map<string, DiagnosticCacheEntry>;
+  readonly uri: string;
+  readonly report: DocumentDiagnosticReport;
+  readonly previous: DiagnosticCacheEntry | undefined;
+  readonly previousResultId: string | undefined;
+  readonly synchronizationId: number | undefined;
+  readonly evidenceRevision: number;
+  readonly isRelatedUriTracked: (uri: string) => boolean;
+}
+
+/** Apply one valid full or linked unchanged pull report. */
+export function applyPullReport(options: ApplyPullReportOptions): boolean {
+  if (!isValidDocumentDiagnosticReport(options.report)) return false;
+  const {
+    store,
+    uri,
+    report,
+    previous,
+    previousResultId,
+    synchronizationId,
+    evidenceRevision,
+    isRelatedUriTracked,
+  } = options;
+  // A report validated as full (kind "full", "", or absent — gopls v0.23.0)
+  // stores its items; only an explicit "unchanged" reuses the previous entry.
+  if (report.kind !== "unchanged") {
+    if (!Array.isArray(report.items)) return false;
+    if (report.resultId !== undefined && typeof report.resultId !== "string") return false;
+    store.set(uri, {
+      diagnostics: report.items,
+      receivedAt: Date.now(),
+      source: "pull",
+      synchronizationId,
+      evidenceRevision,
+      resultId: report.resultId,
+    });
+    applyRelatedPullReports(store, report, evidenceRevision, isRelatedUriTracked);
+    return true;
+  }
+  if (!previous || previousResultId === undefined || typeof report.resultId !== "string") {
+    return false;
+  }
+  store.set(uri, {
+    ...previous,
+    receivedAt: Date.now(),
+    source: "pull",
+    synchronizationId,
+    evidenceRevision,
+    resultId: report.resultId,
+  });
+  applyRelatedPullReports(store, report, evidenceRevision, isRelatedUriTracked);
+  return true;
+}
+
+function applyRelatedPullReports(
+  store: Map<string, DiagnosticCacheEntry>,
+  report: DocumentDiagnosticReport,
+  evidenceRevision: number,
+  isRelatedUriTracked: (uri: string) => boolean,
+): void {
+  for (const [relatedUri, relatedReport] of Object.entries(report.relatedDocuments ?? {})) {
+    if (!isValidDocumentDiagnosticReport(relatedReport, false)) continue;
+    // Skip explicit unchanged reports; full reports (kind "full", "", or
+    // absent) may enter the related-document store.
+    if (relatedReport.kind === "unchanged") continue;
+    if (isRelatedUriTracked(relatedUri)) continue;
+    const existing = store.get(relatedUri);
+    if (existing?.evidenceRevision === evidenceRevision) continue;
+    store.set(relatedUri, {
+      diagnostics: relatedReport.items,
+      receivedAt: Date.now(),
+      source: "pull",
+      evidenceRevision,
+      resultId: relatedReport.resultId,
+    });
+  }
+}

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

@@ -0,0 +1,15 @@
+import type { DocumentDiagnosticReport } from "../config/types.ts";
+import type { DiagnosticPullRequest } from "./client-diagnostic-request.ts";
+
+/** Transport and capability operations required by diagnostic state. */
+export interface ClientDiagnosticsHost {
+  /** Configured server name, for debug-telemetry identity. */
+  server: string;
+  /** Absolute workspace root, for debug-telemetry identity. */
+  cwd?: string;
+  isOperational(): boolean;
+  supportsPullDiagnostics(): boolean;
+  usesIncrementalDocumentSync(): boolean;
+  sendNotification(method: string, params: unknown): void;
+  pullDocumentDiagnostics(request: DiagnosticPullRequest): Promise<DocumentDiagnosticReport | null>;
+}

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

@@ -0,0 +1,214 @@
+// Bounded push-publication telemetry for one client's diagnostic state.
+//
+// Push-only servers can publish an early result and a later semantic result
+// for one document synchronization (ADR 0021). This tracker records one
+// bounded per-synchronization publication summary per diagnostic operation
+// and one ambient event when a later publication promotes a synchronization
+// that an earlier operation already reported unconfirmed. Events carry only
+// bounded server, workspace, relative-file, synchronization identity, count,
+// and timing data. They never carry diagnostic payloads or source text.
+
+import * as path from "node:path";
+import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
+import { boundCwd, truncateIdentity } from "../debug-telemetry.ts";
+import { uriToFile } from "../utils.ts";
+
+/** Maximum tracked synchronizations before the oldest entry is evicted. */
+export const MAX_TRACKED_SYNCHRONIZATIONS = 64;
+
+/** Maximum synchronization entries in one bounded publication summary. */
+export const MAX_SUMMARY_SYNCHRONIZATIONS = 16;
+
+/** Maximum publication count retained for telemetry; 2 means two or more. */
+const MAX_PUBLICATIONS = 2;
+
+/** Bounded identity for one publication telemetry observation. */
+export interface DiagnosticPublicationIdentity {
+  /** Configured server name. */
+  readonly server?: string;
+  /** Absolute workspace root. */
+  readonly cwd?: string;
+  /** Workspace-relative file path; sync-file operations only. */
+  readonly file?: string;
+}
+
+/** One awaited synchronization of a completed diagnostic operation. */
+export interface DiagnosticPublicationSynchronization {
+  readonly uri: string;
+  readonly synchronizationId: number;
+  readonly evidenceRevision: number;
+  readonly confirmed: boolean;
+}
+
+/** One bounded per-synchronization publication summary entry. */
+export interface DiagnosticPublicationSummaryEntry {
+  readonly synchronizationId: number;
+  readonly publications: number;
+  readonly firstReceivedAt: number;
+  readonly lastReceivedAt: number;
+  readonly confirmed: boolean;
+}
+
+interface SynchronizationPublicationState {
+  readonly uri: string;
+  readonly synchronizationId: number;
+  readonly evidenceRevision: number;
+  publications: number;
+  firstReceivedAt: number;
+  lastReceivedAt: number;
+  /** When a finished operation first reported this synchronization unconfirmed. */
+  unconfirmedAt?: number;
+}
+
+function synchronizationKey(
+  uri: string,
+  synchronizationId: number,
+  evidenceRevision: number,
+): string {
+  return `${uri}|${synchronizationId}|${evidenceRevision}`;
+}
+
+/** Track bounded push-publication counts for one LSP client. */
+export class DiagnosticPublicationTracker {
+  readonly #states = new Map<string, SynchronizationPublicationState>();
+
+  constructor(
+    private readonly identity: { server?: string; cwd?: string },
+    private readonly fileFor: (uri: string) => string | undefined,
+  ) {}
+
+  /**
+   * Record one accepted push publication for a synchronization.
+   *
+   * The state map is bounded to {@link MAX_TRACKED_SYNCHRONIZATIONS}; the
+   * oldest tracked synchronization is evicted when the bound is exceeded.
+   */
+  record(
+    uri: string,
+    synchronizationId: number,
+    evidenceRevision: number,
+    receivedAt: number = Date.now(),
+  ): void {
+    const key = synchronizationKey(uri, synchronizationId, evidenceRevision);
+    const existing = this.#states.get(key);
+    if (existing) {
+      existing.publications = Math.min(existing.publications + 1, MAX_PUBLICATIONS);
+      existing.lastReceivedAt = receivedAt;
+      return;
+    }
+    this.#states.set(key, {
+      uri,
+      synchronizationId,
+      evidenceRevision,
+      publications: 1,
+      firstReceivedAt: receivedAt,
+      lastReceivedAt: receivedAt,
+    });
+    if (this.#states.size > MAX_TRACKED_SYNCHRONIZATIONS) {
+      const oldest = this.#states.keys().next().value;
+      if (oldest !== undefined) this.#states.delete(oldest);
+    }
+  }
+
+  /**
+   * Emit one bounded per-synchronization publication summary.
+   *
+   * Synchronizations with no observed push publication are omitted. A
+   * synchronization that ends unconfirmed is marked so a later promotion can
+   * emit the ambient late-republish event.
+   */
+  emitSummary(options: {
+    readonly operation: "refresh-open" | "sync-file";
+    readonly identity: DiagnosticPublicationIdentity;
+    readonly synchronizations: readonly DiagnosticPublicationSynchronization[];
+    readonly operationId?: string;
+  }): void {
+    const entries: DiagnosticPublicationSummaryEntry[] = [];
+    const now = Date.now();
+    for (const synchronization of options.synchronizations) {
+      const state = this.#states.get(
+        synchronizationKey(
+          synchronization.uri,
+          synchronization.synchronizationId,
+          synchronization.evidenceRevision,
+        ),
+      );
+      if (!state) continue;
+      entries.push({
+        synchronizationId: state.synchronizationId,
+        publications: state.publications,
+        firstReceivedAt: state.firstReceivedAt,
+        lastReceivedAt: state.lastReceivedAt,
+        confirmed: synchronization.confirmed,
+      });
+      if (!synchronization.confirmed) state.unconfirmedAt ??= now;
+      else state.unconfirmedAt = undefined;
+    }
+    if (entries.length === 0) return;
+    recordDebugEvent({
+      operationId: options.operationId,
+      source: "lsp",
+      level: "debug",
+      category: "diagnostics.publication",
+      message: "LSP diagnostic publication summary",
+      cwd: boundCwd(options.identity.cwd),
+      data: {
+        operation: options.operation,
+        synchronizations: entries.slice(0, MAX_SUMMARY_SYNCHRONIZATIONS),
+        ...(options.identity.server !== undefined
+          ? { server: truncateIdentity(options.identity.server) }
+          : {}),
+        ...(options.identity.file !== undefined
+          ? { file: truncateIdentity(options.identity.file) }
+          : {}),
+      },
+    });
+  }
+
+  /**
+   * Observe one promotion of a synchronization by a later publication.
+   *
+   * The ambient late-republish event fires only when a finished operation
+   * previously reported the synchronization unconfirmed. The mark is cleared
+   * so one promotion emits at most one event.
+   */
+  promoted(
+    uri: string,
+    synchronizationId: number,
+    evidenceRevision: number,
+    receivedAt: number = Date.now(),
+  ): void {
+    const state = this.#states.get(synchronizationKey(uri, synchronizationId, evidenceRevision));
+    const unconfirmedAt = state?.unconfirmedAt;
+    if (!state || state.publications < 2 || unconfirmedAt === undefined) return;
+    state.unconfirmedAt = undefined;
+    const file = this.fileFor(uri);
+    recordDebugEvent({
+      source: "lsp",
+      level: "debug",
+      category: "diagnostics.publication",
+      message: "LSP diagnostic late republish",
+      cwd: boundCwd(this.identity.cwd),
+      data: {
+        synchronizationId,
+        publications: state.publications,
+        receivedAt,
+        delayMs: Math.max(0, receivedAt - unconfirmedAt),
+        ...(this.identity.server !== undefined
+          ? { server: truncateIdentity(this.identity.server) }
+          : {}),
+        ...(file !== undefined ? { file: truncateIdentity(file) } : {}),
+      },
+    });
+  }
+}
+
+/** Return a workspace-relative diagnostic file path for telemetry identity. */
+export function trackerFileIdentityFor(
+  cwd: string | undefined,
+): (uri: string) => string | undefined {
+  return (uri) => {
+    if (cwd === undefined) return undefined;
+    return path.relative(cwd, path.resolve(cwd, uriToFile(uri)));
+  };
+}

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

@@ -0,0 +1,62 @@
+import { CodeRequestDeadlineError } from "@mrclrchtr/supi-code-runtime/api";
+import type { DocumentDiagnosticReport } from "../config/types.ts";
+import { applyPullReport, type DiagnosticCacheEntry } from "./client-diagnostic-evidence.ts";
+import type { DiagnosticPullRequest } from "./client-diagnostic-request.ts";
+
+interface PullDiagnosticEvidenceOptions {
+  store: Map<string, DiagnosticCacheEntry>;
+  uri: string;
+  timeoutMs: number;
+  synchronizationId?: number;
+  evidenceRevision: number;
+  currentRevision(): number;
+  isCurrentSynchronization(): boolean;
+  isRelatedUriTracked(uri: string): boolean;
+  signal?: AbortSignal;
+  deadline?: number;
+  operationId?: string;
+  pull(request: DiagnosticPullRequest): Promise<DocumentDiagnosticReport | null>;
+}
+
+/** Collect one pull report only if its document and workspace generations remain current. */
+export async function pullDiagnosticEvidence(
+  options: PullDiagnosticEvidenceOptions,
+): Promise<boolean> {
+  const previous = options.store.get(options.uri);
+  const previousResultId = previous?.resultId;
+  const report = await options.pull({
+    uri: options.uri,
+    previousResultId,
+    timeoutMs: options.timeoutMs,
+    signal: options.signal,
+    deadline: options.deadline,
+    operationId: options.operationId,
+  });
+  // Final gate: a report that lands after cancellation or deadline expiry
+  // must not be applied as evidence.
+  if (options.signal?.aborted) throw options.signal.reason;
+  if (options.deadline !== undefined && Date.now() >= options.deadline) {
+    throw new CodeRequestDeadlineError();
+  }
+  if (report === null || report === undefined) {
+    throw new Error("Invalid LSP diagnostic report.");
+  }
+  if (
+    options.evidenceRevision !== options.currentRevision() ||
+    (options.synchronizationId !== undefined && !options.isCurrentSynchronization())
+  ) {
+    return false;
+  }
+  const applied = applyPullReport({
+    store: options.store,
+    uri: options.uri,
+    report,
+    previous,
+    previousResultId,
+    synchronizationId: options.synchronizationId,
+    evidenceRevision: options.evidenceRevision,
+    isRelatedUriTracked: options.isRelatedUriTracked,
+  });
+  if (!applied) throw new Error("Invalid LSP diagnostic report.");
+  return true;
+}