tying up some loose ends (#11292)

docs/traffic_management_module.md

@@ -177,6 +177,33 @@ carries throttle state.
 
 ---
 
+## Tick clocks and wrap safety
+
+Every per-node timestamp in TMM's caches is a free-running modular tick (uint8 or nibble) taken
+from `clockMs()` - never an absolute time. That is what keeps `UnifiedCacheEntry` at 10 bytes
+across up to 2048 entries. The cost is that modular subtraction is only correct while the true age
+stays below the counter's period, so every clock needs something to clear expired state before it
+aliases. (The direct-serve throttle above is the deliberate exception: full `uint32` milliseconds
+compared by wrap-safe subtraction, hence no tick and no sweep.)
+
+| Clock              | Tick / period  | Window          | Kept honest by                                     |
+| ------------------ | -------------- | --------------- | -------------------------------------------------- |
+| pos                | 6 min / 25.6 h | <=255 ticks     | 60 s sweep (margin as low as 1 tick at the clamp)  |
+| rate               | 5 min / 80 min | <=15 ticks      | sweep + read-time window reset (`isRateLimited()`) |
+| unknown            | 1 min / 16 min | 12 ticks        | sweep + read-time window reset                     |
+| NodeInfo `obsTick` | 3 min / 12.8 h | 120 ticks (6 h) | sweep only                                         |
+
+`obsTick` is the sharp case: `maintainNodeInfoCacheLocked()` clearing `hasObserved` is the
+_sole_ guarantee the 6 h serve gate never reads an aliased stamp. That makes the sweep a
+compile-time invariant - guarded by `TMM_HAS_NODEINFO_CACHE` **alone** (never
+`TRAFFIC_MANAGEMENT_CACHE_SIZE`, which a variant may zero independently), mirroring `purgeAll()`:
+a build that has the cache always has its sweep.
+
+The stores these clocks stamp, and the warm tier's contrasting absolute timestamps, are described
+in [node_info_stores.md](node_info_stores.md).
+
+---
+
 ## Configuration
 
 All tunables live under `moduleConfig.traffic_management`; the whole module is gated by the