fix(cache): enforce CacheMetadata active-state invariant

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 914400439

Author: GWeale

src/google/adk/models/cache_metadata.py

@@ -20,6 +20,7 @@
 from pydantic import BaseModel
 from pydantic import ConfigDict
 from pydantic import Field
+from pydantic import model_validator
 
 
 class CacheMetadata(BaseModel):
@@ -97,6 +98,16 @@ class CacheMetadata(BaseModel):
       ),
   )
 
+  @model_validator(mode="after")
+  def _enforce_active_state_invariant(self) -> "CacheMetadata":
+    active = (self.cache_name, self.expire_time, self.invocations_used)
+    if len({f is not None for f in active}) > 1:
+      raise ValueError(
+          "cache_name, expire_time, and invocations_used must all be set "
+          "(active cache) or all be None (fingerprint-only state)"
+      )
+    return self
+
   @property
   def expire_soon(self) -> bool:
     """Check if the cache will expire soon (with 2-minute buffer)."""
@@ -113,12 +124,6 @@ def __str__(self) -> str:
           f"fingerprint={self.fingerprint[:8]}..."
       )
     cache_id = self.cache_name.split("/")[-1]
-    if self.expire_time is None:
-      return (
-          f"Cache {cache_id}: used {self.invocations_used} invocations, "
-          f"cached {self.contents_count} contents, "
-          "expires unknown"
-      )
     time_until_expiry_minutes = (self.expire_time - time.time()) / 60
     return (
         f"Cache {cache_id}: used {self.invocations_used} invocations, "

tests/unittests/models/test_cache_metadata.py

@@ -317,3 +317,30 @@ def test_missing_required_fields(self):
     assert metadata.expire_time is None
     assert metadata.invocations_used is None
     assert metadata.created_at is None
+
+  def test_partial_active_state_rejected(self):
+    """cache_name, expire_time, invocations_used must all be set or all None."""
+    # Only cache_name set.
+    with pytest.raises(ValidationError, match="must all be set"):
+      CacheMetadata(
+          cache_name="projects/123/locations/us-central1/cachedContents/x",
+          fingerprint="abc",
+          contents_count=1,
+      )
+
+    # cache_name + expire_time but no invocations_used.
+    with pytest.raises(ValidationError, match="must all be set"):
+      CacheMetadata(
+          cache_name="projects/123/locations/us-central1/cachedContents/x",
+          expire_time=time.time() + 1800,
+          fingerprint="abc",
+          contents_count=1,
+      )
+
+    # invocations_used set without cache_name (e.g. construction bug).
+    with pytest.raises(ValidationError, match="must all be set"):
+      CacheMetadata(
+          fingerprint="abc",
+          invocations_used=3,
+          contents_count=1,
+      )

tests/unittests/sessions/test_vertex_ai_session_service.py

@@ -1020,7 +1020,12 @@ async def test_append_event():
       ),
       cache_metadata=CacheMetadata(
           cache_name='test_cache_name',
+          expire_time=(
+              datetime.datetime.now(datetime.timezone.utc)
+              + datetime.timedelta(minutes=30)
+          ).timestamp(),
           fingerprint='test_fingerprint',
+          invocations_used=1,
           contents_count=1,
       ),
       citation_metadata=genai_types.CitationMetadata(