fix: VectorClock thread safety, integrity type hints, audit comment (#243)

- VectorClock: add threading.Lock to prevent race conditions in
  concurrent tick/merge/copy/eq operations (#160)
- integrity.py: add Callable/ModuleType type hints to helper
  functions (#158)
- audit.py: fix stale comment — hashes ARE computed by
  MerkleAuditChain.add_entry() (#176)

Closes #160, closes #158, closes #176

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: imran-siddique

packages/agent-compliance/src/agent_compliance/integrity.py

@@ -26,9 +26,11 @@
 import json
 import logging
 import os
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Optional
+from types import ModuleType
+from typing import Any, Optional
 
 logger = logging.getLogger(__name__)
 
@@ -178,7 +180,7 @@ def _hash_file(path: str) -> str:
     return h.hexdigest()
 
 
-def _hash_function_bytecode(func) -> str:
+def _hash_function_bytecode(func: Callable[..., Any]) -> str:
     """SHA-256 hash of a function's compiled bytecode."""
     code = func.__code__
     h = hashlib.sha256()
@@ -187,10 +189,10 @@ def _hash_function_bytecode(func) -> str:
     return h.hexdigest()
 
 
-def _resolve_function(module, dotted_name: str):
+def _resolve_function(module: ModuleType, dotted_name: str) -> Any | None:
     """Resolve 'ClassName.method' or 'function_name' from a module."""
     parts = dotted_name.split(".")
-    obj = module
+    obj: Any = module
     for part in parts:
         obj = getattr(obj, part, None)
         if obj is None:

packages/agent-hypervisor/src/hypervisor/session/vector_clock.py

@@ -10,6 +10,7 @@
 
 from __future__ import annotations
 
+import threading
 from dataclasses import dataclass, field
 
 
@@ -19,23 +20,37 @@ class CausalViolationError(Exception):
 
 @dataclass
 class VectorClock:
-    """A version counter (community edition: tracking only, no enforcement)."""
+    """A version counter (community edition: tracking only, no enforcement).
+
+    Thread-safe: all reads and mutations are guarded by an internal lock
+    to prevent data races when multiple agents tick/merge concurrently.
+    """
 
     clocks: dict[str, int] = field(default_factory=dict)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
 
     def tick(self, agent_did: str) -> None:
         """Increment the clock for an agent."""
-        self.clocks[agent_did] = self.clocks.get(agent_did, 0) + 1
+        with self._lock:
+            self.clocks[agent_did] = self.clocks.get(agent_did, 0) + 1
 
     def get(self, agent_did: str) -> int:
-        return self.clocks.get(agent_did, 0)
+        with self._lock:
+            return self.clocks.get(agent_did, 0)
 
     def merge(self, other: VectorClock) -> VectorClock:
-        """Merge two version counters (take component-wise max)."""
-        merged = VectorClock(clocks=dict(self.clocks))
-        for agent, clock in other.clocks.items():
-            merged.clocks[agent] = max(merged.clocks.get(agent, 0), clock)
-        return merged
+        """Merge two version counters (take component-wise max).
+
+        Acquires locks on both clocks to get consistent snapshots.
+        """
+        # Deterministic lock ordering by id() to prevent deadlocks
+        first, second = sorted([self, other], key=id)
+        with first._lock:
+            with second._lock:
+                merged_clocks = dict(self.clocks)
+                for agent, clock in other.clocks.items():
+                    merged_clocks[agent] = max(merged_clocks.get(agent, 0), clock)
+        return VectorClock(clocks=merged_clocks)
 
     def happens_before(self, other: VectorClock) -> bool:
         return False
@@ -44,16 +59,20 @@ def is_concurrent(self, other: VectorClock) -> bool:
         return False
 
     def copy(self) -> VectorClock:
-        return VectorClock(clocks=dict(self.clocks))
+        with self._lock:
+            return VectorClock(clocks=dict(self.clocks))
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, VectorClock):
             return False
-        all_agents = set(self.clocks.keys()) | set(other.clocks.keys())
-        return all(
-            self.clocks.get(a, 0) == other.clocks.get(a, 0)
-            for a in all_agents
-        )
+        first, second = sorted([self, other], key=id)
+        with first._lock:
+            with second._lock:
+                all_agents = set(self.clocks.keys()) | set(other.clocks.keys())
+                return all(
+                    self.clocks.get(a, 0) == other.clocks.get(a, 0)
+                    for a in all_agents
+                )
 
 
 class VectorClockManager:

packages/agent-mesh/src/agentmesh/governance/audit.py

@@ -51,7 +51,7 @@ class AuditEntry(BaseModel):
     policy_decision: Optional[str] = None
     matched_rule: Optional[str] = None
 
-    # Chaining — kept for API compatibility but not computed
+    # Chaining — populated automatically by MerkleAuditChain.add_entry()
     previous_hash: str = Field(default="")
     entry_hash: str = Field(default="")