prometeu-studio/discussion/workflow/agendas/AGD-0019-studio-project-open-state-under-dot-studio.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0019	studio-project-local-studio-state-under-dot-studio	Persist project-local Studio state under .studio	accepted	2026-04-04	2026-04-04	DEC-0016	studio project-session project-state persistence dot-studio shell layout setup

Pain

O Studio ja tem um modelo de project session para runtime do projeto aberto, mas ainda nao tem um contrato explicito para estado persistente do proprio Studio por projeto.

Sem esse contrato, a organizacao e o setup do Studio por projeto correm tres riscos:

• virar estado apenas em memoria e se perder toda vez que o Studio fecha;
• ser espalhado em arquivos ad hoc, sem uma raiz reservada e sem schema claro;
• misturar configuracao local do projeto com estado global do launcher, quebrando o boundary entre "este projeto no Studio" e "preferencias gerais da aplicacao".

Context

Domain owner: studio Owner surfaces: docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md Related context: discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md, discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md Relevant code: prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java

Ja existe precedente documental para duas direcoes importantes:

• .studio/ e a raiz reservada para estado local ao projeto;
• estado que precisa sobreviver a troca de workspace, mas continuar pertencendo ao projeto aberto, deve ser owned por project session.

O que ainda nao esta fechado e o contrato desta nova camada de estado persistente do Studio por projeto:

• quais dados entram nela;
• quais dados devem continuar apenas em memoria;
• o que e projeto-local versus launcher-global;
• como versionar, carregar, gravar e tolerar corrupcao parcial;
• se o modelo deve ser um store unico do projeto ou varios arquivos especializados sob .studio/.

Exemplos concretos do escopo pretendido agora:

• posicoes de divisorias e proporcoes de layout;
• quais janelas, paineis ou workspaces estavam abertos;
• quais tabs do editor estavam abertas e qual estava ativa;
• caminhos de setup local do Studio para o projeto, como runtime do Prometeu;
• futuras configuracoes locais do Studio que pertencam a este projeto e nao ao launcher global.

Categoria relacionada, mas separada deste contrato principal:

• project-local activity pode continuar vivendo sob .studio/, mas nao precisa pertencer ao mesmo store canonico de project session usado para layout, tabs, janelas e setup.

Observacao importante:

• project-local setup ja e requisito relevante agora, mesmo antes de existir uma UI dedicada para edita-lo, porque o Studio pode precisar consumir configuracoes locais do projeto antes da superficie visual de configuracao ficar pronta.

Open Questions

What to store

• Qual deve ser o escopo minimo obrigatorio do estado persistido do Studio por projeto na primeira wave?
• O owner normativo do runtime deve ser StudioProjectSession com persistencia sob .studio/, ou cada workspace pode persistir diretamente seu proprio estado?
• O contrato deve usar um arquivo consolidado de estado do projeto ou uma arvore de arquivos especializados dentro de .studio/? Fechado: single file. O store principal da project session deve usar um arquivo consolidado, por ser mais simples de manter e governar.
• Quais categorias entram desde a wave 1: layout do shell, divisorias, paineis e janelas abertas, tabs abertas, documento ativo, caminhos de setup local, configuracoes por workspace?
• Project-local setup deve ser tratado como categoria de primeira classe desde o inicio, mesmo antes de haver UI propria?
• A project-local activity deve pertencer ao mesmo store de project session desta agenda? Fechado: nao. Project-local activity pode viver dentro de .studio/, mas deve permanecer dissociada do store principal de project session tratado nesta agenda.
• Quais categorias devem ser explicitamente proibidas por agora: cache derivado, estado efemero de hover, resultados recomputaveis, output operacional pesado, artefatos operacionais transient?

When to save and restore

• Quando o Studio grava esse estado: sob eventos incrementais, no fechamento da sessao, em pontos de checkpoint, ou combinacao controlada? Fechado: a politica base deve ser gravacao no fechamento; checkpoints sao aceitaveis apenas para categorias que realmente precisarem disso; gravacao incremental como regra geral nao e a direcao.
• Quais categorias devem ser restauradas imediatamente ao abrir o projeto e quais devem ser carregadas sob demanda? Fechado: o estado restauravel de shell deve ser reaplicado quando o projeto sobe; no mesmo boundary, quando o shell do projeto desce, o estado correspondente deve ser salvo.
• O setup local do projeto deve ser lido logo na abertura da project session, antes mesmo de o usuario abrir workspaces especificos? Fechado: sim. O setup local do projeto deve ser lido na abertura da project session.
• Como o Studio deve reagir a .studio/ ausente, estado em schema antigo, arquivo invalido ou dados parcialmente corrompidos? Fechado: fallback para valores default. A ausencia de .studio/, schema nao reconhecido ou conteudo invalido/corrompido nao deve impedir a abertura do projeto; o Studio deve cair para defaults seguros.

Options

