qvm: weapon slot lookup

docs/ASSET_PIPELINE_TODO.md

@@ -400,3 +400,6 @@ Research progress: RE-568 [report](research/QVM_LOCOMOTION.md); remaining native
 
 
 Research progress: RE-569 [report](research/QVM_MAIN_CONSUMERS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-571 [report](research/QVM_WEAPON_LOOKUP.md); remaining native/content/runtime/platform scope stays open.

docs/FINDINGS.md

@@ -758,3 +758,6 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 
 
 **RE-569 — Main request and independently bounded animation consumer chains:** Actual54444 reload/interaction order exposes timer interference before the weapon prefix; a separate54455 torso/locomotion/water segment verifies animation and queue overwrite order without bridging the unrecovered weapon body. [Evidence](research/QVM_MAIN_CONSUMERS.md).
+
+
+**RE-571 — Weapon slot lookup and numeric return contract:** 31691 searches the first16 packed weapon slots, compares their low bytes to the full requested integer and returns the first index or−1 without changing game state. [Evidence](research/QVM_WEAPON_LOOKUP.md).

docs/PROVISIONAL_TODO.md

@@ -714,3 +714,6 @@ The [RE-560–569 consumer batch](research/QVM_CONSUMER_BATCH.md) closes bounded
 
 
 Research progress: RE-569 [report](research/QVM_MAIN_CONSUMERS.md); remaining native/content/runtime/platform scope stays open.
+
+
+Research progress: RE-571 [report](research/QVM_WEAPON_LOOKUP.md); remaining native/content/runtime/platform scope stays open.

docs/RESEARCH_LEDGER.md

@@ -546,3 +546,8 @@ Complete47884 selects grounded stance/gait requests, advances a masked bob cycle
 ## 2026-10-20 — RE-569 Main request and independently bounded animation consumer chains (separate task commit)
 
 Actual54444 reload/interaction order exposes timer interference before the weapon prefix; a separate54455 torso/locomotion/water segment verifies animation and queue overwrite order without bridging the unrecovered weapon body. 24 request chains and18 independent animation chains check every live child handoff and exact state with independent task oracles, caller suspension and explicit no-full-tick scope. Full suite: 799 tests pass. Report regenerates byte-identically (1393581 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-571 Weapon slot lookup and numeric return contract (separate task commit)
+
+31691 searches the first16 packed weapon slots, compares their low bytes to the full requested integer and returns the first index or−1 without changing game state. 111 fixtures cover slot0/1/7/15, excluded slot16, duplicates, absent entries, upper-byte canaries and requests outside the low-byte range. Full suite: 803 tests pass. Report regenerates byte-identically (318642 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

@@ -754,3 +754,6 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 
 
 - [x] RE-569 Main request and independently bounded animation consumer chains ([report](research/QVM_MAIN_CONSUMERS.md)).
+
+
+- [x] RE-571 Weapon slot lookup and numeric return contract ([report](research/QVM_WEAPON_LOOKUP.md)).

docs/research/QVM_WEAPON_LOOKUP.md

@@ -0,0 +1,11 @@
+# Weapon slot lookup and numeric return contract
+
+RE-571. Reproduce with `python3 scripts/analyze_qvm_weapon_lookup.py`; check with `python3 scripts/test_qvm_weapon_lookup.py`. The [machine report](qvm-weapon-lookup.json) retains source identity and bounded fixtures.
+
+Complete31691 executes31692..31726, including numeric LEAVE returns. It scans PS312+4×slot for slots0..15, masks each record with255, and compares that byte with the entire requested argument. It returns the first match, including empty ID0 if requested, or−1. Request256 does not wrap to0 and request−1 does not wrap to255. Record upper bytes do not affect equality.
+
+111 fixtures exercise all boundaries and duplicate priority, and retain all16 packed words, inventory, animation/event/resource state and command canaries. The local frame is disjoint from the caller. This is a weapon-slot lookup, distinct from item inventory32117 at PS376; neither legal selectable IDs nor a health gate is imposed here.
+
+Next: apply the actual lookup in selection48798 and completion49028, including fallback and missing-slot behavior, before extending the50746 caller.
+
+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

@@ -315,3 +315,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [RE-569: Main request and independently bounded animation consumer chains](QVM_MAIN_CONSUMERS.md). Reproduce with `python3 scripts/analyze_qvm_main_consumers.py`; check with `python3 scripts/test_qvm_main_consumers.py`.
+
+
+[RE-571: Weapon slot lookup and numeric return contract](QVM_WEAPON_LOOKUP.md). Reproduce with `python3 scripts/analyze_qvm_weapon_lookup.py`; check with `python3 scripts/test_qvm_weapon_lookup.py`.

scripts/analyze_qvm_weapon_lookup.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Complete31691 first16 weapon slots, low-byte equality and numeric return."""
+import itertools
+from pathlib import Path
+from qvm_research_support import source,execute
+from qvm_weapon_support import weapon_seed,weapon_state
+from analyze_qvm_acceleration import PS
+from analyze_qvm import write_json
+LOCAL=0x73000000
+
+def lookup(ins,m,args,cmd=(0,0,0)):
+    m=dict(m);m[LOCAL+20]=args[8];m[LOCAL+24]=args[12];before=weapon_state(m);m,c,r=execute(ins,31692,31727,m,cmd,LOCAL)
+    return m,c,r['return'],{'requested':args[12],'pointer':args[8],'initial':before,'execution':r,'final':weapon_state(m)}
+
+def main():
+    q,raw,h,ins=source();rows=[]
+    for ident,slot,upper in itertools.product([0,1,14,22,27,28,255,256,-1],[-1,0,1,7,15,16],[0,0xa5fe0200]):
+        m=weapon_seed(raw,h)
+        for j in range(17):m[PS+312+4*j]=99
+        if slot>=0:m[PS+312+4*slot]=(ident&255)|upper
+        rows.append(lookup(ins,m,{8:PS,12:ident})[3])
+    for slots in [(0,15),(2,7),(15,16)]:
+        m=weapon_seed(raw,h)
+        for j in slots:m[PS+312+4*j]=0xaa0016
+        rows.append(lookup(ins,m,{8:PS,12:22})[3])
+    write_json(Path('docs/research/qvm-weapon-lookup.json'),{'source':q['source'],'sha256':q['sha256'],'probes':rows,'limits':'Complete finite31691 numeric return; supplied weapon words and requests. First16 slots only, equality compares low-byte record to full requested integer. No selection legality or native execution.'})
+if __name__=='__main__':main()

scripts/qvm_weapon_support.py

@@ -0,0 +1,11 @@
+"""Explicit finite weapon-state fixtures; initialized image versus supplied state."""
+from qvm_suffix_support import seed,state,weapon_config
+from qvm_research_support import constants
+from analyze_qvm_acceleration import PS,FRAME
+
+def weapon_seed(raw,h,cmd=(0,0,0),desired=22):
+    m=weapon_config(seed(raw,h,cmd),raw,h);m.update(constants(raw,h,range(21284,21316,4)));m.update({FRAME+232:0,FRAME+236:0,FRAME+24:(m[FRAME+24]&~255)|(desired&255),PS+204:7,PS+188:31,PS+196:17,PS+44:0})
+    return m
+
+def weapon_state(m):
+    return {**state(m),'weapons':[m[PS+312+4*j]&0xffffffff for j in range(16)],'counter204':m[PS+204]&0xffffffff,'command_weapon':m[FRAME+24]&255,'frame232':m[FRAME+232],'frame236':m[FRAME+236]}

scripts/test_qvm_weapon_lookup.py

@@ -0,0 +1,16 @@
+import json,unittest
+from pathlib import Path
+class WeaponLookupTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-weapon-lookup.json').read_text())
+    def test_complete_first_match_return(self):
+        self.assertEqual(len(self.r['probes']),111)
+        for p in self.r['probes']:self.assertEqual(p['execution']['return'],next((j for j,v in enumerate(p['initial']['weapons']) if v&255==p['requested']),-1))
+    def test_full_requested_integer_not_truncated(self):
+        rows=[p for p in self.r['probes'] if p['requested'] in [-1,256]];self.assertTrue(rows)
+        for p in rows:self.assertEqual(p['execution']['return'],-1)
+    def test_lookup_never_mutates_game_state_or_calls(self):
+        for p in self.r['probes']:self.assertEqual(p['initial'],p['final']);self.assertEqual(p['execution']['calls'],[]);self.assertEqual(p['execution']['byte_writes'],[])
+    def test_first16_bound_and_numeric_leave(self):
+        for p in self.r['probes']:self.assertIn(p['execution']['return'],range(-1,16));self.assertGreater(p['execution']['trace_length'],0)
+if __name__=='__main__':unittest.main()