CacheEvent

sealed interface CacheEvent

Something a SemanticCache (or its CacheStore) did, delivered to a CacheListener the moment it happens.

The counters in CacheStats tell you the totals; events tell you the stream. A dashboard that wants a hit-rate gauge reads CacheStats; a metrics exporter that wants a per-lookup latency histogram, a log line per decision, or a live tap on evictions subscribes to these instead of polling. Emitting is opt-in — a cache with no listeners builds no events and measures no timings, so the default hot path is unchanged.

Every event names the scope it happened in, so a subscriber can tag or filter by scope without threading it separately.

Inheritors

Types

Eviction

class Eviction(val scope: String, val prompt: String, val entryId: String, val cause: EvictionCause) : CacheEvent

An entry left the store, either evicted for capacity/memory or dropped past its TTL.

Hit

class Hit(val scope: String, val prompt: String, val matchedPrompt: String, val similarity: Double, val entryId: String, val timings: EventTimings) : CacheEvent

A lookup that was served from the cache.

Miss

class Miss(val scope: String, val prompt: String, val reason: MissReason, val bestSimilarity: Double?, val detail: String?, val guardName: String?, val timings: EventTimings) : CacheEvent

A lookup that could not be served, with the same reason CacheLookup.Miss reports.

Write

class Write(val scope: String, val prompt: String, val entryId: String) : CacheEvent

A new entry was written, through put, getOrPut, or warm.

Properties

scope

abstract val scope: String

The scope the event happened in.