prometeu-studio/discussion/workflow/decisions/DEC-0016-project-local-studio-state-under-dot-studio.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0016	studio-project-local-studio-state-under-dot-studio	Project-Local Studio State under .studio	accepted	2026-04-04	2026-04-04	AGD-0019		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.