feat(cache): TTL-aware cache tracker for batch workloads (#61)

Add TTLTracker to pkg/cache. Monitors Anthropic's 5-minute prompt cache
TTL per prefix hash and detects cold-start penalties.

- Touch(prefixHash): records request, returns wasAlive (warm/cold)
- NextDeadline / TimeUntilExpiry: time remaining before cache expires
- ScheduleDeadline(hash, margin): latest safe time for next batch request
- ExpiredEntries: all prefixes past their TTL deadline
- Evict: remove entry on boundary retreat
- Stats: aggregate alive/expired counts and hit/miss totals

AnthropicCacheTTL constant (5m) exported for use by callers.

Co-authored-by: Ona <no-reply@ona.com>

Author: Siddhant-K-code

README.md

@@ -795,6 +795,28 @@ Response stats when prefix is frozen:
 }
 ```
 
+#### TTL-aware cache tracker
+
+`TTLTracker` monitors Anthropic's 5-minute prompt cache TTL per prefix hash. Use it to detect cold-start penalties and schedule batch requests before the cache expires:
+
+```go
+tracker := cache.NewTTLTracker(0) // 0 = use AnthropicCacheTTL (5 min)
+
+// After each request that carries a cache_control marker:
+wasAlive := tracker.Touch(plan.PrefixHash)
+if !wasAlive {
+    log.Warn("cache cold start — first request or TTL expired")
+}
+
+// For batch workloads: latest safe time to send next request
+deadline := tracker.ScheduleDeadline(plan.PrefixHash, 30*time.Second)
+time.Sleep(time.Until(deadline))
+
+// Inspect expiry state
+entry := tracker.Entry(plan.PrefixHash)
+fmt.Printf("hits: %d  misses: %d  alive: %v\n", entry.HitCount, entry.MissCount, entry.IsAlive())
+```
+
 #### Prefix stability validator
 
 Detects dynamic content (timestamps, request IDs, UUIDs) bleeding into cached prefixes — the most common cause of 0% cache hit rates:
@@ -899,6 +921,7 @@ Distill is evolving from a dedup utility into a context intelligence layer. Here
 | **Cache-aware dedup** | [#50](https://github.com/Siddhant-K-code/distill/issues/50) | Shipped | `preserve_cache_prefix` option freezes chunks before the last `cache_control` marker so dedup cannot reorder them. Prefix hash and token count reported in stats. |
 | **Prefix stability validator** | [#48](https://github.com/Siddhant-K-code/distill/issues/48) | Shipped | `StabilityValidator` tracks prefix hashes across requests and detects dynamic content (timestamps, request IDs, UUIDs) bleeding into cached prefixes. |
 | **Per-call-site hit rate tracking** | [#47](https://github.com/Siddhant-K-code/distill/issues/47) | Shipped | `CallSiteTracker` records Anthropic cache usage per call site; `AllStats()` returns worst performers first. |
+| **TTL-aware cache tracker** | [#49](https://github.com/Siddhant-K-code/distill/issues/49) | Shipped | `TTLTracker` monitors Anthropic's 5-minute cache TTL per prefix hash. `ScheduleDeadline` tells batch jobs the latest safe time to send the next request. |
 
 ### Code Intelligence
 

pkg/cache/ttl.go

@@ -0,0 +1,187 @@
+package cache
+
+import (
+	"sync"
+	"time"
+)
+
+// AnthropicCacheTTL is the Anthropic prompt cache TTL. The cache entry is
+// kept alive as long as requests arrive within this window; it expires if
+// no request references it for this duration.
+const AnthropicCacheTTL = 5 * time.Minute
+
+// TTLEntry tracks the last-seen time and expiry state of a single cache
+// prefix identified by its hash.
+type TTLEntry struct {
+	PrefixHash  string
+	LastSeen    time.Time
+	ExpiresAt   time.Time
+	HitCount    int
+	MissCount   int
+	// Expired is true when the entry has not been refreshed within AnthropicCacheTTL.
+	Expired bool
+}
+
+// IsAlive returns true when the entry is still within its TTL window.
+func (e *TTLEntry) IsAlive() bool {
+	return time.Now().Before(e.ExpiresAt)
+}
+
+// TTLTracker monitors cache prefix liveness across requests. It detects
+// when a prefix has gone cold (no requests within AnthropicCacheTTL) and
+// records the resulting cold-start penalty.
+//
+// For batch workloads, use Schedule to determine the latest safe time to
+// send the next request without letting the cache expire.
+type TTLTracker struct {
+	mu      sync.Mutex
+	entries map[string]*TTLEntry
+	ttl     time.Duration
+}
+
+// NewTTLTracker creates a tracker with the given TTL.
+// Pass 0 to use AnthropicCacheTTL (5 minutes).
+func NewTTLTracker(ttl time.Duration) *TTLTracker {
+	if ttl <= 0 {
+		ttl = AnthropicCacheTTL
+	}
+	return &TTLTracker{
+		entries: make(map[string]*TTLEntry),
+		ttl:     ttl,
+	}
+}
+
+// Touch records a request for the given prefix hash and returns whether the
+// cache was alive (warm) or had expired (cold start).
+//
+// Call Touch after every request that carries a cache_control marker.
+func (t *TTLTracker) Touch(prefixHash string) (wasAlive bool) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	now := time.Now()
+	entry, ok := t.entries[prefixHash]
+	if !ok {
+		// First time seeing this prefix.
+		t.entries[prefixHash] = &TTLEntry{
+			PrefixHash: prefixHash,
+			LastSeen:   now,
+			ExpiresAt:  now.Add(t.ttl),
+			MissCount:  1,
+		}
+		return false
+	}
+
+	wasAlive = now.Before(entry.ExpiresAt)
+	if wasAlive {
+		entry.HitCount++
+	} else {
+		entry.MissCount++
+		entry.Expired = true
+	}
+	entry.LastSeen = now
+	entry.ExpiresAt = now.Add(t.ttl)
+	return wasAlive
+}
+
+// NextDeadline returns the time by which the next request must arrive to
+// keep the cache entry alive. Returns zero time if the prefix is unknown.
+func (t *TTLTracker) NextDeadline(prefixHash string) time.Time {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	e := t.entries[prefixHash]
+	if e == nil {
+		return time.Time{}
+	}
+	return e.ExpiresAt
+}
+
+// TimeUntilExpiry returns how long until the cache entry expires.
+// Returns 0 if already expired or unknown.
+func (t *TTLTracker) TimeUntilExpiry(prefixHash string) time.Duration {
+	deadline := t.NextDeadline(prefixHash)
+	if deadline.IsZero() {
+		return 0
+	}
+	d := time.Until(deadline)
+	if d < 0 {
+		return 0
+	}
+	return d
+}
+
+// ScheduleDeadline returns the latest time a batch job can wait before
+// sending its next request without letting the cache expire. It subtracts
+// a safety margin from the TTL deadline.
+//
+// safetyMargin should account for network latency and scheduling jitter.
+// A value of 30s is reasonable for most deployments.
+func (t *TTLTracker) ScheduleDeadline(prefixHash string, safetyMargin time.Duration) time.Time {
+	deadline := t.NextDeadline(prefixHash)
+	if deadline.IsZero() {
+		return time.Time{}
+	}
+	return deadline.Add(-safetyMargin)
+}
+
+// Entry returns a snapshot of the TTL entry for a prefix hash, or nil.
+func (t *TTLTracker) Entry(prefixHash string) *TTLEntry {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	e := t.entries[prefixHash]
+	if e == nil {
+		return nil
+	}
+	cp := *e
+	return &cp
+}
+
+// ExpiredEntries returns all entries that have passed their TTL deadline.
+func (t *TTLTracker) ExpiredEntries() []*TTLEntry {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	now := time.Now()
+	var out []*TTLEntry
+	for _, e := range t.entries {
+		if now.After(e.ExpiresAt) {
+			cp := *e
+			out = append(out, &cp)
+		}
+	}
+	return out
+}
+
+// Evict removes the entry for a prefix hash (e.g. after a boundary retreat).
+func (t *TTLTracker) Evict(prefixHash string) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	delete(t.entries, prefixHash)
+}
+
+// Stats returns a summary of all tracked prefixes.
+type TTLStats struct {
+	TotalPrefixes   int
+	AlivePrefixes   int
+	ExpiredPrefixes int
+	TotalHits       int64
+	TotalMisses     int64
+}
+
+// Stats returns aggregate TTL statistics.
+func (t *TTLTracker) Stats() TTLStats {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	now := time.Now()
+	var s TTLStats
+	s.TotalPrefixes = len(t.entries)
+	for _, e := range t.entries {
+		if now.Before(e.ExpiresAt) {
+			s.AlivePrefixes++
+		} else {
+			s.ExpiredPrefixes++
+		}
+		s.TotalHits += int64(e.HitCount)
+		s.TotalMisses += int64(e.MissCount)
+	}
+	return s
+}

pkg/cache/ttl_test.go

@@ -0,0 +1,121 @@
+package cache
+
+import (
+	"testing"
+	"time"
+)
+
+func TestTTLTracker_FirstTouch_ColdStart(t *testing.T) {
+	tr := NewTTLTracker(5 * time.Minute)
+	alive := tr.Touch("hash-abc")
+	if alive {
+		t.Error("expected cold start (wasAlive=false) on first touch")
+	}
+	e := tr.Entry("hash-abc")
+	if e == nil {
+		t.Fatal("expected entry after touch")
+	}
+	if e.MissCount != 1 {
+		t.Errorf("expected MissCount=1, got %d", e.MissCount)
+	}
+}
+
+func TestTTLTracker_SecondTouch_WarmHit(t *testing.T) {
+	tr := NewTTLTracker(5 * time.Minute)
+	tr.Touch("hash-abc")
+	alive := tr.Touch("hash-abc")
+	if !alive {
+		t.Error("expected warm hit (wasAlive=true) on second touch within TTL")
+	}
+	e := tr.Entry("hash-abc")
+	if e.HitCount != 1 {
+		t.Errorf("expected HitCount=1, got %d", e.HitCount)
+	}
+}
+
+func TestTTLTracker_ExpiredEntry(t *testing.T) {
+	// Use a very short TTL to simulate expiry.
+	tr := NewTTLTracker(1 * time.Millisecond)
+	tr.Touch("hash-xyz")
+	time.Sleep(5 * time.Millisecond)
+
+	alive := tr.Touch("hash-xyz")
+	if alive {
+		t.Error("expected cold start after TTL expiry")
+	}
+	e := tr.Entry("hash-xyz")
+	if !e.Expired {
+		t.Error("expected Expired=true after TTL expiry")
+	}
+}
+
+func TestTTLTracker_TimeUntilExpiry(t *testing.T) {
+	tr := NewTTLTracker(5 * time.Minute)
+	tr.Touch("hash-abc")
+	d := tr.TimeUntilExpiry("hash-abc")
+	if d <= 0 || d > 5*time.Minute {
+		t.Errorf("expected 0 < expiry <= 5m, got %v", d)
+	}
+}
+
+func TestTTLTracker_TimeUntilExpiry_Unknown(t *testing.T) {
+	tr := NewTTLTracker(5 * time.Minute)
+	if tr.TimeUntilExpiry("unknown") != 0 {
+		t.Error("expected 0 for unknown prefix")
+	}
+}
+
+func TestTTLTracker_ScheduleDeadline(t *testing.T) {
+	tr := NewTTLTracker(5 * time.Minute)
+	tr.Touch("hash-abc")
+	margin := 30 * time.Second
+	deadline := tr.ScheduleDeadline("hash-abc", margin)
+	if deadline.IsZero() {
+		t.Fatal("expected non-zero deadline")
+	}
+	// Deadline should be ~4m30s from now.
+	remaining := time.Until(deadline)
+	if remaining <= 0 || remaining > 5*time.Minute {
+		t.Errorf("unexpected deadline remaining: %v", remaining)
+	}
+}
+
+func TestTTLTracker_ExpiredEntries(t *testing.T) {
+	tr := NewTTLTracker(1 * time.Millisecond)
+	tr.Touch("a")
+	tr.Touch("b")
+	time.Sleep(5 * time.Millisecond)
+	tr.Touch("c") // fresh entry
+
+	expired := tr.ExpiredEntries()
+	if len(expired) != 2 {
+		t.Errorf("expected 2 expired entries, got %d", len(expired))
+	}
+}
+
+func TestTTLTracker_Evict(t *testing.T) {
+	tr := NewTTLTracker(5 * time.Minute)
+	tr.Touch("hash-abc")
+	tr.Evict("hash-abc")
+	if tr.Entry("hash-abc") != nil {
+		t.Error("expected nil after eviction")
+	}
+}
+
+func TestTTLTracker_Stats(t *testing.T) {
+	tr := NewTTLTracker(5 * time.Minute)
+	tr.Touch("a")
+	tr.Touch("a") // hit
+	tr.Touch("b")
+
+	s := tr.Stats()
+	if s.TotalPrefixes != 2 {
+		t.Errorf("expected 2 prefixes, got %d", s.TotalPrefixes)
+	}
+	if s.AlivePrefixes != 2 {
+		t.Errorf("expected 2 alive, got %d", s.AlivePrefixes)
+	}
+	if s.TotalHits != 1 {
+		t.Errorf("expected 1 total hit, got %d", s.TotalHits)
+	}
+}