M3.8.2 — CacheAligner: HTTP Headers + Metrics

Field	Value
Phase	M3.8 — Context optimization
Size	M — 1–2 days
Status	✅ COMPLETE
Depends	M3.8.1 (CacheAligner complete)
Blocks	M3.8.3

Goal

Integrate CacheAligner output into HTTP response headers and observability metrics so that:

LLM provider can use cache hints
Monitoring can track cache effectiveness
Debugging can identify cache misses

Deliverables

1. PromptBuilder::cache_metrics()

New method returning cache metadata:

pub struct CacheMetrics {
    pub stable_prefix_bytes: usize,
    pub dynamic_tail_bytes: usize,
    pub drift_metric: f32,  // 0.0-1.0 ratio
    pub cache_eligible: bool,  // true if drift < 0.3
}

impl PromptBuilder {
    pub fn cache_metrics(query: &Query, chunk: &Chunk) -> Result<CacheMetrics>
}

Tests (3):

test_cache_metrics_stable_query
test_cache_metrics_high_drift
test_cache_metrics_zero_drift

2. HTTP Response Headers

Add to PromptBuilder output:

X-Cache-Stable-Bytes: size of cacheable prefix
X-Cache-Drift: 0.0-1.0 ratio
X-Cache-Eligible: "true"/"false"
X-Compression-Ratio: original vs. compressed

Tests (4):

test_headers_present_in_response
test_headers_accurate_values
test_headers_skipped_when_disabled
test_headers_format_valid

3. Observability Hooks

Integrate with logging:

pub fn log_cache_metrics(metrics: &CacheMetrics) {
    tracing::info!(
        stable_bytes = metrics.stable_prefix_bytes,
        drift = metrics.drift_metric,
        eligible = metrics.cache_eligible,
        "cache_alignment"
    );
}

Tests (2):

test_metrics_logged_on_alignment
test_drift_high_triggers_warning

Acceptance

All 9 new tests passing
Existing 114 mem-core tests still pass
Cache metrics accurately reflect alignment
HTTP headers present and valid
Zero performance overhead (< 1ms additional)

1.9 KiB Raw Blame History Unescape Escape