housekeeping
This commit is contained in:
+106
@@ -0,0 +1,106 @@
|
||||
---
|
||||
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.
|
||||
+90
@@ -0,0 +1,90 @@
|
||||
---
|
||||
id: LSN-0048
|
||||
ticket: frontend-semantic-host-projection-flexibility
|
||||
title: Frontend-Owned Semantic Vocabularies with Declarative Host Projection
|
||||
created: 2026-05-07
|
||||
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Prometeu had already established that frontend-owned visual themes should remain canonical.
|
||||
The remaining semantic risk was subtler: VS Code prefers host-shaped token categories, and that pressure could easily turn the host taxonomy into the real source of semantic truth.
|
||||
|
||||
This discussion closed that gap by making semantic ownership explicit:
|
||||
|
||||
- the frontend keeps the canonical semantic vocabulary,
|
||||
- host adaptation is additional metadata,
|
||||
- and the adapter translates mechanically instead of inventing semantic policy.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Keep Frontend Semantic Keys Canonical
|
||||
|
||||
**What:**
|
||||
Each frontend remains free to define and evolve its own semantic keys, and those keys stay canonical across the stack.
|
||||
|
||||
**Why:**
|
||||
Semantic meaning belongs to the language frontend, not to a single host's preferred category system.
|
||||
|
||||
**Trade-offs:**
|
||||
Adapters must handle more varied vocabularies, but that is the correct cost of preserving frontend ownership.
|
||||
|
||||
### Add Declarative Host Projection Instead of Global Normalization
|
||||
|
||||
**What:**
|
||||
The frontend now authors host projection metadata describing how canonical semantic keys should map into VS Code token types, modifiers, and fallbacks.
|
||||
|
||||
**Why:**
|
||||
Hosts still need a practical adaptation path, but that adaptation should be explicit projection data rather than a hidden normalization rule.
|
||||
|
||||
**Trade-offs:**
|
||||
The contract grows an extra layer, but it stays declarative and prevents semantic meaning from being reauthored inside the adapter.
|
||||
|
||||
### Keep LSP and the Extension Mechanical
|
||||
|
||||
**What:**
|
||||
LSP transports canonical keys plus projection metadata, and the VS Code extension consumes both mechanically.
|
||||
|
||||
**Why:**
|
||||
If either layer starts hand-mapping semantic meaning, the host stack becomes the de facto author of language semantics.
|
||||
|
||||
**Trade-offs:**
|
||||
The transport and adapter need clearer model shapes, but their responsibilities stay cleaner and more reusable.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Pattern: Canonical Vocabulary Plus Per-Host Projection
|
||||
|
||||
The stable flow is:
|
||||
|
||||
1. frontend defines semantic keys,
|
||||
2. frontend defines host projections for those keys,
|
||||
3. LSP transports canonical keys and projection data together,
|
||||
4. the host adapter applies the projection without reinterpretation.
|
||||
|
||||
### Pattern: Mechanical Translation with Explicit Fallbacks
|
||||
|
||||
Projection metadata should say not only the preferred host token type, but also the fallback when the host cannot represent the frontend key exactly.
|
||||
That keeps fallback behavior visible and reviewable instead of implicit in adapter code.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Do not collapse frontend semantic keys into a repository-wide host taxonomy.
|
||||
- Do not hide semantic policy inside the VS Code extension just because the platform has its own token vocabulary.
|
||||
- Do not transport only host-shaped token types and discard canonical frontend identity.
|
||||
- Do not confuse projection metadata with the canonical semantic contract itself.
|
||||
|
||||
## References
|
||||
|
||||
- `DEC-0034` Frontend semantic vocabularies remain canonical and hosts consume declarative projections
|
||||
- `PLN-0072` Frontend Semantic Host Projection Contract
|
||||
- `PLN-0073` LSP Semantic Host Projection Transport
|
||||
- `PLN-0074` VS Code Semantic Host Projection Adapter
|
||||
- `DEC-0033` Frontend-owned visual theme spec as canonical presentation contract
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Semantic ownership stays with the frontend even when the host prefers a different taxonomy.
|
||||
- Host projection is the right adaptation mechanism; global normalization is not.
|
||||
- LSP and host adapters stay healthier when they translate declaratively instead of authoring semantic meaning.
|
||||
Reference in New Issue
Block a user