qvm: special trace request

docs/ASSET_PIPELINE_TODO.md

@@ -409,3 +409,6 @@ Research progress: RE-572 [report](research/QVM_WEAPON_SELECT.md); remaining nat
 
 
 Research progress: RE-573 [report](research/QVM_WEAPON_COMPLETE.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-574 [report](research/QVM_SPECIAL_QUERY.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -767,3 +767,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-573 — Weapon transition completion and fallback contract:** 49028 looks up command weapon byte then fallbackID1, writes the returned slot without checking a second−1, sets state1, adds250 to timer, requests torso55 and emits30/parameter1. [Evidence](research/QVM_WEAPON_COMPLETE.md).
+
+
+**RE-574 — Helper50525 native trace gates and event contract:** 50525 clears PS12 bit8192 on low up input or, after ordered gates, traces30 units ahead from originZ+30; contents33554432 sets state4096 and queues14 with native record+52 as parameter. [Evidence](research/QVM_SPECIAL_QUERY.md).

docs/PROVISIONAL_TODO.md

@@ -723,3 +723,6 @@ Research progress: RE-572 [report](research/QVM_WEAPON_SELECT.md); remaining nat
 
 
 Research progress: RE-573 [report](research/QVM_WEAPON_COMPLETE.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-574 [report](research/QVM_SPECIAL_QUERY.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -561,3 +561,8 @@ Actual54444 reload/interaction order exposes timer interference before the weapo
 ## 2026-10-20 — RE-573 Weapon transition completion and fallback contract (separate task commit)
 
 49028 looks up command weapon byte then fallbackID1, writes the returned slot without checking a second−1, sets state1, adds250 to timer, requests torso55 and emits30/parameter1. 52 probes independently check requested/fallback priority, slot15, missing fallback, signed timer overflow, type/timer animation gates and event parameter1. Full suite: 811 tests pass. Report regenerates byte-identically (670259 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-574 Helper50525 native trace gates and event contract (separate task commit)
+
+50525 clears PS12 bit8192 on low up input or, after ordered gates, traces30 units ahead from originZ+30; contents33554432 sets state4096 and queues14 with native record+52 as parameter. 80 fixtures check level/type/input priority, strict vertical speed, suppression fields, native request geometry/ABI and signed parameter preservation; direct main caller54020 is inventoried. Full suite: 815 tests pass. Report regenerates byte-identically (271030 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

@@ -763,3 +763,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-573 Weapon transition completion and fallback contract ([report](research/QVM_WEAPON_COMPLETE.md)).
+
+
+- [x] RE-574 Helper50525 native trace gates and event contract ([report](research/QVM_SPECIAL_QUERY.md)).

docs/research/QVM_SPECIAL_QUERY.md

@@ -0,0 +1,11 @@
+# Helper50525 native trace gates and event contract
+
+RE-574. Reproduce with `python3 scripts/analyze_qvm_special_query.py`; check with `python3 scripts/test_qvm_special_query.py`. The [machine report](qvm-special-query.json) retains source identity and bounded fixtures.
+
+Complete50525 runs through50743. Level>1 and types2/3 reject before any input write. Up<10 clears PS12 bit8192 and returns. Otherwise forward>=10, FRAME232=0, absent state4096, absent button64 and vertical velocity>0 are required. At equality up/forward10 pass, velocity0 rejects.
+
+The actual dynamic native trace target is supplied−25 from FRAME224. Start=origin with Z+30, end=start+30×forward basis; frame bounds184..204, entity7 and mask100663297 match its source request. Reply is an explicitly supplied56-byte record. Contents+48 bit33554432 sets state4096 and queues event14 with parameter from+52, preserving its32-bit value. The source does not establish native geometry or gameplay meaning of that parameter.
+
+The direct CONST50525/CALL inventory finds main instruction54020; dynamic references are outside this inventory.80 probes check all ordered gates and queue effects. Remaining: original collision-consistent records and legal writers for FRAME232, state4096 and flag8192; integrate actual main prefix only after its earlier setup effects are known.
+
+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

@@ -324,3 +324,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-573: Weapon transition completion and fallback contract](QVM_WEAPON_COMPLETE.md). Reproduce with `python3 scripts/analyze_qvm_weapon_complete.py`; check with `python3 scripts/test_qvm_weapon_complete.py`.
+
+
+[RE-574: Helper50525 native trace gates and event contract](QVM_SPECIAL_QUERY.md). Reproduce with `python3 scripts/analyze_qvm_special_query.py`; check with `python3 scripts/test_qvm_special_query.py`.

scripts/analyze_qvm_special_query.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Complete50525 ordered gates,30-unit native trace and parameterized event14."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute
+from qvm_weapon_support import weapon_seed,weapon_state
+from qvm_suffix_support import handlers
+from analyze_qvm_acceleration import PS,FRAME,word
+from analyze_qvm_slide_prefix import vec
+from analyze_qvm import write_json
+LOCAL=0x76000000
+
+def special_query(ins,m,cmd,contents=33554432,parameter=27):
+    initial=weapon_state(m);origin=vec(m,PS+20);basis=vec(m,35023892);vz=m[PS+40];queries=[]
+    def trace(i,m,a,c):
+        q={'start':vec(m,a[12]),'end':vec(m,a[24]),'bounds':vec(m,a[16])+vec(m,a[20]),'entity':a[28],'mask':a[32],'contents':contents,'parameter':parameter};queries.append(q)
+        for o in range(0,56,4):m[a[8]+o]=0
+        m[a[8]+48]=contents;m[a[8]+52]=parameter;return m,c,0,q
+    hs=handlers();hs[-25]=trace;m,c,r=execute(ins,50526,50744,m,cmd,LOCAL,hs)
+    return m,{'initial':initial,'commands':list(cmd),'level':m[FRAME+212],'kind':m[PS+4],'buttons':m[FRAME+20],'vertical_velocity':vz,'origin':origin,'basis':basis,'contents':contents,'parameter':parameter,'queries':queries,'execution':r,'final':weapon_state(m)}
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for level,kind,up,fw,contents in itertools.product([0,1,2],[0,2,3],[9,10],[9,10],[0,33554432]):
+        cmd=(fw,0,up);m=weapon_seed(raw,h,cmd);m.update({FRAME+212:level,PS+4:kind,PS+12:8192,PS+40:word(10),FRAME+20:0});rows.append(special_query(ins,m,cmd,contents)[1])
+    for changes,cmd,param in [({FRAME+232:1},(10,0,10),27),({PS+220:4096},(10,0,10),27),({FRAME+20:64},(10,0,10),27),({PS+40:word(0)},(10,0,10),27),({PS+40:word(-1)},(10,0,10),27),({},(10,0,-128),27),({},(10,0,10),0),({},(10,0,10),-1)]:
+        m=weapon_seed(raw,h,cmd);m.update({FRAME+212:0,PS+12:8192,PS+40:word(10),FRAME+20:0});m.update(changes);rows.append(special_query(ins,m,cmd,parameter=param)[1])
+    sites=[i['index']+1 for i in ins[:-1] if i['opcode']=='CONST' and i['operand']==50525 and ins[i['index']+1]['opcode']=='CALL']
+    write_json(Path('docs/research/qvm-special-query.json'),{'source':q['source'],'sha256':q['sha256'],'direct_call_sites':sites,'probes':rows,'limits':'Complete finite50525 with supplied trace56 native reply;30-unit geometry and consumed offsets verified, actual collision and interaction identity not inferred. Only direct CONST/CALL sites inventoried.'})
+if __name__=='__main__':main()

scripts/test_qvm_special_query.py

@@ -0,0 +1,29 @@
+import json,unittest,copy
+from pathlib import Path
+from test_qvm_ground import word,n,f
+from test_qvm_water_events import enqueue
+
+def reaches(p):
+    a=p['initial'];fw,_,up=p['commands'];return p['level']<=1 and p['kind'] not in [2,3] and up>=10 and fw>=10 and a['frame232']==0 and not a['state220']&4096 and not p['buttons']&64 and n(p['vertical_velocity'])>0
+class SpecialQueryTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-special-query.json').read_text())
+    def test_gate_priority_clear_and_exact_state(self):
+        self.assertEqual(len(self.r['probes']),80)
+        for p in self.r['probes']:
+            a=copy.deepcopy(p['initial'])
+            if p['level']<=1 and p['kind'] not in [2,3] and p['commands'][2]<10:a['flags']&=~8192
+            if reaches(p) and p['contents']&33554432:
+                a['state220']|=4096;slot=a['queue']['sequence']&1;a['queue']=enqueue(a['queue'],[14]);a['queue']['parameters'][slot]=p['parameter']&0xffffffff
+            self.assertEqual(p['final'],a)
+    def test_native_trace_request_geometry_and_contract(self):
+        for p in self.r['probes']:
+            self.assertEqual(len(p['queries']),int(reaches(p)))
+            for q in p['queries']:
+                start=p['origin'][:];start[2]=word(f(n(start[2])+30));end=[word(f(n(x)+f(n(d)*30))) for x,d in zip(start,p['basis'])];self.assertEqual(q['start'],start);self.assertEqual(q['end'],end);self.assertEqual((q['entity'],q['mask']),(7,100663297))
+    def test_actual_parameterized_event_child_order(self):
+        for p in self.r['probes']:
+            hit=reaches(p) and p['contents']&33554432;self.assertEqual([c['target'] for c in p['execution']['calls']],([-25,29913] if hit else [-25]) if reaches(p) else [])
+            if hit:self.assertEqual(p['execution']['calls'][-1]['args'],{'8':14,'12':p['parameter'],'16':65536})
+    def test_direct_main_call_site(self):self.assertEqual(self.r['direct_call_sites'],[54020])
+if __name__=='__main__':unittest.main()