---
id: LSN-0047
ticket: studio-new-lsp-api-and-v1-boundary
title: Project-Scoped LSP Boundary and Protocol Containment
created: 2026-05-07
tags: [studio, lsp, vscode, protocol, api, boundary, compiler]
---

## Context

After the legacy embedded editor stack was removed, Prometeu needed a new LSP baseline without repeating the old mistake of collapsing protocol, session lifecycle, host UI, and semantic ownership into one module.

The main architectural pressure came from two facts:

- the VS Code extension already existed as a real LSP client over TCP,
- and the compiler already existed as the canonical owner of semantic behavior.

That meant the missing piece was not "add editor features first". The missing piece was a strict boundary that let the Studio host, the protocol adapter, and the compiler evolve without contaminating each other.

## Key Decisions

### Keep `lsp-api` Minimal and Internal

**What:**
`lsp-api` became a narrow internal Studio boundary, starting with project-scoped lifecycle operations such as boot and shutdown instead of mirroring the LSP protocol.

**Why:**
The Studio needed a reusable internal service boundary, not a second copy of the external wire protocol.

**Trade-offs:**
The API starts intentionally small and may need explicit growth later, but that is safer than locking protocol-shaped DTOs into the internal architecture too early.

### Contain `LSP4J` and Protocol DTOs Inside `lsp-v1`

**What:**
`lsp-v1` became the only concrete protocol adapter and the only module allowed to depend on `LSP4J`.

**Why:**
Protocol libraries are integration details. If they leak outward, the host architecture starts depending on the current transport and implementation framework instead of on stable domain boundaries.

**Trade-offs:**
This forces explicit mapping layers and a little more ceremony, but it keeps protocol churn from infecting the rest of the codebase.

### Make the Server Lifecycle Project-Scoped

**What:**
The LSP server now belongs to project open/close lifecycle instead of global Studio process startup.

**Why:**
Project scope is the real ownership boundary for source roots, compiler context, and editor-facing behavior.

**Trade-offs:**
Lifecycle wiring is slightly more involved, but resource ownership becomes predictable and multi-project behavior stays sane.

### Keep `compiler` as Semantic Owner Even in a Dumb First Wave

**What:**
The baseline server remained intentionally simple in behavior, but its request handling already routes through compiler-facing bridge seams.

**Why:**
A "temporary mock" becomes dangerous when it also becomes the architecture. The repository needed a structurally correct baseline before adding semantic depth.

**Trade-offs:**
Wave 1 delivered less feature richness, but it created a safe foundation for later layering.

## Patterns and Algorithms

### Pattern: Internal Boundary, External Adapter

The stable split is:

1. `lsp-api` exposes internal lifecycle operations,
2. `lsp-v1` speaks protocol and transport,
3. `compiler` owns semantic and analysis behavior,
4. the VS Code extension remains an ordinary external LSP client.

### Pattern: Build the Seams Before the Features

The server can begin "dumb" in capability coverage if:

- the lifecycle boundary is already correct,
- compiler access already flows through explicit bridge services,
- and protocol containment is already enforced.

That sequence is safer than shipping richer features on top of a blurred module boundary.

## Pitfalls

- Do not let `lsp-api` grow into a shadow copy of the LSP protocol.
- Do not import `LSP4J` outside `lsp-v1`, even for convenience.
- Do not move semantic ownership into the protocol adapter just because the adapter is the caller-facing layer.
- Do not boot a global server for the entire Studio process when the actual ownership boundary is the project session.
- Do not treat a connectivity mock as an acceptable long-term module shape.

## References

- `DEC-0032` Boundary normativo entre lsp-api, lsp-v1 e a extensao VS Code
- `PLN-0065` LSP Boundary and Module Scaffolding
- `PLN-0066` Project-Scoped LSP Server Lifecycle in Studio
- `PLN-0067` Compiler-Backed Dumb LSP Server Baseline

## Takeaways

- Protocol adapters should stay narrow and concrete; internal Studio boundaries should stay protocol-agnostic.
- Project-scoped lifecycle is the correct owner for the LSP server.
- A dumb first wave is acceptable only when the architecture is already correct.