docs: document the rewritten ROOT-GNN stack

README.md

@@ -1,41 +1,249 @@
 # GNN4Colliders
 
-This repository is being migrated to a clean, testable implementation under
-`src/gnn4colliders`.
+GNN4Colliders is a collider-machine-learning toolkit. The repository name
+reflects its first production model family, ROOT-GNN; the Python package is
+`gnn4colliders`, and the configuration identifier is `root_gnn`. Shared ROOT
+ingestion, collider features, metadata, tasks, training, inference, and
+distributed utilities are designed so that a future sequence model can reuse
+them without requiring every event to be a graph.
 
-The existing implementation is preserved in [`legacy/`](legacy/) as the
-behavioral reference. New production code belongs in `src/`; notebooks are for
-exploration only. Use the parity tests to document and validate behavior while
-components are migrated incrementally.
+```text
+ROOT files -> EventSample -> shared collider features
+                              ├── GraphSample -> ROOT-GNN
+                              └── future SequenceSample -> ROOT-Transformer
+```
+
+The new implementation lives under [`src/gnn4colliders`](src/gnn4colliders/).
+[`legacy/`](legacy/) is a frozen behavioral reference for parity work and
+historical checkpoint investigation, not a supported runtime backend.
+
+## Installation
+
+The supported development environment is Python 3.12 (`>=3.12,<3.13`), with
+PyTorch 2.2.2 and the optional ROOT-GNN stack DGL 2.4.0. The canonical setup
+is:
+
+```bash
+uv sync --dev --extra root-gnn
+```
+
+The core package can be installed without DGL when only shared data or task
+code is needed. ROOT-GNN models, graph construction, and ROOT-GNN parity tests
+require the `root-gnn` extra. The DGL extra uses the validated CUDA 12.1 wheel
+source configured in `pyproject.toml`; a compatible NVIDIA driver is still
+required. Do not add site-specific CUDA, Slurm, or filesystem paths to model
+or task configuration.
+
+## Quick start
 
