prometeu-studio/discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md

---
id: DEC-0035
ticket: pbs-lsp-editor-assistance-wave-1
title: Wave 1 de assistencia editorial via LSP para PBS no VS Code
status: accepted
created: 2026-05-08
accepted: 2026-05-08
agenda: AGD-0038
plans: [PLN-0075, PLN-0076, PLN-0077]
tags: [studio, lsp, vscode, compiler, compiler-pbs, editor, completion, hover, signature-help]
---

## Context

O stack atual de PBS no VS Code ja entrega diagnostics basicos e semantic highlighting frontend-owned, mas ainda nao oferece assistencia editorial minima para escrita cotidiana de codigo.

Hoje:

1. nao existe `completion`;
2. `hover` existe apenas como placeholder;
3. nao existe `signature help`;
4. o servidor ainda nao anuncia capabilities correspondentes para essas superficies;
5. o compiler e o frontend PBS ja possuem informacao semantica, de linking, stdlib e metadata suficiente para nao precisarmos inventar uma segunda semantica local na extensao.

Esta decisao trata apenas da primeira wave de assistencia editorial para PBS no VS Code.
Ela nao cobre formatter, identacao automatica robusta, quick fixes, `go to definition`, `references`, `rename` nem code actions gerais.

## Decision

O repositório SHALL entregar uma wave 1 de assistencia editorial via LSP para PBS no VS Code com tres superfícies funcionais:

1. `completion`;
2. `hover`;
3. `signature help`.

Esta wave SHALL ser considerada valida quando essas tres superfícies permitirem:

1. descoberta minima de API;
2. leitura de assinatura em simbolos e chamadas;
3. ajuda de chamada sem dependencia de conhecimento semantico local na extensao VS Code.

Esta decisao ALSO locks que:

1. `completion`, `hover` e `signature help` MUST nascer sobre uma mesma base editorial compiler-backed;
2. o LSP MUST ser o owner operacional da assistencia editorial;
3. a extensao VS Code MUST atuar apenas como cliente/adaptador do protocolo, e MUST NOT reconstruir semantica propria para simbolos, members ou assinaturas;
4. heuristicas locais no LSP MAY existir apenas como complemento temporario e estritamente limitado para lacunas nao resolvidas, mas MUST NOT virar uma segunda semantica canônica;
5. `go to definition`, formatter, identacao automatica robusta, quick fixes, `references`, `rename` e code actions amplas MUST ficar fora desta wave.

## Rationale

As tres features desta wave respondem essencialmente ao mesmo conjunto de perguntas:

1. que simbolo eh este?
2. quais members ele expõe?
3. qual assinatura ele tem?
4. de onde ele vem?

Implementa-las por caminhos tecnicos diferentes introduziria:

1. duplicacao entre parser local, heuristicas e linking;
2. incoerencia entre o que aparece em `completion`, `hover` e `signature help`;
3. retrabalho na wave seguinte.

Portanto, a primeira entrega precisa nascer sobre uma base editorial unificada, reaproveitando o que o compiler e o frontend PBS ja sabem sobre:

1. escopo local;
2. imports e aliases;
3. stdlib;
4. builtin types;
5. services, hosts, structs, enums, constructors, functions e methods.

## Technical Specification

### 1. Shared Editorial Resolution Surface

`compiler/pbs` e `studio/lsp` MUST introduzir uma superficie editorial resolvida comum para uso de `completion`, `hover` e `signature help`.

Essa superficie MUST ser capaz de responder, de forma compiler-backed:

1. identidade do simbolo;
2. `kind` do simbolo;
3. modulo/origem quando relevante;
4. assinatura ou shape quando aplicavel;
5. members disponíveis para receivers reconhecidos;
6. documentacao opcional quando existir, sem bloquear esta wave.

Essa superficie MAY ser exposta por novos modelos internos do compiler, novos adapters no bridge do LSP, ou ambos.
Mas ela MUST permanecer derivada do compiler e MUST NOT ser reautoriada na extensao.

### 2. Completion Scope

