---
id: AGD-0013
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE
status: accepted
created: 2026-03-31
resolved: 2026-03-31
decision: DEC-0010
tags:
  - studio
  - editor
  - workspace
  - write
  - read-only
  - vfs
  - frontend-boundary
---

## Pain

O `Code Editor` do Studio ja saiu da fase de abertura somente leitura e agora existe pressao para iniciar a wave de edicao de arquivos.

Mas o recorte pedido nao e "liberar escrita para tudo".
O recorte correto e mais estreito:

- editar apenas arquivos aceitos pelo sistema;
- manter todos os arquivos relacionados ao frontend (`FE`) em `read-only` nesta etapa;
- e evitar que o editor misture, por inferencia, tres conceitos diferentes:
  - arquivo suportado para abrir,
  - arquivo elegivel para highlight/presentacao,
  - arquivo elegivel para mutacao e persistencia.

Se isso nao for fechado agora, a wave de escrita corre risco de nascer com uma regra pobre:

- ou o editor libera escrita para qualquer texto suportado;
- ou empilha `ifs` locais no `EditorWorkspace`;
- ou trata "arquivo do FE" apenas como detalhe visual, sem uma politica operacional clara de mutabilidade.

## Context

Domain owner: `studio`
Owner surface: `docs/specs/studio`

Superficies e referencias relevantes:

- `docs/specs/studio/5. Code Editor Workspace Specification.md` ainda trava a wave atual como `read-only`;
- `docs/specs/studio/6. Project Document VFS Specification.md` ja moveu classificacao de suporte e abertura de documento para `prometeu-vfs`;
- `discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md` consolida que a primeira wave do editor foi propositalmente somente leitura;
- `discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md` consolida que o editor deve consumir um boundary documental, nao virar owner de runtime de filesystem;
- `FilesystemProjectDocumentVfs` hoje diferencia:
  - arquivos `json`/`ndjson`,
  - arquivos `bash`,
  - arquivos do frontend pela linguagem registrada,
  - e `text` generico;
- `EditorWorkspace` ainda marca o `CodeArea` como `setEditable(false)`, ou seja, a wave de escrita exigira revisao normativa e nao apenas um ajuste tecnico.

Clarificacao importante para esta discussion:

- "arquivo aceito" nesta agenda significa arquivo que o sistema aceita abrir como documento textual no boundary atual;
- isso nao implica automaticamente que o arquivo e editavel;
- "arquivo relacionado ao FE" tambem nao pode ficar como intuicao editorial solta;
- a fronteira precisa virar regra operacional explicita, provavelmente no boundary documental ou em politica derivada dele;
- a verificacao deve ficar no `prometeu-vfs`, usando o enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`.

## Open Questions

- [x] O criterio canonico de "arquivo aceito para edicao" deve ser o mesmo universo de documentos suportados para abrir; a politica de acesso do `prometeu-vfs` decide se cada documento suportado fica `read-only` ou `editable` nesta wave.
- [x] "Relacionado ao FE" deve ser definido no `prometeu-vfs` pelo enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`.
- [x] Fora do escopo classificado como `FE`, a wave editavel inicial fica limitada aos tipos textuais ja suportados hoje: `text`, `json`, `ndjson` e `bash`.
- [x] O bloqueio de escrita para FE deve usar o item `read-only` na status bar, com espaco para evoluir para icone de cadeado aberto/fechado e futuro toggle de edicao; arquivos `FE` `read-only` tambem devem mostrar alerta no topo informando que nao podem ser salvos e que qualquer alteracao sera perdida.
- [x] A politica de acesso documental deve morar sempre no `prometeu-vfs`, inclusive para `load` e `save`.
- [x] A primeira wave de edicao inclui snapshot em memoria para documentos editaveis e persistencia em disco no `save` a partir desse snapshot.
- [x] O menu global `Save` nao deve ser usado para este fluxo; `save` e acao local do editor e deve viver numa barra de comandos no topo do editor, inicialmente com `Save` e `Save All`.
- [x] Tabs com arquivos FE `read-only` podem coexistir com tabs editaveis nao-FE no mesmo workspace, com estados visuais diferentes.
- [x] Os arquivos editaveis desta wave nao fazem parte da build em si.
- [x] O snapshot editavel em memoria desta wave deve permanecer contido e separado do snapshot documental usado pelos fluxos que participam da build.

