Files
prometeu-studio/docs/specs/studio/8. Project-Local Studio State Specification.md
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
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.
2026-11-11 01:21:25 +00:00

18 KiB
Raw Permalink Blame History

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:

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.

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.