[jasperpotts]

Closes #1036. Stacked on #1035 (1031-array-parser-nested), because the documents describe features that only exist there.

Summary

Everything the fast code generation series (#991 to #1035) learned about performance, collected where the next round of work will find it, instead of spread over twenty PR descriptions. Documentation only; no code changes.

Performance: no change. These documents record the numbers measured in the series.

docs/performance/:

• README.md: an index, and ten rules to remember (decide on AMD EPYC, measure the real shape of the data, keep generated methods under 8,000 bytes, per-message cost is the cost, …).
• measuring.md: the method:
  • why decisions are made on AMD EPYC rather than Apple Silicon;
  • JMH pitfalls: cached sizes, Level.Invocation, interleaving, pinning, two machines;
  • async-profiler and PrintInlining recipes;
  • allocation tests and the JIT.
• jit-and-inlining.md:
  • HotSpot's inlining and method-size limits, with hot against cold call sites;
  • reading PrintInlining;
  • which inlining changes paid (the varint reader split) and which didn't (the writer's varint).
• format-comparison.md:
  • protobuf and PBJ against SBE, H2O, Borsh, SSZ, MessagePack, RLP, Cap'n Proto, FlatBuffers and Kryo, on an independent block-stream workload: speed, raw and zstd size, and determinism (a canonical protobuf subset);
  • parsing in a smart contract;
  • where the gap to fixed-width formats comes from, and schema-design guidance.
• zero-allocation.md:
  • the garbage-free paths (array parser, reverse writer, views, unboxed oneofs, writers) and why their APIs look as they do;
  • what each nested message costs;
  • what's left (a streaming pull reader, writers on a reverse buffer, a leaner model);
  • per-feature numbers on both workloads.
• history.md: every PR in the series, with what it changed and why, its numbers, and the final table against 0.16.4 and the hand-written reference codec. Tried-and-reverted lessons stay in §9 of docs/fast-codegen-plan.md and are linked, not copied.

CLAUDE.md gains a "Performance Work" section pointing at docs/performance/README.md, so future sessions start from what is already known.

All numbers are from two identical AMD EPYC 9275F machines.

Checks

• Every relative link and anchor resolves.
• Prose is wrapped at 120 characters.

🤖 Generated with Claude Code

[github-actions]

JUnit Test Report

   559 files  ±0     559 suites  ±0   1m 25s ⏱️ ±0s
 2 118 tests ±0   2 114 ✅ ±0   4 💤 ±0  0 ❌ ±0 
11 650 runs  ±0  11 622 ✅ ±0  28 💤 ±0  0 ❌ ±0 

Results for commit 94223e0. ± Comparison against base commit ce64ed7.

[github-actions]

Integration Test Report

    661 files  ±0      661 suites  ±0   57m 54s ⏱️ ±0s
164 383 tests ±0  164 383 ✅ ±0  0 💤 ±0  0 ❌ ±0 
652 346 runs  ±0  652 346 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 94223e0. ± Comparison against base commit ce64ed7.