214 lines
16 KiB
Markdown
214 lines
16 KiB
Markdown
---
|
|
id: AGD-0019
|
|
ticket: studio-project-local-studio-state-under-dot-studio
|
|
title: Persist project-local Studio state under .studio
|
|
status: accepted
|
|
created: 2026-04-04
|
|
resolved: 2026-04-04
|
|
decision: DEC-0016
|
|
tags: [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?
|
|
- [x] 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?
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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`.
|
|
- [x] 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.
|