feat(chronicle): recap result caching

[fagemx]

Context

從 #173 拆出。第一版 recap 每次都呼叫 LLM。快取是 Phase 1 mobile (#174) 的前置需求 — mobile app 讀快取，不需要每次觸發 LLM。

Parent epic: #172
Related: #173 (recap pipeline), #174 (mobile delivery)

---

目標

Recap 結果快取，避免同一 anchor 重複呼叫 LLM。

快取結構

~/.edda/chronicle/cache/
├── <hash>.json          # hash = anchor params 的 deterministic hash
└── index.json           # { hash → { created, anchor_desc, ttl } }

行為

• 同一 anchor + 同一時間範圍 → 直接回傳快取（不重新呼叫 LLM）
• TTL: 預設 4h
• Invalidation: 有新 session 進來（新的 digest timestamp > cache created）→ invalidate
• --fresh flag → 忽略快取，強制重新生成
• Phase 1 (feat(chronicle): Phase 1 — LLM cognitive recap + mobile briefing #174) 的 /api/recap/cached endpoint 直接讀這個快取

架構

edda-chronicle/src/
  cache.rs
    ├── get_cached(anchor_hash) → Option<RecapResult>
    ├── store_result(anchor_hash, result, ttl)
    ├── invalidate_stale()       # 比對 latest session timestamp
    └── cache_key(anchor) → hash # deterministic hash of anchor params

---

驗收標準

• 同一 anchor 第二次呼叫直接回傳快取
• TTL 過期後自動重新生成
• 新 session 進來自動 invalidate 相關快取
• --fresh 忽略快取
• 快取檔案大小合理（< 10KB per recap）
• Phase 1 的 REST API 可直接讀取快取

[fagemx]

Research Phase: Chronicle Recap Result Caching (Issue #176)

Issue Context

Issue: #176 - feat(chronicle): recap result caching
Parent Epic: #172 (Chronicle product pivot - cognitive zoom interface)
Related: #173 (recap pipeline), #174 (mobile delivery)
Status: New feature, no existing implementation

Objective

Implement caching for recap results to avoid repeated LLM calls for the same anchor parameters. This is a prerequisite for Phase 1 mobile (#174) where the mobile app reads cached results without triggering LLM calls.

Current State Analysis

Codebase Structure

1. edda-chronicle crate: Does NOT exist yet

   • Will be created as part of feat(chronicle): Phase 0 — edda recap CLI + edda-chronicle crate #173 (recap pipeline)
   • Expected location: crates/edda-chronicle/
   • Expected modules:
     • anchor.rs - Anchor resolution
     • classify.rs - Behavior classification
     • extract.rs - Transcript extraction
     • relate.rs - BM25 correlation
     • synthesize.rs - LLM synthesis
     • attention.rs - "What needs me" layer
     • state.rs - Last recap state tracking

2. edda-serve REST API: Partially implemented

   • Commit f1c96b3 (branch agent/feat(serve): aggregation API endpoints for chronicle frontend #152, PR feat(serve): add chronicle aggregation API endpoints #182) added endpoints:
     • GET /api/recap - Trigger recap pipeline
     • GET /api/recap/cached - Read cached recap (placeholder)
     • GET /api/overview - Cross-repo attention routing
     • GET /api/projects - List registered projects
   • Current branch (agent/feat(chronicle): recap result caching #176) does NOT have these endpoints
   • The /api/recap/cached endpoint exists but has no actual cache implementation

3. Related infrastructure:

   • edda-store: User-level aggregation at ~/.edda/
   • edda-aggregate: Cross-repo aggregation
   • edda-ledger: Event ledger
   • edda-transcript: Session transcript storage
   • edda-index: Session metadata index

Data Storage Locations

~/.edda/                           # User-level storage (edda-store)
├── registry.json                  # Project registry
└── <project>/
    └── .edda/                     # Per-project storage
        ├── ledger/
        ├── transcripts/
        └── index/

Expected cache location (from issue):
~/.edda/chronicle/cache/
├── <hash>.json                    # Cache entry (hash of anchor params)
└── index.json                     # Cache metadata index

Requirements Analysis

Functional Requirements

1. Cache Structure

   • Location: ~/.edda/chronicle/cache/
   • Individual cache files: <hash>.json where hash = deterministic hash of anchor parameters
   • Index file: index.json tracking all cache entries with metadata

2. Core Operations

   • get_cached(anchor_hash) → Option
   • store_result(anchor_hash, result, ttl)
   • invalidate_stale() - Compare latest session timestamp
   • cache_key(anchor) → hash - Deterministic hash of anchor params

3. Behavior

   • Same anchor + same time range → return cached result (no LLM call)
   • Default TTL: 4 hours
   • Auto-invalidation: New session arrives (digest timestamp > cache created)
   • --fresh flag: Ignore cache, force regeneration
   • Phase 1 (feat(chronicle): Phase 1 — LLM cognitive recap + mobile briefing #174) /api/recap/cached endpoint reads this cache

4. Validation Criteria

   • Second call with same anchor returns cached result
   • TTL expiration triggers regeneration
   • New session invalidates relevant caches
   • --fresh flag bypasses cache
   • Cache file size < 10KB per recap
   • REST API can directly read cache

Non-Functional Requirements

• Performance: Cache hit < 100ms response time
• Storage: Each cache entry < 10KB
• Reliability: Graceful fallback if cache is corrupted
• Concurrency: Handle concurrent cache reads/writes safely

Technical Design Considerations

Anchor Hash Generation

The anchor parameters that should be included in the hash:

struct AnchorParams {
    query: Option<String>,        // Topic query
    project: Option<String>,      // Project name
    since: Option<DateTime>,      // Start time
    scope: Scope,                 // Single/All repos
}

Hash algorithm: BLAKE3 (already used in workspace dependencies)

Cache Entry Structure

{
  "hash": "abc123...",
  "anchor": {
    "query": null,
    "project": "edda",
    "since": "2026-03-04T00:00:00Z",
    "scope": "single"
  },
  "result": {
    "net_result": "...",
    "needs_you": "...",
    "decisions": "...",
    "related": "..."
  },
  "created_at": "2026-03-05T09:15:00Z",
  "ttl_seconds": 14400,
  "latest_session_ts": "2026-03-05T08:00:00Z"
}

Index Structure

{
  "version": 1,
  "entries": {
    "abc123...": {
      "anchor_desc": "edda project since 2026-03-04",
      "created_at": "2026-03-05T09:15:00Z",
      "ttl_seconds": 14400,
      "file_size": 8192
    }
  }
}

Invalidation Strategy

1. Time-based: Check created_at + ttl_seconds < now()
2. Data-based: Check if any session has digest.timestamp > cache.latest_session_ts

File Locking

Need to handle concurrent access:

• Use fs2 crate (already in workspace dependencies) for file locking
• Lock index.json during updates
• Individual cache files can be read without locks (immutable after creation)

Implementation Scope

What to Implement (Issue #176)

1. New module: crates/edda-chronicle/src/cache.rs

   • All cache operations
   • Hash generation
   • TTL management
   • Stale detection

2. Integration points:

   • CLI --fresh flag in cmd_recap.rs (future)
   • REST API /api/recap/cached endpoint (in edda-serve)
   • Cache directory initialization

3. Dependencies:

   • blake3 for hashing (already in workspace)
   • serde + serde_json for serialization
   • time crate for timestamps
   • fs2 for file locking

What NOT to Implement (Out of Scope)

• Actual recap engine (that's feat(chronicle): Phase 0 — edda recap CLI + edda-chronicle crate #173)
• LLM integration (feat(chronicle): Phase 0 — edda recap CLI + edda-chronicle crate #173)
• BM25 search (feat(chronicle): Phase 0 — edda recap CLI + edda-chronicle crate #173)
• Mobile app (feat(chronicle): Phase 1 — LLM cognitive recap + mobile briefing #174)
• Multi-provider LLM client (feat(chronicle): LLM multi-provider client abstraction #175)
• GitHub API enrichment (feat(chronicle): GitHub API enrichment for attention layer #177)

Risks and Challenges

1. Dependency on feat(chronicle): Phase 0 — edda recap CLI + edda-chronicle crate #173: Cache module needs to integrate with recap engine that doesn't exist yet

   • Mitigation: Design cache module to be independent, with clear interfaces

2. Hash collision: BLAKE3 is cryptographically strong, collision extremely unlikely

   • Mitigation: Use full hash output (not truncated)

3. Cache invalidation complexity: Determining when to invalidate

   • Mitigation: Start with simple time-based TTL, add session-based invalidation

4. Concurrent access: Multiple processes accessing cache

   • Mitigation: Use file locks on index, design immutable cache files

5. Storage growth: Cache could grow unbounded

   • Mitigation: Add cleanup mechanism in invalidate_stale()

Questions for Clarification

1. Should we implement cache cleanup/eviction policy in this issue?
2. Should the --fresh flag be in the cache module or in the CLI layer?
3. How should we handle cache misses in /api/recap/cached - error or trigger new recap?
4. Should we store the full RecapResult or just the JSON response?

Next Steps

1. Innovation Phase: Explore different cache implementation approaches
2. Planning Phase: Create detailed implementation plan with file-by-file changes
3. Implementation: Build cache module with tests
4. Integration: Wire up to existing/future recap infrastructure

[fagemx]

Innovation Phase: Cache Implementation Approaches

Overview

This document explores different approaches to implementing the recap result caching system for issue #176. Each approach is evaluated against the requirements and constraints identified in the research phase.

Approach 1: File-Based Cache with Index (Recommended)

Design

~/.edda/chronicle/cache/
├── index.json           # Metadata index
└── entries/
    ├── abc123.json      # Cache entry files
    ├── def456.json
    └── ...

Implementation Details

Index Structure:

{
  "version": 1,
  "entries": {
    "abc123...": {
      "anchor_desc": "edda project since 2026-03-04",
      "created_at": "2026-03-05T09:15:00Z",
      "ttl_seconds": 14400,
      "latest_session_ts": "2026-03-05T08:00:00Z",
      "file": "entries/abc123.json"
    }
  }
}

Cache Entry Structure:

{
  "hash": "abc123...",
  "anchor": { ... },
  "result": {
    "net_result": "...",
    "needs_you": "...",
    "decisions": "...",
    "related": "..."
  },
  "metadata": {
    "created_at": "2026-03-05T09:15:00Z",
    "ttl_seconds": 14400,
    "latest_session_ts": "2026-03-05T08:00:00Z",
    "size_bytes": 8192
  }
}

API:

pub struct Cache {
    cache_dir: PathBuf,
}

impl Cache {
    pub fn open() -> Result<Self>;
    pub fn get(&self, anchor: &AnchorParams) -> Result<Option<CachedRecap>>;
    pub fn store(&self, anchor: &AnchorParams, result: RecapResult, ttl: Duration) -> Result<()>;
    pub fn invalidate_stale(&self) -> Result<usize>;
    pub fn clear(&self) -> Result<()>;
}

Pros

• ✅ Simple and straightforward
• ✅ Human-readable (can inspect cache manually)
• ✅ Easy debugging
• ✅ No external dependencies
• ✅ Matches issue requirements exactly
• ✅ Atomic file writes (write to temp, then rename)
• ✅ Easy to implement cleanup

Cons

• ⚠️ Index file is a potential bottleneck (needs locking)
• ⚠️ Many small files (but acceptable for cache use case)
• ⚠️ No built-in compression (could add later if needed)

Complexity

• Low: Basic file I/O with JSON serialization
• Implementation time: 2-3 hours for core module + tests

Approach 2: SQLite-Based Cache

Design

Use SQLite database to store cache entries:

CREATE TABLE cache_entries (
    hash TEXT PRIMARY KEY,
    anchor_json TEXT NOT NULL,
    result_json TEXT NOT NULL,
    created_at TEXT NOT NULL,
    ttl_seconds INTEGER NOT NULL,
    latest_session_ts TEXT NOT NULL,
    size_bytes INTEGER NOT NULL
);

CREATE INDEX idx_created_at ON cache_entries(created_at);
CREATE INDEX idx_session_ts ON cache_entries(latest_session_ts);

Implementation

pub struct Cache {
    conn: rusqlite::Connection,
}

impl Cache {
    pub fn open(cache_dir: &Path) -> Result<Self>;
    pub fn get(&self, anchor: &AnchorParams) -> Result<Option<CachedRecap>>;
    pub fn store(&self, anchor: &AnchorParams, result: RecapResult, ttl: Duration) -> Result<()>;
    pub fn invalidate_stale(&self) -> Result<usize>;
}

Pros

• ✅ Built-in query capabilities
• ✅ Efficient TTL queries
• ✅ Single file storage
• ✅ Built-in concurrency handling
• ✅ ACID guarantees

Cons

• ❌ Requires adding rusqlite dependency
• ❌ Overkill for simple key-value cache
• ❌ Binary format (not human-readable)
• ❌ SQLite file corruption risk
• ❌ More complex setup

Complexity

• Medium: Need to handle SQLite connections and migrations
• Implementation time: 4-5 hours

Approach 3: In-Memory Cache with Disk Persistence

Design

Keep cache in memory with periodic disk persistence:

pub struct Cache {
    cache_dir: PathBuf,
    entries: Arc<RwLock<HashMap<String, CacheEntry>>>,
    flush_handle: JoinHandle<()>,
}

impl Cache {
    pub fn open(cache_dir: &Path) -> Result<Self> {
        let entries = Self::load_from_disk(cache_dir)?;
        let flush_handle = Self::start_flush_thread(entries.clone(), cache_dir);
        Ok(Self { cache_dir, entries, flush_handle })
    }
}

Pros

• ✅ Fast lookups (in-memory)
• ✅ Can batch disk writes
• ✅ Good for high-frequency access

Cons

• ❌ Complex concurrency model
• ❌ Risk of data loss on crash
• ❌ Memory usage grows with cache size
• ❌ Overkill for expected access patterns
• ❌ Doesn't match issue's file-based structure

Complexity

• High: Need to handle threading, synchronization, crash recovery
• Implementation time: 6-8 hours

Approach 4: Hybrid - Memory Index + File Entries

Design

Keep index in memory, entries on disk:

pub struct Cache {
    cache_dir: PathBuf,
    index: Arc<RwLock<CacheIndex>>,
}

struct CacheIndex {
    entries: HashMap<String, IndexEntry>,
}

Pros

• ✅ Fast index lookups
• ✅ Human-readable entries
• ✅ Reduced disk I/O for lookups

Cons

• ⚠️ More complex than Approach 1
• ⚠️ Need to persist index changes
• ⚠️ Memory usage for index
• ⚠️ Index corruption risk

Complexity

• Medium-High: More moving parts than simple file approach
• Implementation time: 4-5 hours

Evaluation Matrix

Criterion	Approach 1 (File+Index)	Approach 2 (SQLite)	Approach 3 (Memory+Disk)	Approach 4 (Hybrid)
Simplicity	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐
Performance	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Reliability	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
Debuggability	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
No Dependencies	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Match Requirements	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐
Implementation Time	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐

Recommendation: Approach 1 (File-Based Cache with Index)

Rationale

1. Matches Requirements Exactly: The issue specifically describes a file-based structure with index.json
2. Simplicity: Easiest to implement, test, and debug
3. No New Dependencies: Uses existing workspace dependencies (serde, serde_json, blake3, fs2)
4. Good Enough Performance: Cache hits will be < 100ms (requirement met)
5. Reliability: Atomic file writes, easy recovery from corruption
6. Future-Proof: Can migrate to SQLite later if performance becomes an issue

Implementation Strategy

1. Phase 1: Core cache module with basic operations

   • Cache::open(), get(), store()
   • Hash generation with BLAKE3
   • JSON serialization
   • File locking for index

2. Phase 2: TTL and invalidation

   • Time-based expiration
   • Session timestamp tracking
   • invalidate_stale() implementation

3. Phase 3: Integration

   • Wire up to /api/recap/cached endpoint
   • Add --fresh flag support (future)
   • Error handling and fallbacks

Key Design Decisions

1. Hash Function: BLAKE3 (fast, secure, already in dependencies)
2. File Format: JSON (human-readable, debuggable)
3. Locking Strategy: Lock index.json during updates, no locks for reads
4. Atomic Writes: Write to .tmp file, then rename() for atomicity
5. Error Handling: Return Option<RecapResult> for misses, Result<()> for errors
6. Cache Key: Hash of canonicalized anchor JSON (ensures determinism)

Alternative Considered: Separate Cache Files by Project

Idea: Store cache entries per-project:

~/.edda/chronicle/cache/
├── edda/
│   ├── index.json
│   └── entries/...
└── karvi/
    ├── index.json
    └── entries/...

Rejected Because:

• Cross-project anchors (--all) would need to check multiple directories
• More complex index management
• No clear benefit over single cache directory
• Can be added later if needed

Testing Strategy

Unit Tests

• Hash generation determinism
• Cache store and retrieve
• TTL expiration
• Session timestamp invalidation
• Concurrent access (multiple threads)
• Corrupted file recovery

Integration Tests

• End-to-end cache flow
• /api/recap/cached endpoint
• Cache miss scenarios
• Cache invalidation

Performance Tests

• Cache hit latency < 100ms
• Concurrent read performance
• Index file size with 1000+ entries

Open Questions Resolved

1. Cache cleanup/eviction: YES, implement in `invalidate_sta