Compose Huffman send paths and symbol round trips

docs/ASSET_PIPELINE_TODO.md

@@ -216,3 +216,5 @@ Client-mask follow-up: [client parsing](research/CLIENT_MASKS.md) bounds accepte
 Message-bit follow-up: [read modes and assembly](research/MESSAGE_BITS.md) establishes bounded cursor/assembly behavior with supplied Huffman symbols. Recover actual tree/codebooks and real packets before network/renderer integration with converted map assets (RE-344).
 
 Huffman follow-up: [helper probes](research/HUFFMAN_HELPERS.md) establishes raw-bit round trips and supplied-tree decoding, with explicit null-path cursor differences. Real initialized codebooks and message fixtures remain prerequisites for network/map/renderer integration (RE-348).
+
+Encoder follow-up: [supplied-tree symbol streams](research/HUFFMAN_ENCODING.md) validates bounded transmit/receive compositions with synthetic codebooks. Actual game codebooks and full packet contracts remain prerequisites for network/map/renderer integration (RE-352).

docs/FINDINGS.md

@@ -378,3 +378,9 @@ Bounded qagame paths recover bomb-plant/inactivity correction requests, direct f
 **F-119 — Observed supplied-tree receive:** internal symbol 257 consumes LSB-first bits, zero left/one right; successful leaves publish cursor and arbitrary supplied symbol words. Null children output zero and leave the caller cursor unchanged while the global advances. Real tree invariants and failure handling remain open. [HUFF-002](research/HUFFMAN_HELPERS.md).
 
 **F-120 — Observed transmit request:** signed index selects the node pointer at object +32 +8*index; its +16 parent controls a send request with parent/node/buffer arguments. The sampled null-parent path retains cursor. send, real codebooks, valid symbol bounds and runtime/platform conformance remain open. [HUFF-003](research/HUFFMAN_HELPERS.md).
+
+**F-121 — Observed bounded send:** parent walks emit root-to-leaf branch bits, right one/left zero in supplied consistent trees. Byte starts clear, partial bytes retain zero bits, and nine-edge unrolling yields four virtual frames for a 32-edge path. Full ABI/tree/capacity/runtime behavior remains open. [ENC-001](research/HUFFMAN_ENCODING.md).
+
+**F-122 — Observed supplied-codebook round trips:** composed transmit/send/receive returns symbol 42 with matching bytes and cursors for sampled paths up to 32 edges, including a synthetic root-leaf zero-length code. Actual initialized trees and game packet compatibility remain open. [ENC-002](research/HUFFMAN_ENCODING.md).
+
+**F-123 — Observed shared symbol streams:** supplied depth-three codebooks encode/decode repeated and mixed symbols across byte boundaries with three-bit cursor increments. No tree updates occur inside these sampled helpers; actual adaptive initialization/update ownership and complete message codecs remain open. [ENC-003](research/HUFFMAN_ENCODING.md).

docs/PROVISIONAL_TODO.md

@@ -528,3 +528,5 @@ Research progress: [client area-mask parsing](research/CLIENT_MASKS.md) complete
 Research progress: [message read modes and assembly](research/MESSAGE_BITS.md) completes bounded RE-341–343. Broad networking/runtime milestones remain open; RE-344 tracks real Huffman codecs, caller invariants and packet/platform fixtures.
 
 Research progress: [Huffman helper probes](research/HUFFMAN_HELPERS.md) completes bounded RE-345–347. Broad protocol/runtime milestones remain open; RE-348 tracks full send, initialized trees/codebooks, actual packet round trips and platform coverage.
+
+Research progress: [bounded Huffman encoding](research/HUFFMAN_ENCODING.md) completes RE-349–351. Broad network/runtime milestones remain open; RE-352 tracks adaptive initialization/codebooks, real message packets and platform fixtures.

docs/RESEARCH_LEDGER.md

