@mrclrchtr/supi-code-intelligence 4.10.0 → 5.0.0

package/node_modules/@mrclrchtr/supi-tree-sitter/README.md

@@ -26,7 +26,9 @@ This package provides the parser-backed structural substrate consumed by `@mrclr
 - a shared session-scoped Tree-sitter service for structural analysis
 - an owned parsing session API for direct library consumers
 - a `StructuralProvider` adapter published through `./provider/tree-sitter-provider`
-- structural extraction helpers for outline/import/export/node/callee/call-site analysis inside the library surface
+- a long-lived owned Structural Worker that keeps Pi responsive during parser-backed work
+- `CodeRequestControl` cancellation, absolute deadlines, shared atomic interruption, and hard-stop termination
+- structural outline/import/export/node/callee/call-site operations through the asynchronous service surface
 - operation-specific extension discovery through `getStructuralSearchSupportedExtensions()`
 
 It does **not** register pi tools or commands on its own.
@@ -61,7 +63,7 @@ capabilities into the shared workspace runtime.
 ```text
 supi-code-runtime  ← shared contracts + workspace runtime
     ↑
-supi-tree-sitter  ← Tree-sitter WASM + session-scoped service + runtime capabilities
+supi-tree-sitter  ← one owned Structural Worker + session-scoped service + runtime capabilities
 ```
 
 ## Package surfaces
@@ -82,7 +84,7 @@ const parseable = await session.canParse("src/index.ts");
 const outline = await session.outline("src/index.ts");
 const callees = await session.calleesAt("src/index.ts", 42, 10);
 
-session.dispose();
+await session.dispose();
 ```
 
 Shared session-scoped service example:
