test: add benchmarks, runnable examples, and bench-regression infrastructure

[millerjp]

test: add benchmarks, runnable examples, and bench-regression infrastructure

Summary

Add syncmap_bench_test.go (benchmarks for every public method plus concurrent patterns and an overhead comparison against raw sync.Map), example_test.go (runnable godoc Example functions for every public symbol), and the bench.txt baseline + scripts/check-bench-regression.sh wiring that re-enables mask's benchstat-regression-guard CI job.

Requirements

1. syncmap_bench_test.go (package syncmap_test, Apache 2.0 header):
   • One Benchmark* per public symbol: BenchmarkLoad, BenchmarkStore, BenchmarkLoadOrStore, BenchmarkLoadAndDelete, BenchmarkDelete, BenchmarkRange, BenchmarkLen, BenchmarkMap, BenchmarkKeys, BenchmarkValues (or Items if rename #(rename-issue) hasn't landed), BenchmarkSwap, BenchmarkClear, BenchmarkCompareAndSwap, BenchmarkCompareAndDelete.
   • Every benchmark calls b.ReportAllocs().
   • Concurrent patterns: BenchmarkConcurrentReadWrite with b.RunParallel and a realistic read/write ratio.
   • Overhead comparison: BenchmarkOverhead_LoadSyncMap vs BenchmarkOverhead_LoadRawSyncMap (and the same pair for Store, Delete, LoadOrStore, LoadAndDelete) to quantify the generic-wrapper cost.
2. example_test.go (package syncmap_test, Apache 2.0 header):
   • One Example* per public symbol — ExampleSyncMap, ExampleSyncMap_Load, ExampleSyncMap_Store, etc. — each ending with // Output: so they run under go test.
3. bench.txt — committed baseline, produced by go test -bench=. -benchmem -run=^$ -count=5 ./... > bench.txt on an ubuntu-latest-equivalent host.
4. scripts/check-bench-regression.sh — mirror mask's script verbatim (adjust repo-specific paths if any). Exits non-zero when benchstat reports a regression beyond the tolerated threshold.
5. Makefile — re-add the bench-regression target (removed in chore: align CI, release, and tooling to axonops/mask pattern #8 for lack of script). makefile-targets-guard in ci.yml updates its expected list to include it.
6. ci.yml — re-enable the benchstat-regression-guard job from mask (currently commented out / deferred).
7. Apache headers on all new .go files. No AI-attribution tokens. No timing-based synchronisation in Examples (use WaitGroup if any goroutine is spawned; ideally Examples are single-threaded).
8. Benchmarks must have zero additional allocations beyond what sync.Map itself allocates for Load, Store, Delete, LoadOrStore, LoadAndDelete — confirmed by b.ReportAllocs() output and compared to the raw-sync.Map baseline.

Acceptance Criteria

1. syncmap_bench_test.go exists with ≥14 Benchmark* functions (one per public symbol plus concurrent + overhead sets).
2. example_test.go exists with ≥10 Example* functions, one per public symbol.
3. go test -run 'Example' ./... passes — all Examples have matching // Output: blocks.
4. go test -bench=. -benchmem -run=^$ -count=1 ./... produces output for every benchmark; allocs/op for BenchmarkLoad, BenchmarkStore, BenchmarkDelete, BenchmarkLoadOrStore, BenchmarkLoadAndDelete matches (or is within one alloc of) the corresponding BenchmarkOverhead_…RawSyncMap baseline.
5. bench.txt exists at repo root and contains count=5 sample runs for every Benchmark*.
6. scripts/check-bench-regression.sh exists, is executable, and mirrors mask's script.
7. make bench-regression runs benchstat against bench.txt vs a fresh current.txt and exits 0 on an unchanged tree.
8. makefile-targets-guard passes with bench-regression added to its expected list.
9. benchstat-regression-guard job in ci.yml is enabled and passes on this PR.
10. make check and CI green.

Testing Requirements

• go test -run 'Example' ./... — green.
• make bench-regression — green locally on an unchanged tree.
• CI benchstat-regression-guard — green on this PR.
• Coverage not regressed (Examples may add to coverage; benchmarks don't affect -cover).

Documentation Requirements

• Each Example's comment above the function briefly describes the scenario (matching godoc example conventions).
• README additions for "Performance" section (one-line summary + link to the benchstat report) live in feat: add top-level CompareAndSwap and CompareAndDelete functions #14.

Dependencies

• Blocked by: test: rewrite unit tests to external package with testify/goleak; coverage ≥95% #10 (test scaffolding), plus ideally chore: align CI, release, and tooling to axonops/mask pattern (#8) #9 (Swap, Clear) and test: rewrite unit tests to external package with testify/goleak; coverage ≥95% #10 CAS (CompareAndSwap/Delete) so their benchmarks can land in this PR rather than a follow-up. If those haven't merged, this PR benchmarks what exists and a minor follow-up adds the missing benchmarks.
• Blocks: v1.0.0 release quality gate — performance regression protection.

Labels

• testing
• performance
• P1

[millerjp]

Bookkeeping from #14 (merged via PR #22): syncmap_bench_test.go now exists on main and already contains BenchmarkCompareAndSwap, BenchmarkCompareAndSwapMismatch, BenchmarkCompareAndDelete, BenchmarkCompareAndSwapParallel. #15 extends this file with benchmarks for every other public method, the raw-sync.Map overhead comparison set, and the committed bench.txt baseline + scripts/check-bench-regression.sh.