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,196 +0,0 @@
---
id: DEC-0032
ticket: studio-new-lsp-api-and-v1-boundary
title: Boundary normativo entre lsp-api, lsp-v1 e a extensao VS Code
status: accepted
created: 2026-05-05
accepted: 2026-05-05
agenda: AGD-0035
plans: [PLN-0065, PLN-0066, PLN-0067]
tags: [studio, lsp, vscode, protocol, api, boundary, compiler]
---
## Decision
O repositório SHALL reconstruir o stack de linguagem do Studio com separação explícita entre:
1. `lsp-api` como boundary interno do Studio;
2. `lsp-v1` como adapter LSP/JSON-RPC concreto;
3. `compiler` como owner dos serviços semânticos e de análise consumidos por esse adapter;
4. `tools/vscode-extension` como cliente externo que continua falando LSP puro via socket TCP.
Esta decisão ALSO locks os seguintes pontos:
1. `lsp-api` MUST NOT ser espelho do protocolo LSP;
2. `lsp-api` MUST expor apenas funcionalidades internas realmente consumíveis por outras partes do Studio;
3. `lsp-api` MAY começar mínima, por exemplo com contratos como `bootServer(project)` e `shutdownServer(project)`;
4. `lsp-v1` MUST concentrar o servidor LSP concreto, os DTOs de protocolo, o transporte e qualquer dependência de `LSP4J`;
5. `LSP4J` MUST NOT vazar para fora de `lsp-v1`;
6. `lsp-v1` MUST consumir serviços existentes de `compiler` em vez de reconstruir pipeline semântico próprio;
7. o lifecycle do servidor LSP MUST ser associado à abertura e ao fechamento de projeto, não à abertura global do processo Studio;
8. o atual `lsp-v1` presente hoje no repositório serve apenas como mock de conectividade VS Code ↔ Studio e MUST NOT ser tratado como padrão arquitetural, base estrutural ou referência de implementação do backend definitivo.
9. a primeira onda de implementação desta decisão SHALL priorizar arquitetura, lifecycle e separação de responsabilidades, mesmo que o comportamento LSP permaneça deliberadamente simples ou "dumb" por um período controlado.
## Rationale
O stack legado anterior foi removido justamente porque misturava responsabilidades erradas e criou boundaries frágeis entre UI, sessão, semântica e transporte.
Ao mesmo tempo, o projeto já tem dois fatos importantes:
1. a extensão VS Code já existe e já sabe atuar como cliente LSP puro;
2. o Studio já possui serviços de `compiler` que devem continuar sendo a fonte real de comportamento semântico.
Logo, o problema não é "inventar um cliente" nem "reescrever a semântica". O problema é definir corretamente:
1. o que é boundary interno reutilizável do Studio;
2. o que é adapter concreto de protocolo;
3. e onde termina a influência do protocolo externo.
Essa separação reduz acoplamento, melhora teste e evita que detalhes de `LSP4J` ou do transporte contaminem o restante da base.
Também existe uma prioridade explícita de rollout:
1. primeiro consolidar a arquitetura;
2. depois adicionar capacidade semântica por camadas;
3. sem obrigar a primeira implementação a já ser semanticamente rica.
Isso evita repetir o padrão anterior de crescer funcionalidade em cima de uma base estrutural errada.
## Technical Specification
### 1. Module Roles
`lsp-api` MUST ser tratado como módulo de boundary interno do Studio.
Ele SHALL:
1. expor somente contratos que façam sentido para outros consumidores internos do sistema;
2. permanecer agnóstico ao protocolo LSP concreto;
3. permanecer agnóstico a `LSP4J`;
4. permanecer agnóstico ao transporte TCP ou a qualquer detalhe de socket;
5. começar com surface mínima suficiente para o lifecycle do servidor por projeto.
`lsp-v1` MUST ser tratado como o primeiro adapter concreto do boundary acima.
Ele SHALL:
1. implementar o servidor LSP;
2. carregar os DTOs e tipos de protocolo que forem necessários para falar LSP;
3. carregar a dependência de `LSP4J`;
4. realizar a tradução entre o mundo do protocolo e os serviços internos consumidos;
5. concentrar a lógica concreta de sessão e associação `projeto -> servidor`.
### 2. LSP4J Containment
O repositório MUST tratar `LSP4J` como dependência exclusiva de `lsp-v1`.
Portanto:
1. nenhum tipo de `LSP4J` MAY aparecer em `lsp-api`;
2. nenhum tipo de `LSP4J` MAY aparecer em outros módulos do Studio;
3. nenhum contrato de `lsp-api` MAY depender semanticamente de tipos, nomes ou formas obrigadas pelo `LSP4J`;
4. qualquer vazamento de `LSP4J` para fora de `lsp-v1` SHALL ser tratado como violação arquitetural.
### 3. Compiler Ownership
`lsp-v1` MUST consumir serviços existentes de `compiler` quando precisar responder capacidades editoriais e semânticas.
Isso implica:
1. `lsp-v1` MUST NOT reconstruir uma engine semântica paralela por conveniência;
2. `lsp-v1` MUST preferir compor sobre entrypoints e serviços canônicos do `compiler`;
3. qualquer lacuna percebida no `compiler` para servir o novo backend SHALL ser tratada como evolução explícita do `compiler`, e não como autorização para duplicação semântica dentro de `lsp-v1`.
### 4. Server Lifecycle
O lifecycle do servidor MUST ser project-scoped.
Regras:
1. abrir o processo Studio MUST NOT implicitamente significar "subir um servidor LSP global";
2. abrir um projeto MAY disparar `bootServer(project)` através do boundary exposto por `lsp-api`;
3. fechar um projeto MUST disparar `shutdownServer(project)` para o servidor correspondente;
4. a implementação concreta desse bootstrap/shutdown e o vínculo entre projeto e instância do servidor MUST residir em `lsp-v1`.
### 5. Internal API Minimalism
`lsp-api` MUST nascer pequeno.
Ele SHALL:
1. expor apenas o que outro consumidor interno realmente precise enxergar;
2. evitar DTOs de protocolo sem necessidade;
3. evitar antecipar capacidades futuras sem consumidor real;
4. crescer somente quando houver pressão concreta de uso interno.
O contrato inicial mínimo aceito por esta decisão é:
1. `bootServer(project)`
2. `shutdownServer(project)`
Contratos adicionais MAY ser adicionados depois, mas não fazem parte do lock inicial desta decisão.
### 6. VS Code Transport
`tools/vscode-extension` SHALL permanecer cliente LSP puro via socket TCP nesta fase.
Isso implica:
1. a extensão atual pode continuar evoluindo nesse modelo;
2. `lsp-api` MUST permanecer agnóstico a esse transporte;
3. mudanças futuras de transporte MAY ser discutidas depois, mas não fazem parte do boundary normativo inicial.
### 7. Current Mock Status
O `lsp-v1` que existe hoje para testes de conectividade entre VS Code e Studio MUST ser tratado como mock transitório.
Ele MUST NOT:
1. servir de blueprint estrutural do novo servidor;
2. servir de contrato implícito do sistema;
3. servir de justificativa para manter responsabilidades colapsadas;
4. contaminar o padrão de código alvo do backend definitivo.
O backend definitivo SHALL priorizar:
1. separação clara de responsabilidades;
2. boundaries pequenos e explícitos;
3. código fácil de manter;
4. composição sobre serviços canônicos do `compiler`;
5. isolamento rígido do adapter de protocolo.
### 8. Implementation Wave 1
A primeira onda de implementação derivada desta decisão MUST focar em transformar o mock atual em uma estrutura sólida de trabalho.
Essa onda SHALL incluir:
1. `lsp-api` mínimo com bootstrap e shutdown por projeto;
2. `lsp-v1` organizado como adapter concreto limpo, mesmo que ainda responda um conjunto reduzido ou simplificado de capacidades;
3. boot do servidor quando o projeto abrir;
4. shutdown do servidor quando o projeto fechar;
5. isolamento explícito entre boundary interno, adapter de protocolo e consumo de `compiler`.
Essa onda MUST NOT ser bloqueada pela ausência de "carne semântica" completa.
Em outras palavras:
1. é aceitável manter um comportamento LSP inicial deliberadamente simples;
2. não é aceitável manter um padrão arquitetural improvisado só porque o comportamento ainda é simples;
3. a evolução semântica futura SHALL acontecer por camadas sobre a estrutura consolidada.
## Constraints
1. Esta decisão MUST preservar a separação entre boundary interno e adapter externo.
2. Esta decisão MUST preservar `compiler` como owner semântico do sistema.
3. Esta decisão MUST impedir vazamento de `LSP4J` para fora de `lsp-v1`.
4. Esta decisão MUST impedir que o mock atual de conectividade seja usado como padrão do produto.
5. Esta decisão MUST manter `compile/build/run/debug` fora do escopo do `lsp-api` nesta fase.
6. Qualquer plano derivado desta decisão MUST refletir explicitamente o lifecycle por projeto e a contenção de protocolo em `lsp-v1`.
7. O primeiro plano derivado desta decisão MUST priorizar a consolidação estrutural do servidor antes do enriquecimento semântico.
## Revision Log
- 2026-05-05: Initial draft from AGD-0035.
- 2026-05-05: Added explicit phase-1 rollout guidance to solidify architecture before semantic depth.
- 2026-05-05: Accepted and decomposed into PLN-0065, PLN-0066, and PLN-0067.
@@ -1,112 +0,0 @@
---
id: DEC-0034
ticket: frontend-semantic-host-projection-flexibility
title: Frontend semantic vocabularies remain canonical and hosts consume declarative projections
status: accepted
created: 2026-05-06
accepted: 2026-05-06
agenda: AGD-0037
plans: [PLN-0072, PLN-0073, PLN-0074]
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
---
## Decision
Prometeu SHALL keep semantic vocabularies frontend-owned and canonical.
Hosts such as VS Code SHALL consume declarative host projection data authored by the frontend instead of forcing frontend semantic keys into a rigid shared host taxonomy.
This decision locks the following normative points:
1. Each frontend MUST remain free to define its own semantic keys.
2. Prometeu MUST NOT introduce a rigid global semantic token taxonomy as the canonical contract for all frontends.
3. Host-facing semantic adaptation MUST happen through frontend-authored host projection metadata.
4. Host projection metadata MUST be declarative and MUST NOT become the canonical semantic vocabulary.
5. VS Code adaptation MUST consume the frontend semantic vocabulary plus its VS Code projection, not reinterpret semantic meaning ad hoc inside the extension.
## Rationale
The current stack already establishes frontend ownership over visual themes.
Without this complementary rule, semantic vocabulary itself could still drift toward host ownership because VS Code prefers a different semantic model than a frontend may naturally publish.
If the repository made VS Code token categories canonical, it would:
1. collapse frontend semantic freedom,
2. move semantic authorship into the host layer,
3. and make frontend evolution hostage to one specific adapter model.
Declarative host projection preserves the correct ownership boundary:
1. frontend defines semantic meaning,
2. frontend also defines how a given host should project that meaning,
3. host adapters translate mechanically.
## Technical Specification
### 1. Canonical Semantic Vocabulary
The canonical semantic vocabulary for a document language MUST live in that frontend's contract surface.
This implies:
1. semantic keys remain frontend-owned,
2. semantic keys MAY vary significantly between frontends,
3. semantic keys MUST NOT be rewritten into a mandatory repository-wide host-shaped taxonomy.
### 2. Host Projection Contract
Frontend metadata MUST evolve to support host projection descriptors.
At minimum, a host projection descriptor for VS Code MUST be capable of expressing:
1. which canonical semantic key is being projected,
2. which VS Code semantic token type should receive that key,
3. which VS Code semantic token modifiers, if any, should accompany that projection,
4. any fallback behavior needed when the host cannot represent the frontend key exactly.
The host projection descriptor MAY support other hosts later, but the first required host projection is VS Code.
### 3. Ownership Rules
Ownership SHALL be:
1. frontend owns semantic keys,
2. frontend owns host projection metadata,
3. LSP transports both,
4. the host adapter translates both.
The extension MUST NOT become the place where semantic meaning is hand-mapped or reauthored as code-driven policy.
### 4. Relationship to DEC-0033
This decision complements `DEC-0033`.
`DEC-0033` remains normative for:
1. frontend-owned visual theme contracts,
2. frontend-owned theme variants,
3. host adapter responsibilities for visual rendering.
This decision adds the semantic vocabulary clarification that `DEC-0033` left implicit:
1. semantic vocabularies remain frontend-owned and flexible,
2. host adaptation is projection, not normalization.
### 5. VS Code Adapter Rule
For VS Code specifically:
1. the extension MUST consume frontend-owned semantic keys,
2. the extension MUST consume frontend-authored VS Code projection metadata,
3. the extension MUST apply that projection mechanically,
4. the extension MUST NOT force every frontend into a single rigid shared semantic taxonomy to satisfy VS Code.
## Constraints
1. No plan derived from this decision may replace frontend semantic keys with a mandatory global host taxonomy.
2. Any plan touching VS Code semantic adaptation MUST include declarative host projection support.
3. Any plan touching LSP transport for semantic vocabularies MUST preserve frontend canonical keys.
4. This decision MUST be treated as complementary to `DEC-0033`, not as a rollback of frontend-owned theming.
## Revision Log
- 2026-05-06: Initial accepted decision from AGD-0037.