shared-tensor 0.2.9__tar.gz → 0.2.11__tar.gz

shared_tensor-0.2.11/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Athena Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{shared_tensor-0.2.9 → shared_tensor-0.2.11}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: shared-tensor
-Version: 0.2.9
+Version: 0.2.11
 Summary: Native PyTorch CUDA IPC over Unix Domain Socket for same-host process separation
 Author-email: Athena Team <contact@world-sim-dev.org>
 Maintainer-email: Athena Team <contact@world-sim-dev.org>
-License-Expression: Apache-2.0
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/world-sim-dev/shared-tensor
 Project-URL: Repository, https://github.com/world-sim-dev/shared-tensor
 Project-URL: Documentation, https://github.com/world-sim-dev/shared-tensor/tree/main/docs
@@ -65,7 +65,7 @@ Supported:
 - explicit endpoint registration
 - sync `call` and task-backed `submit`
 - managed object handles with explicit release
-- server-side caching, `cache_format_key`, and singleflight
+- server-side caching, `cache_format_key`, singleflight, and explicit cache invalidation
 - manual two-process deployment as the primary production path
 - zero-branch auto mode gated by `SHARED_TENSOR_ENABLED=1`
 
@@ -108,6 +108,8 @@ Production should prefer two explicitly started processes: one server process th
 
 See [examples/model_service.py](./examples/model_service.py) for endpoint definitions.
 
+The server-oriented example modules construct providers with explicit `execution_mode="server"` so importing the module already reflects the intended deployment role.
+
 Server process:
 
 ```python
@@ -154,6 +156,7 @@ manages cache and refcounts         releases managed handles explicitly
 
 Core assumption:
 - the server process that owns the original CUDA allocation must stay alive while clients are still using reopened CUDA tensors or modules
+- handle health checks can detect some stale-object conditions, but they do not remove the producer-liveness requirement
 
 If the server exits, crashes, or is killed before the client is done with the shared CUDA object, behavior is no longer guaranteed by this library. Depending on PyTorch and CUDA runtime state, the client may see CUDA runtime errors, invalid resource handle failures, broken module execution, or process-level instability.
 
@@ -168,6 +171,11 @@ Treat producer liveness as a hard requirement, not a soft optimization.
 
 See [examples/zero_branch_env.py](./examples/zero_branch_env.py). This is a convenience mode for environments that want one file and environment-controlled behavior.
 
+Resolution rule:
+- `SHARED_TENSOR_ENABLED` unset or false: provider stays local
+- `SHARED_TENSOR_ENABLED=1` and `SHARED_TENSOR_ROLE=server`: provider resolves to server and auto-starts the thread-backed local server
+- `SHARED_TENSOR_ENABLED=1` and role unset or `client`: provider resolves to client
+
 ```bash
 SHARED_TENSOR_ENABLED=1 SHARED_TENSOR_ROLE=server python demo.py
 SHARED_TENSOR_ENABLED=1 python demo.py
@@ -185,6 +193,27 @@ shared function runs locally        shared function becomes RPC call
 CUDA object stays on same GPU       CUDA object is reopened via torch IPC
 ```
 
+## Example: Task Submission And Wait
+
+See [examples/async_service.py](./examples/async_service.py).
+
+```python
+from shared_tensor import AsyncSharedTensorClient, SharedTensorProvider
+
+provider = SharedTensorProvider(execution_mode="server")
+
+@provider.share(execution="task")
+def build_delayed_model(delay: float = 0.1):
+    ...
+
+client = AsyncSharedTensorClient()
+task_id = client.submit("build_delayed_model", delay=0.1)
+model = client.wait_for_task(task_id, timeout=30)
+```
+
+Use `SharedTensorProvider(execution="task")` for task-backed endpoints.
+Use `AsyncSharedTensorClient` when you want a task-oriented waiting interface.
+
 ## Example: Reusable Model Registry
 
 See [examples/model_service.py](./examples/model_service.py).
@@ -295,11 +324,47 @@ handle.release()
 ```
 
 Use managed mode for cached models or other reusable long-lived CUDA objects.
