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
@@ -14,7 +14,7 @@ public record AutomationFailure(Code code, String message, Map<String, Object> r
UNSUPPORTED_LANGUAGE, UNSUPPORTED_CAPABILITY, REFERENCE_NOT_FOUND, DOCUMENTATION_UNAVAILABLE,
OUTSIDE_PROJECT_SCOPE, READ_ONLY_SCOPE, OPERATION_NOT_FOUND, CLIENT_REQUEST_CONFLICT,
RUNTIME_UNAVAILABLE, RUNTIME_INCOMPATIBLE, SESSION_NOT_FOUND, BUILD_NOT_FOUND,
NO_FRAME_AVAILABLE, LIMIT_EXCEEDED, NOT_CANCELABLE, INFRASTRUCTURE_FAILURE
NO_FRAME_AVAILABLE, LIMIT_EXCEEDED, NOT_CANCELABLE, MEMCARD_ERROR, INFRASTRUCTURE_FAILURE
}
public AutomationFailure {
Objects.requireNonNull(code); Objects.requireNonNull(message);
@@ -2,6 +2,6 @@ package p.studio.api.automation;
import java.util.List;
public record AutomationOutcome(Kind kind, long requestedFrames, long completedFrames,
List<String> diagnostics, CanonicalCapture capture) {
public enum Kind { SUCCEEDED, TERMINATED, GUEST_FAULT, INFRASTRUCTURE_FAILURE, CANCELLED }
public enum Kind { SUCCEEDED, TERMINATED, GUEST_FAULT, INFRASTRUCTURE_FAILURE, CANCELLED, ACTION_REQUIRED }
public AutomationOutcome { diagnostics = List.copyOf(diagnostics); }
}
@@ -12,6 +12,9 @@ public interface AutomationSession {
ControlResult acquire();
CompletionStage<ControlResult> release(TaskIdentity task);
CompletionStage<ControlResult> reclaim();
default CompletionStage<ControlResult> reclaimDiscardingUnsavedGameData() {
return java.util.concurrent.CompletableFuture.failedFuture(new UnsupportedOperationException("Runtime discard is unavailable"));
}
CompletionStage<ControlResult> closeAsync();
/** Internal specialized service work, not a generic MCP shell/tool endpoint. */
OperationHandle<AutomationOutcome> submit(TaskIdentity task, String summary, Callable<AutomationOutcome> work);
@@ -5,4 +5,10 @@ public interface ManagedHeadlessSession {
String sessionId();
void cancel();
CompletionStage<Void> shutdown();
/** Human consent to discard remaining RAM; never inferred from Stop/reclaim. */
default CompletionStage<Void> shutdown(boolean discardUnsaved) {
if (discardUnsaved) return java.util.concurrent.CompletableFuture.failedFuture(
new UnsupportedOperationException("Runtime discard is unavailable"));
return shutdown();
}
}
@@ -14,7 +14,8 @@ public interface TaskTools {
boolean cancel(Path root, String taskId, String operationId);
HeadlessReply headless(Path root, String taskId, HeadlessAction action, String buildId, Map<String, Object> input);
enum HeadlessAction { BOOT, RESET, SET_INPUT, CLEAR_INPUT, CAPTURE, STATE, FAULT, SHUTDOWN }
enum HeadlessAction { BOOT, RESET, SET_INPUT, CLEAR_INPUT, CAPTURE, STATE, FAULT, SHUTDOWN,
MEMCARD_STATE, MEMCARD_MOUNT, MEMCARD_UNMOUNT, MEMCARD_RECONCILE, MEMCARD_CONTINUE_IN_MEMORY }
record HeadlessReply(Map<String, Object> values, CanonicalCapture capture) {
public HeadlessReply { values = java.util.Collections.unmodifiableMap(new java.util.LinkedHashMap<>(values)); }
}
@@ -3,13 +3,18 @@ package p.studio.api.project;
public record ProjectLocalStudioSetup(
String prometeuRuntimePath,
EditorIndentationSetup editorIndentation,
AgentIntegrationSetup agentIntegration) {
AgentIntegrationSetup agentIntegration,
String memcardPath) {
public ProjectLocalStudioSetup(String runtimePath, EditorIndentationSetup indentation, AgentIntegrationSetup integration) {
this(runtimePath, indentation, integration, null);
}
public ProjectLocalStudioSetup(String runtimePath, EditorIndentationSetup indentation) {
this(runtimePath, indentation, AgentIntegrationSetup.defaults());
}
public ProjectLocalStudioSetup {
agentIntegration = agentIntegration == null ? AgentIntegrationSetup.defaults() : agentIntegration;
prometeuRuntimePath = normalizeText(prometeuRuntimePath);
memcardPath = normalizeText(memcardPath);
editorIndentation = editorIndentation == null
? EditorIndentationSetup.defaults()
: editorIndentation.normalize();
@@ -9,7 +9,13 @@ public record ProjectReference(
String languageId,
int stdlibVersion,
ProjectTarget target,
Path rootPath) {
Path rootPath,
Long appId,
Integer memcardSlots) {
public ProjectReference(String name, String version, String languageId, int stdlibVersion,
ProjectTarget target, Path rootPath) {
this(name, version, languageId, stdlibVersion, target, rootPath, null, null);
}
public ProjectReference {
name = requireText(name, "name");
version = requireText(version, "version");
@@ -19,6 +25,10 @@ public record ProjectReference(
}
Objects.requireNonNull(target, "target");
rootPath = Objects.requireNonNull(rootPath, "rootPath").toAbsolutePath().normalize();
if (appId != null && (appId < 0 || appId > 0xffff_ffffL))
throw new IllegalArgumentException("app_id must be an unsigned 32-bit integer");
if (memcardSlots != null && (memcardSlots < 1 || memcardSlots > 64))
throw new IllegalArgumentException("memcard_slots must be in 1..64");
}
@Override