Benchmark Rust against pinned C# reference (#105)

benchmarks/REPORT.md

@@ -0,0 +1,41 @@
+# Performance comparison report
+
+Accepted evidence captured 2026-08-12 on the Linux x86-64 host documented in
+`README.md`. Ratios are Rust divided by the pinned C# reference; lower is
+better. Bytes are allocated bytes per operation. Full cold and seven-sample
+warm measurements, throughput, allocation count support, retained heap, hashes,
+and toolchains are in `results/`.
+
+| Workload | Rust latency | C# latency | Ratio | Rust bytes | C# bytes | Result |
+|---|---:|---:|---:|---:|---:|---|
+| UUID/math | 107 ns | 105 ns | 1.02x | 36 | 40 | pass |
+| LLSD XML | 23.36 us | 38.74 us | 0.60x | 10,939 | 28,600 | pass |
+| LLSD JSON | 5.23 us | 21.72 us | 0.24x | 7,447 | 3,680 | reviewed pass |
+| LLSD binary | 2.69 us | 11.07 us | 0.24x | 6,749 | 7,960 | pass |
+| LLSD notation | 7.01 us | 18.87 us | 0.37x | 8,489 | 10,096 | pass |
+| LLSD protobuf | 7.34 us | 30.97 us | 0.24x | 8,324 | 26,120 | pass |
+| Packet codec | 209 ns | 176 ns | 1.19x | 124 | 264 | pass |
+| Asset decode | 288 ns | 2.98 us | 0.10x | 1,246 | 4,512 | pass |
+| Image decode | 42.67 us | 48.27 us | 0.88x | 65,536 | 131,612 | pass |
+| Mesh decode | 413.29 us | 378.54 us | 1.09x | 507,740 | 564,593 | pass |
+| Inventory update | 972 ns | 758 ns | 1.28x | 373 | 357 | pass |
+| Object update | 27 ns | 46 ns | 0.59x | 16 | 11 | pass |
+| Rendering | 5.22 us | 1.01 us | 5.15x | 9,480 | 3,048 | reviewed pass |
+| Client throughput | 6.23 us | 3.80 us | 1.64x | 11,795 | 12,054 | reviewed pass |
+
+The initial profile exposed two actionable regressions. Root inventory updates
+rebuilt the entire hierarchy and link index on every record; the new guarded
+root path updates only the affected node/link and changed the comparison from
+about 22.6x latency and 10.2x allocation to 1.28x and 1.05x. TGA decoding copied
+the input stream and dispatched every ordinary pixel through the fully generic
+orientation/palette path; the checked borrowed-input and common-layout path
+changed it from about 3.4x latency and 2.0x allocation to 0.88x and 0.50x.
+
+LLSD JSON, rendering, and client throughput are the reviewed differences. JSON
+trades 2.02x allocated bytes for 4.15x lower latency. Rendering cannot be
+compared as equal work: the pinned C# method is a placeholder one-face cube,
+while Rust returns the required complete checked mesh. Client throughput is
+1.64x slower while allocating fewer bytes because Rust preserves checked
+results and bounded owned maps. The executable limits and rationales are in
+`release-criteria.json`; every other workload passes the default criteria or
+the documented sub-microsecond noise rule.