feat(studio): integrate memcard persistence and headless controls
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good

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:
2026-10-30 11:01:02 +00:00
parent 3a3417eb44
commit 1d8b8c2101
110 changed files with 6502 additions and 85 deletions
@@ -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.