Wire durability into the service/agent path: MetricName + capability + persisted work_above_cp_j (follow-up to #28)

[bepcyc]

PR #28 landed the durability v1 math as a pure analytics module (analytics/durability.py: the work-above-CP fatigue axis and the work-conditioned power decrement), but neither surface is wired further:

• durability_decrement is not exposed through AnalyticsService, has no MetricName member, and has no agent capability resolver — the coach cannot retrieve or cite it, so the metric exists but cannot influence a single answer.
• work_above_cp_j finally has a definition, but the DerivedActivityMetric.work_above_cp_j column stays dormant — nothing computes-and-persists it on ingest/sync.

That leaves the product's second fitness axis invisible to the agent — the opposite of the point. Scope for the wiring slice:

1. AnalyticsService.durability(...) (athlete + activity window → MetricResult), same purity/fail-closed envelope as siblings.
2. A MetricName member + capability resolver so retrieval plans can name it and grounding can verify/cite it (metric, value, as_of like every other citation).
3. Populate work_above_cp_j in the derived-activity path so the axis is queryable per activity.
4. Metric-alias entries (plain-language names → canonical key) so a real model's wording resolves.
5. Tests per the established pattern (golden + property at the service seam; the pure-module suites already exist), and the metrics reference moves the entry from "module-level" truth to service-exposed truth.

The docs reference (#32 cascade) currently documents both honestly as computed-by-module; this issue closes the gap between "computed" and "usable by the coach."

[bepcyc]

@-

[bepcyc]

Deep-research pass: durability science + industry state of the art

A prior review note on this issue flagged that "web search [was] unavailable (quota exhausted) — domain analysis based on training data." This is the missing web-grounded pass. Code claims re-verified against current main first (all confirmed): analytics/durability.py exists and is correct, but there is no AnalyticsService.durability(), no MetricName/resolver, the DerivedActivityMetric.work_above_cp_j column (persistence/models/derived.py:97) is never populated, and there are no aliases. The wiring gap is real. Two findings change how the slice should be wired.

1. The module's design choice is more current than the common industry one — and now has a 2025 systematic review behind it

durability.py uses intensity-weighted accumulated work above CP as the fatigue axis (citing Spragg 2024), rather than raw kJ. That is the right call, and the evidence for it hardened in 2025:

• Spragg et al. 2024 (Eur J Sport Sci, 10.1002/ejsc.12077): in professional cyclists the intensity of prior work, not its quantity, drives the downward shift in the power–duration relationship.
• Sánchez-Jiménez et al. 2025, systematic review of 21 studies (Eur J Appl Physiol; PubMed, 10.1007/s00421-025-05885-0): power-output declines of 10–20% appear after only 2.5–15 kJ·kg⁻¹ of high-intensity work, whereas equal or greater volumes at lower intensity produce smaller decrements. Verbatim conclusion: "the exclusive use of kJ as a fatigue metric may be insufficient… alternative approaches incorporating intensity are needed." This is a direct endorsement of work-above-CP over kJ.

So the differentiator is not "we have durability" (see §2) — it is the intensity-weighted axis + a grounded, cited decrement. Worth stating that explicitly in docs/METRICS.md so the design choice reads as deliberate, not incidental.

2. Correction: consumer tools do now expose durability/fatigue-resistance (the "no tool exposes it" note is outdated)

The earlier (training-data-only) claim that "no popular consumer tool exposes a durability metric" no longer holds as of 2025:

• intervals.icu plots the power curve after N kJ of accumulated work (fatigued vs fresh power curve) specifically to assess fatigue resistance — feature, forum thread.
• Xert shipped a "Pro-Grade" durability/fatigue metric in April 2025 (writeup).
• WKO5 and INSCYD have long offered fatigue/durability-index features.

The honest framing for the product: the market has converged on fatigued power curves keyed to a kJ dose; wattwise's edge is the intensity-weighted axis + the fail-closed grounded citation, not novelty of the concept. The "genuine differentiator" claim should be narrowed accordingly.

3. Methodological cautions to bake into the wiring (Hunter et al. 2025 review)

The most useful source for how to wire this honestly is the methodological review Hunter et al. 2025, "Durability as an index of endurance exercise performance: Methodological considerations" (Exp Physiol; PubMed, 10.1113/EP092120). Key points that should shape the slice:

• There is no consensus assessment protocol — durability quantification is explicitly not standardized. Whatever we expose is one defensible operationalization, not a settled metric. Label it as such.
• Comparability requires controlled conditions. "If factors such as intensity and duration are not controlled, durability cannot be tracked accurately over time." It also confirms durability is confounded by carbohydrate intake, heat, altitude, cadence, position and terrain. Implication: a durability number computed from arbitrary real-world rides is a point observation, not a trend-able longitudinal metric. The citation should carry the load_model and ideally the fatigue dose/conditions, and the coach copy must not imply "your durability improved" from two uncontrolled rides.
• Inter-individual variability is enormous (decrements ranged −31% to +1% across athletes in the cited studies) — reinforces fail-closed + per-athlete framing over population norms.
• Probe duration: the literature uses 15 s / 3 / 5 / 6 / 20-min efforts; the module's 300 s default sits in range and is fine.
• CP re-estimation caution: if any path re-fits CP/W′ in the fatigued state, note the review's warning that 2-point power–duration fits give a spurious perfect fit and can inflate CP / underestimate W′. The decrement-of-best-mean-power approach the module already uses sidesteps this — keep it.

Net recommendation (no scope change to the wiring slice)

The implementation order in the prior comment is sound. Add three honesty constraints: (a) carry load_model + fatigue-dose context in the durability citation; (b) the coach's "unavailable" message should explain why (needs a long, hard, above-W′-threshold ride) and that durability from uncontrolled rides is a snapshot, not a trend; (c) document in docs/METRICS.md that the intensity-weighted axis is a deliberate, literature-backed choice and that no standardized durability protocol exists.

---

Automated deep-research pass — web + PubMed grounded; no code changed. PubMed-sourced articles are attributed with DOI links per PubMed terms.

---

Generated by Claude Code