@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/src/analysis/search/ast-scan-timing.ts

@@ -1,4 +1,6 @@
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
+import { truncateIdentity } from "@mrclrchtr/supi-lsp/debug-telemetry";
 import type { StructuralSearchOperation } from "@mrclrchtr/supi-tree-sitter/api";
 import type { StructuredFileAnalysis, StructuredPatternParams } from "./pattern-analysis.ts";
 
@@ -25,8 +27,11 @@ export interface AstScanTimer {
   record(input: AstScanTimingInput): void;
 }
 
-/** Start one AST scan timer without adding paths to debug-event data. */
-export function startAstScanTimer(): AstScanTimer {
+/** Start one AST scan timer, recording the workspace root as event-level cwd. */
+export function startAstScanTimer(
+  control: CodeRequestControl | undefined,
+  cwd: string,
+): AstScanTimer {
   const timer = startDebugTimer();
   return {
     enumerationCompleted() {
@@ -35,10 +40,12 @@ export function startAstScanTimer(): AstScanTimer {
     record(input) {
       timer.finish(
         () => ({
+          operationId: control?.operationId,
           source: "code-intelligence",
           level: "debug",
           category: "ast-scan.timing",
           message: `AST ${input.context.params.kind} scan analyzed ${input.analysis.analyzedFileCount} files`,
+          cwd: truncateIdentity(cwd),
           data: {
             kind: input.context.params.kind,
             operation: input.operation,

package/src/analysis/search/ast-scan.ts

@@ -5,7 +5,7 @@ import {
   getSupportedExtensions,
   type StructuralSearchOperation,
 } from "@mrclrchtr/supi-tree-sitter/api";
-import { type DeadlineOutcome, settleByDeadline } from "./deadline.ts";
+import { type DeadlineOutcome, type ScheduleDeadline, settleByDeadline } from "./deadline.ts";
 import { relativeDisplayPath } from "./paths.ts";
 
 /** Directory names excluded below an AST Scan root. */
@@ -83,6 +83,8 @@ export interface EnumerateAstFilesOptions {
   readonly timeoutMs?: number;
   readonly signal?: AbortSignal;
   readonly now?: () => number;
+  /** Timer seam for deterministic deadline tests; defaults to wall-clock timers. */
+  readonly schedule?: ScheduleDeadline;
   readonly operations?: AstScanOperations;
 }
 
@@ -292,7 +294,7 @@ class AstFileEnumerator {
   #checkControl(): boolean {
     this.options.signal?.throwIfAborted();
     if (this.#safetyLimited) return false;
-    if (this.#now() <= this.options.deadline) return true;
+    if (this.#now() < this.options.deadline) return true;
     this.#markTimeout();
     return false;
   }
@@ -302,6 +304,7 @@ class AstFileEnumerator {
       deadline: this.options.deadline,
       now: this.#now,
       signal: this.options.signal,
+      schedule: this.options.schedule,
     });
     if (outcome.kind === "timeout") this.#markTimeout();
     return outcome;

package/src/analysis/search/deadline.ts

@@ -24,7 +24,7 @@ export async function settleByDeadline<T>(
 ): Promise<DeadlineOutcome<T>> {
   control.signal?.throwIfAborted();
   const remainingMs = control.deadline - control.now();
-  if (remainingMs < 0) return { kind: "timeout" };
+  if (remainingMs <= 0) return { kind: "timeout" };
 
   return new Promise<DeadlineOutcome<T>>((resolve, reject) => {
     let settled = false;
@@ -70,7 +70,7 @@ export async function settleByDeadline<T>(
       .then(
         (value) => {
           complete(
-            control.now() > control.deadline ? { kind: "timeout" } : { kind: "completed", value },
+            control.now() >= control.deadline ? { kind: "timeout" } : { kind: "completed", value },
           );
         },
         (error: unknown) => fail(error),

package/src/analysis/search/pattern-analysis.ts

@@ -1,12 +1,15 @@
-import type {
-  CodeResult,
-  OutlineData,
-  StructuralProvider as StructuralSubstrate,
+import {
+  type CodeRequestControl,
+  type CodeResult,
+  isCodeRequestDeadlineError,
+  isCodeRequestInterruption,
+  type OutlineData,
+  type StructuralProvider as StructuralSubstrate,
 } from "@mrclrchtr/supi-code-runtime/api";
-import type { CodeFindAstKind } from "../../tool/find/ast-kinds.ts";
+import type { CodeFindAstKind } from "../../tool/code_find/ast-kinds.ts";
 import type { AstScanLimitation } from "./ast-scan.ts";
 import { callableExpressionForMatching } from "./call-name.ts";
-import { settleByDeadline } from "./deadline.ts";
+import { type DeadlineOutcome, type ScheduleDeadline, settleByDeadline } from "./deadline.ts";
 import { relativeDisplayPath } from "./paths.ts";
 
 export interface StructuredPatternParams {
@@ -52,6 +55,9 @@ interface AnalyzeStructuredFilesOptions {
   readonly deadline: number;
   readonly now: () => number;
   readonly signal?: AbortSignal;
+  /** Timer seam for deterministic deadline tests; defaults to wall-clock timers. */
+  readonly schedule?: ScheduleDeadline;
+  readonly requestControl: CodeRequestControl;
   readonly initialLimitations: readonly AstScanLimitation[];
 }
 
@@ -67,34 +73,48 @@ export async function analyzeStructuredFiles(
 
   for (const [index, absoluteFile] of options.files.entries()) {
     options.signal?.throwIfAborted();
-    if (options.now() > options.deadline) {
+    if (options.now() >= options.deadline) {
       addAnalysisTimeout(limitations, options.files.slice(index), options.displayBase);
       break;
     }
     const relativeFile = relativeDisplayPath(options.displayBase, absoluteFile);
     const fileMatches: StructuredMatch[] = [];
     const fileFailures: StructuredFailure[] = [];
-    const outcome = await settleByDeadline(
-      async () => {
-        try {
-          await collectMatchesForFile(
-            fileMatches,
-            fileFailures,
-            options.structural,
-            relativeFile,
-            options.params.kind,
-            matcher,
-          );
-        } catch (error) {
-          fileFailures.push({
-            file: relativeFile,
-            kind: "runtime-error",
-            reason: errorMessage(error),
-          });
-        }
-      },
-      { deadline: options.deadline, now: options.now, signal: options.signal },
-    );
+    let outcome: DeadlineOutcome<void>;
+    try {
+      outcome = await settleByDeadline(
+        async () => {
+          try {
+            await collectMatchesForFile(
+              fileMatches,
+              fileFailures,
+              options.structural,
+              relativeFile,
+              options.params.kind,
+              matcher,
+              options.requestControl,
+            );
+          } catch (error) {
+            if (isCodeRequestInterruption(error, options.requestControl)) throw error;
+            fileFailures.push({
+              file: relativeFile,
+              kind: "runtime-error",
+              reason: errorMessage(error),
+            });
+          }
+        },
+        {
+          deadline: options.deadline,
+          now: options.now,
+          signal: options.signal,
+          schedule: options.schedule,
+        },
+      );
+    } catch (error) {
+      if (!isCodeRequestDeadlineError(error)) throw error;
+      addAnalysisTimeout(limitations, options.files.slice(index), options.displayBase);
+      break;
+    }
     if (outcome.kind === "timeout") {
       addAnalysisTimeout(limitations, options.files.slice(index), options.displayBase);
       break;
@@ -137,13 +157,14 @@ async function collectMatchesForFile(
   relFile: string,
   kind: CodeFindAstKind,
   matcher: (value: string) => boolean,
+  requestControl: CodeRequestControl,
 ): Promise<void> {
   const recordFailure = (kind: StructuredFailureKind, reason: string) => {
     failures.push({ file: relFile, kind, reason });
   };
 
   if (kind === "definition") {
-    const outline = await structural.outline(relFile);
+    const outline = await structural.outline(relFile, requestControl);
     if (!handleStructuralResult(outline, recordFailure)) return;
     for (const item of flattenOutlineItems(outline.data)) {
       if (!matcher(item.name)) continue;
@@ -153,7 +174,7 @@ async function collectMatchesForFile(
   }
 
   if (kind === "export") {
-    const exportsResult = await structural.exports(relFile);
+    const exportsResult = await structural.exports(relFile, requestControl);
     if (!handleStructuralResult(exportsResult, recordFailure)) return;
     for (const item of exportsResult.data) {
       if (!matcher(item.name)) continue;
@@ -163,7 +184,7 @@ async function collectMatchesForFile(
   }
 
   if (kind === "import") {
-    const importsResult = await structural.imports(relFile);
+    const importsResult = await structural.imports(relFile, requestControl);
     if (!handleStructuralResult(importsResult, recordFailure)) return;
     for (const item of importsResult.data) {
       if (!matcher(item.moduleSpecifier)) continue;
@@ -178,7 +199,7 @@ async function collectMatchesForFile(
   }
 
   if (kind === "call") {
-    const callResult = await structural.callSites(relFile);
+    const callResult = await structural.callSites(relFile, requestControl);
     if (!handleStructuralResult(callResult, recordFailure)) return;
     for (const call of callResult.data) {
       if (!matcher(callableExpressionForMatching(call.name))) continue;
@@ -187,7 +208,7 @@ async function collectMatchesForFile(
     return;
   }
 
-  const outline = await structural.outline(relFile);
+  const outline = await structural.outline(relFile, requestControl);
   if (!handleStructuralResult(outline, recordFailure)) return;
   for (const item of flattenOutlineItems(outline.data)) {
     if (kind === "type" && !TYPE_KIND.test(item.kind.toLowerCase())) continue;

package/src/analysis/search/pattern.ts

@@ -1,6 +1,6 @@
 import type { StructuralProvider as StructuralSubstrate } from "@mrclrchtr/supi-code-runtime/api";
 import type { StructuralSearchOperation } from "@mrclrchtr/supi-tree-sitter/api";
-import type { CodeFindAstKind } from "../../tool/find/ast-kinds.ts";
+import type { CodeFindAstKind } from "../../tool/code_find/ast-kinds.ts";
 import type { EvidencePartialReason } from "../evidence.ts";
 import {
   type AstScanExclusion,
@@ -11,6 +11,7 @@ import {
   enumerateAstFiles,
 } from "./ast-scan.ts";
 import { startAstScanTimer } from "./ast-scan-timing.ts";
+import type { ScheduleDeadline } from "./deadline.ts";
 import { relativeDisplayPath } from "./paths.ts";
 import {
   analyzeStructuredFiles,
@@ -56,11 +57,16 @@ export type StructuredPatternOutcome =
 
 /** Internal controls for deterministic deadline, filesystem, and cancellation tests. */
 export interface StructuredPatternControl {
+  readonly operationId?: string;
   readonly signal?: AbortSignal;
   readonly now?: () => number;
   readonly operations?: AstScanOperations;
   readonly maxFiles?: number;
   readonly timeoutMs?: number;
+  /** Optional caller deadline; the earlier caller/policy deadline wins. */
+  readonly deadline?: number;
+  /** Timer seam for deterministic deadline tests; defaults to wall-clock timers. */
+  readonly schedule?: ScheduleDeadline;
 }
 
 export interface StructuredPatternSearchOptions {
@@ -80,11 +86,12 @@ export interface StructuredPatternSearchOptions {
 export async function getStructuredPatternMatches(
   options: StructuredPatternSearchOptions,
 ): Promise<StructuredPatternOutcome> {
-  const scanTimer = startAstScanTimer();
+  const scanTimer = startAstScanTimer(options.control, options.cwd);
   const now = options.control?.now ?? Date.now;
   const maxFiles = options.control?.maxFiles ?? DEFAULT_AST_SCAN_MAX_FILES;
   const timeoutMs = options.control?.timeoutMs ?? DEFAULT_AST_SCAN_TIMEOUT_MS;
-  const deadline = now() + timeoutMs;
+  const policyDeadline = now() + timeoutMs;
+  const deadline = Math.min(options.control?.deadline ?? Number.POSITIVE_INFINITY, policyDeadline);
   const roots = Array.isArray(options.roots) ? [...options.roots] : [options.roots];
   const operation = structuralOperationForKind(options.params.kind);
   options.control?.signal?.throwIfAborted();
@@ -98,6 +105,7 @@ export async function getStructuredPatternMatches(
     timeoutMs,
     signal: options.control?.signal,
     now,
+    schedule: options.control?.schedule,
     operations: options.control?.operations,
   });
   if (enumeration.kind === "invalid-root") {
@@ -127,6 +135,11 @@ export async function getStructuredPatternMatches(
   }
 
   scanTimer.enumerationCompleted();
+  const requestControl = {
+    operationId: options.control?.operationId,
+    signal: options.control?.signal,
+    deadline,
+  };
   const analysis = await analyzeStructuredFiles({
     files: enumeration.files,
     displayBase: enumeration.displayBase,
@@ -135,6 +148,8 @@ export async function getStructuredPatternMatches(
     deadline,
     now,
     signal: options.control?.signal,
+    schedule: options.control?.schedule,
+    requestControl,
     initialLimitations: enumeration.limitations,
   });
   const capabilityMismatches = analysis.failures.filter(

package/src/analysis/target/anchored.ts

@@ -9,12 +9,14 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type {
-  CodeResult,
-  CodeSymbol,
-  NodeAtData,
-  SemanticProvider,
-  StructuralProvider,
+import {
+  type CodeRequestControl,
+  type CodeResult,
+  type CodeSymbol,
+  isCodeRequestInterruption,
+  type NodeAtData,
+  type SemanticProvider,
+  type StructuralProvider,
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { AnchorKind } from "../../session/target-store.ts";
 import type { AnchoredResolutionMetadata, AnchoredResolutionSource } from "../../types/index.ts";
@@ -217,17 +219,20 @@ async function candidatesFromSymbols(
 }
 
 /** Layer 1: match the coordinate against LSP document symbols. Returns null to fall through. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: layered anchored resolution keeps layer-1 symbol matching and identity resolution together.
 async function resolveFromSemantic(
   file: string,
   requested: Anchor,
   provider: AnchoredResolverProvider,
+  control?: CodeRequestControl,
 ): Promise<TargetOutcome | null> {
   if (!provider.documentSymbols) return null;
   let symbols: CodeSymbol[] = [];
   try {
     const result = await provider.documentSymbols(file);
     if (result.kind !== "unavailable") symbols = result.data;
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     symbols = [];
   }
   if (symbols.length === 0) return null;
@@ -241,7 +246,7 @@ async function resolveFromSemantic(
   }
 
   const structural = provider.nodeAt ? { nodeAt: provider.nodeAt } : undefined;
-  const resolveIdentity = createCodeSymbolIdentityResolver(file, symbols, structural);
+  const resolveIdentity = createCodeSymbolIdentityResolver(file, symbols, structural, control);
   if (exact.length === 1) {
     return resolvedFromSymbol(file, exact[0], {
       snapped: false,
@@ -268,12 +273,14 @@ async function resolveFromStructural(
   file: string,
   requested: Anchor,
   provider: AnchoredResolverProvider,
+  control?: CodeRequestControl,
 ): Promise<TargetOutcome | null> {
   if (!provider.nodeAt) return null;
   let nodeResult: CodeResult<NodeAtData> | null = null;
   try {
     nodeResult = await provider.nodeAt(file, requested.line, requested.character);
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     nodeResult = null;
   }
   if (nodeResult?.kind !== "success") return null;
@@ -351,11 +358,13 @@ async function resolveFromStructural(
  * This does not perform heuristic global text search and does not silently
  * treat declaration anchors as name anchors (ADR 0003).
  */
+// biome-ignore lint/complexity/useMaxParams: anchored resolution is a stable public resolver boundary with fixed positional fields.
 export async function resolveAnchoredSymbolTarget(
   file: string,
   line: number,
   character: number,
   provider: AnchoredResolverProvider | null,
+  control?: CodeRequestControl,
 ): Promise<TargetOutcome> {
   if (!fs.existsSync(file)) {
     return { kind: "error", message: `File not found: \`${file}\`` };
@@ -369,9 +378,9 @@ export async function resolveAnchoredSymbolTarget(
 
   const requested: Anchor = { line, character };
   if (provider) {
-    const semantic = await resolveFromSemantic(file, requested, provider);
+    const semantic = await resolveFromSemantic(file, requested, provider, control);
     if (semantic) return semantic;
-    const structural = await resolveFromStructural(file, requested, provider);
+    const structural = await resolveFromStructural(file, requested, provider, control);
     if (structural) return structural;
   }
 

package/src/analysis/target/file.ts

@@ -9,12 +9,14 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type {
-  DeclarationNesting,
-  DocumentCodeSymbol,
-  OutlineData,
-  SemanticProvider as SemanticSubstrate,
-  StructuralProvider as StructuralSubstrate,
+import {
+  type CodeRequestControl,
+  type DeclarationNesting,
+  type DocumentCodeSymbol,
+  isCodeRequestInterruption,
+  type OutlineData,
+  type SemanticProvider as SemanticSubstrate,
+  type StructuralProvider as StructuralSubstrate,
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { AnchorKind } from "../../session/target-store.ts";
 import { normalizePath } from "../search/paths.ts";
@@ -80,6 +82,7 @@ export async function resolveFileTargetGroup(
     semantic?: SemanticSubstrate;
     structural?: StructuralSubstrate;
   } = {},
+  control?: CodeRequestControl,
 ): Promise<
   | { kind: "resolved"; group: ResolvedTargetGroupData }
   | { kind: "invalid-input"; message: string }
@@ -90,8 +93,8 @@ export async function resolveFileTargetGroup(
   const resolvedFile = validation.file;
 
   const [semantic, structural] = await Promise.all([
-    discoverSemantic(resolvedFile, deps.semantic, deps.structural),
-    discoverStructural(resolvedFile, deps.structural),
+    discoverSemantic(resolvedFile, deps.semantic, deps.structural, control),
+    discoverStructural(resolvedFile, deps.structural, control),
   ]);
   if (!semantic.available && !structural.available) {
     const displayFile = path.relative(cwd, resolvedFile) || file;
@@ -148,6 +151,7 @@ async function discoverSemantic(
   file: string,
   semantic: SemanticSubstrate | undefined,
   structural: StructuralSubstrate | undefined,
+  control?: CodeRequestControl,
 ): Promise<DiscoveryResult> {
   if (!semantic) return { available: false, targets: [] };
   try {
@@ -158,12 +162,13 @@ async function discoverSemantic(
       targets: await Promise.all(
         result.data.map(async (symbol) => {
           const target = targetFromSymbol(file, symbol);
-          const refined = await refineTypeAliasIdentity(target, structural);
+          const refined = await refineTypeAliasIdentity(target, structural, control);
           return { ...refined, nesting: target.nesting };
         }),
       ),
     };
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     return { available: false, targets: [] };
   }
 }
@@ -196,13 +201,15 @@ function normalizeNesting(value: unknown): DeclarationNesting {
 async function discoverStructural(
   file: string,
   structural: StructuralSubstrate | undefined,
+  control?: CodeRequestControl,
 ): Promise<DiscoveryResult> {
   if (!structural) return { available: false, targets: [] };
   try {
     const result = await structural.outline(file);
     if (result.kind !== "success") return { available: false, targets: [] };
     return { available: true, targets: flattenOutline(file, result.data) };
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     return { available: false, targets: [] };
   }
 }

package/src/analysis/target/identity.ts

@@ -1,5 +1,10 @@
 import { resolve } from "node:path";
-import type { CodeSymbol, StructuralProvider } from "@mrclrchtr/supi-code-runtime/api";
+import {
+  type CodeRequestControl,
+  type CodeSymbol,
+  isCodeRequestInterruption,
+  type StructuralProvider,
+} from "@mrclrchtr/supi-code-runtime/api";
 import type { ResolvedTargetData, TargetOutcome } from "./types.ts";
 
 /**
@@ -45,6 +50,7 @@ export interface DeclarationOccurrenceIdentity extends DeclarationIdentityResult
 export async function resolveDeclarationIdentityKind(
   observation: DeclarationIdentityObservation,
   structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+  control?: CodeRequestControl,
 ): Promise<DeclarationIdentityResult> {
   const identityKind = canonicalDeclarationKind(observation.providerKind);
   if (
@@ -69,7 +75,8 @@ export async function resolveDeclarationIdentityKind(
     return exactNameAnchor && isTypeAlias
       ? { identityKind: "type", structuralEvidence: true }
       : { identityKind, structuralEvidence: false };
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     return { identityKind, structuralEvidence: false };
   }
 }
@@ -82,6 +89,7 @@ export function createCodeSymbolIdentityResolver(
   file: string,
   allSymbols: readonly CodeSymbol[],
   structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+  control?: CodeRequestControl,
 ): (symbol: CodeSymbol) => Promise<DeclarationOccurrenceIdentity> {
   const identities = new Map<CodeSymbol, Promise<DeclarationIdentityResult>>();
   const occurrences = new Map<CodeSymbol, Promise<DeclarationOccurrenceIdentity>>();
@@ -97,6 +105,7 @@ export function createCodeSymbolIdentityResolver(
         nameAnchor: symbol.nameAnchor ?? null,
       },
       structural,
+      control,
     );
     identities.set(symbol, identity);
     return identity;
@@ -147,6 +156,7 @@ function compareCodeSymbolDeclarations(left: CodeSymbol, right: CodeSymbol): num
 export async function refineTypeAliasIdentity(
   target: ResolvedTargetData,
   structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+  control?: CodeRequestControl,
 ): Promise<ResolvedTargetData> {
   if (target.identityKind !== undefined) return target;
   const identity = await resolveDeclarationIdentityKind(
@@ -160,6 +170,7 @@ export async function refineTypeAliasIdentity(
           : null,
     },
     structural,
+    control,
   );
   return {
     ...target,
@@ -173,9 +184,13 @@ export async function refineTargetOutcomeIdentity(
   outcome: TargetOutcome,
   cwd: string,
   structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+  control?: CodeRequestControl,
 ): Promise<TargetOutcome> {
   if (outcome.kind === "resolved") {
-    return { kind: "resolved", target: await refineTypeAliasIdentity(outcome.target, structural) };
+    return {
+      kind: "resolved",
+      target: await refineTypeAliasIdentity(outcome.target, structural, control),
+    };
   }
   if (outcome.kind !== "disambiguation" && outcome.kind !== "kind-mismatch") return outcome;
 
@@ -195,6 +210,7 @@ export async function refineTargetOutcomeIdentity(
               : null,
         },
         structural,
+        control,
       );
       return {
         candidate: {