-## Development environment
+Prepare a graph cache from a ROOT tree. The feature specifications below are
+illustrative placeholders; replace them with the branches in the input tree.
+The full preparation interface is documented in
+[`docs/configuration.md`](docs/configuration.md).
 
 ```bash
-git clone <repository-url>
-cd GNN4Colliders
+uv run gnn4colliders prepare \
+  data.files=[data/events.root] \
+  data.tree_name=Events \
+  data.cache.path=cache/events.pt \
+  'data.feature_branches=[["jet_pt"],["jet_eta"],["jet_phi"],CALC_E,[1.0],[0.0],NODE_TYPE]' \
+  data.object_types=[vector] \
+  data.scales=[1,1,1,1,1,1,1]
+```
+
+Train, evaluate, and predict from that cache:
+
+```bash
+uv run gnn4colliders train \
+  data.cache.path=cache/events.pt \
+  trainer.max_epochs=1 \
+  environment.output_root=outputs/pretraining_multiclass
+
+uv run gnn4colliders evaluate \
+  data.cache.path=cache/events.pt \
+  inference.checkpoint=outputs/pretraining_multiclass/checkpoints/epoch_0000.pt
+
+uv run gnn4colliders predict \
+  data.cache.path=cache/events.pt \
+  inference.checkpoint=outputs/pretraining_multiclass/checkpoints/epoch_0000.pt \
+  inference.output=outputs/pretraining_multiclass/predictions.npz
+```
+
+For a dependency-complete, temporary-data version of this flow, run
+`uv run python scripts/dev/smoke_end_to_end.py`.
+
+## Core concepts
+
+`EventSample` is the architecture-neutral event boundary. It contains the
+selected `objects`, `label`, `global_features`, and named `EventMetadata`.
+Metadata includes `fold`, `weight`, and stable `sample_id`; callers should not
+interpret public `tracking[:, N]` columns. Legacy tracking mappings exist only
+at compatibility boundaries.
+
+The ROOT-GNN adapter converts shared features to a directed, fully connected
+graph with no self-loops: an event with `N` nodes has `N * (N - 1)` edges.
+Node columns are, in order, `pt`, `eta`, `phi`, `energy`, `btag`, `charge`,
+and `node_type`. Edge columns are `deta`, wrapped `dphi`, and `dR`.
+Object collections are concatenated in configured object-type order. The
+compatibility energy is `pt * cosh(eta)` before per-column scaling.
+
+`GraphSampleCache` stores processed graph samples and schema metadata. It is a
+Level-2 graph cache, not the universal event cache. Feature, graph, and cache
+schema versions are checked when loading; incompatible versions fail before
+training.
+
+## ROOT-GNN training and transfer
+
+`EdgeNetwork` encodes node, edge, and global features, performs iterative
+edge/node/global message passing, decodes a graph representation, and applies
+the classifier. Its output is raw logits; sigmoid or softmax is task-owned.
+
+Multiclass pretraining uses the semantic `model=root_gnn/edge_network` and
+`task=pretraining_multiclass` groups:
+
+```bash
+uv run gnn4colliders train \
+  data.cache.path=cache/events.pt \
+  model=root_gnn/edge_network task=pretraining_multiclass \
+  trainer.max_epochs=20 data.batch_size=64 \
+  environment.output_root=outputs/pretraining_multiclass
+```
+
+Fine-tuning is a separate workflow. It loads a pretrained backbone, replaces
+the classifier, and creates a new task/head optimizer:
+
+```bash
+uv run gnn4colliders train \
+  data.cache.path=cache/target.pt \
+  model=root_gnn/fine_tuned_edge_network \
+  task=binary_classification \
+  checkpoint.pretrained=/path/to/pretrained.pt \
+  model.freeze_backbone=true \
+  trainer.max_epochs=10
+```
+
+Set `model.freeze_backbone=false` to train the reused backbone as well.
+Transfer learning is not resume training:
+
+| Workflow | Meaning | Restored state |
+| --- | --- | --- |
+| Resume | Continue the same task/run | model, optimizer, scheduler, trainer, early stopping, and RNG state when present |
+| Transfer | Start a new task from a pretrained backbone | model weights only; new classifier and optimizer |
 
-uv sync
+Resume example:
 
