MetaCrate/benchmarks/README.md

# Pinned cross-runtime performance evidence

This directory compares representative offline work in native Rust with the
pinned C# source at commit `2aa70bb68513b39795da5d13c88f31b86e85a3ba`.
The runners are separate executables. The Rust executable never starts a CLR,
loads a managed assembly, accesses a grid, or reads `.env`.

## Workloads and fixtures

`fixtures/manifest.json` records SHA-256 for every shared input. Both runners
refuse a changed fixture. The suite measures UUID/matrix/quaternion operations,
all five supported LLSD codecs, packet encode/decode, notecard/TGA/mesh decode,
inventory and object updates, simple rendering, and a batched offline client
message pipeline. Each report contains one cold operation and seven warm
samples. It records latency, throughput, allocated bytes, retained heap bytes,
and allocation count where the runtime exposes it. .NET reports a null
allocation count because its supported in-process GC API exposes bytes, not
operation count; it does not substitute a misleading zero.

The checked-in inputs are deliberately modest so the suite completes on a
four-core, 8 GiB release worker. Iteration counts live in `workloads.json`.
Regenerate binary inputs only after an intentional fixture review:

```sh
cargo run -p metacrate-performance --profile benchmark -- \
  fixtures --fixture-root benchmarks/fixtures
```

## Reproducing the reports

Use the same otherwise-idle machine for both runs. Disable adaptive power or
thermal throttling where the host permits it. The committed evidence was
captured on Linux x86-64 with four AMD EPYC-Genoa vCPUs and 7.6 GiB RAM, Rust
1.97.1, .NET SDK 10.0.400, and the .NET 8.0.30 runtime. C# is built in Release
for `net8.0`. Rust uses the repository's `benchmark` profile (opt-level 1,
debug/incremental disabled): higher optimization of the generated core exceeds
the memory limit on this release worker, so this is a conservative Rust result.

```sh
REFERENCE_ROOT=/absolute/path/to/libremetaverse
test "$(git -C "$REFERENCE_ROOT" rev-parse HEAD)" = \
  2aa70bb68513b39795da5d13c88f31b86e85a3ba

dotnet build benchmarks/csharp-reference/MetaCrate.ReferenceBenchmarks.csproj \
  -c Release -p:ReferenceRoot="$REFERENCE_ROOT"
dotnet benchmarks/csharp-reference/bin/Release/net8.0/MetaCrate.ReferenceBenchmarks.dll \
  run --reference-root "$REFERENCE_ROOT" \
  --fixture-root benchmarks/fixtures \
  --output benchmarks/results/csharp-linux-x86_64.json

cargo run -p metacrate-performance --profile benchmark -- \
  run --fixture-root benchmarks/fixtures \
  --output benchmarks/results/rust-linux-x86_64.json
cargo run -p metacrate-performance --profile benchmark -- \
  compare --rust benchmarks/results/rust-linux-x86_64.json \
  --reference benchmarks/results/csharp-linux-x86_64.json \
  --output benchmarks/results/comparison.json
cargo run -p metacrate-performance --profile benchmark -- \
  audit --fixture-root benchmarks/fixtures \
  --rust benchmarks/results/rust-linux-x86_64.json \
  --reference benchmarks/results/csharp-linux-x86_64.json \
  --comparison benchmarks/results/comparison.json
```

The C# runner executes `git rev-parse` itself and rejects any other source
commit. The comparison rejects different fixture hashes, operating systems, or
architectures.

## Release criteria and reviewed differences

`release-criteria.json` is executable policy. A warm median at least 25% slower
than the reference is material and must be reviewed; the hard default is no
more than 2.0x latency or allocated bytes. Reference operations below one
microsecond are latency-noise exempt, but not allocation exempt.

Three workload-specific differences are accepted:

- Rust LLSD JSON owns and validates the bounded decoded tree. It is over four
  times faster in this evidence, so up to 2.1x allocated bytes is accepted.
- Rust rendering performs the completed behavior: six faces, 24 vertices, 36
  indices, checked normals, UVs, extents, and materials. The pinned C#
  `SimpleRenderer` still returns a one-face/eight-vertex placeholder cube.
  Slowing Rust down by removing correctness would violate the milestone, so the
  policy accepts up to 8x latency and 4x allocated bytes for this workload.
- Rust client throughput returns checked `Result` values and owns the bounded
  OSD map throughout the message pipeline. It allocates fewer bytes than C#;
  its measured 1.64x latency is reviewed up to the unchanged 2x hard limit.

No exception permits changed wire data, decoded values, fixture output, or
public behavior. Any other threshold failure blocks the audit.