7.4 KiB
Project-Local Studio State Specification
Status
Active
Applies To
prometeu-studio-apiprometeu-studio-coreprometeu-studio-ui-javafxprometeu-app- Studio project-session persistence under
.studio/ - project-local Studio session restoration state
- project-local Studio setup configuration
Purpose
Define the normative contract for Studio project-local persistence under .studio/, including the boundary between the main session-restoration store and the dedicated setup configuration file.
Authority and Precedence
This specification implements the accepted decision for project-local Studio state under .studio/.
It extends:
Core Rules
- The canonical root for project-local Studio persistence MUST be
.studio/in the project root. - The main project-local Studio session-restoration store MUST be owned by the neutral project-session boundary, implemented in
p.studio.core.sessionor by a project service explicitly composed into that session. - The main session-restoration store MUST remain a single file at
.studio/state.json. - The main session-restoration store MUST be versioned.
- The main session-restoration store MUST load when the project session opens.
- Restorable shell state accepted by this wave MUST restore when the project shell mounts.
- The main session-restoration store MUST save when the project shell or project session closes.
- Missing, invalid, or schema-incompatible session-restoration state MUST fall back to safe default values and MUST NOT block project open.
- Project-local setup configuration MUST live in a separate file at
.studio/setup.json. - Project-local setup MUST NOT participate in the
.studio/state.jsonsnapshot lifecycle. - Project-local setup MUST be read through a dedicated DTO/file boundary when a consumer needs it.
Accepted Wave-1 Categories
The main session-restoration store MUST include:
shellLayoutopenShellState
Wave-1 accepted meaning is:
shellLayout: restorable layout state already accepted by implementation, including divider positions and equivalent layout proportions for accepted workspaces such asAssets;openShellState: which workspace or equivalent shell-owned project view was open;
Project-Local Setup Configuration
Project-local setup is a separate persistence concern under .studio/.
Rules:
- project-local setup MUST live in
.studio/setup.json; - project-local setup MUST be treated as project configuration rather than session state;
- project-local setup MAY contain runtime-oriented values such as the Prometeu runtime path;
- project-local setup MAY continue carrying project-wide indentation policy defaults for future code-tooling integrations;
- the indentation policy MUST define at least indentation mode and indentation width;
- when setup does not provide an explicit indentation policy, consumers MUST resolve it to
spaceswith width4; - project-local setup MAY grow with additional manual or automatic configuration keys over time;
- consumers such as
PlayMUST read project-local setup from the dedicated setup file rather than from.studio/state.json; - this revision uses a dry format change and MUST NOT preserve compatibility with the obsolete shape where
projectLocalSetupwas embedded in.studio/state.json.
Explicit Exclusions
The main session-restoration store MUST NOT include:
- project-local setup configuration;
- project-local activity history;
- derived cache;
- transient hover-only or equivalent ephemeral UI state;
- heavy operational output;
- recomputable results that do not represent session restoration state.
Under DEC-0060, automation grants, task/control identities, active runtime sessions and the task-local operation/deduplication registry MUST NOT be persisted or restored through .studio/state.json or .studio/setup.json. Reopening a project MUST start under manual control. Restoring DEV as the selected workspace is presentation restoration, not permission to resume work. MCP connection credentials MUST NOT be stored in versioned files; they are regenerated for every project grant and never restored on restart. See the DEV and Automation Specification.
Project-local activity and project-local setup may still live under .studio/, but they are separate persistence concerns and not part of the main session-restoration store defined here.
Ownership Rules
- shell and workspace UI may consume the main session-restoration store through project-session-owned contracts;
- shell and workspace UI must not define competing primary persistence files for accepted wave-1 categories;
- project-local setup may be consumed before a dedicated settings UI exists;
- project-local setup readers must not turn the setup file into another session snapshot by convenience.
Non-Goals
- defining persistence for project-local activity
- introducing a multi-file main store in this wave
- defining a settings editor UI for project-local setup
- persisting arbitrary transient workspace detail by convenience
Exit Criteria
This specification is complete enough when:
- the
.studio/boundary is unambiguous; - accepted and excluded categories are explicit;
- load, restore, save, and fallback timing are explicit;
- and the ownership boundary with
StudioProjectSessionis normatively locked.
Integrated MCP Discovery (DEC-0061)
.studio/setup.json MUST carry neutral agentIntegration intent with
schemaVersion:1, enabled and clientProfile. Preserve runtime and editor
fields. This intent is configuration, not readiness or authorization. Machine-local
resolved client configuration is a separate preparation output.
The transient descriptor is .studio/mcp/connection.json, limited to 16 KiB.
Schema v1 requires integral schemaVersion:1 and nonempty string instanceId,
projectRoot, endpoint, credential, catalogFingerprint. Root MUST match the
connector's canonical root. Endpoint MUST be http://127.0.0.1:<port>/mcp, with
no userinfo, query, fragment or redirect. Grant/task IDs and receipts are forbidden.
On macOS .studio/mcp MUST be owned by the current user with mode 0700;
descriptor, lock and temporary files MUST be 0600 before secrets are written.
Reject symlinked/unsafe paths and tracked descriptor targets. Add precise ignore
rules idempotently without changing unrelated project permissions or files.
Ownership MUST use an OS-held lock on the stable publication.lock inode; do
not delete the lock file on ordinary cleanup. A second live publisher fails. A
crashed process releases its lock through the OS; a new owner may atomically
replace stale content. Write a protected same-directory temporary file and
atomically rename it. Cleanup checks both instance and publication generation
so an old callback cannot remove newer discovery data.
Publication is a required grant lifecycle participant, not a swallowed observer. Prepare/publish occur outside the Core monitor; authority activation uses a generation fence. Acquisition cannot succeed until publication and grant both commit. Failure aborts credentials/files and reports a failed grant. Revoke/close invalidate credentials before asynchronous work cleanup, then remove owned publication and release ownership. File cleanup failure MUST NOT prevent runtime cancellation. An already-admitted release response MUST remain deliverable.