diff --git a/internal/parser/ltf.go b/internal/parser/ltf.go
index f19e97d..f5c32ac 100644
--- a/internal/parser/ltf.go
+++ b/internal/parser/ltf.go
@@ -67,7 +67,7 @@ type ltfContext struct {
 	WindowUsed  int     `json:"window_used"`
 	WindowMax   int     `json:"window_max"`
 	FillPct     float64 `json:"fill_pct"`
-	Compactions int     `json:"compactions"`
+	Compactions int     `json:"compactions"` // running counter: compactions so far in the loop
 	CacheHitPct float64 `json:"cache_hit_pct"`
 }
 
diff --git a/internal/trace/metrics.go b/internal/trace/metrics.go
index 5564fde..61e32c7 100644
--- a/internal/trace/metrics.go
+++ b/internal/trace/metrics.go
@@ -44,6 +44,11 @@ func (t *Trace) MaxContextFill() float64 {
 	return max
 }
 
+// TotalCompactions returns the total number of context compactions in the
+// loop. ContextState.Compactions is a running counter (compactions so far,
+// not per-iteration), so the max across iterations is the total. Max is used
+// instead of the last iteration's value to be robust to out-of-order
+// iterations.
 func (t *Trace) TotalCompactions() int {
 	var max int
 	for _, it := range t.Iterations {
diff --git a/internal/trace/metrics_test.go b/internal/trace/metrics_test.go
new file mode 100644
index 0000000..40700f6
--- /dev/null
+++ b/internal/trace/metrics_test.go
@@ -0,0 +1,16 @@
+package trace
+
+import "testing"
+
+// Compactions is a running counter, so the total is the max across
+// iterations (4 here), not the sum (5).
+func TestTotalCompactionsIsMaxOfRunningCounter(t *testing.T) {
+	tr := &Trace{Iterations: []Iteration{
+		{Number: 1, Context: ContextState{Compactions: 0}},
+		{Number: 2, Context: ContextState{Compactions: 1}},
+		{Number: 3, Context: ContextState{Compactions: 4}},
+	}}
+	if got := tr.TotalCompactions(); got != 4 {
+		t.Errorf("TotalCompactions() = %d, want 4", got)
+	}
+}
diff --git a/internal/trace/types.go b/internal/trace/types.go
index c2aae83..7224109 100644
--- a/internal/trace/types.go
+++ b/internal/trace/types.go
@@ -54,7 +54,7 @@ type ContextState struct {
 	WindowUsed  int
 	WindowMax   int
 	FillPct     float64
-	Compactions int
+	Compactions int // running counter: compactions so far in the loop, not per-iteration
 	CacheHitPct float64
 }