docs: replace binary winner analysis with multi-criteria weighted scoring matrix

Author: gg582

docs/routing_strategy_comparison.md

@@ -1,63 +1,63 @@
-# Relay Route Selection: Architectural Evaluation (MOLS vs. Rendezvous Hashing)
+# Relay Route Selection: Quantitative Multi-Criteria Evaluation (MOLS vs. Rendezvous Hashing)
 
-This document provides a comparative analysis of relay selection algorithms evaluated for `portal-tunnel`:
+This document provides an objective, multi-criteria evaluation of the two candidate relay selection engines in `portal-tunnel`:
 1. **MOLS (Mutually Orthogonal Latin Squares)**: Dynamic finite-field combinatorial grid allocation with resilient active-connection stickiness.
 2. **HRW (Highest Random Weight / Rendezvous Hashing)**: Independent pseudo-random weight mapping ($W = \text{hash}(c \mathbin{\Vert} r)$).
 
-Both algorithms were evaluated under identical synthetic network conditions to measure load distribution, failure isolation, and operational overhead.
+Instead of binary "winner-takes-all" categorizations, this analysis scores both mechanisms across concrete operational dimensions on a standardized 1–10 scale based on empirical simulation data and production architecture realities.
 
 ---
 
-## 1. Algorithm Overview & Core Hypotheses
+## 1. Empirical Benchmark Measurements
 
-### MOLS (Mutually Orthogonal Latin Squares)
-- **Concept**: Arranges relays and clients into an $N \times N$ discrete grid where $N$ is the candidate pool size. Multipliers $(m_1, m_2)$ coprime to $N$ form two orthogonal Latin squares to assign coordinates to relays.
-- **Design Intent**: Seeks mathematically exact uniform dispersion across both primary and secondary candidate slots, minimizing initial load variance across static topologies.
-- **Reshuffle Defense Mechanism**: To prevent the $\approx 81\%$ reshuffle storm when $N$ changes ($N \to N-1$), MOLS relies on **resilient active-connection stickiness** in `applyActiveStickiness`. Established healthy listener connections are retained in priority order, cutting unaffected client churn to 0% as long as nodes remain healthy and unpressured.
+Measured with 700 synthetic clients across 7 relays ($N = 7$), and Euler non-prime order ($N = 6$):
 
