PLT-460: Distribution samplers (uniform, zipfian θ)

[bdchatham]

Implements PLT-460 — the real SampleIndex samplers behind the PLT-455 Distribution type, drawing from PLT-456 seeded sub-streams.

What

• Uniform: O(1) draw into [0,n).
• Zipfian(θ): YCSB precomputed-zeta — zeta computed once (O(N)) and cached, O(1) per draw. θ→0 collapses to uniform, θ→1 heavy hotspot. Smallest-term-first summation for numerical stability at large N.
• Seeded via Distribution.SetStream (mirrors GasPicker.SetStream); new dist:%d:key / dist:%d:size stream ids added to the FROZEN contract (append-only, non-perturbing). Unbound → global RNG (preserves the unseeded path).

Review (systems + idiom)

• Zipfian PMF independently validated against true Zipf; top-k skew monotone in θ (θ=0→1%, 0.5→9.5%, 0.9→42%). Determinism + per-stream-multiset contract upheld; -race clean.
• Fixes applied: guarded a masked eta NaN at n≤2; documented the n-must-be-stable contract; renamed a builtin-shadowing helper + a misleading field; marked the mutex-bearing struct copy-unsafe.

Decision brief: designs/sei-load-workload-modeler/PLT-460-distribution-samplers.md.

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Changes workload randomness and adds frozen RNG stream ids that affect replay compatibility; zipfian math and caching are subtle but heavily tested and documented.

Overview
Replaces the PLT-455 Distribution stubs with real uniform and YCSB zipfian(θ) index samplers, wired for seeded replay like the gas pickers.

Uniform draws in [0, n) via rng.Stream.Uint64N or the global RNG when unbound. Zipfian uses precomputed zeta(n, θ) (cached per n under a mutex), O(1) draws, smallest-term-first summation, and guards for n ≤ 2 / float rounding. Distribution.SetStream binds samplers; n == 0 now returns an error instead of silently returning 0.

The generator calls bindDistributionStreams for each scenario’s KeyDistribution / SizeDistribution using new append-only frozen stream ids dist:%d:key and dist:%d:size. Package config/doc.go documents wire format, math, and reproducibility contracts.

Tests add determinism, seeded vs unseeded, chi-square uniform check, zipfian skew vs θ, init cost, and numerical edge cases.

^{Reviewed by Cursor Bugbot for commit f638310. Bugbot is set up for automated code reviews on this repo. Configure here.}