harden deterministic headless runtime control
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user