+```bash
+uv run gnn4colliders train \
+  data.cache.path=cache/events.pt \
+  checkpoint.resume=outputs/pretraining_multiclass/checkpoints/epoch_0000.pt \
+  trainer.max_epochs=20
+```
+
+Validation is evaluated each epoch and drives scheduling/early stopping;
+`test` remains held out. Evaluation computes task metrics over the complete
+selected split, including weighted ROC AUC where defined:
+
+```bash
+uv run gnn4colliders evaluate \
+  data.cache.path=cache/events.pt \
+  inference.split=test \
+  inference.checkpoint=/path/to/checkpoint.pt
+```
+
+Prediction writes a named compressed NPZ. Labeled data includes `labels`;
+`fold` and `weight` are included when available. Every result includes
+`sample_id`, `logits`, `scores`, and `predictions`:
+
+```bash
+uv run gnn4colliders predict \
+  data.cache.path=cache/events.pt \
+  inference.checkpoint=/path/to/checkpoint.pt \
+  inference.output=outputs/predictions.npz
+```
+
+Optional Python-level ROOT writing is provided by
+`gnn4colliders.inference.write_root_scores`. It clones the selected tree,
+adds `score` (or `score_class_N`), and writes `selection_pass`; IDs ending in
+`:<entry>` preserve alignment and unselected entries receive NaN scores. The
+CLI currently exposes NPZ output only.
+
+The supported legacy checkpoint, metadata, and output boundary is documented
+in [`docs/compatibility.md`](docs/compatibility.md). New code should use named
+metadata fields; positional tracking is accepted only by the explicit
+compatibility adapter.
+
+### ONNX export
+
+Install the optional export dependencies and export a prepared graph-cache
+checkpoint with numerical ONNX validation:
+
+```bash
+uv sync --extra root-gnn --extra onnx
+uv run gnn4colliders export \
+  export.checkpoint=/path/to/checkpoint.pt \
+  export.output=model.onnx \
+  data.cache.path=/path/to/graph-cache.pt
+```
+
+The model accepts processed graph tensors and returns raw logits. See
+[`docs/export.md`](docs/export.md) for the tensor contract and limitations.
+
+## Configuration and environments
+
+Hydra groups are `data`, `model`, `task`, `trainer`, `checkpoint`,
+`inference`, `environment`, and `distributed`. Use configuration for a new
+experiment and Python for new behavior. Examples:
+
+```bash
+uv run gnn4colliders train trainer.max_epochs=50 data.batch_size=64
+uv run gnn4colliders train environment=perlmutter environment.device=cuda
+uv run gnn4colliders train distributed=ddp environment=perlmutter
+```
+
+Each run writes a resolved configuration to
+`<environment.output_root>/resolved_config.yaml`. See
+[`docs/configuration.md`](docs/configuration.md) for the group reference and
+[`docs/perlmutter.md`](docs/perlmutter.md) for launch examples.
+
+## Distributed execution and reproducibility
+
+Launch DDP with `torchrun` or the provided Slurm wrappers. `data.batch_size`
+and `data.num_workers` are per process, so the ordinary effective batch size
+is `batch_size * world_size`. Training shards may be padded for equal steps;
+validation and prediction are unpadded. Rank 0 writes shared checkpoints,
+configs, and predictions, and metrics/results are gathered across ranks.
+
+The configured seed controls initialization and deterministic local loader
+ordering; distributed process seeds are rank-offset and samplers use
+`set_epoch`. CPU runs are reproducible for fixed inputs and environment. GPU
+kernels, DGL, and distributed scheduling can remain nondeterministic, so the
+project does not promise bitwise GPU reproducibility.
+
+## Development and validation
+
+```bash
 uv run pytest
+GNN4COLLIDERS_REQUIRE_ROOT_GNN=1 uv run pytest tests/parity -v
 uv run ruff check .
 uv run ruff format --check .
+uv run python benchmarks/benchmark_preprocessing.py
+uv run python benchmarks/benchmark_training.py --device cpu
 ```
 
-The default environment contains the data, configuration, testing, and
-linting dependencies needed for the current package skeleton. PyTorch and DGL
-are kept in the opt-in `ml` dependency group because their compatible wheels
-depend on the host and CUDA runtime. On a compatible host, install them with:
+Unit tests cover isolated components, integration tests cover small workflows,
+and parity tests compare deterministic behavior with the frozen legacy
+reference. Performance guidance and measured caveats are in
+[`docs/performance.md`](docs/performance.md) and
+[`benchmarks/README.md`](benchmarks/README.md).
 
-```bash
-uv sync --extra ml
-```
+## Architecture and migration status
 
-For Perlmutter or other HPC systems, follow the site-specific PyTorch/DGL
-installation guidance for the loaded CUDA module rather than encoding a CUDA
-wheel URL in this project. In particular, the currently resolved PyPI DGL
-2.2.1 distribution has no Linux wheel, so the `ml` extra is not currently
-installable on this Linux host without a site-provided or source-built DGL.
-Training and inference workflows are not yet implemented.
+See [`docs/architecture.md`](docs/architecture.md) for responsibility
+boundaries and the future sequence-model extension point. See
+[`docs/migration.md`](docs/migration.md) for the migration matrix,
+intentional redesigns, compatibility limits, and deferred work.
 
-See [`docs/migration.md`](docs/migration.md) for migration rules and
-[`docs/architecture.md`](docs/architecture.md) for the target design.
+ROOT-GNN v1 covers ROOT preparation, validated feature/graph/model/task
+behavior, training, fine-tuning, checkpoint resume, evaluation, prediction,
+single-process/DDP execution, and validated ONNX export. Streaming distributed
+output, legacy cleanup, and ROOT-Transformer remain follow-up work.

