agent-coherence 0.1.0__py3-none-any.whl

agent_coherence-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: agent-coherence
+Version: 0.1.0
+Summary: MESI-style artifact coherence for multi-agent AI systems
+Author: Arbiter contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/hipvlady/agent-coherence
+Project-URL: Repository, https://github.com/hipvlady/agent-coherence
+Project-URL: Issues, https://github.com/hipvlady/agent-coherence/issues
+Keywords: multi-agent,llm,cache-coherence,mesi,token-efficiency,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# agent-coherence — The Coherence Protocol for AI Agents
+
+[![CI](https://github.com/hipvlady/agent-coherence/actions/workflows/ci.yml/badge.svg)](https://github.com/hipvlady/agent-coherence/actions/workflows/ci.yml)
+
+`agent-coherence` implements MESI-style cache coherence for shared artifacts in multi-agent LLM systems, reducing synchronization token overhead and preventing stale-context coordination failures.
+
+## Install
+
+```bash
+pip install agent-coherence
+```
+
+## Quick start
+
+```python
+from ccs.simulation.engine import run_strategy_comparison
+from ccs.simulation.scenarios import load_scenario
+
+scenario = load_scenario("benchmarks/scenarios/planning_canonical.yaml")
+report = run_strategy_comparison(scenario, strategies=["eager", "lazy"], runs=5, seed_start=20260305)
+print(report.to_dict()["aggregated"])
+```
+
+## Reproduce benchmark artifacts
+
+```bash
+bash reproduce.sh
+```
+
+See [REPRODUCE.md](REPRODUCE.md) for full output mapping and baseline verification details.
+
+## Paper
+
+Token Coherence: MESI-Style Cache Coherence for Shared Artifacts in Multi-Agent LLM Systems
+
+## License
+
+Apache-2.0 (`LICENSE`)

agent_coherence-0.1.0.dist-info/RECORD

@@ -0,0 +1,52 @@
+ccs/__init__.py,sha256=2S8ad6p_CbjpSl-X3mDhJj9oXjr1AISYM1hFY3PXkxI,142
+ccs/adapters/__init__.py,sha256=gyT71N9t3Fb8itew4jEdjo28T2g3hR4Lxs6viBmwyLE,404
+ccs/adapters/autogen.py,sha256=Prsk1VVsgYv3ebTPaGnN_zRj8Ddj_TYuBEbinD-rxCE,2025
+ccs/adapters/base.py,sha256=eXN315RUBQ6WglPQGb9Hxcj4MHFY81C5crzQdtGw17U,5027
+ccs/adapters/crewai.py,sha256=WUHOn-Czs5B97RANKWiU8iDjHKD1xANnNu5oWZYTr0U,1967
+ccs/adapters/langgraph.py,sha256=NvRzg25FPBjSzIBtLSJqw9E_IWvkoEZrv8MnISYsj6Q,2268
+ccs/agent/__init__.py,sha256=XJfn-7psLp0Jh5RNsWEWF7ZGW57jdmtYjFWLl9HZbJk,243
+ccs/agent/cache.py,sha256=xVCdW-Y2WvNyjhQlEv87txrgRwL6mOPdl3fSaDRa-eI,2142
+ccs/agent/runtime.py,sha256=IxfrFUuQMufpz3kTyKfAaUQDBmQs5cOwbcP13ry3yAE,5317
+ccs/artifacts/__init__.py,sha256=22WxwBkzE7duFv3QOATR31M8oUZX47U_3gz9knZJpGo,525
+ccs/artifacts/diff_engine.py,sha256=THqQBvNt2jecgYSHrSrU00gnswL4PzPre_g-TQMNn8E,2505
+ccs/bus/__init__.py,sha256=5lC8Ays3kjBYrCNi04V5Xan8yjppT1zielN4aDMVA1w,270
+ccs/bus/event_bus.py,sha256=QId5bn_fcFqSgk1M04ChMdSKJIfx-R5563zUuEIRt6w,2511
+ccs/cli/__init__.py,sha256=e1CJhIy_tAMvtQgBQg-UmJejQN9FlRIA4hIVHaI9IsI,154
+ccs/cli/compare.py,sha256=do-UMWIlHjkF9fM2-Y56LMpxubaRrsVVGl7M3lMiRoc,1947
+ccs/cli/simulate.py,sha256=XRlY-p-M5kuNZQllCs7twZCKcZwr158_SUfCzL5zp-k,2526
+ccs/coordinator/__init__.py,sha256=PrFEsZBKkjjiLAZB73HGlwiN_VeyQpRt4tu9DUYEwuU,142
+ccs/coordinator/registry.py,sha256=qbV-__pYudg0qT9oD_rh_m81fHaJiy9fPqPWjc24Rak,4733
+ccs/coordinator/service.py,sha256=dk3lnKikGorZIYR8aFzxA0ClecpsEPA9AEYjiIghv0I,10131
+ccs/core/__init__.py,sha256=zfMsBhGqaCoRnTVLyY-JC5ek4spreU_vg-8oMuCT5SM,426
+ccs/core/clock.py,sha256=zx9pUq52YzvVF1oE4XxM6-cQ4jL26Szf-0CCFeIYC7Q,869
+ccs/core/exceptions.py,sha256=o5s4AxZrt1QzMuLei9p_31mxF5sqw1OrDfc_p5WgC5I,1033
+ccs/core/granularity.py,sha256=Oa_UPOO-gk6vr5qfhtHDBpx_lfz2HqojRHNFxdu3cl4,1555
+ccs/core/invariants.py,sha256=L4fL7Fbt-aYr1Idr1I9UiE9DqmuKPc2jCQc3xsIuT-c,1342
+ccs/core/states.py,sha256=ip5IPDHs0dtteLwVNunnIMSO91XkkpjVee5f2us0574,2712
+ccs/core/types.py,sha256=2dRw1IV0SulwNxP_Dm2vIKFdxwSzaC8URmVDnLwALOw,1595
+ccs/hardening/__init__.py,sha256=IfdPmq1rAcCvJK9Dmo72SDM7GAEeg4gWT8vqhKGkIGM,264
+ccs/hardening/architecture.py,sha256=WW0DFWkiyc2JpzSefgceQ420lqD4R3f3YruANgCxPlw,7619
+ccs/output/__init__.py,sha256=tmlFl0DjV0tjvKKmTPS39Y8OBxQEgKWxrKUs3A2Y2LU,354
+ccs/output/report.py,sha256=WftfAEWpeWW_CoeMgQA8qmdkbm-YBGfNdG13zMEQBLI,3967
+ccs/simulation/__init__.py,sha256=RYWDi74I39j2oOsB9mrKHTaSB77vcopJGHyg6zaE428,611
+ccs/simulation/aggregation.py,sha256=_5uR93OUKMtFEJsUPZbuyFUZlsyKE8VOYW8PvPMjI50,4245
+ccs/simulation/bounds.py,sha256=mn6AcflF0tJbb3rjaXPeHS-mWAA_Q3rG3qBIT26NoIw,766
+ccs/simulation/consistency.py,sha256=0o6nEzEuoCBWIksQEspeb8jAaaUZCa6Xa7m0asSqzAk,2413
+ccs/simulation/engine.py,sha256=fANyYoTmiIKYM3i22UYZBJulNZRgEBhe75lywfl4sBA,18617
+ccs/simulation/metrics.py,sha256=3Tz3_J6-diTb-6SSjkt8W8GVmUDxdZxyv2hyZ-Vx2RU,3345
+ccs/simulation/scenarios.py,sha256=F3xgrKPFuasNN_VyHV1NqvfFwPjg8sEsVUi-5YboHwc,12294
+ccs/strategies/__init__.py,sha256=E_Y3BAFAEAnLPzAN7PR77dtrC-vccXNHMjftPDegELk,642
+ccs/strategies/access_count.py,sha256=IZ4dWKMlPzENZzM2xlVSrOIlsFZtt9LTQoz8niA0Elw,1375
+ccs/strategies/base.py,sha256=74z_TynciGT-gGMaZkGr95x1MzrHN3KiOI-PYMEkqfs,2388
+ccs/strategies/broadcast.py,sha256=ACYq6sf5SFowwmZJYML5jz_MT5-xljRZv3Whe0-RfOA,1326
+ccs/strategies/eager.py,sha256=CnpyK_F6OdHg2JC2B9Xg2LpJ3uPByJ2RHODiUVbATqU,1237
+ccs/strategies/lazy.py,sha256=dk36rrhmvaUgREHeGpAElx3JdcHiVta1dtt600jyLtk,1025
+ccs/strategies/lease.py,sha256=msTDi4RXC7BrlFV71c1Xm8srngkJs82GAYun14qsUVQ,1674
+ccs/strategies/selector.py,sha256=g34sxyQHAcAWyAPVw-YqY_g0OrItO7cFiOpGtrQXUbg,1489
+ccs/transport/__init__.py,sha256=yOEOoqbjv4BOeOgHKpiwBRWd-gtkUcSHAvpc9Kvfg9c,125
+ccs/transport/network_sim.py,sha256=4JwcHu7Vfturctc4NBPjUX_TgJP5hsySbL5uIGB8CUw,2867
+agent_coherence-0.1.0.dist-info/METADATA,sha256=BgW8EXLjkvhsEq-axrcrrq2xeD-8vMkaMrtiC9Cbe8Y,2036
+agent_coherence-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_coherence-0.1.0.dist-info/entry_points.txt,sha256=H1ASIW41_8EPpNxEt6--wZhg_xCJV9-fpQWp2aiyWuk,147
+agent_coherence-0.1.0.dist-info/top_level.txt,sha256=B_84q_sceurFYPD4eVb3n5al34HIbMKe3LgAXojdC_g,4
+agent_coherence-0.1.0.dist-info/RECORD,,

agent_coherence-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_coherence-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+ccs-check-architecture = ccs.hardening.architecture:main
+ccs-compare = ccs.cli.compare:main
+ccs-simulate = ccs.cli.simulate:main

agent_coherence-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ccs

ccs/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""agent-coherence core package."""
+
+__version__ = "0.1.0"

ccs/adapters/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""Framework-facing integration adapters for CCS runtime."""
+
+from .autogen import AutoGenAdapter
+from .base import CoherenceAdapterCore
+from .crewai import CrewAIAdapter
+from .langgraph import LangGraphAdapter
+
+__all__ = [
+    "CoherenceAdapterCore",
+    "LangGraphAdapter",
+    "CrewAIAdapter",
+    "AutoGenAdapter",
+]

ccs/adapters/autogen.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""AutoGen-oriented coherence adapter utilities."""
+
+from __future__ import annotations
+
+from typing import Mapping
+from uuid import UUID
+
+from ccs.core.types import Artifact
+
+from .base import CoherenceAdapterCore
+
+
+class AutoGenAdapter:
+    """Adapter exposing per-turn hooks for AutoGen-like conversations."""
+
+    def __init__(self, *, strategy_name: str = "lazy", core: CoherenceAdapterCore | None = None) -> None:
+        self.core = core if core is not None else CoherenceAdapterCore(strategy_name=strategy_name)
+
+    def register_agent(self, name: str) -> UUID:
+        """Register one conversational agent identity."""
+        return self.core.register_agent(name)
+
+    def register_artifact(self, *, name: str, content: str, size_tokens: int | None = None) -> Artifact:
+        """Register shared artifact for conversation context."""
+        return self.core.register_artifact(name=name, content=content, size_tokens=size_tokens)
+
+    def pre_turn_context(
+        self,
+        *,
+        agent_name: str,
+        artifact_ids: list[UUID],
+        now_tick: int,
+    ) -> dict[UUID, str]:
+        """Fetch current context before an agent turn."""
+        return {
+            artifact_id: self.core.read(agent_name=agent_name, artifact_id=artifact_id, now_tick=now_tick).content
+            for artifact_id in artifact_ids
+        }
+
+    def post_turn_commit(
+        self,
+        *,
+        agent_name: str,
+        updates: Mapping[UUID, str],
+        now_tick: int,
+    ) -> dict[UUID, int]:
+        """Commit turn updates and return updated versions."""
+        versions: dict[UUID, int] = {}
+        for artifact_id, content in updates.items():
+            artifact = self.core.write(
+                agent_name=agent_name,
+                artifact_id=artifact_id,
+                content=content,
+                now_tick=now_tick,
+            )
+            versions[artifact_id] = artifact.version
+        return versions

ccs/adapters/base.py

@@ -0,0 +1,136 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""Common adapter runtime that wires coordinator, agents, and event bus."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import NAMESPACE_URL, UUID, uuid5
+
+from ccs.agent.runtime import AgentRuntime
+from ccs.bus.event_bus import ArtifactUpdateEvent, InMemoryEventBus
+from ccs.coordinator.registry import ArtifactRegistry
+from ccs.coordinator.service import CoordinatorService
+from ccs.core.types import Artifact, FetchResponse
+from ccs.strategies.base import SyncStrategy
+from ccs.strategies.selector import build_strategy
+
+
+@dataclass(frozen=True)
+class AgentBinding:
+    """Resolved identity/runtime tuple for an adapter-managed agent."""
+
+    name: str
+    agent_id: UUID
+    runtime: AgentRuntime
+
+
+class CoherenceAdapterCore:
+    """Reusable cluster abstraction for framework adapters."""
+
+    def __init__(
+        self,
+        *,
+        strategy_name: str = "lazy",
+        lease_ttl_ticks: int = 300,
+        access_count_max_accesses: int = 100,
+        event_bus: InMemoryEventBus | None = None,
+    ) -> None:
+        self.registry = ArtifactRegistry()
+        self.coordinator = CoordinatorService(self.registry)
+        self.strategy: SyncStrategy = build_strategy(
+            strategy_name,
+            lease_ttl_ticks=lease_ttl_ticks,
+            access_count_max_accesses=access_count_max_accesses,
+        )
+        self.event_bus = event_bus if event_bus is not None else InMemoryEventBus()
+        self._agents_by_name: dict[str, AgentBinding] = {}
+
+    def register_agent(self, name: str) -> UUID:
+        """Register one agent runtime and subscribe it to bus events."""
+        existing = self._agents_by_name.get(name)
+        if existing is not None:
+            return existing.agent_id
+
+        agent_id = uuid5(NAMESPACE_URL, f"ccs-agent:{name}")
+        runtime = AgentRuntime(agent_id=agent_id, coordinator=self.coordinator, strategy=self.strategy)
+        self.event_bus.subscribe(
+            agent_id=agent_id,
+            on_invalidation=runtime.handle_invalidation,
+            on_update=lambda event, runtime=runtime: runtime.handle_update(
+                artifact_id=event.artifact_id,
+                version=event.version,
+                content=event.content,
+                now_tick=event.issued_at_tick,
+                writer_agent_id=event.issuer_agent_id,
+            ),
+        )
+        self._agents_by_name[name] = AgentBinding(name=name, agent_id=agent_id, runtime=runtime)
+        return agent_id
+
+    def register_artifact(
+        self,
+        *,
+        name: str,
+        content: str,
+        size_tokens: int | None = None,
+    ) -> Artifact:
+        """Register a shared artifact in the coordinator directory."""
+        return self.coordinator.register_artifact(name=name, content=content, size_tokens=size_tokens)
+
+    def read(self, *, agent_name: str, artifact_id: UUID, now_tick: int) -> FetchResponse:
+        """Read artifact through one registered runtime."""
+        return self._binding(agent_name).runtime.read(artifact_id, now_tick=now_tick)
+
+    def write(
+        self,
+        *,
+        agent_name: str,
+        artifact_id: UUID,
+        content: str,
+        now_tick: int,
+    ) -> Artifact:
+        """Write artifact through one runtime and dispatch peer events."""
+        writer = self._binding(agent_name)
+        updated, invalidation_signals = writer.runtime.write(
+            artifact_id=artifact_id,
+            content=content,
+            now_tick=now_tick,
+        )
+        peers = [binding.agent_id for binding in self._agents_by_name.values() if binding.agent_id != writer.agent_id]
+
+        for signal in invalidation_signals:
+            self.event_bus.publish_invalidation(signal, recipients=peers)
+
+        if self.strategy.broadcasts_content_on_commit():
+            self.event_bus.publish_update(
+                ArtifactUpdateEvent(
+                    artifact_id=artifact_id,
+                    version=updated.version,
+                    content=content,
+                    issued_at_tick=now_tick,
+                    issuer_agent_id=writer.agent_id,
+                ),
+                recipients=peers,
+            )
+
+        return updated
+
+    def content(self, *, agent_name: str, artifact_id: UUID) -> str | None:
+        """Return local content cached by one agent runtime."""
+        return self._binding(agent_name).runtime.content(artifact_id)
+
+    def runtime(self, agent_name: str) -> AgentRuntime:
+        """Return concrete runtime for adapter extensions/testing."""
+        return self._binding(agent_name).runtime
+
+    def agent_names(self) -> list[str]:
+        """Return registered adapter agent names."""
+        return sorted(self._agents_by_name.keys())
+
+    def _binding(self, agent_name: str) -> AgentBinding:
+        binding = self._agents_by_name.get(agent_name)
+        if binding is None:
+            raise KeyError(f"unknown_agent '{agent_name}'")
+        return binding

ccs/adapters/crewai.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""CrewAI-oriented coherence adapter utilities."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from ccs.core.types import Artifact
+
+from .base import CoherenceAdapterCore
+
+
+class CrewAIAdapter:
+    """Adapter exposing task lifecycle helpers for CrewAI-style flows."""
+
+    def __init__(self, *, strategy_name: str = "lazy", core: CoherenceAdapterCore | None = None) -> None:
+        self.core = core if core is not None else CoherenceAdapterCore(strategy_name=strategy_name)
+
+    def register_agent(self, name: str) -> UUID:
+        """Register one crew member identity."""
+        return self.core.register_agent(name)
+
+    def register_artifact(self, *, name: str, content: str, size_tokens: int | None = None) -> Artifact:
+        """Register shared artifact accessible to the crew."""
+        return self.core.register_artifact(name=name, content=content, size_tokens=size_tokens)
+
+    def prepare_task_context(
+        self,
+        *,
+        agent_name: str,
+        artifact_ids: list[UUID],
+        now_tick: int,
+    ) -> dict[UUID, str]:
+        """Materialize artifact content for one task execution."""
+        content_by_artifact: dict[UUID, str] = {}
+        for artifact_id in artifact_ids:
+            response = self.core.read(agent_name=agent_name, artifact_id=artifact_id, now_tick=now_tick)
+            content_by_artifact[artifact_id] = response.content
+        return content_by_artifact
+
+    def commit_task_artifact(
+        self,
+        *,
+        agent_name: str,
+        artifact_id: UUID,
+        content: str,
+        now_tick: int,
+    ) -> int:
+        """Commit task output for one artifact and return resulting version."""
+        artifact = self.core.write(
+            agent_name=agent_name,
+            artifact_id=artifact_id,
+            content=content,
+            now_tick=now_tick,
+        )
+        return artifact.version

ccs/adapters/langgraph.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""LangGraph-oriented coherence adapter utilities."""
+
+from __future__ import annotations
+
+from typing import Mapping
+from uuid import UUID
+
+from ccs.core.types import Artifact
+
+from .base import CoherenceAdapterCore
+
+
+class LangGraphAdapter:
+    """Adapter exposing pre/post node hooks backed by CCS runtime."""
+
+    def __init__(self, *, strategy_name: str = "lazy", core: CoherenceAdapterCore | None = None) -> None:
+        self.core = core if core is not None else CoherenceAdapterCore(strategy_name=strategy_name)
+
+    def register_agent(self, name: str) -> UUID:
+        """Register node runtime identity."""
+        return self.core.register_agent(name)
+
+    def register_artifact(self, *, name: str, content: str, size_tokens: int | None = None) -> Artifact:
+        """Register shared artifact used by LangGraph nodes."""
+        return self.core.register_artifact(name=name, content=content, size_tokens=size_tokens)
+
+    def before_node(
+        self,
+        *,
+        agent_name: str,
+        artifact_ids: list[UUID],
+        now_tick: int,
+    ) -> dict[UUID, dict[str, object]]:
+        """Read artifacts before node execution and return context payload."""
+        context: dict[UUID, dict[str, object]] = {}
+        for artifact_id in artifact_ids:
+            response = self.core.read(agent_name=agent_name, artifact_id=artifact_id, now_tick=now_tick)
+            context[artifact_id] = {
+                "version": response.version,
+                "content": response.content,
+                "state": response.state_grant.value,
+            }
+        return context
+
+    def commit_outputs(
+        self,
+        *,
+        agent_name: str,
+        writes: Mapping[UUID, str],
+        now_tick: int,
+    ) -> dict[UUID, int]:
+        """Commit node outputs and return artifact versions."""
+        versions: dict[UUID, int] = {}
+        for artifact_id, content in writes.items():
+            artifact = self.core.write(
+                agent_name=agent_name,
+                artifact_id=artifact_id,
+                content=content,
+                now_tick=now_tick,
+            )
+            versions[artifact_id] = artifact.version
+        return versions

ccs/agent/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""Agent-side cache and runtime components."""
+
+from .cache import ArtifactCache
+from .runtime import AgentRuntime
+
+__all__ = ["ArtifactCache", "AgentRuntime"]

ccs/agent/cache.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""Local artifact cache used by agent runtime."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from uuid import UUID
+
+from ccs.core.states import MESIState
+from ccs.core.types import ArtifactCacheEntry
+
+
+class ArtifactCache:
+    """In-memory per-agent cache for artifact entries."""
+
+    def __init__(self) -> None:
+        self._entries: dict[UUID, ArtifactCacheEntry] = {}
+
+    def get(self, artifact_id: UUID) -> ArtifactCacheEntry | None:
+        """Return cache entry for artifact if present."""
+        return self._entries.get(artifact_id)
+
+    def put(self, artifact_id: UUID, entry: ArtifactCacheEntry) -> None:
+        """Insert or replace cache entry for artifact."""
+        self._entries[artifact_id] = entry
+
+    def invalidate(
+        self,
+        artifact_id: UUID,
+        *,
+        invalidated_version: int | None = None,
+        issued_at_tick: int = 0,
+    ) -> None:
+        """Set entry state to INVALID, creating placeholder if missing."""
+        entry = self._entries.get(artifact_id)
+        if entry is None:
+            self._entries[artifact_id] = ArtifactCacheEntry(
+                artifact_id=artifact_id,
+                state=MESIState.INVALID,
+                local_version=max(invalidated_version or 0, 0),
+                acquired_at_tick=issued_at_tick,
+            )
+            return
+
+        next_version = entry.local_version
+        if invalidated_version is not None:
+            next_version = min(entry.local_version, invalidated_version)
+        self._entries[artifact_id] = replace(
+            entry,
+            state=MESIState.INVALID,
+            local_version=max(next_version, 0),
+        )
+
+    def has_valid(self, artifact_id: UUID) -> bool:
+        """Return whether artifact is cached in non-invalid state."""
+        entry = self._entries.get(artifact_id)
+        return entry is not None and entry.state != MESIState.INVALID
+
+    def entries(self) -> dict[UUID, ArtifactCacheEntry]:
+        """Return shallow copy of cached entries."""
+        return dict(self._entries)