VCF Header

The header MUST begin with a ##fileformat=VCFvX.Y line. The default version is VCFv4.3.

Headers MUST be constructed via a typestate builder that enforces field registration order at compile time. The builder progresses through phases — Contigs → Filters → Infos → Formats → Samples — and each phase only exposes methods appropriate for that stage. Phase transitions consume the builder and return the next phase; phases may be skipped. build() is available from any phase. Duplicate-ID and type-constraint errors are returned as typed errors.

Each INFO field MUST be declared with ID, Number, Type, and Description. Number is one of: a fixed count, A (one per ALT), R (one per allele), G (one per genotype), or . (unknown/variable). Type is one of: Integer, Float, Flag, Character, String. Flag type requires Number=0.

Each FORMAT field MUST be declared with ID, Number, Type, and Description. Same Number/Type rules as INFO except Flag type is not permitted. GT, if declared, MUST always appear first in the FORMAT column.

Each FILTER MUST be declared with ID and Description. PASS MUST always be present (implicitly or explicitly) and MUST map to BCF dictionary index 0.

Duplicate IDs within the same field category (INFO, FORMAT, FILTER, contig) MUST be rejected with a typed error at build time.

For BCF output, the header MUST provide a string-to-index dictionary mapping all FILTER, INFO, and FORMAT IDs to integer indices. The dictionary is built incrementally during builder construction; the typestate phase ordering guarantees entries appear in canonical order (PASS at index 0, then remaining FILTERs, then INFO, then FORMAT) without a runtime verification pass. Contig names use a separate index namespace matching insertion order.

to_vcf_text() MUST emit all meta-information lines (##) followed by the #CHROM header line. Lines MUST be ordered: fileformat first, then other lines (metadata), then FILTER (PASS first), INFO, FORMAT, contig, then the #CHROM line. This ordering ensures the BCF string dictionary (built by scanning header lines in order) assigns PASS to index 0 and matches the dictionary indices used during encoding.

A from_bam_header(&BamHeader) constructor MUST copy contig names and lengths from the BAM header's @SQ lines, preserving order (and thus tid mapping).