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:

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:

GNN4COLLIDERS_REQUIRE_ROOT_GNN=1 uv run pytest
uv run ruff check .