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
@@ -23,6 +23,9 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
private volatile String sessionId;
private volatile JsonNode hello;
private Path cartridge;
private Path projectRoot;
private Path selectedImage;
private boolean memcardEnabled;
private final CompletableFuture<JsonNode> greeting = new CompletableFuture<>();
private final Map<String, Pending> pending = new ConcurrentHashMap<>();
private final Set<ProcessHandle> descendants = ConcurrentHashMap.newKeySet();
@@ -34,7 +37,7 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
private final AtomicReference<Pending> advance = new AtomicReference<>();
private final Deque<String> stderr = new ArrayDeque<>();
private volatile boolean closing;
private CompletableFuture<Void> shutdown;
private CompletableFuture<TaskTools.HeadlessReply> shutdown;
HeadlessProcessSession(Process process, ObjectMapper source, HeadlessLimits limits, String buildId) {
this.process = process; this.limits = limits; this.buildId = buildId;
@@ -46,21 +49,57 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
}
void initializeAndBoot(Path cartridge) throws Exception {
initializeAndBoot(cartridge, cartridge, false, Map.of());
}
void initializeAndBoot(Path cartridge, Path projectRoot, boolean memcard, Map<String, Object> options) throws Exception {
initializeAndBoot(cartridge, projectRoot, memcard, options, projectRoot.resolve(".studio/memcard.pmc"));
}
void initializeAndBoot(Path cartridge, Path projectRoot, boolean memcard, Map<String, Object> options, Path selectedImage) throws Exception {
this.cartridge = cartridge;
this.projectRoot = projectRoot;
this.selectedImage = selectedImage;
JsonNode bootOptions = mapper.valueToTree(options);
HeadlessMemcard.boot(mapper, cartridge, bootOptions);
long deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(limits.handshakeTimeoutMs());
hello = await(greeting, limits.handshakeTimeoutMs());
version(hello.path("protocolVersion")); text(hello, "runtimeVersion"); capabilities(hello.path("capabilities"));
var required = new HashSet<>(CAPABILITIES);
if (memcard) {
if (count(hello.path("protocolVersion"), "minor") < 1) throw incompatibleMemcard();
boolean available = false;
for (var capability : hello.path("capabilities")) if (capability.asText().equals("memcard")) available = true;
if (!available) throw incompatibleMemcard();
required.add("memcard");
}
var expected = mapper.valueToTree(limits);
for (var fields = expected.fieldNames(); fields.hasNext();) {
String field = fields.next();
if (count(hello.path("limits"), field) != expected.path(field).longValue())
throw new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Runtime limits do not match launch configuration");
}
var init = mapper.createObjectNode(); init.putObject("protocolVersion").put("major", 1).put("minor", 0);
init.set("requiredCapabilities", mapper.valueToTree(CAPABILITIES));
var init = mapper.createObjectNode(); init.putObject("protocolVersion").put("major", 1).put("minor", memcard ? 1 : 0);
init.set("requiredCapabilities", mapper.valueToTree(required));
var negotiated = request("initialize", init, null, remaining(deadline));
version(negotiated.path("protocolVersion")); capabilities(negotiated.path("capabilities"));
state(request("boot", mapper.createObjectNode().put("path", cartridge.toString()), null, limits.callTimeoutMs()));
if (memcard) {
boolean available = false;
for (var capability : negotiated.path("capabilities")) if (capability.asText().equals("memcard")) available = true;
if (count(negotiated.path("protocolVersion"), "minor") < 1 || !available) throw incompatibleMemcard();
}
memcardEnabled = memcard;
state(boot(bootOptions));
}
private static AutomationException incompatibleMemcard() {
return new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Configured runtime requires protocol 1.1 and memcard capability");
}
private JsonNode boot(JsonNode options) throws Exception {
var params = HeadlessMemcard.boot(mapper, cartridge, options);
if (options.has("memcard")) {
if (!memcardEnabled) throw incompatibleMemcard();
HeadlessMemcard.state(request("memcard_mount", HeadlessMemcard.mount(mapper, projectRoot, options.path("memcard"), selectedImage), null, limits.callTimeoutMs()));
}
if (options.has("memcardChoice") && !memcardEnabled) throw incompatibleMemcard();
return request("boot", params, null, limits.callTimeoutMs());
}
@Override public String sessionId() { return sessionId; }
@Override public long maxFramesPerAdvance() { return limits.maxFrames(); }
@@ -68,16 +107,28 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
boolean alive() { return process.isAlive() || descendants.stream().anyMatch(ProcessHandle::isAlive); }
@Override public TaskTools.HeadlessReply call(TaskTools.HeadlessAction action, Map<String, Object> input) throws Exception {
if (action == TaskTools.HeadlessAction.SHUTDOWN) return await(stop(input).toCompletableFuture(), limits.shutdownTimeoutMs() + 1000);
if (!work.tryLock()) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless operation active");
try {
if (closing) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless shutdown active");
String command = switch (action) {
case BOOT -> "boot";
case RESET -> "reset"; case SET_INPUT -> "set_input"; case CLEAR_INPUT -> "clear_input";
case CAPTURE -> "capture"; case STATE -> "get_state"; case FAULT -> "get_fault";
case MEMCARD_STATE -> "get_memcard_state"; case MEMCARD_MOUNT -> "memcard_mount";
case MEMCARD_UNMOUNT -> "memcard_unmount"; case MEMCARD_RECONCILE -> "memcard_reconcile";
case MEMCARD_CONTINUE_IN_MEMORY -> "memcard_continue_in_memory";
default -> throw new IllegalArgumentException("Use lifecycle methods for boot/shutdown");
};
var params = action == TaskTools.HeadlessAction.BOOT ? mapper.createObjectNode().put("path", cartridge.toString()) : mapper.valueToTree(input);
var result = request(command, params, null, limits.callTimeoutMs());
boolean memcardAction = action.name().startsWith("MEMCARD_");
if (memcardAction && !memcardEnabled) throw incompatibleMemcard();
JsonNode params = mapper.valueToTree(input);
if (action == TaskTools.HeadlessAction.MEMCARD_MOUNT) params = HeadlessMemcard.mount(mapper, projectRoot, params, selectedImage);
if (action == TaskTools.HeadlessAction.RESET) {
params = HeadlessMemcard.teardown(mapper, input);
if (!input.isEmpty() && !memcardEnabled) throw incompatibleMemcard();
}
var result = action == TaskTools.HeadlessAction.BOOT ? boot(params) : request(command, params, null, limits.callTimeoutMs());
var values = new LinkedHashMap<String, Object>(); values.put("sessionId", sessionId); values.put("buildId", buildId);
CanonicalCapture capture = null;
switch (action) {
@@ -87,8 +138,12 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
values.put("runtimeVersion", text(hello, "runtimeVersion"));
values.put("limits", mapper.convertValue(hello.path("limits"), Object.class));
values.put("capabilities", mapper.convertValue(hello.path("capabilities"), Object.class));
if (memcardEnabled && action == TaskTools.HeadlessAction.RESET) HeadlessMemcard.state(result.path("memcard"));
}
case FAULT -> { fault(result); values.put("fault", mapper.convertValue(result, Object.class)); }
case MEMCARD_STATE, MEMCARD_MOUNT, MEMCARD_UNMOUNT, MEMCARD_RECONCILE, MEMCARD_CONTINUE_IN_MEMORY -> {
HeadlessMemcard.state(result); values.put("memcard", mapper.convertValue(result, Object.class));
}
default -> { if (!result.isObject()) throw invalid("Invalid acknowledgement"); }
}
return new TaskTools.HeadlessReply(values, capture);
@@ -101,6 +156,7 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
if (!work.tryLock()) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless operation active");
boolean interrupted = false;
try {
if (closing) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless shutdown active");
var item = new Pending("advance", frames, progress); advance.set(item);
send(item, mapper.createObjectNode().put("frames", frames));
JsonNode result;
@@ -121,6 +177,12 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
case "completed" -> { if (completed != frames) throw invalid("Incomplete completed result"); yield AutomationOutcome.Kind.SUCCEEDED; }
case "canceled" -> AutomationOutcome.Kind.CANCELLED;
case "terminated" -> AutomationOutcome.Kind.TERMINATED;
case "action_required" -> {
if (!memcardEnabled) throw invalid("Unnegotiated memcard outcome");
var nativeState = request("get_memcard_state", mapper.createObjectNode(), null, limits.callTimeoutMs());
HeadlessMemcard.state(nativeState); diagnostics.add(nativeState.toString());
yield AutomationOutcome.Kind.ACTION_REQUIRED;
}
case "faulted" -> { fault(result.path("fault")); if (result.path("fault").isNull()) throw invalid("Missing fault"); diagnostics.add(result.path("fault").toString()); yield AutomationOutcome.Kind.GUEST_FAULT; }
case "host_error" -> { error(result.path("error")); diagnostics.add(result.path("error").toString()); yield AutomationOutcome.Kind.INFRASTRUCTURE_FAILURE; }
default -> throw invalid("Unknown advance stop");
@@ -150,26 +212,47 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
abort("Headless session lost during cancellation");
}
}
@Override public synchronized CompletionStage<Void> shutdown() {
@Override public CompletionStage<Void> shutdown() { return stop(Map.of()).thenApply(ignored -> null); }
@Override public CompletionStage<Void> shutdown(boolean discardUnsaved) {
return stop(discardUnsaved ? Map.of("discardUnsaved", true, "pendingWrites", "cancel") : Map.of()).thenApply(ignored -> null);
}
@Override public synchronized CompletionStage<TaskTools.HeadlessReply> stop(Map<String, Object> policy) {
var params = HeadlessMemcard.teardown(mapper, policy);
if (!policy.isEmpty() && !memcardEnabled) return CompletableFuture.failedFuture(incompatibleMemcard());
if (shutdown != null) {
// The first forced shutdown reports infrastructure failure. An explicit human
// retry may acknowledge completed cleanup, but never releases a living process.
if (shutdown.isCompletedExceptionally() && dead.get() && !alive())
shutdown = CompletableFuture.completedFuture(null);
return shutdown;
if (!shutdown.isCompletedExceptionally()) return shutdown;
if (dead.get() && !alive()) return CompletableFuture.completedFuture(new TaskTools.HeadlessReply(Map.of("sessionId", sessionId), null));
// A native refusal leaves this channel usable for an explicit retry.
if (closing) return shutdown;
}
closing = true;
shutdown = CompletableFuture.runAsync(() -> {
shutdown = CompletableFuture.supplyAsync(() -> {
long deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(limits.shutdownTimeoutMs());
try {
if (!dead.get()) {
var response = request("shutdown", mapper.createObjectNode(), null, remaining(deadline));
var response = request("shutdown", params, null, remaining(deadline));
if (!response.path("closed").isBoolean() || !response.path("closed").booleanValue()) throw invalid("Missing shutdown acknowledgement");
if (memcardEnabled) HeadlessMemcard.state(response.path("memcard"));
if (!process.waitFor(remaining(deadline), TimeUnit.MILLISECONDS)) throw new TimeoutException();
terminate();
if (alive()) throw infrastructure("Owned runtime process tree did not terminate");
var values = new LinkedHashMap<String, Object>(); values.put("sessionId", sessionId);
values.putAll(mapper.convertValue(response, new com.fasterxml.jackson.core.type.TypeReference<Map<String, Object>>() {}));
return new TaskTools.HeadlessReply(values, null);
}
terminate();
if (alive()) throw infrastructure("Owned runtime process tree did not terminate");
return new TaskTools.HeadlessReply(Map.of("sessionId", sessionId), null);
} catch (AutomationException refusal) {
if (refusal.failure().code() == AutomationFailure.Code.MEMCARD_ERROR) {
closing = false; throw new CompletionException(refusal);
}
abort("Headless shutdown failed"); throw infrastructure("Headless shutdown failed; owned process tree terminated; save publication outcome unknown");
} catch (Exception failure) {
abort("Headless shutdown failed"); throw infrastructure("Headless shutdown failed; owned process tree terminated");
} finally { terminate(); if (alive()) throw infrastructure("Owned runtime process tree did not terminate"); }
abort("Headless shutdown failed"); throw infrastructure("Headless shutdown failed; owned process tree terminated; save publication outcome unknown");
}
});
return shutdown;
}
@@ -242,6 +325,12 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
case "not_cancelable" -> AutomationFailure.Code.NOT_CANCELABLE;
case "incompatible_version", "unsupported_capability" -> AutomationFailure.Code.RUNTIME_INCOMPATIBLE;
case "limit_exceeded", "response_too_large" -> AutomationFailure.Code.LIMIT_EXCEEDED;
case "memcard_error" -> {
if (!memcardEnabled) throw invalid("Unnegotiated memcard error");
text(error.path("details"), "operation"); text(error.path("details"), "reason");
HeadlessMemcard.state(error.path("details").path("state"));
yield AutomationFailure.Code.MEMCARD_ERROR;
}
default -> AutomationFailure.Code.INFRASTRUCTURE_FAILURE;
};
pending.remove(item.id);