Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/decisions/DEC-0032-studio-new-lsp-api-and-v1-boundary.md
bQUARKz b0073cd7bd
implements PLN-0065
2026-05-05 15:50:55 +01:00

8.7 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0032 studio-new-lsp-api-and-v1-boundary Boundary normativo entre lsp-api, lsp-v1 e a extensao VS Code accepted 2026-05-05 2026-05-05 AGD-0035
PLN-0065
PLN-0066
PLN-0067
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.