@@ -104,15 +106,23 @@ Run the stable outline fixture on the same machine and dependency versions:
 pnpm --filter @mrclrchtr/supi-tree-sitter bench:structural
 ```
 
-The benchmark reports a cold session parser baseline and a repeated parser baseline. Debug capture is active, so the baseline includes the internal timing observation cost. The benchmark records measurements but does not set a pass or fail threshold.
+The benchmark reports cold and repeated outline results. It also reports cold and repeated call-site query results. Repeated operations reuse unchanged parsed trees and compiled queries. Debug capture is active, so the baseline includes the internal timing observation cost. The benchmark records measurements but does not set a pass or fail threshold.
+
+The Structural Worker reads files asynchronously. It identifies fresh parsed files by canonical path, grammar, and SHA-256 content hash. Cached trees use true least-recently-used eviction with limits of 128 files and 32 MiB of retained UTF-8 source bytes. Compiled queries use the same policy with limits of 128 queries and 512 KiB of retained UTF-8 query text. Source and query byte counts are memory-related proxies because `web-tree-sitter` does not report WASM resource sizes. Cached canonical trees stay private in the Worker.
+
+All structural service operations accept optional `CodeRequestControl`. The parent converts cancellation to one shared atomic flag and forwards absolute deadlines. When present, it forwards only the opaque Debug Operation ID through the Worker protocol so parse and query timing events keep direct request ownership. Direct library calls have no ID. Worker read phases observe a local abort signal. Parser and query progress callbacks observe the flag and deadline. If cooperative interruption does not settle in the fixed 250 ms grace period, the parent terminates the Worker. Valid queued work keeps FIFO order on one fresh Worker with cold caches. There is no main-thread parser fallback.
 
 ## Source
 
 - `src/api.ts` — public library entrypoint
 - `src/index.ts` — re-export surface
-- `src/session/runtime.ts` — parser and query runtime
-- `src/session/session.ts` — runtime-backed service helpers and owned session API
+- `src/worker/bootstrap.mjs` — package-owned Worker bootstrap and direct `jiti` loader
+- `src/worker/runtime.ts` — Worker-only parser and query runtime
+- `src/worker/parsed-file-store.ts` — Worker-only parsed-file and compiled-query reuse
+- `src/session/structural-worker-client.ts` — bounded FIFO mailbox, protocol, cancellation, and restart ownership
+- `src/session/runtime-controller.ts` — generation-fenced shared Worker lifecycle
+- `src/session/session.ts` — asynchronous Worker-proxy service and owned session API
 - `src/operation-support.ts` — authoritative operation-specific extension support
 - `src/session/service-registry.ts` — shared session-scoped structural service registry
 - `src/provider/tree-sitter-provider.ts` — `StructuralProvider` adapter consumed by `@mrclrchtr/supi-code-intelligence`
-- `src/tool/outline.ts`, `src/tool/outline-*.ts`, `src/tool/imports.ts`, `src/tool/exports.ts`, `src/tool/node-at.ts`, `src/tool/callees.ts`, `src/tool/call-sites.ts` — structural analyses exposed through the library surface
+- `src/tool/outline.ts`, `src/tool/outline-*.ts`, `src/tool/imports.ts`, `src/tool/exports.ts`, `src/tool/node-at.ts`, `src/tool/callees.ts`, `src/tool/call-sites.ts` — Worker-internal structural analyses

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/README.md

@@ -22,6 +22,8 @@ Read-only provider methods return `CodeQueryResult<T>`:
 
 This keeps successful zero-result facts distinct from routing, transport, and provider failures.
 
+Semantic and structural provider methods also accept optional `CodeRequestControl` metadata. It contains a caller `AbortSignal`, an absolute Unix-epoch deadline, and an optional opaque Debug Operation ID. Adapters preserve the same object. The ID does not change cancellation semantics. Canonical helpers identify cancellation and deadline expiry across bundled package copies. Cooperative structural substrates apply the control; unsupported substrates can preserve it without applying behavior.
+
 ## License
 
 MIT

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.10.0",
+  "version": "5.0.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts

@@ -9,6 +9,7 @@
 // Capability interfaces and availability states
 export type {
   CapabilityState,
+  CodeRequestControl,
   SemanticProvider,
   StructuralProvider,
   StructuralResult,
@@ -21,6 +22,13 @@ export {
   partialCodeQuery,
   unavailableCodeQuery,
 } from "./query-result.ts";
+export {
+  CodeRequestDeadlineError,
+  isCodeRequestDeadlineError,
+  isCodeRequestInterrupted,
+  isCodeRequestInterruption,
+  throwIfCodeRequestInterrupted,
+} from "./request-control.ts";
 // Shared canonical types
 export type {
   CalleeDepth,
@@ -34,6 +42,7 @@ export type {
   DeclarationNesting,
   DisambiguationCandidate,
   DocumentCodeSymbol,
+  DocumentEditPrecondition,
   ExportData,
   FileEdit,
   ImportData,

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

@@ -43,6 +43,16 @@ export type CapabilityState =
 
 // ── Provider interfaces ────────────────────────────────────────────────
 
+/** Request control that adapters preserve and cooperative providers apply. */
+export interface CodeRequestControl {
+  /** Opaque Debug Operation ID for work directly owned by one public Tool call. */
+  readonly operationId?: string;
+  /** Caller cancellation signal, when one exists. */
+  readonly signal?: AbortSignal;
+  /** Absolute wall-clock deadline in Unix epoch milliseconds. */
+  readonly deadline?: number;
+}
+
 /**
  * Semantic analysis capability backed by a language server (LSP).
  *
@@ -51,16 +61,31 @@ export type CapabilityState =
  * null values are completed observations rather than capability failures.
  */
 export interface SemanticProvider {
-  references(filePath: string, position: CodePosition): Promise<CodeQueryResult<CodeLocation[]>>;
+  references(
+    filePath: string,
+    position: CodePosition,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<CodeLocation[]>>;
   implementation(
     filePath: string,
     position: CodePosition,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<CodeLocation[]>>;
-  documentSymbols(filePath: string): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
-  workspaceSymbols(query: string): Promise<CodeQueryResult<CodeSymbol[]>>;
+  documentSymbols(
+    filePath: string,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
+  workspaceSymbols(
+    query: string,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<CodeSymbol[]>>;
 
   /** Optional definition capability with explicit completed-empty semantics. */
-  definition?(filePath: string, position: CodePosition): Promise<CodeQueryResult<CodeLocation[]>>;
+  definition?(
+    filePath: string,
+    position: CodePosition,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<CodeLocation[]>>;
 
   /**
    * Optional hover capability. A completed `null` data value means the
@@ -69,6 +94,7 @@ export interface SemanticProvider {
   hover?(
     filePath: string,
     position: CodePosition,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<{ contents: string; range?: SourceRange } | null>>;
 
   /**
@@ -79,7 +105,7 @@ export interface SemanticProvider {
    * organize imports, dead-code cleanup, etc.) without exposing that branching
    * to callers.
    */
-  refactor?(request: RefactorRequest): Promise<RefactorResult>;
+  refactor?(request: RefactorRequest, control?: CodeRequestControl): Promise<RefactorResult>;
 
   /**
    * Optional rename capability. When present, the provider supports
@@ -88,7 +114,12 @@ export interface SemanticProvider {
    * This remains a lower-level substrate helper for providers that expose
    * symbol rename independently of their general refactor planner.
    */
-  rename?(file: string, position: CodePosition, newName: string): Promise<RefactorResult>;
+  rename?(
+    file: string,
+    position: CodePosition,
+    newName: string,
+    control?: CodeRequestControl,
+  ): Promise<RefactorResult>;
 
   /**
    * Optional code actions capability. When present, the provider
@@ -96,7 +127,11 @@ export interface SemanticProvider {
    *
    * Kept as a low-level substrate helper and for lightweight introspection.
    */
-  codeActions?(file: string, position: CodePosition): Promise<RefactorResult[]>;
+  codeActions?(
+    file: string,
+    position: CodePosition,
+    control?: CodeRequestControl,
+  ): Promise<RefactorResult[]>;
 }
 
 /**
@@ -111,14 +146,19 @@ export interface StructuralProvider {
     file: string,
     line: number,
     character: number,
-    depth?: CalleeDepth,
+    depthOrOptions?: CalleeDepth | { depth?: CalleeDepth; control?: CodeRequestControl },
   ): Promise<CodeResult<CalleesData>>;
-  exports(file: string): Promise<CodeResult<ExportData[]>>;
-  outline(file: string): Promise<CodeResult<OutlineData[]>>;
-  imports(file: string): Promise<CodeResult<ImportData[]>>;
-  nodeAt(file: string, line: number, character: number): Promise<CodeResult<NodeAtData>>;
+  exports(file: string, control?: CodeRequestControl): Promise<CodeResult<ExportData[]>>;
+  outline(file: string, control?: CodeRequestControl): Promise<CodeResult<OutlineData[]>>;
+  imports(file: string, control?: CodeRequestControl): Promise<CodeResult<ImportData[]>>;
+  nodeAt(
+    file: string,
+    line: number,
+    character: number,
+    control?: CodeRequestControl,
+  ): Promise<CodeResult<NodeAtData>>;
   /** Find all call-site identifiers in a file. Returns name + start line for each match. */
-  callSites(file: string): Promise<CodeResult<CallSite[]>>;
+  callSites(file: string, control?: CodeRequestControl): Promise<CodeResult<CallSite[]>>;
 }
 
 /** Convenience alias for `CodeResult` used in structural contexts. */

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/request-control.ts

@@ -0,0 +1,47 @@
+import type { CodeRequestControl } from "./capability/types.ts";
+
+/** Error raised when an absolute code-request deadline has elapsed. */
+export class CodeRequestDeadlineError extends Error {
+  constructor() {
+    super("Code request deadline exceeded");
+    this.name = "CodeRequestDeadlineError";
+  }
+}
+
+/** Test whether request cancellation or its absolute deadline has elapsed. */
+export function isCodeRequestInterrupted(
+  control: CodeRequestControl | undefined,
+  now: () => number = Date.now,
+): boolean {
+  return (
+    control?.signal?.aborted === true ||
+    (control?.deadline !== undefined && now() >= control.deadline)
+  );
+}
+
+/** Throw the caller abort reason or a canonical absolute-deadline error. */
+export function throwIfCodeRequestInterrupted(
+  control: CodeRequestControl | undefined,
+  now: () => number = Date.now,
+): void {
+  control?.signal?.throwIfAborted();
+  if (control?.deadline !== undefined && now() >= control.deadline) {
+    throw new CodeRequestDeadlineError();
+  }
+}
+
+/** Identify an absolute-deadline error across bundled package copies. */
+export function isCodeRequestDeadlineError(error: unknown): error is Error {
+  return (
+    error instanceof CodeRequestDeadlineError ||
+    (error instanceof Error && error.name === "CodeRequestDeadlineError")
+  );
+}
+
+/** Identify an error caused by the supplied request control. */
+export function isCodeRequestInterruption(
+  error: unknown,
+  control: CodeRequestControl | undefined,
+): boolean {
+  return isCodeRequestDeadlineError(error) || control?.signal?.aborted === true;
+}

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

@@ -149,11 +149,18 @@ export interface FileEdit {
   newText: string;
 }
 
+/** A document-state precondition established when semantic edits are normalized. */
+export type DocumentEditPrecondition =
+  | { file: string; kind: "open-document-version"; version: number }
+  | { file: string; kind: "disk-content" };
+
 /**
  * A precise workspace edit — one or more file edits to apply atomically.
  */
 export interface WorkspaceEdit {
   edits: FileEdit[];
+  /** Document state that the semantic provider validated before it made this plan. */
+  documentPreconditions?: DocumentEditPrecondition[];
 }
 
 /**
@@ -202,7 +209,12 @@ export interface DisambiguationCandidate {
  * - `unavailable`: refactoring not possible
  */
 export type RefactorResult =
-  | { kind: "precise"; edits: WorkspaceEdit }
+  | {
+      kind: "precise";
+      edits: WorkspaceEdit;
+      /** Provider roots authorized by the semantic route. Consumers canonicalize before storage. */
+      authorizedMutationRoots: string[];
+    }
   | { kind: "ambiguous"; candidates: DisambiguationCandidate[] }
   | { kind: "unavailable"; reason: string };
 

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/README.md

@@ -28,6 +28,7 @@ pnpm add @mrclrchtr/supi-core
 - `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
 - `loadSupiConfigForScope()` — load one scope at a time for settings UIs
 - `writeSupiConfig()` — persist values
