---
id: DEC-0009
ticket: studio-editor-document-vfs-boundary
title: Estabelecer `prometeu-vfs` como boundary documental de projeto para o Studio
status: in_progress
created: 2026-03-31
accepted: 2026-03-31
agenda: AGD-0012
plans:
  - PLN-0015
  - PLN-0016
  - PLN-0017
  - PLN-0018
tags:
  - studio
  - editor
  - workspace
  - vfs
  - filesystem
  - boundary
---

## Context

O `Code Editor` do Studio ja fechou sua primeira wave como shell editorial read-only, mas a implementacao concreta ainda instancia diretamente servicos filesystem-backed para:

- montar a arvore estrutural do projeto;
- abrir arquivos;
- carregar conteudo de documentos;
- e aplicar regras de suporte ou nao suporte a arquivos.

Isso mantem concerns de I/O e sincronizacao acoplados ao `EditorWorkspace`, quando o owner correto desses concerns deve ser um boundary documental de projeto.

Tambem ficou fechado na agenda que:

- esta etapa nao introduz novas capacidades editoriais alem das que o `EditorWorkspace` ja possui hoje;
- o estado documental precisa continuar vivo mesmo quando o `Code Editor` nao esta em foco;
- o `Project Navigator` nao deve ver filesystem diretamente;
- `prometeu-lsp` deve continuar reservado para a futura camada de protocolo/handlers;
- e packer/assets permanecem fora deste boundary.

## Decision

1. O repositório SHALL introduzir um novo modulo-base chamado `prometeu-vfs`.
2. `prometeu-vfs` SHALL ser o boundary documental de projeto consumido pelo Studio para `tree`, `open files` e `document content`.
3. O Studio MUST passar a tocar o disco atraves de `prometeu-vfs` para o escopo coberto por este boundary.
4. O escopo desta primeira wave MUST transportar apenas as capacidades hoje existentes no `EditorWorkspace`; nenhuma nova feature editorial SHALL ser adicionada nesta etapa.
5. `prometeu-vfs` SHALL viver no lifecycle de sessao de projeto do Studio, nao no lifecycle de foco do `EditorWorkspace`.
6. O snapshot de `prometeu-vfs` MUST cobrir apenas conteudo do projeto.
7. A `tree` exposta por `prometeu-vfs` MUST ser estrutural e de dados apenas; ela MUST NOT carregar concerns visuais ou view-model concerns de UI.
8. O `Project Navigator` do Studio SHALL consumir uma entidade que representa a arvore inteira do projeto e MAY solicitar atualizacoes mais pontuais do que um reload completo.
9. A abertura de arquivos no Studio MUST passar por `prometeu-vfs`, inclusive quando o backend concreto continuar sendo filesystem.
10. Regras de arquivos, plugins e suporte ou nao suporte MUST morar em `prometeu-vfs`; o Studio SHALL apenas apresentar o erro ou estado resultante.
11. A API oficial inicial de `prometeu-vfs` SHALL ficar concentrada em RPC/comandos/queries.
12. `prometeu-vfs` MAY manter eventos internos como parte de seu runtime, mas esses eventos MUST NOT ser publicados como API oficial nesta primeira wave.
13. `refresh` SHALL permanecer somente manual nesta primeira wave.
14. `watchers` MUST permanecer fora de escopo desta decisao e MUST NOT ser introduzidos por inferencia durante planning ou implementation.
15. `prometeu-vfs` SHALL nascer como primitive util do dominio `studio`: hoje para o editor, e futuramente podendo servir `prometeu-lsp`.
16. `prometeu-lsp` MUST permanecer como namespace/modulo separado, reservado para a futura camada de protocolo/handlers acima de `prometeu-vfs`.
17. Packer, assets e demais dominios MUST manter ownership proprio e MUST NOT ser absorvidos por `prometeu-vfs` sem decisao posterior explicita.

## Rationale

Esta decisao fecha a fronteira correta entre shell editorial e runtime documental.

O Studio precisa continuar owner de:

- layout;
- controls;
- navigator visual;
- estado de apresentacao;
- e UX de erro.

`prometeu-vfs` precisa passar a ser owner de:

- leitura estrutural do projeto;
- resolucao de documentos;
- abertura de arquivos;
- regras de suporte;
- refresh manual;
- e sincronizacao documental de sessao.

Isso remove do `EditorWorkspace` um conjunto de concerns que nao pertencem ao shell.

Criar `prometeu-vfs` como modulo novo e superior a renomear `prometeu-lsp` porque:

