qvm: weapon lowering and raising

docs/ASSET_PIPELINE_TODO.md

@@ -424,3 +424,6 @@ Research progress: RE-577 [report](research/QVM_WEAPON_READY.md); remaining nati
 
 
 Research progress: RE-578 [report](research/QVM_RELOAD_COMPLETE.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-579 [report](research/QVM_WEAPON_PHASES.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -782,3 +782,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-578 — Reload completion packed ammo transfer and re-entry:** 51365..51632 increments the magazine byte when record flags16 is set, otherwise replaces it with capacity; both decrement reserve modulo256, reset counter204, clear state8 and call49652(argument0). [Evidence](research/QVM_RELOAD_COMPLETE.md).
+
+
+**RE-579 — Weapon lowering raising and frame gates:** 51633..51801 completes state2 via49028, resets state1 to0 and selects a separate class-based torso table, then gates other states on FRAME232 and FRAME36 before firing entry51802. [Evidence](research/QVM_WEAPON_PHASES.md).

docs/PROVISIONAL_TODO.md

@@ -738,3 +738,6 @@ Research progress: RE-577 [report](research/QVM_WEAPON_READY.md); remaining nati
 
 
 Research progress: RE-578 [report](research/QVM_RELOAD_COMPLETE.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-579 [report](research/QVM_WEAPON_PHASES.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -586,3 +586,8 @@ Actual54444 reload/interaction order exposes timer interference before the weapo
 ## 2026-10-20 — RE-578 Reload completion packed ammo transfer and re-entry (separate task commit)
 
 51365..51632 increments the magazine byte when record flags16 is set, otherwise replaces it with capacity; both decrement reserve modulo256, reset counter204, clear state8 and call49652(argument0). 115 independent probes check increment/replacement, full/partial magazines, reserve0/1/2 wrap, preserved ID/mode/unselected words and live reload re-entry gates. Full suite: 831 tests pass. Report regenerates byte-identically (878739 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-579 Weapon lowering raising and frame gates (separate task commit)
+
+51633..51801 completes state2 via49028, resets state1 to0 and selects a separate class-based torso table, then gates other states on FRAME232 and FRAME36 before firing entry51802. 87 fixtures independently check completion fallback and state handoff, all classes−1..8, button priority, animation timer/type guards and both frame gates. Full suite: 835 tests pass. Report regenerates byte-identically (796730 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

@@ -778,3 +778,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-578 Reload completion packed ammo transfer and re-entry ([report](research/QVM_RELOAD_COMPLETE.md)).
+
+
+- [x] RE-579 Weapon lowering raising and frame gates ([report](research/QVM_WEAPON_PHASES.md)).

docs/research/QVM_WEAPON_PHASES.md

@@ -0,0 +1,11 @@
+# Weapon lowering raising and frame gates
+
+RE-579. Reproduce with `python3 scripts/analyze_qvm_weapon_phases.py`; check with `python3 scripts/test_qvm_weapon_phases.py`. The [machine report](qvm-weapon-phases.json) retains source identity and bounded fixtures.
+
+State2 calls actual49028 and exits. State1 resets PS148 to0, then button8192/16384 requests torso50; otherwise initialized jump table21284..21312 maps classes0/1/5/7 to67,2 to66,3 to78,4 to72 and6 to65; out-of-range defaults67. Unlike49117's idle torso selector, this table does not inspect tag22/25. Actual39482 applies timer/type/toggle guards; phase completion itself still sets state0 when animation is blocked.
+
+Other weapon states reach a pair of frame-word gates: nonzero FRAME232 or FRAME36 exits, otherwise51802 is reached. These are movement-frame words, distinct from same-offset player-state fields; their gameplay interpretation remains open.87 fixtures include actual49028 child effects and numeric command/fallback lookup.
+
+Standalone phase probes intentionally do not run prior positive-timer guards. Full parent composition must preserve those gates and existing parent locals before reaching this slice. Remaining: compose recovered pre-firing parent paths, resume main suffix only on proven returns, and recover mode-specific51802+ firing/availability logic.
+
+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

@@ -339,3 +339,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-578: Reload completion packed ammo transfer and re-entry](QVM_RELOAD_COMPLETE.md). Reproduce with `python3 scripts/analyze_qvm_reload_complete.py`; check with `python3 scripts/test_qvm_reload_complete.py`.
+
+
+[RE-579: Weapon lowering raising and frame gates](QVM_WEAPON_PHASES.md). Reproduce with `python3 scripts/analyze_qvm_weapon_phases.py`; check with `python3 scripts/test_qvm_weapon_phases.py`.

scripts/analyze_qvm_weapon_phases.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""51633..51801 lowering/raising completion and two frame-field gates."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute
+from qvm_weapon_support import weapon_seed,weapon_state
+from qvm_suffix_support import handlers
+from analyze_qvm_weapon_prefix import LOCAL
+from analyze_qvm_weapon_complete import complete
+from analyze_qvm_acceleration import PS,FRAME
+from analyze_qvm import write_json
+
+def phases(ins,m,cmd=(0,0,0)):
+    m.setdefault(FRAME+36,0);before=weapon_state(m);klass=m[4032+432*(before['packed']&255)];f36=m[FRAME+36];hs=handlers()
+    def completion(i,m,a,c):m,r=complete(i,m,c);return m,c,0,r
+    hs[49028]=completion;m,c,r=execute(ins,51633,53046,m,cmd,LOCAL,hs,boundaries=[51802])
+    return m,{'initial':before,'buttons':m[FRAME+20],'kind':m[PS+4],'class':klass,'frame36':f36,'execution':r,'final':weapon_state(m)}
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for desired,timer,kind in itertools.product([1,22,255],[0,-1,100],[0,3]):
+        m=weapon_seed(raw,h,desired=desired);m.update({PS+312:22,PS+316:1,PS+148:2,PS+44:timer,PS+4:kind,FRAME+20:0});rows.append(phases(ins,m)[1])
+    for klass,buttons,tt in itertools.product(range(-1,9),[0,8192,16384],[0,1]):
+        m=weapon_seed(raw,h);m.update({PS+312:22,PS+148:1,4032+432*22:klass,FRAME+20:buttons,PS+80:tt});rows.append(phases(ins,m)[1])
+    for ws,a,b in itertools.product([0,3],[0,1],[0,1]):
+        m=weapon_seed(raw,h);m.update({PS+312:22,PS+148:ws,FRAME+232:a,FRAME+36:b});rows.append(phases(ins,m)[1])
+    m=weapon_seed(raw,h);m.update({PS+312:22,PS+148:1,PS+4:3});rows.append(phases(ins,m)[1])
+    table={str(a):weapon_seed(raw,h)[a] for a in range(21284,21316,4)}
+    write_json(Path('docs/research/qvm-weapon-phases.json'),{'source':q['source'],'sha256':q['sha256'],'jump_table':table,'probes':rows,'limits':'Finite51633..51801, actual49028/39482 children and initialized class table. Standalone entry may violate earlier timer gates; type/phase/frame legality remains open. Stops51802 before mode-specific firing.'})
+if __name__=='__main__':main()

scripts/test_qvm_weapon_phases.py

@@ -0,0 +1,33 @@
+import json,unittest,copy
+from pathlib import Path
+from test_qvm_weapon_complete import completion_state
+from test_qvm_torso_selector import signed
+
+def phase_request(p):
+    if p['initial']['weapon_state']!=1:return None
+    if p['buttons']&(8192|16384):return 50
+    return {0:67,1:67,2:66,3:78,4:72,5:67,6:65,7:67}.get(p['class'],67)
+
+def phase_state(p):
+    a=copy.deepcopy(p['initial']);stop=53046
+    if a['weapon_state']==2:return completion_state(p['execution']['children'][0]['effect']),stop
+    if a['weapon_state']==1:
+        a['weapon_state']=0;r=phase_request(p)
+        if p['kind']<3 and signed(a['torso_timer'])<=0 and a['torso']!=r and a['torso']&~128!=r:a['torso']=((a['torso']&128)^128)|r
+    elif not a['frame232'] and not p['frame36']:stop=51802
+    return a,stop
+class WeaponPhasesTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-weapon-phases.json').read_text())
+    def test_complete_exact_phase_and_frame_state(self):
+        self.assertEqual(len(self.r['probes']),87)
+        for p in self.r['probes']:a,stop=phase_state(p);self.assertEqual(p['final'],a);self.assertEqual(p['execution']['stop'],stop)
+    def test_source_jump_table_and_no_tag_exception(self):self.assertEqual(list(self.r['jump_table'].values()),[51733,51740,51747,51754,51761,51733,51768,51775]);self.assertTrue(any(p['class']==4 and phase_request(p)==72 for p in self.r['probes']))
+    def test_actual_child_dispatch_and_request(self):
+        for p in self.r['probes']:
+            ws=p['initial']['weapon_state'];self.assertEqual([c['target'] for c in p['execution']['calls']],[49028] if ws==2 else [39482] if ws==1 else [])
+            if ws==1:self.assertEqual(p['execution']['calls'][0]['args'],{'8':phase_request(p)})
+    def test_raising_sets_idle_even_if_animation_blocked(self):
+        rows=[p for p in self.r['probes'] if p['initial']['weapon_state']==1 and (p['kind']==3 or p['initial']['torso_timer']>0)];self.assertTrue(rows)
+        for p in rows:self.assertEqual(p['final']['weapon_state'],0);self.assertEqual(p['final']['torso'],p['initial']['torso'])
+if __name__=='__main__':unittest.main()