qvm: damage caps and pellet accumulation

docs/ASSET_PIPELINE_TODO.md

@@ -781,3 +781,6 @@ Research progress: RE-704 [report](research/QVM_DAMAGE_RANGE.md); remaining nati
 
 
 Research progress: RE-705 [report](research/QVM_DAMAGE_ATTENUATION.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-706 [report](research/QVM_DAMAGE_CLAMP.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -1127,3 +1127,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-705 — Weapon24 distance attenuation:** Weapon24 preserves the factor below half range, linearly falls to float32 0.1 by full range, and stays at that floor thereafter; zero range takes the floor without division. [Evidence](research/QVM_DAMAGE_ATTENUATION.md).
+
+
+**RE-706 — Damage saturation and weapon4 accumulation:** Positive damage factors cap at1 and weapon4 additionally caps at float32 0.35; its optional accumulator adds that capped factor without a total clamp. Nonpositive factors return zero immediately. [Evidence](research/QVM_DAMAGE_CLAMP.md).

docs/PROVISIONAL_TODO.md

@@ -1116,3 +1116,6 @@ Research progress: RE-704 [report](research/QVM_DAMAGE_RANGE.md); remaining nati
 
 
 Research progress: RE-705 [report](research/QVM_DAMAGE_ATTENUATION.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-706 [report](research/QVM_DAMAGE_CLAMP.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -1167,3 +1167,8 @@ A dependency-free Rust asset crate parses all619 originals with Python parity fo
 ## 2026-10-21 — RE-705 Weapon24 distance attenuation (separate task commit)
 
 Weapon24 preserves the factor below half range, linearly falls to float32 0.1 by full range, and stays at that floor thereafter; zero range takes the floor without division. 315 piecewise boundary/weapon/factor probes pass exact float32 independent oracles. Full suite: 1271 tests pass. Report regenerates byte-identically (473777 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-706 Damage saturation and weapon4 accumulation (separate task commit)
+
+Positive damage factors cap at1 and weapon4 additionally caps at float32 0.35; its optional accumulator adds that capped factor without a total clamp. Nonpositive factors return zero immediately. 144 finite factor/weapon/pointer/accumulator combinations pass exact saturation and additive oracles. Full suite: 1275 tests pass. Report regenerates byte-identically (215368 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

@@ -1159,3 +1159,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-705 Weapon24 distance attenuation ([report](research/QVM_DAMAGE_ATTENUATION.md)).
+
+
+- [x] RE-706 Damage saturation and weapon4 accumulation ([report](research/QVM_DAMAGE_CLAMP.md)).

docs/research/QVM_DAMAGE_CLAMP.md

@@ -0,0 +1,7 @@
+# Damage saturation and weapon4 accumulation
+
+RE-706. Reproduce with `python3 scripts/analyze_qvm_damage_clamp.py`; check with `python3 scripts/test_qvm_damage_clamp.py`. The [machine report](qvm-damage-clamp.json) retains source identity and bounded fixtures.
+
+Actual289953–290001 clamps factors at1, returns zero at nonpositive values, and caps positive weapon4 factors to word1050253722 (float32 0.35). Weapon4 with a nonnull extra pointer adds that factor to its existing float32 value. The accumulator can exceed1 and accepts explicit negative starting fixtures; no total clamp occurs in this range. The separately computed cubic local36 is not consumed by this slice. Later caller event clamping and legal runtime domains remain separate questions. No calls or health writes occur.
+
+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

@@ -717,3 +717,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-705: Weapon24 distance attenuation](QVM_DAMAGE_ATTENUATION.md). Reproduce with `python3 scripts/analyze_qvm_damage_attenuation.py`; check with `python3 scripts/test_qvm_damage_attenuation.py`.
+
+
+[RE-706: Damage saturation and weapon4 accumulation](QVM_DAMAGE_CLAMP.md). Reproduce with `python3 scripts/analyze_qvm_damage_clamp.py`; check with `python3 scripts/test_qvm_damage_clamp.py`.

scripts/analyze_qvm_damage_clamp.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""Damage factor saturation, weapon4 cap and optional pellet accumulation."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source
+from qvm_damage_support import seed,run,L
+from analyze_qvm_acceleration import word
+from analyze_qvm import write_json
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for w,factor,extra,pointer in itertools.product([3,4,24],[-1,0,0.00001,0.2,0.35,0.35001,1,2],[-0.25,0,0.9],[False,True]):
+        a=dict(weapon=w,factor=factor,extra=extra,pointer=pointer);m=seed(raw,h,**a)
+        if not pointer:m[L+112]=0
+        _,p=run(ins,m,289953,290002);p['input']=a;rows.append(p)
+    write_json(Path('docs/research/qvm-damage-clamp.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Actual289953..290001 finite factors. Extra pointer explicitly supplied/null. Accumulator is not capped here. No later wound/health execution.'})
+if __name__=='__main__':main()

scripts/test_qvm_damage_clamp.py

@@ -0,0 +1,24 @@
+import json,unittest
+from pathlib import Path
+from test_qvm_ground import word,n,f
+class DamageClampTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.ps=json.loads(Path('docs/research/qvm-damage-clamp.json').read_text())['probes']
+    def test_independent_saturation_cap_and_early_zero(self):
+        for p in self.ps:
+            a=p['input'];v=f(a['factor']);v=min(v,1.)
+            if a['weapon']==4 and v>0:v=min(v,n(1050253722))
+            self.assertEqual(p['final']['locals']['20'],word(v))
+            self.assertEqual(p['execution']['return'],0 if a['factor']<=0 else None)
+    def test_accumulate_only_positive_weapon_four_nonnull(self):
+        for p in self.ps:
+            a=p['input'];v=f(a['extra'])
+            if a['weapon']==4 and a['factor']>0 and a['pointer']:v=f(v+n(p['final']['locals']['20']))
+            self.assertEqual(p['final']['extra'],word(v))
+    def test_accumulator_can_exceed_one(self):
+        ps=[p for p in self.ps if p['input']==dict(weapon=4,factor=2,extra=0.9,pointer=True)]
+        self.assertEqual(len(ps),1);self.assertGreater(n(ps[0]['final']['extra']),1)
+    def test_no_calls_and_early_stop(self):
+        for p in self.ps:
+            self.assertEqual(p['execution']['calls'],[]);self.assertEqual(p['execution']['stop'],290002)
+if __name__=='__main__':unittest.main()