validation: use pinned public Hugging Face fixture

docs/end_to_end_validation.md

@@ -16,6 +16,15 @@ The captured runtime versions and seed policy are recorded in
 `validation/manifests/environments.json`; the HF composite fixture provenance
 is recorded in `validation/manifests/multiclass_fixture.json`.
 
+For the portable public regression, run:
+
+```bash
+uv run python -m validation.run_public_validation
+```
+
+This downloads or verifies the pinned `HWresearch/Delphes` 64-event fixture
+and compares the current rewrite against the checked-in legacy golden output.
+
 Strict parity applies to preprocessing, topology, fixed forward, loss, and
 one-step CPU updates. Multi-epoch, GPU and DDP comparisons are scientific:
 compare curves, metrics, distributions and event-level correlations. Named

tests/integration/test_real_root_model.py

@@ -34,7 +34,11 @@ FEATURE_SCALES = [0.1, 1, 1, 0.1, 1, 1, 1]
 
 def _fixture_path() -> Path:
     configured = os.environ.get("GNN4COLLIDERS_ROOT_FIXTURE")
-    return Path(configured) if configured else Path("data/processed/ttH_NLO_64.root")
+    return (
+        Path(configured)
+        if configured
+        else Path("data/fixtures/testing/ttH_NLO_64.root")
+    )
 
 
 @pytest.fixture(scope="module")

tests/integration/test_real_root_sample.py

@@ -34,7 +34,7 @@ def _fixture_path() -> Path:
     configured = os.environ.get("GNN4COLLIDERS_ROOT_FIXTURE")
     if configured:
         return Path(configured)
-    return Path("data/processed/ttH_NLO_64.root")
+    return Path("data/fixtures/testing/ttH_NLO_64.root")
 
 
 @pytest.fixture(scope="module")
@@ -42,8 +42,8 @@ def root_tree():
     path = _fixture_path()
     if not path.exists():
         pytest.skip(
-            f"ROOT sample fixture is absent: {path}; download ttH_NLO.root and "
-            "create the reduced fixture first"
+            f"ROOT sample fixture is absent: {path}; run the public validation "
+            "command to download it"
         )
     root_file = uproot.open(path)
     tree = root_file["output"]

tests/unit/validation/test_fixture.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import shutil
+
+import pytest
+from validation.fixture import TESTING_FIXTURE, ensure_fixture, verify_fixture
+
+
+def test_checked_in_public_fixture_has_pinned_identity():
+    path = ensure_fixture("data/fixtures/testing/ttH_NLO_64.root", download=False)
+    assert path.stat().st_size == TESTING_FIXTURE.size_bytes
+
+
+def test_fixture_checksum_mismatch_is_rejected(tmp_path):
+    path = tmp_path / "fixture.root"
+    shutil.copyfile("data/fixtures/testing/ttH_NLO_64.root", path)
+    path.write_bytes(path.read_bytes() + b"corruption")
+    with pytest.raises(ValueError, match=r"fixture (size|SHA-256) mismatch"):
+        verify_fixture(path)

validation/README.md

@@ -7,38 +7,58 @@ flattened storage plus offsets. Exact fields (IDs, labels, folds, offsets,
 topology) are exact-compared; floating fields use `tolerances.yaml`.
 
 ```bash
-uv run python -m validation.run_full_validation --smoke
-uv run python -m validation.run_full_validation \
-  --legacy-artifact validation_output/legacy \
-  --rewrite-artifact validation_output/rewrite \
-  --output validation_output/reports
+uv run python -m validation.run_public_validation
 ```
 
-Smoke validates serialization and comparison plumbing only; it does not claim
-legacy parity. Full scientific validation uses the same ROOT sample in both
-runtimes, with `GNN4COLLIDERS_E2E_FIXTURE` selecting an external fixture. Keep
+The command verifies the local fixture, downloads it from the pinned Hugging
+Face revision when necessary, extracts the rewrite, compares it with the
+checked-in legacy golden artifact, writes JSON and Markdown reports, and exits
+nonzero on a scientific mismatch. Use `--no-download` for offline runs. Keep
 generated output out of Git.
 
