feat!: report match locations as SeqId with O(1) header lookup

[sriram98v]

Summary

Queries now identify a matching reference by a stable integer id rather than by its header string, and the header ↔ id mapping becomes a separate, O(1) concern.

Previously the locate path allocated one String per occurrence: it resolved a position to (seq_idx, pos) and then immediately cloned seq_headers[seq_idx], only for callers to hash it back to an integer. That cost is per occurrence, not per seed, so it scales with seed multiplicity — hundreds of references for a conserved seed in a metagenomic database, multiplied again by read orientations and pairs.

The integer already existed as the index into the build-ordered header list, and the GPU MEM path already reported it directly (MemHit::positions). This exposes it on the CPU path too and makes both paths agree on one representation.

Addresses the feature request filed from PREMISE (integer reference IDs from locate).

Breaking changes

• SeqId(u32) is the new id type. A newtype rather than a bare u32, so an id can never be swapped with the offset it is paired with — both are u32, and (SeqId, u32) tuples would otherwise be trivial to transpose. Assigned in build order, preserved across to_bytes/from_bytes, with new / get / index accessors.
• Queries return (SeqId, u32) instead of (String, u32) — FmIndex::locate, FmIndex::locate_gpu, FmIndex::map_position, BidirFmIndex::locate_interval, Mem::positions, and the WASM locate. MemHit::positions moves from (u32, u32) to (SeqId, u32), so CPU and GPU MEM results stay the same shape.
• Headers must now be unique. A collision raises the new FmIndexError::DuplicateHeader at build time — this is what lets seq_id be an exact inverse of seq_header rather than a first-wins approximation. It is checked before suffix-array construction, so a bad reference set fails in milliseconds instead of after the expensive build. Sequences supplied without a header are still auto-named seq_{i}, so this only fires on genuinely repeated names.

Migration: callers that need labels resolve ids through seq_header(id), or build an id -> label table once from seq_headers() and index it by SeqId::index().

Added

• seq_headers(), seq_header(id) and seq_id(header) on both FmIndex and BidirFmIndex. Both directions are O(1): seq_header indexes the header vec, seq_id uses a HashMap<Box<str>, u32> built at construction. The map is derived from the headers, so it is not serialized — from_bytes rebuilds it, leaving the index format unchanged.
• WASM bindings seq_header, seq_id, seq_headers (wasm-bindgen preserves the Rust snake_case, matching the existing text_len / num_sequences).

Also

• The web demo was rendering locate() pairs as if they were a flat position list, printing "seq_0,3" in a single column — already wrong before this change. It now resolves ids through seq_headers() once and shows Sequence / Position columns, with HTML escaping since headers come from user-pasted FASTA.
• docs/ (mdBook) previously used the term seq_id for both concepts on the same page — "the sequence's name (a String)" in one section and "numeric (seq_id, offset) indices" in another. A new Sequence ids vs. headers section in concepts.md defines both terms and is cross-linked from five pages.

Test plan

• cargo fmt --check
• cargo clippy --all-features -- -D warnings — 0 warnings (verified with a forced full re-lint)
• cargo build --all-features
• cargo test — 15 binaries, 164 tests, 0 failed
• cargo test --features gpu — all green against a real adapter, including the GPU/CPU MEM parity suites
• cargo doc --no-deps, cpu-only and --all-features — no warnings
• Full deploy.yml dry run: wasm32 release build → wasm-bindgen → npm ci → vite build → mdbook build → site assembly
• npx tsc --noEmit on the demo — no errors in main.ts, typechecked against freshly generated bindings

New tests/seq_ids.rs validates located ids against a brute-force search over the same corpus rather than against another index code path, so it stands on its own:

• Parity at SA sampling rates 1/2/4/8 — rate ≥ 2 exercises the LF-walk that multi-sentinel indexes have previously got wrong, and the old locate tests only covered rate 1.
• seq_id / seq_header are exact inverses; out-of-range ids and unknown headers return None.
• Duplicate-header rejection, including the subtle case of an explicit header colliding with a generated seq_{i} name.
• Ids stable across to_bytes/from_bytes, and header lookup still works after deserialization (the map is rebuilt, not stored).

A seq_id/seq_header inverse property was added to proptest_correctness.rs, and gpu_mem_positions_parity.rs lost the "seq_N" → N string parsing it previously needed to compare CPU against GPU — both sides are SeqId now.

Notes for review

• Cargo.lock is gitignored, so CI resolves dependencies fresh while local runs used this checkout's lock (wasm-bindgen 0.2.117). Pre-existing and unrelated to this change, but it means CI exercises newer minor versions than were tested locally.
• The three commits are kept separate deliberately: 408c553 is additive, 825e247 is the breaking change, 3b3c709 is docs-only. Squash if you prefer a single entry.