qvm: terminal health callbacks and caps

docs/ASSET_PIPELINE_TODO.md

@@ -853,3 +853,6 @@ Research progress: RE-728 [report](research/QVM_HEALTH_INTERCEPTS.md); original
 
 
 Research progress: RE-729 [report](research/QVM_HEALTH_MUTATION.md); original assets unchanged.
+
+
+Research progress: RE-730 [report](research/QVM_HEALTH_TERMINAL.md); original assets unchanged.

docs/FINDINGS.md

@@ -1199,3 +1199,6 @@ RE-714–723 batch complete: [complete contact and health prefixes](research/QVM
 
 
 **RE-729 — Ordinary health subtraction and protected publication:** Ordinary damage subtracts selected damage, optionally floors protected health at5 while clearing client flags, publishes attacker/location and mirrors health to client208; actual211197 drains client184 by300×damage with floor0. [Evidence](research/QVM_HEALTH_MUTATION.md).
+
+
+**RE-730 — Terminal health callbacks and packed meter cap:** Terminal processing caps client228 low16 values above500 (except method26), clamps dead health at−999, records killer pointer and issues pain/death/impulse requests with distinct ABIs and ordering. [Evidence](research/QVM_HEALTH_TERMINAL.md).

docs/PROVISIONAL_TODO.md

@@ -1188,3 +1188,6 @@ Research progress: RE-728 [report](research/QVM_HEALTH_INTERCEPTS.md); full nati
 
 
 Research progress: RE-729 [report](research/QVM_HEALTH_MUTATION.md); full native/platform/game scope remains open.
+
+
+Research progress: RE-730 [report](research/QVM_HEALTH_TERMINAL.md); full native/platform/game scope remains open.

docs/RESEARCH_LEDGER.md

@@ -1288,3 +1288,8 @@ Mode10 can divert distinct live-client lethal damage to206128, while method24/gl
 ## 2026-10-21 — RE-729 Ordinary health subtraction and protected publication
 
 Ordinary damage subtracts selected damage, optionally floors protected health at5 while clearing client flags, publishes attacker/location and mirrors health to client208; actual211197 drains client184 by300×damage with floor0. Focused `cargo xtask test-group health` passes (28 Python tests); selected reports regenerate twice byte-identically, with storage, links and whitespace guards. New report: 580637 bytes. Full-suite validation is deferred to the tenth batch commit. No original assets, Rust runtime or shared VM evaluator changed.
+
+
+## 2026-10-21 — RE-730 Terminal health callbacks and packed meter cap
+
+Terminal processing caps client228 low16 values above500 (except method26), clamps dead health at−999, records killer pointer and issues pain/death/impulse requests with distinct ABIs and ordering. Focused `cargo xtask test-group health` passes (32 Python tests); selected reports regenerate twice byte-identically, with storage, links and whitespace guards. New report: 707250 bytes. Full-suite validation is deferred to the tenth batch commit. No original assets, Rust runtime or shared VM evaluator changed.

docs/REVERSE_ENGINEERING_TODO.md

@@ -1231,3 +1231,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-729 Ordinary health subtraction and protected publication ([report](research/QVM_HEALTH_MUTATION.md)).
+
+
+- [x] RE-730 Terminal health callbacks and packed meter cap ([report](research/QVM_HEALTH_TERMINAL.md)).

docs/research/QVM_HEALTH_TERMINAL.md

@@ -0,0 +1,7 @@
+# Terminal health callbacks and packed meter cap
+
+RE-730. Reproduce with `python3 scripts/analyze_qvm_health_terminal.py`; validate with `cargo xtask test-group health`. See the [machine report](qvm-health-terminal.json).
+
+Actual212800–213006 caps client228 low16 values above500 to exactly500, clearing upper bits, unless method26. Lethal health first requests213009, then floors target health at−999, records attacker720 and optionally captures target664 death callback with location for clients or selected damage for nonclients. Positive health optionally captures target660 pain callback and, for methods16/43/22/25/29/24/37, zeros direction z before requesting213009. The132 fixtures independently check request order and signatures, packed preservation, health clamp and zero-z behavior. Impulse and callback effects are captured at this stage; target/client mirrored health consistency across the later clamp remains a complete-call question.
+
+No original executable/full VM/native world collision or rendering runs. Supplied callback/native responses and fixture domains remain explicit; complete macOS/Linux Rust/Bevy/Solari gameplay remains open.

docs/research/README.md

@@ -789,3 +789,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-729: Ordinary health subtraction and protected publication](QVM_HEALTH_MUTATION.md).
+
+
+[RE-730: Terminal health callbacks and packed meter cap](QVM_HEALTH_TERMINAL.md).

