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.
This commit is contained in:
@@ -234,6 +234,16 @@ Reset leaves the runtime unbooted and clears its capture. It does not implicitly
|
||||
boot the cartridge again. A subsequent explicit boot may reuse the session's
|
||||
known build cartridge; an invalidated process requires an explicit new session.
|
||||
|
||||
Memcard use negotiates the provider's protocol 1.1 extension explicitly. The
|
||||
adapter projects mount/choice/state/reconcile/RAM-continuation and protected
|
||||
teardown as specified in [Project-local memcard integration](<8. Project-Local Studio State Specification.md#published-memcard-host-integration>).
|
||||
Native `memcard_error` refusal preserves structured state and the live channel;
|
||||
it does not trigger process termination or detach. `action_required` preserves
|
||||
known progress and becomes `ACTION_REQUIRED`, with the resident session retained.
|
||||
Human reclaim never supplies discard consent. Following a protected cleanup
|
||||
refusal, DEV offers a separate confirmed discard/retry action; canceling it
|
||||
preserves the process and control guard.
|
||||
|
||||
| Configurable, handshake-advertised limit | Default |
|
||||
| --- | --- |
|
||||
| Frames per advance | 600 |
|
||||
|
||||
@@ -183,15 +183,20 @@ Input objects reject undeclared fields. IDs are nonempty opaque strings.
|
||||
| `studio_control_release` | task | none | state=MANUAL, only after ordered cleanup |
|
||||
| `studio_language_query` | task | operation, parameters | Supported LSP query/proposal result |
|
||||
| `studio_build_start` | task | clientRequestId | operationId, clientRequestId, state |
|
||||
| `studio_headless_boot` | task | buildId | sessionId, buildId; boot uses the task's known build |
|
||||
| `studio_headless_reset` | task | none | Current session/reset state |
|
||||
| `studio_headless_boot` | task | buildId, optional memcard/memcardChoice | sessionId, buildId; boot uses the task's known build |
|
||||
| `studio_headless_reset` | task | optional discardUnsaved/pendingWrites | Current session/reset state and negotiated memcard state |
|
||||
| `studio_headless_set_input` | task | input | Current session acknowledgement |
|
||||
| `studio_headless_clear_input` | task | none | Current session acknowledgement |
|
||||
| `studio_headless_advance` | task | clientRequestId, frames | operationId, clientRequestId, state |
|
||||
| `studio_headless_capture` | task | none | Canonical image and metadata in section 6 |
|
||||
| `studio_headless_state` | task | none | Current session and runtime state |
|
||||
| `studio_headless_fault` | task | none | fault object or null, preserving structural fault details |
|
||||
| `studio_headless_shutdown` | task | none | Session shutdown acknowledgement after managed cleanup |
|
||||
| `studio_headless_shutdown` | task | optional discardUnsaved/pendingWrites | Session shutdown acknowledgement/final memcard state after managed cleanup; native refusal preserves session |
|
||||
| `studio_headless_memcard_state` | task | none | Native media/session/dirty/request/IO/recovery state |
|
||||
| `studio_headless_memcard_mount` | task | action, access, optional path | Explicit idle open/create through the provider |
|
||||
| `studio_headless_memcard_unmount` | task | none | Explicit idle media release |
|
||||
| `studio_headless_memcard_reconcile` | task | none | Runtime-owned same-card revalidation while suspended |
|
||||
| `studio_headless_memcard_continue_in_memory` | task | none | Explicit runtime-owned RAM continuation while suspended |
|
||||
| `studio_operation_get` | task | exactly one of operationId/clientRequestId | State, known progress, typed result/failure |
|
||||
| `studio_operation_cancel` | task | operationId | operationId, cancellationRequested |
|
||||
|
||||
@@ -401,6 +406,17 @@ that process, invalidates previous buildIds and requires a fresh explicit boot.
|
||||
Synchronous headless failures finish their worker before returning the error,
|
||||
so a corrective call cannot race the failed worker's admission lock.
|
||||
|
||||
Memcard boot options are local host configuration, never an arbitrary cartridge
|
||||
path. `memcard` contains explicit action/access and optional image path;
|
||||
`memcardChoice` is an explicit provider choice. Protocol 1.1 plus capability
|
||||
`memcard` is required before mutation. `MEMCARD_ERROR` preserves native
|
||||
operation/reason/state in `runtimeError`. Refused reset/shutdown keep the attached
|
||||
session and task available for inspection and a later explicit choice.
|
||||
`discardUnsaved` and `pendingWrites` are forwarded only when supplied. Neither
|
||||
ordinary Stop/task release nor connection loss supplies discard consent.
|
||||
See [published memcard host integration](<8. Project-Local Studio State Specification.md#published-memcard-host-integration>)
|
||||
for local paths, protected human reclaim and `ACTION_REQUIRED` outcomes.
|
||||
|
||||
Task-local operation/build records are discarded after worker termination on
|
||||
return, revocation or project closure. Cleanup failures never restore authority;
|
||||
the records are still discarded after managed work stops. Neither connection
|
||||
@@ -536,7 +552,8 @@ authentication, Origin, endpoint/method/version handling, tool dispatch, malform
|
||||
or oversized input, closure, restart and old-token rejection. Provider doubles
|
||||
exist only in tests. Composition starts/closes transport with Studio.
|
||||
|
||||
The production registry composes all 17 tools as of step 23, including headless
|
||||
The production registry composes 22 tools, including five negotiated memcard
|
||||
controls and the original headless
|
||||
handlers bound to the actual `HeadlessProcessGateway`. Missing project runtime
|
||||
configuration fails at boot with `RUNTIME_UNAVAILABLE`; tool discovery does not
|
||||
grant authority or launch a process. No fake runtime is shipped.
|
||||
|
||||
@@ -138,3 +138,73 @@ commit. Failure aborts credentials/files and reports a failed grant. Revoke/clos
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user