feat(runtime): support Studio Play and separate integration gates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
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:
@@ -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.
|
||||
Reference in New Issue
Block a user