qvm: water transition events

docs/ASSET_PIPELINE_TODO.md

@@ -373,3 +373,6 @@ Research progress: RE-558 [report](research/QVM_WALKING_MODE.md); remaining nati
 
 
 Research progress: RE-560 [report](research/QVM_FREEFLIGHT.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-561 [report](research/QVM_WATER_EVENTS.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -731,3 +731,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-560 — Complete bounded freeflight movement:** 42486 composes friction, command scale multiplied by1.5, a three-axis wish, normalization and coefficient8 acceleration, then integrates position only if any resulting absolute velocity component exceeds1. [Evidence](research/QVM_FREEFLIGHT.md).
+
+
+**RE-561 — Water transition event matrix and queue composition:** 48716 independently emits entry100/101, exit6, full-submersion7 and resurfacing8. Entry101 requires vertical velocity strictly below−500;0→3 and3→0 each enqueue two ordered events. [Evidence](research/QVM_WATER_EVENTS.md).

docs/PROVISIONAL_TODO.md

@@ -685,3 +685,6 @@ Research progress: RE-558 [report](research/QVM_WALKING_MODE.md); remaining nati
 
 
 Research progress: RE-560 [report](research/QVM_FREEFLIGHT.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-561 [report](research/QVM_WATER_EVENTS.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -501,3 +501,8 @@ RE-549–558 each has its own code/tests/report/documentation commit. All759 tes
 ## 2026-10-19 — RE-560 Complete bounded freeflight movement (separate task commit)
 
 42486 composes friction, command scale multiplied by1.5, a three-axis wish, normalization and coefficient8 acceleration, then integrates position only if any resulting absolute velocity component exceeds1. 64 finite fixtures independently check friction, scaling, wish geometry, normalization, acceleration, strict integration threshold and untouched state. Full suite: 763 tests pass. Report regenerates byte-identically (453652 bytes). Storage/filter, links and whitespace checks pass. No assets/Rust runtime/shared VM evaluator changed; native/reference/legal/full platform scope remains open.
+
+
+## 2026-10-19 — RE-561 Water transition event matrix and queue composition (separate task commit)
+
+48716 independently emits entry100/101, exit6, full-submersion7 and resurfacing8. Entry101 requires vertical velocity strictly below−500;0→3 and3→0 each enqueue two ordered events. 144 fixtures cover all16 legal level pairs, three velocity boundaries and sequence0/1/unsigned wrap; independent queue and mutation oracles pass. Full suite: 767 tests pass. Report regenerates byte-identically (588597 bytes). Storage/filter, links and whitespace checks pass. No assets/Rust runtime/shared VM evaluator changed; native/reference/legal/full platform scope remains open.

docs/REVERSE_ENGINEERING_TODO.md

@@ -725,3 +725,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-560 Complete bounded freeflight movement ([report](research/QVM_FREEFLIGHT.md)).
+
+
+- [x] RE-561 Water transition event matrix and queue composition ([report](research/QVM_WATER_EVENTS.md)).

docs/research/QVM_WATER_EVENTS.md

@@ -0,0 +1,11 @@
+# Water transition event matrix and queue composition
+
+RE-561. Reproduce with `python3 scripts/analyze_qvm_water_events.py`; check with `python3 scripts/test_qvm_water_events.py`. The [machine report](qvm-water-events.json) retains source identity and bounded fixtures.
+
+The whole48716 consumer is interpreted through48796 with actual39238→29913 queue children. Four independent tests of old/current level execute in source order: zero to nonzero emits101 below−500 else100; nonzero to zero emits6; non3 to3 emits7;3 to non3 emits8. Consequently0→3 queues entry then7, and3→0 queues6 then8. Neither old level nor velocity is written by this body.
+
+The recovered two-slot ring queue writes parameter0, indexes the prior sequence low bit, and increments the32-bit sequence, including unsigned wrap.144 finite probes cover levels0..3 and velocity−501/−500/0. Shared suffix fixtures expose weapon/animation/resource state and use explicitly supplied321-duration animation records for later consumers; water events do not read those records.
+
+Remaining: link actual old/current contents sampling and this consumer into the main tick, resolve event sound assets and implement playback. Numeric event interpretation beyond the observed level predicates remains provisional.
+
+No original executable/full QVM/native collision/physics/rendering executes. Native responses and legal input domains are supplied or unverified where stated; full runtime/macOS/Linux Rust/Bevy/Solari gameplay remains open.

docs/research/README.md

@@ -286,3 +286,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-560: Complete bounded freeflight movement](QVM_FREEFLIGHT.md). Reproduce with `python3 scripts/analyze_qvm_freeflight.py`; check with `python3 scripts/test_qvm_freeflight.py`.
+
+
+[RE-561: Water transition event matrix and queue composition](QVM_WATER_EVENTS.md). Reproduce with `python3 scripts/analyze_qvm_water_events.py`; check with `python3 scripts/test_qvm_water_events.py`.

scripts/analyze_qvm_water_events.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Complete48716 transition events with actual two-slot queue writes."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute
+from qvm_suffix_support import seed,state,handlers
+from analyze_qvm_acceleration import PS,FRAME,word
+from analyze_qvm import write_json
+LOCAL=0x6b000000
+
+def water_events(ins,m,cmd=(0,0,0)):
+    initial=state(m);old=m[35024028];level=m[FRAME+212];vz=m[PS+40]&0xffffffff
+    m,c,r=execute(ins,48717,48796,m,cmd,LOCAL,handlers())
+    return m,{'old_level':old,'level':level,'vertical_velocity':vz,'initial':initial,'execution':r,'final':state(m)}
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for old,level,vz,seq in itertools.product(range(4),range(4),[-501,-500,0],[0,1,0xffffffff]):
+        m=seed(raw,h);m.update({35024028:old,FRAME+212:level,PS+40:word(vz),PS+108:seq});rows.append(water_events(ins,m)[1])
+    write_json(Path('docs/research/qvm-water-events.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Complete bounded48716 plus recovered39238/29913 queues. Water levels/velocity/sequence are supplied; contents classification and actual audio playback remain unverified.'})
+if __name__=='__main__':main()

scripts/qvm_suffix_support.py

@@ -0,0 +1,25 @@
+"""Explicit finite state and actual recovered animation/event suffix children."""
+from qvm_research_support import memory
+from analyze_qvm_acceleration import PS,FRAME
+from analyze_qvm_animation_contacts import evaluate,TABLE
+from analyze_qvm_landing import event,queue
+from analyze_bsp_references import trace_fields
+FIELDS={'bob':8,'flags':12,'weapon_timer':44,'ground':68,'leg_timer':72,'legs':76,'torso_timer':80,'torso':84,'entity_flags':104,'slot':144,'weapon_state':148,'health':208,'state220':220,'resource':188,'resource_timer':196}
+
+def state(m):
+    return {**{k:m[PS+o]&0xffffffff for k,o in FIELDS.items()},'packed':m[PS+312+4*m[PS+144]]&0xffffffff,'inventory':[m[PS+376+4*j]&0xffffffff for j in range(16)],'queue':queue(m),'speed':m.get(FRAME+216,0)&0xffffffff,'mode_changed':m.get(FRAME+252,0),'old_mode':m.get(FRAME+256,0)}
+
+def seed(raw,h,cmd=(0,0,0)):
+    m=memory(raw,h,cmd);m.update({PS+220:0,PS+76:41,PS+8:0,FRAME+248:0,FRAME+252:0,FRAME+256:0,FRAME+216:0,35024028:0})
+    for request in range(128):m[TABLE+request*32+28]=321
+    return m
+
+def handlers():
+    def animation(entry):
+        def apply(i,m,a,c):
+            before=state(m);r=evaluate(i,entry,a[8],m);return r['memory'],c,0,{'entry':entry,'request':a[8],'before':before,'after':state(r['memory']),'calls':r['calls'],'children':r['children'],**trace_fields(r,False)}
+        return apply
+    def queued(entry):
+        def apply(i,m,a,c):m,r=event(i,m,entry,a);return m,c,0,r
+        return apply
+    return {**{e:animation(e) for e in [39338,39383,39439,39482,39525,39552]},**{e:queued(e) for e in [39238,45887,29913]}}

scripts/test_qvm_water_events.py

@@ -0,0 +1,33 @@
+import json,unittest,copy
+from pathlib import Path
+from test_qvm_ground import n
+
+def expected(p):
+    old,level=p['old_level'],p['level'];events=[]
+    if old==0 and level!=0:events.append(101 if n(p['vertical_velocity'])< -500 else 100)
+    if old!=0 and level==0:events.append(6)
+    if old!=3 and level==3:events.append(7)
+    if old==3 and level!=3:events.append(8)
+    return events
+
+def enqueue(q,events):
+    q=copy.deepcopy(q)
+    for ev in events:
+        slot=q['sequence']&1;q['events'][slot]=ev;q['parameters'][slot]=0;q['sequence']=(q['sequence']+1)&0xffffffff
+    return q
+class WaterEventsTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-water-events.json').read_text())
+    def test_transition_matrix_and_strict_speed(self):
+        self.assertEqual(len(self.r['probes']),144)
+        for p in self.r['probes']:self.assertEqual([c['args']['8'] for c in p['execution']['calls']],expected(p))
+    def test_actual_queue_order_wrap_and_parameters(self):
+        for p in self.r['probes']:self.assertEqual(p['final']['queue'],enqueue(p['initial']['queue'],expected(p)))
+    def test_double_transition(self):
+        for p in self.r['probes']:
+            if (p['old_level'],p['level'])==(0,3):self.assertEqual(expected(p)[-1],7);self.assertEqual(len(p['execution']['children']),2)
+            if (p['old_level'],p['level'])==(3,0):self.assertEqual(expected(p),[6,8])
+    def test_only_event_state_mutates(self):
+        for p in self.r['probes']:
+            a=copy.deepcopy(p['initial']);a['queue']=p['final']['queue'];self.assertEqual(a,p['final']);self.assertTrue(all(x['call']['target']==39238 for x in p['execution']['children']))
+if __name__=='__main__':unittest.main()