feat: initial release

Assisted-by: GLM 5.3 Flash

stats/zz_guard_test.go

@@ -0,0 +1,40 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: MIT
+
+package stats
+
+import (
+	"os"
+	"runtime"
+	"testing"
+	"time"
+)
+
+// TestMain installs a heap watchdog for the whole package run: the
+// review probes include bin-count and quantile cases that can ask for
+// tens of gigabytes when a guard regresses, and an editor session was
+// already lost to a runaway test allocation once. Any runaway now panics
+// and unwinds instead of taking the host with it.
+func TestMain(m *testing.M) {
+	const cap = 3 << 30 // race instrumentation inflates the heap; a runaway is far above this
+	stop := make(chan struct{})
+	go func() {
+		ticker := time.NewTicker(20 * time.Millisecond)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-stop:
+				return
+			case <-ticker.C:
+				var m runtime.MemStats
+				runtime.ReadMemStats(&m)
+				if m.HeapAlloc > cap {
+					panic("stats test binary heap above 3 GiB: an entry point is allocating without bound")
+				}
+			}
+		}
+	}()
+	code := m.Run()
+	close(stop)
+	os.Exit(code)
+}