Sports Lib API - v23.12.1
    Preparing search index...

    Import activities

    Use SportsLib to import recorded activities. GPX accepts a DOM parser in Node.js, TCX accepts a parsed XML document, FIT accepts binary data, and native JSON restores a previous Sports Lib export.

    Activity types are normalized through ActivityTypesHelper.resolveActivityType() before they are stored on activities. For example, snorkeling resolves to Snorkeling; Mermaiding is a canonical diving activity when a provider supplies that sport name. A provider-specific numeric FIT mapping is added only when the FIT profile or a representative file establishes one.

    Canonical activity types also receive a stable activity group. Skating and Inline Skating belong to the dedicated Skating group, while Ice Skating remains in Winter Sports. Aerial activities retain altitude, ascent, and descent while exposing vertical speed. Motorized and Adaptive Mobility activities retain movement data but do not receive library-calculated Training Stress Score or durability evidence; a source-provided Training Stress Score remains intact.

    The 284 canonical types each belong to exactly one of 18 groups. getActivityTypesForActivityGroup() lists every member once, including the 12 intentionally unspecified types: Chores, Generic, Match, Other, Para Sport, RC Drone Flying, Route, Tactical, Transition, Unknown Sport, Video Gaming and Workout. These retain their existing Unspecified classification and metric behavior. Indoor status is a separate hint; for example, Indoor Walking belongs to Walking and remains indoor. Aliases resolve to the same canonical member rather than creating duplicate group entries.

    Meditation belongs to ActivityTypeGroups.IndoorSportsGroup alongside Yoga, Pilates, and Stretching. FIT sport=generic (0) with sub_sport=breathing (62) defaults to Meditation; an explicit Garmin Breathwork profile preserves Breathwork separately, including training/breathing (10/62) and the French profile Ex. respiration. The aliases meditation, breathing, and generic_breathing resolve to that same canonical value. This preserves the activity name in Suunto's mapping, where Meditation is Suunto App activity ID 112.

    Suunto's documented Stretching export, App activity ID 58, uses FIT training/flexibility_training (10/19). When the recording's creator manufacturer is Suunto, this pair imports as the existing ActivityTypes.Stretching in Indoor Sports. Other manufacturers and recordings without Suunto creator identity retain Flexibility Training. A Suunto accessory or product name alone does not establish that identity. The catalog, numeric metrics, units and JSON schema are unchanged. Valid nonnegative imported TSS stays exact, including zero. The legacy preserveImportedTss flag is deprecated and does not discard imported scores. Reparse retained Suunto 10/19 sources to correct older Flexibility Training classifications, then regenerate persisted event summaries and activity-type aggregates.

    The same Suunto creator guard preserves these distinct documented exports using existing canonical sports:

    Suunto sport FIT sport/sub-sport Canonical type Group
    Motorsports Driving/Generic (24/0) Motorsports Motorized
    Climbing Rock Climbing/Generic (31/0) Climbing Outdoor Adventures
    Ski touring Alpine Skiing/Backcountry (13/37) Ski Touring Winter Sports
    Crosstrainer Fitness Equipment/Elliptical (4/15) Crosstrainer Indoor Sports
    Aerobics Training/Cardio Training (10/26) Aerobics Indoor Sports
    Trekking Hiking/Generic (17/0) Trekking Outdoor Adventures
    Paragliding Hang Gliding/Generic (26/0) Paragliding Aerial Sports
    Calisthenics Fitness Equipment/Strength Training (4/20) Calisthenics Indoor Sports

    For the Generic sub-sport rows, an omitted sub-sport also establishes the broad parent, and an explicit recognized profile retains its existing refinement. Unknown sub-sport IDs do not establish these documented pairs. Specific sub-sports keep their existing classifications: Hiking/Trail remains Hiking, and Rock Climbing/Indoor Climbing remains Indoor Climbing. Other creators retain their existing sport mappings.

    Suunto's Training/Strength Training (10/20) export is shared by Gym and Kettlebell; Alpine Skiing/Downhill (13/9) is shared by Downhill skiing and Telemark skiing. An explicit Kettlebell or Telemark Skiing sport_profile_name preserves that canonical sport before the broader composite alias. Without that profile, the pairs retain Strength Training and Alpine Skiing. No workout title, filename, external metadata, or binary decoding inference is used.

    All these types already exist in the catalog. Their existing groups, TSS policies and numeric metric contracts remain in force; Motorized activities preserve valid nonnegative imported TSS for every legacy flag setting and receive no library-calculated TSS. Reparse retained Suunto sources to correct previously broader labels, then regenerate persisted summaries, activity-type aggregates and affected Training snapshots. Native JSON alone cannot recover the source sport/sub-sport or a discarded source profile.

    Padel belongs to ActivityTypeGroups.TeamRacketGroup alongside Tennis, Squash, and Racquet Ball. FIT sport=racket (64) with sub_sport=padel (85) imports as Padel; padel and racket_padel resolve to the same canonical value. Suunto documents this pair for App activity ID 75. A racket session without a recognized specific sub-sport or racket profile name imports as Racket Sport.

    FIT sport=dance (83) resolves to the existing ActivityTypes.Dancing canonical stored value Dancing in ActivityTypeGroups.IndoorSportsGroup. The explicit sport takes precedence over sub-sport or user-defined profile fallbacks. Dance and dance are aliases of Dancing, not additional canonical types. Existing Dancing JSON remains unchanged, and the DANCING and dancing aliases also restore that value.

    ActivityTypes.JumpRope has canonical stored value Jump Rope in ActivityTypeGroups.IndoorSportsGroup. Explicit FIT sport=jump_rope (84) retains this type before sub-sport or profile fallbacks. JumpRope, jumpRope, jump_rope, and JUMP_ROPE resolve to Jump Rope, including native JSON. Plain Rope and Jump do not identify it.

    ActivityTypes.Pickleball has canonical stored value Pickleball in ActivityTypeGroups.TeamRacketGroup, distinct from Racquet Ball, Padel, and Tennis. FIT sport=racket (64) with sub_sport=pickleball (84) imports as Pickleball before profile fallbacks. The composite requires the Racket parent; a generic or unrelated sport with sub-sport 84 retains its previous classification unless an explicit recognized profile establishes the activity. An explicit Pickleball sport name or recognized profile also resolves to Pickleball across providers. pickleball, PICKLEBALL, and racket_pickleball aliases restore the same canonical type from native JSON. Racket sessions with Padel, Squash, Badminton, Racquet Ball, or Table Tennis sub-sports retain their existing types.

    These identifiers appear in Garmin's official FIT profile. Sport and sub-sport IDs are separate namespaces: sport 84 means Jump Rope, while Racket's sub-sport 84 means Pickleball. The mappings apply across manufacturers without adding provider transport or workout-delivery support.

    Dancing and Jump Rope inherit Indoor Sports' existing speed metric family, movement threshold, indoor hint, and TSS selection; Pickleball inherits the corresponding Team/Racket behavior and has a false indoor hint. These catalog hints do not establish where an individual session was recorded. None has stroke-rate semantics or a durability adapter. The library adds no numeric metric or TSS formula. Usable power curves stay isolated by exact canonical type.

    Stored Generic, Unknown Sport, and Racquet Ball labels cannot recover these distinctions on their own. Reparse retained FIT 83, 84, and 64/84 sources, or restore specific source names/profiles when available, then regenerate separately persisted event summaries, activity-type aggregates, and dependent training summaries. Saved routes need no reparse.

    ActivityTypes.Rucking has canonical stored value Rucking in ActivityTypeGroups.OutdoorAdventuresGroup. FIT hiking/rucking (17/124) preserves the type separately from Hiking and Walking before profile fallbacks, across manufacturers. Explicit Rucking sport/profile names also establish it. rucking and hiking_rucking restore the same value from native JSON. A generic or unrelated parent with sub-sport 124 does not establish Rucking; a pack-weight field alone does not change Hiking or Walking into Rucking. Garmin's Rucking manual lists Rucking under Outdoor. This classification adds no pack-weight metric or weight-dependent calculation.

    ActivityTypes.SailingExpedition has canonical stored value Sailing Expedition in ActivityTypeGroups.WaterSportsGroup. FIT sailing/expedition (32/66) preserves this type separately from Sailing and Sail Racing before profile fallbacks. Explicit Sailing Expedition and Sail Expedition sport/profile names, and their camel-case/snake-case aliases, resolve to the same type, including native JSON. Standalone Expedition does not establish sailing; generic/expedition stays Generic, and hiking/expedition stays Hiking. Garmin documents Sail Expedition as a multiday sailing activity. Classification alone does not restore missing samples or alter the importer's existing duration and stream limits.

    ActivityTypes.CCRDiving has canonical stored value CCR Diving in ActivityTypeGroups.DivingGroup. FIT diving/ccr_diving (53/63) preserves this closed-circuit rebreather type before profile fallbacks, separately from Diving, Scuba Diving, Free Diving, and Pool Apnea. CCRDiving, ccrDiving, ccr_diving, diving_ccr_diving, CCR, and ccr resolve to it, including native JSON. A generic or unrelated parent with sub-sport 63 does not establish CCR Diving; sport 63 still identifies Video Gaming. Garmin's dive modes identify CCR as closed-circuit rebreather diving. These numeric identifiers appear in Garmin's official FIT profile; broad ruck and rebreather activity aliases are not added. The separately recognized Expedition profile retains its own Outdoor Adventures type, distinct from Sailing Expedition.

    All three have the existing movement threshold, a false indoor hint, and no stroke-rate conversion or durability adapter. Rucking inherits Outdoor Adventures' pace/speed and vertical-speed families and normal terrain summaries. Sailing Expedition inherits Water Sports' speed/swim-pace families and Sailing's ascent/descent derivation exclusions, while retaining raw altitude data, altitude summaries, and explicit source ascent/descent. CCR Diving inherits Diving's speed family and excludes terrain summaries (altitude, grade, ascent, and descent) on activities and laps while retaining source streams and dive data. All retain their groups' existing TSS selection. No numeric token, unit, provider transport, delivery support, or Training formula is added by the library. Usable power curves remain isolated by exact canonical type.

    Stored Hiking, Sailing, Diving, Generic, or Unknown Sport labels cannot establish the more specific activities. Reparse retained FIT 17/124, 32/66, or 53/63 sources, or restore specific source names/profiles, then regenerate separately persisted event summaries, activity-type aggregates, and dependent training summaries. Saved routes need no reparse.

    Running, walking, Enduro MTB, and Rally.

    Canonical type FIT sport/sub-sport Group
    Obstacle Racing running/obstacle (1/59) Running
    Ultra Running running/ultra (1/67) Running
    Indoor Walking walking/indoor_walking (11/27), fitness_equipment/indoor_walking (4/27) Walking
    Enduro MTB (existing type) cycling/enduro (2/123) Mountain Biking
    Rally motor_sports/rally (81/125) Motorized

    The identifiers are defined by Garmin's official FIT profile. Garmin lists Obstacle Racing and Ultra Run as running activities. These classifications do not infer ultra running from distance or trail terrain, and add no obstacle count, rest timer, or other new source fields.

    ActivityTypeGroups.WalkingGroup has serialized value walking_group and includes Walking, Indoor Walking, and Nordic Walking. Walking and Nordic Walking move from Outdoor Adventures; Hiking, Rucking, and Trekking remain there. The indoor hint is independent of the family: only Indoor Walking is marked indoor among these three types. All three retain walking pace/speed, average pace/speed, vertical-speed, and the default 0.3 m/s movement threshold; walking does not acquire running grade-adjusted calculations or a durability adapter. This group change applies to existing stored Walking and Nordic Walking values without reparsing; their canonical type strings remain unchanged.

    The FIT pairs take precedence over conflicting custom profile names, across manufacturers. Numeric IDs, numeric strings, snake-case, camel-case, and uppercase protocol names behave consistently. Explicit Obstacle Racing/Obstacle Run, Ultra Running/Ultra Run, Indoor Walking/Walk Indoor, Enduro MTB, and Rally/Rally Driving sport or profile names also resolve to their canonical values. Every declared alias hydrates through native JSON. Existing walking_indoor and walking_indoor_walking aliases now preserve Indoor Walking instead of collapsing to Walking; stored canonical Walking alone cannot establish that a historical activity was indoors.

    Sport and sub-sport namespaces remain separate: sport 59 is Grinding, sport 67 is Meditation, and sport 27 is Horseback Riding. A generic, missing, or unrelated parent with obstacle, ultra, indoor walking, enduro, or rally sub-sport alone cannot establish these types. Plain Enduro is ambiguous: Garmin's cycling Enduro activity and FIM's motorcycle Enduro describe different sports. A Cycling parent with an explicit Enduro profile establishes Enduro MTB; a generic Enduro profile or motorcycle Enduro sub-sport retains the existing broader classification. Rally requires the Motor Sports parent for its FIT sub-sport mapping.

    Obstacle Racing and Ultra Running inherit the existing running metric and TSS selection and running durability protocol, subject to its usual sample, duration, and context checks. Enduro MTB retains its existing gravity-MTB unsupported-context durability evidence and existing TSS eligibility. Indoor Walking retains ordinary TSS eligibility. Rally omits calculated power/HR/MET TSS and removes stale calculated scores while preserving valid nonnegative imported TSS for every legacy flag setting. Rally has no durability adapter. No numeric metric token, unit, formula, durability protocol, workout delivery capability, provider transport, or Training planning contract changes.

    Historical Running, Walking, Fitness Equipment, Cycling, or Motorsports labels need specific retained FIT sources or explicit names to recover the more specific activity type. After correction, regenerate separately persisted event summaries, activity-type aggregates, affected durability evidence, and Training snapshots. Saved routes need no reparse. Review exhaustive group mappings for the new Walking group before persisting corrected classifications.

    Spin, E-bike Mountain, Adventure Race, flying variants, and broad sport categories.

    Canonical type FIT sport/sub-sport Group
    Indoor Cycling (existing) cycling/spin (2/5) Cycling
    E-Mountain Biking (existing) cycling/e_bike_mountain (2/47), e_biking/e_bike_mountain (21/47) Mountain Biking
    Adventure Racing (existing) multisport/adventure_race (18/82), running/adventure_race (1/82) Performance
    Paragliding (existing) flying/fly_paraglide (20/111) Aerial Sports
    Hockey hockey (73) Team/Racket
    Winter Sport winter_sport (58) Winter Sports
    Team Sport team_sport (70) Team/Racket
    Water Sport water_sport (78) Water Sports
    Paramotoring flying/fly_paramotor (20/112) Aerial Sports
    RC Drone Flying flying/rc_drone (20/39) Unspecified

    The official FIT profile supplies the source classifications. Spinning is indoor cycling, so Spin reuses that existing type and its indoor hint. FAI identifies paramotoring as powered paragliding; RC Drone Flying records remote-controlled aircraft or drone flight. Neither flying type establishes an indoor venue. Broad Hockey preserves the source's lack of an ice/field distinction; explicit hockey/field (73/90) and hockey/ice (73/91) still resolve to Field Hockey and Ice Hockey. Winter, Team, and Water Sport do not infer a specific sport, venue, or stroke-rate semantics.

    Numeric IDs, numeric strings, normalized parser names, and explicit sport/profile aliases work across manufacturers. New native JSON aliases include Spin, cycling_spin, cycling_e_bike_mountain, AdventureRace, multisport_adventure_race, running_adventure_race, FlyParaglide, flying_fly_paraglide, WinterSport, TeamSport, WaterSport, FlyParamotor, flying_fly_paramotor, RCDrone, and flying_rc_drone. Each sport-specific sub-sport requires its documented parent; an unknown or unrelated parent does not inherit the standalone alias. Explicit FIT classifications take precedence over a conflicting user-defined profile. Suunto's bare Generic Adventure Racing classification and Hang Gliding pair remain unchanged; their pairs do not supply the more specific Adventure Race or Paraglide distinction.

    Paramotoring and RC Drone Flying omit calculated POWER, HR, pace, and MET TSS, remove stale calculated scores and methods, and preserve valid nonnegative imported TSS, including legacy scores without a method and preserveImportedTss: false. This is a type-specific policy: other Aerial Sports and Unspecified types retain their existing TSS eligibility. The other eight classifications retain their existing group calculations. Water Sport uses the Water Sports speed and swim-pace display families without implying swimming or paddling. Indoor Cycling and E-Mountain Biking retain the existing cycling durability protocol; the other eight types have no durability adapter. No numeric metric, unit, formula, durability protocol, or stored field is added.

    Correct historical broad labels only from retained specific sources or explicit aliases, then regenerate event summaries, activity-type aggregates and applicable durability evidence. Broad stored Generic, Cycling, Running or Flying values alone cannot recover missing distinctions. Saved routes need no reparse.

    Electric enduro, cycling variants, speed walking, whitewater, wingsuit, brick, and hunting with dogs.

    Canonical type FIT sport/sub-sport Group
    E-Enduro MTB cycling/e_bike_enduro (2/127) Mountain Biking
    Track Cycling cycling/track_cycling (2/13) Cycling
    Recumbent Cycling cycling/recumbent (2/10) Cycling
    Speed Walking walking/speed_walking (11/31) Walking
    Whitewater Kayaking kayaking/whitewater (41/41) Water Sports
    Whitewater Rafting rafting/whitewater (42/41) Water Sports
    Wingsuit Flying flying/wingsuit (20/40) Aerial Sports
    Brick Training multisport/brick (18/80) Performance
    Hunting with Dogs hunting/hunting_with_dogs (28/72) Outdoor Adventures

    The official FIT profile documents these parent/sub-sport combinations. Numeric IDs, numeric strings, snake-case, camel-case, and uppercase names resolve consistently across manufacturers. Explicit sport/profile names and native JSON aliases preserve each canonical type. A sub-sport without its documented parent retains its broader classification. E-Enduro is electric mountain biking; motorcycling/e_bike_enduro remains Motorcycling, and ambiguous plain Enduro still requires cycling context. Whitewater alone does not identify kayaking or rafting. Speed Walking retains the FIT name without asserting race-walking competition rules. Brick does not infer component sports or construct activities from multiple sessions.

    Indoor Track, IndoorTrack, Indoor Track Running, and their snake-case aliases preserve Indoor Track Running in Running, with its true indoor hint. Generic Indoor Running remains a separate readable type. On FIT running/track (1/4), a recognized sport_profile_name supplies that distinction; without it, the pair retains Running and does not imply an indoor venue. Existing Track Running and Track and Field profile distinctions remain supported. A specific unrelated FIT pair still takes precedence over an Indoor Track profile. Garmin documents indoor track running. Track Cycling and Recumbent Cycling are not automatically marked indoor.

    Each new type retains its parent sport's existing metric families, movement threshold, elevation policy, and TSS selection. Whitewater Kayaking uses Kayaking's stroke-rate semantics; Whitewater Rafting retains Rafting's existing cadence semantics. Track and Recumbent Cycling use the existing cycling durability protocol with its usual evidence checks. E-Enduro MTB emits unsupported-context gravity-MTB durability evidence, like Enduro MTB, while retaining ordinary TSS eligibility. The six other new types have no durability adapter. Indoor Track Running inherits the existing Indoor Running durability behavior. No numeric metric token, unit, formula, or durability protocol is added.

    Correct historical labels only where a retained source or explicit name provides the distinction, then regenerate affected event summaries, activity-type aggregates and durability evidence. Native JSON hydration can recover explicit aliases such as cycling_track_cycling, but cannot recover detail lost in a stored broad Cycling or Running value. Saved routes need no reparse.

    BMX, Indoor Skiing, ATV, Motocross, and Pool Triathlon.

    Canonical type FIT sport/sub-sport Group
    BMX cycling/bmx (2/29) Cycling
    Indoor Skiing fitness_equipment/indoor_skiing (4/25) Indoor Sports
    ATV motorcycling/atv (22/35) Motorized
    Motocross motorcycling/motocross (22/36) Motorized
    Pool Triathlon multisport/pool_triathlon (18/126) Performance

    The parent/sub-sport combinations come from Garmin's official FIT profile. Its activity list lists BMX under Cycling, XC Ski Indoor under Gym, ATV and Motocross under Motorsports, and Pool Triathlon under Multisport. Sports Lib groups Pool Triathlon with its existing Triathlon and Multisport types in Performance. Indoor Skiing returns a true indoor hint; BMX, ATV, Motocross, and Pool Triathlon return false. A pool-swimming classification does not establish that every triathlon leg is indoors.

    These explicit pairs take precedence over conflicting profile names across manufacturers. Numeric IDs, numeric strings, snake-case, camel-case, and uppercase protocol names resolve consistently. Explicit BMX/BMX Cycling, Indoor Skiing/XC Ski Indoor/Indoor Cross Country Skiing, ATV/All-Terrain Vehicle, Motocross, and Pool Triathlon sport or profile names also resolve to the new canonical types. Every declared alias hydrates and round-trips through native JSON. Bare Quad and MX are not introduced as aliases. A generic, missing, or unrelated parent with sub-sport 29, 25, 35, 36, or 126 alone retains its broader classification. For example, Driving with sub-sport ATV remains Driving. Separate sport IDs 25, 29, 35, and 36 still identify Golf, Fishing, Snowshoeing, and Snowmobiling.

    BMX inherits Cycling's existing speed/average-speed, vertical-speed, movement threshold, TSS selection, and power/heart-rate durability protocol, subject to the usual duration, sample, and context checks. Group membership does not prove that a BMX session provides suitable endurance evidence. Indoor Skiing uses its Indoor Sports group's existing speed/average-speed, default movement threshold, and TSS selection. Pool Triathlon uses Performance's existing speed/average-speed, vertical-speed, default movement threshold, and TSS selection; it does not acquire a whole-triathlon durability adapter or swimming stroke-rate calculations. ATV and Motocross inherit Motorized's calculated power/HR/MET TSS exclusion, remove stale calculated TSS, and preserve valid nonnegative imported TSS for every legacy flag setting. The four non-BMX types have no durability adapter. No numeric metric token, unit, formula, new durability protocol, workout leg, provider transport, or delivery capability is introduced.

    Historical Cycling, Fitness Equipment, Crosscountry Skiing, Motorcycling or Multisport labels cannot establish these more specific types by themselves. Correct them from specific retained FIT classifications or explicit source names, then regenerate separately persisted event summaries, activity-type aggregates and applicable durability evidence. Saved routes need no reparse.

    ActivityTypes.IndoorHandCycle has canonical stored value Indoor Hand Cycle in ActivityTypeGroups.CyclingGroup. FIT cycling/indoor_hand_cycling (2/88) preserves it before custom profile fallback. Specific Indoor Hand Cycle, IndoorHandCycling, indoor_hand_cycle, and indoor_hand_cycling names also resolve to it. This remains distinct from Hand Cycle, Indoor Cycling, and general Cycling. FIT sport 88 still identifies Canoeing.

    ActivityTypes.IndoorWheelchairPushWalk and ActivityTypes.IndoorWheelchairPushRun have stored values Indoor Wheelchair Push Walk and Indoor Wheelchair Push Run in ActivityTypeGroups.AdaptiveMobilityGroup. FIT wheelchair_push_walk/indoor_wheelchair_walk (65/86) and wheelchair_push_run/indoor_wheelchair_run (66/87) preserve the indoor variants before profile fallback. Explicit Indoor Wheelchair Push Walk/Run and indoor_wheelchair_walk/indoor_wheelchair_run names also resolve to them. A missing, generic, unrelated, or mismatched indoor sub-sport keeps the parent's existing Wheelchair Push Walk/Run classification. Suunto's creator-qualified generic/hand_cycling (0/12) still resolves to Wheel Chair, and cycling/hand_cycling (2/12) still resolves to Hand Cycle. All three new indoor types return a true indoor hint. Garmin documents distinct indoor push and handcycling activities.

    ActivityTypes.Overlanding has canonical stored value Overlanding in ActivityTypeGroups.MotorizedGroup. Garmin's activity list uses the name Overland under Motorsports. Explicit Overland/Overlanding names and FIT overland sub-sport (98) under motor_sports (81), driving (24), or motorcycling (22) resolve to it before profile fallback. These are supported protocol combinations, verified with synthetic files; they do not establish a particular device's encoding. Broad Driving, Motorcycling, and Motorsports sessions remain distinct. A generic or unrelated parent with sub-sport 98 alone does not establish Overlanding. Its indoor hint remains false.

    ActivityTypes.TruckerWorkout has canonical stored value Trucker Workout in ActivityTypeGroups.IndoorSportsGroup. FIT trucker_workout sub-sport (83) under generic (0), fitness_equipment (4), or training (10) identifies exercise during driving breaks. Explicit Trucker Workout, Trucker Workouts, and Trucker Health names also resolve to it. Garmin's workout guide describes exercise during breaks. Driving or another unrelated parent with sub-sport 83 retains its parent type; sport 83 still identifies Dancing. The Indoor Sports group provides its existing indoor presentation hint, which does not prove the actual workout location. The specific FIT identifiers come from Garmin's official FIT profile.

    Numeric IDs, numeric strings, snake-case, camel-case, and uppercase FIT names resolve consistently across manufacturers. Every declared alias for these five types hydrates to its canonical value through native JSON. Unrelated parents cannot establish an indoor adaptive or handcycling type from a sub-sport alone; explicit specific source names/profiles remain sufficient. Indoor Hand Cycle inherits Cycling's speed/average-speed and vertical-speed families, 4/3.6 movement threshold, power TSS eligibility, and existing power/heart-rate durability protocol. The other four use their existing groups' speed/average-speed families and default movement threshold, with no vertical-speed, grade-adjusted, or stroke-rate derivation. Existing raw metrics and terrain summaries remain readable. Overlanding and both indoor wheelchair types omit calculated power/HR/MET TSS and stale calculated scores while preserving valid nonnegative imported TSS for every legacy flag setting. Trucker Workout retains its group's existing TSS selection. Those four have no durability adapter. No numeric metric token, unit, formula, durability protocol, provider transport, workout delivery capability, or modeled Training family is added.

    Correcting historical Cycling, Hand Cycle, Wheelchair Push Walk/Run, Driving, Motorcycling, Motorsports, Generic, Fitness Equipment, or Training labels requires retained FIT sources with these specific pairs or explicit names; stored broad labels alone cannot establish the more specific type. Regenerate separately persisted event summaries, activity-type aggregates, durability evidence where applicable, and dependent training summaries after reparsing. Saved routes need no reparse. Power curves stay isolated by exact canonical type.

    ActivityTypes.Grinding has canonical stored value Grinding in ActivityTypeGroups.WaterSportsGroup. Explicit FIT sport grinding (59) identifies operating sailing winches and preserves this type before profile or unrelated sub-sport fallbacks. ActivityTypes.IndoorGrinding has canonical stored value Indoor Grinding in ActivityTypeGroups.IndoorSportsGroup. FIT grinding/indoor_grinding (59/71) preserves the separate indoor type before profile fallbacks. Numeric IDs, numeric strings, snake-case names, and camel-case names resolve consistently across manufacturers. A generic or unrelated parent sport with sub-sport 71 does not establish Indoor Grinding.

    ActivityTypes.SailRacing has canonical stored value Sail Racing in ActivityTypeGroups.WaterSportsGroup. FIT sailing/sail_race (32/65) preserves this type separately from Sailing before profile fallbacks. The sub-sport requires the Sailing parent; a generic or unrelated parent with sub-sport 65 does not establish Sail Racing. Ordinary sailing/generic (32/0) remains Sailing. Sport and sub-sport namespaces stay separate: sport 65 remains Wheelchair Push Walk and sport 71 remains Cricket.

    Garmin's official FIT profile defines these IDs. Garmin's grinding manual distinguishes Grind Onshore and Grind Offshore; its Sail Racing manual uses Sail Race. Those explicit sport/profile names resolve to Indoor Grinding, Grinding, and Sail Racing respectively. Offshore Sail Grinding and Onshore Sail Grinding, documented in Garmin's activity guidance, also resolve to Grinding and Indoor Grinding. Canonical names, camel-case/snake-case aliases, grinding_indoor_grinding, and sailing_sail_race restore the same values from native JSON. Broad grind, onshore, offshore, and race aliases are not added.

    Grinding and Sail Racing inherit Water Sports' speed/swim-pace families and false indoor hint. Like Sailing, they do not derive ascent or descent, but retain source altitude streams, altitude summaries, and explicit source ascent/descent. Indoor Grinding inherits Indoor Sports' speed family, true indoor hint, and existing elevation behavior. Indoor status is a catalog hint; Grind Onshore does not establish a recording's physical location. All three retain the standard movement threshold and TSS selection, including power TSS when the required inputs exist. Cadence remains cadence; there is no stroke-rate conversion or durability adapter. No numeric token, unit, provider transport, workout delivery, Training formula, or modeled family is added by the library. Usable power curves remain isolated by exact canonical activity type.

    Stored Generic, Unknown Sport, or Sailing labels cannot identify these activities on their own. Reparse retained FIT 59, 59/71, or 32/65 sources, or restore specific source names/profiles, then regenerate separately persisted event summaries, activity-type aggregates, and dependent training summaries. Saved routes need no reparse.

    ActivityTypes.PoolApnea has canonical stored value Pool Apnea in ActivityTypeGroups.DivingGroup. Explicit FIT sport pool_apnea (85) preserves this type before sub-sport and profile fallbacks across manufacturers. PoolApnea, poolApnea, and pool_apnea also restore it from native JSON. Diving-group terrain summaries (altitude, grade, ascent, and descent) are excluded on activities and laps, while source streams remain available. FIT diving/apnea_diving (53/56) and diving/apnea_hunting (53/57) still resolve to the separate Free Diving type. A broad apnea alias is not added. Pool Apnea inherits the group's existing speed behavior and false indoor hint; the hint does not establish whether the pool is indoors or outdoors.

    ActivityTypes.Mobility has canonical stored value Mobility in ActivityTypeGroups.IndoorSportsGroup. Explicit FIT sport mobility (86) preserves the type before sub-sport and profile fallbacks. Lowercase mobility restores it from native JSON. It inherits Indoor Sports' speed behavior and true indoor hint. Flexibility Training, Stretching, and Yoga remain separate; training/flexibility_training (4/19) retains Flexibility Training. Polar's finer MOBILITY_DYNAMIC and MOBILITY_STATIC source names are not collapsed into this type without a separate mapping decision.

    ActivityTypes.VideoGaming has canonical stored value Video Gaming in ActivityTypeGroups.UnspecifiedGroup. Explicit FIT sport video_gaming (63) preserves the type before sub-sport and profile fallbacks. VideoGaming, videoGaming, video_gaming, Gaming, and gaming also resolve to this type, including native JSON. Garmin calls the activity Gaming. FIT sub-sport esport (77) is shared with physical sports and does not establish Video Gaming on its own: cycling/esport (2/77) retains Cycling. Video Gaming uses Unspecified's speed behavior and false indoor hint.

    These IDs appear in Garmin's official FIT profile. Garmin's activity profiles list Pool Apnea under Diving and Mobility under Gym. Garmin's activities manual lists Gaming under Other. Sport and sub-sport IDs are separate namespaces: racket/padel (64/85) remains Padel, wheelchair_push_walk/indoor_wheelchair_walk (65/86) remains Wheelchair Push Walk, and Diving sub-sport 63 does not identify Video Gaming.

    Video Gaming receives no library-calculated POWER, HR, pace, or MET TSS even when inputs or overrides are available. Previously calculated TSS and its method are removed during summary generation. A valid nonnegative source-provided TSS remains available and is labeled IMPORTED, including when preserveImportedTss is false. A legacy score without a method retains the existing imported-score interpretation; its provenance cannot be recovered from the number alone. Pool Apnea and Mobility retain their groups' existing TSS eligibility. None of these types has stroke-rate semantics or a durability adapter. No numeric metric token, unit, schema, provider transport, delivery support, or Training formula is added. Usable power curves remain isolated by exact canonical activity type.

    Stored Generic or Unknown Sport labels cannot identify these activities. Reparse retained FIT 85, 86, or 63 sources, or restore specific source names/profiles, then regenerate separately persisted event summaries, activity-type aggregates, and dependent training summaries. Recalculation is needed to clear identified calculated Video Gaming TSS; the source-imported score policy is unchanged. Saved routes need no reparse.

    ActivityTypes.Shooting has canonical stored value Shooting, and ActivityTypes.Geocaching has canonical stored value Geocaching, both in ActivityTypeGroups.OutdoorAdventuresGroup. Explicit FIT sports shooting (56) and geocaching (87) retain these types before sub-sport and profile fallbacks, across manufacturers. Shooting remains distinct from Archery and Hunting; Geocaching remains distinct from Hiking and Walking. Lowercase shooting and geocaching aliases also restore their canonical values from native JSON.

    ActivityTypes.PlatformTennis has canonical stored value Platform Tennis in ActivityTypeGroups.TeamRacketGroup, distinct from Tennis, Padel, Pickleball, and Racquet Ball. FIT sport=racket (64) with sub_sport=platform (93) imports as Platform Tennis before profile fallbacks. These IDs appear in Garmin's official FIT profile linked above; Garmin's activity profiles use the Platform Tennis name. Standalone platform, a generic session with sub-sport 93, or a custom profile does not establish Platform Tennis. Explicit Platform Tennis, PlatformTennis, platformTennis, and platform_tennis sport/profile names do establish it across providers. Those aliases and racket_platform restore the same canonical value from native JSON. Other racket sub-sports retain their existing types.

    Shooting and Geocaching inherit Outdoor Adventures' existing movement threshold, speed/pace and vertical-speed families, terrain behavior, and TSS selection; Platform Tennis inherits the corresponding Team/Racket speed behavior without vertical-speed or grade-adjusted derivation. All three have a false indoor hint, which is a catalog grouping and does not establish where an individual session was recorded. None has stroke-rate semantics or a durability adapter. This adds no numeric metric, provider transport, workout-delivery support, Training formula, or modeled Training family in the library. Usable power curves stay isolated by exact canonical activity type.

    Stored Generic, Unknown Sport, and Racquet Ball labels cannot identify these sports on their own. Reparse retained FIT 56, 87, and 64/93 sources, or restore specific source names/profiles when available, then regenerate separately persisted event summaries, activity-type aggregates, and dependent training summaries. Saved routes need no reparse.

    ActivityTypes.DiscGolf has the canonical stored value Disc Golf in ActivityTypeGroups.TeamRacketGroup, alongside the separate Golf and Frisbee types. FIT sport=disc_golf (69) imports as Disc Golf across manufacturers, using Garmin's activity reference. The explicit sport takes precedence over sub-sport and profile fallbacks, including profiles named Golf or Frisbee. The aliases DiscGolf and disc_golf resolve to the same canonical value. Explicit Frisbee golf names also resolve to Disc Golf: Polar's detailed sport catalog uses FRISBEEGOLF, and Suunto's mapping calls App activity ID 66 Frisbee golf. Both providers document generic FIT exports for this activity; a generic sport without a specific name or recognized profile remains Generic. A supplied Frisbee golf name is sufficient, while plain Frisbee and Golf retain their own types. Disc Golf inherits Team/Racket's existing speed, movement, indoor-status, and TSS behavior; it adds no durability adapter, numeric metric, or provider transport.

    Native JSON preserves the canonical Disc Golf type and its explicit aliases. Stored Generic, Unknown Sport, Golf, or Frisbee labels cannot identify a historical Disc Golf activity on their own. Reparse retained FIT sport 69 or restore a specific source name/profile when available, then regenerate separately persisted summaries or activity-type aggregates. Saved routes need no reparse.

    ActivityTypes.Lacrosse has the canonical stored value Lacrosse in ActivityTypeGroups.TeamRacketGroup, alongside Field Hockey and Rugby. FIT sport=lacrosse (74) imports as Lacrosse across manufacturers, using Garmin's activity reference linked above. The explicit sport takes precedence over generic, Match, or Field sub-sports and user-defined profile fallbacks. The aliases lacrosse and LACROSSE resolve to the same canonical value, including native JSON. Polar's FIT mapping documents Lacrosse as Generic; a generic session needs an explicit Lacrosse sport/profile name to establish that classification. Other generic sessions, Field Hockey, Ice Hockey, and Volleyball retain their existing rules.

    Lacrosse inherits Team/Racket's speed, movement, indoor-status, and TSS behavior without adding a numeric metric, durability adapter, or provider transport. Stored Generic or Unknown Sport labels cannot identify Lacrosse on their own. Reparse retained FIT sport 74 or restore an explicit source name/profile when available, then regenerate separately persisted summaries or activity-type aggregates. Saved routes need no reparse.

    ActivityTypes.WaterTubing has the canonical stored value Water Tubing in ActivityTypeGroups.WaterSportsGroup, distinct from Water Skiing, Wakeboarding, and Rafting. FIT sport=water_tubing (76) imports as Water Tubing across manufacturers, using Garmin's activity reference linked above. The explicit sport takes precedence over sub-sport and user-defined profile fallbacks. WaterTubing and water_tubing resolve to the same canonical value, including native JSON. A generic FIT session needs an explicit Water Tubing profile; standalone Tubing and water_sport remain ambiguous and do not establish this classification.

    Water Tubing inherits Water Sports' speed/swim-pace metric family, movement threshold, and TSS selection. Like Water Skiing and Wakeboarding, it does not derive ascent or descent from altitude streams; explicit source totals and raw altitude streams remain available. It has no stroke-rate semantics or durability adapter. This adds no numeric metric, provider transport, or workout-delivery support. The library adds no TSS formula, and usable power curves remain isolated by exact canonical activity type.

    Stored Generic or Unknown Sport labels cannot identify historical Water Tubing on their own. Reparse retained FIT sport 76 or restore an explicit source name/profile when available, then regenerate separately persisted event summaries, activity-type aggregates, and dependent training summaries. Saved routes need no reparse.

    The following explicit FIT sports also preserve separate canonical activity types across manufacturers. The protocol identifiers appear in Garmin's official FIT profile.

    Public activity type Canonical stored value FIT sport Activity group
    ActivityTypes.Wakesurfing Wakesurfing wakesurfing (77) ActivityTypeGroups.WaterSportsGroup
    ActivityTypes.Archery Archery archery (79) ActivityTypeGroups.OutdoorAdventuresGroup
    ActivityTypes.MixedMartialArts Mixed Martial Arts mixed_martial_arts (80) ActivityTypeGroups.IndoorSportsGroup

    The explicit sport takes precedence over sub-sport and user-defined profile fallbacks. Wakesurfing remains distinct from Surfing and Wakeboarding, Archery from Hunting, and Mixed Martial Arts from Boxing and generic Combat. Explicit wakesurfing, archery, MixedMartialArts, mixedMartialArts, mixed_martial_arts, MMA, and mma aliases also restore their canonical types from native JSON. A generic FIT session needs a specific recognized sport profile; water_sport, plain Martial Arts, Shooting, or a custom profile does not establish one of these classifications.

    These types use their existing groups' movement thresholds, speed metric families, and TSS selection. Wakesurfing uses the Water Sports speed/swim-pace family and does not derive ascent or descent from altitude; source-provided totals and raw altitude remain available. Archery inherits Outdoor Adventures' speed/pace and vertical-speed families and retains terrain summaries. Mixed Martial Arts inherits Indoor Sports' speed family and indoor hint; that hint is a catalog classification, not evidence that a particular session was recorded indoors. All three have no stroke-rate semantics or durability adapter. No numeric metric, provider transport, or workout-delivery support is added.

    Existing Generic and Unknown Sport labels cannot identify these activities on their own. Reparse retained FIT sports 77, 79, and 80, or restore specific source names/profiles when available, then regenerate separately persisted event summaries, activity-type aggregates, and dependent training summaries. Saved routes need no reparse.

    Field Hockey belongs to ActivityTypeGroups.TeamRacketGroup, distinct from Ice Hockey. Suunto App activity ID 113 uses FIT generic/match (0/22); this pair imports as ActivityTypes.FieldHockey only when the recording's creator manufacturer is Suunto (suunto or FIT ID 23), using the same creator precedence described below for Wheel Chair. Other manufacturers and missing creator identity retain Match; generic_match remains its legacy alias. The explicit names Field Hockey, FieldHockey, and field_hockey resolve to the new canonical type across providers. Polar's detailed sport catalog also identifies Field Hockey as FIELD_HOCKEY; this named alias does not infer a Polar FIT tuple or add provider transport.

    FIT sport=hockey (73) with sub_sport=field (90) also imports as the existing ActivityTypes.FieldHockey across manufacturers. These identifiers appear in Garmin's activity reference. The composite alias hockey_field resolves to the same canonical value. Standalone hockey or field does not establish Field Hockey, and unrelated sports with the Field sub-sport retain their previous fallback behavior. This correction reuses the existing Team/Racket group and canonical stored value without adding numeric metrics. Previously stored Unknown Sport values remain unchanged when restoring native JSON; reparse retained FIT sources to recover the specific activity type and regenerate any separately persisted event summaries or activity-type aggregates.

    FIT sport=hockey (73) with sub_sport=ice (91) imports as the existing ActivityTypes.IceHockey across manufacturers, using the identifiers in Garmin's reference linked above. Ice Hockey remains in ActivityTypeGroups.TeamRacketGroup, distinct from Field Hockey and Ice Skating. The composite alias hockey_ice resolves to its existing canonical stored value. Standalone hockey or ice does not establish Ice Hockey; unrelated sports with the Ice sub-sport retain their previous fallback behavior. As with Field Hockey, restoring native JSON does not reclassify historical Unknown Sport values; reparse retained FIT sources and regenerate separately persisted summaries or activity-type aggregates to correct those imports.

    Hand Cycle remains in ActivityTypeGroups.CyclingGroup. FIT sport=cycling (2) with sub_sport=hand_cycling (12) imports as the existing ActivityTypes.Handcycle; the composite alias cycling_hand_cycling resolves to the same canonical value. Suunto documents this pair for App activity ID 109. This mapping requires the Cycling sport; its classification remains Hand Cycle regardless of the recording's manufacturer.

    Suunto's Wheelchair sport (App activity ID 108) uses FIT generic/hand_cycling (0/12) and imports as the existing ActivityTypes.Wheelchair, whose canonical stored value is Wheel Chair in ActivityTypeGroups.AdaptiveMobilityGroup. This provider-specific interpretation requires a Suunto creator manufacturer (suunto or FIT ID 23). The importer uses its existing creator identification: file_id takes precedence, with compatible creator/local device_info filling missing identity. An unrelated sensor or a Suunto-looking device name does not establish that context. Without a known Suunto creator, the pair keeps its existing fallback behavior; no global generic_hand_cycling alias is added. The classification reuses Adaptive Mobility's movement behavior, excludes calculated TSS and durability evidence, and preserves any source-reported TSS.

    FIT sport=wheelchair_push_walk (65) and sport=wheelchair_push_run (66), documented in Garmin's activity reference linked above, import as ActivityTypes.WheelchairPushWalk and ActivityTypes.WheelchairPushRun across manufacturers. Their canonical values are Wheelchair Push Walk and Wheelchair Push Run, with explicit WheelchairPushWalk, wheelchair_push_walk, WheelchairPushRun, and wheelchair_push_run aliases. Both belong to ActivityTypeGroups.AdaptiveMobilityGroup alongside the general Wheel Chair type. Garmin distinguishes pushes at walking speed from pushes at running speed in its wheelchair-mode manual. Classification uses the explicit source sport rather than inferring a mode from recorded speed. FIT sports 65 and 66 take precedence over sub-sport and profile fallbacks, including a generic sub-sport or profiles named Walking, Running, or the other wheelchair push mode. Their indoor wheelchair sub-sports (86 and 87) preserve the respective sport's canonical push mode. Both types retain Adaptive Mobility's speed display, moving-speed threshold, and indoor-status behavior. Calculated TSS and durability remain excluded while source-reported TSS is preserved. Ordinary Walking, Running, Hand Cycle, and the creator-qualified Suunto mapping keep their existing classification rules.

    Stored Unknown Sport, Generic, Walking, or general Wheel Chair labels cannot establish the specific push mode by themselves. Canonical native JSON Wheel Chair and Wheelchair remain general; JSON retaining the explicit wheelchair_push_walk or wheelchair_push_run alias restores the respective push mode. Reparse retained FIT sources to recover sports 65 and 66 from older general imports, then regenerate separately persisted summaries or activity-type aggregates. Saved routes need no reparse.

    Chores is an explicit member of ActivityTypeGroups.UnspecifiedGroup and does not establish an indoor context. Suunto App activity ID 119 uses FIT generic/exercise (0/23); the importer resolves this to ActivityTypes.Chores only with a Suunto creator manufacturer, using the same identity precedence as Wheel Chair and Field Hockey. Other manufacturers or missing creator identity retain Generic; the existing generic_exercise alias remains Generic. The explicit names Chores and chores resolve to the canonical type across providers. No standalone exercise alias is added, and Chores retains the Unspecified group's existing moving-speed and summary behavior.

    Cyclocross belongs to ActivityTypeGroups.CyclingGroup and is distinct from Mountain Biking. FIT sport=cycling (2) with sub_sport=cyclocross (11) imports as Cyclocross; cyclocross and cycling_cyclocross resolve to the same canonical value. Suunto documents this pair for App activity ID 114. The FIT mapping applies across manufacturers; ordinary cycling and mountain biking retain their existing classifications.

    Gravel Cycling belongs to ActivityTypeGroups.CyclingGroup. FIT sport=cycling (2) with sub_sport=gravel_cycling (46) imports as Gravel Cycling, matching Suunto App activity ID 99. The aliases GravelCycling, gravel_cycling, and cycling_gravel_cycling resolve to that canonical value, as does GravelRide, the sport name in Strava's SportType catalog. Consumers must supply Strava's specific sport_type value; the broader Ride activity type remains Cycling. The FIT mapping applies across manufacturers and retains the Cycling group's movement behavior. Ordinary road, track, and mixed-surface cycling keep their existing classifications.

    E-Mountain Biking belongs to ActivityTypeGroups.MountainBikingGroup and is distinct from E-Biking and Mountain Biking. FIT sport=e_biking (21) with sub_sport=e_bike_mountain (47) imports as E-Mountain Biking, matching Suunto App activity ID 106. The aliases EMountainBiking, e_mountain_biking, e_biking_e_bike_mountain, and E-MTB resolve to that canonical value, as does Strava's EMountainBikeRide sport name in the catalog linked above. The composite FIT mapping applies across manufacturers and uses the Mountain Biking group's movement behavior. Ordinary electric cycling, including FIT e_biking/e_bike_fitness (21/28) and the EBikeRide alias, remains E-Biking.

    Splitboarding belongs to ActivityTypeGroups.WinterSportsGroup alongside Snowboarding and Backcountry Skiing. FIT sport=snowboarding (14) with sub_sport=backcountry (37) imports as Splitboarding; splitboarding and snowboarding_backcountry resolve to the same canonical value. Suunto documents this pair for App activity ID 110. This composite preserves the Snowboarding context. Alpine and cross-country backcountry sessions retain their existing Backcountry Skiing classification, and ordinary snowboarding sessions remain Snowboarding.

    Ski Mountaineering belongs to ActivityTypeGroups.WinterSportsGroup and is distinct from Ski Touring and Backcountry Skiing. FIT sport=mountaineering (16) with sub_sport=backcountry (37) imports as Ski Mountaineering, matching Suunto App activity ID 116. The aliases ski_mountaineering and mountaineering_backcountry resolve to that value. These FIT composites apply across manufacturers; Suunto documents the specific pair, while other providers can encode related activities differently.

    Skate Skiing belongs to ActivityTypeGroups.WinterSportsGroup. FIT sport=cross_country_skiing (12) with sub_sport=skate_skiing (42) imports as Skate Skiing, matching Suunto App activity ID 117. The aliases SkateSkiing, skate_skiing, and cross_country_skiing_skate_skiing resolve to that canonical value. This FIT mapping applies across manufacturers and retains the Winter Sports group's movement behavior. Generic cross-country records, including Suunto's Classic skiing (12/0, App activity ID 118), default to Crosscountry Skiing; a recognized sport profile name can still identify a more specific activity. The broader NordicSki activity alias remains Nordic Skiing.

    Track and Field remains the existing ActivityTypes.TrackAndField in ActivityTypeGroups.PerformanceGroup. Suunto's activity table encodes both Track and Field (App ID 59) and Track Running (App ID 103) as FIT running/track (1/4). An explicit sport_profile_name resolving to Track and Field disambiguates that pair before the existing running_track alias. Canonical Track and Field and normalized TrackAndField, track_and_field, and TRACK-AND-FIELD profile names are recognized across manufacturers.

    Track Running belongs to ActivityTypeGroups.RunningGroup and retains the group's pace and moving-speed behavior. The explicit names Track Run, TrackRun, track_run, Track Running, TrackRunning, and track_running resolve to ActivityTypes.TrackRunning across providers. FIT running/track uses that type only when its profile explicitly identifies Track Running; a generic Running session can also use a recognized profile through the existing fallback. The pair alone or an absent/unrecognized profile retains Running. The standalone track name and running_track alias do not establish Track Running, and no numeric provider activity IDs are added. Other specific FIT sport composites retain their existing precedence over profile names. Garmin's Track Run activity is a running activity; manufacturer identity alone cannot disambiguate the shared Suunto pair. Historical Running imports can be corrected only when their retained source includes a recognized Track Running name or Track and Field profile; native JSON Running and running_track keep their existing values.

    FIT backcountry is terrain context, not a standalone sport classification. For example, Polar's FIT mappings reuse it for running, cycling, swimming, and orienteering. Where no recognized composite exists, the importer uses a recognized sport profile or the parent sport: running/backcountry, cycling/backcountry, and swimming/backcountry retain Running, Cycling, and Swimming respectively; generic/backcountry remains Generic. Missing or unknown parent sports do not establish skiing. The legacy standalone activity alias backcountry remains readable in native JSON, but FIT sub-sport fallback does not use it. The ambiguous FIT pairs cannot recover every provider's finer activity distinction.

    Existing native JSON remains readable. Stored Unknown Sport, Generic, Match, Walking, Running, Racquet Ball, Cycling, E-Biking, Mountain Biking, Crosscountry Skiing, and Backcountry Skiing activities cannot establish whether their sources were Meditation, Padel, Field Hockey, Ice Hockey, Chores, Hand Cycle, Wheel Chair, Cyclocross, Gravel Cycling, E-Mountain Biking, Splitboarding, Ski Mountaineering, Skate Skiing, Track Running, or Track and Field, or another sport incorrectly classified by the old FIT backcountry fallback. Re-import or reparse retained original FIT files or restore the specific provider sport name to correct historical classifications, then regenerate any separately persisted event summaries and activity-type aggregates. Saved routes need no reparse, and no new fields, numeric metrics, Training planning capabilities, or durability adapters are added.

    Upgrade every component that reads stored activities before persisting new canonical names. Review exhaustive catalog and provider-mapping expectations during that upgrade; classification alone does not establish provider delivery support. The Hand Cycle, Wheel Chair and explicit Track and Field corrections reuse existing canonical activity types and groups.

    npm install @sports-alliance/sports-lib @xmldom/xmldom
    

    The following source names and native-JSON aliases normalize across manufacturers:

    Imported name Canonical type Activity group
    Racket Sport / Racket Sports / racket Racket Sport (new) Team/Racket
    Para Sport Para Sport (new) Unspecified
    Ultimate Disc / Ultimate Frisbee Ultimate Disc (new) Team/Racket
    AMRAP AMRAP Indoor Sports
    EMOM EMOM Indoor Sports
    Tabata Tabata Indoor Sports
    Dynamic Apnea Dynamic Apnea Diving
    E-Bike Fitness E-Biking Cycling
    Casual Walking Walking Walking
    Bike Commute / Bike Commuting Cycling Cycling

    Space-separated, concatenated, and snake-case aliases resolve to the same values. The canonical new enum members are ActivityTypes.RacketSport, ActivityTypes.ParaSport, and ActivityTypes.UltimateDisc. Ultimate Disc remains distinct from Frisbee and Disc Golf. Broad Para Sport does not identify a particular discipline or establish Adaptive Mobility.

    Garmin's official FIT profile defines Racket sport 64, Para Sport 68, HIIT/AMRAP 62/73, HIIT/EMOM 62/74, HIIT/Tabata 62/75, E-Biking/E-Bike Fitness 21/28, Walking/Casual Walking 11/30, Cycling/Commuting 2/48, and Diving/Dynamic Apnea 53/121. These explicit pairs preserve their types before conflicting profile names. A matching parent is required; the workout-specific sub-sport alone does not relabel a Generic or unrelated activity. Dynamic Apnea is also preserved under Pool Apnea sport 85 when sub-sport 121 is recorded; unnamed Pool Apnea stays broad. Garmin describes AMRAP, EMOM, and Tabata as HIIT timer formats and dynamic apnea as a Pool Apnea mode.

    Racket sub-sports retain Pickleball (84), Padel (85), Platform Tennis (93), Squash (94), Badminton (95), Racquet Ball (96), and Table Tennis (97). With no recognized subtype, a precise Tennis or one of those racket profile names can identify the sport. A conflicting non-racket profile retains Racket Sport. A recognized specific Para Sport profile can identify its discipline; otherwise it retains Para Sport. Ultimate Disc requires an explicit Ultimate Disc or Ultimate Frisbee name/profile. Under Racket or Team Sport, sub-sport ultimate (92) plus such a profile identifies Ultimate Disc; 92 alone does not establish it. Plain Ultimate, Para, Commute, and Dynamic remain ambiguous. Existing explicit Disc Golf stays Disc Golf even with a conflicting Ultimate profile.

    Suunto's documented Badminton (36), Table tennis (40), Racquet ball (41), and Squash (42) exports all use bare Racket sport 64. Without a precise name/profile they now import as Racket Sport. A source-backed correction cannot recover their particular racket sport from that numeric pair alone. Suunto Padel (75, 64/85) remains Padel.

    These types retain their groups' metric families and ordinary TSS eligibility. HIIT formats remain indoor; Dynamic Apnea inherits Diving's terrain-summary exclusions. They add no stroke-rate conversion or durability adapter. Every sport preserves valid nonnegative imported TSS, including zero, for every legacy flag setting. Calculated scores refresh from eligible current inputs; remove an imported stat explicitly when a calculation-only result is required.

    Correct historical Generic, Racquet Ball or Diving labels only from retained source classifications or explicit names, then regenerate event summaries, activity-type aggregates and applicable durability evidence. Stored canonical Racquet Ball remains Racquet Ball; only the broad racket alias changes to Racket Sport. Saved routes need no reparse, and these mappings do not initiate a global reparse.

    Garmin's activity list uses short names that normalize to these canonical types:

    Source name Canonical type Existing activity group
    Bike Indoor Indoor Cycling Cycling
    Bike Tour / Bike Cycling Cycling
    Road Bike Road Cycling Cycling
    Gravel Bike Gravel Cycling Cycling
    MTB Mountain Biking Mountain Biking
    Climb Indoor Indoor Climbing Outdoor Adventures
    Row Indoor Indoor Rowing Indoor Sports
    XC Classic Ski Classic Crosscountry Skiing Winter Sports
    XC Skate Ski Skate Skiing Winter Sports
    Pool Swim Swimming Swimming
    eBike E-Biking Cycling
    Cardio Cardio Training Indoor Sports
    Floor Climb Floor Climbing Outdoor Adventures
    Strength Strength Training Indoor Sports
    Fish Fishing Outdoor Adventures
    Horseback Horseback Riding Outdoor Adventures
    Hunt Hunting Outdoor Adventures
    Kayak Kayaking Water Sports
    Row Rowing Water Sports

    All twenty names resolve through ActivityTypesHelper.resolveActivityType, native JSON hydration, and existing FIT sport/profile-name fallback. Lookup tolerates capitalization, spaces, hyphens, and underscores; multiword enum aliases also expose concatenated and snake-case spellings. FIT's sport_profile_name must actually contain a recognized name for profile fallback to apply. An arbitrary activity title is not that field. These aliases do not change numeric FIT parent/sub-sport rules or override an existing specific classification before profile fallback. The shared eBike alias also recognizes Polar's E_BIKE identifier without provider transport changes.

    Each alias inherits its canonical type's group, indoor hint, metric families, stroke-rate semantics, terrain behavior, calculated-TSS eligibility, and applicable durability adapter. In particular, Pool Swim, Kayak, Row, and Row Indoor use existing stroke-rate semantics. Every type retains valid nonnegative imported TSS exactly, including zero, for every legacy flag setting. The existing sport policy and available inputs determine replacement calculations for previously calculated scores.

    Correcting historical Generic classifications requires retained source names or profiles, followed by regeneration of separately persisted event summaries, activity-type aggregates and applicable durability evidence. Native JSON can recover an explicit alias but cannot identify a sport from an already collapsed Generic value. Upgrade all readers before persisting new canonical names. Saved routes need no reparse.

    Specific source names retain separate canonical activity types. The broad stored types remain readable; Sports Lib never infers a specific discipline from an already collapsed Dancing, HIIT, Mobility, Cycling, Running, or Pool Apnea value.

    Canonical type Group Earlier broad mapping
    Ballet Dancing Indoor Sports Dancing
    Ballroom Dancing Indoor Sports Dancing
    Jazz Dancing Indoor Sports Dancing
    Latin Dancing Indoor Sports Dancing
    Modern Dancing Indoor Sports Dancing
    Show Dancing Indoor Sports Dancing
    Street Dancing Indoor Sports Dancing
    Fitness Dancing Indoor Sports Dancing
    Classic Crosscountry Skiing Winter Sports Crosscountry Skiing
    Dynamic Mobility Indoor Sports Mobility
    Static Mobility Indoor Sports Mobility
    AMRAP Indoor Sports HIIT
    EMOM Indoor Sports HIIT
    Tabata Indoor Sports HIIT
    Dynamic Apnea Diving Pool Apnea
    Indoor Track Running Running Indoor Running
    Fitness Boxing Indoor Sports Boxing
    Fitness Martial Arts Indoor Sports Combat
    Road Running Running Running
    Road Cycling Cycling Cycling
    LES MILLS BARRE Indoor Sports Barre
    LES MILLS BODYATTACK Indoor Sports Cardio Training
    LES MILLS BODYBALANCE Indoor Sports Mind-Body Training
    LES MILLS BODYCOMBAT Indoor Sports Combat
    LES MILLS BODYJAM Indoor Sports Dancing
    LES MILLS BODYPUMP Indoor Sports Weight Training
    LES MILLS BODYSTEP Indoor Sports Step Training
    LES MILLS CORE Indoor Sports Core Training
    LES MILLS GRIT Athletic Indoor Sports HIIT
    LES MILLS GRIT Cardio Indoor Sports HIIT
    LES MILLS GRIT Strength Indoor Sports HIIT
    LES MILLS RPM Cycling Indoor Cycling
    LES MILLS SH'BAM Indoor Sports Dancing
    LES MILLS SPRINT Cycling Indoor Cycling
    LES MILLS TONE Indoor Sports Indoor Training
    LES MILLS THE TRIP Cycling Indoor Cycling
    Parkour Performance Generic
    Vertical Running Trail Running Trail Running
    Spearfishing Diving Diving

    Polar's explicit dance profiles preserve Ballet Dancing, Ballroom Dancing, Jazz Dancing, Latin Dancing, Modern Dancing, Show Dancing, Street Dancing and Fitness Dancing. Ambiguous short names such as Jazz, Latin and Modern still require Polar source context. Static Mobility and Dynamic Mobility remain distinct from broad Mobility and Stretching. Classic Crosscountry Skiing accepts Polar Classic XC skiing, Garmin XC Classic Ski and Suunto Classic skiing profiles; an unnamed cross-country pair remains Crosscountry Skiing because Suunto also uses that pair for Roller Skiing. Road Running and Road Cycling require a precise name or native road context; broad running/cycling records remain broad.

    Each Les Mills program has its recorded class name. LES MILLS CXWORX and LES MILLS CORE resolve to one canonical LES MILLS CORE type because the program was renamed. LES MILLS TRIP and LES MILLS THE TRIP share LES MILLS THE TRIP. Their generic counterparts such as Barre, Core Training, Dancing and Indoor Cycling remain available independently. RPM, SPRINT and THE TRIP belong to Cycling and retain an indoor hint, Indoor Cycling's trainer flag and the existing cycling durability adapter, including native JSON round-trips. Other named classes belong to Indoor Sports. No class name creates a new training formula.

    AMRAP, EMOM and Tabata remain separate Indoor Sports types, including decoded FIT 62/73, 62/74 and 62/75. Dynamic Apnea remains separate from broad Pool Apnea for 53/121 and 85/121, retains Diving terrain exclusions and adds no swimming stroke-rate semantics. Indoor Track Running belongs to Running, retains an indoor hint and the existing indoor running durability behavior, and accepts explicit track profiles on broad, track and indoor running records. Precise incompatible sub-sports such as treadmill, trail running and scuba remain ahead of conflicting profiles.

    Suunto's activity table records Parkouring as Generic, Spearfishing as Diving, and Vertical running as Running/Trail (1/3). Explicit Parkouring or Parkour profiles preserve Parkour in Performance; explicit Spearfishing profiles preserve Spearfishing in Diving, with the existing diving terrain exclusions. Vertical Running belongs to Trail Running and retains that group's metric and durability behavior. An explicit Vertical Running profile on Suunto's shared 1/3 pair preserves the distinct type. Unnamed shared exports remain Generic, Diving, or Trail Running respectively; creator identity alone cannot recover these names. Native JSON also recognizes the explicit names. Suunto App IDs 18, 101, and 115 are not FIT sport IDs and do not change the legacy Suunto JSON/SML ID tables.

    Name lookup accepts string sport names and returns null for invalid inputs. JavaScript object keys such as constructor, toString and __proto__ do not identify sports. Native JSON restores an invalid or unrecognized sport name as Unknown Sport; FIT imports retain the recorded sport when the profile name is invalid. Scuba and apnea sub-sport names preserve their specific diving classification across capitalization, spaces, hyphens and underscores, ahead of conflicting profile names.

    All distinct types preserve valid nonnegative imported TSS, including zero and legacy scores without a method, for every legacy flag setting. Calculated scores refresh only from supported current inputs. Existing power-first selection, HR calibration requirements and MET fallback remain unchanged.

    Review exhaustive sport and group mappings when adopting the new canonical values. Existing collapsed labels require a retained explicit source name or original file, followed by regeneration of event summaries, activity-type aggregates and applicable durability evidence. Installing the library does not reparse stored sources or rewrite persisted activities.

    The provider fixtures cover 146 source entries across Garmin, Polar and Strava, plus compatible export spellings. Distinct disciplines and named workouts retain their names in the 284-type catalog. These classifications use Garmin's activity list, Polar's detailed sport identifiers, and Strava's SportType values.

    Pass source context for names whose meaning depends on the provider:

    import { ActivityTypesHelper, type ActivityTypeSource } from '@sports-alliance/sports-lib';

    const source: ActivityTypeSource = 'polar';
    ActivityTypesHelper.resolveActivityType('MOTORSPORTS_ENDURO', source); // Motorcycle Enduro
    ActivityTypesHelper.resolveActivityType('Enduro', source); // Motorcycle Enduro
    ActivityTypesHelper.resolveActivityType('Enduro MTB'); // Enduro MTB
    ActivityTypesHelper.resolveActivityType('Ski', 'garmin'); // Alpine Skiing
    ActivityTypesHelper.resolveActivityType('Skiing', 'polar'); // Crosscountry Skiing

    Ambiguous bare names require source context: Ski, Skiing, Agility, Aquatics, Core, Esports, Jazz, Latin, Modern, Show, Street, Enduro, Road racing, Riding, Gravel, Ultimate, and Roller skating. Distinct API identifiers and unambiguous profile names also resolve without context. Native activity JSON obtains source context from the recorded creator.manufacturer; an arbitrary creator/device name or activity title does not establish that context. FIT obtains it from the recorded manufacturer enum/name, then uses the actual sport_profile_name field.

    Polar's FIT mapping appendix explains broad exports such as Sled hockey as Hockey, Wheelchair tennis as Tennis, MTB orienteering as Cycling/Backcountry, and Mobility as Generic/Flexibility training. A recognized Polar profile refines its documented parent/sub-sport pair; an unspecified Generic/Generic pair can use the recognized profile too. Incompatible FIT parents, including broad Cycling and Basketball, keep their classification when a known provider profile belongs to an unrelated parent. Standalone alias fallback cannot reinstate that rejected profile. Recognized profiles can still refine their compatible broad parent, such as Garmin Trail Run on Running/Generic. Existing explicit parent/profile composites, such as Cycling/Enduro, and recognized profiles on Generic recordings retain their refinement rules. Shared profile spellings retain all documented contexts; Polar Open water swimming, for example, accepts Swimming/Generic and Swimming/Backcountry. Numeric identifiers are decoded exclusively through the maintained fit-file-parser/profile API. Garmin and Strava name mappings do not claim undocumented device export codes.

    Snorkel requires the explicit recorded profile name to establish Snorkeling. A broad Garmin Diving/Generic session with that profile can resolve to Snorkeling; unnamed diving, single/multi-gas and gauge scuba, and apnea classifications retain their existing behavior. Explicit Garmin Breathwork and the documented French Ex. respiration profile resolve separately from Meditation for Generic/Breathing (0/62) and Training/Breathing (10/62). Garmin's French manual and a public Garmin recording establish that localization and Training parent. An unnamed breathing pair retains Meditation, and unrelated parents retain their existing classification. Backcountry Snowboard preserves Backcountry Snowboarding separately from the existing Splitboarding mapping. Polar Esports means Video Gaming; the FIT esport sub-sport alone retains its existing sport-dependent behavior. Polar's Road racing description identifies race cars, so its MOTORSPORTS_ROADRACING identifier shares Car Racing. Polar Trotting remains its distinct equine profile and does not infer human running or exertion.

    Polar's FIT appendix also uses display names that differ from its detailed API names. Both spellings resolve to the same approved canonical types:

    FIT profile spelling Canonical type
    (Duathlon) Cycling, (Triathlon) Cycling Cycling
    (Duathlon) Running, (Triathlon) Running Running
    (Off-road duathlon) Mountain biking, (Off-road triathlon) Mountain biking Mountain Biking
    (Off-road duathlon) Trail running, (Off-road triathlon) Trail running Trail Running
    (Off-road triathlon) Open water swimming, (Triathlon) Open water swimming Open Water Swimming
    LES MILLS CORE LES MILLS CORE
    LES MILLS THE TRIP LES MILLS THE TRIP
    Shooting sport (indoor) Indoor Shooting
    Shooting sport (outdoor) Shooting

    Les Mills documents the CXWORX-to-CORE rename. Explicit Polar CROSS_TRAINER/Cross-trainer profiles refine Training/Indoor Running (10/45) to Crosstrainer; STRETCHING/Stretching profiles refine Generic/Flexibility Training (0/19) to Stretching. Without those names, existing broad classifications remain. These refinements require Polar manufacturer identity and a compatible parent/sub-sport pair. Suunto's documented 10/19 pair preserves Stretching with Suunto creator identity as described above.

    Australian Football, Korfball, and Netball are separate canonical types in ActivityTypeGroups.TeamRacketGroup. Polar's FIT appendix lists these display names with Generic/Generic exports; no native FIT sport ID or undocumented AccessLink API identifier is assigned. An unnamed Generic recording retains Generic. Australian Football remains distinct from American Football and Soccer; Korfball and Netball remain distinct from Basketball. Explicit names also restore the same canonical types from native JSON. They retain the group's existing metric and TSS policies, a false indoor hint, ordinary cadence semantics, and no durability adapter. The catalog contains 284 canonical types.

    The compatibility fixtures contain documented names and synthetic FIT bytes. Temporary public FIT samples stay outside the repository because redistribution rights were not established. The downloaded Polar and Suunto files omit sport_profile_name, so they establish decoding and broad sport behavior; the documented profile refinements are verified synthetically. Historical broad labels require retained explicit profiles/original files to recover these distinctions, followed by the ordinary consumer summary and Training rebuild. Saved routes need no reparse.

    Provider API identifier / profile name Canonical type Activity group
    Garmin Trail Run Trail Running Trail Running
    Garmin Mixed Session Multisport Performance
    Garmin Expedition Expedition Outdoor Adventures
    Garmin Backcountry Snowboard Backcountry Snowboarding Winter Sports
    Garmin Ski Alpine Skiing Winter Sports
    Garmin Snowmobile Snowmobiling Motorized Sports
    Garmin Sail Sailing Water Sports
    Garmin Snorkel Snorkeling Diving
    Garmin SUP Stand Up Paddling Water Sports
    Garmin Soccer/Football Soccer Team/Racket Sports
    Garmin Motorcycle Motorcycling Motorized Sports
    Garmin Breathwork Breathwork Indoor Sports
    Garmin Track Me Generic Unspecified
    Polar Australian football Australian Football Team/Racket
    Polar Korfball Korfball Team/Racket
    Polar Netball Netball Team/Racket
    Polar AGILITY / Dog agility Dog Agility Outdoor Adventures
    Polar AQUATICS / Aqua fitness Aqua Fitness Water Sports
    Polar BALLET_DANCING / Ballet Ballet Dancing Indoor Sports
    Polar BALLROOM_DANCING / Ballroom Ballroom Dancing Indoor Sports
    Polar BEACH_TENNIS / Beach tennis Beach Tennis Team/Racket Sports
    Polar BEACH_VOLLEYBALL / Beach volley Beach Volleyball Team/Racket Sports
    Polar BIATHLON / Biathlon Biathlon Winter Sports
    Polar BODY_AND_MIND / Body&Mind Mind-Body Training Indoor Sports
    Polar BOOTCAMP / Bootcamp Bootcamp Indoor Sports
    Polar CALISTHENICS / Calisthenics Calisthenics Indoor Sports
    Polar CORE / Core Core Training Indoor Sports
    Polar CROSS_COUNTRY_RUNNING / Cross-country running Crosscountry Running Running
    Polar CROSS-COUNTRY_SKIING / Skiing Crosscountry Skiing Winter Sports
    Polar CURLING / Curling Curling Winter Sports
    Polar DUATHLON_CYCLING / Cycling Cycling Cycling
    Polar DUATHLON_RUNNING / Running Running Running
    Polar E_BIKE / Electric biking E-Biking Cycling
    Polar ESPORTS / Esports Video Gaming Unspecified
    Polar FINNISH_BASEBALL / Finnish baseball Finnish Baseball Team/Racket Sports
    Polar FITNESS_BOXING / Fitness boxing Fitness Boxing Indoor Sports
    Polar FITNESS_DANCING / Fitness dancing Fitness Dancing Indoor Sports
    Polar FITNESS_MARTIAL_ARTS / Fitness martial arts Fitness Martial Arts Indoor Sports
    Polar FITNESS_RACING / Fitness Racing Fitness Racing Performance
    Polar FITNESS_STEP / Step workout Step Training Indoor Sports
    Polar FREE_MULTISPORT / Multisport Multisport Performance
    Polar FUNCTIONAL_TRAINING / Functional training Functional Training Indoor Sports
    Polar FUTSAL / Futsal Futsal Team/Racket Sports
    Polar GRAVEL / Gravel cycling Gravel Cycling Cycling
    Polar GROUP_EXERCISE / Group exercise Indoor Training Indoor Sports
    Polar GYMNASTICK / Gymnastics Gymnastics Indoor Sports
    Polar HIIT / High-intensity interval training HIIT Indoor Sports
    Polar JAZZ_DANCING / Jazz Jazz Dancing Indoor Sports
    Polar JOGGING / Jogging Running Running
    Polar JUDO_MARTIAL_ARTS / Judo Judo Indoor Sports
    Polar JUMP_ROPE / Rope skipping Jump Rope Indoor Sports
    Polar KICKBIKE / Kickbiking Kickbiking Cycling
    Polar KICKBOXING_MARTIAL_ARTS / Kickboxing Kickboxing Indoor Sports
    Polar LATIN_DANCING / Latin Latin Dancing Indoor Sports
    Polar LES_MILLS_BARRE / LES MILLS BARRE LES MILLS BARRE Indoor Sports
    Polar LES_MILLS_BODYATTACK / LES MILLS BODYATTACK LES MILLS BODYATTACK Indoor Sports
    Polar LES_MILLS_BODYBALANCE / LES MILLS BODYBALANCE LES MILLS BODYBALANCE Indoor Sports
    Polar LES_MILLS_BODYCOMBAT / LES MILLS BODYCOMBAT LES MILLS BODYCOMBAT Indoor Sports
    Polar LES_MILLS_BODYJAM / LES MILLS BODYJAM LES MILLS BODYJAM Indoor Sports
    Polar LES_MILLS_BODYPUMP / LES MILLS BODYPUMP LES MILLS BODYPUMP Indoor Sports
    Polar LES_MILLS_BODYSTEP / LES MILLS BODYSTEP LES MILLS BODYSTEP Indoor Sports
    Polar LES_MILLS_CXWORKS / LES MILLS CXWORX LES MILLS CORE Indoor Sports
    Polar LES_MILLS_GRIT_ATHLETIC / LES MILLS GRIT Athletic LES MILLS GRIT Athletic Indoor Sports
    Polar LES_MILLS_GRIT_CARDIO / LES MILLS GRIT Cardio LES MILLS GRIT Cardio Indoor Sports
    Polar LES_MILLS_GRIT_STRENGTH / LES MILLS GRIT Strength LES MILLS GRIT Strength Indoor Sports
    Polar LES_MILLS_RPM / LES MILLS RPM LES MILLS RPM Cycling
    Polar LES_MILLS_SHBAM / LES MILLS SH'BAM LES MILLS SH'BAM Indoor Sports
    Polar LES_MILLS_SPRINT / LES MILLS SPRINT LES MILLS SPRINT Cycling
    Polar LES_MILLS_TONE / LES MILLS TONE LES MILLS TONE Indoor Sports
    Polar LES_MILLS_TRIP / LES MILLS TRIP LES MILLS THE TRIP Cycling
    Polar MOBILITY_DYNAMIC / Mobility (dynamic) Dynamic Mobility Indoor Sports
    Polar MOBILITY_STATIC / Mobility (static) Static Mobility Indoor Sports
    Polar MODERN_DANCING / Modern Modern Dancing Indoor Sports
    Polar MOTORSPORTS_CAR_RACING / Car racing Car Racing Motorized Sports
    Polar MOTORSPORTS_ENDURO / Enduro Motorcycle Enduro Motorized Sports
    Polar MOTORSPORTS_HARD_ENDURO / Hard Enduro Hard Enduro Motorized Sports
    Polar MOTORSPORTS_MOTOCROSS / Motocorss Motocross Motorized Sports
    Polar MOTORSPORTS_ROADRACING / Road racing Car Racing Motorized Sports
    Polar MOTORSPORTS_SNOCROSS / Snocross Snocross Motorized Sports
    Polar OBSTACLE_COURSE_RACING / Obstacle course racing Obstacle Racing Running
    Polar OFFROADDUATHLON / Off-road duathlon Offroad Duathlon Performance
    Polar OFFROADDUATHLON_CYCLING / Mountain biking Mountain Biking Mountain Biking
    Polar OFFROADDUATHLON_RUNNING / Trail running Trail Running Trail Running
    Polar OFFROADTRIATHLON / Off-road triathlon Offroad Triathlon Performance
    Polar OFFROADTRIATHLON_CYCLING / Mountain biking Mountain Biking Mountain Biking
    Polar OFFROADTRIATHLON_RUNNING / Trail running Trail Running Trail Running
    Polar OFFROADTRIATHLON_SWIMMING / Open water swimming Open Water Swimming Swimming
    Polar ORIENTEERING_MTB / Mountain bike orienteering Mountain Bike Orienteering Mountain Biking
    Polar ORIENTEERING_SKI / Ski orienteering Ski Orienteering Winter Sports
    Polar OTHER_INDOOR / Other indoor Indoor Training Indoor Sports
    Polar OTHER_OUTDOOR / Other outdoor Other Unspecified
    Polar PADEL / Padel racing Padel Team/Racket Sports
    Polar PARASPORTS_HAND_CYCLING / Handcycling Hand Cycle Cycling
    Polar PARASPORTS_SLED_HOCKEY / Sled hockey Sled Hockey Team/Racket Sports
    Polar PARASPORTS_WATER_SKIING / Adaptive water skiing Adaptive Water Skiing Water Sports
    Polar PARASPORTS_WHEELCHAIR / Wheelchair racing Wheelchair Racing Adaptive Mobility
    Polar PARASPORTS_WHEELCHAIR_BASKETBALL / Wheelchair basketball Wheelchair Basketball Team/Racket Sports
    Polar PARASPORTS_WHEELCHAIR_TENNIS / Wheelchair tennis Wheelchair Tennis Team/Racket Sports
    Polar POOL_SWIMMING / Pool swimming Swimming Swimming
    Polar RIDING / Riding Horseback Riding Outdoor Adventures
    Polar RINGETTE / Ringette Ringette Team/Racket Sports
    Polar ROAD_BIKING / Road cycling Road Cycling Cycling
    Polar ROAD_RUNNING / Road running Road Running Running
    Polar ROLLER_BLADING / Roller skating Inline Skating Skating
    Polar ROLLER_SKIING_CLASSIC / Classic roller skiing Classic Roller Skiing Performance
    Polar ROLLER_SKIING_FREESTYLE / Freestyle roller skiing Skate Roller Skiing Performance
    Polar SHOW_DANCING / Show Show Dancing Indoor Sports
    Polar SHOOTING_SPORT_INDOOR / Shooting (indoor) Indoor Shooting Indoor Sports
    Polar SHOOTING_SPORT_OUTDOOR / Shooting (outdoor) Shooting Outdoor Adventures
    Polar SKATEBOARDING / Skateboarding Skateboarding Skating
    Polar SKIERG / Ski machine Indoor Skiing Indoor Sports
    Polar SNOWSHOE_TREKKING / Snowshoe trekking Snowshoeing Winter Sports
    Polar SPINNING / Spinning Indoor Cycling Cycling
    Polar SUP Stand Up Paddling Water Sports
    Polar STAIR_WORKOUT / Stair workout Floor Climbing Outdoor Adventures
    Polar STREET_DANCING / Street Street Dancing Indoor Sports
    Polar TAEKWONDO_MARTIAL_ARTS / Taekwondo Taekwondo Indoor Sports
    Polar TRACK_AND_FIELD_RUNNING / Track&field running Track Running Running
    Polar TREADMILL_RUNNING / Treadmill running Treadmill Running
    Polar TRIATHLON_CYCLING / Cycling Cycling Cycling
    Polar TRIATHLON_RUNNING / Running Running Running
    Polar TRIATHLON_SWIMMING / Open water swimming Open Water Swimming Swimming
    Polar TROTTING / Trotting Trotting Outdoor Adventures
    Polar ULTIMATE / Ultimate Ultimate Disc Team/Racket Sports
    Polar ULTRARUNNING_RUNNING / Ultra running Ultra Running Running
    Polar VERTICALSPORTS_WALLCLIMBING / Climbing (indoor) Indoor Climbing Outdoor Adventures
    Polar VERTICALSPORTS_OUTCLIMBING / Climbing (outdoor) Rock Climbing Outdoor Adventures
    Polar WATER_EXERCISE / Water sports Water Sport Water Sports
    Polar WATER_RUNNING / Water running Water Running Water Sports
    Polar WATERSPORTS_CANOEING / Canoeing Canoeing Water Sports
    Polar WATERSPORTS_KAYAKING / Kayaking Kayaking Water Sports
    Polar WATERSPORTS_KITESURFING / Kitesurfing Kitesurfing Water Sports
    Polar WATERSPORTS_SAILING / Sailing Sailing Water Sports
    Polar WATERSPORTS_SURFING / Surfing Surfing Water Sports
    Polar WATERSPORTS_WAKEBOARDING / Wakeboarding Wakeboarding Water Sports
    Polar WATERSPORTS_WATERSKI / Water skiing Water Skiing Water Sports
    Polar WATERSPORTS_WINDSURFING / Windsurfing Windsurfing Water Sports
    Polar XC_SKIING_CLASSIC / Classic XC skiing Classic Crosscountry Skiing Winter Sports
    Polar XC_SKIING_FREESTYLE / Freestyle XC skiing Skate Skiing Winter Sports
    Strava HighIntensityIntervalTraining HIIT Indoor Sports
    Strava MountainBikeRide Mountain Biking Mountain Biking
    Strava PhysicalTherapy Physical Therapy Indoor Sports
    Strava Sail Sailing Water Sports
    Strava Skateboard Skateboarding Skating
    Strava TrailRun Trail Running Trail Running
    Strava VirtualRow Virtual Rowing Indoor Sports

    Virtual Rowing belongs to Indoor Sports and shares rowing stroke-rate and trainer semantics. Aqua Fitness, Adaptive Water Skiing, and Water Running follow the water-sport ascent/descent exclusions. New Motorized and Adaptive Mobility types share their groups' existing calculated-TSS exclusions. Every sport keeps valid nonnegative provider TSS, including zero and legacy scores without a method, for every legacy flag setting. The deprecated option does not discard imported scores. Existing calculated scores refresh from eligible current inputs. This batch adds no MET coefficients, numeric metric tokens, units, or formulas.

    Crosscountry Running inherits the running-speed durability adapter, while Kickbiking and Mountain Bike Orienteering inherit cycling-power. The other 43 types added by this provider batch have no library durability adapter. Consumers can apply their own eligibility policies independently of these library adapters.

    Reparse historical broad/Generic classifications only where the original file or explicit source identifier/profile retains enough detail. Regenerate affected event summaries, activity-type aggregates and applicable durability evidence. Saved routes need no reparse.

    New canonical names require a released library version that recognizes them in every component that reads or writes stored activities. Older library versions do not recognize the added names. Review exhaustive sport/group maps and provider export mappings before persisting corrected classifications. Historical corrections require retained source evidence; installing a new library version does not rewrite stored activities.

    Use await EventImporterSuuntoSML.getFromXML(xml, options) for Suunto SML XML files. The XML parser is loaded when this method is called. Bundlers with code splitting can keep it out of the initial browser bundle when the package is imported or JSON is restored. Handle parser-loading and parsing errors through the returned promise, using await inside try/catch. SML JSON continues to use EventImporterSuuntoSML.getFromJSONString(json, options) without loading the XML parser. This loading change preserves parsed metrics and JSON formats; existing activities need no reparse or migration.

    Recorded track points normally use GPX date-time text. For compatibility, the activity importer also accepts exactly 13 decimal digits as Unix milliseconds; it does not guess Unix seconds or other numeric units. Both forms retain their absolute instants and subsecond precision before sorting. Invalid, empty or structured point times fail with ParsingEventLibError before stream allocation instead of an array-length error. Existing duration limits still apply. Tracks without point times remain route-only inputs. Saved-route parsing is unchanged. Previously rejected files can be imported again after upgrading; already successful imports need no reparse, summary regeneration or data migration.

    The GPX creator attribute supplies the exporter name. Its version attribute is the GPX schema version, not the manufacturer or device software version; neither is inferred from the exporter name. Reparse original GPX to correct manufacturer values persisted by older importers.

    Heart-rate observations include direct heartrate, Garmin track-point extensions and direct ClueTrust GPXDATA hr elements in http://www.cluetrust.com/XML/GPXDATA/1/0, as used by COROS. The namespace URI establishes this alias; an arbitrary XML prefix or unrelated hr element does not. Original-file reparsing recovers previously missed samples and related summaries. HR observations alone do not provide the calibration required for HR TSS.

    Recorded trkpt/extensions/TrackPointExtension/speed uses canonical Speed in m/s when the block and field belong to Garmin's http://www.garmin.com/xmlschemas/TrackPointExtension/v2 namespace. The v1 schema never defined speed; compatibility is limited to the evidenced Amazfit/Zepp (Amazfit creator prefix or Zepp App), Intervals.icu, and explicitly allowlisted legacy exports identified by their direct GPX metadata link. An unknown v1 exporter does not inherit a unit assumption. Prefix spelling is irrelevant; namespace and direct ownership are required. One extension, one recognized block and one finite nonnegative scalar speed are required. Zero is retained; blank, non-finite, negative, nested, attributed or duplicate/conflicting fallback values are ignored (namespace declarations are allowed). Existing direct extensions/speed retains precedence and behavior.

    Recovery supplies the existing Speed stream, without adding a metric or blending missing samples with GPS speed. When no usable speed stream exists, the established distance/GPS fallback remains. Speed-dependent pace, moving time, work and durability summaries can change; recorded distance and timer duration remain independent. Pace-based TSS still requires eligible calibration, and no calibration is inferred from these readings. Selective stream parsing and canonical JSON names/units remain unchanged. Reparse original GPX files and refresh dependent summaries to recover previously ignored observations; regenerating saved JSON cannot restore discarded source values. New GPX exports use v2 and retain recorded zero speeds. Old exports that omitted zeros cannot recover those readings without an independent original containing them. Saved-route parsing is unchanged.

    import { SportsLib } from '@sports-alliance/sports-lib';
    import { DOMParser } from '@xmldom/xmldom';

    const event = await SportsLib.importFromGPX(gpxText, DOMParser);
    const activity = event.getFirstActivity();

    const distanceMetres = activity.getDistance().getValue();
    const heartRate = activity.getStreamData('Heart Rate');
    import { SportsLib } from '@sports-alliance/sports-lib';
    import { DOMParser } from '@xmldom/xmldom';

    const tcxDocument = new DOMParser().parseFromString(tcxText, 'application/xml');
    const tcxEvent = await SportsLib.importFromTCX(tcxDocument);

    const fitEvent = await SportsLib.importFromFit(fitArrayBuffer);

    TCX sport values use the canonical activity-type resolver. Unrecognized, missing or blank sports become Unknown Sport; recognized Running/Biking values retain existing indoor detection when GPS is absent. Reparse original TCX to correct previously missing sport classifications, then refresh consuming summaries.

    TCX also recovers recorded speed when a trackpoint directly contains a single TPX in the http://www.garmin.com/xmlschemas/ActivityExtension/v2 namespace but omits the Extensions wrapper. Its directly owned Speed must be a finite, nonnegative number; zero is retained, and ambiguous or invalid values stay missing. Normal wrapped extensions retain precedence. This compatibility path applies only to speed, using the existing canonical Speed (m/s), derived Pace, and summary calculations; it does not recover unwrapped power or cadence or supply missing TSS calibration. Canonical names, units, and native JSON schemas are unchanged. Previously omitted observations require reparsing the original TCX and refreshing consuming summaries; restoring saved activity JSON cannot recover them.

    Compatibility scalars must contain only numeric text and optional XML namespace declarations. Attributes such as unit="km/h" cannot silently become m/s, and competing TPX or Speed elements in other namespaces prevent unwrapped recovery. Existing standard wrapped-field handling is unchanged.

    Two further TCX layouts are supported with standard fields retaining precedence:

    • Activities whose single, directly owned Creator/Name is COROS Wearables can supply speed through Trackpoint/Extensions/Speed, with all three elements in the TCX v2 namespace. This exporter records km/h, so the importer divides by 3.6 before creating canonical Speed/Pace streams or calculating lap speed summaries and moving time. Standard TPX speed remains in m/s, including in COROS activities. This conversion is scoped to the recognized layout and creator; it never guesses units from sample magnitudes. Unknown creators and ambiguous containers remain unsupported. The exporter convention is also described in GPS Wizard's TCX format analysis.
    • A single Trackpoint/Position/AltitudeMeters, with all three elements in the TCX v2 namespace, supplies missing standard altitude in metres. Negative elevations and zero are valid. Existing altitude processing (gap filling, optional smoothing, terrain metrics and summaries) applies identically to standard altitude.

    Both fallback paths reject blank, non-finite, nested-value, attributed and duplicate/conflicting candidates (XML namespace declarations are allowed). An existing standard container/field keeps its precedence even if empty or malformed. Recorded duration, timestamps and distance remain independent; recovered speed can change moving time and speed summaries, and recovered altitude can change terrain-derived metrics. No TSS calibration is invented. Canonical metric tokens, units and JSON schemas remain unchanged. Reparse original TCX files and refresh dependent summaries to recover historical omissions; no token migration is required.

    Trackpoint/Extensions/TPX/Cadence is not treated as an alias for standard Cadence/RunCadence. Its exporter convention may count both feet rather than complete cycles; units must be established before adding a conversion. Standard trackpoint Cadence and TPX RunCadence retain their existing behavior, including activity-aware Stroke Rate. Recorded lap cadence is read only from a single, finite, nonnegative Cadence directly owned by that lap, in the lap's TCX namespace (including existing v1 and unnamespaced legacy documents). Trackpoint values cannot supply that field, even when they appear before the recorded lap value. This also prevents unsupported TPX/Cadence from entering through the lap-summary path. Existing stream-derived averages and explicit LX AvgRunCadence remain unchanged. The existing lap-stat token is retained; reparse the original TCX to remove historical false lap values. See #156.

    importFromFit accepts recorded activity files and completed activity_summary files with explicit sessions. Summary files can retain session values without record streams, as in Wahoo exports, but cannot synthesize missing sessions. Explicit non-activity file_id.type values, including monitoring, settings, planned workouts and courses, reject with ParsingEventLibError, including conflicting file IDs. Missing file IDs or type fields still permit legacy activity/sessionless recovery. Use importRoutesFromFit for courses; this does not change route parsing. Existing wrongly imported monitoring files fail original-file reparsing instead of producing replacement workouts; consumers must retain or separately review their existing stored data rather than automatically delete it.

    FIT combines complementary records at the same absolute timestamp before padding missing sensor fields. Later explicit values retain precedence; an absent field does not erase another record's observation. Pool swims with recorded HR retain explicit zero/invalid readings as dropout boundaries through load recalculation.

    FIT sessions retain credible explicit start/end timestamps when elapsed and timer summaries are absent or zero. Missing summaries alone do not replace a leg's bounds with the whole recording. Corrupt-date recovery uses the session's own records, including records across its laps; whole-file records are a fallback only for a sole session. An unresolved multisport leg is rejected rather than assigned another leg's record range. Elapsed statistics use the resolved dates, and explicit timer events can still recover paused time within each leg. The configured maximum activity duration remains enforced. Existing affected activities require an original-file reparse and a refresh of derived summaries; restoring their saved JSON cannot reconstruct the missing session boundaries. This correction adds no metrics or fields and preserves canonical names, units, imported TSS and public JSON schemas.

    A missing final FIT session can be recovered as the existing Unknown Sport type when the activity message declares exactly one more session than the file contains. The recorded prefix must have contiguous, ordered bounds and either no session indexes or consecutive zero-based indexes. The final activity timestamp, last record and closing timer event must agree. One ordered timer timeline must corroborate every existing session's active duration within the existing one-second timestamp tolerance; the tail's active time excludes its recorded pauses. A nondecreasing distance counter at both tail boundaries supplies the distance delta. Conflicting readings at the same timestamp reject recovery.

    This recovery preserves earlier legs, including their closing samples, summaries and calibration context. Only records strictly after the last recorded session are added to the new leg. Trailing laps or pool lengths, ambiguous bounds, explicit sport messages, conflicting timer groups, multiple missing sessions and duration-limit violations are left unchanged for separate investigation. It does not guess a sport, redistribute laps, copy earlier calories or infer calibration. Existing summary generation uses the recovered streams; TSS stays unavailable unless independently eligible inputs exist. Generic remains a separate intentional sport type. Sport-only activity_metrics cannot establish ownership for this unknown leg, so they do not supply its VO₂ max, training effect or recovery time. A user_metrics observation is eligible only when exactly one row has an explicit start_of_activity equal to the recovered leg's start. Missing, earlier or competing starts do not fall back to the first row. Earlier recorded legs retain their existing metrics. A workout therefore cannot promote an earlier recovery estimate as if the recovered final leg had supplied it. Existing affected imports need original-file reparse; saved JSON alone cannot establish which leg owned an incorrectly copied observation. Incomplete files containing jumps also remain unchanged: existing jump association can extend beyond a recorded leg, so appending a tail without resolving that ownership could duplicate events and skew workout jump averages.

    Consumers must reparse the original file to recover a missing leg, keep the existing event identity and reconcile child identities and user controls before persistence. Repeated reparses must reuse the recovered leg instead of adding another copy. Preserve manual overrides and exclusions on their original legs, then refresh affected derived summaries. Existing stored activities remain unchanged until reparse. Route import behavior is unaffected.

    A sole explicit FIT session can also retain chronology omitted by an inconsistent elapsed summary. If the activity message supplies a session count, it must be exactly one: a decoded list with one session does not establish whole-workout ownership when the source declares missing sessions or an invalid count. Multiple activity summaries also prevent this recovery; the decoder's final summary must not hide earlier conflicting ownership. Missing legacy counts retain existing behavior. This guard applies to pause, delayed-save, premature-end and terminal-timestamp recovery, and to whole-workout pool timing rejection below. It does not change the separate evidence required for recovering a missing final session. The pause-only proof requires ordered records from the source start through the final stop (the final sample may precede that stop by one whole-second tick), a complete alternating timer timeline in one event group, and records at distinct times within every active interval. The summed intervals must agree with the positive source timer summary. Its precision tolerance is one second per closed interval plus one millisecond: FIT event timestamps encode whole seconds and timer summaries encode milliseconds. It does not grow with workout duration.

    A separate delayed-save proof can use the last recorded exercise stop rather than a later save timestamp. It additionally requires a complete monotonic distance counter ending at the source session distance, records supporting every active interval, and the same active-time agreement. Repeated stop_all events while already stopped do not add active time or extend the exercise end. Records during a stop must retain the preceding distance. The explicit source start remains unchanged; a one-tick difference in the initial timer timestamp does not move it. Missing starts, unclosed intervals, conflicting groups, advancing distance during a stop, inconsistent timer sums and unrecorded final stops reject this proof.

    Explicit zero-distance sessions can use this delayed-save proof when the activity message also declares exactly one session and every in-session distance record is present and zero. At least two closed timer intervals must each have distinct supporting records, with the final record exactly at the final exercise stop. For this zero-distance case, the active-time discrepancy must be strictly less than one second per closed interval, reflecting timestamp quantization rather than a percentage of workout duration. Missing distance is not treated as zero. This does not relax multisport ownership, duration limits or existing positive-distance checks, and never substitutes elapsed time for active time in training-load calculations.

    An early ending timestamp that agrees with active time can instead be repaired from the independently supplied elapsed duration when a single start/stop envelope agrees with that elapsed duration and a complete, ordered distance counter reaches the session distance after the premature end. Those envelope events do not redefine active time. Both proofs require a sole explicit session, preserve the configured duration limit and leave unsupported files on the existing recovery path. Elapsed time and Pause Time reflect the corroborated chronology, while Duration and Timer time retain the supplied active time; long pauses do not become training load.

    For malformed multisport ending timestamps, a valid explicit leg start can be retained with its own elapsed duration only when its earliest cascaded record belongs to an independently bounded, disjoint earlier session, and the repaired end contains every later cascaded record. This prevents a contaminated cascade from moving the later leg to the workout's start. Conflicting ownership, insufficient duration evidence and ordinary single-session date recovery retain their existing behavior.

    FIT lap bounds also retain an independently corroborated source end when the decoder's cascaded lap records extend into later workout data. This requires a unique source lap start, a positive start/end span consistent with the millisecond elapsed summary at FIT's whole-second timestamp precision, one containing explicit source session, and containment within the resolved activity. A supplied timer must be finite and nonnegative. If it exceeds elapsed, it must also agree with the source span at whole-second timestamp precision; contradictory summaries retain the existing timing-recovery path rather than corroborating an end before normalization. Uncorroborated or ambiguous lap timestamps retain the existing recovery behavior. This changes the lap's time window, not its supplied duration, distance or activity samples.

    A fractional elapsed summary can also clip a terminal whole-second record. The importer retains that record only when a complete, alternating timer timeline from the same event group and ordered records independently establish the stop at that next timestamp tick. Each timer interval must have distinct supporting records, and the timer sum must agree with the source active duration within FIT timestamp precision. Only elapsed chronology advances; the supplied active duration remains unchanged. Unsupported terminal records, zero-length timer intervals and contradictory timelines do not gain this recovery.

    Existing affected imports need original-file reparsing and derived-summary refreshes; saved JSON cannot reconstruct omitted samples. Imported TSS remains authoritative. Calculated metrics can change when valid recorded samples are restored. These corrections add no metric tokens, units, options, exports or serialized fields, and do not change route parsing.

    Pool length end dates use credible ending timestamps, retaining fractional elapsed precision when it agrees with the FIT timestamp's whole-second resolution. Positive elapsed duration, then positive timer duration, can recover a missing or invalid end. Resolved activity and owning-lap ends bound each length. Generated samples additionally retain the existing active-timer limit, so a longer elapsed interval does not invent HR exposure during a pause, and a contradictory long timer cannot extend samples into another leg. Explicit indexed lengths crossing a lap's start keep their ownership only when their sampling interval overlaps that lap. Recorded HR and single-lap counters retain their existing precedence. Reparse original FIT files and refresh derived summaries to correct historical swim bounds; the source timer/elapsed stats, imported TSS, metric names, units and JSON shape are retained.

    Some pool exports give consecutive lengths the same later summary timestamp. Elapsed time supplies an earlier endpoint only when the next length's explicitly recorded start corroborates it at FIT's whole-second precision, both message indexes are unique and consecutive, and both lengths already belong to one explicit lap range. The elapsed interval must fit inside that lap and session, with a nonnegative timer no longer than elapsed time. This does not guess an endpoint for a terminal length, change ownership, or rewrite source timer/elapsed statistics.

    A complete generated pool-distance counter also requires complete source evidence. When a non-overlapping explicit lap range contains every declared active/rest length and agrees with its active count, an active member omitted from the session proves that the retained lengths cannot establish a complete counter. The importer disables that length-derived counter and retains recorded distance samples when available. Recorded totals and individual length distances remain intact. It does not redistribute missing distance, invent lengths, or extend the session. Missing or contradictory range/count evidence does not activate this additional guard. These checks apply only to swimming with a lap-swimming sub-sport or positive pool length. Ambiguous timestamps and durations without independent contradictory evidence remain unresolved. Historical corrections require original-file reparse after adopting a release containing the fix; JSON restoration alone cannot supply the omitted evidence. Recorded pace, SWOLF and TSS inputs, pool units and public schemas are unchanged.

    On events, activities and laps, getDuration(), getTimer(), getMovingTime() and getPause() return their corresponding Data object or undefined. The TypeScript declarations now match this existing runtime behavior. A missing statistic does not make parsing fail. Guard the getter before reading or formatting its value:

    import type { ActivityInterface } from '@sports-alliance/sports-lib';

    function displayDuration(activity: ActivityInterface): string {
    const duration = activity.getDuration();
    return duration === undefined ? 'Unavailable' : duration.getDisplayValue();
    }

    Use activity.getDuration()?.getValue() when a calculation accepts number | undefined. A recorded zero remains a valid value; do not test seconds by truthiness or replace missing time with 0, elapsed time or date differences. For a total that requires every leg's duration, leave it unavailable when a contributing leg has no usable duration. Normal measured durations keep the same values and formatting. With strictNullChecks, unguarded access now produces a compile-time error, so consumers must fix those call sites when upgrading. Native JSON still omits absent stats; no persisted-data migration or source reparse is needed solely for this typing correction.

    Swim-length fields use a separate representation: missing timerTime/elapsedTime are null, and resolveSwimTimingSeconds() returns number | null. The timing-validity rules below still apply.

    Keep a known-invalid swimming duration unavailable; do not replace it with elapsed time. Active time measures swimming, while elapsed time can include rests. A missing timer and a timer proved wrong by the source are different cases.

    For a synthetic example, suppose a length reports 7,200 seconds of active time in a workout independently established to last 1,800 seconds. Its active time is impossible. A separate, valid 45-second elapsed value still cannot tell us how much of that interval was spent swimming. The importer leaves the length's timer unavailable and retains the rejected 7,200-second value in timingValidity for diagnostics. It keeps the length, distance, strokes and rest classification. These example numbers are not rejection thresholds.

    For one explicitly identified pool-swim session, the importer can withhold a length or lap timer/elapsed duration that exceeds an independently supported whole-workout envelope. This requires ordered timer events from the session start to a recorded stop and timestamped samples within that envelope. All summary timestamps widen the bound; valid child length totals can additionally support a lap duration. The one-second allowance follows FIT timestamp resolution. There is no fixed duration limit and timer > elapsed alone is not a rejection rule. Multisession files, incomplete timer evidence and later recorded samples are deferred, preserving valid multisport laps and long rests.

    Affected lengths and laps retain their identity, distance, strokes and rest classification. Each contradicted field is omitted from usable timing; an independent valid elapsed field remains available. The additive native-JSON timingValidity field has version: 1, reason exceeds-workout-envelope, and the rejected timerTime and/or elapsedTime source value. normalizeTimingValidity reads this allowlist and resolveSwimTimingSeconds returns usable active time or null; rejected timer time must never fall back to elapsed time. Bounded start/end dates describe containment and must not be used to reconstruct rejected measured time. Legacy JSON without the field keeps its existing interpretation.

    No synthetic readings are generated from an affected length, and an affected active length cannot establish a complete generated distance counter. Recorded sensor samples and authoritative workout totals remain available. Moving time may instead be regenerated from valid recorded samples. Active lengths with rejected timing make pool durability unavailable (missing-output, zero qualifying coverage) rather than improving coverage by dropping the affected rows. Original-file reparse is required to classify historical data; native JSON preserves a classification once present. This change adds no numeric metric names, changes no route parsing, and does not infer replacement durations.

    Sports Lib already applies this rule to its generated swim samples and pool durability analysis. Applications that calculate or display swim timing themselves should use the exported resolver for each swim length:

    import { resolveSwimTimingSeconds, type SwimLengthInterface } from '@sports-alliance/sports-lib';

    function displayLengthTiming(length: SwimLengthInterface): string {
    const seconds = resolveSwimTimingSeconds(length);
    return seconds === null ? 'Unavailable' : `${seconds} s`;
    }

    The resolver distinguishes these cases:

    Length timer Elapsed time Result
    Valid 30 seconds 45 seconds 30 seconds
    Missing, with no rejected-timer marker Valid 45 seconds 45 seconds, retaining the existing fallback
    Rejected by timingValidity.timerTime Valid 45 seconds null (unavailable)
    Valid zero 45 seconds 0 seconds

    The legacy elapsed fallback does not independently prove active swimming time. Do not add another fallback after the resolver returns null: replacing it with elapsed time, endDate - startDate or zero would erase the distinction between rejected, missing and measured timing. Keep the row and show its usable measurements; calculations requiring the rejected duration must remain unavailable rather than silently omit that row or invent a replacement duration. For laps, the importer withholds the affected timing stats; custom lap calculations must likewise honor the marker instead of rebuilding those stats from dates or other duration fields.

    When persisting through Sports Lib's native JSON APIs, the marker is retained automatically. Applications with their own serializers must preserve it on laps and swim lengths so later reads do not revive a rejected duration. Treat the values inside the marker as rejected source evidence, never usable timing. Older JSON without a marker keeps its existing interpretation; reparse the original file to classify historical timing, then refresh dependent summaries. No blanket historical reparse is required, and no new user setting is needed.

    TCX lap elapsed time covers every Track, starting at Lap.StartTime when valid, otherwise the earliest valid trackpoint. A stated start overlapping the previous lap is rejected when this lap’s recorded points all follow that previous lap; its earliest point supplies the start instead. TotalTimeSeconds retains its active-duration meaning and is also the elapsed-time minimum. Separate tracks do not create moving-time intervals across their gaps. Reparse original files to apply these corrections to saved activities, then refresh derived summaries. Canonical metric names, units and JSON schemas are unchanged.

    Sports Lib 23.2 requires FIT Parser ^6.2.3. Supported numeric fields are decoded when a producer omits the endian flag from a FIT base-type byte; each message definition's architecture still determines byte order. This recovers affected timestamps, durations and measurements without adding parser options or changing raw source bytes. Reserved or unknown type codes, incompatible field types, bounds and checksum policy keep their existing validation.

    Reparse retained original FIT files to recover missing or incorrectly decoded values, or retry imports that failed with missing start/end dates. Then regenerate affected persisted summaries, activity-type aggregates and dependent Training snapshots through the consuming application's existing workflow. Native JSON alone cannot recover values discarded during the original parse. Installing the package does not automatically reparse files or rewrite data; correctly decoded imports need no migration. Public signatures, canonical metric tokens, units and JSON schemas are unchanged.

    Ordinary FIT activity imports recover existing device files whose normal record headers set reserved bit 4. Messages using this compatibility path must have complete definitions and native/developer payloads within the source data section. Other invalid data-header bits remain rejected. This restores imports rejected by FIT Parser 5.2.0 through 6.2.1 without rewriting the source or changing imported TSS, calibration rules, or checksum policy. Strict/raw FIT readers, including the independent workout-reference reader below, retain their existing validation; a recoverable activity does not automatically establish valid workout-reference metadata. Retry previously rejected original files with Sports Lib 21.6.11 or later. Existing successful imports need no migration.

    Read optional source references independently of activity imports:

    import { readFITWorkoutReferences, DataSuuntoPlusGuideReferences } from '@sports-alliance/sports-lib';

    const result = readFITWorkoutReferences(fitArrayBuffer); // also accepts Uint8Array / Node Buffer views
    if (result.status !== 'invalid') {
    const pairs = result.suuntoGuides.getValue().references;
    const stored = JSON.parse(JSON.stringify(result.suuntoGuides.toJSON()));
    const restored = DataSuuntoPlusGuideReferences.fromJSON(stored);
    }

    trainingFiles, workouts and suuntoGuides are respectively DataFITTrainingFileReferences, DataFITWorkoutDefinitions and DataSuuntoPlusGuideReferences. Every class has validated construction and setValue, defensive-copy getters, canonical toJSON() and strict static fromJSON(unknown). JSON envelopes use the canonical type as their only key; values contain only an ordered references or definitions array, with no schema-version field. Unknown fields, invalid numbers and malformed strings are rejected rather than silently normalized. Validation snapshots array members without invoking caller-provided array methods, and stores the same scalar values it validates. A rejected setValue() leaves the previous value intact.

    Training-file references retain FIT message 72 fields: type, manufacturer, product, serialNumber, timeCreatedUnixMs and timestampUnixMs. The serial is native uint32z: zero is missing, while 4294967295 is valid. Workout definitions retain message 26 name, sport, subSport and numValidSteps, not full recipes. Native enums remain numeric FIT codes; timestamps are UTC Unix milliseconds. Missing source fields are absent, not inferred. Both lists remain file-scoped. sessions separately records zero-based source order, start/end timestamps and native sport/sub-sport. Malformed optional fields are omitted individually with diagnostics, preserving other valid context and independently valid Guide pairs in that session; an index-only entry is retained if no context is usable. Do not blindly equate a session ordinal with a consumer activity ID or assign every file reference to every session.

    Suunto Guide pairs preserve sessionIndex, developerDataIndex, applicationId, ownerId and externalId. The owner is an OAuth client ID, not the Guide owner's display name. The reader resolves developer field descriptions and preserves NUL-separated positional arrays, grouping strictly within one session and developer index. It accepts SuuntoFitExport1 and SuuntoplusFitExt, both identified in Suunto's decoder example. Developer indexes and field numbers are resolved from each file, not hard-coded. Different indexes, field numbers, Guide identifiers or unrelated SuuntoPlus apps do not require a library update. Changed Guide semantics or a new metadata exporter require reviewed support; arbitrary field names or app IDs do not establish Guide usage.

    wahooWorkouts is a plain, ordered FITWahooWorkoutReference[], not a Data* class. It reads only the observed wahoo-app-plan-v1 layout from native manufacturer message 65285 in a file with exactly one file_id identifying a Wahoo (manufacturer 32) recorded activity (type 4). Its field 3 byte payload must have the exact 35 00 05 header, bounded positive-decimal Plan ID, terminators and fixed-length tail; envelope fields 0–2 must have the observed types and lengths. The payload's scheduled Workout ID is little-endian independently of the FIT definition architecture. The explicit 0xffffffff sentinel becomes workoutId: null; a zero ID is invalid. startTimeUnixMs retains the source metadata's recording start, not the planned date. The opaque final four bytes are deliberately not returned or assigned a meaning. Other private messages are ignored; the reader never searches arbitrary bytes or titles for IDs.

    This layout is an empirical compatibility contract, reproduced in synthetic tests from multiple authorized QA recordings, not a published Wahoo binary specification. invalid_wahoo_reference identifies malformed recognized records; unsupported_wahoo_reference identifies unknown reference-layout headers or an absent/conflicting Wahoo activity-file identity. Either rejects the entire Wahoo reference group, including earlier apparently valid entries, while preserving independent native and Suunto evidence. Duplicate and conflicting valid observations are returned, not silently deduplicated or matched. All references are file-scoped: consumers must separately establish the recorded session, trusted source provenance, exact owned provider delivery and ambiguity policy. A null scheduled Workout ID does not justify title/date/duration matching or account-wide Plan ID matching.

    Restore an explicitly authorized metadata snapshot with the strict codec; unknown fields, unsupported formats, out-of-range values and incomplete/sparse arrays are rejected. Array bounds, object keys and scalar fields are snapshotted once, so validation and copying use the same values even for inputs with accessors or proxies:

    import { parseFITWahooWorkoutReferences, readFITWorkoutReferences } from '@sports-alliance/sports-lib';

    const source = readFITWorkoutReferences(fitArrayBuffer);
    const stored = JSON.parse(JSON.stringify(source.wahooWorkouts));
    const restored = parseFITWahooWorkoutReferences(stored); // owned plain-object snapshot

    The synchronous reader delegates FIT wire-format validation and selected-message extraction to the lightweight fit-file-parser/raw entry point. That entry point does not load the full activity decoder or semantic profile. Sports Lib interprets the retained native field bytes and base types, session-scoped developer fields, interior NUL separators, endianness and compressed timestamps as workout-reference metadata. Source-native enums remain their original numeric FIT codes rather than parser display labels.

    Malformed or conflicting application identities invalidate references for that developer index, including earlier observations. Malformed/conflicting field descriptions invalidate only references depending on those fields, not unrelated fields sharing the exporter. Unresolvable malformed messages report diagnostics without invalidating other identified groups. Unrelated developer IDs may omit an application ID. Strings are not trimmed, case-folded or Unicode-normalized. All valid owners are returned; consumers filter their own identities. Malformed extra Guide owner/external-ID fields make their session/index group ambiguous; they cannot be silently dropped to accept a remaining apparent pair, even when their type metadata cannot be decoded.

    The result is ok, partial (some optional metadata rejected or unsupported), or invalid (no evidence returned). unsupported_exporter means Guide-named fields came from a well-formed but unrecognized application ID, not malformed data. Missing application/field definitions report unresolved_developer_field; malformed definitions report invalid_metadata, and contradictory definitions report conflicting_developer_definition. None of these diagnostics establishes completion. Valid independent references can remain in a partial result. diagnostics contains only a bounded set of codes, never IDs or raw bytes. The reader validates headers, CRC, record structure, relevant field types, endianness and compressed timestamps while retaining only selected metadata messages. Safety bounds are 64 MiB per file and 10,000 records per result collection; exceeding a bound is invalid, never silent truncation. Each Suunto developer group allows up to ten paired IDs of up to 64 Unicode characters, following the documented format. Invalid metadata does not throw into or otherwise change the ordinary activity importer. No credentials or provider requests are involved.

    These classes are registered for dynamic loading but are not numeric metrics. The reader never adds them to Event/Activity stats or default JSON. Treat identifiers as private: validate source provenance and account ownership, then persist only through an explicitly authorized metadata path. A standard FIT serial is not a universal Garmin Training API workout ID or schedule ID; embedded names are not identity proof. References may show selected workout or Guide usage but do not prove all prescribed targets or steps were completed.

    No existing activity/route migration, derived-summary regeneration or global reparse is required. Consumers can read selected retained originals for historical evidence without rewriting activity data. Numeric catalogs must distinguish these structured classes (numeric construction with 0 is rejected) from numeric metrics and plain Wahoo metadata. Existing consumers can ignore the additive wahooWorkouts result field. The library does not complete or relink a planned workout.

    Regression fixtures reproduce the metadata topology of an inspected Guide-bearing Suunto export using synthetic values: standard metrics on one developer index and Guide pairs on a separate SuuntoplusFitExt index. A renumbered variant exercises dynamic resolution. Tests also cover unrelated application-less metadata in existing Garmin/Wahoo samples. No private recordings or identifiers are embedded in these fixtures.

    Sources: Suunto FIT description and Suunto decoder example. The description documents positional owner/external-ID pairing; the example identifies both metadata exporters and distinguishes them from the variable IDs of individual SuuntoPlus apps.

    The FIT parser applies profile scaling to record-level depth, next_stop_depth, summary depth, and bottom-time fields. Sports Lib stores those scaled values directly as canonical meters or seconds without another conversion. The parser emits FIT avg_vam in meters per second; Sports Lib converts that present source value to its public Average VAM metric unit of meters per hour. Parser 4 exposed FIT session field 196 (metabolic_calories) a second time as resting_calories. Parser 5 retains only the canonical name, which Sports Lib imports as Metabolic Calories; it does not substitute the value into Resting Calories. Existing activities must be reparsed to gain Metabolic Calories; existing Resting Calories values in native JSON remain readable. Suunto depth values also remain canonical meters. Depth is available as an advanced chart metric; callers can request Depth explicitly through ActivityParsingOptions.streams.includeTypes.

    Garmin single_gas_diving, multi_gas_diving, and gauge_diving sub-sports resolve to Scuba Diving; apnea_diving and apnea_hunting resolve to Free Diving. These are direct FIT profile mappings and all remain in the Diving activity group.

    FIT dive_gas, tank_summary, and tank_update messages are available through activity.getDiveSourceRecords(). Gas messages are file-level source records and retain source order on each Diving-group activity imported from that FIT file. Tank summaries and tank updates are retained only for the activity whose session window contains their source timestamp. Oxygen and helium contents are percentages; pressures are bar; and volume used is liters. Sports Lib does not infer a gas-to-tank relation, consumption, a gas name, or any missing field. These records are deliberately not scalar metrics; they round-trip in the native ActivityJSONInterface.diveSourceRecords field, with tank timestamps stored as UTC milliseconds.

    Diving activities exclude terrain summaries—Ascent, Descent, altitude min/max/avg, and grade min/max/avg—whether they were imported from a FIT summary, restored from native JSON, regenerated into an all-diving event summary, or would otherwise be hydrated from streams. Mixed event summaries aggregate terrain values only from non-diving activities. Depth represents dive vertical movement. Any source altitude or grade stream remains available when explicitly requested.

    FIT session and lap intensity enums are retained as the string-valued Intensity stat. Values follow the FIT profile, such as active, rest, warmup, cooldown, recovery, interval, and other.

    Cadence-shaped source fields are normalized by activity context. Swimming, open-water swimming, rowing, indoor rowing, kayaking, canoeing, paddling, and stand-up paddling expose Stroke Rate in spm; other activities continue to expose Cadence in rpm. The same rule covers streams plus activity and lap summaries, and prevents both semantic families from being emitted for one activity.

    Use importFromSuunto(suuntoJson) for Suunto JSON. Use importFromJSON(eventJson) only for Sports Lib's native EventJSONInterface representation.

    Suunto JSON/SML activity and lap windows without PauseDuration supply active time, not elapsed time. Elapsed time comes from the owning interval; an explicit elapsed/pause pair retains its supplied semantics. Negative pauses are never emitted. An impossible active summary can be recovered from an explicit Activity start and non-conflicting boolean pause states inside the recorded timeline. Repeated equal states are idempotent. A single-leg header can corroborate window precision only when its start agrees, its active value agrees at float32 precision and its entire elapsed interval lies inside the source sample envelope. This does not extend the activity or its streams. Float32-equivalent timestamp/summary differences alone cannot create a negative pause.

    Mismatched window counts or conflicting sport identifiers cannot donate timing to a leg. Without independent recovery evidence, contradictory active time leaves Duration, Timer time and Pause Time absent, not zero; duration-dependent load candidates (including HR) and newly calculated or cached durability evidence stay unavailable on that parsed instance. Valid imported scores remain eligible, including zero; HR calibration alone cannot establish active duration. Event summaries do not publish partial active/pause totals when a leg is unresolved. Missing summaries retain the existing timestamp fallback. Original-file reparse is required for historical corrections and for retaining private source evidence during regeneration; native JSON preserves the resulting values/absence but cannot recover that evidence. No metric names, units, public fields, route behavior or JSON schemas change.

    Native Suunto JSON multisport laps match timestamped Lap/Autolap windows to their recorded endpoints and sport identifiers, never to sample-array positions. A sport change can supply a partial lap without a separate Lap sample; that remainder stays with its sport leg instead of shifting all subsequent summaries. A final summary batch can be reconciled to Stop only when the same timestamp also contains the final sport's Activity summary and the Move summary. That Activity summary must be the latest timestamped one and fall after the final leg's start; an existing explicit lap endpoint cannot be moved. Earlier batches stay with their own intervals even when a sport is repeated later in the workout. Independent manual and automatic counters keep their own starts, including when only one supplies a final summary at Stop after a marker from the other counter. If an automatic summary could belong to multiple automatic counter types, withhold that ambiguous summary, including when a valid manual summary also flushes at Stop. Retain the Stop marker once if no unambiguous summary represents it; do not invent a generic automatic counter. Check counter ambiguity across the whole workout for global summaries, and only within the owning leg for sport-local summaries. Conflicting windows or sport identifiers do not supply another lap's distance or active duration.

    A genuine lap spanning sports remains one lap on the leg containing its endpoint. An unmatched source marker is retained once with its inferred interval, but that interval alone cannot establish active duration. Cross-leg laps keep source summaries; a single leg's samples cannot generate whole-lap averages or determine cadence/stroke or terrain semantics for the complete lap. Lap JSON and metric tokens are unchanged. Original-file reparse is required to correct historical source matching; native JSON cannot recover discarded source windows. Activity/event totals, streams and training-load methods are unchanged by this lap correction. Consumers should label cross-leg laps separately from sport-local laps and must not clamp their endpoints onto earlier legs' final map or chart samples.

    In mixed-sport Suunto files, a header speed-zone boundary is not owned by every leg. Only applicable leg-local speed boundaries populate those legs' intensity zones; local durations remain available. A header threshold remains eligible when all legs have one resolved sport type. Without an independent running/swimming threshold, pace TSS falls back through the existing eligible methods, or reports unavailable. Overrides and imported scores retain their usual priority. Reparse original Suunto files to correct older copied boundaries; saved JSON cannot establish their original ownership.

    Native JSON hydration preserves each child activity’s saved name independently of the parent event title. Names already present in stored JSON need no source reparse; a name discarded before storage cannot be recovered from that JSON.

    Native JSON hydration preserves explicit stats, except terrain summaries excluded for the Diving activity group, and fills missing pace, swim-pace, and grade-adjusted-pace summaries from compatible speed summaries on events, activities, and laps. This keeps older speed-only exports readable with the same derived-stat behavior as newly parsed files; serializing the hydrated model includes the additive derived stats. It also converts cadence-shaped data to stroke rate for the supported activity types, so stored native JSON does not require reparsing from FIT, TCX, or GPX. Pool-swim length JSON keeps its existing avgCadence property name while hydrating that value as DataStrokeRate.

    Complete native event JSON contains the activities that determine event-summary semantics. Summary-only native event JSON removes Diving-group terrain summaries when its Activity Types stat is present, but preserves other summary semantics. An application can opt in after hydration by calling normalizeActivityMetricSemanticsForStats(summary, contributingActivityTypes). The helper changes only unambiguous homogeneous stroke-rate summaries and removes terrain summaries from homogeneous Diving-group summaries; empty, unknown, and mixed activity-type inputs remain unchanged. Sports Lib does not infer relationships omitted by an application-specific persistence layout.

    Restoring existing Diving-group native JSON now removes terrain ascent/descent, altitude min/max/avg, and grade min/max/avg summary values from events, activities, and laps. No source-file reparse is needed for the restored in-memory model. Re-serializing that model intentionally omits those values; raw source streams remain untouched.

    Regenerating an event from Diving-group activities now omits those terrain summaries, and a mixed event takes them only from its non-diving activities. No source-file reparse is needed; regenerate and reserialize the event summary when an application persists regenerated summaries.

    FIT imports now expose the parser-provided gas and tank messages through getDiveSourceRecords(). Existing native JSON does not gain a persisted field and needs no schema migration. An application that wants to show the records for an already-stored activity must hydrate them again from its retained original FIT source; Sports Lib does not reconstruct them from summary metrics or streams.

    diveSourceRecords is now a native ActivityJSONInterface field. JSON export preserves the ordered gas, tank-summary, and tank-update records, and JSON import restores tank timestamps as Date values. The records remain structured data, not numeric metrics: no gas/tank relationship, mixture name, nitrogen value, or consumption is inferred.

    Activities stored from 20.1.0 or earlier do not contain this new field. Reparse or import the retained original FIT source to backfill it; native JSON cannot reconstruct the records from existing summaries or streams.

    Activities expose one-second streams and typed stats. Read numeric values with getValue() and display-ready values with getDisplayValue(). Depth presentation follows the first swim-pace preference: /100m selects meters and /100yd selects feet, while serialized source values remain meters.

    For stream filtering, generated streams, training-stress settings, and FIT device compaction, see Configure parsing. Planned courses are separate models; see Work with routes.