qvm: event57 world trace caller return

docs/ASSET_PIPELINE_TODO.md

@@ -616,3 +616,9 @@ Research progress: RE-644 [report](research/QVM_TWENTY_PELLETS.md); remaining na
 
 
 Research progress: RE-645 [report](research/QVM_NO_TARGET_STATS.md); remaining native/content/runtime/platform scope stays open.
+
+
+The [RE-637–646 history/pellet batch](research/QVM_HISTORY_PELLET_BATCH.md) recovers complete history rewind/restore and an allocated event57 twenty-pellet return path under supplied world responses. Current next tasks prioritize history production, model hits, contact/damage and nonzero-hit aggregation. Original reference and full Rust/Bevy/Solari macOS/Linux/native/content/network/rendering scope remain open.
+
+
+Research progress: RE-646 [report](research/QVM_EVENT57_WORLD_RETURN.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -965,3 +965,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-645 — Statistic category maps and complete no-target bookkeeping:** 279820 maps weapon/location categories, increments attempts/misses for no-target IDs, and recomputes percentage; zero total after wrap resets percentage without division. [Evidence](research/QVM_NO_TARGET_STATS.md).
+
+
+**RE-646 — Allocated event57 twenty-world-pellet bookkeeping and caller continuation:** Direct285840 now composes actual allocation, event57, quantized direction/global RNG, all20 supplied-world pellets, real no-target bookkeeping and void caller continuation. [Evidence](research/QVM_EVENT57_WORLD_RETURN.md).

docs/PROVISIONAL_TODO.md

@@ -936,3 +936,9 @@ Research progress: RE-644 [report](research/QVM_TWENTY_PELLETS.md); remaining na
 
 
 Research progress: RE-645 [report](research/QVM_NO_TARGET_STATS.md); remaining native/content/runtime/platform scope stays open.
+
+
+The [RE-637–646 history/pellet batch](research/QVM_HISTORY_PELLET_BATCH.md) recovers complete history rewind/restore and an allocated event57 twenty-pellet return path under supplied world responses. Current next tasks prioritize history production, model hits, contact/damage and nonzero-hit aggregation. Original reference and full Rust/Bevy/Solari macOS/Linux/native/content/network/rendering scope remain open.
+
+
+Research progress: RE-646 [report](research/QVM_EVENT57_WORLD_RETURN.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -897,3 +897,8 @@ Whole291641 now executes recovered rewind/configured/restore children before and
 ## 2026-10-20 — RE-645 Statistic category maps and complete no-target bookkeeping (separate task commit)
 
 279820 maps weapon/location categories, increments attempts/misses for no-target IDs, and recomputes percentage; zero total after wrap resets percentage without division. 49 category probes and28 no-target/counter/invalid-attacker cases independently check table-derived categories, all20 stats rows, call order and overflow handling. Full suite: 1055 tests pass. Report regenerates byte-identically (520179 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-20 — RE-646 Allocated event57 twenty-world-pellet bookkeeping and caller continuation (separate task commit)
+
+Direct285840 now composes actual allocation, event57, quantized direction/global RNG, all20 supplied-world pellets, real no-target bookkeeping and void caller continuation. Four complete chains plus a zero-direction boundary independently check every event word/global seed, twenty trace calls, actual bookkeeping ABI, all stats rows and suspended invalid input. Full suite: 1059 tests pass. Report regenerates byte-identically (1683006 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

@@ -948,7 +948,7 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 - [x] RE-634 Fixed player rewind selection and actual restore enumeration ([report](research/QVM_REWIND_SELECTORS.md)).
 
 
-- [ ] RE-636 Recover history bracketing/interpolation and compose complete rewind/restore; continue model-hit/contact/damage, pellet aggregation and entity lifecycle, then original-reference and Rust platform integration. Follow the [next ten tasks](research/QVM_TRACE_REWIND_BATCH.md#next-ten-concrete-tasks).
+- [ ] RE-636 Partially advanced by RE-637–646:history selection/interpolation and complete rewind/restore are recovered; the event57 supplied-world path now completes twenty pellets, no-target statistics and caller continuation. History production/legal timing, model-hit/contact/damage, nonzero-hit aggregation, native world effects and Rust platform integration remain open. Follow the [current next ten tasks](research/QVM_HISTORY_PELLET_BATCH.md#next-ten-concrete-tasks).
 
 
 - [x] RE-635 Configured player_bb construction with recovered allocation ([report](research/QVM_PLAYER_BB_CONSTRUCT.md)).
@@ -979,3 +979,9 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-645 Statistic category maps and complete no-target bookkeeping ([report](research/QVM_NO_TARGET_STATS.md)).
+
+
+- [ ] RE-647 Recover history production, model-hit/contact/damage, nonzero-hit aggregation/statistics and entity lifecycle; validate original/native reference behavior and connect a Rust gameplay slice. See the [next ten tasks](research/QVM_HISTORY_PELLET_BATCH.md#next-ten-concrete-tasks).
+
+
+- [x] RE-646 Allocated event57 twenty-world-pellet bookkeeping and caller continuation ([report](research/QVM_EVENT57_WORLD_RETURN.md)).

docs/research/QVM_EVENT57_WORLD_RETURN.md

@@ -0,0 +1,7 @@
+# Allocated event57 twenty-world-pellet bookkeeping and caller continuation
+
+RE-646. Reproduce with `python3 scripts/analyze_qvm_event57_world_return.py`; check with `python3 scripts/test_qvm_event57_world_return.py`. The [machine report](qvm-event57-world-return.json) retains source identity and bounded fixtures.
+
+The actual285840 caller dispatches recovered277695/277165/277125/278138 and36717, then runs295018 through twenty world-trace fixtures. Recovered279820 executes its no-target branch, and the actual caller resumes to the void epilogue rather than stopping at an opaque child. Dynamic allocated-record argument pointers remain intact. Independent event/quantization/RNG and full-stat-row oracles verify the complete chain; statistics increment once after all twenty pellets. The argument-local seed evolves without altering the stored event/global seed. Zero direction leaves the caller suspended before division and performs no statistics update. Explicit source-pool attacker/client bindings, histories and native response models remain synthetic contracts. No successful model/contact/damage or native-world/gameplay parity is inferred. The overview records all ten tasks and current next gaps.
+
+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_HISTORY_PELLET_BATCH.md

@@ -0,0 +1,51 @@
+# Rewind histories and complete supplied-world shots: RE-637–646
+
+Ten separately checked tasks extend the [trace and rewind-state batch](QVM_TRACE_REWIND_BATCH.md). Complete history rewind and restoration now execute through the player selectors and trace routine. The direct event57 firing path also reaches its void caller boundary after all twenty supplied-world pellets and actual no-target bookkeeping. Native collision and successful player-hit behavior remain unverified.
+
+| Task | Recovered scope | Evidence |
+| --- | --- | --- |
+| RE-637 | History bracketing, equality and fallback weights | [Selection](QVM_REWIND_HISTORY_SELECT.md) |
+| RE-638 | Exact weighted vector interpolation and input aliases | [Vector interpolation](QVM_HISTORY_VECTOR_LERP.md) |
+| RE-639 | Strict half-turn angle correction and interpolation | [Angle interpolation](QVM_HISTORY_ANGLE_LERP.md) |
+| RE-640 | History application: vectors, angles, animation bytes and client fields | [Application](QVM_REWIND_HISTORY_APPLY.md) |
+| RE-641 | Complete 143100 rewind followed by actual restoration | [Whole rewind](QVM_COMPLETE_REWIND.md) |
+| RE-642 | Actual player selectors through complete rewind and restore | [Selector composition](QVM_COMPLETE_REWIND_SELECTORS.md) |
+| RE-643 | Trace routine with recovered rewind/configuration/restoration | [Rewound trace](QVM_REWOUND_TRACE.md) |
+| RE-644 | All twenty pellet iterations, signed seed carry and no-target handoff | [Pellet loop](QVM_TWENTY_PELLETS.md) |
+| RE-645 | Statistic category maps and complete no-target bookkeeping | [Statistics](QVM_NO_TARGET_STATS.md) |
+| RE-646 | Allocated event57 through twenty world traces, statistics and caller continuation | [Event57 composition](QVM_EVENT57_WORLD_RETURN.md) |
+
+## Findings for the rewrite
+
+History selection examines entries 1 through 19 in the supplied 20-entry table, using an 80-byte stride and timestamp offset 68. It picks the first timestamp at or below the target; it does not sort the table. Exhaustion leaves both indices at zero but can still produce an unclamped fallback weight from timestamps zero and one. Equal timestamps have explicit source fallbacks. The producer and intended ordering of live history records remain to be recovered.
+
+The vector helper calculates `(1 - fraction) * a + fraction * b` in source f32 order. A conventional subtract-then-add lerp can produce different bits. Exact output aliases to either input vector are tested; partial overlaps remain open. The angle helper applies strict greater-than-180 and less-than-minus-180 corrections by a single turn, then interpolates without normalizing the result or weight. Large arbitrary angle differences are not fully reduced modulo 360.
+
+History application blends position, velocity and angles, then copies animation bytes and six client fields directly from the lower numerical index. Those discrete fields do not interpolate. Whole 143100 now preserves the complete snapshot, selection and application sequence, then requests a native link. Actual restoration returns the original entity/client fields with the expected loss of animation high bits in the byte snapshot.
+
+The fixed player selectors now execute complete rewind children rather than captured requests. Tests verify full selected records and unchanged unselected pool records. Trace composition dispatches recovered rewind, configured `player_bb` construction and restoration around explicitly supplied native trace records. World and skipped-target paths reach source return zero after cleanup; a model-hit path still suspends before helper 144766. A pending hit path does not pretend cleanup or a return occurred.
+
+The twenty-pellet analysis follows the actual loop and its index progression, rotates by 18 degrees per iteration, carries the signed argument-local seed and checks every endpoint independently. Global RNG remains unchanged during pellet processing. Supplied world traces return zero from the recovered trace routine, leaving all four aggregate target IDs at 1023 and reaching no-target bookkeeping. These fixtures do not exercise successful model/contact/damage branches.
+
+Bookkeeping maps weapon and location categories through initialized jump tables. With no target, it increments the mapped row's attempt and miss counters and computes the stored percentage in source f32 order. If the attempt counter wraps to zero, the source resets the percentage rather than dividing. Invalid weapon categories and attacker minus one have explicit early exits. Victim/team/hit updates remain separate source branches.
+
+The direct 285840 event57 composition now executes source allocation/initialization, temporary event creation, 4096-scale direction truncation, global RNG, the complete twenty-world-pellet path, no-target bookkeeping and the caller continuation to its void epilogue. Statistics update once for the whole no-target shot. The argument-local seed carries independently of the event's stored seed and global RNG. Zero direction stops before projection division and does not resume the caller or update statistics.
+
+## Validation and limits
+
+The 1023-test baseline gains 36 checks, ending at 1059 tests. Independent f32, geometry, full-record, byte-packing, table-mapping, call-order and complete composition oracles check the recovered paths. All task reports regenerate deterministically and stay below 2 MiB. Storage/filter, documentation-link and whitespace checks pass. No original assets, Rust runtime or shared VM evaluator change in this batch.
+
+Player histories, target times, candidate lists, attacker/client bindings and native collision responses are explicit finite fixtures. Native link, unlink and entity-registration requests are captured without engine effects; native math uses the previously stated finite models. Original history population, legal live input domains, native library bit parity and world collision remain unverified. No original executable/full VM, successful model hit, contact/damage, complete live server tick, networking/rendering or macOS/Linux Bevy/Solari gameplay runs here.
+
+## Next ten concrete tasks
+
+1. Recover the producer of the 20-entry history table: insertion/update timing, record ordering, timestamp origin, packing and connection/reset behavior. Validate the time forwarded from the shooter against that producer.
+2. Partition model-hit helper 144766 and recover its first native/copy/math and model-state contracts, preserving unresolved asset/model identity references.
+3. Recover the helper's actual hit classification and output record fields through reached consumers, without supplying a successful player hit as a shortcut.
+4. Continue shared handler 293732 through an actual trace return into contact 292545 and bookkeeping 279820. Preserve source caller pointers, flags and all asset/event references.
+5. Recover 295018's nonzero trace-return branches, contact conditions and four-target/fifteen-slot aggregation. Existing twenty-world-pellet fixtures only cover the zero-return/no-target branch.
+6. Recover victim/team/hit statistic updates, including helper 33715 and percentage/damage accumulation. Compare exact counters against complete no-target behavior.
+7. Recover reached damage 211239 and the tagged trace branch's event64/normal encoding and penetration/retry behavior. Retain actual allocation and explicit native boundaries.
+8. Recover `player_bb` expiry callback 277400 and entity free/reset behavior, then connect allocator timing/capacity evidence to real lifecycle transitions.
+9. Continue query 276433, base construction after allocation and grenade 223156 trajectory/contact/bounce/explosion paths as bounded source stages with independent contracts.
+10. Capture original executable/native/DLL reference traces and implement one verified Rust gameplay slice. Continue all map/model/texture/shader/audio/network findings and macOS/Linux Bevy/Solari rendering/runtime work; these bounded QVM compositions do not complete the game.

docs/research/QVM_TRACE_REWIND_BATCH.md

@@ -49,3 +49,6 @@ Native collision responses in the composed trace fixtures are explicitly supplie
 8. Recover reached damage 211239 and the tagged trace branch's event 64/normal encoding consumers. Reuse actual allocation without inventing health, penetration or impact effects.
 9. Recover `player_bb` expiry callback 277400 and entity free-time behavior. Continue query 276433, base construction after allocation, and grenade 223156 lifecycle as separate bounded follow-ups.
 10. Capture original executable/native/DLL reference traces and connect a verified gameplay path to Rust. Continue asset/map/model/texture/shader/audio/network analysis and macOS/Linux Bevy/Solari rendering and runtime work; these fixtures do not complete the game.
+
+
+Follow-up: the [RE-637–646 history/pellet batch](QVM_HISTORY_PELLET_BATCH.md) completes bounded history rewind/restore and the supplied-world event57 path. Use its next ten tasks for current unresolved work.

docs/research/README.md

@@ -537,3 +537,9 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-645: Statistic category maps and complete no-target bookkeeping](QVM_NO_TARGET_STATS.md). Reproduce with `python3 scripts/analyze_qvm_no_target_stats.py`; check with `python3 scripts/test_qvm_no_target_stats.py`.
+
+
+[RE-637–646 history/pellet batch and current next ten tasks](QVM_HISTORY_PELLET_BATCH.md): complete bounded history rewind/trace composition, twenty-pellet seed carry, no-target statistics and allocated event57 caller continuation.
+
+
+[RE-646: Allocated event57 twenty-world-pellet bookkeeping and caller continuation](QVM_EVENT57_WORLD_RETURN.md). Reproduce with `python3 scripts/analyze_qvm_event57_world_return.py`; check with `python3 scripts/test_qvm_event57_world_return.py`.

scripts/analyze_qvm_event57_world_return.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Allocated event57→twenty supplied-world pellets→statistics→caller boundary."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute,constants
+from qvm_trace_support import resume
+from qvm_server_fire_support import ENTITY,FORWARD,MUZZLE,state
+from analyze_qvm_allocated_event import event,setup
+from analyze_qvm_server_shot_setup import random_word,LOCAL as OUTER
+from analyze_qvm_twenty_pellets import pellets
+from analyze_qvm_no_target_stats import no_target_stats,prepare
+from analyze_qvm_shot_frame import LOCAL as SHOT
+from analyze_qvm_temp_event import record
+from analyze_qvm_acceleration import PS,word
+from analyze_qvm import write_json
+class SuspendedShot(Exception):
+    def __init__(self,m,report):self.memory=m;self.report=report
+
+def shot_world(ins,m,args):
+    m,p=pellets(ins,m,args)
+    if p['status']!='no-target-bookkeeping-pending':return m,{'pellet_stage':p,'status':p['status'],'bookkeeping':None,'continuation':None}
+    stats=[]
+    def bookkeeping(i,m,a):m,e=no_target_stats(i,m,a);stats.append(e);return m,0,{'bookkeeping_index':len(stats)-1,'completed_void_boundary':True}
+    m,e=resume(ins,295019,296197,m,SHOT,pc=296176,handlers={279820:bookkeeping})
+    return m,{'pellet_stage':p,'bookkeeping':stats[0],'continuation':e,'status':'void-epilogue'}
+
+def chain(ins,m):
+    m=dict(m);initial=state(m);seed=m[21044]&0xffffffff;m[OUTER+52]=ENTITY;events=[];shots=[];rng=[]
+    def allocated(i,m,a,c):
+        assert a[8]==MUZZLE;m,e=event(i,m,a[12]);events.append(e);return m,c,e['execution']['return'],{'event_index':len(events)-1,'return':e['execution']['return']}
+    def random(i,m,a,c):m,e=random_word(i,m);rng.append(e);return m,c,e['result'],e
+    def shot(i,m,a,c):
+        m,e=shot_world(i,m,a);e['arguments']=a;shots.append(e)
+        if e['status']!='void-epilogue':raise SuspendedShot(m,e)
+        return m,c,0,{'shot_index':len(shots)-1,'completed_void_boundary':True}
+    try:m,_,outer=execute(ins,285841,285969,m,(0,0,0),OUTER,{277695:allocated,36717:random,295018:shot});status='outer-void-epilogue'
+    except SuspendedShot as pending:m=pending.memory;outer=None;status=pending.report['status']
+    e=events[0];return m,{'initial':initial,'initial_global_seed':seed,'final_global_seed':m[21044]&0xffffffff,'event':{k:v for k,v in e.items() if k!='allocation'},'event_record':record(m,e['execution']['return']),'rng':rng[0],'shot':shots[0],'outer_execution':outer,'status':status,'native_collision_executed':False}
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for forward,rng in list(itertools.product([(1,0,0),(.6,-.25,.8)],[0,0x12345678]))+[((0,0,0),1)]:
+        m=setup(raw,h);m.update(constants(raw,h,range(32856,33364,4)));m[ENTITY+192]=4;m[ENTITY+424]=8;m[PS+312]=4;m[21044]=rng;m[34082500]=0;m[34992580]=0;m=prepare(raw,h,m)
+        for j,v in enumerate(forward):m[FORWARD+4*j]=word(v)
+        for j in range(20):
+            for o in range(0,76,4):m[PS+856+76*j+o]=0
+            m[PS+856+76*j]=10 if rng else 0;m[PS+856+76*j+4]=7 if rng else 0
+        rows.append(chain(ins,m)[1])
+    write_json(Path('docs/research/qvm-event57-world-return.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Actual direct285840 handler→allocated event→295018 twenty supplied-world pellets→no-target279820→void caller boundary. Explicit source-pool attacker/client fixture binding. Native world responses supplied, link/registration captured; no model/contact/damage, native collision, full tick or playable game parity. Zero direction suspends caller.'})
+if __name__=='__main__':main()

scripts/test_qvm_event57_world_return.py

@@ -0,0 +1,22 @@
+import json,copy,unittest
+from pathlib import Path
+from test_qvm_temp_event import event_record
+from test_qvm_server_shot_setup import random_oracle
+from test_qvm_ground import word,n,f
+class Event57WorldReturnTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-event57-world-return.json').read_text())
+    def test_full_allocated_event_and_global_seed_oracle(self):
+        for p in self.r['probes']:
+            expected=event_record(p['event']);seed,value=random_oracle(p['initial_global_seed'])
+            for j,v in enumerate(p['initial']['forward']):expected[str(104+4*j)]=word(float(int(f(n(v)*4096))))
+            expected.update({'184':value&255,'140':7,'192':4});self.assertEqual(p['event_record'],expected);self.assertEqual(p['final_global_seed'],seed);self.assertEqual(p['shot']['arguments'],{'8':589824,'12':34147688+24,'16':34147688+104,'20':value&255})
+    def test_twenty_traces_and_actual_bookkeeping_caller_continuation(self):
+        for p in self.r['probes'][:-1]:
+            self.assertEqual(p['status'],'outer-void-epilogue');self.assertEqual(len(p['shot']['pellet_stage']['pellets']),20);self.assertEqual([c['target'] for c in p['shot']['continuation']['calls']],[279820]);self.assertEqual([c['target'] for c in p['outer_execution']['calls']],[277695,36717,295018]);self.assertEqual(p['shot']['bookkeeping']['arguments'],p['shot']['pellet_stage']['pending_bookkeeping']['arguments'])
+    def test_independent_entire_stats_record_update_once(self):
+        for p in self.r['probes'][:-1]:
+            r=p['shot']['bookkeeping'];expected=copy.deepcopy(r['initial']);row=expected[str(r['weapon_category'])];row['0']+=1;row['4']+=1;row['56']=word(f(100-f(f(float(row['4'])/float(row['0']))*100)));self.assertEqual(r['final'],expected)
+    def test_zero_direction_never_returns_or_updates_statistics(self):
+        p=self.r['probes'][-1];self.assertEqual(p['status'],'zero-direction-division-boundary');self.assertIsNone(p['outer_execution']);self.assertIsNone(p['shot']['bookkeeping']);self.assertTrue(all(not p['native_collision_executed'] for p in self.r['probes']))
+if __name__=='__main__':unittest.main()