nx_alignment.nx

nx_alignment.nx -- AlignmentRecord struct + mapq + revcomp coord remap. license_tier: INDEPENDENT_REDERIVE genealogy_id: international-research-sources/li-2018-minimap2-mapq + sam-spec-v1 G1.4b of NISHI_GENOMICS_SUBSTRATE_ROADMAP.md. The output structure that downstream consumers (variant callers, BAM writers, alignment browsers, audit tooling) consume. Closes the "what does an aligner return?" gap by giving every read-vs-reference alignment a uniform queryable record. Field semantics (SAM-spec aligned but Nishi-native): query_id : caller-assigned numeric id for the query/read ref_id : caller-assigned numeric id for the reference sequence q_start : 0-indexed start position in the ORIGINAL query (NOT the rc-query; rc alignments are remapped via nx_remap_revcomp_coords before record construction) q_end : 0-indexed end (exclusive) in original query r_start : 0-indexed start in reference r_end : 0-indexed end (exclusive) in reference strand : NX_STRAND_FWD (+1) or NX_STRAND_REV (-1) from nx_const score : SW alignment score (linear or affine, caller's choice) mapq : mapping quality, 0..NX_MAPQ_MAX clamped n_seeds : number of seeds in the chain that anchored this alignment (passes through from nx_align_chain output) Mapping-quality model (G1.4b reference impl): mapq = clamp(0, 60, floor(60 * (primary - secondary) / max(1, primary))) - primary = score of the best alignment for this query - secondary = score of the best ALTERNATIVE alignment, or 0 if unique - secondary == 0 -> mapq = 60 (uniquely placed) - secondary == primary -> mapq = 0 (cannot distinguish primary from a tie) - secondary == primary/2 -> mapq = 30 (moderate confidence) - secondary > primary -> mapq = 0 (negative clamps to 0) - primary <= 0 -> mapq = 0 (no real alignment) This is the SIMPLEST coherent integer-arithmetic mapq that matches the high-end BWA-MEM 60-cap convention without pretending to model minimap2's full probabilistic formula (which uses chain count + log + sub-best heuristics, all of which require nx_fixed_point primitives -- G3+).