github.com/beorn7/perks v1.0.1: quantile.Stream

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: verify github.com/beorn7/perks/quantile.Stream in pkg:golang/github.com/beorn7/perks@v1.0.1
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

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.

{"case":{"caseId":"case:sha256:494d5fdbcef1f0b07c4ab34dfb912c6b8eb4639beed7f2006234acb8775ee918","contract":["quantile.NewTargeted initializes a quantile Stream with zero observations","Stream.Insert adds float64 observations and Stream.Count tracks the total count","Stream.Query calculates approximate quantiles within configured error bounds","Stream.Samples returns retained sample representations from the stream","Stream.Reset clears stream observations and resets Count to zero"],"goal":"verify github.com/beorn7/perks/quantile.Stream in pkg:golang/github.com/beorn7/perks@v1.0.1","kind":"HOW","packages":["pkg:golang/github.com/beorn7/perks@v1.0.1"],"schemaVersion":1,"symbols":["github.com/beorn7/perks/quantile.Stream"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","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"],"verifierAdapter":"golang@1"}

module 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 main

import (
	"fmt"

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

func main() {
	// Configure targeted quantiles with desired absolute error tolerance
	targets := map[float64]float64{
		0.50: 0.01,
		0.90: 0.01,
		0.99: 0.001,
	}

	// Create a new stream targeting the specified quantiles
	stream := quantile.NewTargeted(targets)

	// Stream synthetic observations (1.0 through 1000.0)
	for i := 1; i <= 1000; i++ {
		stream.Insert(float64(i))
	}

	fmt.Printf("Total observations: %d\n", stream.Count())
	fmt.Printf("p50 estimate: %.2f\n", stream.Query(0.50))
	fmt.Printf("p90 estimate: %.2f\n", stream.Query(0.90))
	fmt.Printf("p99 estimate: %.2f\n", stream.Query(0.99))

	// Inspect retained samples
	samples := stream.Samples()
	fmt.Printf("Sample points retained: %d\n", len(samples))

	// Reset stream observations
	stream.Reset()
	fmt.Printf("Observations after reset: %d\n", stream.Count())
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/beorn7/perks/quantile.Stream in pkg:golang/github.com/beorn7/perks@v1.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/beorn7/perks@v1.0.1"
  ],
  "symbols": [
    "github.com/beorn7/perks/quantile.Stream"
  ]
}

package main

import (
	"fmt"
	"math"
	"os"

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

func main() {
	// Assertion 1: quantile.NewTargeted initializes a quantile Stream with zero observations
	{
		targets := map[float64]float64{
			0.50: 0.01,
			0.90: 0.01,
			0.99: 0.001,
		}
		stream := quantile.NewTargeted(targets)
		if stream == nil {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected non-nil stream from NewTargeted\n")
			os.Exit(1)
		}
		if count := stream.Count(); count != 0 {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected initial count 0, got %d\n", count)
			os.Exit(1)
		}

		lowBiased := quantile.NewLowBiased(0.01)
		if lowBiased == nil || lowBiased.Count() != 0 {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected non-nil lowBiased stream with count 0\n")
			os.Exit(1)
		}
	}

	// Assertion 2: Stream.Insert adds float64 observations and Stream.Count tracks the total count
	{
		stream := quantile.NewTargeted(map[float64]float64{0.50: 0.01})
		for i := 1; i <= 250; i++ {
			stream.Insert(float64(i))
		}
		if count := stream.Count(); count != 250 {
			fmt.Fprintf(os.Stderr, "assertion 2 failed: expected count 250, got %d\n", count)
			os.Exit(1)
		}

		for i := 251; i <= 500; i++ {
			stream.Insert(float64(i))
		}
		if count := stream.Count(); count != 500 {
			fmt.Fprintf(os.Stderr, "assertion 2 failed: expected count 500, got %d\n", count)
			os.Exit(1)
		}
	}

	// Assertion 3: Stream.Query calculates approximate quantiles within configured error bounds
	{
		stream := quantile.NewTargeted(map[float64]float64{
			0.50: 0.01,
			0.90: 0.01,
			0.99: 0.001,
		})
		n := 1000
		for i := 1; i <= n; i++ {
			stream.Insert(float64(i))
		}

		p50 := stream.Query(0.50)
		if math.Abs(p50-500.0) > 20.0 {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: expected p50 near 500.0, got %f\n", p50)
			os.Exit(1)
		}

		p90 := stream.Query(0.90)
		if math.Abs(p90-900.0) > 20.0 {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: expected p90 near 900.0, got %f\n", p90)
			os.Exit(1)
		}

		p99 := stream.Query(0.99)
		if math.Abs(p99-990.0) > 15.0 {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: expected p99 near 990.0, got %f\n", p99)
			os.Exit(1)
		}
	}

	// Assertion 4: Stream.Samples returns retained sample representations from the stream
	{
		stream := quantile.NewTargeted(map[float64]float64{0.50: 0.01})
		for i := 1; i <= 600; i++ {
			stream.Insert(float64(i))
		}
		samples := stream.Samples()
		if len(samples) == 0 {
			fmt.Fprintf(os.Stderr, "assertion 4 failed: expected non-empty samples slice\n")
			os.Exit(1)
		}
		for _, s := range samples {
			if s.Value <= 0 || s.Width <= 0 {
				fmt.Fprintf(os.Stderr, "assertion 4 failed: invalid sample value or width: %+v\n", s)
				os.Exit(1)
			}
		}
	}

	// Assertion 5: Stream.Reset clears stream observations and resets Count to zero
	{
		stream := quantile.NewTargeted(map[float64]float64{0.50: 0.01})
		for i := 1; i <= 100; i++ {
			stream.Insert(float64(i))
		}
		if stream.Count() != 100 {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: expected count 100 before reset, got %d\n", stream.Count())
			os.Exit(1)
		}

		stream.Reset()
		if count := stream.Count(); count != 0 {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: expected count 0 after reset, got %d\n", count)
			os.Exit(1)
		}
		if q0 := stream.Query(0.50); q0 != 0 {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: expected query 0 on empty stream, got %f\n", q0)
			os.Exit(1)
		}
	}

	fmt.Println("All contract assertions passed successfully.")
}