126 lines
5.5 KiB
Markdown
126 lines
5.5 KiB
Markdown
---
|
|
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.
|