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.
211 lines
12 KiB
Markdown
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.
|