Add shared human/task asset batches with reviewed atomic publication, explicit reference rebinds, ownership inspection and qualified glyph/scene budgets. Expose the same authoring and capacity results through Assets and MCP. Deliver isolated guest test targets, retained visual evidence and immutable runtime lifecycle/control observations. Preserve provider qualification and installed authoring examples alongside the completed discussion lessons. Close AGD-106 coordination and the delivered discussion workflows through housekeeping, updating lesson references and preserving qualification limits. Sound remains outside the asset delivery wave. Validation: 579 module tests and 31 additional desktop, process and installed checks passed; native glyph/scene 16/17 boundaries qualified. Discussion validation passed after housekeeping.
304 lines
18 KiB
Markdown
304 lines
18 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.
|
||
|
||
|
||
## Project LSP endpoint discovery
|
||
|
||
An open project's Studio LSP adapter MUST atomically publish `.studio/lsp.json`
|
||
after its loopback server starts. Schema version 1 contains `schemaVersion`,
|
||
`projectRoot` (canonical filesystem path), `sessionId` (fresh for each boot),
|
||
`processId`, `host` (`127.0.0.1`) and `port` (the actual OS-assigned port).
|
||
Publication failure MUST stop the newly started server. Shutdown MUST stop the
|
||
server and remove discovery only when its session identity still owns the file.
|
||
The file is transient, unversioned, carries no credential and MUST be independent
|
||
of automation grants. It does not change the public LSP configuration default.
|
||
|
||
The VS Code extension MUST default to discovering this file for exactly one local
|
||
workspace project, validate schema/root/process/host/port, and initialize against
|
||
that canonical workspace. It MUST NOT silently select one of several roots or
|
||
fall back to a fixed port. Absent or dead-process discovery means waiting for
|
||
Studio; malformed metadata MUST be reported without connecting. File creation,
|
||
replacement or deletion and workspace/configuration changes MUST restart discovery.
|
||
Retries MUST use capped exponential backoff (2–30 seconds), reset after connection,
|
||
and stop at extension shutdown. Connection state MUST be visible without recurring
|
||
error popups. Explicit manual mode MAY use configured host/port for other hosts.
|
||
The server's project binding validation remains authoritative.
|
||
|
||
## Persistent visual evidence
|
||
|
||
Visual evidence MUST be retained separately from session restoration in
|
||
`.studio/evidence/`. Immutable publication directories contain PNG objects and a
|
||
publication record, including comparison reports and reviewed baseline revisions.
|
||
The application filesystem adapter MUST stage and integrity-check complete objects
|
||
and publish the directory atomically. Incomplete staging MUST NOT be listed and
|
||
MAY be cleaned under the store lock on reopen. Rebuild, release, shutdown and
|
||
project/application closure MUST preserve completed publications.
|
||
|
||
The byte quota MUST be configurable and default to 512 MiB per project. Admission
|
||
MUST serialize concurrent publishers, include object and publication metadata
|
||
bytes, and refuse before publication with used/required/limit. It MUST NOT evict
|
||
evidence or replace a baseline to admit new data. Deletion MUST be explicit,
|
||
authorized and refuse while another report or baseline references the publication.
|
||
|
||
Each artifact MUST retain an opaque ID, SHA-256 of original bytes, size, MIME,
|
||
dimensions and available project/task/operation/client-request/build/session/frame
|
||
provenance. Current staleness MUST be a separate observation, never a metadata
|
||
rewrite. Imported references MUST identify their external origin without invented
|
||
runtime identities. Report and baseline history MUST remain immutable.
|
||
|
||
## Isolated guest test artifacts
|
||
|
||
Test build output MUST live in `.studio/test-builds/<targetId>/<buildId>/`; test
|
||
run media/transcript identity MUST live under `.studio/test-runs/<runId>/`. These
|
||
are separate from session restoration and the production build output. Successful
|
||
builds MUST retain immutable target/configuration/source/dependency/asset provenance.
|
||
Incomplete or cancelled output MUST NOT publish a usable build identity. Test media
|
||
MUST be disposable and explicit; default/personal card paths MUST NOT be reused.
|
||
Closing/reopening a process for persistence proof MUST retain the same selected
|
||
disposable image and distinguish RAM, accepted commit and demonstrated durability.
|
||
Each run retains media.json with the explicit mode/creating image identity and
|
||
result.json with its immutable completion/verdict, native causes, provenance and
|
||
cleanup observation. Reopen accepts only a service-owned disposable-create run,
|
||
never an arbitrary media path or a personal/default-image alias. These records
|
||
are historical results, not restored task authority or permission to resume work.
|
||
|
||
## Recoverable asset batches and ownership
|
||
|
||
Asset batch staging, journals, source grants and retained request/result
|
||
correlation MUST remain separate from session restoration. The project-local
|
||
batch store is `.studio/asset-batches/`; ownership/dependency declarations are
|
||
separate versioned authoring metadata at `.studio/asset-ownership.json`.
|
||
These stores MUST NOT duplicate registry authority over AssetId, UUID, location
|
||
or build inclusion. Restoring a journal/result MUST NOT restore task authority
|
||
or an external source grant.
|
||
|
||
A revision covers the relevant project/asset manifests, the authoritative
|
||
`assets/.prometeu/index.json`, ordered composition, Studio metadata including
|
||
animation bindings, declared ownership/dependencies and relevant input-byte
|
||
hashes. Missing expected inputs are explicit revision facts. Every preview
|
||
declares all asset/manifest/registry/metadata/input changes before publication.
|
||
Revalidation immediately before commit MUST reject changed inputs.
|
||
|
||
Staging and a durable recoverable journal MUST precede publication. Shared
|
||
readers/writers MUST recover pending publication before accessing project truth.
|
||
Before the commit point, failure/cancellation leaves the old complete state;
|
||
after it, recovery and result queries report the new complete applied state,
|
||
including after a lost response or late cancellation. Never expose an
|
||
intermediate batch as committed. The service detects external changes during
|
||
revalidation; it does not serialize external writers that ignore Studio
|
||
coordination. Request correlation records MUST NOT act as access credentials.
|
||
|
||
PNG sources inside the canonical project use current project read authority.
|
||
External PNGs require an opaque project-bound grant issued by explicit human
|
||
source selection. Validate canonical scope, expected bytes and PNG bounds before
|
||
staging, then revalidate relevant source bytes at commit. A path, hash or
|
||
caller-supplied claim alone is not an external-source grant.
|