fit-file-parser 5.2.1 → 6.1.1

package/CHANGELOG.md

@@ -1,205 +1,49 @@
 # Change Log
 
-## Unreleased
-
-## 5.2.1
-
-### Fixed
-
-- Preserve unusual vendor field definitions in lossless raw-message output so
-  domain consumers can validate only the messages they understand.
-- Add corpus checks for raw-message-only and combined raw/decoded parsing.
-
-## 5.2.0
-
-### Added
-
-- Add opt-in, message-filterable `raw_messages` output with exact native and
-  developer-field bytes, wire base types, endianness, message occurrence, and
-  reconstructed compressed timestamps. Existing decoded output remains
-  unchanged when the option is disabled.
-- Add `rawMessagesOnly` for bounded metadata consumers that do not need decoded
-  activity collections alongside retained messages.
-
-### Fixed
-
-- Decode compressed timestamp records without consuming bytes for the omitted
-  timestamp field.
-
-## 5.1.0
+## 6.1.1 - 2026-09-21
 
 ### Added
 
-- Add opt-in, message-filterable `raw_developer_fields` output with exact
-  developer-field bytes, global-message occurrence, developer-data index, and
-  field-definition number. Existing decoded output remains unchanged when the
-  option is disabled.
-
-## 5.0.2
-
-### Fixed
+- Export lookup helpers for FIT manufacturer, Garmin product, sport, and
+  sub-sport identifiers from the package root.
+- Export the same helpers from the lightweight `fit-file-parser/profile`
+  entry point for lookup-only consumers.
+- Add reverse sport, sub-sport, and course-point identifier lookups.
+- Add lightweight `fit-file-parser/raw` and `fit-file-parser/encoder` entry
+  points for profile-independent message scanning and encoding.
+- Add a strict raw-message reader with CRC, definition, developer-field, and
+  compressed-timestamp validation.
+- Export an opt-in Garmin product display-name helper without changing parsed
+  `product` or `product_name` fields.
+- Decode mountain enduro and mountain downhill sub-sport identifiers.
 
-- Clarify the 5.0 migration for standard session field 196: use canonical
-  `metabolic_calories` rather than the old duplicate `resting_calories` label.
-- Clarify that the removed guessed `recovery_advisor` label was standard
-  session field 140, which the SDK defines as `avg_depth` in meters.
+### Compatibility
 
-## 5.0.1
+- Existing parsed output remains unchanged except that sub-sport IDs 153 and
+  154 now resolve to `mountain_enduro` and `mountain_downhill`.
+- Existing Garmin product display names ported from SportsLib are preserved.
 
-### Fixed
-
-- Run CI and version-driven npm publishing from the repository's `main`
-  branch, with a guarded manual recovery path for a missed release.
-
-## 5.0.0
+## 6.0.2 - 2026-09-21
 
 ### Changed
 
-- Generate the complete standard message, field, and type surface from the
-  pinned Garmin FIT SDK without handwritten standard-profile overrides.
-- Preserve SDK alphanumeric tokens when generating public `snake_case` names,
-  including `n2`, `po2`, `time128`, and Garmin product identifiers.
-- Restrict non-SDK support to a collision-checked allowlist of Garmin fields
-  and private messages observed in the external FIT corpus.
-- Emit only parsed FIT values: Garmin product names are no longer inferred,
-  and record elapsed/timer values are generated only when
-  `elapsedRecordField: true` is requested.
-
-### Breaking
-
-- Remove compatibility aliases such as `resting_calories`,
-  `recovery_advisor`, `repeat_dive_time`, and deprecated time-in-zone names.
-- Remove guessed stress fields, handwritten enum/type additions, placeholder
-  zero-mask names, and the misspelled `hip_swing_excercise_name` type.
-- Use the pinned SDK's `cadence_zone_high_bondary` spelling and generated
-  alphanumeric field/type spellings instead of manual corrections.
-- Correct generated declarations to expose runtime `Date` values, numeric FIT
-  `bool` fields and unknown enum IDs, decoded mask objects, nullable array
-  entries, and optional profile fields.
-- Keep undated cascade rows in file order and avoid duplicating them when a lap
-  or session boundary timestamp is absent.
-
-## 4.1.1
-
-### Fixed
-
-- Apply Garmin FIT profile scale and offset to primitive numeric fields, while
-  retaining semicircle conversion only for fields declared in semicircles.
-- Apply FIT developer-field offsets with the parser's equivalent signed form,
-  including scaled signed developer values.
-- Decode native diving ascent-rate fields as meters per second instead of
-  geographic coordinates.
-- Decode native dive depth and bottom-time fields with their Garmin FIT SDK
-  scale instead of exposing their encoded integer representation.
-- Keep the pinned Garmin SDK authoritative for standard field types, arrays,
-  scales, offsets, and units while retaining compatible public field names.
-
-## 4.1.0
+- Consolidate the complete message, field, wire-metadata, type, enum, and
+  product contract into one static maintained profile.
+- Maintain the FIT interoperability profile directly as static project source.
+- Preserve decoded output and the public TypeScript surface.
 
 ### Added
 