+Managed object introspection now includes `created_at` and `last_accessed_at` timestamps through `get_object_info()`.
+
+## Cache Invalidation
+
+The library now exposes explicit cache invalidation instead of forcing process restarts when a cached object becomes stale.
+
+```python
+provider.invalidate_call_cache("load_model", hidden_size=4096)
+provider.invalidate_endpoint_cache("load_model")
+```
+
+Client-side equivalents are also available:
+
+```python
+client.invalidate_call_cache("load_model", hidden_size=4096)
+client.invalidate_endpoint_cache("load_model")
+```
+
+Use call-level invalidation when you want to evict one cache key.
+Use endpoint-level invalidation when you want to drop all cached variants for the endpoint.
+Invalidation removes cache lookup entries; it does not guarantee that already-issued client handles remain valid after producer death.
+
+
+## Handle Health Checks
+
+Managed handles now carry the producer `server_id` and support lightweight liveness probes:
+
+```python
+handle = client.call("load_model", hidden_size=4096)
+info = handle.get_object_info()
+client.ensure_handle_live(handle)
+```
+
+If the producer no longer owns the object, `client.ensure_handle_live(handle)` raises `SharedTensorStaleHandleError`.
+This is still advisory, not a durability guarantee: it helps detect stale handles earlier, but it cannot make producer death safe.
 
 ## Runtime Introspection
 
-`client.get_server_info()` now returns readiness and process metadata in addition to endpoint and capability data.
+`client.get_server_info()` now returns readiness, stable `server_id`, cache/task counters, and process metadata in addition to endpoint and capability data.
 In client mode, `provider.get_runtime_info()` wraps that into a provider-oriented view.
+`AsyncSharedTensorClient` exposes the same runtime, cache invalidation, release, and handle-health helper methods as `SharedTensorClient`; the async surface is task-oriented, not capability-reduced.
 
 ```python
 info = provider.get_runtime_info()

{shared_tensor-0.2.9 → shared_tensor-0.2.11}/README.md

@@ -12,7 +12,7 @@ Supported:
 - explicit endpoint registration
 - sync `call` and task-backed `submit`
 - managed object handles with explicit release
-- server-side caching, `cache_format_key`, and singleflight
+- server-side caching, `cache_format_key`, singleflight, and explicit cache invalidation
 - manual two-process deployment as the primary production path
 - zero-branch auto mode gated by `SHARED_TENSOR_ENABLED=1`
 
@@ -55,6 +55,8 @@ Production should prefer two explicitly started processes: one server process th
 
 See [examples/model_service.py](./examples/model_service.py) for endpoint definitions.
 
+The server-oriented example modules construct providers with explicit `execution_mode="server"` so importing the module already reflects the intended deployment role.
+
 Server process:
 
 ```python
@@ -101,6 +103,7 @@ manages cache and refcounts         releases managed handles explicitly
 
 Core assumption:
 - the server process that owns the original CUDA allocation must stay alive while clients are still using reopened CUDA tensors or modules
+- handle health checks can detect some stale-object conditions, but they do not remove the producer-liveness requirement
 
 If the server exits, crashes, or is killed before the client is done with the shared CUDA object, behavior is no longer guaranteed by this library. Depending on PyTorch and CUDA runtime state, the client may see CUDA runtime errors, invalid resource handle failures, broken module execution, or process-level instability.
 
@@ -115,6 +118,11 @@ Treat producer liveness as a hard requirement, not a soft optimization.
 
 See [examples/zero_branch_env.py](./examples/zero_branch_env.py). This is a convenience mode for environments that want one file and environment-controlled behavior.
 
+Resolution rule:
+- `SHARED_TENSOR_ENABLED` unset or false: provider stays local
+- `SHARED_TENSOR_ENABLED=1` and `SHARED_TENSOR_ROLE=server`: provider resolves to server and auto-starts the thread-backed local server
+- `SHARED_TENSOR_ENABLED=1` and role unset or `client`: provider resolves to client
+
 ```bash
 SHARED_TENSOR_ENABLED=1 SHARED_TENSOR_ROLE=server python demo.py
 SHARED_TENSOR_ENABLED=1 python demo.py
@@ -132,6 +140,27 @@ shared function runs locally        shared function becomes RPC call
 CUDA object stays on same GPU       CUDA object is reopened via torch IPC
 ```
 
