Cache Scope and Keys

When adding or modifying caching/deduplication, ensure the cache identity (routing + key + scope) matches the exact contract where reuse is valid.

Key rules:

• Don’t misroute payloads/data into the wrong cache class (it breaks downstream assumptions). Validate/type-separate before caching.
• Gate dedupe logic to the correct mode/contract; never let a shared dedupe path change a different caller’s behavior.
• Make cache bypass/partition decisions at cache construction time (so the boundary can’t be bypassed by earlier history narrowing).
• Avoid stale fast-path reuse: when you detect an execution path that can desynchronize state (e.g., UI/tab rebinds), mark “possibly diverged” and skip the fast cached result until an authoritative signal updates the cache.
• Cache keys/signatures must encode the real compatibility scope. Don’t collapse distinct variants into one identity (e.g., using only “key present” instead of stable key identity).
• Bound and scope caches: use LRU/eviction, and scope process-global caches by active profile/config signature to prevent cross-profile leakage.

Example (mode-gated dedupe key):

def should_dedupe(event_guid: str, *, use_socketio: bool) -> bool:
    # Dedupe only applies to Socket.IO duplicate suppression.
    return use_socketio and bool(event_guid)

Example (scoped config cache):

_config_cache_by_home = {}

def load_audit_config_scoped(hermes_home: str) -> dict:
    key = hermes_home
    if key in _config_cache_by_home:
        return dict(_config_cache_by_home[key])
    cfg = compute_cfg(hermes_home)
    _config_cache_by_home[key] = cfg
    return dict(cfg)

Example (signature compatibility without secret material):

• Include stable, non-secret identity fields in the cache signature (e.g., a hashed/derived key identity), not only “key exists”. Ensure the signature changes when runtime auth/session compatibility changes.

Apply these checks during code review: “Is this cache used by multiple call paths/modes? If so, is reuse gated correctly and does the key include all compatibility dimensions? Is the cache bounded and scoped to the correct profile/lifecycle?”