docs/architecture.md

@@ -1,4 +1,79 @@
-# Reverse-engineered architecture: `root_gnn_dgl`
+# GNN4Colliders architecture
+
+## Current v1 architecture
+
+The supported rewrite is layered around an architecture-neutral event boundary:
+
+```text
+ROOT/Awkward
+    ↓
+EventSample + EventMetadata
+    ↓
+shared collider feature construction
+    ├── GraphSample -> versioned graph cache -> GraphBatch
+    └── future SequenceSample -> ROOT-Transformer (not implemented)
+                                      ↓
+                               ROOT-GNN EdgeNetwork
+                                      ↓
+                               raw logits -> Task
+                                  ├── loss
+                                  ├── predictions
+                                  └── full-split metrics
+                                      ↓
+                          Trainer / Predictor / outputs
+```
+
+| Layer | Responsibility |
+| --- | --- |
+| `data` | ROOT/Awkward ingestion, event samples, metadata, graph caches, folds, and batching |
+| `features` | Shared collider-object features and derived physics quantities |
+| `graphs` | Topology, edge features, and the DGL representation adapter |
+| `models/root_gnn` | ROOT-GNN encoders, message passing, classifier, and transfer boundary |
+| `tasks` | Loss, score/prediction, labels, weights, and metrics |
+| `training` | Optimizer lifecycle, validation, early stopping, checkpointing, and reproducibility |
+| `inference` | Ordered prediction/evaluation and NPZ/ROOT output adapters |
+| `distributed` | Rank-local devices, sharding, DDP, and cross-rank collection |
+| `config` / `cli` | Semantic Hydra composition and thin user-facing commands |
+
+`EventSample` is shared infrastructure, not a ROOT-GNN object. `GraphSample`
+is the current representation-specific adapter. This separation is the
+extension point for a future sequence/token representation.
+
+The new public metadata contract is named `EventMetadata(fold, weight,
+sample_id, extra)`. The legacy positional tracking tensor is accepted only by
+compatibility-facing ingestion code. A `GraphSampleCache` is deliberately a
+Level-2 graph cache; replacing it with a universal cache would couple future
+model families to DGL.
+
+For deployment, a prepared `GraphBatch` can pass through the isolated
+`RootGNNExportAdapter` into an ONNX model. This is an inference boundary only;
+the native model continues to consume DGL graphs and ONNX does not read ROOT
+or construct collider features.
+
+## Current public workflow
+
+`prepare` reads ROOT through `RootEventDataset`, builds shared features and
+DGL graphs, and saves a schema-checked cache. `train` creates a model/task and
+`Trainer`; validation is the model-selection split and test is held out.
+`evaluate` computes metrics after collecting the complete split. `predict`
+returns detached CPU tensors in loader order and writes named NPZ fields.
+`write_root_scores` is an optional Python adapter with explicit entry alignment;
+the CLI currently exposes NPZ output.
+
+Compatibility responsibilities are isolated in `gnn4colliders.compat`.
+Supported historical checkpoint prefixes, classifier names, and the two-column
+tracking conversion are listed in [`compatibility.md`](compatibility.md).
+The modern pipeline does not propagate positional tracking or historical NPZ
+fields.
+
+Checkpoints are independent of the model implementation: they carry model and
+task metadata, lifecycle state, schema versions, and optional RNG state.
+Prefix normalization supports DDP `module.` and compiled `_orig_mod.` weights,
+plus the active ROOT-GNN historical classifier-name compatibility path.
+
+---
+
+## Historical behavioral reference
 
 This document covers the target system in `legacy/root_gnn_dgl/`. The sibling
 `legacy/physicsnemo/` tree is a prior rewrite attempt and is not a behavioral
@@ -6,6 +81,12 @@ target.
 
 ## 1. High-level system description
 
