qvm: server muzzle origins

docs/ASSET_PIPELINE_TODO.md

@@ -469,3 +469,6 @@ Research progress: RE-594 [report](research/QVM_SERVER_FIRE_EVENT.md); remaining
 
 
 Research progress: RE-595 [report](research/QVM_SERVER_FIRE_BASIS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-596 [report](research/QVM_SERVER_MUZZLE.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -827,3 +827,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-595 — Server firing suppression statistic and angle basis:** 289235 first rejects client6164!=0, otherwise increments statistic4116 unless entity weaponID1, then builds global forward/right/up from client angles using native sin/cos requests. [Evidence](research/QVM_SERVER_FIRE_BASIS.md).
+
+
+**RE-596 — Server muzzle origins and actual firing handoff:** 288779 uses entity+24 plus integer client viewheight and14×forward;288871 omits the forward offset. The actual289485 caller passes global basis/output pointers without native snapping. [Evidence](research/QVM_SERVER_MUZZLE.md).

docs/PROVISIONAL_TODO.md

@@ -787,3 +787,6 @@ Research progress: RE-594 [report](research/QVM_SERVER_FIRE_EVENT.md); remaining
 
 
 Research progress: RE-595 [report](research/QVM_SERVER_FIRE_BASIS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-596 [report](research/QVM_SERVER_MUZZLE.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -665,3 +665,8 @@ Actual outer31 publication reaches server151634, which writes client4140=0 and43
 ## 2026-10-20 — RE-595 Server firing suppression statistic and angle basis (separate task commit)
 
 289235 first rejects client6164!=0, otherwise increments statistic4116 unless entity weaponID1, then builds global forward/right/up from client angles using native sin/cos requests. 80 independent fixtures check suppression, ID0/1/22/28, statistic wrap, float32 pitch/yaw/roll basis formulas and actual six-native-call order/arguments. Full suite: 891 tests pass. Report regenerates byte-identically (335153 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-596 Server muzzle origins and actual firing handoff (separate task commit)
+
+288779 uses entity+24 plus integer client viewheight and14×forward;288871 omits the forward offset. The actual289485 caller passes global basis/output pointers without native snapping. 50 independent fixtures check pitched/nonunit forward, fractional/negative entity bases, viewheight boundaries, unused right/up pointers, in-place entity-base output and actual caller arguments. Full suite: 895 tests pass. Report regenerates byte-identically (159008 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

@@ -829,3 +829,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-595 Server firing suppression statistic and angle basis ([report](research/QVM_SERVER_FIRE_BASIS.md)).
+
+
+- [x] RE-596 Server muzzle origins and actual firing handoff ([report](research/QVM_SERVER_MUZZLE.md)).

docs/research/QVM_SERVER_MUZZLE.md

@@ -0,0 +1,11 @@
+# Server muzzle origins and actual firing handoff
+
+RE-596. Reproduce with `python3 scripts/analyze_qvm_server_muzzle.py`; check with `python3 scripts/test_qvm_server_muzzle.py`. The [machine report](qvm-server-muzzle.json) retains source identity and bounded fixtures.
+
+Complete288779 copies entity+24 into output, adds client164 converted to float to Z, then adds14×the supplied forward vector component-wise. Right/up arguments are unused. Complete288871 copies the same entity base and only adds viewheight. No trace, snap, normalization or other native call is present.
+
+50 fixtures deliberately keep entity+24 distinct from entity+488 and PS origin, so the position source is not inferred from familiar field names. Nonunit forward remains unnormalized. In-place output at entity+24 is explicitly covered; output/direction aliasing beyond these fixtures is not declared legal.
+
+Actual289485..289498 invokes288779 with ENTITY and global forward/right/up/muzzle pointers after the recovered angle basis. The caller output matches the independent formula. Next: map the source dispatcher to handlers without inventing their effects.
+
+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

@@ -388,3 +388,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-595: Server firing suppression statistic and angle basis](QVM_SERVER_FIRE_BASIS.md). Reproduce with `python3 scripts/analyze_qvm_server_fire_basis.py`; check with `python3 scripts/test_qvm_server_fire_basis.py`.
+
+
+[RE-596: Server muzzle origins and actual firing handoff](QVM_SERVER_MUZZLE.md). Reproduce with `python3 scripts/analyze_qvm_server_muzzle.py`; check with `python3 scripts/test_qvm_server_muzzle.py`.

scripts/analyze_qvm_server_muzzle.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Complete288779/288871 muzzle helpers and actual289485 caller handoff."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute
+from qvm_server_fire_support import seed,state,ENTITY,FORWARD,RIGHT,UP,MUZZLE
+from analyze_qvm_acceleration import PS,word
+from analyze_qvm_slide_prefix import vec
+from analyze_qvm import write_json
+LOCAL=0x7c000000
+
+def muzzle(ins,m,entry,args):
+    before=state(m);size=ins[entry]['operand'];base=LOCAL+(entry==288871)*0x1000;m=dict(m)
+    for offset,value in args.items():m[base+size+offset]=value
+    output=args[24] if entry==288779 else args[12];fw=vec(m,args[12]) if entry==288779 else None
+    m,c,r=execute(ins,entry+1,288869 if entry==288779 else 288901,m,(0,0,0),base)
+    return m,{'entry':entry,'arguments':args,'initial':before,'input_forward':fw,'output_address':output,'output':vec(m,output),'execution':r,'final':state(m)}
+
+def caller(ins,m,base):
+    m[base+88]=ENTITY
+    def child(i,m,a,c):m,r=muzzle(i,m,288779,a);return m,c,0,r
+    m,c,r=execute(ins,289485,289499,m,(0,0,0),base,{288779:child});return m,r
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for entry,fw,height,origin in itertools.product([288779,288871],[(1,0,0),(.6,0,.8),(-1,-.5,2)],[-1,0,38,127],[(10,20,30),(-.5,1.5,-2.5)]):
+        m=seed(raw,h);m[PS+164]=height
+        for j,v in enumerate(fw):m[FORWARD+4*j]=word(v)
+        for j,v in enumerate(origin):m[ENTITY+24+4*j]=word(v)
+        args={8:ENTITY,12:FORWARD,16:0,20:0,24:MUZZLE} if entry==288779 else {8:ENTITY,12:MUZZLE};rows.append(muzzle(ins,m,entry,args)[1])
+    for entry in [288779,288871]:
+        m=seed(raw,h);args={8:ENTITY,12:FORWARD,16:RIGHT,20:UP,24:ENTITY+24} if entry==288779 else {8:ENTITY,12:ENTITY+24};rows.append(muzzle(ins,m,entry,args)[1])
+    from analyze_qvm_server_fire_basis import basis,LOCAL as PARENT
+    m=seed(raw,h);m,b=basis(ins,m);m,r=caller(ins,m,PARENT)
+    write_json(Path('docs/research/qvm-server-muzzle.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'caller':{'basis':b,'execution':r,'final':state(m)},'limits':'Complete finite288779/288871 and actual caller289485..289498. No native snap/trace or assumed normalization. In-place output/entity-base fixtures explicit; other alias domains and live position semantics unverified.'})
+if __name__=='__main__':main()

scripts/test_qvm_server_muzzle.py

@@ -0,0 +1,22 @@
+import json,unittest,copy
+from pathlib import Path
+from test_qvm_ground import word,n,f
+
+def output(p):
+    a=p['initial'];v=list(map(n,a['entity_base']));v[2]=f(v[2]+f(a['viewheight']))
+    if p['entry']==288779:v=[f(x+f(n(d)*14)) for x,d in zip(v,p['input_forward'])]
+    return list(map(word,v))
+class ServerMuzzleTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-server-muzzle.json').read_text())
+    def test_all_exact_origin_height_and_forward_offsets(self):
+        self.assertEqual(len(self.r['probes']),50)
+        for p in self.r['probes']:self.assertEqual(p['output'],output(p))
+    def test_only_output_mutation_no_native_or_child(self):
+        for p in self.r['probes']:
+            a=copy.deepcopy(p['initial']);a['muzzle' if p['output_address']==36477712 else 'entity_base']=p['output'];self.assertEqual(p['final'],a);self.assertEqual(p['execution']['calls'],[])
+    def test_entity_base_is_distinct_from_live_origin_and_ps_origin(self):
+        for p in self.r['probes']:self.assertEqual(p['initial']['entity_origin'],p['final']['entity_origin']);self.assertNotEqual(p['initial']['entity_base'],p['initial']['entity_origin'])
+    def test_actual_server_caller_child_arguments_and_output(self):
+        p=self.r['caller'];self.assertEqual([c['target'] for c in p['execution']['calls']],[288779]);child=p['execution']['children'][0]['effect'];self.assertEqual(child['arguments'],{'8':589824,'12':36477748,'16':36477736,'20':36477724,'24':36477712});self.assertEqual(p['final']['muzzle'],output(child))
+if __name__=='__main__':unittest.main()