qvm: contact event announcement gates

docs/ASSET_PIPELINE_TODO.md

@@ -811,3 +811,6 @@ Research progress: RE-714 [report](research/QVM_CONTACT_FACTOR.md); remaining na
 
 
 Research progress: RE-715 [report](research/QVM_CONTACT_SPECIAL.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-716 [report](research/QVM_CONTACT_ANNOUNCEMENT.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -1157,3 +1157,6 @@ RE-703–712 batch complete: [damage factor and contact dispatch](research/QVM_D
 
 
 **RE-715 — Special weapon4 contact classification:** The special contact path fixes scalar1, reads the first context category and reclassifies head/torso through actual inventory, without invoking289594 or changing its accumulator. [Evidence](research/QVM_CONTACT_SPECIAL.md).
+
+
+**RE-716 — Contact event and announcement gates:** Events require nonzero caller flag and scalar; announcement7259 additionally requires34081316 and clear victim client220 bit16384/entity552 bit16. [Evidence](research/QVM_CONTACT_ANNOUNCEMENT.md).

docs/PROVISIONAL_TODO.md

@@ -1146,3 +1146,6 @@ Research progress: RE-714 [report](research/QVM_CONTACT_FACTOR.md); remaining na
 
 
 Research progress: RE-715 [report](research/QVM_CONTACT_SPECIAL.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-716 [report](research/QVM_CONTACT_ANNOUNCEMENT.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -1215,3 +1215,8 @@ Ordinary292545 now calls complete289594, multiplies its returned float factor by
 ## 2026-10-21 — RE-715 Special weapon4 contact classification (separate task commit)
 
 The special contact path fixes scalar1, reads the first context category and reclassifies head/torso through actual inventory, without invoking289594 or changing its accumulator. 224 category/client/health/slot combinations check scalar, classifier decisions, exact item queries and exclusion of slot16. Full suite: 1308 tests pass. Report regenerates byte-identically (215339 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-716 Contact event and announcement gates (separate task commit)
+
+Events require nonzero caller flag and scalar; announcement7259 additionally requires34081316 and clear victim client220 bit16384/entity552 bit16. 144 gate combinations check continuation, announcement truth table, original format and every call argument. Full suite: 1312 tests pass. Report regenerates byte-identically (123916 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

@@ -1189,3 +1189,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-715 Special weapon4 contact classification ([report](research/QVM_CONTACT_SPECIAL.md)).
+
+
+- [x] RE-716 Contact event and announcement gates ([report](research/QVM_CONTACT_ANNOUNCEMENT.md)).

docs/research/QVM_CONTACT_ANNOUNCEMENT.md

@@ -0,0 +1,7 @@
+# Contact event and announcement gates
+
+RE-716. Reproduce with `python3 scripts/analyze_qvm_contact_announcement.py`; check with `python3 scripts/test_qvm_contact_announcement.py`. The [machine report](qvm-contact-announcement.json) retains source identity and bounded fixtures.
+
+Actual292833–292916 bypasses events to293373 when caller148 is zero or scalar56 compares equal to float zero. Negative explicit scalar fixtures still pass this gate. Announcement7259 is conditional on global34081316 and clear victim client220 bit16384 plus entity552 bit16. Its eight arguments are original format97459, target ID, attacker ID, location, weapon, attacker client504 name pointer, victim client504 name pointer, and original3704+4×location label pointer. The request is captured without executing formatting/output effects. Announcement suppression does not suppress the event continuation at292917. No event allocation or health damage occurs in this range.
+
+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

@@ -747,3 +747,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-715: Special weapon4 contact classification](QVM_CONTACT_SPECIAL.md). Reproduce with `python3 scripts/analyze_qvm_contact_special.py`; check with `python3 scripts/test_qvm_contact_special.py`.
+
+
+[RE-716: Contact event and announcement gates](QVM_CONTACT_ANNOUNCEMENT.md). Reproduce with `python3 scripts/analyze_qvm_contact_announcement.py`; check with `python3 scripts/test_qvm_contact_announcement.py`.

scripts/analyze_qvm_contact_announcement.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""Contact event eligibility and conditional announcement call arguments."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source
+from qvm_contact_support import seed,run
+from analyze_qvm import write_json
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for flag,scalar,announce,client_flags,entity_flags,loc in itertools.product([0,1],[-1,0,1],[0,1],[0,16384],[0,16],[1,3,14]):
+        a=dict(flag=flag,scalar=scalar,announce=announce,client_flags=client_flags,entity_flags=entity_flags,location=loc);m=seed(raw,h,**a);label=m[3704+4*loc];_,p=run(ins,m,292833,293373,boundaries=[292917]);p.update(input=a,location_label_pointer=label);rows.append(p)
+    text=raw[h['data_offset']+97459:].split(b'\0',1)[0].decode()
+    write_json(Path('docs/research/qvm-contact-announcement.json'),{'source':q['source'],'sha256':q['sha256'],'format':{'address':97459,'text':text},'probes':rows,'limits':'Actual292833..292916;7259 request captured without formatting/output effects. Stops before event or at dispatch continuation. Explicit nonnull clients for announcement branch.'})
+if __name__=='__main__':main()

scripts/test_qvm_contact_announcement.py

@@ -0,0 +1,20 @@
+import json,unittest
+from pathlib import Path
+from qvm_contact_support import A_CLIENT,V_CLIENT
+class ContactAnnouncementTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-contact-announcement.json').read_text());cls.ps=cls.r['probes']
+    def test_event_gate_independent_of_announcement(self):
+        for p in self.ps:
+            a=p['input'];self.assertEqual(p['execution']['stop'],292917 if a['flag'] and a['scalar']!=0 else 293373)
+    def test_announcement_flag_truth_table(self):
+        for p in self.ps:
+            a=p['input'];wanted=bool(a['flag'] and a['scalar']!=0 and a['announce'] and not a['client_flags']&16384 and not a['entity_flags']&16);self.assertEqual(len(p['effects']['announcements']),int(wanted))
+    def test_exact_eight_argument_request(self):
+        for p in self.ps:
+            for c in p['effects']['announcements']:self.assertEqual(c['arguments'],{'8':97459,'12':65,'16':7,'20':p['input']['location'],'24':3,'28':A_CLIENT+504,'32':V_CLIENT+504,'36':p['location_label_pointer']})
+    def test_source_format_and_no_event_or_health_execution(self):
+        from qvm_research_support import source
+        _,raw,h,_=source();self.assertEqual(self.r['format']['text'],raw[h['data_offset']+97459:].split(b'\0',1)[0].decode());self.assertEqual(len(self.ps),144)
+        for p in self.ps:self.assertEqual(p['effects']['events'],[]);self.assertEqual(p['effects']['damage'],[])
+if __name__=='__main__':unittest.main()