Option A - Persistencia ad hoc por area do Studio sob .studio/

• Approach: cada area do Studio grava diretamente os arquivos de que precisa sob .studio/, por exemplo shell/layout, editor tabs, setup local e outros modulos futuros, sem um owner central de sessao nem um schema compartilhado forte.
• Pro: destrava persistencia rapido para features isoladas e exige pouco desenho inicial.
• Con: tende a fragmentar naming, lifecycle, migration e recovery; piora consistencia entre workspaces e dificulta distinguir estado normativo de lixo historico.
• Maintainability: baixa a media. Facil de iniciar, dificil de governar quando mais workspaces passarem a persistir.
• Trade-offs detalhados:
  • reduz custo de entrada para a primeira feature consumidora, mas troca esse ganho por uma futura consolidacao mais cara;
  • favorece autonomia local de shell e workspaces, mas quebra o boundary de project session que o repositorio vem fortalecendo;
  • simplifica a escrita inicial, mas complica leitura, migracao de schema e tolerancia a falhas, porque cada workspace pode passar a degradar de um jeito diferente;
  • permite fatiar rollout por workspace, mas aumenta o risco de formatos incompatíveis coexistirem dentro de .studio/.

Option B - Project-session state store canonico sob .studio/

• Approach: definir um contrato explicito de estado persistente do Studio por projeto, owned pela StudioProjectSession, com raiz canonica em .studio/ e schema/versionamento governados pelo Studio.
• Pro: preserva o boundary correto entre runtime de sessao, persistencia local do projeto e concerns globais do launcher; facilita recovery, migration e extensao futura.
• Con: exige desenhar ownership, schema e politica de gravacao antes de implementar a primeira feature consumidora.
• Maintainability: forte. O Studio ganha uma surface clara para persistencia de layout, tabs, setup local e futuras configuracoes por projeto sem espalhar responsabilidade por cada modulo.
• Trade-offs detalhados:
  • aumenta custo de desenho agora, mas reduz custo estrutural das proximas features que precisarem persistir estado por projeto;
  • centraliza ownership e recovery, o que melhora consistencia, mas exige uma API suficientemente clara para nao virar gargalo ou objeto “god state”;
  • facilita schema versioning, migration e corrupcao parcial, mas pede disciplina para separar configuracao local canonica de cache derivado;
  • protege a diferenca entre projeto-local e launcher-global, mas exige que o recorte inicial seja pequeno o bastante para nao bloquear implementacao por excesso de ambicao;
  • acomoda bem layout, setup e estado restauravel de UI, mas precisa de limites claros para nao começar a absorver qualquer detalhe efemero de sessao.

Option C - Manter apenas estado global do launcher e evitar persistencia por projeto nesta fase

• Approach: limitar a memoria persistente a recent projects e preferencias globais; cada projeto reconstroi layout, setup local e tabs do zero a cada abertura.
• Pro: menor custo imediato e nenhum contrato novo dentro do projeto.
• Con: conflita com o objetivo de tornar o projeto aberto uma unidade com estado proprio; degrada continuidade de uso e ignora o precedente ja registrado para .studio/.
• Maintainability: simples no curtissimo prazo, mas funcionalmente insuficiente se o Studio quer evoluir como ambiente de trabalho persistente por projeto.
• Trade-offs detalhados:
  • preserva simplicidade operacional agora, mas empurra o problema para depois sem melhorar a arquitetura do projeto aberto;
  • evita erro de modelagem prematuro, mas tambem impede validar cedo a disciplina de .studio/ e project session;
  • mantem o launcher como unico ponto persistente, mas mistura setup local do projeto com concerns globais que deveriam permanecer fora do projeto;
  • reduz risco de schema local mal desenhado, mas aumenta risco de cada nova feature tentar contornar a ausencia de persistencia por atalhos locais.

Discussion

O ponto principal aqui nao e apenas "onde salvar um JSON". O que precisa ser fechado e o boundary arquitetural:

1. ownership de runtime: quem monta o estado em memoria enquanto o projeto esta aberto;

2. ownership de persistencia: quem serializa e restaura esse estado sem deixar cada workspace inventar sua propria disciplina;

3. shape do dado: o que conta como organizacao e setup do Studio por projeto, o que e apenas view state efemero e o que pertence ao launcher global;

4. resiliencia: como o Studio lida com schema evolution, arquivos ausentes e degradacao parcial sem falhar ao abrir um projeto.

O precedente atual aponta para uma direcao relativamente forte:

• .studio/ deve continuar sendo a raiz reservada do projeto para concerns do Studio;
• StudioProjectSession ja e o owner natural do estado que vive acima do foco de um workspace;
• workspaces devem consumir servicos de sessao, nao redefinir ownership de persistencia por conta propria.
• nem todo dado sob .studio/ precisa cair dentro do mesmo store de project session; activity e o exemplo claro de uma categoria projeto-local, mas com semantica e politica de persistencia diferentes.
• para o store principal desta agenda, single file e a direcao preferida, porque simplifica manutencao, leitura, escrita e governanca inicial.

