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