@mrclrchtr/supi-code-intelligence 6.0.1 → 6.2.0

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

@@ -75,9 +75,14 @@ export interface SemanticProvider {
     filePath: string,
     control?: CodeRequestControl,
   ): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
+  /**
+   * Collect workspace symbols from routes that can contribute within the
+   * optional canonical path scopes.
+   */
   workspaceSymbols(
     query: string,
     control?: CodeRequestControl,
+    scopes?: readonly string[],
   ): Promise<CodeQueryResult<CodeSymbol[]>>;
 
   /** Optional definition capability with explicit completed-empty semantics. */

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "6.0.1",
+  "version": "6.2.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/debug-identity.ts

@@ -0,0 +1,11 @@
+/** Maximum UTF-16 code-unit length of one debug identity string. */
+export const MAX_DEBUG_IDENTITY_STRING = 512;
+
+/** Marker appended to a truncated debug identity string. */
+export const DEBUG_IDENTITY_TRUNCATION_MARKER = "…";
+
+/** Bound one debug identity string, including its truncation marker. */
+export function truncateDebugIdentity(value: string): string {
+  if (value.length <= MAX_DEBUG_IDENTITY_STRING) return value;
+  return `${value.slice(0, MAX_DEBUG_IDENTITY_STRING - 1)}${DEBUG_IDENTITY_TRUNCATION_MARKER}`;
+}

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

@@ -3,6 +3,11 @@
 // Kept separate from debug-registry.ts so debug-timing.ts can import the
 // registry without creating an import cycle through the barrel re-export.
 
+export {
+  DEBUG_IDENTITY_TRUNCATION_MARKER,
+  MAX_DEBUG_IDENTITY_STRING,
+  truncateDebugIdentity,
+} from "./debug-identity.ts";
 // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "6.0.1",
+  "version": "6.2.0",
   "description": "Structural AST analysis for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -30,14 +30,13 @@
     "src/**/*.mjs",
     "src/**/*.json",
     "resources",
-    "scripts/*.mjs",
     "!__tests__"
   ],
   "dependencies": {
     "jiti": "^2.7.0",
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-code-runtime": "6.0.1",
-    "@mrclrchtr/supi-core": "6.0.1"
+    "@mrclrchtr/supi-code-runtime": "6.2.0",
+    "@mrclrchtr/supi-core": "6.2.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",
@@ -45,7 +44,6 @@
     "jiti",
     "web-tree-sitter"
   ],
-  "main": "src/api.ts",
   "exports": {
     "./api": "./src/api.ts",
     "./package.json": "./package.json",

package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/kotlin/tree-sitter-kotlin.wasm.json

@@ -6,7 +6,7 @@
     "releaseAsset": "https://github.com/fwcd/tree-sitter-kotlin/releases/download/0.3.8/tree-sitter-kotlin.wasm"
   },
   "generatedWith": {
-    "treeSitterCli": "0.26.12"
+    "treeSitterCli": "0.26.13"
   },
   "sha256": "e08447e36ad5d86f39f91f13defce0636aea1490b8d65dafde6fa72649422061"
 }

package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/sql/tree-sitter-sql.wasm.json

