add headless automation
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-09-22 13:28:31 +01:00
parent 5b106af0f3
commit e0c08c8b00
15 changed files with 883 additions and 47 deletions
@@ -0,0 +1,125 @@
---
id: LSN-0057
ticket: headless-automation-host-and-deterministic-runtime-control
title: Deterministic Host Control Follows Logical Runtime Boundaries
created: 2026-09-22
tags: [runtime, host, headless, deterministic, testing, input, framebuffer, lifecycle]
---
## Context
Prometeu needed an automation host that could boot and control a real cartridge
without a window, display surface, audio device, or refresh-rate delay. The
runtime already had the necessary domain boundaries: normalized
`InputSignals`, logical-frame execution, structured `CrashReport` values, and
worker-published `OwnedRgba8888Frame` values. The missing piece was a host that
composed those boundaries without inheriting desktop presentation concerns.
The implementation introduced the in-process `prometeu-host-headless` library
under `DEC-0043`. It proved deterministic input, frame advancement, pixel
capture, faults, audio discard, and reset behavior with directory cartridges
assembled directly in Rust tests.
## Key Decisions
### Logical Frames, Not Host Ticks, Are the Automation Unit
**What:** `advance_frame` repeatedly ticks firmware until the VM closes one
logical frame or reports a fault. It temporarily releases VM pause through the
existing debug-step request and leaves the VM paused afterward.
**Why:** A firmware tick is an execution budget slice, not necessarily a guest
frame. Exposing ticks would make automation sensitive to budget configuration
and host speed. Waiting for `FrameSync`, end-of-ROM, or a fault gives callers a
guest-visible boundary.
**Trade-offs:** One automation operation may execute multiple firmware ticks.
The host must therefore drain audio after every tick and must distinguish
instruction stepping from logical-frame advancement.
### Published Worker Frames Are the Pixel Oracle
**What:** Frame capture reads the `LatestRenderFrameStore` populated by the
existing render worker and waits for a frame id newer than the one observed
before advancement.
**Why:** Reading mutable hardware buffers would create a second observation
path and could expose partially applied work. The published
`OwnedRgba8888Frame` is already the runtime's canonical completed-frame
boundary, as described by `LSN-0049`.
**Trade-offs:** Logical execution and frame publication finish on different
threads, so capture must synchronize with publication. That wait is worker
completion, not refresh pacing.
### Cold Reset Must Clear Lifecycle Ownership as Well as VM State
**What:** Entering `FirmwareState::Reset` terminates the resident game before
clearing VM sessions and global runtime cartridge state.
**Why:** Clearing only the VM session registry leaves the foreground lifecycle
stack pointing at the old resident task. The next boot then looks like a second
resident game and fails with `ResidentGameAlreadyExists`. A cold boot boundary
must clear both execution state and the ownership records that authorize it.
**Trade-offs:** Reset is destructive lifecycle replacement. It intentionally
does not preserve the previous game as resumable state; Home suspend/resume is
the separate contract for preservation.
## Patterns and Algorithms
### Deterministic Frame Advancement
1. Record the current logical-frame index and latest published frame id.
2. Unpause the active VM session and request one debug frame step.
3. Tick firmware with the retained `InputSignals`.
4. Clear pending audio commands after every tick.
5. Continue until the logical-frame index advances or a structured fault is
visible.
6. Pause the VM again.
7. Read the publication store until the worker publishes a different frame id.
This keeps the oracle independent of wall-clock refresh timing while exercising
the same firmware, VM, render worker, input, and audio paths as a real host.
### Repeatability Oracle
Compare only stable runtime outputs:
- logical-frame index;
- published RGBA8888 pixels and frame identity progression;
- debugger-shaped state (`pc`, stack top, frame index, and app id);
- structured fault data.
Do not compare host CPU time, `Instant` timestamps, or certification budgets.
Those values characterize execution conditions, not deterministic guest state.
## Pitfalls
- One firmware tick is not guaranteed to complete one guest frame.
- Instruction `step` and logical-frame advancement have different contracts.
- Capturing the hardware front buffer bypasses the canonical worker publication
boundary.
- Sleeping for a display period makes a headless host inherit presentation
pacing and turns 300-frame tests into multi-second runs.
- Clearing VM sessions without clearing resident-game lifecycle ownership does
not produce a cold reset.
- Opening or emulating an audio device is unnecessary when the required sink
semantics are simply to consume and discard queued commands.
## References
- Decision: `DEC-0043` (Headless Host and Deterministic Frame Control)
- Related lesson: `LSN-0049` (Render Workers Publish Frames, Hosts Present Them)
- Related lesson: `LSN-0053` (Game Switching Is Lifecycle Replacement, Not Loader Work)
- Audio contract: `docs/specs/runtime/05-audio-peripheral.md`
## Takeaways
- Automation should advance guest-defined logical boundaries, not host loop
iterations.
- Deterministic input is a retained normalized value supplied to every tick.
- The render worker's publication store is the single trustworthy pixel oracle.
- Headless execution can reuse production runtime paths without linking native
presentation or audio-device libraries.
- A cold reset must clear lifecycle ownership and execution state together.