scripts/analyze_qvm_health_terminal.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Packed meter cap, terminal pain/death requests and impulse handoff."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source
+from qvm_health_effects_support import seed,run
+from analyze_qvm import write_json
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    cases=[dict(health=health,method=method,packed=packed,pain=True,death=True,direction=(3,4,7)) for health,method,packed in itertools.product([-2000,-1,0,1,100],[12,16,22,24,26,37],[0x50001,0x501f4,0x501f5,0x5ffff])]
+    cases += [dict(health=health,pain=pain,death=death,client=False,direction=(3,4,7)) for health,pain,death in itertools.product([-1000,0,1],[False,True],[False,True])]
+    for a in cases:
+        _,p=run(ins,seed(raw,h,**a),212800,213007);p['input']=a;rows.append(p)
+    write_json(Path('docs/research/qvm-health-terminal.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Actual212800..213006 to void-exit boundary. Pain/death callbacks and213009 impulse captured; no callback/velocity effects supplied. Nonclient fixtures enter only this guarded terminal slice.'})
+if __name__=='__main__':main()

scripts/test_qvm_health_terminal.py

@@ -0,0 +1,27 @@
+import json,unittest
+from pathlib import Path
+from qvm_health_effects_support import TARGET,ATTACKER,DIRECTION,PAIN,DEATH
+from test_qvm_ground import word
+class HealthTerminalTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.ps=json.loads(Path('docs/research/qvm-health-terminal.json').read_text())['probes']
+    def test_packed_low_word_cap_and_health_clamp(self):
+        for p in self.ps:
+            a=p['input'];packed=a.get('packed',0x50001);packed=500 if a.get('method',12)!=26 and packed&65535>500 else packed
+            if p['final']['client'] is not None:self.assertEqual(p['final']['client']['228'],packed)
+            health=a['health'];self.assertEqual(p['final']['entity']['684'],(max(-999,health) if health<=0 else health)&0xffffffff);self.assertEqual(p['final']['entity']['720'],ATTACKER if health<=0 else 0)
+    def test_pain_and_death_callback_abis(self):
+        for p in self.ps:
+            a=p['input'];dead=a['health']<=0;called=a.get('death',False) if dead else a.get('pain',False);self.assertEqual(len(p['effects']['callbacks']),int(called))
+            if called:
+                c=p['effects']['callbacks'][0];self.assertEqual(c['target'],DEATH if dead else PAIN);expected={'8':TARGET,'12':ATTACKER,'16':ATTACKER,'20':3 if a.get('client',True) else 100,'24':a.get('method',12)} if dead else {'8':TARGET,'12':ATTACKER,'16':100};self.assertEqual(c['arguments'],expected)
+    def test_alive_method_impulse_direction_and_call_order(self):
+        for p in self.ps:
+            a=p['input'];alive=a['health']>0;impulse=not alive or a.get('method',12) in (16,43,22,25,29,24,37);self.assertEqual(len(p['effects']['impulses']),int(impulse));direction=list(map(word,[3,4,7]));
+            if alive and impulse:direction[2]=0
+            self.assertEqual(p['final']['direction'],direction)
+            calls=[c['target'] for c in p['execution']['calls']];cb=[c['target'] for c in p['effects']['callbacks']];self.assertEqual(calls,([213009]+cb) if not alive else (cb+[213009] if impulse else cb))
+    def test_exit_boundary_and_unapplied_velocity(self):
+        self.assertEqual(len(self.ps),132)
+        for p in self.ps:self.assertEqual(p['execution']['stop'],213007)
+if __name__=='__main__':unittest.main()

xtask/checks.tsv

@@ -1153,3 +1153,5 @@ report	scripts/analyze_qvm_health_intercepts.py	docs/research/qvm-health-interce
 edge	docs/research/qvm-health-intercepts.json	scripts/test_qvm_health_intercepts.py
 report	scripts/analyze_qvm_health_mutation.py	docs/research/qvm-health-mutation.json
 edge	docs/research/qvm-health-mutation.json	scripts/test_qvm_health_mutation.py
+report	scripts/analyze_qvm_health_terminal.py	docs/research/qvm-health-terminal.json
+edge	docs/research/qvm-health-terminal.json	scripts/test_qvm_health_terminal.py