What decentralized cache coherency invariants prevent agents from acting on mutually contradictory replicas?

**Date of Record:** 2026 October 27 **Scope:** Applies when multiple agentic sessions cache shared resource state (configuration, capability descriptors, or content) independently, and the caches diverge, so agents reading from their local caches act on contradictory worldviews without realizing it. Does not apply to strictly centralized cache layers or agents that always read from origin.

Core Distinction

The separation between **cache locality** (each agent's cache is fast and accessible) and **cache coherency** (all agents' caches reflect the same underlying state within acceptable bounds). Relying on locality creates the **Contradictory Replica Hazard**: Agent A's cache says the config is X, Agent B's cache says Y, both agents act on their caches, and the resulting actions contradict each other, causing split-brain behavior in a system that appears unified.

What Was Observed

In decentralized agent mesh architectures, failing to enforce cache coherency produces three primary failure modes:

  1. **Config Split-Brain:** Agents in different mesh segments cache different configuration values. Each segment behaves correctly under its own config, but the segments contradict each other, and downstream consumers see inconsistent results.
  2. **Capability Descriptor Race:** Agents cache capability descriptors with different expiry times. Some agents see a capability as deprecated, others see it as active, and the mesh's behavior depends on which agent handles each request.
  3. **Silent Staleness:** An agent's cache is stale but the agent doesn't know it. The agent makes decisions based on stale state, unaware that peers have already updated theirs.

Recorded Elements

  1. **`cache_version_signature`:** For each cache entry, the exact version of the underlying state it reflects, allowing detection of stale entries.
  2. **`cache_coherency_epoch_receipt`:** A cryptographic proof from the origin of the latest state epoch, allowing each agent to check whether its cache is within coherency bounds.
  3. **`cache_invalidation_broadcast_receipt`:** When the origin updates state, a cryptographic broadcast to all caching agents, prompting invalidation.
  4. **`cache_coherency_tolerance_receipt`:** The explicit tolerance for cache staleness before the agent must invalidate (e.g., "max 5 seconds staleness"), allowing coherency to be balanced against performance.

Condition of Validity

* **Applies when:** Multiple agents cache the same state, caches can diverge, and agents act on cached state. * **Does not apply when:** Caching is strictly local to each agent with no cross-agent state, or agents always read from origin.

Decision Boundary

  1. **Does the cache entry reflect the origin's current state?** If yes, standard caching applies. If no, the cache is stale.
  2. **Is the staleness within the `cache_coherency_tolerance_receipt`?** If yes, the cache is acceptable. If no, the agent must invalidate before acting.
  3. **Has a `cache_invalidation_broadcast_receipt` been received?** If yes, the agent must invalidate immediately, regardless of tolerance.
  4. **Conversely, when can an agent act on stale cache without invalidation?** Only when the specific action is provably insensitive to the state change (e.g., the action doesn't touch the changed field), or the staleness is verified to be within tolerance for the action's requirements.

Operational Effect

  1. **Split-Brain Prevention:** Cache coherency bounds prevent agents from acting on contradictory state.
  2. **Staleness Awareness:** Agents know when their caches are stale, enabling informed decisions.
  3. **Broadcast Discipline:** Origin updates trigger invalidation broadcasts, reducing divergence windows.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class CoherencyVerdict(Enum):
    CACHE_CURRENT = auto()
    CACHE_WITHIN_TOLERANCE = auto()
    CACHE_STALE_INVALIDATE = auto()
    INVALIDATION_BROADCASTED = auto()

@dataclass(frozen=True)
class CacheEntry:
    entry_id: str
    cached_state_epoch: float
    origin_current_epoch: float
    tolerance_sec: float
    invalidation_broadcast_received: bool

@dataclass(frozen=True)
class CoherencyPolicy:
    require_broadcast_invalidation: bool

@dataclass(frozen=True)
class CoherencyManifest:
    verdict: CoherencyVerdict
    staleness_sec: float
    directive: str
    manifest_digest: str

class DecentralizedCacheCoherencyGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_cache_entry(
        cls, entry: CacheEntry, policy: CoherencyPolicy
    ) -> CoherencyManifest:
        
        # Gate 1: Broadcast invalidation
        if entry.invalidation_broadcast_received and policy.require_broadcast_invalidation:
            return CoherencyManifest(
                verdict=CoherencyVerdict.INVALIDATION_BROADCASTED,
                staleness_sec=entry.origin_current_epoch - entry.cached_state_epoch,
                directive=f"INVALIDATE: Broadcast received for {entry.entry_id}. Re-fetch.",
                manifest_digest=cls._hash(f"BROADCAST:{entry.entry_id}")
            )

        staleness = entry.origin_current_epoch - entry.cached_state_epoch

        # Gate 2: Current
        if staleness <= 0:
            digest = cls._hash(json.dumps({
                "entry": entry.entry_id,
                "staleness": f"{staleness:.1f}",
                "status": "CURRENT"
            }, sort_keys=True))
            return CoherencyManifest(
                verdict=CoherencyVerdict.CACHE_CURRENT,
                staleness_sec=0.0,
                directive=f"PROCEED: Cache {entry.entry_id} current.",
                manifest_digest=digest
            )

        # Gate 3: Within tolerance
        if staleness <= entry.tolerance_sec:
            digest = cls._hash(json.dumps({
                "entry": entry.entry_id,
                "staleness": f"{staleness:.1f}",
                "tolerance": f"{entry.tolerance_sec:.1f}"
            }, sort_keys=True))
            return CoherencyManifest(
                verdict=CoherencyVerdict.CACHE_WITHIN_TOLERANCE,
                staleness_sec=staleness,
                directive=f"PROCEED_WITH_CAUTION: Cache {entry.entry_id} stale by {staleness:.1f}s within {entry.tolerance_sec:.1f}s.",
                manifest_digest=digest
            )

        # Gate 4: Stale
        return CoherencyManifest(
            verdict=CoherencyVerdict.CACHE_STALE_INVALIDATE,
            staleness_sec=staleness,
            directive=f"INVALIDATE: Cache {entry.entry_id} stale by {staleness:.1f}s > {entry.tolerance_sec:.1f}s.",
            manifest_digest=cls._hash(f"STALE:{entry.entry_id}:{staleness:.1f}")
        )