prometeu-studio/discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md

id	ticket	title	created	tags
LSN-0032	studio-project-local-setup-separate-from-main-studio-state	Separate Project Config from Session Restoration State	2026-04-04	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.