housekeeping

This commit is contained in:
2026-05-07 14:53:33 +01:00
parent 905d92afe7
commit 0e6a2cd5bc
16 changed files with 234 additions and 1303 deletions
@@ -1,128 +0,0 @@
---
id: AGD-0035
ticket: studio-new-lsp-api-and-v1-boundary
title: Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code
status: accepted
created: 2026-05-05
resolved: 2026-05-05
decision: DEC-0032
tags: [studio, lsp, vscode, protocol, api, boundary]
---
## Pain
O stack legado de editor, `prometeu-lsp` e `prometeu-vfs` acabou de ser removido. O próximo passo natural é reconstruir o backend de linguagem, mas sem repetir o erro anterior de misturar engine semântica, transporte LSP, sessão editorial e host UI em um único desenho.
Ao mesmo tempo, já existe uma extensão em `tools/vscode-extension` que hoje sabe conectar via TCP em `127.0.0.1:7777` e falar LSP como cliente real. Isso reduz incerteza no lado do FE, mas aumenta a exigência arquitetural do backend: o servidor novo precisa nascer com boundary correto.
O risco central é reintroduzir acoplamento acidental entre:
- contratos internos de linguagem;
- transporte externo LSP;
- implementação concreta baseada em `LSP4J`;
- e necessidades específicas do VS Code.
## Context
- O cleanup do stack legado foi fechado por `DEC-0031`.
- A extensão VS Code já existe em `tools/vscode-extension`.
- A extensão usa `vscode-languageclient` e conecta por socket TCP configurável.
- O usuário quer explicitamente que `LSP4J` **não vaze** de `lsp-v1`.
- A intenção geral do produto é que o Studio fale a própria língua internamente e exponha adapters externos para FEs, no mesmo espírito já discutido para integrações como Tiled.
Hoje, a pergunta não é "como implementar o LSP inteiro", mas sim:
- que módulos recriar;
- qual boundary o `lsp-api` realmente deve carregar;
- e qual responsabilidade cabe a `lsp-v1` como adapter concreto.
Também já existe um direcionamento adicional do produto:
- `lsp-v1` deve consumir serviços existentes de `compiler`;
- `lsp-api` deve expor funcionalidades reutilizáveis por outras partes do sistema;
- o bootstrap do servidor deve acontecer quando um projeto é aberto, e o shutdown quando o projeto é fechado;
- a API pode começar mínima, por exemplo com `boot server` e `shutdown server`, e crescer só quando houver necessidade real.
## Open Questions
- [x] O `lsp-api` deve expor contratos próprios de domínio/serviço ou DTOs alinhados diretamente ao protocolo LSP?
R: o lsp-api deve expor somente servicos que serao usados por outras partes do sistema, e nao ser um espelho do protocolo.
- [x] O `lsp-v1` deve ser somente um adapter `LSP4J` sobre serviços internos de `compiler`, ou também pode carregar parte da orquestração de sessão?
R: O lsp-v1 deve conter o servidor e todo o necessario para falar LSP, incluindo DTOs e dependencias de LSP4J (e fazer uso de compiler quando necessario). o start e o stop do servidor podem ser chamados via lsp-api, mas a logica de orquestracao de sessao deve ficar dentro do lsp-v1.
- [x] O lifecycle de bootstrap/shutdown do servidor por projeto pertence ao `lsp-api`, ao `lsp-v1`, ou a outro serviço do Studio?
R: o contrato fica no lsp-api, mas a logica de orquestracao fica no lsp-v1. o lsp-api pode expor um contrato como `bootServer(project)` e `shutdownServer(project)`, mas a implementacao concreta e a logica de associar o servidor ao projeto fica no lsp-v1.
- [x] O canal de automação (`compile/build/run/debug`) deve viver fora do novo `lsp-api` desde o início?
R: o canal de automacao deve viver fora do lsp-api. nesse primeiro momento o foco principal deve ser o LSP e o comportamento editorial/semantico. o canal de automacao pode ser discutido e implementado separadamente, sem misturar responsabilidades.
- [x] O `tools/vscode-extension` deve continuar falando LSP puro em socket TCP, ou o produto precisa reservar outra estratégia de transporte já nesta fase?
R: o vscode-extension deve continuar falando LSP puro em socket TCP. o lsp-api deve ser agnóstico ao transporte, mas ainda aceito recomendacoes q sejam mais faceis ou performaticas.
## Options
### Option A - `lsp-api` como API diretamente moldada pelo protocolo LSP
- **Approach:** recriar `lsp-api` com tipos e serviços muito próximos da superfície do protocolo, deixando `lsp-v1` apenas como bootstrap `LSP4J` e roteamento para `compiler`.
- **Pro:** acelera integração com o cliente existente e reduz tradução entre camadas.
- **Con:** tende a tornar o protocolo externo dono do desenho interno; muda mal quando surgir outro FE ou outro adapter.
- **Maintainability:** fraca. O risco de vazamento conceitual do protocolo para dentro do domínio é alto, mesmo sem importar classes `LSP4J` fora de `lsp-v1`.
### Option B - `lsp-api` mínima e operacional; `lsp-v1` como adapter LSP4J que consome `compiler`
- **Approach:** `lsp-api` expõe uma surface mínima e reutilizável para o sistema, começando com operações como `boot server(project)` e `shutdown server(project)` e, no máximo, contratos estáveis que outras partes do Studio precisem enxergar. `lsp-v1` concentra a implementação concreta do servidor, depende exclusivamente de `LSP4J`, e consome os serviços do `compiler` para responder às capacidades LSP.
- **Pro:** respeita a regra de não vazamento de `LSP4J`, evita inflar a API cedo demais e alinha o lifecycle do servidor ao projeto aberto, não ao processo global do Studio.
- **Con:** exige disciplina para não transformar `lsp-api` em um espelho parcial do protocolo nem `lsp-v1` em um segundo backend semântico solto do `compiler`.
- **Maintainability:** forte. O backend nasce hexagonal e o custo de evolução fica mais previsível.
### Option C - Sem `lsp-api`; expor apenas um servidor LSP concreto em `lsp-v1`
- **Approach:** pular a separação e concentrar tudo em um único módulo novo de servidor, com contratos locais apenas package-private ou internos.
- **Pro:** menor custo inicial de scaffolding.
- **Con:** repete exatamente o tipo de colapso arquitetural que gerou o legado descartado; dificulta teste, substituição de transporte e integração com outros FEs.
- **Maintainability:** ruim. A velocidade inicial é comprada com dívida estrutural imediata.
## Discussion
O dado novo mais importante é que o cliente VS Code já está funcional como cliente LSP puro. Isso elimina a necessidade de desenhar o protocolo "pensando no editor". O editor já sabe falar LSP; quem precisa de disciplina agora é o Studio.
Isso empurra a arquitetura para uma separação bem objetiva:
- `lsp-api` não deve ser "API pública do protocolo";
- `lsp-api` deve ser uma API interna e mínima do backend de linguagem do Studio;
- `lsp-v1` deve ser o adapter LSP concreto e consumidor dos serviços de `compiler`;
- `LSP4J` deve existir exclusivamente em `lsp-v1`.
O ponto sensível é não confundir "API interna" com "engine concreta". Se `lsp-api` virar um lugar para pôr qualquer detalhe de sessão, thread, socket, `CompletableFuture` de transporte, ou estruturas do `LSP4J`, ele já nasce errado. Pelo direcionamento atual, a API deve começar deliberadamente estreita:
- boot do servidor por projeto;
- shutdown do servidor por projeto;
- e só depois crescer quando outro consumidor real do sistema exigir isso.
Também vale separar desde já o que não pertence ao LSP:
- `compile/build/run/debug` não devem entrar no `lsp-api` por conveniência;
- esses fluxos pertencem a um contrato de automação paralelo;
- o LSP deve se limitar ao que é comportamento editorial/semântico.
Outro ponto: o usuário já fixou que o Studio é o backend autoritativo e o cliente externo é só cliente. Isso reforça que o lifecycle do servidor precisa acompanhar o projeto aberto. Em outras palavras:
- abrir Studio não implica subir servidor LSP global;
- abrir projeto pode implicar subir o servidor LSP daquele projeto;
- fechar projeto deve encerrar o servidor correspondente.
As respostas atuais também fecharam um boundary operacional importante:
- quem "fala LSP" de verdade é o `lsp-v1`;
- `lsp-api` não é adapter nem espelho do protocolo;
- `lsp-api` existe para expor um boundary interno consumível pelo Studio;
- o contrato mínimo inicial pode ser pequeno, desde que suficiente para boot/shutdown por projeto;
- DTOs, tipos e dependências do protocolo podem existir em `lsp-v1` sem contaminar a API interna.
## Resolution
Direção recomendada para convergir:
1. recriar `lsp-api` como surface interna mínima e reutilizável do sistema, começando com bootstrap e shutdown por projeto;
2. recriar `lsp-v1` como adapter LSP/JSON-RPC concreto, com dependência exclusiva de `LSP4J`;
3. fazer `lsp-v1` consumir serviços existentes de `compiler`, em vez de reconstruir pipeline semântico próprio;
4. deixar a lógica concreta de orquestração de sessão e associação `projeto -> servidor` dentro de `lsp-v1`, mesmo quando o bootstrap/shutdown for disparado através de `lsp-api`;
5. tratar qualquer tipo `LSP4J` fora de `lsp-v1` como violação arquitetural;
6. manter `tools/vscode-extension` como cliente LSP puro em socket TCP;
7. discutir separadamente o contrato de automação para `compile/build/run/debug`, em vez de empurrá-lo para dentro do LSP.
Neste ponto, a agenda já tem direção clara o bastante para virar `decision`. O que ainda resta fechar depois disso é implementação, não escolha arquitetural principal.
@@ -1,85 +0,0 @@
---
id: AGD-0037
ticket: frontend-semantic-host-projection-flexibility
title: Frontend Semantic Vocabulary Flexibility and Host Projection
status: accepted
created: 2026-05-06
resolved: 2026-05-06
decision: DEC-0034
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
---
## Pain
The current discussion exposed an architectural tension:
- frontend semantic keys must remain frontend-owned and flexible,
- but VS Code prefers host-shaped semantic token categories and modifiers,
- and forcing frontend vocabularies into a rigid global taxonomy would collapse frontend ownership into host constraints.
If Prometeu treats VS Code semantic categories as the canonical semantic contract, the frontend loses semantic freedom and the wrong layer starts owning language meaning.
## Context
Domain owner: `compiler/general`
This discussion extends `DEC-0033` rather than replacing it.
`DEC-0033` already locked that visual themes are frontend-owned and hosts are adapters.
What remained implicit was how a frontend-owned semantic vocabulary should adapt to host capabilities when the host prefers a different semantic model.
The key clarification is:
- the frontend semantic vocabulary remains canonical,
- host adaptation is declarative projection,
- host projection does not become the canonical semantic contract.
## Open Questions
- [x] Should Prometeu define a rigid global semantic token taxonomy shared by every frontend?
R: no. Each frontend keeps its own vocabulary.
- [x] How should VS Code consume flexible frontend vocabularies without becoming the owner of semantic meaning?
R: through a frontend-authored host projection for VS Code.
- [x] Does this revise `DEC-0033`?
R: it complements `DEC-0033` by clarifying semantic vocabulary and host projection responsibilities.
## Options
### Option A - Canonicalize around VS Code token types
- **Approach:** Force frontends to express semantic meaning in a shared VS Code-shaped taxonomy.
- **Pro:** Simplifies host adaptation.
- **Con:** Makes the host model canonical and removes frontend semantic freedom.
- **Maintainability:** Poor. It solves adapter simplicity by weakening frontend ownership.
### Option B - Keep frontend vocabularies canonical and add declarative host projection
- **Approach:** Let each frontend define its own semantic keys and publish host projection metadata that explains how a host such as VS Code should adapt those keys.
- **Pro:** Preserves frontend semantic ownership while keeping host adaptation mechanical.
- **Con:** Requires an additional contract layer.
- **Maintainability:** Strong. Ownership stays correct and adapters remain declarative.
## Tradeoffs
Option A would make the current VS Code situation easier, but only by moving semantic authorship to the wrong layer.
Option B adds contract surface, but that surface is the correct one because it keeps the frontend canonical and makes host projection explicit rather than implicit.
## Recommendation
Adopt Option B.
Frontend semantic keys remain canonical and flexible.
Hosts such as VS Code consume a declarative projection authored by the frontend for that host.
## Discussion
This discussion is intentionally narrow.
It does not reopen the frontend-owned visual theme decision.
It only clarifies that semantic vocabulary itself must also remain frontend-owned, and that host adaptation must be expressed as projection rather than normalization into a rigid shared taxonomy.
## Resolution
Accepted on 2026-05-06.
Prometeu keeps frontend-owned semantic vocabularies flexible and introduces declarative host projection as the adaptation mechanism for hosts such as VS Code.