docs/end_to_end_validation.md

# End-to-end reference validation

Task 21 compares staged event identity, labels, folds, weights, globals, node
features, topology, edge features, batching, fixed-weight forward, loss and
metrics, one optimizer step, short training, checkpoint reload, and inference.
The first failing stage is retained in JSON and Markdown reports.

Legacy and rewrite extraction may use separate environments. Each writes the
version-1 artifact described in `validation/README.md`; the comparator never
imports legacy modules or DGL graph objects. Record ROOT file/tree, selection,
event count, file size, SHA-256, branches, seeds, versions, device and source
identities in the artifact manifest. Do not use an absolute personal path as a
scientific event identity.

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
metadata, modern NPZ names and the version-1 checkpoint schema are expected
interface differences and must be reported explicitly.

Run the existing gates separately:

```bash
GNN4COLLIDERS_REQUIRE_ROOT_GNN=1 uv run pytest
uv run ruff check .
```