+- `replaceSupiConfigSection()` — replace one nested section while preserving other sections
 - `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
@@ -49,6 +50,7 @@ Config file locations:
 
 - context-provider registry for `/supi-context`
 - debug-event registry and monotonic phase timers for producers that want shared debug capture
+- optional Debug Operation IDs for exact, directly owned public Tool-call correlation; ambient events stay uncorrelated
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.10.0",
+  "version": "5.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

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

@@ -148,6 +148,37 @@ export function writeSupiConfig(
   fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
 }
 
+/**
+ * Replace one complete config section while preserving other sections.
+ *
+ * This is useful for nested settings that must remove stale keys as part of
+ * one update. An empty section is removed from the config file.
+ */
+export function replaceSupiConfigSection(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+  const existing = readJsonFile(configPath) ?? {};
+
+  if (Object.keys(value).length > 0) existing[loc.section] = value;
+  else delete existing[loc.section];
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+  if (content) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, "utf-8");
+    return;
+  }
+
+  try {
+    fs.unlinkSync(configPath);
+  } catch {
+    // File may not exist.
+  }
+}
+
 /**
  * Remove a key from a config section.
  * Used by `interval default` to remove the project override.

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

@@ -1,10 +1,12 @@
 // supi-core config domain — config loading.
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
+  getSupiConfigPath,
   loadSupiConfig,
   loadSupiConfigForScope,
   loadSupiConfigSectionForScope,
   readJsonFile,
   removeSupiConfigKey,
+  replaceSupiConfigSection,
   writeSupiConfig,
 } from "./config/config.ts";

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -25,6 +25,8 @@ export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
 };
 
 export interface DebugEventInput {
+  /** Opaque identity for events directly owned by one public Tool call. */
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -42,6 +44,8 @@ export interface DebugEvent extends DebugEventInput {
 }
 
 export interface DebugEventQuery {
+  /** Match one exact Debug Operation ID. */
+  operationId?: string;
   source?: string;
   level?: DebugLevel;
   category?: string;
@@ -53,6 +57,7 @@ export interface DebugEventQuery {
 export interface DebugEventView {
   id: number;
   timestamp: number;
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -84,6 +89,7 @@ interface DebugRegistryState {
 }
 
 const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-core/debug-registry");
+const DEBUG_OPERATION_ID_RE = /^op-[A-Za-z0-9_-]{21}[AQgw]$/;
 const SECRET_KEY_RE = /(?:token|password|passwd|secret|api[_-]?key|authorization|credential)/i;
 const ENV_SECRET_RE =
   /\b([A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|authorization|credential)[A-Za-z0-9_]*)=(?:'[^']*'|"[^"]*"|\S+)/gi;
@@ -135,11 +141,17 @@ export function isDebugLevel(value: unknown): value is DebugLevel {
   return value === "debug" || value === "info" || value === "warning" || value === "error";
 }
 
-/** Match a debug event against the supported source, level, and category filters. */
+/** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
+export function isDebugOperationId(value: unknown): value is string {
+  return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
+}
+
+/** Match a debug event against the supported exact filters. */
 export function matchesDebugEventQuery(
-  event: Pick<DebugEventView, "source" | "level" | "category">,
-  query: Pick<DebugEventQuery, "source" | "level" | "category">,
+  event: Pick<DebugEventView, "operationId" | "source" | "level" | "category">,
+  query: Pick<DebugEventQuery, "operationId" | "source" | "level" | "category">,
 ): boolean {
+  if (query.operationId && event.operationId !== query.operationId) return false;
   if (query.source && event.source !== query.source) return false;
   if (query.level && event.level !== query.level) return false;
   if (query.category && event.category !== query.category) return false;
@@ -197,6 +209,7 @@ function toSanitizedView(event: DebugEvent): DebugEventView {
   return {
     id: event.id,
     timestamp: event.timestamp,
+    operationId: event.operationId,
     source: event.source,
     level: event.level,
     category: event.category,
@@ -216,6 +229,9 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
 /** Record a session-local debug event if debugging is enabled. */
 export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   const state = getState();
+  if (input.operationId !== undefined && !isDebugOperationId(input.operationId)) {
+    return null;
+  }
   if (!state.config.enabled) {
     return null;
   }

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/settings/settings-registry.ts

@@ -41,7 +41,10 @@ export interface SettingsApplyResult {
  */
 export interface SettingsModule {
   id: string;
+  /** Human-readable section label shown in the UI. */
   label: string;
+  /** Optional label that groups this module within its section. */
+  subsection?: string;
   read(context: SettingsContext): Promise<SettingsSnapshot>;
   apply(request: SettingsActionRequest): Promise<SettingsApplyResult>;
 }

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/jiti/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Pooya Parsa <pooya@pi0.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.