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:
@@ -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.
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user