docs/research/QVM_STEP_STATE.md

Game-QVM child flags, clock update and early dispatch

RE-421–423 / F-175–177. qvm-step-state.json retains shipped qagame child53418 instruction evidence, 240 flag-gate probes, eight clock probes, twenty scheduler/clock compositions and 105 early-dispatch probes. Reproduce with python3 scripts/analyze_qvm_step_state.py; verify with python3 scripts/test_qvm_step_state.py.

This follows the movement scheduler. All results are bounded synthetic instruction evaluations. No original executable, native callee, complete QVM or physics runs. The clock prefix replaces the previously assumed clock advancement in selected scheduler fixtures; all other child work remains omitted. External dispatch callees are recorded with default return zero and no effects. This is not a full movement or runtime fixture.

STEP-001 — Packed-word attack candidate and flag release (RE-421)

The child prefix at53593–53714 sets player-state+104 bit512 only when all of these predicates hold:

• Initial player-state+12 bit256 is clear.
• Player-state+4 is not5.
• Command buttons at frame+20 include mask1.
• The second byte of the packed word at player-state+312 +4*player-state[+144] is nonzero.

Otherwise it clears bit512, retaining all other +104 bits. This is an attack-related candidate flag; the packed byte's weapon/ammunition interpretation and full consumers require confirmation. The sample uses selector7 with file-independent supplied packed words, not a proof of legal selector bounds.

A later, separate predicate clears player-state+12 bit256 when player-state+208 >0 and (buttons &5) ==0. Other cases retain it. The predicates execute in this order: the first sees the initial bit256 even if the second subsequently clears it. Buttons value2 passes the release predicate, while values1/4/5 block it. No external calls occur within these gate probes.

240 fixtures vary bit256, types0/5, buttons0/1/2/4/5, packed words0/1/256/0xffffffff and health-like words-1/0/1. An independent bit oracle checks both final words, including ordering and unchanged neighboring bits.

STEP-002 — Actual clock prefix and scheduler composition (RE-422)

At53714 the graph requests trap target-101 with (35023892,0,140). This scratch-reset request is retained but not executed or composed here. The following clock prefix (53723–53789) reads requested time from frame+4 and old time through frame[+0], then:

1. Computes signed32(requested-old) and clamps the elapsed value to1–200 at global35023932.
2. Copies the requested timestamp itself, rather than old time plus clamped elapsed, into player-state+0.
3. Stores clamped elapsed at player-state+284.
4. Copies three source words from player-state+20 to35024004, and three from player-state+32 to35024016.
5. Converts elapsed to binary32, multiplies by the file-observed binary32 word981668463, and stores the rounded binary32 result at35023928.

The vector source words and frame/global pointers are supplied explicitly. The prefix writes each required scratch value before reading it in these slices; this does not recover the full scratch reset's native effects. Origin/velocity and fractional-time semantics are candidates pending later consumers and runtime evidence.

Eight probes cover negative/zero/one/200/over-200 differences and signed wrap boundaries. Even a requested time earlier than old time is copied directly while elapsed becomes1. This is a standalone prefix observation: the outer scheduler normally rejects backward input before reaching the child. Wrapped differences are modeled as signed32 arithmetic, not declared legal clock transitions.

Twenty compositions connect the scheduler's stopped child request to the evaluated clock-prefix instructions, then resume the outer loop with the resulting word memory. Final times999/1000/1001/1067/2001, flags0/8192 and fixed modes0/1 cover rejection, equality, capped gaps and multiple steps. Every child timestamp, clamped elapsed, fractional word and copied vector is independently checked, together with the complete outer schedule.

Only this prefix is composed. It uses a supplied frame pointer and seeded vector source words; scratch reset, prior input cleanup, view-angle work, physics, callbacks and subsequent child mutations are omitted. The optional scheduler child-effect interface keeps the earlier report's default supplied-clock model/output unchanged.

The shared QVM evaluator adds signed-int32 CVIF to binary32; focused boundary tests cover zero, +/-1 and both signed-int32 endpoints. No nonfinite values are introduced by this conversion. Actual runtime rounding/control-state conformance remains open.

STEP-003 — Direction flag, suppression and early mode calls (RE-423)

The separate dispatch slice starts at54022, after omitted angle/trigonometric/helper work. A negative signed forward byte sets player-state+12 bit16384. Positive forward, or zero forward with nonzero right, clears it. Zero forward/right retains the existing bit. This update occurs before the movement-byte suppression below.

The slice clears all three command movement bytes if any predicate holds:

• Player-state type at+4 is at least3 and player-state+220 bit2048 is clear.
• Player-state+220 bit16384 is set.
• Frame+232 equals2.
• Frame+240 is nonzero.

Then early dispatch follows this priority:

Condition	Recorded callee targets, in order	Continuation
Frame+232 ==2	47422,46773,42838	Return boundary54473
Otherwise type2, or player-state+220 bit2048, or frame+240 nonzero	47422,42486,53048	Return boundary54473
Otherwise type1	45461,53048	Return boundary54473
Otherwise type4	None	Return boundary54473
Remaining sampled type	None in this slice	Main-path boundary54244

All recorded calls have empty explicit argument slots here and rely on surrounding globals/state; this batch does not recover their full signatures or effects. The frame/type/bit meanings remain provisional rather than assigning physics names from numeric matches alone.

105 fixtures cover types0–5, frame+232 values0/2, frame+240 values0/1, four +220 flag combinations and signed forward/right direction cases. Tests verify exact byte suppression, flag updates, call ordering and whether the main path is reached. Later main-path weapon/collision/physics selection remains open.

Validation and remaining work

Eight independent tests cover gate ordering/packed bytes, clock writes versus clamped elapsed, evaluated-prefix scheduler composition, directional flags/suppression, exact early-dispatch requests, verified source/scratch-request evidence, CVIF boundaries and explicit model scope. Earlier reports are regenerated to protect shared-evaluator and scheduler defaults.

RE-420 remains open for full child behavior and runtime work. RE-424 must recover scratch reset and native trap effects, omitted angle/trigonometric helpers, early-dispatch callee semantics and real clock/vector mutations, remaining action/weapon/physics/collision branches, packed selectors/flags/types through producers and consumers, complete step/outer-loop composition and actual gameplay/macOS/Linux behavior before Rust/Bevy/Solari compatibility claims. Packet/entity/player/snapshot/rendering work also remains open.

Follow-up: view and position tails recovers helper53186 angle conversion, conditional basis algebra and two position tails. Native trig, omitted callee/physics effects and real composition/runtime validation remain open.

Follow-up: main routing/timer recovery continues beyond54244, evaluates53048 countdowns and records ordered main requests/six-mode priority. Selected real clock elapsed words feed timer/animation fixtures; full child/environment/physics/state remains open (RE-457–460).