-- Generate all 124 standard messages, 1,406 fields, and 200 profile types from
-  the exactly pinned Garmin FIT SDK 21.208.0 profile.
-- Retain every recognized message in file order under the typed
-  `ParsedFit.messages` index without changing existing list, cascade, or
-  singleton outputs.
-- Decode Garmin strength-training `set` messages in list and cascade modes.
-- Add reproducible generated-profile and privacy-safe external corpus audits,
-  and enforce profile freshness and coverage in CI.
-
-### Fixed
-
-- Decode fields from their wire base types, including compatible developer
-  enum/uint8/byte definitions and correctly sized numeric arrays.
-- Reconstruct compressed timestamps and keep timestamp state isolated between
-  parser instances.
-- Accept omitted header CRCs, validate file CRCs across the complete FIT header
-  and data section, and report strict header and file CRC failures explicitly.
-- Reject structurally unsafe FIT inputs consistently in callback and Promise
-  APIs while retaining force-mode recovery for CRC corruption.
-- Correct Garmin profile mappings for OHR settings, monitoring HR, sleep,
-  time-in-zone, altitude offsets, and lap/segment flow and grit summaries.
-- Correct Celsius-to-Kelvin conversion, add `celsius` as the canonical
-  temperature unit, and retain `°C` as a supported alias.
-
-### Compatibility and documentation
-
-- Preserve compatible legacy field names, scales, value shapes, parser
-  signatures, output modes, and date behavior while adding canonical profile
-  names.
-- Add regression coverage for temperature, pressure, validation, compressed
-  timestamps, generated profile messages, repeated messages, and MTB
-  flow/grit data.
-- Refresh the README with current runtime, API, units, output modes, developer
-  fields, encoder behavior, and repository commands.
-
-## 4.0.2
-
-- Preserve record alignment when developer-field descriptions are missing or
-  appear after their message definitions.
-- Decode subsequent developer-field values once their descriptions become
-  available, in both strict and force modes.
-
-## 4.0.0
-
-### FIT decoder performance
-
-- Parse `ArrayBuffer` inputs and exact Node.js `Buffer` views directly, avoiding a full copy of the source file.
-- Reuse one parse-local `DataView` instead of allocating temporary views for each supported endian field.
-- Cache standard field metadata and enum/mask lookups on reusable message definitions.
-- Reuse raw field storage for records that share a local message definition.
-- Generate elapsed and timer fields once per record instead of once per decoded field.
-- Skip header and file CRC scans in `force: true` mode, where CRC mismatches are intentionally ignored; strict mode continues to validate both CRCs.
-- Preserve legacy malformed-field zero-padding, field-boundary, developer-field, invalid-value, and offset-buffer behavior.
-
-### Measured benefit
-
-- Suunto 93-hour / 7.5 MB FIT decoding: 1.057 s to 0.375 s, a 64.5% reduction.
-- Garmin 110-hour / 28.6 MB FIT decoding: 3.643 s to 1.241 s, a 65.9% reduction.
-- Input-related array-buffer memory is approximately halved by removing the full source copy:
-  - Suunto: 15.0 MB to 7.5 MB.
-  - Garmin: 57.2 MB to 28.6 MB.
-
-There are no intentional parsed-output or public API changes in this release. Output parity was verified across 162 checked-in fixture/mode combinations, 8,320 generated malformed endian-definition cases, and both private long-duration benchmark files.
-
-## 3.1.0
-
-- Add the public `FitEncoder` API for writing FIT headers, definitions, data messages, and CRCs.
-- Preserve the `course.sub_sport` field while parsing FIT course files.
-
-<a name="1.5.4"></a>
-
-## [1.5.4](https://github.com/jimmykane/fit-parser/compare/v1.0.0...v1.5.3) (2019-03-01)
-
-- **Features**: HRV, Developer fields, devices and much more
-- **Miscellaneous**: Fix most of the issues parsing fit files
-
-<a name="1.0.1"></a>
-
-## [1.0.1](https://github.com/pierremtb/easy-fit/compare/v1.0.0...v1.0.1) (2018-09-18)
-
-### 😭 Unclassified (not [following convention](https://github.com/sportheroes/bk-conventional-changelog#types-of-commits))
-
-- **Miscellaneous**: fix: Applied to src/fit offset adjustments from commit 9ed802 ([70b3eb6](https://github.com/pierremtb/easy-fit/commit/70b3eb6) - [JoeTheFkingFrypan](https://github.com/JoeTheFkingFrypan))
-
-<a name="1.0.0"></a>
-
-# [1.0.0](https://github.com/pierremtb/easy-fit/compare/0.0.7...1.0.0) (2018-09-17)
-
-### 😭 Unclassified (not [following convention](https://github.com/sportheroes/bk-conventional-changelog#types-of-commits))
-
-- **Miscellaneous**: Fix readme typo ([2282c06](https://github.com/pierremtb/easy-fit/commit/2282c06)))
-- **Miscellaneous**: chore: preparing to release fork internally ([3eef5f7](https://github.com/pierremtb/easy-fit/commit/3eef5f7) - [JoeTheFkingFrypan](https://github.com/JoeTheFkingFrypan))
-- **Miscellaneous**: fix: Typo leading to uint16 to never be invalidated ([9ed802c](https://github.com/pierremtb/easy-fit/commit/9ed802c) - [JoeTheFkingFrypan](https://github.com/JoeTheFkingFrypan))
-- **Miscellaneous**: Merge remote-tracking branch 'jenglert/master' ([819d78e](https://github.com/pierremtb/easy-fit/commit/819d78e)))
-- **Miscellaneous**: fix missing buffer dependency and compile dst ([a4b237a](https://github.com/pierremtb/easy-fit/commit/a4b237a)))
-- **Miscellaneous**: Merge remote-tracking branch 'FrostDigital/master' ([6fa9258](https://github.com/pierremtb/easy-fit/commit/6fa9258)))
-- **Miscellaneous**: Makes parsing of fit files with developer defined fields possible (#1) ([9aea666](https://github.com/pierremtb/easy-fit/commit/9aea666))), closes [#1](https://github.com/pierremtb/easy-fit/issues/1)
-- **Miscellaneous**: fix: Adjusted offset for all altitude-related fields ([1ff0fa4](https://github.com/pierremtb/easy-fit/commit/1ff0fa4) - [JoeTheFkingFrypan](https://github.com/JoeTheFkingFrypan))
-- **Miscellaneous**: chore(devices): add forerunner 735 xt ([aacaa04](https://github.com/pierremtb/easy-fit/commit/aacaa04)))
-- **Miscellaneous**: Compile src ([ee4aa00](https://github.com/pierremtb/easy-fit/commit/ee4aa00)))
-- **Miscellaneous**: Add support for other lap types ([dcf42a1](https://github.com/pierremtb/easy-fit/commit/dcf42a1)))
-- **Miscellaneous**: Compile src ([50b9b21](https://github.com/pierremtb/easy-fit/commit/50b9b21)))
-- **Miscellaneous**: Merge remote-tracking branch 'pierremtb/master' ([f7f5ff0](https://github.com/pierremtb/easy-fit/commit/f7f5ff0)))
-- **Miscellaneous**: Add support for more manufacturers ([2d122d2](https://github.com/pierremtb/easy-fit/commit/2d122d2)))
-- **Miscellaneous**: Really compiled last changes on binary.js this time, small details on package.json file -> bumped to 0.0.8 ([e5dc98f](https://github.com/pierremtb/easy-fit/commit/e5dc98f)))
+- Add opt-in `unmapped_messages` preservation, including exact bytes and
+  definition metadata, without changing default parsed output.
+- Add regression coverage for unknown messages, unknown fields inside known
+  messages, the immutable compatibility profile, and default-output stability.
+- Add an optional privacy-safe corpus summary for unmapped message/field IDs,
+  wire base types, sizes, occurrences, and file counts.
+- Document the manual update requirements and corpus verification workflow in
+  `PROFILE.md`.
+
+There are no intentional parsed-output or public API changes in this release.
+Output parity was verified across 162 checked-in fixture/mode combinations,
+8,320 generated malformed endian-definition cases, and both private
+long-duration benchmark files.

package/PROFILE.md

@@ -0,0 +1,43 @@
+# FIT Profile Maintenance
+
+The parser uses one static interoperability table in `src/profile.ts` for
+normal installs, builds, tests, and releases. It contains message and field
+identifiers, names, wire types, array behavior, scales, offsets, units, enum
+labels, and product identifiers. `npm run profile:check` pins full-table
+fingerprints and the resulting message, field, type, enum-value, and product
+counts so accidental drift fails CI.
+
+## Unknown and newer fields
+
+A FIT definition contains enough wire metadata to retain a field even when the
+maintained table cannot assign it a semantic name. Pass
+`includeUnmappedMessages: true` to expose unmapped native or unresolved
+developer fields in `unmapped_messages`, including:
+
+- global message number and occurrence index;
+- endianness and reconstructed compressed timestamp, when applicable;
+- field-definition number and FIT base-type byte;
+- an exact copy of the field's wire bytes.
+
+The opt-in keeps default decoded results unchanged. Consumers that need a
+complete raw representation of selected messages can continue to use
+`includeRawMessages`; `unmapped_messages` stores only the fields the maintained
+table cannot decode.
+
+## Updating the table
+
+Every mapping change requires focused regression coverage. Do not guess
+adjacent identifiers or add a mapping solely to make `unmapped_messages`
+disappear. Update `src/profile.ts`, the relevant tests, and the public types,
+then verify the complete compatibility contract:
+
+```sh
+npm run codegen
+npm run profile:check
+npm run check
+npm run compatibility:check -- /path/to/reference-package /path/to/fit-corpus
+npm run corpus:check -- ../FIT-test-files --allow-force-recovery
+```
+
+`src/fit_types.ts` is generated from the maintained table and must not be
+edited manually.

package/README.md

@@ -15,6 +15,8 @@ including developer-defined data.
 - Convert speed, length, temperature, and pressure fields to preferred units.
 - Decode developer fields while preserving record alignment when descriptions
   arrive after their definitions.
+- Optionally preserve every unmapped native or unresolved developer field in
+  `unmapped_messages` with its exact wire bytes.
 - Encode profile-agnostic FIT messages with validated field definitions and
   CRCs.
 - Use ESM or CommonJS with bundled TypeScript declarations.
@@ -29,56 +31,12 @@ including developer-defined data.
 npm install fit-file-parser
 ```
 
-## Migrating from 4.x to 5.0
-
-Version 5.0 is a breaking release because parsed output now follows the pinned
-Garmin FIT SDK profile without compatibility aliases or guessed fields. Parser
-construction, module imports, output modes, and parser options are unchanged.
-
-Update field access, destructuring, persisted schemas, and snapshots to use the
-SDK-backed names. Common migrations include:
-
-| 4.x name                       | 5.0 name                     |
-| ------------------------------ | ---------------------------- |
-| `speed_1s`                     | `speed1s`                    |
-| `start_n_2`, `end_n_2`         | `start_n2`, `end_n2`         |
-| `o_2_toxicity`                 | `o2_toxicity`                |
-| `avg_spo_2`, `reading_spo_2`   | `avg_spo2`, `reading_spo2`   |
-| `po_2`                         | `po2`                        |
-| `cycle_length_16`              | `cycle_length16`             |
-| `map_3_sample_mean`            | `map3_sample_mean`           |
-| `time_256`                     | `time256`                    |
-| `last_night_5_min_high`        | `last_night5_min_high`       |
-| `average_7_day_deviation`      | `average7_day_deviation`     |
-| `spo_2_data`, `hsa_spo_2_data` | `spo2_data`, `hsa_spo2_data` |
-| `repeat_dive_time`             | `repeat_dive_interval`       |
-| `cadence_zone_high_boundary`   | `cadence_zone_high_bondary`  |
-| `HipSwingExcerciseName`        | `HipSwingExerciseName`       |
-| `resting_calories`             | `metabolic_calories`         |
-
-The same alphanumeric-token rule applies to enum strings, for example
-`camera_orientation_90` becomes `camera_orientation90`, `po_2_warn` becomes
-`po2_warn`, and `power_3s` becomes `power3s`. The generated TypeScript
-declarations are the exhaustive name and value reference for the pinned SDK.
-
-Parser 4 exposed standard session field 196 (`metabolic_calories`) a second
-time as `resting_calories`; use the canonical `metabolic_calories` name in 5.0.
-`recovery_advisor` was a guessed label for standard session field 140, whose
-canonical SDK field is `avg_depth` in meters. Other behavior to account for
-during migration:
-
-- `product_name` is emitted only when it exists in the FIT input. It is no
-  longer inferred from `manufacturer` and `product`.
-- Record `elapsed_time` and `timer_time` require
-  `elapsedRecordField: true`.
-- FIT timestamps are typed as `Date`, FIT `bool` values remain numeric, mask
-  fields are `{ value, ...flags }` objects, unknown enum values remain numbers,
-  and array entries may be `null` when the FIT invalid sentinel is retained.
-- Every profile field is optional because individual FIT message definitions
-  determine which fields are present.
-- When upgrading from 4.1.0 or earlier, remove application-side scale or offset
-  corrections for parsed numeric values, including dive depth, bottom time,
-  ascent rate, and developer fields. The parser now applies the SDK metadata.
+## Profile coverage
+
+The static profile contains 126 messages, 1,444 fields, 200 types, and 4,403
+mapped values. Pass `includeUnmappedMessages: true` to retain fields outside
+that maintained surface by number and exact bytes; applications that need all
+bytes for recognized messages can also opt into `raw_messages`.
 
 ## Quick start
 
@@ -186,6 +144,31 @@ provider-specific semantics. Pass `true` to retain developer fields from every
 global message, or an array such as `[18]` to bound collection to specific FIT
 message numbers.
 
+### Opt-in preservation of unmapped fields
+
+Set `includeUnmappedMessages: true` to return fields that are absent from the
+maintained profile or belong to an unknown global message in
+`unmapped_messages`. Only unmapped fields are retained, so normal known fields
+are not duplicated:
+
+```javascript
+const data = await new FitParser({ includeUnmappedMessages: true })
+  .parseAsync(content)
+
+for (const message of data.unmapped_messages ?? []) {
+  console.log({
+    globalMessageNumber: message.global_message_number,
+    messageIndex: message.message_index,
+    fields: message.fields,
+    developerFields: message.developer_fields,
+  })
+}
+```
+
+Each entry uses the same wire-level field representation as `raw_messages`.
+This opt-in ensures a newer FIT field cannot disappear merely because it
+does not yet have a reviewed semantic mapping.
+
 ### Lossless selected messages
 
 Set `includeRawMessages` when a consumer needs native FIT numeric codes rather
@@ -256,16 +239,14 @@ unchanged.
 
 ## Profile-backed output
 
-Standard message names, field names, enum values, wire types, scales, offsets,
-arrays, and units come from the exactly pinned Garmin FIT SDK profile. Public
-names use the parser's generated `snake_case` form while preserving SDK
-alphanumeric tokens such as `n2`, `po2`, and `time128`. The parser does not add
-compatibility aliases for alternate field spellings.
+Recognized message names, field names, enum values, wire types, scales,
+offsets, arrays, and units come from the community-maintained table in
+`src/profile.ts`. Its maintenance and verification contract is documented in
+[`PROFILE.md`](./PROFILE.md).
 
-The small vendor extension table contains only Garmin fields and private
-messages observed in the external FIT corpus. Extensions cannot replace a
-standard SDK field or type value; the profile audit rejects collisions and
-unregistered additions.
+Public names use `snake_case` while preserving established alphanumeric tokens
+such as `n2`, `po2`, and `time128`. Unmapped fields remain available by number
+and exact bytes in `unmapped_messages` rather than receiving guessed names.
 
 Only values present in the FIT input are emitted. In particular,
 `product_name` is not inferred from `manufacturer` and `product`, and record
@@ -276,6 +257,57 @@ unknown enum IDs remain numbers, and invalid entries retained inside FIT arrays
 are `null`. All profile fields are optional because each FIT message definition
 chooses which fields are present.
 
+Applications that need profile lookups independently of parsing can use the
+exported manufacturer, Garmin product, sport, sub-sport, and course-point helpers:
+
+```javascript
+import {
+  getFitCoursePointId,
+  getFitGarminProductDisplayName,
+  getFitManufacturerName,
+  getFitSportId,
+  getFitSportName,
+  getFitSubSportId,
+  getFitSubSportName,
+} from 'fit-file-parser'
+
+getFitManufacturerName(1) // "garmin"
+getFitGarminProductDisplayName(4655) // "Edge MTB"
+getFitSportName(2) // "cycling"
+getFitSubSportName(153) // "mountain_enduro"
+getFitSportId('cycling') // 2
+getFitSubSportId('indoor_cycling') // 6
+getFitCoursePointId('rest_area') // 29
+```
+
+These helpers read the same maintained profile used by the decoder. The product
+display helper is opt-in and does not synthesize or overwrite parsed
+`product_name` values.
+
+Lookup-only consumers can import the same helpers from
+`fit-file-parser/profile` without loading the parser entry point.
+
+### Lightweight raw messages
+
+Consumers that need strict FIT framing, CRC validation, compressed timestamps,
+and exact fields without loading the semantic profile can use the lightweight
+raw entry point:
+
+```javascript
+import { readFitMessages } from 'fit-file-parser/raw'
+
+const { messages } = readFitMessages(content, {
+  messageNumbers: [18, 26, 72],
+  maxInputBytes: 64 * 1024 * 1024,
+})
+```
+
+The result retains native and developer fields as defensive `Uint8Array`
+copies. It does not apply names, enum formatting, scales, units, or
+provider-specific interpretation. Invalid input throws `FitMessageReaderError`
+with a stable `code` such as `invalid_header`, `invalid_crc`, or
+`invalid_structure`.
+
 ## Inputs
 
 Both parser methods accept:
@@ -302,7 +334,7 @@ base types, sizes, and values in their raw FIT representation. Applying FIT
 scales and offsets is the caller's responsibility.
 
 ```javascript
-import { FitBaseType, FitEncoder } from 'fit-file-parser'
+import { FitBaseType, FitEncoder } from 'fit-file-parser/encoder'
 
 const encoder = new FitEncoder()
 encoder.writeMessage(0, [
@@ -338,6 +370,9 @@ Scalar 64-bit values use `bigint`. Strings, numeric arrays, and other
 variable-length values use exact-size `Uint8Array` values. Invalid field
 definitions or numeric ranges throw before a partial message is written.
 
+The encoder remains available from the package root; the `/encoder` entry
+point avoids loading the decoder and semantic profile.
+
 ## TypeScript and module formats
 
 The package includes TypeScript declarations and exports
@@ -363,21 +398,22 @@ const {
 
 Run commands from the repository root.
 
-| Command                            | Purpose                                            |
-| ---------------------------------- | -------------------------------------------------- |
-| `npm ci`                           | Install locked dependencies.                       |
-| `npm run build`                    | Build ESM and CommonJS output.                     |
-| `npm test -- --run`                | Run the complete test suite once.                  |
-| `npm test -- --run test/<file>.ts` | Run a focused test file.                           |
-| `npm run codegen`                  | Regenerate the Garmin profile and public types.    |
-| `npm run codegen:check`            | Verify both generated files are current.           |
-| `npm run profile:audit`            | Audit SDK profile coverage and private overlays.   |
-| `npm run corpus:check -- <path>`   | Validate an external FIT corpus without file data. |
-| `npm run lint`                     | Check lint and formatting rules.                   |
-| `npm run fmt`                      | Apply the configured formatting rules.             |
-| `npm run type-check`               | Run TypeScript without emitting files.             |
-| `npm run examples`                 | Build and regenerate checked-in example outputs.   |
-| `npm run check`                    | Run profile audit, lint, types, tests, and builds. |
+| Command                            | Purpose                                             |
+| ---------------------------------- | --------------------------------------------------- |
+| `npm ci`                           | Install locked dependencies.                        |
+| `npm run build`                    | Build ESM and CommonJS output.                      |
+| `npm run clean`                    | Remove the generated build output.                  |
+| `npm test -- --run`                | Run the complete test suite once.                   |
+| `npm test -- --run test/<file>.ts` | Run a focused test file.                            |
+| `npm run codegen`                  | Regenerate public types from the static profile.    |
+| `npm run codegen:check`            | Verify generated public types are current.          |
+| `npm run profile:check`            | Audit profile counts, structure, and fingerprints.  |
+| `npm run corpus:check -- <path>`   | Validate an external FIT corpus without file data.  |
+| `npm run lint`                     | Check lint and formatting rules.                    |
+| `npm run fmt`                      | Apply the configured formatting rules.              |
+| `npm run type-check`               | Run TypeScript without emitting files.              |
+| `npm run examples`                 | Build and regenerate checked-in example outputs.    |
+| `npm run check`                    | Run profile checks, lint, types, tests, and builds. |
 
 ### External FIT corpus (optional)
 
@@ -390,18 +426,26 @@ git clone https://github.com/ThomasKuehne/FIT-test-files.git ../FIT-test-files
 npm run corpus:check -- ../FIT-test-files --allow-force-recovery
 npm run corpus:check -- ../FIT-test-files --allow-force-recovery --raw-messages
 npm run corpus:check -- ../FIT-test-files --allow-force-recovery --raw-messages-with-decoded-output
+npm run compatibility:check -- /path/to/reference-package ../FIT-test-files
 ```
 
 The command accepts any corpus path; the sibling location is only a convenient
 convention. Add `--raw-messages` to exercise lossless raw-message-only parsing
 for every message in each file, or `--raw-messages-with-decoded-output` to also
-verify the ordinary decoded output path. The corpus contains a known header-CRC
-failure that is expected to recover only in force mode. It reports aggregate
-counts and never prints file names or parsed activity data.
-
-Do not edit `src/garmin_profile.generated.ts` or `src/fit_types.ts` manually.
-Update the pinned SDK, audited vendor extensions, or a generator, then run
-`npm run codegen`.
+verify the ordinary decoded output path. Add `--unmapped-summary` for a
+privacy-safe aggregate of unknown message/field identifiers, base types, sizes,
+occurrences, and file counts. The corpus contains a known header-CRC failure
+that is expected to recover only in force mode. Reports never print file names
+or parsed activity values.
+
+`compatibility:check` parses every corpus file with both the current build and
+a reference package, compares their complete default outputs, and reports only
+aggregate counts. Files rejected by both strict parsers are retried in force
+mode.
+
+Edit `src/profile.ts` only through reviewed profile changes with focused
+regression coverage and a documented source. Do not edit `src/fit_types.ts`
+manually; run `npm run codegen` after changing the maintained profile.
 
 Repository-specific automation guidance is tracked in
 [`.agent/README.md`](./.agent/README.md). More examples are available in the

package/dist/binary.d.ts

@@ -40,6 +40,8 @@ export declare function readRecord(blob: Uint8Array, messageTypes: MessageTypeDe
     compressedTimestamp?: number;
     rawFields?: RawFieldValue[];
     rawDeveloperFields?: RawDeveloperFieldValue[];
+    unmappedFields?: RawFieldValue[];
+    unmappedDeveloperFields?: RawDeveloperFieldValue[];
 };
 export declare function getArrayBuffer(buffer: ArrayBuffer | Buffer): ArrayBuffer;
 export declare function calculateCRC(blob: Uint8Array, start: number, end: number): number;

package/dist/binary.js

@@ -522,6 +522,8 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             && options.includeRawDeveloperFields.includes(messageType.globalMessageNumber));
     const rawFields = includeRawMessage ? [] : undefined;
     const rawDeveloperFields = includeRawDeveloperFields || includeRawMessage ? [] : undefined;
+    const unmappedFields = options.includeUnmappedMessages ? [] : undefined;
+    const unmappedDeveloperFields = options.includeUnmappedMessages ? [] : undefined;
     if (retainsRawMessages(options)) {
         const nativeSize = messageType.fieldDefs.reduce((total, field, index) => (total + (isCompressedTimestamp && index === 0 && field.fDefNo === 253 ? 0 : field.size)), 0);
         const developerSize = developerFieldDefs.reduce((total, field) => total + field.size, 0);
@@ -537,12 +539,17 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             rawData[i] = InvalidFieldData;
             continue;
         }
-        if (rawFields && readDataFromIndex + fDef.size <= dataEnd) {
-            rawFields.push({
+        if ((rawFields || (unmappedFields && !isOutputFieldName(fDef.name)))
+            && readDataFromIndex + fDef.size <= dataEnd) {
+            const rawField = {
                 fieldDefinitionNumber: fDef.fDefNo,
                 baseType: fDef.baseTypeNo,
                 rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + fDef.size)),
-            });
+            };
+            rawFields === null || rawFields === void 0 ? void 0 : rawFields.push(rawField);
+            if (!isOutputFieldName(fDef.name)) {
+                unmappedFields === null || unmappedFields === void 0 ? void 0 : unmappedFields.push(rawField);
+            }
         }
         const data = readData(blob, dataView, fDef, readDataFromIndex);
         if (data !== InvalidFieldData
@@ -566,15 +573,21 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
     for (let i = 0; i < developerFieldDefs.length; i++) {
         const developerFieldDef = developerFieldDefs[i];
         const rawDataIndex = messageType.fieldDefs.length + i;
-        if (rawDeveloperFields
+        let rawDeveloperField;
+        if ((rawDeveloperFields
+            || (unmappedDeveloperFields && developerFieldDef.resolvedFieldDef === undefined))
             && readDataFromIndex + developerFieldDef.size <= dataEnd) {
-            rawDeveloperFields.push({
+            rawDeveloperField = {
                 developerDataIndex: developerFieldDef.developerDataIndex,
                 fieldDefinitionNumber: developerFieldDef.fieldDefinitionNumber,
                 rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + developerFieldDef.size)),
-            });
+            };
+            rawDeveloperFields === null || rawDeveloperFields === void 0 ? void 0 : rawDeveloperFields.push(rawDeveloperField);
         }
         const fDef = resolveDeveloperFieldDefinition(developerFieldDef, messageType.littleEndian, developerFields, options);
+        if (!fDef && rawDeveloperField) {
+            unmappedDeveloperFields === null || unmappedDeveloperFields === void 0 ? void 0 : unmappedDeveloperFields.push(rawDeveloperField);
+        }
         if (fDef) {
             const data = readData(blob, dataView, fDef, readDataFromIndex);
             if (data !== InvalidFieldData
@@ -692,6 +705,10 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
         message: fields,
         rawFields,
         rawDeveloperFields,
+        unmappedFields: unmappedFields && unmappedFields.length > 0 ? unmappedFields : undefined,
+        unmappedDeveloperFields: unmappedDeveloperFields && unmappedDeveloperFields.length > 0
+            ? unmappedDeveloperFields
+            : undefined,
     };
 }
 export function getArrayBuffer(buffer) {

package/dist/cjs/binary.d.ts

@@ -40,6 +40,8 @@ export declare function readRecord(blob: Uint8Array, messageTypes: MessageTypeDe
     compressedTimestamp?: number;
     rawFields?: RawFieldValue[];
     rawDeveloperFields?: RawDeveloperFieldValue[];
+    unmappedFields?: RawFieldValue[];
+    unmappedDeveloperFields?: RawDeveloperFieldValue[];
 };
 export declare function getArrayBuffer(buffer: ArrayBuffer | Buffer): ArrayBuffer;
 export declare function calculateCRC(blob: Uint8Array, start: number, end: number): number;