@mrclrchtr/supi-code-intelligence 4.9.0 → 5.0.0

package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/structural-worker-protocol.ts

@@ -0,0 +1,452 @@
+// biome-ignore-all lint/style/noExcessiveLinesPerFile: one private protocol module defines and validates the full closed contract
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
+import { isDebugOperationId } from "@mrclrchtr/supi-core/debug";
+import type { TreeSitterResult } from "../types.ts";
+import type { StructuralTimingEvent } from "./structural-timing.ts";
+
+/** Version of the private parent/Structural Worker message contract. */
+export const STRUCTURAL_WORKER_PROTOCOL_VERSION = 1 as const;
+
+/** Fixed internal bounds for one Structural Worker lifecycle. */
+export const STRUCTURAL_WORKER_LIMITS = Object.freeze({
+  maxQueuedRequests: 32,
+  maxMessageBytes: 512 * 1024,
+  targetChunkBytes: 256 * 1024,
+  maxResultBytes: 16 * 1024 * 1024,
+  maxAtomicValueBytes: 256 * 1024,
+  hardStopGraceMs: 250,
+});
+
+export type StructuralWorkerOperation =
+  | { readonly operation: "canParse"; readonly file: string }
+  | { readonly operation: "query"; readonly file: string; readonly query: string }
+  | {
+      readonly operation: "outline" | "imports" | "exports" | "callSites";
+      readonly file: string;
+    }
+  | {
+      readonly operation: "nodeAt";
+      readonly file: string;
+      readonly line: number;
+      readonly character: number;
+    }
+  | {
+      readonly operation: "calleesAt";
+      readonly file: string;
+      readonly line: number;
+      readonly character: number;
+      readonly depth?: "direct" | "deep";
+    };
+
+export interface StructuralWorkerRequestMessage {
+  readonly kind: "request";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+  readonly requestId: string;
+  readonly input: StructuralWorkerOperation;
+  readonly operationId?: string;
+  readonly deadline?: number;
+  readonly cancellationFlag: SharedArrayBuffer;
+}
+
+export interface StructuralWorkerCancelMessage {
+  readonly kind: "cancel";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+  readonly requestId: string;
+}
+
+export interface StructuralWorkerChunkAckMessage {
+  readonly kind: "chunk-ack";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+  readonly requestId: string;
+  readonly sequence: number;
+}
+
+export type ParentToStructuralWorkerMessage =
+  | StructuralWorkerRequestMessage
+  | StructuralWorkerCancelMessage
+  | StructuralWorkerChunkAckMessage;
+
+export interface StructuralWorkerReadyMessage {
+  readonly kind: "ready";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+}
+
+export interface StructuralWorkerStartupFailureMessage {
+  readonly kind: "startup-failure";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+  readonly message: string;
+}
+
+export interface StructuralWorkerChunkMessage {
+  readonly kind: "chunk";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+  readonly requestId: string;
+  readonly sequence: number;
+  readonly final: boolean;
+  readonly encodedBytes: number;
+  readonly payload: Uint8Array;
+}
+
+export interface StructuralWorkerObservationMessage {
+  readonly kind: "observation";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+  readonly requestId: string;
+  readonly observation: StructuralTimingEvent;
+}
+
+export interface StructuralWorkerTerminalMessage {
+  readonly kind: "terminal";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+  readonly requestId: string;
+  readonly outcome: "completed" | "cancelled" | "timeout";
+}
+
+export type StructuralWorkerToParentMessage =
+  | StructuralWorkerReadyMessage
+  | StructuralWorkerStartupFailureMessage
+  | StructuralWorkerChunkMessage
+  | StructuralWorkerObservationMessage
+  | StructuralWorkerTerminalMessage;
+
+export type StructuralProtocolValidation<T> =
+  | { readonly kind: "valid"; readonly message: T }
+  | { readonly kind: "invalid"; readonly reason: string };
+
+/** Validate an untrusted request before the Structural Worker executes it. */
+export function validateStructuralWorkerRequest(
+  value: unknown,
+): StructuralProtocolValidation<StructuralWorkerRequestMessage> {
+  if (!isRecord(value)) return invalid("Structural Worker request must be an object");
+  const required = ["kind", "version", "generation", "requestId", "input", "cancellationFlag"];
+  const allowed = new Set([...required, "operationId", "deadline"]);
+  if (
+    required.some((key) => !(key in value)) ||
+    Object.keys(value).some((key) => !allowed.has(key))
+  ) {
+    return invalid("Invalid structural request envelope");
+  }
+  if (
+    value.kind !== "request" ||
+    value.version !== STRUCTURAL_WORKER_PROTOCOL_VERSION ||
+    !isPositiveInteger(value.generation) ||
+    !isRequestId(value.requestId) ||
+    !isRecord(value.input) ||
+    !(value.cancellationFlag instanceof SharedArrayBuffer) ||
+    value.cancellationFlag.byteLength !== Int32Array.BYTES_PER_ELEMENT ||
+    (value.deadline !== undefined &&
+      (typeof value.deadline !== "number" || !Number.isFinite(value.deadline))) ||
+    (value.operationId !== undefined && !isDebugOperationId(value.operationId))
+  ) {
+    return invalid("Invalid structural request");
+  }
+  return valid(value as unknown as StructuralWorkerRequestMessage);
+}
+
+/** Encode one complete structural result into fixed-size binary chunks. */
+export function encodeStructuralResult(result: TreeSitterResult<unknown>): Uint8Array[] {
+  assertPlainProtocolValue(result);
+  const bytes = Buffer.from(JSON.stringify(result), "utf8");
+  if (bytes.byteLength > STRUCTURAL_WORKER_LIMITS.maxResultBytes) {
+    throw new Error(
+      `Structural result exceeds the ${STRUCTURAL_WORKER_LIMITS.maxResultBytes}-byte limit`,
+    );
+  }
+  const chunks: Uint8Array[] = [];
+  for (
+    let offset = 0;
+    offset < bytes.byteLength;
+    offset += STRUCTURAL_WORKER_LIMITS.targetChunkBytes
+  ) {
+    const end = Math.min(offset + STRUCTURAL_WORKER_LIMITS.targetChunkBytes, bytes.byteLength);
+    chunks.push(Uint8Array.from(bytes.subarray(offset, end)));
+  }
+  return chunks.length > 0 ? chunks : [new Uint8Array()];
+}
+
+/** Reconstruct one complete structural result from validated binary chunks. */
+export function decodeStructuralResult<T>(chunks: readonly Uint8Array[]): TreeSitterResult<T> {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  if (total > STRUCTURAL_WORKER_LIMITS.maxResultBytes) {
+    throw new Error(
+      `Structural result exceeds the ${STRUCTURAL_WORKER_LIMITS.maxResultBytes}-byte limit`,
+    );
+  }
+  const parsed: unknown = JSON.parse(
+    Buffer.concat(
+      chunks.map((chunk) => Buffer.from(chunk)),
+      total,
+    ).toString("utf8"),
+  );
+  assertTreeSitterResult(parsed);
+  return parsed as TreeSitterResult<T>;
+}
+
+/** Validate an untrusted message received from a Structural Worker. */
+export function validateWorkerToParentMessage(
+  value: unknown,
+): StructuralProtocolValidation<StructuralWorkerToParentMessage> {
+  if (!isRecord(value)) return invalid("Structural Worker message must be an object");
+  if (value.version !== STRUCTURAL_WORKER_PROTOCOL_VERSION) {
+    return invalid("Unsupported Structural Worker protocol version");
+  }
+  if (!isPositiveInteger(value.generation)) return invalid("Invalid Worker generation");
+  switch (value.kind) {
+    case "ready":
+      return hasExactKeys(value, ["kind", "version", "generation"])
+        ? valid(value as unknown as StructuralWorkerReadyMessage)
+        : invalid("Invalid ready message");
+    case "startup-failure":
+      return hasExactKeys(value, ["kind", "version", "generation", "message"]) &&
+        isBoundedString(value.message, 1_024)
+        ? valid(value as unknown as StructuralWorkerStartupFailureMessage)
+        : invalid("Invalid startup failure");
+    case "chunk":
+      return validateChunk(value);
+    case "observation":
+      return validateObservation(value);
+    case "terminal":
+      return validateTerminal(value);
+    default:
+      return invalid("Unknown Structural Worker message kind");
+  }
+}
+
+/** Build the exact request control represented by one Worker request. */
+export interface StructuralWorkerRequestControl extends CodeRequestControl {
+  readonly cancellationFlag: Int32Array;
+}
+
+function validateChunk(
+  value: Record<string, unknown>,
+): StructuralProtocolValidation<StructuralWorkerChunkMessage> {
+  if (
+    !hasExactKeys(value, [
+      "kind",
+      "version",
+      "generation",
+      "requestId",
+      "sequence",
+      "final",
+      "encodedBytes",
+      "payload",
+    ])
+  ) {
+    return invalid("Invalid chunk envelope");
+  }
+  if (!isRequestId(value.requestId)) return invalid("Invalid request id");
+  if (!Number.isSafeInteger(value.sequence) || Number(value.sequence) < 0) {
+    return invalid("Invalid chunk sequence");
+  }
+  if (typeof value.final !== "boolean") return invalid("Invalid final chunk marker");
+  if (!(value.payload instanceof Uint8Array)) return invalid("Invalid chunk payload");
+  if (value.encodedBytes !== value.payload.byteLength) return invalid("Invalid chunk byte count");
+  if (value.payload.byteLength > STRUCTURAL_WORKER_LIMITS.targetChunkBytes) {
+    return invalid("Structural Worker chunk exceeds the byte limit");
+  }
+  if (
+    estimateChunkMessageBytes(value.payload.byteLength) > STRUCTURAL_WORKER_LIMITS.maxMessageBytes
+  ) {
+    return invalid("Structural Worker message exceeds the byte limit");
+  }
+  return valid(value as unknown as StructuralWorkerChunkMessage);
+}
+
+function validateObservation(
+  value: Record<string, unknown>,
+): StructuralProtocolValidation<StructuralWorkerObservationMessage> {
+  if (!hasExactKeys(value, ["kind", "version", "generation", "requestId", "observation"])) {
+    return invalid("Invalid observation envelope");
+  }
+  if (!isRequestId(value.requestId)) return invalid("Invalid request id");
+  if (!isStructuralTimingEvent(value.observation)) return invalid("Invalid structural observation");
+  return valid(value as unknown as StructuralWorkerObservationMessage);
+}
+
+function validateTerminal(
+  value: Record<string, unknown>,
+): StructuralProtocolValidation<StructuralWorkerTerminalMessage> {
+  if (!hasExactKeys(value, ["kind", "version", "generation", "requestId", "outcome"])) {
+    return invalid("Invalid terminal envelope");
+  }
+  if (!isRequestId(value.requestId)) return invalid("Invalid request id");
+  if (
+    value.outcome !== "completed" &&
+    value.outcome !== "cancelled" &&
+    value.outcome !== "timeout"
+  ) {
+    return invalid("Invalid terminal outcome");
+  }
+  return valid(value as unknown as StructuralWorkerTerminalMessage);
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: every sanitized nested timing field is validated at one trust boundary
+function isStructuralTimingEvent(value: unknown): value is StructuralTimingEvent {
+  if (!isRecord(value) || !isRecord(value.data) || !isRecord(value.data.timing)) return false;
+  const expected =
+    value.operationId === undefined
+      ? ["source", "level", "category", "message", "data"]
+      : ["operationId", "source", "level", "category", "message", "data"];
+  if (!hasExactKeys(value, expected)) return false;
+  if (value.operationId !== undefined && !isDebugOperationId(value.operationId)) return false;
+  if (value.source !== "tree-sitter" || value.level !== "debug") return false;
+  if (
+    value.category !== "structural.parse.timing" &&
+    value.category !== "structural.query.timing"
+  ) {
+    return false;
+  }
+  if (
+    !isBoundedString(value.message, 96) ||
+    !/^Tree-sitter (?:parse|query) [a-z-]+$/.test(value.message)
+  ) {
+    return false;
+  }
+  if (!isGrammar(value.data.grammar)) return false;
+  if (value.data.cache !== undefined && !isCacheObservation(value.data.cache)) return false;
+  const timing = value.data.timing;
+  if (!hasExactKeys(timing, ["durationMs", "phasesMs"]) || !isFiniteDuration(timing.durationMs)) {
+    return false;
+  }
+  if (!isRecord(timing.phasesMs) || Object.keys(timing.phasesMs).length > 8) return false;
+  if (
+    Object.entries(timing.phasesMs).some(
+      ([phase, duration]) => !/^[a-z-]{1,32}$/.test(phase) || !isFiniteDuration(duration),
+    )
+  ) {
+    return false;
+  }
+  return value.category === "structural.parse.timing"
+    ? isParseTimingData(value.data)
+    : isQueryTimingData(value.data);
+}
+
+function assertTreeSitterResult(value: unknown): asserts value is TreeSitterResult<unknown> {
+  if (!isRecord(value) || typeof value.kind !== "string")
+    throw new Error("Invalid structural result");
+  if (value.kind === "success" && "data" in value) return;
+  if (
+    value.kind === "unsupported-language" ||
+    value.kind === "file-access-error" ||
+    value.kind === "validation-error" ||
+    value.kind === "runtime-error"
+  ) {
+    if (typeof value.message === "string") return;
+  }
+  throw new Error("Invalid structural result");
+}
+
+function assertPlainProtocolValue(value: unknown, seen = new Set<object>()): void {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("Structural result contains a non-finite number");
+    return;
+  }
+  if (typeof value !== "object") throw new Error("Structural result contains an unsupported value");
+  if (seen.has(value)) throw new Error("Structural result contains a cycle");
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) assertPlainProtocolValue(item, seen);
+    seen.delete(value);
+    return;
+  }
+  if (Object.getPrototypeOf(value) !== Object.prototype) {
+    const size = Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+    if (size > STRUCTURAL_WORKER_LIMITS.maxAtomicValueBytes) {
+      throw new Error("Structural result contains an oversize indivisible value");
+    }
+    throw new Error("Structural result contains a non-plain value");
+  }
+  for (const item of Object.values(value)) assertPlainProtocolValue(item, seen);
+  seen.delete(value);
+}
+
+function isParseTimingData(data: Record<string, unknown>): boolean {
+  const expected =
+    data.cache === undefined
+      ? ["operation", "grammar", "parserState", "outcome", "timing"]
+      : ["operation", "grammar", "parserState", "outcome", "cache", "timing"];
+  if (!hasExactKeys(data, expected)) return false;
+  return (
+    data.operation === "parse" &&
+    (data.parserState === "cold" ||
+      data.parserState === "initializing" ||
+      data.parserState === "reused") &&
+    ["cancelled", "completed", "file-access-error", "runtime-error", "timeout"].includes(
+      String(data.outcome),
+    )
+  );
+}
+
+function isQueryTimingData(data: Record<string, unknown>): boolean {
+  if (!hasExactKeys(data, ["operation", "grammar", "outcome", "captureCount", "cache", "timing"])) {
+    return false;
+  }
+  return (
+    data.operation === "query" &&
+    Number.isSafeInteger(data.captureCount) &&
+    Number(data.captureCount) >= 0 &&
+    ["cancelled", "completed", "runtime-error", "timeout", "validation-error"].includes(
+      String(data.outcome),
+    )
+  );
+}
+
+function isCacheObservation(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasExactKeys(value, ["state", "retained", "evictionCount"]) &&
+    (value.state === "hit" || value.state === "miss" || value.state === "replacement") &&
+    typeof value.retained === "boolean" &&
+    Number.isSafeInteger(value.evictionCount) &&
+    Number(value.evictionCount) >= 0
+  );
+}
+
+function isGrammar(value: unknown): boolean {
+  return isBoundedString(value, 16) && /^[a-z]+$/.test(value);
+}
+
+function isFiniteDuration(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  return actual.length === expected.length && expected.every((key) => actual.includes(key));
+}
+
+function isBoundedString(value: unknown, maxLength: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= maxLength;
+}
+
+function estimateChunkMessageBytes(payloadBytes: number): number {
+  return payloadBytes + 1024;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPositiveInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && Number(value) > 0;
+}
+
+function isRequestId(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 128;
+}
+
+function valid<T>(message: T): StructuralProtocolValidation<T> {
+  return { kind: "valid", message };
+}
+
+function invalid(reason: string): StructuralProtocolValidation<never> {
+  return { kind: "invalid", reason };
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/call-sites.ts

@@ -1,8 +1,9 @@
 /** File-wide call-site extraction using per-grammar tree-sitter queries. */
 
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { detectGrammar } from "../language.ts";
-import type { TreeSitterRuntime } from "../session/runtime.ts";
 import type { CallSiteMatch, GrammarId, TreeSitterResult } from "../types.ts";
+import type { TreeSitterRuntime } from "../worker/runtime.ts";
 
 // ── Per-grammar call-site queries ─────────────────────────────────────
 
@@ -48,6 +49,7 @@ export function supportsCallSitesGrammar(grammarId: GrammarId): boolean {
 export async function extractCallSites(
   runtime: TreeSitterRuntime,
   filePath: string,
+  control?: CodeRequestControl,
 ): Promise<TreeSitterResult<CallSiteMatch[]>> {
   const grammarId = detectGrammar(filePath);
   if (!grammarId) {
@@ -67,7 +69,7 @@ export async function extractCallSites(
     };
   }
 
-  const queryResult = await runtime.queryFile(filePath, queryStr);
+  const queryResult = await runtime.queryFile(filePath, queryStr, control);
   if (queryResult.kind !== "success") return queryResult;
 
   const captures = queryResult.data;

package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/callees.ts

@@ -1,8 +1,9 @@
 // Structural callee extraction — enclosing-scope lookup with per-language queries.
 
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { detectGrammar } from "../language.ts";
-import type { TreeSitterRuntime } from "../session/runtime.ts";
 import type { GrammarId, SourceRange, TreeSitterResult } from "../types.ts";
+import { queryParsedFile, type TreeSitterRuntime } from "../worker/runtime.ts";
 
 /** Result shape returned by lookupCalleesAt. */
 export interface CalleesAtResult {
@@ -174,6 +175,7 @@ export async function lookupCalleesAt(
   line: number,
   character: number,
   depth: "direct" | "deep" = "direct",
+  control?: CodeRequestControl,
 ): Promise<TreeSitterResult<CalleesAtResult>> {
   // Validate coordinates and grammar
   const validation = validateCalleeInput(filePath, line, character);
@@ -181,10 +183,10 @@ export async function lookupCalleesAt(
   const { grammarId } = validation;
 
   // Parse the file
-  const parseResult = await runtime.parseFile(filePath);
+  const parseResult = await runtime.parseFile(filePath, control);
   if (parseResult.kind !== "success") return parseResult;
 
-  const { tree } = parseResult.data;
+  const { tree, source } = parseResult.data;
 
   try {
     const scopes = ENCLOSING_SCOPE_TYPES[grammarId];
@@ -214,7 +216,13 @@ export async function lookupCalleesAt(
       };
     }
 
-    const queryResult = await runtime.queryFile(filePath, queryStr);
+    const queryResult = await queryParsedFile(runtime, {
+      grammarId,
+      tree,
+      source,
+      queryString: queryStr,
+      control,
+    });
     if (queryResult.kind !== "success") {
       return {
         kind: "runtime-error",

package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/exports.ts

@@ -1,16 +1,18 @@
 // Export extraction for supported files.
 
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { nodeToRange } from "../coordinates.ts";
-import type { TreeSitterRuntime } from "../session/runtime.ts";
 import type { SyntaxNodeLike } from "../syntax-node.ts";
 import type { ExportRecord, TreeSitterResult } from "../types.ts";
+import type { TreeSitterRuntime } from "../worker/runtime.ts";
 
 /** Extract export records from a supported file. */
 export async function extractExports(
   runtime: TreeSitterRuntime,
   filePath: string,
+  control?: CodeRequestControl,
 ): Promise<TreeSitterResult<ExportRecord[]>> {
-  const parseResult = await runtime.parseFile(filePath);
+  const parseResult = await runtime.parseFile(filePath, control);
   if (parseResult.kind !== "success") return parseResult;
 
   const { tree, source } = parseResult.data;

package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/imports.ts

@@ -1,16 +1,18 @@
 // Import extraction for supported files.
 
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { nodeToRange } from "../coordinates.ts";
-import type { TreeSitterRuntime } from "../session/runtime.ts";
 import type { SyntaxNodeLike } from "../syntax-node.ts";
 import type { ImportRecord, TreeSitterResult } from "../types.ts";
+import type { TreeSitterRuntime } from "../worker/runtime.ts";
 
 /** Extract import records from a supported file. */
 export async function extractImports(
   runtime: TreeSitterRuntime,
   filePath: string,
+  control?: CodeRequestControl,
 ): Promise<TreeSitterResult<ImportRecord[]>> {
-  const parseResult = await runtime.parseFile(filePath);
+  const parseResult = await runtime.parseFile(filePath, control);
   if (parseResult.kind !== "success") return parseResult;
 
   const { tree, source } = parseResult.data;

package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/node-at.ts

@@ -1,8 +1,9 @@
 // Node-at-position lookup.
 
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { nodeToRange, publicToTreeSitter, splitSourceLines } from "../coordinates.ts";
-import type { TreeSitterRuntime } from "../session/runtime.ts";
 import type { NodeAtResult, SourceRange, TreeSitterResult } from "../types.ts";
+import type { TreeSitterRuntime } from "../worker/runtime.ts";
 
 const MAX_ANCESTRY = 10;
 
@@ -11,8 +12,9 @@ export async function lookupNodeAt(
   runtime: TreeSitterRuntime,
   filePath: string,
   line: number,
-  character: number,
+  ...position: [character: number, control?: CodeRequestControl]
 ): Promise<TreeSitterResult<NodeAtResult>> {
+  const [character, control] = position;
   if (!Number.isInteger(line) || line < 1) {
     return { kind: "validation-error", message: "line must be a positive 1-based integer" };
   }
@@ -20,7 +22,7 @@ export async function lookupNodeAt(
     return { kind: "validation-error", message: "character must be a positive 1-based integer" };
   }
 
-  const parseResult = await runtime.parseFile(filePath);
+  const parseResult = await runtime.parseFile(filePath, control);
   if (parseResult.kind !== "success") return parseResult;
 
   const { tree, source } = parseResult.data;

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

@@ -1,5 +1,7 @@
 // Public tree-sitter package types.
 
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
+
 /** 1-based source range compatible with LSP position convention. */
 export interface SourceRange {
   startLine: number;
@@ -73,38 +75,57 @@ export interface CallSiteMatch {
   startLine: number;
 }
 
-/** Shared Tree-sitter service surface, independent of lifecycle ownership. */
+/**
+ * Shared Tree-sitter service surface, independent of lifecycle ownership.
+ * Optional request control cooperatively stops reads, parser progress, query
+ * progress, and cache publication without exposing raw WASM resources.
+ */
 export interface TreeSitterService {
   /** Validate that a supported file can be read and parsed; does not expose the raw tree. */
-  canParse(file: string): Promise<TreeSitterResult<{ file: string; language: string }>>;
+  canParse(
+    file: string,
+    control?: CodeRequestControl,
+  ): Promise<TreeSitterResult<{ file: string; language: string }>>;
   /** Run a Tree-sitter query and return all captures. */
-  query(file: string, queryString: string): Promise<TreeSitterResult<QueryCapture[]>>;
+  query(
+    file: string,
+    queryString: string,
+    control?: CodeRequestControl,
+  ): Promise<TreeSitterResult<QueryCapture[]>>;
   /**
    * Extract shallow declarations, including supported nested code members,
    * HTML ids, and SQL schema members.
    */
-  outline(file: string): Promise<TreeSitterResult<OutlineItem[]>>;
+  outline(file: string, control?: CodeRequestControl): Promise<TreeSitterResult<OutlineItem[]>>;
   /** Extract static ES import declarations. */
-  imports(file: string): Promise<TreeSitterResult<ImportRecord[]>>;
+  imports(file: string, control?: CodeRequestControl): Promise<TreeSitterResult<ImportRecord[]>>;
   /** Extract exported declarations, named exports, re-exports, and TS export assignments. */
-  exports(file: string): Promise<TreeSitterResult<ExportRecord[]>>;
+  exports(file: string, control?: CodeRequestControl): Promise<TreeSitterResult<ExportRecord[]>>;
   /** Return the smallest syntax node at a 1-based UTF-16 position. */
-  nodeAt(file: string, line: number, character: number): Promise<TreeSitterResult<NodeAtResult>>;
+  nodeAt(
+    file: string,
+    line: number,
+    character: number,
+    control?: CodeRequestControl,
+  ): Promise<TreeSitterResult<NodeAtResult>>;
   /** Extract structural outgoing calls from the enclosing scope at a position. */
   calleesAt(
     file: string,
     line: number,
     character: number,
-    depth?: "direct" | "deep",
+    depthOrOptions?:
+      | "direct"
+      | "deep"
+      | { depth?: "direct" | "deep"; control?: CodeRequestControl },
   ): Promise<TreeSitterResult<CalleesAtResult>>;
   /** Extract all call-site identifiers in a file. */
-  callSites(file: string): Promise<TreeSitterResult<CallSiteMatch[]>>;
+  callSites(file: string, control?: CodeRequestControl): Promise<TreeSitterResult<CallSiteMatch[]>>;
 }
 
-/** Owned Tree-sitter session that must release its runtime resources. */
+/** Owned Tree-sitter session that must release its Worker resources. */
 export interface TreeSitterSession extends TreeSitterService {
-  /** Release parser and grammar resources owned by this session. */
-  dispose(): void;
+  /** Terminate and await the Structural Worker owned by this session. */
+  dispose(): Promise<void>;
 }
 
 /** Session-scoped shared structural service published by the extension runtime. */