## Options

### Option A - Liberar escrita para todo arquivo textual suportado
- **Approach:** Tratar todo `VfsTextDocument` como potencialmente editavel, exceto binarios ou sem handler.
- **Pro:** Menor custo inicial e quase nenhum metadado novo.
- **Con:** Viola diretamente o recorte pedido, porque arquivos de FE tambem passariam a ser editaveis ou exigiriam excecoes tardias e espalhadas.
- **Maintainability:** Baixa. A regra nasce ampla demais e depois precisa ser recortada por remendos.

### Option B - Manter suporte no VFS e derivar editabilidade so no `EditorWorkspace`
- **Approach:** O `prometeu-vfs` continua apenas dizendo se o arquivo abre, e o editor decide localmente se aquele documento fica `read-only` ou editavel.
- **Pro:** Mudanca pequena no boundary atual.
- **Con:** Regride a disciplina arquitetural recente; o editor volta a carregar regra de produto que deveria ser compartilhavel e auditavel.
- **Maintainability:** Media para baixa. Funciona rapido, mas enfraquece o boundary documental.

### Option C - Introduzir uma politica explicita de acesso documental acima do VFS
- **Approach:** Manter o `prometeu-vfs` como owner de suporte/abertura e adicionar uma classificacao explicita de `document access mode`, distinguindo ao menos `unsupported`, `read-only` e `editable`.
- **Pro:** Separa corretamente:
  - abrir o documento,
  - classificar o documento,
  - e decidir se esta wave permite mutacao.
- **Con:** Exige desenhar melhor onde essa politica mora e como ela chega ao editor sem inflar o contrato cedo demais.
- **Maintainability:** Forte. O sistema ganha uma regra clara e evolutiva para waves futuras.

### Option D - Colocar a politica de editabilidade dentro do contrato documental do `prometeu-vfs`
- **Approach:** O proprio boundary documental passa a devolver metadados normativos de acesso, incluindo se o documento e `editable` ou `read-only` nesta wave.
- **Pro:** Mantem suporte, tipo documental e politica de acesso no mesmo owner, reduzindo ambiguidade nos consumidores.
- **Con:** Exige desenhar com cuidado o snapshot editavel em memoria, o ciclo de `save` e a fronteira do que continua fora da build.
- **Maintainability:** Forte, desde que o contrato permaneça estreito e centrado em acesso documental, nao em UX.

## Discussion

As discussoes anteriores fecharam duas coisas importantes:

1. o editor nao deve fingir semantica de IDE cedo demais;
2. o editor nao deve voltar a ser owner de concerns documentais que ja foram movidos para `prometeu-vfs`.

Isso significa que a wave de escrita precisa evitar dois erros simetricos:

- liberar mutacao ampla demais e quebrar o recorte de produto;
- ou resolver a restricao de FE com condicionais locais no `EditorWorkspace`, quebrando a separacao arquitetural que acabou de ser criada.

O ponto mais delicado aqui e que "arquivo textual aceito" e "arquivo editavel nesta etapa" ja nao sao a mesma coisa.
Hoje o sistema ja consegue abrir um conjunto de documentos textuais, inclusive documentos associados ao frontend.
Mas o pedido atual cria uma nova regra de produto:

- alguns arquivos suportados continuarao `read-only`;
- e isso nao acontece por incapacidade tecnica de abrir o arquivo, mas por decisao deliberada de wave.

