3. Header line

header-line     = header-content padding LF        ; exactly 257 octets
header-content  = magic SP version SP records SP csdt-offset SP csdt-size SP
                  sha-field
magic           = %x50.4C.58.49                    ; "PLXI"
version         = %x76 dec
                  ; "v" then the format version, "v6"
records         = %x72.65.63.6F.72.64.73.3D dec    ; "records=" N
csdt-offset     = %x63.73.64.74.5F.6F.66.66.73.65.74.3D dec
                  ; "csdt_offset=" O
csdt-size       = %x63.73.64.74.5F.73.69.7A.65.3D dec
                  ; "csdt_size=" C
sha-field       = %x73.68.61.32.35.36.3D [sha-hex]
                  ; "sha256=" H or "sha256=" (placeholder)
sha-hex         = 64lhex
lhex            = %x30-39 / %x61-66
                  ; lowercase hexadecimal only
dec             = %x30 / (%x31-39 *19%x30-39)
                  ; decimal, no sign, no leading zeros, value < 2^64
padding         = *SP
                  ; space-fill so header-content + padding = 256 octets
SP              = %x20
LF              = %x0A

Each token is separated from the next by exactly one SP. There are exactly six tokens.

• version MUST be 6. A header whose version token parses as any other number MUST be rejected with unsupported_version. Versions 1 to 5 are retired numbering systems and have no readers.
• records is the number of record lines in the body (§4).
• csdt-offset and csdt-size locate the appendix (§2). When csdt-size is nonzero, csdt-offset MUST be a multiple of 64.
• sha-field carries the lowercase hex SHA-256 digest defined in §6.

A writer first emits a placeholder header and, when its output is seekable, overwrites it in place with the final header after the body and appendix are written. The fixed 256-byte width makes the rewrite possible without moving any other byte.

• A final header MUST carry a 64-digit sha-hex, and its records, csdt-offset, csdt-size and digest MUST equal the footer's record_count, csdt_offset, csdt_size and sha256.
• A placeholder header is exactly PLXI v6 records=0 csdt_offset=0 csdt_size=0 sha256= (empty digest) padded to 256 bytes. A writer whose output cannot seek (a gzip stream) leaves it in place. For a file with a placeholder header, the footer is the only source of the counts, offsets and digest.
• A header that is neither final nor placeholder (for example an empty digest with a nonzero records) MUST be rejected with header_footer_mismatch.

The header line is not covered by the SHA-256 digest (§6). Everything a reader trusts from it is therefore cross-checked against the footer.