Garmin Running Data Normalizer v1.2.1

Garmin Running Data Normalizer v1.2.1

Status: Release candidate pending Human approval and publication.

v1.2.1 is a bounded Windows runtime and onboarding hotfix for the published
v1.2.0 release. It does not change the normalization schema, default timezone,
stable keys, deterministic output contract, Snapshot policy, or supported
dataset boundary.

Root cause

Stable v1.2.0 declared no runtime dependencies. Python on Windows does not
necessarily include an IANA timezone database, so ZoneInfo("Asia/Tokyo")
could raise ZoneInfoNotFoundError. In one third-party Windows environment,
that missing data surfaced through the general
ACTIVITIES_NORMALIZATION_FAILED boundary. Installing tzdata manually
restored the tracked Synthetic Run-All.

This evidence is bounded to one third-party Windows environment and does not
establish universal Windows compatibility.

Changes

• Declare tzdata only when platform_system == "Windows". This supplies the
  IANA database for clean editable, wheel, source-distribution, and package
  index installs without replacing system timezone data on macOS or Linux.
• Emit the safe TIMEZONE_DATA_UNAVAILABLE diagnostic when the configured IANA
  timezone cannot be loaded. Normal CLI output does not expose a traceback,
  private path, host identifier, or Garmin data.
• Add explicit Windows PowerShell onboarding alongside macOS/Linux commands.
• Add a public-command validator that detects platform-specific documentation
  regressions and inconsistency between packaging metadata and Windows
  guidance.
• Add a windows-latest CI job that validates Asia/Tokyo, repeated Synthetic
  Run-All, deterministic output, and isolated wheel and source-distribution
  installs.

Verification

The merged hotfix passed the bootstrap-ci workflow on main with both
test and windows-runtime jobs successful. The Windows job installed
tzdata automatically for editable, wheel, and source-distribution paths.
Each isolated artifact install resolved Asia/Tokyo and completed the tracked
Synthetic Run-All with PASS_WITH_WARNINGS, exit code 0, and Activities
detected 1 / processed 1.

Release-candidate validation additionally covers the full unit and pytest
suites, bootstrap/platform/static/schema/public-command/public-history
validators, strict distribution metadata checking, and isolated artifact
installation. Exact RC results are recorded in the release PR.

Compatibility

• Python 3.11+ support is unchanged.
• Default timezone remains the IANA zone Asia/Tokyo; it is not replaced with
  a fixed UTC offset.
• Existing one-shot Run-All and Snapshot commands are unchanged.
• Output formats, filenames, record grain, stable keys, and exit-code semantics
  are unchanged.
• The new runtime dependency applies on Windows only.

Upgrade guidance

v1.2.0 remains the current stable release until the v1.2.1 tag, GitHub Release,
and package publication pass their separate Human approval gates. Until then,
Windows users of stable v1.2.0 who encounter ZoneInfoNotFoundError can install
the workaround inside the same environment:

python -m pip install tzdata

After v1.2.1 is published, install or upgrade through the normal package-index
path and confirm:

python -c "from zoneinfo import ZoneInfo; print(ZoneInfo('Asia/Tokyo'))"
python -m garmin_running_data_normalizer --version

Remaining release boundaries

This release-candidate preparation does not create a tag, publish a GitHub
Release, upload to TestPyPI or Production PyPI, change the stable alias, or
replace the temporary v1.2.0 advisory. Each action remains subject to explicit
Human approval after the release PR and CI are reviewed.