# GRACE foundation-model deployment changelog

Each entry = one HF release of the foundation models. Versioning follows
`pgs/uq/deployment_protocol.md` §4:

- **`vX`** — single **incremental release version** (1, 2, 3, …), shared by the
  `model-vX` / `checkpoint-vX` / `kk-vX` tags of a release. Monotonic; never reused.
- **`-uq-vN`** — UQ feature version of the artifacts in that release (uqv6 → `-uq-v6`).

This file is the **source of truth**, tracked in-repo. On every deploy a copy is
uploaded to the HF repo root as `CHANGELOG.md` (same `create_commit` as the payloads).
Newest release on top.

---

## v3 — uq-v6 — *PLANNED (not yet deployed)*

- All 18 foundation models rebuilt with the **uqv6** UQ feature (schema 6:
  L2-normalized basis direction `(B/‖B‖)@R` + log-norm density channels).
  De-collapses GMM covariance and flags **both** compression and stretch.
- **Default precision flipped to fp32.** The bare model name now resolves to the
  **fp32** SavedModel + checkpoint (2× faster, ½ memory; fp32↔fp64 gap negligible —
  gamma max-rel ≤5e-5). The full-precision build is published non-default as
  **`<name>-fp64`**. ⚠ Users who pull the bare name get fp32 on the next cache-miss;
  use `<name>-fp64` for tight finite-difference / bit-reproducible work. kokkos is
  precision-agnostic (one fp64 npz serves both).
- kokkos exports re-baked from the uqv6 artifacts (`uq_schema_version = 6`,
  `uq_feature_dim` 130 (1L) / 131 (2L), `uq_rp_normalize` + `uq_rp_add_density_channel`).
- **kokkos.npz distributed separately** as a raw file (not bundled in the model
  tarball) — see protocol §6.
- Tags: `model-v3-uq-v6`, `checkpoint-v3-uq-v6`, `kk-v3-uq-v6`.
- Done (2026-06-26): all 18 kokkos exported; UFF-GARDEN restaged fp32-default + `-fp64`;
  `foundation_models.py` wired (fp32 default, `-fp64` registered, kokkos separate-dist);
  `bin/upload_v3_{uqv6,kokkos}_hf.sh` written + dry-run-validated; schema-6-aware kk
  `pair_style grace` C++ build **shipped** (kk-vs-TF validated 18/18 OK for E/F/stress
  fp64 GPU + gamma fp64 GPU / fp32 CPU).
- Remaining before deploy: run `upload_v3_*_hf.sh --push` (public push) + commit
  `foundation_models.py`. No blockers left.

## v2 — *currently deployed*

- Previous generation, live on the legacy HF tags `kk` (model archives, kokkos
  bundled) and `uq-v1` (original 8 OMAT-UQ checkpoints). UQ = uqv2/uqv3-era.
- This is the baseline the v3 rollout supersedes.