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,244 @@
package p.studio.app.runtime;
import com.fasterxml.jackson.databind.*;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.io.TempDir;
import p.studio.api.automation.*;
import p.studio.api.project.*;
import p.studio.api.shipper.ShipperPrepareResult;
import p.studio.app.operation.ExecutorOperationExecutor;
import p.studio.core.project.*;
import p.studio.core.shipper.*;
import p.studio.compiler.messages.BuilderPipelineConfig;
import p.studio.compiler.models.BuilderPipelineContext;
import p.studio.compiler.workspaces.BuilderPipelineService;
import p.studio.utilities.logs.LogAggregator;
import java.nio.file.*;
import java.util.*;
import java.util.concurrent.*;
import static org.junit.jupiter.api.Assertions.*;
/** PBS/shipper -> configured dispatcher -> distinct OS processes; no native injection. */
class MemcardInstalledRuntimeTest {
@TempDir Path root;
final ObjectMapper mapper = new ObjectMapper();
static final String PREFIX = """
import {Mem, MemcardBuffer} from @sdk:mem;
import {Color} from @core:color;
import {Gfx} from @sdk:gfx;
declare global context: long = 0;
""";
static final String WRITER = PREFIX + """
declare global request: long = 0;
declare global saved: bool = false;
[MemcardBoot] fn restore(c: long) -> int {
context = c;
let icon = new MemcardBuffer(560);
if Mem.presentation(c, "Process persistence", 1 as long, 1, 1, icon, 0, 560) != 0 as long { return 1; }
return 0;
}
[Frame] fn frame() -> void {
if saved { Gfx.clear(Color.rgb(0, 255, 0)); return; }
Gfx.clear(Color.rgb(255, 0, 0));
if request == 0 as long {
let bytes = new MemcardBuffer(4);
bytes.write(0, 0); bytes.write(1, 127); bytes.write(2, 128); bytes.write(3, 255);
let written = Mem.slot_write(context, 0, 0, bytes, 0, 4);
if written.status != 0 as long or written.bytes_written != 4 as long { let fail = 1 / 0; }
let commit = Mem.slot_commit(context, 0);
if commit.status != 0 as long { let fail = 1 / 0; }
request = commit.request;
return;
}
let observation = Mem.query(context, request);
if observation.status != 0 as long { let fail = 1 / 0; }
if observation.state == 0 as long { return; }
if observation.state != 1 as long { let fail = 1 / 0; }
saved = true;
}
""";
static final String READER = PREFIX + """
[MemcardBoot] fn restore(c: long) -> int {
context = c;
let stat = Mem.slot_stat(c, 0);
if stat.status != 0 as long { return 1; }
if stat.used_bytes != 4 as long { return 1; }
let bytes = new MemcardBuffer(4);
let read = Mem.slot_read(c, 0, 0, bytes, 0, 4);
if read.status != 0 as long { return 1; }
if read.bytes_read != 4 as long { return 1; }
if bytes.read(0) != 0 or bytes.read(1) != 127 or bytes.read(2) != 128 or bytes.read(3) != 255 { return 1; }
return 0;
}
[Frame] fn frame() -> void { Gfx.clear(Color.rgb(0, 127, 255)); }
""";
private ShipperPrepareResult build(Path projectRoot, String source, String version, boolean optimized, p.packer.Packer packer) throws Exception {
Files.createDirectories(projectRoot.resolve("src"));
Files.writeString(projectRoot.resolve("prometeu.json"), """
{"name":"process-memcard","version":"%s","language":"pbs","stdlib":"1","target":"Game",
"dependencies":[],"app_id":4294967295,"memcard_slots":1}
""".formatted(version));
Files.writeString(projectRoot.resolve("src/mod.barrel"), "pub fn frame() -> void;");
Files.writeString(projectRoot.resolve("src/main.pbs"), source);
CompilerBuildGateway compiler = (project, log) -> {
var result = BuilderPipelineService.INSTANCE.build(BuilderPipelineContext.fromConfig(
new BuilderPipelineConfig(false, project.rootPath().toString())), LogAggregator.with(log));
var compiled = result.compileResult();
var program = optimized ? compiled.optimizedIrvm() : compiled.irvm();
var module = new p.studio.compiler.backend.bytecode.BytecodeEmitter().emit(program.coherentEmissionPlan());
new p.studio.compiler.backend.bytecode.BytecodePreloadVerifierService().verify(module);
if (source.equals(READER)) verifyReadOnlyOracle(program.coherentEmissionPlan());
try { Files.write(result.bytecodeArtifactPath(), module.serialize()); }
catch (java.io.IOException failure) { throw new java.io.UncheckedIOException(failure); }
return new CompilerBuildGateway.CompilerBuildOutput(result.bytecodeArtifactPath(),
compiled.analysisSnapshot().irBackend().getReservedMetadata().requiredCapabilities().asList());
};
var setup = new ProjectLocalStudioSetupStore(mapper);
var project = new ProjectCatalogService(projectRoot, mapper, setup).openProject(projectRoot);
try (var workers = Executors.newSingleThreadExecutor()) {
var build = new StudioShipperService(compiler, packer.workspaceService(), mapper, new ExecutorOperationExecutor(workers))
.prepare(project, ignored -> {}).completion().toCompletableFuture().get(30, TimeUnit.SECONDS);
assertTrue(build.success(), build.diagnostics().toString());
var manifest = mapper.readTree(build.manifestPath().toFile());
assertEquals(4294967295L, manifest.path("app_id").longValue()); assertEquals(version, manifest.path("app_version").asText());
System.out.println("MEMCARD ARTIFACT " + mapper.writeValueAsString(Map.of(
"optimized", optimized, "version", version, "producer", source.equals(WRITER) ? "writer" : source.equals(READER) ? "reader" : "dirty",
"pbxSha256", sha(Files.readAllBytes(build.manifestPath().getParent().resolve("program.pbx"))),
"manifestSha256", sha(Files.readAllBytes(build.manifestPath())),
"sourceSha256", sha(source.getBytes(java.nio.charset.StandardCharsets.UTF_8)))));
return build;
}
}
private static String sha(byte[] bytes) throws Exception {
return java.util.HexFormat.of().formatHex(java.security.MessageDigest.getInstance("SHA-256").digest(bytes));
}
private void verifyReadOnlyOracle(p.studio.compiler.backend.bytecode.BytecodeEmitter.EmissionPlan plan) {
// SDK definitions may retain unused imports. Follow executable entry/roles,
// including closure construction, rather than treating imports as calls.
var pending = new ArrayDeque<Integer>(); pending.add(0);
for (int i = 0; i < plan.functions().size(); i++)
if (plan.functions().get(i).metadata().role() != p.studio.compiler.models.registry.IRRegistry.Role.NONE) pending.add(i);
var visited = new HashSet<Integer>();
while (!pending.isEmpty()) {
int index = pending.remove(); if (!visited.add(index)) continue;
for (var operation : plan.functions().get(index).operations()) {
if (operation.kind() == p.studio.compiler.backend.bytecode.BytecodeEmitter.OperationKind.CALL_FUNC) pending.add(operation.immediate());
if (operation.kind() == p.studio.compiler.backend.bytecode.BytecodeEmitter.OperationKind.REGISTRY) {
var instruction = operation.registryInstruction();
if (instruction.op().opcode() == 0x52) pending.add(instruction.immediate());
assertNotEquals(0x53, instruction.op().opcode(), "Reader oracle must have a statically inspectable call graph");
assertNotEquals(0x58, instruction.op().opcode(), "Reader oracle must have no dynamic contract call");
}
if (operation.syscallDecl() != null) assertFalse(Set.of("slot_write", "slot_commit", "slot_clear", "presentation", "publish_presentation")
.contains(operation.syscallDecl().name()), "Reader must not reach a saving or presentation call");
}
}
}
private HeadlessProcessSession boot(Path projectRoot, ShipperPrepareResult build, Path image, String action, String choice, String access) throws Exception {
String installation = System.getProperty("studio.test.runtimeInstall", "");
assertFalse(installation.isBlank(), "Supply -PstudioRuntimeInstall=<configured runtime installation>");
var store = new ProjectLocalStudioSetupStore(mapper);
var project = new ProjectCatalogService(projectRoot, mapper, store).openProject(projectRoot);
store.save(project, new ProjectLocalStudioSetup(installation, null));
var session = (HeadlessProcessSession) new HeadlessProcessGateway(mapper, store::load).boot(project, "process-build", build,
Map.of("memcard", Map.of("path", image.toString(), "action", action, "access", access), "memcardChoice", choice));
System.out.println("MEMCARD process=" + session.pid() + " installation=" + installation + " choice=" + choice);
return session;
}
private JsonNode memcard(HeadlessProcessSession session) throws Exception {
return mapper.valueToTree(session.call(TaskTools.HeadlessAction.MEMCARD_STATE, Map.of()).values().get("memcard"));
}
private void close(HeadlessProcessSession session) throws Exception {
try { session.shutdown().toCompletableFuture().get(7, TimeUnit.SECONDS); assertFalse(session.alive()); }
finally { session.abort("test cleanup"); }
}
@Test void savesThenDifferentProcessesReadExactBytesAcrossVersionUpgradeWithoutResaving() throws Exception {
try (var packer = p.packer.Packer.bootstrap(mapper, ignored -> {})) {
for (boolean optimized : new boolean[]{false, true}) {
Path project = root.resolve(optimized ? "optimized" : "ordinary");
Path image = root.resolve(optimized ? "optimized.pmc" : "ordinary.pmc");
var writer = boot(project, build(project, WRITER, "1", optimized, packer), image, "create", "persistent", "read_write");
long writerPid = writer.pid();
try {
long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(15);
JsonNode state;
do {
var outcome = writer.advance(1, ignored -> {});
assertEquals(AutomationOutcome.Kind.SUCCEEDED, outcome.kind(), outcome.diagnostics().toString());
state = memcard(writer);
assertTrue(System.nanoTime() < deadline, state.toString());
} while (!state.path("request").path("operation").asText().equals("commit") || !state.path("request").path("state").asText().equals("success"));
assertFalse(state.path("dirty").booleanValue()); assertFalse(state.path("io").path("active").booleanValue());
} finally { close(writer); }
byte[] durable = Files.readAllBytes(image);
for (String version : List.of("1", "2")) {
var reader = boot(project, build(project, READER, version, optimized, packer), image, "open", "persistent", "read_write");
assertNotEquals(writerPid, reader.pid());
try {
var outcome = reader.advance(2, ignored -> {});
assertEquals(AutomationOutcome.Kind.SUCCEEDED, outcome.kind(), outcome.diagnostics().toString());
assertNotNull(outcome.capture());
var pixels = javax.imageio.ImageIO.read(new java.io.ByteArrayInputStream(outcome.capture().png()));
assertEquals(0xff007fff, pixels.getRGB(0, 0), "Reader renders oracle only after exact bootstrap validation");
var state = memcard(reader);
assertTrue(state.path("request").isNull(), state.toString());
assertEquals(4294967295L, state.path("session").path("appId").longValue());
} finally { close(reader); }
assertArrayEquals(durable, Files.readAllBytes(image), "Readback must not rewrite media");
System.out.println("PASS PBS process save/reopen optimizer=" + optimized + " version=" + version + " unchangedImageSha256=" + sha(durable));
}
}
}
}
@Test void memoryOnlyShutdownRefusalKeepsSessionUntilExplicitDiscardAndOpenNeverCreates() throws Exception {
try (var packer = p.packer.Packer.bootstrap(mapper, ignored -> {})) {
Path project = root.resolve("memory");
String dirty = PREFIX + """
[MemcardBoot] fn restore(c: long) -> int {
context = c;
if Mem.presentation(c, "Dirty", 1 as long, 1, 1, new MemcardBuffer(560), 0, 560) != 0 as long { return 1; }
return 0;
}
[Frame] fn frame() -> void {
Mem.slot_write(context, 0, 0, new MemcardBuffer(1), 0, 1);
Gfx.clear(Color.rgb(1, 2, 3));
}
""";
var build = build(project, dirty, "1", true, packer);
var store = new ProjectLocalStudioSetupStore(mapper);
var reference = new ProjectCatalogService(project, mapper, store).openProject(project);
store.save(reference, new ProjectLocalStudioSetup(System.getProperty("studio.test.runtimeInstall"), null));
var gateway = new HeadlessProcessGateway(mapper, store::load);
Path absent = root.resolve("absent.pmc");
var failure = assertThrows(AutomationException.class, () -> gateway.boot(reference, "missing", build,
Map.of("memcard", Map.of("path", absent.toString(), "action", "open", "access", "read_write"), "memcardChoice", "persistent")));
assertEquals(AutomationFailure.Code.MEMCARD_ERROR, failure.failure().code()); assertFalse(Files.exists(absent));
var memory = (HeadlessProcessSession) gateway.boot(reference, "memory", build, Map.of("memcardChoice", "memory_fresh"));
try {
assertEquals(AutomationOutcome.Kind.SUCCEEDED, memory.advance(1, ignored -> {}).kind());
var refusal = assertThrows(ExecutionException.class, () -> memory.shutdown().toCompletableFuture().get(7, TimeUnit.SECONDS));
assertEquals(AutomationFailure.Code.MEMCARD_ERROR, ((AutomationException) refusal.getCause()).failure().code());
assertTrue(memory.alive()); assertTrue(memcard(memory).path("dirty").booleanValue());
var resetRefusal = assertThrows(AutomationException.class, () -> memory.call(TaskTools.HeadlessAction.RESET, Map.of()));
assertEquals(AutomationFailure.Code.MEMCARD_ERROR, resetRefusal.failure().code());
assertTrue(memory.alive()); assertTrue(memcard(memory).path("dirty").booleanValue());
memory.call(TaskTools.HeadlessAction.RESET, Map.of("discardUnsaved", true, "pendingWrites", "cancel"));
assertFalse(memcard(memory).path("dirty").booleanValue());
assertFalse(Files.exists(project.resolve(".studio/memcard.pmc")));
memory.call(TaskTools.HeadlessAction.MEMCARD_MOUNT, Map.of("action", "create", "access", "read_write"));
assertTrue(Files.isRegularFile(project.resolve(".studio/memcard.pmc")));
memory.call(TaskTools.HeadlessAction.MEMCARD_UNMOUNT, Map.of());
for (var recovery : List.of(TaskTools.HeadlessAction.MEMCARD_RECONCILE, TaskTools.HeadlessAction.MEMCARD_CONTINUE_IN_MEMORY)) {
var rejected = assertThrows(AutomationException.class, () -> memory.call(recovery, Map.of()));
assertEquals(AutomationFailure.Code.MEMCARD_ERROR, rejected.failure().code());
var details = mapper.valueToTree(rejected.failure().runtimeError()).path("details");
assertEquals("invalid_state", details.path("reason").asText());
assertTrue(memory.alive());
}
memory.stop(Map.of("discardUnsaved", true, "pendingWrites", "cancel")).toCompletableFuture().get(7, TimeUnit.SECONDS);
assertFalse(memory.alive());
System.out.println("PASS protected reset/shutdown, explicit default-path create/unmount and native recovery refusal");
} finally { memory.abort("test cleanup"); }
}
}
}