137 lines
6.4 KiB
Markdown
137 lines
6.4 KiB
Markdown
---
|
|
id: LSN-0032
|
|
ticket: studio-project-local-setup-separate-from-main-studio-state
|
|
title: Separate Project Config from Session Restoration State
|
|
created: 2026-04-04
|
|
tags: [studio, project-session, project-state, persistence, dot-studio, setup, configuration, boundary]
|
|
---
|
|
|
|
## Context
|
|
|
|
Studio had already introduced project-local persistence under `.studio/`, with a main single-file store at `.studio/state.json`.
|
|
That first wave correctly established project-local session restoration, but it also embedded `projectLocalSetup` in the same file.
|
|
|
|
After implementation and real lifecycle testing, the boundary problem became clearer:
|
|
|
|
- `shellLayout`, `openShellState`, and `editorRestoration` are session-restoration state;
|
|
- runtime path and similar project-local settings are configuration of the project itself;
|
|
- those two categories do not share the same lifecycle, mutation model, or troubleshooting surface.
|
|
|
|
The revision work closed that mismatch by splitting project configuration from session restoration while keeping both under `.studio/`.
|
|
|
|
## Key Decisions
|
|
|
|
### Separate Project-Local Setup from `.studio/state.json`
|
|
|
|
**What:**
|
|
`projectLocalSetup` was removed from the main session-restoration state contract.
|
|
The main store now remains focused on:
|
|
|
|
- `shellLayout`
|
|
- `openShellState`
|
|
- `editorRestoration`
|
|
|
|
Project-local setup now lives in its own file at `.studio/setup.json`.
|
|
|
|
**Why:**
|
|
Session restoration is about reopening the Studio shell in the last accepted project-local shape.
|
|
Project setup is about durable configuration that consumers such as `Play` may need independently from shell/session restore behavior.
|
|
|
|
Those concerns belong to the same project-local root, but not to the same file or lifecycle contract.
|
|
|
|
**Trade-offs:**
|
|
This adds another persisted file under `.studio/`.
|
|
That extra file is worth it because it prevents `state.json` from becoming an accidental catch-all store and gives project configuration a clearer operational identity.
|
|
|
|
### Keep Setup Out of the Session Snapshot Lifecycle
|
|
|
|
**What:**
|
|
The setup file is read through a dedicated DTO/service boundary and is intended for on-demand consumption.
|
|
It does not participate in the in-memory snapshot lifecycle used by `.studio/state.json`.
|
|
|
|
**Why:**
|
|
Project configuration is not session state.
|
|
Treating it as another session snapshot would blur the boundary again and recreate the same design problem in a different shape.
|
|
|
|
**Trade-offs:**
|
|
Consumers must explicitly read the setup file instead of receiving it “for free” from session-state snapshots.
|
|
That is an intentional cost because it preserves the correct mental model and ownership.
|
|
|
|
### Use a Dry Format Change for Early Boundary Repair
|
|
|
|
**What:**
|
|
The revision intentionally did not add compatibility for the obsolete shape where `projectLocalSetup` was embedded in `.studio/state.json`.
|
|
|
|
**Why:**
|
|
The goal of this wave was to repair the boundary cleanly, not to carry transitional compatibility machinery for a very recent format that had not yet earned long-term support cost.
|
|
|
|
**Trade-offs:**
|
|
Existing local fixtures and test projects had to be updated directly.
|
|
That is acceptable for a controlled early-stage format revision.
|
|
|
|
## Final Implementation
|
|
|
|
The Studio domain now uses two different project-local persistence files under `.studio/`:
|
|
|
|
- `.studio/state.json` for session-restoration state only;
|
|
- `.studio/setup.json` for project-local configuration.
|
|
|
|
The implementation changes established that split across code, tests, and specs:
|
|
|
|
- `ProjectLocalStudioState` and `ProjectLocalStudioStateService` no longer include `projectLocalSetup`.
|
|
- `ProjectLocalStudioSetup` and `ProjectLocalStudioSetupService` define the dedicated setup DTO and reader.
|
|
- `ProjectStudioPaths` now exposes the dedicated `.studio/setup.json` path.
|
|
- the Studio specs now describe setup as project configuration rather than session state.
|
|
- test projects under `test-projects/` now include the dedicated `setup.json` file.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
### Pattern: One Project-Local Root, Multiple Persistence Contracts
|
|
|
|
It is valid for several project-local persistence files to live under the same `.studio/` root when they represent different categories:
|
|
|
|
- session-restoration snapshots;
|
|
- project configuration;
|
|
- activity history;
|
|
- or other future categories.
|
|
|
|
The important rule is not “one root means one file”.
|
|
The important rule is that each file must have a clear semantic contract.
|
|
|
|
### Pattern: Separate Snapshot State from Durable Config
|
|
|
|
If data is restored through open/mount/close lifecycle behavior, it is snapshot state.
|
|
If data configures how the project should behave when some consumer needs it, it is durable config.
|
|
|
|
Those categories should not share the same file by convenience.
|
|
|
|
### Pattern: Read Config on Demand
|
|
|
|
When configuration does not belong to the session snapshot lifecycle, use a narrow reader boundary and let consumers fetch it when needed.
|
|
That keeps configuration from being accidentally reclassified as runtime session state.
|
|
|
|
## Pitfalls
|
|
|
|
- Do not let `state.json` become a generic “everything under `.studio/`” store.
|
|
- Do not move project-local setup into global application preferences just to avoid another file.
|
|
- Do not turn the dedicated setup file back into a session snapshot by caching it in the same lifecycle as layout restoration.
|
|
- Do not add compatibility machinery reflexively when the real need is to fix a still-young boundary cleanly.
|
|
- Do not leave the setup file name ambiguous across code and specs; the implementation should choose one explicit canonical name and use it consistently.
|
|
|
|
## References
|
|
|
|
- `DEC-0017` Separate project-local setup from session restoration state under `.studio/`
|
|
- `PLN-0038` Separate project-local setup from session restoration state
|
|
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
|
|
- `docs/specs/studio/8. Project-Local Studio State Specification.md`
|
|
- `prometeu-studio/src/main/java/p/studio/projects/ProjectStudioPaths.java`
|
|
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioState.java`
|
|
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioSetup.java`
|
|
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioSetupService.java`
|
|
|
|
## Takeaways
|
|
|
|
- Project-local persistence under `.studio/` does not imply a single-file design.
|
|
- Session restoration state and project configuration are different persistence categories and should stay separate.
|
|
- A small, explicit config reader is often better than folding durable configuration into a session snapshot contract.
|