v1.2.0

Garmin Running Data Normalizer v1.2.0

v1.2.0 adds an opt-in, private local Snapshot Accumulation lifecycle while
preserving the existing v1.1.1 one-shot Run-All interface and stable 1.x
output contract.

Highlights

• An immutable, account-bounded Snapshot Store preserves explicitly confirmed
  complete Garmin Export observations and validated archive members by content.
• missing_is_not_delete prevents later absence from silently deleting earlier
  evidence.
• Family-specific merge policies distinguish entity upsert, event union,
  immutable FIT content union, and regenerated derived datasets.
• Historical backfill can be inserted deterministically; all 24 registration
  order permutations produce the same canonical result.
• Repeat registration of identical content is idempotent.
• Seven-state missing-value semantics keep absence, explicit null, empty,
  malformed, unsupported, retained, and promoted states auditable.
• Cumulative unique FIT materialization deduplicates content aliases before
  parsing, then regenerates Activity–FIT relationships under the existing
  evidence-qualified contract.
• Incremental canonical output matches a fresh full rebuild from the same
  approved Snapshot set.
• All 13 required failure and recovery scenarios pass.

Correctness and contract improvements

• Runtime schema validation agrees with the generated schema catalog,
  including integer identifiers.
• Invalid FIT enum sentinels, including the raw sport sentinel, normalize to
  JSON null with deterministic audit counts.
• Multi-session FIT is normalized only when declared lap allocation is complete
  and unambiguous. Conflicting files remain visible in FIT audit and are
  excluded from normalized sessions/laps and relationship eligibility.
• Activity-side, FIT-session-side, eligible, and structurally excluded
  populations are reported separately; relationship coverage is an evidence
  boundary, not a success score.
• Full local output can retain memo text and email-shaped source filenames.
  Those fields remain private-local and are removed from the optional
  external-safe pack.
• The Product Quick Start now documents the stable Snapshot commands, directory
  input contract, ZIP-inside-directory support, and private-store handling.

Verification

Public synthetic validation covers registration, merge, determinism,
full-rebuild equivalence, FIT deduplication, relationship regeneration,
failure/recovery behavior, package installation, and privacy scanning.
Public-safe aggregate evidence from four repeated Garmin Account Data Export
snapshots from the same account confirms cumulative behavior without publishing
private dates, paths, tokens, filenames, hashes, identifiers, rows, or record
values.

Backward compatibility

The existing run-all --input DIRECTORY --output DIRECTORY workflow remains
supported. Dataset names, grain, stable keys, fixed one-shot output paths,
Python 3.11+ support, and the standard-library runtime dependency boundary do
not change. Snapshot adoption is optional; no migration is required for
one-shot users.

Direct ZIP input remains unsupported and fails with INPUT_NOT_DIRECTORY.
Supported ZIP assets are inspected only when found inside the supplied input
directory.

Upgrade guidance

After package-index publication has completed, upgrade normally from PyPI.
One-shot users can keep their existing commands. Snapshot users should read the
v1.2 migration guide,
retain each complete Export until registration and verification succeed, use
one opaque account boundary per store, and back up only a verified store.

Known limitations

• Snapshot deletion, tombstones, automatic garbage collection, and automatic
  deletion inference are not provided.
• Explicit null/empty values and unsupported fields can require review rather
  than automatic promotion.
• Snapshot Stores are private, local, and user-managed; backup and restore must
  be verified explicitly.
• Windows manual environment characterization remains pending.
• Sleep, HRV, and Health Status remain library-level and are not promoted into
  Snapshot Run-All output.

Privacy boundary

Snapshot Stores, approved inputs, and full outputs contain private local data
and must not be committed or shared. Public examples use synthetic fixtures.
The optional external-safe pack is allowlist-only and excludes identifiers,
provenance, memo text, exact timestamps, coordinates, and unneeded health or
performance detail. It still requires Human review before transfer.