@sackville-mcp/lsp 0.0.1-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,1247 @@
+import { MessageConnection } from "vscode-jsonrpc/node.js";
+
+//#region src/encoding.d.ts
+/**
+ * Position-encoding conversion — the single highest-correctness-risk corner of the LSP
+ * bridge (ADR 0011), and the reason this is the first slice. An LSP `Position.character`
+ * is a 0-based offset measured in **code units of the negotiated encoding**, NOT a column.
+ * JS strings are UTF-16, so a naive `col - 1` passes every ASCII test and then silently
+ * points at the WRONG symbol the moment a line contains a non-BMP character (emoji, CJK,
+ * combining marks) under a server that negotiated UTF-8. That is the worst failure for an
+ * agent tool — plausible, wrong, and silent — so the conversion is a pure, separately
+ * unit-tested function exercised against non-BMP fixtures here, before any server exists.
+ *
+ * Human columns are 1-based and count **Unicode code points** (what a person counts);
+ * LSP characters are 0-based code-unit offsets in the negotiated encoding.
+ */
+type PositionEncoding = 'utf-8' | 'utf-16' | 'utf-32';
+/**
+ * The encodings we advertise to the server, in preference order. UTF-16 is first
+ * deliberately: it is the JS-native, best-tested path (a server honouring our preference
+ * picks the one we exercise most). We still implement all three for servers that only
+ * speak UTF-8 (e.g. clangd).
+ */
+declare const PREFERRED_ENCODINGS: readonly PositionEncoding[];
+/**
+ * Resolve the encoding to use from the server's reported `positionEncoding`. Absent ⇒ the
+ * spec default, UTF-16. **Present but unsupported ⇒ throw** — never silently default, or
+ * we would do offset math in the wrong unit and return wrong locations.
+ */
+declare function resolvePositionEncoding(reported: string | undefined): PositionEncoding;
+/**
+ * Convert a 1-based human column (counting code points) on `lineText` to a 0-based LSP
+ * `character` offset in `encoding`. A column past the line end clamps to the line length.
+ */
+declare function toLspCharacter(lineText: string, humanColumn: number, encoding: PositionEncoding): number;
+/**
+ * Inverse of {@link toLspCharacter}: map a 0-based LSP `character` offset back to a 1-based
+ * human code-point column. An offset landing inside a multi-unit code point clamps to that
+ * code point's start; an offset past the line end clamps to one past the last column.
+ */
+declare function fromLspCharacter(lineText: string, lspCharacter: number, encoding: PositionEncoding): number;
+interface LspPositionParts {
+  line: number;
+  character: number;
+}
+/**
+ * Convert a human 1-based line:column over the full source `text` to a 0-based LSP
+ * `Position` in `encoding`. Lines are split on LF/CR/CRLF WITHOUT normalizing the document
+ * (the text we send the server is its source of truth); a leading BOM is stripped before
+ * line-1 column math.
+ */
+declare function toLspPosition(text: string, humanLine: number, humanColumn: number, encoding: PositionEncoding): LspPositionParts;
+interface HumanPosition {
+  line: number;
+  column: number;
+}
+/** Inverse of {@link toLspPosition}: map an LSP `Position` back to human 1-based line:column. */
+declare function fromLspPosition(text: string, position: LspPositionParts, encoding: PositionEncoding): HumanPosition;
+//#endregion
+//#region src/normalize.d.ts
+/**
+ * Pure LSP-result normalizers (ADR 0011, slice 1). LSP responses are polymorphic in ways
+ * that silently corrupt an agent-facing tool if mishandled — these reducers collapse each
+ * shape to one Sackville form, with no I/O. The traps the adversarial pass flagged:
+ *
+ * - **`Location` vs `LocationLink`.** definition/typeDefinition return
+ *   `Location | Location[] | LocationLink[] | null`; `LocationLink` uses `targetUri` /
+ *   `targetSelectionRange` — DIFFERENT field names than `Location`'s `uri`/`range`. Reading
+ *   `.uri`/`.range` off a link yields `undefined` → silently empty navigation.
+ * - **`DocumentSymbol` vs `SymbolInformation`.** documentSymbol returns hierarchical
+ *   `DocumentSymbol[]` (has `children`/`selectionRange`) OR flat `SymbolInformation[]` (has
+ *   `location`) — two incompatible shapes under one method.
+ * - **Hover contents** can be `MarkupContent | MarkedString | MarkedString[]`.
+ *
+ * Ranges are kept in LSP 0-based form here; mapping them back to human 1-based line:column
+ * needs the file text + the negotiated encoding and lives in `encoding.ts`
+ * (`fromLspPosition`), applied at the surface.
+ */
+interface LspPosition {
+  line: number;
+  character: number;
+}
+interface LspRange {
+  start: LspPosition;
+  end: LspPosition;
+}
+interface Location {
+  uri: string;
+  range: LspRange;
+}
+interface LocationLink {
+  targetUri: string;
+  targetRange: LspRange;
+  targetSelectionRange: LspRange;
+  originSelectionRange?: LspRange;
+}
+interface NormalizedLocation {
+  uri: string;
+  /** The precise symbol range (LocationLink.targetSelectionRange, or Location.range). */
+  range: LspRange;
+  /** The full enclosing range, when the server sent a LocationLink. */
+  fullRange?: LspRange;
+}
+/** Normalize any definition/references/typeDefinition result shape to a flat location list. */
+declare function normalizeLocations(result: Location | Location[] | LocationLink[] | null | undefined): NormalizedLocation[];
+type MarkedString = string | {
+  language: string;
+  value: string;
+};
+interface MarkupContent {
+  kind: 'plaintext' | 'markdown';
+  value: string;
+}
+interface Hover {
+  contents: MarkupContent | MarkedString | MarkedString[];
+  range?: LspRange;
+}
+interface NormalizedHover {
+  value: string;
+  range?: LspRange;
+}
+/** Normalize hover contents (MarkupContent | MarkedString | MarkedString[]) to one string. */
+declare function normalizeHover(hover: Hover | null | undefined): NormalizedHover | null;
+declare function symbolKindName(kind: number): string;
+interface DocumentSymbol {
+  name: string;
+  kind: number;
+  detail?: string;
+  range: LspRange;
+  selectionRange: LspRange;
+  children?: DocumentSymbol[];
+}
+interface SymbolInformation {
+  name: string;
+  kind: number;
+  location: Location;
+  containerName?: string;
+}
+interface NormalizedSymbol {
+  name: string;
+  kind: number;
+  kindName: string;
+  detail?: string;
+  range: LspRange;
+  children?: NormalizedSymbol[];
+  /** Set only for flat SymbolInformation results. */
+  container?: string;
+}
+/** Normalize documentSymbol's dual shape (hierarchical DocumentSymbol[] or flat SymbolInformation[]). */
+declare function normalizeDocumentSymbols(result: DocumentSymbol[] | SymbolInformation[] | null | undefined): NormalizedSymbol[];
+/**
+ * A raw `workspace/symbol` result member. Two shapes under one method (LSP 3.17):
+ * - `SymbolInformation`: `location` is a full `Location` (`{uri, range}`).
+ * - `WorkspaceSymbol`: `location` may be a full `Location` OR a uri-only `{uri}` — the server
+ *   defers the range to a `workspaceSymbol/resolve` round-trip. Reading `.location.range` off
+ *   the uri-only form yields `undefined`; we surface the uri and omit the range (v1 does not
+ *   resolve — see fixtures README; the real `typescript-language-server` 5.3.0 sends the full
+ *   `Location` form).
+ */
+interface WorkspaceSymbol {
+  name: string;
+  kind: number;
+  containerName?: string;
+  location: Location | {
+    uri: string;
+  };
+}
+interface NormalizedWorkspaceSymbol {
+  name: string;
+  kind: number;
+  kindName: string;
+  uri: string;
+  /** Absent when the server returned a uri-only `WorkspaceSymbol` (no range without resolve). */
+  range?: LspRange;
+  /** The declaring container (class/namespace), when the server reported one. */
+  container?: string;
+}
+/** Normalize a `workspace/symbol` result (flat `SymbolInformation[]`/`WorkspaceSymbol[]`). */
+declare function normalizeWorkspaceSymbols(result: WorkspaceSymbol[] | null | undefined): NormalizedWorkspaceSymbol[];
+declare function diagnosticSeverityName(severity: number): string;
+/** A raw LSP `Diagnostic` (the member of a `publishDiagnostics` notification's `diagnostics`). */
+interface Diagnostic {
+  range: LspRange;
+  message: string;
+  severity?: number;
+  code?: number | string;
+  source?: string;
+  tags?: number[];
+  relatedInformation?: {
+    location: Location;
+    message: string;
+  }[];
+}
+interface NormalizedRelatedInfo {
+  uri: string;
+  /** LSP 0-based range (mapped to human coords against its own file at the surface). */
+  range: LspRange;
+  message: string;
+}
+interface NormalizedDiagnostic {
+  /** LSP 0-based range (mapped to human coords in the queried file at the surface). */
+  range: LspRange;
+  message: string;
+  severity?: number;
+  /** `Error`/`Warning`/`Information`/`Hint`, when the server set a severity. */
+  severityName?: string;
+  code?: number | string;
+  source?: string;
+  /** `Unnecessary`/`Deprecated`, only when non-empty. */
+  tags?: string[];
+  related?: NormalizedRelatedInfo[];
+}
+/** Normalize a `publishDiagnostics` `diagnostics[]` (push model) — severity/tag names, related info. */
+declare function normalizeDiagnostics(items: Diagnostic[] | null | undefined): NormalizedDiagnostic[];
+/** A raw `CallHierarchyItem` (prepareCallHierarchy result + the node inside incoming/outgoing). */
+interface CallHierarchyItem {
+  name: string;
+  kind: number;
+  detail?: string;
+  uri: string;
+  range: LspRange;
+  selectionRange: LspRange;
+}
+interface NormalizedCallItem {
+  name: string;
+  kind: number;
+  kindName: string;
+  detail?: string;
+  uri: string;
+  range: LspRange;
+  selectionRange: LspRange;
+}
+/** One edge of the call hierarchy: the other item + the ranges where the call occurs. */
+interface NormalizedCall {
+  item: NormalizedCallItem;
+  fromRanges: LspRange[];
+}
+declare function normalizeCallHierarchyItem(item: CallHierarchyItem): NormalizedCallItem;
+declare function normalizeCallHierarchyItems(result: CallHierarchyItem[] | null | undefined): NormalizedCallItem[];
+/** `callHierarchy/incomingCalls` → `{from, fromRanges}[]`; the edge item is the CALLER. */
+declare function normalizeIncomingCalls(result: {
+  from: CallHierarchyItem;
+  fromRanges: LspRange[];
+}[] | null | undefined): NormalizedCall[];
+/** `callHierarchy/outgoingCalls` → `{to, fromRanges}[]`; the edge item is the CALLEE. */
+declare function normalizeOutgoingCalls(result: {
+  to: CallHierarchyItem;
+  fromRanges: LspRange[];
+}[] | null | undefined): NormalizedCall[];
+/**
+ * The tri-state query outcome (ADR 0011): an empty result is only authoritatively
+ * `no_result` when the server is READY; while it is still indexing an empty result is
+ * `not_ready` and must never be collapsed into "no definition" (an agent would act on the
+ * lie). Readiness is decided by the client (slice 2); this is the pure combinator.
+ */
+type QueryStatus = 'ok' | 'not_ready' | 'no_result';
+declare function decideStatus(isEmpty: boolean, ready: boolean): QueryStatus;
+/** A raw LSP `TextEdit` (or `AnnotatedTextEdit`, which adds `annotationId`). */
+interface RawTextEdit {
+  range: LspRange;
+  newText: string;
+  annotationId?: string;
+}
+/** A raw `TextDocumentEdit` documentChanges member: a versioned doc + its edits. */
+interface RawTextDocumentEdit {
+  textDocument: {
+    uri: string;
+    version?: number | null;
+  };
+  edits: RawTextEdit[];
+}
+/** Resource-operation options (LSP `CreateFileOptions`/`RenameFileOptions`/`DeleteFileOptions`). */
+interface ResourceOpOptions {
+  overwrite?: boolean;
+  ignoreIfExists?: boolean;
+  ignoreIfNotExists?: boolean;
+  recursive?: boolean;
+}
+/** A raw file-resource operation documentChanges member (CreateFile/RenameFile/DeleteFile). */
+interface RawResourceOperation {
+  kind: 'create' | 'rename' | 'delete';
+  uri?: string;
+  oldUri?: string;
+  newUri?: string;
+  options?: ResourceOpOptions;
+}
+interface RawWorkspaceEdit {
+  changes?: Record<string, RawTextEdit[]>;
+  documentChanges?: (RawTextDocumentEdit | RawResourceOperation)[];
+  changeAnnotations?: Record<string, {
+    label?: string;
+    needsConfirmation?: boolean;
+  }>;
+}
+/** One edit on a file, range kept in LSP 0-based form (mapped to human coords at the surface). */
+interface NormalizedFileEdit {
+  range: LspRange;
+  newText: string;
+  /** A `needsConfirmation` change annotation rode this edit — preview-only, excluded from apply. */
+  needsConfirmation?: boolean;
+  /** The change-annotation label, when one was attached. */
+  annotationLabel?: string;
+}
+interface NormalizedFileEdits {
+  uri: string;
+  edits: NormalizedFileEdit[];
+}
+/** A flagged resource operation — surfaced in the preview (paths relativized at the surface). */
+interface NormalizedResourceOp {
+  kind: 'create' | 'rename' | 'delete';
+  uris: string[];
+}
+/**
+ * One operation in `documentChanges` ORDER (the apply engine executes these in sequence — a
+ * "Move to file" is `create`→`edit`(new)→`delete`(old), so order is load-bearing). `files`/
+ * `resourceOps` are the order-free buckets kept for preview/back-compat.
+ */
+type NormalizedOp = {
+  type: 'edit';
+  uri: string;
+  edits: NormalizedFileEdit[];
+} | {
+  type: 'create';
+  uri: string;
+  options?: ResourceOpOptions;
+} | {
+  type: 'rename';
+  oldUri: string;
+  newUri: string;
+  options?: ResourceOpOptions;
+} | {
+  type: 'delete';
+  uri: string;
+  options?: ResourceOpOptions;
+};
+interface NormalizedWorkspaceEdit {
+  files: NormalizedFileEdits[];
+  resourceOps: NormalizedResourceOp[];
+  /** The operations in `documentChanges` order (the apply engine's authority). */
+  operations: NormalizedOp[];
+}
+/**
+ * Normalize a `WorkspaceEdit` to a uniform `files → edits` list plus a separate, flagged list of
+ * resource operations. Handles both shapes (ADR 0011 addendum §2.5):
+ * - `documentChanges` takes PRECEDENCE over `changes` when both are present (never merged).
+ * - Per-file and per-edit order is preserved.
+ * - `CreateFile`/`RenameFile`/`DeleteFile` members are surfaced under `resourceOps`, never
+ *   translated into a TextEdit (v1 refuses to apply them).
+ * - An `AnnotatedTextEdit` is normalized to `{range,newText}`; if its annotation is
+ *   `needsConfirmation` the edit carries `needsConfirmation: true` + the label (a preview-only
+ *   signal, excluded from apply) so the server's safety signal is never silently dropped.
+ *
+ * NOTE: real `typescript-language-server` 5.3.0 returns the legacy `changes` map for an ordinary
+ * rename even when the client advertises `documentChanges` (see `test/fixtures/README.md`); the
+ * `documentChanges` branch is exercised by a synthesized fixture.
+ */
+declare function normalizeWorkspaceEdit(raw: RawWorkspaceEdit | null | undefined): NormalizedWorkspaceEdit;
+/** `textDocument/prepareRename` raw result variants. */
+type RawPrepareRename = LspRange | {
+  range: LspRange;
+  placeholder?: string;
+} | {
+  defaultBehavior: boolean;
+};
+/** Normalized prepareRename outcome — a non-null value means the position IS renameable. */
+interface PrepareRenameOutcome {
+  /** The renameable token range, when the server provided one. */
+  range?: LspRange;
+  /** A suggested placeholder (the existing identifier), when provided. */
+  placeholder?: string;
+  /** The server signalled default behavior (renameable; it derives the range itself). */
+  defaultBehavior?: boolean;
+}
+/**
+ * Normalize a `prepareRename` result. `null` ⇒ the position is NOT renameable (the engine maps
+ * this to a structured refusal, distinct from a tri-state `no_result`). A bare `Range`,
+ * `{range, placeholder}`, and `{defaultBehavior}` all mean renameable — the real
+ * `typescript-language-server` 5.3.0 returns a bare `Range` (see `test/fixtures/README.md`).
+ */
+declare function normalizePrepareRename(raw: RawPrepareRename | null | undefined): PrepareRenameOutcome | null;
+//#endregion
+//#region src/client.d.ts
+/** An operator-registry server entry: the binary + argv to spawn (structurally separate). */
+interface ServerSpec {
+  command: string;
+  args: string[];
+  initializationOptions?: unknown;
+}
+/** An established connection to a language server, plus how to tear the process down. */
+interface LspConnection {
+  connection: MessageConnection;
+  /** Hard teardown (SIGKILL + stream close) — last resort after graceful `shutdown`. */
+  dispose(): void;
+}
+/** Injected spawn seam — the only place a real process is created (tests inject a fake peer). */
+type ServerSpawn = (spec: ServerSpec) => LspConnection;
+/** Default live spawn: a child process over stdio, framed by the reference transport. */
+declare const defaultServerSpawn: ServerSpawn;
+interface LspClientOptions {
+  /** OPERATOR per-request wall-clock cap (ms) — the single authoritative deadline. */
+  timeoutMs: number;
+  /** Single-attempt mode: no retry/backoff (the gate's deterministic default). */
+  noRetry?: boolean;
+  /** Injected clock. Default `Date.now`. */
+  now?: () => number;
+  /** Injected cancellable delay. Default a `setTimeout` promise (the one seam that may). */
+  delay?: (ms: number) => Promise<void>;
+  /** Base backoff (ms) for the empty-result retry. Default 50. */
+  baseBackoffMs?: number;
+  /** Max backoff (ms). Default 1000. */
+  maxBackoffMs?: number;
+}
+/** Server provenance from `initialize` — `serverInfo`, optional per the protocol. */
+interface ServerInfo {
+  name: string;
+  version?: string;
+}
+/** A call-hierarchy group: one prepared source item + the calls in the requested direction. */
+interface CallHierarchyGroup {
+  source: NormalizedCallItem;
+  calls: NormalizedCall[];
+}
+type CallDirection = 'incoming' | 'outgoing';
+/** A navigation result with its tri-state status and version/encoding provenance. */
+interface NavResult<T> {
+  status: QueryStatus;
+  result: T;
+  serverInfo?: ServerInfo;
+  encoding: PositionEncoding;
+}
+interface InitializeSummary {
+  encoding: PositionEncoding;
+  serverInfo?: ServerInfo;
+  capabilities: ServerCapabilities;
+}
+/** The subset of `ServerCapabilities` this slice reads (any non-`false`/non-absent ⇒ enabled). */
+type ServerCapabilities = Record<string, unknown>;
+/** Thrown when a navigation is requested against a capability the server did not advertise. */
+declare class LspUnsupportedError extends Error {
+  constructor(message: string);
+}
+declare class LspClient {
+  private readonly conn;
+  private readonly timeoutMs;
+  private readonly noRetry;
+  private readonly now;
+  private readonly delay;
+  private readonly baseBackoffMs;
+  private readonly maxBackoffMs;
+  private listening;
+  private _encoding;
+  private _serverInfo;
+  private _capabilities;
+  /** Active indexing work-done-progress tokens — non-empty ⇒ the server is still indexing. */
+  private readonly activeProgress;
+  /** Resolvers waiting for indexing to DRAIN (the active set to empty); fired on the final `end`. */
+  private readonly drainWaiters;
+  /**
+   * Open documents (open-once, no `didClose` by default). `version` is the per-uri monotonic
+   * document version: seeded at 1 by `didOpen`, pre-incremented by each `applyEdited` `didChange`
+   * — versions MUST strictly increase or the server ignores the change and keeps stale text.
+   */
+  private readonly open;
+  /**
+   * Pushed diagnostics per uri (the PUSH model — `textDocument/publishDiagnostics` is a server
+   * notification, not a request; tsserver advertises no `diagnosticProvider`, so pull diagnostics
+   * are unavailable). An entry's absence ⇒ the server hasn't published for that uri yet.
+   */
+  private readonly diagnostics;
+  /** Uris freshly `didOpen`ed whose first post-open publish hasn't arrived yet. */
+  private readonly awaitingDiagnostics;
+  /** Resolvers waiting for the NEXT publish on a uri (keyed); fired by the publish handler. */
+  private readonly diagnosticsWaiters;
+  constructor(connection: MessageConnection, options: LspClientOptions);
+  get encoding(): PositionEncoding;
+  get serverInfo(): ServerInfo | undefined;
+  get capabilities(): ServerCapabilities;
+  /** Indexing is active when at least one `$/progress` work-done token is open. */
+  get indexing(): boolean;
+  /** Any non-`false`, non-absent `*Provider` value counts as enabled (LSP convention). */
+  supports(provider: string): boolean;
+  /**
+   * `prepareRename` is advertised only by the OBJECT form `renameProvider: {prepareProvider:true}`
+   * — the boolean `supports()` helper cannot detect it, so the engine must check this before
+   * calling `prepareRename` (bare `renameProvider: true` supports rename but not prepare).
+   */
+  get supportsPrepareRename(): boolean;
+  /**
+   * Whether the server accepts `workspace/didChangeWorkspaceFolders` — the gate for the manager's
+   * grow-only warm-server reuse. Advertised by `ServerCapabilities.workspace.workspaceFolders`:
+   * `supported !== false` AND `changeNotifications` truthy (the spec allows `true` OR a string
+   * registration id). rust-analyzer advertises it; the captured tsserver 5.3.0 does NOT, so the
+   * manager falls back to spawning a fresh per-group server there.
+   */
+  get supportsWorkspaceFolderChange(): boolean;
+  /**
+   * Handshake. Registers the deadlock-safe inbound handlers + the `$/progress` listener
+   * BEFORE `listen()`, advertises the preferred encodings, then reads back the negotiated
+   * encoding + capabilities + provenance and sends `initialized`.
+   */
+  initialize(rootUri: string, opts?: {
+    initializationOptions?: unknown; /** Multi-root workspace folders. Defaults to the single `[{rootUri, 'root'}]` (ADR 0011 tail). */
+    workspaceFolders?: {
+      uri: string;
+      name: string;
+    }[];
+  }): Promise<InitializeSummary>;
+  /** Register the id-bearing inbound replies (deadlock-safe) + the `$/progress` tracker. */
+  private installInboundHandlers;
+  /** A promise that resolves the next time indexing drains to empty (an `end` clears the set). */
+  private indexingDrain;
+  /**
+   * Wait until the server is NOT indexing, bounded by `deadline`. Returns true if it settled,
+   * false if the deadline elapsed while still indexing. Event-driven (resolves on the `$/progress`
+   * `end`), with the injected `delay` as the deadline backstop — so the gate drives it
+   * deterministically and a real session blocks no longer than the operator timeout.
+   */
+  private awaitIndexingSettled;
+  /** Open a document full-text once (version 1); subsequent calls just bump the refcount. */
+  ensureOpen(uri: string, languageId: string, text: string): void;
+  /** Decrement a document's refcount (keeps the entry + version). Does NOT `didClose`. */
+  releaseDoc(uri: string): void;
+  /**
+   * After Sackville writes `newText` to `uri` on disk (write-mode, ADR 0011 addendum), resync the
+   * server's in-memory buffer with a **full-text `didChange`** so a later navigation sees
+   * post-rename positions (we never `didClose`, so the server still holds the pre-rename text).
+   * The version is **pre-incremented** — it must be strictly greater than the last `didOpen`/
+   * `didChange` or the server ignores the change. No-op for a uri the server never opened (it
+   * re-reads fresh on the next `didOpen`). Full-text (no incremental ranges) — correctness over
+   * bytes, and it avoids re-introducing offset math on the server-bound path.
+   */
+  applyEdited(uri: string, newText: string): void;
+  /**
+   * A file moved on disk (resource-op `RenameFile`). The open-once/no-`didClose` invariant keys the
+   * server buffer by `oldUri`, which now names a non-existent path — a later query would be silently
+   * wrong (the worst failure class). MIGRATE the open entry: `didClose(oldUri)` + `didOpen(newUri)`
+   * with the moved text, carrying the refcount and the languageId to the new key. NO-OP if `oldUri`
+   * was never opened (Sackville opens only the queried file, so the renamed file is usually closed).
+   * Run inside the held multi-URI lock so no concurrent query races the key migration.
+   */
+  didFileRename(oldUri: string, newUri: string, newText: string): void;
+  /**
+   * A file was deleted on disk (resource-op `DeleteFile`). `didClose` + evict the open entry so the
+   * server stops tracking a buffer for a path that no longer exists. NO-OP if it was never opened.
+   */
+  didFileDelete(uri: string): void;
+  /**
+   * Notify the server that the workspace-folder set changed (`workspace/didChangeWorkspaceFolders`)
+   * — the wire primitive behind the manager's grow-only warm-server reuse. A fire-and-forget
+   * notification, so it is ordered on the single connection BEFORE any subsequent request: a query
+   * sent right after sees the new folder scope. Capability gating is the caller's job (the manager
+   * only calls this when {@link supportsWorkspaceFolderChange}); the folders are operator-allowlisted
+   * roots, never agent-supplied paths.
+   */
+  changeWorkspaceFolders(added: {
+    uri: string;
+    name: string;
+  }[], removed: {
+    uri: string;
+    name: string;
+  }[]): void;
+  definition(uri: string, position: {
+    line: number;
+    character: number;
+  }): Promise<NavResult<NormalizedLocation[]>>;
+  typeDefinition(uri: string, position: {
+    line: number;
+    character: number;
+  }): Promise<NavResult<NormalizedLocation[]>>;
+  references(uri: string, position: {
+    line: number;
+    character: number;
+  }): Promise<NavResult<NormalizedLocation[]>>;
+  hover(uri: string, position: {
+    line: number;
+    character: number;
+  }): Promise<NavResult<NormalizedHover | null>>;
+  /** Document symbols — the file outline. Position-less (whole document); tri-state like the rest. */
+  documentSymbols(uri: string): Promise<NavResult<NormalizedSymbol[]>>;
+  /** A promise that resolves on the next `publishDiagnostics` for `uri`. */
+  private nextDiagnostics;
+  /**
+   * Diagnostics for an OPEN document (ADR 0011 staged tail; PUSH model). NOT capability-gated —
+   * `textDocument/publishDiagnostics` is a server notification every server may send, and tsserver
+   * advertises no `diagnosticProvider` (pull diagnostics are staged). The caller (manager.run) has
+   * already `didOpen`ed the file, which triggers the server's publish.
+   *
+   * Readiness (grounded in the captured timeline — `didOpen` → `$/progress` begin/end → publish
+   * ~60ms AFTER the project loads): wait out the project-load `$/progress`, then return the publish
+   * once the file's first post-open publish has arrived. An EMPTY publish is a legitimate `ok` (a
+   * clean file), never `no_result`. If the project never settles or no publish arrives within the
+   * deadline ⇒ `not_ready` (retry), the same honest-tri-state posture as the navigation reads.
+   */
+  documentDiagnostics(uri: string): Promise<NavResult<NormalizedDiagnostic[]>>;
+  /** PUSH model — accumulate the server's `publishDiagnostics` for an open file (see {@link documentDiagnostics}). */
+  private pushDiagnostics;
+  /**
+   * PULL model — `textDocument/diagnostic` (LSP 3.17), capability-gated on `diagnosticProvider`.
+   * A request/response (unlike push), so it is deterministic for a single-shot read. Echoes the
+   * provider's `identifier` when one was advertised (rust-analyzer requires it). Tri-state, with
+   * the diagnostics-specific twist that an EMPTY report is a legitimate `ok` (a clean file), NEVER
+   * `no_result` — so this does NOT reuse {@link withRetry} (whose empty ⇒ no_result is wrong here).
+   * Readiness: wait out the project-load `$/progress`; if the send (re)starts indexing, re-query the
+   * loaded project within the deadline; a soft "not ready" `ResponseError` backs off and retries
+   * inside the deadline. Still indexing at the deadline ⇒ `not_ready` (retry).
+   */
+  private pullDiagnostics;
+  /**
+   * `workspace/symbol` — project-wide symbol search by name (ADR 0011 staged tail). Position-less
+   * and file-less: the query is just a name fragment matched against the whole indexed workspace,
+   * so it needs no open document (the project is loaded at `initialize`). Tri-state like the rest —
+   * an empty result while the project is still indexing is `not_ready`, never collapsed into
+   * "no such symbol" (the cold-load trap the rest of the client already guards). Handles both the
+   * flat `SymbolInformation[]` (range present) and the uri-only `WorkspaceSymbol[]` shapes.
+   */
+  workspaceSymbols(query: string): Promise<NavResult<NormalizedWorkspaceSymbol[]>>;
+  /**
+   * `textDocument/prepareRename` — the cheap validate-first pre-flight (write-mode, ADR 0011
+   * addendum). Tri-state: `null` while indexing ⇒ `not_ready`; `null` while ready ⇒ `no_result`
+   * (the engine maps that to a structured "not renameable here" refusal); a non-null outcome ⇒
+   * `ok`. Only callable when {@link supportsPrepareRename} (the engine skips it otherwise).
+   */
+  prepareRename(uri: string, position: {
+    line: number;
+    character: number;
+  }): Promise<NavResult<PrepareRenameOutcome | null>>;
+  /**
+   * `textDocument/rename` — compute the cross-file `WorkspaceEdit` for renaming the symbol at
+   * `position` to `newName`. Capability-gated on `renameProvider`; normalized to the uniform
+   * `files`/`resourceOps` shape; tri-state (empty/`null` while indexing ⇒ `not_ready`). This
+   * computes only — applying the edit to disk is the gated engine's job (Slice F), never here.
+   */
+  rename(uri: string, position: {
+    line: number;
+    character: number;
+  }, newName: string): Promise<NavResult<NormalizedWorkspaceEdit>>;
+  /**
+   * Call hierarchy — a TWO-round-trip protocol. `prepareCallHierarchy` resolves the symbol at
+   * `position` to one or more `CallHierarchyItem`s (null vs empty is distinct; overloads yield
+   * MANY — we keep them all, never silently the first); then per item we fetch incoming or
+   * outgoing calls. Tri-state lives on the PREPARE step (empty-while-indexing ⇒ not_ready). A
+   * prepared item with no callers/callees is a legitimate `ok` with empty `calls`. The RAW item
+   * is passed back to the calls request (it may carry an opaque `data` field the server needs).
+   */
+  callHierarchy(uri: string, position: {
+    line: number;
+    character: number;
+  }, direction: CallDirection): Promise<NavResult<CallHierarchyGroup[]>>;
+  private navigateLocations;
+  /**
+   * The tri-state request loop: settle → send → decide, all inside one operator deadline.
+   *
+   * The load-bearing rule (ADR 0011 addendum — proven by a live `typescript-language-server`
+   * capture): **a result returned while the server is still indexing the project is NOT
+   * trustworthy** — tsserver answers an early request from a single-file *inferred* project
+   * (a non-empty BUT PARTIAL answer — e.g. a cross-file rename that sees only the opened file)
+   * and only *then* finishes loading the configured project. So:
+   *
+   * 1. Before sending, wait out any in-flight indexing (`awaitIndexingSettled`) so we hit the
+   *    loaded project.
+   * 2. After sending, if indexing is active (the send itself triggered the configured-project
+   *    load), the answer is from the unstable inferred project — loop to settle + re-query.
+   * 3. Once the server is settled: a non-empty result is `ok`; an empty result is `no_result`
+   *    (retried with bounded backoff) — or `not_ready` only if we hit the deadline still indexing.
+   *
+   * This trades the old "return `not_ready` fast" for "wait for the correct answer within the
+   * deadline" — correctness over latency, bounded by the operator timeout.
+   */
+  private withRetry;
+  private wrap;
+  /** Graceful teardown: LSP `shutdown` request then the `exit` notification. */
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/registry.d.ts
+/**
+ * The operator-bound language→server registry (ADR 0011). Safety-critical: the agent supplies
+ * only a `language` string and NEVER a binary, argv, or path. The operator binds the registry
+ * out-of-band (`SACKVILLE_LSP_SERVERS`, JSON); a language absent from it is refused, never
+ * spawned.
+ *
+ * The registry is **JSON with `command` and `args[]` structurally separate** — deliberately
+ * NOT a `lang=cmd args;…` mini-DSL the engine would re-split, because real server commands
+ * routinely contain spaces, `=`, and wrapper prefixes (`rustup run stable rust-analyzer`).
+ * Splitting a string would corrupt those; an explicit array cannot.
+ */
+/** One operator-registered language server: the binary + argv, kept structurally separate. */
+interface ServerRegistryEntry {
+  command: string;
+  args: string[];
+  /** Passed verbatim as the LSP `initialize` `initializationOptions` (hardening flags, etc.). */
+  initializationOptions?: unknown;
+  /** The `languageId` sent in `didOpen`; defaults to the registry key when omitted. */
+  languageId?: string;
+}
+/** The full registry, keyed by the agent-facing `language` string. */
+type ServerRegistry = Record<string, ServerRegistryEntry>;
+/** Thrown on a malformed operator registry or a request for an unbound language. */
+declare class LspRegistryError extends Error {
+  constructor(message: string);
+}
+/**
+ * Parse + validate the operator JSON registry. Fails loud on anything malformed — an
+ * operator misconfiguration must be a clear error, never a silently-empty or
+ * partially-parsed registry an agent then queries against.
+ */
+declare function parseServerRegistry(json: string): ServerRegistry;
+/** Resolve a language to its registered server, or refuse it (never spawns an unbound server). */
+declare function resolveServer(registry: ServerRegistry, language: string): ServerRegistryEntry;
+//#endregion
+//#region src/manager.d.ts
+/** Thrown when the manager refuses a request (root outside the allowlist, server cap reached). */
+declare class LspManagerError extends Error {
+  constructor(message: string);
+}
+interface LanguageServerManagerOptions {
+  /** The operator-bound language→server registry (the agent picks only a language). */
+  registry: ServerRegistry;
+  /** OPERATOR allowlist of project roots a server may be initialized against. */
+  allowedRoots: string[];
+  /** Per-request wall-clock cap (ms) handed to each `LspClient`. */
+  timeoutMs: number;
+  /** Injected spawn seam. Default {@link defaultServerSpawn} (real `child_process.spawn`). */
+  serverSpawn?: ServerSpawn;
+  /** Idle time before a server is eligible for reaping, in ms. Default 15 min (warm servers). */
+  idleTtlMs?: number;
+  /** Max concurrent servers. Default 8. */
+  maxServers?: number;
+  /** Grace (ms) between the LSP `shutdown`/`exit` and the hard `dispose()`. Default 2000. */
+  shutdownGraceMs?: number;
+  /** Single-attempt client mode (the gate's deterministic default; production retries). */
+  noRetry?: boolean;
+  /** Injected clock. Default `Date.now`. */
+  now?: () => number;
+  /** Injected delay (the shutdown grace). Default a `setTimeout` promise. */
+  delay?: (ms: number) => Promise<void>;
+}
+interface QueryInput {
+  /** The agent-facing language id (resolved against the operator registry). */
+  language: string;
+  /** The primary project root — where the queried file lives; must be in `allowedRoots`. */
+  projectRoot: string;
+  /** The document URI being queried (`file://…`). */
+  uri: string;
+  /** The document's full text (sent verbatim in `didOpen`). */
+  text: string;
+  /**
+   * Additional allowlisted roots bound as workspace folders on the SAME server (multi-root, ADR
+   * 0011 tail). The server is keyed by the sorted root GROUP, so one server handles the whole
+   * group and cross-root navigation resolves. Each must be in `allowedRoots`. Default: none.
+   */
+  workspaceRoots?: string[];
+}
+/** Provenance for one live server — what `lsp_languages` surfaces (never the command/path). */
+interface ServerDescription {
+  language: string;
+  projectRoot: string;
+  /** The full root group, set only for a multi-root server (length > 1). */
+  roots?: string[];
+  serverInfo?: {
+    name: string;
+    version?: string;
+  };
+  capabilities: Record<string, boolean>;
+}
+declare class LanguageServerManager {
+  private readonly registry;
+  private readonly allowedRoots;
+  private readonly timeoutMs;
+  private readonly serverSpawn;
+  private readonly idleTtlMs;
+  private readonly maxServers;
+  private readonly shutdownGraceMs;
+  private readonly noRetry;
+  private readonly now;
+  private readonly delay;
+  private readonly servers;
+  /** In-flight spawn+initialize, so concurrent first callers share one initialization. */
+  private readonly initing;
+  private reaper;
+  constructor(options: LanguageServerManagerOptions);
+  get serverCount(): number;
+  /**
+   * Run `fn` against the (shared, lazily-spawned) server for `(language, projectRoot)`, under
+   * the per-`(server, uri)` mutex. The document is opened once (refcounted in the client) and
+   * the server's idle clock is reset on entry and exit; `inFlight` is held for the duration so
+   * the reaper cannot tear the server down mid-request.
+   */
+  run<T>(input: QueryInput, fn: (client: LspClient) => Promise<T>): Promise<T>;
+  /**
+   * Like {@link run}, but holds the per-`(server, uri)` lock for MANY uris at once — the
+   * primitive a multi-file write needs (Slice F′). Locks are acquired in a deterministic SORTED
+   * order so two concurrent multi-file renames can never deadlock (no lock-ordering cycle), and
+   * are all held across the whole `fn` (the stage+commit+`didChange` window). Does NOT `didOpen`
+   * any document — the caller opened what it needs during the compute phase (open-once/refcount).
+   */
+  runWithUris<T>(input: {
+    language: string;
+    projectRoot: string;
+    uris: string[];
+    workspaceRoots?: string[];
+  }, fn: (client: LspClient) => Promise<T>): Promise<T>;
+  /**
+   * The resolved, sorted, de-duplicated root group for a query — the primary `projectRoot` plus any
+   * `workspaceRoots`. EVERY member is `assertRootAllowed`'d (refused before any spawn), so a
+   * multi-root group cannot smuggle in an un-allowlisted folder.
+   */
+  private resolveGroup;
+  /** Resolve (and lazily spawn+initialize) the shared server for `(language, root group)`. */
+  private acquire;
+  /**
+   * Find the UNIQUELY-largest warm server whose root group is a strict subset of `roots` (same
+   * language, and it must advertise workspace-folder change support), grow it to `roots` in place,
+   * and re-key it. Returns the grown entry, or `undefined` when there is no candidate or the largest
+   * subset is ambiguous (≥2 candidates tie for the most roots) — in which case we spawn fresh rather
+   * than guess which to mutate. Grow-only: a subset request of an existing LARGER server is NOT
+   * shrunk (it spawns its own server) — keeping keys, `describe()`, and confinement unambiguous.
+   */
+  private tryGrowExisting;
+  private spawnAndInit;
+  /** Provenance for every currently-live server (drives the always-on `lsp_languages` tool). */
+  describe(): ServerDescription[];
+  private assertRootAllowed;
+  /** Serialize `fn` against all other callers holding the same `(server, uri)` lock. */
+  private withUriLock;
+  /**
+   * Acquire the per-uri locks for EVERY uri (deduped, SORTED — deadlock-free ordering) and hold
+   * them all across `fn`, releasing in reverse on exit. Each lock chains on the same per-uri
+   * promise the single-uri `withUriLock` uses, so a multi-file write serializes correctly against
+   * any concurrent single-file query on one of its files.
+   */
+  private withUriLocks;
+  /**
+   * Reap every server idle for at least `idleTtlMs` that has NO in-flight request. Returns the
+   * reaped keys. Drives the deterministic reaper logic; `nowMs` defaults to the injected clock.
+   */
+  sweepIdle(nowMs?: number): Promise<string[]>;
+  private reap;
+  /** LSP `shutdown` → `exit` (graceful), then a clock-driven grace, then the hard `dispose()`. */
+  private gracefulStop;
+  /** Start the production idle reaper (a `setInterval` driving the injected-clock `sweepIdle`). */
+  startReaper(intervalMs: number): void;
+  stopReaper(): void;
+  /** Gracefully stop and dispose every server; the manager can be reused afterward. */
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/confine.d.ts
+/**
+ * The shared paired-gate + path-confinement guards for the LSP engines (ADR 0011). Factored
+ * out of `query.ts` so the read engine (`LspQueryEngine`) and the write engine
+ * (`LspRenameEngine`, Slice F) share one implementation — with a `resolveSymlinks` mode that
+ * the WRITE path always sets.
+ *
+ * The read path confines the single queried file lexically (lower stakes). The write path must
+ * confine EVERY file a `WorkspaceEdit` would touch, and lexically is not enough: `resolve()`
+ * does not canonicalize symlinks, so a symlink INSIDE the root pointing OUTSIDE it passes a
+ * prefix check and a write would clobber the out-of-root target. The write path therefore
+ * `realpath`-canonicalizes the root and each target's nearest existing ancestor and re-asserts
+ * containment, and refuses any non-`file://` scheme. Confinement is pure path/metadata work —
+ * it runs BEFORE any target file content is read.
+ */
+/** Thrown when the paired operator gate denies a query/edit (allowRun off, out-of-bounds, bad scheme). */
+declare class LspGateError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/query.d.ts
+/** Reads a file's text, or `undefined` if it cannot be read. */
+type FileReader = (absolutePath: string) => string | undefined;
+interface LspQueryEngineOptions {
+  manager: LanguageServerManager;
+  /** OPERATOR opt-in to run navigation (which requires a live indexing daemon). Deny-by-default. */
+  allowRun: boolean;
+  /** OPERATOR allowlist of project roots. Load-bearing even with allowRun. */
+  allowedRoots: string[];
+  /** Injected file reader (default `readFileSync`). */
+  readFile?: FileReader;
+}
+type LspQueryKind = 'definition' | 'typeDefinition' | 'references' | 'hover' | 'documentSymbols' | 'workspaceSymbol' | 'diagnostics' | 'callHierarchy';
+interface LspQueryInput {
+  /** The agent-facing language (resolved against the operator registry). */
+  language: string;
+  /** Project root — must be in `allowedRoots`; pinned to the server's `rootUri`. */
+  projectRoot: string;
+  /**
+   * Additional allowlisted roots bound as workspace folders on the SAME server (multi-root, ADR
+   * 0011 tail) — so cross-root navigation resolves through one server. Each must be in
+   * `allowedRoots`. The queried `file` still lives under the primary `projectRoot`.
+   */
+  workspaceRoots?: string[];
+  /**
+   * The file to query, relative to `projectRoot` (or absolute within it). Required for every kind
+   * EXCEPT `workspaceSymbol`, which searches the whole indexed project and needs no open file.
+   */
+  file?: string;
+  /** 1-based human line — required for the position-based kinds, ignored for `documentSymbols`. */
+  line?: number;
+  /** 1-based human column (code points) — required for the position-based kinds. */
+  column?: number;
+  kind: LspQueryKind;
+  /** The search string — required for (and only used by) `workspaceSymbol`. */
+  query?: string;
+  /** Call-hierarchy direction (callers vs callees); defaults to `incoming`. */
+  direction?: CallDirection;
+  /** Optional toolchain provenance to echo (the surface computes via `detectInstalledVersion`). */
+  toolchain?: {
+    name: string;
+    version: string | null;
+  };
+}
+interface HumanRange {
+  start: HumanPosition;
+  end: HumanPosition;
+}
+interface ResultLocation {
+  uri: string;
+  range: HumanRange;
+  /** The full enclosing range, when the server sent a LocationLink. */
+  fullRange?: HumanRange;
+  /** False ⇒ the target file was unreadable; the range is a best-effort `+1` of the LSP offsets. */
+  mapped: boolean;
+}
+/** A document symbol with its range mapped to human 1-based coords; children recurse. */
+interface ResultSymbol {
+  name: string;
+  kind: number;
+  kindName: string;
+  detail?: string;
+  range: HumanRange;
+  /** Set only for flat `SymbolInformation` results. */
+  container?: string;
+  children?: ResultSymbol[];
+}
+/** A diagnostic with its range(s) mapped to human 1-based coords. */
+interface ResultDiagnostic {
+  range: HumanRange;
+  message: string;
+  severity?: number;
+  severityName?: string;
+  code?: number | string;
+  source?: string;
+  tags?: string[];
+  related?: {
+    uri: string;
+    range: HumanRange;
+    message: string;
+  }[];
+}
+/** A workspace symbol with its range (if any) mapped to human 1-based coords. */
+interface ResultWorkspaceSymbol {
+  name: string;
+  kind: number;
+  kindName: string;
+  uri: string;
+  /** The declaring container (class/namespace), when the server reported one. */
+  container?: string;
+  /** Absent when the server returned a uri-only `WorkspaceSymbol` (no range without resolve). */
+  range?: HumanRange;
+  /** True when a range was present AND its target file was readable (encoding-faithful map). */
+  mapped: boolean;
+}
+/** A call-hierarchy item with its ranges mapped to human 1-based coords. */
+interface ResultCallItem {
+  name: string;
+  kind: number;
+  kindName: string;
+  detail?: string;
+  uri: string;
+  range: HumanRange;
+  selectionRange: HumanRange;
+}
+/** One call edge: the other item + the human-coord ranges where the call occurs. */
+interface ResultCall {
+  item: ResultCallItem;
+  fromRanges: HumanRange[];
+}
+interface ResultCallGroup {
+  source: ResultCallItem;
+  direction: CallDirection;
+  calls: ResultCall[];
+}
+interface LspQueryResult {
+  status: QueryStatus;
+  kind: LspQueryKind;
+  locations?: ResultLocation[];
+  hover?: {
+    value: string;
+    range?: HumanRange;
+  };
+  symbols?: ResultSymbol[];
+  workspaceSymbols?: ResultWorkspaceSymbol[];
+  diagnostics?: ResultDiagnostic[];
+  callHierarchy?: ResultCallGroup[];
+  serverInfo?: ServerInfo;
+  toolchain?: {
+    name: string;
+    version: string | null;
+  };
+  encoding: PositionEncoding;
+  versionWarning?: string;
+}
+declare class LspQueryEngine {
+  private readonly manager;
+  private readonly allowRun;
+  private readonly allowedRoots;
+  private readonly readFile;
+  constructor(options: LspQueryEngineOptions);
+  query(input: LspQueryInput): Promise<LspQueryResult>;
+  /**
+   * Run the project-wide `workspace/symbol` search and shape its cross-file result.
+   *
+   * `workspace/symbol` takes no position, but a real server still needs a *project* to search.
+   * Some servers — notably `typescript-language-server` — only build a project once a document is
+   * open, and answer `workspace/symbol` with a "No Project" error otherwise (caught running the
+   * greeter example live, the cold-load lesson again). So the agent may pass an OPTIONAL anchor
+   * `file`: when present we open it (establishing the project) before searching; when absent we
+   * search with no document open, which works for eager indexers (gopls, rust-analyzer) that load
+   * the project at `initialize`.
+   */
+  private queryWorkspaceSymbol;
+  /** The shared provenance/status envelope every result carries (status + encoding + provenance). */
+  private baseResult;
+  private shape;
+  private mapLocation;
+  /** Map a normalized document symbol (and its children) to human coords in the queried file. */
+  private mapSymbol;
+  /** Map a diagnostic's range (queried file) + any relatedInformation ranges (their own files). */
+  private mapDiagnostic;
+  /** Map a workspace symbol to human coords, reading its OWN target file (cross-file, read-only). */
+  private mapWorkspaceSymbol;
+  private mapCallItem;
+  private mapCallGroup;
+  private textForUri;
+  /** Map an LSP 0-based range to a human 1-based range, encoding-faithfully when text is known. */
+  private mapRange;
+}
+//#endregion
+//#region src/rename.d.ts
+/** Reads a file's text, or `undefined` if it cannot be read. */
+type FileReader$1 = (absolutePath: string) => string | undefined;
+/**
+ * Lists candidate source files (absolute paths) under the allowlisted root group to scan for the
+ * partial-rename completeness guard — same-language source only (`extension`, e.g. `.py`). Injected
+ * so the gate never walks a real tree; `truncated` ⇒ a cap was hit and the scan is not exhaustive.
+ */
+type ProjectFileLister = (roots: string[], opts: {
+  extension: string;
+}) => {
+  files: string[];
+  truncated: boolean;
+};
+/** Default lister: a bounded, symlink-safe recursive walk collecting `extension` files, skipping
+ * dependency/VCS/cache/build dirs and any dotdir. Stops (`truncated`) at {@link MAX_SCAN_FILES}.
+ * The partial-rename guard is OFF until a lister is wired (like `redact`, the surfaces wire this). */
+declare const defaultListFiles: ProjectFileLister;
+/** How exhaustively the partial-rename guard could verify the edit covers every textual use. */
+type RenameCompleteness = 'complete' | 'suspect' | 'unknown';
+/**
+ * One physical filesystem action in an apply commit. A `write` creates-or-overwrites a file's
+ * content (the fold of a CreateFile + its edits, or an edit to a pre-existing file); `rename`/
+ * `delete` are the resource-op file moves/removals (`RenameFile`/`DeleteFile`).
+ */
+type PhysicalOp = {
+  kind: 'write';
+  absPath: string;
+  newText: string;
+} | {
+  kind: 'rename';
+  fromAbs: string;
+  toAbs: string;
+} | {
+  kind: 'delete';
+  absPath: string;
+};
+interface CommitResult {
+  /** The ops that completed, in order. */
+  completed: PhysicalOp[];
+  /** True ⇒ an op faulted mid-execute; `completed` is the TERMINAL landed set (rename/delete are
+   * irreversible — there is no rollback; reconcile via VCS). */
+  partial: boolean;
+  error?: string;
+}
+/**
+ * The write seam (injected; tests substitute a fake so the gate never touches disk). The default
+ * **stages every `write` to a sibling temp (+ fsync) first** (no target touched until all temps
+ * exist — the strength the pure-text rename relies on), then executes every op IN ORDER: a `write`
+ * commits via atomic rename of its temp, a `rename`/`delete` runs the fs primitive. Resource ops
+ * are irreversible and cannot be staged, so a fault during the execute phase is terminal —
+ * `partial: true` names exactly what landed.
+ */
+interface RenameWriter {
+  commit(ops: PhysicalOp[]): CommitResult;
+}
+declare const defaultRenameWriter: RenameWriter;
+interface LspRenameEngineOptions {
+  manager: LanguageServerManager;
+  /** OPERATOR opt-in to run navigation (which requires a live indexing daemon). Deny-by-default. */
+  allowRun: boolean;
+  /** OPERATOR allowlist of project roots. Load-bearing even with allowRun. */
+  allowedRoots: string[];
+  /** OPERATOR opt-in to WRITE the edit to disk. Distinct from allowRun; off ⇒ dry-run preview. */
+  allowWrite: boolean;
+  /**
+   * OPERATOR opt-in to APPLY a rename whose completeness verdict is `suspect` — i.e. the old
+   * identifier also appears in same-language files the server's edit does NOT touch (the hallmark
+   * of an open-files-scoped server like pyright, whose cross-file rename can be silently partial).
+   * Deny-by-default: a suspect rename is REFUSED for write unless this is set. Never an agent input.
+   */
+  allowPartialRename?: boolean;
+  /**
+   * OPERATOR opt-in to APPLY a DESTRUCTIVE resource op — `overwrite: true` on a CreateFile
+   * (truncate-and-replace an existing file) or a RenameFile (clobber an existing REGULAR-FILE
+   * target). Deny-by-default; refused for write unless set. Recursive/dir delete + symlink/dir
+   * targets STAY refused even with this gate. Meaningless without `allowWrite` (the engine
+   * re-checks both before any destructive op); never an agent input.
+   */
+  allowDestructiveResourceOps?: boolean;
+  readFile?: FileReader$1;
+  /** Lists same-language source files to scan for the partial-rename guard. UNSET ⇒ the guard is
+   * inactive (no scan); the bin/CLI/MCP wire `defaultListFiles` to turn it on (cf. `redact`). */
+  listFiles?: ProjectFileLister;
+  writer?: RenameWriter;
+  /** Secret redaction over every surfaced hunk (default identity; the bin wires @sackville-mcp/safety). */
+  redact?: (text: string) => string;
+}
+interface LspRenameInput {
+  language: string;
+  projectRoot: string;
+  /** The file to rename in, relative to projectRoot (or absolute within it). */
+  file: string;
+  /** 1-based human line of the symbol to rename. */
+  line: number;
+  /** 1-based human column (code points) of the symbol to rename. */
+  column: number;
+  /** The new identifier. Validated by isPlausibleRenameName before reaching the server. */
+  newName: string;
+  /**
+   * Additional allowlisted roots bound as workspace folders on the SAME server (multi-root). A
+   * cross-root rename may edit files in any of these; each must be in `allowedRoots`, and edited
+   * files confine to the GROUP (`projectRoot` ∪ `workspaceRoots`), not just the primary root.
+   */
+  workspaceRoots?: string[];
+  /** Optional toolchain provenance to echo. */
+  toolchain?: {
+    name: string;
+    version: string | null;
+  };
+}
+interface RenamePreviewEdit {
+  range: HumanRange;
+  oldText: string;
+  newText: string;
+  needsConfirmation?: boolean;
+  annotationLabel?: string;
+}
+interface RenamePreviewFile {
+  uri: string;
+  /** Project-relative path (never absolute). `(out of project root)` for an out-of-root edit. */
+  file: string;
+  editCount: number;
+  /** True ⇒ the edit targets a file outside the allowlisted root; its bytes are NOT surfaced. */
+  outOfRoot?: boolean;
+  /** The per-edit hunks (omitted for an out-of-root or unreadable file). */
+  hunks?: RenamePreviewEdit[];
+}
+interface RenameDigest {
+  file: string;
+  before: string;
+  after: string;
+}
+interface LspRenameResult {
+  status: QueryStatus;
+  kind: 'rename';
+  applied: boolean;
+  /** A structured reason the rename was not applied (not renameable, multi-file, resource ops, drift). */
+  refused?: string;
+  newName: string;
+  fileCount: number;
+  totalEditCount: number;
+  edits: RenamePreviewFile[];
+  resourceOps?: NormalizedResourceOp[];
+  /** Per-file pre/post SHA-256 digests — the apply audit (only when applied). */
+  digests?: RenameDigest[];
+  /** Project-relative paths whose prior content a DESTRUCTIVE overwrite clobbered (gated; landed
+   * only) — so a destructive clobber is always explicit in the envelope, not inferred from a digest. */
+  overwritten?: string[];
+  /** True ⇒ an irreversible resource op faulted mid-commit; `digests` names what landed (no
+   * rollback — reconcile via VCS). */
+  partial?: boolean;
+  partialError?: string;
+  /**
+   * The partial-rename guard verdict (omitted when the rename was not `ok`). `complete` — every
+   * same-language file mentioning the old name is in the edit; `suspect` — some are NOT (the edit
+   * may be partial, e.g. an open-files-scoped server); `unknown` — the scan was truncated.
+   */
+  completeness?: RenameCompleteness;
+  /** Project-relative same-language files that mention the old identifier but are absent from the
+   * edit (capped). Populated when `completeness === 'suspect'`. */
+  suspectedMissedFiles?: string[];
+  serverInfo?: ServerInfo;
+  toolchain?: {
+    name: string;
+    version: string | null;
+  };
+  encoding: PositionEncoding;
+  versionWarning?: string;
+}
+declare class LspRenameEngine {
+  private readonly manager;
+  private readonly allowRun;
+  private readonly allowedRoots;
+  private readonly allowWrite;
+  private readonly allowPartialRename;
+  private readonly allowDestructiveResourceOps;
+  private readonly readFile;
+  /** When unset the partial-rename guard is inactive (the bin/CLI/MCP wire `defaultListFiles`). */
+  private readonly listFiles?;
+  private readonly writer;
+  private readonly redact;
+  constructor(options: LspRenameEngineOptions);
+  rename(input: LspRenameInput): Promise<LspRenameResult>;
+  /**
+   * Decide + execute the apply, consuming the ordered `operations` (text edits interleaved with
+   * CreateFile/RenameFile/DeleteFile). Confine EVERY touched URI (edit + create + rename old&new +
+   * delete) to the root group all-or-nothing BEFORE any I/O; refuse the v1 cuts early (non-default
+   * resource-op options; editing a file also renamed in the same batch). Then, under the multi-URI
+   * lock over ALL touched URIs, replay the ops over a virtual content map (no writes) with the
+   * staleness guards, build a physical plan, stage-then-commit it, and resync any open buffer
+   * (`didChange` for an edited file, `didClose`+`didOpen` migration for a renamed/deleted one).
+   */
+  private applyEdit;
+  /**
+   * The partial-rename completeness guard. Extracts the old identifier at the queried position,
+   * then scans the allowlisted root group for same-language files that mention it as a whole word
+   * but are NOT covered by the server's edit (text edits + resource-op endpoints). Any such file is
+   * a SUSPECT — the edit is likely partial (an open-files-scoped server). `unknown` ⇒ the scan was
+   * truncated (cap hit). Server-agnostic: a whole-project-rename server covers every use ⇒ `complete`.
+   */
+  private assessCompleteness;
+  private shape;
+  private previewFile;
+  private hunk;
+}
+//#endregion
+export { type CallDirection, type CallHierarchyGroup, type CallHierarchyItem, type CommitResult, type Diagnostic, type DocumentSymbol, type FileReader, type Hover, type HumanPosition, type HumanRange, type InitializeSummary, LanguageServerManager, type LanguageServerManagerOptions, type Location, type LocationLink, LspClient, type LspClientOptions, type LspConnection, LspGateError, LspManagerError, type LspPosition, type LspPositionParts, LspQueryEngine, type LspQueryEngineOptions, type LspQueryInput, type LspQueryKind, type LspQueryResult, type LspRange, LspRegistryError, LspRenameEngine, type LspRenameEngineOptions, type LspRenameInput, type LspRenameResult, LspUnsupportedError, type MarkedString, type MarkupContent, type NavResult, type NormalizedCall, type NormalizedCallItem, type NormalizedDiagnostic, type NormalizedFileEdit, type NormalizedFileEdits, type NormalizedHover, type NormalizedLocation, type NormalizedRelatedInfo, type NormalizedResourceOp, type NormalizedSymbol, type NormalizedWorkspaceEdit, type NormalizedWorkspaceSymbol, PREFERRED_ENCODINGS, type PhysicalOp, type PositionEncoding, type PrepareRenameOutcome, type ProjectFileLister, type QueryInput, type QueryStatus, type RawPrepareRename, type RawResourceOperation, type RawTextDocumentEdit, type RawTextEdit, type RawWorkspaceEdit, type RenameCompleteness, type RenameDigest, type RenamePreviewEdit, type RenamePreviewFile, type RenameWriter, type ResultCall, type ResultCallGroup, type ResultCallItem, type ResultDiagnostic, type ResultLocation, type ResultSymbol, type ResultWorkspaceSymbol, type ServerDescription, type ServerInfo, type ServerRegistry, type ServerRegistryEntry, type ServerSpawn, type ServerSpec, type SymbolInformation, type WorkspaceSymbol, decideStatus, defaultListFiles, defaultRenameWriter, defaultServerSpawn, diagnosticSeverityName, fromLspCharacter, fromLspPosition, normalizeCallHierarchyItem, normalizeCallHierarchyItems, normalizeDiagnostics, normalizeDocumentSymbols, normalizeHover, normalizeIncomingCalls, normalizeLocations, normalizeOutgoingCalls, normalizePrepareRename, normalizeWorkspaceEdit, normalizeWorkspaceSymbols, parseServerRegistry, resolvePositionEncoding, resolveServer, symbolKindName, toLspCharacter, toLspPosition };
+//# sourceMappingURL=index.d.mts.map