pmacs/docs/lsp-language-coverage-framing.md

LSP language coverage: LaTeX (and the Haskell/OCaml question)

Status: revision 3. Implemented at d79afdc; step zero discharged by observation, and its result corrected two things this document had wrong.

Recorded precisely: the user authorized dispatch after a summary of revision 2's four corrections, rather than returning findings on the document as they did for the other lanes. The §3 verification caveat is therefore still live and binding — it is step zero, not a footnote.

Revision 2 corrects three facts revision 1 got wrong or stale, and answers the question revision 1 named as most likely to make the entry wrong in practice. Haskell's server is installed; Slice 1 is smaller than framed because the extension wiring already exists; Q#LX3's deferral argument rests on a COHERENCE.md line the same document contradicts twice; and Q#LX2 (the LaTeX root) now has a proposal rather than a shrug.

Revision 1 was untracked, on main, in one checkout. Per the handoff's own rule — work is portable only after it is committed and pushed — it did not travel. That is fixed by this branch.

---

0. What prompted this

An audit of the host machine against builtin/runtime/lsp.lua. pmacs configures LSP for fourteen languages — verified exactly, by extracting the pmacs.lsp.config.* keys:

bash  c  cmake  cpp  cuda  dockerfile  go  json  lua
python  rust  toml  yaml  zig

Lean is NOT among the gaps, and revision 1's first draft wrongly said it was. Lean 4 has builtin/runtime/lean.lua, lean_abbrev.lua and lean_input.lua (all three present), an arborium-lean grammar, and comment/typed-edit integration — Arc 8 Stages 1–4b, merged. The error came from grepping lsp.lua alone, which is the wrong place to look for a language that earned its own module.

1. The gap, re-measured

Language	tree-sitter	LSP config	Server on this machine
LaTeX	✅ grammar + builtin/queries/latex/highlights.scm	❌	texlab 5.25.1 — installed
Haskell	❌	❌	haskell-language-server — INSTALLED
OCaml	❌	❌	ocaml/opam/dune yes, ocaml-lsp-server absent

Correction: revision 1 said Haskell's server was missing. Both haskell-language-server and haskell-language-server-wrapper are on this machine. That collapses revision 1's Slice 1 / Slice 2 split, which rested on "Slice 2 needs servers installed first" — only OCaml does now.

LaTeX remains the sharp case: the grammar work landed, so a .tex buffer highlights correctly and offers no completion, no diagnostics, no go-to-definition, while texlab sits on disk unused.

2. Ground truth — Slice 1 is smaller than revision 1 claimed

Revision 1 proposed "one pmacs.lsp.config.latex entry, plus filetype mappings for .tex/.latex/.sty/.cls, matching the grammar's existing extension set so highlighting and LSP agree on what a LaTeX file is."

The filetype mappings are redundant, and the rationale describes a problem that cannot occur. Three facts, read rather than assumed:

• The grammar already carries exactly those extensions. src/syntax.rs:1110-1112 — name: "latex", extensions: &["tex", "latex", "sty", "cls"].
• Grammar-extension detection sits AHEAD of the LSP filetype map. The merged docs/latex-grammar-math-substrate-framing.md:166-171 states the chain — modeline → grammar extension → LSP filetype map → filename map → shebang — and concludes that adding those extensions "wires the whole chain with no Lua edit".
• The filetype map is explicitly a fallback. lsp.lua:267-270: "Every language with an LSP config now also ships a grammar, so this is mainly the LSP-only fallback that keeps a language id stable if a grammar is ever dropped, plus the seam for user-added mappings."

So a .tex buffer already resolves to language latex. They cannot disagree, because the grammar's extension list is what drives detection.

Slice 1 is therefore one thing: the pmacs.lsp.config.latex entry (plus its root resolver, §3). Filetype-map entries may still be added as the documented drop-a-grammar fallback, but that is belt-and-braces and should be labelled as such rather than sold as making two systems agree.

