harness

type BaselineFile struct {
	Version           int                      `json:"version"`
	CapturedAt        string                   `json:"captured_at"`
	CapturedOn        string                   `json:"captured_on"`
	Queries           map[string]QueryBaseline `json:"queries"`
	ProjectionFactors map[string]Projection    `json:"projection_factors"`
}

type Cluster struct {
	// contains filtered or unexported fields
}

type ClusterConfig struct {
	WadjetBin  string // path to wadjet binary
	RunDir     string // /tmp/wadjet-harness/run-X
	NumWorkers int
	GoMemLimit int64
	PgAddr     string // pgwire listen address for coordinator (default ":15433")
	DataDir    string // local data dir (FileStore) for StorageType=="file"

	// MemoryBudget, when > 0, is passed as both --memory-budget and
	// --shared-pool-budget to every spawned process (coordinator and
	// workers). 0 leaves both flags unset, falling through to the
	// engine's cgroup/physical-memory auto-detection — which floors the
	// per-task budget near 2 GB (cmd/wadjet/main.go minBudgetPerTask) and
	// auto-sizes the shared pool as (envelope - cache) independent of
	// --memory-budget, so GOMEMLIMIT alone cannot force spill at these
	// fixture sizes: "spill triggers are pool-driven" (main.go), so both
	// flags need the explicit override, not just --memory-budget.
	MemoryBudget int64

	// StorageType selects the coordinator/worker storage backend.
	// "" or "file" -> FileStore at DataDir (default)
	// "s3"         -> MinIO/S3 at Endpoint/Region/Bucket
	StorageType string
	Bucket      string
	Region      string
	Endpoint    string
	SSL         bool

	// DataPlane selects the worker↔coord transport. "" or "nats" uses
	// the legacy NATS reply-subject path; "grpc" enables the new
	// data-plane gRPC stream (Phase B+). Both transports route into the
	// same coord-side gatherReceiver so cross-flag results are
	// identical; the toggle exists to validate the new path without
	// committing to it as default.
	DataPlane string

	// ExtraServeArgs are appended verbatim to every spawned `wadjet serve`
	// command (coordinator and workers). Used to exercise deploy-gated
	// flags through the local harness before an EC2 run.
	ExtraServeArgs []string

	// SpawnWrapper, when non-empty, is prepended to every spawned process's
	// argv: wrapper[0] wrapper[1:]... <wadjet-bin> <args...>. Used to run
	// the cluster under an enforcement harness — e.g. a docker memory-cap
	// wrapper for edge-box simulation (hard OOM-kill semantics that
	// GOMEMLIMIT alone cannot provide). The wrapper owns env forwarding:
	// exec.Command env vars (GOMEMLIMIT, GODEBUG, heap-dump paths) do NOT
	// cross a container boundary unless the wrapper forwards them.
	SpawnWrapper []string

	Logger *slog.Logger
}

type Config struct {
	Mode           Mode
	Slice          Slice  // local only
	CoordURL       string // golden only
	DataDir        string // local only; default /tmp/sf100-sample
	BaselinePath   string
	OutPath        string
	Queries        []string // empty means all 22 + micros
	UpdateBaseline bool
	NoCompare      bool
	WadjetBin      string // path to wadjet binary; auto-built if empty
	PgAddr         string // local only; override for coordinator pgwire listen addr
	NumWorkers     int    // local only; cluster size to spawn (0 = default of 2)

	// Runs repeats the whole query suite against the same live cluster
	// (0/1 = once). The EC2 SF100 protocol is benchmark_runs=2 — run 1
	// populates the NVMe base-table cache cold, run 2 measures the
	// steady regime over it (docs/benchmarks/
	// steady-slower-than-cold-2026-08-08.md); this is the local mirror.
	// Baseline comparison applies to run 1 only; later runs are recorded
	// with QueryMeasurement.Run set, plus a cross-run row-count/value-sig
	// identity check.
	Runs int

	// ScaleFactor is the TPC-H data volume for local mode generation.
	// 0 (zero value) defaults to 0.01 (~10 MB total, lineitem 60K rows).
	// Larger values let the harness exercise per-stage round-trip and
	// memory-pressure paths at meaningful scale without EC2 spend:
	//   0.1  → ~150 MB total, lineitem 600K rows  (~5-10 sec total benchmark)
	//   1.0  → ~1.5 GB total, lineitem 6M rows    (~30-60 sec)
	//   10.0 → ~15 GB total — local generation will take minutes; only useful
	//          on machines with disk + memory to spare.
	ScaleFactor float64 // 0 = SF0.01 default

	// S3 source (Source=="s3" only)
	Source     string // "local" (default) or "s3"
	Bucket     string
	Region     string
	Endpoint   string
	SSL        bool
	DataPrefix string // prefix under Bucket containing table data (e.g. "tables/")

	// DataPlane selects worker↔coord transport for the spawned cluster.
	// Empty / "nats" uses the legacy NATS reply-subject path. "grpc"
	// enables the data-plane gRPC stream (Phase B+).
	DataPlane string

	// ExtraServeArgs are appended verbatim to every spawned `wadjet serve`
	// command (coordinator and workers). Use to exercise deploy-gated
	// flags (e.g. --bounded-dirty-writes, --mmap-relief) through the
	// local harness before an EC2 run.
	ExtraServeArgs []string

	// SpawnWrapper is prepended to every spawned process argv (see
	// ClusterConfig.SpawnWrapper). E.g. a docker memory-cap wrapper for
	// edge-box simulation.
	SpawnWrapper []string
}

