harden deterministic headless runtime control
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-09-23 07:09:46 +01:00
parent 2516fae4fc
commit 89101d1b20
14 changed files with 856 additions and 121 deletions
@@ -0,0 +1,134 @@
---
id: LSN-0058
ticket: headless-automation-host-hardening
title: Deterministic Observation Must Follow the Active Producer
created: 2026-09-23
tags: [runtime, host, headless, deterministic, rendering, testing, debugger]
---
## Context
The first headless automation host appeared to synchronize frame capture with a
render worker: it started a worker, remembered the latest published frame id,
and spun for a bounded number of iterations after logical execution. Source
revalidation showed that this story did not match the running system. A Game
cartridge executes inside an active `VmSession`, and that session selected the
existing `LocalSynchronous` render consumer. The worker started on the global
fallback runtime never consumed the active session's submissions.
The visible frame was already published synchronously through the normal
platform sink. The spin was therefore redundant in successful runs and would
still have been incorrect for a future asynchronous path because it waited for
"any different frame" rather than the specific frame requested by automation.
## Key Decisions
### The Observation Contract Follows the Active Execution Owner
**What:** The headless host intentionally uses the active session's local
synchronous consumer and removes the unused global worker and bounded spin.
**Why:** Synchronization must be defined against the component that actually
produces the observed value. Waiting on an unrelated worker creates accidental
success and makes the architecture harder to reason about.
**Trade-offs:** The deterministic headless host does not exercise worker
concurrency on every cartridge run. Worker equivalence remains a separate
runtime conformance concern rather than part of each game's oracle.
### Completion Carries Exact Identity
**What:** Successful frame advancement retains the explicit
`{logical_frame_index, FrameId}` pair and capture validates that exact published
frame before cloning its `OwnedRgba8888Frame`.
**Why:** A generation change only proves that something was published. It does
not prove which logical operation produced it. Exact identity makes stale or
mis-associated observations detectable.
**Trade-offs:** Logical frame numbers and render frame ids remain separate
domains. Callers compare the explicit pair rather than assuming equality or a
fixed offset.
### A Tick Slice Must Be Smaller Than the Logical Budget
**What:** The runtime's per-firmware-tick execution slice is smaller than the
total logical-frame cycle budget. Headless advancement loops across slices
until the frame closes or a terminal outcome occurs.
**Why:** When both limits were equal, `BudgetExhausted` left zero remaining
logical budget, so another tick could not make progress. The documented
multi-tick contract existed only nominally. Separating the limits makes a tick
an implementation slice and keeps a logical frame as the automation unit.
**Trade-offs:** A computation-heavy logical frame can span several firmware
ticks. This is observable through deterministic tick counters but does not
change guest frame semantics.
### Debug Instruction Step Must Prime the Entry Call
**What:** The shared debugger instruction-step primitive prepares the VM entry
call when the call stack is empty before executing one instruction.
**Why:** Direct boot intentionally stops before the first game instruction. A
debug step at that point previously encountered the coroutine safepoint and
reported `FrameSync` as an unexpected panic instead of executing the first
instruction.
**Trade-offs:** Entry preparation remains shared runtime behavior. No
headless-specific VM branch is introduced.
## Patterns and Algorithms
### Deterministic Frame Advance
1. Record the current logical-frame index and latest canonical frame id.
2. Release pause and request the same one-frame stop used by debugger control.
3. Tick firmware while feeding the retained normalized `InputSignals`.
4. Continue through internal cycle-slice exhaustion.
5. Stop on exactly one logical-frame increment, structured fault, lifecycle
termination, or a typed host safety-limit error.
6. Clear the frame-step request and finish paused.
7. On success, require a new canonical frame and retain its exact identity with
the completed logical index.
### Deterministic Oracle Boundary
Include observations that describe simulated execution: logical frame and
frame identity, canonical pixels and layout, guest-visible state, structured
status/faults, and deterministic machine counters.
Exclude observations of the host running the simulation: wall time, CPU time,
thread scheduling, presentation cadence, worker timing, and host-only
identities.
## Pitfalls
- A worker created by a host may not own the active session being automated.
- Bounded spinning is neither an acknowledgement nor an identity check.
- "Latest changed" is weaker than "the requested frame was published."
- Equal slice and logical budgets can make multi-tick continuation impossible
even when the control loop appears to support it.
- A debug step from a pristine boot boundary must establish the same entry-call
precondition as normal execution.
- Human-readable fault summaries are useful diagnostics but are not a stable
automation interface; retain structured `CrashReport` values.
## References
- Decision: `DEC-0044` (Deterministic Headless Automation Host Contract)
- Prior lesson: `LSN-0057` (Deterministic Host Control Follows Logical Runtime Boundaries)
- Render worker lesson: `LSN-0049` (Render Workers Publish Frames, Hosts Present Them)
- Graphics contract: `docs/specs/runtime/04-gfx-peripheral.md`
- Debug contract: `docs/specs/runtime/10-debug-inspection-and-profiling.md`
- Portability and headless contract: `docs/specs/runtime/11-portability-and-cross-platform-execution.md`
## Takeaways
- Revalidate ownership and data flow from source before hardening a wait.
- Deterministic observation requires exact completion identity, not timing luck.
- Keep logical-frame control above internal execution slices.
- Use one production runtime path for interactive debugging and headless
automation; vary host transport and pacing, not machine semantics.
- Test infrastructure boundaries with counters and structured outcomes instead
of sleeps or log parsing.