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
@@ -0,0 +1,59 @@
package p.studio.core.project;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import p.studio.api.project.ProjectReference;
import java.io.IOException;
import java.nio.file.*;
import java.util.Objects;
/** Versioned cartridge identity is independent of local host/media configuration. */
public record ProjectCartridgeConfiguration(Long appId, Integer memcardSlots) {
public static ProjectCartridgeConfiguration read(JsonNode manifest) {
if (manifest == null || !manifest.isObject()) throw new IllegalArgumentException("Project manifest must be an object");
Long id = integer(manifest, "app_id", 0, 0xffff_ffffL);
Long slots = integer(manifest, "memcard_slots", 1, 64);
return new ProjectCartridgeConfiguration(id, slots == null ? null : slots.intValue());
}
private static Long integer(JsonNode manifest, String name, long min, long max) {
if (!manifest.has(name)) return null;
JsonNode value = manifest.get(name);
if (!value.isIntegralNumber() || !value.canConvertToLong() || value.longValue() < min || value.longValue() > max)
throw new IllegalArgumentException(name + " must be an integer in " + min + ".." + max);
return value.longValue();
}
public static long legacyAppId(ProjectReference project) {
int hash = Objects.hash(project.name(), project.version(), project.languageId(), project.stdlibVersion());
return hash == Integer.MIN_VALUE ? 1 : Math.max(1, Math.abs(hash));
}
/** Adopt once, preserving the original generated identity and all unrelated JSON. */
public static synchronized ProjectCartridgeConfiguration adopt(ProjectReference project, ObjectMapper mapper) throws IOException {
Path path = project.rootPath().resolve("prometeu.json");
ObjectNode manifest = mapper.readTree(path.toFile()) instanceof ObjectNode node ? node : null;
ProjectCartridgeConfiguration config = read(manifest);
if (config.appId() != null) return config;
long id = project.appId() == null ? legacyAppId(project) : project.appId();
manifest.put("app_id", id);
Path temporary = Files.createTempFile(path.getParent(), ".prometeu-identity-", ".json");
try {
mapper.writerWithDefaultPrettyPrinter().writeValue(temporary.toFile(), manifest);
Files.move(temporary, path, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING);
} finally {
Files.deleteIfExists(temporary);
}
return new ProjectCartridgeConfiguration(id, config.memcardSlots());
}
public static Path developmentImage(ProjectReference project) {
return ProjectStudioPaths.studioRoot(project).resolve("memcard.pmc");
}
public static Path selectedImage(ProjectReference project, p.studio.api.project.ProjectLocalStudioSetup setup) {
return setup.memcardPath() == null ? developmentImage(project)
: project.rootPath().resolve(setup.memcardPath()).toAbsolutePath().normalize();
}
}
@@ -137,7 +137,12 @@ public final class ProjectCatalogService implements ProjectCatalog {
} catch (IllegalArgumentException exception) {
throw new IllegalArgumentException("project manifest invalid target: " + manifestPath(normalized), exception);
}
return new ProjectReference(name, version, language, stdlib, target, normalized);
final ProjectCartridgeConfiguration cartridge;
try {
cartridge = ProjectCartridgeConfiguration.read(mapper.readTree(manifestPath(normalized).toFile()));
} catch (IOException exception) { throw new UncheckedIOException(exception); }
return new ProjectReference(name, version, language, stdlib, target, normalized,
cartridge.appId(), cartridge.memcardSlots());
}
private boolean isValidProjectRoot(Path path) {
@@ -164,10 +169,11 @@ public final class ProjectCatalogService implements ProjectCatalog {
"language": "%s",
"stdlib": "%d",
"target": "%s",
"app_id": %d,
"dependencies": []
}
""".formatted(project.name(), project.version(), project.languageId(),
project.stdlibVersion(), project.target().exportReferenceName());
project.stdlibVersion(), project.target().exportReferenceName(), ProjectCartridgeConfiguration.legacyAppId(project));
}
private String defaultGitIgnore() {
@@ -9,10 +9,19 @@ import java.util.function.Consumer;
/** Neutral runtime port. The process adapter owns protocol, effective limits and supervision. */
public interface HeadlessGateway {
Session boot(ProjectReference project, String buildId, ShipperPrepareResult build) throws Exception;
default Session boot(ProjectReference project, String buildId, ShipperPrepareResult build, Map<String, Object> options) throws Exception {
if (!options.isEmpty()) throw new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Runtime boot options unavailable");
return boot(project, buildId, build);
}
interface Session extends ManagedHeadlessSession {
long maxFramesPerAdvance();
TaskTools.HeadlessReply call(TaskTools.HeadlessAction action, Map<String, Object> input) throws Exception;
AutomationOutcome advance(long frames, Consumer<TrackedOperation.Progress> progress) throws Exception;
default java.util.concurrent.CompletionStage<TaskTools.HeadlessReply> stop(Map<String, Object> policy) {
if (!policy.isEmpty()) return java.util.concurrent.CompletableFuture.failedFuture(
new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Runtime teardown options unavailable"));
return shutdown().thenApply(v -> new TaskTools.HeadlessReply(Map.of("sessionId", sessionId()), null));
}
}
}
@@ -174,6 +174,13 @@ public final class DefaultAutomationSession implements AutomationSession {
return beginReturn(false, identity, true);
}
@Override public CompletionStage<ControlResult> reclaim() { return beginReturn(false, null, false); }
@Override public CompletionStage<ControlResult> reclaimDiscardingUnsavedGameData() {
synchronized (this) {
if (state != ControlState.RETURNING_CONTROL || returning == null || !returning.isDone())
return result(ControlResult.Status.BUSY, "First request ordinary reclaim and inspect its result");
}
return beginReturn(false, null, false, true);
}
@Override public CompletionStage<ControlResult> closeAsync() {
var cleanup = beginReturn(true, null, false);
for (var participant : List.copyOf(documents)) {
@@ -183,6 +190,9 @@ public final class DefaultAutomationSession implements AutomationSession {
}
private CompletionStage<ControlResult> beginReturn(boolean closing, TaskIdentity identity, boolean requireIdentity) {
return beginReturn(closing, identity, requireIdentity, false);
}
private CompletionStage<ControlResult> beginReturn(boolean closing, TaskIdentity identity, boolean requireIdentity, boolean discardUnsaved) {
final CompletableFuture<ControlResult> result;
final OperationHandle<AutomationOutcome> operation;
final ManagedHeadlessSession ownedRuntime;
@@ -217,7 +227,7 @@ public final class DefaultAutomationSession implements AutomationSession {
if (operation != null) operation.cancel();
CompletionStage<Void> stopped = operation == null ? CompletableFuture.completedFuture(null) : operation.termination();
CompletionStage<Void> shutdown = CompletableFuture.completedFuture(null);
if (ownedRuntime != null) { ownedRuntime.cancel(); shutdown = ownedRuntime.shutdown(); }
if (ownedRuntime != null) { ownedRuntime.cancel(); shutdown = ownedRuntime.shutdown(discardUnsaved); }
cleanup = CompletableFuture.allOf(stopped.toCompletableFuture(), shutdown.toCompletableFuture(), idle, publisherIdle, publicationCleanup.toCompletableFuture());
cleanup = cleanup.whenComplete((v, failure) -> cleanups.forEach(Runnable::run));
// Closing disposes documents; an explicit return must refresh them before unlocking.
@@ -315,6 +325,8 @@ public final class DefaultAutomationSession implements AutomationSession {
}
private static String message(Throwable failure) {
while (failure instanceof CompletionException && failure.getCause() != null) failure = failure.getCause();
if (failure instanceof AutomationException nativeFailure && nativeFailure.failure().code() == AutomationFailure.Code.MEMCARD_ERROR)
return nativeFailure.getMessage() + "\n" + nativeFailure.failure().runtimeError();
return Objects.requireNonNullElse(failure.getMessage(), failure.getClass().getSimpleName());
}
}
@@ -126,10 +126,10 @@ public final class DefaultTaskTools implements TaskTools {
if (build == null) throw failure(AutomationFailure.Code.BUILD_NOT_FOUND, "No successful current task build with this ID");
if (data.runtime != null) {
if (!buildId.equals(data.runtimeBuildId)) throw failure(AutomationFailure.Code.BUILD_NOT_FOUND, "Reset session belongs to another build");
result = data.runtime.call(HeadlessAction.BOOT, Map.of());
result = data.runtime.call(HeadlessAction.BOOT, input);
} else {
var port = gateway.orElseThrow(() -> failure(AutomationFailure.Code.RUNTIME_UNAVAILABLE, "Headless process adapter is not composed"));
var runtime = port.boot(catalog.openProject(data.task.projectRoot()), buildId, build);
var runtime = port.boot(catalog.openProject(data.task.projectRoot()), buildId, build, input);
try { session.attachRuntime(data.task, runtime); }
catch (RuntimeException denied) { runtime.cancel(); runtime.shutdown().toCompletableFuture().join(); throw denied; }
data.runtime = runtime;
@@ -138,9 +138,13 @@ public final class DefaultTaskTools implements TaskTools {
}
data.reset = false;
} else if (action == HeadlessAction.SHUTDOWN) {
String sessionId = requireRuntime(data).sessionId();
stopRuntime(data);
result = new HeadlessReply(Map.of("sessionId", sessionId), null);
try { result = requireRuntime(data).stop(input).toCompletableFuture().join(); }
catch (CompletionException failure) {
if (failure.getCause() instanceof RuntimeException cause) throw cause;
throw failure;
}
data.session.detachRuntime(data.task, data.runtime);
data.runtime = null; data.runtimeBuildId = null; data.reset = false;
} else {
result = requireRuntime(data).call(action, input);
if (action == HeadlessAction.RESET) { data.reset = true; session.markCaptureStale(); }
@@ -169,7 +173,11 @@ public final class DefaultTaskTools implements TaskTools {
var runtime = data.runtime;
if (runtime == null) return;
runtime.cancel();
runtime.shutdown().toCompletableFuture().join();
try { runtime.shutdown().toCompletableFuture().join(); }
catch (CompletionException failure) {
if (failure.getCause() instanceof RuntimeException cause) throw cause;
throw failure;
}
data.session.detachRuntime(data.task, runtime);
data.runtime = null;
data.runtimeBuildId = null;
@@ -64,6 +64,10 @@ public final class StudioShipperService implements Shipper, SavedProjectPreparat
final CompilerBuildGateway.CompilerBuildOutput build = compiler.compile(project,
message -> emit(logs, sink, ShipperLogEntry.info(ShipperLogSource.BUILD, normalize(message))));
checkCancelled();
final var cartridge = p.studio.core.project.ProjectCartridgeConfiguration.adopt(project, mapper);
if ((cartridge.memcardSlots() != null) != build.requiredCapabilities().contains("memcard")) {
throw new IllegalArgumentException("memcard_slots and compiled memcard capability must be declared together");
}
if (build.bytecodeArtifact() != null) {
emit(logs, sink, ShipperLogEntry.info(ShipperLogSource.BUILD,
"Prepared program bytecode at " + build.bytecodeArtifact()));
@@ -88,7 +92,7 @@ public final class StudioShipperService implements Shipper, SavedProjectPreparat
artifacts.forEach(path -> emit(logs, sink, ShipperLogEntry.info(ShipperLogSource.PACK, "Emitted " + path)));
final Path manifest = writeManifest(project, build, logs, sink);
return new ShipperPrepareResult(ShipperPreparationStatus.SUCCESS, logs, manifest, artifacts, diagnostics);
} catch (RuntimeException exception) {
} catch (IOException | RuntimeException exception) {
final String message = exception.getMessage() == null ? exception.getClass().getSimpleName() : exception.getMessage();
diagnostics.add(message);
emit(logs, sink, ShipperLogEntry.error(ShipperLogSource.BUILD, message));
@@ -109,7 +113,9 @@ public final class StudioShipperService implements Shipper, SavedProjectPreparat
final ObjectNode manifest = mapper.createObjectNode();
manifest.put("magic", "PMTU");
manifest.put("cartridge_version", 1);
manifest.put("app_id", stableAppId(project));
final var cartridge = p.studio.core.project.ProjectCartridgeConfiguration.adopt(project, mapper);
manifest.put("app_id", cartridge.appId());
if (cartridge.memcardSlots() != null) manifest.put("memcard_slots", cartridge.memcardSlots());
manifest.put("title", project.name());
manifest.put("app_version", project.version());
manifest.put("app_mode", project.target().exportReferenceName());
@@ -134,11 +140,6 @@ public final class StudioShipperService implements Shipper, SavedProjectPreparat
return loaded != null && loaded.isArray() ? loaded : mapper.createArrayNode();
}
private int stableAppId(ProjectReference project) {
final int hash = Objects.hash(project.name(), project.version(), project.languageId(), project.stdlibVersion());
return hash == Integer.MIN_VALUE ? 1 : Math.max(1, Math.abs(hash));
}
private ShipperLogEntry logFor(PackerOperationStatus status, ShipperLogSource source, String message) {
return status == PackerOperationStatus.SUCCESS
? ShipperLogEntry.info(source, message)
@@ -0,0 +1,42 @@
package p.studio.core.project;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import p.studio.api.project.*;
import java.nio.file.*;
import static org.junit.jupiter.api.Assertions.*;
class ProjectCartridgeConfigurationTest {
@TempDir Path root;
final ObjectMapper mapper = new ObjectMapper();
ProjectReference project(String name, String version, String language, int stdlib) {
return new ProjectReference(name, version, language, stdlib, ProjectTarget.Game, root);
}
@Test void adoptionPreservesLegacyIdentityUnknownFieldsAndAllLaterMetadataChanges() throws Exception {
Files.writeString(root.resolve("prometeu.json"), "{\"name\":\"Original\",\"custom\":{\"kept\":true},\"memcard_slots\":64}");
var original = project("Original", "1", "pbs", 1);
var initial = ProjectCartridgeConfiguration.adopt(original, mapper);
assertEquals(ProjectCartridgeConfiguration.legacyAppId(original), initial.appId());
assertEquals(64, initial.memcardSlots());
assertTrue(mapper.readTree(root.resolve("prometeu.json").toFile()).path("custom").path("kept").booleanValue());
byte[] persisted = Files.readAllBytes(root.resolve("prometeu.json"));
assertEquals(initial, ProjectCartridgeConfiguration.adopt(project("Renamed", "2", "other", 2), mapper));
assertArrayEquals(persisted, Files.readAllBytes(root.resolve("prometeu.json")));
assertEquals(root.resolve(".studio/memcard.pmc"), ProjectCartridgeConfiguration.developmentImage(original));
}
@Test void strictUnsignedIdentityAndSlotsDoNotRewriteInvalidInput() throws Exception {
for (var field : java.util.List.of("app_id", "memcard_slots")) {
for (var value : java.util.List.of("null", "true", "\"1\"", "1.5", "-1", "4294967296", "18446744073709551616")) {
String json = "{\"" + field + "\":" + value + "}";
Files.writeString(root.resolve("prometeu.json"), json);
assertThrows(IllegalArgumentException.class, () -> ProjectCartridgeConfiguration.adopt(project("a", "1", "pbs", 1), mapper), json);
assertEquals(json, Files.readString(root.resolve("prometeu.json")));
}
}
assertEquals(0xffff_ffffL, ProjectCartridgeConfiguration.read(mapper.readTree("{\"app_id\":4294967295,\"memcard_slots\":1}")).appId());
assertEquals(0L, ProjectCartridgeConfiguration.read(mapper.readTree("{\"app_id\":0}")).appId());
for (var value : java.util.List.of("0", "65"))
assertThrows(IllegalArgumentException.class, () -> ProjectCartridgeConfiguration.read(mapper.readTree("{\"memcard_slots\":" + value + "}")));
}
}
@@ -79,4 +79,15 @@ final class ProjectLocalStudioSetupStoreTest {
final Path projectRoot = tempDir.resolve(name);
return new ProjectReference("Main", "1.0.0", "pbs", 1, ProjectTarget.Game, projectRoot);
}
@Test void explicitMediaSelectionIsLocalAndSurvivesSetupRoundTrip() {
var service = new ProjectLocalStudioSetupStore(new com.fasterxml.jackson.databind.ObjectMapper());
var project = project("media");
var setup = new ProjectLocalStudioSetup("/runtime", null, null, " ../shared/save.pmc ");
service.save(project, setup);
assertEquals(setup, service.load(project));
assertEquals(project.rootPath().resolve("../shared/save.pmc").toAbsolutePath().normalize(),
ProjectCartridgeConfiguration.selectedImage(project, service.load(project)));
assertEquals(ProjectStudioPaths.studioRoot(project).resolve("memcard.pmc"),
ProjectCartridgeConfiguration.selectedImage(project, ProjectLocalStudioSetup.defaults()));
}
}
@@ -0,0 +1,64 @@
package p.studio.core.project;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import p.studio.api.project.*;
import p.studio.api.operation.*;
import p.studio.core.shipper.*;
import p.packer.PackerWorkspaceService;
import p.packer.messages.*;
import p.packer.dtos.PackerPackExecutionSummaryDTO;
import java.nio.file.*;
import java.lang.reflect.Proxy;
import java.util.*;
import java.util.concurrent.Callable;
import static org.junit.jupiter.api.Assertions.*;
class StudioMemcardShipperTest {
@TempDir Path root;
final ObjectMapper mapper = new ObjectMapper();
private StudioShipperService shipper(List<String> capabilities) {
var packer = (PackerWorkspaceService) Proxy.newProxyInstance(PackerWorkspaceService.class.getClassLoader(),
new Class<?>[]{PackerWorkspaceService.class}, (proxy, method, args) -> switch (method.getName()) {
case "validatePackWorkspace" -> new ValidatePackWorkspaceResult(PackerOperationStatus.SUCCESS, "ready", List.of());
case "packWorkspace" -> new PackWorkspaceResult(PackerOperationStatus.SUCCESS, "packed",
new PackerPackExecutionSummaryDTO("test", 0, 0, List.of()));
default -> throw new AssertionError(method.getName());
});
var executor = new OperationExecutor() { public <R> OperationHandle<R> submit(String text, Callable<R> task) { throw new AssertionError("direct prepare only"); } };
return new StudioShipperService((project, logs) -> new CompilerBuildGateway.CompilerBuildOutput(null, capabilities), packer, mapper, executor);
}
private ProjectReference project() { return new ProjectReference("Game", "1", "pbs", 1, ProjectTarget.Game, root); }
@Test void emitsUnsignedIdentitySlotsAndCapabilityWithoutHostConfiguration() throws Exception {
for (int count : List.of(1,64)) {
Files.writeString(root.resolve("prometeu.json"), "{\"app_id\":4294967295,\"memcard_slots\":"+count+"}");
var result = shipper(List.of("memcard")).prepareNow(project(), log -> {});
assertTrue(result.success(), result.diagnostics().toString());
var manifest = mapper.readTree(result.manifestPath().toFile());
assertEquals(4294967295L, manifest.path("app_id").longValue());
assertEquals(count, manifest.path("memcard_slots").intValue());
assertEquals("memcard", manifest.path("capabilities").get(0).textValue());
assertFalse(manifest.has("memcard_path"));
}
}
@Test void legacyOrdinaryProjectKeepsIdentityAcrossLaterVersionAndOmitsSlots() throws Exception {
Files.writeString(root.resolve("prometeu.json"), "{\"custom\":true}");
var first = shipper(List.of()).prepareNow(project(), log -> {});
assertTrue(first.success(),first.diagnostics().toString());
var saved = mapper.readTree(first.manifestPath().toFile());
assertFalse(saved.has("memcard_slots"));
var changed = new ProjectReference("Rename", "2", "other", 2, ProjectTarget.Game, root);
var second = shipper(List.of()).prepareNow(changed, log -> {});
assertTrue(second.success());
assertEquals(saved.path("app_id"),mapper.readTree(second.manifestPath().toFile()).path("app_id"));
assertTrue(mapper.readTree(root.resolve("prometeu.json").toFile()).path("custom").booleanValue());
}
@Test void rejectsPartialConfiguration() throws Exception {
Files.writeString(root.resolve("prometeu.json"), "{\"app_id\":1,\"memcard_slots\":1}");
assertFalse(shipper(List.of()).prepareNow(project(),log -> {}).success());
Files.writeString(root.resolve("prometeu.json"), "{\"app_id\":1}");
assertFalse(shipper(List.of("memcard")).prepareNow(project(),log -> {}).success());
assertFalse(Files.exists(root.resolve("build/manifest.json")));
}
}
@@ -205,6 +205,26 @@ class DefaultAutomationSessionTest {
docs.refresh = CompletableFuture.completedFuture(null);
assertEquals(RETURNED, await(s.reclaim()).status()); assertTrue(s.snapshot().manualAllowed());
}
@Test void protectedReclaimKeepsRuntimeUntilHumanExplicitlyDiscardsGameRam() {
var s = session(); var task = start(s);
var discarded = new java.util.concurrent.atomic.AtomicBoolean();
s.attachRuntime(task, new ManagedHeadlessSession() {
public String sessionId() { return "dirty"; }
public void cancel() { }
public CompletionStage<Void> shutdown() { return shutdown(false); }
public CompletionStage<Void> shutdown(boolean consent) {
if (!consent) return CompletableFuture.failedFuture(new AutomationException(new AutomationFailure(
AutomationFailure.Code.MEMCARD_ERROR, "Unsaved changes", java.util.Map.of("details", java.util.Map.of("reason", "unsaved_changes")))));
discarded.set(true); return CompletableFuture.completedFuture(null);
}
});
assertEquals(BUSY, await(s.reclaimDiscardingUnsavedGameData()).status());
assertEquals(CLEANUP_FAILED, await(s.reclaim()).status());
assertFalse(discarded.get()); assertFalse(s.snapshot().manualAllowed());
assertTrue(s.snapshot().diagnostics().toString().contains("unsaved_changes"));
assertEquals(RETURNED, await(s.reclaimDiscardingUnsavedGameData()).status());
assertTrue(discarded.get()); assertTrue(s.snapshot().manualAllowed());
}
@Test void registryIsPerProjectAndClosedAuthorityCannotBeReused() {
var registry = new ProjectAccessRegistry(); var s = session();