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

id	ticket	title	status	created	resolved	decision	tags
AGD-0014	studio-editor-write-wave-supported-non-frontend-files	Definir a fase de FE read-only com LSP minimo no Code Editor do Studio	accepted	2026-03-31	2026-03-31	DEC-0011	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

• 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.
• 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.
• O escopo minimo do prometeu-lsp integrado nesta fase e diagnostics, symbols/outline, definition e highlight.
• Completion fica explicitamente fora desta fase minima por ainda nao existir direito de edicao de FE.
• 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.
• 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.