@mrclrchtr/supi-lsp 3.2.0 → 4.1.0

package/README.md

@@ -10,7 +10,7 @@
 
 Language Server Protocol runtime library for the [pi coding agent](https://github.com/earendil-works/pi).
 
-This is a **library-only** package — it has no pi extension surface and does not register public tools by itself. Public semantic code-intelligence behavior is exposed through `@mrclrchtr/supi-code-intelligence`'s `code_*` tools.
+This package is library-only. It registers no model-callable tools; `@mrclrchtr/supi-code-intelligence` owns the public `code_*` family.
 
 ## Install
 
@@ -18,90 +18,100 @@ This is a **library-only** package — it has no pi extension surface and does n
 npm install @mrclrchtr/supi-lsp
 ```
 
-## What this package provides
+## What it provides
 
-`@mrclrchtr/supi-lsp` provides the semantic substrate used by SuPi's code-intelligence stack:
+- `LspRuntimeController` for workspace lifecycle and status
+- `WorkspaceLspRuntime` for routing, readiness, semantic operations, tracked files, diagnostics, and recovery
+- explicit ready, pending, inactive, disabled, and unavailable registry states
+- a `SemanticProvider` adapter for `supi-code-runtime`
+- precise rename and code-action edit conversion
 
-- a session-scoped `SessionLspService`
-- LSP client lifecycle, transport, and workspace routing
-- diagnostics collection, stale-diagnostic recovery, and summaries
-- a shared `SemanticProvider` adapter for the workspace runtime
-- operation-aware semantic refactor planning for first-wave precise text-edit operations
+Clients, `LspManager`, and the default runtime implementation remain internal.
 
-First-wave refactor mapping in the semantic provider:
+## Runtime split
 
-- `rename_symbol` and legacy `rename` alias → `textDocument/rename`
-- `update_imports` → precise organize-imports/source actions only
-- `delete_dead_code` → precise quickfix/refactor-rewrite actions only
-- `rename_file` / `move_file` → explicit unavailable results for now
+`LspRuntimeController` owns:
 
-The historical LSP status overlay is no longer part of this package. Substrate-owned status UX now lives in `@mrclrchtr/supi-code-intelligence` as the `/supi-ci-status` command.
+- language-server detection and startup
+- shutdown
+- settings and missing-server inventory
+- publishing workspace runtime state
 
-## Startup performance
+`WorkspaceLspRuntime` owns:
 
-Language servers start automatically when a PI session opens. By default, every server with matching source files in the project is started **concurrently** — in polyglot repos or monorepos with multiple language footprints, this parallel startup can cause a significant CPU spike.
+- hover, definition, references, implementations, symbols, rename, and code actions
+- file/workspace readiness waits
+- tracked-file lifecycle and workspace change notifications
+- diagnostics, summaries, refresh, and recovery
+- project-server inventory and file support checks
 
-**To reduce startup overhead:**
+This separation keeps lifecycle/status distinct from workspace operations.
 
-- **Disable specific language servers** that you don't need. Only servers whose source files are detected in the project will be started. To explicitly exclude a language:
+## Example
 
-  ```json
-  {
-    "lsp": {
-      "servers": {
-        "python": { "enabled": false },
-        "rust": { "enabled": false }
-      }
-    }
+```ts
+import { getWorkspaceLspRuntime, toLspPosition } from "@mrclrchtr/supi-lsp/api";
+
+const state = getWorkspaceLspRuntime("/project");
+if (state.kind === "ready") {
+  const definitions = await state.runtime.definition(
+    "src/index.ts",
+    toLspPosition(6, 11),
+  );
+  if (definitions.kind === "completed") {
+    // `data: null` is a successful no-definition observation.
+    console.log(definitions.data);
   }
-  ```
+}
+```
 
-  Add this to `.pi/supi/config.json` (project) or `~/.pi/agent/supi/config.json` (global). Only the listed language servers are disabled; all others remain active.
+Runtime methods use raw 0-based LSP positions. `toLspPosition()` converts user-facing 1-based coordinates. Read-only semantic and diagnostic methods return `CodeQueryResult<T>` so completed empty protocol responses remain distinct from partial or unavailable requests. A ready runtime owner may contain only lazy routes: workspace semantic readiness requires at least one active ready client, while file readiness requires the routed client for that file to start successfully. Empty client sets and failed routes are unavailable, not vacuously ready.
 
-  > **Note:** The global `lsp.enabled` switch and `lsp.active` allowlist were removed in v0.7.0. LSP is always-on by default. Per-language `lsp.servers.<language>.enabled: false` is the only supported way to opt out. If your config still has `lsp.enabled` or `lsp.active` keys, they are ignored and a deprecation warning will appear at session start.
+## Startup performance
 
-  Server discovery walks the project tree at depth 3 (skipping `node_modules`, `.git`, `.pnpm`). Every detected language server starts in parallel via `Promise.all`.
+Detected servers start concurrently. In a polyglot workspace, disable unneeded languages in `.pi/supi/config.json` or `~/.pi/agent/supi/config.json`:
 
-## Architecture
+```json
+{
+  "lsp": {
+    "servers": {
+      "python": { "enabled": false },
+      "rust": { "enabled": false }
+    }
+  }
+}
+```
 
-`@mrclrchtr/supi-lsp` is the **semantic substrate** in SuPi's code-understanding stack.
-It depends on `@mrclrchtr/supi-core` and `@mrclrchtr/supi-code-runtime` for shared
-contracts, and provides a session-scoped LSP service that publishes semantic and
-diagnostic capabilities into the shared workspace runtime.
+The old `lsp.enabled` and `lsp.active` settings are deprecated and ignored. If every server definition is disabled, the controller publishes an explicit `disabled` runtime state instead of an empty `ready` runtime. When a ready owner has no active client yet, it stays published for lazy routing while semantic capability remains pending.
+
+## Architecture
 
 ```text
-supi-code-runtime  ← shared contracts + workspace runtime
-    ↑
-supi-lsp           ← LSP client + session-scoped service + runtime capabilities
-    ↑
-supi-code-intelligence ← public code_* tools over the semantic substrate
+supi-code-runtime       canonical contracts + capability broker
+        ↑
+supi-lsp                semantic lifecycle + Workspace LSP runtime
+        ↑
+supi-code-intelligence  Workspace session + public code_* tools
 ```
 
-## Package surfaces
-
-- `@mrclrchtr/supi-lsp/api` — reusable session-scoped LSP service and related types
-- `@mrclrchtr/supi-lsp/provider/lsp-semantic-provider` — shared `SemanticProvider` adapter
+The private `DefaultWorkspaceLspRuntime` is the single operational seam. It normalizes
+paths and coordinates readiness, semantic requests, tracked files, diagnostics, recovery,
+and owner-controlled shutdown around the package-internal manager. Clients and the manager
+remain hidden from consumers.
 
-Example:
+See [`docs/adr/0016-workspace-lsp-runtime-interface.md`](../../docs/adr/0016-workspace-lsp-runtime-interface.md).
 
-```ts
-import { getSessionLspService, toLspPosition } from "@mrclrchtr/supi-lsp/api";
-
-const state = getSessionLspService("/project");
-if (state.kind === "ready") {
-  const defs = await state.service.definition("src/index.ts", toLspPosition(6, 11));
-}
-```
+## Package exports
 
-`SessionLspService` methods use raw **0-based LSP positions**. Public `code_*` tools keep the user-facing **1-based** coordinate UX.
+- `@mrclrchtr/supi-lsp/api` — runtime/controller/config types and registry operations
+- `@mrclrchtr/supi-lsp/provider/lsp-semantic-provider` — semantic provider adapter
 
 ## Source
 
-- `src/client/` — LSP client, transport, refresh, and request handling
-- `src/config/` — server config, defaults, capabilities, and exported LSP protocol types
-- `src/diagnostics/` — stale diagnostics, suppression diagnostics, and workspace sentinels
-- `src/manager/` — manager lifecycle, routing, diagnostics, and recovery helpers
-- `src/provider/lsp-semantic-provider.ts` — shared `SemanticProvider` adapter
-- `src/session/` — service registry, runtime registration, scanner, and controller logic
-- `src/api.ts` — reusable developer-facing surface
-- `src/index.ts` — package-root re-export surface
+- `src/client/` — protocol client, transport, refresh, and requests
+- `src/config/` — server configuration and protocol types
+- `src/diagnostics/` — stale diagnostics and workspace sentinels
+- `src/manager/` — package-internal server pool and routing, diagnostic, and recovery mechanics
+- `src/provider/` — semantic and refactor adapters
+- `src/session/runtime-controller.ts` — lifecycle/status
+- `src/session/runtime-registry.ts` — `WorkspaceLspRuntime` and registry

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

@@ -8,6 +8,14 @@ This is a **library-only package** — it has no pi extension surface, no user-f
 
 - `@mrclrchtr/supi-code-runtime/api` — shared canonical types, capability interfaces, workspace runtime registry, and typed request context
 
+Read-only provider methods return `CodeQueryResult<T>`:
+
+- `completed` — collection completed; `data` may be empty or `null`
+- `partial` — usable data was collected, but one or more provider branches failed
+- `unavailable` — no result was established; includes a reason
+
+This keeps successful zero-result facts distinct from routing, transport, and provider failures.
+
 ## License
 
 MIT

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -50,7 +50,6 @@
   },
   "main": "src/api.ts",
   "exports": {
-    "./abort-utils": "./src/abort-utils.ts",
     "./api": "./src/api.ts",
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
@@ -71,7 +70,6 @@
     "./status-spinner": "./src/status-spinner.ts",
     "./terminal": "./src/terminal.ts",
     "./tool-framework": "./src/tool-framework.ts",
-    "./prompt-surface": "./src/prompt-surface.ts",
-    "./types": "./src/types.ts"
+    "./prompt-surface": "./src/prompt-surface.ts"
   }
 }

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

@@ -6,8 +6,6 @@
 // For lighter imports, use one of the domain subpaths directly
 // (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./abort-utils.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -42,5 +40,3 @@ export * from "./status-spinner.ts";
 export * from "./terminal.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./tool-framework.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./types.ts";

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/evidence-badge.ts

@@ -22,14 +22,15 @@ export interface EvidenceBadgeInput {
  * |------------------------------------------------------|---------------------------------------|
  * | shown=12, total=12, omitted=0, label="references"   | `12 references`                       |
  * | shown=8,  total=20, omitted=12, label="symbols"     | `8 of 20 symbols (12 omitted)`        |
- * | shown=5,  total=null, reason="timeout", label="matches" | `5 matches — timeout`              |
+ * | shown=5, total=null, omitted=2, reason="timeout" | `5 matches (2 collected omitted; more may exist — timeout)` |
  */
 export function formatEvidenceBadge(input: EvidenceBadgeInput): string {
   const { shownCount, totalCount, omittedCount, partialReason, label } = input;
 
   if (totalCount === null) {
     const reasonSuffix = partialReason ? ` — ${partialReason}` : "";
-    return `${shownCount} ${label}${reasonSuffix}`;
+    const omittedPrefix = (omittedCount ?? 0) > 0 ? `${omittedCount} collected omitted; ` : "";
+    return `${shownCount} ${label} (${omittedPrefix}more may exist${reasonSuffix})`;
   }
 
   if (omittedCount !== null && omittedCount > 0) {

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -6,8 +6,6 @@
 // For lighter imports, use one of the domain subpaths directly
 // (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./abort-utils.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -36,5 +34,3 @@ export * from "./status-spinner.ts";
 export * from "./terminal.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./tool-framework.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./types.ts";

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/llm.ts

@@ -24,16 +24,6 @@ export interface WithRetryOptions {
   onRetry?: (attempt: number, delayMs: number) => void;
 }
 
-/**
- * Attempt an async operation with retries and exponential backoff.
- *
- * If the signal is already aborted on entry, the operation is skipped entirely.
- * If the signal aborts during a delay, the delay is cancelled immediately.
- *
- * @param fn - The async operation to retry.
- * @param options - Optional configuration for retries, backoff, signal, and callbacks.
- * @returns The result on success, or `null` if all attempts fail or the signal aborts.
- */
 /**
  * Create a promise that resolves after `ms` milliseconds, or rejects if
  * the signal fires before the timeout elapses.

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/path-utils.ts

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 /** Strip pi's optional leading `@` file-path prefix from a tool input. */
 export function stripToolPathPrefix(target: string): string {
@@ -16,25 +17,28 @@ export function resolveToolPath(cwd: string, target: string): string {
   return path.resolve(cwd, stripToolPathPrefix(target));
 }
 
-/** Convert a file path to a file:// URI. */
+/**
+ * Convert a file path to a file:// URI.
+ *
+ * Uses Node's `pathToFileURL` to produce a standards-compliant URI with
+ * proper percent-encoding of spaces, hashes, and other special characters.
+ */
 export function fileToUri(filePath: string): string {
-  const resolved = path.resolve(filePath);
-  if (process.platform === "win32") {
-    return `file:///${resolved.replace(/\\/g, "/")}`;
-  }
-  return `file://${resolved}`;
+  return pathToFileURL(filePath).href;
 }
 
