qvm: complete model hit helper

docs/ASSET_PIPELINE_TODO.md

@@ -733,3 +733,6 @@ Research progress: RE-686 [report](research/QVM_COMPLETE_LEAF.md); remaining nat
 
 
 Research progress: RE-687 [report](research/QVM_GEOMETRIC_HIERARCHY.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-688 [report](research/QVM_COMPLETE_MODEL_HIT.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -1079,3 +1079,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-687 — Recursive model traversal with actual leaf geometry:** 25341 now composes actual22009 and23092 through recursive hierarchies, producing hit records from packed geometry rather than supplied leaf replies. [Evidence](research/QVM_GEOMETRIC_HIERARCHY.md).
+
+
+**RE-688 — Complete model-hit helper through geometry and publication:** Complete144766 now executes actual pose/hierarchy/leaf geometry/classification/sorting and returns geometric hit0/1 with exact trace publication. [Evidence](research/QVM_COMPLETE_MODEL_HIT.md).

docs/PROVISIONAL_TODO.md

@@ -1062,3 +1062,6 @@ Research progress: RE-686 [report](research/QVM_COMPLETE_LEAF.md); remaining nat
 
 
 Research progress: RE-687 [report](research/QVM_GEOMETRIC_HIERARCHY.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-688 [report](research/QVM_COMPLETE_MODEL_HIT.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -1087,3 +1087,8 @@ Complete23092 now produces actual geometry-derived context records through packe
 ## 2026-10-21 — RE-687 Recursive model traversal with actual leaf geometry (separate task commit)
 
 25341 now composes actual22009 and23092 through recursive hierarchies, producing hit records from packed geometry rather than supplied leaf replies. 18 postorder compositions independently check every leaf context, ancestry matrix, carried record count, hit/miss outcome and caller return. Full suite: 1206 tests pass. Report regenerates byte-identically (423592 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-21 — RE-688 Complete model-hit helper through geometry and publication (separate task commit)
+
+Complete144766 now executes actual pose/hierarchy/leaf geometry/classification/sorting and returns geometric hit0/1 with exact trace publication. 16 full model compositions independently check pose, every leaf context, actual hit/miss, recognized categories, source child order and final trace words. Full suite: 1210 tests pass. Report regenerates byte-identically (575367 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

@@ -1105,3 +1105,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-687 Recursive model traversal with actual leaf geometry ([report](research/QVM_GEOMETRIC_HIERARCHY.md)).
+
+
+- [x] RE-688 Complete model-hit helper through geometry and publication ([report](research/QVM_COMPLETE_MODEL_HIT.md)).

docs/research/QVM_COMPLETE_MODEL_HIT.md

@@ -0,0 +1,7 @@
+# Complete model-hit helper through geometry and publication
+
+RE-688. Reproduce with `python3 scripts/analyze_qvm_complete_model_hit.py`; check with `python3 scripts/test_qvm_complete_model_hit.py`. The [machine report](qvm-complete-model-hit.json) retains source identity and bounded fixtures.
+
+Complete144767–146620 dispatches actual32254,25341,23092 and25835 over explicit packed models. Native math and bounded zero fill remain models. The new root-only fixtures use actual target/client pointers, frame0/22 records and yaw-dependent bases; hit results arise from source intersection rather than supplied replies. Trace point/normal/target ID publication matches independent geometry-derived contexts, and no-hit traces retain their initial words. Separate input and hit-output buffers avoid accidental fixture aliasing. Original asset identities/live bounds/native engine parity remain open.
+
+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

@@ -663,3 +663,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-687: Recursive model traversal with actual leaf geometry](QVM_GEOMETRIC_HIERARCHY.md). Reproduce with `python3 scripts/analyze_qvm_geometric_hierarchy.py`; check with `python3 scripts/test_qvm_geometric_hierarchy.py`.
+
+
+[RE-688: Complete model-hit helper through geometry and publication](QVM_COMPLETE_MODEL_HIT.md). Reproduce with `python3 scripts/analyze_qvm_complete_model_hit.py`; check with `python3 scripts/test_qvm_complete_model_hit.py`.

scripts/analyze_qvm_complete_model_hit.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Complete144766 with actual pose, hierarchy/leaf geometry, sort/publication."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute,constants
+from qvm_shot_math_support import TRIG
+from analyze_qvm_complete_pose import pose
+from analyze_qvm_model_ray_prefix import LOCAL
+from analyze_qvm_model_transforms import BUFFERS,TABLES
+from analyze_qvm_geometric_hierarchy import attach,geometric_walk
+from analyze_qvm_complete_leaf import words
+from analyze_qvm_surface_category import support
+from analyze_qvm_hit_publication import SORT
+from analyze_qvm_shot_trace_request import fixture as trace_fixture,TRACE,END,HIT
+from analyze_qvm_entity_init import POOL,STRIDE
+from analyze_qvm_acceleration import word
+from analyze_qvm_slide_prefix import vec
+from analyze_qvm import write_json
+
+START=END+0x3000
+
+def complete(ins,m,bs,args,names):
+    m=dict(m);before=words(m,args[12],14);poses=[];hierarchies=[];sorts=[]
+    for o,v in args.items():m[LOCAL+312+o]=v
+    def posed(i,m,a,c):m,r=pose(i,m,a);poses.append(r);return m,c,0,{'pose_index':len(poses)-1}
+    def zero(i,m,a,c):
+        assert a[8] in BUFFERS and a[12]==0 and a[16]==88
+        for o in range(0,88,4):m[a[8]+o]=0
+        return m,c,0,{'bounded_zero_fill':a}
+    def geometry(i,m,a,c):m,r=geometric_walk(i,m,bs,a,names);hierarchies.append(r);return m,c,0,{'hierarchy_index':len(hierarchies)-1}
+    def sort(i,m,a,c):
+        pointer=a[8];initial=words(m,pointer);m[SORT+56]=pointer;m,_,e=execute(i,25836,26036,m,c,SORT);r={'before':initial,'after':words(m,pointer),'execution':e};sorts.append(r);return m,c,0,{'sort_index':len(sorts)-1}
+    m,_,e=execute(ins,144767,146621,m,(0,0,0),LOCAL,{**TRIG,32254:posed,-101:zero,25341:geometry,25835:sort})
+    return m,{'arguments':args,'before_trace':before,'after_trace':words(m,args[12],14),'poses':poses,'hierarchies':hierarchies,'sorts':sorts,'context':words(m,args[24]),'execution':e}
+
+def prepare(raw,h,animation=0,yaw=0,hit=True,name='h_head',m=None,shooter=None):
+    if m is None:m,a=trace_fixture(raw,h);shooter=a[8]
+    else:m=dict(m)
+    s,bs=support(raw,h);m.update(s);m.update(constants(raw,h,list(range(20624,20700,4))+[21348,21352,21356]));target=POOL+65*STRIDE;client=m[target+520];m[TRACE+52]=65;m[target]=65;m[client+700]=0
+    for o,v in [(6196,0),(6204,animation),(6212,word(.5)),(6248,0),(6256,animation),(6264,word(.5))]:m[client+o]=v
+    for o in [4380,4384,4388,4392]:m[client+o]=0
+    source_client=m[shooter+520];m[source_client]=200;m[source_client+6176]=216
+    for p,v in [(target+24,(0,0,0)),(target+36,(0,0,0)),(target+60,(0,yaw,0)),(END,(.2,.5,0) if hit else (20,20,0)),(START,(.2,.5,1) if hit else (20,20,1))]:
+        for j,x in enumerate(v):m[p+4*j]=word(x)
+    for table,p in zip(TABLES,BUFFERS):
+        m[table]=p;m[p+88]=p+1024;m[p+92]=0;m[p+96]=0;m[p+1024+80]=0
+    attach(m,bs,BUFFERS[0],0x78f00000,name,frame_count=23)
+    for o in range(0,308,4):m[HIT+o]=0
+    return m,bs,{8:shooter,12:TRACE,16:START,20:END,24:HIT},{BUFFERS[0]:name}
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for animation,yaw,hit,name in itertools.product([0,22],[0,45],[False,True],['h_head','u_torso']):
+        m,bs,a,names=prepare(raw,h,animation,yaw,hit,name);m,r=complete(ins,m,bs,a,names);r['fixture']={'animation':animation,'yaw':yaw,'hit':hit,'name':name};rows.append(r)
+    write_json(Path('docs/research/qvm-complete-model-hit.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Complete144766 with actual32254/25341/22009/23092/25835 on explicit model tables and packed surface geometry. Here root has no children; broader hierarchy separate. Native math/zero fill modeled, no original assets/runtime/native world parity.'})
+if __name__=='__main__':main()

scripts/analyze_qvm_geometric_hierarchy.py

@@ -12,10 +12,10 @@ from analyze_qvm import write_json
 VERTICES=[[0,0,0],[256,0,0],[0,256,0]]
 NAMES=['h_head','u_torso','l_rfoot','g_vest']
 
-def attach(m,bs,node,part,name,vertices=VERTICES):
+def attach(m,bs,node,part,name,vertices=VERTICES,frame_count=2):
     model=m[node+88];m[model+84]=1;m[model+100]=part-model;m.update({part+80:3,part+84:1,part+88:128,part+100:512,part+104:1024});put_text(m,bs,part+4,name.encode())
     for j in range(3):m[part+128+4*j]=j
-    for frame in range(2):
+    for frame in range(frame_count):
         for j,v in enumerate(vertices):
             address=part+512+(frame*3+j)*8;data=b''.join(int(x).to_bytes(2,'little',signed=True) for x in v)+b'\0\0'
             for k,b in enumerate(data):bs[address+k]=b

scripts/test_qvm_complete_model_hit.py

@@ -0,0 +1,23 @@
+import json,unittest
+from pathlib import Path
+from test_qvm_complete_leaf import expected as leaf
+from test_qvm_complete_pose import expected as pose
+class CompleteModelHitTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.rows=json.loads(Path('docs/research/qvm-complete-model-hit.json').read_text())['probes']
+    def test_independent_pose_and_complete_leaf_geometry(self):
+        self.assertEqual(len(self.rows),16)
+        for p in self.rows:
+            state,angles,flag=pose(p['poses'][0]);self.assertEqual(p['poses'][0]['final_state'],state);self.assertEqual(p['poses'][0]['output_legs_body_head'],angles)
+            for r in p['hierarchies'][0]['leaf_reports']:self.assertEqual(r['effect']['after'],leaf(r['effect']))
+    def test_exact_numeric_return_and_trace_publication(self):
+        for p in self.rows:
+            hit=bool(p['context'][16]);expected=p['before_trace'][:]
+            if hit:expected[3:6]=p['context'][3:6];expected[6:9]=p['context'][9:12];expected[13]=65
+            self.assertEqual(p['after_trace'],expected);self.assertEqual(p['execution']['return'],int(hit));self.assertEqual(hit,p['fixture']['hit'])
+    def test_actual_source_callee_order(self):
+        for p in self.rows:self.assertEqual([c['target'] for c in p['execution']['calls']],[-107,32254]+[-101]*4+[-104,-105]*9+[25341,25835])
+    def test_hit_records_come_from_geometry_and_recognized_names(self):
+        for p in self.rows:
+            if p['fixture']['hit']:self.assertEqual(p['context'][17],1 if p['fixture']['name']=='h_head' else 3);self.assertEqual(p['sorts'][0]['before'],p['sorts'][0]['after'])
+if __name__=='__main__':unittest.main()