+The active rewrite exposes `gnn4colliders.models.root_gnn.EdgeNetwork`. Its
+encoders and message-passing blocks form a reusable backbone whose decoded
+graph representation is passed to an explicit classifier. `FineTunedEdgeNetwork`
+reuses that backbone and replaces only the task-specific classifier, with
+explicit frozen or trainable-backbone control.
+
 `root_gnn_dgl` is a ROOT-to-DGL graph classification system. YAML selects
 dataset, model, loss, and finish-function classes by import path. The dataset
 reads ROOT trees, converts collider objects to fully connected DGL graphs, and
@@ -137,6 +218,55 @@ Keys strip `module.` and compiled models save the underlying `_orig_mod` state;
 to a cloned ROOT tree ([`training_script.py:57-140`](../legacy/root_gnn_dgl/scripts/training_script.py),
 [`inference.py:328-385`](../legacy/root_gnn_dgl/scripts/inference.py)).
 
+### Training lifecycle boundary
+
+The active rewrite keeps lifecycle orchestration architecture-independent:
+
+```text
+GraphDataLoader -> GraphBatch -> Model -> Task -> Trainer
+                                      loss/metrics
+```
+
+`gnn4colliders.training.Trainer` owns device placement, train/evaluation mode,
+gradient and optimizer steps, epoch aggregation, optional scheduler stepping,
+early stopping, and in-memory history. Tasks own loss and metric semantics;
+the trainer does not inspect positional tracking columns or collider-specific
+features. Evaluation concatenates detached outputs across the complete split
+before calling task metrics, so ROC AUC is not computed per mini-batch.
+
+Checkpoint persistence and the Python inference/output layer are implemented
+as separate adapters. The semantic CLI and distributed application boundary
+are implemented in the current stack. `gnn4colliders.inference.Predictor` accumulates detached CPU
+logits, task-defined scores/predictions, labels, and named event metadata in
+loader order; `write_npz` is the primary named-field format and ROOT score
+writing is an optional alignment-aware adapter.
+
+The new lifecycle uses conventional split semantics. `train` updates model
+parameters, `validation` is evaluated after every epoch and drives scheduler,
+early-stopping, and later model selection, and `test` is held out. The trainer
+does not accept a test loader in `fit`; callers evaluate the held-out test set
+separately after training. This deliberately corrects the legacy convention
+where a loader named `test` was used for model selection and `val` represented
+held-out testing.
+
+## Distributed execution
+
+`gnn4colliders.distributed` contains the small DDP boundary used by the
+application layer. `DistributedContext` reads the standard `torchrun`
+environment (`RANK`, `LOCAL_RANK`, and `WORLD_SIZE`), selects the rank-local
+device, and owns process-group cleanup. Graph samples are sharded before
+batching; training may pad rank shards for equal step counts, while validation
+and prediction use unpadded shards so events are not counted twice.
+
+The configured graph `batch_size` is per process. DDP wraps an otherwise
+ordinary model after device placement, and checkpoint state is normalized to
+the underlying model keys. Loss gradients are synchronized by DDP; epoch
+metrics and evaluation outputs are gathered across ranks. Rank 0 writes
+resolved configuration, checkpoints, and NPZ predictions. Moderate-size
+prediction gathering is in-memory; streaming/sharded output is a future
+extension.
+
+
 ## Randomness, external services, and coupling
 
 The CLI exposes `--seed`, but `main` passes it to model construction rather
