feat(sampling): Implement VarOptItemsSketch core functionality

[Fengzdadi]

Summary

This PR implements the core VarOptItemsSketch[T] for variance-optimal weighted sampling, following the C++ and Java implementations exactly. ref #98

Changes

internal/family.go

• Added VarOptItems family (ID=13, MaxPreLongs=4)

sampling/varopt_items_sketch.go (new file, ~520 lines)

• VarOptItemsSketch[T] struct with fields: k, n, h, m, r, totalWeightR, data, weights
• Update algorithm matching C++/Java:
  • Warmup mode (h ≤ k): stores all items directly
  • Transition at h > k via transitionFromWarmup()
  • growCandidateSet() / downsampleCandidateSet() for variance-optimal sampling
  • chooseDeleteSlot() / chooseWeightedDeleteSlot() for weighted random selection
• Min-heap operations: heapify(), siftUp(), siftDown()
• Go 1.23 iterator: Samples() iter.Seq2[T, float64] for elegant range iteration

sampling/varopt_items_sketch_test.go (new file, ~218 lines)

8 unit tests matching C++ test coverage:

• TestVarOptItemsSketch_NewSketch - constructor and k validation
• TestVarOptItemsSketch_WarmupPhase - exact mode behavior
• TestVarOptItemsSketch_TransitionToEstimation - h > k transition
• TestVarOptItemsSketch_EstimationMode - sampling mode invariants
• TestVarOptItemsSketch_InvalidWeight - negative/zero weight handling
• TestVarOptItemsSketch_Reset - reset state verification
• TestVarOptItemsSketch_UniformWeights - reservoir-like behavior
• TestVarOptItemsSketch_CumulativeWeight - weight sum preservation (matches C++ test with exp(5*N(0,1)) distribution and 1e-13 tolerance)

API Usage

sketch, _ := NewVarOptItemsSketch[string](256)

// Add weighted items
sketch.Update("item1", 1.5)
sketch.Update("item2", 3.0)

// Iterate samples
for item, weight := range sketch.Samples() {
    fmt.Printf("Item: %s, Weight: %f\n", item, weight)
}

Note

The current implementation includes detailed comments for clarity. If the reviewers prefer, we can simplify the comments.

[proost]

can you consider functional options pattern? so you can integrate with "NewVarOptItemsSketch"

[proost]

returing struct like

type Sample[T] struct {
    data T
    Weight float64
}

is more clear API.

NOTE: convention is using All. ref: https://pkg.go.dev/iter#hdr-Naming_Conventions

[proost]

It should not panic. can you returning error?

[Fengzdadi]

Thanks for the great feedback @proost! I've addressed all three points. I learned a lot about Go design philosophy from your review - still have much to learn about idiomatic Go patterns :)

[proost]

Thank you!