qvm: weapon mode prefix

docs/ASSET_PIPELINE_TODO.md

@@ -388,3 +388,6 @@ Research progress: RE-564 [report](research/QVM_INTERACTION_REQUEST.md); remaini
 
 
 Research progress: RE-565 [report](research/QVM_PACKED_CONTROLS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-566 [report](research/QVM_WEAPON_PREFIX.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -746,3 +746,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-565 — Packed mode availability edge latch and resource countdown:** 50250 edge-latches button128 into state32768/event15;50309 permits availability on mode flag4 or nonzero magazine;50397 drains with the full dt when its countdown reaches zero. [Evidence](research/QVM_PACKED_CONTROLS.md).
+
+
+**RE-566 — Mode switch and ordered weapon prefix:** 49327 cycles packed mode with release latch16 and ID-specific exceptions;50746 orders button latch, weapon timer decrement, resource countdown and mode switch before weapon selection. [Evidence](research/QVM_WEAPON_PREFIX.md).

docs/PROVISIONAL_TODO.md

@@ -700,3 +700,6 @@ Research progress: RE-564 [report](research/QVM_INTERACTION_REQUEST.md); remaini
 
 
 Research progress: RE-565 [report](research/QVM_PACKED_CONTROLS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-566 [report](research/QVM_WEAPON_PREFIX.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -526,3 +526,8 @@ RE-549–558 each has its own code/tests/report/documentation commit. All759 tes
 ## 2026-10-20 — RE-565 Packed mode availability edge latch and resource countdown (separate task commit)
 
 50250 edge-latches button128 into state32768/event15;50309 permits availability on mode flag4 or nonzero magazine;50397 drains with the full dt when its countdown reaches zero. Seven chained latch ticks,30 availability probes and44 resource fixtures independently check release/rearm, queue wrap, packed addressing, signed multiplication/subtraction wrap and clamps. Full suite: 783 tests pass. Report regenerates byte-identically (191549 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-20 — RE-566 Mode switch and ordered weapon prefix (separate task commit)
+
+49327 cycles packed mode with release latch16 and ID-specific exceptions;50746 orders button latch, weapon timer decrement, resource countdown and mode switch before weapon selection. 82 mode fixtures and84 prefix fixtures independently check complete writes, source-order child state, death/flag early exits and negative timer preservation. Full suite: 787 tests pass. Report regenerates byte-identically (642934 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

@@ -740,3 +740,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-565 Packed mode availability edge latch and resource countdown ([report](research/QVM_PACKED_CONTROLS.md)).
+
+
+- [x] RE-566 Mode switch and ordered weapon prefix ([report](research/QVM_WEAPON_PREFIX.md)).

docs/research/QVM_WEAPON_PREFIX.md

@@ -0,0 +1,11 @@
+# Mode switch and ordered weapon prefix
+
+RE-566. Reproduce with `python3 scripts/analyze_qvm_weapon_prefix.py`; check with `python3 scripts/test_qvm_weapon_prefix.py`. The [machine report](qvm-weapon-prefix.json) retains source identity and bounded fixtures.
+
+Complete49327 first handles held/released state16 before any timer gate: release clears16 and returns. Otherwise positive PS44, state1024/8 or ID0 block switching. IDs11/12/13 with state32 and mode1 block. ID1 with magazine1 exits in mode0 but automatically advances a nonzero mode without requiring button8; other cases require button8. New mode=old+1, wrapping to0 if its first record word is zero. A change sets state16, loads the new mode timer+12 into PS44, replaces only packed bits16..23, sets FRAME252=1 and FRAME256=old mode.
+
+The recovered50746 prefix clears state32 when button1 is absent, then exits on PS12 bit256 or nonpositive health. Otherwise actual50250 runs, positive PS44 is reduced by full integer dt, actual50397 runs, then actual49327. A timer1 with dt16 can remain−15 at the bounded stop; no clamp has yet occurred. Tests independently compose each child using its live input and compare final state.
+
+This is deliberately a prefix: evaluation stops at50872 immediately after49327, or at the actual early exit53046. Weapon-selection48798 and the remainder through firing/reload/projectile logic are omitted, not stubbed as completed behavior. Remaining: recover those bodies, live mode initialization, complete command selection and reference runtime parity.
+
+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

@@ -301,3 +301,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-565: Packed mode availability edge latch and resource countdown](QVM_PACKED_CONTROLS.md). Reproduce with `python3 scripts/analyze_qvm_packed_controls.py`; check with `python3 scripts/test_qvm_packed_controls.py`.
+
+
+[RE-566: Mode switch and ordered weapon prefix](QVM_WEAPON_PREFIX.md). Reproduce with `python3 scripts/analyze_qvm_weapon_prefix.py`; check with `python3 scripts/test_qvm_weapon_prefix.py`.

scripts/analyze_qvm_weapon_prefix.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""49327 mode switch and50746 weapon prefix, explicitly stopping before50872."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute
+from qvm_suffix_support import seed,state,handlers,weapon_config
+from analyze_qvm_packed_controls import control
+from analyze_qvm_acceleration import PS,FRAME
+from analyze_qvm import write_json
+LOCAL=0x70000000
+MODE=LOCAL+0x1000
+
+def mode_switch(ins,m,cmd=(0,0,0)):
+    before=state(m);packed=before['packed'];ident=packed&255;mode=(packed>>16)&255;ptr=4244+432*ident;cfg={'next_enabled':m[ptr+52*(mode+1)],'next_timer':m[ptr+52*(mode+1)+12],'zero_timer':m[ptr+12]}
+    m,c,r=execute(ins,49328,49650,m,cmd,MODE)
+    return m,{'initial':before,'buttons':m[FRAME+20],'mode_config':cfg,'execution':r,'final':state(m)}
+
+def weapon_prefix(ins,m,cmd=(0,0,0)):
+    before=state(m);buttons=m[FRAME+20];dt=m[35023932]
+    def leaf(entry):
+        def apply(i,m,a,c):m,r=control(i,m,entry,c);return m,c,r['execution']['return'] or 0,r
+        return apply
+    def mode(i,m,a,c):m,r=mode_switch(i,m,c);return m,c,0,r
+    m,c,r=execute(ins,50747,53046,m,cmd,LOCAL,{50250:leaf(50250),50397:leaf(50397),49327:mode},boundaries=[50872])
+    return m,{'initial':before,'buttons':buttons,'dt':dt,'execution':r,'final':state(m)}
+
+def main():
+    q,raw,h,ins=source();modes=[];prefix=[]
+    for ident,mode,buttons,mag in itertools.product([0,1,11,12,13,22],[0,1,2],[0,8],[1,2]):
+        m=weapon_config(seed(raw,h),raw,h);m.update({PS+312:ident|(mode<<16)|(mag<<8)|(3<<24),PS+44:0,FRAME+20:buttons});modes.append(mode_switch(ins,m)[1])
+    for changes in [{PS+220:16},{PS+220:16,FRAME+20:0},{PS+220:1024},{PS+220:8},{PS+44:1},{PS+220:32,PS+312:11|(1<<16)|(2<<8)},{PS+220:32,PS+312:12|(1<<16)|(2<<8)},{PS+220:32,PS+312:13|(1<<16)|(2<<8)},{4244+432+52:1,4244+432+52+12:123},{4244+432+52:0}]:
+        m=weapon_config(seed(raw,h),raw,h);m.update({PS+312:1|(2<<8),FRAME+20:8,PS+44:0});m.update(changes);p=mode_switch(ins,m)[1];p['supplied_changes']={str(k):v for k,v in changes.items()};modes.append(p)
+    for buttons,flags,health,timer in itertools.product([0,1,8,128,136],[0,256],[0,100],[0,1,16,17]):
+        m=weapon_config(seed(raw,h),raw,h);m.update({PS+312:22|(2<<8),FRAME+20:buttons,PS+12:flags,PS+208:health,PS+44:timer,PS+220:32,PS+188:1000,PS+196:15,35023932:16,4244+432*22+28:2});prefix.append(weapon_prefix(ins,m)[1])
+    for ident,mode,mag,buttons,flags in [(11,1,2,9,32),(1,1,1,0,32),(1,0,1,8,0),(22,0,2,9,16)]:
+        m=weapon_config(seed(raw,h),raw,h);m.update({PS+312:ident|(mode<<16)|(mag<<8),FRAME+20:buttons,PS+220:flags,PS+44:0});prefix.append(weapon_prefix(ins,m)[1])
+    write_json(Path('docs/research/qvm-weapon-prefix.json'),{'source':q['source'],'sha256':q['sha256'],'mode_switch':modes,'prefix':prefix,'limits':'49327 complete;50746 only50747..50871 or actual early exit53046. Weapon selection48798 and all subsequent firing/reload/projectile behavior intentionally omitted. No full weapon simulation/live mode legality.'})
+if __name__=='__main__':main()

scripts/test_qvm_weapon_prefix.py

@@ -0,0 +1,41 @@
+import json,unittest,copy
+from pathlib import Path
+from test_qvm_torso_selector import signed
+from test_qvm_packed_controls import resource_state,i32
+from test_qvm_water_events import enqueue
+
+def mode_state(p):
+    a=copy.deepcopy(p['initial']);flags=a['state220'];buttons=p['buttons'];packed=a['packed'];ident=packed&255;mode=(packed>>16)&255;mag=(packed>>8)&255
+    if flags&16:
+        if not buttons&8:a['state220']&=~16
+        return a
+    if signed(a['weapon_timer'])>0 or flags&(1024|8) or ident==0:return a
+    if ident in [11,12,13] and flags&32 and mode==1:return a
+    if ident==1 and mag==1:
+        if mode==0:return a
+    elif not buttons&8:return a
+    new=mode+1 if p['mode_config']['next_enabled'] else 0
+    if new==mode:return a
+    a['state220']|=16;a['weapon_timer']=p['mode_config']['next_timer'] if new else p['mode_config']['zero_timer'];a['packed']=(packed&~0xff0000)|((new&255)<<16);a['mode_changed']=1;a['old_mode']=mode;return a
+class WeaponPrefixTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-weapon-prefix.json').read_text())
+    def test_complete_mode_gates_and_exact_writes(self):
+        self.assertEqual(len(self.r['mode_switch']),82)
+        for p in self.r['mode_switch']:self.assertEqual(p['final'],mode_state(p));self.assertEqual(p['execution']['calls'],[])
+    def test_prefix_order_and_early_exit(self):
+        self.assertEqual(len(self.r['prefix']),84)
+        for p in self.r['prefix']:
+            live=not p['initial']['flags']&256 and signed(p['initial']['health'])>0;self.assertEqual([c['target'] for c in p['execution']['calls']],[50250,50397,49327] if live else []);self.assertEqual(p['execution']['stop'],50872 if live else 53046)
+    def test_live_child_composition_and_exact_final(self):
+        for p in self.r['prefix']:
+            a=copy.deepcopy(p['initial']);buttons=p['buttons']
+            if not buttons&1:a['state220']&=~32
+            if not a['flags']&256 and signed(a['health'])>0:
+                edge,resource,mode=[x['effect'] for x in p['execution']['children']];self.assertEqual(edge['initial'],a);pressed=bool(buttons&128);event=pressed and not a['state220']&32768;a['state220']=(a['state220']|32768) if pressed else a['state220']&~32768;a['queue']=enqueue(a['queue'],[15] if event else []);self.assertEqual(edge['final'],a)
+                if signed(a['weapon_timer'])>0:a['weapon_timer']=i32(signed(a['weapon_timer'])-p['dt'])&0xffffffff
+                self.assertEqual(resource['initial'],a);a=resource_state(resource);self.assertEqual(resource['final'],a);self.assertEqual(mode['initial'],a);a=mode_state(mode)
+            self.assertEqual(p['final'],a)
+    def test_negative_timer_survives_prefix_and_scope(self):
+        self.assertTrue(any(p['initial']['weapon_timer']==1 and signed(p['final']['weapon_timer'])==-15 for p in self.r['prefix']));self.assertIn('Weapon selection48798',self.r['limits']);self.assertTrue(all(48798 not in [x['target'] for x in p['execution']['calls']] for p in self.r['prefix']))
+if __name__=='__main__':unittest.main()