studio session persistent
This commit is contained in:
@@ -1,213 +0,0 @@
|
||||
---
|
||||
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.
|
||||
-169
@@ -1,169 +0,0 @@
|
||||
---
|
||||
id: DEC-0016
|
||||
ticket: studio-project-local-studio-state-under-dot-studio
|
||||
title: Project-Local Studio State under .studio
|
||||
status: accepted
|
||||
created: 2026-04-04
|
||||
accepted: 2026-04-04
|
||||
agenda: AGD-0019
|
||||
plans: []
|
||||
tags: [studio, project-session, project-state, persistence, dot-studio, shell, layout, setup]
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
The Studio MUST persist project-local Studio state under `.studio/` in the project root.
|
||||
|
||||
This decision normatively separates three concerns:
|
||||
|
||||
1. project-local Studio state owned by the project and restored with that project;
|
||||
2. launcher-global state that is not owned by any specific project;
|
||||
3. project-local activity artifacts that may live under `.studio/` but are not part of the main project-session state store defined here.
|
||||
|
||||
The main project-local Studio state store MUST be owned by `StudioProjectSession`, or by a persistence service explicitly owned by `StudioProjectSession`.
|
||||
|
||||
Shells and workspaces MUST consume that state through the project-session boundary.
|
||||
They MUST NOT define ad hoc independent persistence contracts for layout, tabs, windows, or project-local setup.
|
||||
|
||||
The main project-session store MUST start as a `single file` under `.studio/`.
|
||||
|
||||
The first accepted scope of that store MUST include:
|
||||
|
||||
- project-local setup required by Studio to operate on the project, including paths such as the Prometeu runtime path;
|
||||
- shell layout state such as splitter positions and layout proportions;
|
||||
- open shell/workspace state such as which panels, windows, or workspaces were open;
|
||||
- editor restoration state including open tabs and the active tab.
|
||||
|
||||
`Project-local setup` is a first-class category from the start, even before a dedicated UI exists to edit it.
|
||||
The Studio MAY consume such setup programmatically before a UI surface exists.
|
||||
|
||||
`Project-local activity` MUST remain outside the main project-session store defined by this decision.
|
||||
It MAY continue to live under `.studio/`, but it SHALL be treated as a separate concern with its own storage contract and persistence policy.
|
||||
|
||||
The main project-session store MUST NOT be used for:
|
||||
|
||||
- derived cache;
|
||||
- ephemeral hover or transient interaction state;
|
||||
- recomputable operational results;
|
||||
- heavy operational output;
|
||||
- activity history.
|
||||
|
||||
## Rationale
|
||||
|
||||
The repository already converged on two architectural directions:
|
||||
|
||||
- `.studio/` is the reserved root for project-local Studio concerns;
|
||||
- `StudioProjectSession` is the correct owner for state that must survive workspace focus changes while remaining scoped to one opened project.
|
||||
|
||||
This decision extends those directions into a normative persistence contract.
|
||||
|
||||
The chosen model prevents three failure modes:
|
||||
|
||||
1. launcher-global persistence swallowing project-local setup and organization;
|
||||
2. each shell or workspace inventing its own persistence format under `.studio/`;
|
||||
3. the main session state store absorbing unrelated concerns such as activity history or cache data.
|
||||
|
||||
Starting with a `single file` is intentionally conservative.
|
||||
It reduces governance and maintenance cost for the first wave while preserving the option to evolve the schema later if needed.
|
||||
|
||||
Treating project-local setup as first-class from the start is necessary because Studio runtime behavior may depend on local project configuration before any settings UI is available.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Storage Root
|
||||
|
||||
The canonical root for project-local Studio persistence MUST be `.studio/` in the project root.
|
||||
|
||||
The main project-session state store MUST be created under that root.
|
||||
|
||||
### 2. Ownership Boundary
|
||||
|
||||
`StudioProjectSession` MUST own the lifecycle of the main project-session state store.
|
||||
|
||||
That ownership includes:
|
||||
|
||||
- loading project-local setup when the project session opens;
|
||||
- exposing the loaded state to shell and workspace consumers through project-session-owned contracts;
|
||||
- coordinating restoration when the project shell mounts;
|
||||
- coordinating persistence when the project shell or project session closes.
|
||||
|
||||
No workspace MAY bypass this boundary by defining an unrelated primary store for project-local Studio organization or setup.
|
||||
|
||||
### 3. Store Shape
|
||||
|
||||
The main store MUST begin as a `single file`.
|
||||
|
||||
This file MUST act as the canonical snapshot for the categories accepted by this decision.
|
||||
|
||||
The schema MUST be explicitly versioned so future revisions can detect compatibility and migration boundaries.
|
||||
|
||||
### 4. Accepted Wave-1 Categories
|
||||
|
||||
Wave 1 of the main project-session store MUST cover:
|
||||
|
||||
- `projectLocalSetup`
|
||||
Project-local configuration required by Studio to operate on the project, including Prometeu runtime path and equivalent future setup fields.
|
||||
|
||||
- `shellLayout`
|
||||
Restorable shell organization such as divider positions, layout proportions, and equivalent shell-level geometry state.
|
||||
|
||||
- `openShellState`
|
||||
Which panels, windows, or workspaces were open when the project shell last persisted.
|
||||
|
||||
- `editorRestoration`
|
||||
Open editor tabs and the active tab.
|
||||
|
||||
These names are conceptual categories.
|
||||
Plans MAY refine the concrete field names, but they MUST preserve the exact normative scope above.
|
||||
|
||||
### 5. Explicit Exclusions
|
||||
|
||||
The main project-session store MUST NOT include:
|
||||
|
||||
- activity history;
|
||||
- derived cache data;
|
||||
- ephemeral UI interaction state such as hover-only data;
|
||||
- heavy operational logs or output buffers;
|
||||
- recomputable results that do not represent project-local Studio setup or restoration state.
|
||||
|
||||
If a future category is proposed, it MUST be classified explicitly as either:
|
||||
|
||||
- main project-session state;
|
||||
- separate `.studio/` concern;
|
||||
- launcher-global concern;
|
||||
- or non-persisted transient state.
|
||||
|
||||
### 6. Read / Restore / Save Policy
|
||||
|
||||
The main policy is normatively locked as follows:
|
||||
|
||||
- project-local setup MUST be read when `StudioProjectSession` opens;
|
||||
- restorable shell and editor state MUST be restored when the project shell mounts;
|
||||
- the main project-session store MUST be saved when the project shell or project session closes.
|
||||
|
||||
The repository default for this store is `save on close`.
|
||||
|
||||
General incremental persistence MUST NOT be the default policy for the main store.
|
||||
|
||||
Checkpoints MAY be introduced only for categories that explicitly require intermediate persistence.
|
||||
Any such checkpoint behavior MUST be justified in a later plan or revision and MUST remain category-scoped rather than becoming an uncontrolled global autosave rule.
|
||||
|
||||
### 7. Failure Handling
|
||||
|
||||
If `.studio/` is absent, the main store is missing, the schema is unknown, or the content is invalid or partially corrupted, the Studio MUST fall back to safe default values.
|
||||
|
||||
Such conditions MUST NOT block opening the project.
|
||||
|
||||
The fallback behavior MUST preserve the ability to open the project and operate the Studio with default shell, workspace, and setup assumptions as far as possible.
|
||||
|
||||
## Constraints
|
||||
|
||||
- No plan may reinterpret launcher-global state as project-local state without an explicit revision to this decision.
|
||||
- No plan may move `project-local activity` into the main project-session store without an explicit revision to this decision.
|
||||
- No plan may replace the `single file` starting point with a multi-file tree by inference.
|
||||
- No plan may treat ephemeral UI noise or derived cache as accepted wave-1 project-session state.
|
||||
- If a later implementation needs checkpoint persistence for a specific category, that need MUST be justified explicitly instead of silently broadening the save policy.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-04: Initial accepted decision from AGD-0019.
|
||||
-217
@@ -1,217 +0,0 @@
|
||||
---
|
||||
id: PLN-0037
|
||||
ticket: studio-project-local-studio-state-under-dot-studio
|
||||
title: Project-local Studio state store and restoration
|
||||
status: done
|
||||
created: 2026-04-04
|
||||
completed: 2026-04-04
|
||||
tags: [studio, project-session, project-state, persistence, dot-studio, shell, layout, setup]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the first accepted wave of project-local Studio state persistence under `.studio/`, using a single-file project-session-owned store that restores setup, shell organization, and editor tabs for a project.
|
||||
|
||||
## Background
|
||||
|
||||
DEC-0016 normatively locks the following:
|
||||
|
||||
- project-local Studio state must live under `.studio/` in the project root;
|
||||
- the main store must be owned by `StudioProjectSession`;
|
||||
- the main store must start as a single file;
|
||||
- wave 1 must include project-local setup, shell layout, open shell/workspace state, and editor restoration;
|
||||
- project-local activity must remain outside the main store;
|
||||
- the policy is read on project-session open, restore on shell mount, and save on shell/project close;
|
||||
- missing or invalid persisted state must fall back to safe defaults without blocking project open.
|
||||
|
||||
The current codebase already has a `StudioProjectSession` boundary plus a `MainView` shell and an `EditorWorkspace` with in-memory tab/session state, but it has no project-local persistence contract for those concerns.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Propagate DEC-0016 into Studio specifications.
|
||||
- Introduce a project-session-owned single-file state store under `.studio/`.
|
||||
- Load project-local setup when a project session opens.
|
||||
- Restore shell layout and open shell/workspace state when the project shell mounts.
|
||||
- Restore editor open tabs and active tab from project-local persisted state.
|
||||
- Save the main project-session store when the shell or project session closes.
|
||||
- Fall back to default values when persisted state is absent, unknown, or invalid.
|
||||
- Add tests for store parsing, fallback behavior, session ownership, shell restoration, and editor tab restoration.
|
||||
|
||||
### Excluded
|
||||
- Project-local activity persistence changes.
|
||||
- General autosave or global incremental persistence for the main store.
|
||||
- Multi-file store layout under `.studio/`.
|
||||
- New settings UI for project-local setup editing.
|
||||
- Persistence of ephemeral hover state, derived cache, heavy logs, or recomputable operational output.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Propagate DEC-0016 into Studio specs
|
||||
|
||||
**What:** Add normative spec coverage for the project-local Studio state store and its wave-1 boundaries.
|
||||
|
||||
**How:** Update the existing shell and editor specs, and add a dedicated Studio persistence spec if needed, so the repository explicitly states:
|
||||
- `.studio/` is the project-local root for the main Studio state store;
|
||||
- `StudioProjectSession` owns load/save lifecycle for the store;
|
||||
- the store begins as a single file;
|
||||
- wave-1 categories are `projectLocalSetup`, `shellLayout`, `openShellState`, and `editorRestoration`;
|
||||
- `project-local activity` is excluded from the main store;
|
||||
- read/restore/save policy and default fallback behavior are normative.
|
||||
|
||||
The preferred propagation shape is:
|
||||
- update [`docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/studio/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) for shell/session ownership and restore/save timing;
|
||||
- update [`docs/specs/studio/5. Code Editor Workspace Specification.md`](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/studio/5.%20Code%20Editor%20Workspace%20Specification.md) to replace the current “no cross-session tab restoration” rule with the accepted wave-1 restoration contract;
|
||||
- add a new dedicated spec such as [`docs/specs/studio/8. Project-Local Studio State Specification.md`](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/studio/8.%20Project-Local%20Studio%20State%20Specification.md) to hold the store schema boundary and exclusions.
|
||||
|
||||
**File(s):**
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/studio/5. Code Editor Workspace Specification.md`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/studio/8. Project-Local Studio State Specification.md`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/studio/README.md` if the new spec must be indexed
|
||||
|
||||
### Step 2 - Define the project-session state store contract and single-file codec
|
||||
|
||||
**What:** Create the main persisted-state model and the single-file read/write boundary used by `StudioProjectSession`.
|
||||
|
||||
**How:** Introduce a small persistence module or package in `prometeu-studio` that defines:
|
||||
- a versioned root DTO for the main state file;
|
||||
- wave-1 category DTOs for `projectLocalSetup`, `shellLayout`, `openShellState`, and `editorRestoration`;
|
||||
- a file path convention under `.studio/`;
|
||||
- loader/writer logic that returns safe defaults when the file is absent, unreadable, schema-incompatible, or invalid.
|
||||
|
||||
The implementation must keep `project-local activity` out of this file and must not broaden the schema to cache-like or transient UI data.
|
||||
|
||||
**File(s):**
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/projectsessions/`
|
||||
- a new package for state persistence such as `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/projectstate/`
|
||||
- corresponding test files under `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/test/java/p/studio/`
|
||||
|
||||
### Step 3 - Extend StudioProjectSession to load setup and expose restorable state
|
||||
|
||||
**What:** Move the main store lifecycle into the project-session boundary.
|
||||
|
||||
**How:** Update `StudioProjectSession` and `StudioProjectSessionFactory` so opening a project session:
|
||||
- loads the main store from `.studio/`;
|
||||
- exposes the loaded state to shell/workspace consumers through explicit accessors or a dedicated session-owned state service;
|
||||
- makes project-local setup available before workspace-specific UI mounts.
|
||||
|
||||
The session boundary must remain the owner of the persistence lifecycle; `MainView` and workspaces may consume the state but must not redefine load semantics.
|
||||
|
||||
**File(s):**
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSessionFactory.java`
|
||||
- any new project-session-owned state service under `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/projectsessions/` or `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/projectstate/`
|
||||
|
||||
### Step 4 - Restore shell layout and open shell/workspace state from the session store
|
||||
|
||||
**What:** Apply persisted shell organization when the project shell mounts and capture it again when the shell closes.
|
||||
|
||||
**How:** Update `MainView` and any shell controls it owns so they can:
|
||||
- restore the selected/open workspace state from the session store instead of hardcoding the default assets workspace when persisted state exists;
|
||||
- restore accepted shell layout properties such as splitter positions or equivalent shell-level geometry once the relevant shell surfaces are mounted;
|
||||
- collect the latest shell state before the shell or project session closes so `save on close` persists the canonical snapshot.
|
||||
|
||||
If a specific shell surface does not yet expose restorable layout state, introduce the minimal shell-owned API needed to read/write that state without making the shell controls own persistence themselves.
|
||||
|
||||
**File(s):**
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/window/MainView.java`
|
||||
- shell controls under `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/controls/shell/`
|
||||
- application/window close wiring where the current Studio shell lifecycle is finalized
|
||||
|
||||
### Step 5 - Restore editor open tabs and active tab through an editor-owned snapshot contract
|
||||
|
||||
**What:** Persist and restore the editor workspace’s accepted wave-1 restoration state.
|
||||
|
||||
**How:** Refactor the editor workspace so it can:
|
||||
- export a pure restoration snapshot containing open tab paths and active tab path;
|
||||
- accept a restoration snapshot when the workspace mounts under a project session;
|
||||
- reopen supported files through `prometeu-vfs` using those persisted paths;
|
||||
- fall back safely when a previously open file no longer exists or is no longer supported;
|
||||
- preserve the active-tab choice when restoration succeeds.
|
||||
|
||||
This step must not broaden into persistence of editor-local transient data beyond what DEC-0016 accepts.
|
||||
|
||||
**File(s):**
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorTabStrip.java` if small UI adjustments are needed for restore-first behavior
|
||||
|
||||
### Step 6 - Wire save-on-close and category-scoped checkpoints if any are required
|
||||
|
||||
**What:** Make the accepted save policy real in the application lifecycle.
|
||||
|
||||
**How:** Ensure the main store is serialized:
|
||||
- when the project shell closes;
|
||||
- and when the project session closes through its normal lifecycle.
|
||||
|
||||
Do not introduce general autosave for the main store.
|
||||
Only add checkpoint saves if a specific accepted category proves it cannot safely rely on close-time persistence alone, and keep that logic isolated to that category.
|
||||
|
||||
**File(s):**
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/window/MainView.java`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`
|
||||
- any shell/window lifecycle integration surface that currently owns project-window close behavior
|
||||
|
||||
### Step 7 - Add tests for defaults, restoration, and persistence boundaries
|
||||
|
||||
**What:** Lock the decision through automated tests.
|
||||
|
||||
**How:** Add tests that verify:
|
||||
- missing `.studio/` falls back to defaults;
|
||||
- invalid or schema-incompatible persisted content falls back to defaults;
|
||||
- project-local setup is loaded at project-session open;
|
||||
- shell/workspace state is restored from persisted state when present;
|
||||
- editor open tabs and active tab restore correctly;
|
||||
- `project-local activity` is not part of the main store contract;
|
||||
- saving the main store happens on the accepted close boundary.
|
||||
|
||||
**File(s):**
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/test/java/p/studio/projectsessions/`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/test/java/p/studio/window/`
|
||||
- `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/test/java/p/studio/workspaces/editor/`
|
||||
- tests for the new persistence package under `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/test/java/p/studio/projectstate/`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Persisted-state codec tests for versioned single-file read/write behavior.
|
||||
- Fallback tests for absent, invalid, and schema-incompatible state files.
|
||||
- Session-service tests proving default values are exposed when persisted state is unusable.
|
||||
- Editor snapshot tests proving only open-tab paths and active-tab identity are persisted.
|
||||
|
||||
### Integration Tests
|
||||
- `StudioProjectSessionFactory` tests that verify setup is loaded during session open.
|
||||
- Shell or window tests that verify persisted workspace selection and shell state are applied on mount.
|
||||
- Editor workspace tests that reopen tabs from persisted paths and preserve the active tab when possible.
|
||||
- Close-lifecycle tests that verify the main store is written when the shell or session closes.
|
||||
|
||||
### Manual Verification
|
||||
- Open a project with no `.studio/` state and confirm the Studio boots with defaults.
|
||||
- Configure project-local setup such as a Prometeu runtime path, close the shell, reopen the project, and confirm the setup is restored.
|
||||
- Open multiple editor tabs, switch the active tab, close the project, reopen it, and confirm the same tabs and active tab are restored.
|
||||
- Change shell/workspace organization that is in scope for wave 1, close the project, reopen it, and confirm that layout/workspace state is restored.
|
||||
- Corrupt or remove the persisted state file and confirm the project still opens with defaults instead of failing.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Studio specs normatively describe the `.studio/` single-file project-session store and its exclusions.
|
||||
- [ ] `StudioProjectSession` owns loading of project-local setup and access to the main state store.
|
||||
- [ ] The main store is persisted as a single file under `.studio/`.
|
||||
- [ ] Wave-1 categories are implemented without admitting excluded categories such as activity history or derived cache.
|
||||
- [ ] Shell/workspace state restores on shell mount and saves on shell/project close.
|
||||
- [ ] Editor open tabs and active tab restore from persisted project-local state.
|
||||
- [ ] Missing or invalid persisted state falls back to safe defaults without blocking project open.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision [`DEC-0016-project-local-studio-state-under-dot-studio.md`](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/discussion/workflow/decisions/DEC-0016-project-local-studio-state-under-dot-studio.md)
|
||||
- Existing project-session boundary in `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/projectsessions/`
|
||||
- Existing editor tab/session behavior in `/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/prometeu-studio/src/main/java/p/studio/workspaces/editor/`
|
||||
|
||||
## Risks
|
||||
|
||||
- The current shell controls may not yet expose enough structured state to restore all accepted wave-1 layout fields cleanly.
|
||||
- Editor restoration may need a small refactor to separate pure restore snapshots from current UI-driven open-file behavior.
|
||||
- A new persistence spec may overlap with current shell/editor specs unless propagation boundaries are written carefully.
|
||||
- Save-on-close behavior may depend on application/window lifecycle code not yet centralized in one obvious surface.
|
||||
Reference in New Issue
Block a user