Merge branch 'feature/phase3-proximity-introspection'

Author: sanity

rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "freenet-stdlib"
-version = "0.1.15"
+version = "0.1.20"
 edition = "2021"
 rust-version = "1.71.1"
 publish = true

rust/src/client_api/client_events.rs

@@ -727,6 +727,7 @@ pub enum QueryResponse {
     ConnectedPeers { peers: Vec<(Peer, SocketAddr)> },
     NetworkDebug(NetworkDebugInfo),
     NodeDiagnostics(NodeDiagnosticsResponse),
+    ProximityCache(ProximityCacheInfo),
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone)]
@@ -806,6 +807,57 @@ pub enum NodeQuery {
         /// Diagnostic configuration specifying what information to collect
         config: NodeDiagnosticsConfig,
     },
+    /// Phase 3: Query proximity cache information for update propagation
+    ProximityCacheInfo,
+}
+
+/// Phase 3: Proximity cache information for update propagation
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ProximityCacheInfo {
+    /// Contracts this node is currently caching
+    pub my_cache: Vec<ContractCacheEntry>,
+    /// What we know about neighbor caches
+    pub neighbor_caches: Vec<NeighborCacheInfo>,
+    /// Proximity propagation statistics
+    pub stats: ProximityStats,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ContractCacheEntry {
+    /// Full contract key as string
+    pub contract_key: String,
+    /// 32-bit hash for proximity matching
+    pub cache_hash: u32,
+    /// When this contract was cached (Unix timestamp)
+    pub cached_since: u64,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct NeighborCacheInfo {
+    /// Peer identifier
+    pub peer_id: String,
+    /// Contract hashes this neighbor is known to cache
+    pub known_contracts: Vec<u32>,
+    /// Last update received from this neighbor (Unix timestamp)
+    pub last_update: u64,
+    /// Number of updates received from this neighbor
+    pub update_count: u64,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ProximityStats {
+    /// Number of cache announcements sent
+    pub cache_announces_sent: u64,
+    /// Number of cache announcements received
+    pub cache_announces_received: u64,
+    /// Updates forwarded via proximity (not subscription)
+    pub updates_via_proximity: u64,
+    /// Updates forwarded via subscription
+    pub updates_via_subscription: u64,
+    /// False positives due to hash collisions
+    pub false_positive_forwards: u64,
+    /// Average number of contracts per neighbor
+    pub avg_neighbor_cache_size: f32,
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone)]