170 lines
7.3 KiB
Markdown
170 lines
7.3 KiB
Markdown
---
|
|
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.
|