@@ -209,3 +209,7 @@ Completed bounded RE-341–343 with `analyze_message_bits.py`: eight verified gr
 ## 2026-10-11 — Raw-bit helpers and supplied Huffman trees
 
 Completed bounded RE-345–347 with `analyze_huffman_helpers.py`: ten verified graphs across the Linux ELF64 engines, 288 bit-write probes, 64 raw bit-stream round trips, 352 supplied-tree receive and 72 transmit-boundary probes. HUFF-001–003/F-118–120 distinguish byte-start clear from partial-byte OR, raw round trips from real Huffman encoding, supplied-tree traversal from initialized codebooks, null-path global advances from caller cursor publication, and transmit lookup/arguments from execution of send. Virtual backing storage, arbitrary/non-Boolean/signed inputs and leaf symbols remain explicit local probes. Transmit PUSH omission and stopped CALL boundaries are documented; no original process or native callee executes. Eight independent tests verify mutation/canaries/wrap/global writes, independent bit packing, node-table walks and null cursors, leaf words, signed lookup/request arguments, paired outputs and call boundaries. All 302 tests pass; new and preceding reports regenerate byte-identically, and storage/link/whitespace checks pass. RE-344 remains open; RE-348 tracks full recursive/unrolled send, adaptive initialization/frequencies/tree/codebooks, message/packet compositions and legal input/cursor/tree/runtime/all-platform invariants.
+
+## 2026-10-11 — Bounded Huffman send and symbol streams
+
+Completed bounded RE-349–351 with `analyze_huffman_encoding.py`: six verified graphs across the Linux ELF64 engines, 720 supplied-path send compositions, 192 symbol round trips and thirty shared-tree streams. ENC-001–003/F-121–123 distinguish root-order code bits from LSB byte packing, dirty partial-byte retention from byte-start clearing, nine-edge unrolling from explicit recursive virtual frames, supplied codebooks from actual initialized game trees, and symbol round trips from full message/packet conformance. Frame prologues/epilogues and wrapper PUSH/POP are excluded explicitly; full caller-register restoration and disjoint virtual stacks preserve child memory effects across stopped CALL boundaries. No original process or native callee executes. Eight independent tests verify packing/canaries/cursors, recursion thresholds, parent-child tree consistency, transmit/receive symbols, repeated streams, zero-depth/empty cases, recomposed call-free traces and paired results. All 310 tests pass; new and preceding reports regenerate byte-identically, and storage/link/whitespace checks pass. RE-348 remains open; RE-352 tracks adaptive initialization/node allocation/rank/swaps/frequencies/codebooks, actual message/packet composition, legal inputs/capacity/truncation and ABI/runtime/all-platform/snapshot/renderer coverage.

docs/REVERSE_ENGINEERING_TODO.md

@@ -417,3 +417,8 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 - [x] RE-346 Compose supplied native tree walks, leaf symbol output and null-path caller/global cursor publication ([HUFF-002](research/HUFFMAN_HELPERS.md)).
 - [x] RE-347 Recover signed symbol-table lookup, parent routing and stopped transmit/send requests ([HUFF-003](research/HUFFMAN_HELPERS.md)).
 - [ ] RE-348 Recover recursive/unrolled send and bit writes, adaptive tree allocation/initialization/frequency tables/codebooks, full transmit/receive and message writer/reader/real-packet compositions; validate legal inputs/tree/cursor invariants, null failures, overflow/truncation and original-runtime/all-platform contracts.
+
+- [x] RE-349 Compose bounded unrolled/recursive send paths with root-order bits, dirty-byte behavior and frame-depth oracles ([ENC-001](research/HUFFMAN_ENCODING.md)).
+- [x] RE-350 Compose transmit/send/receive against supplied comb trees with exact symbol/cursor/byte round trips ([ENC-002](research/HUFFMAN_ENCODING.md)).
+- [x] RE-351 Compose shared-tree repeated/multi-symbol streams with independent byte and per-symbol cursor oracles ([ENC-003](research/HUFFMAN_ENCODING.md)).
+- [ ] RE-352 Recover adaptive Huffman initialization/node allocation/rank/swap/frequency updates and actual codebooks, full message writers/readers/real-packet compositions, overflow/truncation and legal tree/symbol/cursor invariants; validate ABI, original-runtime/all-platform and snapshot/renderer integration.

