qvm: firing input gates

docs/ASSET_PIPELINE_TODO.md

@@ -430,3 +430,6 @@ Research progress: RE-579 [report](research/QVM_WEAPON_PHASES.md); remaining nat
 
 
 Research progress: RE-580 [report](research/QVM_WEAPON_RETURN_CHAINS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-582 [report](research/QVM_FIRE_GATE.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -788,3 +788,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-580 — Pre-firing weapon return chains and actual main suffix handoff:** Recovered50746 branches now compose through51801, preserving the pre-switch mode local; actual53046 returns resume main torso/locomotion/water calls while51802 paths keep the caller suspended. [Evidence](research/QVM_WEAPON_RETURN_CHAINS.md).
+
+
+**RE-582 — Firing charge hold release and ordinary input gate:** 51802..52084 uses mode flag8 to availability-gate a state32/64 charge latch and event1, handles requested-ID exceptions11/12, and otherwise lets nonzero burst counters bypass absent button1. [Evidence](research/QVM_FIRE_GATE.md).

docs/PROVISIONAL_TODO.md

@@ -746,3 +746,6 @@ The [RE-571–580 weapon batch](research/QVM_WEAPON_BATCH.md) closes bounded loo
 
 
 Research progress: RE-580 [report](research/QVM_WEAPON_RETURN_CHAINS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-582 [report](research/QVM_FIRE_GATE.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -598,3 +598,8 @@ Actual54444 reload/interaction order exposes timer interference before the weapo
 Recovered50746 branches now compose through51801, preserving the pre-switch mode local; actual53046 returns resume main torso/locomotion/water calls while51802 paths keep the caller suspended. 16 independent source-order scenarios check every reload/interaction/prefix/selection/guard/ready/ammo/phase handoff, full final state, suspension versus resume and old-mode-local preservation. Full suite: 839 tests pass. Report regenerates byte-identically (1198369 bytes). Storage/filter, links and whitespace checks pass. No assets/Rust runtime/shared VM evaluator changed; native/reference/legal/full platform scope remains open.
 
 RE-580 additional regression: all19 reports from RE-560–569 and RE-571–579 regenerate byte-identically after the explicit-byte-input and optional caller-memory/local-preservation additions. The new composition keeps the parent suspended at51802 rather than assuming a firing-body return.
+
+
+## 2026-10-20 — RE-582 Firing charge hold release and ordinary input gate (separate task commit)
+
+51802..52084 uses mode flag8 to availability-gate a state32/64 charge latch and event1, handles requested-ID exceptions11/12, and otherwise lets nonzero burst counters bypass absent button1. 203 independent fixtures check charge start/hold/release/cancel, flags4 availability, command mismatch exceptions and signed nonzero counters without altering ammo or published request fields. Full suite: 843 tests pass. Report regenerates byte-identically (1209597 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

@@ -787,3 +787,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-580 Pre-firing weapon return chains and actual main suffix handoff ([report](research/QVM_WEAPON_RETURN_CHAINS.md)).
+
+
+- [x] RE-582 Firing charge hold release and ordinary input gate ([report](research/QVM_FIRE_GATE.md)).

docs/research/QVM_FIRE_GATE.md

@@ -0,0 +1,11 @@
+# Firing charge hold release and ordinary input gate
+
+RE-582. Reproduce with `python3 scripts/analyze_qvm_fire_gate.py`; check with `python3 scripts/test_qvm_fire_gate.py`. The [machine report](qvm-fire-gate.json) retains source identity and bounded fixtures.
+
+Complete gate51802..52084 stops at52085 or actual return53046. Mode flag8 calls actual50309. Unavailable resets weapon timer/state0. A matching held button1 (IDs11/12 must match command weapon) without state64 sets32/64, loads weapon record4056 timer and emits1. A latched hold returns while32 remains set; when32 clears it clears64 and proceeds. Release can clear64 and proceed, but an unlatched release resets state/timer and exits. ID11 has an additional held-command-mismatch cancellation; ID12 follows the observed release route instead.
+
+Without flag8, a zero PS204 counter requires button1 and sets32; any nonzero counter bypasses this gate, including explicit synthetic negative values. Availability50309 reads the packed mode, while this parent uses its preserved local mode. Reports distinguish both flags.203 finite fixtures exercise the literal predicates, not inferred legal gameplay inputs.
+
+No magazine debit, actual shot, projectile/hitscan or native event dispatch occurs in this slice. The next tasks follow availability failure and ammo debit before firing-pose/request publication.
+
+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

@@ -347,3 +347,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-580: Pre-firing weapon return chains and actual main suffix handoff](QVM_WEAPON_RETURN_CHAINS.md). Reproduce with `python3 scripts/analyze_qvm_weapon_return_chains.py`; check with `python3 scripts/test_qvm_weapon_return_chains.py`.
+
+
+[RE-582: Firing charge hold release and ordinary input gate](QVM_FIRE_GATE.md). Reproduce with `python3 scripts/analyze_qvm_fire_gate.py`; check with `python3 scripts/test_qvm_fire_gate.py`.

scripts/analyze_qvm_fire_gate.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""51802..52084 charge/hold/release versus ordinary firing gate."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source
+from qvm_firing_support import seed,segment
+from analyze_qvm_acceleration import PS,FRAME
+from analyze_qvm import write_json
+
+def gate(ins,m,cmd=(0,0,0),preserve_locals=False):return segment(ins,m,51802,[52085],cmd,preserve_locals)
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for ident,flags,mag,special,button in itertools.product([1,11,12,22],[0,8,12],[0,1],[0,64,32,96],[0,1]):
+        m=seed(raw,h,ident,mag);m.update({4244+432*ident+4:flags,PS+220:special,FRAME+20:button});rows.append(gate(ins,m)[1])
+    for ident,button,state in itertools.product([11,12],[0,1],[0,64]):
+        m=seed(raw,h,ident,1);m.update({4244+432*ident+4:8,PS+220:state,FRAME+20:button,FRAME+24:22});rows.append(gate(ins,m)[1])
+    for count in [-1,1,2]:
+        m=seed(raw,h);m.update({4244+432*22+4:0,PS+204:count,FRAME+20:0});rows.append(gate(ins,m)[1])
+    write_json(Path('docs/research/qvm-fire-gate.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Finite51802..52084; actual50309/event children, supplied mode flags and entry state. Stops52085 or53046; charge naming provisional and no actual firing/native dispatch.'})
+if __name__=='__main__':main()

scripts/qvm_firing_support.py

@@ -0,0 +1,28 @@
+"""Finite firing segment fixtures; parent locals and published request are explicit."""
+from qvm_research_support import constants,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_packed_controls import control
+from analyze_qvm_acceleration import PS,FRAME
+
+def seed(raw,h,ident=22,mag=2,mode=0):
+    m=weapon_seed(raw,h,desired=ident);m.update(constants(raw,h,range(21316,21348,4)));m.update({PS+312:ident|(mag<<8)|(mode<<16)|(3<<24),PS+204:0,PS+188:0,PS+196:0,PS+216:777,FRAME+260:91,FRAME+264:92,FRAME+20:1,FRAME+36:0,PS+68:8});return m
+
+def state(m):return {**weapon_state(m),'field216':m[PS+216]&0xffffffff,'request260':m[FRAME+260],'request264':m[FRAME+264]}
+
+def config(m):
+    ident=m[LOCAL+12];mode=m[LOCAL+16];ptr=4244+432*ident+52*mode
+    packed=m[PS+312+4*m[PS+144]];live=4244+432*(packed&255)+52*((packed>>16)&255)
+    return {'packed_flags':m[live+4]&0xffffffff,'charge_timer':m[4056+432*ident]&0xffffffff,**{k:m[ptr+o]&0xffffffff for k,o in [('flags',4),('delay',8),('resource_delay',24),('burst_delay',44),('burst_count',48)]},'capacity':m[4052+432*ident]&0xffffffff,'class':m[4032+432*ident],'tag':m[4196+432*ident]}
+
+def fire_handlers():
+    hs=handlers()
+    def available(i,m,a,c):m,r=control(i,m,50309,c);return m,c,r['execution']['return'],r
+    hs[50309]=available;return hs
+
+def segment(ins,m,start,boundaries,cmd=(0,0,0),preserve_locals=False):
+    if not preserve_locals:m[LOCAL+12]=m[PS+312+4*m[PS+144]]&255;m[LOCAL+16]=(m[PS+312+4*m[PS+144]]>>16)&255
+    before=state(m);cfg=config(m);lid=m[LOCAL+12];mode=m[LOCAL+16]
+    m,c,r=execute(ins,start,53046,m,cmd,LOCAL,fire_handlers(),boundaries=boundaries,byte_inputs={FRAME+24:m[FRAME+24]&255})
+    return m,{'initial':before,'buttons':m[FRAME+20],'kind':m[PS+4],'local_id':lid,'local_mode':mode,'config':cfg,'execution':r,'final':state(m)}

scripts/test_qvm_fire_gate.py

@@ -0,0 +1,38 @@
+import json,unittest,copy
+from pathlib import Path
+from test_qvm_torso_selector import signed
+from test_qvm_water_events import enqueue
+
+def gate_state(p):
+    a=copy.deepcopy(p['initial']);flags=p['config']['flags'];pressed=bool(p['buttons']&1);ident=p['local_id'];stop=52085
+    if flags&8:
+        available=bool((a['packed']>>8)&255 or p['config']['packed_flags']&4)
+        if not available:a['weapon_timer']=a['weapon_state']=0;return a,53046
+        if pressed and (ident not in [11,12] or ident==a['command_weapon']):
+            if not a['state220']&64:a['state220']|=96;a['weapon_timer']=p['config']['charge_timer'];a['queue']=enqueue(a['queue'],[1]);return a,53046
+            if a['state220']&32:return a,53046
+            a['state220']&=~64
+        elif not a['state220']&64 or (ident==11 and pressed and ident!=a['command_weapon']):a['weapon_timer']=a['weapon_state']=0;return a,53046
+        else:a['state220']&=~64
+    elif a['counter204']==0:
+        if not pressed:a['weapon_timer']=a['weapon_state']=0;return a,53046
+        a['state220']|=32
+    return a,stop
+class FireGateTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-fire-gate.json').read_text())
+    def test_complete_gate_state(self):
+        self.assertEqual(len(self.r['probes']),203)
+        for p in self.r['probes']:a,stop=gate_state(p);self.assertEqual(p['final'],a);self.assertEqual(p['execution']['stop'],stop)
+    def test_actual_availability_and_event_calls(self):
+        for p in self.r['probes']:
+            expected=[50309] if p['config']['flags']&8 else []
+            if p['final']['queue']!=p['initial']['queue']:expected.append(39238)
+            self.assertEqual([c['target'] for c in p['execution']['calls']],expected)
+    def test_ordinary_nonzero_counter_bypasses_button_release(self):
+        for p in self.r['probes']:
+            if not p['config']['flags']&8 and p['initial']['counter204']!=0:self.assertEqual(p['execution']['stop'],52085)
+    def test_magazine_and_request_fields_untouched(self):
+        for p in self.r['probes']:
+            for k in ['weapons','packed','request260','request264','resource']:self.assertEqual(p['initial'][k],p['final'][k])
+if __name__=='__main__':unittest.main()