Update docs for cliff detection and performance cross-reference

Add cliff detection overhead note to heartbeat performance doc and
restore Performance section in architecture doc as a cross-reference.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lmiccini

docs/instanceha_architecture.md

@@ -20,9 +20,10 @@ InstanceHA is a high-availability service for OpenStack that automatically detec
 12. [Startup Reconciliation](#startup-reconciliation)
 13. [Graceful Shutdown](#graceful-shutdown)
 14. [Security](#security)
-15. [Testing](#testing)
-16. [Deployment](#deployment)
-17. [Configuration Options Reference](#configuration-options-reference)
+15. [Performance](#performance)
+16. [Testing](#testing)
+17. [Deployment](#deployment)
+18. [Configuration Options Reference](#configuration-options-reference)
 
 ---
 
@@ -1853,6 +1854,12 @@ These values are passed as `METRICS_TLS_MIN_VERSION` and `METRICS_TLS_CIPHERS` e
 
 ---
 
+## Performance
+
+For heartbeat filter latency, UDP listener throughput, lock contention, memory overhead, and scalability projections at 1000-node scale, see [instanceha_heartbeat_performance.md](instanceha_heartbeat_performance.md).
+
+---
+
 ## Testing
 
 ### Test Categories

docs/instanceha_heartbeat_performance.md

@@ -120,6 +120,21 @@ nova-compute crashed (heartbeat still arriving). It acquires the
 against the timestamp map. Filter performance is unaffected by the
 protocol version since it operates on the in-memory timestamp dictionary.
 
+#### Cliff Detection Overhead
+
+Before filtering individual hosts, the function performs cliff detection:
+it counts the number of hosts with a fresh heartbeat (within
+`HEARTBEAT_TIMEOUT`) by scanning all entries in the timestamp snapshot,
+and compares this count against the previous cycle's value. If the drop
+exceeds `HEARTBEAT_CLIFF_THRESHOLD` (default 50%) and the previous count
+was ≥ 3, fencing is skipped entirely for that cycle.
+
+This adds an O(n) pass over all timestamps (where n = total nodes, not
+just down hosts). At 1000 nodes this is a single dict iteration with one
+comparison per entry — well under 100 us and negligible compared to the
+Nova API call latency. The per-host filter logic that follows is
+unchanged.
+
 ### Latency by Down-Host Count
 
 The THRESHOLD determines the maximum number of simultaneously down hosts