O risco de ir por um caminho ad hoc e que shell, editor e setup local comecem a salvar layout, tabs e caminhos em formatos independentes e acidentalmente normativos. Depois disso, consolidar ownership, migration e cleanup fica mais caro do que desenhar a superficie certa agora.

Ao mesmo tempo, uma primeira wave disciplinada nao precisa resolver toda a persistencia futura do Studio. Ela pode fechar:

• a raiz canonicamente reservada;
• o owner do runtime e da serializacao;
• as categorias de estado permitidas e proibidas na wave inicial;
• o formato geral de schema e versionamento;
• a politica de recovery minima para nao travar abertura de projeto.

Trade-off central da agenda:

• se priorizarmos velocidade local da primeira feature, Option A parece atraente, mas ela compra essa velocidade quebrando o owner correto;
• se priorizarmos architecture hygiene, Option B e a direcao mais consistente, mas ela precisa de um recorte rigoroso para nao tentar resolver persistencia total do Studio numa tacada so;
• Option C so faz sentido se o objetivo real nao for ainda ter projeto aberto como unidade persistente, o que conflita com a premissa desta agenda.

Os trade-offs tambem se separam naturalmente em dois eixos:

1. what to store quanto mais categorias entram na wave 1, maior o valor imediato de restauracao do Studio por projeto; por outro lado, maior o risco de misturar setup canonico com estado efemero ou cache derivado.

   A convergencia atual deste eixo ja sugere uma separacao interna:

   • um store principal de project session para layout, setup, janelas e restauracao de tabs;
   • stores ou artefatos adjacentes sob .studio/ para categorias com semantica diferente, como project-local activity.

2. when to save/restore quanto mais automatico e frequente for o save, menor a perda de estado; por outro lado, maior o risco de churn de escrita, snapshots inconsistentes e acoplamento excessivo a eventos de UI.

Leituras ja convergidas neste eixo:

• project-local setup deve ser restaurado logo na abertura da project session;
• o estado restauravel do shell deve subir com o projeto e ser salvo quando esse shell descer;
• save on close deve ser a politica padrao;
• checkpoints podem existir, mas apenas quando alguma categoria realmente exigir persistencia intermediaria.

Leitura atual dos trade-offs:

1. o maior risco de produto e nao ter continuidade de organizacao e setup do Studio entre aberturas do projeto;
2. project-local setup tem prioridade alta porque pode ser consumido mesmo antes da UI de configuracao existir;
3. o maior risco arquitetural e permitir que shell e workspaces inventem persistencia independente para layout, tabs e configuracao local;
4. o maior risco de execucao em Option B e superdimensionar a primeira wave ou salvar estado demais cedo demais;
5. portanto, a melhor convergencia parece ser um store canonico de sessao/projeto com escopo inicial deliberadamente estreito, single file no inicio, mas explicitamente capaz de crescer para layout, setup e configuracoes futuras.

Resolution

Recommended direction: seguir com Option B.

A agenda deve convergir para uma decision com os seguintes fechamentos:

1. .studio/ permanece a raiz canonica de estado local ao projeto para o Studio;
2. StudioProjectSession ou um servico explicitamente owned por ela deve ser o owner do runtime e da persistencia do estado local do Studio por projeto;
3. shell e workspaces devem consumir esse estado por contrato, em vez de cada um persistir arbitrariamente por conta propria;
4. a primeira wave deve definir claramente quais categorias entram, com forte prioridade para project-local setup, layout restauravel e tabs/janelas abertas;
5. o contrato deve prever schema/versionamento e recovery de dados ausentes ou invalidos;
6. o boundary entre estado projeto-local e estado launcher-global deve ficar explicito;
7. o desenho inicial deve suportar extensao futura para novas categorias de configuracao local sem exigir reorganizacao ad hoc de .studio/;
8. a decision deve separar explicitamente what to store de when to save/restore, em vez de misturar conteudo e politica operacional;
9. a politica base de persistencia deve ser read on project-session open, restore on shell mount, save on shell/project close, com checkpoints apenas quando justificadamente necessarios;
10. project-local activity deve ser explicitamente tratada como concern separado: continua sob .studio/, mas fora do store principal de project session;
11. o store principal deve comecar como single file;
12. ausencia, schema antigo ou conteudo invalido/corrompido devem degradar para valores default seguros, sem bloquear abertura do projeto.

Next step suggestion: fechar nesta agenda, em separado, what to store e when to save/restore:

• what to store: pelo menos project-local setup, shell layout, open panels/workspaces, editor open tabs + active tab;
• when to save/restore: leitura do setup ja na abertura da project session, restauracao do layout/tabs na entrada do shell, save no fechamento, e checkpoints apenas para categorias que realmente precisarem.