--- id: AGD-0014 ticket: studio-editor-write-wave-supported-non-frontend-files title: Definir a fase de FE read-only com LSP minimo no Code Editor do Studio status: accepted created: 2026-03-31 resolved: 2026-03-31 decision: DEC-0011 tags: - studio - editor - workspace - write - frontend-boundary - lsp - access-policy --- ## Pain A agenda `AGD-0013` fechou a primeira wave de escrita deixando todo arquivo de `FE` em `read-only`. Isso foi a decisao correta para destravar a wave inicial, e agora abre uma fase intermediaria mais segura: - manter `FE` em `read-only`; - introduzir um `prometeu-lsp` minimo integrado ao Studio; - e validar o ganho semantico em cima do substrate documental do `prometeu-vfs`. O tema de liberacao efetiva de edicao para `FE` deixa de ser escopo desta agenda. Ele deve seguir para outra discussion propria. ## Context Domain owner: `studio` Owner surface: `docs/specs/studio` Superficies e referencias relevantes: - `AGD-0013` aceitou que, nesta wave, arquivos de `FE` permanecem `read-only`; - `AGD-0013` tambem cravou que um futuro `prometeu-lsp` integrado ao Studio deve consumir o conteudo exposto por `prometeu-vfs`, usando snapshot em memoria para documentos abertos e filesystem para documentos fechados; - `docs/specs/studio/6. Project Document VFS Specification.md` fecha `prometeu-vfs` como substrate documental de sessao; - `discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md` consolida a regra de nao fingir semantica de IDE antes da hora; - `discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md` consolida que `prometeu-lsp` deve ser consumidor futuro acima de `prometeu-vfs`, nao seu substituto; - `prometeu-packer-api` ja oferece um exemplo util de flat packaging por superficie explicita, com pacotes como `dtos`, `messages`, `events` e subgrupos pequenos e nomeados; - a build e a analise semantica ja precisam continuar distintas: snapshot editorial em memoria nao pode virar input canonico de build por inferencia. Clarificacao importante desta agenda: - esta agenda nao libera edicao de `FE`; - esta agenda fecha apenas a fase `FE read-only + LSP minimo`; - a futura liberacao de mutacao e `save` para `FE` deve acontecer em outra discussion propria; - aqui o foco e definir o contrato minimo entre `prometeu-vfs` e `prometeu-lsp` integrado enquanto `FE` continua `read-only`. ## Open Questions - [x] Pode existir uma fase intermediaria com `FE` ainda `read-only`, mas ja com `prometeu-lsp` integrado minimo consumindo o `prometeu-vfs`; o direito de edicao do `FE` continua para uma fase posterior em outra discussion. - [x] Nesta fase `read-only`, o `prometeu-lsp` deve consumir o snapshot em memoria do `prometeu-vfs` para arquivos abertos e cair para filesystem apenas quando o arquivo estiver fechado. - [x] O escopo minimo do `prometeu-lsp` integrado nesta fase e `diagnostics`, `symbols`/`outline`, `definition` e `highlight`. - [x] `Completion` fica explicitamente fora desta fase minima por ainda nao existir direito de edicao de `FE`. - [x] Nao e necessario implementar agora persistencia de contexto de acesso por documento no `prometeu-vfs`, mas ja deve existir uma entidade de contexto onde esses valores possam ser consultados e alterados sob demanda, facilitando persistencia futura. - [x] O estado editorial em memoria de arquivos `FE` pode alimentar analise semantica sem nunca alimentar build; qualquer futura ponte com build fica fora desta agenda e de outra decisao propria. ## Options ### Option A - Misturar LSP minimo e futura liberacao de edicao na mesma agenda - **Approach:** Tentar resolver agora tanto a fase `read-only + LSP` quanto o futuro direito de edicao de `FE`. - **Pro:** Menos artefatos de workflow. - **Con:** Mistura readiness semantica com mutacao editorial e amplia demais o escopo. - **Maintainability:** Baixa. A agenda perde nitidez. ### Option B - Introduzir LSP minimo com FE ainda read-only, e liberar edicao depois em outra discussion - **Approach:** Primeiro integrar um `prometeu-lsp` minimo ao Studio enquanto arquivos de `FE` permanecem `read-only`; so depois, em uma fase seguinte, decidir a liberacao de `save` e mutacao editorial de `FE`. - **Pro:** Valida cedo a cadeia `prometeu-vfs` -> snapshots de sessao -> consumidor semantico, sem ainda assumir a responsabilidade de mutacao em arquivos de linguagem. - **Con:** Cria uma fase intermediaria a mais e exige disciplina para nao tratar "LSP minimo" como permissao implicita para editar. - **Maintainability:** Muito forte. Separa readiness semantica de direito de mutacao e reduz rework. ### Option C - Fazer uma fase minima ainda menor - **Approach:** Limitar o LSP minimo a `diagnostics` e talvez `symbols`, deixando `definition` e `highlight` para depois. - **Pro:** Reduz a primeira entrega semantica. - **Con:** Pode subentregar valor perceptivel e fragmentar demais a fase minima. - **Maintainability:** Media. So vale se a superficie tecnica ainda estiver imatura. ## Discussion O que a discussao atual ja deixa claro e que o `FE` tem peso diferente dos outros textos suportados hoje. Para `text`, `json`, `ndjson` e `bash`, a primeira wave editavel pode ser tratada como escopo editorial controlado: - `prometeu-vfs` carrega; - o editor altera; - o `prometeu-vfs` guarda snapshot; - e o `save` persiste em disco; - tudo isso sem envolver build nem semantica forte. Para `FE`, esse raciocinio parece insuficiente. O proprio caminho que foi cravado em `AGD-0013` indica a direcao correta: - quando `FE` for liberado, `prometeu-lsp` integrado entra em questao; - esse LSP deve consumir o mesmo substrate documental; - e o snapshot em memoria do VFS deve ser a verdade de analise para documentos abertos. O refinamento trazido agora melhora essa sequencia: - nao e necessario esperar a liberacao de edicao de `FE` para introduzir um `prometeu-lsp` minimo; - ao contrario, ter uma fase de `FE` ainda `read-only`, mas ja observavel semanticamente, parece um passo mais seguro; - isso deixa o time validar ingestao de snapshots, diagnosticos, outline ou outras leituras sem ainda assumir `save`, mutacao e UX de conflito para arquivos de linguagem. Isso tambem sugere que o tema de direito de edicao do `FE` deve sair desta agenda. Aqui basta fechar a fase de leitura semantica minima enquanto o `FE` continua bloqueado para mutacao. Tambem importa manter o boundary certo: - `prometeu-vfs` continua owner de documentos, snapshots e persistencia; - `prometeu-lsp` futuro consome esse estado para analise; - o editor continua owner de UX; - build continua fronteira separada. Tambem vale fechar desde ja um principio de organizacao da API: - o `prometeu-lsp` deve usar flat packaging tomando `prometeu-packer-api` como referencia; - isso favorece superficies explicitas para `dtos`, `messages`, `events` e tipos correlatos; - evita esconder o contrato do LSP em arvore profunda demais ou em pacotes acidentais por feature interna; - e ajuda a manter a fronteira publica do modulo legivel para Studio e consumidores futuros. Se isso for respeitado, um LSP integrado proprio do Studio faz mais sentido do que qualquer adaptacao para editor externo. O que interessa aqui e ter um consumidor semantico alinhado ao runtime documental do produto, nao compatibilidade com VSCode. O conjunto de ganhos mais plausivel para esta fase minima e: - `diagnostics`; - `documentSymbol`/`workspaceSymbol` e `Outline`; - `definition`; - `highlight` no `FE`. `Completion`, `rename`, code actions, formatting e direito de edicao devem ficar fora desta agenda. Tambem ficou fechado que: - nao precisamos implementar agora persistencia de contexto de acesso por documento no `prometeu-vfs`; - mas ja devemos agrupar esses valores em uma mesma entidade de contexto, para que possam ser buscados e alterados sob demanda; - isso deixa o caminho mais curto para persistir esse contexto depois, sem refazer a modelagem; - e o contrato nao deve bloquear a futura introducao de um toggle de `read-only`/edicao por arquivo. ## Resolution Recommended direction: seguir com **Option B**. Direcao recomendada neste momento: 1. o `FE` permanece `read-only` nesta agenda; 2. esta agenda fecha apenas a fase de `prometeu-lsp` minimo com `FE` ainda `read-only`; 3. essa fase trata o `prometeu-lsp` integrado como consumidor do conteudo exposto por `prometeu-vfs`; 4. para documentos de `FE` abertos, a analise observa o snapshot em memoria da sessao; 5. para documentos de `FE` fechados, a analise pode cair para o estado em filesystem; 6. `prometeu-vfs` continua owner de snapshots, persistencia e politica de acesso documental; 7. `prometeu-lsp` nao vira owner de `save`, de persistencia nem de politica de acesso; 8. esta agenda mira como escopo minimo `diagnostics`, `symbols`/`outline`, `definition` e `highlight`; 9. `completion`, `rename`, code actions, formatting e a liberacao de edicao de `FE` ficam para depois; 10. a futura liberacao de edicao de `FE` deve acontecer em outra discussion propria; 11. nenhuma fase desta agenda pode misturar automaticamente snapshot editorial com input canonico de build. 12. a API de `prometeu-lsp` deve preferir flat packaging no estilo de `prometeu-packer-api`, com superficies explicitas como `dtos`, `messages` e `events`. 13. o `prometeu-vfs` nao precisa implementar agora contexto persistente de acesso por documento, mas deve introduzir uma entidade de contexto unica para esses valores, de modo que leitura/mutacao sob demanda ja exista e a persistencia futura seja uma extensao natural. Next step suggestion: converter esta agenda em `decision` normativa para a fase `FE read-only + LSP minimo`, deixando a futura liberacao de edicao de `FE` para outra discussion.