+## Example: Task Submission And Wait
+
+See [examples/async_service.py](./examples/async_service.py).
+
+```python
+from shared_tensor import AsyncSharedTensorClient, SharedTensorProvider
+
+provider = SharedTensorProvider(execution_mode="server")
+
+@provider.share(execution="task")
+def build_delayed_model(delay: float = 0.1):
+    ...
+
+client = AsyncSharedTensorClient()
+task_id = client.submit("build_delayed_model", delay=0.1)
+model = client.wait_for_task(task_id, timeout=30)
+```
+
+Use `SharedTensorProvider(execution="task")` for task-backed endpoints.
+Use `AsyncSharedTensorClient` when you want a task-oriented waiting interface.
+
 ## Example: Reusable Model Registry
 
 See [examples/model_service.py](./examples/model_service.py).
@@ -242,11 +271,47 @@ handle.release()
 ```
 
 Use managed mode for cached models or other reusable long-lived CUDA objects.
+Managed object introspection now includes `created_at` and `last_accessed_at` timestamps through `get_object_info()`.
+
+## Cache Invalidation
+
+The library now exposes explicit cache invalidation instead of forcing process restarts when a cached object becomes stale.
+
+```python
+provider.invalidate_call_cache("load_model", hidden_size=4096)
+provider.invalidate_endpoint_cache("load_model")
+```
+
+Client-side equivalents are also available:
+
+```python
+client.invalidate_call_cache("load_model", hidden_size=4096)
+client.invalidate_endpoint_cache("load_model")
+```
+
+Use call-level invalidation when you want to evict one cache key.
+Use endpoint-level invalidation when you want to drop all cached variants for the endpoint.
+Invalidation removes cache lookup entries; it does not guarantee that already-issued client handles remain valid after producer death.
+
+
+## Handle Health Checks
+
+Managed handles now carry the producer `server_id` and support lightweight liveness probes:
+
+```python
+handle = client.call("load_model", hidden_size=4096)
+info = handle.get_object_info()
+client.ensure_handle_live(handle)
+```
+
+If the producer no longer owns the object, `client.ensure_handle_live(handle)` raises `SharedTensorStaleHandleError`.
+This is still advisory, not a durability guarantee: it helps detect stale handles earlier, but it cannot make producer death safe.
 
 ## Runtime Introspection
 
-`client.get_server_info()` now returns readiness and process metadata in addition to endpoint and capability data.
+`client.get_server_info()` now returns readiness, stable `server_id`, cache/task counters, and process metadata in addition to endpoint and capability data.
 In client mode, `provider.get_runtime_info()` wraps that into a provider-oriented view.
+`AsyncSharedTensorClient` exposes the same runtime, cache invalidation, release, and handle-health helper methods as `SharedTensorClient`; the async surface is task-oriented, not capability-reduced.
 
 ```python
 info = provider.get_runtime_info()

{shared_tensor-0.2.9 → shared_tensor-0.2.11}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shared-tensor"
-version = "0.2.9"
+version = "0.2.11"
 description = "Native PyTorch CUDA IPC over Unix Domain Socket for same-host process separation"
 readme = "README.md"
-license = "Apache-2.0"
+license = "MIT"
 authors = [
     {name = "Athena Team", email = "contact@world-sim-dev.org"}
 ]

{shared_tensor-0.2.9 → shared_tensor-0.2.11}/shared_tensor/__init__.py

@@ -1,22 +1,22 @@
 """shared_tensor: same-host same-GPU PyTorch CUDA IPC over local UDS RPC."""
 
 from shared_tensor.async_client import AsyncSharedTensorClient
-from shared_tensor.async_provider import AsyncSharedTensorProvider
 from shared_tensor.async_task import TaskInfo, TaskStatus
 from shared_tensor.client import SharedTensorClient
+from shared_tensor.errors import SharedTensorStaleHandleError
 from shared_tensor.managed_object import SharedObjectHandle
 from shared_tensor.provider import SharedTensorProvider
 from shared_tensor.server import SharedTensorServer
 
 __all__ = [
     "AsyncSharedTensorClient",
-    "AsyncSharedTensorProvider",
     "SharedTensorClient",
     "SharedObjectHandle",
+    "SharedTensorStaleHandleError",
     "SharedTensorProvider",
     "SharedTensorServer",
     "TaskInfo",
     "TaskStatus",
 ]
 
