qvm: model multi-hit ordering

docs/ASSET_PIPELINE_TODO.md

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

docs/FINDINGS.md

@@ -1082,3 +1082,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **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).
+
+
+**RE-689 — Complete multi-part model hits and priority ordering:** Actual star/nested model hierarchies generate categories1/3/5/6, then source sorting can prioritize torso3 over a nearer arm5/6 without changing context nearest vectors. [Evidence](research/QVM_MODEL_MULTI_HITS.md).

docs/PROVISIONAL_TODO.md

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

docs/RESEARCH_LEDGER.md

@@ -1092,3 +1092,8 @@ Complete23092 now produces actual geometry-derived context records through packe
 ## 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.
+
+
+## 2026-10-21 — RE-689 Complete multi-part model hits and priority ordering (separate task commit)
+
+Actual star/nested model hierarchies generate categories1/3/5/6, then source sorting can prioritize torso3 over a nearer arm5/6 without changing context nearest vectors. Eight whole-model fixtures independently check every leaf, complete sorted context, geometric category sets, misses and distance-order changes from actual hits. Full suite: 1214 tests pass. Report regenerates byte-identically (524843 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

@@ -1108,3 +1108,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-688 Complete model-hit helper through geometry and publication ([report](research/QVM_COMPLETE_MODEL_HIT.md)).
+
+
+- [x] RE-689 Complete multi-part model hits and priority ordering ([report](research/QVM_MODEL_MULTI_HITS.md)).

docs/research/QVM_MODEL_MULTI_HITS.md

@@ -0,0 +1,7 @@
+# Complete multi-part model hits and priority ordering
+
+RE-689. Reproduce with `python3 scripts/analyze_qvm_model_multi_hits.py`; check with `python3 scripts/test_qvm_model_multi_hits.py`. The [machine report](qvm-model-multi-hits.json) retains source identity and bounded fixtures.
+
+Complete144766 now traverses explicit star/nested model tables, actual pose/sample transforms and packed geometry for four recognized surfaces. The record stream is generated by source intersection, then checked against independent stable-key sorting and the source type3 priority swap. Nearest context vectors remain unchanged by record priority, so trace publication and first record category can refer to different source choices. Hit/miss returns, source point arithmetic and all context words are checked. These tables are fixture hierarchies, not a claimed original skeleton; native math/zero fill remain models and damage/runtime 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

@@ -666,3 +666,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [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`.
+
+
+[RE-689: Complete multi-part model hits and priority ordering](QVM_MODEL_MULTI_HITS.md). Reproduce with `python3 scripts/analyze_qvm_model_multi_hits.py`; check with `python3 scripts/test_qvm_model_multi_hits.py`.

scripts/analyze_qvm_model_multi_hits.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Complete model helper through multi-part hierarchy and actual priority sorting."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source
+from analyze_qvm_complete_model_hit import prepare,complete
+from analyze_qvm_model_transforms import BUFFERS
+from analyze_qvm_geometric_hierarchy import attach
+from analyze_qvm_acceleration import word
+from analyze_qvm import write_json
+NAMES=['h_head','u_arml','u_armr','u_torso']
+
+def hierarchy(m,bs,layout):
+    a,b,c,d=BUFFERS;children={a:[b,c,d] if layout=='star' else [b],b:[c,d] if layout=='nested' else [],c:[],d:[]};names=dict(zip(BUFFERS,NAMES))
+    for index,node in enumerate(BUFFERS):
+        for o in [100,104,108]:m[node+o]=0
+        model=m[node+88];adj=children[node];m[node+92]=0x79010000+256*index if adj else 0;m[node+96]=0 if index==0 else (b if layout=='nested' and index>1 else a);m[model+80]=len(adj);tag_data=0x79000000+16384*index;m[model+96]=tag_data-model
+        for child_index,child in enumerate(adj):
+            m[m[node+92]+4*child_index]=child
+            for frame in range(23):
+                sample=tag_data+(frame*len(adj)+child_index)*112
+                for o in range(64,112,4):m[sample+o]=0
+                m[sample+72]=word([.75,.5,.25][child_index]);m[sample+76]=word(1);m[sample+92]=word(1);m[sample+108]=word(1)
+        attach(m,bs,node,0x78f00000+4096*index,NAMES[index],frame_count=23)
+    return names
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for layout,animation,hit in itertools.product(['star','nested'],[0,22],[False,True]):
+        m,bs,args,names=prepare(raw,h,animation,0,hit);names=hierarchy(m,bs,layout);m,r=complete(ins,m,bs,args,names);r['fixture']={'layout':layout,'animation':animation,'hit':hit};rows.append(r)
+    write_json(Path('docs/research/qvm-model-multi-hits.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Complete144766 with actual packed hierarchy/geometry and record sorting. Star/nested metadata are explicit fixtures, not validated original skeletons. Native math/zero fill modeled; no world collision/damage/reference parity.'})
+if __name__=='__main__':main()

scripts/test_qvm_complete_leaf.py

@@ -14,7 +14,7 @@ def expected(p):
                 b=[[n(x) for x in row] for row in matrix(a['basis_chain'])];o=list(map(n,a['node_origin']));vertices=[[word(f(f(f(f(n(v[0])*b[0][c])+f(n(v[1])*b[1][c]))+f(n(v[2])*b[2][c]))+o[c])) for c in range(3)] for v in vertices]
             c={'vertices':vertices,'origin':a['origin'],'direction':a['direction']};hit,det,u,v,t=candidate(c)
             if not hit:continue
-            c.update({'u':u,'v':v,'parameter':t});normal,edges,point=geometry({'candidate':c});category={'h_head':1,'u_torso':3,'l_rfoot':14,'g_vest':4}.get(s['name'],a['null_word4'])
+            c.update({'u':u,'v':v,'parameter':t});normal,edges,point=geometry({'candidate':c});category={'h_head':1,'u_torso':3,'l_rfoot':14,'g_vest':4,'u_arml':5,'u_armr':6}.get(s['name'],a['null_word4'])
             if n(t)<n(near):near=t;r[3:6]=point;r[9:12]=normal;r[15]=index
             if n(t)>n(far):far=t;r[:3]=point;r[6:9]=normal;r[14]=index
             count=r[16]

scripts/test_qvm_model_multi_hits.py

@@ -0,0 +1,29 @@
+import json,unittest
+from pathlib import Path
+from test_qvm_ground import n
+from test_qvm_complete_leaf import expected as leaf
+
+def sorted_context(before):
+    out=before[:];count=out[16];rows=[out[17+5*j:22+5*j] for j in range(count)];rows=sorted(rows,key=lambda row:n(row[4]))
+    if len(rows)>1 and rows[0][0] in [5,6]:
+        candidate=next((j for j,row in enumerate(rows[1:],1) if row[0]==3),None)
+        if candidate is not None:rows[0],rows[candidate]=rows[candidate],rows[0]
+    for j,row in enumerate(rows):out[17+5*j:22+5*j]=row
+    return out
+class ModelMultiHitTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.rows=json.loads(Path('docs/research/qvm-model-multi-hits.json').read_text())['probes']
+    def test_independent_every_actual_leaf_geometry(self):
+        self.assertEqual(len(self.rows),8)
+        for p in self.rows:
+            for r in p['hierarchies'][0]['leaf_reports']:self.assertEqual(r['effect']['after'],leaf(r['effect']))
+    def test_full_sort_context_and_type_priority_from_actual_hits(self):
+        for p in self.rows:
+            r=p['sorts'][0];self.assertEqual(r['after'],sorted_context(r['before']));self.assertEqual(p['context'],r['after'])
+    def test_actual_hit_category_sets_and_numeric_return(self):
+        for p in self.rows:
+            expected={1,3,5,6} if p['fixture']['hit'] else set();self.assertEqual({p['context'][17+5*j] for j in range(p['context'][16])},expected);self.assertEqual(p['execution']['return'],int(p['fixture']['hit']))
+    def test_priority_can_break_distance_order_without_changing_nearest_header(self):
+        hit=[p for p in self.rows if p['fixture']['hit']];self.assertTrue(any([n(p['context'][21+5*j]) for j in range(p['context'][16])]!=sorted(n(p['context'][21+5*j]) for j in range(p['context'][16])) for p in hit))
+        for p in self.rows:self.assertEqual(p['sorts'][0]['before'][:17],p['sorts'][0]['after'][:17])
+if __name__=='__main__':unittest.main()