- preserva a hierarquia conceitual correta;
- evita ruido editorial nos roadmaps ja existentes;
- e mantem `lsp` como consumidor futuro do substrate documental, nao como nome prematuro do substrate em si.

Manter eventos publicos fora da primeira wave tambem e deliberado:

- o modulo continua livre para estabilizar sua maquina interna;
- o contrato externo inicial permanece menor e mais controlado;
- e nenhum consumidor passa a depender de detalhes de runtime antes da hora.

## Technical Specification

### 1. Module Boundary

- O workspace Gradle MUST incluir um novo modulo `prometeu-vfs`.
- Esse modulo SHALL ser a superficie de integracao documental do Studio para o escopo coberto por esta decisao.
- `prometeu-lsp` SHALL permanecer separado e sem reaproveitamento nominal do namespace.

### 2. Project Session Ownership

- A instancia principal de `prometeu-vfs` MUST pertencer a uma sessao de projeto do Studio.
- O `EditorWorkspace` MUST consumir essa instancia, e MUST NOT ser o owner do lifecycle documental.
- Troca de foco entre workspaces MUST NOT destruir o estado documental da sessao.

### 3. Filesystem Access

- Para o escopo coberto por esta decisao, o Studio MUST acessar o disco atraves de `prometeu-vfs`.
- O backend inicial de `prometeu-vfs` SHALL ser filesystem-backed.
- Essa decisao MUST NOT ser interpretada como criacao de um filesystem universal para todos os dominios do produto.

### 4. Structural Tree Contract

- `prometeu-vfs` MUST expor uma representacao estrutural do projeto inteiro.
- Essa representacao MUST incluir apenas dados e metadados estruturais/documentais necessarios ao consumo.
- Essa representacao MUST NOT conter:
  - estado de expansao visual;
  - selecao;
  - foco;
  - scroll;
  - reveal;
  - icones;
  - ou qualquer chrome de navigator.
- O Studio MAY derivar view models visuais a partir dessa estrutura.
- O `Project Navigator` MAY solicitar atualizacoes pontuais, sem obrigar reload completo da arvore a cada interacao.

### 5. Document and Open-File Contract

- Abrir um arquivo no Studio MUST significar resolver esse arquivo atraves de `prometeu-vfs`.
- O conteudo de documento devolvido por `prometeu-vfs` SHALL representar apenas o estado documental do projeto dentro da sessao atual.
- Esta decisao MUST NOT ser interpretada como permissao para introduzir novas features de edicao, save, dirty tracking, merge ou write semantics.

### 6. Support Rules and Errors

- A determinacao de suporte ou nao suporte de um arquivo MUST ocorrer em `prometeu-vfs`.
- Regras relacionadas a plugins e resolucao de handlers de arquivo MUST morar em `prometeu-vfs`.
- O Studio SHALL apenas reagir ao resultado, exibindo erro ou estado apropriado com os mecanismos de UI existentes ou futuros.

### 7. Communication Model

- A API oficial inicial de `prometeu-vfs` MUST ser RPC-oriented.
- O modulo MAY manter eventos internos para coordenacao de runtime.
- Esses eventos internos MUST NOT ser expostos como API publica nesta primeira wave.
- Nenhum plano ou implementacao posterior MAY promover eventos internos a API publica por inferencia; isso exigira decisao posterior explicita.

### 8. Refresh and Watchers

- `refresh` SHALL permanecer manual.
- `watchers` MUST permanecer fora de escopo.
- Nenhum plano posterior MAY introduzir watching automatico por aproximacao arquitetural.

### 9. Domain Boundaries

- O escopo de `prometeu-vfs` SHALL permanecer restrito ao boundary documental de projeto do dominio `studio`.
- `prometeu-vfs` MUST NOT absorver responsabilidades do packer.
- `prometeu-vfs` MUST NOT redefinir ownership de assets.
- Um futuro `prometeu-lsp` MAY consumir `prometeu-vfs`, mas `prometeu-vfs` MUST NOT depender de uma camada LSP para justificar seu contrato.

## Constraints

- Esta decisao e normativamente travada ao escopo hoje existente no `EditorWorkspace`.
- Nenhuma feature nova de editor pode ser adicionada por conveniencia durante a migracao para `prometeu-vfs`.
- O contrato inicial deve permanecer pequeno o suficiente para planejamento e implementacao direta.
- Qualquer tentativa de:
  - expor eventos publicos;
  - introduzir watchers;
  - ampliar o snapshot para fora do conteudo do projeto;
  - ou absorver outros dominios;
  exigira nova decisao explicita.

## Revision Log

- 2026-03-31: Initial draft from AGD-0012.