chore: import upstream snapshot with attribution

docs/lsp.md

@@ -0,0 +1,431 @@
+# LSP Routing
+
+Gortex uses the Language Server Protocol (LSP) for two things:
+
+1. **Compiler-grade resolution during enrichment.** When the resolver
+   leaves an edge as `ast_inferred` or `text_matched`, an LSP server
+   (`textDocument/definition` + `textDocument/implementation`) upgrades
+   it to `lsp_resolved` / `lsp_dispatch`. This raises precision on
+   `find_usages`, `get_callers`, `find_implementations`, and the
+   contract pipeline's binding resolver.
+2. **On-demand actions** via the four MCP tools that wrap the LSP
+   action surface: `get_diagnostics`, `get_code_actions`,
+   `apply_code_action`, `fix_all_in_file`.
+
+Both paths route through the same per-daemon `lsp.Router` — one
+subprocess per language server, lazy-spawned on first request, idle
+reaper at ten minutes, LRU eviction at six concurrent.
+
+## Server registry
+
+Sixteen servers ship in the registry today
+(`internal/semantic/lsp/registry.go`):
+
+| Spec name                    | Command                          | Languages                   | Default priority |
+| ---------------------------- | -------------------------------- | --------------------------- | ---------------- |
+| `gopls`                      | `gopls`                          | go                          | 3                |
+| `typescript-language-server` | `typescript-language-server`     | typescript, javascript      | 5                |
+| `pyright`                    | `pyright-langserver`             | python                      | 5                |
+| `rust-analyzer`              | `rust-analyzer`                  | rust                        | 5                |
+| `clangd`                     | `clangd --background-index`      | c, c++, objc, objc++        | 5                |
+| `jdtls`                      | `jdtls`                          | java                        | 6                |
+| `kotlin-language-server`     | `kotlin-language-server`         | kotlin                      | 6                |
+| `omnisharp`                  | `omnisharp -lsp`                 | csharp                      | 5                |
+| `ruby-lsp`                   | `ruby-lsp`                       | ruby                        | 5                |
+| `phpactor`                   | `phpactor language-server`       | php                         | 5                |
+| `lua-language-server`        | `lua-language-server`            | lua                         | 5                |
+| `sourcekit-lsp`              | `sourcekit-lsp`                  | swift                       | 5                |
+| `haskell-language-server`    | `haskell-language-server-wrapper`| haskell                     | 5                |
+| `elixir-ls`                  | `elixir-ls`                      | elixir                      | 5                |
+| `ocamllsp`                   | `ocamllsp`                       | ocaml                       | 5                |
+| `zls`                        | `zls`                            | zig                         | 5                |
+
+Several specs declare `AlternativeCommands` — Gortex picks the first
+binary on `PATH`:
+
+- `pyright` → falls back to `jedi-language-server` or `pylsp`.
+- `ruby-lsp` → falls back to `solargraph stdio`.
+- `phpactor` → falls back to `intelephense --stdio`.
+
+Lower priority numbers win when more than one provider serves the same
+language. `gopls` is `3` so it beats SCIP-based providers (`5`) for Go;
+`jdtls` is `6` so it's lower-priority than the SCIP-java path that
+ships separately.
+
+`clangd` is the one server that needs a compilation database for full
+enrichment. Point it at a `compile_commands.json` (or a `compile_flags.txt`
+/ `.clangd`) at the repo root; without one, gortex degrades that repository's
+enrichment to reference confirmation — see
+[Enrichment cost model](#enrichment-cost-model).
+
+## Enabling a server
+
+Add it to `.gortex.yaml`:
+
+```yaml
+semantic:
+  enabled: true
+  mode: typecheck     # or "callgraph"
+  providers:
+    - name: gopls
+      enabled: true
+    - name: rust-analyzer
+      enabled: true
+    - name: pyright
+      enabled: true
+```
+
+Names match the **Spec name** column above. The router pre-registers
+every enabled spec at boot but does not spawn anything yet —
+subprocesses start the first time a tool calls into them.
+
+## Installing the underlying servers
+
+Gortex does not ship the LSP binaries. Install the ones you want to
+use; the router falls back gracefully when a binary is missing
+(`SpecAvailable(name)` returns false → tool returns a structured
+`no_lsp_for` error instead of hanging).
+
+```bash
+# Go
+go install golang.org/x/tools/gopls@latest
+
+# Rust
+rustup component add rust-analyzer
+
+# Python (pick one)
+npm install -g pyright            # recommended
+pip install jedi-language-server  # alt
+pip install python-lsp-server     # alt (pylsp)
+
+# TypeScript / JavaScript
+npm install -g typescript typescript-language-server
+
+# C / C++ / Objective-C
+brew install llvm                 # ships clangd
+# or apt install clangd
+
+# Java
+brew install jdtls
+
+# Kotlin
+brew install kotlin-language-server
+
+# C#
+dotnet tool install --global Microsoft.OmniSharp
+
+# Ruby (pick one)
+gem install ruby-lsp              # recommended
+gem install solargraph            # alt
+
+# PHP (pick one)
+composer global require phpactor/phpactor
+npm install -g intelephense       # alt
+
+# Lua
+brew install lua-language-server
+
+# Swift
+# Bundled with Xcode toolchain on macOS; no separate install.
+
+# Haskell
+ghcup install hls
+
+# Elixir
+brew install elixir-ls
+
+# OCaml
+opam install ocaml-lsp-server
+
+# Zig
+brew install zls
+```
+
+Verify with `gortex daemon status` — the LSP-router section lists
+`alive`, `last_used`, and the resolved command for each running
+server. Newly enabled specs show up only after the first request that
+needs them.
+
+## Lifecycle
+
+The router applies these defaults in `cmd/gortex/server.go` and
+`cmd/gortex/mcp.go`:
+
+| Knob              | Default      | What it does                                                                                          |
+| ----------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
+| `WithIdleTimeout` | 10 minutes   | Subprocess closes if no `For()` / `ForSpec()` call lands in this window.                              |
+| `WithReaperInterval` | 1 minute   | Background tick invokes `Reap()` to enforce the idle timeout.                                          |
+| `WithMaxAlive`    | 6 servers    | LRU eviction kicks in when a seventh distinct server would spawn — the least-recently-used one closes. |
+
+These defaults suit a polyglot workspace where most languages are
+touched only intermittently. Override them by editing the
+`lsp.NewRouter(...).With...` chain in your build if you need a longer
+warm pool or a tighter memory bound.
+
+## Enrichment cost model
+
+The resolution path (use 1 at the top of this page) runs as a batch
+**enrichment pass** — one pass per (repository × language server) — that walks
+the repo's nodes for that language and upgrades edges the AST resolver left
+ambiguous. A pass runs up to five phases:
+
+1. **Interface pass** — for each interface / abstract declaration, asks the
+   server for its implementations (`textDocument/implementation`) and links the
+   dispatch edges.
+2. **Confirm pass** — for every ambiguous edge (one whose confidence the
+   resolver could not raise to certainty), asks for the referent's references
+   (`textDocument/references`) and confirms or refutes the edge. Grouped by
+   referent file so each file opens once.
+3. **Definition-rebind fallback** — for edges the confirm pass could not settle
+   from references alone, asks for the call site's definition
+   (`textDocument/definition`) and rebinds the edge to the concrete target.
+4. **References-add pass** — only for servers that expose references but not a
+   call hierarchy; recovers the caller edges a declaration's references imply.
+5. **Per-file sweep** — the whole-repo hover / hierarchy phase. Per function or
+   method it prepares a call hierarchy and reads outgoing (and, where it helps,
+   incoming) calls; per type or interface it reads the super/subtype hierarchy;
+   per symbol it hovers for a type string.
+
+Each phase opens the files it touches on the language server (`didOpen`) and
+closes them when done (`didClose`). The first four phases carry most of the
+precision gain; the sweep carries most of the cost — on a warm restart, where
+every node already reloads with its resolved edges and type stamp, the sweep is
+almost pure churn.
+
+### Bounded document session
+
+All five phases share one **document session** per pass. It opens each file on a
+server at most once while the file is in use, keeps recently-closed files warm
+in an LRU tail so a later phase reuses the open document instead of reopening
+it, and closes everything at pass end. The simultaneously-open ceiling is
+`2 × max_parallel` documents per server (floor 4): the pinned working set stays
+within `max_parallel` (bounded by the pass's file semaphore) and the extra
+headroom is the warm tail. `didOpen` / `didClose` stay paired per (file,
+server) — a file opened on a server that later dies still gets its close attempt
+on that server — while the server's open-document set stays bounded.
+
+This matters most for `clangd` without a compilation database: every `didOpen`
+triggers a full fallback-preamble + AST rebuild, so reopening the same file
+across phases multiplies that cost.
+
+### Sweep modes
+
+The per-file sweep (phase 5) is gated by a **sweep mode**:
+
+| Mode     | Behaviour                                                                                                                                                                                                                                                                                                                                                              |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `demand` | **Default.** Sweep a file only when its declarations still carry unresolved same-name call candidates (enrichment demand) or it declares a type / interface whose super/subtype hierarchy the sweep recovers. A file with neither signal is skipped, so a warm restart pays no sweep for it. Within a swept file, a node that already carries a `semantic_type` stamp from an earlier pass is not re-hovered. |
+| `full`   | Sweep every file of the language — maximal hover and hierarchy coverage, the right choice for a first cold index.                                                                                                                                                                                                                                                       |
+| `off`    | Skip the per-file sweep entirely. The confirm / rebind / references-add / interface passes still run, so edge tiers and recall are unaffected — only hover type strings and sweep-recovered hierarchy edges are dropped.                                                                                                                                                 |
+
+Resolution precedence, highest first:
+
+1. The `GORTEX_LSP_SWEEP` environment variable (`demand` / `full` / `off`, with
+   `none` accepted as an alias for `off`; case- and whitespace-insensitive). Set
+   it where you launch `gortex daemon` / `gortex server` to dial one run without
+   editing config.
+2. The `.gortex.yaml` key `semantic.lsp_sweep` (same values).
+3. A per-server default. Most servers have none and fall through to the global
+   default; **rust-analyzer defaults to `full`**. Rust method calls bind
+   overwhelmingly to standard-library receiver types the graph never indexes, so
+   static confirmation leaves rust-analyzer's net-new call-hierarchy edges on the
+   table — its recall lives in the full sweep. Either operator source above
+   overrides it, so `semantic.lsp_sweep: demand` (or the env) puts rust-analyzer
+   back on the demand gate.
+4. The `demand` default.
+
+An unrecognised value at any level is ignored and the next source applies.
+
+```yaml
+semantic:
+  enabled: true
+  lsp_sweep: demand   # demand (default) | full | off
+```
+
+### Incoming-calls policy
+
+In the sweep's call-hierarchy step, outgoing calls are always fetched — the
+sweep visits every caller, so a declaration's outgoing hops alone reconstruct
+every intra-repo static call edge. Incoming calls are fetched only where the
+outgoing side is blind: a dispatch-relevant declaration (whose concrete callers
+land on the incoming side of an interface method, not its outgoing side) or one
+that still carries unresolved demand — or under `full` mode. Files are swept
+demand-first, so a declaration whose incoming calls are skipped at a deadline
+cut still loses no reachable edge. The count of declined round trips rides on
+the pass-complete log as `incoming_calls_skipped`.
+
+### Compile-database preflight (clangd)
+
+Before enriching a repository with a server that needs a compilation database
+(`clangd`), gortex checks the workspace root for one of:
+
+- `compile_commands.json` — canonical CMake / Bear output
+- `build*/compile_commands.json` — out-of-tree build directories
+- `compile_flags.txt` — clangd's flat-flags fallback
+- `.clangd` — a hand-written clangd config
+
+If none is present, clangd rebuilds a full fallback AST on every `didOpen`, and
+opening a header directly makes it a standalone translation unit with no
+cross-file signal to show for the cost. Rather than drive that churn, the pass
+**degrades to reference confirmation**: it runs the confirm and rebind passes
+(which work inside the fallback translation unit on fallback flags) and skips
+the interface pass, the references-add pass, the entire per-file sweep, and all
+header files. Edge tiers and confirmed / refuted edges are unaffected; hover
+type strings and call / type-hierarchy edges are absent for that pass.
+
+A degraded pass warns once with the remediation and marks its result
+`degraded`. `index_health` surfaces a recommendation naming the repository and
+provider:
+
+> generate compile_commands.json (cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON,
+> bear -- make, or meson) at the repo root, then reindex
+
+Degradation is deliberate, not a failure — `semantic_enrichment_ok` stays true.
+
+### Telemetry
+
+The pass-complete log line (`LSP enrich: hover phase complete`) carries the cost
+accounting for the pass:
+
+| Field | Meaning |
+| ----- | ------- |
+| `sweep_mode` | The effective sweep mode for the pass. |
+| `did_opens` | Total `didOpen` calls across every phase. |
+| `reopened_files` | Files opened more than once (a warm-tail miss). |
+| `doc_evictions` | LRU evictions — a `didClose` forced to make room. |
+| `peak_open_docs` | Peak simultaneously-open documents on any one server. |
+| `req_references`, `req_implementations`, `req_definitions`, `req_hovers` | Per-method request counts. |
+| `req_prepare_call_hierarchy`, `req_outgoing_calls`, `req_incoming_calls` | Call-hierarchy request counts. |
+| `incoming_calls_skipped` | Incoming-calls round trips the policy above declined. |
+| `req_prepare_type_hierarchy`, `req_supertypes`, `req_subtypes` | Type-hierarchy request counts. |
+| `skipped_already_stamped` | Nodes whose hover was skipped because they already carried a `semantic_type`. |
+
+A degraded pass logs `LSP enrich: degraded pass complete (reference
+confirmation only)` instead, with `degraded=true` and the document-open counters
+but no hover / hierarchy counts.
+
+## Diagnostics
+
+Two surfaces:
+
+### Pull (poll-based)
+
+`get_diagnostics` returns the most recent `publishDiagnostics` payload
+the LSP server produced for a file. Use it for one-shot reads, batch
+checks, or contexts where the agent doesn't maintain a long-lived
+session.
+
+### Push (opt-in)
+
+`subscribe_diagnostics` opts the calling MCP session into
+`notifications/diagnostics` push events. After subscribing, every LSP
+`publishDiagnostics` for any router-managed server is forwarded to the
+session as an MCP notification with this shape:
+
+```json
+{
+  "method": "notifications/diagnostics",
+  "params": {
+    "uri":         "file:///abs/path/to/main.go",
+    "path":        "/abs/path/to/main.go",
+    "server":      "gopls",
+    "diagnostics": [
+      { "range": {"start": {"line": 41, "character": 4}, "end": {...}},
+        "severity": 1, "message": "missing return", "source": "gopls" }
+    ]
+  }
+}
+```
+
+Push semantics:
+
+- **Opt-in per session.** Sessions that never call `subscribe_diagnostics`
+  receive nothing — no broadcast spam.
+- **Delta-only.** Identical re-publishes (which some servers emit on
+  every save even when nothing changed) are suppressed at the
+  broadcaster — your subscribers only see real changes.
+- **All-router-managed servers.** One subscription covers every spec
+  the user enabled in config. The `server` field on each notification
+  identifies which LSP produced the payload.
+- **Non-blocking.** Notifications use `SendNotificationToAllClients`
+  which drops to an error hook when a session's notification channel
+  is full — slow consumers don't block the LSP message-pump.
+
+Call `unsubscribe_diagnostics` to opt back out (idempotent).
+
+Pair with `get_code_actions` + `apply_code_action` + `fix_all_in_file`
+for the full edit-time diagnostic loop without polling.
+
+## Language-specific behaviour
+
+A few servers need per-language handling beyond the generic router. These
+knobs are **environment variables** read by the daemon process — set them
+where you launch `gortex daemon` / `gortex server`. There is no `.gortex.yaml`
+key for them today.
+
+### C# — NuGet audit advisories (`omnisharp` / `csharp-ls`)
+
+The Roslyn `MSBuildWorkspace` these servers build escalates a NuGet audit
+*warning* (the `NU19xx` family — e.g. a transitively vulnerable package) to a
+**fatal** project-load failure and drops every project that references the
+flagged package. Those projects then have no compilation, so the server emits
+false `CS####` "unresolved type / namespace" diagnostics — even though
+`dotnet build` / `dotnet test` keep `NU19xx` a non-fatal warning and succeed.
+
+Gortex applies two complementary, C#-scoped fixes, **both on by default**:
+
+| Env var | Default | Effect |
+| --- | --- | --- |
+| `GORTEX_LSP_CSHARP_RESTORE` | on | Before spawning the C# server, run `dotnet restore -p:NuGetAudit=false` in the workspace so the MSBuild workspace loads every project (root-cause fix). Best-effort: a failure logs and falls through to a normal spawn; skipped on passive IDE attach and when `dotnet` is not on `PATH`. |
+| `GORTEX_LSP_CSHARP_DIAG_FILTER` | on | Strip diagnostics whose code is the `NU####` NuGet family from `publishDiagnostics` before storing / fanning out (symptom fix). Deliberately narrow — real `CS####` compiler diagnostics always pass through. |
+
+Set either to a falsey value (`0` / `off` / `false` / `none`) to disable it —
+e.g. `GORTEX_LSP_CSHARP_RESTORE=0` for offline / air-gapped indexing or to
+keep indexing off the network. Restore is on by default because gortex only
+indexes repositories you explicitly add (it never auto-discovers), and
+spawning the C# server already evaluates the project's MSBuild graph — so the
+restore adds no execution surface beyond the workspace load it precedes. A
+successful restore logs `lsp: csharp pre-restore complete (NuGetAudit
+suppressed)`; a failure logs `lsp: csharp pre-restore failed; spawning server
+anyway` with the restore output tail.
+
+### Java — build-backed resolution (`jdtls`)
+
+By default `jdtls` runs in a **no-build** mode (JRE-only classpath, Maven /
+Gradle import and autobuild disabled) so indexing an untrusted Java repo never
+runs its build. Resolution is more limited in this mode (jdtls falls back to
+an "invisible project"). Set `GORTEX_LSP_JDTLS_TRUST_BUILD=1` (or `true`) to
+allow full Maven / Gradle import + autobuild for higher-fidelity resolution —
+**opt-in**, because it executes the repository's build tooling. Enable it only
+for repositories you trust.
+
+## Troubleshooting
+
+- **`no_lsp_for` error:** the file extension didn't match any
+  registered spec. Either the spec isn't enabled in `.gortex.yaml`, or
+  the binary isn't on `PATH`. Run the spec's `--version` directly to
+  confirm install.
+- **`router spawn <name>: ...` error:** the binary was on `PATH` at
+  boot but the subprocess failed to initialise (commonly a missing
+  dependency such as `node` for `pyright`, or a workspace-config
+  mismatch). The error surfaces the LSP server's stderr.
+- **Server keeps restarting:** the idle reaper closed it, then the
+  next request re-spawned. Increase `WithIdleTimeout` if this hurts
+  warm-cache benchmarks.
+- **High memory under polyglot load:** lower `WithMaxAlive` from 6 to
+  3-4. The LRU evicts the least-recent server transparently.
+
+## Implementation notes
+
+- The router lives at `internal/semantic/lsp/router.go`. It satisfies
+  the `semantic.LSPRouter` interface so `semantic.Manager` can drive
+  batch enrichment without taking a hard import dependency on the lsp
+  package (which would create a cycle — lsp already imports semantic
+  for the Provider interface).
+- `tools_lsp.go::lspProviderForPath` queries the router first; if no
+  router is wired (legacy boot paths, tests), it falls back to a scan
+  through `Manager.AllProviders()` so user-defined daemons (specs not
+  in the registry) still work.
+- One `*lsp.Provider` per spec, regardless of how many MCP sessions
+  hit it. Concurrency is bounded by `ServerSpec.MaxParallel` (6-10
+  inflight requests per server depending on the spec).