qvm: allsolid recovery

docs/ASSET_PIPELINE_TODO.md

@@ -309,3 +309,6 @@ Research progress: [QVM ground loss and landing prefix](research/QVM_GROUND_CALL
 
 
 Research progress: [QVM landing severity/event queue/caller](research/QVM_LANDING.md) completes bounded RE-513–515: two-slot queue writers, full landing body and actual ground/main timer ordering. Numeric event/PS216 semantics and native/remaining main effects remain open under RE-512/516; broad game/rendering/runtime/platform milestones remain open.
+
+
+Research progress: [QVM allsolid recovery](research/QVM_RECOVERY.md) completes bounded RE-517–519: ordered27-point search, original-origin retrace/record priority and16 ground/main continuations. Trace responses remain supplied; RE-516/520 retain native collision/legal/combined main/runtime/platform work and broad game/rendering milestones.

docs/FINDINGS.md

@@ -639,3 +639,10 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 **F-245 — Landing severity and suffix:**45912 scales squared impact by level, gates events on score/health/surface/argument, writes numeric queue/PS216 or Z300 branches, clears PS8 only after score>=1, and conditionally sets an entity bit for horizontal norm>300. Strict event thresholds are7/30/45. [LAND-001](research/QVM_LANDING.md).
 
 **F-246 — Actual landing caller:**complete bounded45912 effects precede46773's movement timer250 and touch stores; actual main aging yields234. Level3 skips landing entirely, and a reached child need not emit an event. Native collisions/other main callees/full runtime remain supplied, omitted or unverified. [LANDCHAIN-001](research/QVM_LANDING.md).
+
+
+**F-247 — Recovery search:**46296 enumerates27 offsets in X/Y/Z order and tests candidate allsolid. Full failure returns0, clears ground/plane/walk and preserves PS position/velocity; local last-record output and global trace remain distinct. [RECOVER-001](research/QVM_RECOVERY.md).
+
+**F-248 — Free candidate is not committed:**first clear triggers a new original-origin Z−0.25 trace, full56-byte copy and return1 without retesting follow-up allsolid. Actual46773 classifies that updated record or exits on evaluated return0. Native physical consistency remains unverified. [RECOVER-002](research/QVM_RECOVERY.md).
+
+**F-249 — Recovery-to-main connection:**16 actual caller fixtures derive plane/normal/touch inputs, select ten evaluated41768 chains and six omitted43626 requests, then continue post environment. Full native/main/runtime gameplay remains open. [RECOVERCHAIN-001](research/QVM_RECOVERY.md).

docs/PROVISIONAL_TODO.md

@@ -621,3 +621,6 @@ Research progress: [QVM ground loss and landing prefix](research/QVM_GROUND_CALL
 
 
 Research progress: [QVM landing severity/event queue/caller](research/QVM_LANDING.md) completes bounded RE-513–515: two-slot queue writers, full landing body and actual ground/main timer ordering. Numeric event/PS216 semantics and native/remaining main effects remain open under RE-512/516; broad game/rendering/runtime/platform milestones remain open.
+
+
+Research progress: [QVM allsolid recovery](research/QVM_RECOVERY.md) completes bounded RE-517–519: ordered27-point search, original-origin retrace/record priority and16 ground/main continuations. Trace responses remain supplied; RE-516/520 retain native collision/legal/combined main/runtime/platform work and broad game/rendering milestones.

docs/RESEARCH_LEDGER.md

@@ -399,3 +399,7 @@ Completed bounded RE-509–511 with `analyze_qvm_ground_callees.py`:32 standalon
 ## 2026-10-18 — Game-QVM full bounded landing, numeric event queue and actual ground caller
 
 Completed bounded RE-513–515 with `analyze_qvm_landing.py`:82 landing-body fixtures,10 supplied-severity suffix boundaries, five three-write queue sequences and six actual ground/main chains. LANDEVENT-001/LAND-001/LANDCHAIN-001/F-244–246 recover29913 two-slot event/parameter writes and int32 sequence wrap,39238 parameter0 forwarding/45887 surface8192 suppression and signed surface>>20 parameters, complete45912 level/severity/health/surface/argument gates with numeric queue/PS216/Z300 outputs, field8 cleanup and strict horizontal norm>300 suffix. Numeric event/PS216 consumers and health/damage meanings remain unverified;29913 is a memory queue writer, not an external damage routine. Strict severity cutoffs1/7/30/45 and speed299/300/301 are checked independently; supplied score probes are not claimed collision-derived. Reached39525/39383,39238,45887 and29913 effects evaluate in disjoint frames. Four accepted-ground chains evaluate landing before caller250 movement timer/touch stores and actual aging234; two level3 controls reach41768 while skipping landing effects. Alternative modes/post-ground animation/other posture-action-query-suffix/native effects remain omitted or unverified. Roots/contents/trace records/interpolation/gravity800/legal initial state remain supplied; no original executable/full QVM/native collision/physics/rendering executes. Eight tests independently verify every body/suffix state, score/event/queue/field/velocity output, signed queue wrap/wrapper suppression/root arguments, ground-caller timer/touch order, queue retention and unreached-child/selected-slide controls, source partitions and scope. All639 tests pass. Prior ground-callee report regenerates byte-identically; final landing report reproduces twice byte-identically (506714 bytes). Storage/filter setup, documentation links and whitespace checks pass. No assets or existing analyzer/evaluator code changed. RE-512 remains open for broader scope; RE-516 tracks event/PS216 consumers,46296 recovery/native/legal effects, other action/posture-ground/animation/mode/suffix work and complete main/scheduler/macOS/Linux Rust/Bevy/Solari gameplay. Broad game/assets/rendering/protocol milestones remain open.
+
+## 2026-10-19 — Game-QVM allsolid recovery and actual ground/main caller
+
+Completed bounded RE-517–519 with `analyze_qvm_recovery.py`:34 standalone46296 probes cover every first-clear rank0–26, full27-trial exhaustion and rank0/13/26 follow-up-solid/air controls;16 actual ground/main chains connect evaluated recovery state/return/record. RECOVER-001–002/RECOVERCHAIN-001/F-247–249 recover X/Y/Z ordered offsets−1/0/+1, first-zero-allsolid short circuit, failure ground1023/plane-walk0 without PS position/velocity changes, and success retrace from original origin to Z−0.25 rather than committing the free candidate. Source copies56-byte follow-up to globals and returns1 without retesting allsolid; caller classifies updated local record or exits on0, preserving local/global record distinctions on failure. Repeated native-call checkpoints are explicitly re-enabled after evaluating each consumed allsolid branch. Main outcomes:ten evaluated41768 first-clear/wrapper/gravity chains and six omitted43626 requests, then actual post environment. Candidate/follow-up/native responses remain supplied, including deliberately inconsistent follow-up-allsolid controls; logging/other ground-posture-action-query-mode-suffix/native/legal/full runtime effects remain omitted or unverified. No original executable/full QVM/native collision/physics/rendering executes. Eight independent tests verify every search coordinate/order/count/argument, native bounds/mask/pointers, unchanged PS vectors, original-origin retrace/copy/allsolid priority, actual caller classification/touch/return state, derived routing/reached slide/mode/post-environment handoffs, full source partition/hash and scope. All647 tests pass. Prior main-environment report regenerates byte-identically; new recovery report reproduces twice byte-identically (1540584 bytes, below normal-Git2MiB). Storage/filter setup, documentation links and whitespace checks pass. No assets or existing analyzer/evaluator code changed. RE-516 remains open for broader scope; RE-520 tracks native collision/consistent contact-escape/logging/ABI domains, combined posture/recovery/landing/lost/animation/action/alternative-mode/suffix state, event/PS216 consumers and complete main/scheduler/macOS/Linux Rust/Bevy/Solari gameplay. Broad game/assets/rendering/protocol milestones remain open.

docs/REVERSE_ENGINEERING_TODO.md

@@ -636,3 +636,9 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 - [x] RE-514 Evaluate remaining45912 severity/level/health/surface/argument gates, numeric queue/PS216/Z outputs and cleanup/horizontal-speed suffix ([LAND-001](research/QVM_LANDING.md)).
 - [x] RE-515 Evaluate full bounded landing child at actual ground boundary before250-timer/touch stores and live main aging/routing, suppressing unreached level3 children ([LANDCHAIN-001](research/QVM_LANDING.md)).
 - [ ] RE-516 Recover event/PS216 consumers/health semantics,46296 recovery/native collision/content/root ABI/legal domains,54981/action/posture-ground/animation/alternative-mode/suffix effects and full main/scheduler/macOS/Linux Rust/Bevy/Solari gameplay. Continue broader game/assets/rendering/protocol work.
+
+
+- [x] RE-517 Recover46296 ordered27-point allsolid search, first-clear short circuit, full failure and unchanged origin/velocity policy ([RECOVER-001](research/QVM_RECOVERY.md)).
+- [x] RE-518 Recover original-origin follow-up/full trace copy/unretested allsolid and actual46773 return/local/global record classification priority ([RECOVER-002](research/QVM_RECOVERY.md)).
+- [x] RE-519 Carry actual recovery/caller plane/normal/flags/touch state through main timer/routing, reached clear-slide mode and post environment ([RECOVERCHAIN-001](research/QVM_RECOVERY.md)).
+- [ ] RE-520 Recover native collision/consistent escape-contact domains/logging/ABI effects; combine posture/recovery/landing/lost/animation/action/alternative-mode/suffix state and event/PS216 consumers; complete main/scheduler/macOS/Linux Rust/Bevy/Solari gameplay and broader game/assets/rendering/protocol work.

docs/research/QVM_GROUND.md

@@ -78,3 +78,6 @@ Follow-up: [ground-loss and landing-prefix recovery](QVM_GROUND_CALLEES.md) comp
 
 
 Follow-up: [landing/event queue caller composition](QVM_LANDING.md) completes bounded RE-513–515, replacing omitted landing effects in selected actual ground/main chains and preserving caller timer/touch ordering. Native/other callees/legal/full runtime limits remain explicit.
+
+
+Follow-up: [allsolid recovery caller composition](QVM_RECOVERY.md) completes bounded RE-517–519, replacing supplied46296 returns with evaluated search/retrace/global-copy effects at selected actual ground/main boundaries. Native contact validity and broader callee/runtime limits remain explicit.

docs/research/QVM_MAIN_ENVIRONMENT.md

@@ -41,3 +41,6 @@ Follow-up: [main posture producer composition](QVM_MAIN_POSTURE.md) completes bo
 
 
 Follow-up: [ground-loss caller recovery](QVM_GROUND_CALLEES.md) completes bounded RE-509–511, evaluating46527 in selected actual46773/main chains and separately recovering the landing kinematics prefix. Native/action/full landing/main/runtime work remains open under RE-508/512.
+
+
+Follow-up: [actual allsolid recovery](QVM_RECOVERY.md) completes bounded RE-517–519 and carries evaluated recovery outputs through selected main/clear-slide/post-environment paths. The earlier report keeps its original supplied-recovery scope.

docs/research/QVM_RECOVERY.md

@@ -0,0 +1,33 @@
+# QVM allsolid recovery search and ground/main continuation
+
+This batch completes bounded RE-517–519 / F-247–249, recovering46296 and evaluating it at the actual46773 allsolid boundary. It extends [ground recovery's earlier supplied-return model](QVM_GROUND.md) and [main environment composition](QVM_MAIN_ENVIRONMENT.md). Native trace responses remain supplied; this is source-policy recovery, not a geometry-derived escape implementation.
+
+Reproduce with `python3 scripts/analyze_qvm_recovery.py`; validate with `python3 scripts/test_qvm_recovery.py`. The [machine report](qvm-recovery.json) retains source identity, complete recovery instruction partition, every callback record/argument,34 standalone probes and16 main chains. No original executable, full QVM, native collision, physics or rendering executes.
+
+## RECOVER-001 — Ordered27-point search (RE-517)
+
+Helper46296 tries offsets−1/0/+1 on each axis around current PS origin, with X outermost, Y next and Z innermost. Each candidate begins from a fresh copy of the original position and uses ordered binary32 addition of converted integer offsets. It requests a same-start/end trace at that candidate with the actual bounds, entity selector, mask and caller-provided output pointer.
+
+The helper consumes only each candidate's allsolid word to decide whether to continue. A nonzero value advances the ordered search. The first zero stops it; no remaining prepared candidates are evaluated. Standalone fixtures cover every first-clear rank0–26 and full27-trial exhaustion. Additional rank0/13/26 fixtures vary the follow-up record. The evaluator explicitly re-enables the repeated callback checkpoint after evaluating its allsolid branch, so later callbacks receive distinct supplied records rather than reusing the first response.
+
+If all27 candidates remain solid, source stores ground1023 and clears plane/walk, then returns0. It leaves PS origin, velocity and flags unchanged. The output buffer contains the last supplied candidate record, but the separate global trace record is not recopied on this failure path. Standalone canary globals and actual caller records verify that distinction. Logging is disabled by the supplied frame+32=0; the logging path/native behavior is not claimed.
+
+## RECOVER-002 — Original-origin retrace and caller record priority (RE-518)
+
+Finding a free candidate does **not** copy that candidate into PS origin. Source instead builds another trace from the original origin to original Z−0.25, using the same caller output buffer. It copies all56 bytes of that supplied follow-up record to trace globals and returns1. It does not retest the follow-up allsolid word or validate fraction/position consistency. Three deliberately supplied follow-up-allsolid fixtures still return1; they establish source priority, not physically consistent collisions or valid escape positions.
+
+At actual46773, the first allsolid trace is copied to globals before recovery is requested. The new child then runs against that live local output buffer; its evaluated return word replaces the caller result local before continuation. A zero result exits classification with the child's ground/plane/walk changes, without consuming the final candidate's normal as a new global plane. A nonzero result classifies the updated follow-up record, including its fraction, normal and surface.
+
+Flat and follow-up-allsolid records with fraction0.5/normal Z1 reach accepted-ground policy; the caller does not retest allsolid after child return. A steep normal Z0.5 preserves a plane without walk acceptance. Fraction1 requests ground-loss handling, whose effects remain omitted in these particular chains, then clears plane/walk. Requested accepted-ground39253 touch registration is evaluated. Landing/upward-animation and other ground effects remain recorded/omitted as specified.
+
+## RECOVERCHAIN-001 — Recovery state into main routing and motion (RE-519)
+
+Sixteen main fixtures vary first-clear rank0/13/26 or complete failure, with flat/steep/follow-up-allsolid/air record patterns. Actual clock, pre-content, ground/recovery, main timer and routing instructions share state. Ten fixtures select/evaluate41768 with a first-clear slide, wrapper bypass and gravity tail; six request43626 with its body omitted. Derived recovery/caller plane and normal values enter the reached movement chain.
+
+The post-ground/content sequence receives the actual after-dispatch position, velocity, flags, timer and touches. It retains the earlier supplied native environment responses and omitted ground landing/animation/action/posture/query/alternative-mode/suffix effects. Bounds/viewheight and input state remain seeded here rather than invoking the optional posture composition. No legal collision-domain, complete53418/scheduler, native ABI or macOS/Linux/Rust/Bevy/Solari gameplay equivalence follows from these finite fixtures.
+
+## Validation and remaining tasks
+
+Eight independent tests verify all34 standalone and16 composed searches, every candidate coordinate/order/short circuit, full27 failure and all pointer/bounds/mask arguments, unchanged PS position/velocity, original-origin retrace/full trace copy, follow-up allsolid priority, separate local/global records, actual ground classification/return handoff/touches, main route counts, reached slide/mode outputs, post-environment handoff, source hash/partition and explicit scope. Reproducibility/full-suite/storage/link/whitespace results are recorded in the ledger.
+
+RE-516 remains open for broader native/legal/main/runtime scope; the finite46296 body/caller policy is now covered by RE-517–519. RE-520 tracks native trace/collision and consistent contact/escape domains, logging/other native ABI effects, combined posture/recovery/landing/ground-loss/animation/action/alternative-mode/suffix state, event/PS216 consumers and complete main/scheduler/macOS/Linux Rust/Bevy/Solari gameplay. Other game/assets/rendering/protocol milestones remain open.

docs/research/README.md

@@ -222,3 +222,6 @@ The extension collector adds five focused tests for native tail calls, command-r
 
 
 [QVM landing severity, event queue and ground caller](QVM_LANDING.md) adds RE-513–515. Reproduce with `python3 scripts/analyze_qvm_landing.py`; check with `python3 scripts/test_qvm_landing.py`. Landing/event writers evaluate before actual ground timer/touch stores; numeric consumers/native collision/full runtime remain open.
+
+
+[QVM allsolid recovery and ground/main caller](QVM_RECOVERY.md) adds RE-517–519. Reproduce with `python3 scripts/analyze_qvm_recovery.py`; check with `python3 scripts/test_qvm_recovery.py`. Actual46296/caller state evaluates with supplied trace responses; consistent collision/native/full runtime domains remain open.

scripts/analyze_qvm_recovery.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Allsolid27-point search, original-origin retrace and actual ground/main caller."""
+import itertools,json
+from pathlib import Path
+from analyze_bsp_references import trace_fields
+from analyze_deferred_auth import trace_slice
+from analyze_qvm import decode,write_json
+from analyze_qvm_acceleration import PS,FRAME,word
+from analyze_qvm_slide_prefix import seed,vec
+from analyze_qvm_main_environment import env_state,contents,ground
+from analyze_qvm_main_contact import probe
+from analyze_qvm_animation_contacts import evaluate
+from analyze_vm_extensions import verified
+
+LOCAL=0x5c000000
+OUTPUT=0x60000000
+GROUND=0x46000000
+
+
+def state(m):return {'origin':vec(m,PS+20),'velocity':vec(m,PS+32),'ground':m[PS+68],'plane':m[35023940],'walk':m[35023936],'flags':m[PS+12]&0xffffffff,'trace_globals':[m[35023944+4*i]&0xffffffff for i in range(14)]}
+
+
+def recovery(ins,m,output,escape=None,kind='flat'):
+    initial=state(m);m=dict(m);m[LOCAL+80]=output;pc=46297;calls=[];trace=[];requests=[];candidate=0
+    while True:
+        t=trace_slice(ins,46297,46525,m,{},resume_at=pc,stop_targets=[s for s in [46393,46472] if s!=pc],local_base=LOCAL,halt_on_leave=True,capture_stack=True,limit=1024);m=t['memory'];pc=t['stop'];calls+=t['calls'];trace+=t['trace']
+        if t['trace'] and ins[t['trace'][-1]]['opcode']=='LEAVE':return m,{'initial':initial,'escape':escape,'followup_kind':kind,'return_word':t['stack'][-1],'requests':requests,'output_record':[m[output+4*i]&0xffffffff for i in range(14)],'final':state(m),'calls':calls,**trace_fields({'trace':trace},False)}
+        c=t['calls'][-1];a=c['args'];start=vec(m,a[12]);end=vec(m,a[24])
+        if pc==46393:
+            solid=int(candidate!=escape);record=[solid,0,word(0),*start,word(1),0,0,0,0,4,0,99];candidate+=1
+        elif pc==46472:
+            record=[int(kind=='solid'),0,word(1 if kind=='air' else .5),*end,0,0,word(.5 if kind=='steep' else 1),0,0,2,0,8]
+        else:raise AssertionError('Unexpected recovery boundary')
+        requests.append({'instruction':c['instruction'],'args':a,'start':start,'end':end,'bounds':vec(m,a[16])+vec(m,a[20]),'record':record})
+        for i,v in enumerate(record):m[a[8]+4*i]=v
+        if pc==46393:
+            # Evaluate the consumed allsolid test to an empty-stack branch boundary,
+            # then re-enable46393 so every later candidate callback is intercepted.
+            branch=trace_slice(ins,46297,46525,m,{},resume_at=46393,stop_targets=[46398,46480],local_base=LOCAL,limit=32);m=branch['memory'];pc=branch['stop'];calls+=branch['calls'];trace+=branch['trace']
+
+
+def memory(flags=128):
+    m=seed(velocity=(10,20,0),flags=flags);m.update({PS+4:0,PS+68:7,PS+72:17,PS+76:25,PS+220:0,PS+164:38,FRAME+32:0,FRAME+228:-26,FRAME+208:99,FRAME+212:0,35023936:1})
+    for i in range(14):m[35023944+4*i]=700+i;m[OUTPUT+4*i]=800+i
+    return m
+
+
+def standalone(ins,escape,kind='flat'):return recovery(ins,memory(),OUTPUT,escape,kind)[1]
+
+
+def ground_recovery(ins,m,escape,kind):
+    before=env_state(m);pre=trace_slice(ins,46774,47215,m,{},stop_targets=[46847],local_base=GROUND,limit=512);m=pre['memory'];a=pre['calls'][-1]['args'];record=[1,0,word(0),*vec(m,PS+20),0,0,word(1),0,0,2,0,8]
+    for i,v in enumerate(record):m[a[8]+4*i]=v
+    at=trace_slice(ins,46774,47215,m,{},resume_at=46847,stop_targets=[46860],local_base=GROUND,limit=512);m,child=recovery(ins,at['memory'],GROUND+36,escape,kind);m[GROUND+112]=child['return_word'];post=trace_slice(ins,46774,47215,m,{},resume_at=46860,byte_memory={FRAME+25:1},local_base=GROUND,limit=1024);m=post['memory'];touch=None
+    for c in post['calls']:
+        if c['target']==39253:effect=evaluate(ins,39253,c['args'][8],m);m=effect['memory'];touch={'calls':effect['calls'],**trace_fields(effect,False)}
+    return m,{'target':46773,'before':before,'initial_record':record,'recovery':child,'after':env_state(m),'touch_child':touch,'calls':pre['calls']+at['calls']+post['calls'],**trace_fields({'trace':pre['trace']+at['trace']+post['trace']},False)}
+
+
+def main_chain(ins,escape,kind):
+    def effect(ins,m,target,phase):
+        if target==47217:m,r=contents(ins,m,[0,0,0])
+        elif phase=='before':m,r=ground_recovery(ins,m,escape,kind)
+        else:m,r=ground(ins,m,'flat')
+        r['phase']=phase;return m,r
+    p=probe(ins,1016,0,2208,'clear',initial_memory=memory(flags=2208),environment_effect=effect);p.update({'escape':escape,'followup_kind':kind});return p
+
+
+def main():
+    q=json.loads(Path('docs/research/qvm/qagame.json').read_text());_,ins=decode(verified(Path(q['source']['member']['output']).read_bytes(),q['sha256']))
+    probes=[standalone(ins,e) for e in list(range(27))+[None]]+[standalone(ins,e,k) for e,k in itertools.product([0,13,26],['solid','air'])]
+    out={'source':q['source'],'sha256':q['sha256'],'recovery_instructions':ins[46296:46527],'probes':probes,'main_chains':[main_chain(ins,e,k) for e,k in itertools.product([0,13,26,None],['flat','steep','solid','air'])],'limitations':'Bounded finite shipped-QVM recovery and ground/main composition; no original executable/full QVM/native collision/physics/rendering executes. Candidate allsolid words and complete followup/native ground/content/slide records/root responses are supplied, not collision-derived. Search trials establish source order/branch/state effects, not a real escape or legal contact domain. Found candidate is not committed to PS origin; followup retraces original origin and its allsolid/fraction consistency is not validated. Actual ground caller receives evaluated recovery return/record/globals; requested touch registration executes. Other ground loss/landing/animation/action/posture/query/alternative-mode/suffix effects remain omitted; full53418/scheduler/native ABI/legal/runtime/macOS/Linux/Rust/Bevy/Solari gameplay remain open.'};write_json(Path('docs/research/qvm-recovery.json'),out);print('Recovered ordered allsolid search and actual ground/main continuation')
+
+
+if __name__=='__main__':main()

scripts/test_qvm_recovery.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Independent27-point ordering, retrace/copy and actual caller formulas."""
+import hashlib,itertools,json
+from pathlib import Path
+import unittest
+from test_qvm_ground import f,n,word
+from test_qvm_slide_repeated import oracle as slide_oracle
+
+
+def check_recovery(test,p):
+    escape=p['escape'];q=p['requests'];count=27 if escape is None else escape+1;test.assertEqual(len(q),count+(escape is not None));offsets=list(itertools.product([-1,0,1],repeat=3));initial=p['initial']
+    for i,r in enumerate(q[:count]):
+        point=[word(f(n(v)+d)) for v,d in zip(initial['origin'],offsets[i])];test.assertEqual(r['start'],point);test.assertEqual(r['end'],point);test.assertEqual(r['instruction'],46391);test.assertEqual(r['record'][0],int(i!=escape));test.assertEqual(r['args']['12'],r['args']['24'])
+    expected=dict(initial)
+    if escape is None:
+        expected.update({'ground':1023,'plane':0,'walk':0});test.assertEqual(p['output_record'],q[-1]['record'])
+    else:
+        r=q[-1];test.assertEqual(r['instruction'],46470);test.assertEqual(r['start'],initial['origin']);test.assertEqual(r['end'],initial['origin'][:2]+[word(f(n(initial['origin'][2])-.25))]);test.assertEqual(p['output_record'],r['record']);expected['trace_globals']=r['record']
+    test.assertEqual(p['return_word'],int(escape is not None));test.assertEqual(p['final'],expected);test.assertEqual(p['calls'],[{'instruction':r['instruction'],'target':-25,'args':r['args']} for r in q])
+
+
+class QvmRecoveryTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/qvm-recovery.json').read_text())
+
+    def test_every_search_rank_and_exhaustion_against_independent_order(self):
+        self.assertEqual(len(self.r['probes']),34);self.assertEqual({p['escape'] for p in self.r['probes']},set(range(27))|{None})
+        for p in self.r['probes']:check_recovery(self,p)
+        for p in self.r['main_chains']:check_recovery(self,p['environment'][1]['recovery'])
+
+    def test_callback_abi_and_candidate_not_committed_to_origin(self):
+        for p in self.r['probes']:
+            for r in p['requests']:
+                a=r['args'];self.assertEqual(a['8'],0x60000000);self.assertEqual(a['16'],0x300b8);self.assertEqual(a['20'],0x300c4);self.assertEqual(a['28'],7);self.assertEqual(a['32'],0x2010001);self.assertEqual(r['bounds'],list(map(word,[-15,-15,-24,15,15,45])))
+                if r['instruction']==46391:self.assertEqual(a['12'],0x5c000024)
+                else:self.assertEqual(a['12'],0x10014);self.assertEqual(a['24'],0x5c000024)
+            self.assertEqual(p['final']['origin'],p['initial']['origin']);self.assertEqual(p['final']['velocity'],p['initial']['velocity'])
+
+    def test_followup_solid_not_retested_and_full_record_copy(self):
+        solid=[p for p in self.r['probes'] if p['followup_kind']=='solid'];self.assertEqual(len(solid),3)
+        for p in solid:self.assertEqual(p['return_word'],1);self.assertEqual(p['output_record'][0],1);self.assertEqual(p['final']['trace_globals'],p['output_record'])
+        for p in self.r['probes']:
+            if p['escape'] is None:self.assertEqual(p['final']['trace_globals'],p['initial']['trace_globals']);self.assertNotEqual(p['output_record'],p['final']['trace_globals'])
+
+    def test_actual_ground_caller_consumes_return_and_updated_record(self):
+        self.assertEqual(len(self.r['main_chains']),16)
+        for p in self.r['main_chains']:
+            g=p['environment'][1];r=g['recovery'];expected=dict(g['before']);expected['touches']=expected['touches'][:]
+            if not r['return_word']:
+                expected.update({'normal':g['initial_record'][6:9],'surface':g['initial_record'][11],'ground':1023,'plane':0,'walk':0});self.assertIsNone(g['touch_child']);self.assertEqual([c['target'] for c in g['calls']],[-25,46296])
+            else:
+                record=r['output_record'];expected.update({'normal':record[6:9],'surface':record[11]})
+                if n(record[2])==1:expected.update({'plane':0,'walk':0});self.assertEqual([c['target'] for c in g['calls']],[-25,46296,46527])
+                elif n(record[8])<n(1060320051):expected.update({'plane':1,'walk':0,'ground':1023});self.assertIsNone(g['touch_child'])
+                else:
+                    flags=expected['flags']&~18
+                    if flags&128:flags&=~128;expected['timer']=0
+                    expected.update({'plane':1,'walk':1,'ground':8,'flags':flags,'touches':[8]});self.assertIsNotNone(g['touch_child'])
+            self.assertEqual(g['after'],expected)
+
+    def test_main_timer_routing_and_reached_mode_only(self):
+        counts={41768:0,43626:0}
+        for p in self.r['main_chains']:
+            g=p['environment'][1]['after'];self.assertEqual(p['timer']['before']['flags'],g['flags']);mode=41768 if g['flags']&128 else 43626;self.assertEqual(p['selected_mode'],mode);counts[mode]+=1;self.assertEqual(p['mode'] is not None,mode==41768)
+            if p['mode']:
+                w=p['mode']['wrapper'];entry=dict(w['before']);entry['ground_normal']=g['normal'];slide_oracle(self,w['first_slide'],entry);self.assertEqual(w['first_slide']['ground'],g['plane']);self.assertEqual(w['first_slide']['return_word'],0);self.assertIsNone(w['step'])
+        self.assertEqual(counts,{41768:10,43626:6})
+
+    def test_actual_mode_tail_and_final_environment_handoff(self):
+        for p in self.r['main_chains']:
+            if p['mode']:
+                m=p['mode'];expected=dict(m['wrapper']['final']);vz=f(n(expected['velocity'][2])-f(f(800)*n(p['clock']['float_dt'])));expected['velocity']=expected['velocity'][:2]+[word(vz)]
+                if vz<0:expected['flags']&=~192;expected['timer']=0
+                self.assertEqual(m['mode_final'],expected);self.assertEqual(p['after_dispatch'],expected)
+            e=p['environment'][2]
+            for k in ['origin','velocity','flags','timer','touches']:self.assertEqual(e['before'][k],p['after_dispatch'][k])
+            self.assertEqual(p['final']['origin'],p['after_dispatch']['origin']);self.assertEqual(p['final']['velocity'],p['after_dispatch']['velocity'])
+
+    def test_source_hash_full_partition_and_log_disabled_fixture(self):
+        q=json.loads(Path('docs/research/qvm/qagame.json').read_text());self.assertEqual(self.r['source'],q['source']);self.assertEqual(self.r['sha256'],hashlib.sha256(Path(q['source']['member']['output']).read_bytes()).hexdigest());self.assertEqual(self.r['recovery_instructions'][0]['index'],46296);self.assertEqual(self.r['recovery_instructions'][-1]['index'],46526)
+        for p in self.r['probes']:self.assertTrue(all(c['target']==-25 for c in p['calls']))
+
+    def test_native_escape_origin_and_runtime_limits_explicit(self):
+        for text in ['no original executable/full QVM/native collision/physics/rendering executes','not a real escape or legal contact domain','Found candidate is not committed to PS origin','full53418/scheduler/native ABI/legal/runtime/macOS/Linux/Rust/Bevy/Solari gameplay remain open']:self.assertIn(text,self.r['limitations'])
+
+
+if __name__=='__main__':unittest.main()