---
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.