3. Q#LX2 — the LaTeX project root (answered in rev 2)

Revision 1 called this "the question most likely to make the entry wrong in practice" and left it open. It is the difference between texlab serving a multi-file thesis and serving isolated files, so it is the whole value of the lane for the stated use case.

The mechanism exists. pmacs.lsp.config.<lang>.root accepts a string or a resolver function, resolved through resolve_root_fn (lsp.lua:543) with per-resolver memoization, and on the reuse path as well as the spawn path (:535). A configured root "MUST be a canonical absolute path" (:525). So this is a config entry, not new machinery.

My vote: an upward marker walk with an explicit precedence, falling back to the file's own directory. In order:

1. .texlabroot — if texlab honours it (see the verification caveat below), an explicit user-placed marker should win over everything inferred.
2. latexmkrc / .latexmkrc — a build config is a strong, deliberate signal of a document root.
3. Tectonic.toml — the same for tectonic projects.
4. The file's own directory, as the fallback.

Deliberately NOT in the walk: .git. A repository root is the wrong answer for LaTeX — texlab wants the document root, and a thesis inside a monorepo would otherwise get the monorepo. This is the one place where copying the other fourteen entries' instinct would be actively wrong.

And omitting it is NOT sufficient — revision 2 stopped one step short. project_root_for falls through to pmacs.project.detect when a resolver returns nil, and that walk lists .git among its markers (src/project.rs:184). So a resolver that politely declined on a markerless file would hand texlab the monorepo by the back door, with the exclusion looking correct at every line you would think to read. The resolver therefore never declines for a file with a directory, and the pin is end-to-end through attach — with the same fixture asserting the shared detector really would have answered the repository root, so the test cannot pass vacuously.

Deliberately NOT proposed: scanning for \documentclass. That is the semantically correct notion of a root document, and it is a directory scan on every resolve, with its own caching and invalidation questions. If the marker walk proves insufficient in use, that is the next increment — with evidence.

CAVEAT DISCHARGED (revision 3), and the premise behind it was wrong in a way that raises the lane's stakes.

Established by driving a hand-written LSP client against texlab run and reading texlab's source at the exact installed tag v5.25.1:

• .texlabroot is real, and so is a wider marker set than this document listed. crates/distro/src/language.rs maps .texlabroot/texlabroot → Root, Tectonic.toml → Tectonic, .latexmkrc/latexmkrc → Latexmkrc, and ProjectRoot::walk_and_find walks ancestors testing all three, innermost winning. The implementation ships texlab's own set, including the bare spellings §3 omitted.
• But texlab cannot rescue a root we get wrong. Every arm of that walk searches workspace.iter() — documents already loaded — and the workspace is built from the folders the client supplies. Observed directly: with rootUri at chapters/, no ancestor marker (.texlabroot included) widened texlab's view, and its dependency graph never reached the parent document; with rootUri at the marker directory, the parent resolved whether or not a marker was present.

So config.latex.root IS the project scope. Revision 2 framed the resolver as choosing between plausible roots that texlab might refine. It does not refine. The resolver is the whole value of the lane for a multi-file thesis, not a nicety — which is the opposite of how §2's "Slice 1 is one config entry" reads, and worth stating plainly.

(Also observed rather than assumed: bare texlab answers initialize over stdio, so args = {} is correct and the run subcommand is unnecessary.)

4. Open questions

Q#LX1 — does texlab need settings or init_options?

