github.com/beorn7/perks v1.0.1: compute approximate stream quantiles with targeted error bounds

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: compute approximate stream quantiles with targeted error bounds
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/beorn7/perks@v1.0.1
Demonstrate these symbols/APIs:
  - github.com/beorn7/perks/quantile.(*Stream).Insert
  - github.com/beorn7/perks/quantile.(*Stream).Query
  - github.com/beorn7/perks/quantile.NewTargeted

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

package sample

import (
	"math"
	"testing"
)

func TestContractQuantile(t *testing.T) {
	// 1. quantile.NewTargeted initializes a quantile Stream for specified quantile targets and error bounds
	targets := map[float64]float64{
		0.50: 0.01,
		0.90: 0.01,
		0.99: 0.001,
	}
	stream := NewTargetedStream(targets)
	if stream == nil {
		t.Fatal("expected non-nil stream from NewTargetedStream")
	}
	if count := stream.Count(); count != 0 {
		t.Fatalf("expected initial count 0, got %d", count)
	}

	// 2. quantile.Stream.Insert inserts float64 observations into the stream and increments Count
	n := 1000
	values := make([]float64, n)
	for i := 0; i < n; i++ {
		values[i] = float64(i + 1)
	}
	InsertValues(stream, values)

	if count := stream.Count(); count != n {
		t.Fatalf("expected count %d after insertions, got %d", n, count)
	}

	// 3. quantile.Stream.Query computes approximate quantiles within configured error bounds
	p50 := QueryQuantile(stream, 0.50)
	expectedP50 := 500.0
	if math.Abs(p50-expectedP50) > 20.0 {
		t.Fatalf("expected p50 within [480, 520], got %f", p50)
	}

	p90 := QueryQuantile(stream, 0.90)
	expectedP90 := 900.0
	if math.Abs(p90-expectedP90) > 20.0 {
		t.Fatalf("expected p90 within [880, 920], got %f", p90)
	}

	p99 := QueryQuantile(stream, 0.99)
	expectedP99 := 990.0
	if math.Abs(p99-expectedP99) > 15.0 {
		t.Fatalf("expected p99 within [975, 1000], got %f", p99)
	}

	// 4. quantile.Stream.Reset clears stream observations and resets Count to 0
	ResetStream(stream)
	if count := stream.Count(); count != 0 {
		t.Fatalf("expected count 0 after reset, got %d", count)
	}
}

{"case":{"caseId":"case:sha256:3eb659688258c2a47af50f0c0cf312972acac4d1dd2721b6355fc0e807d327cf","contract":["quantile.NewTargeted initializes a quantile Stream for specified quantile targets and error bounds","quantile.Stream.Insert inserts float64 observations into the stream and increments Count","quantile.Stream.Query computes approximate quantiles within configured error bounds","quantile.Stream.Reset clears stream observations and resets Count to 0"],"goal":"compute approximate stream quantiles with targeted error bounds","kind":"HOW","packages":["pkg:golang/github.com/beorn7/perks@v1.0.1"],"schemaVersion":1,"symbols":["github.com/beorn7/perks/quantile.(*Stream).Insert","github.com/beorn7/perks/quantile.(*Stream).Query","github.com/beorn7/perks/quantile.NewTargeted"]},"contractCommand":["go","test","./..."],"environment":{"arch":"amd64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/beorn7/perks@v1.0.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/beorn7/perks@v1.0.1","symbols":["github.com/beorn7/perks/quantile.(*Stream).Insert","github.com/beorn7/perks/quantile.(*Stream).Query","github.com/beorn7/perks/quantile.NewTargeted"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.26.6

require github.com/beorn7/perks v1.0.1

github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=

package sample

import (
	"github.com/beorn7/perks/quantile"
)

// NewTargetedStream creates a new Stream targeting specific quantiles and invariant tolerances.
func NewTargetedStream(targets map[float64]float64) *quantile.Stream {
	return quantile.NewTargeted(targets)
}

// InsertValues inserts a slice of float64 data points into the quantile stream.
func InsertValues(stream *quantile.Stream, values []float64) {
	for _, v := range values {
		stream.Insert(v)
	}
}

// QueryQuantile queries the estimated value for a given quantile q (0.0 <= q <= 1.0).
func QueryQuantile(stream *quantile.Stream, q float64) float64 {
	return stream.Query(q)
}

// ResetStream clears all recorded data from the stream.
func ResetStream(stream *quantile.Stream) {
	stream.Reset()
}

{
  "schemaVersion": 1,
  "goal": "compute approximate stream quantiles with targeted error bounds",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/beorn7/perks@v1.0.1"
  ],
  "symbols": [
    "github.com/beorn7/perks/quantile.(*Stream).Insert",
    "github.com/beorn7/perks/quantile.(*Stream).Query",
    "github.com/beorn7/perks/quantile.NewTargeted"
  ]
}