Portanto, o modelo tende a precisar de uma superficie nova de classificacao.
Se ela nao existir, o editor fica tentado a usar heuristicas locais:

- `typeId == languageId`
- path em source roots
- extensao
- ou combinacoes desses sinais

Esse caminho e rapido, mas ruim.
Ele espalha a politica de mutabilidade pelo consumidor errado.

Tambem houve um fechamento importante para a decisao:

- o recorte canonico de `FE` deve ser verificado no `prometeu-vfs`;
- essa verificacao deve usar o enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`;
- e o editor deve apenas consumir essa classificacao pronta, sem rederivar a regra localmente.

Se isso nao for fechado, o time pode permitir escrita em arquivos do frontend por acidente apenas porque eles aparecem como `text`, `json` ou outro tipo textual generico.

Outro fechamento importante desta agenda e que a primeira whitelist editavel nao cresce alem do que o produto ja suporta hoje como texto:

- `text`
- `json`
- `ndjson`
- `bash`

Ou seja, a wave inicial de edicao nao abre novo suporte documental.
Ela apenas permite mutacao em um subconjunto dos documentos textuais que ja existem hoje, excluindo o escopo classificado como `FE`.

Tambem ja existe um fechamento arquitetural relevante sobre ownership:

- a politica de acesso nao deve viver em policy layer solta no `studio`;
- `prometeu-vfs` deve ser o owner de `load`, `save` e da classificacao `read-only` versus `editable`;
- para documentos editaveis desta wave, o VFS deve manter um snapshot em memoria durante a sessao;
- quando houver `save`, o VFS persiste em disco o conteudo desse snapshot;
- o editor consome esse estado e dispara a intencao de salvar, mas nao reimplementa a politica nem o fluxo de persistencia.

Tambem ficou fechado que o universo canonico de documentos continua sendo o conjunto suportado pelo VFS.
O que muda nao e o universo de abertura, mas a politica de acesso aplicada a cada documento suportado:

- alguns suportados permanecem `read-only`, como o escopo de `FE`;
- outros suportados podem entrar como `editable` nesta wave;
- e essa decisao continua centralizada no `prometeu-vfs`.

Isso empurra a agenda com mais forca para a direcao de `Option D`.

Outro limite importante tambem ficou explicitado:

- os arquivos editaveis desta wave nao participam da build em si;
- portanto, a wave de escrita nao pode inferir integracao com pipeline, recompilacao, invalidacao de artefatos ou qualquer contrato de build;
- o escopo aqui e documental/editorial, nao de toolchain.
- isso tambem significa que o snapshot editavel em memoria nao deve se misturar com snapshots documentais ou entradas que alimentem a build;
- deve existir contencao clara entre:
  - o estado editorial temporario usado pela sessao de edicao;
  - e o estado documental/build-facing que outros fluxos do sistema possam consumir.

Essa contencao importa porque "ter snapshot em memoria" nao pode virar permissao implicita para o restante do produto observar rascunhos editoriais como se fossem input canonico de build.

A direcao mais coerente hoje parece ser preservar o boundary documental e introduzir um conceito explicito de politica de acesso.
Essa politica pode morar:

1. dentro do `prometeu-vfs`, se quisermos que o owner documental responda tambem pela mutabilidade da wave;
2. ou numa camada de policy ainda no dominio `studio`, mas acima do VFS, desde que o `EditorWorkspace` continue apenas consumindo a decisao pronta.

Com o fechamento atual, a agenda ja converge para descartar a segunda alternativa.
O que parece fraco e empurrar isso para o `EditorWorkspace`, e o usuario tambem ja fechou que a politica de acesso deve passar sempre por `prometeu-vfs`.

No plano de UX, a direcao tambem ficou suficiente para a proxima etapa:

- o estado `read-only` de `FE` deve aparecer na status bar;
- essa superficie pode evoluir mais tarde para um toggle explicito de habilitar/desabilitar edicao por arquivo;
- o `prometeu-vfs` deve, portanto, ja nascer pensando em contexto persistente de acesso por documento;
- `Save` e `Save All` nao pertencem ao menu global do shell e sim ao editor, em uma barra de comandos propria no topo;
- arquivos `FE` `read-only` nao podem ser salvos;
- ao abrir esse tipo de arquivo, o editor deve mostrar um alerta no topo informando que ele e `read-only` e que qualquer alteracao sera perdida.

Tambem vale registrar desde ja a implicacao para um futuro `prometeu-lsp` integrado ao Studio:

- o objetivo nao e portar o suporte das linguagens Prometeu para VSCode ou para um editor externo;
- portanto, a agenda de escrita nao deve introduzir dependencia de protocolo externo como fundamento da edicao;
- um futuro `prometeu-lsp` integrado deve ser tratado como consumidor semantico in-process ou Studio-owned acima do mesmo substrate de sessao, e nao como dono da politica de acesso documental;
- esse consumidor futuro deve observar o estado documental/snapshots editoriais necessarios para analise, sem colapsar a contencao entre estado editorial temporario e inputs canonicos de build;
- `read-only` para `FE` nesta wave significa apenas bloqueio de mutacao editorial, nao proibicao de leitura ou analise semantica futura;
- a integracao semantica continua sendo tema de decisao propria e nao deve ser inferida automaticamente a partir desta wave de escrita.

Observacao cravada para o proximo ciclo:

- quando o escopo de `FE` for liberado para edicao, o `prometeu-lsp` integrado ao Studio deve entrar em questao como consumidor do conteudo disponibilizado pelo `prometeu-vfs`;
- para documentos abertos, a analise deve enxergar o snapshot em memoria da sessao;
- para documentos nao abertos, a analise pode ler o estado em filesystem exposto pelo mesmo boundary;
- isso reforca que `prometeu-vfs` precisa permanecer como substrate documental canonico do editor e da futura analise semantica integrada.

## Resolution

Esta agenda convergiu para uma direcao suficiente para `decision`.

Recomendacao final: evoluir para uma decisao que introduza uma classificacao explicita de acesso documental para o `Code Editor`, separando:

1. arquivo nao suportado;
2. arquivo suportado porem `read-only`;
3. arquivo suportado e editavel.

Fechamentos aceitos:

- manter todo arquivo relacionado ao `FE` em `read-only` nesta wave;
- deixar o `prometeu-vfs` verificar se o `typeId` do documento cai no conjunto de `allowedExtensions` do `FrontendSpec`;
- manter como universo canonico os mesmos documentos suportados para abrir, sem criar registro paralelo de elegibilidade fora do `prometeu-vfs`;
- limitar a wave editavel inicial, fora do escopo de `FE`, aos tipos ja suportados hoje: `text`, `json`, `ndjson` e `bash`;
- fazer `prometeu-vfs` ser o owner de `load`, snapshot editavel em memoria e `save` em disco para esses documentos;
- tratar essa wave como escopo documental que nao participa da build em si;
- manter contencao explicita entre snapshot editorial em memoria e qualquer snapshot/build-input de carater canonico;
- expor o estado `read-only` de `FE` na status bar, com espaco para futura evolucao a toggle por arquivo;
- adicionar uma barra de comandos no topo do editor com `Save` e `Save All`, em vez de usar o menu global do shell;
- permitir coexistencia de tabs `read-only` de `FE` com tabs editaveis nao-`FE`;
- e mostrar alerta no topo para arquivos `FE` informando que sao `read-only`, nao podem ser salvos e que qualquer alteracao sera perdida.
- registrar que um futuro `prometeu-lsp` integrado ao Studio deve consumir o mesmo substrate de sessao/documentos sem virar owner da politica de acesso ou forcar compatibilidade com editor externo.

Next step suggestion: converter esta agenda em `decision` normativa para propagar a wave de escrita controlada do editor para specs, plano e implementacao.