feat(runtime): support Studio Play and separate integration gates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

Add the windowless Studio host with authenticated binary control/frame channels,
managed input, pause/resume/stop, frame ownership and save-aware shutdown.
Preserve deterministic headless execution and add protocol/process fixtures.
Separate unit CI and coverage from opt-in integration/socket qualification,
retaining the prior combined coverage floors in the configuration history.

Validation: tooling make verify passed runtime ci-domains and integration.
This commit is contained in:
2026-11-19 17:32:02 +00:00
parent 2d5735cb13
commit f1adf86dd5
19 changed files with 1484 additions and 38 deletions
+13 -6
View File
@@ -1,4 +1,4 @@
.PHONY: fmt fmt-check clippy test-local test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-audit coverage-domain-gate test ci ci-domains cobertura
.PHONY: fmt fmt-check clippy test-unit test-local test-integration test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-audit coverage-domain-gate test ci ci-domains cobertura
fmt:
cargo fmt --all
@@ -9,8 +9,15 @@ fmt-check:
clippy:
cargo clippy --workspace --all-targets --all-features -- -D warnings
test-local:
cargo test --workspace --all-targets --all-features --no-fail-fast
test-unit:
cargo test --workspace --lib --bins --all-features --no-fail-fast
# Compatibility entry point: repository-local verification is unit-only.
test-local: test-unit
# Explicit opt-in, orchestrated by ../tooling; test sources stay in this repository.
test-integration:
cargo test --workspace --tests --all-features --no-fail-fast
test-debugger-socket:
cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored
@@ -19,7 +26,7 @@ clean:
cargo llvm-cov clean --workspace
coverage:
cargo llvm-cov --workspace --all-features --html --output-dir target/llvm-cov
cargo llvm-cov --workspace --lib --bins --all-features --html --output-dir target/llvm-cov
coverage-report-json:
cargo llvm-cov report --json --output-path target/llvm-cov/report.json
@@ -46,9 +53,9 @@ coverage-domain-evidence:
coverage-domain-gate:
./scripts/coverage-domain-evidence.sh --check-all
test: fmt-check clippy test-local test-debugger-socket
test: fmt-check clippy test-unit
# Local and GitHub entry point; Jenkins exposes the same targets as stages.
CI_DOMAIN_STEPS = clean fmt-check clippy test-local test-debugger-socket coverage coverage-report-json coverage-xml coverage-json coverage-domain-audit coverage-domain-gate
CI_DOMAIN_STEPS = clean fmt-check clippy test-unit coverage coverage-report-json coverage-xml coverage-json coverage-domain-audit coverage-domain-gate
ci: ci-domains
ci-domains:
+9 -2
View File
@@ -133,7 +133,14 @@ The authoritative target used by both GitHub and Jenkins is:
make ci-domains
```
The five debugger socket tests bind localhost sockets and are marked ignored in Rust test metadata; both `make test` and `make ci-domains` select only `runner::tests` through `test-debugger-socket`. Physical audio and other manual probes remain opt-in. See [quality-gate prerequisites and commands](docs/vm-arch/COVERAGE_DOMAINS.md#commands-and-ci).
`make test-unit` selects library and binary unit-test harnesses with
`--lib --bins --all-features`; `test-local` remains an alias. Both `make test`
and `make ci-domains` run only this suite. Integration targets under `tests/`,
installed-process qualification and the five ignored debugger socket tests are
excluded from the pipeline. They remain available explicitly through
`make test-integration` and `make test-debugger-socket`, orchestrated by
`../tooling`. Tests and fixtures stay in this repository. Physical audio and manual probes remain opt-in. See
[quality-gate prerequisites and commands](docs/vm-arch/COVERAGE_DOMAINS.md#commands-and-ci).
## Coverage Governance
@@ -170,7 +177,7 @@ make coverage-domain-evidence DOMAIN=host/headless
```
`make ci-domains` runs formatting, strict workspace/all-target/all-feature Clippy,
all-target tests, the five debugger socket tests, fresh coverage and every domain
library/binary unit tests, fresh unit-only coverage and every domain
ownership/evidence gate. Both CI providers archive available evidence on failure.
A failing run never lowers a configured floor; local and CI checks use the same
repository-owned commands. Reports identify their revision, source/configuration
@@ -40,6 +40,19 @@ impl LatestRenderFrameStore {
pub fn latest_frame(&self) -> Option<OwnedRgba8888Frame> {
self.latest.lock().unwrap().clone()
}
/// Copy only a different complete publication; paused observers need not copy pixels.
pub fn latest_frame_after(
&self,
previous: Option<(RenderOwnership, FrameId)>,
) -> Option<OwnedRgba8888Frame> {
self.latest
.lock()
.unwrap()
.as_ref()
.filter(|frame| previous != Some((frame.ownership, frame.frame_id)))
.cloned()
}
}
impl RenderWorkerFrameSink for LatestRenderFrameStore {
@@ -6,6 +6,7 @@ pub mod input;
pub mod log_sink;
pub mod runner;
pub mod stats;
pub mod studio;
pub mod utilities;
pub mod wall_clock;
@@ -18,6 +19,9 @@ use winit::event_loop::EventLoop;
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
struct Cli {
/// Run an interactive Studio session without creating a desktop window.
#[arg(long, requires = "run", conflicts_with = "debug")]
studio: bool,
/// Run a cartridge
#[arg(long, value_name = "PATH", conflicts_with = "debug")]
run: Option<String>,
@@ -54,6 +58,23 @@ struct Cli {
pub fn run() -> Result<(), Box<dyn std::error::Error>> {
let cli = Cli::parse();
if cli.studio {
let bootstrap = studio::wire::Bootstrap::read(std::io::stdin().lock())?;
let mut runner =
HostRunner::new(cli.fs_root, cli.cap.as_ref().and_then(|path| load_cap_config(path)));
if let Some(path) = cli.memcard {
runner
.install_memcard(path, cli.create_memcard)
.map_err(|e| format!("Cannot install memory card: {e:?}"))?;
}
runner.set_boot_target(BootTarget::Cartridge {
path: cli.run.expect("--studio requires --run"),
debug: false,
debug_port: 0,
});
return studio::run(runner, bootstrap).map_err(Into::into);
}
let fs_root = cli.fs_root;
let cap_config = cli.cap.as_ref().and_then(|path| load_cap_config(path));
@@ -151,6 +151,7 @@ pub struct HostRunner {
render_frame_store: LatestRenderFrameStore,
/// Tracks whether a new logical frame or host-only surface invalidation requires presentation.
presentation: PresentationState,
studio_capture: bool,
}
impl HostRunner {
@@ -238,9 +239,161 @@ impl HostRunner {
audio: HostAudio::new(),
render_frame_store,
presentation: PresentationState::default(),
studio_capture: false,
}
}
/// One canonical interactive slice, shared by desktop and Studio pacing.
fn tick_machine(&mut self) {
self.audio.service();
if !self.debugger.waiting_for_start {
if self.studio_capture {
let mut platform = crate::studio::platform::StudioPlatform {
hardware: &mut self.hardware,
store: &self.render_frame_store,
};
self.firmware.tick(&self.input.signals, &mut platform);
} else {
self.firmware.tick(&self.input.signals, &mut self.hardware);
}
self.stats.record_host_cpu_time(self.firmware.os.vm().last_frame_cpu_time_us());
}
self.hardware.audio.set_paused(
self.firmware.game_lifecycle_audio_paused()
|| self.firmware.os.vm().paused()
|| self.debugger.waiting_for_start,
);
self.audio.service();
}
pub(crate) fn studio_audio_init(&mut self) {
if let Err(error) = self.audio.init(self.hardware.audio.transport()) {
eprintln!("[HostAudio] Disabled: {error}");
}
}
pub(crate) fn studio_boot_step(&mut self, disposable: bool) -> Result<bool, String> {
self.studio_capture = true;
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(true);
}
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
return Err("Cartridge failed during Studio boot".into());
}
self.firmware.os.memcard().poll(Instant::now());
if let FirmwareState::LoadCartridge(step) = &mut self.firmware.state
&& step.needs_memcard_choice()
&& !self.firmware.os.memcard().preparation_active()
{
let choice = if disposable {
prometeu_system::memcard::admission::Choice::MemoryFresh
} else {
prometeu_system::memcard::admission::Choice::Persistent
};
step.choose_memcard(
&mut self.firmware.os,
choice,
self.hardware.wall_clock().utc_unix_seconds(),
)
.map_err(|e| format!("Studio save selection failed: {e:?}"))?;
}
self.tick_machine();
self.studio_logs();
Ok(matches!(self.firmware.state, FirmwareState::GameRunning(_)))
}
pub(crate) fn studio_step(
&mut self,
signals: prometeu_hal::InputSignals,
) -> Result<(), String> {
self.input.signals = signals;
self.tick_machine();
self.studio_logs();
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
return Err("Cartridge faulted during Studio Play".into());
}
Ok(())
}
pub(crate) fn studio_pause(&mut self, paused: bool) {
self.input.clear_guest_signals();
self.firmware.os.vm().set_paused(paused);
self.hardware.audio.set_paused(paused);
self.audio.service();
}
pub(crate) fn studio_dimensions(&self) -> (usize, usize) {
self.hardware.display_size()
}
pub(crate) fn studio_tick_index(&mut self) -> u64 {
self.firmware.os.frame_index()
}
pub(crate) fn studio_frame(
&mut self,
previous: Option<(RenderOwnership, prometeu_hal::FrameId)>,
) -> Option<OwnedRgba8888Frame> {
let active = self.firmware.os.vm().active_render_ownership();
self.render_frame_store
.latest_frame_after(previous)
.filter(|frame| should_present_worker_frame(&self.firmware.state, frame, active))
}
fn studio_logs(&mut self) {
let last = self.log_sink.last_seq();
let events = match last {
Some(seq) => self.firmware.os.logs_after(seq),
None => self.firmware.os.recent_logs(4096),
};
self.log_sink.process_events(events);
}
pub(crate) fn studio_stop(&mut self, disposable: bool) -> Result<(), String> {
self.studio_pause(true);
let deadline = Instant::now() + Duration::from_secs(2);
loop {
let service = self.firmware.os.memcard();
service.poll(Instant::now());
if !service.session.io_active()
&& !service.session.has_deferred_write()
&& !service.preparation_active()
{
break;
}
if Instant::now() >= deadline {
return Err("Save IO has not finished; retry Stop".into());
}
let lane = service.lane.clone();
lane.wait_for_progress(lane.progress_stamp(), Duration::from_millis(5));
}
if self.firmware.os.memcard().session.unsaved() && !disposable {
return Err("Unsaved game data; resume and save before stopping".into());
}
self.firmware
.os
.stop_background_io()
.map_err(|e| format!("Save shutdown failed: {e:?}"))?;
self.firmware.os.memcard().session.end_session();
self.firmware.os.memcard().poll(Instant::now());
self.firmware
.os
.memcard()
.uninstall_card()
.map_err(|e| format!("Save detach failed: {e:?}"))?;
self.firmware
.os
.vm()
.stop_render_worker()
.map_err(|e| format!("Render shutdown failed: {e:?}"))?;
Ok(())
}
pub(crate) fn studio_abort(&mut self) {
self.studio_pause(true);
let _ = self.firmware.os.vm().stop_render_worker();
let _ = self.firmware.os.stop_background_io();
}
fn window(&self) -> &'static Window {
self.window.expect("window not created yet")
}
@@ -435,18 +588,7 @@ impl ApplicationHandler for HostRunner {
while self.accumulator >= self.frame_target_dt {
// Reclaim returned audio owners before another guest attempt, even
// when the previous attempt paused or stopped at backpressure.
self.audio.service();
// Unless the debugger is waiting for a 'start' command, advance the system.
if !self.debugger.waiting_for_start {
self.firmware.tick(&self.input.signals, &mut self.hardware);
self.stats.record_host_cpu_time(self.firmware.os.vm().last_frame_cpu_time_us());
}
let is_paused = self.firmware.game_lifecycle_audio_paused()
|| self.firmware.os.vm().paused()
|| self.debugger.waiting_for_start;
self.hardware.audio.set_paused(is_paused);
self.audio.service();
self.tick_machine();
self.accumulator -= self.frame_target_dt;
self.stats.record_frame();
@@ -500,6 +642,73 @@ impl ApplicationHandler for HostRunner {
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn studio_can_boot_and_publish_without_a_window() {
let cart = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../test-cartridges/dummy-boy");
let mut host = HostRunner::new(None, None);
host.set_boot_target(BootTarget::Cartridge {
path: cart.to_string_lossy().into_owned(),
debug: false,
debug_port: 0,
});
let deadline = Instant::now() + Duration::from_secs(5);
while !host.studio_boot_step(true).unwrap() {
assert!(Instant::now() < deadline);
std::thread::sleep(Duration::from_millis(1));
}
host.studio_pause(true);
host.studio_pause(false);
for _ in 0..60 {
host.studio_step(Default::default()).unwrap();
std::thread::sleep(Duration::from_millis(2));
}
let frame = host.studio_frame(None);
let published = host.render_frame_store.latest_frame().map(|f| (f.frame_id, f.ownership));
let active = host.firmware.os.vm().active_render_ownership();
assert!(
frame.is_some(),
"store {published:?}, owner {active:?}, state {:?}, frame {}",
host.firmware.state,
host.firmware.os.frame_index()
);
let frame = frame.unwrap();
assert!(host.studio_frame(Some((frame.ownership, frame.frame_id))).is_none());
// Exercise the same audio transport/callback through Studio lifecycle,
// without requiring a physical output device in this contract test.
use prometeu_hal::{AudioBridge, LoopMode, sample::Sample};
let (mut callback, mut reclaimer) = crate::audio::AudioCallback::new();
assert_eq!(
host.hardware.audio.play_sample(
Arc::new(Sample::new(48000, vec![1000; 32])),
0,
255,
0,
1.0,
0,
LoopMode::On,
),
prometeu_hal::AudioOpStatus::Ok
);
host.hardware.audio.finish_frame();
let transport = host.hardware.audio.transport();
let mut pcm = [0.0; 64];
callback.render(&transport, &mut pcm);
assert!(pcm.iter().any(|sample| *sample != 0.0));
reclaimer.service(&transport);
host.studio_pause(true);
callback.render(&transport, &mut pcm);
assert!(pcm.iter().all(|sample| *sample == 0.0));
reclaimer.service(&transport);
host.studio_pause(false);
callback.render(&transport, &mut pcm);
assert!(pcm.iter().any(|sample| *sample != 0.0));
reclaimer.service(&transport);
host.studio_stop(true).unwrap();
callback.render(&transport, &mut pcm);
assert!(pcm.iter().all(|sample| *sample == 0.0));
}
use prometeu_firmware::BootTarget;
use prometeu_firmware::firmware::firmware_state::{
GameRunningStep, HubHomeStep, ShellRunningStep,
@@ -0,0 +1,255 @@
//! Interactive Play integration, separate from the automation host.
pub(crate) mod platform;
mod transport;
pub mod wire;
use crate::runner::HostRunner;
use prometeu_hal::InputSignals;
use std::{
io,
time::{Duration, Instant},
};
use transport::Transport;
use wire::*;
fn number64(p: &[u8]) -> u64 {
u64::from_le_bytes(p.try_into().unwrap())
}
fn result(
transport: &Transport,
command: u16,
request: u64,
status: u16,
epoch: u64,
tick: u64,
text: &str,
) -> io::Result<()> {
let mut p = Vec::with_capacity(20 + text.len());
p.extend_from_slice(&command.to_le_bytes());
p.extend_from_slice(&status.to_le_bytes());
p.extend_from_slice(&epoch.to_le_bytes());
p.extend_from_slice(&tick.to_le_bytes());
p.extend_from_slice(text.as_bytes());
transport.send(RESULT, request, p)
}
fn input(p: &[u8], width: usize, height: usize) -> io::Result<(u64, InputSignals)> {
if p.len() != 20 {
return Err(invalid("Invalid Studio input length"));
}
let mask = u16::from_le_bytes(p[8..10].try_into().unwrap());
if mask & !0x1fff != 0 || p[10..12] != [0, 0] {
return Err(invalid("Invalid Studio input bits"));
}
let x = i32::from_le_bytes(p[12..16].try_into().unwrap());
let y = i32::from_le_bytes(p[16..20].try_into().unwrap());
if mask & 0x1000 != 0 && (x < 0 || y < 0 || x as usize >= width || y as usize >= height) {
return Err(invalid("Studio touch outside display"));
}
let bit = |n: u16| mask & (1u16 << n) != 0;
Ok((
number64(&p[..8]),
InputSignals {
up_signal: bit(0),
down_signal: bit(1),
left_signal: bit(2),
right_signal: bit(3),
a_signal: bit(4),
b_signal: bit(5),
x_signal: bit(6),
y_signal: bit(7),
l_signal: bit(8),
r_signal: bit(9),
start_signal: bit(10),
select_signal: bit(11),
f_signal: bit(12),
x_pos: x,
y_pos: y,
},
))
}
pub(crate) fn run(mut runner: HostRunner, boot: Bootstrap) -> io::Result<()> {
let transport = Transport::connect(&boot)?;
runner.studio_audio_init();
let (width, height) = runner.studio_dimensions();
frame_bytes(width as u32, height as u32, width as u32)?;
let mut ready = false;
let mut started = false;
let mut state = 0u32;
let mut epoch = 1u64;
let mut signals = InputSignals::default();
let mut next_tick = Instant::now();
let boot_deadline = Instant::now() + Duration::from_secs(10);
let slice = Duration::from_nanos(1_000_000_000 / 60);
let mut last_request = 0;
let mut last_frame = None;
let outcome = (|| -> io::Result<()> {
loop {
if let Some(error) = transport.failure() {
return Err(invalid(&error));
}
if ready && transport.idle() > Duration::from_secs(5) {
return Err(invalid("Studio control heartbeat expired"));
}
for _ in 0..64 {
let Some(message) = transport.next() else {
break;
};
let h = message.header;
if h.kind == INPUT {
let (received, input) = input(&message.payload, width, height)?;
if received == epoch && state == 1 {
signals = input;
}
continue;
}
if h.kind == PING {
if !message.payload.is_empty() {
return Err(invalid("Invalid PING payload"));
}
let mut p = Vec::with_capacity(20);
p.extend_from_slice(&epoch.to_le_bytes());
p.extend_from_slice(&runner.studio_tick_index().to_le_bytes());
p.extend_from_slice(&state.to_le_bytes());
transport.send(PONG, h.request, p)?;
continue;
}
if !matches!(h.kind, START | PAUSE | RESUME | STOP)
|| !message.payload.is_empty()
|| h.request == 0
{
return Err(invalid("Invalid Studio control command"));
}
if h.request <= last_request {
result(
&transport,
h.kind,
h.request,
1,
epoch,
runner.studio_tick_index(),
"Stale or duplicate request",
)?;
continue;
}
last_request = h.request;
if h.kind == STOP {
signals = InputSignals::default();
state = 2;
epoch = epoch.checked_add(1).ok_or_else(|| invalid("epoch exhausted"))?;
match runner.studio_stop(boot.disposable) {
Ok(()) => {
result(
&transport,
STOP,
h.request,
0,
epoch,
runner.studio_tick_index(),
"",
)?;
transport.finish(h.request)?;
return Ok(());
}
Err(error) => {
result(
&transport,
STOP,
h.request,
2,
epoch,
runner.studio_tick_index(),
&error,
)?;
continue;
}
}
}
if !ready {
result(
&transport,
h.kind,
h.request,
1,
epoch,
runner.studio_tick_index(),
"Cartridge is not ready",
)?;
continue;
}
match h.kind {
START if state == 0 => {
started = true;
state = 1;
runner.studio_pause(false);
next_tick = Instant::now();
}
START if state == 2 && !started => {
started = true;
}
PAUSE if state == 1 || state == 0 => {
state = 2;
epoch += 1;
signals = InputSignals::default();
runner.studio_pause(true);
}
RESUME if state == 2 && started => {
state = 1;
epoch += 1;
signals = InputSignals::default();
runner.studio_pause(false);
next_tick = Instant::now();
}
PAUSE if state == 2 => {}
RESUME if state == 1 => {}
_ => {
result(
&transport,
h.kind,
h.request,
1,
epoch,
runner.studio_tick_index(),
"Invalid execution state",
)?;
continue;
}
}
result(&transport, h.kind, h.request, 0, epoch, runner.studio_tick_index(), "")?;
}
if !ready {
if Instant::now() > boot_deadline {
return Err(invalid("Studio cartridge boot timed out"));
}
ready = runner.studio_boot_step(boot.disposable).map_err(|e| invalid(&e))?;
if ready {
runner.studio_pause(true);
let mut p = Vec::new();
for n in [width as u32, height as u32, 60, RGBA8] {
p.extend_from_slice(&n.to_le_bytes());
}
p.extend_from_slice(env!("CARGO_PKG_VERSION").as_bytes());
transport.send(READY, 0, p)?;
}
} else if state == 1 && Instant::now() >= next_tick {
runner.studio_step(signals).map_err(|e| invalid(&e))?;
next_tick += slice;
if next_tick + Duration::from_millis(100) < Instant::now() {
next_tick = Instant::now();
}
}
// Completion is asynchronous and can arrive after Pause stopped logical ticks.
if ready && let Some(frame) = runner.studio_frame(last_frame) {
last_frame = Some((frame.ownership, frame.frame_id));
transport.publish(epoch, frame);
}
std::thread::sleep(Duration::from_millis(1));
}
})();
if let Err(error) = &outcome {
eprintln!("[Studio] {error}");
let _ = transport.send(ERROR, 0, error.to_string().into_bytes());
runner.studio_abort();
}
outcome
}
@@ -0,0 +1,69 @@
//! Observe complete synchronous submissions without changing machine/render semantics.
use prometeu_drivers::hardware::Hardware;
use prometeu_hal::*;
use prometeu_system::LatestRenderFrameStore;
pub(crate) struct StudioPlatform<'a> {
pub hardware: &'a mut Hardware,
pub store: &'a LatestRenderFrameStore,
}
impl RenderSubmissionSink for StudioPlatform<'_> {
fn submit_render_submission(
&mut self,
submission: RenderSubmission,
) -> Result<(), RenderSubmitError> {
let marker = (submission.frame_id, submission.ownership);
self.hardware.submit_render_submission(submission)?;
if marker.1.app_mode == app_mode::AppMode::Game {
let (w, h) = self.hardware.display_size();
let frame = OwnedRgba8888Frame::packed(
marker.0,
marker.1,
w,
h,
self.hardware.gfx.front_buffer().to_vec(),
)
.map_err(|_| RenderSubmitError::SubmissionRejected)?;
self.store.publish_frame(frame);
}
Ok(())
}
}
impl RuntimePlatform for StudioPlatform<'_> {
fn wall_clock(&self) -> &dyn WallClock {
self.hardware.wall_clock()
}
fn display_size(&self) -> (usize, usize) {
self.hardware.display_size()
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self
}
fn render_backend(&mut self) -> &mut dyn RenderBackend {
self.hardware
}
fn game2d_frame_composer(&mut self) -> &mut dyn Game2DFrameComposer {
self.hardware
}
fn audio(&self) -> &dyn AudioBridge {
self.hardware.audio()
}
fn audio_mut(&mut self) -> &mut dyn AudioBridge {
self.hardware.audio_mut()
}
fn input(&self) -> &dyn InputPlatform {
self.hardware.input()
}
fn input_mut(&mut self) -> &mut dyn InputPlatform {
self.hardware.input_mut()
}
fn assets(&self) -> &dyn AssetBridge {
self.hardware.assets()
}
fn assets_mut(&mut self) -> &mut dyn AssetBridge {
self.hardware.assets_mut()
}
fn telemetry(&self) -> &dyn TelemetryPlatform {
self.hardware.telemetry()
}
}
@@ -0,0 +1,260 @@
use super::wire::*;
use prometeu_hal::OwnedRgba8888Frame;
use std::io::{self, Read};
use std::net::{Ipv4Addr, Shutdown, SocketAddr, TcpStream};
use std::sync::{
Arc, Condvar, Mutex,
atomic::{AtomicBool, Ordering},
mpsc::{self, Receiver, SyncSender},
};
use std::thread::JoinHandle;
use std::time::{Duration, Instant};
struct Publication {
epoch: u64,
frame: Arc<OwnedRgba8888Frame>,
}
#[derive(Default)]
struct Video {
latest: Option<Publication>,
flight: Option<(u64, u64)>,
}
struct Shared {
video: Mutex<Video>,
wake: Condvar,
closed: AtomicBool,
failure: Mutex<Option<String>>,
activity: Mutex<Instant>,
}
impl Shared {
fn fail(&self, message: impl ToString) {
if self.closed.load(Ordering::Acquire) {
return;
}
let mut failure = self.failure.lock().unwrap();
if failure.is_none() {
*failure = Some(message.to_string());
}
self.wake.notify_all();
}
fn stopped(&self) -> bool {
self.closed.load(Ordering::Acquire) || self.failure.lock().unwrap().is_some()
}
}
struct Outbound {
kind: u16,
request: u64,
payload: Vec<u8>,
flushed: Option<SyncSender<()>>,
}
pub(super) struct Transport {
shared: Arc<Shared>,
outgoing: SyncSender<Outbound>,
incoming: Receiver<Message>,
control: TcpStream,
video: TcpStream,
workers: Vec<JoinHandle<()>>,
}
impl Transport {
pub fn connect(boot: &Bootstrap) -> io::Result<Self> {
fn connect(port: u16) -> io::Result<TcpStream> {
let socket = TcpStream::connect_timeout(
&SocketAddr::from((Ipv4Addr::LOCALHOST, port)),
Duration::from_secs(5),
)?;
socket.set_nodelay(true)?;
socket.set_write_timeout(Some(Duration::from_secs(2)))?;
Ok(socket)
}
let control = connect(boot.control_port)?;
let video = connect(boot.video_port)?;
let mut writer = Writer::new(control.try_clone()?);
writer.send(HELLO, 0, &boot.hello(1))?;
let mut video_writer = Writer::new(video.try_clone()?);
video_writer.send(HELLO, 0, &boot.hello(2))?;
let shared = Arc::new(Shared {
video: Mutex::new(Video::default()),
wake: Condvar::new(),
closed: AtomicBool::new(false),
failure: Mutex::new(None),
activity: Mutex::new(Instant::now()),
});
let (tx, rx) = mpsc::sync_channel::<Outbound>(256);
let (commands, incoming) = mpsc::sync_channel(256);
let mut workers = Vec::new();
let state = shared.clone();
workers.push(std::thread::Builder::new().name("studio-control-write".into()).spawn(
move || {
while !state.stopped() {
let out = match rx.recv_timeout(Duration::from_millis(100)) {
Ok(out) => out,
Err(mpsc::RecvTimeoutError::Timeout) => continue,
Err(_) => break,
};
if let Err(error) = writer.send(out.kind, out.request, &out.payload) {
state.fail(error);
break;
}
if let Some(done) = out.flushed {
let _ = done.send(());
}
}
},
)?);
let state = shared.clone();
let socket = control.try_clone()?;
workers.push(std::thread::Builder::new().name("studio-control-read".into()).spawn(
move || {
let mut reader = Reader::new(socket);
while !state.stopped() {
let message = match reader.receive_control() {
Ok(m) => m,
Err(e) => {
state.fail(format!("Studio control lost: {e}"));
break;
}
};
*state.activity.lock().unwrap() = Instant::now();
if message.header.kind == FRAME_RECEIVED {
if message.payload.len() != 16 || message.header.request != 0 {
state.fail("Invalid frame acknowledgement");
break;
}
let p = &message.payload;
let ack = (
u64::from_le_bytes(p[..8].try_into().unwrap()),
u64::from_le_bytes(p[8..].try_into().unwrap()),
);
let mut frames = state.video.lock().unwrap();
if frames.flight != Some(ack) {
drop(frames);
state.fail("Unexpected frame acknowledgement");
break;
}
frames.flight = None;
state.wake.notify_all();
} else if commands.try_send(message).is_err() {
state.fail("Studio control queue saturated");
break;
}
}
},
)?);
let state = shared.clone();
let session = boot.session;
workers.push(std::thread::Builder::new().name("studio-video-write".into()).spawn(
move || {
let mut previous = None;
let mut payload = Vec::new();
while !state.stopped() {
let (epoch, frame) = {
let mut frames = state.video.lock().unwrap();
loop {
if state.stopped() {
return;
}
if frames.flight.is_none()
&& let Some(p) = &frames.latest
{
let marker = (p.epoch, p.frame.frame_id.get());
if previous != Some(marker) {
let result = (p.epoch, p.frame.clone());
frames.flight = Some(marker);
previous = Some(marker);
break result;
}
}
frames = state
.wake
.wait_timeout(frames, Duration::from_millis(100))
.unwrap()
.0;
}
};
let size = match frame_bytes(
frame.width as u32,
frame.height as u32,
frame.width as u32,
) {
Ok(n) => n,
Err(e) => {
state.fail(e);
break;
}
};
payload.clear();
payload.reserve(FRAME_METADATA_BYTES + size);
payload.extend_from_slice(&session);
payload.extend_from_slice(&epoch.to_le_bytes());
payload.extend_from_slice(&frame.frame_id.get().to_le_bytes());
for n in [frame.width as u32, frame.height as u32, frame.width as u32, RGBA8] {
payload.extend_from_slice(&n.to_le_bytes());
}
for y in 0..frame.height {
for pixel in &frame.pixels
[y * frame.stride_pixels..y * frame.stride_pixels + frame.width]
{
payload.extend_from_slice(&pixel.to_be_bytes());
}
}
if let Err(e) = video_writer.send(FRAME, 0, &payload) {
state.fail(format!("Studio video lost: {e}"));
break;
}
}
},
)?);
let state = shared.clone();
let mut watch = video.try_clone()?;
workers.push(std::thread::Builder::new().name("studio-video-watch".into()).spawn(
move || {
let mut byte = [0];
match watch.read(&mut byte) {
Ok(0) => state.fail("Studio video connection closed"),
Ok(_) => state.fail("Unexpected data on video channel"),
Err(e) => state.fail(format!("Studio video connection failed: {e}")),
}
},
)?);
Ok(Self { shared, outgoing: tx, incoming, control, video, workers })
}
pub fn send(&self, kind: u16, request: u64, payload: Vec<u8>) -> io::Result<()> {
self.outgoing
.try_send(Outbound { kind, request, payload, flushed: None })
.map_err(|_| invalid("Studio output queue unavailable"))
}
pub fn finish(&self, request: u64) -> io::Result<()> {
let (tx, rx) = mpsc::sync_channel(1);
self.outgoing
.try_send(Outbound { kind: STOPPED, request, payload: Vec::new(), flushed: Some(tx) })
.map_err(|_| invalid("Studio output queue unavailable"))?;
rx.recv_timeout(Duration::from_secs(2))
.map_err(|_| invalid("Studio shutdown acknowledgement failed"))
}
pub fn next(&self) -> Option<Message> {
self.incoming.try_recv().ok()
}
pub fn failure(&self) -> Option<String> {
self.shared.failure.lock().unwrap().clone()
}
pub fn idle(&self) -> Duration {
self.shared.activity.lock().unwrap().elapsed()
}
pub fn publish(&self, epoch: u64, frame: OwnedRgba8888Frame) {
self.shared.video.lock().unwrap().latest =
Some(Publication { epoch, frame: Arc::new(frame) });
self.shared.wake.notify_one();
}
}
impl Drop for Transport {
fn drop(&mut self) {
self.shared.closed.store(true, Ordering::SeqCst);
self.shared.wake.notify_all();
let _ = self.control.shutdown(Shutdown::Both);
let _ = self.video.shutdown(Shutdown::Both);
for worker in self.workers.drain(..) {
let _ = worker.join();
}
}
}
@@ -0,0 +1,227 @@
//! Bounded, explicitly little-endian Studio Play messages.
use std::io::{self, Read, Write};
pub const HEADER_BYTES: usize = 32;
pub const CONTROL_LIMIT: usize = 64 * 1024;
pub const FRAME_LIMIT: usize = 16 * 1024 * 1024;
pub const FRAME_METADATA_BYTES: usize = 48;
pub const HELLO: u16 = 1;
pub const READY: u16 = 2;
pub const START: u16 = 3;
pub const PAUSE: u16 = 4;
pub const RESUME: u16 = 5;
pub const STOP: u16 = 6;
pub const RESULT: u16 = 7;
pub const INPUT: u16 = 8;
pub const FRAME: u16 = 9;
pub const FRAME_RECEIVED: u16 = 10;
pub const PING: u16 = 11;
pub const PONG: u16 = 12;
pub const ERROR: u16 = 13;
pub const STOPPED: u16 = 14;
pub const BOOTSTRAP: u16 = 15;
pub const RGBA8: u32 = 1;
pub fn invalid(message: &str) -> io::Error {
io::Error::new(io::ErrorKind::InvalidData, message)
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Header {
pub kind: u16,
pub length: usize,
pub sequence: u64,
pub request: u64,
}
impl Header {
fn validate(self) -> io::Result<()> {
if !(HELLO..=BOOTSTRAP).contains(&self.kind) || self.sequence == 0 {
return Err(invalid("invalid Studio message type/sequence"));
}
if self.length > if self.kind == FRAME { FRAME_LIMIT } else { CONTROL_LIMIT } {
return Err(invalid("Studio payload exceeds limit"));
}
Ok(())
}
pub fn encode(self) -> io::Result<[u8; HEADER_BYTES]> {
self.validate()?;
let mut b = [0; HEADER_BYTES];
b[..4].copy_from_slice(b"PST1");
b[4..6].copy_from_slice(&1u16.to_le_bytes());
b[8..10].copy_from_slice(&self.kind.to_le_bytes());
b[12..16].copy_from_slice(&(self.length as u32).to_le_bytes());
b[16..24].copy_from_slice(&self.sequence.to_le_bytes());
b[24..32].copy_from_slice(&self.request.to_le_bytes());
Ok(b)
}
pub fn decode(b: &[u8; HEADER_BYTES]) -> io::Result<Self> {
if &b[..4] != b"PST1" || b[4..8] != [1, 0, 0, 0] || b[10..12] != [0, 0] {
return Err(invalid("invalid Studio magic/version/flags"));
}
let h = Self {
kind: u16::from_le_bytes(b[8..10].try_into().unwrap()),
length: u32::from_le_bytes(b[12..16].try_into().unwrap()) as usize,
sequence: u64::from_le_bytes(b[16..24].try_into().unwrap()),
request: u64::from_le_bytes(b[24..32].try_into().unwrap()),
};
h.validate()?;
Ok(h)
}
}
#[derive(Debug)]
pub struct Message {
pub header: Header,
pub payload: Vec<u8>,
}
pub struct Reader<R> {
input: R,
sequence: u64,
}
impl<R: Read> Reader<R> {
pub fn new(input: R) -> Self {
Self { input, sequence: 0 }
}
pub fn receive(&mut self) -> io::Result<Message> {
self.receive_bounded(FRAME_LIMIT)
}
pub fn receive_control(&mut self) -> io::Result<Message> {
self.receive_bounded(CONTROL_LIMIT)
}
fn receive_bounded(&mut self, limit: usize) -> io::Result<Message> {
let mut bytes = [0; HEADER_BYTES];
self.input.read_exact(&mut bytes)?;
let header = Header::decode(&bytes)?;
if header.length > limit {
return Err(invalid("payload exceeds channel limit"));
}
if header.sequence <= self.sequence {
return Err(invalid("non-monotonic Studio sequence"));
}
self.sequence = header.sequence;
let mut payload = vec![0; header.length];
self.input.read_exact(&mut payload)?;
Ok(Message { header, payload })
}
}
pub struct Writer<W> {
output: W,
sequence: u64,
}
impl<W: Write> Writer<W> {
pub fn new(output: W) -> Self {
Self { output, sequence: 0 }
}
pub fn send(&mut self, kind: u16, request: u64, payload: &[u8]) -> io::Result<()> {
self.sequence =
self.sequence.checked_add(1).ok_or_else(|| invalid("sequence exhausted"))?;
self.output.write_all(
&Header { kind, request, sequence: self.sequence, length: payload.len() }.encode()?,
)?;
self.output.write_all(payload)?;
self.output.flush()
}
}
#[derive(Debug)]
pub struct Bootstrap {
pub session: [u8; 16],
pub token: [u8; 32],
pub control_port: u16,
pub video_port: u16,
pub disposable: bool,
}
impl Bootstrap {
pub fn read(input: impl Read) -> io::Result<Self> {
let m = Reader::new(input).receive()?;
let p = &m.payload;
if m.header.kind != BOOTSTRAP || m.header.request != 0 || p.len() != 53 || p[52] > 1 {
return Err(invalid("invalid Studio bootstrap"));
}
let b = Self {
session: p[..16].try_into().unwrap(),
token: p[16..48].try_into().unwrap(),
control_port: u16::from_le_bytes(p[48..50].try_into().unwrap()),
video_port: u16::from_le_bytes(p[50..52].try_into().unwrap()),
disposable: p[52] != 0,
};
if b.control_port == 0 || b.video_port == 0 || b.control_port == b.video_port {
return Err(invalid("invalid Studio ports"));
}
Ok(b)
}
pub fn hello(&self, role: u8) -> Vec<u8> {
let mut p = Vec::with_capacity(49);
p.extend_from_slice(&self.session);
p.extend_from_slice(&self.token);
p.push(role);
p
}
}
pub fn frame_bytes(width: u32, height: u32, stride: u32) -> io::Result<usize> {
if width == 0 || height == 0 || stride != width {
return Err(invalid("invalid frame dimensions/stride"));
}
(stride as usize)
.checked_mul(height as usize)
.and_then(|n| n.checked_mul(4))
.filter(|n| *n <= FRAME_LIMIT - FRAME_METADATA_BYTES)
.ok_or_else(|| invalid("frame exceeds limit"))
}
#[cfg(test)]
mod tests {
use super::*;
fn fixture() -> Vec<u8> {
let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../devtools/studio-protocol/fixtures/pause.hex");
std::fs::read_to_string(root)
.unwrap()
.split_whitespace()
.map(|s| u8::from_str_radix(s, 16).unwrap())
.collect()
}
#[test]
fn header_matches_shared_fixture() {
let expected = fixture();
let actual = Header { kind: PAUSE, length: 0, sequence: 1, request: 42 }.encode().unwrap();
assert_eq!(actual.as_slice(), expected);
assert_eq!(Header::decode(&actual).unwrap().request, 42);
}
#[test]
fn truncation_replay_and_invalid_header_fail() {
let bytes = fixture();
assert!(Reader::new(&bytes[..31]).receive().is_err());
let repeated = [bytes.as_slice(), bytes.as_slice()].concat();
let mut r = Reader::new(repeated.as_slice());
assert!(r.receive().is_ok());
assert!(r.receive().is_err());
for offset in [0, 4, 6, 8, 10] {
let mut bad: [u8; 32] = bytes.clone().try_into().unwrap();
bad[offset] = 255;
assert!(Header::decode(&bad).is_err());
}
assert!(
Header { kind: INPUT, length: CONTROL_LIMIT + 1, sequence: 1, request: 0 }
.encode()
.is_err()
);
assert!(frame_bytes(u32::MAX, u32::MAX, u32::MAX).is_err());
assert!(frame_bytes(480, 270, 481).is_err());
assert_eq!(frame_bytes(480, 270, 480).unwrap(), 518400);
}
#[test]
fn fragmented_reads_and_writes_preserve_messages() {
struct Short<'a>(&'a [u8]);
impl Read for Short<'_> {
fn read(&mut self, b: &mut [u8]) -> io::Result<usize> {
let n = b.len().min(3).min(self.0.len());
b[..n].copy_from_slice(&self.0[..n]);
self.0 = &self.0[n..];
Ok(n)
}
}
let mut bytes = Vec::new();
Writer::new(&mut bytes).send(INPUT, 9, &[1, 2, 3]).unwrap();
let m = Reader::new(Short(&bytes)).receive().unwrap();
assert_eq!(m.payload, [1, 2, 3]);
assert_eq!(m.header.request, 9);
assert!(Reader::new(&bytes[..bytes.len() - 1]).receive().is_err());
}
}
@@ -0,0 +1,215 @@
//! Real process qualification: no window, slow consumer, pause and broken IPC.
use prometeu_host_desktop_winit::studio::wire::*;
use std::io::{self, BufRead, Write};
use std::net::{Shutdown, TcpListener, TcpStream};
use std::process::{Child, Command, ExitStatus, Stdio};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
struct Session {
child: Child,
control: Reader<TcpStream>,
writer: Writer<TcpStream>,
video: Reader<TcpStream>,
control_socket: TcpStream,
video_socket: TcpStream,
logs: Arc<Mutex<Vec<String>>>,
}
impl Session {
fn start() -> Self {
let control = TcpListener::bind("127.0.0.1:0").unwrap();
let video = TcpListener::bind("127.0.0.1:0").unwrap();
let cart = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../test-cartridges/dummy-boy");
let child = Command::new(env!("CARGO_BIN_EXE_prometeu-host-desktop-winit"))
.args(["--studio", "--run"])
.arg(cart)
.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::piped())
.spawn()
.unwrap();
let logs = Arc::new(Mutex::new(Vec::new()));
let mut session_child = child;
for stream in [
Box::new(session_child.stdout.take().unwrap()) as Box<dyn io::Read + Send>,
Box::new(session_child.stderr.take().unwrap()) as Box<dyn io::Read + Send>,
] {
let log = logs.clone();
std::thread::spawn(move || {
for line in io::BufReader::new(stream).lines().map_while(Result::ok) {
let mut lines = log.lock().unwrap();
if lines.len() == 200 {
lines.remove(0);
}
lines.push(line);
}
});
}
let mut p = vec![3; 16];
p.extend_from_slice(&[7; 32]);
p.extend_from_slice(&control.local_addr().unwrap().port().to_le_bytes());
p.extend_from_slice(&video.local_addr().unwrap().port().to_le_bytes());
p.push(1);
Writer::new(session_child.stdin.take().unwrap()).send(BOOTSTRAP, 0, &p).unwrap();
fn accept(listener: TcpListener) -> TcpStream {
listener.set_nonblocking(true).unwrap();
let deadline = Instant::now() + Duration::from_secs(10);
loop {
match listener.accept() {
Ok((s, _)) => {
s.set_nonblocking(false).unwrap();
s.set_read_timeout(Some(Duration::from_secs(10))).unwrap();
return s;
}
Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
assert!(Instant::now() < deadline, "child did not connect");
std::thread::sleep(Duration::from_millis(5));
}
Err(e) => panic!("accept: {e}"),
}
}
}
let control = accept(control);
let video = accept(video);
let mut c = Reader::new(control.try_clone().unwrap());
let mut v = Reader::new(video.try_clone().unwrap());
for (message, role) in [(c.receive().unwrap(), 1), (v.receive().unwrap(), 2)] {
assert_eq!(message.header.kind, HELLO);
assert_eq!(&message.payload[..16], &[3; 16]);
assert_eq!(&message.payload[16..48], &[7; 32]);
assert_eq!(message.payload[48], role);
}
let control_socket = control.try_clone().unwrap();
let mut session = Self {
child: session_child,
control: c,
writer: Writer::new(control),
video: v,
control_socket,
video_socket: video,
logs,
};
let ready = session.control.receive().unwrap();
assert_eq!(ready.header.kind, READY, "{:?}", session.logs.lock().unwrap());
assert_eq!(u32::from_le_bytes(ready.payload[..4].try_into().unwrap()), 480);
session
}
fn command(&mut self, kind: u16, request: u64) -> Message {
self.writer.send(kind, request, &[]).unwrap();
let r = self.control.receive().unwrap();
assert_eq!(r.header.kind, RESULT, "{:?}", self.logs.lock().unwrap());
assert_eq!(r.header.request, request);
assert_eq!(u16::from_le_bytes(r.payload[2..4].try_into().unwrap()), 0, "{:?}", r.payload);
r
}
fn ping(&mut self) -> (u64, u64, u32) {
self.writer.send(PING, 0, &[]).unwrap();
let m = self.control.receive().unwrap();
assert_eq!(m.header.kind, PONG);
(
u64::from_le_bytes(m.payload[..8].try_into().unwrap()),
u64::from_le_bytes(m.payload[8..16].try_into().unwrap()),
u32::from_le_bytes(m.payload[16..20].try_into().unwrap()),
)
}
fn frame(&mut self) -> Message {
let m = self
.video
.receive()
.unwrap_or_else(|e| panic!("video: {e}; logs: {:?}", self.logs.lock().unwrap()));
assert_eq!(m.header.kind, FRAME);
assert_eq!(m.payload.len(), 48 + 480 * 270 * 4);
m
}
fn ack(&mut self, frame: &Message) {
self.writer.send(FRAME_RECEIVED, 0, &frame.payload[16..32]).unwrap();
}
fn exit(&mut self) -> ExitStatus {
let deadline = Instant::now() + Duration::from_secs(4);
loop {
if let Some(status) = self.child.try_wait().unwrap() {
return status;
}
assert!(
Instant::now() < deadline,
"runtime did not exit: {:?}",
self.logs.lock().unwrap()
);
std::thread::sleep(Duration::from_millis(10));
}
}
}
impl Drop for Session {
fn drop(&mut self) {
let _ = self.child.kill();
let _ = self.child.wait();
}
}
#[test]
fn slow_video_does_not_stop_ticks_and_pause_resumes_same_process() {
let mut s = Session::start();
let pid = s.child.id();
s.command(START, 1);
let first = s.frame();
let initial = s.ping();
std::thread::sleep(Duration::from_millis(150));
let later = s.ping();
assert!(later.1 > initial.1);
// No credit was returned while the runtime kept publishing. The next frame skips old presentations.
s.ack(&first);
let recent = s.frame();
assert!(
u64::from_le_bytes(recent.payload[24..32].try_into().unwrap())
> u64::from_le_bytes(first.payload[24..32].try_into().unwrap()) + 1
);
s.command(PAUSE, 2);
let paused = s.ping();
assert_eq!(paused.2, 2);
std::thread::sleep(Duration::from_millis(80));
assert_eq!(s.ping().1, paused.1);
s.command(RESUME, 3);
std::thread::sleep(Duration::from_millis(60));
assert!(s.ping().1 > paused.1);
assert_eq!(s.child.id(), pid);
s.command(STOP, 4);
assert_eq!(s.control.receive().unwrap().header.kind, STOPPED);
assert!(s.exit().success());
}
#[test]
fn broken_video_ends_runtime_even_when_paused() {
let mut s = Session::start();
s.command(START, 1);
s.command(PAUSE, 2);
s.video_socket.shutdown(Shutdown::Both).unwrap();
assert!(!s.exit().success());
}
#[test]
fn startup_focus_loss_arms_game_without_advancing_until_manual_resume() {
let mut s = Session::start();
let initial = s.ping().1;
s.command(PAUSE, 1);
s.command(START, 2);
std::thread::sleep(Duration::from_millis(50));
let paused = s.ping();
assert_eq!(paused.1, initial);
assert_eq!(paused.2, 2);
s.command(RESUME, 3);
let _ = s.frame();
assert!(s.ping().1 > initial);
s.command(STOP, 4);
assert_eq!(s.control.receive().unwrap().header.kind, STOPPED);
assert!(s.exit().success());
}
#[test]
fn truncated_control_ends_only_its_owned_runtime() {
let mut s = Session::start();
s.command(START, 1);
s.control_socket.write_all(b"PST").unwrap();
s.control_socket.shutdown(Shutdown::Write).unwrap();
assert!(!s.exit().success());
}
@@ -0,0 +1,38 @@
use prometeu_host_desktop_winit::studio::wire::*;
#[test]
fn rgba_fixture_pins_channel_order_and_metadata() {
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../devtools/studio-protocol/fixtures/rgba.hex");
let bytes: Vec<u8> = std::fs::read_to_string(path)
.unwrap()
.split_whitespace()
.map(|s| u8::from_str_radix(s, 16).unwrap())
.collect();
let m = Reader::new(bytes.as_slice()).receive().unwrap();
assert_eq!(m.header.kind, FRAME);
assert_eq!(m.header.length, 56);
assert_eq!(&m.payload[..16], &(0u8..16).collect::<Vec<_>>());
assert_eq!(
&m.payload[48..],
&[0xff0000ffu32.to_be_bytes(), 0x0000ff80u32.to_be_bytes()].concat()
);
assert_eq!(frame_bytes(2, 1, 2).unwrap() + FRAME_METADATA_BYTES, m.payload.len());
}
#[test]
fn bootstrap_rejects_wrong_roles_lengths_and_ports() {
let mut p = vec![0; 53];
p[48..50].copy_from_slice(&1234u16.to_le_bytes());
p[50..52].copy_from_slice(&1235u16.to_le_bytes());
p[52] = 1;
let mut bytes = Vec::new();
Writer::new(&mut bytes).send(BOOTSTRAP, 0, &p).unwrap();
let boot = Bootstrap::read(bytes.as_slice()).unwrap();
assert!(boot.disposable);
assert_eq!(boot.hello(1).len(), 49);
p[50..52].copy_from_slice(&1234u16.to_le_bytes());
bytes.clear();
Writer::new(&mut bytes).send(BOOTSTRAP, 0, &p).unwrap();
assert!(Bootstrap::read(bytes.as_slice()).is_err());
}
@@ -0,0 +1,2 @@
50 53 54 31 01 00 00 00 04 00 00 00 00 00 00 00
01 00 00 00 00 00 00 00 2a 00 00 00 00 00 00 00
@@ -0,0 +1,6 @@
50 53 54 31 01 00 00 00 09 00 00 00 38 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
01 00 00 00 00 00 00 00 07 00 00 00 00 00 00 00
02 00 00 00 01 00 00 00 02 00 00 00 01 00 00 00
ff 00 00 ff 00 00 ff 80
@@ -279,6 +279,13 @@ PROMETEU promises:
## 13 Deterministic Headless Control
The interactive desktop host also supports Studio-owned realtime execution without
a native game window, specified by [Studio Play Protocol v1](11b-studio-play-protocol.md).
This mode retains interactive pacing, native audio and the existing firmware/VM;
it is not the deterministic automation host. Its frame transport workers must not
block machine advancement on UI/video consumption. This addition does not change
the headless controls below, guest capabilities or canonical frame ownership.
The external tooling boundary is specified separately in
[Headless Automation Protocol v1](11a-headless-automation-protocol.md). It preserves
the in-process semantics in this section and does not extend the guest ABI.
@@ -0,0 +1,81 @@
# Studio Play Protocol v1
This protocol belongs to the interactive desktop host. It does not extend or replace
the deterministic headless automation protocol. The mode and Java adapter are
implemented and exercised on macOS ARM64 with a relocated installation of current
debug binaries. Protocol fixtures do not qualify other platforms or release builds.
The Studio starts `prometeu-runtime --studio --run <directory>` directly. No native
window/event loop is created in this mode. The parent listens on two ephemeral IPv4
loopback ports: control/input and video. Both connect/authenticate before readiness.
The parent sends a BOOTSTRAP message through private child stdin and closes stdin.
Bootstrap payload: session ID (16 bytes), random token (32 bytes), control/video ports
(u16 each), disposable-save selection (u8: 0 persistent, 1 explicitly disposable).
Token material must not appear in arguments or logs. No reconnect or automatic restart.
All integer fields use little-endian encoding. Messages have this 32-byte header:
| Offset | Type | Meaning |
| --- | --- | --- |
| 0 | 4 bytes | ASCII PST1 |
| 4 / 6 | u16 / u16 | major 1 / minor 0 |
| 8 / 10 | u16 / u16 | type / flags (zero) |
| 12 | u32 | payload bytes, validated before allocation |
| 16 | u64 | strictly increasing nonzero sequence per direction/channel |
| 24 | u64 | request correlation, zero for unsolicited messages |
Types: HELLO=1, READY=2, START=3, PAUSE=4, RESUME=5, STOP=6, RESULT=7,
INPUT=8, FRAME=9, FRAME_RECEIVED=10, PING=11, PONG=12, ERROR=13,
STOPPED=14, BOOTSTRAP=15. Unknown types/flags/versions, invalid sizes, replay,
invalid UTF-8 and truncated messages fail the connection. Control payload limit is
64 KiB; FRAME limit is 16 MiB including metadata. Overflow is rejected.
| Message | Payload |
| --- | --- |
| HELLO | session[16], token[32], role u8 (control=1, video=2) |
| READY | width/height/fps/format u32; UTF-8 runtime version in remaining bytes |
| START / PAUSE / RESUME / STOP / PING | empty; nonzero request ID for commands |
| RESULT | command u16, status u16 (0 success, 1 invalid state, 2 save blocked), input epoch u64, tick u64, UTF-8 diagnostic remainder |
| INPUT | input epoch u64, buttons u16, reserved u16=0, touch x/y i32 |
| FRAME | session[16], input epoch u64, frame ID u64, width/height/stride/format u32, pixels |
| FRAME_RECEIVED | input epoch u64, frame ID u64 |
| PONG | input epoch u64, tick u64, state u32 (0 ready, 1 running, 2 paused) |
| ERROR | UTF-8 diagnostic |
| STOPPED | empty; correlated with successful STOP |
Pixel format 1 is compact RGBA8: R,G,B,A bytes, stride equal to width. Never memcpy
native u32 `0xRRGGBBAA` as wire pixels. FRAME metadata occupies 48 bytes; dimensions
must match readiness and payload length exactly. Zoom is entirely a Studio concern.
INPUT bits 0..11 are up/down/left/right/a/b/x/y/l/r/start/select; bit 12 is touch.
Other bits are invalid. Apply samples in order at the canonical tick boundary; this
does not introduce event retention beyond canonical button sampling.
The machine starts only after START. Pause suspends simulation/audio and neutralizes
input; resume retains the same execution. A new input epoch invalidates queued input
across pause/resume. PAUSE is also admitted in READY: a subsequent START arms execution
while retaining that pause, and only an explicit RESUME begins ticks. This lets focus
loss during startup take effect before the first game tick. Control and heartbeat work
while paused. Stop preserves the
existing save/teardown checks; save refusal is a RESULT and keeps the session alive.
An explicitly disposable session permits discarding only its selected transient data.
Frame publication never waits for IO or presentation. One frame can be in flight;
FRAME_RECEIVED releases credit after full reception/validation, not after painting.
The sender selects the most recent complete publication when credit is available.
It must finish a partly written message or fail. The receiver drains independently
of the FX thread and replaces only an unowned pending complete image. Three local
receiver buffers cover receive, pending and FX-copy ownership; WritableImage owns its
own pixels. At most one pending FX notification is permitted.
Handshake deadline: 10 seconds. Command deadline: 5 seconds. Heartbeat interval:
1 second, failed after 5 seconds without valid control progress. Video silence while
paused and slow FX painting are not connection failures. Unexpected EOF on either
required channel or malformed data ends the runtime and reports available logs.
The Studio confirms exit and cleanup before releasing execution ownership; it does
not claim failed-process saves were flushed or rolled back. Normal EOF after STOPPED
is expected. Termination uses a 2-second bounded wait and a further 2-second forced
termination observation when required. The child also exits on lost parent control.
Language-neutral fixtures live in `devtools/studio-protocol/fixtures/` and are consumed
by both codecs. Qualification includes fragmented IO, invalid payloads, late session
messages, slow painting/sending, failure of each channel and headless regressions.
+1
View File
@@ -91,6 +91,7 @@ In the current state, no chapter under the active `docs/specs/runtime/` root is
| [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) | machine diagnostics | normative |
| [`11-portability-and-cross-platform-execution.md`](11-portability-and-cross-platform-execution.md) | portability contract | normative |
| [`11a-headless-automation-protocol.md`](11a-headless-automation-protocol.md) | external headless host automation | normative |
| [`11b-studio-play-protocol.md`](11b-studio-play-protocol.md) | interactive Studio binary IPC, separate from headless | normative |
| [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) | firmware and system orchestration | normative |
| [`13-cartridge.md`](13-cartridge.md) | cartridge package | normative |
| [`14-boot-profiles.md`](14-boot-profiles.md) | firmware boot flow | normative |
+35 -10
View File
@@ -53,6 +53,14 @@ prefix must be assigned before the ownership audit can pass.
## How test suites contribute
The current repository pipeline executes and measures only library/binary unit
tests (`--lib --bins`). Integration targets under `tests/`, debugger socket tests,
installed qualification and physical-device checks are excluded. Selected suites
are orchestrated by `../tooling`; their tests and fixtures stay in this repository.
Selecting them explicitly is separate from the unit quality gate.
The cross-suite contribution descriptions and previous measurements below retain
historical context; they do not imply integration execution in the current gate.
VM unit/integration tests, including numeric_contract and the portable
MPFR-generated fixture, exercise vm/core. Bytecode round-trip and Registry
admission tests exercise bytecode; end-to-end loading can also exercise
@@ -74,7 +82,7 @@ they do not create separate gates with zero executable lines.
Only crate src paths participate in this domain denominator; integration
test directories, examples, benches, external dependencies and standalone
Python oracle code are outside it. The LLVM instrumentation/report remains
the existing workspace all-features default-profile measurement. Unit tests
the workspace all-features default-profile, library/binary-unit measurement. Unit tests
colocated in src retain the tool's existing reporting behavior.
The standalone MPFR precision/bit comparison remains complementary numeric
@@ -129,12 +137,11 @@ The ordered checks are:
1. Clean previous LLVM coverage instrumentation and reports.
2. Check formatting.
3. Run workspace Clippy with warnings denied.
4. Run workspace tests across all targets and features.
5. Run the five ignored debugger socket tests.
6. Generate workspace coverage, HTML, full JSON, Cobertura and summary JSON.
7. Audit source ownership/evidence and check every fixed coverage domain floor.
4. Run library/binary unit tests across all workspace features (`make test-unit`).
5. Generate unit-only workspace coverage, HTML, full JSON, Cobertura and summary JSON.
6. Audit source ownership/evidence and check every fixed coverage domain floor.
The socket command is deliberately restricted:
The optional socket command is deliberately restricted and is not part of CI:
```sh
cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored
@@ -194,9 +201,8 @@ scripts/coverage-domain-evidence.sh --check --verbose hal/core
### Explicit manual qualification
Ordinary all-target tests and coverage leave ignored device/measurement tests
ignored. The shared target only opts in to the five socket tests above. It does
not certify the following manual workloads:
Unit tests and coverage leave ignored device/measurement tests ignored. The shared
target does not opt in to socket tests and does not certify the following manual workloads:
```sh
# Physical desktop audio, exact named test.
@@ -269,7 +275,26 @@ The full local `make ci-domains` validation passed with 939 tests passed and
in verification; its final floor uses the lower measurement. All gates were
rechecked against the verification report after that final adjustment.
## Current coverage measurement
## Unit-only baseline revision
The gate now measures only `--lib --bins` unit harnesses. Two independent fresh
measurements agreed on bytecode 86.51%, host/headless 58.74%, and tooling 50.96%.
Their explicitly approved unit floors use five percentage points of headroom:
| Domain | Unit measurement | Unit floor | Previous combined floor |
| --- | ---: | ---: | ---: |
| bytecode | 86.51% | 81.51% | 88.26% |
| host/headless | 58.74% | 53.74% | 83.39% |
| tooling | 50.96% | 45.96% | 59.75% |
The other twelve floors and all source ownership paths are unchanged. The config
identifies `test_suite: unit` and preserves each replaced combined floor in
`previous_combined_baseline_percent`. This is a reviewed change of measurement
scope, not an automatic response to future coverage failures. Subsequent unit
regressions remain subject to these fixed floors. Earlier combined measurements
below remain historical and are not current unit coverage claims.
## Previous combined-suite coverage measurement
The [current evidence](COVERAGE_DOMAINS_CURRENT.json) identifies the committed
source by HEAD and content fingerprints, records the strict shared gate and
+4 -5
View File
@@ -32,12 +32,11 @@ pipeline {
stage('Clippy') {
steps { sh 'make -j1 clippy' }
}
stage('Workspace tests') {
steps { sh 'make -j1 test-local' }
}
stage('Debugger socket tests') {
steps { sh 'make -j1 test-debugger-socket' }
stage('Unit tests') {
steps { sh 'make -j1 test-unit' }
}
// Integration/socket/installed qualification is orchestrated by ../tooling;
// it is intentionally not invoked by this repository pipeline.
stage('Coverage') {
steps { sh 'make -j1 coverage' }
}
@@ -1,5 +1,6 @@
{
"version": 1,
"test_suite": "unit",
"domains": {
"system/os": {
"baseline_percent": 77.24,
@@ -54,7 +55,8 @@
]
},
"host/headless": {
"baseline_percent": 83.39,
"baseline_percent": 53.74,
"previous_combined_baseline_percent": 83.39,
"paths": [
"crates/host/prometeu-host-headless/src/"
]
@@ -66,7 +68,8 @@
]
},
"bytecode": {
"baseline_percent": 88.26,
"baseline_percent": 81.51,
"previous_combined_baseline_percent": 88.26,
"paths": [
"crates/console/prometeu-bytecode/src/"
]
@@ -111,7 +114,8 @@
]
},
"tooling": {
"baseline_percent": 59.75,
"baseline_percent": 45.96,
"previous_combined_baseline_percent": 59.75,
"paths": [
"crates/tools/prometeu-cli/src/",
"crates/tools/pbxgen-dummy-boy/src/",