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
+10 -1
View File
@@ -75,7 +75,9 @@ palette, host presentation, or compatibility contract.
### Published owned frame
The canonical worker-published frame value is `OwnedRgba8888Frame`.
The canonical published frame value is `OwnedRgba8888Frame`. It is produced by
either the local synchronous consumer or the asynchronous render worker; the
consumer path does not change the frame contract.
`OwnedRgba8888Frame` contains:
@@ -184,6 +186,13 @@ producer path MUST remain non-blocking with respect to worker rasterization and
host present. A slow worker can cause replacement/drop telemetry, but it MUST
NOT create an unbounded queue or stall VM logical frame production.
A local synchronous consumer consumes the same immutable `RenderSubmission`
through the same render backend and publishes the same canonical
`OwnedRgba8888Frame` before returning. It does not use the asynchronous
single-slot handoff and therefore does not weaken or reinterpret the worker's
non-blocking producer contract. A host may select this path when an explicit
synchronous observation boundary is part of its host contract.
### 4.4 Frame pacing
Game logical frames are paced by the runtime frame scheduler, not by render
@@ -81,6 +81,25 @@ When the host activates instruction-level inspection, it may observe:
- operand stack
- call stack
### 3.3 Debugger and Headless Semantic Alignment
Interactive debugging and deterministic headless automation share runtime
meanings even though their transports and pacing differ:
| Runtime meaning | Debugger command/observation | Headless operation |
| --- | --- | --- |
| Pause active VM execution | `pause` | `pause()` |
| Resume active VM execution | `resume` | `resume()` |
| Execute one VM instruction and remain paused | `step` | `step()` |
| Complete one logical frame and remain paused | `stepFrame` | `advance_frame()` |
| Read overlapping execution state | `getState` | `get_state()` |
| Observe structured current fault | event/current state | `get_fault()` |
| Inject normalized input | not defined by the debugger protocol | `set_input()` |
| Reset the machine execution | not defined by the debugger protocol | `reset()` |
| Capture the canonical published frame | not defined by the debugger protocol | `capture_frame()` |
The headless API does not define or extend an external automation protocol.
## 4 State Inspection Boundary
Detailed state inspection is a host-owned concern. The runtime may expose deterministic machine state to host tooling, but this chapter does not define a general guest ABI for introspection convenience.
@@ -118,8 +118,8 @@ Hardware differences:
The graphics system:
- produces typed logical render submissions that render to RGBA8888 output
- may consume Game submissions through a render worker that publishes owned
`OwnedRgba8888Frame` values
- consumes Game submissions through either a local synchronous consumer or a
render worker, both of which publish owned `OwnedRgba8888Frame` values
- uses an indexed palette
- does not depend on a specific GPU
@@ -128,8 +128,8 @@ The platform layer:
- exposes typed service facades for render submission, render backend
execution, Game 2D composition, input, audio, assets, and telemetry
- consumes closed render submissions through a render-surface implementation
- transports published RGBA8888 output or worker-published
`OwnedRgba8888Frame` pixels into a host presentation surface without
- transports published `OwnedRgba8888Frame` pixels into a host presentation
surface without
injecting host-owned debug overlay pixels
- is the runtime-facing portability boundary; runtime and firmware code must not
depend on a monolithic hardware bridge or on a concrete hardware aggregate
@@ -216,3 +216,72 @@ PROMETEU promises:
- **identical logical behavior**
- **reproducible technical decisions**
## 13 Deterministic Headless Control
The headless host is a separate, generic Prometeu host for in-process
automation. It runs the same directory cartridge, firmware, active VM session,
capability checks, normalized input, render submissions, and fault model as an
interactive host. A cartridge cannot detect or request headless execution, and
headless execution grants no additional guest capability.
The headless host requires no native window, display server, physical input,
physical audio device, or realtime frame pacing. It uses the explicit local
synchronous Game render consumer. A successful logical-frame advance returns
only after the exact canonical `OwnedRgba8888Frame` for that advance has been
published. It does not start or wait for an asynchronous render worker, and
publication correctness does not use spinning, yielding, sleeping, or a
wall-clock timeout.
### 13.1 Control contract
- `boot(path)` loads a normal directory cartridge and stops on entry to
`GameRunning`, before the first game instruction. A second boot attempt
requires `reset()` and otherwise returns `AlreadyBooted`.
- `reset()` enters the normal firmware reset boundary and clears input, active
sessions, structured faults, and headless frame correlation. Capture is
unavailable until the new run completes a frame.
- `pause()` and `resume()` control the active VM session. `step()` executes one
VM instruction and finishes paused without reporting a completed logical
frame.
- `set_input()` retains one complete `InputSignals` snapshot, including the
digital pad and touch signal/coordinates. `clear_input()` restores its
default. The normal begin-frame input sampling defined by the input
peripheral derives `pressed`, `released`, `down`, and `hold` state.
- `advance_frame()` advances internal firmware ticks until exactly one logical
frame closes through `FrameSync` or `EndOfRom`, or until a structured fault or
lifecycle termination prevents completion. Internal cycle-slice exhaustion
continues the same frame; it is not itself a frame boundary.
- `advance_frames(n)` is repeated `advance_frame()`. It reports the requested
and completed counts plus completed-all, fault, or termination. Zero is a
no-op; fault or termination preserves partial completed progress.
- A frame advance finishes paused. Guest faults are outcomes represented by
`CrashReport`; host precondition, publication, and safety-limit failures are
host errors.
- `capture_frame()` returns an owned clone of the canonical frame paired with
the latest successful advance. The explicit `{logical_frame_index, FrameId}`
pair is authoritative; no numeric equality or fixed offset is implied.
- `get_state()` classifies execution as running, paused, terminated, or faulted
and exposes the overlapping debugger state. `get_fault()` returns structured
`CrashReport` data rather than requiring log or summary parsing.
- Valid audio commands pass through normal runtime semantics. The headless host
drains them into a null/discard sink; it does not synthesize PCM or require an
output device.
### 13.2 Deterministic oracle
Deterministic comparison includes the logical-frame index and paired `FrameId`,
canonical framebuffer pixels (or a stable pixel hash) and dimensions/stride,
guest-visible PC/stack/app state, structured execution status and fault data,
and deterministic counters describing simulated execution.
The oracle excludes wall-clock or boot-time timestamps, real elapsed duration,
host CPU time, thread-scheduling measurements, presentation cadence,
render-worker timing telemetry, and host-owned identities without simulated
machine meaning. The same cartridge, initial machine state, and per-frame input
timeline must produce the same included observations on independent runs and
after reset.
AI tooling may consume this generic host API from outside the machine. It does
not create an AI mode, testing mode, replay protocol, gameplay introspection
surface, or guest capability.