qvm: ordinary contact factor handoff

docs/ASSET_PIPELINE_TODO.md

@@ -805,3 +805,6 @@ Research progress: RE-712 [report](research/QVM_CONTACT_DISPATCH.md); remaining
 
 
 RE-703–712 batch complete: [damage factor and contact dispatch](research/QVM_DAMAGE_FACTOR_BATCH.md). Complete289594 handles original-model contact factors and wound bookkeeping;211239 is still captured. RE-702 is partially advanced and RE-713 tracks contact/event/health composition, native parity and Rust/Bevy/Solari platform work. No playable-game milestone is claimed.
+
+
+Research progress: RE-714 [report](research/QVM_CONTACT_FACTOR.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -1151,3 +1151,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 RE-703–712 batch complete: [damage factor and contact dispatch](research/QVM_DAMAGE_FACTOR_BATCH.md). Complete289594 handles original-model contact factors and wound bookkeeping;211239 is still captured. RE-702 is partially advanced and RE-713 tracks contact/event/health composition, native parity and Rust/Bevy/Solari platform work. No playable-game milestone is claimed.
+
+
+**RE-714 — Ordinary contact factor composition:** Ordinary292545 now calls complete289594, multiplies its returned float factor by100 and suppresses the scalar when the output location is zero. [Evidence](research/QVM_CONTACT_FACTOR.md).

docs/PROVISIONAL_TODO.md

@@ -1140,3 +1140,6 @@ Research progress: RE-712 [report](research/QVM_CONTACT_DISPATCH.md); remaining
 
 
 RE-703–712 batch complete: [damage factor and contact dispatch](research/QVM_DAMAGE_FACTOR_BATCH.md). Complete289594 handles original-model contact factors and wound bookkeeping;211239 is still captured. RE-702 is partially advanced and RE-713 tracks contact/event/health composition, native parity and Rust/Bevy/Solari platform work. No playable-game milestone is claimed.
+
+
+Research progress: RE-714 [report](research/QVM_CONTACT_FACTOR.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -1205,3 +1205,8 @@ Contact293373 recomputes global forward/right/up from attacker angles, calls2112
 
 
 Batch RE-703–712 closes ten independently checked research tasks in ten separate commits, advancing the Python baseline1259→1300. All ten reports regenerate byte-identically below2MiB. See the [batch overview](research/QVM_DAMAGE_FACTOR_BATCH.md) for findings, native-model boundaries and remaining work. Original assets, Rust code and the shared VM evaluator are unchanged. RE-702 remains partially open; RE-713 records the next scope.
+
+
+## 2026-10-21 — RE-714 Ordinary contact factor composition (separate task commit)
+
+Ordinary292545 now calls complete289594, multiplies its returned float factor by100 and suppresses the scalar when the output location is zero. 96 weapon/location/equipment/clock/override fixtures verify actual pointer handoff, float32 scaling and zero-location suppression. Full suite: 1304 tests pass. Report regenerates byte-identically (311243 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

@@ -1183,3 +1183,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [ ] RE-713 Compose complete contact292545 and health211239, continue shared/pellet callers, capture native parity, and integrate Rust/Bevy/Solari toward playable macOS/Linux builds. See the [next ten tasks](research/QVM_DAMAGE_FACTOR_BATCH.md#remaining-limits-and-next-ten-tasks).
+
+
+- [x] RE-714 Ordinary contact factor composition ([report](research/QVM_CONTACT_FACTOR.md)).

docs/research/QVM_CONTACT_FACTOR.md

@@ -0,0 +1,7 @@
+# Ordinary contact factor composition
+
+RE-714. Reproduce with `python3 scripts/analyze_qvm_contact_factor.py`; check with `python3 scripts/test_qvm_contact_factor.py`. The [machine report](qvm-contact-factor.json) retains source identity and bounded fixtures.
+
+Actual292675–292735 composes complete289594 using the live caller location pointer LOCAL60 and extra accumulator pointer. The fixture starts scalar/location at zero as the recovered contact prefix does. Both client-presence branches select integer100, converted to float32 for multiplication. A zero output location then forces scalar0, even when the factor child final override returns1. Child inventory executes recovered32155/32117; spawn-protection notifications are captured. Source caller/child call trees and external accumulator results are retained. Spatial buffers and full client records occupy separate ranges. No event or211239 health execution occurs.
+
+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

@@ -741,3 +741,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-703–712 batch overview and next tasks](QVM_DAMAGE_FACTOR_BATCH.md).
+
+
+[RE-714: Ordinary contact factor composition](QVM_CONTACT_FACTOR.md). Reproduce with `python3 scripts/analyze_qvm_contact_factor.py`; check with `python3 scripts/test_qvm_contact_factor.py`.

scripts/analyze_qvm_contact_factor.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+"""Actual ordinary contact to complete damage-factor child and scalar publication."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source
+from qvm_contact_support import seed,run,L
+from analyze_qvm import write_json
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for loc,w,armor,now,override in itertools.product([0,1,3,11],[3,4,24],[False,True],[3999,4000],[0,1]):
+        a=dict(location=loc,weapon=w,helmet_slot=15 if armor else -1,vest_slot=0 if armor else -1,now=now,override=override,special=False);m=seed(raw,h,**a);m[L+60]=0;m[L+56]=0;_,p=run(ins,m,292675,292833);p['input']=a;rows.append(p)
+    write_json(Path('docs/research/qvm-contact-factor.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Actual292675..292735 composed with complete289594 and actual inventory. No event/health execution. Explicit client/clock/location fixtures; native notification effects captured.'})
+if __name__=='__main__':main()

scripts/qvm_contact_support.py

@@ -0,0 +1,73 @@
+"""Separated contact fixtures and explicit recovered children; no world runtime."""
+import math
+from qvm_research_support import constants
+from qvm_trace_support import resume,captured
+from analyze_qvm_acceleration import word,number
+from analyze_qvm_contact_gates import LOCAL as L,ATTACKER,TARGET
+from analyze_qvm_direction_codec import table,encode
+from analyze_qvm_interaction_request import inventory_check
+from analyze_qvm_victim_stats import mode
+from analyze_qvm_temp_event import temp_event,record
+from qvm_server_fire_support import PROJECTILE as EVENT
+from qvm_damage_support import L as DAMAGE_LOCAL
+A_CLIENT=L+0x10000
+V_CLIENT=L+0x20000
+TRACE=L+0x30000
+CONTEXT=L+0x40000
+EXTRA=L+0x50000
+FEEDBACK_LOCAL=0x7b100000
+
+
+def seed(raw,h,**a):
+    m=constants(raw,h,list(range(3704,3768,4))+list(range(4068,4068+432*34,4))+list(range(32796,32856,4)))
+    m.update(table(raw,h))
+    for p,size in [(L,512),(DAMAGE_LOCAL,128),(ATTACKER,880),(TARGET,880),(A_CLIENT,7000),(V_CLIENT,7000),(EVENT,880),(CONTEXT,308),(TRACE,56)]:
+        for o in range(0,size,4):m[p+o]=0
+    m.update({L+132:ATTACKER,L+136:TRACE,L+140:a.get('weapon',3),L+144:CONTEXT,L+148:a.get('flag',0),L+152:EXTRA,L+48:TARGET,L+52:int(a.get('special',False)),L+56:word(a.get('scalar',35)),L+60:a.get('location',3),L+44:EVENT,ATTACKER:7,TARGET:a.get('victim_id',65),ATTACKER+520:A_CLIENT if a.get('attacker_client',True) else 0,TARGET+520:V_CLIENT if a.get('client',True) else 0,TARGET+688:a.get('damageable',1),TARGET+684:a.get('health',100),TARGET+552:a.get('entity_flags',0),TRACE+52:65,TRACE+48:a.get('surface_flags',0),TRACE+44:a.get('surface_word',99),CONTEXT+64:a.get('count',1),CONTEXT+60:a.get('part',2),CONTEXT+68:a.get('location',3),CONTEXT+84:word(a.get('distance',0)),EXTRA:word(a.get('extra',0.25)),A_CLIENT+3096:1,V_CLIENT+3096:1 if a.get('same_team',False) else 2,V_CLIENT+208:a.get('client_health',100),V_CLIENT+4140:1000,V_CLIENT+220:a.get('client_flags',8),V_CLIENT+4312:word(0),34992532:a.get('now',5000),34074804:3,34090788:a.get('mode',3),34087532:a.get('friendly_fire',0),34066516:a.get('override',0),34081316:a.get('announce',0)})
+    for slot,item in [(a.get('vest_slot',-1),17),(a.get('helmet_slot',-1),22)]:
+        if slot>=0:m[V_CLIENT+376+4*slot]=0xaa0000|item
+    for p,values in [(ATTACKER+24,a.get('attacker_origin',(3,4,0))),(TARGET+24,a.get('target_origin',(0,0,0))),(ATTACKER+60,a.get('angles',(0,0,0))),(TRACE+12,a.get('point',(1.9,-2.9,3.1))),(TRACE+24,a.get('normal',(0,0,1))),(36477748,a.get('forward',(0.3333,-0.002,1))),(36477712,a.get('muzzle',(1.25,-2.5,3.75)))]:
+        for j,v in enumerate(values):m[p+4*j]=word(v)
+    return m
+
+
+def inventory(i,m,a):
+    m,_,v,r=inventory_check(i,m,a,(0,0,0));return m,v,r
+
+
+def predicate(i,m,a):
+    m,r=mode(i,m,a[8]);return m,r['result'],r
+
+
+def factor(i,m,a):
+    for o,v in a.items():m[DAMAGE_LOCAL+84+o]=v
+    before={str(o):m[a[12]+o] for o in [684,836]};notices=[]
+    m,e=resume(i,289595,290491,m,DAMAGE_LOCAL,handlers={32155:inventory,278003:captured(278003,notices)})
+    return m,e['return'],{'execution':e,'location':m[a[24]],'extra_word':m[a[28]]&0xffffffff,'initial_target':before,'notices':notices}
+
+
+def feedback(i,m,a):
+    for o,v in a.items():m[FEEDBACK_LOCAL+28+o]=v
+    m,e=resume(i,285143,285225,m,FEEDBACK_LOCAL,handlers={33715:predicate})
+    return m,0,e
+
+
+def handlers(effects):
+    def event(i,m,a):
+        m,r=temp_event(i,m,a[8],a[12]);effects['events'].append(r);return m,EVENT,r
+    def codec(i,m,a):
+        m,r=encode(i,m,[m[a[8]+4*j] for j in range(3)],pointer=a[8]);return m,r['result'],r
+    def trig(fn):
+        def call(i,m,a):v=word(fn(number(a[8])));return m,v,{'input_word':a[8]&0xffffffff,'result_word':v,'native_math_modeled':True}
+        return call
+    def bookkeeping(i,m,a):
+        m,v,r=feedback(i,m,a);effects['feedback'].append({'arguments':a,'execution':r});return m,v,r
+    return {289594:factor,32155:inventory,33715:predicate,277695:event,60317:codec,-104:trig(math.sin),-105:trig(math.cos),-107:trig(math.sqrt),7259:captured(7259,effects['announcements']),278003:captured(278003,effects['notices']),285142:bookkeeping,211239:captured(211239,effects['damage'])}
+
+
+def run(ins,m,start,stop,boundaries=(),include_event=False):
+    effects={k:[] for k in ['events','announcements','notices','feedback','damage']}
+    m,e=resume(ins,start,stop,m,L,handlers=handlers(effects),boundaries=boundaries,limit=20000)
+    p={'scalar_word':m[L+56]&0xffffffff,'location':m[L+60],'special':m[L+52],'extra_word':m[EXTRA]&0xffffffff,'target_health':m[TARGET+684],'execution':e,'effects':effects}
+    if include_event:p['event_record']=record(m,EVENT)
+    return m,p

scripts/test_qvm_contact_factor.py

@@ -0,0 +1,20 @@
+import json,unittest
+from pathlib import Path
+from test_qvm_ground import word,n,f
+class ContactFactorTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.ps=json.loads(Path('docs/research/qvm-contact-factor.json').read_text())['probes']
+    def test_actual_factor_return_scaled_in_float32(self):
+        for p in self.ps:
+            children=p['execution']['children'];self.assertEqual(len(children),1);factor=children[0]['effect'];v=0 if p['location']==0 else f(n(factor['execution']['return'])*100);self.assertEqual(p['scalar_word'],word(v))
+    def test_output_location_comes_from_child_pointer(self):
+        from qvm_contact_support import L
+        for p in self.ps:
+            child=p['execution']['children'][0];self.assertEqual(child['call']['args']['24'],L+60);self.assertEqual(p['location'],child['effect']['location'])
+    def test_zero_location_suppresses_even_override(self):
+        rows=[p for p in self.ps if p['input']['location']==0 and p['input']['override'] and p['input']['now']==4000];self.assertTrue(rows)
+        for p in rows:self.assertEqual(p['scalar_word'],0)
+    def test_only_factor_call_and_no_health_or_events(self):
+        self.assertEqual(len(self.ps),96)
+        for p in self.ps:self.assertEqual([c['target'] for c in p['execution']['calls']],[289594]);self.assertEqual(p['target_health'],100);self.assertTrue(all(not v for v in p['effects'].values()))
+if __name__=='__main__':unittest.main()