prometeu-studio/discussion/workflow/agendas/AGD-0014-studio-editor-frontend-edit-rights.md

---
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.