nx_const.nx source

1// nx_const.nx -- meta source of truth for universal constants. 2// 3// license_tier: ORIGINAL 4// genealogy_id: nishi-substrate/constant-registry 5// 6// CARDINAL: constants that are SHARED across multiple modules and 7// are UNIVERSAL (not algorithm-specific or application-tunable) live 8// in ONE place. Per user 2026-05-19: 9// "lets get a meta source of truth or whatever its called for 10// values that should be like pi and calculations and all that 11// as we build bits up so that these values arent scattered 12// everywhere" 13// 14// What belongs HERE (in nx_const.nx): 15// - Mathematical constants: pi, e, ln(2), sqrt(2), golden ratio 16// - Alphabet encodings: DNA 2-bit codes, ASCII for nucleotides 17// - Universal sentinels: NEG_INF, POS_INF, sentinel bytes 18// - Common ASCII: digits, whitespace, punctuation 19// 20// What stays LOCAL to its module (NOT in nx_const): 21// - Algorithm-spec constants: SHA-256 K[64], ChaCha20 sigma, AES S-box, 22// P-256 curve params. These are PART OF the algorithm spec; moving 23// them away from the implementation obscures provenance (license_tier 24// + genealogy_id audit). See feedback-defer-ethics + Cardinal 11. 25// - Application-tunable values: default gap penalties, k-mer sizes, 26// window widths. These are user choices per workload, not universals. 27// - File-format magic: opcode tables, struct offsets, ISA codes. 28// 29// Floating-point policy: 30// The substrate is no-float (Cardinal 6 + crypto modules). Math 31// constants are stored at fixed-point scale 1e18 (suffix _x1e18). 32// Callers divide by NX_FIXED_SCALE_1E18 or use the integer-arithmetic 33// helpers to be added in nx_fixed_point (G3+). Scale 1e18 fits in 34// i64 (max ~9.2e18) and preserves all 18 decimal digits of the 35// underlying transcendental, which exceeds IEEE-754 double precision. 36// 37// Discovery: 38// docs/NISHI_CONSTANT_REGISTRY.md explains the policy + how to 39// propose new entries. Any new constant that appears in two 40// modules belongs here; refactor pull both into an import of this 41// module per Cardinal 22 (composition over configuration). 42 43// ============================================================ 44// Math constants -- scale 1e18 fixed-point. 45// ============================================================ 46 47// Scale factor: integer arithmetic divides by this to recover float. 48const NX_FIXED_SCALE_1E18: i64 = 1000000000000000000 49 50// pi = 3.141592653589793238... * 1e18 51const NX_PI_X1E18: i64 = 3141592653589793238 52 53// e = 2.718281828459045235... * 1e18 54const NX_E_X1E18: i64 = 2718281828459045235 55 56// ln(2) = 0.693147180559945309... * 1e18 57const NX_LN2_X1E18: i64 = 693147180559945309 58 59// log_2(e) = 1.442695040888963407... * 1e18 60const NX_LOG2E_X1E18: i64 = 1442695040888963407 61 62// sqrt(2) = 1.414213562373095049... * 1e18 63const NX_SQRT2_X1E18: i64 = 1414213562373095049 64 65// golden ratio phi = (1 + sqrt(5)) / 2 = 1.618033988749894848... * 1e18 66const NX_GOLDEN_X1E18: i64 = 1618033988749894848 67 68// Euler-Mascheroni gamma = 0.577215664901532860... * 1e18 69const NX_GAMMA_X1E18: i64 = 577215664901532861 70 71// ============================================================ 72// DNA 2-bit encoding -- canonical across nx_sequence + downstream. 73// A = 00, C = 01, G = 10, T = 11; complement = code XOR 0b11. 74// ============================================================ 75 76const NX_DNA_A: i64 = 0 77const NX_DNA_C: i64 = 1 78const NX_DNA_G: i64 = 2 79const NX_DNA_T: i64 = 3 80 81const NX_DNA_COMPLEMENT_MASK: i64 = 3 82 83// ============================================================ 84// ASCII codes -- nucleotides + common punctuation used across 85// the substrate. Avoid hard-coding 0x4E / 0x41 etc. in modules. 86// ============================================================ 87 88const NX_ASCII_NULL: i64 = 0x00 89const NX_ASCII_TAB: i64 = 0x09 90const NX_ASCII_LF: i64 = 0x0A 91const NX_ASCII_CR: i64 = 0x0D 92const NX_ASCII_SPACE: i64 = 0x20 93const NX_ASCII_DOLLAR: i64 = 0x24 94const NX_ASCII_PLUS: i64 = 0x2B 95const NX_ASCII_HYPHEN: i64 = 0x2D 96const NX_ASCII_DOT: i64 = 0x2E 97const NX_ASCII_SLASH: i64 = 0x2F 98const NX_ASCII_DIGIT_0: i64 = 0x30 99const NX_ASCII_DIGIT_9: i64 = 0x39 100const NX_ASCII_COLON: i64 = 0x3A 101const NX_ASCII_GT: i64 = 0x3E 102const NX_ASCII_AT: i64 = 0x40 103 104// DNA + IUPAC bases, uppercase. 105const NX_ASCII_DNA_A: i64 = 0x41 106const NX_ASCII_DNA_B: i64 = 0x42 107const NX_ASCII_DNA_C: i64 = 0x43 108const NX_ASCII_DNA_D: i64 = 0x44 109const NX_ASCII_DNA_G: i64 = 0x47 110const NX_ASCII_DNA_H: i64 = 0x48 111const NX_ASCII_DNA_K: i64 = 0x4B 112const NX_ASCII_DNA_M: i64 = 0x4D 113const NX_ASCII_DNA_N: i64 = 0x4E 114const NX_ASCII_DNA_R: i64 = 0x52 115const NX_ASCII_DNA_S: i64 = 0x53 116const NX_ASCII_DNA_T: i64 = 0x54 117const NX_ASCII_DNA_U: i64 = 0x55 118const NX_ASCII_DNA_V: i64 = 0x56 119const NX_ASCII_DNA_W: i64 = 0x57 120const NX_ASCII_DNA_Y: i64 = 0x59 121 122// DNA bases, lowercase. 123const NX_ASCII_DNA_a: i64 = 0x61 124const NX_ASCII_DNA_c: i64 = 0x63 125const NX_ASCII_DNA_g: i64 = 0x67 126const NX_ASCII_DNA_t: i64 = 0x74 127 128// ============================================================ 129// Universal sentinel values for DP / pathfinding / placeholder. 130// Bound: 1e9. Fits comfortably in i32 range so arithmetic with 131// these values plus typical scores cannot overflow i64. For 132// substrate-wide use; do NOT exceed magnitude 1e9 in any single 133// addition path or saturating-add semantics required. 134// ============================================================ 135 136const NX_NEG_INF_I64: i64 = -1000000000 137const NX_POS_INF_I64: i64 = 1000000000 138 139// Placeholder for "not yet computed" or "no result"; distinguishable 140// from any real position value because positions are >= 0. 141const NX_INDEX_NONE: i64 = -1 142 143// ============================================================ 144// FM-index sentinel: lexicographically smallest byte by convention. 145// ============================================================ 146 147const NX_FM_SENTINEL_BYTE: i64 = 0x24 // '$' 148 149// ============================================================ 150// Genomic strand orientation -- substrate-wide convention so 151// nx_align_match_stranded / nx_align_chain / future variant 152// callers all agree on the sign of strand tags. 153// ============================================================ 154 155const NX_STRAND_FWD: i64 = 1 // forward / + / sense 156const NX_STRAND_REV: i64 = -1 // reverse-complement / - / antisense 157const NX_STRAND_UNKNOWN: i64 = 0 158 159// ============================================================ 160// Variant call categories -- universal across VCF / GATK / 161// bcftools / FreeBayes / Mutect2. Used by every SNV / indel / 162// SV caller downstream. 163// ============================================================ 164 165const NX_VARIANT_NONE: i64 = 0 // no variant -- matches reference 166const NX_VARIANT_HET: i64 = 1 // heterozygous variant (0/1) 167const NX_VARIANT_HOM: i64 = 2 // homozygous variant (1/1) 168 169// ============================================================ 170// Indel event categories -- canonical across SAM/VCF/GATK/bcftools. 171// Used by pileup indel-detection primitives + indel-aware 172// variant callers. INS = bases inserted in query vs reference; 173// DEL = bases deleted from query vs reference. 174// ============================================================ 175 176const NX_INDEL_NONE: i64 = 0 177const NX_INDEL_INS: i64 = 1 178const NX_INDEL_DEL: i64 = 2 179 180// ============================================================ 181// Phred quality offsets + Q-value bounds -- SAM/FASTQ spec. 182// Phred+33 (Sanger / Illumina 1.8+): ASCII = Q + 33, range Q [0..93] 183// Phred+64 (legacy Illumina 1.3-1.7): ASCII = Q + 64, range Q [0..62] 184// ============================================================ 185 186const NX_PHRED33_OFFSET: i64 = 33 187const NX_PHRED64_OFFSET: i64 = 64 188const NX_PHRED_MIN_Q: i64 = 0 189const NX_PHRED_MAX_Q: i64 = 93 // upper Phred+33 ASCII cap (126 - 33) 190 191// ============================================================ 192// CIGAR operation codes -- SAM/BAM v1 spec binary encoding. 193// Used by SW backtrace output, alignment-record CIGAR strings, 194// SAM serialiser. These values are SPEC-DEFINED (SAM v1 195// Section 1.4.6 + BAMv1 binary layout) so they qualify as 196// universal alphabet codes belonging in nx_const. 197// ============================================================ 198 199const NX_CIGAR_M: i64 = 0 // alignment match (consume query + ref); M 200const NX_CIGAR_I: i64 = 1 // insertion to ref (consume query only); I 201const NX_CIGAR_D: i64 = 2 // deletion from ref (consume ref only); D 202const NX_CIGAR_N: i64 = 3 // skipped region (intron-style large gap); N 203const NX_CIGAR_S: i64 = 4 // soft clip (query bases not aligned); S 204const NX_CIGAR_H: i64 = 5 // hard clip (query bases not stored); H 205const NX_CIGAR_P: i64 = 6 // padding (silent deletion vs padded ref);P 206const NX_CIGAR_EQ: i64 = 7 // sequence match (explicit); = 207const NX_CIGAR_X: i64 = 8 // sequence mismatch (explicit); X 208 209// ============================================================ 210// BAM 4-bit IUPAC nucleotide encoding -- SAMv1 §4.2 Table 1. 211// Each base in SEQ is packed into one nibble; high nibble first. 212// Spec-defined alphabet so it belongs in nx_const per META-CARDINAL 213// [[feedback-constants-registry-meta-source-of-truth]]. 214// ============================================================ 215 216const NX_BAM_NT_EQ: i64 = 0 // '=' equals reference 217const NX_BAM_NT_A: i64 = 1 218const NX_BAM_NT_C: i64 = 2 219const NX_BAM_NT_M: i64 = 3 // A or C 220const NX_BAM_NT_G: i64 = 4 221const NX_BAM_NT_R: i64 = 5 // A or G 222const NX_BAM_NT_S: i64 = 6 // C or G 223const NX_BAM_NT_V: i64 = 7 // A or C or G 224const NX_BAM_NT_T: i64 = 8 225const NX_BAM_NT_W: i64 = 9 // A or T 226const NX_BAM_NT_Y: i64 = 10 // C or T 227const NX_BAM_NT_H: i64 = 11 // A or C or T 228const NX_BAM_NT_K: i64 = 12 // G or T 229const NX_BAM_NT_D: i64 = 13 // A or G or T 230const NX_BAM_NT_B: i64 = 14 // C or G or T 231const NX_BAM_NT_N: i64 = 15 // any (default for unknown) 232 233// BAM file magic + version (SAMv1 §4.1). 234const NX_BAM_MAGIC_B: i64 = 0x42 // 'B' 235const NX_BAM_MAGIC_A: i64 = 0x41 // 'A' 236const NX_BAM_MAGIC_M: i64 = 0x4D // 'M' 237const NX_BAM_MAGIC_1: i64 = 0x01 // BAM v1 238 239// BAM sentinel: -1 for unmapped refID / pos / next_refID / next_pos. 240const NX_BAM_UNMAPPED: i64 = -1 241const NX_BAM_NO_QUAL_BYTE: i64 = 0xFF // per spec: all 0xFF if quals absent 242 243// ============================================================ 244// Bit-width / byte-count helpers used substrate-wide. 245// ============================================================ 246 247const NX_BYTE_BITS: i64 = 8 248const NX_I64_BYTES: i64 = 8 249const NX_I64_BITS: i64 = 64 250const NX_PAGE_BYTES: i64 = 4096