-/** Convert a file:// URI to a file path. */
+/**
+ * Convert a file:// URI to a file path.
+ *
+ * Uses Node's `fileURLToPath` for standards-compliant decoding. Non-file
+ * URIs are passed through unchanged so consumers (such as LSP diagnostic
+ * handling) remain compatible with non-file URI schemes.
+ */
 export function uriToFile(uri: string): string {
   if (!uri.startsWith("file://")) return uri;
-  let filePath = decodeURIComponent(uri.slice(7));
-  if (
-    process.platform === "win32" &&
-    filePath.startsWith("/") &&
-    /^[A-Za-z]:/.test(filePath.slice(1))
-  ) {
-    filePath = filePath.slice(1);
+  try {
+    return fileURLToPath(uri);
+  } catch {
+    return uri;
   }
-  return filePath;
 }

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-action-menu.ts

@@ -34,6 +34,7 @@ export function buildActionMenu(field: ScopedFieldValue, scope: SettingsScope):
     if (choices.length > 0) {
       for (const choice of choices) menu.push({ value: `set:${choice}`, label: choice });
     } else if (field.field.kind === "number") menu.push({ value: "edit", label: "Edit value…" });
+    else if (field.field.kind === "string") menu.push({ value: "edit", label: "Edit value…" });
     else if (field.field.kind === "stringList") menu.push({ value: "edit", label: "Edit values…" });
     else if (field.field.kind === "modelPicker")
       menu.push({ value: "edit", label: "Choose model…" });

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts

@@ -86,6 +86,11 @@ export interface NumberField extends BaseField {
   values?: string[];
 }
 
+/** One free-form string. */
+export interface StringField extends BaseField {
+  kind: "string";
+}
+
 /** Comma-separated string list. */
 export interface StringListField extends BaseField {
   kind: "stringList";
@@ -164,6 +169,7 @@ export type SettingsField =
   | BoolField
   | EnumField
   | NumberField
+  | StringField
   | StringListField
   | ModelPickerField
   | CustomField;
@@ -248,6 +254,8 @@ export function formatValue(value: unknown, field: SettingsField): string {
       return value ? "on" : "off";
     case "number":
       return String(value ?? "");
+    case "string":
+      return typeof value === "string" && value ? value : "none";
     case "stringList": {
       const arr = Array.isArray(value) ? value : [];
       return arr.length > 0 ? arr.map(String).join(", ") : "none";
@@ -271,6 +279,7 @@ export function sourceBadge(displayValue: string, source: ValueSource): string {
 
 /** Format the value used to prefill editors and compare concrete choices. */
 export function formatEditValue(value: unknown, field: SettingsField): string {
+  if (field.kind === "string") return typeof value === "string" ? value : "";
   if (field.kind === "stringList") {
     const arr = Array.isArray(value) ? value : [];
     return arr.map(String).join(", ");

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings.ts

@@ -26,6 +26,7 @@ export type {
   SettingsField,
   SettingsFieldAction,
   SettingsPersistedChange,
+  StringField,
   StringListField,
   ValueSource,
 } from "./settings/settings-schema.ts";

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "description": "SuPi code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "3.2.0"
+    "@mrclrchtr/supi-core": "4.1.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

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

@@ -15,6 +15,14 @@ export type {
   StructuralProvider,
   StructuralResult,
 } from "./capability/types.ts";
+export type { CodeQueryResult } from "./query-result.ts";
+// Shared query-result constructors and contract
+export {
+  completedCodeQuery,
+  mapCodeQueryResult,
+  partialCodeQuery,
+  unavailableCodeQuery,
+} from "./query-result.ts";
 // Shared canonical types
 export type {
   CalleeDepth,
@@ -25,7 +33,9 @@ export type {
   CodeResult,
   CodeSymbol,
   ConfidenceMode,
+  DeclarationNesting,
   DisambiguationCandidate,
+  DocumentCodeSymbol,
   ExportData,
   FileEdit,
   ImportData,
@@ -37,7 +47,6 @@ export type {
   SourceRange,
   WorkspaceEdit,
 } from "./types.ts";
-export { normalizeRefactorOperation } from "./types.ts";
 export type { WorkspaceContext } from "./workspace/context.ts";
 // Workspace context
 export { createWorkspaceContext } from "./workspace/context.ts";

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

@@ -4,6 +4,7 @@
  * tree-sitter) advertise what they can do.
  */
 
+import type { CodeQueryResult } from "../query-result.ts";
 import type {
   CalleeDepth,
   CalleesData,
@@ -12,6 +13,7 @@ import type {
   CodePosition,
   CodeResult,
   CodeSymbol,
+  DocumentCodeSymbol,
   ExportData,
   ImportData,
   NodeAtData,
@@ -44,32 +46,30 @@ export type CapabilityState =
 /**
  * Semantic analysis capability backed by a language server (LSP).
  *
- * Methods return `null` to signal absence (unavailable / inactive) and
- * an array to signal a successful query (possibly empty).
+ * Every read query preserves whether collection completed, completed only
+ * partially, or was unavailable. Successful empty arrays and protocol-level
+ * null values are completed observations rather than capability failures.
  */
 export interface SemanticProvider {
-  references(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
-  implementation(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
-  documentSymbols(filePath: string): Promise<CodeSymbol[] | null>;
-  workspaceSymbols(query: string): Promise<CodeSymbol[] | null>;
+  references(filePath: string, position: CodePosition): Promise<CodeQueryResult<CodeLocation[]>>;
+  implementation(
+    filePath: string,
+    position: CodePosition,
+  ): Promise<CodeQueryResult<CodeLocation[]>>;
+  documentSymbols(filePath: string): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
+  workspaceSymbols(query: string): Promise<CodeQueryResult<CodeSymbol[]>>;
 
-  /**
-   * Optional definition capability. Returns the definition location(s) for
-   * the symbol at the given position. When the provider cannot produce
-   * definition info, returns `null`.
-   */
-  definition?(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
+  /** Optional definition capability with explicit completed-empty semantics. */
+  definition?(filePath: string, position: CodePosition): Promise<CodeQueryResult<CodeLocation[]>>;
 
   /**
-   * Optional hover capability. Returns a simplified type/signature info
-   * shape that does not depend on vscode-languageserver-types. When the
-   * provider cannot produce hover info (unavailable, unsupported file,
-   * no result at the given position), returns `null`.
+   * Optional hover capability. A completed `null` data value means the
+   * provider successfully found no hover at the requested point.
    */
   hover?(
     filePath: string,
     position: CodePosition,
-  ): Promise<{ contents: string; range?: SourceRange } | null>;
+  ): Promise<CodeQueryResult<{ contents: string; range?: SourceRange } | null>>;
 
   /**
    * Optional operation-aware refactor capability.
@@ -85,8 +85,8 @@ export interface SemanticProvider {
    * Optional rename capability. When present, the provider supports
    * precise semantic symbol-rename operations.
    *
-   * Kept as a low-level substrate helper for compatibility while the public
-   * tool surface still exposes a legacy `rename` alias.
+   * 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>;
 
@@ -97,16 +97,6 @@ export interface SemanticProvider {
    * Kept as a low-level substrate helper and for lightweight introspection.
    */
   codeActions?(file: string, position: CodePosition): Promise<RefactorResult[]>;
-
-  /**
-   * Optional lightweight code action titles for display purposes.
-   * Returns simplified title/kind pairs at the given position.
-   * When the provider cannot produce code actions, returns `null`.
-   */
-  codeActionTitles?(
-    file: string,
-    position: CodePosition,
-  ): Promise<Array<{ title: string; kind?: string }> | null>;
 }
 
 /**

package/node_modules/@mrclrchtr/supi-code-runtime/src/index.ts

@@ -12,9 +12,12 @@ export type {
   CapabilityState,
   CodeLocation,
   CodePosition,
+  CodeQueryResult,
   CodeResult,
   CodeSymbol,
   ConfidenceMode,
+  DeclarationNesting,
+  DocumentCodeSymbol,
   ExportData,
   ImportData,
   NodeAtData,
@@ -29,8 +32,11 @@ export type {
   WorkspaceContext,
 } from "./api.ts";
 export {
+  completedCodeQuery,
   createWorkspaceContext,
   getDefaultWorkspaceRuntime,
-  normalizeRefactorOperation,
+  mapCodeQueryResult,
+  partialCodeQuery,
+  unavailableCodeQuery,
   WorkspaceRuntime,
 } from "./api.ts";

package/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts

@@ -0,0 +1,42 @@
+/**
+ * Result of a read-only code-provider query.
+ *
+ * `completed` includes successful empty observations, such as an empty
+ * reference list or a protocol-level null hover. `partial` preserves usable
+ * data when a multi-provider query could not complete every branch.
+ * `unavailable` means the query did not establish a result.
+ */
+export type CodeQueryResult<T> =
+  | { readonly kind: "completed"; readonly data: T }
+  | { readonly kind: "partial"; readonly data: T; readonly reason: string }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+/** Construct a successfully completed code-query result, including empty data. */
+export function completedCodeQuery<T>(data: T): CodeQueryResult<T> {
+  return { kind: "completed", data };
+}
+
+/** Construct a usable but incomplete code-query result. */
+export function partialCodeQuery<T>(data: T, reason: string): CodeQueryResult<T> {
+  return { kind: "partial", data, reason };
+}
+
+/** Construct a code-query result that could not be established. */
+export function unavailableCodeQuery<T = never>(reason: string): CodeQueryResult<T> {
+  return { kind: "unavailable", reason };
+}
+
+/** Map completed or partial query data while preserving its availability state. */
+export function mapCodeQueryResult<T, U>(
+  result: CodeQueryResult<T>,
+  map: (data: T) => U,
+): CodeQueryResult<U> {
+  switch (result.kind) {
+    case "completed":
+      return completedCodeQuery(map(result.data));
+    case "partial":
+      return partialCodeQuery(map(result.data), result.reason);
+    case "unavailable":
+      return unavailableCodeQuery(result.reason);
+  }
+}