docs/research/HUFFMAN_ENCODING.md

@@ -0,0 +1,37 @@
+# Bounded Huffman send and supplied-tree symbol streams
+
+Reproduce with `python3 scripts/analyze_huffman_encoding.py`; validate with `python3 scripts/test_huffman_encoding.py`. [huffman-encoding.json](huffman-encoding.json) retains three hash-verified graphs per Linux ELF64 engine: send, Huff_offsetTransmit and Huff_offsetReceive. This follows [helper and lookup probes](HUFFMAN_HELPERS.md).
+
+These compositions evaluate native instructions over supplied trees, symbol tables and buffers. They do not run original processes or native callees. The send frame starts after register saves/stack allocation and stops before restores; its output-buffer register and stack pointer are supplied explicitly. Recursive calls are stopped, evaluated with separate virtual stack frames spaced by 0x1000, then resumed with all caller registers explicitly restored and child memory effects retained. Wrapper PUSH is omitted and execution stops before POP. This is a bounded composition model, not proven ABI behavior or native stack usage.
+
+## ENC-001 — Root-to-leaf bits, unrolled lanes and recursion (RE-349)
+
+Seven hundred twenty paired send compositions cover selected path lengths 0–10/16/17/24/32; all-zero, all-one and both alternating branch patterns; initial cursors 0/7/8; and buffer sentinels zero/0xff. Each supplied comb tree has a distinct sibling leaf at every path level, consistent parent links and one selected symbol leaf. Tree construction is synthetic and does not recover game codebooks or balancing.
+
+The composed sender walks parent pointers toward the root, then emits branches in root-to-leaf order. A child equal to the parent's right pointer at +8 produces one; other supplied consistent children produce zero. Parent links are at +16. It writes bits least-significant-first within bytes and updates global bloc. At byte boundaries the output byte clears before either branch; within a byte zero retains prior bits and one ORs its bit. Dirty starting partial bytes therefore retain prior set bits, matching the earlier raw-helper finding.
+
+Nine edges are unrolled before another recursive composition is needed. Depth nine uses one virtual frame, ten uses two, twenty-four uses three and thirty-two uses four; the sampled frame count is ceil(path_length/9). The collector stops the native recursive CALL and composes its instruction body explicitly. No original CALL or RET executes. The zero-depth entries record the wrapper's no-send case, with no send instructions or output mutation; they do not exercise send on a null current-node argument.
+
+Independent root-path bit packing verifies all sixteen retained output bytes, global cursor, outside canaries and recursion thresholds. Cyclic or inconsistent parent/child trees, null current nodes, arbitrary depths and buffer capacity are untested.
+
+## ENC-002 — Transmit and receive symbol composition (RE-350)
+
+One hundred ninety-two paired symbol round trips cover depths 0/1/2/8/9/10/17/32, four branch patterns and cursors 0/7/8. Huff_offsetTransmit selects symbol 42 through the supplied table, then its stopped send request is composed and the wrapper resumes to publish global bloc into the caller's cursor. The receive cursor is reset to the same starting position; Huff_offsetReceive traverses the same supplied tree and returns symbol 42.
+
+Both directions consume exactly the supplied path length and agree on the final cursor. Encoded bytes match independent packing; outside canaries remain intact. A zero-depth tree consists of a root leaf and yields symbol 42 with no bit consumption. This degenerate synthetic tree is useful for local wrapper behavior but is not evidence that the game's actual codebook permits zero-length symbols.
+
+These fixtures replace supplied decoder symbols with actual supplied-tree instruction traversal and replace stopped encoder requests with composed send instructions. They still do not establish the initialized adaptive tree, frequency tables, code lengths, packet compatibility or complete MSG_WriteBits/MSG_ReadBits behavior.
+
+## ENC-003 — Shared-tree multi-symbol streams (RE-351)
+
+Thirty paired sequences use one supplied complete depth-three tree, with symbols 40–47 at its eight leaves. Sequences are empty, one symbol, two ascending cycles, sixteen repeated final symbols and alternating first/final symbols, each at cursor 0/7/8. The tree remains shared throughout transmission and reception; lookup, send and receive instructions compose for every symbol.
+
+Each code is the three-bit root-to-leaf representation of symbol-minus-40, emitted root bit first but packed LSB-first within the output bytes. Every symbol advances the cursor by three. Independent stream packing verifies bytes across boundaries, both per-symbol cursor lists and decoded sequences. Repeated symbols do not trigger tree updates inside these three sampled helper functions; adaptive initialization/update ownership outside them remains open.
+
+Buffers begin at zero, while the separate dirty-buffer probes characterize retained partial-byte bits. These are supplied-codebook round trips, not real game symbol streams, network messages or corpus conformance.
+
+## Validation and next work
+
+Eight independent tests check dirty-buffer/root-path packing, nine-edge recursive thresholds, encoded bytes/symbols/cursors/canaries, supplied parent/child consistency, shared stream packing/repetition, zero-depth/empty streams, recomposed traces excluding native CALLs and paired outputs. Reports retain trace lengths/hashes and verified full graphs. No evaluator extension was needed.
+
+RE-352: recover Huffman initialization, node allocation/swapping/rank/frequency updates and actual game codebooks; compose full message writers/readers with real code lengths and packets; recover capacity/overflow/truncation and legal symbol/tree/cursor invariants; validate ABI, original-runtime/all-platform and snapshot/renderer integration before Rust implementation.