@@ -5,7 +5,7 @@
     "repository": "https://github.com/derekstride/tree-sitter-sql"
   },
   "generatedWith": {
-    "treeSitterCli": "0.26.12"
+    "treeSitterCli": "0.26.13"
   },
   "sha256": "9b93a15dc3eade66df4347731f2687b939daf987c8382660d6118e863604ab09",
   "trust": {

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

@@ -1,4 +1,4 @@
-// Public tree-sitter session factory, shared session service access, and shared types.
+// Public Tree-sitter session factory, lifecycle controller, and shared types.
 //
 // This package is library-only — no pi extension surface.
 // Exports structured runtime/service APIs only.
@@ -7,19 +7,11 @@
 // Language detection helpers
 export {
   detectGrammar,
-  getSupportedExtension,
   getSupportedExtensions,
-  isJsTsGrammar,
-  isSupportedFile,
 } from "./language.ts";
 export type { StructuralSearchOperation } from "./operation-support.ts";
 export { getStructuralSearchSupportedExtensions } from "./operation-support.ts";
-export type {
-  TsControllerState,
-  TsStartResult,
-} from "./session/runtime-controller.ts";
 export { TreeSitterRuntimeController } from "./session/runtime-controller.ts";
-export { getSessionTreeSitterService } from "./session/service-registry.ts";
 export { createTreeSitterSession } from "./session/session.ts";
 
 // Shared types
@@ -32,8 +24,6 @@ export type {
   NodeAtResult,
   OutlineItem,
   QueryCapture,
-  SessionTreeSitterService,
-  SessionTreeSitterServiceState,
   SourceRange,
   SupportedExtension,
   TreeSitterResult,

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

@@ -81,6 +81,25 @@ export function nodeToRange(
   };
 }
 
+/** Validate that a public position exists in the source bounds. */
+export function validatePublicPositionBounds(
+  line: number,
+  character: number,
+  source: string,
+): { kind: "validation-error"; message: string } | null {
+  const lines = splitSourceLines(source);
+  if (line > lines.length) {
+    return { kind: "validation-error", message: "line is beyond end of file" };
+  }
+
+  const lineText = lines[line - 1] ?? "";
+  if (character > lineText.length + 1) {
+    return { kind: "validation-error", message: "character is beyond end of line" };
+  }
+
+  return null;
+}
+
 /** Split source into logical lines without CRLF line-ending bytes. */
 export function splitSourceLines(source: string): string[] {
   return source.replace(/\r\n?/g, "\n").split("\n");

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

@@ -12,7 +12,7 @@ import type { GrammarId, SupportedExtension } from "./types.ts";
 const sourceDir = path.dirname(fileURLToPath(import.meta.url));
 
 /** Mapping from file extension to grammar identifier. */
-const EXTENSION_GRAMMAR: Record<string, GrammarId> = {
+const EXTENSION_GRAMMAR = {
   ".js": "javascript",
   ".jsx": "javascript",
   ".mjs": "javascript",
@@ -48,17 +48,12 @@ const EXTENSION_GRAMMAR: Record<string, GrammarId> = {
   ".xhtml": "html",
   ".r": "r",
   ".sql": "sql",
-};
-
-const SUPPORTED_EXTENSIONS = new Set<string>(Object.keys(EXTENSION_GRAMMAR));
+} satisfies Record<SupportedExtension, GrammarId>;
 
-/** Check if a file extension is supported. */
-export function isSupportedFile(filePath: string): boolean {
-  return detectGrammar(filePath) !== undefined;
-}
+const SUPPORTED_EXTENSIONS = Object.keys(EXTENSION_GRAMMAR) as SupportedExtension[];
 
 /** Return all supported file extensions (with leading dot). */
-export function getSupportedExtensions(): string[] {
+export function getSupportedExtensions(): SupportedExtension[] {
   return [...SUPPORTED_EXTENSIONS];
 }
 
@@ -69,23 +64,10 @@ export function getSupportedExtensionGrammarEntries(): Array<
   return Object.entries(EXTENSION_GRAMMAR) as Array<readonly [SupportedExtension, GrammarId]>;
 }
 
-/** Get the file extension if it's supported, otherwise undefined. */
-export function getSupportedExtension(filePath: string): SupportedExtension | undefined {
-  const ext = path.extname(filePath).toLowerCase();
-  return SUPPORTED_EXTENSIONS.has(ext) ? (ext as SupportedExtension) : undefined;
-}
-
 /** Detect the grammar for a file. Returns undefined if unsupported. */
 export function detectGrammar(filePath: string): GrammarId | undefined {
   const ext = path.extname(filePath).toLowerCase();
-  return EXTENSION_GRAMMAR[ext];
-}
-
-const JS_TS_GRAMMARS: ReadonlySet<GrammarId> = new Set(["javascript", "typescript", "tsx"]);
-
-/** Returns true if the grammar is one the JS/TS extractors understand. */
-export function isJsTsGrammar(grammarId: GrammarId): boolean {
-  return JS_TS_GRAMMARS.has(grammarId);
+  return EXTENSION_GRAMMAR[ext as SupportedExtension];
 }
 
 /** Grammar WASM file names within the vendored resources directory. */

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

@@ -1,25 +1,7 @@
-import { getSupportedExtensionGrammarEntries, isJsTsGrammar } from "./language.ts";
+import { getSupportedExtensionGrammarEntries } from "./language.ts";
 import { supportsCallSitesGrammar } from "./tool/call-sites.ts";
 import type { GrammarId, SupportedExtension } from "./types.ts";
 
-const OUTLINE_GRAMMARS: ReadonlySet<GrammarId> = new Set([
-  "javascript",
-  "typescript",
-  "tsx",
-  "python",
-  "rust",
-  "go",
-  "c",
-  "cpp",
-  "java",
-  "kotlin",
-  "ruby",
-  "bash",
-  "html",
-  "r",
-  "sql",
-]);
-
 /** Structural collection operations whose language support defines an AST Scan universe. */
 const STRUCTURAL_SEARCH_OPERATIONS = ["outline", "imports", "exports", "call-sites"] as const;
 
@@ -49,10 +31,10 @@ export function supportsGrammarOperation(
     case "call-sites":
       return supportsCallSitesGrammar(grammar);
     case "outline":
-      return OUTLINE_GRAMMARS.has(grammar);
+      return true;
     case "imports":
     case "exports":
-      return isJsTsGrammar(grammar);
+      return grammar === "javascript" || grammar === "typescript" || grammar === "tsx";
     default:
       throw new TypeError(`Unsupported structural search operation: ${String(operation)}`);
   }

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

@@ -35,31 +35,27 @@ export function createTreeSitterProvider(service: TreeSitterService): Structural
     },
 
     async exports(file, control?) {
-      const result = control ? await service.exports(file, control) : await service.exports(file);
+      const result = await service.exports(file, control);
       return mapTreeSitterResult(result, mapExportRecords);
     },
 
     async outline(file, control?) {
-      const result = control ? await service.outline(file, control) : await service.outline(file);
+      const result = await service.outline(file, control);
       return mapTreeSitterResult(result, mapOutlineItems);
     },
 
     async imports(file, control?) {
-      const result = control ? await service.imports(file, control) : await service.imports(file);
+      const result = await service.imports(file, control);
       return mapTreeSitterResult(result, mapImportRecords);
     },
 
     async nodeAt(file, line, character, control?) {
-      const result = control
-        ? await service.nodeAt(file, line, character, control)
-        : await service.nodeAt(file, line, character);
+      const result = await service.nodeAt(file, line, character, control);
       return mapTreeSitterResult(result, mapNodeAtResult);
     },
 
     async callSites(file, control?) {
-      const result = control
-        ? await service.callSites(file, control)
-        : await service.callSites(file);
+      const result = await service.callSites(file, control);
       return mapTreeSitterResult(result, mapCallSites);
     },
   };

package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/runtime-controller.ts

@@ -2,16 +2,12 @@
 
 import { fileURLToPath } from "node:url";
 import type { WorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
-import type { SessionTreeSitterService, TreeSitterService, TreeSitterSession } from "../types.ts";
-import {
-  registerTreeSitterCapabilities,
-  unregisterTreeSitterCapabilities,
-} from "./runtime-registration.ts";
-import { clearSessionTreeSitterService, setSessionTreeSitterService } from "./service-registry.ts";
+import { createTreeSitterProvider } from "../provider/tree-sitter-provider.ts";
+import type { TreeSitterService, TreeSitterSession } from "../types.ts";
 import { createTreeSitterSession } from "./session.ts";
 
 /** Starting state before or after shutdown. */
-export type TsControllerState = TsControllerInitial | TsControllerReady | TsControllerUnavailable;
+type TsControllerState = TsControllerInitial | TsControllerReady | TsControllerUnavailable;
 
 interface TsControllerInitial {
   kind: "initial";
@@ -29,20 +25,20 @@ interface TsControllerUnavailable {
 }
 
 /** Result type from {@link TreeSitterRuntimeController.start}. */
-export type TsStartResult = { kind: "ready" } | { kind: "unavailable"; reason: string };
+type TsStartResult = { kind: "ready" } | { kind: "unavailable"; reason: string };
 
 /** Pi-independent lifecycle for one shared workspace Structural Worker. */
 export class TreeSitterRuntimeController {
   readonly #cwd: string;
   #state: TsControllerState = { kind: "initial" };
-  #runtime: WorkspaceRuntime | null;
+  readonly #runtime: WorkspaceRuntime;
   #pendingSession: TreeSitterSession | null = null;
   #generation = 0;
   #transition = Promise.resolve();
 
-  constructor(cwd: string, runtime?: WorkspaceRuntime) {
+  constructor(cwd: string, runtime: WorkspaceRuntime) {
     this.#cwd = cwd;
-    this.#runtime = runtime ?? null;
+    this.#runtime = runtime;
   }
 
   get cwd(): string {
@@ -53,14 +49,10 @@ export class TreeSitterRuntimeController {
     return this.#state.kind;
   }
 
-  get service(): SessionTreeSitterService | null {
+  get service(): TreeSitterService | null {
     return this.#state.kind === "ready" ? this.#state.service : null;
   }
 
-  setRuntime(runtime: WorkspaceRuntime): void {
-    this.#runtime = runtime;
-  }
-
   /** Start and validate one Structural Worker before capability publication. */
   start(): Promise<TsStartResult> {
     const generation = ++this.#generation;
@@ -95,8 +87,7 @@ export class TreeSitterRuntimeController {
       if (generation !== this.#generation || this.#pendingSession !== session) {
         return supersededStart();
       }
-      setSessionTreeSitterService(this.#cwd, session);
-      if (this.#runtime) registerTreeSitterCapabilities(this.#runtime, this.#cwd, session);
+      this.#runtime.registerStructural(this.#cwd, createTreeSitterProvider(session));
       this.#pendingSession = null;
       this.#state = { kind: "ready", session, service: session };
       return { kind: "ready" };
@@ -119,8 +110,7 @@ export class TreeSitterRuntimeController {
   }
 
   #takeOwnedSessions(): Set<TreeSitterSession> {
-    if (this.#runtime) unregisterTreeSitterCapabilities(this.#runtime, this.#cwd);
-    clearSessionTreeSitterService(this.#cwd);
+    this.#runtime.clearStructural(this.#cwd);
     const sessions = new Set<TreeSitterSession>();
     if (this.#pendingSession) sessions.add(this.#pendingSession);
     if (this.#state.kind === "ready") sessions.add(this.#state.session);

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

@@ -44,7 +44,13 @@ export function createTreeSitterService(client: StructuralWorkerClient): TreeSit
       const control = typeof depthOrOptions === "string" ? undefined : depthOrOptions?.control;
       return execute<CalleesAtResult>(
         client,
-        { operation: "calleesAt", file, line, character, depth },
+        {
+          operation: "calleesAt",
+          file,
+          line,
+          character,
+          ...(depth === undefined ? {} : { depth }),
+        },
         control,
       );
     },

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

@@ -4,8 +4,6 @@ import { Worker } from "node:worker_threads";
 import {
   type CodeRequestControl,
   CodeRequestDeadlineError,
-  isCodeRequestDeadlineError,
-  isCodeRequestInterruption,
   throwIfCodeRequestInterrupted,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { isDebugOperationId, startDebugTimer } from "@mrclrchtr/supi-core/debug";
@@ -20,6 +18,7 @@ import {
   STRUCTURAL_WORKER_PROTOCOL_VERSION,
   type StructuralWorkerOperation,
   type StructuralWorkerToParentMessage,
+  validateStructuralWorkerOperation,
   validateWorkerToParentMessage,
 } from "./structural-worker-protocol.ts";
 
@@ -122,6 +121,10 @@ export class StructuralWorkerClient {
     input: StructuralWorkerOperation,
     control?: CodeRequestControl,
   ): Promise<TreeSitterResult<T>> {
+    const validation = validateStructuralWorkerOperation(input);
+    if (validation.kind === "invalid") {
+      return { kind: "validation-error", message: validation.reason };
+    }
     throwIfCodeRequestInterrupted(control);
     if (this.#closed) return runtimeError("Structural Worker is shut down");
     if (control?.operationId !== undefined && !isDebugOperationId(control.operationId)) {
@@ -308,6 +311,9 @@ export class StructuralWorkerClient {
     const active = this.#active;
     if (!active || active.id !== message.requestId)
       return this.#protocolFailure("Unknown chunk request id");
+    if (active.finalSequence !== null) {
+      return this.#protocolFailure("Structural Worker sent a chunk after the final chunk");
+    }
     if (active.awaitingAck !== null) {
       return this.#protocolFailure("Structural Worker sent more than one unacknowledged chunk");
     }
@@ -530,9 +536,7 @@ export class StructuralWorkerClient {
     if (request.settled) return;
     request.settled = true;
     request.cleanupControl();
-    if (isCodeRequestInterruption(error, request.control) || isCodeRequestDeadlineError(error))
-      request.reject(error);
-    else request.reject(error);
+    request.reject(error);
   }
 }
 

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

@@ -1,5 +1,4 @@
 // 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";
@@ -120,6 +119,45 @@ export type StructuralProtocolValidation<T> =
   | { readonly kind: "valid"; readonly message: T }
   | { readonly kind: "invalid"; readonly reason: string };
 
+/** Validate one operation before it enters the Structural Worker mailbox. */
+export function validateStructuralWorkerOperation(
+  value: unknown,
+): StructuralProtocolValidation<StructuralWorkerOperation> {
+  if (!isRecord(value) || typeof value.operation !== "string") {
+    return invalid("Invalid structural operation");
+  }
+
+  switch (value.operation) {
+    case "canParse":
+    case "outline":
+    case "imports":
+    case "exports":
+    case "callSites":
+      return hasExactKeys(value, ["operation", "file"]) && isFileValue(value.file)
+        ? valid(value as unknown as StructuralWorkerOperation)
+        : invalid("Invalid structural operation");
+    case "query":
+      return hasExactKeys(value, ["operation", "file", "query"]) &&
+        isFileValue(value.file) &&
+        isQueryValue(value.query)
+        ? valid(value as unknown as StructuralWorkerOperation)
+        : invalid("Invalid structural operation");
+    case "nodeAt":
+      return hasExactKeys(value, ["operation", "file", "line", "character"]) &&
+        isFileValue(value.file) &&
+        isPositiveInteger(value.line) &&
+        isPositiveInteger(value.character)
+        ? valid(value as unknown as StructuralWorkerOperation)
+        : invalid("Invalid structural operation");
+    case "calleesAt":
+      return isCalleesAtOperation(value)
+        ? valid(value as unknown as StructuralWorkerOperation)
+        : invalid("Invalid structural operation");
+    default:
+      return invalid("Invalid structural operation");
+  }
+}
+
 /** Validate an untrusted request before the Structural Worker executes it. */
 export function validateStructuralWorkerRequest(
   value: unknown,
@@ -128,7 +166,7 @@ export function validateStructuralWorkerRequest(
   const required = ["kind", "version", "generation", "requestId", "input", "cancellationFlag"];
   const allowed = new Set([...required, "operationId", "deadline"]);
   if (
-    required.some((key) => !(key in value)) ||
+    required.some((key) => !Object.hasOwn(value, key)) ||
     Object.keys(value).some((key) => !allowed.has(key))
   ) {
     return invalid("Invalid structural request envelope");
@@ -138,7 +176,6 @@ export function validateStructuralWorkerRequest(
     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 &&
@@ -147,7 +184,71 @@ export function validateStructuralWorkerRequest(
   ) {
     return invalid("Invalid structural request");
   }
-  return valid(value as unknown as StructuralWorkerRequestMessage);
+  const operation = validateStructuralWorkerOperation(value.input);
+  return operation.kind === "valid"
+    ? valid(value as unknown as StructuralWorkerRequestMessage)
+    : invalid(operation.reason);
+}
+
+/** Validate an untrusted cancellation envelope before it reaches the Worker state machine. */
+export function validateStructuralWorkerCancel(
+  value: unknown,
+): StructuralProtocolValidation<StructuralWorkerCancelMessage> {
+  if (!isRecord(value)) return invalid("Structural Worker cancel must be an object");
+  if (!hasExactKeys(value, ["kind", "version", "generation", "requestId"])) {
+    return invalid("Invalid structural cancel envelope");
+  }
+  if (
+    value.kind !== "cancel" ||
+    value.version !== STRUCTURAL_WORKER_PROTOCOL_VERSION ||
+    !isPositiveInteger(value.generation) ||
+    !isRequestId(value.requestId)
+  ) {
+    return invalid("Invalid structural cancel");
+  }
+  return valid(value as unknown as StructuralWorkerCancelMessage);
+}
+
+/** Validate an untrusted chunk acknowledgement before it reaches the Worker state machine. */
+export function validateStructuralWorkerChunkAck(
+  value: unknown,
+): StructuralProtocolValidation<StructuralWorkerChunkAckMessage> {
+  if (!isRecord(value)) return invalid("Structural Worker chunk acknowledgement must be an object");
+  if (!hasExactKeys(value, ["kind", "version", "generation", "requestId", "sequence"])) {
+    return invalid("Invalid structural chunk acknowledgement envelope");
+  }
+  if (
+    value.kind !== "chunk-ack" ||
+    value.version !== STRUCTURAL_WORKER_PROTOCOL_VERSION ||
+    !isPositiveInteger(value.generation) ||
+    !isRequestId(value.requestId) ||
+    !isNonNegativeInteger(value.sequence)
+  ) {
+    return invalid("Invalid structural chunk acknowledgement");
+  }
+  return valid(value as unknown as StructuralWorkerChunkAckMessage);
+}
+
+/** Validate any untrusted message sent from the parent to the Structural Worker. */
+export function validateParentToStructuralWorkerMessage(
+  value: unknown,
+): StructuralProtocolValidation<ParentToStructuralWorkerMessage> {
+  if (!isRecord(value)) return invalid("Structural Worker parent message must be an object");
+  switch (value.kind) {
+    case "request":
+      return validateStructuralWorkerRequest(value);
+    case "cancel":
+      return validateStructuralWorkerCancel(value);
+    case "chunk-ack":
+      return validateStructuralWorkerChunkAck(value);
+    default:
+      return invalid("Unknown Structural Worker parent message kind");
+  }
+}
+
+/** Read a generation only when the parent message has a safe positive integer shape. */
+export function getStructuralWorkerMessageGeneration(value: unknown): number | undefined {
+  return isRecord(value) && isPositiveInteger(value.generation) ? value.generation : undefined;
 }
 
 /** Encode one complete structural result into fixed-size binary chunks. */
@@ -219,11 +320,6 @@ export function validateWorkerToParentMessage(
   }
 }
 
-/** 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> {
@@ -439,10 +535,39 @@ function isPositiveInteger(value: unknown): value is number {
   return Number.isSafeInteger(value) && Number(value) > 0;
 }
 
+function isNonNegativeInteger(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 isCalleesAtOperation(value: Record<string, unknown>): boolean {
+  const keysValid =
+    hasExactKeys(value, ["operation", "file", "line", "character"]) ||
+    hasExactKeys(value, ["operation", "file", "line", "character", "depth"]);
+  return (
+    keysValid &&
+    isFileValue(value.file) &&
+    isPositiveInteger(value.line) &&
+    isPositiveInteger(value.character) &&
+    (!("depth" in value) || value.depth === "direct" || value.depth === "deep")
+  );
+}
+
+function isFileValue(value: unknown): value is string {
+  return isNonBlankString(value, 16_384);
+}
+
+function isQueryValue(value: unknown): value is string {
+  return isNonBlankString(value, 10_000);
+}
+
+function isNonBlankString(value: unknown, maxLength: number): value is string {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maxLength;
+}
+
 function valid<T>(message: T): StructuralProtocolValidation<T> {
   return { kind: "valid", message };
 }