@mrclrchtr/supi-code-runtime 4.9.0 → 5.0.0

package/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/package.json

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

package/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/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/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/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 };