docs/research/HUFFMAN_HELPERS.md

@@ -35,3 +35,5 @@ The PUSH is explicitly changed to NOP for the virtual-frame slice; evaluation st
 Eight tests independently check exact byte clear/OR behavior, canaries and modular cursor/global writes; raw round-trip packing; tree walk and null cursor publication; unrestricted supplied leaf words; signed lookup/send request arguments; stopped CALL boundaries and paired outputs. Full verified graphs retain instruction addresses; larger probes use trace counts/hashes. No shared evaluator changes were needed.
 
 RE-348: recover all recursive/unrolled send paths and bit writes, tree/node allocation and adaptive initialization/frequency tables/codebooks; compose transmit/receive and actual message writers/readers, with real packets and truncation/overflow handling; audit legal symbol/input/cursor/tree invariants, null failure consumers and original-runtime/all-platform behavior before Rust protocol integration.
+
+Encoder follow-up: [bounded send and symbol streams](HUFFMAN_ENCODING.md) composes native send and supplied-tree transmit/receive (RE-349–351). Initialized game codebooks, full message packets and runtime/platform coverage remain open.

docs/research/README.md

@@ -129,3 +129,5 @@ The extension collector adds five focused tests for native tail calls, command-r
 [Message read modes and bit assembly](MESSAGE_BITS.md) adds RE-341–343: exact resets, OOB loads/errors/cursors and raw-bit/compressed-symbol/sign-tail compositions. Reproduce with `python3 scripts/analyze_message_bits.py`; check with `python3 scripts/test_message_bits.py`. Huffman trees, writers, legal caller invariants and real packet/runtime/platform conformance remain open.
 
 [Raw-bit helpers and supplied Huffman trees](HUFFMAN_HELPERS.md) adds RE-345–347: byte clear/OR, raw round trips, supplied-tree decoding/null cursor paths and transmit lookup/request boundaries. Reproduce with `python3 scripts/analyze_huffman_helpers.py`; check with `python3 scripts/test_huffman_helpers.py`. Full send, real codebooks/messages and runtime/platform contracts remain open.
