@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/src/analysis/health/file-scope.ts

@@ -0,0 +1,184 @@
+// Single-file diagnostics collection for code_health.
+//
+// Owns the file-scope health request: the live pull, the tsconfig scope
+// decision for the requested file, and the evidence factories shared by the
+// file-scope outcomes. Kept separate from the workspace-tracked collection
+// (diagnostics.ts) so the scope-decision surface stays in one place.
+
+import { existsSync } from "node:fs";
+import {
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+} from "@mrclrchtr/supi-code-runtime/api";
+import {
+  type Diagnostic,
+  type DiagnosticEvidenceDocument,
+  type DiagnosticEvidenceSummary,
+  type FileScopeDecision,
+  getFileScopeDecision,
+  TENTATIVE_PUSH_UNAVAILABLE_REASON,
+  type WorkspaceLspRuntime,
+} from "@mrclrchtr/supi-lsp/api";
+import type {
+  HealthDiagnosticEntry,
+  HealthDiagnosticMessage,
+  HealthDiagnosticObservation,
+  HealthDiagnosticScope,
+} from "../../session/health-types.ts";
+
+/** Collect a live per-file diagnostic pull with its tsconfig scope decision. */
+export async function collectScopedFileDiagnostics(options: {
+  service: WorkspaceLspRuntime;
+  scope: Extract<HealthDiagnosticScope, { kind: "file" }>;
+  cwd: string;
+  detailed?: boolean;
+  requestControl?: CodeRequestControl;
+}): Promise<HealthDiagnosticObservation> {
+  const { service, scope, cwd, detailed, requestControl } = options;
+  try {
+    const result = await service.fileDiagnostics(scope.path, 4, requestControl);
+    if (result.kind === "unavailable") {
+      const evidence =
+        result.reason === TENTATIVE_PUSH_UNAVAILABLE_REASON
+          ? singleFileEvidence(scope.path, "unconfirmed")
+          : unavailableFileEvidence(scope.path);
+      return unavailableDiagnostics(
+        scope,
+        result.reason,
+        evidence,
+        fileScopeStatus(scope.path, cwd),
+      );
+    }
+
+    const entries = toFileDiagnosticEntries(scope.path, result.data, detailed);
+    const status = fileScopeStatus(scope.path, cwd);
+    return result.kind === "partial"
+      ? {
+          kind: "partial",
+          scope,
+          entries,
+          evidence: singleFileEvidence(scope.path, "unconfirmed"),
+          reason: result.reason,
+          ...(status ? { scopeStatus: status } : {}),
+        }
+      : {
+          kind: "completed",
+          scope,
+          entries,
+          evidence: singleFileEvidence(scope.path, "confirmed"),
+          ...(status ? { scopeStatus: status } : {}),
+        };
+  } catch (error) {
+    if (isCodeRequestInterruption(error, requestControl)) throw error;
+    return unavailableDiagnostics(
+      scope,
+      errorMessage(error, "File diagnostic request failed."),
+      unavailableFileEvidence(scope.path),
+      fileScopeStatus(scope.path, cwd),
+    );
+  }
+}
+
+/**
+ * Tsconfig scope decision for the requested file, when it can be computed.
+ *
+ * Uses the same decision model the diagnostic filter delegates to, so the
+ * rendered status line cannot drift from filter behavior. Telemetry-only:
+ * a failure to compute never fails the diagnostic request.
+ */
+export function fileScopeStatus(filePath: string, cwd: string): FileScopeDecision | null {
+  try {
+    return getFileScopeDecision(filePath, cwd);
+  } catch {
+    return null;
+  }
+}
+
+export function toFileDiagnosticEntries(
+  file: string,
+  diagnostics: ReadonlyArray<Pick<Diagnostic, "severity" | "message" | "source" | "range">>,
+  detailed?: boolean,
+): HealthDiagnosticEntry[] {
+  const errors = diagnostics.filter((diagnostic) => (diagnostic.severity ?? 1) === 1).length;
+  const warnings = diagnostics.filter((diagnostic) => (diagnostic.severity ?? 1) === 2).length;
+  if (!hasIssueCounts(errors, warnings)) return [];
+  const entry: HealthDiagnosticEntry = { file, errors, warnings };
+  if (detailed) {
+    return [{ ...entry, messages: extractMessages(diagnostics) }];
+  }
+  return [entry];
+}
+
+// ── Message extraction ────────────────────────────────────────────────
+
+const MAX_MESSAGES_PER_FILE = 3;
+
+function extractMessages(
+  diagnostics: ReadonlyArray<Pick<Diagnostic, "severity" | "message" | "source" | "range">>,
+): HealthDiagnosticMessage[] {
+  const errorsAndWarnings = diagnostics
+    .filter((d) => (d.severity ?? 1) <= 2)
+    .sort(
+      (a, b) => (a.severity ?? 1) - (b.severity ?? 1) || a.range.start.line - b.range.start.line,
+    );
+
+  return errorsAndWarnings.slice(0, MAX_MESSAGES_PER_FILE).map((d) => ({
+    line: d.range.start.line + 1,
+    severity: (d.severity ?? 1) === 1 ? ("error" as const) : ("warning" as const),
+    message: typeof d.message === "string" ? d.message : d.message.value,
+    ...(d.source ? { source: d.source } : {}),
+  }));
+}
+
+export function unavailableDiagnostics(
+  scope: HealthDiagnosticScope,
+  reason: string,
+  evidence: DiagnosticEvidenceSummary = emptyEvidence(),
+  scopeStatus?: FileScopeDecision | null,
+): HealthDiagnosticObservation {
+  return {
+    kind: "unavailable",
+    scope,
+    entries: [],
+    evidence,
+    reason,
+    ...(scopeStatus ? { scopeStatus } : {}),
+  };
+}
+
+export function unavailableFileEvidence(file: string): DiagnosticEvidenceSummary {
+  return singleFileEvidence(file, existsSync(file) ? "failed" : "removed");
+}
+
+export 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 emptyEvidence(): DiagnosticEvidenceSummary {
+  return {
+    requested: 0,
+    confirmed: 0,
+    unconfirmed: 0,
+    failed: 0,
+    removed: 0,
+    documents: [],
+  };
+}
+
+function hasIssueCounts(errors: number, warnings: number): boolean {
+  return errors > 0 || warnings > 0;
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message ? error.message : fallback;
+}

