test(cli): B3c determinism + self-contained gates; docs(readme): build-once → query

CLI gates: two rosalind index builds are byte-identical, and rosalind locate serves queries from the .idx alone after the source FASTA is deleted (load never rebuilds). README documents the build-once -> query workflow and the record-only --memory-budget-mb plan line.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: logannye

README.md

@@ -21,7 +21,7 @@ Rosalind streams variant calling over coordinate-sorted alignments with a workin
 
 At the **command line**, Rosalind currently operates on a **single reference contig per run**, reads plain or **gzip/bgzf-compressed** FASTQ/FASTA (auto-detected, including from stdin), and runs **single-threaded**. Variant calling is **single-sample** (germline) or a **tumor/normal pair** (somatic); calling is SNV-focused, with simple indels in the somatic path. Alignment uses exact-match seeding. The FM-index is built in memory at the start of each run (memory proportional to the reference); the bounded-memory property applies to the streaming pileup and variant-calling stages. These boundaries define what the engine targets well today — small-to-moderate references, targeted regions, and per-sample streaming workloads.
 
-The library also provides a multi-contig FM-index over the concatenated genome (`genomics::GenomeIndex`) that resolves matches to `(contig, position)`; it is not yet used by the CLI. See the roadmap below.
+The library also provides a multi-contig FM-index over the concatenated genome (`genomics::GenomeIndex`) that resolves matches to `(contig, position)`; it is exposed via `rosalind index` / `rosalind locate` (wiring multi-contig through `align`/`variants` is a later phase). See the roadmap below.
 
 ## Who it's for
 
@@ -36,7 +36,7 @@ The library also provides a multi-contig FM-index over the concatenated genome (
 The core primitive is a streaming, CIGAR-aware pileup column stream; variant calling and custom plugins consume it.
 
 - **Phase A (done):** the streaming pileup engine; calibrated, abstention-aware germline SNV calling; tumor/normal somatic SNV calling; spec-valid VCF output; a BLAKE3 reproducibility receipt per run.
-- **Phase B (in progress):** streaming gzip/bgzf input and a multi-contig FM-index over the concatenated genome (`genomics::GenomeIndex`, with `(contig, position)` resolution and boundary-aware exact-match lookup) have landed. Next: wiring multi-contig through the CLI (whole-genome alignment and calling), a build-once memory-mapped index (`rosalind index`), and pipe-native composition across subcommands.
+- **Phase B (in progress):** streaming gzip/bgzf input, a multi-contig FM-index over the concatenated genome (`genomics::GenomeIndex`, with `(contig, position)` resolution and boundary-aware exact-match lookup), and a build-once, memory-mapped index (`rosalind index` to build, `rosalind locate` to query — never rebuilds, byte-identically reproducible) have landed. Next: wiring multi-contig through the `align`/`variants` CLI (whole-genome alignment and calling), and pipe-native composition across subcommands.
 - **Later:** germline indel calling and richer read QC; deterministic multithreading with an enforced memory budget; a Python binding exposing the pileup stream.
 
 Target architecture and per-phase plans: [`docs/superpowers/specs/`](docs/superpowers/specs/), [`docs/superpowers/plans/`](docs/superpowers/plans/).
@@ -104,6 +104,34 @@ Other subcommands (run `rosalind <subcommand> --help` for exact flags):
 
 `align` indexes the first FASTA record; additional records are ignored with a warning (single-contig scope). `variants` reads coordinate-sorted SAM/BAM alignments. Inputs may be plain or gzip/bgzf-compressed (auto-detected); pass `-` to read FASTQ from stdin, e.g. `gzip -dc reads.fastq.gz | rosalind align --reads - --reference ref.fa --format sam`.
 
+## Build once, query many: the persisted index
+
+Build a portable, memory-mappable index from a (multi-contig) reference once:
+
+```bash
+rosalind index --reference genome.fa --output genome.idx
+# index: genome.idx
+# contigs: 3 (90 bp total)
+#   chr1	30
+#   ...
+# reference_blake3: <hex>
+# index_bytes: <n>
+```
+
+Then query it in milliseconds — it is memory-mapped, never rebuilt:
+
+```bash
+rosalind locate --index genome.idx --pattern GATTACA
+# chr3	0
+# chr3	11
+```
+
+`rosalind index` is deterministic (the `.idx` is byte-identical across builds of
+the same reference). `--memory-budget-mb M` prints a record-only build plan line
+(`[OK]`/`[OVER]`) — it does not yet enforce the budget (that is a later phase).
+`locate` is exact-match only; seed/chain/extend alignment against the persisted
+index lands in a later phase.
+
 ### Rust API
 
 ```rust

tests/index_cli.rs

@@ -143,7 +143,12 @@ fn locate_matches_in_ram_ground_truth() {
     ])
     .unwrap();
 
-    for pat in ["GATTACA", "ACGT", "GGGGG", "NNNN", "TTTTGGGG", "ZZZZ"] {
+    // Battery: multi-hit, lowercase (case-insensitive), cross-contig boundary
+    // straddle ("CTTTTTT" spans chr1's tail into chr2 -> rejected, 0 hits),
+    // N-bearing, and an invalid base ("ZZZZ" -> 0 hits).
+    for pat in [
+        "GATTACA", "gattaca", "ACGT", "GGGGG", "NNNN", "TTTTGGGG", "CTTTTTT", "ZZZZ",
+    ] {
         let out = Command::new(bin())
             .args(["locate", "--index", idx.to_str().unwrap(), "--pattern", pat])
             .output()
@@ -170,3 +175,71 @@ fn locate_matches_in_ram_ground_truth() {
     }
     std::fs::remove_dir_all(&dir).ok();
 }
+
+#[test]
+fn index_build_is_deterministic_via_cli() {
+    let dir = tmpdir();
+    let fa = write_fasta(&dir);
+    let idx1 = dir.join("a.idx");
+    let idx2 = dir.join("b.idx");
+    for out in [&idx1, &idx2] {
+        let r = Command::new(bin())
+            .args([
+                "index",
+                "--reference",
+                fa.to_str().unwrap(),
+                "--output",
+                out.to_str().unwrap(),
+            ])
+            .output()
+            .expect("index");
+        assert!(r.status.success());
+    }
+    assert_eq!(
+        std::fs::read(&idx1).unwrap(),
+        std::fs::read(&idx2).unwrap(),
+        "two CLI builds of the same reference must be byte-identical"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn locate_works_from_the_artifact_alone() {
+    // Build, delete the source FASTA, then locate from the index file alone —
+    // proving the load path is self-contained and never rebuilds.
+    let dir = tmpdir();
+    let fa = write_fasta(&dir);
+    let idx = dir.join("ref.idx");
+    assert!(Command::new(bin())
+        .args([
+            "index",
+            "--reference",
+            fa.to_str().unwrap(),
+            "--output",
+            idx.to_str().unwrap(),
+        ])
+        .output()
+        .expect("index")
+        .status
+        .success());
+    std::fs::remove_file(&fa).unwrap(); // the only source of the sequence is now gone
+
+    let out = Command::new(bin())
+        .args([
+            "locate",
+            "--index",
+            idx.to_str().unwrap(),
+            "--pattern",
+            "GATTACA",
+        ])
+        .output()
+        .expect("locate");
+    assert!(out.status.success());
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert_eq!(
+        stdout.lines().count(),
+        2,
+        "GATTACA: 2 hits in chr3, served from the artifact alone"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}