-__version__ = "0.2.9"
+__version__ = "0.2.11"

{shared_tensor-0.2.9 → shared_tensor-0.2.11}/shared_tensor/async_client.py

@@ -10,6 +10,7 @@ from typing import Any, cast
 from shared_tensor.async_task import TaskInfo, TaskStatus
 from shared_tensor.client import SharedTensorClient
 from shared_tensor.errors import SharedTensorRemoteError, SharedTensorTaskError
+from shared_tensor.managed_object import SharedObjectHandle
 
 
 logger = logging.getLogger(__name__)
@@ -51,6 +52,38 @@ class AsyncSharedTensorClient:
     def get_task_result(self, task_id: str) -> Any:
         return self.result(task_id)
 
+    def ping(self) -> bool:
+        return self._client.ping()
+
+    def get_server_info(self) -> dict[str, Any]:
+        return self._client.get_server_info()
+
+    def list_endpoints(self) -> dict[str, Any]:
+        return self._client.list_endpoints()
+
+    def release(self, object_id: str) -> bool:
+        return self._client.release(object_id)
+
+    def release_many(self, object_ids: list[str]) -> dict[str, bool]:
+        return self._client.release_many(object_ids)
+
+    def get_object_info(self, object_id: str) -> dict[str, Any] | None:
+        return self._client.get_object_info(object_id)
+
+    def ensure_handle_live(
+        self,
+        handle: SharedObjectHandle[Any],
+        *,
+        refresh: bool = True,
+    ) -> dict[str, Any]:
+        return self._client.ensure_handle_live(handle, refresh=refresh)
+
+    def invalidate_call_cache(self, endpoint: str, *args: Any, **kwargs: Any) -> bool:
+        return self._client.invalidate_call_cache(endpoint, *args, **kwargs)
+
+    def invalidate_endpoint_cache(self, endpoint: str) -> int:
+        return self._client.invalidate_endpoint_cache(endpoint)
+
     def wait(
         self,
         task_id: str,

{shared_tensor-0.2.9 → shared_tensor-0.2.11}/shared_tensor/client.py

@@ -7,6 +7,7 @@ import socket
 from dataclasses import dataclass
 from typing import Any, cast
 
+from shared_tensor.async_task import TaskStatus
 from shared_tensor.errors import (
     SharedTensorCapabilityError,
     SharedTensorClientError,
@@ -16,12 +17,12 @@ from shared_tensor.errors import (
     SharedTensorProtocolError,
     SharedTensorRemoteError,
     SharedTensorSerializationError,
+    SharedTensorStaleHandleError,
     SharedTensorTaskError,
 )
 from shared_tensor.managed_object import ReleaseHandle, SharedObjectHandle
 from shared_tensor.runtime import get_local_server
 from shared_tensor.transport import recv_message, send_message
-from shared_tensor.async_task import TaskStatus
 from shared_tensor.utils import (
     deserialize_payload,
     resolve_runtime_socket_path,
@@ -29,7 +30,6 @@ from shared_tensor.utils import (
     validate_payload_for_transport,
 )
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -41,6 +41,9 @@ class _ClientReleaser(ReleaseHandle):
     def release(self) -> bool:
         return self.client.release(self.object_id)
 
+    def get_object_info(self) -> dict[str, Any] | None:
+        return self.client.get_object_info(self.object_id)
+
 
 class SharedTensorClient:
     """UDS client for endpoint-oriented local RPC execution."""
@@ -76,6 +79,8 @@ class SharedTensorClient:
             code = 5
         elif isinstance(exc, SharedTensorConfigurationError):
             code = 6
+        elif isinstance(exc, SharedTensorStaleHandleError):
+            code = 8
         else:
             code = 7
         return SharedTensorRemoteError(
@@ -105,6 +110,7 @@ class SharedTensorClient:
             object_id=cast(str, object_id),
             value=value,
             _releaser=_ClientReleaser(client=self, object_id=cast(str, object_id)),
+            server_id=self._infer_server_id(),
         )
 
     def _send_request(self, request: dict[str, Any]) -> Any:
@@ -158,6 +164,15 @@ class SharedTensorClient:
     def _request(self, method: str, params: dict[str, Any] | None = None) -> Any:
         return self._send_request({"method": method, "params": params or {}})
 
+    def _infer_server_id(self) -> str | None:
+        local_server = self._local_server()
+        if local_server is not None:
+            return cast(str | None, getattr(local_server, "server_id", None))
+        try:
+            return cast(str | None, self.get_server_info().get("server_id"))
+        except (SharedTensorClientError, SharedTensorRemoteError, SharedTensorProtocolError):
+            return None
+
     def call(self, endpoint: str, *args: Any, **kwargs: Any) -> Any:
         if self.verbose_debug:
             logger.debug("Client calling endpoint", extra={"endpoint": endpoint})
@@ -245,6 +260,25 @@ class SharedTensorClient:
         result = self._request("get_object_info", {"object_id": object_id})
         return cast(dict[str, Any] | None, result.get("object"))
 
+    def ensure_handle_live(self, handle: SharedObjectHandle[Any], *, refresh: bool = True) -> dict[str, Any]:
+        info = handle.get_object_info(refresh=refresh)
+        if info is None:
+            raise SharedTensorStaleHandleError(
+                f"Managed object '{handle.object_id}' is no longer registered on the producer",
+                object_id=handle.object_id,
+                server_id=handle.server_id,
+                reason="object_missing",
+            )
+        observed_server_id = cast(str | None, info.get("server_id"))
+        if handle.server_id is not None and observed_server_id is not None and observed_server_id != handle.server_id:
+            raise SharedTensorStaleHandleError(
+                f"Managed object '{handle.object_id}' belongs to server '{handle.server_id}' but producer now reports '{observed_server_id}'",
+                object_id=handle.object_id,
+                server_id=handle.server_id,
+                reason="server_mismatch",
+            )
+        return info
+
     def ping(self) -> bool:
         if self._local_server() is not None:
             return True
@@ -260,6 +294,31 @@ class SharedTensorClient:
             return self._run_local(lambda: cast(dict[str, Any], local_server._get_server_info()))
         return cast(dict[str, Any], self._request("get_server_info"))
 
+    def invalidate_call_cache(self, endpoint: str, *args: Any, **kwargs: Any) -> bool:
+        local_server = self._local_server()
+        if local_server is not None:
+            return self._run_local(
+                lambda: bool(local_server.invalidate_call_cache(endpoint, args=tuple(args), kwargs=dict(kwargs)))
+            )
+        encoding, args_payload, kwargs_payload = serialize_call_payloads(tuple(args), dict(kwargs))
+        result = self._request(
+            "invalidate_call_cache",
+            {
+                "endpoint": endpoint,
+                "args_bytes": args_payload,
+                "kwargs_bytes": kwargs_payload,
+                "encoding": encoding,
+            },
+        )
+        return bool(result["invalidated"])
+
+    def invalidate_endpoint_cache(self, endpoint: str) -> int:
+        local_server = self._local_server()
+        if local_server is not None:
+            return self._run_local(lambda: int(local_server.invalidate_endpoint_cache(endpoint)))
+        result = self._request("invalidate_endpoint_cache", {"endpoint": endpoint})
+        return int(result["invalidated"])
+
     def list_endpoints(self) -> dict[str, Any]:
         local_server = self._local_server()
         if local_server is not None:
@@ -344,4 +403,5 @@ class SharedTensorClient:
             object_id=cast(str, object_id),
             value=value,
             _releaser=_ClientReleaser(client=self, object_id=cast(str, object_id)),
+            server_id=cast(str | None, result.get("server_id")),
         )

{shared_tensor-0.2.9 → shared_tensor-0.2.11}/shared_tensor/errors.py

@@ -15,6 +15,7 @@ __all__ = [
     "SharedTensorClientError",
     "SharedTensorServerError",
     "SharedTensorProviderError",
+    "SharedTensorStaleHandleError",
 ]
 
 
@@ -69,3 +70,20 @@ class SharedTensorServerError(SharedTensorError):
 
 class SharedTensorProviderError(SharedTensorError):
     """Raised for provider registration or invocation problems."""
+
+
+class SharedTensorStaleHandleError(SharedTensorError):
+    """Raised when a managed handle can no longer be trusted."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        object_id: str | None = None,
+        server_id: str | None = None,
+        reason: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.object_id = object_id
+        self.server_id = server_id
+        self.reason = reason

{shared_tensor-0.2.9 → shared_tensor-0.2.11}/shared_tensor/managed_object.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+import time
 import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from threading import RLock
 from typing import Any, Generic, TypeVar
 
@@ -17,6 +18,8 @@ class ManagedObjectEntry:
     endpoint: str
     cache_key: str | None
     refcount: int = 1
+    created_at: float = 0.0
+    last_accessed_at: float = 0.0
 
 
 @dataclass(slots=True)
@@ -42,15 +45,19 @@ class ManagedObjectRegistry:
             if entry is None:
                 self._cache_index.pop(cache_key, None)
                 return None
+            entry.last_accessed_at = time.time()
             return entry
 
     def register(self, *, endpoint: str, value: Any, cache_key: str | None) -> ManagedObjectEntry:
         with self._lock:
+            now = time.time()
             entry = ManagedObjectEntry(
                 object_id=uuid.uuid4().hex,
                 value=value,
                 endpoint=endpoint,
                 cache_key=cache_key,
+                created_at=now,
+                last_accessed_at=now,
             )
             self._entries[entry.object_id] = entry
             if cache_key is not None:
@@ -67,6 +74,7 @@ class ManagedObjectRegistry:
             if entry is None:
                 return None
             entry.refcount += 1
+            entry.last_accessed_at = time.time()
             return entry
 
     def release(self, object_id: str) -> ManagedReleaseResult:
@@ -100,6 +108,31 @@ class ManagedObjectRegistry:
                 "endpoint": entry.endpoint,
                 "cache_key": entry.cache_key,
                 "refcount": entry.refcount,
+                "created_at": entry.created_at,
+                "last_accessed_at": entry.last_accessed_at,
+            }
+
+    def invalidate_cache_key(self, cache_key: str) -> bool:
+        with self._lock:
+            object_id = self._cache_index.pop(cache_key, None)
+            return object_id is not None
+
+    def invalidate_endpoint(self, endpoint: str) -> int:
+        with self._lock:
+            keys = [
+                cache_key
+                for cache_key, object_id in self._cache_index.items()
+                if (entry := self._entries.get(object_id)) is not None and entry.endpoint == endpoint
+            ]
+            for cache_key in keys:
+                self._cache_index.pop(cache_key, None)
+            return len(keys)
+
+    def stats(self) -> dict[str, int]:
+        with self._lock:
+            return {
+                "objects": len(self._entries),
+                "cached_objects": len(self._cache_index),
             }
 
     def clear(self) -> None:
@@ -112,6 +145,9 @@ class ReleaseHandle:
     def release(self) -> bool:  # pragma: no cover - protocol surface only
         raise NotImplementedError
 
+    def get_object_info(self) -> dict[str, Any] | None:  # pragma: no cover - protocol surface only
+        raise NotImplementedError
+
 
 @dataclass(slots=True)
 class SharedObjectHandle(Generic[T]):
@@ -119,6 +155,8 @@ class SharedObjectHandle(Generic[T]):
     value: T
     _releaser: ReleaseHandle
     released: bool = False
+    server_id: str | None = None
+    _metadata_cache: dict[str, Any] | None = field(default=None, init=False, repr=False)
 
     def release(self) -> bool:
         if self.released:
@@ -126,8 +164,19 @@ class SharedObjectHandle(Generic[T]):
         released = self._releaser.release()
         if released:
             self.released = True
+            self._metadata_cache = None
         return released
 
+    def get_object_info(self, *, refresh: bool = False) -> dict[str, Any] | None:
+        if self.released:
+            return None
+        if self._metadata_cache is None or refresh:
+            self._metadata_cache = self._releaser.get_object_info()
+        return None if self._metadata_cache is None else dict(self._metadata_cache)
+
+    def is_stale(self) -> bool:
+        return self.get_object_info(refresh=True) is None
+
     def __enter__(self) -> SharedObjectHandle[T]:
         return self