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

Degraded

class Degraded(val scope: String, val prompts: List<String>, val operation: DegradedOperation, val policy: EmbedFailurePolicy, val cause: Throwable) : CacheEvent

The Embedder failed and EmbedFailurePolicy.FALL_BACK_TO_COMPUTE stepped aside, so the call ran uncached.

EmbedderMismatch

class EmbedderMismatch(val scope: String, val prompt: String, val expected: String, val found: String, val entryId: String) : CacheEvent

A candidate was refused because it was written by a different Embedder.identity.

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, val saved: Double = 0.0, val currency: String? = null) : 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.

Shadow

class Shadow(val report: ShadowReport) : CacheEvent

A shadow-mode lookup: what the cache would have decided, at every configured threshold.

Write

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

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

WriteVetoed

class WriteVetoed(val scope: String, val prompt: String, val reason: String) : CacheEvent

A write the cache declined to make because a CachePolicy vetoed it.

Properties

scope

abstract val scope: String

The scope the event happened in.