[Epic] Evidence-qualified running performance profile and personalized pace/heart-rate zones

[jimmykane]

Summary

Build a running-specific analytical profile inspired by the RunZones example performance review.

The feature should interpret recent running evidence into personalized operational pace and heart-rate zones, a duration-sensitive performance profile, training-domain exposure, and transparent evidence quality.

This is an analysis-first epic. Version 1 remains observational and evidence-qualified rather than prescribing workouts.

Why

Quantified Self already provides strong multi-sport load, readiness, sleep, durability, historical build comparison, power profile, and CP/W′/Pmax analysis. The missing layer is deeper running interpretation:

continuous workout evidence → useful running segments → current pace/heart-rate profile → supported zones and performance ranges → clear athlete-facing conclusions

We own the sibling sports-lib repository, so the reusable parsing and modeling foundation is an owned workstream rather than an external dependency.

User outcomes

As a runner, I want to understand:

• what my recent training currently supports;
• my operational pace and heart-rate ranges for recovery, easy, steady, threshold, hard aerobic, and fast repetition work;
• how pace changes between continuous efforts and long or short repetitions;
• which performance durations are directly supported by recent evidence;
• which workouts contributed to the profile and which were excluded;
• what additional evidence would materially change the interpretation.

Version 1 experience

Add a capability-gated Running profile section to Training, after Training Mix and before Power Systems.

When sufficient evidence exists, show:

• current pace evidence based primarily on the latest rolling 28 days;
• a separately validated, bounded historical heart-rate window;
• six paired operational pace/heart-rate zones;
• duration-sensitive continuous, long-repetition, and short-repetition pace ranges;
• accepted workout observations on a pace-versus-heart-rate view;
• a supported duration-performance curve with uncertainty ranges;
• recent exposure by interpreted training domain;
• weekly distance, long-run count, qualifying workout count, and evidence coverage;
• plain-language What the evidence supports and What would change this view conclusions;
• explicit preparing, insufficient-evidence, unstable, failed, and ready states.

Missing evidence remains unavailable. It must not become zero, a population default, or an unsupported estimate.

Workstreams

1. sports-lib: compact per-workout evidence

Process speed, grade-adjusted speed, heart rate, laps, pauses, and workout structure while continuous streams are available during parsing.

Persist a bounded, versioned, fingerprinted running-performance evidence stat containing neutral observations such as:

• standard-duration speed and grade-adjusted-speed evidence;
• stable continuous segments;
• repetition and recovery groups;
• pace consistency;
• average and late-segment heart rate;
• HR drift or settling;
• context, coverage, and typed exclusion reasons.

Do not persist timelines or a second copy of continuous streams.

2. sports-lib: longitudinal running-profile fitter

Add a reusable, evidence-gated fitter following the existing CP/W′/Pmax design principles.

It should return operational zones, supported duration ranges, contributor provenance, fit quality, typed unavailability reasons, and leave-one-workout-out stability. Quantified Self owns window and refresh policy; sports-lib owns deterministic evidence interpretation and fitting.

Road, trail, treadmill, indoor, and virtual-running contexts remain explicitly separated unless a documented compatibility rule permits reuse. Other sports must never establish running pace.

3. Quantified Self: derived snapshot

Add a training_running_profile derived metric built from persisted activity evidence.

• Preserve the normal coordinator/worker lifecycle.
• Keep calculations out of Angular.
• Effective-date results and exclude future evidence.
• Do not allow a workout to influence a model used to evaluate that same workout.
• Preserve previous valid results while a new generation builds.
• Keep strict validation, redaction, MCP output-schema coverage, and negative-leakage fixtures aligned.

4. Quantified Self: Training presentation

Add responsive, accessible zone, curve, exposure, evidence-quality, and empty-state views using existing Training and ECharts patterns.

Update Training help, the public Training feature page, and docs/training-workspace.md.

5. Historical transition and validation

Release and pin the owned sports-lib change before enabling the Quantified Self feature. Use the existing idempotent sports-lib reparse pipeline to populate compact evidence for retained historical sources. Do not start a production reparse as part of implementation.

Validate representative athlete histories and known races before enabling athlete-facing performance ranges.

Acceptance criteria

• New running imports generate deterministic compact evidence without persisting continuous streams.
• Existing retained sources can gain evidence through the normal sports-lib reparse lifecycle.
• Recent running evidence establishes pace; older races cannot silently define current pace.
• Heart rate is treated as delayed context during repetitions.
• Outputs are withheld when duration coverage, data quality, fit quality, or source stability is insufficient.
• Evidence quality is explained through coverage and diagnostics rather than an opaque score.
• Contexts and activity types cannot leak into one another.
• Model-derived zones are not presented as laboratory-measured LT1/LT2.
• Training renders all result states accessibly and responsively.
• Help, Training architecture documentation, strict derived schemas, MCP contracts, and negative-leakage fixtures remain aligned.
• Focused sports-lib, Functions, frontend, reparse, MCP contract, plugin, and documentation checks pass.

Deferred from version 1

• Workout prescriptions or adaptive training plans.
• Per-session execution scores.
• Automatic best-race recipe selection.
• Race-day or on-course coaching.
• PDF report generation.
• Claims that inferred zones are physiologically measured thresholds.

These can be considered after the analytical profile has been validated against representative histories and known performances.