MHC annotation and supplied alleles
===================================

Build the curated sequence reference once with ``tcren build-mhc-ref`` before
annotating structures. The search index is then built as needed. The FASTA
reference itself is not automatically downloaded by scoring commands.

The standard structure score needs MHC chain roles, class and groove annotation.
Groove regions are projected from canonical class/role sequences. Exact allele
identity and the optional NetMHCpan pseudosequence annotation are not inputs to
the default cohort score. Allele identity is context for the explicit allele
confidence proxy.

A cropped MHC chain may match several reference alleles identically. The sequence
search selects a deterministic representative and retains co-best alleles among
its returned hits. This is not a genotype call or an exhaustive equivalence
class: the search returns at most 50 hits per chain. ``query_coverage`` and
``exact_observed_match`` describe the representative alignment, not full-length
allele identity. ``search_hit_limit_reached`` signals a possibly truncated list.

Supply known context in ``metadata.tsv`` beside the structures, keyed by unique
``id`` (or ``complex.id``). Use ``mhc`` for an allele such as ``HLA-A*02:01`` or
``A*02``. Class II can use ``mhc.a`` and ``mhc.b``, or a slash-separated
``DRA*01:01/DRB1*01:01`` pair in ``mhc``. Supplied field resolution is retained;
``A*02`` is never expanded into an arbitrary two-field allele.

The mapped call records ``allele_source=supplied``, the separate
``representative_allele``, and ``supplied_support``. Exact observed-sequence
support means the observed chain is contained in an existing reference sequence
consistent with the declaration. It cannot resolve differences outside that
chain. Non-exact sequence support or absence from returned co-best hits emits a
warning and remains visible in ``supplied_support``; absence from a limited hit
list alone does not establish a genotype conflict. Contradictory class/chain
roles or conflicting metadata fail explicitly. Supplied metadata does not
change the mapped role or groove projection. The energy-score table exposes MHCa evidence with the ``mhc.`` prefix.
For both chains of a class-II complex, Python callers can inspect
``structure.mhc_calls``; the MHCa table fields do not describe the MHCb allele.