# Migration and model-family roadmap

## Frozen ROOT-GNN baseline

The `root-gnn-parity-baseline` tag records the completed migration of the
active ROOT-GNN behavior into `src/gnn4colliders.models.root_gnn`. The
campaign covered full event preprocessing and graph parity, binary objectives
and metrics, deterministic fine-tuning, full-split training, checkpoint reload
and resume, reproducibility, and serialized graph-cache checks.

The historical implementation is no longer in the active source tree. Its
observable behavior is represented by committed fixtures, tests, and the
one-way checkpoint/metadata compatibility adapters. New work must not add
imports from historical implementation paths.

## Shared contracts

New model families should consume these boundaries:

- `EventSample` and named `EventMetadata` from `data`;
- shared collider feature builders from `features`;
- a representation-specific sample/batch type from the relevant adapter;
- task-owned loss, score, prediction, and metric semantics;
- the shared `Trainer`, checkpoint, reproducibility, and inference APIs.

The graph path is the current ROOT-GNN representation. A sequence or token
model should add a separate representation boundary rather than placing
sequence behavior in graph modules or generic data code.

## Transformer model-family milestone

The first `root_transformer` vertical slice is implemented with:

1. Define a small `SequenceSample` contract and deterministic fixture.
2. Implement token construction using shared event/features infrastructure.
3. Add the transformer model under `models/root_transformer/`.
4. Connect it to the existing binary task and trainer on a tiny fixture.
5. Add checkpoint, prediction, and reproducibility tests.

The first implementation is available as
`model=root_transformer/transformer`. It can train on an existing graph cache
by adapting node features into ordered sequence tokens; this is a migration
bridge while a native sequence cache and DDP sequence loader are evaluated.

Native sequence-cache storage and distributed sequence loading remain follow-up
work; do not generalize shared interfaces until those use cases require it.

## Validation requirements

Every new model family must provide unit tests for its representation and
model, a small end-to-end integration test, checkpoint reload coverage, and a
deterministic repeatability check. Scientific behavior that is intentionally
shared with ROOT-GNN should be compared against the frozen reference fixture;
architecture-specific behavior should have its own reference outputs.