docs/compatibility.md

# Compatibility boundary

The package's canonical APIs use named `EventMetadata` fields and the version
1 checkpoint schema. Compatibility is explicit and one-way: old artifacts are
adapted into the new representation and are never rewritten implicitly.

| Artifact or behavior | Supported | Boundary | Notes |
| --- | :---: | --- | --- |
| New checkpoint (`schema_version: 1`) | yes | `CheckpointManager` | Full model/lifecycle resume when state is present |
| Legacy `model_epoch_N.pt` checkpoint | yes | `gnn4colliders.compat.load_legacy_checkpoint` | Model state and active early-stop fields are adapted |
| Legacy DDP/compiled prefixes | yes | `normalize_legacy_state_dict_keys` | Supports `module.` and `_orig_mod.` |
| Legacy ROOT-GNN classifier name | yes | `map_legacy_edge_network_state_dict` | Maps `classify` to `classifier` |
| Legacy optimizer state | partial | legacy checkpoint adapter | Loaded when present; scheduler state is not available in the historical format |
| Legacy scheduler state | no | — | Historical checkpoints do not carry a supported scheduler state |
| Positional tracking rows | yes, at ingestion boundary | `EventMetadata.from_legacy_tracking` | Exactly `tracking[0] = fold`, `tracking[1] = weight`; shorter rows fail |
| Generic/unknown tracking layouts | no | — | The package does not guess historical column meanings |
| Modern NPZ output | yes | `inference.write_npz` | Named fields: `sample_id`, `logits`, `scores`, `predictions`, and available metadata |
| Historical `tracking_info` NPZ output | no | — | No active consumer remains; positional output is intentionally unsupported |
| Legacy YAML `module`/`class`/`args` | compatibility only | configuration boundary | Accepted only where the semantic factory can safely interpret it; new configs use semantic model names |

The frozen parity fixtures and `root-gnn-parity-baseline` tag preserve the
historical observations for parity tests and investigation. Production modules
do not import executable historical model code.