prometeu-vsf
This commit is contained in:
+178
@@ -0,0 +1,178 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user