gpugen

type FootprintKey struct {
	Family string // e.g. "sdxl", "wan2.2", "whisper", "acestep"
	Quant  string // e.g. "bf16", "q8_0"; "" = node default
	Task   string // fleet task_type, e.g. "image-gen"
}

type Sampling struct {
	Footprint   *FootprintKey
	SampleFunc  func(childPid int) (float64, error)
	OnFootprint func(peakGiB float64)
}

type Spec struct {
	// Exe is the executable ("" => "node"). Script is its first argument (the
	// render/*.mjs path, or for `node -e` the verb). Args are the remaining argv.
	Exe    string
	Script string
	Args   []string
	// Env are extra "K=V" entries appended to the current environment (e.g.
	// COMFY_DIR, MEMORY_STACK, GPU_LOCK_WAIT_MS). nil = inherit only.
	Env []string
	// Out is the file the runner must produce; a missing/empty Out after a clean
	// exit is treated as failure (the caller defers). Required.
	Out string
	// Timeout bounds the whole invocation (cold-start + render + margin).
	Timeout time.Duration
	// ComfyAPI is the ComfyUI endpoint freeComfyVRAM hits after the run. "" =>
	// the COMFY_API env or the 127.0.0.1:8188 default. Set "" to inherit; a runner
	// with no ComfyUI (TTS) can leave it — /free on a dead endpoint is a no-op.
	ComfyAPI string
	// SkipFreeComfy, when true, suppresses the post-run ComfyUI /free (the TTS/voice
	// path never starts ComfyUI, so there is nothing to free). The killTree + output
	// stat still apply — the python worker still gets process-tree-killed on timeout.
	SkipFreeComfy bool
	// Footprint, when non-nil, turns on passive per-render VRAM peak sampling for
	// the fleet-node footprint store (added 2026-07-17): while the child runs,
	// SampleFunc is polled and the max observation is reported via OnFootprint —
	// on SUCCESS only (a crashed/phantom run's peak may be partial). nil keeps the
	// legacy CombinedOutput path byte-identical.
	Footprint *FootprintKey
	// SampleFunc returns the current VRAM usage in GiB attributable to the render
	// rooted at childPid. The CALLER composes what a sample means (PDH process-tree
	// sum, or a global-delta closure) — gpugen stays dependency-free and only tracks
	// the peak. nil = no sampling (OnFootprint never fires).
	SampleFunc func(childPid int) (float64, error)
	// OnFootprint receives the observed peak (GiB) after a SUCCESSFUL render whose
	// sampled peak was > 0. nil = observations are discarded.
	OnFootprint func(peakGiB float64)
}