refactor: implement RoutableSuperKmer and update k-mer indexing pipeline

Replace raw SuperkMer routing with a new RoutableSuperKimer type that embeds canonical sequences and precomputed minimizers, enabling direct partition routing via hash. Update the build pipeline to yield RoutableSuperKmers throughout (builder, scatterer), refactor FASTA/unitig export commands to use the new type and compressed outputs (.fasta.gz, .unitigs.fasta.zst), revise SuperKmer header to store n_kmers instead of seql (avoiding 256-byte wrap), and update documentation to reflect minimizer-based theory, two evidence-encoding strategies for unitig-MPHF indexing (global offset vs. ID+rank), and the new obipipeline library architecture with parallel workers, biased scheduling, and error handling.

docmd/implementation/superkmer.md

@@ -2,26 +2,34 @@
 
 ## Memory layout
 
-A super-kmer is stored as a **32-bit header** followed by a **byte-aligned nucleotide sequence** (2 bits/base, nucleotide 0 at the MSB of the first byte, max 256 nt):
+A super-kmer is stored as a **32-bit header** followed by a **byte-aligned nucleotide sequence** (2 bits/base, nucleotide 0 at the MSB of the first byte):
 
 | Field | Bits | Role |
 |-------|------|------|
 | COUNT | 24   | Occurrence count (≤ 16 M) |
-| SEQL  | 8    | Sequence length in nucleotides (1–256) |
+| NKMERS | 8   | Number of kmers (= seq_length − k + 1, range 1–255) |
 
-Bit layout (MSB to LSB): `[31:8] COUNT  [7:0] SEQL`
+Bit layout (MSB to LSB): `[31:8] COUNT  [7:0] NKMERS`
 
-SEQL is stored as a raw `u8`: values 1–255 represent lengths 1–255; **0 represents 256** (wrapping convention). The public accessor returns a `usize` and performs the conversion:
+NKMERS is stored as a raw `u8` in **kmer units**, not nucleotides. The nucleotide length is recovered as `NKMERS + k − 1`. This avoids the awkward wrapping convention (`0 = 256`) that would be needed if nucleotide length were stored directly, and gains k−1 = 30 units of headroom:
+
+| unit | u8 covers | max nucleotides |
+|---|---|---|
+| nucleotides | 255 nt | 225 kmers |
+| **kmers** | **255 kmers** | **285 nt** |
+
+The public accessors:
 
 ```rust
-fn seql(&self)               -> usize { if s == 0 { 256 } else { s as usize } }
+fn n_kmers(&self)            -> usize { (self.0 & 0xFF) as usize }
+fn seql(&self)               -> usize { self.n_kmers() + K - 1 }
 fn count(&self)              -> u32   { self.0 >> 8 }
 fn increment(&mut self)               { self.0 += 1 << 8; }
 fn add(&mut self, n: u32)             { self.0 += n << 8; }
 fn set_count(&mut self, n: u32)       { self.0 = (self.0 & 0xFF) | (n << 8); }
 ```
 
-The SEQL field is 8 bits, capping the stored sequence at 256 nt. Given the expected length of ~40 nt, this cap is almost never reached; when it is, the super-kmer is split at 256 nt with a k−1 overlap, preserving all kmers without duplication.
+In practice, observed super-kmer lengths on metagenomic data (k=31) are below 55 nucleotides (≤ 25 kmers) — far from the 255-kmer cap. If a super-kmer ever exceeds 255 kmers, it is split with a k−1 nucleotide overlap, preserving all kmers without duplication (identical mechanism to partition-boundary splits).
 
 The sequence is always stored in canonical form (lexicographic minimum of forward and reverse complement), with nucleotide 0 at the MSB of the first byte. The byte array can be hashed directly without any adjustment.
 
@@ -61,10 +69,11 @@ const fn revcomp4(x: u8) -> u8 {
 
 `REVCOMP4` is 256 bytes (fits in L1 cache), computed at compile time. No endianness dependency — all operations are pure arithmetic on byte values.
 
-**Step 2 — realignment.**  After step 1, `padding = n × 8 − SEQL × 2` spurious bits (complements of the original padding A's) appear at the start of the array. They are flushed left using `BitSlice<u8, Msb0>::rotate_left(padding)` from the `bitvec` crate, which is SIMD-accelerated. The trailing `padding` bits are then zeroed:
+**Step 2 — realignment.**  After step 1, `padding = n × 8 − seql × 2` spurious bits (complements of the original padding A's) appear at the start of the array. They are flushed left using `BitSlice<u8, Msb0>::rotate_left(padding)` from the `bitvec` crate, which is SIMD-accelerated. The trailing `padding` bits are then zeroed:
 
 ```rust
-shift = n * 8 - SEQL * 2          // number of padding bits
+let seql = self.n_kmers() + k - 1;
+shift = n * 8 - seql * 2          // number of padding bits
 bits.rotate_left(shift)
 bits[len - shift..].fill(false)
 ```
@@ -141,8 +150,9 @@ The bit slice `seq[i*2 .. (i+k)*2]` (Msb0 order) is loaded as a big-endian `u64`
 !!! abstract "Algorithm — Super-kmer reverse complement"
     ```text
     procedure SuperKmerRevcomp(seq, SEQL):
-        n     ← ⌈SEQL / 4⌉                  -- number of bytes
-        shift ← n × 8 − SEQL × 2            -- padding bits to flush
+        seql  ← NKMERS + k − 1               -- nucleotide length
+        n     ← ⌈seql / 4⌉                  -- number of bytes
+        shift ← n × 8 − seql × 2            -- padding bits to flush
 
         -- step 1: swap bytes outside-in, applying REVCOMP4 to each (256-byte L1 table)
         lo ← 0 ; hi ← n − 1