Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/decisions/DEC-0009-studio-prometeu-vfs-project-document-boundary.md
bQUARKz 0f056a1ea1
prometeu-vsf
2026-03-31 08:00:10 +01:00

8.2 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0009 studio-editor-document-vfs-boundary Estabelecer `prometeu-vfs` como boundary documental de projeto para o Studio in_progress 2026-03-31 2026-03-31 AGD-0012
PLN-0015
PLN-0016
PLN-0017
PLN-0018
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.