+
+[Bounded Huffman encoding and symbol streams](HUFFMAN_ENCODING.md) adds RE-349–351: unrolled/recursive send, supplied-tree symbol round trips and shared multi-symbol streams. Reproduce with `python3 scripts/analyze_huffman_encoding.py`; check with `python3 scripts/test_huffman_encoding.py`. Actual adaptive initialization/codebooks, message packets and runtime/platform contracts remain open.

scripts/analyze_huffman_encoding.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Synthetic unrolled/recursive send and supplied-tree symbol round trips."""
+import copy
+import gzip
+import itertools
+import json
+from pathlib import Path
+from analyze_area_queries import site
+from analyze_bsp_references import global_address,trace_fields
+from analyze_collision_composition import evaluate,get_word,put_word
+from analyze_engine_control import control_flow
+from analyze_qvm import write_json
+from analyze_vm_extensions import native_functions,verified
+
+DATA,CURSOR,TREE,TABLE,OUT=0x10000,0x20000,0x30000,0x50000,0x60000
+
+
+def run(g,start,stops,m,regs):return evaluate(g,start,stops,m,regs,limit=10000,capture_registers=True)
+
+
+def send(g,m,parent,child,buffer,stack=0x80000,level=1):
+    rows=g['instructions'];start=site(g,'movq','%rdi, 0x20(%rsp)');end=site(g,'movq','0x28(%rsp), %rbx');idx=next(i for i,x in enumerate(rows) if x['opcode']=='callq');call=rows[idx]['address']
+    regs={'%rdi':parent,'%rsi':child,'%rdx':buffer,'%r12':buffer,'%rsp':stack};trace=[];frames=1;maximum=level
+    while True:
+        t=run(g,start,[call,end],m,regs);trace+=t['trace'];m=t['memory'];regs=t['registers']
+        if t['stop']==end:break
+        child_result=send(g,m,regs['rdi'],regs['rsi'],regs['rdx'],stack+0x1000,level+1)
+        m=child_result['memory'];trace+=child_result['trace'];frames+=child_result['frames'];maximum=max(maximum,child_result['maximum_depth'])
+        # Explicit restoration of all caller registers; no implicit ABI or native CALL.
+        start=rows[idx+1]['address']
+    return {'memory':m,'trace':trace,'frames':frames,'maximum_depth':maximum}
+
+
+def transmit(graphs,m,symbol,bloc):
+    g=copy.deepcopy(graphs['Huff_offsetTransmit']);rows=g['instructions']
+    for x in rows:
+        if x['opcode']=='pushq':x['opcode']='nop';x['operands']=''
+    idx=next(i for i,x in enumerate(rows) if x['opcode']=='callq');end=next(x['address'] for x in rows if x['opcode']=='popq')
+    t=run(g,rows[0]['address'],[rows[idx]['address'],end],m,{'%rdi':TABLE,'%rsi':symbol,'%rdx':DATA,'%rcx':CURSOR});trace=t['trace'];m=t['memory'];maximum=0
+    if t['stop']!=end:
+        regs=t['registers'];c=send(graphs['send'],m,regs['rdi'],regs['rsi'],regs['rdx']);m=c['memory'];trace+=c['trace'];maximum=c['maximum_depth']
+        t=run(g,rows[idx+1]['address'],[end],m,regs);trace+=t['trace'];m=t['memory']
+    return m,trace,maximum
+
+
+def comb(m,bits):
+    # Chain toward the selected leaf, with a distinct leaf sibling on every level.
+    nodes=[]
+    for i,bit in enumerate(bits):
+        addr=TREE+128*i;nxt=addr+128;sibling=addr+64;left,right=(sibling,nxt) if bit else (nxt,sibling)
+        for node,l,r,parent,symbol in [(addr,left,right,addr-128 if i else 0,257),(sibling,0,0,addr,80+i)]:
+            put_word(m,node,l,8);put_word(m,node+8,r,8);put_word(m,node+16,parent,8);put_word(m,node+52,symbol);nodes.append([node,l,r,parent,symbol])
+    leaf=TREE+128*len(bits);put_word(m,leaf,0,8);put_word(m,leaf+8,0,8);put_word(m,leaf+16,leaf-128 if bits else 0,8);put_word(m,leaf+52,42);nodes.append([leaf,0,0,leaf-128 if bits else 0,42]);put_word(m,TABLE+32+8*42,leaf,8)
+    return leaf,nodes
+
+
+def buffer_memory(start,sentinel):
+    m={DATA+i:sentinel for i in range(-1,17)};m[DATA-1]=m[DATA+16]=0x7b;put_word(m,CURSOR,start);return m
+
+
+def receive(g,m):
+    stops=[x['address'] for x in g['instructions'] if x['opcode']=='retq']
+    return run(g,g['instructions'][0]['address'],stops,m,{'%rdi':TREE,'%rsi':OUT,'%rdx':DATA,'%rcx':CURSOR})
+
+
+def main():
+    out={'native':{},'limitations':'Paired Linux ELF64 synthetic instruction compositions only. Trees/tables/virtual buffers and disjoint stack frames supplied. send prologue/epilogue excluded; wrapper PUSH omitted; all callers restored explicitly across stopped CALL boundaries. No original process/native callee or actual tree initialization/codebook/message packet executes. Cycles, invalid parent/child links, capacity/truncation/overflow, ABI, real codecs and all-platform/runtime conformance remain open.'}
+    for label in ['linux--Quake3-UrT-Ded.x86_64','linux--Quake3-UrT.x86_64']:
+        r=json.loads(Path(f'docs/research/native/{label}.json').read_text());verified((Path('.cache/UrbanTerror43')/r['source']['path']).read_bytes(),r['source']['sha256']);a=r['artifacts']['disassembly.txt'];fs=native_functions(verified(gzip.open(a['path'],'rb').read(),a['uncompressed_sha256']).decode());graphs={n:control_flow(fs[n]) for n in ['send','Huff_offsetTransmit','Huff_offsetReceive']}
+        bloc=global_address(next(x for x in graphs['send']['instructions'] if '(%rip)' in x['operands']));probes=[];roundtrips=[]
+        for depth,pattern,sentinel,start in itertools.product(list(range(11))+[16,17,24,32],range(4),[0,255],[0,7,8]):
+            bits=[0 if pattern==0 else 1 if pattern==1 else i%2 if pattern==2 else (i+1)%2 for i in range(depth)];m=buffer_memory(start,sentinel);leaf,nodes=comb(m,bits);put_word(m,bloc,start)
+            if depth:t=send(graphs['send'],m,leaf-128,leaf,DATA)
+            else:t={'memory':m,'trace':[],'frames':0,'maximum_depth':0}
+            m=t['memory'];probes.append({'depth':depth,'path_bits':bits,'sentinel':sentinel,'initial_bit':start,'encoded_bytes':[m[DATA+i] for i in range(16)],'final_global':get_word(m,bloc),'canaries':[m[DATA-1],m[DATA+16]],'frames':t['frames'],'maximum_depth':t['maximum_depth'],**trace_fields(t,False)})
+        for depth,pattern,start in itertools.product([0,1,2,8,9,10,17,32],range(4),[0,7,8]):
+            bits=[0 if pattern==0 else 1 if pattern==1 else i%2 if pattern==2 else (i+1)%2 for i in range(depth)];m=buffer_memory(start,0);leaf,nodes=comb(m,bits);m,trace,maximum=transmit(graphs,m,42,bloc);end=get_word(m,CURSOR);encoded=[m[DATA+i] for i in range(16)];put_word(m,CURSOR,start)
+            t=receive(graphs['Huff_offsetReceive'],m);m=t['memory'];trace+=t['trace']
+            roundtrips.append({'depth':depth,'path_bits':bits,'initial_bit':start,'nodes':nodes,'encoded_bytes':encoded,'transmit_cursor':end,'received_symbol':get_word(m,OUT),'receive_cursor':get_word(m,CURSOR),'final_global':get_word(m,bloc),'canaries':[m[DATA-1],m[DATA+16]],'maximum_depth':maximum,**trace_fields({'trace':trace},False)})
+        sequences=[]
+        for sequence,start in itertools.product([[],[40],list(range(40,48))*2,[47]*16,[40,47]*8],[0,7,8]):
+            m=buffer_memory(start,0);nodes=[]
+            for i in range(15):
+                addr=TREE+64*i;internal=i<7;left=TREE+64*(2*i+1) if internal else 0;right=TREE+64*(2*i+2) if internal else 0;parent=TREE+64*((i-1)//2) if i else 0;symbol=257 if internal else 40+i-7
+                put_word(m,addr,left,8);put_word(m,addr+8,right,8);put_word(m,addr+16,parent,8);put_word(m,addr+52,symbol);nodes.append([addr,left,right,parent,symbol])
+                if not internal:put_word(m,TABLE+32+8*symbol,addr,8)
+            trace=[];cursors=[]
+            for symbol in sequence:m,part,_=transmit(graphs,m,symbol,bloc);trace+=part;cursors.append(get_word(m,CURSOR))
+            encoded=[m[DATA+i] for i in range(16)];put_word(m,CURSOR,start);decoded=[];readcursors=[]
+            for _ in sequence:
+                t=receive(graphs['Huff_offsetReceive'],m);m=t['memory'];trace+=t['trace'];decoded.append(get_word(m,OUT));readcursors.append(get_word(m,CURSOR))
+            sequences.append({'symbols':sequence,'initial_bit':start,'nodes':nodes,'encoded_bytes':encoded,'decoded_symbols':decoded,'transmit_cursors':cursors,'receive_cursors':readcursors,'canaries':[m[DATA-1],m[DATA+16]],**trace_fields({'trace':trace},False)})
+        out['native'][label]={'source':r['source'],'disassembly_sha256':a['uncompressed_sha256'],'graphs':graphs,'send_probes':probes,'roundtrips':roundtrips,'sequences':sequences}
+    write_json(Path('docs/research/huffman-encoding.json'),out);print('Recovered 720 send compositions, 192 symbol round trips and 30 shared-tree sequences')
+
+
+if __name__=='__main__':main()

scripts/test_huffman_encoding.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Independent root-path packing, recursive depth and symbol stream oracles."""
+import json
+from pathlib import Path
+import unittest
+from analyze_huffman_encoding import DATA,TREE,buffer_memory,comb,send
+from analyze_bsp_references import global_address
+from analyze_collision_composition import put_word
+
+
+def packed(bits,start,sentinel=0):
+    out=[sentinel]*16
+    for i,bit in enumerate(bits):
+        p=start+i
+        if p%8==0:out[p//8]=0
+        out[p//8]|=bit<<(p%8)
+    return out
+
+
+class HuffmanEncodingTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):cls.r=json.loads(Path('docs/research/huffman-encoding.json').read_text())
+
+    def test_root_first_path_bits_and_dirty_byte_packing(self):
+        for n in self.r['native'].values():
+            self.assertEqual(len(n['send_probes']),360)
+            for p in n['send_probes']:
+                self.assertEqual(p['encoded_bytes'],packed(p['path_bits'],p['initial_bit'],p['sentinel']))
+                self.assertEqual(p['final_global'],p['initial_bit']+p['depth']);self.assertEqual(p['canaries'],[0x7b]*2)
+
+    def test_nine_edge_unrolling_and_recursion_threshold(self):
+        for n in self.r['native'].values():
+            for p in n['send_probes']:
+                expected=(p['depth']+8)//9;self.assertEqual(p['frames'],expected);self.assertEqual(p['maximum_depth'],expected)
+            self.assertTrue(any(p['depth']==32 and p['maximum_depth']==4 for p in n['send_probes']))
+
+    def test_symbol_roundtrips_match_paths_and_exact_cursors(self):
+        for n in self.r['native'].values():
+            self.assertEqual(len(n['roundtrips']),96)
+            for p in n['roundtrips']:
+                self.assertEqual(p['encoded_bytes'],packed(p['path_bits'],p['initial_bit']));self.assertEqual(p['received_symbol'],42)
+                for k in ['transmit_cursor','receive_cursor','final_global']:self.assertEqual(p[k],p['initial_bit']+p['depth'])
+                self.assertEqual(p['canaries'],[0x7b]*2)
+
+    def test_supplied_parent_and_child_paths_are_consistent(self):
+        for n in self.r['native'].values():
+            for p in n['roundtrips']:
+                nodes={x[0]:x for x in p['nodes']};node=TREE
+                for bit in p['path_bits']:
+                    child=nodes[node][2 if bit else 1];self.assertEqual(nodes[child][3],node);self.assertEqual(nodes[node][4],257);node=child
+                self.assertEqual(nodes[node][4],42);self.assertEqual(nodes[node][1:3],[0,0]);self.assertEqual(nodes[TREE][3],0)
+
+    def test_shared_tree_stream_byte_packing_and_repeated_symbols(self):
+        for n in self.r['native'].values():
+            self.assertEqual(len(n['sequences']),15)
+            for p in n['sequences']:
+                bits=[((symbol-40)>>shift)&1 for symbol in p['symbols'] for shift in [2,1,0]]
+                self.assertEqual(p['encoded_bytes'],packed(bits,p['initial_bit']));self.assertEqual(p['decoded_symbols'],p['symbols'])
+                expected=[p['initial_bit']+3*(i+1) for i in range(len(p['symbols']))]
+                self.assertEqual(p['transmit_cursors'],expected);self.assertEqual(p['receive_cursors'],expected);self.assertEqual(p['canaries'],[0x7b]*2)
+
+    def test_zero_edge_and_empty_stream_have_no_output_mutations(self):
+        for n in self.r['native'].values():
+            for p in n['send_probes']:
+                if p['depth']==0:self.assertEqual(p['encoded_bytes'],[p['sentinel']]*16);self.assertEqual(p['trace_length'],0)
+            for p in n['sequences']:
+                if not p['symbols']:self.assertEqual(p['encoded_bytes'],[0]*16);self.assertEqual(p['trace_length'],0)
+
+    def test_recomposed_trace_excludes_native_calls_and_has_bounded_frames(self):
+        for n in self.r['native'].values():
+            g=n['graphs']['send'];m=buffer_memory(7,0);bits=[i%2 for i in range(32)];leaf,_=comb(m,bits)
+            bloc=global_address(next(x for x in g['instructions'] if '(%rip)' in x['operands']));put_word(m,bloc,7)
+            t=send(g,m,leaf-128,leaf,DATA);calls={x['address'] for x in g['instructions'] if x['opcode']=='callq'}
+            self.assertTrue(calls.isdisjoint(t['trace']));self.assertEqual(t['maximum_depth'],4);self.assertEqual([t['memory'][DATA+i] for i in range(16)],packed(bits,7))
+
+    def test_paired_outputs_match_without_instruction_hashes(self):
+        a,b=self.r['native'].values()
+        for key in ['send_probes','roundtrips','sequences']:
+            def clean(rows):return [{k:v for k,v in p.items() if k not in ['trace','trace_sha256']} for p in rows]
+            self.assertEqual(clean(a[key]),clean(b[key]))
+
+
+if __name__=='__main__':unittest.main()