-## Current HF fixture campaign
+The lower-level artifact tooling remains available for regenerating references
+in the historical legacy environment:
+
+```bash
+uv run python -m validation.run_full_validation --smoke
+```
+
+## Current public HF fixture
+
+The normal public regression path requires only the current environment. It
+verifies the pinned public fixture, downloads it when missing, extracts the
+rewrite, and compares it with the legacy golden artifact:
+
+```bash
+uv run python -m validation.run_public_validation
+```
+
+The fixture identity is:
+
+```text
+repository: HWresearch/Delphes (dataset)
+revision: 76a6c362bfba8e766ba7255a5c08a55257f78d0e
+path: testing/ttH_NLO_64.root
+sha256: 89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec
+events: 64
+```
 
-The small fixture can be extracted in both environments:
+The historical extraction commands below are retained only for regenerating or
+auditing the golden artifact in a legacy environment:
 
 ```bash
-ROOT=/global/cfs/projectdirs/atlas/joshua/gnn_data/hf_validation/testing/ttH_NLO_64.root
+ROOT=data/fixtures/testing/ttH_NLO_64.root
 HF_SHA=89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec
 
 conda run -n dgl env PYTHONPATH=.:legacy/root_gnn_dgl:src \
-  python validation/extract_legacy.py /tmp/legacy_ttree.root validation_output/legacy \
+  python validation/extract_legacy.py "$ROOT" validation_output/legacy \
   --source-sha256 "$HF_SHA"
 
 PYTHONPATH=.:src uv run python validation/extract_rewrite.py "$ROOT" \
   validation_output/rewrite --source-sha256 "$HF_SHA"
 ```
 
-The legacy environment is Python 3.8/Uproot 5.3 and cannot read the HF
-RNTuple directly. Convert the fixture to a temporary TTree with a modern
-Uproot process; this changes only the ROOT container representation, not event
-values. The manifest retains the original HF SHA-256. Then run `forward.py`
+The manifest retains the original HF SHA-256. Then run `forward.py`
 with `model_epoch_71.pt`, `train_step.py`, `compare_step.py`, and
 `compare_tasks.py` to generate fixed-forward, one-step, and task reports.
 

validation/extract_common.py

