qvm: held item interruption and override

docs/ASSET_PIPELINE_TODO.md

@@ -793,3 +793,6 @@ Research progress: RE-708 [report](research/QVM_DAMAGE_ATTRIBUTION.md); remainin
 
 
 Research progress: RE-709 [report](research/QVM_DAMAGE_LOCATION_FLAGS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-710 [report](research/QVM_DAMAGE_INTERRUPT.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -1139,3 +1139,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-709 — Damage location jump table and client flags:** The original32796 jump table ORs client192 bit4 for locations1/2, bit1 for3/4/7/8, and bit2 for5/6/9–14; signed out-of-range locations bypass it. [Evidence](research/QVM_DAMAGE_LOCATION_FLAGS.md).
+
+
+**RE-710 — Held-item deadline and final factor override:** Held item low-byte14 at factor≥0.2 or23 at factor≥0.5 writes client6304=time+200 for nonleg locations; global34066516 returns1 after side effects. [Evidence](research/QVM_DAMAGE_INTERRUPT.md).

docs/PROVISIONAL_TODO.md

@@ -1128,3 +1128,6 @@ Research progress: RE-708 [report](research/QVM_DAMAGE_ATTRIBUTION.md); remainin
 
 
 Research progress: RE-709 [report](research/QVM_DAMAGE_LOCATION_FLAGS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-710 [report](research/QVM_DAMAGE_INTERRUPT.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -1187,3 +1187,8 @@ Active wounds record attacker pointer at target836 and weapon at client4300; cou
 ## 2026-10-21 — RE-709 Damage location jump table and client flags (separate task commit)
 
 The original32796 jump table ORs client192 bit4 for locations1/2, bit1 for3/4/7/8, and bit2 for5/6/9–14; signed out-of-range locations bypass it. 133 location/initial-flag fixtures verify every original branch target, signed bypass and preservation of unrelated fields. Full suite: 1287 tests pass. Report regenerates byte-identically (195933 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-710 Held-item deadline and final factor override (separate task commit)
+
+Held item low-byte14 at factor≥0.2 or23 at factor≥0.5 writes client6304=time+200 for nonleg locations; global34066516 returns1 after side effects. 167 item/threshold/location/override/client/clock fixtures pass independent float32, low-byte and signed-wrap oracles. Full suite: 1291 tests pass. Report regenerates byte-identically (252605 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

@@ -1171,3 +1171,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-709 Damage location jump table and client flags ([report](research/QVM_DAMAGE_LOCATION_FLAGS.md)).
+
+
+- [x] RE-710 Held-item deadline and final factor override ([report](research/QVM_DAMAGE_INTERRUPT.md)).

docs/research/QVM_DAMAGE_INTERRUPT.md

@@ -0,0 +1,7 @@
+# Held-item deadline and final factor override
+
+RE-710. Reproduce with `python3 scripts/analyze_qvm_damage_interrupt.py`; check with `python3 scripts/test_qvm_damage_interrupt.py`. The [machine report](qvm-damage-interrupt.json) retains source identity and bounded fixtures.
+
+Actual290374–290490 reads the active held-slot index client144 and low byte of client312+4×index. Item14 requires factor at least float32(0.2); item23 requires at least0.5. Locations11–14 suppress the client6304=time+200 write. Null clients bypass held reads. Deadline behavior is structurally recovered; its gameplay interpretation remains provisional. Global34066516 nonzero overrides the return to float32(1) only after these effects, leaving local factor and earlier effects intact. Explicit near-overflow clock fixtures expose32-bit wrap without asserting legal server clock domains. No health damage or external calls 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

@@ -729,3 +729,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-709: Damage location jump table and client flags](QVM_DAMAGE_LOCATION_FLAGS.md). Reproduce with `python3 scripts/analyze_qvm_damage_location_flags.py`; check with `python3 scripts/test_qvm_damage_location_flags.py`.
+
+
+[RE-710: Held-item deadline and final factor override](QVM_DAMAGE_INTERRUPT.md). Reproduce with `python3 scripts/analyze_qvm_damage_interrupt.py`; check with `python3 scripts/test_qvm_damage_interrupt.py`.

scripts/analyze_qvm_damage_interrupt.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""Held-item interruption deadlines and final damage-factor override."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source
+from qvm_damage_support import seed,run
+from analyze_qvm import write_json
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    cases=[dict(held=held,factor=factor,location=loc,override=override) for held,factor,loc,override in itertools.product([0,14,23,0xaa000e,0xaa0017],[0.19999,0.2,0.49999,0.5],[1,10,11,14],[0,1])]
+    cases += [dict(client=False,held=held,factor=1,override=override) for held,override in itertools.product([14,23],[0,1])]
+    cases += [dict(held=14,factor=0.2,now=now) for now in [-200,0,2147483600]]
+    for a in cases:
+        _,p=run(ins,seed(raw,h,**a),290374,290491);p['input']=a;rows.append(p)
+    write_json(Path('docs/research/qvm-damage-interrupt.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Actual290374..290490 with supplied factor/client/held inventory and clock. Deadline purpose is inferred; final override does not retroactively undo side effects.'})
+if __name__=='__main__':main()

scripts/test_qvm_damage_interrupt.py

@@ -0,0 +1,20 @@
+import json,unittest
+from pathlib import Path
+from test_qvm_ground import word,f,n
+class DamageInterruptTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.ps=json.loads(Path('docs/research/qvm-damage-interrupt.json').read_text())['probes']
+    def test_exact_threshold_item_mask_and_location_gates(self):
+        for p in self.ps:
+            a=p['input'];item=a['held']&255;v=f(a['factor']);active=a.get('client',True) and ((item==14 and v>=n(1045220557)) or (item==23 and v>=0.5)) and a.get('location',3) not in (11,12,13,14)
+            self.assertEqual(p['final']['client']['6304'],(a.get('now',5000)+200)&0xffffffff if active else 123)
+    def test_return_override_does_not_replace_local_factor(self):
+        for p in self.ps:
+            a=p['input'];self.assertEqual(p['execution']['return']&0xffffffff,word(1 if a.get('override',0) else a['factor']));self.assertEqual(p['final']['locals']['20'],word(a['factor']))
+    def test_signed_deadline_wrap(self):
+        p=next(p for p in self.ps if p['input'].get('now')==2147483600);self.assertEqual(p['final']['client']['6304'],2147483800)
+    def test_no_calls_or_other_tracked_state_changes(self):
+        self.assertEqual(len(self.ps),167)
+        for p in self.ps:
+            a=dict(p['initial']['client']);b=dict(p['final']['client']);a.pop('6304');b.pop('6304');self.assertEqual(a,b);self.assertEqual(p['execution']['calls'],[])
+if __name__=='__main__':unittest.main()