router: train Renegade on the isotonic residual instead of a fixed 50:50 blend

[sanity]

Motivation

The router currently combines the Renegade k-NN prediction with the distance-based isotonic estimate via a fixed convex blend whose weight grows with Renegade's data count, not its accuracy:

// crates/core/src/router.rs (predict_routing_outcome)
let w = self.renegade_predictor.failure_weight(); // = events / RAMP, capped at 0.5
failure_estimate = failure_estimate * (1.0 - w) + renegade_failure.clamp(0.0, 1.0) * w;

(same shape for response time and transfer rate)

Two problems with this:

1. The weight ignores accuracy. As Renegade accumulates observations it earns up to half the vote even if it is noisier than the isotonic base for that query. The natural signal to weight by (Renegade's Brier / calibration vs the base) is now measured by the new prediction-accuracy dashboard, but the blend doesn't look at it.
2. The two models overlap. Renegade already takes distance as a feature, so it is partly re-learning the same distance→outcome signal the isotonic base already captures. A 50:50 average of two predictors of the same target is a hand-tuned ensemble, not a principled one.

Proposal: train Renegade on the isotonic residual (residual boosting)

Instead of predicting the raw outcome and blending, train Renegade to predict the delta of the base model:

• Training target = actual_outcome − isotonic_estimate(at record time).
• Final prediction = isotonic_estimate + renegade_residual_prediction.

This is gradient-boosting / stacking with the isotonic model as the strong, monotone-prior base:

• Renegade spends its capacity on the residual structure it is actually there for (peer x contract interactions distance can't see), instead of re-learning the distance signal.
• Removes the arbitrary 50:50 cap and the count-based ramp.
• Optionally shrink/gate the residual by Renegade's local confidence (neighbour count / variance) so a low-data Renegade contributes ~0 correction (what the count-ramp crudely approximates today).

Considerations / open questions

• Record-time target: compute the isotonic estimate before adding the new observation and store the residual as Renegade's output. The accuracy-tracking path already predicts-before-add, so the hook exists.
• Overlap with the isotonic per-peer EWMA delta: that already learns a peer-marginal correction. Decide whether residual-Renegade composes with it (Renegade = peer x contract residual, EWMA = peer-marginal residual) or replaces it.
• Binary failure: residual in [-1, 1]; final = clamp(isotonic + residual, 0, 1). Fine.
• Validate with the new panels: a residual-boosted Renegade should show lower Brier than both the raw-blend Renegade and the isotonic base. If it doesn't, it isn't earning its place.
• Keep a guardrail / shadow-measure before trusting the correction in live routing (avoid a routing regression).

Context

Surfaced while building the per-peer prediction-accuracy dashboard (Outcomes vs Distance + Prediction Accuracy panels). That dashboard is the instrument to evaluate this change. Routing algorithm intentionally untouched in that PR.

[AI-assisted - Claude]

[github-actions]

🤖 Auto-labeled

Applied labels:

• T-enhancement (98% confidence)
• E-hard (85% confidence)
• A-networking (95% confidence)
• S-needs-design (90% confidence)

Reasoning: This issue proposes an architectural/algorithmic improvement to the router's prediction stack (replace fixed blend with residual-boosting), which is an enhancement to existing functionality. Implementing it touches core routing code and prediction pipelines, requires careful validation and guardrails, and raises open design questions (record-time targets, composition with EWMA), so it is non-trivial (E-hard) and should be treated as a design decision (S-needs-design). The change primarily affects networking/routing logic (A-networking).

Previous labels: none

If these labels are incorrect, please update them. This helps improve the auto-labeling system.

[sanity]

Issue Priority Assessment

Generated: 2026-06-19T03:19:50.851708101+00:00
Issue hash: 63b3b11a

Value Assessment

The issue is clearly still relevant — the count-based weight ramp with a hard 50% cap is exactly as described. This is a well-reasoned algorithmic enhancement proposal, not a bug report.

Assessment:

The code is precisely as described in the issue. The blending logic at router.rs:672-675 still uses failure_weight() = events / RAMP_CONSTANT capped at 0.5, exactly the mechanism the issue critiques. The problem is real: Renegade earns voting weight as it accumulates data volume, not as it demonstrates accuracy improvement over the isotonic base. Since Renegade takes distance as a feature, it partially re-learns signal the isotonic model already captures, meaning the blend can be worse than either model alone in certain regimes.

The user impact is indirect but meaningful. Routing quality directly determines GET/subscribe success rates and latency for every Freenet user. If the blended prediction is systematically miscalibrated for peer-contract pairs where Renegade is noisy, the router directs queries toward peers that fail more often — causing the retry overhead and latency the network already struggles with. The issue is not a sudden breakage but rather a systematic quality ceiling that limits how well the router can perform as the network grows and as per-peer signal becomes more valuable.

Strategically, this aligns squarely with the project's routing improvement trajectory. The issue notes that the per-peer accuracy dashboard needed to evaluate the change was just built (and the Brier score infrastructure exists at renegade_brier_score / renegade_recent_brier_score in RouterCounters). Residual boosting is a principled approach borrowed from gradient boosting literature — it would let Renegade focus its capacity on the peer×contract interaction signal the isotonic model genuinely cannot see, eliminating the redundant distance re-learning. The proposal is well-scoped: the record-time isotonic estimate can be computed before adding the new observation (the accuracy path already does this), so the training-target change is localized.

This does not block other active work, but it is upstream of routing quality metrics, which means any future work that tries to interpret Brier scores or validate routing improvements will be working against a noisier baseline until this is addressed. The E-hard label is accurate — the change requires care around the binary failure clamping, the interaction with the existing per-peer EWMA delta (another residual layer), and validation that the residual-boosted Renegade actually reduces Brier on real traces before it touches live routing. The S-needs-design label is appropriate: the open question about whether residual-Renegade composes with or replaces the EWMA delta needs an explicit decision before implementation. This is moderately high value work — not urgent, but the kind of improvement that compounds positively over time as network size and Renegade's training data grow.

Cost Assessment

The codebase exploration gives me enough to write a thorough assessment.

Implementation Cost Assessment — Issue #4485: Train Renegade on the isotonic residual

The issue is fully actionable. The relevant code is concentrated in two files — crates/core/src/router/routing_predictor.rs (the Renegade k-NN predictor and its training loop) and crates/core/src/router/isotonic_estimator.rs (the base model and per-peer EWMA adjustment) — with the blend logic sitting in crates/core/src/router.rs's predict_routing_outcome function around line 674. None of this has been superseded; the prediction-accuracy dashboard mentioned in the issue has already landed (Brier score tracking is wired up at lines 332–344 of routing_predictor.rs), so the instrumentation the proposal depends on exists and is ready to use.

The scope is narrow but the interactions are subtle. The core change requires computing the isotonic estimate before the new observation is added (the issue notes this hook already exists in the accuracy-tracking path), storing that estimate as the residual target rather than the raw outcome, retraining the Renegade k-NN against those residuals, and replacing the count-ramped blend in predict_routing_outcome with an additive correction clamped to [0,1]. The complication is that there are actually three parallel prediction paths — failure probability, response time, and transfer rate — each with their own weight ramp (FAILURE_WEIGHT_RAMP_EVENTS = 200, TIMING_WEIGHT_RAMP_EVENTS = 100) and their own Renegade stages. All three need the same residual treatment, which multiplies the surface area. There's also the open design question the issue flags explicitly: whether residual-Renegade composes with the isotonic per-peer EWMA adjustment (alpha = 0.1, minimum 5 observations before application) or replaces it. The EWMA already learns a peer-marginal correction; if Renegade is now learning a peer×contract residual, the two are additive in theory but could double-count if the per-peer EWMA bleeds into contract-specific territory. Resolving this requires a design decision before writing code, and making the wrong call silently degrades routing quality.

There are no external dependencies. No third-party services, keys, or organizational approvals are involved — everything is pure Rust in-process ML. The risk profile is moderate: routing decisions directly affect network performance, so a buggy residual target (e.g., computing isotonic after the observation rather than before) would silently bias Renegade toward predicting zero corrections, and a misclamped residual in [-1,1] could push the final estimate outside [0,1] without the clamp at the blend site. The existing accuracy dashboard (Brier score, renegade_accuracy_pairs) is the natural regression guard, but it takes hundreds of live events to reveal a bias, making pre-deployment unit testing essential. Testing effort is meaningful: the ideal test suite exercises the predict-before-add ordering, verifies that a peer with strong residual structure (peer×contract signal not captured by distance) gets lower Brier with the residual approach than with the blend approach, and confirms the [0,1] clamp on the final composite. Simulation tests using run_simulation_direct are the right vehicle since the affected code lives squarely in the routing/topology layer, but writing good residual-signal scenarios requires care. Overall this is a medium-cost change — perhaps 2–3 days of focused work — with the design decision about EWMA composition being the primary uncertainty that could expand it.

---

Generated by issue-prioritizer