@@ -136,7 +136,7 @@ def extract_root(
             "events": event_count,
             "sha256": file_sha256(path),
             "source_sha256": source_sha256 or file_sha256(path),
-            "input_path": str(path),
+            "input_path": path.name,
             "feature_schema": [
                 "pt",
                 "eta",

validation/fixture.py

@@ -0,0 +1,111 @@
+"""Pinned public validation-fixture discovery, download, and verification."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class PublicFixture:
+    repository: str
+    revision: str
+    repository_path: str
+    sha256: str
+    size_bytes: int
+
+    @property
+    def url(self) -> str:
+        return (
+            f"https://huggingface.co/datasets/{self.repository}/resolve/"
+            f"{self.revision}/{self.repository_path}?download=true"
+        )
+
+
+TESTING_FIXTURE = PublicFixture(
+    repository="HWresearch/Delphes",
+    revision="76a6c362bfba8e766ba7255a5c08a55257f78d0e",
+    repository_path="testing/ttH_NLO_64.root",
+    sha256="89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec",
+    size_bytes=15050,
+)
+
+
+def default_fixture_path(root: str | Path = ".") -> Path:
+    return Path(root) / "data" / "fixtures" / "testing" / "ttH_NLO_64.root"
+
+
+def file_sha256(path: str | Path) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def verify_fixture(path: str | Path, fixture: PublicFixture = TESTING_FIXTURE) -> Path:
+    """Verify size and SHA-256 before allowing a fixture into validation."""
+
+    path = Path(path)
+    if not path.is_file():
+        raise FileNotFoundError(f"validation fixture is missing: {path}")
+    actual_size = path.stat().st_size
+    if actual_size != fixture.size_bytes:
+        raise ValueError(
+            f"fixture size mismatch for {path}: expected {fixture.size_bytes}, "
+            f"got {actual_size}"
+        )
+    actual_sha256 = file_sha256(path)
+    if actual_sha256 != fixture.sha256:
+        raise ValueError(
+            f"fixture SHA-256 mismatch for {path}: expected {fixture.sha256}, "
+            f"got {actual_sha256}"
+        )
+    return path
+
+
+def download_fixture(
+    path: str | Path,
+    fixture: PublicFixture = TESTING_FIXTURE,
+    *,
+    timeout: float = 60.0,
+) -> Path:
+    """Download a pinned fixture atomically and verify it before returning."""
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".download", dir=path.parent
+    )
+    os.close(fd)
+    temporary = Path(temporary_name)
+    try:
+        with urllib.request.urlopen(fixture.url, timeout=timeout) as response:
+            with temporary.open("wb") as output:
+                while chunk := response.read(1024 * 1024):
+                    output.write(chunk)
+        verify_fixture(temporary, fixture)
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+    return path
+
+
+def ensure_fixture(
+    path: str | Path | None = None,
+    *,
+    download: bool = True,
+    fixture: PublicFixture = TESTING_FIXTURE,
+) -> Path:
+    """Return a verified local fixture, downloading it when necessary."""
+
+    path = Path(path) if path is not None else default_fixture_path()
+    if path.is_file():
+        return verify_fixture(path, fixture)
+    if not download:
+        raise FileNotFoundError(f"validation fixture is missing: {path}")
+    return download_fixture(path, fixture)

validation/golden/testing/legacy/artifact.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc5164e3eda8f88991fc87a70e13e766b1ae2ef3604a614273d9f6c52cdcf792
+size 40151

validation/golden/testing/legacy/manifest.json

@@ -0,0 +1,33 @@
+{
+  "arrays": [
+    "edge_dst_flat",
+    "edge_features_flat",
+    "edge_offsets",
+    "edge_src_flat",
+    "folds",
+    "globals",
+    "labels",
+    "node_features_flat",
+    "node_offsets",
+    "sample_id",
+    "weights"
+  ],
+  "event_count": 64,
+  "events": 64,
+  "feature_schema": [
+    "pt",
+    "eta",
+    "phi",
+    "energy",
+    "btag",
+    "charge",
+    "node_type"
+  ],
+  "input_path": "ttH_NLO_64.root",
+  "repository_path": "testing/ttH_NLO_64.root",
+  "schema_version": 1,
+  "sha256": "89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec",
+  "source": "huggingface://datasets/HWresearch/Delphes",
+  "source_sha256": "89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec",
+  "tree": "output"
+}

validation/manifests/dataset.json

@@ -1,6 +1,6 @@
 {
   "source": "https://huggingface.co/datasets/HWresearch/Delphes",
-  "revision": "main",
+  "revision": "76a6c362bfba8e766ba7255a5c08a55257f78d0e",
   "files": [
     {
       "repository_path": "testing/ttH_NLO_64.root",

validation/run_public_validation.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Run rewrite-vs-golden validation using the pinned public HF fixture."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from validation.compare import compare_artifacts, write_reports
+from validation.extract_common import (
+    FEATURE_BRANCHES,
+    OBJECT_TYPES,
+    SCALES,
+    extract_root,
+)
+from validation.fixture import TESTING_FIXTURE, ensure_fixture
+
+
+def _extract_rewrite(root_file: Path, output: Path) -> None:
+    from gnn4colliders.features import build_node_features
+
+    def build(event):
+        features, _ = build_node_features(event, FEATURE_BRANCHES, OBJECT_TYPES, SCALES)
+        return features
+
+    extract_root(
+        root_file,
+        output,
+        build_features=build,
+        sample_name=TESTING_FIXTURE.repository_path,
+        source_sha256=TESTING_FIXTURE.sha256,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--fixture", type=Path)
+    parser.add_argument("--output", type=Path, default=Path("validation_output/public"))
+    parser.add_argument(
+        "--no-download",
+        action="store_true",
+        help="fail instead of downloading a missing fixture",
+    )
+    args = parser.parse_args()
+
+    fixture = ensure_fixture(args.fixture, download=not args.no_download)
+    golden = Path(__file__).parent / "golden" / "testing" / "legacy"
+    if not (golden / "manifest.json").is_file():
+        raise FileNotFoundError(f"golden reference is missing: {golden}")
+    rewrite = args.output / "rewrite"
+    _extract_rewrite(fixture, rewrite)
+    report = compare_artifacts(golden, rewrite)
+    report["fixture"] = {
+        "repository": TESTING_FIXTURE.repository,
+        "revision": TESTING_FIXTURE.revision,
+        "repository_path": TESTING_FIXTURE.repository_path,
+        "sha256": TESTING_FIXTURE.sha256,
+        "size_bytes": TESTING_FIXTURE.size_bytes,
+    }
+    report_dir = args.output / "report"
+    write_reports(report, report_dir)
+    print(
+        json.dumps(
+            {
+                "overall_status": report["overall_status"],
+                "fixture": str(fixture),
+                "report": str(report_dir),
+            },
+            indent=2,
+        )
+    )
+    return 0 if report["overall_status"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())