@@ -187,11 +317,34 @@ when a config has a validation fold ([`training_script.py:682-747`](../legacy/ro
 
 ## 3. De facto interfaces to preserve
 
+### Metadata-aware dataset boundary
+
+The rewrite uses named `EventMetadata` (`fold`, `weight`, and stable
+`sample_id`) instead of exposing the legacy positional tracking tensor.
+`GraphSample`, `GraphBatch`, `SplitDefinition`, and `GraphDataLoader` form the
+ROOT-GNN orchestration boundary. Graph caches carry feature, graph, and cache
+schema versions and reject incompatible artifacts before loading.
+
+The current cache implementation stores processed `GraphSample` values (the
+Level-2 cache). The separation from `RootEventDataset` is intentional: a
+future Level-1 cache can store normalized `EventSample`/feature data for
+sequence or transformer representations without requiring DGL graph caches.
+
 The rewrite's shared data boundary is `gnn4colliders.data`: it reads selected
 ROOT/Awkward branches and returns architecture-neutral event samples. Feature
 construction and graph building remain separate downstream boundaries, so the
 same samples can be reused by non-graph model families.
 
+### Configuration and CLI boundary
+
+Hydra composes semantic YAML groups under `configs/` and passes the resolved
+configuration to explicit application factories in `gnn4colliders.config`.
+Those factories allow-list supported models, tasks, and trainer components;
+YAML is never treated as an arbitrary Python import specification. The thin
+`gnn4colliders` CLI selects `prepare`, `train`, `evaluate`, or `predict` and
+delegates to the stable data, training, checkpoint, and inference APIs. A new
+experiment should generally be a YAML change; new behavior belongs in Python.
+
 1. YAML `module`, `class`, `args`, plus runtime `sample_graph` and
    `sample_global` injection.
 2. Dataset items `(DGLGraph, label, tracking, global_features)`.

docs/migration.md

@@ -86,8 +86,24 @@ padding. Compare against `RootDataset.save/load`, `LazyDataset`, and
 Treat `NONE`, `STEPS`, `FIXED`, and `NODE` as explicit features; do not hide
 the hardcoded fixed padding sizes.
 
+Task 7 establishes the metadata-aware orchestration boundary around this
+phase: `EventMetadata`, `GraphSample`, `GraphBatch`, fold-based split
+selection, deterministic batching, and a version-checked graph-sample cache.
+The cache is deliberately Level 2; normalized event caching remains a future
+extension so non-graph model families can reuse ROOT preprocessing.
+
 ## Phase 4 — active model parity
 
+Task 8 adds the active `EdgeNetwork` and `FineTunedEdgeNetwork` under
+`gnn4colliders.models.root_gnn`. The update order and MLP ordering follow the
+legacy active path. The rewrite uses an explicit backbone/classifier boundary,
+local DGL graph scope, and does not mutate global RNG state in constructors.
+Model parity now covers fixed-weight pretraining and transfer paths, including
+historical checkpoint prefixes. The legacy transfer implementation has an
+active bug when nonempty globals are supplied (`Pretrained_Output` ignores its
+argument); parity therefore characterizes its supported no-global path, while
+the rewritten model supports both global and fallback modes.
+
 Port `models.GCN.Edge_Network` first. Preserve constructor parameters,
 `forward(graph, global_feats)`, feature keys, processor order, MLP LayerNorm
 placement, and logits shape. Compare intermediate and final tensors on fixed
@@ -117,6 +133,19 @@ classes only with dedicated tests; do not substitute their reductions.
 
 ## Phase 6 — checkpoint and lifecycle
 
+Task 10 implemented the in-memory single-process training lifecycle before the
+checkpoint portion of this phase: `Trainer`, explicit optimizer/scheduler
+builders, `EarlyStopping`, reproducibility seeding, `GraphBatch.to`, and
+epoch/history result types. Checkpoint persistence/resume and the Python
+inference/evaluation and named NPZ/ROOT output layers are now implemented.
+Distributed execution and CLI wiring were completed in the later phases.
+
+Task 10 also establishes corrected split semantics: validation is evaluated
+every epoch and is the only split used for model selection or early stopping;
+the test split remains held out and is evaluated separately after fitting. The
+legacy loader naming inversion (`test` used for selection and `val` held out)
+is not carried into the rewrite.
+
 Create a checkpoint adapter preserving `model_epoch_<epoch>.pt` and keys
 `epoch`, `model_state_dict`, `optimizer_state_dict`, and `early_stop`
 ([`training_script.py:565-604`](../legacy/root_gnn_dgl/scripts/training_script.py)).
@@ -130,12 +159,22 @@ resume, restart, early termination, and `.npz` fields before distributed work.
 
 ## Phase 7 — CLI, inference, and export
 
+Task 12 implemented ordered prediction/evaluation, task-owned score
+semantics, checkpoint weight-only loading, named metadata retention, NPZ
+output, and explicit ROOT entry alignment. The semantic CLI and the validated
+ROOT-GNN ONNX export adapter are implemented.
+
+Task 13 adds Hydra composition and a single-process CLI around those existing
+APIs. The current application data boundary is a versioned
+`GraphSampleCache`; ROOT preparation converts events through the shared
+feature and graph builders before writing that cache.
+
 Build thin new applications around tested library interfaces in this order:
 
 1. preprocessing/cache generation (`scripts/prep_data.py`);
 2. training/evaluation (`scripts/training_script.py`);
 3. inference to `.npz` and ROOT (`scripts/inference.py`);
-4. ONNX export after PyTorch parity (`scripts/export_onnx.py`).
+4. ONNX export after PyTorch parity (`gnn4colliders export`).
 
 Use subprocess integration tests with tiny fixtures. Preserve CLI options only
 where they serve an active workflow; document removed diagnostic/cluster-only
@@ -143,20 +182,107 @@ options.
 
 ## Phase 8 — reproducibility and deployment
 
-Introduce one explicit seed policy covering Python, NumPy, Torch, sampling,
-augmentation, and clustering. Add deterministic-mode tests and document GPU
-nondeterminism. Isolate Slurm/NCCL, Podman-HPC, ROOT, and Hugging Face data
-download integrations behind adapters only after local behavior is stable.
+Task 14 adds the initial deployment boundary: CPU/GPU DDP through standard
+`torchrun` variables, rank-local graph-sample sharding, global metric/output
+gathering, rank-0 checkpoint/config writing, and Perlmutter-oriented Slurm
+examples. Evaluation deliberately avoids sampler padding duplicates. The
+remaining follow-up is a streaming or sharded output path for very large
+distributed inference jobs.
+
+The seed policy remains explicit: the configured seed is offset by rank for
+process-local randomness, while distributed sample assignment is derived from
+the configured seed, world size, and epoch. GPU kernel nondeterminism and
+exact per-rank RNG checkpoint replay remain environment-dependent. Slurm/NCCL,
+Podman-HPC, ROOT, and Hugging Face integrations stay in launcher/adapters
+rather than package code.
 
 ## Checkpoint compatibility checklist
 
-- [ ] Load the checked-in multiclass pretrained checkpoint.
-- [ ] Load a legacy fine-tuning checkpoint after prefix normalization.
-- [ ] Resume optimizer and early-stop state.
-- [ ] Produce equivalent logits on a deterministic graph fixture.
-- [ ] Produce equivalent `.npz` score, label, and tracking fields.
-- [ ] Preserve ROOT scalar/vector score branch conventions if ROOT output stays.
+- [x] Load a checked-in or generated multiclass pretrained checkpoint.
+- [x] Load a legacy fine-tuning checkpoint after prefix normalization.
+- [x] Resume optimizer and early-stop state.
+- [x] Produce equivalent logits on a deterministic graph fixture.
+- [x] Produce equivalent `.npz` score, label, and metadata fields.
+- [x] Preserve ROOT scalar/vector score branch conventions in the Python adapter.
 
 Known risks are documented in [`architecture.md`](architecture.md): edge order,
 self-loops, weight semantics, validation/test naming, padding, dynamic
 selection evaluation, reproducibility, and the experimental model/loss surface.
+
+## Migration closure status
+
+### Task 18 compatibility closure
+
+The compatibility boundary is now explicit in `gnn4colliders.compat`.
+Production ingestion stores named `EventMetadata`; legacy two-column tracking
+is converted only at the compatibility boundary. Checkpoint prefix cleanup and
+the historical ROOT-GNN `classify` to `classifier` mapping have one canonical
+implementation. The new checkpoint schema and named NPZ output remain
+canonical. See [`compatibility.md`](compatibility.md) for the supported and
+intentionally unsupported historical artifacts.
+
+The following matrix describes the supported new stack, rather than every
+class that exists in `legacy/`:
+
+| Legacy area | New-stack status | Notes |
+| --- | --- | --- |
+| ROOT/Awkward ingestion | migrated | `RootEventDataset` returns `EventSample` in file/event order |
+| node features | migrated + parity-tested | seven-column schema, `CALC_E`, ordering, scales, float32 |
+| edge construction | migrated + parity-tested | directed source-major topology and `[deta,dphi,dR]` |
+| graph cache | migrated | versioned `GraphSampleCache`; graph-level cache only |
+| folds and weights | migrated | named `EventMetadata.fold` and `.weight` |
+| batching | migrated | deterministic local loader and DDP sharding |
+| legacy padding modes | deferred | no active new-stack consumer |
+| `Edge_Network` | migrated + parity-tested | `EdgeNetwork`, raw logits |
+| transfer/fine-tuning | migrated + parity-tested | frozen or trainable backbone |
+| loss and metrics | migrated + parity-tested | task-owned weighted reductions and full-split AUC |
+| training lifecycle | migrated | `Trainer`, validation semantics, scheduler, early stopping |
+| checkpoints/resume | migrated | schema v1; historical weight/prefix adapter |
+| inference/NPZ | migrated | named output fields and ordered accumulation |
+| ROOT score output | compatibility adapter | Python API supported; CLI currently NPZ-only |
+| DDP | migrated | torchrun boundary, rank-0 artifacts, gathered metrics |
+| Slurm/Perlmutter | launcher examples | site policy remains outside package code |
+| ONNX export | migrated for ROOT-GNN | tensor-only adapter, ONNX Runtime validation, and `export` CLI; raw graph tensors are the input contract |
+
+### Intentional redesigns
+
+These are deliberate new-stack contracts, not accidental parity failures:
+
+* `tracking[:, 0]` and `tracking[:, 1]` become named `metadata.fold` and
+  `metadata.weight`; public consumers do not depend on positional columns.
+* Dynamic legacy YAML `module`/`class` construction becomes allow-listed
+  semantic Hydra configuration.
+* The monolithic training script becomes `Task` + `Trainer` + checkpoint and
+  inference adapters.
+* Graph state is scoped to the forward pass rather than relying on persistent
+  mutation of shared graph state.
+* Model constructors do not mutate global RNG state; seeding is explicit in
+  the training/application boundary.
+* Validation is the selection/early-stopping split and test is held out. This
+  corrects the legacy loader-name inversion.
+
+Compatibility preserves externally observable scientific behavior where it is
+validated; it does not promise to preserve every legacy implementation bug.
+The characterized legacy transfer path had a nonempty-global handling bug;
+the rewrite supports named globals. Negative weights, rare empty graphs,
+historical checkpoint variants, and legacy padding edge cases remain areas to
+audit when a supported consumer requires them.
+
+## ROOT-GNN v1 completion checklist
+
+- [x] active ROOT data path and graph cache
+- [x] validated feature, graph, model, task, and metric behavior
+- [x] train from scratch and fine-tune a pretrained backbone
+- [x] resume new-stack checkpoints and load supported historical weights
+- [x] evaluate and predict named outputs
+- [x] single-process and DDP application boundaries
+- [x] Perlmutter/Slurm launcher examples and profiling guidance
+- [x] ROOT-GNN ONNX export and CPU Runtime parity
+- [ ] streaming/sharded large-scale prediction output
+- [ ] removal of frozen legacy reference
+- [ ] ROOT-Transformer representation/model
+
+ROOT-GNN v1 is complete when the checked-in new stack can prepare active data,
+reproduce validated legacy behavior, train, transfer, resume, evaluate,
+predict, and run single-process or DDP workflows. The remaining unchecked
+items are intentionally deferred rather than undocumented promises.