5.5 KiB
id, ticket, title, created, tags
| id | ticket | title | created | tags | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| LSN-0057 | headless-automation-host-and-deterministic-runtime-control | Deterministic Host Control Follows Logical Runtime Boundaries | 2026-09-22 |
|
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
- Record the current logical-frame index and latest published frame id.
- Unpause the active VM session and request one debug frame step.
- Tick firmware with the retained
InputSignals. - Clear pending audio commands after every tick.
- Continue until the logical-frame index advances or a structured fault is visible.
- Pause the VM again.
- 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
stepand 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.