feat(test): coverage map load/save with freshness metadata

Author: sbryngelson

toolchain/mfc/test/coverage.py

@@ -4,8 +4,12 @@
 docs/superpowers/specs/2026-05-29-coverage-test-selection-design.md.
 """
 
+import datetime
+import gzip
 import hashlib
 import json
+from pathlib import Path
+from typing import Optional, Tuple
 
 
 def param_hash(params: dict) -> str:
@@ -16,3 +20,34 @@ def param_hash(params: dict) -> str:
     """
     canonical = json.dumps(params, sort_keys=True, separators=(",", ":"), default=str)
     return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]
+
+
+COVERAGE_MAP_PATH = Path("tests/coverage_map.json.gz")
+
+
+def save_map(path: Path, entries: dict, *, n_tests: int, git_sha: str, gfortran_version: str) -> None:
+    payload = dict(entries)
+    payload["_meta"] = {
+        "built_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "git_sha": git_sha,
+        "gfortran_version": gfortran_version,
+        "n_tests": n_tests,
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with gzip.open(path, "wt", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, sort_keys=True)
+
+
+def load_map(path: Path) -> Tuple[Optional[dict], Optional[dict]]:
+    """Return (entries_without_meta, meta), or (None, None) if missing/corrupt."""
+    if not Path(path).exists():
+        return None, None
+    try:
+        with gzip.open(path, "rt", encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, gzip.BadGzipFile, json.JSONDecodeError, UnicodeDecodeError):
+        return None, None
+    if not isinstance(data, dict) or "_meta" not in data:
+        return None, None
+    meta = data.pop("_meta")
+    return data, meta

toolchain/mfc/test/test_coverage_unit.py

@@ -1,4 +1,7 @@
-from mfc.test.coverage import param_hash
+import tempfile
+from pathlib import Path
+
+from mfc.test.coverage import load_map, param_hash, save_map
 
 
 def test_param_hash_is_order_independent():
@@ -22,3 +25,24 @@ def test_param_hash_nested_order_independent():
     a = param_hash({"patch": {"x": 1, "y": 2}})
     b = param_hash({"patch": {"y": 2, "x": 1}})
     assert a == b
+
+
+def test_save_then_load_roundtrip():
+    with tempfile.TemporaryDirectory() as d:
+        p = Path(d) / "m.json.gz"
+        save_map(p, {"abc": ["src/simulation/m_rhs.fpp"]}, n_tests=1, git_sha="deadbee", gfortran_version="13")
+        entries, meta = load_map(p)
+        assert entries == {"abc": ["src/simulation/m_rhs.fpp"]}
+        assert meta["n_tests"] == 1 and meta["git_sha"] == "deadbee"
+        assert "built_at" in meta
+
+
+def test_load_missing_returns_none():
+    assert load_map(Path("/nonexistent/m.json.gz")) == (None, None)
+
+
+def test_load_corrupt_returns_none():
+    with tempfile.TemporaryDirectory() as d:
+        p = Path(d) / "m.json.gz"
+        p.write_bytes(b"not gzip")
+        assert load_map(p) == (None, None)