docs: enhance benchmark documentation with value construction convention

benches/reports.rs

@@ -2,6 +2,15 @@
 //!
 //! This is a standalone binary (not a criterion benchmark) that prints
 //! human-readable comparison tables for cache policy evaluation.
+//!
+//! ## Value construction convention
+//!
+//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc<V>` so callers
+//! choose what to store. We pass [`Arc::new`] directly, which the compiler
+//! resolves to `fn(u64) -> Arc<u64>`, i.e. the value is the key itself wrapped
+//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't
+//! depend on payload contents, so the cheapest possible payload keeps the
+//! workload focused on policy behavior rather than allocator/clone cost.
 
 use bench_support as common;
 use bench_support::for_each_policy;

benches/runner.rs

@@ -4,6 +4,15 @@
 //! JSON results to `target/benchmarks/<run-id>/results.json`.
 //!
 //! Run with: `cargo bench --bench runner`
+//!
+//! ## Value construction convention
+//!
+//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc<V>` so callers
+//! choose what to store. We pass [`Arc::new`] directly, which the compiler
+//! resolves to `fn(u64) -> Arc<u64>`, i.e. the value is the key itself wrapped
+//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't
+//! depend on payload contents, so the cheapest possible payload keeps the
+//! workload focused on policy behavior rather than allocator/clone cost.
 
 use bench_support as common;
 use bench_support::for_each_policy;

benches/workloads.rs

@@ -11,6 +11,15 @@
 //! For micro-ops (get/insert latency), see: `cargo bench --bench ops`
 //! For policy-specific operations, see: `cargo bench --bench policy_*`
 //! For external crate comparison, see: `cargo bench --bench comparison`
+//!
+//! ## Value construction convention
+//!
+//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc<V>` so callers
+//! choose what to store. We pass [`Arc::new`] directly, which the compiler
+//! resolves to `fn(u64) -> Arc<u64>`, i.e. the value is the key itself wrapped
+//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't
+//! depend on payload contents, so the cheapest possible payload keeps the
+//! workload focused on policy behavior rather than allocator/clone cost.
 
 use bench_support as common;
 use bench_support::for_each_policy;