Files
prometeu-runtime/discussion/lessons/DSC-0049-headless-automation-host-and-deterministic-runtime-control/LSN-0057-deterministic-host-control-follows-logical-runtime-boundaries.md
T
bquarkz e0c08c8b00
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
add headless automation
2026-09-22 13:28:31 +01:00

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