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,270 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import p.studio.compiler.messages.*;
import p.studio.compiler.models.*;
import p.studio.compiler.models.registry.IRRegistry;
import p.studio.compiler.workspaces.BuilderPipelineService;
import p.studio.utilities.logs.LogAggregator;
import java.nio.file.*;
import java.util.*;
import static org.junit.jupiter.api.Assertions.*;
class PbsMemcardTest {
@TempDir Path root;
private CompileResult compile(Path project) {
return BuilderPipelineService.INSTANCE.compile(BuilderPipelineContext.fromConfig(
new BuilderPipelineConfig(false, project.toString())), LogAggregator.stdout());
}
private void fixture(String name, CompileResult result) throws Exception {
var directory = Path.of(System.getProperty("pbs.registryConformanceDirectory"));
Files.createDirectories(directory);
for (boolean optimize : new boolean[]{false, true}) {
var program = optimize ? new OptimizeIRVMService().optimize(result.irvm()) : result.irvm();
var output = new p.studio.compiler.backend.bytecode.BytecodeEmitter().emit(program.coherentEmissionPlan());
new p.studio.compiler.backend.bytecode.BytecodePreloadVerifierService().verify(output);
Files.write(directory.resolve(name + (optimize ? "-optimized" : "") + ".pbx"), output.serialize());
}
}
private Path project(String source, String configuration) throws Exception {
Files.createDirectories(root.resolve("src"));
Files.writeString(root.resolve("prometeu.json"), "{\"name\":\"memcard\",\"version\":\"1\",\"language\":\"pbs\",\"stdlib\":\"1\",\"target\":\"Game\",\"dependencies\":[]" + configuration + "}");
Files.writeString(root.resolve("src/mod.barrel"), "pub fn frame() -> void;");
Files.writeString(root.resolve("src/main.pbs"), source);
return root;
}
@Test void allFourteenNativeImportsKeepExactArgumentAndResultCounts() throws Exception {
var compiled = compile(project("""
import {Mem, MemcardBuffer} from @sdk:mem;
declare global context: long = 0;
[MemcardBoot] fn boot(c: long) -> int { context = c; return 0; }
[Frame] fn frame() -> void {
let bytes = new MemcardBuffer(560);
Mem.slot_count(context); Mem.slot_stat(context, 0);
Mem.slot_read(context, 0, 0, bytes, 0, 4);
Mem.slot_write(context, 0, 0, bytes, 0, 4);
Mem.slot_commit(context, 0); Mem.slot_clear(context, 0);
Mem.query(context, 1 as long); Mem.release(context, 1 as long);
Mem.info(context); Mem.metadata(context);
Mem.presentation(context, "ABI", 1 as long, 1, 1, bytes, 0, 560);
Mem.diagnostic(context, "ABI"); Mem.publish_presentation(context);
}
""", ",\"app_id\":4294967295,\"memcard_slots\":1"));
var expected = Map.ofEntries(Map.entry("bootstrap", "0/1"), Map.entry("slot_count", "1/2"),
Map.entry("slot_stat", "2/7"), Map.entry("slot_read", "6/2"), Map.entry("slot_write", "6/2"),
Map.entry("slot_commit", "2/2"), Map.entry("slot_clear", "2/1"), Map.entry("query", "2/3"),
Map.entry("release", "2/1"), Map.entry("info", "1/6"), Map.entry("metadata", "1/4"),
Map.entry("presentation", "8/1"), Map.entry("diagnostic", "2/1"), Map.entry("publish_presentation", "1/2"));
assertEquals(14, compiled.bytecodeModule().syscalls().size());
for (var binding : compiled.bytecodeModule().syscalls()) {
assertEquals("mem", binding.module()); assertEquals(1, binding.version());
assertEquals(expected.get(binding.name()), binding.argSlots() + "/" + binding.retSlots());
}
var carrier = compiled.bytecodeModule().registry().types().stream()
.filter(t -> "MemcardBuffer".equals(t.name())).findFirst().orElseThrow();
assertEquals(new IRRegistry.Array(IRRegistry.TypeRef.builtin(0x10)), carrier.body());
Path fixtures = Path.of(System.getProperty("pbs.registryConformanceDirectory"));
Files.createDirectories(fixtures); Files.write(fixtures.resolve("pbs-memcard-abi.pbx"), compiled.bytecodeBytes());
}
@Test void installedOptInSourceProducesExactRoleAndGateWithBothOptimizers() throws Exception {
var loader = p.studio.compiler.pbs.PbsFrontendCompiler.class.getClassLoader();
String prefix = "pbs-knowledge/examples/game/1/memcard/";
Files.createDirectories(root.resolve("src"));
for (String file : List.of("prometeu.json", "src/mod.barrel", "src/main.pbs")) {
try (var stream = loader.getResourceAsStream(prefix + file)) {
assertNotNull(stream, file); Files.copy(stream, root.resolve(file));
}
}
var result = compile(root);
assertFalse(result.diagnostics().stream().anyMatch(d -> d.isError()), result.diagnostics().toString());
var backend = result.analysisSnapshot().irBackend();
assertEquals(1, backend.getLifecycleDeclaration().bootstrapCalls().size());
Path fixtures = Path.of(System.getProperty("pbs.registryConformanceDirectory"));
Files.createDirectories(fixtures);
for (boolean optimize : new boolean[]{false, true}) {
var program = result.irvm();
if (optimize) program = new OptimizeIRVMService().optimize(program);
var output = new p.studio.compiler.backend.bytecode.BytecodeEmitter().emit(program.coherentEmissionPlan());
new p.studio.compiler.backend.bytecode.BytecodePreloadVerifierService().verify(output);
assertEquals(1, output.functions().stream().filter(f -> f.metadata().role() == IRRegistry.Role.MEMCARD_BOOT).count());
assertNotEquals(IRRegistry.Role.MEMCARD_BOOT, output.functions().getFirst().metadata().role());
var imports = output.syscalls();
assertEquals(1, imports.stream().filter(s -> s.module().equals("mem") && s.name().equals("bootstrap") && s.version() == 1 && s.argSlots() == 0 && s.retSlots() == 1).count());
Files.write(fixtures.resolve("pbs-memcard-example" + (optimize ? "-optimized" : "") + ".pbx"), output.serialize());
}
var source = Files.readString(root.resolve("src/main.pbs"));
Files.writeString(root.resolve("src/main.pbs"), source.replace("import {Mem, MemcardBuffer}",
"import {Mem as Card, MemcardBuffer as Bytes}")
.replace("new MemcardBuffer(", "new Bytes(").replace("Mem.", "Card."));
fixture("pbs-memcard-alias", compile(root));
Files.writeString(root.resolve("src/main.pbs"), source.replace("Mem.release(saveContext, saveRequest);", ""));
fixture("pbs-memcard-retained", compile(root));
var checks = """
let empty = new MemcardBuffer(0);
if empty.capacity() != 0 { let fail = 1 / 0; }
let native = new MemcardBuffer(2);
if native.capacity() != 2 or native.read(0) != 0 or native.read(1) != 0 { let fail = 1 / 0; }
let alias = passMemcardBuffer(native);
alias.write(1, 255);
if native.read(1) != 255 { let fail = 1 / 0; }
let capture = fn [native]() -> int { return native.read(1); };
if capture() != 255 { let fail = 1 / 0; }
let ordered = new MemcardBuffer(2);
ordered.write apply (value: byteEffect(2), index: byteEffect(1));
if byteOrder != 21 or ordered.read(1) != 2 { let fail = 1 / 0; }
let ordinary = new array<int>(2);
ordinary[0] = 0;
if ordinary[1].hasSome() { let fail = 1 / 0; }
if (ordinary[0] else 1) != 0 { let fail = 1 / 0; }
let count = Mem.slot_count(saveContext);
if count.status != 0 as long or count.count != 1 as long { let fail = 1 / 0; }
let info = Mem.info(saveContext);
if info.status != 0 as long { let fail = 1 / 0; }
let metadata = Mem.metadata(saveContext);
if metadata.status != 0 as long { let fail = 1 / 0; }
let badSlot = Mem.slot_read(saveContext, 64, 0, new MemcardBuffer(1), 0, 1);
if badSlot.status != 11 as long { let fail = 1 / 0; }
let namedFailure = Mem.slot_read apply (count: 1, array_offset: 0, bytes: new MemcardBuffer(1), offset: 0, slot: 64, context: saveContext);
if namedFailure.status != 11 as long { let fail = 1 / 0; }
let badRange = Mem.slot_write(saveContext, 0, 65536, new MemcardBuffer(1), 0, 1);
if badRange.status != 11 as long { let fail = 1 / 0; }
if Mem.diagnostic(saveContext, "Contract checks passed") != 0 as long { let fail = 1 / 0; }
if Mem.slot_clear(saveContext, 0) != 0 as long { let fail = 1 / 0; }
let source = new MemcardBuffer(4);
source.write(0, 0); source.write(1, 127); source.write(2, 128); source.write(3, 255);
let seeded = Mem.slot_write(saveContext, 0, 0, source, 0, 4);
if seeded.status != 0 as long { let fail = 1 / 0; }
let target = new MemcardBuffer(6);
for i: int from 0 until 6 { target.write(i, 11); }
let targetAlias = target;
let partial = Mem.slot_read(saveContext, 0, 1, target, 2, 2);
if partial.status != 0 as long or partial.bytes_read != 2 as long { let fail = 1 / 0; }
if targetAlias.read(2) != 127 or targetAlias.read(3) != 128 { let fail = 1 / 0; }
if target.read(0) != 11 or target.read(1) != 11 or target.read(4) != 11 or target.read(5) != 11 { let fail = 1 / 0; }
""";
Files.writeString(root.resolve("src/main.pbs"), source.replace("let bytes = new MemcardBuffer(4);", checks + "let bytes = new MemcardBuffer(4);")
+ "\nfn passMemcardBuffer(buffer: MemcardBuffer) -> MemcardBuffer { return buffer; }\n"
+ "declare global byteOrder: int = 0; fn byteEffect(value: int) -> int { byteOrder = byteOrder * 10 + value; return value; }\n");
fixture("pbs-memcard-contract", compile(root));
var publish = """
if saved {
let icon = new MemcardBuffer(560);
if Mem.presentation(saveContext, "Updated presentation", 2 as long, 1, 1, icon, 0, 560) != 0 as long { let fail = 1 / 0; }
let publication = Mem.publish_presentation(saveContext);
if publication.status != 0 as long { let fail = 1 / 0; }
saveRequest = publication.request;
}
""";
Files.writeString(root.resolve("src/main.pbs"), source.replace("saveRequest = 0 as long;", "saveRequest = 0 as long;" + publish));
fixture("pbs-memcard-publish", compile(root));
var clear = """
if clearing == false {
if Mem.slot_clear(saveContext, 0) != 0 as long { let fail = 1 / 0; }
let clearRequest = Mem.slot_commit(saveContext, 0);
if clearRequest.status != 0 as long { let fail = 1 / 0; }
saveRequest = clearRequest.request;
clearing = true;
completed = false;
}
""";
Files.writeString(root.resolve("src/main.pbs"), source.replace("declare global completed: bool = false;", "declare global completed: bool = false; declare global clearing: bool = false;")
.replace("saveRequest = 0 as long;", "saveRequest = 0 as long;" + clear));
fixture("pbs-memcard-clear", compile(root));
var busy = """
let blockedWrite = Mem.slot_write(saveContext, 0, 0, bytes, 0, 1);
if blockedWrite.status != 9 as long { let fail = 1 / 0; }
if Mem.slot_clear(saveContext, 0) != 9 as long { let fail = 1 / 0; }
let blockedCommit = Mem.slot_commit(saveContext, 0);
if blockedCommit.status != 9 as long { let fail = 1 / 0; }
""";
Files.writeString(root.resolve("src/main.pbs"), source.replace("if commit.status == 0 as long { saveRequest = commit.request; }", "if commit.status == 0 as long { saveRequest = commit.request;" + busy + "}"));
fixture("pbs-memcard-busy", compile(root));
Files.writeString(root.resolve("src/main.pbs"), source.replace("let bytes = new MemcardBuffer(4);",
"let bytes = new MemcardBuffer(4096); bytes.write(1, 127); bytes.write(2, 128); bytes.write(3, 255); bytes.write(4095, 255);")
.replace("Mem.slot_write(saveContext, 0, 0, bytes, 0, 4)", "Mem.slot_write(saveContext, 0, 0, bytes, 0, 4096)"));
fixture("pbs-memcard-transfer-limit", compile(root));
for (var trap : Map.of("byte-negative", "bytes.write(0, -1);", "byte-overflow", "bytes.write(0, 256);").entrySet()) {
Files.writeString(root.resolve("src/main.pbs"), source.replace("let write = Mem.slot_write", trap.getValue() + " let write = Mem.slot_write"));
fixture("pbs-memcard-" + trap.getKey(), compile(root));
}
Files.writeString(root.resolve("src/main.pbs"), source.replace("Mem.slot_write(saveContext, 0, 0, bytes, 0, 4)", "Mem.slot_write(saveContext, 0, 0, bytes, 0, 4097)"));
fixture("pbs-memcard-transfer-overflow", compile(root));
for (var test : Map.of("capacity-negative", "let invalid = new MemcardBuffer(-1);",
"capacity-overflow", "let invalid = new MemcardBuffer(4097);",
"read-bounds", "bytes.read(4);", "write-bounds", "bytes.write(-1, 42);").entrySet()) {
Files.writeString(root.resolve("src/main.pbs"), source.replace("let write = Mem.slot_write", test.getValue() + " let write = Mem.slot_write"));
fixture("pbs-memcard-" + test.getKey(), compile(root));
}
for (var test : Map.of("inconsistent", "return 1;", "trap", "let failed = 1 / 0; return 0;", "fuel", "while true {} return 0;").entrySet()) {
Files.writeString(root.resolve("src/main.pbs"), source.replace("return 0;\n}", test.getValue() + "\n}"));
var failure = compile(root);
assertFalse(failure.diagnostics().stream().anyMatch(d -> d.isError()), failure.diagnostics().toString());
fixture("pbs-memcard-" + test.getKey(), failure);
}
}
@Test void carrierIsNominalInSourceAndSdkOriginCannotBeForged() throws Exception {
String prefix = """
import {Mem, MemcardBuffer} from @sdk:mem;
[MemcardBoot] fn boot(context: long) -> int { return 0; }
""";
for (var body : List.of(
"let bad = new MemcardBuffer();",
"let bad = new MemcardBuffer(true);",
"let bad = new MemcardBuffer(4 as long);",
"let bytes = new array<int>(4); Mem.slot_write(1 as long, 0, 0, bytes, 0, 4);",
"let bytes = new MemcardBuffer(4); let ordinary: array<int> = bytes;")) {
project(prefix + "[Frame] fn frame() -> void {" + body + "}", ",\"memcard_slots\":1");
assertThrows(RuntimeException.class, () -> compile(root), body);
}
var diagnostics = p.studio.compiler.source.diagnostics.DiagnosticSink.empty();
new p.studio.compiler.pbs.PbsFrontendCompiler().compileFile(new p.studio.compiler.source.identifiers.FileId(0),
"[SdkMemcardBuffer] declare struct Fake() {}", diagnostics);
assertTrue(diagnostics.hasErrors(), "User source must not grant the native carrier layout");
}
@Test void importedMemcardHookHasOneCanonicalRoleAndRetainedDependencies() throws Exception {
project("""
import {selected as first, readBootCount} from @memcard:hooks;
import {selected as second} from @memcard:facade;
[Frame] fn frame() -> void { if readBootCount() != 1 { let fail = 1 / 0; } }
""", ",\"memcard_slots\":1");
Files.createDirectories(root.resolve("src/hooks"));
Files.createDirectories(root.resolve("src/facade"));
Files.writeString(root.resolve("src/hooks/mod.barrel"), "pub fn selected(context: long) -> int; pub fn readBootCount() -> int;");
Files.writeString(root.resolve("src/hooks/main.pbs"), """
import {Mem, MemcardBuffer} from @sdk:mem;
declare global boots: int = 0;
fn readBootCount() -> int { return boots; }
[MemcardBoot] fn selected(context: long) -> int {
boots += 1;
let icon = new MemcardBuffer(560);
if Mem.presentation(context, "Imported hook", 1 as long, 1, 1, icon, 0, 560) != 0 as long { return 1; }
return 0;
}
""");
Files.writeString(root.resolve("src/facade/mod.barrel"), "pub fn selected(context: long) -> int;");
Files.writeString(root.resolve("src/facade/main.pbs"), "import {selected} from @memcard:hooks;");
var result = compile(root);
assertEquals(1, result.bytecodeModule().functions().stream()
.filter(f -> f.metadata().role() == IRRegistry.Role.MEMCARD_BOOT).count());
fixture("pbs-memcard-imports", result);
Files.writeString(root.resolve("src/conflict.pbs"), "[MemcardBoot] fn conflicting(context: long) -> int { return 0; }");
var conflict = BuilderPipelineService.INSTANCE.analyze(BuilderPipelineContext.fromConfig(
new BuilderPipelineConfig(false, root.toString())), LogAggregator.empty());
assertTrue(conflict.diagnostics().stream().anyMatch(d -> d.isError()
&& d.getMessage().contains("MemcardBoot")), conflict.diagnostics().toString());
}
@Test void rejectsPartialCartridgeConfigurationsAndInvalidManifestNumbers() throws Exception {
String hook = "[MemcardBoot] fn boot(context: long) -> int { return 0; } [Frame] fn frame() -> void {}";
for (var config : List.of("", ",\"memcard_slots\":0", ",\"memcard_slots\":65", ",\"memcard_slots\":\"1\"", ",\"memcard_slots\":1.5", ",\"app_id\":4294967296", ",\"app_id\":true")) {
project(hook, config);
assertThrows(RuntimeException.class, () -> compile(root), config);
}
project("[Frame] fn frame() -> void {}", ",\"memcard_slots\":1");
assertThrows(RuntimeException.class, () -> compile(root));
for (int slots : List.of(1,64)) {
var success = compile(project(hook, ",\"app_id\":4294967295,\"memcard_slots\":" + slots));
assertFalse(success.diagnostics().stream().anyMatch(d -> d.isError()), success.diagnostics().toString());
}
}
}