prometeu-studio/discussion/workflow/agendas/AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0013	studio-editor-write-wave-supported-non-frontend-files	Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE	accepted	2026-03-31	2026-03-31	DEC-0010	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

• 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.
• "Relacionado ao FE" deve ser definido no prometeu-vfs pelo enquadramento do typeId contra allowedExtensions do FrontendSpec.
• Fora do escopo classificado como FE, a wave editavel inicial fica limitada aos tipos textuais ja suportados hoje: text, json, ndjson e bash.
• 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.
• A politica de acesso documental deve morar sempre no prometeu-vfs, inclusive para load e save.
• A primeira wave de edicao inclui snapshot em memoria para documentos editaveis e persistencia em disco no save a partir desse snapshot.
• 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.
• Tabs com arquivos FE read-only podem coexistir com tabs editaveis nao-FE no mesmo workspace, com estados visuais diferentes.
• Os arquivos editaveis desta wave nao fazem parte da build em si.
• 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.