It pulls configuration via workspace/configuration under a texlab section, which pmacs answers (#13). An empty section takes defaults, as the Go entry does for gopls.

My vote: ship nothing. Build-on-save and forward-search are the two candidates and both are opinionated; forward-search additionally needs a configured viewer, so a default would be wrong for most machines. Users override through the same init.lua seam as the other fourteen.

Q#LX4 — do Haskell and OCaml belong in this lane at all? (renumbered — see below)

With HLS installed, Haskell is now the same shape as LaTeX: one entry, no new dependency. But the argument against it never rested on the dependency. The .hs files here are levineuwirth.org's Hakyll generator, edited rarely; HLS is version-coupled to GHC and is a large resident process for a language touched a few times a year.

My vote: LaTeX only in this lane. Add Haskell when there is use evidence, which is a one-line change at that point. OCaml needs ocaml-lsp-server via opam (not packaged for Arch) and is not close.

Renumbered from Q#HS1 deliberately. The merged docs/latex-grammar-math-substrate-framing.md already uses Q#LX2 for a different question — its grammar vendoring source (:83) — so revision 1's Q#LX2 collided with a live ID in the same language area. This document's LaTeX questions are Q#LX1 and the root question in §3; the language-scope question takes Q#LX4 to avoid a second collision.

Q#LX3 — does this touch multi-root LSP affinity? — RESOLVED, and revision 1 read a stale line

Revision 1 called this "the one item that could argue for deferring Slice 1", on the basis that multi-root affinity was in flight.

It merged as PR #161. COHERENCE.md:124 lists it among landed coherence work, and :867 says "First slice landed (PR #161)". Only :1669 still says "first slice in flight" — and that line contradicts the other two within the same document.

So the deferral argument dissolves: a LaTeX entry keyed like the existing servers rides the convention that already landed. The COHERENCE.md:1669 inconsistency is real and should be fixed, but by whoever next touches §20 — not smuggled into this lane.

5. Coherence impact (§20)

• Journey steps touched: none. This adds a row to an existing registry; no new surface, keybinding, or panel.
• Interaction islands: none added.
• Config registry adoption: yes, and only that. One entry in the existing pmacs.lsp.config table, overridable from init.lua by the same mechanism as the fourteen already there.
• Background-work attribution (§9): unchanged, and NOT improved. texlab spawns under the existing LSP supervision path with no new lifecycle — but it is another process that appears in *lsp* and whose requests appear in *workers* with nothing joining them. The worker-identity lane owns that; this lane neither helps nor worsens it.
• §20 classification: WIRING, not model. It surfaces machinery that already exists rather than adding a runtime entity — and §2 shows it is more purely wiring than revision 1 thought.

6. Verification

• A .tex buffer attaches texlab, witnessed end to end rather than by asserting the config table's contents.
• Detection is unchanged: .tex/.latex/.sty/.cls still resolve to latex via the grammar path (§2), asserted so that a later "helpful" filetype-map addition cannot be mistaken for the thing that made it work.
• The root resolver returns the marker directory, witnessed on a fixture with a latexmkrc above a chapters/ subdirectory — the thesis shape, which is the case a file-directory root gets wrong.
• It falls back to the file's own directory with no marker present.
• .git does NOT become the root (§3) — a fixture with a repository above a document directory, asserting the document directory wins. This is the case where copying the other entries' instinct is wrong, so it is pinned.
• A missing texlab surfaces guidance, through the existing spawn-failure path (#204) — asserted, not assumed, since that path is what makes the failure honest.
• Fixtures bound project detection with pmacs.project.set_search_boundary. R8 was a fixture letting detection escape into the developer's environment; a LaTeX root fixture is exactly that hazard's shape.

What this will NOT prove: that texlab resolves multi-file \input graphs correctly (that is texlab's job, not pmacs's), or that Haskell and OCaml work (Q#LX4).

7. Not in scope

New tree-sitter grammars — Haskell and OCaml would have LSP without highlighting, a real asymmetry that must be stated in the PR rather than discovered by a user. Any change to Lean, which needs none. Math/typesetting work (#172 owns it). Any change to the LSP spawn-failure surface (#204). Scanning for \documentclass to find a root document (§3). Fixing COHERENCE.md:1669's stale multi-root line (Q#LX3) — real, but another lane's edit. Haskell and OCaml entries (Q#LX4).