@mrclrchtr/supi-code-intelligence 4.9.0 → 5.0.0

package/node_modules/@mrclrchtr/supi-tree-sitter/src/worker/worker-main.ts

@@ -0,0 +1,201 @@
+import type { MessagePort } from "node:worker_threads";
+import { isCodeRequestDeadlineError } from "@mrclrchtr/supi-code-runtime/api";
+import type { StructuralTimingEvent } from "../session/structural-timing.ts";
+import { assertStructuralProtocolMessageSize } from "../session/structural-worker-message-size.ts";
+import {
+  encodeStructuralResult,
+  type ParentToStructuralWorkerMessage,
+  STRUCTURAL_WORKER_PROTOCOL_VERSION,
+  type StructuralWorkerChunkAckMessage,
+  type StructuralWorkerRequestMessage,
+  validateStructuralWorkerRequest,
+} from "../session/structural-worker-protocol.ts";
+import type { TreeSitterResult } from "../types.ts";
+import type { StructuralRequestControl } from "./request-control.ts";
+import { TreeSitterRuntime } from "./runtime.ts";
+import { StructuralWorkerService } from "./service.ts";
+
+interface WorkerBootstrapData {
+  readonly cwd: string;
+  readonly generation: number;
+}
+
+interface ActiveWorkerRequest {
+  readonly message: StructuralWorkerRequestMessage;
+  readonly control: StructuralRequestControl;
+  readonly abortController: AbortController;
+  chunks: Uint8Array[];
+  nextSequence: number;
+  awaitingAck: boolean;
+  outcome: "completed" | "cancelled" | "timeout";
+}
+
+/** Start the package-private Structural Worker implementation. */
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: one Worker loop owns active request and chunk acknowledgement state
+export async function runStructuralWorker(
+  parentPort: MessagePort,
+  workerData: WorkerBootstrapData,
+): Promise<void> {
+  const runtime = new TreeSitterRuntime(workerData.cwd, (event) => forwardObservation(event));
+  const service = new StructuralWorkerService(runtime);
+  let active: ActiveWorkerRequest | null = null;
+
+  const post = (message: unknown) => {
+    assertStructuralProtocolMessageSize(message);
+    parentPort.postMessage(message);
+  };
+  const forwardObservation = (observation: StructuralTimingEvent) => {
+    if (!active) return;
+    post({
+      kind: "observation",
+      version: STRUCTURAL_WORKER_PROTOCOL_VERSION,
+      generation: workerData.generation,
+      requestId: active.message.requestId,
+      observation,
+    });
+  };
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: protocol dispatch keeps request, cancel, and acknowledgement validation together
+  parentPort.on("message", (message: ParentToStructuralWorkerMessage) => {
+    if (message.version !== STRUCTURAL_WORKER_PROTOCOL_VERSION) return;
+    if (message.generation !== workerData.generation) return;
+    if (message.kind === "cancel") {
+      if (active?.message.requestId === message.requestId) active.abortController.abort();
+      return;
+    }
+    if (message.kind === "chunk-ack") {
+      if (active?.message.requestId === message.requestId) sendNextChunk(message);
+      return;
+    }
+    if (message.kind !== "request" || active) return;
+    const validation = validateStructuralWorkerRequest(message);
+    if (validation.kind === "invalid") return;
+    void execute(validation.message);
+  });
+
+  try {
+    await runtime.ensureGrammarParser("javascript");
+    post({
+      kind: "ready",
+      version: STRUCTURAL_WORKER_PROTOCOL_VERSION,
+      generation: workerData.generation,
+    });
+  } catch (error) {
+    post({
+      kind: "startup-failure",
+      version: STRUCTURAL_WORKER_PROTOCOL_VERSION,
+      generation: workerData.generation,
+      message: error instanceof Error ? error.message : "Structural Worker startup failed",
+    });
+    runtime.dispose();
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one terminal boundary classifies every operation result and interruption
+  async function execute(message: StructuralWorkerRequestMessage): Promise<void> {
+    const abortController = new AbortController();
+    const cancellationFlag = new Int32Array(message.cancellationFlag);
+    const control: StructuralRequestControl = {
+      operationId: message.operationId,
+      signal: abortController.signal,
+      deadline: message.deadline,
+      cancellationFlag,
+    };
+    active = {
+      message,
+      control,
+      abortController,
+      chunks: [],
+      nextSequence: 0,
+      awaitingAck: false,
+      outcome: "completed",
+    };
+    let result: TreeSitterResult<unknown>;
+    try {
+      result = await service.execute(message.input, control);
+    } catch (error) {
+      const timedOut =
+        isCodeRequestDeadlineError(error) ||
+        (message.deadline !== undefined && Date.now() >= message.deadline);
+      const cancelled = abortController.signal.aborted || Atomics.load(cancellationFlag, 0) !== 0;
+      active.outcome = timedOut ? "timeout" : cancelled ? "cancelled" : "completed";
+      result = {
+        kind: "runtime-error",
+        message: timedOut
+          ? "Structural request deadline exceeded"
+          : cancelled
+            ? "Structural request cancelled"
+            : error instanceof Error
+              ? error.message
+              : "Structural Worker operation failed",
+      };
+    }
+    if (!active || active.message.requestId !== message.requestId) return;
+    try {
+      active.chunks = encodeStructuralResult(result);
+    } catch (error) {
+      active.chunks = encodeStructuralResult({
+        kind: "runtime-error",
+        message: error instanceof Error ? error.message : "Structural result encoding failed",
+      });
+    }
+    sendChunk();
+  }
+
+  function sendNextChunk(message: StructuralWorkerChunkAckMessage): void {
+    if (!active?.awaitingAck || message.sequence !== active.nextSequence - 1) return;
+    active.awaitingAck = false;
+    if (active.nextSequence >= active.chunks.length) {
+      postTerminal();
+      return;
+    }
+    sendChunk();
+  }
+
+  function sendChunk(): void {
+    if (!active || active.awaitingAck) return;
+    updateInterruptionOutcome(active);
+    const sequence = active.nextSequence;
+    const payload = active.chunks[sequence];
+    if (!payload) {
+      postTerminal();
+      return;
+    }
+    active.nextSequence += 1;
+    active.awaitingAck = true;
+    post({
+      kind: "chunk",
+      version: STRUCTURAL_WORKER_PROTOCOL_VERSION,
+      generation: workerData.generation,
+      requestId: active.message.requestId,
+      sequence,
+      final: active.nextSequence === active.chunks.length,
+      encodedBytes: payload.byteLength,
+      payload,
+    });
+  }
+
+  function postTerminal(): void {
+    if (!active) return;
+    updateInterruptionOutcome(active);
+    post({
+      kind: "terminal",
+      version: STRUCTURAL_WORKER_PROTOCOL_VERSION,
+      generation: workerData.generation,
+      requestId: active.message.requestId,
+      outcome: active.outcome,
+    });
+    active = null;
+  }
+
+  function updateInterruptionOutcome(request: ActiveWorkerRequest): void {
+    if (request.message.deadline !== undefined && Date.now() >= request.message.deadline) {
+      request.outcome = "timeout";
+    } else if (
+      request.abortController.signal.aborted ||
+      (request.control.cancellationFlag !== undefined &&
+        Atomics.load(request.control.cancellationFlag, 0) !== 0)
+    ) {
+      request.outcome = "cancelled";
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-intelligence",
-  "version": "4.9.0",
+  "version": "5.0.0",
   "description": "LSP and AST navigation, search, diagnostics, and refactoring",
   "license": "MIT",
   "repository": {
@@ -35,10 +35,10 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
-    "@mrclrchtr/supi-code-runtime": "4.9.0",
-    "@mrclrchtr/supi-core": "4.9.0",
-    "@mrclrchtr/supi-tree-sitter": "4.9.0",
-    "@mrclrchtr/supi-lsp": "4.9.0"
+    "@mrclrchtr/supi-core": "5.0.0",
+    "@mrclrchtr/supi-lsp": "5.0.0",
+    "@mrclrchtr/supi-tree-sitter": "5.0.0",
+    "@mrclrchtr/supi-code-runtime": "5.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/src/analysis/health/diagnostics.ts

@@ -2,9 +2,19 @@
 // Extracted from orchestrate.ts.
 
 import { existsSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
+import {
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+} from "@mrclrchtr/supi-code-runtime/api";
 import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
-import type { Diagnostic, WorkspaceLspRuntime } from "@mrclrchtr/supi-lsp/api";
+import type {
+  Diagnostic,
+  DiagnosticEvidenceDocument,
+  DiagnosticEvidenceSummary,
+  WorkspaceLspRuntime,
+} from "@mrclrchtr/supi-lsp/api";
+import { mergeDiagnosticEvidence } from "../../diagnostics/evidence.ts";
 import type {
   HealthDiagnosticEntry,
   HealthDiagnosticMessage,
@@ -28,60 +38,117 @@ export function diagnosticScope(scopeFilter: string | null): HealthDiagnosticSco
 
 interface CollectDiagnosticsOptions {
   readonly service: WorkspaceLspRuntime | null;
+  /** Runtime used for evidence snapshots when semantic operations are unavailable. */
+  readonly evidenceService?: WorkspaceLspRuntime | null;
   readonly included: readonly HealthSection[];
   readonly scope: HealthDiagnosticScope;
   readonly cwd: string;
   readonly unavailableReason: string;
   /** Collect individual messages per file (detailed level). */
   readonly detailed?: boolean;
+  readonly requestControl?: CodeRequestControl;
+  /** Final evidence from an explicit workspace refresh, when one ran. */
+  readonly refreshEvidence?: DiagnosticEvidenceSummary;
 }
 
 /** Collect diagnostics without widening the requested evidence scope. */
 export async function collectDiagnostics(
   options: CollectDiagnosticsOptions,
 ): Promise<HealthDiagnosticObservation> {
-  const { service, included, scope, cwd, unavailableReason, detailed } = options;
+  const { service, included, scope, cwd, unavailableReason, detailed, requestControl } = options;
   if (!included.includes("diagnostics")) return { kind: "not-requested", entries: [] };
-  if (!service) return unavailableDiagnostics(scope, unavailableReason);
+  if (!service) {
+    return unavailableDiagnostics(
+      scope,
+      unavailableReason,
+      unavailableScopeEvidence(scope, options.refreshEvidence, options.evidenceService, cwd),
+    );
+  }
 
   return scope.kind === "file"
-    ? collectScopedFileDiagnostics(service, scope, detailed)
-    : collectTrackedFileDiagnostics(service, scope, cwd, detailed);
+    ? collectScopedFileDiagnostics(service, scope, detailed, requestControl)
+    : collectTrackedFileDiagnostics({
+        service,
+        scope,
+        cwd,
+        detailed,
+        refreshEvidence: options.refreshEvidence,
+      });
 }
 
 async function collectScopedFileDiagnostics(
   service: WorkspaceLspRuntime,
   scope: Extract<HealthDiagnosticScope, { kind: "file" }>,
   detailed?: boolean,
+  requestControl?: CodeRequestControl,
 ): Promise<HealthDiagnosticObservation> {
   try {
-    const result = await service.fileDiagnostics(scope.path, 4);
-    if (result.kind === "unavailable") return unavailableDiagnostics(scope, result.reason);
+    const result = await service.fileDiagnostics(scope.path, 4, requestControl);
+    if (result.kind === "unavailable") {
+      return unavailableDiagnostics(scope, result.reason, unavailableFileEvidence(scope.path));
+    }
 
     const entries = toFileDiagnosticEntries(scope.path, result.data, detailed);
     return result.kind === "partial"
-      ? { kind: "partial", scope, entries, reason: result.reason }
-      : { kind: "completed", scope, entries };
+      ? {
+          kind: "partial",
+          scope,
+          entries,
+          evidence: singleFileEvidence(scope.path, "unconfirmed"),
+          reason: result.reason,
+        }
+      : {
+          kind: "completed",
+          scope,
+          entries,
+          evidence: singleFileEvidence(scope.path, "confirmed"),
+        };
   } catch (error) {
-    return unavailableDiagnostics(scope, errorMessage(error, "File diagnostic request failed."));
+    if (isCodeRequestInterruption(error, requestControl)) throw error;
+    return unavailableDiagnostics(
+      scope,
+      errorMessage(error, "File diagnostic request failed."),
+      unavailableFileEvidence(scope.path),
+    );
   }
 }
 
+interface TrackedFileDiagnosticOptions {
+  readonly service: WorkspaceLspRuntime;
+  readonly scope: Extract<HealthDiagnosticScope, { kind: "tracked-files" }>;
+  readonly cwd: string;
+  readonly detailed?: boolean;
+  readonly refreshEvidence?: DiagnosticEvidenceSummary;
+}
+
 function collectTrackedFileDiagnostics(
-  service: WorkspaceLspRuntime,
-  scope: Extract<HealthDiagnosticScope, { kind: "tracked-files" }>,
-  cwd: string,
-  detailed?: boolean,
+  options: TrackedFileDiagnosticOptions,
 ): HealthDiagnosticObservation {
+  const { service, scope, cwd, detailed, refreshEvidence } = options;
   try {
-    const entries = detailed
+    const snapshot = detailed
       ? collectWorkspaceDiagnosticsDetailed(service, scope.filter, cwd)
       : collectWorkspaceDiagnostics(service, scope.filter, cwd);
-    return { kind: "completed", scope, entries };
+    const sourceEvidence = mergeEvidence(refreshEvidence, snapshot.evidence, cwd);
+    const scopedEvidence = selectTrackedFileEvidence(sourceEvidence, scope.filter, cwd);
+    const evidence = ensureEvidenceCoversEntries(scopedEvidence, snapshot.entries, cwd);
+    return evidenceIsComplete(evidence, snapshot.entries.length > 0, snapshot.current)
+      ? { kind: "completed", scope, entries: snapshot.entries, evidence }
+      : {
+          kind: "partial",
+          scope,
+          entries: snapshot.entries,
+          evidence,
+          reason: diagnosticEvidenceReason(evidence),
+        };
   } catch (error) {
+    const evidence = options.refreshEvidence
+      ? selectTrackedFileEvidence(options.refreshEvidence, scope.filter, cwd)
+      : emptyEvidence();
     return unavailableDiagnostics(
       scope,
       errorMessage(error, "Tracked-file diagnostic snapshot is unavailable."),
+      evidence,
     );
   }
 }
@@ -105,18 +172,22 @@ function collectWorkspaceDiagnostics(
   service: WorkspaceLspRuntime,
   scopeFilter: string | null,
   cwd: string,
-): HealthDiagnosticEntry[] {
+): {
+  entries: HealthDiagnosticEntry[];
+  current: boolean;
+  evidence: DiagnosticEvidenceSummary;
+} {
   const summary = service.getWorkspaceDiagnosticSummary();
   const result: HealthDiagnosticEntry[] = [];
 
-  for (const entry of summary) {
+  for (const entry of summary.entries) {
     const filePath = resolve(cwd, entry.file);
     if (scopeFilter && !isWithinOrEqual(scopeFilter, filePath)) continue;
     if (!hasIssueCounts(entry.errors, entry.warnings)) continue;
     result.push({ file: filePath, errors: entry.errors, warnings: entry.warnings });
   }
 
-  return result;
+  return { entries: result, current: summary.current, evidence: summary.evidence };
 }
 
 /** Detailed workspace path: full diagnostics with messages, capped per file. */
@@ -124,18 +195,22 @@ function collectWorkspaceDiagnosticsDetailed(
   service: WorkspaceLspRuntime,
   scopeFilter: string | null,
   cwd: string,
-): HealthDiagnosticEntry[] {
+): {
+  entries: HealthDiagnosticEntry[];
+  current: boolean;
+  evidence: DiagnosticEvidenceSummary;
+} {
   const outstanding = service.getOutstandingDiagnostics(2);
   const result: HealthDiagnosticEntry[] = [];
 
-  for (const { file, diagnostics } of outstanding) {
+  for (const { file, diagnostics } of outstanding.entries) {
     const filePath = resolve(cwd, file);
     if (scopeFilter && !isWithinOrEqual(scopeFilter, filePath)) continue;
     const entries = toFileDiagnosticEntries(filePath, diagnostics, true);
     result.push(...entries);
   }
 
-  return result;
+  return { entries: result, current: outstanding.current, evidence: outstanding.evidence };
 }
 
 // ── Message extraction ────────────────────────────────────────────────
@@ -159,11 +234,49 @@ function extractMessages(
   }));
 }
 
+function unavailableScopeEvidence(
+  scope: HealthDiagnosticScope,
+  refreshEvidence: DiagnosticEvidenceSummary | undefined,
+  evidenceService: WorkspaceLspRuntime | null | undefined,
+  cwd: string,
+): DiagnosticEvidenceSummary {
+  const runtimeEvidence = readRuntimeEvidence(evidenceService);
+  const knownEvidence = refreshEvidence
+    ? mergeDiagnosticEvidence(refreshEvidence, runtimeEvidence, cwd, "conservative")
+    : runtimeEvidence;
+  if (knownEvidence.requested === 0 && knownEvidence.documents.length === 0) {
+    return scope.kind === "file" ? unavailableFileEvidence(scope.path) : emptyEvidence();
+  }
+  const scoped = selectTrackedFileEvidence(
+    knownEvidence,
+    scope.kind === "file" ? scope.path : scope.filter,
+    cwd,
+  );
+  if (scoped.requested > 0) return scoped;
+  return scope.kind === "file" ? unavailableFileEvidence(scope.path) : scoped;
+}
+
+function unavailableFileEvidence(file: string): DiagnosticEvidenceSummary {
+  return singleFileEvidence(file, existsSync(file) ? "failed" : "removed");
+}
+
+function readRuntimeEvidence(
+  service: WorkspaceLspRuntime | null | undefined,
+): DiagnosticEvidenceSummary {
+  if (!service) return emptyEvidence();
+  try {
+    return service.getWorkspaceDiagnosticSummary().evidence;
+  } catch {
+    return emptyEvidence();
+  }
+}
+
 function unavailableDiagnostics(
   scope: HealthDiagnosticScope,
   reason: string,
+  evidence: DiagnosticEvidenceSummary = emptyEvidence(),
 ): HealthDiagnosticObservation {
-  return { kind: "unavailable", scope, entries: [], reason };
+  return { kind: "unavailable", scope, entries: [], evidence, reason };
 }
 
 function errorMessage(error: unknown, fallback: string): string {
@@ -174,6 +287,105 @@ function hasIssueCounts(errors: number, warnings: number): boolean {
   return errors > 0 || warnings > 0;
 }
 
+function emptyEvidence(): DiagnosticEvidenceSummary {
+  return {
+    requested: 0,
+    confirmed: 0,
+    unconfirmed: 0,
+    failed: 0,
+    removed: 0,
+    documents: [],
+  };
+}
+
+function singleFileEvidence(
+  file: string,
+  status: DiagnosticEvidenceDocument["status"],
+): DiagnosticEvidenceSummary {
+  return {
+    requested: 1,
+    confirmed: status === "confirmed" ? 1 : 0,
+    unconfirmed: status === "unconfirmed" ? 1 : 0,
+    failed: status === "failed" ? 1 : 0,
+    removed: status === "removed" ? 1 : 0,
+    documents: [{ file, status }],
+  };
+}
+
+function mergeEvidence(
+  refreshEvidence: DiagnosticEvidenceSummary | undefined,
+  snapshotEvidence: DiagnosticEvidenceSummary,
+  cwd: string,
+): DiagnosticEvidenceSummary {
+  return refreshEvidence
+    ? mergeDiagnosticEvidence(refreshEvidence, snapshotEvidence, cwd, "conservative")
+    : snapshotEvidence;
+}
+
+function selectTrackedFileEvidence(
+  evidence: DiagnosticEvidenceSummary,
+  scopeFilter: string | null,
+  cwd: string,
+): DiagnosticEvidenceSummary {
+  if (evidence.documents.length === 0) return evidence;
+
+  const documents = evidence.documents.filter((document) => {
+    if (scopeFilter === null) return true;
+    return isWithinOrEqual(scopeFilter, resolve(cwd, document.file));
+  });
+  return summarizeEvidence(documents);
+}
+
+function ensureEvidenceCoversEntries(
+  evidence: DiagnosticEvidenceSummary,
+  entries: readonly HealthDiagnosticEntry[],
+  cwd: string,
+): DiagnosticEvidenceSummary {
+  if (entries.length === 0) return evidence;
+  const documents = [...evidence.documents];
+  const knownFiles = new Set(documents.map((document) => resolve(cwd, document.file)));
+  for (const entry of entries) {
+    const file = resolve(cwd, entry.file);
+    if (knownFiles.has(file)) continue;
+    knownFiles.add(file);
+    documents.push({ file: relative(cwd, file), status: "unconfirmed" });
+  }
+  return summarizeEvidence(documents);
+}
+
+function summarizeEvidence(
+  documents: readonly DiagnosticEvidenceDocument[],
+): DiagnosticEvidenceSummary {
+  const counts = {
+    requested: documents.length,
+    confirmed: 0,
+    unconfirmed: 0,
+    failed: 0,
+    removed: 0,
+  };
+  for (const document of documents) counts[document.status]++;
+  return { ...counts, documents: [...documents] };
+}
+
+function evidenceIsComplete(
+  evidence: DiagnosticEvidenceSummary,
+  hasDiagnosticEntries: boolean,
+  snapshotCurrent: boolean,
+): boolean {
+  if (!snapshotCurrent && evidence.requested === 0) return false;
+  if (evidence.requested === 0) return !hasDiagnosticEntries;
+  return (
+    evidence.confirmed === evidence.requested &&
+    evidence.unconfirmed === 0 &&
+    evidence.failed === 0 &&
+    evidence.removed === 0
+  );
+}
+
+function diagnosticEvidenceReason(evidence: DiagnosticEvidenceSummary): string {
+  return `Diagnostic evidence is partial: ${evidence.requested} requested, ${evidence.confirmed} confirmed, ${evidence.unconfirmed} unconfirmed, ${evidence.failed} failed, ${evidence.removed} removed.`;
+}
+
 export function isDirectory(filePath: string): boolean {
   try {
     return statSync(filePath).isDirectory();

package/src/analysis/health/recovery.ts

@@ -1,7 +1,7 @@
 // Recovery and state description helpers for code_health.
 // Extracted from orchestrate.ts.
 
-import type { CapabilityState } from "@mrclrchtr/supi-code-runtime/api";
+import type { CapabilityState, CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import type { RecoverDiagnosticsResult, WorkspaceLspRuntime } from "@mrclrchtr/supi-lsp/api";
 
 // ── Recovery ──────────────────────────────────────────────────────────
@@ -9,6 +9,7 @@ import type { RecoverDiagnosticsResult, WorkspaceLspRuntime } from "@mrclrchtr/s
 interface RecoverOptions {
   service: WorkspaceLspRuntime;
   progress?: () => void;
+  control?: CodeRequestControl;
 }
 
 /** Run the runtime's best-effort recovery and preserve its established outcome. */
@@ -16,7 +17,10 @@ export async function recoverDiagnosticRuntime(
   opts: RecoverOptions,
 ): Promise<RecoverDiagnosticsResult> {
   opts.progress?.();
-  return opts.service.recoverDiagnostics({ restartIfStillStale: true });
+  return opts.service.recoverDiagnostics({
+    restartIfStillStale: true,
+    control: opts.control,
+  });
 }
 
 // ── State description helpers ─────────────────────────────────────────

package/src/analysis/provider.ts

@@ -11,6 +11,7 @@
  */
 
 import {
+  type CodeRequestControl,
   getDefaultWorkspaceRuntime,
   type SemanticProvider,
   type StructuralProvider,
@@ -85,6 +86,54 @@ export function getCodeProviderState(cwd: string): CodeProviderState {
 /** Alias for getCodeProviderState — kept for backward compatibility. */
 export const getCodeProvider = getCodeProviderState;
 
+/** Bind one exact request-control value to every semantic provider operation. */
+export function withSemanticRequestControl<T extends SemanticProvider>(
+  provider: T | null,
+  control: CodeRequestControl | undefined,
+): T | null {
+  if (!provider || !control) return provider;
+  return {
+    ...provider,
+    references: (file, position) => provider.references(file, position, control),
+    implementation: (file, position) => provider.implementation(file, position, control),
+    documentSymbols: (file) => provider.documentSymbols(file, control),
+    workspaceSymbols: (query) => provider.workspaceSymbols(query, control),
+    hover: provider.hover
+      ? (file, position) => provider.hover?.(file, position, control)
+      : undefined,
+    definition: provider.definition
+      ? (file, position) => provider.definition?.(file, position, control)
+      : undefined,
+    refactor: provider.refactor ? (request) => provider.refactor?.(request, control) : undefined,
+    rename: provider.rename
+      ? (file, position, newName) => provider.rename?.(file, position, newName, control)
+      : undefined,
+    codeActions: provider.codeActions
+      ? (file, position) => provider.codeActions?.(file, position, control)
+      : undefined,
+  } as T;
+}
+
+/** Bind one exact request-control value to every structural provider operation. */
+export function withStructuralRequestControl<T extends StructuralProvider>(
+  provider: T | null,
+  control: CodeRequestControl | undefined,
+): T | null {
+  if (!provider || !control) return provider;
+  return {
+    ...provider,
+    calleesAt: (file, line, character, depthOrOptions) => {
+      const depth = typeof depthOrOptions === "string" ? depthOrOptions : depthOrOptions?.depth;
+      return provider.calleesAt(file, line, character, { depth, control });
+    },
+    exports: (file) => provider.exports(file, control),
+    outline: (file) => provider.outline(file, control),
+    imports: (file) => provider.imports(file, control),
+    nodeAt: (file, line, character) => provider.nodeAt(file, line, character, control),
+    callSites: (file) => provider.callSites(file, control),
+  } as T;
+}
+
 /**
  * Create a single CodeProvider that delegates semantic methods to the
  * semantic (LSP) provider and structural methods to the structural
@@ -138,6 +187,15 @@ function createCompositeProvider(
         semantic?.definition?.(...args) ?? unavailableCodeQuery("Semantic definition unavailable")
       );
     },
+    async refactor(...args: Parameters<NonNullable<SemanticProvider["refactor"]>>) {
+      const result = await semantic?.refactor?.(...args);
+      return (
+        result ?? {
+          kind: "unavailable" as const,
+          reason: "Refactor not available",
+        }
+      );
+    },
     async codeActions(...args: Parameters<NonNullable<SemanticProvider["codeActions"]>>) {
       return semantic?.codeActions?.(...args) ?? [];
     },