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
@@ -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 |