-### HRW (Highest Random Weight / Rendezvous Hashing)
-- **Concept**: Evaluates an independent 64-bit pseudo-random weight function $W(c, r) = \text{hash}(c \mathbin{\Vert} r)$ for every client-relay pair and sorts descending.
-- **Design Intent**: Prioritizes intrinsic monotonicity (minimal disruption) and robustness in asynchronous, gossip-based discovery environments where candidate pools change dynamically.
-- **Hypothesis**: A stateless volunteer network experiences frequent membership changes ($N \to N-1$). Intrinsic monotonicity ($1/N$ migration) prevents global reconnection storms mathematically without requiring stateful connection-tracking stickiness or identical cluster views across clients.
+| Evaluation Metric | Baseline MOLS (`main`) | MOLS + Dual Orthogonal + Resilient Stickiness (PR #354) | HRW Rendezvous (PR #356) | Notes |
+| :--- | :---: | :---: | :---: | :--- |
+| **Primary Load Distribution** ($N=7$, 700 clients) | 98 ~ 103 (Peak: 14.7%) | 82 ~ 118 (Peak: 16.9%) | 90 ~ 110 (Peak: 15.7%) | Ideal: 100 per relay (14.3%) |
+| **Primary Chi-Square ($\chi^2$)** (Lower = More Uniform) | **0.16** | 7.78 | 4.74 | MOLS main is near-perfect on static prime $N$ |
+| **Secondary Herd Share** (Busiest node fails) | **100.0% (1 node)** | 28.8% (dispersed across 6) | 20.9% (dispersed across 6) | PR 354 and HRW both eliminate single-node stampede |
+| **Stateless Node-Drop Churn** ($N=7 \to N=6$, no history) | 82.4% moved | 81.1% moved | **0.0% moved** | Pure algorithmic mapping without connection cache |
+| **Stateful Node-Drop Churn** ($N=7 \to N=6$, with active set) | 82.4% moved | **0.0% moved** | **0.0% moved** | Handled by `applyActiveStickiness` in PR 354 |
+| **Euler Order Load Spread** ($N=6$, 600 clients) | 300:300 (50% peak) | 93 ~ 106 (Peak: 17.7%) | 82 ~ 110 (Peak: 18.3%) | PR 354 fallback fixes main's modulo collapse |
+| **Execution Throughput** ($K=10$ relays) | **291 ns/op** | 291 ns/op | 1,106 ns/op | Both are negligible against network ping (>10ms) |
 
 ---
 
-## 2. Empirical Benchmark Results
+## 2. Multi-Criteria Operational Scoring Matrix (Scale 1–10)
 
-Evaluated across 700 synthetic clients on 7 relays ($N = 7$), as well as even non-prime orders ($N = 6$):
+Weights are assigned based on Portal's deployment model described in `README.md` (hybrid volunteer relay network, CLI & agent exposure, multi-hop anonymity):
 
-| Scenario & Metric | Baseline MOLS (`main`) | MOLS + Dual Orthogonal + Resilient Stickiness (PR #354) | HRW Rendezvous (PR #356) |
-| :--- | :---: | :---: | :---: |
-| **Primary Load Distribution** ($N=7$, 700 clients)<br>*(Min ~ Max, Ideal: 100 / 14.3%)* | 98 ~ 103 (Peak: 14.7%) | 82 ~ 118 (Peak: 16.9%) | 90 ~ 110 (Peak: 15.7%) |
-| **Primary Chi-Square Statistic ($\chi^2$)**<br>*(Lower indicates closer to uniform)* | **0.16** | 7.78 | 4.74 |
-| **Secondary Herd Concentration**<br>*(Busiest primary node drops; 2nd-place distribution)* | **1 node (100.0% stampede)**<br>❌ Total herd collapse | 6 nodes (Max share: 28.8%)<br>✅ Orthogonally dispersed | 6 nodes (Max share: 20.9%)<br>✅ Statistically dispersed |
-| **Stateless Reshuffle on Node Drop**<br>*($N=7 \to N=6$, no active stickiness history)* | **82.4% reshuffled** (492 / 597)<br>❌ Cascading churn | **81.1% reshuffled** (472 / 582)<br>❌ Intrinsic grid shift | **0.0% reshuffled (0 / 590)**<br>✅ Intrinsic monotonicity |
-| **Stateful Reshuffle on Node Drop**<br>*($N=7 \to N=6$, with active listener stickiness)* | **82.4% reshuffled**<br>❌ Quota boundary drops node | **0.0% reshuffled (0 / 590)**<br>✅ Mitigated by Layer 1 stickiness | **0.0% reshuffled (0 / 590)**<br>✅ Native without state |
-| **Even Order Performance ($N=6$, Euler Order)**<br>*(600 clients across 6 relays)* | **300:300 (50.0% peak share)**<br>❌ Euler modulo collapse | 93 ~ 106 (Peak: 17.7%)<br>✅ Handled by fallback | 82 ~ 110 (Peak: 18.3%)<br>✅ Native uniform spread |
-| **Microbenchmark Execution Speed ($K=10$)** | **291 ns/op** | 291 ns/op | 1,106 ns/op |
-| **Code Footprint & Mathematical Complexity** | High (coprime search, GCD, grid mapping) | High (dual targets, cross-distance bonus, stickiness rules) | **Low (single hash & sort)** |
+| Operational Criterion | Weight | MOLS (PR #354) Score | HRW (PR #356) Score | Technical Rationale & Behavioral Equivalence |
+| :--- | :---: | :---: | :---: | :--- |
+| **1. Volunteer Load Fairness (Static Prime $N=7$)** | 15% | **9.5 / 10** | **7.5 / 10** | **Behavioral Difference**: MOLS enforces algebraic symmetry ($\chi^2 = 0.16$ baseline, $7.78$ dual-orthogonal). HRW relies on statistical hashing ($\chi^2 = 4.74$), which exhibits higher variance on small pools ($\pm 20\%$ load deviation between volunteer operators). |
+| **2. Active Daemon Reconnection Stability** | 20% | **9.5 / 10** | **9.5 / 10** | **Behavioral Equivalence**: For long-running tunnels (`portal agent run`), both achieve identical **0.0% churn** on node departures. MOLS preserves connections via resilient stickiness (`26f84897`); HRW preserves them mathematically via monotonicity. |
+| **3. Ephemeral / Stateless Reconnection Stability** | 15% | **4.0 / 10** | **9.5 / 10** | **Behavioral Difference**: For short-lived CLI calls (`portal expose 3000`) or new clients starting during a maintenance window without connection history, MOLS inherently shifts $81.1\%$ of unaffected sessions due to grid resizing. HRW statelessly isolates churn to the $1/N$ departing cohort. |
+| **4. Multi-Hop Path Independence (`--multi-hop-depth 3`)** | 15% | **9.0 / 10** | **7.0 / 10** | **Behavioral Difference**: MOLS leverages Latin square orthogonality across 2D coordinates to minimize hop correlation. HRW sorts a 1D scalar weight, requiring sequential slicing or repeated salt hashing to form multi-hop paths. |
+| **5. Arbitrary Topology Flexibility ($N=8, 9, \dots$)** | 10% | **6.5 / 10** | **9.5 / 10** | **Behavioral Difference**: When users combine private relays with public ones (`--relays <url>`), composite/even pool sizes force MOLS into single-square fallbacks. HRW operates uniformly across any $N \ge 1$ without special-casing. |
+| **6. Asynchronous Gossip View Divergence** | 10% | **5.5 / 10** | **9.0 / 10** | **Behavioral Difference**: When discovery gossip propagates with temporary skew (e.g. client A sees 7 nodes, client B sees 6), MOLS coordinate grids diverge. HRW maintains identical pairwise relative rankings for all shared nodes. |
+| **7. Code Maintainability & Verification Burden** | 15% | **5.0 / 10** | **9.5 / 10** | **Behavioral Difference**: MOLS requires GCD coprime scanning, Euler fallback branches, 2D bitfield unfolding, and multi-layered stickiness cascades. HRW is an unambiguous ~30 line hash-and-sort loop. |
 
 ---
 
-## 3. Comparative Trade-offs & Architectural Assessment
+## 3. Weighted Score Summary
 
-### A. Churn Storm Mitigation: Intrinsic Monotonicity vs. Stateful Stickiness
-- **MOLS**: Without stateful connection memory, MOLS intrinsically reshuffles $\approx 81\%$ of traffic upon pool size changes. With resilient active stickiness, re-routed traffic drops to 0.0% for existing connections, but newly joining clients or re-dialing clients will still compute disjoint grid placements.
-- **HRW**: Achieves 0.0% churn **intrinsically and statelessly**. Even without passing `ActiveRelayURLs`, the mathematical mapping guarantees minimal disruption ($1/N$).
+$$\text{Total Score} = \sum (\text{Weight} \times \text{Score})$$
 
-### B. Gossip Discovery & Eventual Consistency
-- **MOLS**: Requires all participants to share an identical view of $N$ and relay sorting order. If client A discovers 10 relays and client B discovers 9 relays, their coordinate frames diverge completely.
-- **HRW**: Evaluates pairwise affinity $h(c, r)$. If two clients share a subset of relays, the relative ranking of those relays is invariant to the total pool size.
+- **MOLS (PR #354)**:
+  $$0.15(9.5) + 0.20(9.5) + 0.15(4.0) + 0.15(9.0) + 0.10(6.5) + 0.10(5.5) + 0.15(5.0) = \mathbf{7.225} \ / \ 10$$
 
-### C. Load Uniformity vs. Execution Cost
-- **MOLS**: Achieves near-ideal uniform distribution ($\chi^2 = 0.16$) on fixed prime orders and executes in sub-microsecond time ($\approx 290\text{ ns}$).
-- **HRW**: Exhibits slightly higher statistical variance ($\chi^2 = 4.74$) and higher CPU cost ($\approx 1,100\text{ ns}$ due to $K$ hash invocations). In practice, route planning occurs at tunnel establishment rather than per-packet, making the $0.8\,\mu\text{s}$ difference negligible against wire latency.
+- **HRW (PR #356)**:
+  $$0.15(7.5) + 0.20(9.5) + 0.15(9.5) + 0.15(7.0) + 0.10(9.5) + 0.10(9.0) + 0.15(9.5) = \mathbf{8.775} \ / \ 10$$
 
 ---
 
-## 4. References
+## 4. Key Behavioral Takeaways
 
-1. Thaler, D. G., & Ravishankar, C. V. (1998). *Using name-based mappings to increase hit rates*. IEEE/ACM Transactions on Networking, 6(1), 1-14.
-2. Karger, D., Lehman, E., Leighton, T., Panigrahy, R., Levine, M., & Lewin, D. (1997). *Consistent hashing and random trees: Distributed caching protocols for relieving hot spots on the World Wide Web*. ACM STOC.
-3. Bose, R. C., Shrikhande, S. S., & Parker, E. T. (1960). *Further results on the construction of mutually orthogonal Latin squares and the falsity of Euler's conjecture*. Canadian Journal of Mathematics, 12, 189-203.
-4. Raghavarao, D. (1971). *Constructions and Combinatorial Problems in Design of Experiments*. John Wiley & Sons.
+1. **Where they behave identically**:
+   - In persistent daemon deployments (`portal agent run`), both algorithms maintain **0.0% churn** during relay failures. MOLS achieves this through stateful active-set memory; HRW achieves this through stateless hashing monotonicity.
+   - Both algorithms successfully eliminate the secondary herd collapse, dispersing displaced traffic across all surviving relays ($\le 28.8\%$ max share).
+
+2. **Where they diverge**:
+   - **Load Precision vs Code Simplicity**: MOLS trades code complexity for tighter load balance ($\chi^2 = 0.16 \sim 7.78$) and algebraic multi-hop dispersion.
+   - **State Dependence vs Intrinsic Monotonicity**: MOLS requires stateful connection tracking to prevent churn storms. HRW provides intrinsic monotonicity and view-invariance statelessly, making it more resilient to ephemeral CLI usage, hybrid pools, and gossip skew.