`completion` MUST ser entregue como superfície minima utilizavel.

Na wave 1, isso MUST cobrir pelo menos:

1. keywords da linguagem;
2. nomes locais em escopo;
3. simbolos importados/publicos relevantes;
4. members apos `.` para superfícies reconhecidas, incluindo `service`, `host`, `builtin type`, `struct`, e call surfaces relacionadas.

`completion` SHOULD expor labels, kinds e detalhes coerentes com a mesma base usada por `hover`.

`completion` MUST NOT depender de tabela hardcoded na extensao para stdlib ou members de PBS.

### 3. Hover Scope

`hover` MUST deixar de ser placeholder e passar a ser simbolo-resolved.

Na wave 1, o hover MUST incluir quando disponivel:

1. `kind` do simbolo;
2. assinatura quando aplicavel;
3. modulo/origem quando relevante;
4. tipo ou shape basico quando isso existir de forma confiavel.

`hover` MAY incluir documentacao textual opcional.
Mas a autoria de documentacao em PBS, incluindo eventual anotacao como `Document(...)`, MUST seguir discussao separada e MUST NOT bloquear esta wave.

### 4. Signature Help Scope

`signature help` MUST ser implementado para chamadas de:

1. funcao;
2. metodo;
3. construtor.

Na wave 1, ele MUST informar:

1. a assinatura ativa;
2. o parametro ativo;
3. labels coerentes com a mesma representacao de assinatura usada no hover.

`signature help` MUST usar a mesma base editorial de resolucao usada por `completion` e `hover`.

### 5. Boundary Responsibilities

`compiler/pbs`:

1. MUST continuar sendo a fonte de verdade de semantica, linking e metadata relevante para simbolos e call surfaces;
2. MUST fornecer a base necessaria para resolucao editorial de simbolos, members e assinaturas.

`studio/lsp`:

1. MUST projetar essa base editorial em endpoints/protocol features adequados;
2. MUST anunciar as capabilities LSP necessarias para `completion`, `hover` e `signature help`;
3. MUST manter o transporte fiel ao modelo compiler-backed.

`tools/vscode-extension`:

1. MUST consumir o protocolo como cliente;
2. MUST NOT carregar tabelas paralelas de membros, stdlib ou assinaturas como fonte principal;
3. MAY conter apenas a logica estrutural normal de integração exigida pelo VS Code.

### 6. Documentation Preparation Rule

Esta wave MUST preparar um campo ou superfície opcional para documentacao editorial resolvida por simbolo.

Mas esta decisao ALSO locks que:

1. a surface de autoria dessa documentacao em PBS nao faz parte desta wave;
2. a sintaxe ou contrato de linguagem para documentacao authored deve ser discutido separadamente;
3. a ausencia dessa autoria nao bloqueia `completion`, `hover` nem `signature help` da wave 1.

### 7. Explicit Non-Goals

Esta decisao MUST NOT:

1. incluir formatter completo;
2. incluir identacao automatica robusta de documento;
3. incluir `go to definition`;
4. incluir `references`;
5. incluir `rename`;
6. incluir quick fixes;
7. incluir code actions mais amplas;
8. definir o modelo de autoria de documentacao em PBS.

## Constraints

1. A wave 1 MUST priorizar coerencia entre `completion`, `hover` e `signature help` sobre cobertura enciclopedica de todos os casos.
2. A extensao VS Code MUST permanecer thin; a inteligencia editorial MUST ficar no compiler/LSP.
3. A implementacao MUST favorecer evolucao futura para `definition`, `references`, `documentation`, e outras editor features sem exigir reescrita conceitual da base editorial.
4. A implementacao MUST evitar surfaces duplicadas para stdlib, aliases, members e signatures.
5. Qualquer plan derivado desta decisao MUST separar claramente:
   - base editorial compiler-backed;
   - projeção LSP/protocolo;
   - integração VS Code.

## Revision Log

- 2026-05-08: Initial draft from AGD-0038.
- 2026-05-08: Accepted and decomposed into PLN-0075, PLN-0076, and PLN-0077.