type HangDetector struct {
	// contains filtered or unexported fields
}

type MeasurementCollector struct {
	// contains filtered or unexported fields
}

type Mode string

type PreflightResult struct {
	OK     bool
	Errors []string
}

type Projection struct {
	WallMsMultiplier     float64 `json:"wall_ms_multiplier"`
	HeapMultiplier       float64 `json:"heap_multiplier"`
	AllocCountMultiplier float64 `json:"alloc_count_multiplier"`
	SpillMultiplier      float64 `json:"spill_multiplier"`
}

type QueryBaseline struct {
	WallMsP50              int64   `json:"wall_ms_p50"`
	WallMsTolerancePct     float64 `json:"wall_ms_tolerance_pct"`
	PeakHeapMB             int64   `json:"peak_heap_mb"`
	PeakHeapTolerancePct   float64 `json:"peak_heap_tolerance_pct"`
	AllocCount             int64   `json:"alloc_count"`
	AllocCountTolerancePct float64 `json:"alloc_count_tolerance_pct"`
	SpillBytesWritten      int64   `json:"spill_bytes_written"`
	SpillTolerancePct      float64 `json:"spill_tolerance_pct"`
	RowCount               int64   `json:"row_count"`
	RowChecksum            string  `json:"row_checksum"`
	// ValueSig is the canonical per-column numeric-sum signature
	// (valuesig.go), compared with ValueSigRelTol relative tolerance —
	// unlike RowChecksum it is order-insensitive and float-wobble-proof,
	// so it can gate VALUES (the #278 / eager-§14.3 corruption class that
	// row counts cannot see). Empty = not gated.
	ValueSig string `json:"value_sig,omitempty"`
}

type QueryDelta struct {
	Query        string  `json:"query"`
	Metric       string  `json:"metric"`
	Baseline     float64 `json:"baseline"`
	Projected    float64 `json:"projected"`
	DriftPct     float64 `json:"drift_pct"`
	TolerancePct float64 `json:"tolerance_pct"`
	Status       string  `json:"status"` // "PASS", "REGRESS"
	// Detail carries non-scalar divergence context (e.g. which value-
	// signature column diverged and by how much).
	Detail string `json:"detail,omitempty"`
}

type QueryMeasurement struct {
	Query         string    `json:"query"`
	WallMs        int64     `json:"wall_ms"`
	PeakHeapMB    int64     `json:"peak_heap_mb"`
	AllocCount    int64     `json:"alloc_count"`
	SpillBytes    int64     `json:"spill_bytes"`
	RowCount      int64     `json:"row_count"`
	RowChecksum   string    `json:"row_checksum"`
	ValueSig      string    `json:"value_sig,omitempty"`
	GoroutinePeak int       `json:"goroutine_peak"`
	Hung          bool      `json:"hung"`
	HangDumpPath  string    `json:"hang_dump_path,omitempty"`
	StartedAt     time.Time `json:"started_at"`
	// Run numbers the suite pass this measurement came from under
	// Config.Runs > 1 (0/absent = single-pass run or run 1).
	Run int `json:"run,omitempty"`
}

type RunResult struct {
	Mode         Mode               `json:"mode"`
	Slice        Slice              `json:"slice,omitempty"`
	StartedAt    time.Time          `json:"started_at"`
	DurationMs   int64              `json:"duration_ms"`
	Queries      []QueryMeasurement `json:"queries"`
	BaselinePath string             `json:"baseline_path"`
	Regressions  []QueryDelta       `json:"regressions"`
	Hangs        []string           `json:"hangs"`
	Passed       bool               `json:"passed"`
	ExitCode     int                `json:"exit_code"`
}

type Slice string

type SliceConfig struct {
	Name          Slice
	LineitemFiles int
	OrdersFiles   int
	GoMemLimit    int64 // bytes; passed to worker via GOMEMLIMIT env
	ExpectSpill   bool  // if true and total spill bytes == 0, fail the run

	// MemoryBudget, when > 0, is passed as --memory-budget to every
	// spawned process (bytes; see ClusterConfig.MemoryBudget). GOMEMLIMIT
	// alone does not force spill: when --memory-budget is left at its
	// default (0), the engine auto-detects a per-task budget from the
	// cgroup/physical-memory envelope and floors it near 2 GB
	// (cmd/wadjet/main.go minBudgetPerTask) to stay viable for SF100-class
	// joins — far above anything this slice's fixtures need, so it never
	// spills regardless of GoMemLimit. 0 = flag unset (small slice; no
	// spill expected, so let the engine auto-detect as usual).
	MemoryBudget int64
}

type ValueSigAccum struct {
	// contains filtered or unexported fields
}