feat(host): expose memcard controls and qualify process persistence
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-10-30 10:10:07 +00:00
parent dcf6561ea7
commit a4bec5bc45
42 changed files with 4778 additions and 100 deletions
+22
View File
@@ -2,6 +2,28 @@
use clap::Args;
use prometeu_host_headless::automation::Limits;
#[derive(Args, Debug)]
pub struct DesktopMediaArgs {
/// Explicit memory-card image used by the desktop host.
#[arg(long, value_name = "PATH")]
pub memcard: Option<String>,
/// Create a new image; never replace an existing destination.
#[arg(long, requires = "memcard")]
pub create_memcard: bool,
}
impl DesktopMediaArgs {
pub fn forwarded_args(&self) -> Vec<String> {
let mut args = Vec::new();
if let Some(path) = &self.memcard {
args.extend(["--memcard".into(), path.clone()]);
}
if self.create_memcard {
args.push("--create-memcard".into());
}
args
}
}
#[derive(Args, Debug)]
pub struct HeadlessArgs {
/// Use the versioned JSONL stdin/stdout protocol (required).
+14 -8
View File
@@ -25,6 +25,8 @@ enum Commands {
Run {
/// Path to the cartridge (directory or .pmc file).
cart: String,
#[command(flatten)]
media: prometeu_cli::DesktopMediaArgs,
},
/// Executes a cartridge in Assisted Mode (Debug).
/// The runtime will wait for a DevTools connection before starting.
@@ -34,6 +36,8 @@ enum Commands {
/// TCP port for the DevTools server (default: 7777).
#[arg(long, default_value_t = 7777)]
port: u16,
#[command(flatten)]
media: prometeu_cli::DesktopMediaArgs,
},
}
@@ -72,15 +76,17 @@ fn main() {
let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
dispatch(&exe_dir, "prometeu-headless", &borrowed);
}
Some(Commands::Run { cart }) => {
dispatch(&exe_dir, "prometeu-runtime", &["--run", &cart]);
Some(Commands::Run { cart, media }) => {
let mut args = vec!["--run".into(), cart];
args.extend(media.forwarded_args());
let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
dispatch(&exe_dir, "prometeu-runtime", &borrowed);
}
Some(Commands::Debug { cart, port }) => {
dispatch(
&exe_dir,
"prometeu-runtime",
&["--debug", &cart, "--port", &port.to_string()],
);
Some(Commands::Debug { cart, port, media }) => {
let mut args = vec!["--debug".into(), cart, "--port".into(), port.to_string()];
args.extend(media.forwarded_args());
let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
dispatch(&exe_dir, "prometeu-runtime", &borrowed);
}
None => {
use clap::CommandFactory;
@@ -16,6 +16,8 @@ use std::sync::{
mpsc,
};
use std::time::{Duration, Instant};
#[path = "support/memcard_process.rs"]
mod memcard_process;
struct TempDir(PathBuf);
impl TempDir {
@@ -241,7 +243,7 @@ fn png_bytes(capture: &Value) -> Vec<u8> {
fn handshake_versions_capabilities_and_limits_are_explicit() {
let mut c = Client::new(&["--stdio"]);
assert_eq!(c.hello["runtimeVersion"], env!("CARGO_PKG_VERSION"));
assert_eq!(c.hello["protocolVersion"], json!({"major":1,"minor":0}));
assert_eq!(c.hello["protocolVersion"], json!({"major":1,"minor":1}));
assert_eq!(
c.hello["limits"],
json!({"maxFrames":600,"maxCommandBytes":65536,"maxResponseBytes":33554432,
@@ -267,7 +269,7 @@ fn handshake_versions_capabilities_and_limits_are_explicit() {
"initialize",
json!({"protocolVersion":{"major":1,"minor":42},"requiredCapabilities":[]})
)["protocolVersion"]["minor"],
0
1
);
assert_eq!(
c.call(
@@ -0,0 +1,355 @@
use super::*;
use prometeu_test_support::memcard_fixture::{MemcardFixture, memcard_program};
fn card(kind: MemcardFixture, version: &str) -> TempDir {
let dir = TempDir::new();
fs::write(dir.0.join("program.pbx"), memcard_program(kind)).unwrap();
fs::write(
dir.0.join("manifest.json"),
serde_json::to_vec(&json!({
"magic":"PMTU","cartridge_version":1,"app_id":4294967295u32,
"title":"Neutral persistence","app_version":version,"app_mode":"Game",
"capabilities":["memcard"],"memcard_slots":1
}))
.unwrap(),
)
.unwrap();
dir
}
fn start_at(binary: &Path) -> Client {
let mut c = Client::spawn(binary, &["headless", "--stdio"], Some(&std::env::temp_dir()));
c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":1},"requiredCapabilities":["memcard"]}),
);
c
}
fn start() -> Client {
start_at(Path::new(env!("CARGO_BIN_EXE_prometeu")))
}
fn mount(c: &mut Client, path: &Path, action: &str, access: &str) -> Value {
c.ok("memcard_mount", json!({"path":path,"action":action,"access":access}))
}
fn launch(c: &mut Client, dir: &TempDir, choice: &str) {
c.ok("boot", json!({"path":dir.0,"memcardChoice":choice}));
}
fn oracle(c: &mut Client, expected: i64) {
let deadline = Instant::now() + Duration::from_secs(5);
loop {
let advance = c.ok("advance", json!({"frames":1}));
assert_eq!(
advance["stop"],
"completed",
"{advance}; state={}; mem={}; fault={}",
c.ok("get_state", json!({})),
c.ok("get_memcard_state", json!({})),
c.ok("get_fault", json!({}))
);
let state = c.ok("get_state", json!({}));
let top = state["stackTop"].as_array().unwrap();
if top.last().and_then(|v| v["value"].as_str()) == Some(&expected.to_string()) {
return;
}
assert!(Instant::now() < deadline, "oracle {expected} not reached: {state}");
}
}
fn reason(c: &mut Client, command: &str, params: Value, expected: &str) -> Value {
let error = c.call(command, params)["error"].clone();
assert_eq!(error["code"], "memcard_error", "{error}");
assert_eq!(error["details"]["reason"], expected, "{error}");
error["details"]["state"].clone()
}
fn persistence(binary: &Path) {
let root = TempDir::new();
let image = root.0.join("save.pmc");
let write = card(MemcardFixture::Write, "1");
let mut first = start_at(binary);
let mounted = mount(&mut first, &image, "create", "read_write");
assert_eq!(mounted["media"]["cardId"].as_str().unwrap().len(), 32);
launch(&mut first, &write, "persistent");
oracle(&mut first, 101);
let saved = first.ok("get_memcard_state", json!({}));
assert_eq!(saved["request"]["state"], "success");
assert_eq!(saved["request"]["retained"], true);
assert_eq!(saved["dirty"], false);
assert_eq!(saved["io"]["active"], false);
first.close();
let bytes = fs::read(&image).unwrap();
for version in ["1", "2"] {
let read = card(MemcardFixture::Read, version);
let mut next = start_at(binary);
mount(&mut next, &image, "open", "read_write");
launch(&mut next, &read, "persistent");
oracle(&mut next, 201);
assert_eq!(next.ok("get_state", json!({}))["appId"], 4294967295u32);
assert_eq!(
next.ok("get_memcard_state", json!({}))["request"],
Value::Null,
"reader must not submit a save"
);
next.close();
assert!(fs::read(&image).unwrap() == bytes, "readback must not rewrite the image");
}
let read = card(MemcardFixture::Read, "2");
let mut memory = start_at(binary);
mount(&mut memory, &image, "open", "read_only");
reason(&mut memory, "boot", json!({"path":read.0,"memcardChoice":"persistent"}), "read_only");
memory.ok("reset", json!({}));
launch(&mut memory, &read, "memory_existing");
oracle(&mut memory, 201);
assert_eq!(memory.ok("get_memcard_state", json!({}))["session"]["mode"], "memory_only");
memory.close();
assert!(fs::read(&image).unwrap() == bytes);
}
#[test]
fn memcard_public_distinct_process_save_readback_and_version_identity() {
persistence(Path::new(env!("CARGO_BIN_EXE_prometeu")));
}
#[test]
#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive"]
fn packaged_memcard_process_persistence() {
let installation = PathBuf::from(
std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL").expect("extracted distribution"),
);
persistence(&installation.join("prometeu"));
}
#[test]
fn memcard_dirty_refusal_retains_channel_and_explicit_ram_has_no_save() {
let dirty = card(MemcardFixture::Dirty, "1");
let mut c = start();
launch(&mut c, &dirty, "memory_fresh");
oracle(&mut c, 301);
for command in ["shutdown", "reset"] {
let state = reason(&mut c, command, json!({}), "unsaved_changes");
assert_eq!(state["dirty"], true);
assert_eq!(state["session"]["resident"], true);
assert_eq!(c.ok("get_state", json!({}))["appId"], 4294967295u32);
}
let reset = c.ok("reset", json!({"discardUnsaved":true,"pendingWrites":"cancel"}));
assert_eq!(reset["memcard"]["dirty"], false);
let write = card(MemcardFixture::Write, "1");
launch(&mut c, &write, "memory_fresh");
oracle(&mut c, 104);
let state = c.ok("get_memcard_state", json!({}));
assert_eq!(state["request"]["state"], "memory_only");
assert_eq!(state["dirty"], true);
assert_eq!(state["io"]["active"], false);
assert_eq!(state["media"]["path"], Value::Null);
c.ok("shutdown", json!({"discardUnsaved":true}));
c.wait_exit();
}
#[test]
fn memcard_media_errors_and_negotiation_never_select_a_fallback() {
let root = TempDir::new();
let missing = root.0.join("missing.pmc");
let mut old = Client::new(&["--stdio"]);
old.initialize();
assert_eq!(
old.call("memcard_mount", json!({"path":missing,"action":"create","access":"read_write"}))
["error"]["code"],
"unsupported_capability"
);
assert!(!missing.exists());
old.close();
let mut c = Client::new(&["--stdio"]);
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":1,"minor":0},"requiredCapabilities":["memcard"]})
)["error"]["code"],
"incompatible_version"
);
c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":1},"requiredCapabilities":["memcard"]}),
);
reason(
&mut c,
"memcard_mount",
json!({"path":missing,"action":"open","access":"read_write"}),
"unavailable",
);
assert!(!missing.exists());
let cart = card(MemcardFixture::Write, "1");
reason(&mut c, "boot", json!({"path":cart.0}), "choice_required");
assert_eq!(c.ok("get_state", json!({}))["logicalFrameIndex"], 0);
c.ok("reset", json!({}));
let corrupt = root.0.join("corrupt.pmc");
let mut bytes = vec![0; 5_259_264];
bytes[..8].copy_from_slice(b"PMCARD1\0");
bytes[8] = 1;
fs::write(&corrupt, &bytes).unwrap();
reason(
&mut c,
"memcard_mount",
json!({"path":corrupt,"action":"open","access":"read_write"}),
"corrupt",
);
assert!(fs::read(&corrupt).unwrap() == bytes);
assert_eq!(c.ok("get_memcard_state", json!({}))["session"]["mode"], Value::Null);
c.close();
}
#[cfg(unix)]
#[test]
fn memcard_process_ownership_covers_aliases_readers_and_release() {
let root = TempDir::new();
let image = root.0.join("save.pmc");
let hard = root.0.join("hard.pmc");
let sym = root.0.join("sym.pmc");
let mut owner = start();
mount(&mut owner, &image, "create", "read_write");
fs::hard_link(&image, &hard).unwrap();
std::os::unix::fs::symlink(&image, &sym).unwrap();
let bytes = fs::read(&image).unwrap();
let mut contender = start();
for path in [&image, &hard, &sym] {
for access in ["read_only", "read_write"] {
reason(
&mut contender,
"memcard_mount",
json!({"path":path,"action":"open","access":access}),
"busy",
);
}
}
reason(
&mut contender,
"memcard_mount",
json!({"path":image,"action":"create","access":"read_write"}),
"already_exists",
);
assert!(fs::read(&image).unwrap() == bytes);
owner.ok("memcard_unmount", json!({}));
mount(&mut contender, &image, "open", "read_only");
reason(
&mut owner,
"memcard_mount",
json!({"path":image,"action":"open","access":"read_only"}),
"busy",
);
contender.close();
mount(&mut owner, &image, "open", "read_write");
owner.close();
}
#[cfg(unix)]
#[test]
fn memcard_creation_race_and_process_death_release_real_ownership() {
let root = TempDir::new();
let image = root.0.join("race.pmc");
// Kill the actual storage-owning process rather than its dispatcher parent.
let mut a = Client::new(&["--stdio"]);
let mut b = Client::new(&["--stdio"]);
for c in [&mut a, &mut b] {
c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":1},"requiredCapabilities":["memcard"]}),
);
}
let params = json!({"path":image,"action":"create","access":"read_write"});
let aid = a.send("memcard_mount", params.clone());
let bid = b.send("memcard_mount", params);
let ar = a.response(&aid);
let br = b.response(&bid);
assert_ne!(
ar.get("result").is_some(),
br.get("result").is_some(),
"exactly one creator must win"
);
let (winner, loser, error) =
if ar.get("result").is_some() { (&mut a, &mut b, br) } else { (&mut b, &mut a, ar) };
assert_eq!(error["error"]["details"]["reason"], "already_exists");
let before = fs::read(&image).unwrap();
winner.child.kill().unwrap();
winner.child.wait().unwrap();
mount(loser, &image, "open", "read_write");
loser.close();
assert!(fs::read(&image).unwrap() == before);
}
#[cfg(unix)]
#[test]
fn memcard_access_denial_is_typed_and_does_not_create_or_modify_media() {
use std::os::unix::fs::PermissionsExt;
let root = TempDir::new();
let image = root.0.join("denied.pmc");
let mut creator = start();
mount(&mut creator, &image, "create", "read_write");
creator.close();
let before = fs::read(&image).unwrap();
fs::set_permissions(&image, fs::Permissions::from_mode(0o0)).unwrap();
let mut c = start();
reason(
&mut c,
"memcard_mount",
json!({"path":image,"action":"open","access":"read_write"}),
"access_denied",
);
c.close();
fs::set_permissions(&image, fs::Permissions::from_mode(0o600)).unwrap();
assert!(fs::read(&image).unwrap() == before);
}
#[cfg(unix)]
#[test]
fn desktop_dispatch_forwards_explicit_media_without_interpreting_player_policy() {
use std::os::unix::fs::PermissionsExt;
let installation = TempDir::new();
let dispatcher = installation.0.join("prometeu");
fs::copy(env!("CARGO_BIN_EXE_prometeu"), &dispatcher).unwrap();
let runtime = installation.0.join("prometeu-runtime");
fs::write(&runtime, "#!/bin/sh\nprintf '%s\\n' \"$@\"\n").unwrap();
fs::set_permissions(&runtime, fs::Permissions::from_mode(0o755)).unwrap();
for command in ["run", "debug"] {
let output = Command::new(&dispatcher)
.args([command, "cartridge", "--memcard", "image with spaces.pmc", "--create-memcard"])
.output()
.unwrap();
assert!(output.status.success());
let actual = String::from_utf8(output.stdout).unwrap();
let mut expected = vec![format!("--{command}"), "cartridge".into()];
if command == "debug" {
expected.extend(["--port".into(), "7777".into()]);
}
expected.extend([
"--memcard".into(),
"image with spaces.pmc".into(),
"--create-memcard".into(),
]);
assert_eq!(actual.lines().collect::<Vec<_>>(), expected);
}
assert!(
!Command::new(&dispatcher)
.args(["run", "cartridge", "--create-memcard"])
.output()
.unwrap()
.status
.success()
);
}
#[test]
fn memcard_idle_observation_never_advances_guest_counters() {
let root = TempDir::new();
let image = root.0.join("save.pmc");
let cart = card(MemcardFixture::Write, "1");
let mut c = start();
mount(&mut c, &image, "create", "read_write");
launch(&mut c, &cart, "persistent");
c.ok("advance", json!({"frames":1}));
let before = c.ok("get_state", json!({}));
let deadline = Instant::now() + Duration::from_secs(3);
loop {
let state = c.ok("get_memcard_state", json!({}));
if !state["io"]["active"].as_bool().unwrap() {
assert_eq!(state["request"]["state"], "success");
break;
}
assert!(Instant::now() < deadline);
}
let after = c.ok("get_state", json!({}));
for field in ["pc", "logicalFrameIndex", "tickIndex", "stackTop"] {
assert_eq!(before[field], after[field], "{field}");
}
c.close();
}