nx_cigar.nx

nx_cigar.nx -- CIGAR run-length compression + ASCII serialiser. license_tier: INDEPENDENT_REDERIVE genealogy_id: international-research-sources/sam-spec-v1.4.6-section-1.4.6 G1.4c of NISHI_GENOMICS_SUBSTRATE_ROADMAP.md. Closes the gap from raw op-stream (nx_align_backtrace output) to SAM/BAM-spec CIGAR string. Three primitives compose: cigar_compress : MMMIIDD -> [(M,3), (I,2), (D,2)] cigar_serialize : [(M,3), (I,2), (D,2)] -> "3M2I2D" ASCII nx_i64_to_ascii_digits : positive int -> ASCII digits (no float) The two-stage compress + serialise split (rather than a one-shot ops -> ASCII string) is deliberate: downstream consumers may want the (op, count) array WITHOUT serialisation (for variant-calling pileup, for binary BAM writer where ops are length-prefixed uint32 not ASCII), and pre-serialised strings are inefficient to walk programmatically. SAM-spec ASCII mapping (from NX_CIGAR_M/I/D codes): NX_CIGAR_M (0) -> 'M' 0x4D NX_CIGAR_I (1) -> 'I' 0x49 NX_CIGAR_D (2) -> 'D' 0x44 NX_CIGAR_N (3) -> 'N' 0x4E NX_CIGAR_S (4) -> 'S' 0x53 NX_CIGAR_H (5) -> 'H' 0x48 NX_CIGAR_P (6) -> 'P' 0x50 NX_CIGAR_EQ(7) -> '=' 0x3D NX_CIGAR_X (8) -> 'X' 0x58 What G1.4c does NOT do (deferred): - BAM binary uint32 packing (op_len << 4 | op_code) -- nx_bam_writer (G6) - Soft-clipping op insertion at alignment ends -- G1.4c.2 - = / X explicit match/mismatch distinction -- G1.4c.2 - CIGAR parsing (ASCII -> ops) for reading SAM input -- G1.4d API: cigar_compress(ops, n_ops, out_codes, out_lens, max_out) -> i64 cigar_serialize(codes, lens, n_groups, out_ascii, max_ascii) -> i64