qvm: bounded leaf hit publication

docs/ASSET_PIPELINE_TODO.md

@@ -724,3 +724,6 @@ Research progress: RE-683 [report](research/QVM_HIT_GEOMETRY.md); remaining nati
 
 
 Research progress: RE-684 [report](research/QVM_SURFACE_CATEGORY.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-685 [report](research/QVM_LEAF_HIT_PUBLISH.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -1070,3 +1070,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-684 — File-backed surface name classifier and exact string children:** 21493 recognizes fourteen case-sensitive names/categories1..14 through actual21458 perfect hashing and36306 packed comparison. [Evidence](research/QVM_SURFACE_CATEGORY.md).
+
+
+**RE-685 — Nearest farthest context updates and bounded hit append:** 23092 updates nearest/farthest point-normal-part independently of category/capacity, then appends nonzero category five-word records only below count10. [Evidence](research/QVM_LEAF_HIT_PUBLISH.md).

docs/PROVISIONAL_TODO.md

@@ -1053,3 +1053,6 @@ Research progress: RE-683 [report](research/QVM_HIT_GEOMETRY.md); remaining nati
 
 
 Research progress: RE-684 [report](research/QVM_SURFACE_CATEGORY.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-685 [report](research/QVM_LEAF_HIT_PUBLISH.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -1072,3 +1072,8 @@ Actual queried/allocated grenade enters223156, evaluates source trajectory, trun
 ## 2026-10-21 — RE-684 File-backed surface name classifier and exact string children (separate task commit)
 
 21493 recognizes fourteen case-sensitive names/categories1..14 through actual21458 perfect hashing and36306 packed comparison. 47 dictionary/mutation fixtures verify exact entries, case-sensitive collisions, helper dispatch and unsigned GTU high-bit/equality semantics. Full suite: 1193 tests pass. Report regenerates byte-identically (74336 bytes). Storage/filter, links and whitespace checks pass. No assets/Rust runtime changed; the bounded evaluator adds independently tested unsigned GTU; native/reference/legal/full platform scope remains open.
+
+
+## 2026-10-21 — RE-685 Nearest farthest context updates and bounded hit append (separate task commit)
+
+23092 updates nearest/farthest point-normal-part independently of category/capacity, then appends nonzero category five-word records only below count10. 96 whole-context fixtures independently check negative/equal/large parameters, strict bounds, categories, initialized null-pointer consumption and capacities0/9/10/11. Full suite: 1197 tests pass. Report regenerates byte-identically (350422 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

@@ -1096,3 +1096,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-684 File-backed surface name classifier and exact string children ([report](research/QVM_SURFACE_CATEGORY.md)).
+
+
+- [x] RE-685 Nearest farthest context updates and bounded hit append ([report](research/QVM_LEAF_HIT_PUBLISH.md)).

docs/research/QVM_LEAF_HIT_PUBLISH.md

@@ -0,0 +1,7 @@
+# Nearest farthest context updates and bounded hit append
+
+RE-685. Reproduce with `python3 scripts/analyze_qvm_leaf_hit_publish.py`; check with `python3 scripts/test_qvm_leaf_hit_publish.py`. The [machine report](qvm-leaf-hit-publish.json) retains source identity and bounded fixtures.
+
+Actual25162–25280 first updates nearest on strict smaller parameter and farthest on strict larger parameter. It then reads metadata entry+4 and appends [category,point.xyz,parameter] when category is nonzero and count<10. Cap/zero category do not suppress prior nearest/farthest writes. Normal is retained in the context header, not each five-word record. Negative parameters remain eligible. A classifier miss therefore consumes initialized word4 in this fixture, distinct from an explicit zero-category table slot; original live word4 mutations remain unknown. Final distance header stores occur later in the primitive-loop epilogue and are not invented here.
+
+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

@@ -654,3 +654,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-684: File-backed surface name classifier and exact string children](QVM_SURFACE_CATEGORY.md). Reproduce with `python3 scripts/analyze_qvm_surface_category.py`; check with `python3 scripts/test_qvm_surface_category.py`.
+
+
+[RE-685: Nearest farthest context updates and bounded hit append](QVM_LEAF_HIT_PUBLISH.md). Reproduce with `python3 scripts/analyze_qvm_leaf_hit_publish.py`; check with `python3 scripts/test_qvm_leaf_hit_publish.py`.

scripts/analyze_qvm_leaf_hit_publish.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""23092 nearest/farthest updates and ten-record append cap."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute
+from analyze_qvm_leaf_vertices import LOCAL
+from analyze_qvm_surface_category import support,classify,put_text,TEXT
+from analyze_qvm_acceleration import word
+from analyze_qvm import write_json
+CONTEXT=0x78c00000
+
+def context(m,p=CONTEXT):return [m[p+o]&0xffffffff for o in range(0,308,4)]
+def publish(ins,m,base=LOCAL):
+    m=dict(m);p=m[base+452];before=context(m,p);inputs={'parameter':m[base+268]&0xffffffff,'nearest':m[base+172]&0xffffffff,'farthest':m[base+176]&0xffffffff,'point':[m[base+400+4*j]&0xffffffff for j in range(3)],'normal':[m[base+388+4*j]&0xffffffff for j in range(3)],'part_index':m[base+160],'category':m[m[base+168]+4]&0xffffffff};m,_,e=execute(ins,25162,25281,m,(0,0,0),base)
+    return m,{'input':inputs,'before':before,'after':context(m,p),'nearest':m[base+172]&0xffffffff,'farthest':m[base+176]&0xffffffff,'execution':e}
+
+def main():
+    q,raw,h,ins=source();base,bytes_base=support(raw,h);rows=[]
+    for name,count,t in itertools.product(['h_head','l_rfoot','unknown','zero-entry'],[0,9,10,11],[-2,0,1,5,1e7,1e7+1]):
+        m=dict(base);bs=dict(bytes_base)
+        if name=='zero-entry':entry=3764
+        else:put_text(m,bs,TEXT,name.encode());m,c=classify(ins,m,bs,TEXT,len(name));entry=c['result_pointer']
+        for o in range(0,308,4):m[CONTEXT+o]=0x12340000+o
+        m.update({CONTEXT+64:count,LOCAL+452:CONTEXT,LOCAL+268:word(t),LOCAL+172:word(1e7),LOCAL+176:word(0),LOCAL+160:7,LOCAL+168:entry})
+        for local,v in [(400,(1.25,-2.5,3.75)),(388,(0,0,1))]:
+            for j,x in enumerate(v):m[LOCAL+local+4*j]=word(x)
+        _,r=publish(ins,m);r['name_fixture']=name;rows.append(r)
+    write_json(Path('docs/research/qvm-leaf-hit-publish.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Actual25162–25280 with file-backed metadata entry or explicit zero-slot fixture. Unknown classifier pointer0 retains initialized word4, whose live mutation remains unknown. Negative parameter is not filtered here. No primitive loop completion yet.'})
+if __name__=='__main__':main()

scripts/test_qvm_leaf_hit_publish.py

@@ -0,0 +1,25 @@
+import json,unittest
+from pathlib import Path
+from test_qvm_ground import n
+
+def expected(p):
+    a=p['input'];r=p['before'][:];t=n(a['parameter']);near=a['nearest'];far=a['farthest']
+    if t<n(near):r[3:6]=a['point'];r[9:12]=a['normal'];r[15]=a['part_index'];near=a['parameter']
+    if t>n(far):r[0:3]=a['point'];r[6:9]=a['normal'];r[14]=a['part_index'];far=a['parameter']
+    count=r[16]
+    if a['category'] and count<10:r[16]=count+1;r[17+5*count:22+5*count]=[a['category']]+a['point']+[a['parameter']]
+    return r,near,far
+class LeafHitPublishTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.rows=json.loads(Path('docs/research/qvm-leaf-hit-publish.json').read_text())['probes']
+    def test_independent_every_context_word_and_bounds(self):
+        self.assertEqual(len(self.rows),96)
+        for p in self.rows:self.assertEqual((p['after'],p['nearest'],p['farthest']),expected(p))
+    def test_capacity_does_not_suppress_nearest_farthest(self):self.assertTrue(any(p['before'][16]>=10 and p['before']!=p['after'] for p in self.rows))
+    def test_zero_category_and_unknown_pointer_are_distinct(self):
+        for p in self.rows:
+            if p['name_fixture']=='zero-entry':self.assertEqual(p['input']['category'],0);self.assertEqual(p['after'][16],p['before'][16])
+            if p['name_fixture']=='unknown':self.assertEqual(p['input']['category'],34089888)
+    def test_no_child_calls_or_final_distance_header_writes(self):
+        for p in self.rows:self.assertEqual(p['execution']['calls'],[]);self.assertEqual(p['before'][12:14],p['after'][12:14])
+if __name__=='__main__':unittest.main()