package/src/analysis/health/recovery.ts

@@ -1,14 +1,21 @@
 // Recovery and state description helpers for code_health.
 // Extracted from orchestrate.ts.
 
-import type { CapabilityState } from "@mrclrchtr/supi-code-runtime/api";
-import type { RecoverDiagnosticsResult, WorkspaceLspRuntime } from "@mrclrchtr/supi-lsp/api";
+import type { CapabilityState, CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
+import type {
+  DiagnosticEvidenceSummary,
+  RecoverDiagnosticsResult,
+  WorkspaceLspRuntime,
+} from "@mrclrchtr/supi-lsp/api";
 
 // ── Recovery ──────────────────────────────────────────────────────────
 
 interface RecoverOptions {
   service: WorkspaceLspRuntime;
   progress?: () => void;
+  control?: CodeRequestControl;
+  /** Evidence from the maintenance refresh, so the recovery pass skips its own refresh. */
+  initialEvidence?: DiagnosticEvidenceSummary;
 }
 
 /** Run the runtime's best-effort recovery and preserve its established outcome. */
@@ -16,7 +23,11 @@ export async function recoverDiagnosticRuntime(
   opts: RecoverOptions,
 ): Promise<RecoverDiagnosticsResult> {
   opts.progress?.();
-  return opts.service.recoverDiagnostics({ restartIfStillStale: true });
+  return opts.service.recoverDiagnostics({
+    restartIfStillStale: true,
+    ...(opts.initialEvidence !== undefined ? { initialEvidence: opts.initialEvidence } : {}),
+    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) ?? [];
     },

package/src/analysis/readiness.ts

@@ -1,4 +1,8 @@
-import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import {
+  type CodeRequestControl,
+  getDefaultWorkspaceRuntime,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
 import {
   getWorkspaceLspRuntime,
   type SemanticReadinessResult,
@@ -8,13 +12,20 @@ import {
 
 export const DEFAULT_SEMANTIC_STARTUP_TIMEOUT_MS = 15_000;
 
+/** Neutral reason for a typed semantic readiness timeout. */
+export const SEMANTIC_READINESS_TIMEOUT_REASON =
+  "Semantic provider did not become ready within the wait window; retry shortly.";
+
 export type SemanticStartupScope = { kind: "workspace" } | { kind: "file"; file: string };
 
 export async function ensureSemanticReadiness(
   cwd: string,
   scope: SemanticStartupScope,
   timeoutMs: number = DEFAULT_SEMANTIC_STARTUP_TIMEOUT_MS,
+  control?: CodeRequestControl,
 ): Promise<SemanticReadinessResult> {
+  // A cancelled caller stops before any readiness work starts.
+  throwIfCodeRequestInterrupted(control);
   const workspace = getDefaultWorkspaceRuntime().getWorkspace(cwd);
   if (workspace.semantic.provider === null) {
     return {
@@ -24,7 +35,7 @@ export async function ensureSemanticReadiness(
   }
 
   if (workspace.semantic.state.kind === "ready") {
-    return resolveReadySemanticState(cwd, scope, timeoutMs);
+    return resolveReadySemanticState(cwd, scope, timeoutMs, control);
   }
 
   if (workspace.semantic.state.kind !== "pending") {
@@ -34,13 +45,15 @@ export async function ensureSemanticReadiness(
     };
   }
 
-  const deadline = Date.now() + timeoutMs;
+  // The request deadline bounds the internal readiness budget when it is
+  // earlier than the relative startup timeout.
+  const deadline = Math.min(Date.now() + timeoutMs, control?.deadline ?? Infinity);
 
   const remainingAfterService = deadline - Date.now();
   if (remainingAfterService <= 0) {
     return { kind: "timeout" };
   }
-  const lspState = await resolveSemanticServiceState(cwd, remainingAfterService);
+  const lspState = await resolveSemanticServiceState(cwd, remainingAfterService, control);
   if (lspState.kind === "pending") {
     return { kind: "timeout" };
   }
@@ -58,8 +71,13 @@ export async function ensureSemanticReadiness(
   if (remainingAfterLsp <= 0) {
     return { kind: "timeout" };
   }
-  return scope.kind === "workspace"
-    ? lspState.runtime.waitUntilReadyForWorkspace({ timeoutMs: remainingAfterLsp })
+  if (scope.kind === "workspace") {
+    return control
+      ? lspState.runtime.waitUntilReadyForWorkspace({ timeoutMs: remainingAfterLsp }, control)
+      : lspState.runtime.waitUntilReadyForWorkspace({ timeoutMs: remainingAfterLsp });
+  }
+  return control
+    ? lspState.runtime.waitUntilReadyForFile(scope.file, { timeoutMs: remainingAfterLsp }, control)
     : lspState.runtime.waitUntilReadyForFile(scope.file, { timeoutMs: remainingAfterLsp });
 }
 
@@ -67,11 +85,17 @@ function resolveReadySemanticState(
   cwd: string,
   scope: SemanticStartupScope,
   timeoutMs: number,
+  control?: CodeRequestControl,
 ): Promise<SemanticReadinessResult> | SemanticReadinessResult {
   const lspState = getWorkspaceLspRuntime(cwd);
   if (lspState.kind === "ready") {
-    return scope.kind === "workspace"
-      ? lspState.runtime.waitUntilReadyForWorkspace({ timeoutMs })
+    if (scope.kind === "workspace") {
+      return control
+        ? lspState.runtime.waitUntilReadyForWorkspace({ timeoutMs }, control)
+        : lspState.runtime.waitUntilReadyForWorkspace({ timeoutMs });
+    }
+    return control
+      ? lspState.runtime.waitUntilReadyForFile(scope.file, { timeoutMs }, control)
       : lspState.runtime.waitUntilReadyForFile(scope.file, { timeoutMs });
   }
   return {
@@ -86,8 +110,9 @@ function resolveReadySemanticState(
 async function resolveSemanticServiceState(
   cwd: string,
   timeoutMs: number,
+  control?: CodeRequestControl,
 ): Promise<WorkspaceLspRuntimeState> {
   const initialState = getWorkspaceLspRuntime(cwd);
   if (initialState.kind !== "pending") return initialState;
-  return waitForWorkspaceLspRuntime(cwd, timeoutMs);
+  return waitForWorkspaceLspRuntime(cwd, timeoutMs, control);
 }

package/src/analysis/refactor/apply.ts

@@ -16,6 +16,7 @@ import { readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:
 import { basename, dirname, join } from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import type { FileEdit, WorkspaceEdit } from "@mrclrchtr/supi-code-runtime/api";
+import { revalidateMutationAuthority } from "./mutation-authority.ts";
 import { compareCodePositions, createLogicalLineIndex } from "./position.ts";
 import { validateEditAgainstFiles } from "./safety.ts";
 
@@ -24,8 +25,12 @@ export type ApplyResult =
   | { kind: "error"; reason: string };
 
 export interface ApplyOptions {
+  /** Canonical roots authorized by the semantic provider that made the plan. */
+  authorizedMutationRoots: readonly string[];
   /** Expected SHA-256 fingerprints per file, validated after queue acquisition. */
   expectedFingerprints?: ReadonlyMap<string, string>;
+  /** Current LSP document version, or null when the document is not open. */
+  getOpenDocumentVersion?: (file: string) => number | null;
 }
 
 /**
@@ -49,16 +54,24 @@ export interface ApplyOptions {
  */
 export async function applyWorkspaceEdit(
   edit: WorkspaceEdit,
-  options: ApplyOptions = {},
+  options: ApplyOptions,
 ): Promise<ApplyResult> {
   const grouped = groupEditsByFile(edit.edits);
   const files = [...grouped.keys()].sort();
   return withAllMutationQueues(files, async () => {
+    const authority = revalidateMutationAuthority(files, options.authorizedMutationRoots);
+    if (authority.kind === "unavailable") {
+      return { kind: "error", reason: authority.reason };
+    }
+
     if (options.expectedFingerprints) {
       const freshness = validateFingerprints(files, options.expectedFingerprints);
       if (!freshness.ok) return { kind: "error", reason: freshness.reason };
     }
 
+    const documentState = validateDocumentPreconditions(edit, options.getOpenDocumentVersion);
+    if (!documentState.ok) return { kind: "error", reason: documentState.reason };
+
     const validation = validateEditAgainstFiles(edit);
     if (!validation.safe) {
       return { kind: "error", reason: validation.reason };
@@ -76,6 +89,37 @@ export async function applyWorkspaceEdit(
   });
 }
 
+function validateDocumentPreconditions(
+  edit: WorkspaceEdit,
+  getOpenDocumentVersion: ApplyOptions["getOpenDocumentVersion"],
+): { ok: true } | { ok: false; reason: string } {
+  const preconditions = edit.documentPreconditions ?? [];
+  if (preconditions.length === 0) return { ok: true };
+  if (!getOpenDocumentVersion) {
+    return {
+      ok: false,
+      reason: "Stored document preconditions cannot be revalidated.",
+    };
+  }
+
+  for (const precondition of preconditions) {
+    const currentVersion = getOpenDocumentVersion(precondition.file);
+    if (precondition.kind === "open-document-version" && currentVersion !== precondition.version) {
+      return {
+        ok: false,
+        reason: `File ${precondition.file} open document version has changed since the plan was generated.`,
+      };
+    }
+    if (precondition.kind === "disk-content" && currentVersion !== null) {
+      return {
+        ok: false,
+        reason: `File ${precondition.file} is now open and no longer uses disk content as its master.`,
+      };
+    }
+  }
+  return { ok: true };
+}
+
 function validateFingerprints(
   files: string[],
   expected: ReadonlyMap<string, string>,

package/src/analysis/refactor/mutation-authority.ts

@@ -0,0 +1,143 @@
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import * as path from "node:path";
+
+export type MutationAuthorityResult =
+  | { kind: "authorized"; canonicalRoots: string[] }
+  | { kind: "unavailable"; reason: string };
+
+/**
+ * Establish canonical provider roots and verify that all mutation files are
+ * regular files inside at least one root.
+ */
+export function establishMutationAuthority(
+  files: readonly string[],
+  providerRoots: readonly string[],
+): MutationAuthorityResult {
+  const roots = canonicalizeProviderRoots(providerRoots);
+  if (roots.kind === "unavailable") return roots;
+
+  const fileValidation = validateFiles(files, roots.canonicalRoots);
+  return fileValidation.kind === "unavailable" ? fileValidation : roots;
+}
+
+/** Revalidate stored canonical roots and mutation files immediately before mutation. */
+export function revalidateMutationAuthority(
+  files: readonly string[],
+  canonicalRoots: readonly string[],
+): MutationAuthorityResult {
+  if (canonicalRoots.length === 0) {
+    return { kind: "unavailable", reason: "Mutation plan has no authorized provider root." };
+  }
+
+  for (const root of canonicalRoots) {
+    if (!path.isAbsolute(root) || path.normalize(root) !== root) {
+      return { kind: "unavailable", reason: `Stored mutation root "${root}" is not canonical.` };
+    }
+    try {
+      if (!lstatSync(root).isDirectory() || realpathSync(root) !== root) {
+        return { kind: "unavailable", reason: `Stored mutation root "${root}" has changed.` };
+      }
+    } catch {
+      return { kind: "unavailable", reason: `Stored mutation root "${root}" is unavailable.` };
+    }
+  }
+
+  return validateFiles(files, canonicalRoots);
+}
+
+function canonicalizeProviderRoots(providerRoots: readonly string[]): MutationAuthorityResult {
+  if (providerRoots.length === 0) {
+    return { kind: "unavailable", reason: "Semantic route did not authorize a mutation root." };
+  }
+
+  const canonicalRoots = new Set<string>();
+  for (const root of providerRoots) {
+    if (!path.isAbsolute(root)) {
+      return { kind: "unavailable", reason: `Mutation root "${root}" is not absolute.` };
+    }
+    try {
+      const canonicalRoot = realpathSync(root);
+      if (!statSync(canonicalRoot).isDirectory()) {
+        return {
+          kind: "unavailable",
+          reason: `Mutation root "${root}" is not a directory.`,
+        };
+      }
+      canonicalRoots.add(canonicalRoot);
+    } catch {
+      return {
+        kind: "unavailable",
+        reason: `Mutation root "${root}" cannot be resolved to a canonical directory.`,
+      };
+    }
+  }
+
+  return { kind: "authorized", canonicalRoots: [...canonicalRoots].sort() };
+}
+
+function validateFiles(
+  files: readonly string[],
+  canonicalRoots: readonly string[],
+): MutationAuthorityResult {
+  for (const file of new Set(files)) {
+    const validation = validateFile(file, canonicalRoots);
+    if (validation) return { kind: "unavailable", reason: validation };
+  }
+  return { kind: "authorized", canonicalRoots: [...canonicalRoots] };
+}
+
+function validateFile(file: string, canonicalRoots: readonly string[]): string | null {
+  if (!path.isAbsolute(file) || path.normalize(file) !== file) {
+    return `Mutation file "${file}" is not a normalized absolute path.`;
+  }
+
+  let canonicalParent: string;
+  try {
+    canonicalParent = realpathSync(path.dirname(file));
+  } catch {
+    return `Mutation file "${file}" does not have a resolvable canonical parent.`;
+  }
+
+  try {
+    if (!lstatSync(file).isFile()) {
+      return `Mutation file "${file}" is not a regular file.`;
+    }
+  } catch {
+    return `Mutation file "${file}" is not a readable regular file.`;
+  }
+
+  let canonicalFile: string;
+  try {
+    canonicalFile = realpathSync(file);
+  } catch {
+    return `Mutation file "${file}" cannot be resolved to a canonical file.`;
+  }
+
+  const expectedCanonicalFile = path.join(canonicalParent, path.basename(file));
+  if (path.resolve(canonicalFile) !== path.resolve(expectedCanonicalFile)) {
+    return `Mutation file "${file}" resolves through an unsupported file link.`;
+  }
+  if (!canonicalRoots.some((root) => isWithinOrEqual(root, canonicalFile))) {
+    return `Mutation file "${file}" is outside the authorized provider roots.`;
+  }
+  return null;
+}
+
+function isWithinOrEqual(root: string, candidate: string): boolean {
+  return isMutationPathWithinRoot(root, candidate, path);
+}
+
+/** Check canonical path containment with the selected platform path rules. */
+export function isMutationPathWithinRoot(
+  root: string,
+  candidate: string,
+  pathApi: Pick<typeof path, "isAbsolute" | "relative" | "sep">,
+): boolean {
+  const difference = pathApi.relative(root, candidate);
+  return (
+    difference === "" ||
+    (difference !== ".." &&
+      !difference.startsWith(`..${pathApi.sep}`) &&
+      !pathApi.isAbsolute(difference))
+  );
+}

package/src/analysis/relations/callees.ts

@@ -2,6 +2,7 @@
  * Structural callee lookup — finds direct calls in the enclosing scope at a target position.
  */
 
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import type { CalleeEntry, CalleeScope, RelationsServiceDeps } from "./types.ts";
 
 export interface CalleesResult {
@@ -26,12 +27,19 @@ export async function collectCallees(
   deps: RelationsServiceDeps,
   maxResults?: number,
   depth: "direct" | "deep" = "direct",
+  control?: CodeRequestControl,
 ): Promise<CalleesResult> {
   if (!deps.provider?.calleesAt) {
     return unavailableCallees(targetName);
   }
 
-  const result = await deps.provider.calleesAt(targetFile, targetLine, targetCharacter, depth);
+  const depthOrOptions = control ? { depth, control } : depth;
+  const result = await deps.provider.calleesAt(
+    targetFile,
+    targetLine,
+    targetCharacter,
+    depthOrOptions,
+  );
   if (result.kind !== "success" || !result.data) {
     return unavailableCallees(targetName);
   }

package/src/analysis/relations/types.ts

@@ -1,4 +1,4 @@
-import type { SemanticProvider } from "@mrclrchtr/supi-code-runtime/api";
+import type { CodeRequestControl, SemanticProvider } from "@mrclrchtr/supi-code-runtime/api";
 
 /**
  * Shared types for the relations analysis modules.
@@ -58,7 +58,10 @@ export interface RelationsServiceDeps {
       file: string,
       line: number,
       character: number,
-      depth?: "direct" | "deep",
+      depthOrOptions?:
+        | "direct"
+        | "deep"
+        | { depth?: "direct" | "deep"; control?: CodeRequestControl },
     ) => Promise<{
       kind: string;
       data?: {