# What Types of Data Can CacheAligner Detect? A Deep Dive into Headroom's Volatile Content Patterns

> Discover the four volatile data patterns CacheAligner detects: UUIDs, timestamps, JWTs, and hex hashes. Learn how its structural validation works and what it means for your data.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: deep-dive
- Published: 2026-06-12

---

**CacheAligner detects four specific volatile data patterns—UUIDs, ISO-8601 timestamps, JWTs, and hex hashes (MD5, SHA-1, SHA-256)—using structural validation functions rather than regular expressions.**

CacheAligner is a detector-only transform in the `chopratejas/headroom` repository designed to spot dynamic content within system prompts. By identifying these volatile patterns, developers can maintain stable cache prefixes and optimize LLM inference costs. The implementation relies on precise structural checks implemented in [`headroom/transforms/cache_aligner.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/cache_aligner.py).

## The Four Data Types CacheAligner Detects

According to the `chopratejas/headroom` source code, CacheAligner specifically looks for four concrete patterns that commonly introduce volatility into system prompts.

### UUIDs (Canonical RFC 4122)

CacheAligner identifies standard UUIDs through the `_is_uuid` function (lines 76-93). The validation confirms the token contains exactly 36 characters including four hyphens, then attempts to parse it using Python's `uuid.UUID` constructor. This catches canonical forms like `123e4567-e89b-12d3-a456-426614174000` without relying on regex patterns.

### ISO-8601 Timestamps

The `_is_iso8601` function (lines 96-112) detects date-time strings by first checking length and delimiter structure, then normalizing any "Z" suffix to `+00:00` before passing to `datetime.fromisoformat`. This recognizes formats such as `2024-03-01T12:34:56Z` while rejecting invalid date strings through Python's standard library validation.

### JSON Web Tokens (JWTs)

JWT detection occurs in `_is_jwt_shape` (lines 115-136), which splits the token on periods and verifies three distinct segments. Each segment must be base64-url decodable and contain at least 4 bytes. This structural approach identifies tokens like `eyJhbGciOiJIUzI1NiIs...` by validating the shape rather than decoding payload claims.

### Hexadecimal Hash Digests

The `_is_hex_hash` function (lines 139-152) recognizes MD5, SHA-1, and SHA-256 hashes by checking if the token length exists in the set `{32, 40, 64}` and successfully parses as hexadecimal via `int(token, 16)`. This distinguishes cryptographic fingerprints from random alphanumeric strings through length-specific validation.

## How the Detection Pipeline Works

CacheAligner processes prompts through a four-stage pipeline that never mutates the input text.

**Tokenization** – The `_split_tokens` helper splits prompt text on whitespace and strips surrounding punctuation to isolate candidate strings.

**Classification** – Each token passes through `_classify_token`, which sequentially invokes the four detection helpers in order of specificity (UUID, ISO-8601, JWT, then hash).

**Reporting** – For every match, the system creates a `VolatileFinding(label, sample)` dataclass instance. A warning log aggregates counts per label, while a stable hash of the unchanged system prompt is stored in `CachePrefixMetrics` for observability.

**Scoring** – The `CacheAligner.get_alignment_score` method converts finding counts into a 0-100 alignment metric, subtracting 10 points per volatile detection and clamping the result.

## Source Code Reference

The core detection logic resides in [`headroom/transforms/cache_aligner.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/cache_aligner.py), which exports the `CacheAligner` class and the `detect_volatile_content` convenience function. Configuration options live in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) via `CacheAlignerConfig`, while architecture documentation in [`wiki/ARCHITECTURE.md`](https://github.com/chopratejas/headroom/blob/main/wiki/ARCHITECTURE.md) positions CacheAligner as the first stage in the compression pipeline.

## Practical Usage Example

The following example demonstrates detecting a UUID, timestamp, and JWT within a system prompt:

```python
from headroom.transforms.cache_aligner import detect_volatile_content, align_for_cache

system_prompt = """
You are a helpful assistant.
Today is 2024-03-01.
Your request id is 123e4567-e89b-12d3-a456-426614174000.
Auth token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
"""

findings = detect_volatile_content(system_prompt)
for f in findings:
    print(f"⚠️  {f.label}: {f.sample}")

messages = [{"role": "system", "content": system_prompt}]
cleaned, prefix_hash = align_for_cache(messages)

print("\nStable prefix hash:", prefix_hash)
print("Messages unchanged:", cleaned == messages)  # True

```

This outputs detection warnings for each volatile pattern while returning the original messages unmodified and a stable hash for cache comparison.

## Summary

- CacheAligner detects **four specific patterns**: UUIDs, ISO-8601 timestamps, JWTs, and hex hashes (MD5/SHA-1/SHA-256).
- Detection uses **structural validation** (`uuid.UUID`, `datetime.fromisoformat`, base64 decoding, and `int(token, 16)`) rather than regular expressions.
- The transform is **read-only**: it never modifies prompts, only reports findings via `VolatileFinding` objects and logs.
- Implementation resides in [`headroom/transforms/cache_aligner.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/cache_aligner.py) with specific helper functions at lines 76-152.
- An **alignment score** (0-100) quantifies cache stability based on the count of volatile content detected.

## Frequently Asked Questions

### Does CacheAligner modify the prompt content?

No. CacheAligner is a detector-only transform that identifies volatile patterns but never mutates the input messages. The `align_for_cache` function returns the original messages unchanged alongside a stable prefix hash and detection metrics.

### How does CacheAligner detect UUIDs without using regular expressions?

The `_is_uuid` function validates UUIDs by checking the token length (36 characters), confirming four hyphens exist at specific positions, and attempting instantiation via Python's `uuid.UUID` parser. This structural approach avoids regex overhead while ensuring RFC 4122 compliance.

### What is the alignment score and how is it calculated?

The alignment score is a 0-100 metric produced by `CacheAligner.get_alignment_score`. The calculation subtracts 10 points for each volatile finding detected in the prompt, then clamps the result to a minimum of 0. Higher scores indicate more cache-friendly content with fewer dynamic elements.

### Can I disable specific detection patterns in CacheAligner?

Yes. Configuration is managed through `CacheAlignerConfig` in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py), which allows toggling individual detectors or adjusting the sensitivity thresholds for the alignment scoring algorithm.