Files
prometeu-studio/docs/specs/studio/8. Project-Local Studio State Specification.md
T
bquarkz 1d8b8c2101
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
feat(studio): integrate memcard persistence and headless controls
Persist cartridge identity and slot configuration, add MemcardBoot and the MemcardBuffer SDK, and consume the runtime's negotiated memcard host controls with protected teardown.

Qualify save/reopen and version upgrades through distinct configured runtime processes. Include specs, examples, regression evidence and the consolidated discussion lesson.
2026-10-30 11:01:02 +00:00

211 lines
12 KiB
Markdown

# Project-Local Studio State Specification
## Status
Active
## Applies To
- `prometeu-studio-api`
- `prometeu-studio-core`
- `prometeu-studio-ui-javafx`
- `prometeu-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:
- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
## Core Rules
1. The canonical root for project-local Studio persistence MUST be `.studio/` in the project root.
2. The main project-local Studio session-restoration store MUST be owned by the neutral project-session boundary, implemented in `p.studio.core.session` or by a project service explicitly composed into that session.
3. The main session-restoration store MUST remain a single file at `.studio/state.json`.
4. The main session-restoration store MUST be versioned.
5. The main session-restoration store MUST load when the project session opens.
6. Restorable shell state accepted by this wave MUST restore when the project shell mounts.
7. The main session-restoration store MUST save when the project shell or project session closes.
8. Missing, invalid, or schema-incompatible session-restoration state MUST fall back to safe default values and MUST NOT block project open.
9. Project-local setup configuration MUST live in a separate file at `.studio/setup.json`.
10. Project-local setup MUST NOT participate in the `.studio/state.json` snapshot lifecycle.
11. 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:
- `shellLayout`
- `openShellState`
Wave-1 accepted meaning is:
- `shellLayout`: restorable layout state already accepted by implementation, including divider positions and equivalent layout proportions for accepted workspaces such as `Assets`;
- `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 `spaces` with width `4`;
- project-local setup MAY grow with additional manual or automatic configuration keys over time;
- consumers such as `Play` MUST 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 `projectLocalSetup` was 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](10.%20DEV%20and%20Automation%20Specification.md).
`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 `StudioProjectSession` is 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.
## Cartridge identity and local memcard configuration
Versioned prometeu.json owns explicit numeric uint32 app_id and optional integral
memcard_slots in 1..64. Studio project references preserve both. New projects persist
their initial identity. Before shipping a legacy project, the current legacy
name/version/language/stdlib hash is adopted once via atomic manifest replacement,
with unknown fields preserved. Existing explicit IDs are authoritative and are
never regenerated on upgrades/rename/clone. A copied manifest represents the same
game; a distinct game requires an explicitly different identity. Invalid values
MUST fail rather than fall back to hashing. build/manifest.json propagates ID and
coherent slots/capability. Compiler validation additionally requires MemcardBoot
and the bootstrap boundary for memcard images.
Media path and session choice are local runtime-host configuration. The development
image location is `.studio/memcard.pmc`, outside rebuildable output; shared external
images require explicit selection. Studio creates no media implicitly and never
replaces existing saves. Runtime owns creation/mounting/concurrency, headless,
player-choice/dirty-discard workflow and reconciliation. Studio consumes only a
published interface of its configured runtime installation. It MUST NOT invent
flags/JSONL fields, implement an alternative host or duplicate SO/Hub.
Missing provider controls/dirty-pending diagnostics remain explicit integration
dependencies. They do not alter the guest ABI or permit silent memory-only fallback.
A process failure does not establish whether publication occurred; supervision
errors MUST NOT be presented as durable save failure/rollback. Native host evidence
and configured-process reopen evidence MUST be reported separately.
### Published memcard host integration
Memcard projects MUST negotiate protocol 1.1 and capability `memcard` with their
configured installation before mounting media or booting. Ordinary projects keep
the 1.0 flow. Runtime version strings are not capability detection.
`studio_headless_boot` accepts optional `memcard` mount configuration (`path`,
explicit `action:open/create`, explicit `access:read_write/read_only`) and the
explicit `memcardChoice:persistent/memory_fresh/memory_existing`. Studio sends
the published `memcard_mount` before `boot`, preserving native domain failures.
Omitted mount path selects the project-local development path; it does not imply
mounting, creation or a memory choice. An explicit create at that default path
may create its `.studio` parent; the runtime alone formats and creates the media.
Explicit external paths resolve against the project root. No open failure may
be retried as create, repaired or converted into a RAM choice automatically.
Local `.studio/setup.json` MAY set `memcardPath` to explicitly select another
image; relative selections resolve against the project root. Desktop Debug passes
the published `--memcard` option for opt-in projects, and headless mount defaults
to that same selection. An explicit per-session mount path overrides it for that
session. No desktop `--create-memcard` is inferred from file absence or launch.
Ordinary projects receive no media startup options. The default development
selection remains `.studio/memcard.pmc` when `memcardPath` is absent.
The consumer exposes native state, idle mount/unmount, same-card reconciliation
and explicit continuation in memory. These operations preserve the runtime's
state and choices; they do not expose private payloads. Reset/shutdown accept
explicit `discardUnsaved` and `pendingWrites:wait/cancel`; omission preserves
provider defaults. A native refusal MUST retain the process, channel and session
association. A subsequent explicit decision can retry. The structured
`memcard_error` is carried as `MEMCARD_ERROR` with unchanged native details.
An `action_required` advance is an `ACTION_REQUIRED` outcome with native
diagnostics, preserving known completed frames and the resident session.
Human reclaim first attempts protected shutdown without discard consent. On
refusal it keeps manual mutation locked and exposes the diagnostics. DEV offers
a separately confirmed discard of unsaved game RAM and cancellation of admitted
writes before retrying cleanup. Canceling that confirmation sends no consent.
Neither task release, Stop, reclaim nor a timeout implicitly permits discard.
Forced termination remains infrastructure failure with unknown publication
outcome; it MUST NOT manufacture a durable save result.