qvm: geometric rewound trace cleanup

docs/ASSET_PIPELINE_TODO.md

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

docs/FINDINGS.md

@@ -1085,3 +1085,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **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).
+
+
+**RE-690 — Rewound trace through actual model geometry and complete cleanup:** 291641 now reaches complete returns through actual geometric model hits or model misses followed by a supplied world retry, including actual rewind/restoration and cleanup. [Evidence](research/QVM_GEOMETRIC_REWOUND_TRACE.md).

docs/PROVISIONAL_TODO.md

@@ -1068,3 +1068,9 @@ Research progress: RE-688 [report](research/QVM_COMPLETE_MODEL_HIT.md); remainin
 
 
 Research progress: RE-689 [report](research/QVM_MODEL_MULTI_HITS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-690 [report](research/QVM_GEOMETRIC_REWOUND_TRACE.md); remaining native/content/runtime/platform scope stays open.
+
+
+RE-681–690 batch complete: [source model geometry through rewound trace](research/QVM_GEOMETRY_TRACE_BATCH.md). RE-691 tracks original asset/reference validation and downstream contact/damage; playable Rust/Bevy/Solari integration remains open.

docs/RESEARCH_LEDGER.md

@@ -1097,3 +1097,8 @@ Complete144766 now executes actual pose/hierarchy/leaf geometry/classification/s
 ## 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.
+
+
+## 2026-10-21 — RE-690 Rewound trace through actual model geometry and complete cleanup (separate task commit)
+
+291641 now reaches complete returns through actual geometric model hits or model misses followed by a supplied world retry, including actual rewind/restoration and cleanup. Two whole caller compositions independently check every leaf/context sort, numeric return, native candidate sequence, every rewind and all tracked restored entity records. Full suite: 1218 tests pass. Report regenerates byte-identically (953113 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

@@ -1083,7 +1083,7 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 - [x] RE-679 Constructed grenade through trajectory and event prelude ([report](research/QVM_GRENADE_EVENT_PREFIX.md)).
 
 
-- [ ] RE-680 Recover leaf primitive decoding/intersection and actual hit records, compose full model/trace cleanup, then continue damage, grenade completion, heap ownership and live scheduling toward a verified Rust gameplay slice. See the [next ten tasks](research/QVM_MODEL_RESOURCE_BATCH.md#next-ten-concrete-tasks).
+- [ ] RE-680 Substantially advanced by RE-681–690: packed leaf geometry, actual hit records, recursive hierarchy, complete model helper and rewound trace cleanup now execute on bounded packed-model fixtures. Original asset/buffer/reference parity, downstream contact/damage, grenade/heap/scheduling completion and Rust gameplay remain open. See the [batch and next ten tasks](research/QVM_GEOMETRY_TRACE_BATCH.md).
 
 
 - [x] RE-681 Packed frame vertices through world triangle construction ([report](research/QVM_LEAF_VERTICES.md)).
@@ -1111,3 +1111,9 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-689 Complete multi-part model hits and priority ordering ([report](research/QVM_MODEL_MULTI_HITS.md)).
+
+
+- [x] RE-690 Rewound trace through actual model geometry and complete cleanup ([report](research/QVM_GEOMETRIC_REWOUND_TRACE.md)).
+
+
+- [ ] RE-691 Connect original model assets and reference traces to recovered geometry, then continue contact/damage, shared/pellet aggregation and remaining runtime/lifecycle work toward a verified Rust gameplay slice. See the [next ten tasks](research/QVM_GEOMETRY_TRACE_BATCH.md#next-ten-concrete-tasks).

docs/research/QVM_GEOMETRIC_REWOUND_TRACE.md

@@ -0,0 +1,7 @@
+# Rewound trace through actual model geometry and complete cleanup
+
+RE-690. Reproduce with `python3 scripts/analyze_qvm_geometric_rewound_trace.py`; check with `python3 scripts/test_qvm_geometric_rewound_trace.py`. The [machine report](qvm-geometric-rewound-trace.json) retains source identity and bounded fixtures.
+
+An optional model resolver preserves the existing pending-model report. The new291641 composition executes complete144766 with actual packed hierarchy/geometry, returning source-derived model0/1. A model hit reaches cleanup and return1; a model miss unlinks/retries the explicitly supplied native world candidate, cleans up and returns0. Actual rewind/restore selectors run around both paths. Independent geometry, sorted-context, complete rewind and whole-entity restoration oracles verify results, including known animation-byte loss. Native trace candidate records remain supplied and links captured, while model-hit replies are no longer supplied. Contact/damage, original assets/world collision and live/native 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/QVM_GEOMETRY_TRACE_BATCH.md

@@ -0,0 +1,49 @@
+# Source model geometry through rewound trace: RE-681–690
+
+Ten separately checked tasks extend the [model/resource batch](QVM_MODEL_RESOURCE_BATCH.md). Packed model data now drive complete leaf, hierarchy and model-hit source paths. The rewound trace reaches cleanup and returns using those geometric model outcomes. Native broadphase candidates remain supplied, and original asset/runtime parity remains open.
+
+| Task | Recovered scope | Evidence |
+| --- | --- | --- |
+| RE-681 | Signed packed frame vertices, interpolation and world triangles | [Leaf vertices](QVM_LEAF_VERTICES.md) |
+| RE-682 | Determinant epsilon, barycentrics and ray parameter | [Ray/triangle candidates](QVM_RAY_TRIANGLE.md) |
+| RE-683 | Exact source normal, normalized edges and point | [Hit geometry](QVM_HIT_GEOMETRY.md) |
+| RE-684 | File-backed perfect-hash classifier with actual string children | [Surface categories](QVM_SURFACE_CATEGORY.md) |
+| RE-685 | Nearest/farthest context and ten-record append limit | [Hit publication](QVM_LEAF_HIT_PUBLISH.md) |
+| RE-686 | Complete leaf loops with source-produced geometric records | [Complete leaf](QVM_COMPLETE_LEAF.md) |
+| RE-687 | Recursive hierarchy with actual leaf geometry | [Geometric hierarchy](QVM_GEOMETRIC_HIERARCHY.md) |
+| RE-688 | Complete model helper through pose, geometry, sorting and trace output | [Complete model hit](QVM_COMPLETE_MODEL_HIT.md) |
+| RE-689 | Complete multi-part model hits and priority ordering | [Multi-part hits](QVM_MODEL_MULTI_HITS.md) |
+| RE-690 | Rewound trace through geometric model returns and cleanup | [Geometric rewound trace](QVM_GEOMETRIC_REWOUND_TRACE.md) |
+
+## Findings for the rewrite
+
+Leaf23092 addresses eight-byte vertices by frame, vertex count and triangle index. It sign-extends xyz16, interpolates B+(A−B)×fraction and scales1/64 before applying the prepared ancestry basis/origin. The last two vertex bytes are not read in this position slice. Independent fixtures cover signed extrema, reversed/equal frames, permutations and extrapolation. Model surface/frame ownership and live bounds still require original asset evidence.
+
+The triangle test rejects an open determinant epsilon interval and out-of-triangle barycentrics. It accepts either winding and triangle-edge equality. It does not reject negative ray parameters or impose a segment endpoint limit here. Normal construction uses cross(a−b,b−c), then normalizes that cross product and both edges. Point construction uses a+(unit(a−b)×u+unit(b−c)×v), which differs from a conventional ray intersection point. The recovered source words are preserved without silently substituting expected geometry or claiming intended design.
+
+Classifier21493 recognizes fourteen exact case-sensitive names/categories1..14 using actual21458 hashing, file-backed association/entry tables and actual36306 packed comparison. It checks lengths6..8. A miss returns pointer zero; the later consumer reads word4, whose initialized value is34089888. That raw-data path is distinct from a valid zero-category entry, and live mutation/unknown-name semantics remain unresolved. The bounded evaluator gains independently tested unsigned GTU support.
+
+Publication first updates strict nearest/farthest point, normal and part index, independent of category or record capacity. Nonzero categories append [category,point.xyz,parameter] while count<10. Normal belongs to the context header, not each record. Each leaf initializes its own distance bounds, while record count carries across leaves. Sorting preserves equal-key order until the separate torso3 priority swap over a leading arm5/6; that swap can break numeric distance order without changing nearest context vectors.
+
+Complete23092,25341 and144766 now execute over explicit packed model fixtures. Actual pose, child transforms, geometry, classification and sorting produce model hit/miss results; no model-hit response is supplied. Star/nested multi-part fixtures exercise categories1/3/5/6. Complete291641 composes these outcomes with actual rewind/restore selectors: a geometric hit cleans up and returns1; a geometric miss retries a supplied native world candidate, cleans up and returns0. Whole tracked entity records restore with the previously documented animation-byte truncation.
+
+The complete leaf run exposed a bounded evaluator inconsistency: STORE4 updated word memory but could leave stale active byte memory that later BLOCK_COPY read. STORE4 now synchronizes those bytes. A dedicated regression checks word-to-byte-to-copy coherence. Relevant earlier history/rewind/pose/model reports regenerated unchanged after the fix, as did the existing pending-model and captured-leaf reports after optional resolver extensions.
+
+## Validation and limits
+
+The1177-test baseline gains41 checks, ending at1218 passing tests. Every new report regenerates byte-identically and stays below2MiB. Independent signed-byte, float32 geometry, exact dictionary, whole-context, pose, sorting, rewind and entity-restoration oracles verify bounded source behavior. Storage/filter, documentation-link and whitespace checks pass. No assets or Rust runtime change.
+
+Packed model tables, surface geometry, acyclic hierarchies, player histories, clocks and legal input domains remain explicit fixtures. Native finite math/zero fill are models; native trace candidates are supplied and link/unlink requests are captured. The geometric model outcome is source-derived, but no original executable/full VM, original model-buffer import, native world collision, contact/damage, live server tick, networking/rendering or macOS/Linux Rust/Bevy/Solari gameplay runs here. RE-680 is substantially advanced but remains open for original asset/geometry parity and downstream damage/runtime work. RE-691 tracks the next tasks.
+
+## Next ten concrete tasks
+
+1. Connect original model assets to recovered surface/frame/tag layouts, documenting ownership, bounds, material/surface names and coordinate conventions.
+2. Validate recovered point, fourth-row and unknown-name behavior against original executable/native/DLL traces; preserve observed parity rather than assuming intended formulas.
+3. Expand full model geometry to original frame/animation transitions, overlapping surfaces, capacity exhaustion and live target/skeleton bindings.
+4. Recover contact292545 with actual geometric model outputs and exact caller pointer/flag contracts.
+5. Recover reached damage211239 health/armor/team/location rules, events and side effects through independent source contracts and original reference checks.
+6. Continue shared handler293732 through actual trace/contact/bookkeeping; validate source-produced target/location statistics.
+7. Continue295018 through successful pellet aggregation, four-target/fifteen-slot bookkeeping and contact conditions.
+8. Recover penetration/retry/event64 paths, boundary cleanup and direction encoding, retaining explicit native collision contracts.
+9. Continue grenade223156 completion, heap16934 ownership/coalescing and actual history reset/append scheduling with original references.
+10. Implement a verified Rust gameplay slice and continue all macOS/Linux Bevy/Solari assets/maps/models/shaders/audio/network/runtime goals; this research batch does not complete the game.

docs/research/README.md

@@ -669,3 +669,9 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [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`.
+
+
+[RE-690: Rewound trace through actual model geometry and complete cleanup](QVM_GEOMETRIC_REWOUND_TRACE.md). Reproduce with `python3 scripts/analyze_qvm_geometric_rewound_trace.py`; check with `python3 scripts/test_qvm_geometric_rewound_trace.py`.
+
+
+[RE-681–690: Source model geometry through rewound trace](QVM_GEOMETRY_TRACE_BATCH.md), with validation limits and the next ten concrete tasks.

scripts/analyze_qvm_geometric_rewound_trace.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""Actual rewind/trace/model/restore composition with supplied native candidates."""
+from pathlib import Path
+from qvm_research_support import source
+from analyze_qvm_rewound_trace import scene,runtime_trace
+from analyze_qvm_complete_model_hit import prepare,complete
+from analyze_qvm_model_multi_hits import hierarchy
+from analyze_qvm_entity_init import POOL,STRIDE
+from analyze_qvm_temp_event import record
+from analyze_qvm import write_json
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for hit in [False,True]:
+        m,a,traces=scene(raw,h,ins,'model-pending');shooter_client=m[a[8]+520];clock=[m[shooter_client],m[shooter_client+6176]];m,bs,ma,names=prepare(raw,h,hit=hit,m=m,shooter=a[8]);m[shooter_client],m[shooter_client+6176]=clock;names=hierarchy(m,bs,'star');a[16]=ma[16];a[20]=ma[20];traces=[65] if hit else [65,1023];models=[]
+        def resolved(i,m,args):
+            m,r=complete(i,m,bs,args,names);models.append(r);return m,r['execution']['return'],{'actual_model_index':len(models)-1}
+        points=[POOL+i*STRIDE for i in [0,1,8,63,64,65,66,67,68,69]];before={str(p):record(m,p) for p in points};m,r=runtime_trace(ins,m,a,traces,model_resolver=resolved);r.update({'hit_fixture':hit,'models':models,'initial_records':before,'final_records':{str(p):record(m,p) for p in points}});rows.append(r)
+    write_json(Path('docs/research/qvm-geometric-rewound-trace.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Actual291641 rewind/model/restore and full144766 geometry on explicit packed hierarchy. Native trace candidate records still supplied, native links captured, finite math/zero fill modeled. No supplied model-hit replies. Damage/contact/original world collision/live parity remain open.'})
+if __name__=='__main__':main()

scripts/analyze_qvm_rewound_trace.py

@@ -13,7 +13,7 @@ from analyze_qvm_acceleration import word
 from analyze_qvm import write_json
 PENDING={291986:144766,292020:211239,292213:277695,292226:60317}
 
-def runtime_trace(ins,m,args,traces):
+def runtime_trace(ins,m,args,traces,model_resolver=None):
     m=dict(m)
     for o,v in args.items():m[LOCAL+144+o]=v
     requests=[];responses=[];lifecycle=[]
@@ -25,7 +25,9 @@ def runtime_trace(ins,m,args,traces):
         index=traces[len(responses)];words=[0]*14;words[2]=word(1 if index>=1022 else .5);words[13]=index
         for j,v in enumerate(words):m[a[8]+4*j]=v
         e={'arguments':a,'supplied_words':words,'native_effect_not_executed':True};responses.append(e);return m,0,e
-    m,e=resume(ins,291642,292543,m,LOCAL,handlers={144082:rewind,144493:configured,144413:restore,-32:captured(-32,requests),-31:captured(-31,requests),-25:trace},boundaries=list(PENDING))
+    handlers={144082:rewind,144493:configured,144413:restore,-32:captured(-32,requests),-31:captured(-31,requests),-25:trace}
+    if model_resolver is not None:handlers[144766]=model_resolver
+    m,e=resume(ins,291642,292543,m,LOCAL,handlers=handlers,boundaries=[p for p in PENDING if not(model_resolver is not None and p==291986)])
     return m,{'arguments':args,'responses':responses,'native_requests':requests,'lifecycle':lifecycle,'execution':e,'status':'returned' if e['return'] is not None else 'child-pending','pending_target':PENDING.get(e['stop'])}
 
 def scene(raw,h,ins,label):

scripts/test_qvm_geometric_rewound_trace.py

@@ -0,0 +1,27 @@
+import json,unittest
+from pathlib import Path
+from test_qvm_complete_rewind import expected as rewind
+from test_qvm_complete_leaf import expected as leaf
+from test_qvm_model_multi_hits import sorted_context
+class GeometricRewoundTraceTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.rows=json.loads(Path('docs/research/qvm-geometric-rewound-trace.json').read_text())['probes']
+    def test_actual_model_outcome_and_complete_caller_return(self):
+        self.assertEqual(len(self.rows),2)
+        for p in self.rows:self.assertEqual(p['execution']['return'],int(p['hit_fixture']));self.assertEqual(p['status'],'returned');self.assertIsNone(p['pending_target']);self.assertEqual(len(p['responses']),1 if p['hit_fixture'] else 2);self.assertEqual(p['models'][0]['execution']['return'],int(p['hit_fixture']))
+    def test_independent_full_leafs_and_sorted_context(self):
+        for p in self.rows:
+            model=p['models'][0]
+            for r in model['hierarchies'][0]['leaf_reports']:self.assertEqual(r['effect']['after'],leaf(r['effect']))
+            self.assertEqual(model['context'],sorted_context(model['sorts'][0]['before']))
+    def test_actual_rewind_and_restore_full_entity_records(self):
+        for p in self.rows:
+            self.assertEqual([r['target'] for r in p['lifecycle']],[144082,144413])
+            for r in p['lifecycle'][0]['effect']['rewinds']:self.assertEqual((r['final_entity'],r['final_client']),rewind(r)[0])
+            for pointer,original in p['initial_records'].items():
+                expected=original.copy()
+                if (int(pointer)-34091368)//880 in [1,8,63]:expected['196']&=255;expected['200']&=255
+                self.assertEqual(p['final_records'][pointer],expected)
+    def test_native_candidate_contract_and_model_child_are_distinct(self):
+        for p in self.rows:self.assertIn(144766,[c['target'] for c in p['execution']['calls']]);self.assertTrue(all(r['native_effect_not_executed'] for r in p['responses']));self.assertNotIn(211239,[c['target'] for c in p['execution']['calls']])
+if __name__=='__main__':unittest.main()