memctl

type BudgetStrategy interface {
	// ComputeWorkers returns the recommended worker count for the
	// given available memory (bytes) and CPU core count.
	// Must return >= 1.
	ComputeWorkers(availableMemory uint64, cpuCores int) int
}

type DefaultBudget struct {
	// BaseOverhead is memory reserved for non-worker use (bytes).
	// Subtracted before dividing by PerWorkerCost.
	BaseOverhead uint64

	// PerWorkerCost is the memory cost per worker (bytes).
	// Typically: model size + batch buffer + working set per worker.
	PerWorkerCost uint64

	// BudgetFraction is the fraction of available memory to use.
	// Must be in (0, 1]. The rest is reserved as safety buffer.
	BudgetFraction float64

	// MaxCoresRatio caps workers relative to CPU cores.
	// 0 means no CPU-based cap. Example: 2.0 = at most 2× cores.
	MaxCoresRatio float64

	// MaxWorkers is the absolute maximum. 0 means no cap.
	MaxWorkers int
}

type MemInfo struct {
	At time.Time // when this sample was taken

	SystemAvailable   uint64 // /proc/meminfo MemAvailable (bytes)
	SystemAvailableOK bool

	ProcessRSS   uint64 // /proc/self/status VmRSS (bytes)
	ProcessRSSOK bool

	GoRuntimeTotal   uint64 // runtime/metrics /memory/classes/total:bytes
	GoRuntimeTotalOK bool

	CgroupCurrent uint64 // cgroup v2 memory.current (bytes)
	CgroupLimit   uint64 // cgroup v2 memory.max (bytes; 0 = unlimited)
	CgroupOK      bool   // true when cgroup v2 is detected and readable
}

type Options struct {
	// Interval between memory samples. Must be > 0.
	Interval time.Duration

	// Immediate, when true, takes a sample immediately on entry
	// before waiting for the first tick. Catches startup spikes.
	Immediate bool

	// OnPanic is called if the callback panics. If nil, the panic
	// is re-raised (default: don't mask bugs). If non-nil, Watch
	// logs the panic via OnPanic and continues sampling.
	OnPanic func(any)
}