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