Module semantic_cache 

Semantic Cache with Provenance-Safe Keys (Task 8)

This module provides a semantic caching layer that:

• Uses exact key matching for deterministic cache hits
• Supports semantic similarity search for approximate matches
• Preserves provenance (DERIVED_FROM edges to sources)
• Integrates with AllowedSet for policy-aware caching

Design Principles

1. Exact-match first: Hash of (normalized_query, AllowedSet) for deterministic hits
2. Semantic fallback: ANN search with explicit similarity threshold
3. Provenance tracking: Every cache entry tracks its source documents
4. Policy integration: Cache hits respect AllowedSet (no post-filtering)

Complexity

• Exact match: O(1) hash lookup
• Semantic search: O(log n) with HNSW index
• Policy gating: O(1) per entry with namespace/allowed-set check

Cache Invalidation Strategy

Cache entries are invalidated when:

1. TTL expires
2. Any source document is updated (via provenance edges)
3. Policy changes affect the AllowedSet

Note: Semantic similarity ≠ query equivalence. Similar queries may have different correct answers, so semantic cache hits are marked as “approximate”.

Structs

CacheEntry

A cached result entry

CacheKey

Unique cache key combining query and access context

CacheLookupResult

Cache lookup result

SemanticCache

Provenance-safe semantic cache

SemanticCacheConfig

Configuration for the semantic cache

Enums

CacheMatchType

Type of cache match

Functions

hash_allowed_set

Compute a hash of an AllowedSet for cache keying