# OMICS-X: MASTER BUG REGISTRY
**Date**: April 1, 2026
**Last Updated**: April 16, 2026
**Total Bugs Found**: 22
---
## Executive Summary
### Critical State Assessment
🔴 **4 CRITICAL** bugs found including:
- HMM transition logic corrupts all algorithms
- GPU memory leak causes device failure
- BAM integer overflow causes data loss
- CUDA shared memory limits (already fixed ✅)
🟠 **10 HIGH** severity bugs affecting GPU, HMM, concurrency, boundaries
🟡 **8 MEDIUM** severity bugs in CIGAR, parsing, error handling
The codebase has **systemic correctness issues** requiring immediate high-priority fixes across core algorithms and I/O.
---
## Master Bug Registry - All 22 Bugs
### ✅ FIXED (3)
| 6 | CUDA Dynamic Shared Memory | CRITICAL | cuda_kernels_rtc.rs | ✅ FIXED | 2026-04-01 |
| 7 | Hardcoded Karlin-Altschul | HIGH | hmm.rs | ✅ FIXED | 2026-04-01 |
| 1 | NEON Excessive Allocations | MEDIUM | simd_viterbi.rs | ✅ FIXED | 2026-04-01 |
### ⏳ TODO (19)
| **10** | **HMM Transition Logic Error** | **CRITICAL** | **hmm.rs** | **Logic** | **40-50** |
| **11** | **BAM Integer Overflow** | **CRITICAL** | **bam.rs** | **Type** | **30-40** |
| **12** | **GPU Memory Leak** | **CRITICAL** | **gpu_executor.rs** | **Resource** | **60-80** |
| 2 | GPU Kernel Launch (Viterbi) | HIGH | simd_viterbi.rs | GPU | 40-50 |
| 3 | CUDA smith/needleman CPU | HIGH | kernel/cuda.rs | GPU | 80-100 |
| 5 | Incomplete HMM Transitions | HIGH | hmmer3_parser.rs | Parser | 60-80 |
| 9 | Unsafe Transition Indexing | HIGH | simd_viterbi.rs | Logic | 70-90 |
| 13 | Mutex Poisoning Cascade | HIGH | distributed.rs | Concurrency | 70-90 |
| 14 | Type Underflow | HIGH | mod.rs | Type | 40-50 |
| 15 | String Parsing DoS | HIGH | hmm_multiformat.rs | Parser | 50-70 |
| 16 | Uninitialized DP Vectors | HIGH | hmm.rs | Logic | 30-40 |
| 17 | Missing Bounds Checks | HIGH | simd_viterbi.rs | Bounds | 50-70 |
| 4 | HMMER3 Parsing Fragility | MEDIUM | hmmer3_full_parser.rs | Parser | 50-70 |
| 8 | .gz Compression Support | MEDIUM | cli_file_io.rs | I/O | 40-50 |
| 18 | CIGAR Off-by-One | MEDIUM | mod.rs | Logic | 1 |
| 19 | AA Code Wraparound | MEDIUM | hmm.rs | Logic | 40-50 |
| 20 | expect() Panic on CIGAR | MEDIUM | mod.rs | Error | 20-30 |
| 21 | Race Condition in Future | MEDIUM | hmm.rs | Concurrency | 30-40 |
| 22 | CUDA Hardcoded Alphabet Size | MEDIUM | cuda_kernels_rtc.rs | Architecture | 80-100 |
---
## Severity Breakdown
### 🔴 CRITICAL (4 bugs)
**Define**: System-level data corruption, device failure, complete algorithm breakdown
- Bug #6 ✅ FIXED - CUDA shared memory overflow
- Bug #10 ⏳ TODO - HMM transition logic (all algorithms invalid)
- Bug #11 ⏳ TODO - BAM overflow (data loss)
- Bug #12 ⏳ TODO - GPU memory leak (device exhaustion)
### 🟠 HIGH (11 bugs)
**Define**: Algorithm incorrectness, crashes, dropped results
- Bugs #2, #3, #5, #9 - GPU acceleration + algorithm defects (original audit)
- Bugs #13-17 - Concurrency, bounds, uninitialized memory (new audit)
### 🟡 MEDIUM (8 bugs)
**Define**: Edge cases, corner cases, robustness
- Bugs #1, #4, #8 - Performance + robustness (original audit)
- Bugs #18-21 - Off-by-one, parsing, error handling (new audit)
---
## Implementation Roadmap - Prioritized by Impact
### PHASE 0: CRITICAL FIX (IMMEDIATE - < 30 min)
**Impact**: Fix algorithms, prevent data corruption
- [ ] **Bug #10** - HMM Transition Indices (40-50 LOC) ⚠️ **HIGHEST PRIORITY**
- Affects: Forward, Viterbi, Backward, Baum-Welch algorithms
- Impact: All HMM results currently invalid
- Estimated: 30 min
- [ ] **Bug #18** - CIGAR Off-by-One (1 LOC) ✓ Quick win
- Affects: Alignment output format
- Estimated: 2 min
### PHASE 1: CRITICAL FIXES (1-2 hours)
- [ ] **Bug #11** - BAM Integer Overflow (30-40 LOC)
- Use u32 instead of i32, validate sizes
- Prevents data corruption
- [ ] **Bug #12** - GPU Memory Leak (60-80 LOC)
- Add RAII scope guard for GPU buffers
- Prevents device exhaustion
- [ ] **Bug #14** - Type Underflow (40-50 LOC)
- Use saturating_sub, valid checks
- Prevents score inversion
- [ ] **Bug #13** - Mutex Poisoning (70-90 LOC)
- Handle poisoned mutexes gracefully
- Prevents cascade failures
### PHASE 2: HIGH PRIORITY FIXES (3 hours)
- [ ] **Bug #15** - String Parsing DoS (50-70 LOC)
- Defensive parsing with proper error handling
- Prevents crashes on malformed input
- [ ] **Bug #16** - Uninitialized Vectors (30-40 LOC)
- Explicit initialization before use
- Prevents undefined behavior
- [ ] **Bug #17** - Bounds Checking (50-70 LOC)
- Add validation before array access
- Prevents panics
- [ ] **Bug #22** - CUDA Hardcoded Alphabet Size (80-100 LOC)
- Parameterize alphabet_size instead of hardcoding 20/24
- Support multi-alphabet (DNA, RNA, custom codes)
- Make emissions/scoring matrix sizes flexible
- [ ] **Bug #2, #3** - GPU Kernel Launches (120-150 LOC)
- Implement actual GPU computation
- Enables acceleration
- [ ] **Bug #5, #9** - HMM Transitions Parsing (130-170 LOC)
- Complete 7-transition parsing
- Safe transition indexing
### PHASE 3: MEDIUM PRIORITY (1-2 hours)
- [ ] **Bug #4** - HMMER3 Robust Parsing (50-70 LOC)
- State machine parser
- Robustness improvement
- [ ] **Bug #8** - .gz Compression (40-50 LOC)
- Auto-detect .gz format
- UX improvement
- [ ] **Bug #19** - AA Code Validation (40-50 LOC)
- Enum-based validation
- Prevent silent corruption
- [ ] **Bug #20** - expect() Error Handling (20-30 LOC)
- Replace panics with proper errors
- Better debugging
- [ ] **Bug #21** - Race Condition (30-40 LOC)
- Arc<Mutex<>> wrapping
- Deterministic results
---
## Dependency Graph
```
Bug #10 (HMM Logic) ──┐
├─→ Bug #9 (Transition Indexing)
│
Bug #5 (Transitions) ─┘
Bug #12 (GPU Leak) ──┐
├─→ Bug #2 (Viterbi GPU)
Bug #3 (CUDA SW/NW)─┘
Bug #14 (Type) ──┐
└─→ GAP cost scoring
Bug #11 (BAM) ──┐
└─→ Large genome support
Independent bugs: #1-4, #8, #13, #15-21
```
---
## Risk Assessment Matrix
| #10 | Very High | Very High | 🔴 CRITICAL | Fix immediately |
| #12 | Very High | Medium | 🔴 CRITICAL | Fix immediately |
| #11 | High | Medium | 🟠 HIGH | Fix ASAP |
| #2,#3 | High | Low | 🟠 HIGH | Fix soon |
| #14 | High | Low | 🟠 HIGH | Fix soon |
| #15 | Medium | Low | 🟡 MEDIUM | Fix eventually |
| Others | Low-Med | Low | 🟡 MEDIUM | Fix as time permits |
---
## Testing Guide
### For Each Bug Fix, Add:
1. **Unit Test** - Direct test of fixed function
2. **Regression Test** - Ensure fix doesn't break other code
3. **Integration Test** - End-to-end workflow with fix
4. **Stress Test** - Large inputs, edge cases
Example for Bug #10 (HMM Transitions):
```rust
#[test]
fn test_hm_transitions_indices_correct() {
// Each transition must use distinct indices
// Forward/Viterbi/Backward produce same results on known input
// Baum-Welch converges to reference parameters
let hmm = load_reference_hmm("PFAM_reference.hmm");
let sequence = b"MKVLVIGDRPG...";
let forward_score = hmm.forward_score(sequence);
let viterbi_path = hmm.viterbi(sequence);
// Validate against known reference results
assert!((forward_score - REFERENCE_SCORE).abs() < 0.01);
assert_eq!(viterbi_path.cigar, REFERENCE_CIGAR);
}
```
---
## Metrics
### Before Fixes (Current State)
- ✅ Compiles: Yes
- ✅ Tests Pass: 275/275 (100%)
- ❌ Correctness: ⚠️ Algorithm results invalid (Bug #10)
- ❌ Stability: ⚠️ GPU crash risk, memory leak (Bug #12)
- ❌ Data Integrity: ⚠️ Overflow, wraparound (Bugs #11, #19)
### After All Fixes (Target State)
- ✅ Compiles: Yes (no breaking changes)
- ✅ Tests Pass: 300+/300+ (100%+, new tests added)
- ✅ Correctness: All algorithms validated
- ✅ Stability: No panics, proper error handling
- ✅ Data Integrity: Safe type conversions, bounds checked
---
## Estimated Effort Summary
| Phase 0 | 2 | 41-51 | 0.5 hours |
| Phase 1 | 5 | 220-280 | 1.5 hours |
| Phase 2 | 6 | 460-620 | 3 hours |
| Phase 3 | 6 | 270-380 | 2 hours |
| **TOTAL** | **19** | **991-1331** | **7 hours** |
Combined with already-fixed bugs: **12-16 hours total project work**
---
## Bug #22: CUDA Hardcoded Alphabet Size (NEW)
**Severity**: 🟡 MEDIUM-HIGH
**Files**: `cuda_kernels_rtc.rs` (lines 26-30, 153-169) + `simd_viterbi.rs` (lines 204-207)
**Category**: Architecture - Hardcoded Constants
**Problem**:
```rust
// In simd_viterbi.rs (line 204-207)
let mut emis_matrix = vec![f64::NEG_INFINITY; 20 * m]; // HARDCODED 20
for aa in 0..20.min(state.emissions.len()) { // Loop assumes 20 amino acids
emis_matrix[aa * m + state_idx] = state.emissions[aa];
}
// In cuda_kernels_rtc.rs (line 26, 153-169)
__shared__ int smatrix[24 * 24]; // Hardcoded for 24 codes
// ...
float* emis = &s_mem[m * 3]; // Assumes 20*m emission matrix
```
**Impact**:
- ✗ Only supports standard 20 amino acids (+ 4 extended codes)
- ✗ Cannot handle DNA (4 codes), RNA (4 codes), or custom alphabets
- ✗ Emis_matrix allocation fails for different alphabet sizes
- ✗ SIMD/GPU code doesn't adapt to actual alphabet size
- **Limits library to protein-only use case**
**When It Breaks**:
```rust
// DNA sequences won't work properly
let dna_hmm = HmmerModel::with_alphabet("DNA", 4); // 4 codes
decoder.decode(dna_sequence, &dna_hmm); // ✗ Fails or corrupts
// Emission matrix allocated for 20, but DNA needs only 4
```
**Root Cause**: Copy-paste from implementation for proteins, never parameterized
**Fix Strategy**:
1. Add alphabet size to HmmerModel struct
2. Pass alphabet_size to CUDA kernels as parameter
3. Dynamic allocation based on alphabet
```rust
// Option A: Add to HmmerModel
pub struct HmmerModel {
// ... existing fields ...
pub alphabet_size: usize, // NEW: 4 for DNA, 20 for protein
}
// Option B: Parameterize CUDA kernel
pub const VITERBI_HMM_KERNEL: &str = r#"
extern "C" __global__ void viterbi_forward_kernel(
const unsigned char* sequence,
float* dp_m,
float* dp_i,
float* dp_d,
const float* transitions,
const float* emissions,
int n,
int m,
int alphabet_size, // NEW parameter
int emis_mem_per_aa // NEW: alphabet_size * m
) {
int emis_total = emis_mem_per_aa; // Instead of hardcoded 20*m
// ... rest of kernel ...
}
"#;
// Option C: Calculate at runtime
let alphabet_size = model.alphabet_size; // Query from model
let emis_matrix = vec![f64::NEG_INFINITY; alphabet_size * m];
```
**Estimated LOC**: 80-100 (affects CUDA kernel definition + GPU dispatcher + simd_viterbi.rs)
**Tests Required**:
```rust
#[test]
fn test_dna_alphabet_support() {
let dna_hmm = HmmerModel::with_alphabet(ProfileType::DNA);
assert_eq!(dna_hmm.alphabet_size, 4);
let sequence = b"ACGTACGT";
let result = decoder.decode(sequence, &dna_hmm);
assert!(result.is_ok());
}
```
---
## Additional Verified Issues (5 Audited Components)
**Audit on April 16, 2026 verified these 5 components**:
| Parser (* infinity) | ✅ NO BUG | Already correct: handles "*" for -inf (lines 303-310) |
| Bridge conversion | ✅ NO BUG | Bijective mapping, no off-by-one (lines 79-117) |
| SIMD alignment | ✅ NO BUG | Proper use of unaligned loads (_mm256_loadu_*) |
| CLI unwrap() | ✅ NO BUG | Zero panics: proper error handling throughout |
**Result**: 1 new bug found, 4 components verified as correct.
---
## Recommendations
### 1. IMMEDIATE ACTION (Next 30 minutes)
Fix Bug #10 and #18 - these have highest impact/effort ratio
### 2. TRIAGE (Next 2 hours)
Fix Critical and High-severity bugs in Phase 0-2
### 3. SUSTAINED (Next 4-6 hours)
Complete all Medium-severity bugs in Phase 3
### 4. VALIDATION (Ongoing)
- Run full test suite after each phase
- Add regression tests for each fix
- Performance benchmark before/after
### 5. DOCUMENTATION
- Document why each bug occurred
- Add safeguards to prevent recurrence
- Update developer guidelines
---
## Version Planning
- **v1.0.2** - Current (All known issues resolved)
---
**Project Status**: ⚠️ **CRITICAL** - Immediate action required (19 bugs unfixed)
**Recommendation**: Halt feature development, prioritize bug fixes for correctness and stability.